1 package net.bmahe.genetics4j.gpu.opencl.model; 2 3 import java.util.Set; 4 5 import org.immutables.value.Value; 6 import org.jocl.cl_platform_id; 7 8 /** 9 * Represents an OpenCL platform providing access to compute devices and their capabilities. 10 * 11 * <p>Platform encapsulates the information about an OpenCL platform, which is a vendor-specific 12 * implementation of the OpenCL specification. Each platform represents a collection of OpenCL 13 * devices (CPUs, GPUs, accelerators) provided by a single vendor with consistent runtime behavior. 14 * 15 * <p>Key platform characteristics include: 16 * <ul> 17 * <li><strong>Vendor identification</strong>: Platform vendor (AMD, NVIDIA, Intel, etc.)</li> 18 * <li><strong>Capability profile</strong>: FULL_PROFILE or EMBEDDED_PROFILE feature support</li> 19 * <li><strong>Version support</strong>: OpenCL specification version implemented</li> 20 * <li><strong>Extension support</strong>: Additional features beyond the core specification</li> 21 * <li><strong>Device count</strong>: Number of compute devices available on this platform</li> 22 * </ul> 23 * 24 * <p>Platform selection considerations: 25 * <ul> 26 * <li><strong>Vendor optimization</strong>: Different vendors may optimize for different workloads</li> 27 * <li><strong>Feature requirements</strong>: Embedded profiles may lack required features</li> 28 * <li><strong>Version compatibility</strong>: Newer OpenCL versions provide additional features</li> 29 * <li><strong>Extension dependencies</strong>: Some algorithms may require specific extensions</li> 30 * <li><strong>Device availability</strong>: Platforms must have compatible devices</li> 31 * </ul> 32 * 33 * <p>Common filtering patterns: 34 * <pre>{@code 35 * // Select platforms with full OpenCL profile support 36 * Predicate<Platform> fullProfileFilter = platform -> 37 * platform.profile() == PlatformProfile.FULL_PROFILE; 38 * 39 * // Select platforms from specific vendors 40 * Predicate<Platform> vendorFilter = platform -> 41 * platform.vendor().toLowerCase().contains("nvidia") || 42 * platform.vendor().toLowerCase().contains("amd"); 43 * 44 * // Select platforms with minimum OpenCL version 45 * Predicate<Platform> versionFilter = platform -> { 46 * String version = platform.version(); 47 * return version.contains("2.") || version.contains("3."); 48 * }; 49 * 50 * // Select platforms with required extensions 51 * Predicate<Platform> extensionFilter = platform -> 52 * platform.extensions().contains("cl_khr_fp64"); 53 * 54 * // Combine filters for comprehensive platform selection 55 * Predicate<Platform> combinedFilter = fullProfileFilter 56 * .and(versionFilter) 57 * .and(platform -> platform.numDevices() > 0); 58 * }</pre> 59 * 60 * <p>Platform discovery workflow: 61 * <ol> 62 * <li><strong>Enumeration</strong>: System discovers all available OpenCL platforms</li> 63 * <li><strong>Information query</strong>: Platform properties are read from OpenCL runtime</li> 64 * <li><strong>Model creation</strong>: Platform objects are created with discovered information</li> 65 * <li><strong>Filtering</strong>: User-defined predicates select appropriate platforms</li> 66 * <li><strong>Device discovery</strong>: Selected platforms are queried for available devices</li> 67 * </ol> 68 * 69 * <p>Performance implications: 70 * <ul> 71 * <li><strong>Driver optimization</strong>: Platform vendors optimize for their hardware</li> 72 * <li><strong>Memory models</strong>: Different platforms may have different memory hierarchies</li> 73 * <li><strong>Kernel compilation</strong>: Platform-specific optimizations during compilation</li> 74 * <li><strong>Runtime behavior</strong>: Platform-specific scheduling and resource management</li> 75 * </ul> 76 * 77 * <p>Error handling considerations: 78 * <ul> 79 * <li><strong>Platform availability</strong>: Platforms may become unavailable at runtime</li> 80 * <li><strong>Version compatibility</strong>: Kernels may require specific OpenCL versions</li> 81 * <li><strong>Extension support</strong>: Missing extensions may cause compilation failures</li> 82 * <li><strong>Device enumeration</strong>: Platform may have no compatible devices</li> 83 * </ul> 84 * 85 * @see Device 86 * @see PlatformProfile 87 * @see net.bmahe.genetics4j.gpu.spec.GPUEAExecutionContext#platformFilters() 88 * @see net.bmahe.genetics4j.gpu.opencl.PlatformUtils 89 */ 90 @Value.Immutable 91 public interface Platform { 92 93 /** 94 * Returns the native OpenCL platform identifier. 95 * 96 * @return the OpenCL platform ID for low-level operations 97 */ 98 cl_platform_id platformId(); 99 100 /** 101 * Returns the OpenCL profile supported by this platform. 102 * 103 * @return the platform profile (FULL_PROFILE or EMBEDDED_PROFILE) 104 */ 105 PlatformProfile profile(); 106 107 /** 108 * Returns the OpenCL version string supported by this platform. 109 * 110 * @return the OpenCL version (e.g., "OpenCL 2.1") 111 */ 112 String version(); 113 114 /** 115 * Returns the platform name provided by the vendor. 116 * 117 * @return the human-readable platform name 118 */ 119 String name(); 120 121 /** 122 * Returns the platform vendor name. 123 * 124 * @return the vendor name (e.g., "NVIDIA Corporation", "AMD") 125 */ 126 String vendor(); 127 128 /** 129 * Returns the set of OpenCL extensions supported by this platform. 130 * 131 * @return set of extension names (e.g., "cl_khr_fp64", "cl_khr_global_int32_base_atomics") 132 */ 133 Set<String> extensions(); 134 135 /** 136 * Returns the number of OpenCL devices available on this platform. 137 * 138 * @return the count of devices that can be used for computation 139 */ 140 int numDevices(); 141 142 /** 143 * Creates a new builder for constructing Platform instances. 144 * 145 * @return a new builder for creating platform objects 146 */ 147 static ImmutablePlatform.Builder builder() { 148 return ImmutablePlatform.builder(); 149 } 150 }