| 1 | package net.bmahe.genetics4j.gpu.opencl; | |
| 2 | ||
| 3 | import java.util.Objects; | |
| 4 | ||
| 5 | import org.jocl.CL; | |
| 6 | import org.jocl.Pointer; | |
| 7 | import org.jocl.Sizeof; | |
| 8 | import org.jocl.cl_device_id; | |
| 9 | import org.jocl.cl_kernel; | |
| 10 | ||
| 11 | /** | |
| 12 | * Utility class providing convenient methods for querying OpenCL kernel work group information. | |
| 13 | * | |
| 14 | * <p>KernelInfoUtils encapsulates the low-level OpenCL API calls required for retrieving kernel-specific execution | |
| 15 | * characteristics on target devices. This information is essential for optimizing kernel launch parameters and ensuring | |
| 16 | * efficient resource utilization in GPU-accelerated evolutionary algorithms. | |
| 17 | * | |
| 18 | * <p>Key functionality includes: | |
| 19 | * <ul> | |
| 20 | * <li><strong>Work group queries</strong>: Retrieve kernel-specific work group size limits and preferences</li> | |
| 21 | * <li><strong>Memory usage queries</strong>: Query local and private memory requirements per work-item</li> | |
| 22 | * <li><strong>Performance optimization</strong>: Access preferred work group size multiples for optimal execution</li> | |
| 23 | * <li><strong>Resource validation</strong>: Obtain kernel resource requirements for launch parameter validation</li> | |
| 24 | * </ul> | |
| 25 | * | |
| 26 | * <p>Common usage patterns: | |
| 27 | * | |
| 28 | * <pre>{@code | |
| 29 | * // Query kernel work group characteristics | |
| 30 | * long maxWorkGroupSize = KernelInfoUtils.getKernelWorkGroupInfoLong(deviceId, kernel, CL.CL_KERNEL_WORK_GROUP_SIZE); | |
| 31 | * | |
| 32 | * long preferredMultiple = KernelInfoUtils | |
| 33 | * .getKernelWorkGroupInfoLong(deviceId, kernel, CL.CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE); | |
| 34 | * | |
| 35 | * // Query memory requirements | |
| 36 | * long localMemSize = KernelInfoUtils.getKernelWorkGroupInfoLong(deviceId, kernel, CL.CL_KERNEL_LOCAL_MEM_SIZE); | |
| 37 | * | |
| 38 | * long privateMemSize = KernelInfoUtils.getKernelWorkGroupInfoLong(deviceId, kernel, CL.CL_KERNEL_PRIVATE_MEM_SIZE); | |
| 39 | * | |
| 40 | * // Optimize work group size based on kernel characteristics | |
| 41 | * long optimalWorkGroupSize = (maxWorkGroupSize / preferredMultiple) * preferredMultiple; | |
| 42 | * }</pre> | |
| 43 | * | |
| 44 | * <p>Kernel optimization workflow: | |
| 45 | * <ol> | |
| 46 | * <li><strong>Kernel compilation</strong>: Compile kernel for target device</li> | |
| 47 | * <li><strong>Characteristic query</strong>: Retrieve kernel-specific execution parameters</li> | |
| 48 | * <li><strong>Launch optimization</strong>: Configure work group sizes based on kernel requirements</li> | |
| 49 | * <li><strong>Resource validation</strong>: Ensure memory requirements don't exceed device limits</li> | |
| 50 | * </ol> | |
| 51 | * | |
| 52 | * <p>Error handling: | |
| 53 | * <ul> | |
| 54 | * <li><strong>Parameter validation</strong>: Validates all input parameters</li> | |
| 55 | * <li><strong>OpenCL error propagation</strong>: OpenCL errors are propagated as runtime exceptions</li> | |
| 56 | * <li><strong>Memory management</strong>: Automatically handles buffer allocation and cleanup</li> | |
| 57 | * </ul> | |
| 58 | * | |
| 59 | * @see KernelInfo | |
| 60 | * @see KernelInfoReader | |
| 61 | * @see net.bmahe.genetics4j.gpu.opencl.model.Device | |
| 62 | */ | |
| 63 | public class KernelInfoUtils { | |
| 64 | ||
| 65 | private KernelInfoUtils() { | |
| 66 | ||
| 67 | } | |
| 68 | ||
| 69 | /** | |
| 70 | * Queries and returns a long value for kernel work group information on the specified device. | |
| 71 | * | |
| 72 | * <p>This method retrieves kernel-specific execution characteristics that vary by device, such as maximum work group | |
| 73 | * size, preferred work group size multiples, and memory usage requirements. This information is essential for | |
| 74 | * optimizing kernel launch parameters. | |
| 75 | * | |
| 76 | * @param deviceId the OpenCL device to query | |
| 77 | * @param kernel the compiled OpenCL kernel | |
| 78 | * @param parameter the OpenCL parameter constant (e.g., CL_KERNEL_WORK_GROUP_SIZE, CL_KERNEL_LOCAL_MEM_SIZE) | |
| 79 | * @return the long value of the requested kernel work group property | |
| 80 | * @throws IllegalArgumentException if deviceId or kernel is null | |
| 81 | */ | |
| 82 | public static long getKernelWorkGroupInfoLong(final cl_device_id deviceId, final cl_kernel kernel, | |
| 83 | final int parameter) { | |
| 84 | Objects.requireNonNull(deviceId); | |
| 85 | Objects.requireNonNull(kernel); | |
| 86 | ||
| 87 |
1
1. getKernelWorkGroupInfoLong : Substituted 1 with 0 → NO_COVERAGE |
final long[] values = new long[1]; |
| 88 |
4
1. getKernelWorkGroupInfoLong : removed call to org/jocl/Pointer::to → NO_COVERAGE 2. getKernelWorkGroupInfoLong : removed call to org/jocl/CL::clGetKernelWorkGroupInfo → NO_COVERAGE 3. getKernelWorkGroupInfoLong : Substituted 8 with 9 → NO_COVERAGE 4. getKernelWorkGroupInfoLong : replaced call to org/jocl/CL::clGetKernelWorkGroupInfo with argument → NO_COVERAGE |
CL.clGetKernelWorkGroupInfo(kernel, deviceId, parameter, Sizeof.cl_long, Pointer.to(values), null); |
| 89 | ||
| 90 |
2
1. getKernelWorkGroupInfoLong : Substituted 0 with 1 → NO_COVERAGE 2. getKernelWorkGroupInfoLong : replaced long return with 0 for net/bmahe/genetics4j/gpu/opencl/KernelInfoUtils::getKernelWorkGroupInfoLong → NO_COVERAGE |
return values[0]; |
| 91 | } | |
| 92 | } | |
Mutations | ||
| 87 |
1.1 |
|
| 88 |
1.1 2.2 3.3 4.4 |
|
| 90 |
1.1 2.2 |