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 final long[] values = new long[1];
88 CL.clGetKernelWorkGroupInfo(kernel, deviceId, parameter, Sizeof.cl_long, Pointer.to(values), null);
89
90 return values[0];
91 }
92 }