From 4ec65bf7eaaab9dd7820f6659d6d33395aad41dc Mon Sep 17 00:00:00 2001 From: Brice Videau Date: Wed, 4 Sep 2024 18:33:23 -0500 Subject: [PATCH] Added instance specification. --- api/appendix_f.asciidoc | 5 ++ api/cl_khr_icd.asciidoc | 31 ++++++++ api/opencl_platform_layer.asciidoc | 110 +++++++++++++++++++++++++++++ xml/cl.xml | 46 +++++++++++- 4 files changed, 191 insertions(+), 1 deletion(-) diff --git a/api/appendix_f.asciidoc b/api/appendix_f.asciidoc index b20d88295..99c30b8a1 100644 --- a/api/appendix_f.asciidoc +++ b/api/appendix_f.asciidoc @@ -435,6 +435,11 @@ ifdef::cl_khr_icd[] include::{generated}/api/version-notes/CL_PLATFORM_NOT_FOUND_KHR.asciidoc[] | Returned by {clGetPlatformIDs} when no platforms are available. + +| {CL_INVALID_INSTANCE_KHR_anchor} + +include::{generated}/api/version-notes/CL_INVALID_INSTANCE_KHR.asciidoc[] + | Returned when the specified instance is not a <>. endif::cl_khr_icd[] ifdef::cl_khr_semaphore[] diff --git a/api/cl_khr_icd.asciidoc b/api/cl_khr_icd.asciidoc index 2d2bcba97..a37f17d9c 100644 --- a/api/cl_khr_icd.asciidoc +++ b/api/cl_khr_icd.asciidoc @@ -255,6 +255,23 @@ query dispatchable entry points using {clIcdGetFunctionAddressForPlatformKHR} and then set the platform dispatch data using {clIcdSetPlatformDispatchDataKHR}. +The ICD Loader will also query the following functions from the library: +{clIcdCreateInstancePlatformKHR} and {clIcdDestroyInstancePlatformKHR}. +If these two functions are present and the library's platforms are ICD 2 +compatible, these platforms will be deemed *instance compatible*. + +Users can create new instances using {clCreateInstanceKHR}. Instances contain +an instance platforms of all *instance compatible* platforms. These instance +platforms can be queried using {clGetPlatformIDsForInstanceKHR}. Devices returned +by {clGetDeviceIDs} used on an instance platform will be instance devices. +An instance can be destroyed using {clDestroyInstanceKHR}. + +When new instances are created the loader will create new instances of these +platforms using {clIcdCreateInstancePlatformKHR}, and set instance platforms' +dispatch data using {clIcdSetPlatformDispatchDataKHR}. When an instance is +destroyed, instance platforms are destroyed with +{clIcdDestroyInstancePlatformKHR}. + === New Commands * {clIcdGetPlatformIDsKHR} @@ -263,6 +280,11 @@ New in version 2.0.0: * {clIcdGetFunctionAddressForPlatformKHR} * {clIcdSetPlatformDispatchDataKHR} + * {clIcdCreateInstancePlatformKHR} + * {clIcdDestroyInstancePlatformKHR} + * {clCreateInstanceKHR} + * {clDestroyInstanceKHR} + * {clGetPlatformIDsForInstanceKHR} === New Enums @@ -286,6 +308,15 @@ Loader: * {CL_PLATFORM_UNLOADABLE_KHR} +Returned by {clDestroyInstanceKHR} or {clGetPlatformIDsForInstanceKHR} +when an invalid instance is given: + + * {CL_INVALID_INSTANCE_KHR} + +Accepted as terminator to the _properties_ list of {clCreateInstanceKHR}. + + * {CL_INSTANCE_PROPERTIES_LIST_END_KHR} + === Issues . Some OpenCL functions do not take an object argument from which their diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index 8f32e713e..f79d5ca68 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -94,6 +94,7 @@ include::{generated}/api/protos/clIcdGetFunctionAddressForPlatformKHR.txt[] include::{generated}/api/version-notes/clIcdGetFunctionAddressForPlatformKHR.asciidoc[] * _platform_ refers to the platform ID returned by {clIcdGetPlatformIDsKHR} + or by {clIcdCreateInstancePlatformKHR} * _func_name_ name of an API entry point {clIcdGetFunctionAddressForPlatformKHR} returns the address of the API entry @@ -121,6 +122,115 @@ executed successfully. It returns {CL_INVALID_PLATFORM} if _platform_ is not a valid platform. -- +[open,refpage='clIcdCreateInstancePlatformKHR',desc='Create an instance of a platform',type='protos'] +-- +An instance platform can be created by the ICD Loader by using the following +function: + +include::{generated}/api/protos/clIcdCreateInstancePlatformKHR.txt[] +include::{generated}/api/version-notes/clIcdCreateInstancePlatformKHR.asciidoc[] + + * _platform_ refers to the platform ID returned by {clIcdGetPlatformIDsKHR} + + * _errcode_ret_ will return an appropriate error code as described below. + If _errcode_ret_ is `NULL`, no error code is returned. + +{clIcdCreateInstancePlatformKHR} returns a valid non-zero OpenCL platform object +and _errcode_ret_ is set to {CL_SUCCESS} if the instance platform object is +created successfully. +Otherwise, it returns a `NULL` value with one of the following error values +returned in _errcode_ret_: + + * {CL_INVALID_PLATFORM} if _platform_ is not a valid platform. + * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources + required by the OpenCL implementation on the host. +-- + +[open,refpage='clIcdDestroyInstancePlatformKHR',desc='Destroy an instance of a platform',type='protos'] +-- +An instance platform can be destroyed by the ICD Loader by using the following +function: + +include::{generated}/api/protos/clIcdDestroyInstancePlatformKHR.txt[] +include::{generated}/api/version-notes/clIcdDestroyInstancePlatformKHR.asciidoc[] + + * _platform_ refers to the instance platform object returned by + {clIcdCreateInstancePlatformKHR} + +{clIcdDestroyInstancePlatformKHR} returns {CL_SUCCESS} if the function is +executed successfully. +It returns {CL_INVALID_PLATFORM} if _platform_ is not a valid instance platform. +-- + +[open,refpage='clCreateInstanceKHR',desc='Create an OpenCL instance',type='protos'] +-- +An instance can be created by the user by using the following function: + +include::{generated}/api/protos/clCreateInstanceKHR.txt[] +include::{generated}/api/version-notes/clCreateInstanceKHR.asciidoc[] + + * _properties_ specifies additional instance properties in a + {CL_INSTANCE_PROPERTIES_LIST_END_KHR_anchor} terminated list. + Can be `NULL` if no properties are given. + * _errcode_ret_ will return an appropriate error code as described below. + If _errcode_ret_ is `NULL`, no error code is returned. + +{clCreateInstanceKHR} returns a valid non-zero OpenCL instance object +and _errcode_ret_ is set to {CL_SUCCESS} if the instance object is +created successfully. +Otherwise, it returns a `NULL` value with one of the following error values +returned in _errcode_ret_: + + * {CL_INVALID_VALUE} if _properties_ contains an invalid value + * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources + required by the OpenCL implementation on the host. + * {CL_PLATFORM_NOT_FOUND_KHR} if zero instance platforms are available. +-- + +[open,refpage='clDestroyInstanceKHR',desc='Destroy an OpenCL instance',type='protos'] +-- +An instance can be destroyed by the user by using the following function: + +include::{generated}/api/protos/clDestroyInstanceKHR.txt[] +include::{generated}/api/version-notes/clDestroyInstanceKHR.asciidoc[] + + * _instance_ refers to the instance object returned by {clCreateInstanceKHR}. + +{clDestroyInstanceKHR} returns {CL_SUCCESS} if the function is executed +successfully. +It returns {CL_INVALID_INSTANCE_KHR} if _instance_ is not a valid instance +object. +-- + +[open,refpage='clGetPlatformIDsForInstanceKHR',desc='Query list of available platforms in an instance',type='protos'] +-- +The list of platforms available in an instance can be obtained with the +function: + +include::{generated}/api/protos/clGetPlatformIDsForInstanceKHR.txt[] +include::{generated}/api/version-notes/clGetPlatformIDsForInstanceKHR.asciidoc[] + + * _instance_ refers to the instance object returned by {clCreateInstanceKHR}. + * _num_entries_ is the number of {cl_platform_id_TYPE} entries that can + be added to _platforms_. If _platforms_ is not `NULL`, then _num_entries_ + must be greater than zero. + * _platforms_ returns a list of OpenCL platforms available for access through + the _instance_. The {cl_platform_id_TYPE} values returned in _platforms_ + can be used to identify a specific instance platform. If the _platforms_ + argument is `NULL`, then this argument is ignored. The number of OpenCL + platforms returned is the minimum of the value specified by _num_entries_ + or the number of instance platforms available. + * _num_platforms_ returns the number of instance platforms available. + If _num_platforms_ is `NULL`, then this argument is ignored. + +{clGetPlatformIDsForInstanceKHR} returns {CL_SUCCESS} if the function is +executed successfully. +It returns {CL_INVALID_INSTANCE_KHR} if _instance_ is not a valid instance object. +It returns {CL_INVALID_VALUE} if _num_entries_ is equal to zero and +_platforms_ is not `NULL` or if both _num_platforms_ and _platforms_ are +`NULL`. +-- + endif::cl_khr_icd[] [open,refpage='clGetPlatformInfo',desc='Query information about an OpenCL platform',type='protos'] diff --git a/xml/cl.xml b/xml/cl.xml index 1745f724d..0708bba5d 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -156,6 +156,7 @@ server's OpenCL/api-docs repository. typedef struct _cl_event * cl_event; typedef struct _cl_sampler * cl_sampler; typedef struct _cl_semaphore_khr * cl_semaphore_khr; + typedef struct _cl_instance_khr * cl_instance_khr; typedef cl_uint cl_bool; typedef cl_ulong cl_bitfield; typedef cl_ulong cl_properties; @@ -255,6 +256,7 @@ server's OpenCL/api-docs repository. typedef cl_bitfield cl_platform_command_buffer_capabilities_khr; typedef cl_bitfield cl_mutable_dispatch_asserts_khr typedef cl_bitfield cl_device_kernel_clock_capabilities_khr; + typedef intptr_t cl_instance_properties_khr; Structure types @@ -710,7 +712,10 @@ server's OpenCL/api-docs repository. - + + + + @@ -731,6 +736,7 @@ server's OpenCL/api-docs repository. + @@ -2579,6 +2585,31 @@ server's OpenCL/api-docs repository. cl_platform_id platform void* dispatch_data + + cl_platform_id clIcdCreateInstancePlatformKHR + cl_platform_id platform + cl_int* errcode_ret + + + cl_int clIcdDestroyInstancePlatformKHR + cl_platform_id platform + + + cl_instance_khr clCreateInstanceKHR + const cl_instance_properties_khr* properties + cl_int* errcode_ret + + + cl_int clDestroyInstanceKHR + cl_instance_khr instance + + + cl_int clGetPlatformIDsForInstanceKHR + cl_instance_khr instance + cl_uint num_entries + cl_platform_id* platforms + cl_uint* num_platforms + cl_program clCreateProgramWithILKHR cl_context context @@ -5628,12 +5659,20 @@ server's OpenCL/api-docs repository. + + + + + + + + @@ -5642,6 +5681,11 @@ server's OpenCL/api-docs repository. + + + + +