diff --git a/extensions/cl_loader_info.asciidoc b/extensions/cl_loader_info.asciidoc new file mode 100644 index 000000000..e9338afd9 --- /dev/null +++ b/extensions/cl_loader_info.asciidoc @@ -0,0 +1,164 @@ +// Copyright 2018-2023 The Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ + +:data-uri: +:icons: font +include::../config/attribs.txt[] +:source-highlighter: coderay + += cl_loader_info +:R: pass:q,r[^(R)^] +Khronos{R} OpenCL Working Group + +== Name Strings + +`cl_loader_info` + +== Contact + +Please see the *Issues* list in the Khronos *OpenCL-Docs* repository: + +https://github.com/KhronosGroup/OpenCL-Docs + +== Contributors + +// spell-checker: disable +Vincent Danjean, Université Grenoble Alpes + +Brice Videau, Argonne National Laboratory +// spell-checker: enable + +== Notice + +Copyright (c) 2023 The Khronos Group Inc. + +== Status + +Final Draft + +== Version + +Built On: {docdate} + +Version: 1.0.0 + +== Dependencies + +This extension is written against the OpenCL Specification +Version 1.0, Revision 1. + +This extension requires OpenCL 1.0. + +== Overview + +This extension describes the `cl_loader_info` loader extension which +defines a simple mechanism through which an OpenCL installable client +driver loader (ICD Loader) may report loader specific meta-data such +as version or vendor. + +== New API Functions + +[source,c] +---- +cl_int clGetICDLoaderInfoOCLICD(cl_icdl_info param_name, + size_t param_value_size, + void *param_value, + size_t *param_value_size_ret); +---- + +== New API Types + +[source,c] +---- +typedef cl_uint cl_icdl_info; +---- + +== New API Enums + +Accepted as _param_name_ to the function *clGetICDLoaderInfoOCLICD*: + +[source,c] +---- +#define CL_ICDL_OCL_VERSION 1 +#define CL_ICDL_VERSION 2 +#define CL_ICDL_NAME 3 +#define CL_ICDL_VENDOR 4 +---- + +Note that for backward compatibility reasons, the enum values do not +follow OpenCL enum values attribution. + +== Modifications to the OpenCL API Specification + +[open,refpage='clGetICDLoaderInfoOCLICD',desc='Query information about an OpenCL ICD Loader',type='protos'] +Information concerning an OpenCL ICD Loader can be obtained with the function: +[source,c] +---- +cl_int clGetICDLoaderInfoOCLICD(cl_icdl_info param_name, + size_t param_value_size, + void *param_value, + size_t *param_value_size_ret); +---- + + * _param_name_ is an enumeration constant that identifies the ICD loader + information being queried. It can be one of the following values as + specified in the <> table. + * _param_value_size_ specifies the size in bytes of memory pointed to by + _param_value_. + This size in bytes must be ≥ to the size of return type specified in the + <> table. + * _param_value_ is a pointer to memory location where appropriate values for a + given _param_name_, as specified in the <> table, will be returned. + If _param_value_ is `NULL`, it is ignored. + * _param_value_size_ret_ returns the actual size in bytes of data being + queried by _param_name_. + If _param_value_size_ret_ is `NULL`, it is ignored. + +The information that can be queried using *clGetICDLoaderInfoOCLICD* is specified +in the <> table. + +[[loader-queries-table]] +.List of supported param_names by <> +[width="100%"] +[cols="30,20,80"] +[options="header"] +|==== +| ICD Loader Info | Return Type | Description +| *CL_ICDL_OCL_VERSION* | char[] | OpenCL version supported by the ICD Loader +| *CL_ICDL_VERSION* | char[] | ICD Loader version string +| *CL_ICDL_NAME* | char[] | ICD Loader name string +| *CL_ICDL_VENDOR* | char[] | ICD Loader vendor string +|==== + +*clGetICDLoaderInfoOCLICD* returns *CL_SUCCESS* if the function is +executed successfully. +Otherwise, it returns one of the following errors. + + * *CL_INVALID_VALUE* if _param_name_ is not one of the supported values or + if size in bytes specified by _param_value_size_ is < size of return + type as specified in the <> table, + and _param_value_ is not a `NULL` value. + + +== Conformance tests + +. The new *clGetICDLoaderInfoOCLICD* entrypoint must be called and succeed. +. The value returned for `CL_ICDL_OCL_VERSION` must repect the OpenCL version + string format. + +== Issues + +. Should this extension be a regular extension? ++ +-- +*RESOLVED*: Yes. This is a userfacing extension. +-- + +== Version History + +[cols="5,15,15,70"] +[grid="rows"] +[options="header"] +|==== +| Version | Date | Author | Changes +| 1.0.0 | 2023-03-01 | Brice Videau | *Initial revision* +|==== diff --git a/xml/cl.xml b/xml/cl.xml index b3dbcd457..614ecc951 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -223,6 +223,7 @@ server's OpenCL/api-docs repository. typedef cl_bitfield cl_mem_alloc_flags_img; typedef cl_uint cl_layer_info; typedef cl_uint cl_layer_api_version; + typedef cl_uint cl_icdl_info; typedef struct _cl_icd_dispatch cl_icd_dispatch; typedef cl_bitfield cl_device_scheduling_controls_capabilities_arm; typedef cl_bitfield cl_device_controlled_termination_capabilities_arm; @@ -2212,6 +2213,13 @@ server's OpenCL/api-docs repository. + + + + + + + @@ -4115,6 +4123,13 @@ server's OpenCL/api-docs repository. cl_uint* num_entries_ret const cl_icd_dispatch** layer_dispatch + + cl_int clGetICDLoaderInfoOCLICD + cl_icdl_info param_name + size_t param_value_size + void* param_value + size_t* param_value_size_ret + cl_int clGetSupportedGLTextureFormatsINTEL cl_context context @@ -5501,6 +5516,23 @@ server's OpenCL/api-docs repository. + + + + + + + + + + + + + + + + +