KernelInfoUtils.java

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

Mutations

88

1.1
Location : getKernelWorkGroupInfoLong
Killed by : none Substituted 1 with 0 → NO_COVERAGE

89

1.1
Location : getKernelWorkGroupInfoLong
Killed by : none removed call to org/jocl/Pointer::to → NO_COVERAGE

2.2
Location : getKernelWorkGroupInfoLong
Killed by : none removed call to org/jocl/CL::clGetKernelWorkGroupInfo → NO_COVERAGE

3.3
Location : getKernelWorkGroupInfoLong
Killed by : none Substituted 8 with 9 → NO_COVERAGE

4.4
Location : getKernelWorkGroupInfoLong
Killed by : none replaced call to org/jocl/CL::clGetKernelWorkGroupInfo with argument → NO_COVERAGE

91

1.1
Location : getKernelWorkGroupInfoLong
Killed by : none Substituted 0 with 1 → NO_COVERAGE

2.2
Location : getKernelWorkGroupInfoLong
Killed by : none replaced long return with 0 for net/bmahe/genetics4j/gpu/opencl/KernelInfoUtils::getKernelWorkGroupInfoLong → NO_COVERAGE

Active mutators

Tests examined


Report generated by PIT 1.19.6