From 890d050b7f5f638751574275dae3e1595dcf1ba9 Mon Sep 17 00:00:00 2001 From: Brice Videau Date: Fri, 24 Feb 2023 11:53:18 -0600 Subject: [PATCH 1/5] Add definition of cl_icdl extension. --- ext/cl_icdl.asciidoc | 133 +++++++++++++++++++++++++++++++++++++++++++ xml/cl.xml | 32 +++++++++++ 2 files changed, 165 insertions(+) create mode 100644 ext/cl_icdl.asciidoc diff --git a/ext/cl_icdl.asciidoc b/ext/cl_icdl.asciidoc new file mode 100644 index 000000000..d9a1d5bf7 --- /dev/null +++ b/ext/cl_icdl.asciidoc @@ -0,0 +1,133 @@ +// Copyright 2017-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/ + +[[cl_icdl-opencl]] +== OpenCL ICD Loader Info Queries + +[[cl_icdl-overview]] +=== Overview + +This section describes *cl_icdl* 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. + +=== General information + +==== Version history + +[cols="1,1,3",options="header",] +|==== +| *Date* | *Version* | *Description* +| 2023-02-24 | 1.0.0 | First assigned version. +|==== + +==== Contributors + +Vincent Danjean, Université Grenoble Alpes +Brice Videau, Argonne National Laboratory + +[[cl_icdl-new-procedures-and-functions]] +=== New Procedures and Functions + +An ICD loader needs to implement and expose through +*clGetExtensionFunctionAddress* and +*clGetExtensionFunctionAddressForPlatform* this new +entry point. + +[source,opencl] +---- +cl_int clGetICDLoaderInfoOCLICD(cl_icdl_info param_name, + size_t param_value_size, + void *param_value, + size_t *param_value_size_ret); +---- + +[[cl_icdl-new-api-types]] +=== New API Types + +[source,opencl] +---- +typedef cl_uint cl_icdl_info; +---- + +[[cl_icdl-new-enums]] +=== New API Enums + +Accepted as _param_name_ to the function *clGetICDLoaderInfoOCLICD*: + +[source,opencl] +---- +#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. + +[[cl_icdl-documentation]] +=== OpenCL ICD Loader Info Queries Documentation + +==== Querying ICD Loader Info + +[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,opencl] +---- +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="<34%,<33%,<33%",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. + +[[cl_icdl-info-queries-souce-code]] +=== Source Code + +The official source for the ICD loader is available on github, at: + +https://github.com/KhronosGroup/OpenCL-ICD-Loader +The official API headers are available on github, at: + +https://github.com/KhronosGroup/OpenCL-Headers +The header file *CL/cl_icdl.h* defines the ICD Loader info queries. diff --git a/xml/cl.xml b/xml/cl.xml index b3dbcd457..e1c2ac1a0 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. + + + + + + + + + + + + + + + + + From 42eb820c7ad949cdee37c6dd1db5e9c9db6f3c2a Mon Sep 17 00:00:00 2001 From: Brice Videau Date: Fri, 24 Feb 2023 16:05:27 -0600 Subject: [PATCH 2/5] Fix typo. --- xml/cl.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/cl.xml b/xml/cl.xml index e1c2ac1a0..bc0149f17 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -5523,7 +5523,7 @@ server's OpenCL/api-docs repository. - + From 1e9ce31eb2c03a1c4cd8a424119825111382113a Mon Sep 17 00:00:00 2001 From: Brice Videau Date: Wed, 1 Mar 2023 15:04:30 -0600 Subject: [PATCH 3/5] Updated extension proposal to be a regular extension. --- .../cl_loader_info.asciidoc | 122 ++++++++++++------ xml/cl.xml | 4 +- 2 files changed, 81 insertions(+), 45 deletions(-) rename ext/cl_icdl.asciidoc => extensions/cl_loader_info.asciidoc (61%) diff --git a/ext/cl_icdl.asciidoc b/extensions/cl_loader_info.asciidoc similarity index 61% rename from ext/cl_icdl.asciidoc rename to extensions/cl_loader_info.asciidoc index d9a1d5bf7..2f10ea7cd 100644 --- a/ext/cl_icdl.asciidoc +++ b/extensions/cl_loader_info.asciidoc @@ -1,42 +1,69 @@ -// Copyright 2017-2023 The Khronos Group. This work is licensed under a +// 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/ -[[cl_icdl-opencl]] -== OpenCL ICD Loader Info Queries +:data-uri: +:icons: font +include::../config/attribs.txt[] +:source-highlighter: coderay -[[cl_icdl-overview]] -=== Overview += cl_loader_info +:R: pass:q,r[^(R)^] +Khronos{R} OpenCL Working Group -This section describes *cl_icdl* 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. +== Name Strings -=== General information +`cl_loader_info` -==== Version history +== Contact -[cols="1,1,3",options="header",] -|==== -| *Date* | *Version* | *Description* -| 2023-02-24 | 1.0.0 | First assigned version. -|==== +Please see the *Issues* list in the Khronos *OpenCL-Docs* repository: + +https://github.com/KhronosGroup/OpenCL-Docs + +**** +The 'Contact' section describes a way for users of the extension to +report bugs or to suggest clarifications to the specification text. +It may be a pointer to a 'git' repo, or to a vendors support forum, +or an email address for the principal extension author. +**** -==== Contributors +== Contributors -Vincent Danjean, Université Grenoble Alpes +// 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 -[[cl_icdl-new-procedures-and-functions]] -=== New Procedures and Functions +This extension is written against the OpenCL Specification +Version 1.0, Revision 1. -An ICD loader needs to implement and expose through -*clGetExtensionFunctionAddress* and -*clGetExtensionFunctionAddressForPlatform* this new -entry point. +This extension requires OpenCL 1.0. -[source,opencl] +== 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, @@ -44,20 +71,18 @@ cl_int clGetICDLoaderInfoOCLICD(cl_icdl_info param_name, size_t *param_value_size_ret); ---- -[[cl_icdl-new-api-types]] -=== New API Types +== New API Types -[source,opencl] +[source,c] ---- typedef cl_uint cl_icdl_info; ---- -[[cl_icdl-new-enums]] -=== New API Enums +== New API Enums Accepted as _param_name_ to the function *clGetICDLoaderInfoOCLICD*: -[source,opencl] +[source,c] ---- #define CL_ICDL_OCL_VERSION 1 #define CL_ICDL_VERSION 2 @@ -68,14 +93,11 @@ Accepted as _param_name_ to the function *clGetICDLoaderInfoOCLICD*: Note that for backward compatibility reasons, the enum values do not follow OpenCL enum values attribution. -[[cl_icdl-documentation]] -=== OpenCL ICD Loader Info Queries Documentation - -==== Querying ICD Loader Info +== 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,opencl] +[source,c] ---- cl_int clGetICDLoaderInfoOCLICD(cl_icdl_info param_name, size_t param_value_size, @@ -121,13 +143,27 @@ Otherwise, it returns one of the following errors. type as specified in the <> table, and _param_value_ is not a `NULL` value. -[[cl_icdl-info-queries-souce-code]] -=== Source Code -The official source for the ICD loader is available on github, at: +== 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. -https://github.com/KhronosGroup/OpenCL-ICD-Loader -The official API headers are available on github, at: +== Issues -https://github.com/KhronosGroup/OpenCL-Headers -The header file *CL/cl_icdl.h* defines the ICD Loader info queries. +. 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 e1c2ac1a0..0ca879736 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -5516,9 +5516,9 @@ server's OpenCL/api-docs repository. - + - + From e120cc4d245487063697d1526674c2c396d3d93d Mon Sep 17 00:00:00 2001 From: Brice Videau Date: Wed, 1 Mar 2023 15:17:36 -0600 Subject: [PATCH 4/5] Removed comment leftover comment section. --- extensions/cl_loader_info.asciidoc | 7 ------- 1 file changed, 7 deletions(-) diff --git a/extensions/cl_loader_info.asciidoc b/extensions/cl_loader_info.asciidoc index 2f10ea7cd..e4b2d9928 100644 --- a/extensions/cl_loader_info.asciidoc +++ b/extensions/cl_loader_info.asciidoc @@ -20,13 +20,6 @@ Khronos{R} OpenCL Working Group Please see the *Issues* list in the Khronos *OpenCL-Docs* repository: + https://github.com/KhronosGroup/OpenCL-Docs -**** -The 'Contact' section describes a way for users of the extension to -report bugs or to suggest clarifications to the specification text. -It may be a pointer to a 'git' repo, or to a vendors support forum, -or an email address for the principal extension author. -**** - == Contributors // spell-checker: disable From 1a8a3b321d91a4cf07049e2d24e280d0225b5877 Mon Sep 17 00:00:00 2001 From: Brice Videau Date: Fri, 3 Mar 2023 15:11:35 -0600 Subject: [PATCH 5/5] Adjust table for better rendering in html. --- extensions/cl_loader_info.asciidoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/extensions/cl_loader_info.asciidoc b/extensions/cl_loader_info.asciidoc index e4b2d9928..e9338afd9 100644 --- a/extensions/cl_loader_info.asciidoc +++ b/extensions/cl_loader_info.asciidoc @@ -118,7 +118,9 @@ in the <> table. [[loader-queries-table]] .List of supported param_names by <> -[width="100%",cols="<34%,<33%,<33%",options="header"] +[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