From ce502ecc7dbf4cd2c5c271e74cb14c86bfaa587d Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Tue, 26 Mar 2024 09:06:56 -0700 Subject: [PATCH 01/71] Switch to GitHub Actions for CI (#1085) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * WIP First stab at Github Actions * sudo * remove travis config * change travis builds to only build on tags * sync GitHub actions with travis script * configure dependabot github actions version updates * update gem versions * add libwebp-dev dependency for asciidoctor-mathematical * minor updates * update for the new spec toolchain --------- Co-authored-by: Kévin Petit --- .github/dependabot.yml | 10 +++++++ .github/workflows/presubmit.yml | 49 +++++++++++++++++++++++++++++++++ .travis.yml | 4 +++ 3 files changed, 63 insertions(+) create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/presubmit.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..2390d8c80 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,10 @@ +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "monthly" + groups: + github-actions: + patterns: + - "*" diff --git a/.github/workflows/presubmit.yml b/.github/workflows/presubmit.yml new file mode 100644 index 000000000..605571254 --- /dev/null +++ b/.github/workflows/presubmit.yml @@ -0,0 +1,49 @@ +name: Presubmit + +permissions: + contents: read + +on: [push, pull_request] + +jobs: + build: + name: Build all specs + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + submodules: recursive + + - name: Install required packages + run: | + sudo apt-get install -y libpango1.0-dev libwebp-dev ghostscript fonts-lyx jing libavalon-framework-java libbatik-java python3-pyparsing + sudo gem install asciidoctor -v 2.0.16 + sudo gem install coderay -v 1.1.1 + sudo gem install rouge -v 3.19.0 + sudo gem install ttfunk -v 1.7.0 + sudo gem install hexapdf -v 0.27.0 + sudo gem install asciidoctor-pdf -v 2.3.4 + sudo gem install asciidoctor-mathematical -v 0.3.5 + sudo pip install pyparsing + + - name: List git tag + run: | + git describe --tags --dirty + + - name: Generate core specs (HTML and PDF) + run: | + python3 makeSpec -clean -spec core OUTDIR=out.core -j 5 api c env ext cxx4opencl + + - name: Generate core + extension specs (HTML) + run: | + python3 makeSpec -clean -spec khr OUTDIR=out.khr -j 12 html + + - name: Generate reference pages + run: | + python3 makeSpec -spec khr OUTDIR=out.refpages -j 12 manhtmlpages + + - name: Validate XML + run: | + make -C xml validate diff --git a/.travis.yml b/.travis.yml index f8e77eddd..bc8f9117f 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,5 +1,9 @@ dist: focal +# Only build (and deploy) on travis for tags. +# Use GitHub actions for other CI. +if: tag IS present + language: ruby git: From 484432c01240d8468f295e3a9941ced3823c73b7 Mon Sep 17 00:00:00 2001 From: Ewan Crawford Date: Tue, 26 Mar 2024 16:12:42 +0000 Subject: [PATCH 02/71] Reference layered extensions in command-buffer intro (#1090) The "Interaction With Other Extensions" introductory section of `cl_khr_command_buffer` references future layered extensions as part of the design rationale. Two of these layered extensions currently exist, so we can update this section to reference them directly as opposed to the existing speculative language. --- api/cl_khr_command_buffer.asciidoc | 39 ++++++++++++++++++------------ 1 file changed, 23 insertions(+), 16 deletions(-) diff --git a/api/cl_khr_command_buffer.asciidoc b/api/cl_khr_command_buffer.asciidoc index 6099d7729..d866b92a0 100644 --- a/api/cl_khr_command_buffer.asciidoc +++ b/api/cl_khr_command_buffer.asciidoc @@ -123,9 +123,12 @@ the capability is optional to enable optimizations on command-buffer recording. The introduction of the command-buffer abstraction enables functionality beyond what the `cl_khr_command_buffer` extension currently provides, i.e. the recording of immutable commands to a single queue which can then be -executed without commands synchronizing outside the command-buffer. It is -intended that extra functionality expanding on this will be provided as layered -extensions on top of `cl_khr_command_buffer`. +executed without commands synchronizing outside the command-buffer. Extra +functionality expanding on this is provided as layered extensions on top of +`cl_khr_command_buffer`. The layered extensions that currently exist are: + +* `<>` +* `<>` Having `cl_khr_command_buffer` as a minimal base specification means that the API defines mechanisms for functionality that is not enabled by this extension, @@ -138,29 +141,33 @@ support their intended use cases. The {clCommandNDRangeKernelKHR} entry-point defines a `properties` parameter of new type {cl_ndrange_kernel_command_properties_khr_TYPE}. No properties are defined -in `cl_khr_command_buffer`, but the parameter is intended to enable future -functionality that would change the characteristics of the kernel command. +in `cl_khr_command_buffer`, but the parameter enables layered extensions like +`<>` to define properties that inform +the characteristics of the kernel command. ==== Command Handles All command recording entry-points define a {cl_mutable_command_khr_TYPE} output parameter which provides a handle to the specific command being recorded. Use of these output handles is not enabled by the `cl_khr_command_buffer` extension, -but the handles will allow individual commands in a command-buffer to be -referenced by the user. In particular, the capability for an application to use -these handles to modify commands between enqueues of a command-buffer is -envisaged. +but the handles allow individual commands in a command-buffer to be +referenced by the user. + +Use of these handles is enabled in `<>` +to give the capability for an application to use the handles to modify commands +between enqueues of a command-buffer. ==== List of Queues Only a single command-queue can be associated with a command-buffer in the -`cl_khr_command_buffer` extension, but the API is designed with the intention -that a future extension will allow commands to be recorded across multiple -queues in the same command-buffer, providing replay of heterogeneous task -graphs. - -Using multiple queue functionality will result in an error without any layered -extensions to relax usage of the following API features: +`cl_khr_command_buffer` extension, but the API is designed so that the layered +`<>` extension can relax this constraint +to allow commands to be recorded across multiple queues in the same +command-buffer, providing replay of heterogeneous task graphs. + +Using multiple queue functionality will result in an error without +`<>` to relax usage of the following API +features: * When a command-buffer is created the API enables passing a list of queues that the command-buffer will record commands to. Only a single queue is From be1aa793068ba1816ab197bfb7247f26bb685c96 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Tue, 26 Mar 2024 09:14:03 -0700 Subject: [PATCH 03/71] fixes a few incorrect asciidoctor attributes (#1091) --- OpenCL_API.txt | 3 +++ api/cl_khr_command_buffer.asciidoc | 16 ++++++++-------- api/cl_khr_device_uuid.asciidoc | 2 +- api/cl_khr_egl_event.asciidoc | 2 +- api/cl_khr_gl_sharing.asciidoc | 4 ++-- api/cl_khr_semaphore.asciidoc | 2 +- api/cl_khr_subgroups.asciidoc | 2 +- api/opencl_architecture.asciidoc | 8 ++++---- api/opencl_runtime_layer.asciidoc | 28 +++++++++++++--------------- 9 files changed, 34 insertions(+), 33 deletions(-) diff --git a/OpenCL_API.txt b/OpenCL_API.txt index 2be31d8e1..2be2268ca 100644 --- a/OpenCL_API.txt +++ b/OpenCL_API.txt @@ -39,6 +39,9 @@ include::config/version-local-links.asciidoc[] // Formatting and links for API functions and enums. include::api/dictionary.asciidoc[] +// Feature Dictionary - used by some extensions. +include::c/feature-dictionary.asciidoc[] + // External Footnotes include::api/footnotes.asciidoc[] diff --git a/api/cl_khr_command_buffer.asciidoc b/api/cl_khr_command_buffer.asciidoc index d866b92a0..a4ade6c6e 100644 --- a/api/cl_khr_command_buffer.asciidoc +++ b/api/cl_khr_command_buffer.asciidoc @@ -207,8 +207,8 @@ features: === New Structures - * {cl_command_buffer_khr} - * {cl_mutable_command_khr} + * {cl_command_buffer_khr_TYPE} + * {cl_mutable_command_khr_TYPE} === New Types @@ -227,19 +227,15 @@ features: * {cl_device_info_TYPE} ** {CL_DEVICE_COMMAND_BUFFER_CAPABILITIES_KHR} ** {CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR} - * {cl_device_command_buffer_capabilities_khr - bitfield_TYPE} + * {cl_device_command_buffer_capabilities_khr_TYPE} ** {CL_COMMAND_BUFFER_CAPABILITY_KERNEL_PRINTF_KHR} ** {CL_COMMAND_BUFFER_CAPABILITY_DEVICE_SIDE_ENQUEUE_KHR} ** {CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR} ** {CL_COMMAND_BUFFER_CAPABILITY_OUT_OF_ORDER_KHR} * {cl_command_buffer_properties_khr_TYPE} ** {CL_COMMAND_BUFFER_FLAGS_KHR} - * {cl_command_buffer_flags_khr - bitfield_TYPE} + * {cl_command_buffer_flags_khr_TYPE} ** {CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR} - * {Error codes_TYPE} - ** {CL_INVALID_COMMAND_BUFFER_KHR} - ** {CL_INVALID_SYNC_POINT_WAIT_LIST_KHR} - ** {CL_INCOMPATIBLE_COMMAND_QUEUE_KHR} * {cl_command_buffer_info_khr_TYPE} ** {CL_COMMAND_BUFFER_QUEUES_KHR} ** {CL_COMMAND_BUFFER_NUM_QUEUES_KHR} @@ -253,6 +249,10 @@ features: ** {CL_COMMAND_BUFFER_STATE_PENDING_KHR} * {cl_command_type_TYPE} ** {CL_COMMAND_COMMAND_BUFFER_KHR} + * New Error Codes + ** {CL_INVALID_COMMAND_BUFFER_KHR} + ** {CL_INVALID_SYNC_POINT_WAIT_LIST_KHR} + ** {CL_INCOMPATIBLE_COMMAND_QUEUE_KHR} === Sample Code diff --git a/api/cl_khr_device_uuid.asciidoc b/api/cl_khr_device_uuid.asciidoc index 023b34dfd..87f803daf 100644 --- a/api/cl_khr_device_uuid.asciidoc +++ b/api/cl_khr_device_uuid.asciidoc @@ -23,7 +23,7 @@ across processes or APIs. Accepted value for the _param_name_ parameter to {clGetDeviceInfo}: - * {cl_device_info} + * {cl_device_info_TYPE} ** {CL_DEVICE_UUID_KHR} ** {CL_DRIVER_UUID_KHR} ** {CL_DEVICE_LUID_VALID_KHR} diff --git a/api/cl_khr_egl_event.asciidoc b/api/cl_khr_egl_event.asciidoc index 86b5fbb32..f9663530f 100644 --- a/api/cl_khr_egl_event.asciidoc +++ b/api/cl_khr_egl_event.asciidoc @@ -54,7 +54,7 @@ context, and to reach into each such context. . Should we restrict which CL APIs can be used with this cl_event? + -- -*RESOLVED* Use is limited to {clEnqueueAcquire}*** calls only. +*RESOLVED* Use is limited to calls to acquire and release memory objects only. -- . What is the desired behaviour for this extension when EGLSyncKHR is of a diff --git a/api/cl_khr_gl_sharing.asciidoc b/api/cl_khr_gl_sharing.asciidoc index b6c55df65..7d1bcdaa8 100644 --- a/api/cl_khr_gl_sharing.asciidoc +++ b/api/cl_khr_gl_sharing.asciidoc @@ -23,7 +23,7 @@ object, using additional attributes described for {clCreateContext}. An OpenCL image object may be created from an OpenGL texture or renderbuffer object as described for {clCreateFromGLTexture} and -{clCreateFromGLRenderuffer}, respectively. +{clCreateFromGLRenderbuffer}, respectively. An OpenCL buffer object may be created from an OpenGL buffer object using {clCreateFromGLBuffer}. @@ -59,7 +59,7 @@ and buffer object images with OpenCL is required by this extension. * {cl_gl_context_info_TYPE} * {cl_gl_object_type_TYPE} * {cl_gl_texture_info_TYPE} - * {cl_gl_platform_info} + * {cl_gl_platform_info_TYPE} === New Tokens diff --git a/api/cl_khr_semaphore.asciidoc b/api/cl_khr_semaphore.asciidoc index 43c2b1ae9..25c8cdd48 100644 --- a/api/cl_khr_semaphore.asciidoc +++ b/api/cl_khr_semaphore.asciidoc @@ -93,7 +93,7 @@ In particular, this extension defines: * New return values from {clGetEventInfo} ** {CL_COMMAND_SEMAPHORE_WAIT_KHR} ** {CL_COMMAND_SEMAPHORE_SIGNAL_KHR} - * New error codes + * New Error Codes ** {CL_INVALID_SEMAPHORE_KHR} diff --git a/api/cl_khr_subgroups.asciidoc b/api/cl_khr_subgroups.asciidoc index 4acff29aa..bc5e2df20 100644 --- a/api/cl_khr_subgroups.asciidoc +++ b/api/cl_khr_subgroups.asciidoc @@ -35,7 +35,7 @@ OpenCL C specification for more information. === New Types - * {cl_kernel_sub_group_info} + * {cl_kernel_sub_group_info_TYPE} === New Commands diff --git a/api/opencl_architecture.asciidoc b/api/opencl_architecture.asciidoc index 3ad82c904..a342edbf3 100644 --- a/api/opencl_architecture.asciidoc +++ b/api/opencl_architecture.asciidoc @@ -2232,7 +2232,7 @@ working with version numbers easier. {CL_VERSION_PATCH_BITS_anchor} are the number of bits in the corresponding field. * `CL_VERSION_MAJOR_MASK`, `CL_VERSION_MINOR_MASK`, and - {CL_VERSION_PATCH_MASK` are bitmasks used to extract the + `CL_VERSION_PATCH_MASK` are bitmasks used to extract the corresponding packed fields from the version number. [source,opencl] @@ -2274,7 +2274,7 @@ corresponding entity (e.g. extension or built-in kernel) name: include::{generated}/api/structs/cl_name_version.txt[] * _version_ is a <>. - * _name_ is an array of {CL_NAME_VERSION_MAX_NAME_SIZE_anchor} `char` - containing a null-terminated string whose maximum length is therefore - {CL_NAME_VERSION_MAX_NAME_SIZE} - 1`. + * _name_ is an array of {CL_NAME_VERSION_MAX_NAME_SIZE_anchor} characters + containing a null-terminated string, whose maximum length is therefore + {CL_NAME_VERSION_MAX_NAME_SIZE} minus one. -- diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 298620641..bb1146285 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -4727,19 +4727,19 @@ ifdef::cl_khr_egl_image[] [open,refpage='clCreateFromEGLImageKHR',desc='Create cl_mem target from EGLImage source',type='protos'] -- -To create an `EGLImage` target of type {cl_mem} from the `EGLImage` source +To create an `EGLImage` target of type {cl_mem_TYPE} from the `EGLImage` source provided as _image_, call the function include::{generated}/api/protos/clCreateFromEGLImageKHR.txt[] include::{generated}/api/version-notes/clCreateFromEGLImageKHR.asciidoc[] * _display_ should be of type `EGLDisplay`, cast into the type - {CLeglDisplayKHR}. + {CLeglDisplayKHR_TYPE}. * _image_ should be of type `EGLImageKHR`, cast into the type {CLeglImageKHR_TYPE}. Assuming no errors are generated in this function, the resulting image object will be an `EGLImage` target of the specified `EGLImage` _image_. - The resulting {cl_mem} is an image object which may be used normally by + The resulting {cl_mem_TYPE} is an image object which may be used normally by all OpenCL operations. This maps to an `image2d_t` type in OpenCL kernel code. * _flags_ is a bit-field that is used to specify usage information about @@ -4786,7 +4786,7 @@ returned in _errcode_ret_: above. * {CL_INVALID_EGL_OBJECT_KHR} if _image_ is not a valid `EGLImage` object. * {CL_IMAGE_FORMAT_NOT_SUPPORTED} if the OpenCL implementation is not able - to create a {cl_mem} compatible with the provided {CLeglImageKHR_TYPE} + to create a {cl_mem_TYPE} compatible with the provided {CLeglImageKHR_TYPE} for an implementation-dependent reason (this could be caused by, but not limited to, reasons such as unsupported texture formats, etc). * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources @@ -6264,7 +6264,7 @@ include::{generated}/api/version-notes/clGetGLTextureInfo.asciidoc[] .OpenGL texture info that may be queried with {clGetGLTextureInfo} [cols=",,",options="header",] |==== -| {cl_gl_texture_info} | Return Type | Info. Returned in _param_value_ +| {cl_gl_texture_info_TYPE} | Return Type | Info. Returned in _param_value_ | {CL_GL_TEXTURE_TARGET_anchor} include::{generated}/api/version-notes/CL_GL_TEXTURE_TARGET.asciidoc[] @@ -7153,10 +7153,9 @@ memory objects through the other API with which such objects are shared. Failure to provide such synchronization may result in race conditions and other undefined behavior including non-portability between implementations. -Prior to acquiring objects shared with the other API via an appropriate -{clEnqueueAcquire}*** call, the application must ensure that any pending -operations in that API which accesses the objects specified in _mem_objects_ -have completed. +Prior to acquiring objects shared with the other API, the application must +ensure that any pending operations in that API which accesses the objects +specified in _mem_objects_ have completed. Depending on the application and the implementation, there are two extensions which may be used to synchronize with other APIs: @@ -7216,10 +7215,9 @@ are supported on a platform. ===== Synchronizing OpenCL Operations With Other APIs -After releasing a shared memory object via an appropriate -{clEnqueueRelease}*** call, the application is responsible for ensuring that -any pending OpenCL operations which access the objects specified in -_mem_objects_ have completed prior to executing subsequent commands in the +After releasing a shared memory object, the application is responsible for +ensuring that any pending OpenCL operations which access the objects specified +in _mem_objects_ have completed prior to executing subsequent commands in the other API which reference these objects. This may be accomplished portably by calling {clWaitForEvents} with the @@ -12348,7 +12346,7 @@ When the event object is deleted, the reference will be removed from the EGL sync object. Events returned from {clCreateEventFromEGLSyncKHR} may only be consumed by -{clEnqueueAcquire}*** commands. +commands to acquire and release memory objects. Passing such events to any other CL API that enqueues commands will generate a {CL_INVALID_EVENT} error. @@ -12452,7 +12450,7 @@ sync object. Events returned from {clCreateEventFromGLsyncKHR} can be used in the _event_wait_list_ argument to {clEnqueueAcquireGLObjects} and CL APIs that -take a {cl_event} as an argument but do not enqueue commands. +take a {cl_event_TYPE} as an argument but do not enqueue commands. Passing such events to any other CL API that enqueues commands will generate a {CL_INVALID_EVENT} error. -- From 65fc388ef76d09cd400ede61b1ebd29a60d48bdf Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Tue, 26 Mar 2024 09:19:17 -0700 Subject: [PATCH 04/71] strengthen requirements for CL_DEVICE_TYPE query (#1069) * strengthen requirements for CL_DEVICE_TYPE query * require that an OpenCL device only reports a single device type * clarify device types that may be used with clCreateContextFromType --- api/opencl_platform_layer.asciidoc | 32 +++++++++++++++--------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index b27079192..c09ff4304 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -383,12 +383,18 @@ include::{generated}/api/version-notes/CL_DEVICE_TYPE_ACCELERATOR.asciidoc[] include::{generated}/api/version-notes/CL_DEVICE_TYPE_CUSTOM.asciidoc[] | Specialized devices that implement some of the OpenCL runtime APIs but - do not support all required OpenCL functionality. + do not support all of the required OpenCL functionality. | {CL_DEVICE_TYPE_DEFAULT_anchor} include::{generated}/api/version-notes/CL_DEVICE_TYPE_DEFAULT.asciidoc[] | The default OpenCL device in the platform. + One device in the platform must be returned as the {CL_DEVICE_TYPE_DEFAULT} + device when passed as the _device_type_ to {clGetDeviceIDs}. + {CL_DEVICE_TYPE_DEFAULT} is only used to query OpenCL devices using + {clGetDeviceIDs} or to create OpenCL contexts using + {clCreateContextFromType}, and will never be returned in {CL_DEVICE_TYPE} + for any OpenCL device. The default OpenCL device must not be a {CL_DEVICE_TYPE_CUSTOM} device. | {CL_DEVICE_TYPE_ALL_anchor} @@ -396,22 +402,13 @@ include::{generated}/api/version-notes/CL_DEVICE_TYPE_DEFAULT.asciidoc[] include::{generated}/api/version-notes/CL_DEVICE_TYPE_ALL.asciidoc[] | All OpenCL devices available in the platform, except for {CL_DEVICE_TYPE_CUSTOM} devices. + {CL_DEVICE_TYPE_ALL} is only used to query OpenCL devices using + {clGetDeviceIDs} or to create OpenCL contexts using + {clCreateContextFromType}, and will never be returned in {CL_DEVICE_TYPE} + for any OpenCL device. |==== -The device type is purely informational and has no semantic meaning. - -Some devices may be more than one type. -For example, a {CL_DEVICE_TYPE_CPU} device may also be a -{CL_DEVICE_TYPE_GPU} device, or a {CL_DEVICE_TYPE_ACCELERATOR} device -may also be some other, more descriptive device type. -{CL_DEVICE_TYPE_CUSTOM} devices must not be combined with any other -device types. - -One device in the platform should be a {CL_DEVICE_TYPE_DEFAULT} device. -The default device should also be a more specific device type, such -as {CL_DEVICE_TYPE_CPU} or {CL_DEVICE_TYPE_GPU}. - // refError {clGetDeviceIDs} returns {CL_SUCCESS} if the function is executed @@ -483,10 +480,13 @@ device except for the following queries: include::{generated}/api/version-notes/CL_DEVICE_TYPE.asciidoc[] | {cl_device_type_TYPE} - | The type or types of the OpenCL device. + | The type of the OpenCL device. + The device type is purely informational and has no semantic meaning. + The device must report a single device type, which must not be + {CL_DEVICE_TYPE_DEFAULT} or {CL_DEVICE_TYPE_ALL}. Please see the <> table - for supported device types and device type combinations. + for supported device types and device type descriptions. | {CL_DEVICE_VENDOR_ID_anchor} footnote:[{fn-vendor-id}] From 2e912fd7f4f72a36ef33b68df859107918012ad1 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Tue, 26 Mar 2024 09:20:02 -0700 Subject: [PATCH 05/71] fix a markup issue regarding cl_khr_subgroup_extended_types (#1104) --- OpenCL_C.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/OpenCL_C.txt b/OpenCL_C.txt index 5e7776c9b..eab333330 100644 --- a/OpenCL_C.txt +++ b/OpenCL_C.txt @@ -13888,8 +13888,8 @@ footnote:[{fn-half-supported}], `float`, and `double` footnote:[{fn-double-supported}]. ifdef::cl_khr_subgroup_extended_types[] -NOTE: If the `<>` extension is supported, -the supported `gentype`s also include `char`, `uchar`, `short`, and +NOTE: If the `<>` extension is supported, the +generic type name `gentype` may additionally be `char`, `uchar`, `short`, and `ushort`. For the `sub_group_broadcast` function, `gentype` may additionally be one of the supported built-in vector data types `char__n__`, `uchar__n__`, From bb480d8dbae9c9b0b09ea3bd17376b991b6de68a Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Tue, 26 Mar 2024 09:20:11 -0700 Subject: [PATCH 06/71] fix footnotes (#1097) Moves text for CL_KERNEL_ARG_TYPE_QUALIFIER out of a footnote and into the main spec text. Removes link to the cl_khr_fp16 extension for the footnote. This is not ideal, but is a reasonable short-term solution. --- api/footnotes.asciidoc | 15 +-------------- api/opencl_runtime_layer.asciidoc | 26 ++++++++++++++++++++++---- 2 files changed, 23 insertions(+), 18 deletions(-) diff --git a/api/footnotes.asciidoc b/api/footnotes.asciidoc index e21cb8719..26e1454f3 100644 --- a/api/footnotes.asciidoc +++ b/api/footnotes.asciidoc @@ -68,19 +68,6 @@ This value for memory_scope can only be used with atomic_work_item_fence with fl Note that the performance of 64-bit integer arithmetic can vary significantly between embedded devices. \ ] -:fn-kernel-arg-type-const-addr-space: pass:n[ \ -{CL_KERNEL_ARG_TYPE_CONST} is returned for {CL_KERNEL_ARG_TYPE_QUALIFIER} if the argument is declared with the `constant` address space qualifier. \ -] - -:fn-kernel-arg-type-qualifier: pass:n[ \ -{CL_KERNEL_ARG_TYPE_CONST} is returned if the argument is a pointer and the referenced type is declared with the const qualifier. \ -For example, a kernel argument declared as `global int const *x` returns {CL_KERNEL_ARG_TYPE_CONST} but a kernel argument declared as `global int * const x` does not. + \ -Similarly, {CL_KERNEL_ARG_TYPE_RESTRICT} will be returned if the pointer type is marked `restrict`. \ -For example, `global int * restrict x` returns {CL_KERNEL_ARG_TYPE_RESTRICT}. + \ -{CL_KERNEL_ARG_TYPE_VOLATILE} is returned for {CL_KERNEL_ARG_TYPE_QUALIFIER} if the argument is a pointer and the referenced type is declared with the volatile qualifier. \ -For example, a kernel argument declared as `global int volatile *x` returns {CL_KERNEL_ARG_TYPE_VOLATILE} but a kernel argument declared as `global int * volatile x` does not. \ -] - :fn-map-count-usage: pass:n[ \ The map count returned should be considered immediately stale. \ It is unsuitable for general use in applications. \ @@ -120,7 +107,7 @@ Rather than attempt to share {cl_kernel_TYPE} objects among multiple host thread ] :fn-readimageh: pass:n[ \ -And *read_imageh*, if the `<>` extension is supported. \ +And *read_imageh*, if the `cl_khr_fp16` extension is supported. \ ] :fn-reference-count-usage: pass:n[ \ diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index bb1146285..de138f557 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -11078,15 +11078,33 @@ include::{generated}/api/version-notes/CL_KERNEL_ARG_TYPE_QUALIFIER.asciidoc[] for the argument given by _arg_index_. The returned values can be: - {CL_KERNEL_ARG_TYPE_CONST_anchor} - footnote:[{fn-kernel-arg-type-qualifier}] - footnote:[{fn-kernel-arg-type-const-addr-space}] + + {CL_KERNEL_ARG_TYPE_CONST_anchor} + {CL_KERNEL_ARG_TYPE_RESTRICT_anchor} + {CL_KERNEL_ARG_TYPE_VOLATILE_anchor} + {CL_KERNEL_ARG_TYPE_PIPE_anchor}, or + {CL_KERNEL_ARG_TYPE_NONE_anchor} - {CL_KERNEL_ARG_TYPE_NONE} is returned for all parameters passed by + {CL_KERNEL_ARG_TYPE_CONST} is returned if the kernel argument is a + pointer and the referenced type is declared with the `const` qualifier. + For example, a kernel argument declared as `global int const*` returns + {CL_KERNEL_ARG_TYPE_CONST} but a kernel argument declared as `global + int* const` does not. + Additionally, {CL_KERNEL_ARG_TYPE_CONST} is returned if the kernel + argument is declared with the `constant` address space qualifier. + + {CL_KERNEL_ARG_TYPE_RESTRICT} is returned if the pointer type is marked + `restrict`. + For example, `global int* restrict` returns + {CL_KERNEL_ARG_TYPE_RESTRICT}. + + {CL_KERNEL_ARG_TYPE_VOLATILE} is returned for + {CL_KERNEL_ARG_TYPE_QUALIFIER} if the kernel argument is a pointer and + the referenced type is declared with the `volatile` qualifier. + For example, a kernel argument declared as `global int volatile*` + returns {CL_KERNEL_ARG_TYPE_VOLATILE} but a kernel argument declared as + `global int* volatile` does not. + + {CL_KERNEL_ARG_TYPE_NONE} is returned for all kernel arguments passed by value. | {CL_KERNEL_ARG_NAME_anchor} From 00c79690be2454ccc3a9e7cfd348af5d24fa4869 Mon Sep 17 00:00:00 2001 From: Ewan Crawford Date: Tue, 26 Mar 2024 18:47:04 +0000 Subject: [PATCH 07/71] Fixup cl_khr_command_buffer after spec unification (#1089) After PR #950 merged the cl_khr_command_buffer spec needs updated in a couple of places: * Error around _num_queues_ to `clCreateCommandBufferKHR` should be in terms of `cl_khr_command_buffer_multi_device`. * "New Structure" heading can be deleted as these are listed under "New Types" * Typos in rendering of some types --- api/cl_khr_command_buffer.asciidoc | 5 ----- api/opencl_runtime_layer.asciidoc | 5 ++++- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/api/cl_khr_command_buffer.asciidoc b/api/cl_khr_command_buffer.asciidoc index a4ade6c6e..a71d0ec99 100644 --- a/api/cl_khr_command_buffer.asciidoc +++ b/api/cl_khr_command_buffer.asciidoc @@ -205,11 +205,6 @@ features: ** {clCommandSVMMemcpyKHR} ** {clCommandSVMMemFillKHR} -=== New Structures - - * {cl_command_buffer_khr_TYPE} - * {cl_mutable_command_khr_TYPE} - === New Types * {cl_device_command_buffer_capabilities_khr_TYPE} diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index de138f557..cb7908951 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -14145,7 +14145,10 @@ returned in _errcode_ret_: specified by {CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR}. * {CL_INVALID_CONTEXT} if all the command-queues in _queues_ do not have the same OpenCL context. - * {CL_INVALID_VALUE} if _num_queues_ is zero. + * {CL_INVALID_VALUE} if the `<>` + extension is supported and _num_queues_ is zero, or if the + `<>` extension is not supported + and _num_queues_ is not one. * {CL_INVALID_VALUE} if _queues_ is `NULL`. * {CL_INVALID_VALUE} if values specified in _properties_ are not valid, or if the same property name is specified more than once. From c1f23242218e7ebef19622f32c7c9786976e485c Mon Sep 17 00:00:00 2001 From: Ewan Crawford Date: Sun, 31 Mar 2024 19:00:21 +0100 Subject: [PATCH 08/71] Set anchor on `CL_COMMAND_BUFFER_MUTABLE_KHR` (#1115) The link in the "New Enums" section of cl_khr_command_buffer_mutable_dispatch doesn't lead anywhere otherwise. --- api/opencl_runtime_layer.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index cb7908951..b8af9a812 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -14051,7 +14051,7 @@ include::{generated}/api/version-notes/CL_COMMAND_BUFFER_DEVICE_SIDE_SYNC_KHR.as endif::cl_khr_command_buffer_multi_device[] ifdef::cl_khr_command_buffer_mutable_dispatch[] - {CL_COMMAND_BUFFER_MUTABLE_KHR} - Enables modification of the + {CL_COMMAND_BUFFER_MUTABLE_KHR_anchor} - Enables modification of the command-buffer, by default command-buffers are immutable. If set, commands in the command-buffer may be updated via {clUpdateMutableCommandsKHR}. From 65043c4685dffa7ce66188f4cbb21117a90fcf25 Mon Sep 17 00:00:00 2001 From: Jon Leech <4693344+oddhack@users.noreply.github.com> Date: Sun, 31 Mar 2024 11:05:00 -0700 Subject: [PATCH 09/71] Fix provisional extension notes in appendices (#1113) * Remove provisional notice include for recently ratified extensions * Remove provisional_notice include for each provisional extensions. Add a new subsection of the extensions appendix capturing the same information. The autogenerated link in the extension metadata for each provisional extension links to this subsection. --- api/appendix_extensions.asciidoc | 16 ++++++++++++++++ api/cl_khr_command_buffer.asciidoc | 2 -- api/cl_khr_command_buffer_multi_device.asciidoc | 2 -- ..._khr_command_buffer_mutable_dispatch.asciidoc | 2 -- api/cl_khr_external_memory.asciidoc | 2 -- api/cl_khr_external_memory_dma_buf.asciidoc | 4 ---- api/cl_khr_external_memory_dx.asciidoc | 4 ---- api/cl_khr_external_memory_opaque_fd.asciidoc | 4 ---- api/cl_khr_external_memory_win32.asciidoc | 4 ---- api/cl_khr_external_semaphore.asciidoc | 4 ---- api/cl_khr_external_semaphore_dx_fence.asciidoc | 4 ---- api/cl_khr_external_semaphore_opaque_fd.asciidoc | 4 ---- api/cl_khr_external_semaphore_sync_fd.asciidoc | 4 ---- api/cl_khr_external_semaphore_win32.asciidoc | 4 ---- api/cl_khr_semaphore.asciidoc | 4 ---- 15 files changed, 16 insertions(+), 48 deletions(-) diff --git a/api/appendix_extensions.asciidoc b/api/appendix_extensions.asciidoc index 2e5ceccbb..0c2d4dc4e 100644 --- a/api/appendix_extensions.asciidoc +++ b/api/appendix_extensions.asciidoc @@ -25,6 +25,22 @@ alphabetically by author ID. Within each group, extensions are listed in alphabetical order by their names. + +[[boilerplate-provisional-header]] +== Provisional Extensions + +_Provisional_ OpenCL extensions described in this appendix have been +Ratified under the Khronos Intellectual Property Framework. +They are being made publicly available as provisional extensions to enable +review and feedback from the community. +While an extension is provisional, features may be added, removed, or +changed in non-backward compatible ways. + +If you have feedback on a provisional extension, please create an issue on +the link:https://github.com/KhronosGroup/OpenCL-Docs/[OpenCL-Docs +repository]. + + == Extension Dependencies Extensions which have dependencies on specific core versions or on other diff --git a/api/cl_khr_command_buffer.asciidoc b/api/cl_khr_command_buffer.asciidoc index a71d0ec99..e5da09a4f 100644 --- a/api/cl_khr_command_buffer.asciidoc +++ b/api/cl_khr_command_buffer.asciidoc @@ -419,8 +419,6 @@ features: *UNRESOLVED* -- -include::provisional_notice.asciidoc[] - === Version History * Revision 0.9.0, 2021-11-10 diff --git a/api/cl_khr_command_buffer_multi_device.asciidoc b/api/cl_khr_command_buffer_multi_device.asciidoc index 9d3d87c34..60ea8c530 100644 --- a/api/cl_khr_command_buffer_multi_device.asciidoc +++ b/api/cl_khr_command_buffer_multi_device.asciidoc @@ -305,8 +305,6 @@ require it. *RESOLVED*: Added as an optional feature. -- -include::provisional_notice.asciidoc[] - === Version History * Revision 0.9.0, 2023-04-14 diff --git a/api/cl_khr_command_buffer_mutable_dispatch.asciidoc b/api/cl_khr_command_buffer_mutable_dispatch.asciidoc index beda74ae0..ea37650c2 100644 --- a/api/cl_khr_command_buffer_mutable_dispatch.asciidoc +++ b/api/cl_khr_command_buffer_mutable_dispatch.asciidoc @@ -367,8 +367,6 @@ specification it is omitted, and if its functionality has demand later, it may be a introduced as a stand alone extension. -- -include::provisional_notice.asciidoc[] - === Version History * Revision 0.9.0, 2022-08-31 diff --git a/api/cl_khr_external_memory.asciidoc b/api/cl_khr_external_memory.asciidoc index 0685d72c3..c9f3567ba 100644 --- a/api/cl_khr_external_memory.asciidoc +++ b/api/cl_khr_external_memory.asciidoc @@ -298,8 +298,6 @@ while (true) { *UNRESOLVED* -- -include::provisional_notice.asciidoc[] - === Version History * Revision 0.9.0, 2021-09-10 diff --git a/api/cl_khr_external_memory_dma_buf.asciidoc b/api/cl_khr_external_memory_dma_buf.asciidoc index 19d54ffa4..63c86b339 100644 --- a/api/cl_khr_external_memory_dma_buf.asciidoc +++ b/api/cl_khr_external_memory_dma_buf.asciidoc @@ -72,10 +72,6 @@ TODO * {cl_external_memory_handle_type_khr_TYPE} ** {CL_EXTERNAL_MEMORY_HANDLE_DMA_BUF_KHR} -=== Issues - -include::provisional_notice.asciidoc[] - === Version History * Revision 0.9.0, 2021-09-10 diff --git a/api/cl_khr_external_memory_dx.asciidoc b/api/cl_khr_external_memory_dx.asciidoc index c2fbf6184..5675324ec 100644 --- a/api/cl_khr_external_memory_dx.asciidoc +++ b/api/cl_khr_external_memory_dx.asciidoc @@ -75,10 +75,6 @@ TODO ** {CL_EXTERNAL_MEMORY_HANDLE_D3D12_HEAP_KHR} ** {CL_EXTERNAL_MEMORY_HANDLE_D3D12_RESOURCE_KHR} -=== Issues - -include::provisional_notice.asciidoc[] - === Version History * Revision 0.9.0, 2021-09-10 diff --git a/api/cl_khr_external_memory_opaque_fd.asciidoc b/api/cl_khr_external_memory_opaque_fd.asciidoc index 990582b40..1b1d7c44a 100644 --- a/api/cl_khr_external_memory_opaque_fd.asciidoc +++ b/api/cl_khr_external_memory_opaque_fd.asciidoc @@ -72,10 +72,6 @@ TODO * {cl_external_memory_handle_type_khr_TYPE} ** {CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_FD_KHR} -=== Issues - -include::provisional_notice.asciidoc[] - === Version History * Revision 0.9.0, 2021-09-10 diff --git a/api/cl_khr_external_memory_win32.asciidoc b/api/cl_khr_external_memory_win32.asciidoc index fdbb7e75d..8b07606bc 100644 --- a/api/cl_khr_external_memory_win32.asciidoc +++ b/api/cl_khr_external_memory_win32.asciidoc @@ -73,10 +73,6 @@ TODO ** {CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_KHR} ** {CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_KMT_KHR} -=== Issues - -include::provisional_notice.asciidoc[] - === Version History * Revision 0.9.0, 2021-09-10 diff --git a/api/cl_khr_external_semaphore.asciidoc b/api/cl_khr_external_semaphore.asciidoc index 211b42ff2..8e44962ac 100644 --- a/api/cl_khr_external_semaphore.asciidoc +++ b/api/cl_khr_external_semaphore.asciidoc @@ -274,10 +274,6 @@ while (true) { } ---- -=== Issues - -include::provisional_notice.asciidoc[] - === Version History * Revision 0.9.0, 2021-09-10 diff --git a/api/cl_khr_external_semaphore_dx_fence.asciidoc b/api/cl_khr_external_semaphore_dx_fence.asciidoc index 6f9c2ee71..1fd274587 100644 --- a/api/cl_khr_external_semaphore_dx_fence.asciidoc +++ b/api/cl_khr_external_semaphore_dx_fence.asciidoc @@ -39,10 +39,6 @@ D3D12 fence as an external semaphore using the APIs introduced by * {cl_external_semaphore_handle_type_khr_TYPE} ** {CL_SEMAPHORE_HANDLE_D3D12_FENCE_KHR} -=== Issues - -include::provisional_notice.asciidoc[] - === Version History * Revision 0.9.0, 2021-09-10 diff --git a/api/cl_khr_external_semaphore_opaque_fd.asciidoc b/api/cl_khr_external_semaphore_opaque_fd.asciidoc index d1119242f..b74a93884 100644 --- a/api/cl_khr_external_semaphore_opaque_fd.asciidoc +++ b/api/cl_khr_external_semaphore_opaque_fd.asciidoc @@ -39,10 +39,6 @@ introduced by `<>`. * {cl_external_semaphore_handle_type_khr_TYPE} ** {CL_SEMAPHORE_HANDLE_OPAQUE_FD_KHR} -=== Issues - -include::provisional_notice.asciidoc[] - === Version History * Revision 0.9.0, 2021-09-10 diff --git a/api/cl_khr_external_semaphore_sync_fd.asciidoc b/api/cl_khr_external_semaphore_sync_fd.asciidoc index a8175fe28..507588848 100644 --- a/api/cl_khr_external_semaphore_sync_fd.asciidoc +++ b/api/cl_khr_external_semaphore_sync_fd.asciidoc @@ -48,10 +48,6 @@ external semaphore using the APIs introduced by * {cl_external_semaphore_handle_type_khr_TYPE} ** {CL_SEMAPHORE_HANDLE_SYNC_FD_KHR} -=== Issues - -include::provisional_notice.asciidoc[] - === Version History * Revision 0.9.0, 2021-09-10 diff --git a/api/cl_khr_external_semaphore_win32.asciidoc b/api/cl_khr_external_semaphore_win32.asciidoc index 224302f2d..e8b1a772a 100644 --- a/api/cl_khr_external_semaphore_win32.asciidoc +++ b/api/cl_khr_external_semaphore_win32.asciidoc @@ -40,10 +40,6 @@ introduced by `<>`. ** {CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KHR} ** {CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KMT_KHR} -=== Issues - -include::provisional_notice.asciidoc[] - === Version History * Revision 0.9.0, 2021-09-10 diff --git a/api/cl_khr_semaphore.asciidoc b/api/cl_khr_semaphore.asciidoc index 25c8cdd48..4d442fec2 100644 --- a/api/cl_khr_semaphore.asciidoc +++ b/api/cl_khr_semaphore.asciidoc @@ -247,10 +247,6 @@ while (true) { } ---- -=== Issues - -include::provisional_notice.asciidoc[] - === Version History * Revision 0.9.0, 2021-09-10 From 95204bfefe935309d3ef22f7e3988c6343f076ec Mon Sep 17 00:00:00 2001 From: Jon Leech <4693344+oddhack@users.noreply.github.com> Date: Sun, 31 Mar 2024 11:13:19 -0700 Subject: [PATCH 10/71] Synchronize scripts with Vulkan and correct extension appendix section nesting (#1116) The observable effects of this are - Pushes the subsection titles in the extension appendices down one level, similar to #1087 but keeping the scripts in sync - Adds an autogenerated 'API Interactions' section with currently only affects the cl_khr_command_buffer extension, since that's the only one with some APIs tagged in the XML as dependent on a particular core version --- scripts/extensionmetadocgenerator.py | 100 ++++++++++++++++++++++++--- scripts/genRef.py | 3 +- scripts/reflib.py | 17 +++++ scripts/spec_tools/conventions.py | 23 +++++- 4 files changed, 129 insertions(+), 14 deletions(-) diff --git a/scripts/extensionmetadocgenerator.py b/scripts/extensionmetadocgenerator.py index bc38084ea..a200bab95 100644 --- a/scripts/extensionmetadocgenerator.py +++ b/scripts/extensionmetadocgenerator.py @@ -9,7 +9,7 @@ import sys from functools import total_ordering from generator import GeneratorOptions, OutputGenerator, regSortFeatures, write -from parse_dependency import dependencyMarkup +from parse_dependency import dependencyMarkup, dependencyNames class ExtensionMetaDocGeneratorOptions(GeneratorOptions): """ExtensionMetaDocGeneratorOptions - subclass of GeneratorOptions. @@ -23,6 +23,7 @@ class Extension: def __init__(self, generator, # needed for logging and API conventions filename, + interface, name, number, ext_type, @@ -36,9 +37,14 @@ def __init__(self, specialuse, ratified ): + """Object encapsulating information from an XML tag. + Most of the parameters / members are XML tag values. + 'interface' is the actual XML element.""" + self.generator = generator self.conventions = generator.genOpts.conventions self.filename = filename + self.interface = interface self.name = name self.number = number self.ext_type = ext_type @@ -176,7 +182,7 @@ def conditionalLinkExt(self, extName, indent = ' '): def resolveDeprecationChain(self, extensions, succeededBy, isRefpage, file): if succeededBy not in extensions: write(f' ** *NOTE* The extension `{succeededBy}` is not supported for the API specification being generated', file=file) - self.generator.logMsg('warn', f'resolveDeprecationChain: {self.name} defines a superceding interface {succeededBy} which is not in the supported extensions list') + self.generator.logMsg('warn', f'resolveDeprecationChain: {self.name} defines a superseding interface {succeededBy} which is not in the supported extensions list') return ext = extensions[succeededBy] @@ -223,10 +229,11 @@ def writeTag(self, tag, value, isRefpage, fp): if isRefpage: # Use subsection headers for the tag name - tagPrefix = '== ' + # Because we do not know what preceded this, add whitespace + tagPrefix = '\n== ' tagSuffix = '' else: - # Use an bolded item list for the tag name + # Use a bolded item list for the tag name tagPrefix = '*' tagSuffix = '*::' @@ -238,12 +245,14 @@ def writeTag(self, tag, value, isRefpage, fp): if isRefpage: write('', file=fp) - def makeMetafile(self, extensions, isRefpage = False): + def makeMetafile(self, extensions, SPV_deps, isRefpage = False): """Generate a file containing extension metainformation in asciidoctor markup form. - extensions - dictionary of Extension objects for extensions spec is being generated against + - SPV_deps - dictionary of SPIR-V extension names required for each + extension and version name - isRefpage - True if generating a refpage include, False if generating a specification extension appendix include""" @@ -256,7 +265,7 @@ def makeMetafile(self, extensions, isRefpage = False): if not isRefpage: write('[[' + self.name + ']]', file=fp) - write('=== ' + self.name, file=fp) + write('== ' + self.name, file=fp) write('', file=fp) self.writeTag('Name String', '`' + self.name + '`', isRefpage, fp) @@ -301,6 +310,34 @@ def makeMetafile(self, extensions, isRefpage = False): ' of provisional header files for enablement and stability details.*', file=fp) write('', file=fp) + # Determine version and extension interactions from 'depends' + # attributes of tags. + interacts = set() + for elem in self.interface.findall('require[@depends]'): + names = dependencyNames(elem.get('depends')) + interacts |= names + + if len(interacts) > 0: + self.writeTag('API Interactions', None, isRefpage, fp) + + def versionKey(name): + """Sort _VERSION_ names before extension names""" + return '_VERSION_' not in name + + names = sorted(sorted(interacts), key=versionKey) + for name in names: + write(f'* Interacts with {name}', file=fp) + + write('', file=fp) + + if self.name in SPV_deps: + self.writeTag('SPIR-V Dependencies', None, isRefpage, fp) + + for spvname in sorted(SPV_deps[self.name]): + write(f' * {self.conventions.formatSPIRVlink(spvname)}', file=fp) + + write('', file=fp) + if self.deprecationType: self.writeTag('Deprecation State', None, isRefpage, fp) @@ -362,7 +399,7 @@ def makeMetafile(self, extensions, isRefpage = False): if handle.startswith('gitlab:'): prettyHandle = 'icon:gitlab[alt=GitLab, role="red"]' + handle.replace('gitlab:@', '') elif handle.startswith('@'): - issuePlaceholderText = f'[{self.name}]{handle}' + issuePlaceholderText = f'[{self.name}] {handle}' issuePlaceholderText += f'%0A*Here describe the issue or question you have about the {self.name} extension*' trackerLink = f'link:++https://github.com/KhronosGroup/Vulkan-Docs/issues/new?body={issuePlaceholderText}++' prettyHandle = f'{trackerLink}[icon:github[alt=GitHub,role="black"]{handle[1:]},window=_blank,opts=nofollow]' @@ -408,7 +445,7 @@ def checkProposal(extname): tag = 'Extension Proposal' for (name, path) in sorted(proposals): self.writeTag(tag, - f'link:{{specRepositoryURL}}/{path}[{name}]', + f'{{proposalRefPath}}{path}[{name}]', isRefpage, fp) # Setting tag = None so additional values will not get # additional tag headers. @@ -446,6 +483,8 @@ def __init__(self, *args, **kwargs): # List of strings containing all vendor tags self.vendor_tags = [] self.file_suffix = '' + # SPIR-V dependencies, generated in beginFile() + self.SPV_deps = {} def newFile(self, filename): self.logMsg('diag', '# Generating include file:', filename) @@ -465,6 +504,28 @@ def beginFile(self, genOpts): for tag in root.findall('tags/tag'): self.vendor_tags.append(tag.get('name')) + # If there are elements in the XML, generate a + # reverse map from API version and extension names to the SPV + # extensions they depend on. + + def add_dep(SPV_deps, name, spvname): + """Add spvname as a dependency of name. + name may be an API or extension name.""" + + if name not in SPV_deps: + SPV_deps[name] = set() + SPV_deps[name].add(spvname) + + for spvext in root.findall('spirvextensions/spirvextension'): + spvname = spvext.get('name') + for elem in spvext.findall('enable'): + if elem.get('version'): + version_name = elem.get('version') + add_dep(self.SPV_deps, version_name, spvname) + elif elem.get('extension'): + ext_name = elem.get('extension') + add_dep(self.SPV_deps, ext_name, spvname) + # Create subdirectory, if needed self.makeDir(self.directory) @@ -516,9 +577,9 @@ def endFile(self): # Generate metadoc extension files, in refpage and non-refpage form for ext in self.extensions.values(): - ext.makeMetafile(self.extensions, isRefpage = False) + ext.makeMetafile(self.extensions, self.SPV_deps, isRefpage = False) if self.conventions.write_refpage_include: - ext.makeMetafile(self.extensions, isRefpage = True) + ext.makeMetafile(self.extensions, self.SPV_deps, isRefpage = True) # Key to sort extensions alphabetically within 'KHR', 'EXT', vendor # extension prefixes. @@ -565,6 +626,10 @@ def makeSortKey(extname): # This is difficult to change, and it is very unlikely changing # it will be needed. + # Do not include the lengthy '*extension_appendices_toc' indices + # in the Antora site build, since all the extensions are already + # indexed on the right navigation sidebar. + write('', file=current_extensions_appendix_fp) write('include::{generated}/meta/deprecated_extensions_guard_macro' + self.file_suffix + '[]', file=current_extensions_appendix_fp) write('', file=current_extensions_appendix_fp) @@ -577,7 +642,9 @@ def makeSortKey(extname): write('== List of Current Extensions', file=current_extensions_appendix_fp) write('endif::HAS_DEPRECATED_EXTENSIONS[]', file=current_extensions_appendix_fp) write('', file=current_extensions_appendix_fp) + write('ifndef::site-gen-antora[]', file=current_extensions_appendix_fp) write('include::{generated}/meta/current_extension_appendices_toc' + self.file_suffix + '[]', file=current_extensions_appendix_fp) + write('endif::site-gen-antora[]', file=current_extensions_appendix_fp) write('\n<<<\n', file=current_extensions_appendix_fp) write('include::{generated}/meta/current_extension_appendices' + self.file_suffix + '[]', file=current_extensions_appendix_fp) @@ -587,7 +654,9 @@ def makeSortKey(extname): write('ifdef::HAS_DEPRECATED_EXTENSIONS[]', file=deprecated_extensions_appendix_fp) write('[[deprecated-extension-appendices-list]]', file=deprecated_extensions_appendix_fp) write('== List of Deprecated Extensions', file=deprecated_extensions_appendix_fp) + write('ifndef::site-gen-antora[]', file=deprecated_extensions_appendix_fp) write('include::{generated}/meta/deprecated_extension_appendices_toc' + self.file_suffix + '[]', file=deprecated_extensions_appendix_fp) + write('endif::site-gen-antora[]', file=deprecated_extensions_appendix_fp) write('\n<<<\n', file=deprecated_extensions_appendix_fp) write('include::{generated}/meta/deprecated_extension_appendices' + self.file_suffix + '[]', file=deprecated_extensions_appendix_fp) write('endif::HAS_DEPRECATED_EXTENSIONS[]', file=deprecated_extensions_appendix_fp) @@ -604,7 +673,9 @@ def makeSortKey(extname): write('ifdef::HAS_PROVISIONAL_EXTENSIONS[]', file=provisional_extensions_appendix_fp) write('[[provisional-extension-appendices-list]]', file=provisional_extensions_appendix_fp) write('== List of Provisional Extensions', file=provisional_extensions_appendix_fp) + write('ifndef::site-gen-antora[]', file=provisional_extensions_appendix_fp) write('include::{generated}/meta/provisional_extension_appendices_toc' + self.file_suffix + '[]', file=provisional_extensions_appendix_fp) + write('endif::site-gen-antora[]', file=provisional_extensions_appendix_fp) write('\n<<<\n', file=provisional_extensions_appendix_fp) write('include::{generated}/meta/provisional_extension_appendices' + self.file_suffix + '[]', file=provisional_extensions_appendix_fp) write('endif::HAS_PROVISIONAL_EXTENSIONS[]', file=provisional_extensions_appendix_fp) @@ -614,8 +685,14 @@ def makeSortKey(extname): for name in sorted_keys: ext = self.extensions[name] - include = self.makeExtensionInclude(ext.name) + # Increase the leveloffset of the extension include so it is + # lower than the subsection (extension name) it belongs to + include = ':leveloffset: +1\n' + include += '\n' + self.makeExtensionInclude(ext.name) + '\n\n' + include += ':leveloffset: -1\n' + link = ' * ' + self.conventions.formatExtension(ext.name) + if ext.provisional == 'true': write(self.conditionalExt(ext.name, include), file=provisional_extension_appendices_fp) write(self.conditionalExt(ext.name, link), file=provisional_extension_appendices_toc_fp) @@ -675,6 +752,7 @@ def beginFeature(self, interface, emit): extdata = Extension( generator = self, filename = filename, + interface = interface, name = name, number = number, ext_type = ext_type, diff --git a/scripts/genRef.py b/scripts/genRef.py index 2b103761a..9b78fd0dc 100755 --- a/scripts/genRef.py +++ b/scripts/genRef.py @@ -223,7 +223,7 @@ def refPageShell(pageName, pageDesc, fp, head_content = None, sections=None, tai """Generate body of a reference page. - pageName - string name of the page - - pageDesc - string short description of the page, or empty string + - pageDesc - string short description of the page - fp - file to write to - head_content - text to include before the sections - sections - iterable returning (title,body) for each section. @@ -245,7 +245,6 @@ def refPageShell(pageName, pageDesc, fp, head_content = None, sections=None, tai conventions.extra_refpage_body, '', sep='\n', file=fp) - if pageDesc.strip() == '': pageDesc = 'NO SHORT DESCRIPTION PROVIDED' logWarn('refPageHead: no short description provided for', pageName) diff --git a/scripts/reflib.py b/scripts/reflib.py index 36db7590d..41fec4928 100644 --- a/scripts/reflib.py +++ b/scripts/reflib.py @@ -326,6 +326,13 @@ def fixupRefs(pageMap, specFile, file): pi.param = nextPara(file, pi.include) if pi.body is None: pi.body = nextPara(file, pi.param) + + # Vulkan Feature struct refpages may have interstitial + # text between the include block and the actual + # parameter descriptions. + # If so, advance the body one more paragraph. + if 'This structure describes the following feature' in file[pi.param]: + pi.body = nextPara(file, pi.body) else: if pi.body is None: pi.body = nextPara(file, pi.include) @@ -337,6 +344,16 @@ def fixupRefs(pageMap, specFile, file): pi.param = clampToBlock(pi.param, pi.include, pi.end) pi.body = clampToBlock(pi.body, pi.param, pi.end) + if pi.type in ['funcpointers', 'protos']: + # It is possible for the inferred parameter section to be invalid, + # such as for the type PFN_vkVoidFunction, which has no parameters. + # Since the parameter section is always a bullet-point list, we know + # the section is invalid if its text does not start with a list item. + # Note: This also deletes parameter sections that are simply empty. + if pi.param is not None and not file[pi.param].startswith(' * '): + pi.body = pi.param + pi.param = None + # We can get to this point with .include, .param, and .validity # all being None, indicating those sections were not found. diff --git a/scripts/spec_tools/conventions.py b/scripts/spec_tools/conventions.py index 5b9f6dd40..edfa906cf 100644 --- a/scripts/spec_tools/conventions.py +++ b/scripts/spec_tools/conventions.py @@ -102,6 +102,17 @@ def formatExtension(self, name): """Mark up an extension name as a link in the spec.""" return '`<<{}>>`'.format(name) + def formatSPIRVlink(self, name): + """Mark up a SPIR-V extension name as an external link in the spec. + Since these are external links, the formatting probably will be + the same for all APIs creating such links, so long as they use + the asciidoctor {spirv} attribute for the base path to the SPIR-V + extensions.""" + + (vendor, _) = self.extension_name_split(name) + + return f'{{spirv}}/{vendor}/{name}.html[{name}]' + @property @abc.abstractmethod def null(self): @@ -285,7 +296,7 @@ def extension_name_prefix(self): Typically two uppercase letters followed by an underscore. Assumed to be the same as api_prefix, but some APIs use different - case convntions.""" + case conventions.""" return self.api_prefix @@ -443,6 +454,16 @@ def generate_max_enum_in_docs(self): documentation includes.""" return False + def extension_name_split(self, name): + """Split an extension name, returning (vendor, rest of name). + The API prefix of the name is ignored.""" + + match = EXT_NAME_DECOMPOSE_RE.match(name) + vendor = match.group('vendor') + bare_name = match.group('name') + + return (vendor, bare_name) + @abc.abstractmethod def extension_file_path(self, name): """Return file path to an extension appendix relative to a directory From 1bf9208f89d4fbd2e1374872af7438dbf5b795e0 Mon Sep 17 00:00:00 2001 From: Jon Leech <4693344+oddhack@users.noreply.github.com> Date: Sun, 31 Mar 2024 11:15:22 -0700 Subject: [PATCH 11/71] Fix markup for a few extension names. (#1112) --- OpenCL_C.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/OpenCL_C.txt b/OpenCL_C.txt index eab333330..aecf83270 100644 --- a/OpenCL_C.txt +++ b/OpenCL_C.txt @@ -218,13 +218,13 @@ operations across a work-group. ifdef::cl_khr_integer_dot_product[] | {opencl_c_integer_dot_product_input_4x8bit_packed} + - (when the {cl_khr_integer_dot_product} extension macro is defined) + (when the `<>` extension macro is defined) | The OpenCL C compiler supports built-in functions that perform dot products on 4x8 bit packed integer vectors | {opencl_c_integer_dot_product_input_4x8bit} + - (when the {cl_khr_integer_dot_product} extension macro is defined) + (when the `<>` extension macro is defined) | The OpenCL C compiler supports built-in functions that perform dot products on 4x8 bit integer vectors endif::cl_khr_integer_dot_product[] @@ -354,7 +354,7 @@ ifdef::cl_khr_fp16[] ==== Half-Precision Floating-Point The `cl_khr_fp16` extension was promoted to OpenCL C 1.2 as an optional -feature, and to OpenCL 3.0 as the optional {cl_khr_fp16} feature. +feature, and to OpenCL 3.0 as the optional `<>` feature. The extension provides 16-bit precision scalar and vector floating-point data types and extends many functions to accept these types. endif::cl_khr_fp16[] @@ -365,7 +365,7 @@ ifdef::cl_khr_fp64[] ==== Double-Precision Floating-Point The `cl_khr_fp64` extension was promoted to OpenCL C 1.2 as an optional -feature, and to OpenCL 3.0 as the optional {cl_khr_fp64} feature. +feature, and to OpenCL 3.0 as the optional `<>` feature. The extension provides double-precision scalar and vector floating-point data types and extends many functions to accept these types. endif::cl_khr_fp64[] From 0da93bbad26343f6425aba35bc32e093eb141be2 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Sun, 31 Mar 2024 14:13:29 -0700 Subject: [PATCH 12/71] use the feature macro dictionary attributes in more places (#1107) --- api/appendix_h.asciidoc | 36 +++++++++++++++--------------- api/opencl_architecture.asciidoc | 2 +- api/opencl_platform_layer.asciidoc | 4 ++-- c/footnotes.asciidoc | 18 +++++++-------- ext/to_core_features.asciidoc | 2 +- 5 files changed, 31 insertions(+), 31 deletions(-) diff --git a/api/appendix_h.asciidoc b/api/appendix_h.asciidoc index 9e9ec6ea8..1bbd6f330 100644 --- a/api/appendix_h.asciidoc +++ b/api/appendix_h.asciidoc @@ -121,10 +121,10 @@ OpenCL C compilers supporting atomics orders or scopes beyond the mandated minimum will define some or all of following feature macros as appropriate: [none] -* `+__opencl_c_atomic_order_acq_rel+` -- Indicating atomic operations support acquire-release orderings. -* `+__opencl_c_atomic_order_seq_cst+` -- Indicating atomic operations and fences support acquire sequentially consistent orderings. -* `+__opencl_c_atomic_scope_device+` -- Indicating atomic operations and fences support device-wide memory ordering constraints. -* `+__opencl_c_atomic_scope_all_devices+` -- Indicating atomic operations and fences support all-device memory ordering constraints, across any host threads and all devices that can share SVM memory with each other and the host process. +* {opencl_c_atomic_order_acq_rel} -- Indicating atomic operations support acquire-release orderings. +* {opencl_c_atomic_order_seq_cst} -- Indicating atomic operations and fences support acquire sequentially consistent orderings. +* {opencl_c_atomic_scope_device} -- Indicating atomic operations and fences support device-wide memory ordering constraints. +* {opencl_c_atomic_scope_all_devices} -- Indicating atomic operations and fences support all-device memory ordering constraints, across any host threads and all devices that can share SVM memory with each other and the host process. == Device-Side Enqueue @@ -184,9 +184,9 @@ When device-side enqueue is supported but a replaceable default on-device queue |==== -OpenCL C compilers supporting device-side enqueue and on-device queues will define the feature macro `+__opencl_c_device_enqueue+`. -OpenCL C compilers that define the feature macro `+__opencl_c_device_enqueue+` must also define the feature macro `+__opencl_c_generic_address_space+` because some OpenCL C functions for device-side enqueue accept pointers to the generic address space. -OpenCL C compilers that define the feature macro `+__opencl_c_device_enqueue+` must also define the feature macro `+__opencl_c_program_scope_global_variables+` because an implementation of blocks may interact with program scope variables in global address space as part of ABI. +OpenCL C compilers supporting device-side enqueue and on-device queues will define the feature macro {opencl_c_device_enqueue}. +OpenCL C compilers that define the feature macro {opencl_c_device_enqueue} must also define the feature macro {opencl_c_generic_address_space} because some OpenCL C functions for device-side enqueue accept pointers to the generic address space. +OpenCL C compilers that define the feature macro {opencl_c_device_enqueue} must also define the feature macro {opencl_c_program_scope_global_variables} because an implementation of blocks may interact with program scope variables in global address space as part of ABI. == Pipes @@ -216,8 +216,8 @@ When pipes are not supported: |==== -OpenCL C compilers supporting pipes will define the feature macro `+__opencl_c_pipes+`. -OpenCL C compilers that define the feature macro `+__opencl_c_pipes+` must also define the feature macro `+__opencl_c_generic_address_space+` because some OpenCL C functions for pipes accept pointers to the generic address space. +OpenCL C compilers supporting pipes will define the feature macro {opencl_c_pipes}. +OpenCL C compilers that define the feature macro {opencl_c_pipes} must also define the feature macro {opencl_c_generic_address_space} because some OpenCL C functions for pipes accept pointers to the generic address space. == Program Scope Global Variables @@ -243,7 +243,7 @@ When program scope global variables are not supported: |==== -OpenCL C compilers supporting program scope global variables will define the feature macro `+__opencl_c_program_scope_global_variables+`. +OpenCL C compilers supporting program scope global variables will define the feature macro {opencl_c_program_scope_global_variables}. // TODO: There is no SPIR-V capability specific to program scope global variables. // May need to update the validation rules to disallow program scope global variables @@ -294,7 +294,7 @@ When read-write images are not supported: |==== -OpenCL C compilers supporting read-write images will define the feature macro `+__opencl_c_read_write_images+`. +OpenCL C compilers supporting read-write images will define the feature macro {opencl_c_read_write_images}. == Creating 2D Images From Buffers @@ -434,7 +434,7 @@ When sub-groups are not supported: |==== -OpenCL C compilers supporting sub-groups will define the feature macro `+__opencl_c_subgroups+`. +OpenCL C compilers supporting sub-groups will define the feature macro {opencl_c_subgroups}. == Program Initialization and Clean-Up Kernels @@ -479,7 +479,7 @@ When writing to 3D image objects is not supported: |==== -OpenCL C compilers supporting writing to 3D image objects will define the feature macro `+__opencl_c_3d_image_writes+`. +OpenCL C compilers supporting writing to 3D image objects will define the feature macro {opencl_c_3d_image_writes}. == Work-group Collective Functions @@ -497,7 +497,7 @@ When work-group collective functions are not supported: |==== -OpenCL C compilers supporting work-group collective functions will define the feature macro `+__opencl_c_work_group_collective_functions+`. +OpenCL C compilers supporting work-group collective functions will define the feature macro {opencl_c_work_group_collective_functions}. == Generic Address Space @@ -515,7 +515,7 @@ When the generic address space is not supported: |==== -OpenCL C compilers supporting the generic address space will define the feature macro `+__opencl_c_generic_address_space+`. +OpenCL C compilers supporting the generic address space will define the feature macro {opencl_c_generic_address_space}. //== Required APIs // @@ -549,6 +549,6 @@ OpenCL C compilers supporting the generic address space will define the feature Some OpenCL C language features were already optional before OpenCL 3.0, the API mechanisms for querying these have not changed. New feature macros for these optional features have been added to OpenCL C to provide a consistent mechanism for using optional features in OpenCL C 3.0. -OpenCL C compilers supporting images will define the feature macro `+__opencl_c_images+`. -OpenCL C compilers supporting the `double` type will define the feature macro `+__opencl_c_fp64+`. -OpenCL C compilers supporting the `long`, `unsigned long` and `ulong` types will define the feature macro `+__opencl_c_int64+`, note that compilers for FULL_PROFILE devices must support these types and define the macro unconditionally. +OpenCL C compilers supporting images will define the feature macro {opencl_c_images}. +OpenCL C compilers supporting the `double` type will define the feature macro {opencl_c_fp64}. +OpenCL C compilers supporting the `long`, `unsigned long` and `ulong` types will define the feature macro {opencl_c_int64}, note that compilers for FULL_PROFILE devices must support these types and define the macro unconditionally. diff --git a/api/opencl_architecture.asciidoc b/api/opencl_architecture.asciidoc index a342edbf3..4ae5b44ad 100644 --- a/api/opencl_architecture.asciidoc +++ b/api/opencl_architecture.asciidoc @@ -2168,7 +2168,7 @@ OpenCL 3.0 also adds a new version of the OpenCL C programming language, which m The new version of OpenCL C is backwards compatible with OpenCL C 1.2, but is not backwards compatible with OpenCL C 2.0. The new version of OpenCL C must be explicitly requested via the `-cl-std=` build option, otherwise a program will continue to be compiled using the highest OpenCL C 1.x language version supported for the device. + -Whenever an OpenCL C feature is optional in the new version of the OpenCL C programming language, it will be paired with a feature macro, such as `+__opencl_c_feature_name+`, and a corresponding API query. +Whenever an OpenCL C feature is optional in the new version of the OpenCL C programming language, it will be paired with a feature macro, such as {opencl_c_feature_name}, and a corresponding API query. If a feature macro is defined then the feature is supported by the OpenCL C compiler, otherwise the optional feature is not supported. In order to allow future versions of OpenCL to support new types of diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index c09ff4304..c5f591ac9 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -2068,9 +2068,9 @@ returned for {CL_DEVICE_INTEGER_DOT_PRODUCT_CAPABILITIES_KHR}: |==== | Feature Bit | Feature Macro | {CL_DEVICE_INTEGER_DOT_PRODUCT_INPUT_4x8BIT_PACKED_KHR} - | `__opencl_c_integer_dot_product_input_4x8bit_packed` + | {opencl_c_integer_dot_product_input_4x8bit_packed} | {CL_DEVICE_INTEGER_DOT_PRODUCT_INPUT_4x8BIT_KHR} - | `__opencl_c_integer_dot_product_input_4x8bit` + | {opencl_c_integer_dot_product_input_4x8bit} |==== endif::cl_khr_integer_dot_product[] diff --git a/c/footnotes.asciidoc b/c/footnotes.asciidoc index 4045e8e60..6abc922aa 100644 --- a/c/footnotes.asciidoc +++ b/c/footnotes.asciidoc @@ -22,12 +22,12 @@ The <> consume operation is not supported. \ :fn-atomic-double-supported: pass:n[ \ The `atomic_double` type is only supported if double precision is supported and the *cl_khr_int64_base_atomics* and *cl_khr_int64_extended_atomics* extensions are supported and have been enabled. \ -If this is the case then an OpenCL C 3.0 compiler must also define the `+__opencl_c_fp64+` feature. \ +If this is the case then an OpenCL C 3.0 compiler must also define the {opencl_c_fp64} feature. \ ] :fn-atomic-int64-supported: pass:n[ \ The atomic_long and atomic_ulong types are supported if the *cl_khr_int64_base_atomics* and *cl_khr_int64_extended_atomics* extensions are supported and have been enabled. \ -If this is the case then an OpenCL C 3.0 compiler must also define the `+__opencl_c_int64+` feature. \ +If this is the case then an OpenCL C 3.0 compiler must also define the {opencl_c_int64} feature. \ ] :fn-atomic-size_t-supported: pass:n[ \ @@ -77,17 +77,17 @@ Although `CL_UNORM_INT_101010_2` was added in OpenCL 2.1, because there was no O :fn-double: pass:n[ \ The `double` scalar type is an optional type that is supported if the value of the `CL_DEVICE_DOUBLE_FP_CONFIG` device query is not zero. \ -If this is the case then an OpenCL C 3.0 compiler must also define the `+__opencl_c_fp64+` feature macro. \ +If this is the case then an OpenCL C 3.0 compiler must also define the {opencl_c_fp64} feature macro. \ ] :fn-double-supported: pass:n[ \ Only if double precision is supported. \ -In OpenCL C 3.0 this will be indicated by the presence of the `+__opencl_c_fp64+` feature macro. \ +In OpenCL C 3.0 this will be indicated by the presence of the {opencl_c_fp64} feature macro. \ ] :fn-double-vec: pass:n[ \ The `double__n__` vector type is an optional type that is supported if the value of the `CL_DEVICE_DOUBLE_FP_CONFIG` device query is not zero. \ -If this is the case then an OpenCL C 3.0 compiler must also define the `+__opencl_c_fp64+` feature macro. \ +If this is the case then an OpenCL C 3.0 compiler must also define the {opencl_c_fp64} feature macro. \ ] :fn-dse-CLK_ENQUEUE_FLAGS_WAIT_WORK_GROUP: pass:n[ \ @@ -132,7 +132,7 @@ If an implementation extends this specification to support IEEE-754 flags or exc :fn-float-types-supported: pass:n[ \ The `half` scalar and vector types can only be used if the *cl_khr_fp16* extension is supported and has been enabled. \ -The `double` scalar and vector types can only be used if `double` precision is supported, e.g. for OpenCL C 3.0 the `+__opencl_c_fp64+` feature macro is present. \ +The `double` scalar and vector types can only be used if `double` precision is supported, e.g. for OpenCL C 3.0 the {opencl_c_fp64} feature macro is present. \ ] :fn-fmin-fmax-nan: pass:n[ \ @@ -155,7 +155,7 @@ Refer to the detailed description of the built-in < Date: Sun, 31 Mar 2024 14:14:49 -0700 Subject: [PATCH 13/71] add initial draft of Valid Usage and Undefined Behavior section (#1105) --- api/opencl_architecture.asciidoc | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/api/opencl_architecture.asciidoc b/api/opencl_architecture.asciidoc index 4ae5b44ad..af80cd9ea 100644 --- a/api/opencl_architecture.asciidoc +++ b/api/opencl_architecture.asciidoc @@ -2278,3 +2278,33 @@ include::{generated}/api/structs/cl_name_version.txt[] containing a null-terminated string, whose maximum length is therefore {CL_NAME_VERSION_MAX_NAME_SIZE} minus one. -- + +[[valid-usage]] +=== Valid Usage and Undefined Behavior + +The OpenCL specification describes valid usage and how to use the API correctly. +For some conditions where an API is used incorrectly, behavior is well-defined, +such as returning an error code. +For other conditions, behavior is undefined, and may include program +termination. +However, OpenCL implementations must always ensure that incorrect usage by an +application does not affect the integrity of the operating system, the OpenCL +implementation, or other OpenCL client applications in the system. +In particular, any guarantees made by an operating system about whether memory +from one process can be visible to another process or not must not be violated +by an OpenCL implementation for any memory allocation. +OpenCL implementations are not required to make additional security or integrity +guarantees beyond those provided by the operating system unless explicitly +directed by the application’s use of a particular feature or extension. + +[NOTE] +-- +For instance, if an operating system guarantees that data in all its memory +allocations are set to zero when newly allocated, the OpenCL implementation must +make the same guarantees for any allocations it controls. + +Similarly, if an operating system guarantees that use-after-free of host +allocations will not result in values written by another process becoming +visible, the same guarantees must be made by the OpenCL implementation for +memory accessible to an OpenCL device. +-- From 2349f64751f3c952d1d003763381d6c9450fe06b Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Sun, 31 Mar 2024 14:15:26 -0700 Subject: [PATCH 14/71] update generated version text for extension APIs and enums (#1108) --- scripts/gen_version_notes.py | 57 +++++++++++++++++++++--------------- 1 file changed, 33 insertions(+), 24 deletions(-) diff --git a/scripts/gen_version_notes.py b/scripts/gen_version_notes.py index b16faa42d..21271643d 100755 --- a/scripts/gen_version_notes.py +++ b/scripts/gen_version_notes.py @@ -33,29 +33,37 @@ def GetFooter(): return """ """ -def FullNote(name, added_in, deprecated_by): - # Four patterns: (1) always present in OpenCL, (2) added after 1.0, (3) in - # 1.0 but now deprecated, and (4) added after 1.0 but now deprecated. - if added_in == "1.0" and deprecated_by == None: - return "\n// Intentionally empty, %s has always been present." % name - if added_in != "1.0" and deprecated_by == None: - return "\nIMPORTANT: {%s} is {missing_before} version %s." % (name, added_in) - if added_in == "1.0" and deprecated_by != None: - return "\nIMPORTANT: {%s} is {deprecated_by} version %s." % (name, deprecated_by) - if added_in != "1.0" and deprecated_by != None: - return "\nIMPORTANT: {%s} is {missing_before} version %s and {deprecated_by} version %s." % (name, added_in, deprecated_by) - -def ShortNote(name, added_in, deprecated_by): - # Four patterns: (1) always present in OpenCL, (2) added after 1.0, (3) in - # 1.0 but now deprecated, and (4) added after 1.0 but now deprecated. - if added_in == "1.0" and deprecated_by == None: - return "// Intentionally empty, %s has always been present." % name - if added_in != "1.0" and deprecated_by == None: - return "{missing_before} version %s." % added_in - if added_in == "1.0" and deprecated_by != None: - return "{deprecated_by} version %s." % deprecated_by - if added_in != "1.0" and deprecated_by != None: - return "{missing_before} version %s and {deprecated_by} version %s." % (added_in, deprecated_by) +def FullNote(name, is_extension, added_in, deprecated_by): + if is_extension: + assert deprecated_by == None + return "\nIMPORTANT: {%s} is provided by the `%s` extension." % (name, added_in) + else: + # Four patterns: (1) always present in OpenCL, (2) added after 1.0, (3) in + # 1.0 but now deprecated, and (4) added after 1.0 but now deprecated. + if added_in == "1.0" and deprecated_by == None: + return "\n// Intentionally empty, %s has always been present." % name + if added_in != "1.0" and deprecated_by == None: + return "\nIMPORTANT: {%s} is {missing_before} version %s." % (name, added_in) + if added_in == "1.0" and deprecated_by != None: + return "\nIMPORTANT: {%s} is {deprecated_by} version %s." % (name, deprecated_by) + if added_in != "1.0" and deprecated_by != None: + return "\nIMPORTANT: {%s} is {missing_before} version %s and {deprecated_by} version %s." % (name, added_in, deprecated_by) + +def ShortNote(name, is_extension, added_in, deprecated_by): + if is_extension: + assert deprecated_by == None + return "provided by the `%s` extension." % added_in + else: + # Four patterns: (1) always present in OpenCL, (2) added after 1.0, (3) in + # 1.0 but now deprecated, and (4) added after 1.0 but now deprecated. + if added_in == "1.0" and deprecated_by == None: + return "// Intentionally empty, %s has always been present." % name + if added_in != "1.0" and deprecated_by == None: + return "{missing_before} version %s." % added_in + if added_in == "1.0" and deprecated_by != None: + return "{deprecated_by} version %s." % deprecated_by + if added_in != "1.0" and deprecated_by != None: + return "{missing_before} version %s and {deprecated_by} version %s." % (added_in, deprecated_by) # Find feature or extension groups that are parents of a or # <${entry_type}> tag, and then find all the @@ -74,6 +82,7 @@ def process_xml(spec, entry_type, note_printer): for feature in spec.findall(f'.//{feature_type}/require/{entry_type}/../..'): for entry in feature.findall(f'.//{entry_type}'): name = entry.get('name') + is_extension = feature_type != 'feature' deprecated_by = None numberOfEntries += 1 @@ -104,7 +113,7 @@ def process_xml(spec, entry_type, note_printer): versionFileName = os.path.join(args.directory, name + ".asciidoc") with open(versionFileName, 'w') as versionFile: versionFile.write(GetHeader()) - versionFile.write(note_printer(name, added_in, deprecated_by)) + versionFile.write(note_printer(name, is_extension, added_in, deprecated_by)) versionFile.write(GetFooter()) numberOfNewEntries += 0 if added_in == "1.0" else 1 From 298e8286367b045d718aff09d0672d86c18ef89e Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Sun, 31 Mar 2024 14:33:12 -0700 Subject: [PATCH 15/71] add missing anchors (#1120) * add missing anchors for external memory and semaphore commands * add missing anchors for external memory handles also a few missing anchors for various extensions * fix a few more missing anchors and incorrect attributes --- OpenCL_C.txt | 2 +- api/cl_khr_extended_versioning.asciidoc | 6 +- api/cl_khr_external_semaphore.asciidoc | 2 +- ...cl_khr_external_semaphore_sync_fd.asciidoc | 2 +- api/cl_khr_gl_event.asciidoc | 2 +- api/cl_khr_semaphore.asciidoc | 2 +- api/cl_khr_spir.asciidoc | 2 +- api/opencl_architecture.asciidoc | 2 +- api/opencl_platform_layer.asciidoc | 12 +++- api/opencl_runtime_layer.asciidoc | 69 +++++++++++++------ scripts/checklinks.py | 6 +- 11 files changed, 71 insertions(+), 36 deletions(-) diff --git a/OpenCL_C.txt b/OpenCL_C.txt index aecf83270..9dfc156b2 100644 --- a/OpenCL_C.txt +++ b/OpenCL_C.txt @@ -9735,7 +9735,7 @@ The *F* conversion specifier produces `INF`, `INFINITY`, or `NAN` instead of **e,E** A `double`, `half__n__`, `float__n__` or `double__n__` argument representing a floating-point number is converted in the style -__[__**-**__]d__**.**__ddd __**e{plusmn}}**_dd_, where there is one digit +__[__**-**__]d__**.**__ddd __**e{plusmn}**_dd_, where there is one digit (which is nonzero if the argument is nonzero) before the decimal-point character and the number of digits after it is equal to the precision; if the precision is missing, it is taken as 6; if the precision is zero and the diff --git a/api/cl_khr_extended_versioning.asciidoc b/api/cl_khr_extended_versioning.asciidoc index 4cf053be1..cf2ea54ee 100644 --- a/api/cl_khr_extended_versioning.asciidoc +++ b/api/cl_khr_extended_versioning.asciidoc @@ -47,9 +47,9 @@ Versioning>> section. === New Macro Names - * {CL_VERSION_MAJOR_BITS_KHR_anchor} - * {CL_VERSION_MINOR_BITS_KHR_anchor} - * {CL_VERSION_PATCH_BITS_KHR_anchor} + * {CL_VERSION_MAJOR_BITS_KHR} + * {CL_VERSION_MINOR_BITS_KHR} + * {CL_VERSION_PATCH_BITS_KHR} * `CL_VERSION_MAJOR_MASK_KHR` * `CL_VERSION_MINOR_MASK_KHR` * `CL_VERSION_PATCH_MASK_KHR` diff --git a/api/cl_khr_external_semaphore.asciidoc b/api/cl_khr_external_semaphore.asciidoc index 8e44962ac..0671f544a 100644 --- a/api/cl_khr_external_semaphore.asciidoc +++ b/api/cl_khr_external_semaphore.asciidoc @@ -279,7 +279,7 @@ while (true) { * Revision 0.9.0, 2021-09-10 ** Initial version (provisional). * Revision 0.9.1, 2023-11-16 - ** Added {CL_SEMAPHORE_EXPORTABLE_KHR_anchor}. + ** Added {CL_SEMAPHORE_EXPORTABLE_KHR}. * Revision 0.9.2, 2023-11-21 ** Added re-import function call to `<>` diff --git a/api/cl_khr_external_semaphore_sync_fd.asciidoc b/api/cl_khr_external_semaphore_sync_fd.asciidoc index 507588848..0368bdee3 100644 --- a/api/cl_khr_external_semaphore_sync_fd.asciidoc +++ b/api/cl_khr_external_semaphore_sync_fd.asciidoc @@ -53,6 +53,6 @@ external semaphore using the APIs introduced by * Revision 0.9.0, 2021-09-10 ** Initial version (provisional). * Revision 0.9.1, 2023-11-16 - ** Added {CL_SEMAPHORE_EXPORTABLE_KHR_anchor}. + ** Added {CL_SEMAPHORE_EXPORTABLE_KHR}. * Revision 0.9.2, 2023-11-21 ** Added re-import function call to `<>` diff --git a/api/cl_khr_gl_event.asciidoc b/api/cl_khr_gl_event.asciidoc index b7d10c5c4..2118d7e2b 100644 --- a/api/cl_khr_gl_event.asciidoc +++ b/api/cl_khr_gl_event.asciidoc @@ -96,7 +96,7 @@ runtime. . Where can events generated from GL syncs be usable? + -- -*PROPOSED*: Only with clEnqueueAcquireGLObjects, and attempting to use such +*PROPOSED*: Only with {clEnqueueAcquireGLObjects}, and attempting to use such an event elsewhere will generate an error. There is no apparent use case for using such events elsewhere, and possibly some cost to supporting it, balanced by the cost of checking the source of diff --git a/api/cl_khr_semaphore.asciidoc b/api/cl_khr_semaphore.asciidoc index 4d442fec2..ec578bc37 100644 --- a/api/cl_khr_semaphore.asciidoc +++ b/api/cl_khr_semaphore.asciidoc @@ -79,7 +79,7 @@ In particular, this extension defines: * {cl_device_info_TYPE} ** {CL_DEVICE_SEMAPHORE_TYPES_KHR} * {cl_semaphore_type_khr_TYPE} - ** {CL_SEMAPHORE_TYPE_BINARY_KHR} 1 + ** {CL_SEMAPHORE_TYPE_BINARY_KHR} * {cl_semaphore_info_khr_TYPE} ** {CL_SEMAPHORE_CONTEXT_KHR} ** {CL_SEMAPHORE_REFERENCE_COUNT_KHR} diff --git a/api/cl_khr_spir.asciidoc b/api/cl_khr_spir.asciidoc index 33ec23e43..a79966984 100644 --- a/api/cl_khr_spir.asciidoc +++ b/api/cl_khr_spir.asciidoc @@ -31,7 +31,7 @@ feature in OpenCL 2.1. * {cl_device_info_TYPE} ** {CL_DEVICE_SPIR_VERSIONS} * {cl_program_binary_type_TYPE} - ** CL_PROGRAM_BINARY_TYPE_INTERMEDIATE} + ** {CL_PROGRAM_BINARY_TYPE_INTERMEDIATE} === Version History diff --git a/api/opencl_architecture.asciidoc b/api/opencl_architecture.asciidoc index af80cd9ea..0a70e6278 100644 --- a/api/opencl_architecture.asciidoc +++ b/api/opencl_architecture.asciidoc @@ -2226,7 +2226,7 @@ working with version numbers easier. {cl_version_TYPE}. * `CL_VERSION_PATCH` extracts the _patch_ version from a packed {cl_version_TYPE}. - * `CL_MAKE_VERSION` returns a packed `cl_version_TYPE} from a + * `CL_MAKE_VERSION` returns a packed {cl_version_TYPE} from a _major_, _minor_ and _patch_ version. * {CL_VERSION_MAJOR_BITS_anchor}, {CL_VERSION_MINOR_BITS_anchor}, and {CL_VERSION_PATCH_BITS_anchor} are the number of bits in the diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index c5f591ac9..6211b1384 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -786,7 +786,7 @@ endif::cl_khr_image2d_from_buffer[] include::{generated}/api/version-notes/CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT.asciidoc[] ifdef::cl_khr_image2d_from_buffer[] -The equivalent {CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT_anchor} may be used +The equivalent {CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT_KHR_anchor} may be used if the `<>` extension is supported. endif::cl_khr_image2d_from_buffer[] | {cl_uint_TYPE} @@ -1813,6 +1813,8 @@ include::{generated}/api/version-notes/CL_DEVICE_UUID_KHR.asciidoc[] Device UUIDs must be immutable for a given device across processes, driver APIs, driver versions, and system reboots. + + {CL_UUID_SIZE_KHR_anchor} is the size of the UUID, in bytes. | {CL_DRIVER_UUID_KHR_anchor} include::{generated}/api/version-notes/CL_DRIVER_UUID_KHR.asciidoc[] @@ -1820,6 +1822,8 @@ include::{generated}/api/version-notes/CL_DRIVER_UUID_KHR.asciidoc[] | {cl_uchar_TYPE}[{CL_UUID_SIZE_KHR}] | Returns a universally unique identifier (UUID) for the software driver for the device. + + {CL_UUID_SIZE_KHR} is the size of the UUID, in bytes. | {CL_DEVICE_LUID_VALID_KHR_anchor} include::{generated}/api/version-notes/CL_DEVICE_LUID_VALID_KHR.asciidoc[] @@ -1843,6 +1847,8 @@ include::{generated}/api/version-notes/CL_DEVICE_LUID_KHR.asciidoc[] value can be cast to an `LUID` object and must be equal to the locally unique identifier of an `IDXGIAdapter1` object that corresponds to the OpenCL device. + + {CL_LUID_SIZE_KHR_anchor} is the size of the LUID, in bytes. | {CL_DEVICE_NODE_MASK_KHR_anchor} include::{generated}/api/version-notes/CL_DEVICE_NODE_MASK_KHR.asciidoc[] @@ -1936,14 +1942,14 @@ include::{generated}/api/version-notes/CL_DEVICE_INTEGER_DOT_PRODUCT_CAPABILITIE | Returns the integer dot product capabilities supported by the device. - {CL_DEVICE_INTEGER_DOT_PRODUCT_INPUT_4x8BIT_PACKED_KHR} is always + {CL_DEVICE_INTEGER_DOT_PRODUCT_INPUT_4x8BIT_PACKED_KHR_anchor} is always set, indicating that all implementations that support `<>` must support dot product built-in functions and, when SPIR-V is supported, SPIR-V instructions that take four-component vectors of 8-bit integers packed into 32-bit integers as input. - {CL_DEVICE_INTEGER_DOT_PRODUCT_INPUT_4x8BIT_KHR} is set when dot + {CL_DEVICE_INTEGER_DOT_PRODUCT_INPUT_4x8BIT_KHR_anchor} is set when dot product built-in functions and, when SPIR-V is supported, SPIR-V instructions that take four-component of 8-bit elements as input are supported. diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index b8af9a812..7e98ce853 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -5568,7 +5568,7 @@ The `<>` extension extends of handles, and adds as a property that may be specified when creating a buffer or an image memory object from an external handle: - * {CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_FD_KHR} specifies a POSIX file + * {CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_FD_KHR_anchor} specifies a POSIX file descriptor handle that has only limited valid usage outside of OpenCL and other compatible APIs. It must be compatible with the POSIX system calls `dup`, `dup2`, @@ -5585,7 +5585,7 @@ The `<>` extension extends handles, and adds as a property that may be specified when creating a buffer or an image memory object from an external handle: - * {CL_EXTERNAL_MEMORY_HANDLE_DMA_BUF_KHR} is a file descriptor for a Linux + * {CL_EXTERNAL_MEMORY_HANDLE_DMA_BUF_KHR_anchor} is a file descriptor for a Linux dma_buf. It owns a reference to the underlying memory resource represented by its memory object. @@ -5607,21 +5607,21 @@ The `<>` extension extends of handles, and adds as a property that may be specified when creating a buffer or an image memory object from an external handle: - * {CL_EXTERNAL_MEMORY_HANDLE_D3D11_TEXTURE_KHR} specifies an NT handle + * {CL_EXTERNAL_MEMORY_HANDLE_D3D11_TEXTURE_KHR_anchor} specifies an NT handle returned by `IDXGIResource1::CreateSharedHandle` referring to a Direct3D 10 or 11 texture resource. It owns a reference to the memory used by the Direct3D resource. - * {CL_EXTERNAL_MEMORY_HANDLE_D3D11_TEXTURE_KMT_KHR} specifies a global + * {CL_EXTERNAL_MEMORY_HANDLE_D3D11_TEXTURE_KMT_KHR_anchor} specifies a global share handle returned by `IDXGIResource::GetSharedHandle` referring to a Direct3D 10 or 11 texture resource. It does not own a reference to the underlying Direct3D resource, and will therefore become invalid when all memory objects and Direct3D resources associated with it are destroyed. - * {CL_EXTERNAL_MEMORY_HANDLE_D3D12_HEAP_KHR} specifies an NT handle + * {CL_EXTERNAL_MEMORY_HANDLE_D3D12_HEAP_KHR_anchor} specifies an NT handle returned by `ID3D12Device::CreateSharedHandle` referring to a Direct3D 12 heap resource. It owns a reference to the resources used by the Direct3D heap. - * {CL_EXTERNAL_MEMORY_HANDLE_D3D12_RESOURCE_KHR} specifies an NT handle + * {CL_EXTERNAL_MEMORY_HANDLE_D3D12_RESOURCE_KHR_anchor} specifies an NT handle returned by `ID3D12Device::CreateSharedHandle` referring to a Direct3D 12 committed resource. It owns a reference to the memory used by the Direct3D resource. @@ -5633,7 +5633,7 @@ The `<>` extension extends of handles, and adds as a property that may be specified when creating a buffer or an image memory object from an external handle: - * {CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_KHR} specifies an NT handle that + * {CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_KHR_anchor} specifies an NT handle that has only limited valid usage outside of OpenCL and other compatible APIs. It must be compatible with the functions `DuplicateHandle`, @@ -5641,7 +5641,7 @@ buffer or an image memory object from an external handle: `SetHandleInformation`. It owns a reference to the underlying memory resource represented by its memory object. - * {CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_KMT_KHR} specifies a global + * {CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_KMT_KHR_anchor} specifies a global share handle that has only limited valid usage outside of OpenCL and other compatible APIs. It is not compatible with any native APIs. @@ -6213,10 +6213,10 @@ include::{generated}/api/version-notes/clGetGLObjectInfo.asciidoc[] * _memobj_ is the memory object to query. * _gl_object_type_ returns the type of OpenGL object attached to _memobj_ - and can be {CL_GL_OBJECT_BUFFER}, {CL_GL_OBJECT_TEXTURE2D}, - {CL_GL_OBJECT_TEXTURE3D}, {CL_GL_OBJECT_TEXTURE2D_ARRAY}, - {CL_GL_OBJECT_TEXTURE1D}, {CL_GL_OBJECT_TEXTURE1D_ARRAY}, - {CL_GL_OBJECT_TEXTURE_BUFFER}, or {CL_GL_OBJECT_RENDERBUFFER}. + and can be {CL_GL_OBJECT_BUFFER_anchor}, {CL_GL_OBJECT_TEXTURE2D_anchor}, + {CL_GL_OBJECT_TEXTURE3D_anchor}, {CL_GL_OBJECT_TEXTURE2D_ARRAY_anchor}, + {CL_GL_OBJECT_TEXTURE1D_anchor}, {CL_GL_OBJECT_TEXTURE1D_ARRAY_anchor}, + {CL_GL_OBJECT_TEXTURE_BUFFER_anchor}, or {CL_GL_OBJECT_RENDERBUFFER_anchor}. If _gl_object_type_ is `NULL`, it is ignored * _gl_object_name_ returns the OpenGL object name used to create _memobj_. If _gl_object_name_ is `NULL`, it is ignored. @@ -10875,7 +10875,10 @@ Also see `<>`. include::{generated}/api/version-notes/CL_KERNEL_MAX_SUB_GROUP_SIZE_FOR_NDRANGE.asciidoc[] -Also see `<>`. +ifdef::cl_khr_subgroups[] +The equivalent {CL_KERNEL_MAX_SUB_GROUP_SIZE_FOR_NDRANGE_KHR_anchor} may be used if +the `<>` extension is supported. +endif::cl_khr_subgroups[] | {size_t_TYPE}* | {size_t_TYPE} | Returns the maximum sub-group size for this kernel. @@ -10892,7 +10895,10 @@ Also see `<>`. include::{generated}/api/version-notes/CL_KERNEL_SUB_GROUP_COUNT_FOR_NDRANGE.asciidoc[] -Also see `<>`. +ifdef::cl_khr_subgroups[] +The equivalent {CL_KERNEL_SUB_GROUP_COUNT_FOR_NDRANGE_KHR_anchor} may be used if +the `<>` extension is supported. +endif::cl_khr_subgroups[] | {size_t_TYPE}* | {size_t_TYPE} | Returns the number of sub-groups that will be present in each @@ -12112,6 +12118,17 @@ ifdef::cl_khr_egl_event[] include::{generated}/api/version-notes/CL_COMMAND_EGL_FENCE_SYNC_OBJECT_KHR.asciidoc[] endif::cl_khr_egl_event[] +ifdef::cl_khr_external_memory[] +| {clEnqueueAcquireExternalMemObjectsKHR} + | {CL_COMMAND_ACQUIRE_EXTERNAL_MEM_OBJECTS_KHR_anchor} + +include::{generated}/api/version-notes/CL_COMMAND_ACQUIRE_EXTERNAL_MEM_OBJECTS_KHR.asciidoc[] +| {clEnqueueReleaseExternalMemObjectsKHR} + | {CL_COMMAND_RELEASE_EXTERNAL_MEM_OBJECTS_KHR_anchor} + +include::{generated}/api/version-notes/CL_COMMAND_RELEASE_EXTERNAL_MEM_OBJECTS_KHR.asciidoc[] +endif::cl_khr_external_memory[] + ifdef::cl_khr_gl_sharing[] | {clEnqueueAcquireGLObjects} | {CL_COMMAND_ACQUIRE_GL_OBJECTS_anchor} @@ -12130,6 +12147,17 @@ ifdef::cl_khr_gl_event[] include::{generated}/api/version-notes/CL_COMMAND_GL_FENCE_SYNC_OBJECT_KHR.asciidoc[] endif::cl_khr_gl_event[] +ifdef::cl_khr_semaphore[] +| {clEnqueueSignalSemaphoresKHR} + | {CL_COMMAND_SEMAPHORE_SIGNAL_KHR_anchor} + +include::{generated}/api/version-notes/CL_COMMAND_SEMAPHORE_SIGNAL_KHR.asciidoc[] +| {clEnqueueWaitSemaphoresKHR} + | {CL_COMMAND_SEMAPHORE_WAIT_KHR_anchor} + +include::{generated}/api/version-notes/CL_COMMAND_SEMAPHORE_WAIT_KHR.asciidoc[] +endif::cl_khr_semaphore[] + |==== Using {clGetEventInfo} to determine if a command identified by _event_ has @@ -12747,14 +12775,15 @@ This section describes the semaphore types and functions defined by the * {cl_semaphore_type_khr_TYPE} represent the different types of semaphores. - ** It is mandatory to support {CL_SEMAPHORE_TYPE_BINARY_KHR}. +// TODO: This isn't a very good anchor for {CL_SEMAPHORE_TYPE_BINARY_KHR}... + ** It is mandatory to support {CL_SEMAPHORE_TYPE_BINARY_KHR_anchor}. * {cl_semaphore_properties_khr_TYPE} represents properties associated with semaphores. ** {CL_SEMAPHORE_TYPE_KHR} must be supported. * {cl_semaphore_info_khr_TYPE} represents queries for additional information about semaphores. ** All enums described in the "`New API Enums`" section of the - `<>` extension for cl_semaphore_info_khr_TYPE} must + `<>` extension for {cl_semaphore_info_khr_TYPE} must be supported. * {cl_semaphore_payload_khr_TYPE} represents payload values of semaphores. * {cl_semaphore_khr_TYPE} represent semaphore objects. @@ -12791,7 +12820,7 @@ properties by {cl_semaphore_properties_khr_TYPE} that can be passed to | {CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR_anchor} | {cl_device_id_TYPE}[] | Specifies the list of OpenCL devices (terminated with - {CL_SEMAPHORE_DEVICE_HANDLE_LIST_END_KHR}) to associate with the + {CL_SEMAPHORE_DEVICE_HANDLE_LIST_END_KHR_anchor}) to associate with the semaphore. Only a single device is permitted in the list. @@ -12801,7 +12830,7 @@ ifdef::cl_khr_external_semaphore[] include::{generated}/api/version-notes/CL_SEMAPHORE_EXPORT_HANDLE_TYPES_KHR.asciidoc[] | {cl_external_semaphore_handle_type_khr_TYPE}[] | Specifies the list of semaphore handle type properties (terminated - with {CL_SEMAPHORE_EXPORT_HANDLE_TYPES_LIST_END_KHR}) that can be + with {CL_SEMAPHORE_EXPORT_HANDLE_TYPES_LIST_END_KHR_anchor}) that can be used to export the semaphore being created. endif::cl_khr_external_semaphore[] |==== @@ -15803,7 +15832,7 @@ description here and is defined as: include::{generated}/api/structs/cl_mutable_base_config_khr.txt[] * _type_ is the type of this structure, and must be - {CL_STRUCTURE_TYPE_MUTABLE_BASE_CONFIG_KHR} + {CL_STRUCTURE_TYPE_MUTABLE_BASE_CONFIG_KHR_anchor} * _next_ is `NULL` or a pointer to an extending structure. * _num_mutable_dispatch_ is the number of mutable-dispatch objects to configure in this enqueue of the command-buffer. @@ -15823,7 +15852,7 @@ The {cl_mutable_dispatch_arg_khr_TYPE} structure is passed to include::{generated}/api/structs/cl_mutable_dispatch_config_khr.txt[] * _type_ is the type of this structure, and must be - {CL_STRUCTURE_TYPE_MUTABLE_DISPATCH_CONFIG_KHR}. + {CL_STRUCTURE_TYPE_MUTABLE_DISPATCH_CONFIG_KHR_anchor}. * _next_ is `NULL` or a pointer to an extending structure. * _command_ is a mutable-command object returned by {clCommandNDRangeKernelKHR} representing a kernel execution as part of a diff --git a/scripts/checklinks.py b/scripts/checklinks.py index 3b8ee644c..816f601a7 100755 --- a/scripts/checklinks.py +++ b/scripts/checklinks.py @@ -28,9 +28,9 @@ sourcefile.close() # We're not going to check API links. - #filelinks = re.findall(r"{((cl\w+)|(CL\w+))}", sourcetext) - filelinks = re.findall(r"{((CL\w+))}", sourcetext) - fileanchors = re.findall(r"{((cl\w+)|(CL\w+))_anchor}", sourcetext) + #filelinks = re.findall(r"{((cl\w+)|(CL_\w+))}", sourcetext) + filelinks = re.findall(r"{((CL_\w+))}", sourcetext) + fileanchors = re.findall(r"{((cl\w+)|(CL_\w+))_anchor}", sourcetext) filelinks = [re.sub(r"_anchor\b", "", link[0]) for link in filelinks] fileanchors = [anchor[0] for anchor in fileanchors] From 5d8106d6476b7bcf9ba7d59d200a17c90d2b21be Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Sun, 31 Mar 2024 15:34:35 -0700 Subject: [PATCH 16/71] cleans up extension metadata (#1122) use a consistent order for new commands, types, enums, etc. add a few missing extension types do not use the new SPIR-V capabilities section use consistent terminology --- api/cl_khr_command_buffer_multi_device.asciidoc | 8 ++++---- api/cl_khr_command_buffer_mutable_dispatch.asciidoc | 10 +++++----- api/cl_khr_d3d10_sharing.asciidoc | 12 ++++++------ api/cl_khr_d3d11_sharing.asciidoc | 7 ++++++- api/cl_khr_dx9_media_sharing.asciidoc | 7 ++++++- api/cl_khr_egl_event.asciidoc | 2 +- api/cl_khr_egl_image.asciidoc | 3 +++ api/cl_khr_external_memory.asciidoc | 4 ---- api/cl_khr_external_memory_dma_buf.asciidoc | 12 ------------ api/cl_khr_external_memory_dx.asciidoc | 12 ------------ api/cl_khr_external_memory_opaque_fd.asciidoc | 12 ------------ api/cl_khr_external_memory_win32.asciidoc | 12 ------------ api/cl_khr_fp16.asciidoc | 2 +- api/cl_khr_fp64.asciidoc | 2 +- api/cl_khr_gl_event.asciidoc | 2 +- api/cl_khr_gl_sharing.asciidoc | 2 +- api/cl_khr_icd.asciidoc | 2 +- api/cl_khr_il_program.asciidoc | 2 +- api/cl_khr_image2d_from_buffer.asciidoc | 2 +- api/cl_khr_integer_dot_product.asciidoc | 4 ---- api/cl_khr_spir.asciidoc | 2 +- api/cl_khr_subgroups.asciidoc | 8 ++++---- api/cl_khr_terminate_context.asciidoc | 8 ++++---- 23 files changed, 47 insertions(+), 90 deletions(-) diff --git a/api/cl_khr_command_buffer_multi_device.asciidoc b/api/cl_khr_command_buffer_multi_device.asciidoc index 60ea8c530..26d2d72ea 100644 --- a/api/cl_khr_command_buffer_multi_device.asciidoc +++ b/api/cl_khr_command_buffer_multi_device.asciidoc @@ -46,6 +46,10 @@ Depending on platform support the mapping of commands to the new target device can be done either explicitly by the user, or automatically by the OpenCL runtime. +=== New Commands + + * {clRemapCommandBufferKHR} + === New Types Bitfield for querying command-buffer capabilities of an OpenCL Platform with @@ -54,10 +58,6 @@ queries table>>: * {cl_platform_command_buffer_capabilities_khr_TYPE} -=== New Commands - - * {clRemapCommandBufferKHR} - === New Enums Enums for querying device command-buffer capabilities with diff --git a/api/cl_khr_command_buffer_mutable_dispatch.asciidoc b/api/cl_khr_command_buffer_mutable_dispatch.asciidoc index ea37650c2..6f35f3006 100644 --- a/api/cl_khr_command_buffer_mutable_dispatch.asciidoc +++ b/api/cl_khr_command_buffer_mutable_dispatch.asciidoc @@ -70,6 +70,11 @@ As all command recording entry-points return a {cl_mutable_command_khr_TYPE} handle, and aspects like which {cl_mem_TYPE} object a command uses could also be updated between enqueues of the command-buffer. +=== New Commands + + * {clUpdateMutableCommandsKHR} + * {clGetMutableCommandInfoKHR} + === New Types * {cl_mutable_dispatch_fields_khr_TYPE} @@ -81,11 +86,6 @@ also be updated between enqueues of the command-buffer. * {cl_mutable_dispatch_exec_info_khr_TYPE} * {cl_mutable_dispatch_arg_khr_TYPE} -=== New Commands - - * {clUpdateMutableCommandsKHR} - * {clGetMutableCommandInfoKHR} - === New Enums * {cl_device_info_TYPE} diff --git a/api/cl_khr_d3d10_sharing.asciidoc b/api/cl_khr_d3d10_sharing.asciidoc index ace32dbe9..1f8fe5242 100644 --- a/api/cl_khr_d3d10_sharing.asciidoc +++ b/api/cl_khr_d3d10_sharing.asciidoc @@ -16,11 +16,6 @@ include::{generated}/meta/{refprefix}cl_khr_d3d10_sharing.txt[] `cl_khr_d3d10_sharing` provides interoperability between OpenCL and Direct3D 10. -=== New Types - - * {cl_d3d10_device_source_khr_TYPE} - * {cl_d3d10_device_set_khr_TYPE} - === New Commands * {clGetDeviceIDsFromD3D10KHR} @@ -30,7 +25,12 @@ include::{generated}/meta/{refprefix}cl_khr_d3d10_sharing.txt[] * {clEnqueueAcquireD3D10ObjectsKHR} * {clEnqueueReleaseD3D10ObjectsKHR} -=== New Tokens +=== New Types + + * {cl_d3d10_device_source_khr_TYPE} + * {cl_d3d10_device_set_khr_TYPE} + +=== New Enums * {cl_d3d10_device_source_khr_TYPE} ** {CL_D3D10_DEVICE_KHR} diff --git a/api/cl_khr_d3d11_sharing.asciidoc b/api/cl_khr_d3d11_sharing.asciidoc index 884044eda..2ee08b859 100644 --- a/api/cl_khr_d3d11_sharing.asciidoc +++ b/api/cl_khr_d3d11_sharing.asciidoc @@ -25,7 +25,12 @@ include::{generated}/meta/{refprefix}cl_khr_d3d11_sharing.txt[] * {clEnqueueAcquireD3D11ObjectsKHR} * {clEnqueueReleaseD3D11ObjectsKHR} -=== New Tokens +=== New Types + + * {cl_d3d11_device_source_khr_TYPE} + * {cl_d3d11_device_set_khr_TYPE} + +=== New Enums * {cl_d3d11_device_source_khr_TYPE} ** {CL_D3D11_DEVICE_KHR} diff --git a/api/cl_khr_dx9_media_sharing.asciidoc b/api/cl_khr_dx9_media_sharing.asciidoc index 92e8ed517..60465c6d5 100644 --- a/api/cl_khr_dx9_media_sharing.asciidoc +++ b/api/cl_khr_dx9_media_sharing.asciidoc @@ -32,7 +32,12 @@ adapter. * {clEnqueueAcquireDX9MediaSurfacesKHR} * {clEnqueueReleaseDX9MediaSurfacesKHR} -=== New Tokens +=== New Types + + * {cl_dx9_media_adapter_type_khr_TYPE} + * {cl_dx9_media_adapter_set_khr_TYPE} + +=== New Enums * {cl_dx9_media_adapter_type_khr_TYPE} ** {CL_ADAPTER_D3D9_KHR} diff --git a/api/cl_khr_egl_event.asciidoc b/api/cl_khr_egl_event.asciidoc index f9663530f..97293a7cc 100644 --- a/api/cl_khr_egl_event.asciidoc +++ b/api/cl_khr_egl_event.asciidoc @@ -24,7 +24,7 @@ functionality of creating an EGL sync object from an OpenCL event object. * {clCreateEventFromEGLSyncKHR} -=== New Tokens +=== New Enums * New Error Codes ** {CL_INVALID_EGL_OBJECT_KHR} diff --git a/api/cl_khr_egl_image.asciidoc b/api/cl_khr_egl_image.asciidoc index d324637ad..d4e7f5fee 100644 --- a/api/cl_khr_egl_image.asciidoc +++ b/api/cl_khr_egl_image.asciidoc @@ -22,6 +22,9 @@ from from EGLImages. * {clCreateFromEGLImageKHR} * {clEnqueueAcquireEGLObjectsKHR} * {clEnqueueReleaseEGLObjectsKHR} + +=== New Enums + * {cl_event_info_TYPE} ** {CL_COMMAND_ACQUIRE_EGL_OBJECTS_KHR} ** {CL_COMMAND_RELEASE_EGL_OBJECTS_KHR} diff --git a/api/cl_khr_external_memory.asciidoc b/api/cl_khr_external_memory.asciidoc index c9f3567ba..867d9a5f2 100644 --- a/api/cl_khr_external_memory.asciidoc +++ b/api/cl_khr_external_memory.asciidoc @@ -66,10 +66,6 @@ TODO * {clEnqueueAcquireExternalMemObjectsKHR} * {clEnqueueReleaseExternalMemObjectsKHR} -=== New Structures - - * None - === New Types * {cl_external_memory_handle_type_khr_TYPE} diff --git a/api/cl_khr_external_memory_dma_buf.asciidoc b/api/cl_khr_external_memory_dma_buf.asciidoc index 63c86b339..be578969e 100644 --- a/api/cl_khr_external_memory_dma_buf.asciidoc +++ b/api/cl_khr_external_memory_dma_buf.asciidoc @@ -55,18 +55,6 @@ TODO // The 'New ...' section can be auto-generated -=== New Commands - - None - -=== New Structures - - * None - -=== New Types - - * None - === New Enums * {cl_external_memory_handle_type_khr_TYPE} diff --git a/api/cl_khr_external_memory_dx.asciidoc b/api/cl_khr_external_memory_dx.asciidoc index 5675324ec..a0be41b1b 100644 --- a/api/cl_khr_external_memory_dx.asciidoc +++ b/api/cl_khr_external_memory_dx.asciidoc @@ -55,18 +55,6 @@ TODO // The 'New ...' section can be auto-generated -=== New Commands - - None - -=== New Structures - - * None - -=== New Types - - * None - === New Enums * {cl_external_memory_handle_type_khr_TYPE} diff --git a/api/cl_khr_external_memory_opaque_fd.asciidoc b/api/cl_khr_external_memory_opaque_fd.asciidoc index 1b1d7c44a..208b2391b 100644 --- a/api/cl_khr_external_memory_opaque_fd.asciidoc +++ b/api/cl_khr_external_memory_opaque_fd.asciidoc @@ -55,18 +55,6 @@ TODO // The 'New ...' section can be auto-generated -=== New Commands - - None - -=== New Structures - - * None - -=== New Types - - * None - === New Enums * {cl_external_memory_handle_type_khr_TYPE} diff --git a/api/cl_khr_external_memory_win32.asciidoc b/api/cl_khr_external_memory_win32.asciidoc index 8b07606bc..65f3dc337 100644 --- a/api/cl_khr_external_memory_win32.asciidoc +++ b/api/cl_khr_external_memory_win32.asciidoc @@ -55,18 +55,6 @@ TODO // The 'New ...' section can be auto-generated -=== New Commands - - None - -=== New Structures - - * None - -=== New Types - - * None - === New Enums * {cl_external_memory_handle_type_khr_TYPE} diff --git a/api/cl_khr_fp16.asciidoc b/api/cl_khr_fp16.asciidoc index 7732cc29e..d2ebcd284 100644 --- a/api/cl_khr_fp16.asciidoc +++ b/api/cl_khr_fp16.asciidoc @@ -23,7 +23,7 @@ built-in types that can be used for arithmetic operations, conversions, etc. See the link:{OpenCLCSpecURL}#cl_khr_fp16[Half-Precision Floating-Point] section of the OpenCL C specification for more information. -=== New Tokens +=== New Enums * {cl_device_info_TYPE} ** {CL_DEVICE_HALF_FP_CONFIG} diff --git a/api/cl_khr_fp64.asciidoc b/api/cl_khr_fp64.asciidoc index ad1e8f763..9bb28c3a5 100644 --- a/api/cl_khr_fp64.asciidoc +++ b/api/cl_khr_fp64.asciidoc @@ -24,7 +24,7 @@ conversions, etc. See the link:{OpenCLCSpecURL}#cl_khr_fp64[Double-Precision Floating-Point] section of the OpenCL C specification for more information. -=== New Tokens +=== New Enums * {cl_device_info_TYPE} ** {CL_DEVICE_DOUBLE_FP_CONFIG} diff --git a/api/cl_khr_gl_event.asciidoc b/api/cl_khr_gl_event.asciidoc index 2118d7e2b..2ee22f486 100644 --- a/api/cl_khr_gl_event.asciidoc +++ b/api/cl_khr_gl_event.asciidoc @@ -30,7 +30,7 @@ as the OpenCL context. * {clCreateEventFromGLsyncKHR} -=== New Tokens +=== New Enums * {cl_command_type_TYPE} ** {CL_COMMAND_GL_FENCE_SYNC_OBJECT_KHR} diff --git a/api/cl_khr_gl_sharing.asciidoc b/api/cl_khr_gl_sharing.asciidoc index 7d1bcdaa8..94a1a0004 100644 --- a/api/cl_khr_gl_sharing.asciidoc +++ b/api/cl_khr_gl_sharing.asciidoc @@ -61,7 +61,7 @@ and buffer object images with OpenCL is required by this extension. * {cl_gl_texture_info_TYPE} * {cl_gl_platform_info_TYPE} -=== New Tokens +=== New Enums * New Error Codes ** {CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR} diff --git a/api/cl_khr_icd.asciidoc b/api/cl_khr_icd.asciidoc index a28baa504..fb99fb74f 100644 --- a/api/cl_khr_icd.asciidoc +++ b/api/cl_khr_icd.asciidoc @@ -236,7 +236,7 @@ continue on to the next. * {clIcdGetPlatformIDsKHR} -=== New Tokens +=== New Enums Accepted as _param_name_ to the function {clGetPlatformInfo}: diff --git a/api/cl_khr_il_program.asciidoc b/api/cl_khr_il_program.asciidoc index fc4a3d7e9..472823546 100644 --- a/api/cl_khr_il_program.asciidoc +++ b/api/cl_khr_il_program.asciidoc @@ -28,7 +28,7 @@ This functionality described by this extension is a core feature in OpenCL * {clCreateProgramWithILKHR} -=== New Tokens +=== New Enums * {cl_device_info_TYPE} ** {CL_DEVICE_IL_VERSION_KHR} diff --git a/api/cl_khr_image2d_from_buffer.asciidoc b/api/cl_khr_image2d_from_buffer.asciidoc index 17432c1ea..cb3f29eb0 100644 --- a/api/cl_khr_image2d_from_buffer.asciidoc +++ b/api/cl_khr_image2d_from_buffer.asciidoc @@ -22,7 +22,7 @@ This extension became a core feature in OpenCL 2.0. Refer to the discussion of 2D images created from buffers in the <> section for additional details. -=== New Tokens +=== New Enums * {CL_DEVICE_IMAGE_PITCH_ALIGNMENT_KHR} * {CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT_KHR} diff --git a/api/cl_khr_integer_dot_product.asciidoc b/api/cl_khr_integer_dot_product.asciidoc index ef47c2a6c..38377238d 100644 --- a/api/cl_khr_integer_dot_product.asciidoc +++ b/api/cl_khr_integer_dot_product.asciidoc @@ -52,10 +52,6 @@ Product] section of the OpenCL C specification for more information. ** {CL_DEVICE_INTEGER_DOT_PRODUCT_ACCELERATION_PROPERTIES_8BIT_KHR} ** {CL_DEVICE_INTEGER_DOT_PRODUCT_ACCELERATION_PROPERTIES_4x8BIT_PACKED_KHR} -=== New SPIR-V Capabilities - - * TBD - === Version History * Revision 1.0.0, 2021-06-17 diff --git a/api/cl_khr_spir.asciidoc b/api/cl_khr_spir.asciidoc index a79966984..6776a9cc6 100644 --- a/api/cl_khr_spir.asciidoc +++ b/api/cl_khr_spir.asciidoc @@ -26,7 +26,7 @@ information on compiling SPIR binaries. which is supported by the `<>` extension, and is a core feature in OpenCL 2.1. -=== New Tokens +=== New Enums * {cl_device_info_TYPE} ** {CL_DEVICE_SPIR_VERSIONS} diff --git a/api/cl_khr_subgroups.asciidoc b/api/cl_khr_subgroups.asciidoc index bc5e2df20..44edb39c7 100644 --- a/api/cl_khr_subgroups.asciidoc +++ b/api/cl_khr_subgroups.asciidoc @@ -33,14 +33,14 @@ However, note that: See the link:{OpenCLCSpecURL}#cl_khr_subgroups[Sub-Groups] section of the OpenCL C specification for more information. -=== New Types - - * {cl_kernel_sub_group_info_TYPE} - === New Commands * {clGetKernelSubGroupInfoKHR} +=== New Types + + * {cl_kernel_sub_group_info_TYPE} + === New Enums * {cl_kernel_sub_group_info_TYPE} diff --git a/api/cl_khr_terminate_context.asciidoc b/api/cl_khr_terminate_context.asciidoc index fac86afd8..103f5f7ea 100644 --- a/api/cl_khr_terminate_context.asciidoc +++ b/api/cl_khr_terminate_context.asciidoc @@ -35,14 +35,14 @@ closure of ongoing operations when the results are no longer required in a much more expedient manner than waiting for all previously enqueued operations to finish. -=== New Types - - * {cl_device_terminate_capability_khr_TYPE} - === New Commands * {clTerminateContextKHR} +=== New Types + + * {cl_device_terminate_capability_khr_TYPE} + === New Enums * {cl_device_info_TYPE} From 9baba39a2de48a9b1ac816a7e80b29c0eb95a70d Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Sun, 31 Mar 2024 21:44:00 -0700 Subject: [PATCH 17/71] fix section titles for sub-group extensions (#1124) also fix a few other section titles for consistency --- OpenCL_C.txt | 64 ++++++++++++++++++++++++++-------------------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/OpenCL_C.txt b/OpenCL_C.txt index 9dfc156b2..7a3b8379d 100644 --- a/OpenCL_C.txt +++ b/OpenCL_C.txt @@ -570,7 +570,7 @@ endif::cl_khr_subgroup_ballot[] ifdef::cl_khr_subgroup_clustered_reduce[] [[cl_khr_subgroup_clustered_reduce,cl_khr_subgroup_clustered_reduce]] -==== Clustered Reductions +==== Sub-Group Clustered Reductions The `cl_khr_subgroup_clustered_reduce` extension adds support for clustered reductions that operate on a subset of work items in the sub-group. @@ -600,7 +600,7 @@ endif::cl_khr_subgroup_extended_types[] ifdef::cl_khr_subgroup_non_uniform_arithmetic[] [[cl_khr_subgroup_non_uniform_arithmetic,cl_khr_subgroup_non_uniform_arithmetic]] -==== Built-in Non-Uniform Arithmetic Functions for Sub-Groups +==== Sub-Group Non-Uniform Arithmetic The `cl_khr_subgroup_non_uniform_arithmetic` extension adds the ability to use some sub-group functions within non-uniform flow control, including @@ -620,7 +620,7 @@ endif::cl_khr_subgroup_non_uniform_arithmetic[] ifdef::cl_khr_subgroup_non_uniform_vote[] [[cl_khr_subgroup_non_uniform_vote,cl_khr_subgroup_non_uniform_vote]] -==== Built-in Non-Uniform Vote and Election Functions for Sub-Groups +==== Sub-Group Non-Uniform Vote and Election Functions The `cl_khr_subgroup_non_uniform_vote` extension adds the ability to elect a single work item from a sub-group to perform a task and to hold votes among @@ -651,7 +651,7 @@ endif::cl_khr_subgroup_rotate[] ifdef::cl_khr_subgroup_shuffle[] [[cl_khr_subgroup_shuffle,cl_khr_subgroup_shuffle]] -==== General Purpose Shuffles +==== Sub-Group General Purpose Shuffles The `cl_khr_subgroup_shuffle` extension adds additional ways to exchange data among work items in a sub-group. @@ -665,7 +665,7 @@ endif::cl_khr_subgroup_shuffle[] ifdef::cl_khr_subgroup_shuffle_relative[] [[cl_khr_subgroup_shuffle_relative,cl_khr_subgroup_shuffle_relative]] -==== Relative Shuffles +==== Sub-Group Relative Shuffles The `cl_khr_subgroup_shuffle_relative` extension adds specialized ways to exchange data among work items in a sub-group that may perform better on @@ -8141,7 +8141,7 @@ This section specifies each general kind. [[atomic_store]] -===== *The atomic_store Functions* +===== The atomic_store Functions [open,refpage='atomic_store',desc='The atomic_store Functions',type='freeform',spec='clang',anchor='atomic_store',xrefs='atomicFunctions atomicTypes atomic_compare_exchange atomic_exchange atomic_fetch_key atomic_flag atomic_flag_clear atomic_flag_test_and_set atomic_flag_test_and_set_explicit atomic_init atomic_load atomic_store atomic_work_item_fence'] -- @@ -8212,7 +8212,7 @@ feature. [[atomic_load]] -===== *The atomic_load Functions* +===== The atomic_load Functions [open,refpage='atomic_load',desc='The atomic_load Functions',type='freeform',spec='clang',anchor='atomic_load',xrefs='atomicFunctions atomicTypes atomic_compare_exchange atomic_exchange atomic_fetch_key atomic_flag atomic_flag_clear atomic_flag_test_and_set atomic_flag_test_and_set_explicit atomic_init atomic_load atomic_store atomic_work_item_fence'] -- @@ -8276,7 +8276,7 @@ feature. [[atomic_exchange]] -===== *The atomic_exchange Functions* +===== The atomic_exchange Functions [open,refpage='atomic_exchange',desc='The atomic_exchange Functions',type='freeform',spec='clang',anchor='atomic_exchange',xrefs='atomicFunctions atomicTypes atomic_compare_exchange atomic_exchange atomic_fetch_key atomic_flag atomic_flag_clear atomic_flag_test_and_set atomic_flag_test_and_set_explicit atomic_init atomic_load atomic_store atomic_work_item_fence'] -- @@ -8348,7 +8348,7 @@ feature. [[atomic_compare_exchange]] -===== *The atomic_compare_exchange Functions* +===== The atomic_compare_exchange Functions [open,refpage='atomic_compare_exchange',desc='The atomic_compare_exchange Functions',type='freeform',spec='clang',anchor='atomic_compare_exchange',xrefs='atomicFunctions atomicTypes atomic_compare_exchange atomic_exchange atomic_fetch_key atomic_flag atomic_flag_clear atomic_flag_test_and_set atomic_flag_test_and_set_explicit atomic_init atomic_load atomic_store atomic_work_item_fence'] -- @@ -8669,7 +8669,7 @@ feature. [[atomic_fetch_key]] -===== *The atomic_fetch and modify Functions* +===== The atomic_fetch and modify Functions [open,refpage='atomic_fetch_key',desc='The atomic_fetch and modify Functions',type='freeform',spec='clang',anchor='atomic_fetch_key',xrefs='atomicFunctions atomicTypes atomic_compare_exchange atomic_exchange atomic_fetch_key atomic_flag atomic_flag_clear atomic_flag_test_and_set atomic_flag_test_and_set_explicit atomic_init atomic_load atomic_store atomic_work_item_fence'] -- @@ -8772,7 +8772,7 @@ feature. [[atomic_flag]] -===== *Atomic Flag Type and Operations* +===== Atomic Flag Type and Operations [open,refpage='atomic_flag',desc='Atomic Flag Type and Operations',type='freeform',spec='clang',anchor='atomic_flag',xrefs='atomicFunctions atomicTypes atomic_compare_exchange atomic_exchange atomic_fetch_key atomic_flag atomic_flag_clear atomic_flag_test_and_set atomic_flag_test_and_set_explicit atomic_init atomic_load atomic_store atomic_work_item_fence'] -- @@ -8800,7 +8800,7 @@ global atomic_flag guard = ATOMIC_FLAG_INIT; [[atomic_flag_test_and_set]] -===== *The atomic_flag_test_and_set Functions* +===== The atomic_flag_test_and_set Functions [open,refpage='atomicFlagTestAndSet',desc='The atomic_flag_test_and_set Functions',type='freeform',spec='clang',anchor='atomic_flag_test_and_set',xrefs='atomicFunctions atomicTypes atomic_compare_exchange atomic_exchange atomic_fetch_key atomic_flag atomic_flag_clear atomic_init atomic_load atomic_store atomic_work_item_fence',alias='atomic_flag_test_and_set atomic_flag_test_and_set_explicit'] -- @@ -8874,7 +8874,7 @@ feature. [[atomic_flag_clear]] -===== *The atomic_flag_clear Functions* +===== The atomic_flag_clear Functions [open,refpage='atomic_flag_clear',desc='The atomic_flag_clear Functions',type='freeform',spec='clang',anchor='atomic_flag_clear',xrefs='atomicFunctions atomicTypes atomic_compare_exchange atomic_exchange atomic_fetch_key atomic_flag atomic_flag_clear atomic_flag_test_and_set atomic_flag_test_and_set_explicit atomic_init atomic_load atomic_store atomic_work_item_fence'] -- @@ -10087,7 +10087,7 @@ queried using the `CL_DEVICE_MAX_SAMPLERS` token in *clGetDeviceInfo*. [[determining-the-border-color-or-value]] -===== *Determining the Border Color or Value* +===== Determining the Border Color or Value If `` in sampler is `CLK_ADDRESS_CLAMP`, then out-of-range image coordinates return the border color. @@ -10104,7 +10104,7 @@ of the following values: [[srgb-images]] -===== *sRGB Images* +===== sRGB Images The built-in image read functions will perform sRGB to linear RGB conversions if the image is an sRGB image. @@ -14071,7 +14071,7 @@ ifdef::cl_khr_subgroup_ballot[] NOTE: The functionality described in this section <> support for the `<>` extension. -The <> describes OpenCL C +The <> describes OpenCL C programming language built-in functions to allow work items in a sub-group to collect and operate on ballots from work items in the sub-group. These functions need not be encountered by all work items in a sub-group @@ -14266,7 +14266,7 @@ endif::cl_khr_subgroup_ballot[] ifdef::cl_khr_subgroup_clustered_reduce[] [[sub-group-clustered-reduction-functions]] -==== Built-in Clustered Reduction Functions for Sub-Groups +==== Built-in Sub-Group Clustered Reduction Functions NOTE: The functionality described in this section <> support for the `<>` extension. @@ -14298,7 +14298,7 @@ footnote:[{fn-half-supported}], and `double` footnote:[{fn-double-supported}]. [[table-clustered-reduce-math-functions]] -.Built-in Arithmetic Functions for Sub-Groups +.Built-in Sub-Group Clustered Reduction Arithmetic Functions [cols="1a,1",options="header",] |==== | Function | Description @@ -14336,7 +14336,7 @@ the supported built-in scalar data types `char`, `uchar`, `short`, `ushort`, `int`, `uint`, `long`, or `ulong`. [[table-clustered-reduce-bitwise-functions]] -.Built-in Bitwise Functions for Sub-Groups +.Built-in Sub-Group Clustered Reduction Bitwise Functions [cols="1a,1",options="header",] |==== | Function | Description @@ -14366,7 +14366,7 @@ logically `true` and a zero _predicate_ argument or return value is logically `false`. [[table-clustered-reduce-logical-functions]] -.Built-in Logical Functions for Sub-Groups +.Built-in Sub-Group Clustered Reduction Logical Functions [cols="3a,2",options="header",] |==== | Function | Description @@ -14388,7 +14388,7 @@ endif::cl_khr_subgroup_clustered_reduce[] ifdef::cl_khr_subgroup_non_uniform_arithmetic[] -==== Built-in Non-Uniform Scan and Reduction Functions for Sub-Groups +==== Built-in Sub-Group Non-Uniform Scan and Reduction Functions NOTE: The functionality described in this section <> support for the `<>` extension. @@ -14407,7 +14407,7 @@ footnote:[{fn-half-supported}], and `double` footnote:[{fn-double-supported}]. [[table-non-uniform-math-functions]] -.Built-in Non-Uniform Arithmetic Functions for Sub-Groups +.Built-in Sub-Group Non-Uniform Arithmetic Functions [cols="3a,2",options="header",] |==== | Function | Description @@ -14499,7 +14499,7 @@ supported built-in scalar data types `char`, `uchar`, `short`, `ushort`, `int`, `uint`, `long`, and `ulong`. [[table-non-uniform-bitwise-functions]] -.Built-in Non-Uniform Bitwise Functions for Sub-Groups +.Built-in Sub-Group Non-Uniform Bitwise Functions [cols="3a,2",options="header",] |==== | Function | Description @@ -14561,7 +14561,7 @@ logically `true` and a zero _predicate_ argument or return value is logically `false`. [[table-non-uniform-logical-functions]] -.Built-in Non-Uniform Logical Functions for Sub-Groups +.Built-in Sub-Group Non-Uniform Logical Functions [cols="2a,1",options="header",] |==== | Function | Description @@ -14614,7 +14614,7 @@ endif::cl_khr_subgroup_non_uniform_arithmetic[] ifdef::cl_khr_subgroup_non_uniform_vote[] -==== Built-in Non-Uniform Vote Functions for Sub-Groups +==== Built-in Sub-Group Non-Uniform Vote Functions NOTE: The functionality described in this section <> support for the `<>` extension. @@ -14632,7 +14632,7 @@ footnote:[{fn-half-supported}], and `double` footnote:[{fn-double-supported}]. [[table-non-uniform-vote-functions]] -.Built-in Non-Uniform Vote Functions for Sub-Groups +.Built-in Sub-Group Non-Uniform Vote Functions [cols="1a,1",options="header",] |==== | Function | Description @@ -14704,7 +14704,7 @@ footnote:[{fn-half-supported}], and `double` footnote:[{fn-double-supported}]. [[table-rotate-functions]] -.Built-in Rotation Functions for Sub-Groups +.Built-in Sub-Group Rotation Functions [cols="1a,1",options="header",] |==== | Function | Description @@ -14748,7 +14748,7 @@ endif::cl_khr_subgroup_rotate[] ifdef::cl_khr_subgroup_shuffle[] -==== Built-in Shuffle Functions for Sub-Groups +==== Built-in Sub-Group General Purpose Shuffle Functions NOTE: The functionality described in this section <> support for the `<>` extension. @@ -14765,7 +14765,7 @@ footnote:[{fn-half-supported}], and `double` footnote:[{fn-double-supported}]. [[table-shuffle-functions]] -.Built-in Shuffle Functions for Sub-Groups +.Built-in Sub-Group General Purpose Shuffle Functions [cols="1a,1",options="header",] |==== | Function | Description @@ -14804,7 +14804,7 @@ endif::cl_khr_subgroup_shuffle[] ifdef::cl_khr_subgroup_shuffle_relative[] -==== Add a new Section 6.15.X - Sub-Group Relative Shuffle Built-in Functions +==== Built-in Sub-Group Relative Shuffle Functions The table below describes specialized OpenCL C programming language built-in functions that allow work items in a sub-group to exchange data. @@ -14817,7 +14817,7 @@ footnote:[{fn-half-supported}], and `double` footnote:[{fn-double-supported}]. [[table-shuffle-relative-functions]] -.Built-in Relative Shuffle Functions for Sub-Groups +.Built-in Sub-Group Relative Shuffle Functions [cols="1a,1",options="header",] |==== | Function | Description @@ -14859,7 +14859,7 @@ endif::cl_khr_subgroup_shuffle_relative[] [[extended-sub-groups-mapping]] -=== Sub-Groups Function Mapping and Capabilities +==== Sub-Groups Function Mapping and Capabilities This section describes a possible mapping between OpenCL built-in sub-group functions and SPIR-V instructions and required SPIR-V capabilities. From 48128e30adc04d21d89e7277a3b7f6655bacbda9 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Sun, 31 Mar 2024 22:49:21 -0700 Subject: [PATCH 18/71] adjustments to fix long table cells (#1125) We really need a better long-term solution for this... --- OpenCL_C.txt | 925 ++++++++++++---------- api/opencl_runtime_layer.asciidoc | 28 +- config/rouge/lib/rouge/lexers/opencl.rb | 23 +- config/rouge/lib/rouge/lexers/opencl_c.rb | 1 + 4 files changed, 540 insertions(+), 437 deletions(-) diff --git a/OpenCL_C.txt b/OpenCL_C.txt index 7a3b8379d..bcab4229f 100644 --- a/OpenCL_C.txt +++ b/OpenCL_C.txt @@ -3528,18 +3528,18 @@ Examples: kernel void f() { -int *ptr; -local int *lptr; -global int *gptr; -local int val = 55; - -ptr = &val; // legal: implicit cast to generic, then assign -lptr = ptr; // illegal: no implicit cast from - // generic to local -lptr = gptr; // illegal: no implicit cast from - // global to local -ptr = gptr; // legal: implicit cast from global to generic, - // then assign + int *ptr; + local int *lptr; + global int *gptr; + local int val = 55; + + ptr = &val; // legal: implicit cast to generic, then assign + lptr = ptr; // illegal: no implicit cast from + // generic to local + lptr = gptr; // illegal: no implicit cast from + // global to local + ptr = gptr; // legal: implicit cast from global to generic, + // then assign } ---------- @@ -6225,8 +6225,8 @@ a| [source,opencl_c] ---- gentype bitfield_insert( - gentype base, gentype insert, - uint offset, uint count) + gentype base, gentype insert, + uint offset, uint count) ---- | Returns a copy of _base_, with a modified bitfield that comes from _insert_. @@ -6252,8 +6252,8 @@ a| [source,opencl_c] ---- igentype bitfield_extract_signed( - gentype base, - uint offset, uint count) + gentype base, + uint offset, uint count) ---- | Returns an extracted bitfield from _base_ with sign extension. The type of the return value is always a signed type. @@ -6277,8 +6277,8 @@ a| [source,opencl_c] ---- ugentype bitfield_extract_unsigned( - gentype base, - uint offset, uint count) + gentype base, + uint offset, uint count) ---- | Returns an extracted bitfield from _base_ with zero extension. The type of the return value is always an unsigned type. @@ -6301,7 +6301,7 @@ a| [source,opencl_c] ---- gentype bit_reverse( - gentype base) + gentype base) ---- | Returns the value of _base_ with reversed bits. That is, the bit numbered _n_ of the result value will be taken from @@ -7581,7 +7581,7 @@ ifdef::cl_khr_async_work_group_copy_fence[] |[source,opencl_c] ---- void async_work_group_copy_fence( - cl_mem_fence_flags flags) + cl_mem_fence_flags flags) ---- | Orders async copies produced by the work-items of a work-group executing a kernel. @@ -7682,28 +7682,28 @@ a| [source,opencl_c] ---- event_t async_work_group_copy_2D2D( - __local void *dst, - size_t dst_offset, - const __global void *src, - size_t src_offset, - size_t num_bytes_per_element, - size_t num_elements_per_line, - size_t num_lines, - size_t src_total_line_length, - size_t dst_total_line_length, - event_t event) + __local void *dst, + size_t dst_offset, + const __global void *src, + size_t src_offset, + size_t num_bytes_per_element, + size_t num_elements_per_line, + size_t num_lines, + size_t src_total_line_length, + size_t dst_total_line_length, + event_t event) event_t async_work_group_copy_2D2D( - __global void *dst, - size_t dst_offset, - const __local void *src, - size_t src_offset, - size_t num_bytes_per_element, - size_t num_elements_per_line, - size_t num_lines, - size_t src_total_line_length, - size_t dst_total_line_length, - event_t event) + __global void *dst, + size_t dst_offset, + const __local void *src, + size_t src_offset, + size_t num_bytes_per_element, + size_t num_elements_per_line, + size_t num_lines, + size_t src_total_line_length, + size_t dst_total_line_length, + event_t event) ---- | Perform an async copy of (_num_elements_per_line_ * _num_lines_) elements of size _num_bytes_per_element_ from (_src_ + (_src_offset_ * @@ -7730,34 +7730,34 @@ a| [source,opencl_c] ---- event_t async_work_group_copy_3D3D( - __local void *dst, - size_t dst_offset, - const __global void *src, - size_t src_offset, - size_t num_bytes_per_element, - size_t num_elements_per_line, - size_t num_lines, - size_t num_planes, - size_t src_total_line_length, - size_t src_total_plane_area, - size_t dst_total_line_length, - size_t dst_total_plane_area, - event_t event) + __local void *dst, + size_t dst_offset, + const __global void *src, + size_t src_offset, + size_t num_bytes_per_element, + size_t num_elements_per_line, + size_t num_lines, + size_t num_planes, + size_t src_total_line_length, + size_t src_total_plane_area, + size_t dst_total_line_length, + size_t dst_total_plane_area, + event_t event) event_t async_work_group_copy_3D3D( - __global void *dst, - size_t dst_offset, - const __local void *src, - size_t src_offset, - size_t num_bytes_per_element, - size_t num_elements_per_line, - size_t num_lines, - size_t num_planes, - size_t src_total_line_length, - size_t src_total_plane_area, - size_t dst_total_line_length, - size_t dst_total_plane_area, - event_t event) + __global void *dst, + size_t dst_offset, + const __local void *src, + size_t src_offset, + size_t num_bytes_per_element, + size_t num_elements_per_line, + size_t num_lines, + size_t num_planes, + size_t src_total_line_length, + size_t src_total_plane_area, + size_t dst_total_line_length, + size_t dst_total_plane_area, + event_t event) ---- | Perform an async copy of ((_num_elements_per_line_ * _num_lines_) * _num_planes_) elements of size _num_bytes_per_element_ from (_src_ + @@ -10750,28 +10750,28 @@ a| [source,opencl_c] ---- float4 read_imagef( - read_only image2d_t image, - sampler_t sampler, - float2 coord, - float lod) + read_only image2d_t image, + sampler_t sampler, + float2 coord, + float lod) int4 read_imagei( - read_only image2d_t image, - sampler_t sampler, - float2 coord, - float lod) + read_only image2d_t image, + sampler_t sampler, + float2 coord, + float lod) uint4 read_imageui( - read_only image2d_t image, - sampler_t sampler, - float2 coord, - float lod) + read_only image2d_t image, + sampler_t sampler, + float2 coord, + float lod) float read_imagef( - read_only image2d_depth_t image, - sampler_t sampler, - float2 coord, - float lod) + read_only image2d_depth_t image, + sampler_t sampler, + float2 coord, + float lod) ---- | Use the coordinate _coord.xy_ to do an element lookup in the mip level specified by _lod_ in the 2D image object specified by _image_. @@ -10782,32 +10782,32 @@ a| [source,opencl_c] ---- float4 read_imagef( - read_only image2d_t image, - sampler_t sampler, - float2 coord, - float2 gradient_x, - float2 gradient_y) + read_only image2d_t image, + sampler_t sampler, + float2 coord, + float2 gradient_x, + float2 gradient_y) int4 read_imagei( - read_only image2d_t image, - sampler_t sampler, - float2 coord, - float2 gradient_x, - float2 gradient_y) + read_only image2d_t image, + sampler_t sampler, + float2 coord, + float2 gradient_x, + float2 gradient_y) uint4 read_imageui( - read_only image2d_t image, - sampler_t sampler, - float2 coord, - float2 gradient_x, - float2 gradient_y) + read_only image2d_t image, + sampler_t sampler, + float2 coord, + float2 gradient_x, + float2 gradient_y) float read_imagef( - read_only image2d_depth_t image, - sampler_t sampler, - float2 coord, - float2 gradient_x, - float2 gradient_y) + read_only image2d_depth_t image, + sampler_t sampler, + float2 coord, + float2 gradient_x, + float2 gradient_y) ---- | Use the gradients to compute the lod and coordinate _coord.xy_ to do an element lookup in the mip level specified by the computed lod in @@ -10819,22 +10819,22 @@ a| [source,opencl_c] ---- float4 read_imagef( - read_only image1d_t image, - sampler_t sampler, - float coord, - float lod) + read_only image1d_t image, + sampler_t sampler, + float coord, + float lod) int4 read_imagei( - read_only image1d_t image, - sampler_t sampler, - float coord, - float lod) + read_only image1d_t image, + sampler_t sampler, + float coord, + float lod) uint4 read_imageui( - read_only image1d_t image, - sampler_t sampler, - float coord, - float lod) + read_only image1d_t image, + sampler_t sampler, + float coord, + float lod) ---- | Use the coordinate _coord_ to do an element lookup in the mip level specified by _lod_ in the 1D image object specified by _image_. @@ -10845,25 +10845,25 @@ a| [source,opencl_c] ---- float4 read_imagef( - read_only image1d_t image, - sampler_t sampler, - float coord, - float gradient_x, - float gradient_y) + read_only image1d_t image, + sampler_t sampler, + float coord, + float gradient_x, + float gradient_y) int4 read_imagei( - read_only image1d_t image, - sampler_t sampler, - float coord, - float gradient_x, - float gradient_y) + read_only image1d_t image, + sampler_t sampler, + float coord, + float gradient_x, + float gradient_y) uint4 read_imageui( - read_only image1d_t image, - sampler_t sampler, - float coord, - float gradient_x, - float gradient_y) + read_only image1d_t image, + sampler_t sampler, + float coord, + float gradient_x, + float gradient_y) ---- | Use the gradients to compute the lod and coordinate _coord_ to do an element lookup in the mip level specified by the computed lod in the @@ -10875,22 +10875,22 @@ a| [source,opencl_c] ---- float4 read_imagef( - read_only image3d_t image, - sampler_t sampler, - float4 coord, - float lod) + read_only image3d_t image, + sampler_t sampler, + float4 coord, + float lod) int4 read_imagei( - read_only image3d_t image, - sampler_t sampler, - float4 coord, - float lod) + read_only image3d_t image, + sampler_t sampler, + float4 coord, + float lod) uint4 read_imageui( - read_only image3d_t image, - sampler_t sampler, - float4 coord, - float lod) + read_only image3d_t image, + sampler_t sampler, + float4 coord, + float lod) ---- | Use the coordinate _coord.xyz_ to do an element lookup in the mip level specified by _lod_ in the 3D image object specified by _image_. @@ -10901,25 +10901,25 @@ a| [source,opencl_c] ---- float4 read_imagef( - read_only image3d_t image, - sampler_t sampler, - float4 coord, - float4 gradient_x, - float4 gradient_y) + read_only image3d_t image, + sampler_t sampler, + float4 coord, + float4 gradient_x, + float4 gradient_y) int4 read_imagei( - read_only image3d_t image, - sampler_t sampler, - float4 coord, - float4 gradient_x, - float4 gradient_y) + read_only image3d_t image, + sampler_t sampler, + float4 coord, + float4 gradient_x, + float4 gradient_y) uint4 read_imageui( - read_only image3d_t image, - sampler_t sampler, - float4 coord, - float4 gradient_x, - float4 gradient_y) + read_only image3d_t image, + sampler_t sampler, + float4 coord, + float4 gradient_x, + float4 gradient_y) ---- | Use the gradients to compute the lod and coordinate _coord.xyz_ to do an element lookup in the mip level specified by the computed lod in @@ -10931,22 +10931,22 @@ a| [source,opencl_c] ---- float4 read_imagef( - read_only image1d_array_t image, - sampler_t sampler, - float2 coord, - float lod) + read_only image1d_array_t image, + sampler_t sampler, + float2 coord, + float lod) int4 read_imagei( - read_only image1d_array_t image, - sampler_t sampler, - float2 coord, - float lod) + read_only image1d_array_t image, + sampler_t sampler, + float2 coord, + float lod) uint4 read_imageui( - read_only image1d_array_t image, - sampler_t sampler, - float2 coord, - float lod) + read_only image1d_array_t image, + sampler_t sampler, + float2 coord, + float lod) ---- | Use the coordinate _coord.x_ to do an element lookup in the 1D image identified by _coord.x_ and mip level specified by _lod_ in the 1D @@ -10958,25 +10958,25 @@ a| [source,opencl_c] ---- float4 read_imagef( - read_only image1d_array_t image, - sampler_t sampler, - float2 coord, - float gradient_x, - float gradient_y) + read_only image1d_array_t image, + sampler_t sampler, + float2 coord, + float gradient_x, + float gradient_y) int4 read_imagei( - read_only image1d_array_t image, - sampler_t sampler, - float2 coord, - float gradient_x, - float gradient_y) + read_only image1d_array_t image, + sampler_t sampler, + float2 coord, + float gradient_x, + float gradient_y) uint4 read_imageui( - read_only image1d_array_t image, - sampler_t sampler, - float2 coord, - float gradient_x, - float gradient_y) + read_only image1d_array_t image, + sampler_t sampler, + float2 coord, + float gradient_x, + float gradient_y) ---- | Use the gradients to compute the lod and coordinate _coord.x_ to do an element lookup in the mip level specified by the computed lod in the @@ -10988,28 +10988,28 @@ a| [source,opencl_c] ---- float4 read_imagef( - read_only image2d_array_t image, - sampler_t sampler, - float4 coord, - float lod) + read_only image2d_array_t image, + sampler_t sampler, + float4 coord, + float lod) int4 read_imagei( - read_only image2d_array_t image, - sampler_t sampler, - float4 coord, - float lod) + read_only image2d_array_t image, + sampler_t sampler, + float4 coord, + float lod) uint4 read_imageui( - read_only image2d_array_t image, - sampler_t sampler, - float4 coord, - float lod) + read_only image2d_array_t image, + sampler_t sampler, + float4 coord, + float lod) float read_imagef( - read_only image2d_array_depth_t image, - sampler_t sampler, - float4 coord, - float lod) + read_only image2d_array_depth_t image, + sampler_t sampler, + float4 coord, + float lod) ---- | Use the coordinate _coord.xy_ to do an element lookup in the 2D image identified by _coord.z_ and mip level specified by _lod_ in the 2D @@ -11021,32 +11021,32 @@ a| [source,opencl_c] ---- float4 read_imagef( - read_only image2d_array_t image, - sampler_t sampler, - float4 coord, - float2 gradient_x, - float2 gradient_y) + read_only image2d_array_t image, + sampler_t sampler, + float4 coord, + float2 gradient_x, + float2 gradient_y) int4 read_imagei( - read_only image2d_array_t image, - sampler_t sampler, - float4 coord, - float2 gradient_x, - float2 gradient_y) + read_only image2d_array_t image, + sampler_t sampler, + float4 coord, + float2 gradient_x, + float2 gradient_y) uint4 read_imageui( - read_only image2d_array_t image, - sampler_t sampler, - float4 coord, - float2 gradient_x, - float2 gradient_y) + read_only image2d_array_t image, + sampler_t sampler, + float4 coord, + float2 gradient_x, + float2 gradient_y) float read_imagef( - read_only image2d_array_depth_t image, - sampler_t sampler, - float4 coord, - float2 gradient_x, - float2 gradient_y) + read_only image2d_array_depth_t image, + sampler_t sampler, + float4 coord, + float2 gradient_x, + float2 gradient_y) ---- | Use the gradients to compute the lod coordinate and _coord.xy_ to do an element lookup in the 2D image identified by _coord.z_ and mip @@ -11520,9 +11520,9 @@ a| [source,opencl_c] ---- float4 read_imagef( - image2d_msaa_t image, - int2 coord, - int sample) + image2d_msaa_t image, + int2 coord, + int sample) ---- | Use the coordinate _(coord.x, coord.y)_ and _sample_ to do an element lookup in the 2D image object specified by _image_. @@ -11548,13 +11548,15 @@ float4 read_imagef( a| [source,opencl_c] ---- -int4 read_imagei(image2d_msaa_t image, - int2 coord, - int sample) +int4 read_imagei( + image2d_msaa_t image, + int2 coord, + int sample) -uint4 read_imageui(image2d_msaa_t image, - int2 coord, - int sample) +uint4 read_imageui( + image2d_msaa_t image, + int2 coord, + int sample) ---- | Use the coordinate _(coord.x, coord.y)_ and _sample_ to do an element lookup in the 2D image object specified by _image_. @@ -11588,9 +11590,10 @@ uint4 read_imageui(image2d_msaa_t image, a| [source,opencl_c] ---- -float4 read_imagef(image2d_array_msaa_t image, - int4 coord, - int sample) +float4 read_imagef( + image2d_array_msaa_t image, + int4 coord, + int sample) ---- | Use _coord.xy_ and _sample_ to do an element lookup in the 2D image identified by _coord.z_ in the 2D image array specified by _image_. @@ -11616,13 +11619,15 @@ float4 read_imagef(image2d_array_msaa_t image, a| [source,opencl_c] ---- -int4 read_imagei(image2d_array_msaa_t image, - int4 coord, - int sample) +int4 read_imagei( + image2d_array_msaa_t image, + int4 coord, + int sample) -uint4 read_imageui(image2d_array_msaa_t image, - int4 coord, - int sample) +uint4 read_imageui( + image2d_array_msaa_t image, + int4 coord, + int sample) ---- | Use _coord.xy_ and _sample_ to do an element lookup in the 2D image identified by _coord.z_ in the 2D image array specified by _image_. @@ -11656,9 +11661,10 @@ uint4 read_imageui(image2d_array_msaa_t image, a| [source,opencl_c] ---- -float read_imagef(image2d_msaa_depth_t image, - int2 coord, - int sample) +float read_imagef( + image2d_msaa_depth_t image, + int2 coord, + int sample) ---- | Use the coordinate _(coord.x, coord.y)_ and _sample_ to do an element lookup in the 2D depth image object specified by _image_. @@ -11751,15 +11757,27 @@ endif::cl_khr_srgb_image_writes[] [[table-image-write]] .Built-in Image Write Functions -[cols=",",options="header",] +[cols="3,4",options="header",] |==== | Function | Description -| void *write_imagef*(_aQual_ image2d_t _image_, int2 _coord_, float4 _color_) + +| void *write_imagef*( + + _aQual_ image2d_t _image_, + + int2 _coord_, + + float4 _color_) + ifdef::cl_khr_fp16[] - void *write_imageh*(_aQual_ image2d_t _image_, int2 _coord_, half4 _color_) + + void *write_imageh*( + + _aQual_ image2d_t _image_, + + int2 _coord_, + + half4 _color_) + endif::cl_khr_fp16[] - void *write_imagei*(_aQual_ image2d_t _image_, int2 _coord_, int4 _color_) + - void *write_imageui*(_aQual_ image2d_t _image_, int2 _coord_, uint4 _color_) + void *write_imagei*( + + _aQual_ image2d_t _image_, + + int2 _coord_, + + int4 _color_) + + void *write_imageui*( + + _aQual_ image2d_t _image_, + + int2 _coord_, + + uint4 _color_) | Write _color_ value to location specified by _coord.xy_ in the 2D image object specified by _image_. Appropriate data format conversion to the specified image format is @@ -11805,15 +11823,23 @@ ifdef::cl_khr_fp16[] `<>` extension macro. endif::cl_khr_fp16[] | | -| void *write_imagef*(_aQual_ image2d_array_t _image_, int4 _coord_, +| void *write_imagef*( + + _aQual_ image2d_array_t _image_, + + int4 _coord_, + float4 _color_) + ifdef::cl_khr_fp16[] - void *write_imageh*(_aQual_ image2d_array_t _image_, int4 _coord_, + void *write_imageh*( + + _aQual_ image2d_array_t _image_, + + int4 _coord_, + half4 _color_) + endif::cl_khr_fp16[] - void *write_imagei*(_aQual_ image2d_array_t _image_, int4 _coord_, + void *write_imagei*( + + _aQual_ image2d_array_t _image_, + + int4 _coord_, + int4 _color_) + - void *write_imageui*(_aQual_ image2d_array_t _image_, int4 _coord_, + void *write_imageui*( + + _aQual_ image2d_array_t _image_, + + int4 _coord_, + uint4 _color_) | Write _color_ value to location specified by _coord.xy_ in the 2D image identified by _coord.z_ in the 2D image array specified by @@ -11862,25 +11888,41 @@ ifdef::cl_khr_fp16[] `<>` extension macro. endif::cl_khr_fp16[] | | -| void *write_imagef*(_aQual_ image1d_t _image_, int _coord_, +| void *write_imagef*( + + _aQual_ image1d_t _image_, + + int _coord_, + float4 _color_) + ifdef::cl_khr_fp16[] - void *write_imageh*(_aQual_ image1d_t _image_, int _coord_, + void *write_imageh*( + + _aQual_ image1d_t _image_, + + int _coord_, + half4 _color_) + endif::cl_khr_fp16[] - void *write_imagei*(_aQual_ image1d_t _image_, int _coord_, + void *write_imagei*( + + _aQual_ image1d_t _image_, + + int _coord_, + int4 _color_) + - void *write_imageui*(_aQual_ image1d_t _image_, int _coord_, + void *write_imageui*( + + _aQual_ image1d_t _image_, + + int _coord_, + uint4 _color_) + - void *write_imagef*(_aQual_ image1d_buffer_t _image_, int _coord_, + void *write_imagef*( + + _aQual_ image1d_buffer_t _image_, + + int _coord_, + float4 _color_) + ifdef::cl_khr_fp16[] - void *write_imageh*(_aQual_ image1d_buffer_t _image_, int _coord_, + void *write_imageh*( + + _aQual_ image1d_buffer_t _image_, + + int _coord_, + half4 _color_) + endif::cl_khr_fp16[] - void *write_imagei*(_aQual_ image1d_buffer_t _image_, int _coord_, + void *write_imagei*( + + _aQual_ image1d_buffer_t _image_, + + int _coord_, + int4 _color_) + - void *write_imageui*(_aQual_ image1d_buffer_t _image_, int _coord_, + void *write_imageui*( + + _aQual_ image1d_buffer_t _image_, + + int _coord_, + uint4 _color_) | Write _color_ value to location specified by _coord_ in the 1D image or 1D image buffer object specified by _image_. @@ -11927,15 +11969,23 @@ ifdef::cl_khr_fp16[] `<>` extension macro. endif::cl_khr_fp16[] | | -| void *write_imagef*(_aQual_ image1d_array_t _image_, int2 _coord_, +| void *write_imagef*( + + _aQual_ image1d_array_t _image_, + + int2 _coord_, + float4 _color_) + ifdef::cl_khr_fp16[] - void *write_imageh*(_aQual_ image1d_array_t _image_, int2 _coord_, + void *write_imageh*( + + _aQual_ image1d_array_t _image_, + + int2 _coord_, + half4 _color_) + endif::cl_khr_fp16[] - void *write_imagei*(_aQual_ image1d_array_t _image_, int2 _coord_, + void *write_imagei*( + + _aQual_ image1d_array_t _image_, + + int2 _coord_, + int4 _color_) + - void *write_imageui*(_aQual_ image1d_array_t _image_, int2 _coord_, + void *write_imageui*( + + _aQual_ image1d_array_t _image_, + + int2 _coord_, uint4 _color_) | Write _color_ value to location specified by _coord.x_ in the 1D image identified by _coord.y_ in the 1D image array specified by _image_. @@ -11979,7 +12029,9 @@ ifdef::cl_khr_fp16[*write_imageh*,] <> support for OpenCL C 1.2 or newer. | | -| void *write_imagef*(_aQual_ image2d_depth_t _image_, int2 _coord_, +| void *write_imagef*( + + _aQual_ image2d_depth_t _image_, + + int2 _coord_, + float _depth_) | Write _depth_ value to location specified by _coord.xy_ in the 2D depth image object specified by _image_. @@ -12005,7 +12057,9 @@ ifdef::cl_khr_fp16[*write_imageh*,] <> support for OpenCL C 2.0 or newer, or for the `<>` extension macro. | | -| void *write_imagef*(_aQual_ image2d_array_depth_t _image_, int4 _coord_, +| void *write_imagef*( + + _aQual_ image2d_array_depth_t _image_, + + int4 _coord_, + float _depth_) | Write _depth_ value to location specified by _coord.xy_ in the 2D image identified by _coord.z_ in the 2D depth image array specified by @@ -12032,15 +12086,23 @@ ifdef::cl_khr_fp16[*write_imageh*,] <> support for OpenCL C 2.0 or newer, or for the `<>` extension macro. | | -| void *write_imagef*(_aQual_ image3d_t _image_, int4 _coord_, +| void *write_imagef*( + + _aQual_ image3d_t _image_, + + int4 _coord_, + float4 _color_) + ifdef::cl_khr_fp16[] - void *write_imageh*(_aQual_ image3d_t _image_, int4 _coord_, + void *write_imageh*( + + _aQual_ image3d_t _image_, + + int4 _coord_, + half4 _color_) + endif::cl_khr_fp16[] - void *write_imagei*(_aQual_ image3d_t _image_, int4 _coord_, + void *write_imagei*( + + _aQual_ image3d_t _image_, + + int4 _coord_, + int4 _color_) + - void *write_imageui*(_aQual_ image3d_t _image_, int4 _coord_, + void *write_imageui*( + + _aQual_ image3d_t _image_, + + int4 _coord_, + uint4 _color_) | Write _color_ value to the location specified by _coord.xyz_ in the 3D image object specified by _image_. @@ -12096,28 +12158,28 @@ a| [source,opencl_c] ---- void write_imagef( - write_only image2d_t image, - int2 coord, - int lod, - float4 color) + write_only image2d_t image, + int2 coord, + int lod, + float4 color) void write_imagei( - write_only image2d_t image, - int2 coord, - int lod, - int4 color) + write_only image2d_t image, + int2 coord, + int lod, + int4 color) void write_imageui( - write_only image2d_t image, - int2 coord, - int lod, - uint4 color) + write_only image2d_t image, + int2 coord, + int lod, + uint4 color) void write_imagef( - write_only image2d_depth_t image, - int2 coord, - int lod, - float depth) + write_only image2d_depth_t image, + int2 coord, + int lod, + float depth) ---- | Write _color_ value to location specified by _coord.xy_ in the mip level specified by _lod_ in the 2D image object specified by _image_. @@ -12137,22 +12199,22 @@ a| [source,opencl_c] ---- void write_imagef( - write_only image1d_t image, - int coord, - int lod, - float4 color) + write_only image1d_t image, + int coord, + int lod, + float4 color) void write_imagei( - write_only image1d_t image, - int coord, - int lod, - int4 color) + write_only image1d_t image, + int coord, + int lod, + int4 color) void write_imageui( - write_only image1d_t image, - int coord, - int lod, - uint4 color) + write_only image1d_t image, + int coord, + int lod, + uint4 color) ---- | Write _color_ value to location specified by _coord_ in the mip level specified by _lod_ in the 1D image object specified by _image_. @@ -12170,22 +12232,22 @@ a| [source,opencl_c] ---- void write_imagef( - write_only image1d_array_t image, - int2 coord, - int lod, - float4 color) + write_only image1d_array_t image, + int2 coord, + int lod, + float4 color) void write_imagei( - write_only image1d_array_t image, - int2 coord, - int lod, - int4 color) + write_only image1d_array_t image, + int2 coord, + int lod, + int4 color) void write_imageui( - write_only image1d_array_t image, - int2 coord, - int lod, - uint4 color) + write_only image1d_array_t image, + int2 coord, + int lod, + uint4 color) ---- | Write _color_ value to location specified by _coord.x_ in the 1D image identified by _coord.y_ and mip level _lod_ in the 1D image array @@ -12205,28 +12267,28 @@ a| [source,opencl_c] ---- void write_imagef( - write_only image2d_array_t image, - int4 coord, - int lod, - float4 color) + write_only image2d_array_t image, + int4 coord, + int lod, + float4 color) void write_imagei( - write_only image2d_array_t image, - int4 coord, - int lod, - int4 color) + write_only image2d_array_t image, + int4 coord, + int lod, + int4 color) void write_imageui( - write_only image2d_array_t image, - int4 coord, - int lod, - uint4 color) + write_only image2d_array_t image, + int4 coord, + int lod, + uint4 color) void write_imagef( - write_only image2d_array_depth_t image, - int4 coord, - int lod, - float depth) + write_only image2d_array_depth_t image, + int4 coord, + int lod, + float depth) ---- | Write _color_ value to location specified by _coord.xy_ in the 2D image identified by _coord.z_ and mip level _lod_ in the 2D image array @@ -12247,22 +12309,22 @@ a| [source,opencl_c] ---- void write_imagef( - write_only image3d_t image, - int4 coord, - int lod, - float4 color) + write_only image3d_t image, + int4 coord, + int lod, + float4 color) void write_imagei( - write_only image3d_t image, - int4 coord, - int lod, - int4 color) + write_only image3d_t image, + int4 coord, + int lod, + int4 color) void write_imageui( - write_only image3d_t image, - int4 coord, - int lod, - uint4 color) + write_only image3d_t image, + int4 coord, + int lod, + uint4 color) ---- | Write _color_ value to location specified by _coord.xyz_ and mip level _lod_ in the 3D image object specified by _image_. @@ -12765,22 +12827,28 @@ logically `false`. [[table-builtin-work-group-logical]] .Built-in Work-group Logical Arithmetic Functions -[cols="2a,1",options="header"] +[cols="4a,3",options="header"] |==== | Function | Description |[source,opencl_c] ---- -int work_group_reduce_logical_and(int predicate); -int work_group_reduce_logical_or(int predicate); -int work_group_reduce_logical_xor(int predicate); +int work_group_reduce_logical_and( + int predicate); +int work_group_reduce_logical_or( + int predicate); +int work_group_reduce_logical_xor( + int predicate); ---- | Returns the logical *and*, *or*, or *xor* of _predicate_ for all work items in the work-group. |[source,opencl_c] ---- -int work_group_scan_inclusive_logical_and(int predicate); -int work_group_scan_inclusive_logical_or(int predicate); -int work_group_scan_inclusive_logical_xor(int predicate); +int work_group_scan_inclusive_logical_and( + int predicate); +int work_group_scan_inclusive_logical_or( + int predicate); +int work_group_scan_inclusive_logical_xor( + int predicate); ---- | Returns the result of an inclusive scan operation, which is the logical *and*, *or*, or *xor* of _predicate_ for all work items in the @@ -12788,9 +12856,12 @@ int work_group_scan_inclusive_logical_xor(int predicate); work item's work-group linear local ID. |[source,opencl_c] ---- -int work_group_scan_exclusive_logical_and(int predicate); -int work_group_scan_exclusive_logical_or(int predicate); -int work_group_scan_exclusive_logical_xor(int predicate); +int work_group_scan_exclusive_logical_and( + int predicate); +int work_group_scan_exclusive_logical_or( + int predicate); +int work_group_scan_exclusive_logical_xor( + int predicate); ---- | Returns the result of an exclusive scan operation, which is the logical *and*, *or*, or *xor* of _predicate_ for all work items in the @@ -12814,22 +12885,28 @@ supported built-in scalar data types `int`, `uint`, `long`, and `ulong`. [[table-builtin-work-group-bitwise-integer]] .Built-in Work-group Bitwise Integer Functions -[cols="2a,1",options="header"] +[cols="1a,1",options="header"] |==== | Function | Description |[source,opencl_c] ---- -gentype work_group_reduce_and(gentype value); -gentype work_group_reduce_or(gentype value); -gentype work_group_reduce_xor(gentype value); +gentype work_group_reduce_and( + gentype value); +gentype work_group_reduce_or( + gentype value); +gentype work_group_reduce_xor( + gentype value); ---- | Returns the bitwise *and*, *or*, or *xor* of _value_ for all work items in the work-group. |[source,opencl_c] ---- -gentype work_group_scan_inclusive_and(gentype value); -gentype work_group_scan_inclusive_or(gentype value); -gentype work_group_scan_inclusive_xor(gentype value); +gentype work_group_scan_inclusive_and( + gentype value); +gentype work_group_scan_inclusive_or( + gentype value); +gentype work_group_scan_inclusive_xor( + gentype value); ---- | Returns the result of an inclusive scan operation, which is the bitwise *and*, *or*, or *xor* of _value_ for all work items in the work-group @@ -12837,9 +12914,12 @@ gentype work_group_scan_inclusive_xor(gentype value); work-group linear local ID. |[source,opencl_c] ---- -gentype work_group_scan_exclusive_and(gentype value); -gentype work_group_scan_exclusive_or(gentype value); -gentype work_group_scan_exclusive_xor(gentype value); +gentype work_group_scan_exclusive_and( + gentype value); +gentype work_group_scan_exclusive_or( + gentype value); +gentype work_group_scan_exclusive_xor( + gentype value); ---- | Returns the result of an exclusive scan operation, which is the bitwise *and*, *or*, or *xor* of _value_ for all work items in the work-group @@ -12865,18 +12945,20 @@ precision is supported). [[table-builtin-work-group-multiplicative]] .Built-in Work-group Multiplicative Functions -[cols="2a,1",options="header"] +[cols="1a,1",options="header"] |==== | Function | Description |[source,opencl_c] ---- -gentype work_group_reduce_mul(gentype value); +gentype work_group_reduce_mul( + gentype value); ---- | Returns the multiplication of _value_ for all work items in the work-group. |[source,opencl_c] ---- -gentype work_group_scan_inclusive_mul(gentype value); +gentype work_group_scan_inclusive_mul( + gentype value); ---- | Returns the result of an inclusive scan operation which is the multiplication of _value_ for all work items in the work-group with a @@ -12884,7 +12966,8 @@ gentype work_group_scan_inclusive_mul(gentype value); work-group linear local ID. |[source,opencl_c] ---- -gentype work_group_scan_exclusive_mul(gentype value); +gentype work_group_scan_exclusive_mul( + gentype value); ---- | Returns the result of an exclusive scan operation which is the multiplication of _value_ for all work items in the work-group with a @@ -14098,8 +14181,8 @@ footnote:[{fn-double-supported}]. |[source,opencl_c] ---- gentype sub_group_non_uniform_broadcast( - gentype value, - uint index ) + gentype value, + uint index ) ---- | Returns _value_ for the work item with sub-group local ID equal to _index_. @@ -14113,14 +14196,14 @@ gentype sub_group_non_uniform_broadcast( |[source,opencl_c] ---- gentype sub_group_broadcast_first( - gentype value ) + gentype value ) ---- | Returns _value_ for the work item with the smallest sub-group local ID among active work items in the sub-group. |[source,opencl_c] ---- uint4 sub_group_ballot( - int predicate ) + int predicate ) ---- | Returns a bitfield combining the _predicate_ values from all work items in the sub-group. @@ -14132,7 +14215,7 @@ uint4 sub_group_ballot( |[source,opencl_c] ---- int sub_group_inverse_ballot( - uint4 value ) + uint4 value ) ---- | Returns the predicate value for this work item in the sub-group from the bitfield _value_ representing predicate values from all work items in @@ -14148,8 +14231,8 @@ int sub_group_inverse_ballot( |[source,opencl_c] ---- int sub_group_ballot_bit_extract( - uint4 value, - uint index ) + uint4 value, + uint index ) ---- | Returns the predicate value for the work item with sub-group local ID equal to _index_ from the bitfield _value_ representing predicate values @@ -14164,7 +14247,7 @@ int sub_group_ballot_bit_extract( |[source,opencl_c] ---- uint sub_group_ballot_bit_count( - uint4 value ) + uint4 value ) ---- | Returns the number of bits that are set in the bitfield _value_, only considering the bits in _value_ that represent predicate values @@ -14173,7 +14256,7 @@ uint sub_group_ballot_bit_count( |[source,opencl_c] ---- uint sub_group_ballot_inclusive_scan( - uint4 value ) + uint4 value ) ---- | Returns the number of bits that are set in the bitfield _value_, only considering the bits in _value_ representing work items with a sub-group @@ -14181,7 +14264,7 @@ uint sub_group_ballot_inclusive_scan( |[source,opencl_c] ---- uint sub_group_ballot_exclusive_scan( - uint4 value ) + uint4 value ) ---- | Returns the number of bits that are set in the bitfield _value_, only considering the bits in _value_ representing work items with a sub-group @@ -14189,7 +14272,7 @@ uint sub_group_ballot_exclusive_scan( |[source,opencl_c] ---- uint sub_group_ballot_find_lsb( - uint4 value ) + uint4 value ) ---- | Returns the smallest sub-group local ID with a bit set in the bitfield _value_, only considering the bits in _value_ that represent predicate @@ -14202,7 +14285,7 @@ uint sub_group_ballot_find_lsb( |[source,opencl_c] ---- uint sub_group_ballot_find_msb( - uint4 value ) + uint4 value ) ---- | Returns the largest sub-group local ID with a bit set in the bitfield _value_, only considering the bits in _value_ that represent predicate @@ -14305,13 +14388,13 @@ footnote:[{fn-double-supported}]. |[source,opencl_c] ---- gentype sub_group_clustered_reduce_add( - gentype value, uint clustersize ) + gentype value, uint clustersize ) gentype sub_group_clustered_reduce_mul( - gentype value, uint clustersize ) + gentype value, uint clustersize ) gentype sub_group_clustered_reduce_min( - gentype value, uint clustersize ) + gentype value, uint clustersize ) gentype sub_group_clustered_reduce_max( - gentype value, uint clustersize ) + gentype value, uint clustersize ) ---- | Returns the summation, multiplication, minimum, or maximum of _value_ for all active work items in the sub-group within a cluster of the @@ -14343,11 +14426,11 @@ the supported built-in scalar data types `char`, `uchar`, `short`, `ushort`, |[source,opencl_c] ---- gentype sub_group_clustered_reduce_and( - gentype value, uint clustersize ) + gentype value, uint clustersize ) gentype sub_group_clustered_reduce_or( - gentype value, uint clustersize ) + gentype value, uint clustersize ) gentype sub_group_clustered_reduce_xor( - gentype value, uint clustersize ) + gentype value, uint clustersize ) ---- | Returns the bitwise *and*, *or*, or *xor* of _value_ for all active work items in the sub-group within a cluster of the specified _clustersize_. @@ -14373,11 +14456,11 @@ logically `false`. |[source,opencl_c] ---- int sub_group_clustered_reduce_logical_and( - int predicate, uint clustersize ) + int predicate, uint clustersize ) int sub_group_clustered_reduce_logical_or( - int predicate, uint clustersize ) + int predicate, uint clustersize ) int sub_group_clustered_reduce_logical_xor( - int predicate, uint clustersize ) + int predicate, uint clustersize ) ---- | Returns the logical *and*, *or*, or *xor* of _predicate_ for all active work items in the sub-group within a cluster of the specified @@ -14414,13 +14497,13 @@ footnote:[{fn-double-supported}]. |[source,opencl_c] ---- gentype sub_group_non_uniform_reduce_add( - gentype value ) + gentype value ) gentype sub_group_non_uniform_reduce_min( - gentype value ) + gentype value ) gentype sub_group_non_uniform_reduce_max( - gentype value ) + gentype value ) gentype sub_group_non_uniform_reduce_mul( - gentype value ) + gentype value ) ---- | Returns the summation, multiplication, minimum, or maximum of _value_ for all active work items in the sub-group. @@ -14432,13 +14515,13 @@ gentype sub_group_non_uniform_reduce_mul( |[source,opencl_c] ---- gentype sub_group_non_uniform_scan_inclusive_add( - gentype value ) + gentype value ) gentype sub_group_non_uniform_scan_inclusive_min( - gentype value ) + gentype value ) gentype sub_group_non_uniform_scan_inclusive_max( - gentype value ) + gentype value ) gentype sub_group_non_uniform_scan_inclusive_mul( - gentype value ) + gentype value ) ---- | Returns the result of an inclusive scan operation, which is the summation, multiplication, minimum, or maximum of _value_ for all active @@ -14452,13 +14535,13 @@ gentype sub_group_non_uniform_scan_inclusive_mul( |[source,opencl_c] ---- gentype sub_group_non_uniform_scan_exclusive_add( - gentype value ) + gentype value ) gentype sub_group_non_uniform_scan_exclusive_min( - gentype value ) + gentype value ) gentype sub_group_non_uniform_scan_exclusive_max( - gentype value ) + gentype value ) gentype sub_group_non_uniform_scan_exclusive_mul( - gentype value ) + gentype value ) ---- | Returns the result of an exclusive scan operation, which is the summation, multiplication, minimum, or maximum of _value_ for all active @@ -14506,22 +14589,22 @@ supported built-in scalar data types `char`, `uchar`, `short`, `ushort`, |[source,opencl_c] ---- gentype sub_group_non_uniform_reduce_and( - gentype value ) + gentype value ) gentype sub_group_non_uniform_reduce_or( - gentype value ) + gentype value ) gentype sub_group_non_uniform_reduce_xor( - gentype value ) + gentype value ) ---- | Returns the bitwise *and*, *or*, or *xor* of _value_ for all active work items in the sub-group. |[source,opencl_c] ---- gentype sub_group_non_uniform_scan_inclusive_and( - gentype value ) + gentype value ) gentype sub_group_non_uniform_scan_inclusive_or( - gentype value ) + gentype value ) gentype sub_group_non_uniform_scan_inclusive_xor( - gentype value ) + gentype value ) ---- | Returns the result of an inclusive scan operation, which is the bitwise *and*, *or*, or *xor* of _value_ for all active work items in the @@ -14530,11 +14613,11 @@ gentype sub_group_non_uniform_scan_inclusive_xor( |[source,opencl_c] ---- gentype sub_group_non_uniform_scan_exclusive_and( - gentype value ) + gentype value ) gentype sub_group_non_uniform_scan_exclusive_or( - gentype value ) + gentype value ) gentype sub_group_non_uniform_scan_exclusive_xor( - gentype value ) + gentype value ) ---- | Returns the result of an exclusive scan operation, which is the bitwise *and*, *or*, or *xor* of _value_ for all active work items in the @@ -14568,22 +14651,22 @@ logically `false`. |[source,opencl_c] ---- int sub_group_non_uniform_reduce_logical_and( - int predicate ) + int predicate ) int sub_group_non_uniform_reduce_logical_or( - int predicate ) + int predicate ) int sub_group_non_uniform_reduce_logical_xor( - int predicate ) + int predicate ) ---- | Returns the logical *and*, *or*, or *xor* of _predicate_ for all active work items in the sub-group. |[source,opencl_c] ---- int sub_group_non_uniform_scan_inclusive_logical_and( - int predicate ) + int predicate ) int sub_group_non_uniform_scan_inclusive_logical_or( - int predicate ) + int predicate ) int sub_group_non_uniform_scan_inclusive_logical_xor( - int predicate ) + int predicate ) ---- | Returns the result of an inclusive scan operation, which is the logical *and*, *or*, or *xor* of _predicate_ for all active work items in the @@ -14592,11 +14675,11 @@ int sub_group_non_uniform_scan_inclusive_logical_xor( |[source,opencl_c] ---- int sub_group_non_uniform_scan_exclusive_logical_and( - int predicate ) + int predicate ) int sub_group_non_uniform_scan_exclusive_logical_or( - int predicate ) + int predicate ) int sub_group_non_uniform_scan_exclusive_logical_xor( - int predicate ) + int predicate ) ---- | Returns the result of an exclusive scan operation, which is the logical *and*, *or*, or *xor* of _predicate_ for all active work items in the @@ -14648,7 +14731,7 @@ int sub_group_elect() |[source,opencl_c] ---- int sub_group_non_uniform_all( - int predicate ) + int predicate ) ---- | Examines _predicate_ for all active work items in the sub-group and returns a non-zero value if _predicate_ is non-zero for all active work @@ -14660,7 +14743,7 @@ int sub_group_non_uniform_all( |[source,opencl_c] ---- int sub_group_non_uniform_any( - int predicate ) + int predicate ) ---- | Examines _predicate_ for all active work items in the sub-group and returns a non-zero value if _predicate_ is non-zero for any active work @@ -14672,7 +14755,7 @@ int sub_group_non_uniform_any( |[source,opencl_c] ---- int sub_group_non_uniform_all_equal( - gentype value ) + gentype value ) ---- | Examines _value_ for all active work items in the sub-group and returns a non-zero value if _value_ is equivalent for all active invocations in @@ -14712,7 +14795,7 @@ footnote:[{fn-double-supported}]. |[source,opencl_c] ---- gentype sub_group_rotate( - gentype value, int delta) + gentype value, int delta) ---- | Returns _value_ for the work item with sub-group local ID equal to the remainder of the division of the sum of this work item's sub-group local @@ -14725,8 +14808,8 @@ gentype sub_group_rotate( |[source,opencl_c] ---- gentype sub_group_clustered_rotate( - gentype value, int delta, - uint clustersize) + gentype value, int delta, + uint clustersize) ---- | Returns _value_ for the work item with sub-group local ID equal to the sum of, the remainder of the division of the sum of this work item's ID @@ -14772,7 +14855,7 @@ footnote:[{fn-double-supported}]. |[source,opencl_c] ---- gentype sub_group_shuffle( - gentype value, uint index ) + gentype value, uint index ) ---- | Returns _value_ for the work item with sub-group local ID equal to _index_. @@ -14785,7 +14868,7 @@ gentype sub_group_shuffle( |[source,opencl_c] ---- gentype sub_group_shuffle_xor( - gentype value, uint mask ) + gentype value, uint mask ) ---- | Returns _value_ for the work item with sub-group local ID equal to this work item's sub-group local ID xor'd with _mask_. @@ -14824,7 +14907,7 @@ footnote:[{fn-double-supported}]. |[source,opencl_c] ---- gentype sub_group_shuffle_up( - gentype value, uint delta ) + gentype value, uint delta ) ---- | Returns _value_ for the work item with sub-group local ID equal to this work item's sub-group local ID minus _delta_. @@ -14840,7 +14923,7 @@ gentype sub_group_shuffle_up( |[source,opencl_c] ---- gentype sub_group_shuffle_down( - gentype value, uint delta ) + gentype value, uint delta ) ---- | Returns _value_ for the work item with sub-group local ID equal to this work item's sub-group local ID plus _delta_. diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 7e98ce853..b349d587a 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -14049,7 +14049,7 @@ include::{generated}/api/version-notes/clCreateCommandBufferKHR.asciidoc[] + [[commandbuffer-properties]] .{clCreateCommandBufferKHR} properties -[cols=",,",options="header",] +[cols="2,1,3",options="header",] |==== | Recording Properties | Property Value | Description @@ -15187,7 +15187,7 @@ endif::cl_khr_command_buffer_mutable_dispatch[] [[ndrange-kernel-properties-table]] .List of supported properties by {clCommandNDRangeKernelKHR} -[cols=",,",options="header",] +[cols="3,2,10",options="header",] |==== | Recording Properties | Property Value | Description @@ -15208,7 +15208,9 @@ include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_ASSERTS_KHR.asciidoc[ _0_ to _work_dim - 1_ of _ceil(global_work_size[i]/local_work_size[i])_. -include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_ASSERT_NO_ADDITIONAL_WORK_GROUPS_KHR.asciidoc[] +// Removed for now to reduce table cell size. +// The extension dependency is captured in the property itself. +//include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_ASSERT_NO_ADDITIONAL_WORK_GROUPS_KHR.asciidoc[] | {CL_MUTABLE_DISPATCH_UPDATABLE_FIELDS_KHR_anchor} @@ -15226,7 +15228,9 @@ include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_UPDATABLE_FIELDS_KHR. parameter. Otherwise, the _global_work_offset_ cannot be modified. -include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_GLOBAL_OFFSET_KHR.asciidoc[] +// Removed for now to reduce table cell size. +// The extension dependency is captured in the property itself. +//include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_GLOBAL_OFFSET_KHR.asciidoc[] {CL_MUTABLE_DISPATCH_GLOBAL_SIZE_KHR_anchor} determines whether the _global_work_size_ of kernel execution can be modified after @@ -15237,7 +15241,9 @@ include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_GLOBAL_OFFSET_KHR.asc parameter. Otherwise, the _global_work_size_ cannot be modified. -include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_GLOBAL_SIZE_KHR.asciidoc[] +// Removed for now to reduce table cell size. +// The extension dependency is captured in the property itself. +//include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_GLOBAL_SIZE_KHR.asciidoc[] {CL_MUTABLE_DISPATCH_LOCAL_SIZE_KHR_anchor} determines whether the _local_work_size_ of kernel execution can be modified after recording. @@ -15247,7 +15253,9 @@ include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_GLOBAL_SIZE_KHR.ascii parameter. Otherwise, the _local_work_size_ cannot be modified. -include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_LOCAL_SIZE_KHR.asciidoc[] +// Removed for now to reduce table cell size. +// The extension dependency is captured in the property itself. +//include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_LOCAL_SIZE_KHR.asciidoc[] {CL_MUTABLE_DISPATCH_ARGUMENTS_KHR_anchor} determines whether the kernel arguments set on _kernel_ can be updated between executions. @@ -15258,7 +15266,9 @@ include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_LOCAL_SIZE_KHR.asciid parameter. Otherwise, the kernel arguments cannot be modified between executions. -include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_ARGUMENTS_KHR.asciidoc[] +// Removed for now to reduce table cell size. +// The extension dependency is captured in the property itself. +//include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_ARGUMENTS_KHR.asciidoc[] {CL_MUTABLE_DISPATCH_EXEC_INFO_KHR_anchor} determines whether the information passed to _kernel_ can be updated between executions. @@ -15268,7 +15278,9 @@ include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_ARGUMENTS_KHR.asciido parameter. Otherwise, the kernel execution information cannot be modified. -include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_EXEC_INFO_KHR.asciidoc[] +// Removed for now to reduce table cell size. +// The extension dependency is captured in the property itself. +//include::{generated}/api/version-notes/CL_MUTABLE_DISPATCH_EXEC_INFO_KHR.asciidoc[] If {CL_MUTABLE_DISPATCH_UPDATABLE_FIELDS_KHR_anchor} is not specified then it defaults to the value returned by the diff --git a/config/rouge/lib/rouge/lexers/opencl.rb b/config/rouge/lib/rouge/lexers/opencl.rb index 69d22503e..1e1457c80 100644 --- a/config/rouge/lib/rouge/lexers/opencl.rb +++ b/config/rouge/lib/rouge/lexers/opencl.rb @@ -120,6 +120,8 @@ class OpenCL < Cpp cl_profiling_info cl_sampler_properties cl_kernel_exec_info + cl_context_memory_initialize_khr + cl_device_terminate_capability_khr cl_device_unified_shared_memory_capabilities_intel cl_mem_properties_intel cl_mem_alloc_flags_intel @@ -135,6 +137,7 @@ class OpenCL < Cpp cl_mem_alloc_flags_img cl_layer_info cl_layer_api_version + cl_icdl_info cl_icd_dispatch cl_device_scheduling_controls_capabilities_arm cl_device_controlled_termination_capabilities_arm @@ -142,6 +145,7 @@ class OpenCL < Cpp cl_device_feature_capabilities_intel cl_device_integer_dot_product_capabilities_khr cl_semaphore_properties_khr + cl_semaphore_reimport_properties_khr cl_semaphore_info_khr cl_semaphore_type_khr cl_semaphore_payload_khr @@ -153,7 +157,16 @@ class OpenCL < Cpp cl_command_buffer_info_khr cl_command_buffer_state_khr cl_command_buffer_properties_khr + cl_command_buffer_flags_khr cl_ndrange_kernel_command_properties_khr + cl_mutable_command_khr + cl_mutable_dispatch_fields_khr + cl_mutable_command_info_khr + cl_command_buffer_structure_type_khr + cl_device_fp_atomic_capabilities_ext + cl_image_requirements_info_ext + cl_platform_command_buffer_capabilities_khr + cl_mutable_dispatch_asserts_khr cl_dx9_surface_info_khr cl_motion_estimation_desc_intel cl_mem_ext_host_ptr @@ -174,16 +187,10 @@ class OpenCL < Cpp CL_VERSION_PATCH_KHR CL_MAKE_VERSION_KHR cl_device_integer_dot_product_acceleration_properties_khr - cl_command_buffer_khr - cl_mutable_command_khr - cl_mutable_command_info_khr - cl_command_buffer_structure_type_khr - cl_mutable_base_config_khr cl_mutable_dispatch_arg_khr - cl_mutable_dispatch_config_khr cl_mutable_dispatch_exec_info_khr - cl_mutable_dispatch_fields_khr - cl_platform_command_buffer_capabilities_khr + cl_mutable_dispatch_config_khr + cl_mutable_base_config_khr ) # Here are some interesting tokens diff --git a/config/rouge/lib/rouge/lexers/opencl_c.rb b/config/rouge/lib/rouge/lexers/opencl_c.rb index 9a56bf6c2..72412f13c 100644 --- a/config/rouge/lib/rouge/lexers/opencl_c.rb +++ b/config/rouge/lib/rouge/lexers/opencl_c.rb @@ -31,6 +31,7 @@ class OpenCL_C < Cpp image2d_array_t image2d_depth_t image2d_array_depth_t + image2d_msaa_t sampler_t queue_t ndrange_t From ed84d3576e846f945d35f5a621208df4be0ae35e Mon Sep 17 00:00:00 2001 From: Jon Leech <4693344+oddhack@users.noreply.github.com> Date: Mon, 1 Apr 2024 08:28:17 -0700 Subject: [PATCH 19/71] Restore static refpages to the build (#1127) These were commented out during debugging and not restored. Also factors out a small difference between Vulkan and OpenCL scripts. Closes #1121 --- Makefile | 5 +++-- scripts/docgenerator.py | 8 ++++++-- scripts/spec_tools/conventions.py | 8 ++++++++ 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index 8e171b81e..1540b8343 100644 --- a/Makefile +++ b/Makefile @@ -459,7 +459,7 @@ $(REFPATH)/apispec.txt: $(SPECFILES) $(GENREF) $(SCRIPTS)/reflib.py $(PYAPIMAP) (cat $(MANDIR)/rewritehead ; \ echo ; echo "# Aliases hard-coded in refpage markup" ; \ sort < $(REFPATH)/rewritebody) > $(REFPATH)/.htaccess - echo $(CP) $(MANDIR)/static/*.txt $(REFPATH) + $(CP) $(MANDIR)/static/*.txt $(REFPATH) # These targets are HTML5 ref pages # @@ -493,11 +493,12 @@ $(MANHTMLDIR)/%.html: $(REFPATH)/%.txt $(MANCOPYRIGHT) $(GENDEPENDS) $(KATEXINST $(VERYQUIET)$(ASCIIDOCTOR) -b html5 $(ADOCOPTS) $(ADOCHTMLOPTS) \ $(ADOCREFOPTS) -o $@ $< +# This is not formatted as a refpage, so needs a different build rule $(MANHTMLDIR)/intro.html: $(REFPATH)/intro.txt $(MANCOPYRIGHT) $(VERYQUIET)echo "Building $@ from $< using default options" $(VERYQUIET)$(MKDIR) $(MANHTMLDIR) $(VERYQUIET)$(ASCIIDOCTOR) -b html5 $(ADOCOPTS) $(ADOCHTMLOPTS) \ - $(ADOCREFOPTS) -o $@ $< + -o $@ $< # Targets generated from the XML and registry processing scripts # apimap.py - Python encoding of the registry diff --git a/scripts/docgenerator.py b/scripts/docgenerator.py index 3692768cf..b714ef7c4 100644 --- a/scripts/docgenerator.py +++ b/scripts/docgenerator.py @@ -255,7 +255,11 @@ def writeInclude(self, directory, basename, contents): index_term = basename write('indexterm:[{}]'.format(index_term), file=fp) - write(f'[source%unbreakable,{self.conventions.docgen_language}]', file=fp) + source_options = self.conventions.docgen_source_options + source_language = self.conventions.docgen_language + source_directive = f'[source{source_options},{source_language}]' + + write(source_directive, file=fp) write('----', file=fp) write(contents, file=fp) write('----', file=fp) @@ -270,7 +274,7 @@ def writeInclude(self, directory, basename, contents): # Asciidoc anchor write(self.genOpts.conventions.warning_comment, file=fp) write('// Include this no-xref version without cross reference id for multiple includes of same file', file=fp) - write(f'[source,%unbreakable,{self.conventions.docgen_language}]', file=fp) + write(source_directive, file=fp) write('----', file=fp) write(contents, file=fp) write('----', file=fp) diff --git a/scripts/spec_tools/conventions.py b/scripts/spec_tools/conventions.py index edfa906cf..50ca75d41 100644 --- a/scripts/spec_tools/conventions.py +++ b/scripts/spec_tools/conventions.py @@ -548,3 +548,11 @@ def docgen_language(self): blocks.""" return 'c++' + + @property + def docgen_source_options(self): + """Return block options to be used in docgenerator [source] blocks, + which are appended to the 'source' block type. + Can be empty.""" + + return '%unbreakable' From 45adff76098c6050d362336bf253ce8a12437a9a Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 1 Apr 2024 23:24:15 -0700 Subject: [PATCH 20/71] fix an incorrect link to cl_khr_async_work_group_copy_fence (#1132) --- api/appendix_e.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/appendix_e.asciidoc b/api/appendix_e.asciidoc index 2bec7aeb0..c88b80933 100644 --- a/api/appendix_e.asciidoc +++ b/api/appendix_e.asciidoc @@ -521,7 +521,7 @@ Changes from *v3.0.9*: * Clarified that {clCompileProgram} is valid for programs created from SPIR. * Documented the possible state of a kernel object after a failed call to {clSetKernelArg}. * Added new extensions: - ** `<>` (final) + ** `<>` (final) ** `<>` (final) ** `<>` ** `<>` (provisional) From 0f01c28b75f99c670cd78ae9aca85e6231352cb6 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Tue, 2 Apr 2024 08:23:16 -0700 Subject: [PATCH 21/71] add extension docs for spir-v-related extensions (#1123) * add extension docs for spir-v-related extensions cl_khr_spirv_extended_debug_info cl_khr_spirv_linkonce_odr cl_khr_spirv_no_integer_wrap_decoration * fix extension name --- OpenCL_Ext.txt | 4 --- api/cl_khr_spirv_extended_debug_info.asciidoc | 27 ++++++++++++++++++ api/cl_khr_spirv_linkonce_odr.asciidoc | 27 ++++++++++++++++++ ..._spirv_no_integer_wrap_decoration.asciidoc | 28 +++++++++++++++++++ config/opencl.asciidoc | 1 + ext/quick_reference.asciidoc | 12 ++++++++ ext/spirv_extensions.asciidoc | 14 ---------- xml/cl.xml | 3 ++ 8 files changed, 98 insertions(+), 18 deletions(-) create mode 100644 api/cl_khr_spirv_extended_debug_info.asciidoc create mode 100644 api/cl_khr_spirv_linkonce_odr.asciidoc create mode 100644 api/cl_khr_spirv_no_integer_wrap_decoration.asciidoc delete mode 100644 ext/spirv_extensions.asciidoc diff --git a/OpenCL_Ext.txt b/OpenCL_Ext.txt index 68e4295b7..b84dddf87 100644 --- a/OpenCL_Ext.txt +++ b/OpenCL_Ext.txt @@ -51,10 +51,6 @@ include::ext/introduction.asciidoc[] // included markup in the OpenCL API and C Language Specifications, rather // than being included here as separate documents. -// These are SPIR-V Extensions: - -include::ext/spirv_extensions.asciidoc[] - // Index and Appendices: ifdef::backend-pdf[] diff --git a/api/cl_khr_spirv_extended_debug_info.asciidoc b/api/cl_khr_spirv_extended_debug_info.asciidoc new file mode 100644 index 000000000..5e280fb1a --- /dev/null +++ b/api/cl_khr_spirv_extended_debug_info.asciidoc @@ -0,0 +1,27 @@ +// Copyright 2017-2024 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}cl_khr_spirv_extended_debug_info.txt[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2020-04-21 +*IP Status*:: + No known IP claims. +*Contributors*:: + TBD + +=== Description + +`cl_khr_spirv_extended_debug_info` allows use of the SPIR-V +`OpenCL.DebugInfo.100` extended instruction set. + +See the +link:{OpenCLEnvSpecURL}#_cl_khr_spirv_extended_debug_info[cl_khr_spirv_extended_debug_info] +section of the OpenCL SPIR-V Environment specification for more information. + +=== Version History + + * Revision 1.0.0, 2020-04-21 + ** First assigned version. diff --git a/api/cl_khr_spirv_linkonce_odr.asciidoc b/api/cl_khr_spirv_linkonce_odr.asciidoc new file mode 100644 index 000000000..f35df832f --- /dev/null +++ b/api/cl_khr_spirv_linkonce_odr.asciidoc @@ -0,0 +1,27 @@ +// Copyright 2017-2024 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}cl_khr_spirv_linkonce_odr.txt[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2020-04-21 +*IP Status*:: + No known IP claims. +*Contributors*:: + TBD + +=== Description + +`cl_khr_spirv_linkonce_odr` allows use of the SPIR-V extension +`SPV_KHR_linkonce_odr`. + +See the +link:{OpenCLEnvSpecURL}#_cl_khr_spirv_linkonce_odr[cl_khr_spirv_linkonce_odr] +section of the OpenCL SPIR-V Environment specification for more information. + +=== Version History + + * Revision 1.0.0, 2020-04-21 + ** First assigned version. diff --git a/api/cl_khr_spirv_no_integer_wrap_decoration.asciidoc b/api/cl_khr_spirv_no_integer_wrap_decoration.asciidoc new file mode 100644 index 000000000..d8456b6ab --- /dev/null +++ b/api/cl_khr_spirv_no_integer_wrap_decoration.asciidoc @@ -0,0 +1,28 @@ +// Copyright 2017-2024 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}cl_khr_spirv_no_integer_wrap_decoration.txt[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2020-04-21 +*IP Status*:: + No known IP claims. +*Contributors*:: + TBD + +=== Description + +`cl_khr_spirv_no_integer_wrap_decoration` allows use of the SPIR-V extension +`SPV_KHR_no_integer_wrap_decoration`, which adds new decorations to indicate +that a given instruction does not cause integer wrapping to occur. + +See the +link:{OpenCLEnvSpecURL}#_cl_khr_spirv_no_integer_wrap_decoration[cl_khr_spirv_no_integer_wrap_decoration] +section of the OpenCL SPIR-V Environment specification for more information. + +=== Version History + + * Revision 1.0.0, 2020-04-21 + ** First assigned version. diff --git a/config/opencl.asciidoc b/config/opencl.asciidoc index 62f166b4f..7839cc441 100644 --- a/config/opencl.asciidoc +++ b/config/opencl.asciidoc @@ -7,6 +7,7 @@ :khronos-opencl-repo: https://github.com/KhronosGroup/OpenCL-Docs :khronos-opencl-pr: {khronos-opencl-repo}/pull :OpenCLCSpecURL: OpenCL_C.html +:OpenCLEnvSpecURL: OpenCL_Env.html :blank: pass:[ +] :pp: ++ diff --git a/ext/quick_reference.asciidoc b/ext/quick_reference.asciidoc index 3b47e039f..6fddf7120 100644 --- a/ext/quick_reference.asciidoc +++ b/ext/quick_reference.asciidoc @@ -232,6 +232,18 @@ Language Specifications. | Standard Portable Intermediate Representation Programs | Extension, Superseded by IL Programs / SPIR-V +| [[cl_khr_spirv_extended_debug_info]] link:{APISpecURL}#cl_khr_spirv_extended_debug_info[`cl_khr_spirv_extended_debug_info`] +| Allows Use of the SPIR-V `OpenCL.DebugInfo.100` Extended Instruction Set +| Extension + +| [[cl_khr_spirv_linkonce_odr]] link:{APISpecURL}#cl_khr_spirv_linkonce_odr[`cl_khr_spirv_linkonce_odr`] +| Allows Use of the SPIR-V `SPV_KHR_linkonce_odr` Extension +| Extension + +| [[cl_khr_spirv_no_integer_wrap_decoration]] link:{APISpecURL}#cl_khr_spirv_no_integer_wrap_decoration[`cl_khr_spirv_no_integer_wrap_decoration`] +| Allows Use of the SPIR-V `SPV_KHR_no_integer_wrap_decoration` Extension +| Extension + | [[cl_khr_srgb_image_writes]] link:{APISpecURL}#cl_khr_srgb_image_writes[`cl_khr_srgb_image_writes`] | Write to sRGB Images | Extension diff --git a/ext/spirv_extensions.asciidoc b/ext/spirv_extensions.asciidoc deleted file mode 100644 index bffbf1f8d..000000000 --- a/ext/spirv_extensions.asciidoc +++ /dev/null @@ -1,14 +0,0 @@ -// Copyright 2017-2024 The Khronos Group. This work is licensed under a -// Creative Commons Attribution 4.0 International License; see -// http://creativecommons.org/licenses/by/4.0/ - -[[spirv_extensions]] -== Extensions to the OpenCL SPIR-V Environment - -An OpenCL SPIR-V environment may be modified by OpenCL extensions. -Please refer to the OpenCL SPIR-V Environment Specification for descriptions how OpenCL extensions modify an OpenCL SPIR-V environment. -In addition to the extensions described in this document, the OpenCL SPIR-V Environment Specification also describes how the following OpenCL extensions modify an OpenCL SPIR-V environment: - -* `cl_khr_spirv_no_integer_wrap_decoration` -* `cl_khr_spirv_extended_debug_info` -* `cl_khr_spirv_linkonce_odr` diff --git a/xml/cl.xml b/xml/cl.xml index fa6b29974..b0c5cc2ed 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -7442,6 +7442,9 @@ server's OpenCL/api-docs repository. + + + From 93f7aaa6e6fad75b9e34bce9842cc4c4b20528ee Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Tue, 2 Apr 2024 08:27:20 -0700 Subject: [PATCH 22/71] add and link error codes for extensions (#1119) * add error codes for cl_khr_command_buffer * add error codes for cl_khr_d3d10_sharing * add error codes for cl_khr_d3d11_sharing * error codes for cl_khr_dx9_media_sharing * error codes for cl_khr_egl_event * error codes for cl_khr_egl_image * error codes for cl_khr_gl_sharing * error codes for cl_khr_semaphore * error codes for cl_khr_terminate_context * error codes for cl_khr_command_buffer_mutable_dispatch * fix typo Co-authored-by: Alastair Murray --------- Co-authored-by: Alastair Murray --- api/appendix_f.asciidoc | 124 +++++++++++++++++- ...r_command_buffer_mutable_dispatch.asciidoc | 2 +- api/cl_khr_d3d10_sharing.asciidoc | 2 +- api/cl_khr_d3d11_sharing.asciidoc | 2 +- api/cl_khr_dx9_media_sharing.asciidoc | 2 +- api/cl_khr_egl_event.asciidoc | 7 +- api/cl_khr_egl_image.asciidoc | 2 +- api/cl_khr_external_memory.asciidoc | 2 +- api/cl_khr_gl_sharing.asciidoc | 5 +- api/cl_khr_semaphore.asciidoc | 2 +- 10 files changed, 130 insertions(+), 20 deletions(-) diff --git a/api/appendix_f.asciidoc b/api/appendix_f.asciidoc index f2bb39c62..b20d88295 100644 --- a/api/appendix_f.asciidoc +++ b/api/appendix_f.asciidoc @@ -139,12 +139,6 @@ include::{generated}/api/version-notes/CL_INVALID_EVENT.asciidoc[] include::{generated}/api/version-notes/CL_INVALID_EVENT_WAIT_LIST.asciidoc[] | Returned when the specified event wait list or number of events in the wait list is not valid. -// This is currently defined in cl.h, but it's not a core API error code. -//| {CL_INVALID_GL_OBJECT_anchor} -// -//include::{generated}/api/version-notes/CL_INVALID_GL_OBJECT.asciidoc[] -//| - | {CL_INVALID_GLOBAL_OFFSET_anchor} include::{generated}/api/version-notes/CL_INVALID_GLOBAL_OFFSET.asciidoc[] @@ -332,6 +326,110 @@ include::{generated}/api/version-notes/CL_MAX_SIZE_RESTRICTION_EXCEEDED.asciidoc include::{generated}/api/version-notes/CL_PROFILING_INFO_NOT_AVAILABLE.asciidoc[] | Returned by {clGetEventProfilingInfo} when the command associated with the specified event was not enqueued into a command-queue with {CL_QUEUE_PROFILING_ENABLE}. +ifdef::cl_khr_command_buffer[] +| {CL_INVALID_COMMAND_BUFFER_KHR_anchor} + +include::{generated}/api/version-notes/CL_INVALID_COMMAND_BUFFER_KHR.asciidoc[] +| Returned when the specified command-buffer is not a <>. + +| {CL_INVALID_SYNC_POINT_WAIT_LIST_KHR_anchor} + +include::{generated}/api/version-notes/CL_INVALID_SYNC_POINT_WAIT_LIST_KHR.asciidoc[] +| Returned when the specified sync point wait list or number of sync points in the wait list is not valid. + +| {CL_INCOMPATIBLE_COMMAND_QUEUE_KHR_anchor} + +include::{generated}/api/version-notes/CL_INCOMPATIBLE_COMMAND_QUEUE_KHR.asciidoc[] +| Returned when one or more command-queues is incompatible with a command-buffer. +endif::cl_khr_command_buffer[] + +ifdef::cl_khr_command_buffer_mutable_dispatch[] +| {CL_INVALID_MUTABLE_COMMAND_KHR_anchor} + +include::{generated}/api/version-notes/CL_INVALID_MUTABLE_COMMAND_KHR.asciidoc[] +| Returned when a specified command is not a <>. +endif::cl_khr_command_buffer_mutable_dispatch[] + +ifdef::cl_khr_d3d10_sharing[] +| {CL_INVALID_D3D10_DEVICE_KHR_anchor} + +include::{generated}/api/version-notes/CL_INVALID_D3D10_DEVICE_KHR.asciidoc[] +| Returned when a Direct3D 10 device cannot interoperate with OpenCL device IDs. +| {CL_INVALID_D3D10_RESOURCE_KHR_anchor} + +include::{generated}/api/version-notes/CL_INVALID_D3D10_RESOURCE_KHR.asciidoc[] +| Returned when an OpenCL object cannot be created from a Direct3D 10 resource. +| {CL_D3D10_RESOURCE_ALREADY_ACQUIRED_KHR_anchor} + +include::{generated}/api/version-notes/CL_D3D10_RESOURCE_ALREADY_ACQUIRED_KHR.asciidoc[] +| Returned when attempting to acquire an OpenCL object created from a Direct3D 10 resource that was already acquired. +| {CL_D3D10_RESOURCE_NOT_ACQUIRED_KHR_anchor} + +include::{generated}/api/version-notes/CL_D3D10_RESOURCE_NOT_ACQUIRED_KHR.asciidoc[] +| Returned when attempting to release an OpenCL object created from a Direct3D 10 resource that has not been acquired. +endif::cl_khr_d3d10_sharing[] + +ifdef::cl_khr_d3d11_sharing[] +| {CL_INVALID_D3D11_DEVICE_KHR_anchor} + +include::{generated}/api/version-notes/CL_INVALID_D3D11_DEVICE_KHR.asciidoc[] +| Returned when a Direct3D 11 device cannot interoperate with OpenCL device IDs. +| {CL_INVALID_D3D11_RESOURCE_KHR_anchor} + +include::{generated}/api/version-notes/CL_INVALID_D3D11_RESOURCE_KHR.asciidoc[] +| Returned when an OpenCL object cannot be created from a Direct3D 11 resource. +| {CL_D3D11_RESOURCE_ALREADY_ACQUIRED_KHR_anchor} + +include::{generated}/api/version-notes/CL_D3D11_RESOURCE_ALREADY_ACQUIRED_KHR.asciidoc[] +| Returned when attempting to acquire an OpenCL object created from a Direct3D 11 resource that was already acquired. +| {CL_D3D11_RESOURCE_NOT_ACQUIRED_KHR_anchor} + +include::{generated}/api/version-notes/CL_D3D11_RESOURCE_NOT_ACQUIRED_KHR.asciidoc[] +| Returned when attempting to release an OpenCL object created from a Direct3D 11 resource that has not been acquired. +endif::cl_khr_d3d11_sharing[] + +ifdef::cl_khr_dx9_media_sharing[] +| {CL_INVALID_DX9_MEDIA_ADAPTER_KHR_anchor} + +include::{generated}/api/version-notes/CL_INVALID_DX9_MEDIA_ADAPTER_KHR.asciidoc[] +| Returned when a DirectX 9 media adapter cannot interoperate with OpenCL device IDs. +| {CL_INVALID_DX9_MEDIA_SURFACE_KHR_anchor} + +include::{generated}/api/version-notes/CL_INVALID_DX9_MEDIA_SURFACE_KHR.asciidoc[] +| Returned when an OpenCL object cannot be created from a DirectX 9 media surface. +| {CL_DX9_MEDIA_SURFACE_ALREADY_ACQUIRED_KHR_anchor} + +include::{generated}/api/version-notes/CL_DX9_MEDIA_SURFACE_ALREADY_ACQUIRED_KHR.asciidoc[] +| Returned when attempting to acquire an OpenCL object created from a DirectX 9 media surface that was already acquired. +| {CL_DX9_MEDIA_SURFACE_NOT_ACQUIRED_KHR_anchor} + +include::{generated}/api/version-notes/CL_DX9_MEDIA_SURFACE_NOT_ACQUIRED_KHR.asciidoc[] +| Returned when attempting to release an OpenCL object created from a DirectX 9 media surface that has not been acquired. +endif::cl_khr_dx9_media_sharing[] + +ifdef::cl_khr_egl_image[] +| {CL_EGL_RESOURCE_NOT_ACQUIRED_KHR_anchor} + +include::{generated}/api/version-notes/CL_EGL_RESOURCE_NOT_ACQUIRED_KHR.asciidoc[] +| Possible event status if an EGL resource is used without being acquired. +| {CL_INVALID_EGL_OBJECT_KHR_anchor} + +include::{generated}/api/version-notes/CL_INVALID_EGL_OBJECT_KHR.asciidoc[] +| Returned when the specified EGL object is not valid. +endif::cl_khr_egl_image[] + +ifdef::cl_khr_gl_sharing[] +// Note: This is currently defined in cl.h, but it's not a core API error code. +| {CL_INVALID_GL_OBJECT_anchor} + +include::{generated}/api/version-notes/CL_INVALID_GL_OBJECT.asciidoc[] +| Returned when the specified OpenGL object is not valid, or when there is no associated OpenGL object for an OpenCL object. +| {CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR_anchor} + +include::{generated}/api/version-notes/CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR.asciidoc[] +| Returned when the specified OpenGL sharing context creation property is not valid. +endif::cl_khr_gl_sharing[] + ifdef::cl_khr_icd[] | {CL_PLATFORM_NOT_FOUND_KHR_anchor} @@ -339,4 +437,18 @@ include::{generated}/api/version-notes/CL_PLATFORM_NOT_FOUND_KHR.asciidoc[] | Returned by {clGetPlatformIDs} when no platforms are available. endif::cl_khr_icd[] +ifdef::cl_khr_semaphore[] +| {CL_INVALID_SEMAPHORE_KHR_anchor} + +include::{generated}/api/version-notes/CL_INVALID_SEMAPHORE_KHR.asciidoc[] +| Returned when the specified semaphore is not a <>. +endif::cl_khr_semaphore[] + +ifdef::cl_khr_terminate_context[] +| {CL_CONTEXT_TERMINATED_KHR_anchor} + +include::{generated}/api/version-notes/CL_CONTEXT_TERMINATED_KHR.asciidoc[] +| Returned when the specified context has already been terminated, or as an event status for terminated commands. +endif::cl_khr_terminate_context[] + |==== diff --git a/api/cl_khr_command_buffer_mutable_dispatch.asciidoc b/api/cl_khr_command_buffer_mutable_dispatch.asciidoc index 6f35f3006..8883fc837 100644 --- a/api/cl_khr_command_buffer_mutable_dispatch.asciidoc +++ b/api/cl_khr_command_buffer_mutable_dispatch.asciidoc @@ -118,7 +118,7 @@ also be updated between enqueues of the command-buffer. * {cl_command_buffer_structure_type_khr_TYPE} ** {CL_STRUCTURE_TYPE_MUTABLE_BASE_CONFIG_KHR} ** {CL_STRUCTURE_TYPE_MUTABLE_DISPATCH_CONFIG_KHR} - * New <> + * New Error Codes ** {CL_INVALID_MUTABLE_COMMAND_KHR} === Sample Code diff --git a/api/cl_khr_d3d10_sharing.asciidoc b/api/cl_khr_d3d10_sharing.asciidoc index 1f8fe5242..0a69e5e89 100644 --- a/api/cl_khr_d3d10_sharing.asciidoc +++ b/api/cl_khr_d3d10_sharing.asciidoc @@ -46,7 +46,7 @@ include::{generated}/meta/{refprefix}cl_khr_d3d10_sharing.txt[] ** {CL_MEM_D3D10_RESOURCE_KHR} * {cl_image_info_TYPE} ** {CL_IMAGE_D3D10_SUBRESOURCE_KHR} - * {cl_event_info_TYPE} + * {cl_command_type_TYPE} ** {CL_COMMAND_ACQUIRE_D3D10_OBJECTS_KHR} ** {CL_COMMAND_RELEASE_D3D10_OBJECTS_KHR} * New Error Codes diff --git a/api/cl_khr_d3d11_sharing.asciidoc b/api/cl_khr_d3d11_sharing.asciidoc index 2ee08b859..e0573b296 100644 --- a/api/cl_khr_d3d11_sharing.asciidoc +++ b/api/cl_khr_d3d11_sharing.asciidoc @@ -46,7 +46,7 @@ include::{generated}/meta/{refprefix}cl_khr_d3d11_sharing.txt[] ** {CL_MEM_D3D11_RESOURCE_KHR} * {cl_image_info_TYPE} ** {CL_IMAGE_D3D11_SUBRESOURCE_KHR} - * {cl_event_info_TYPE} + * {cl_command_type_TYPE} ** {CL_COMMAND_ACQUIRE_D3D11_OBJECTS_KHR} ** {CL_COMMAND_RELEASE_D3D11_OBJECTS_KHR} * New Error Codes diff --git a/api/cl_khr_dx9_media_sharing.asciidoc b/api/cl_khr_dx9_media_sharing.asciidoc index 60465c6d5..91fd3dad4 100644 --- a/api/cl_khr_dx9_media_sharing.asciidoc +++ b/api/cl_khr_dx9_media_sharing.asciidoc @@ -55,7 +55,7 @@ adapter. ** {CL_MEM_DX9_MEDIA_SURFACE_INFO_KHR} * {cl_image_info_TYPE} ** {CL_IMAGE_DX9_MEDIA_PLANE_KHR} - * {cl_event_info_TYPE} + * {cl_command_type_TYPE} ** {CL_COMMAND_ACQUIRE_DX9_MEDIA_SURFACES_KHR} ** {CL_COMMAND_RELEASE_DX9_MEDIA_SURFACES_KHR} * New Error Codes diff --git a/api/cl_khr_egl_event.asciidoc b/api/cl_khr_egl_event.asciidoc index 97293a7cc..106bb82ec 100644 --- a/api/cl_khr_egl_event.asciidoc +++ b/api/cl_khr_egl_event.asciidoc @@ -26,8 +26,7 @@ functionality of creating an EGL sync object from an OpenCL event object. === New Enums - * New Error Codes - ** {CL_INVALID_EGL_OBJECT_KHR} + * {cl_command_type_TYPE} ** {CL_COMMAND_EGL_FENCE_SYNC_OBJECT_KHR} === Issues @@ -57,13 +56,13 @@ context, and to reach into each such context. *RESOLVED* Use is limited to calls to acquire and release memory objects only. -- - . What is the desired behaviour for this extension when EGLSyncKHR is of a + . What is the desired behavior for this extension when EGLSyncKHR is of a type other than `EGL_SYNC_FENCE_KHR`? + -- *RESOLVED* This extension only requires support for `EGL_SYNC_FENCE_KHR`. Support of other types is an implementation choice, and will result in -CL_INVALID_EGL_OBJECT_KHR if unsupported. +{CL_INVALID_EGL_OBJECT_KHR} if unsupported. -- === Version History diff --git a/api/cl_khr_egl_image.asciidoc b/api/cl_khr_egl_image.asciidoc index d4e7f5fee..0d1b0df27 100644 --- a/api/cl_khr_egl_image.asciidoc +++ b/api/cl_khr_egl_image.asciidoc @@ -25,7 +25,7 @@ from from EGLImages. === New Enums - * {cl_event_info_TYPE} + * {cl_command_type_TYPE} ** {CL_COMMAND_ACQUIRE_EGL_OBJECTS_KHR} ** {CL_COMMAND_RELEASE_EGL_OBJECTS_KHR} * New Error Codes diff --git a/api/cl_khr_external_memory.asciidoc b/api/cl_khr_external_memory.asciidoc index 867d9a5f2..dbe5e6a95 100644 --- a/api/cl_khr_external_memory.asciidoc +++ b/api/cl_khr_external_memory.asciidoc @@ -81,7 +81,7 @@ TODO ** {CL_MEM_DEVICE_HANDLE_LIST_KHR} ** {CL_MEM_DEVICE_HANDLE_LIST_END_KHR} * Return values from from {clGetEventInfo} when _param_name_ is - {CL_EVENT_COMMAND_TYPE}: + {cl_command_type_TYPE}: ** {CL_COMMAND_ACQUIRE_EXTERNAL_MEM_OBJECTS_KHR} ** {CL_COMMAND_RELEASE_EXTERNAL_MEM_OBJECTS_KHR} diff --git a/api/cl_khr_gl_sharing.asciidoc b/api/cl_khr_gl_sharing.asciidoc index 94a1a0004..237d96511 100644 --- a/api/cl_khr_gl_sharing.asciidoc +++ b/api/cl_khr_gl_sharing.asciidoc @@ -63,8 +63,6 @@ and buffer object images with OpenCL is required by this extension. === New Enums - * New Error Codes - ** {CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR} * {cl_gl_context_info_TYPE} ** {CL_CURRENT_DEVICE_FOR_GL_CONTEXT_KHR} ** {CL_DEVICES_FOR_GL_CONTEXT_KHR} @@ -86,7 +84,8 @@ and buffer object images with OpenCL is required by this extension. * {cl_gl_texture_info_TYPE} ** {CL_GL_TEXTURE_TARGET} ** {CL_GL_MIPMAP_LEVEL} - + * New Error Codes + ** {CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR} === Issues diff --git a/api/cl_khr_semaphore.asciidoc b/api/cl_khr_semaphore.asciidoc index ec578bc37..1d3af4634 100644 --- a/api/cl_khr_semaphore.asciidoc +++ b/api/cl_khr_semaphore.asciidoc @@ -90,7 +90,7 @@ In particular, this extension defines: ** {CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR} ** {CL_SEMAPHORE_DEVICE_HANDLE_LIST_END_KHR} // TODO these are not described anywhere in the extension spec document - * New return values from {clGetEventInfo} + * {cl_command_type_TYPE} ** {CL_COMMAND_SEMAPHORE_WAIT_KHR} ** {CL_COMMAND_SEMAPHORE_SIGNAL_KHR} * New Error Codes From 2515b1d01e17d60bade621a90aae67a8fd124779 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Tue, 2 Apr 2024 08:53:46 -0700 Subject: [PATCH 23/71] add a few missing enums to the XML file (#1118) * add a few missing enums to the XML file use the feature dictionaries in a lot more places * add versioning macros to OpenCL 3.0 * update dictionary generation for API macros * add missing anchors --- OpenCL_C.txt | 761 +++++++++--------- api/cl_khr_extended_versioning.asciidoc | 20 +- api/opencl_architecture.asciidoc | 12 +- c/dictionary.asciidoc | 5 + c/footnotes.asciidoc | 14 +- env/common_properties.asciidoc | 66 +- env/extensions.asciidoc | 4 +- env/image_addressing_and_filtering.asciidoc | 138 ++-- env/numerical_compliance.asciidoc | 8 +- ext/introduction.asciidoc | 22 +- ...GetExtensionFunctionAddressForPlatform.txt | 4 +- scripts/gen_dictionaries.py | 62 ++ xml/cl.xml | 24 + 13 files changed, 617 insertions(+), 523 deletions(-) create mode 100644 c/dictionary.asciidoc diff --git a/OpenCL_C.txt b/OpenCL_C.txt index bcab4229f..dd372a8bb 100644 --- a/OpenCL_C.txt +++ b/OpenCL_C.txt @@ -33,6 +33,9 @@ include::config/attribs.txt[] // Attributes that are shared by OpenCL specifications. include::config/opencl.asciidoc[] +// Formatting and links for API functions and enums. +include::c/dictionary.asciidoc[] + // Feature Dictionary include::c/feature-dictionary.asciidoc[] @@ -1095,7 +1098,7 @@ The `image2d_t`, `image3d_t`, `image2d_array_t`, `image1d_t`, `image1d_buffer_t`, `image1d_array_t`, `image2d_depth_t`, `image2d_array_depth_t` and `sampler_t` types are only defined if the device supports images, i.e. the value of the <>) is `CL_TRUE`. +{CL_DEVICE_IMAGE_SUPPORT} device query>>) is {CL_TRUE}. If this is the case then an OpenCL C 3.0 or newer compiler must also define the {opencl_c_images} feature macro. ==== @@ -2751,7 +2754,7 @@ be declared in program scope or in the outermost kernel scope or inside Each argument to a kernel that is a pointer to the `{constant}` address space is counted separately towards the maximum number of such arguments, defined as the value of the <>. +{CL_DEVICE_MAX_CONSTANT_ARGS} device query>>. ==== It is illegal to write to a variable in the constant address space and will @@ -3628,7 +3631,7 @@ qualifier: ==== Kernel functions with variables declared inside the function with the `{local}` or `local` qualifier can be called by the host using appropriate -APIs such as *clEnqueueNDRangeKernel*. +APIs such as {clEnqueueNDRangeKernel}. ==== The `{kernel}` and `kernel` names are reserved for use as functions @@ -3712,20 +3715,20 @@ concerns or some preference for divisibility by 2. The optional `+__attribute__((work_group_size_hint(X, Y, Z)))+` is a hint to the compiler and is intended to specify the work-group size that may be used i.e. value most likely to be specified by the _local_work_size_ argument to -*clEnqueueNDRangeKernel*. +{clEnqueueNDRangeKernel}. For example, the `+__attribute__((work_group_size_hint(1, 1, 1)))+` is a hint to the compiler that the kernel will most likely be executed with a work-group size of 1. The optional `+__attribute__((reqd_work_group_size(X, Y, Z)))+` is the work-group size that must be used as the _local_work_size_ argument to -*clEnqueueNDRangeKernel*. +{clEnqueueNDRangeKernel}. This allows the compiler to optimize the generated code appropriately for this kernel. -If `Z` is one, the _work_dim_ argument to *clEnqueueNDRangeKernel* can be 2 +If `Z` is one, the _work_dim_ argument to {clEnqueueNDRangeKernel} can be 2 or 3. -If `Y` and `Z` are one, the _work_dim_ argument to *clEnqueueNDRangeKernel* +If `Y` and `Z` are one, the _work_dim_ argument to {clEnqueueNDRangeKernel} can be 1, 2 or 3. -- @@ -3927,7 +3930,7 @@ supported with `{global}` address space qualifier. ifdef::cl_khr_initialize_memory[] . [[restrictions-initialize-memory]] The following restriction only applies if the `<>` extension is supported: + - If the context is created with `CL_CONTEXT_MEMORY_INITIALIZE_KHR`, + If the context is created with {CL_CONTEXT_MEMORY_INITIALIZE_KHR}, appropriate memory locations as specified by the bit-field are initialized with zeroes, prior to the start of execution of any kernel. The driver chooses when, prior to kernel execution, the initialization of @@ -4014,7 +4017,7 @@ The following predefined macro names are available. `+__OPENCL_C_VERSION__+` :: Substitutes an integer reflecting the OpenCL C version specified by the `-cl-std` build option (see <>) to - *clBuildProgram* or *clCompileProgram*. + {clBuildProgram} or {clCompileProgram}. If the `-cl-std` build option is not specified, the highest OpenCL C 1.x language version supported by each device is used as the version of OpenCL C when compiling the program for each device. @@ -4031,7 +4034,7 @@ The following predefined macro names are available. or a big endian architecture (an integer constant of 1 if device is little endian and is undefined otherwise). Also refer to the value of the <>. + {CL_DEVICE_ENDIAN_LITTLE} device query>>. `+__kernel_exec(X, typen)+` (and `kernel_exec(X, typen)`) :: is defined as: @@ -4047,13 +4050,13 @@ __kernel __attribute__((work_group_size_hint(X, 1, 1))) \ This is an integer constant of 1 if images are supported and is undefined otherwise. Also refer to the value of the <> and the {opencl_c_images} + {CL_DEVICE_IMAGE_SUPPORT} device query>> and the {opencl_c_images} feature. `+__FAST_RELAXED_MATH__+` :: Used to determine if the `-cl-fast-relaxed-math` optimization option is - specified in build options given to *clBuildProgram* or - *clCompileProgram*. + specified in build options given to {clBuildProgram} or + {clCompileProgram}. This is an integer constant of 1 if the `-cl-fast-relaxed-math` build option is specified and is undefined otherwise. @@ -4913,7 +4916,7 @@ that operate on mixed scalar and vector types, however. -- The following table describes the list of built-in work-item functions that can be used to query the number of dimensions, the global and local work -size specified to *clEnqueueNDRangeKernel*, and the global and local +size specified to {clEnqueueNDRangeKernel}, and the global and local identifier of each work-item when this kernel is being executed on a device. [[table-work-item-functions]] @@ -4924,12 +4927,12 @@ identifier of each work-item when this kernel is being executed on a device. | uint *get_work_dim*() | Returns the number of dimensions in use. This is the value given to the _work_dim_ argument specified in - *clEnqueueNDRangeKernel*. + {clEnqueueNDRangeKernel}. | size_t *get_global_size*(uint _dimindx_) | Returns the number of global work-items specified for dimension identified by _dimindx_. This value is given by the _global_work_size_ argument to - *clEnqueueNDRangeKernel*. + {clEnqueueNDRangeKernel}. Valid values of _dimindx_ are 0 to *get_work_dim*() - 1. For other values of _dimindx_, *get_global_size*() returns 1. @@ -4945,7 +4948,7 @@ identifier of each work-item when this kernel is being executed on a device. | Returns the number of local work-items specified in dimension identified by _dimindx_. This value is at most the value given by the _local_work_size_ - argument to *clEnqueueNDRangeKernel* if _local_work_size_ is not + argument to {clEnqueueNDRangeKernel} if _local_work_size_ is not `NULL`; otherwise the OpenCL implementation chooses an appropriate _local_work_size_ value which is returned by this function. If the kernel is executed with a non-uniform work-group size @@ -4964,7 +4967,7 @@ identifier of each work-item when this kernel is being executed on a device. the number of local work-items in each of the work-groups that make up the uniform region of the global range in the dimension identified by _dimindx_. - If the _local_work_size_ argument to *clEnqueueNDRangeKernel* is not + If the _local_work_size_ argument to {clEnqueueNDRangeKernel} is not `NULL`, this value will match the value specified in _local_work_size_[_dimindx_]. If _local_work_size_ is `NULL`, this value will match the local size @@ -4995,7 +4998,7 @@ identifier of each work-item when this kernel is being executed on a device. For other values, *get_group_id*() returns 0. | size_t *get_global_offset*(uint _dimindx_) | *get_global_offset* returns the offset values specified in - _global_work_offset_ argument to *clEnqueueNDRangeKernel*. + _global_work_offset_ argument to {clEnqueueNDRangeKernel}. Valid values of _dimindx_ are 0 to *get_work_dim*() - 1. For other values, *get_global_offset*() returns 0. @@ -5070,7 +5073,7 @@ sub-group when this kernel is being executed on a device. This number will be constant for the duration of a work-group's execution. If the kernel is executed with a non-uniform work-group size - (i.e. the global_work_size values specified to *clEnqueueNDRangeKernel* + (i.e. the global_work_size values specified to {clEnqueueNDRangeKernel} are not evenly divisible by the local_work_size values for any dimension, calls to this built-in from some work-groups may return different values than calls to this built-in from other work-groups. @@ -5087,7 +5090,7 @@ sub-group when this kernel is being executed on a device. | *get_sub_group_id* returns the sub-group ID which is a number from 0 .. *get_num_sub_groups*() - 1. - For *clEnqueueTask*, this returns 0. + For {clEnqueueTask}, this returns 0. | uint *get_sub_group_local_id*() | Returns the unique work-item ID within the current sub-group. @@ -5811,16 +5814,16 @@ the application. [cols=",",options="header",] |==== | Macro in OpenCL Language | Macro for application -| `FLT_DIG` | `CL_FLT_DIG` -| `FLT_MANT_DIG` | `CL_FLT_MANT_DIG` -| `FLT_MAX_10_EXP` | `CL_FLT_MAX_10_EXP` -| `FLT_MAX_EXP` | `CL_FLT_MAX_EXP` -| `FLT_MIN_10_EXP` | `CL_FLT_MIN_10_EXP` -| `FLT_MIN_EXP` | `CL_FLT_MIN_EXP` -| `FLT_RADIX` | `CL_FLT_RADIX` -| `FLT_MAX` | `CL_FLT_MAX` -| `FLT_MIN` | `CL_FLT_MIN` -| `FLT_EPSILSON` | `CL_FLT_EPSILON` +| `FLT_DIG` | {CL_FLT_DIG} +| `FLT_MANT_DIG` | {CL_FLT_MANT_DIG} +| `FLT_MAX_10_EXP` | {CL_FLT_MAX_10_EXP} +| `FLT_MAX_EXP` | {CL_FLT_MAX_EXP} +| `FLT_MIN_10_EXP` | {CL_FLT_MIN_10_EXP} +| `FLT_MIN_EXP` | {CL_FLT_MIN_EXP} +| `FLT_RADIX` | {CL_FLT_RADIX} +| `FLT_MAX` | {CL_FLT_MAX} +| `FLT_MIN` | {CL_FLT_MIN} +| `FLT_EPSILSON` | {CL_FLT_EPSILON} |==== The following macros shall expand to integer constant expressions whose @@ -5883,15 +5886,15 @@ the application. [cols=",",options="header",] |==== | Macro in OpenCL Language | Macro for application -| `DBL_DIG` | `CL_DBL_DIG` -| `DBL_MANT_DIG` | `CL_DBL_MANT_DIG` -| `DBL_MAX_10_EXP` | `CL_DBL_MAX_10_EXP` -| `DBL_MAX_EXP` | `CL_DBL_MAX_EXP` -| `DBL_MIN_10_EXP` | `CL_DBL_MIN_10_EXP` -| `DBL_MIN_EXP` | `CL_DBL_MIN_EXP` -| `DBL_MAX` | `CL_DBL_MAX` -| `DBL_MIN` | `CL_DBL_MIN` -| `DBL_EPSILSON` | `CL_DBL_EPSILON` +| `DBL_DIG` | {CL_DBL_DIG} +| `DBL_MANT_DIG` | {CL_DBL_MANT_DIG} +| `DBL_MAX_10_EXP` | {CL_DBL_MAX_10_EXP} +| `DBL_MAX_EXP` | {CL_DBL_MAX_EXP} +| `DBL_MIN_10_EXP` | {CL_DBL_MIN_10_EXP} +| `DBL_MIN_EXP` | {CL_DBL_MIN_EXP} +| `DBL_MAX` | {CL_DBL_MAX} +| `DBL_MIN` | {CL_DBL_MIN} +| `DBL_EPSILSON` | {CL_DBL_EPSILON} |==== The following constants are also available. @@ -5952,16 +5955,16 @@ the application. [cols=",",options="header",] |==== | Macro in OpenCL Language | Macro for application -| `HALF_DIG` | `CL_HALF_DIG` -| `HALF_MANT_DIG` | `CL_HALF_MANT_DIG` -| `HALF_MAX_10_EXP` | `CL_HALF_MAX_10_EXP` -| `HALF_MAX_EXP` | `CL_HALF_MAX_EXP` -| `HALF_MIN_10_EXP` | `CL_HALF_MIN_10_EXP` -| `HALF_MIN_EXP` | `CL_HALF_MIN_EXP` -| `HALF_RADIX` | `CL_HALF_RADIX` -| `HALF_MAX` | `CL_HALF_MAX` -| `HALF_MIN` | `CL_HALF_MIN` -| `HALF_EPSILSON` | `CL_HALF_EPSILON` +| `HALF_DIG` | {CL_HALF_DIG} +| `HALF_MANT_DIG` | {CL_HALF_MANT_DIG} +| `HALF_MAX_10_EXP` | {CL_HALF_MAX_10_EXP} +| `HALF_MAX_EXP` | {CL_HALF_MAX_EXP} +| `HALF_MIN_10_EXP` | {CL_HALF_MIN_10_EXP} +| `HALF_MIN_EXP` | {CL_HALF_MIN_EXP} +| `HALF_RADIX` | {CL_HALF_RADIX} +| `HALF_MAX` | {CL_HALF_MAX} +| `HALF_MIN` | {CL_HALF_MIN} +| `HALF_EPSILSON` | {CL_HALF_EPSILON} |==== The following constants are also available. @@ -6352,21 +6355,21 @@ the application. [cols=",",options="header",] |==== | Macro in OpenCL Language | Macro for application -| `CHAR_BIT` | `CL_CHAR_BIT` -| `CHAR_MAX` | `CL_CHAR_MAX` -| `CHAR_MIN` | `CL_CHAR_MIN` -| `INT_MAX` | `CL_INT_MAX` -| `INT_MIN` | `CL_INT_MIN` -| `LONG_MAX` | `CL_LONG_MAX` -| `LONG_MIN` | `CL_LONG_MIN` -| `SCHAR_MAX` | `CL_SCHAR_MAX` -| `SCHAR_MIN` | `CL_SCHAR_MIN` -| `SHRT_MAX` | `CL_SHRT_MAX` -| `SHRT_MIN` | `CL_SHRT_MIN` -| `UCHAR_MAX` | `CL_UCHAR_MAX` -| `USHRT_MAX` | `CL_USHRT_MAX` -| `UINT_MAX` | `CL_UINT_MAX` -| `ULONG_MAX` | `CL_ULONG_MAX` +| `CHAR_BIT` | {CL_CHAR_BIT} +| `CHAR_MAX` | {CL_CHAR_MAX} +| `CHAR_MIN` | {CL_CHAR_MIN} +| `INT_MAX` | {CL_INT_MAX} +| `INT_MIN` | {CL_INT_MIN} +| `LONG_MAX` | {CL_LONG_MAX} +| `LONG_MIN` | {CL_LONG_MIN} +| `SCHAR_MAX` | {CL_SCHAR_MAX} +| `SCHAR_MIN` | {CL_SCHAR_MIN} +| `SHRT_MAX` | {CL_SHRT_MAX} +| `SHRT_MIN` | {CL_SHRT_MIN} +| `UCHAR_MAX` | {CL_UCHAR_MAX} +| `USHRT_MAX` | {CL_USHRT_MAX} +| `UINT_MAX` | {CL_UINT_MAX} +| `ULONG_MAX` | {CL_ULONG_MAX} |==== -- @@ -9525,7 +9528,7 @@ The OpenCL C programming language implements the *printf* function. When the event that is associated with a particular kernel invocation is completed, the output of all printf() calls executed by this kernel invocation is flushed to the implementation-defined output stream. -Calling *clFinish* on a command-queue flushes all pending output by printf +Calling {clFinish} on a command-queue flushes all pending output by printf in previously enqueued and completed commands to the implementation-defined output stream. In the case that printf is executed from multiple work-items concurrently, @@ -9906,7 +9909,7 @@ kernel void my_kernel(global char *s, ... ) a `float` argument to a `double` only if the `double` data type is supported. Refer to the value of the <>. + {CL_DEVICE_DOUBLE_FP_CONFIG} device query>>. If the `double` data type is not supported, the argument will be a `float` instead of a `double`. * For the embedded profile, the *l* length modifier is supported only if @@ -9929,7 +9932,7 @@ from and/or write to specific locations in the image. Support for the image built-in functions is optional. If a device supports images then the value of the <>) is `CL_TRUE` and the OpenCL C +{CL_DEVICE_IMAGE_SUPPORT} device query>>) is {CL_TRUE} and the OpenCL C compiler for that device must define the `+__IMAGE_SUPPORT__+` macro. A compiler for OpenCL C 3.0 or newer for that device must also support the {opencl_c_images} feature. @@ -9963,7 +9966,7 @@ component. The image read functions take a sampler argument. The sampler can be passed as an argument to the kernel using -*clSetKernelArg*, or can be declared in the outermost scope of kernel +{clSetKernelArg}, or can be declared in the outermost scope of kernel functions, or it can be a constant variable of type `sampler_t` declared in the program source. @@ -10005,8 +10008,8 @@ Note that samplers declared using the `constant` qualifier are not counted towards the maximum number of arguments pointing to the constant address space or the maximum size of the `constant` address space allowed per device (i.e. the value of the <> and <> device queries). +{CL_DEVICE_MAX_CONSTANT_ARGS}>> and <> device queries). The sampler fields are described in the following table. @@ -10082,7 +10085,7 @@ const sampler_t samplerA = CLK_NORMALIZED_COORDS_TRUE | addressing mode and a nearest filter. The maximum number of samplers that can be declared in a kernel can be -queried using the `CL_DEVICE_MAX_SAMPLERS` token in *clGetDeviceInfo*. +queried using the {CL_DEVICE_MAX_SAMPLERS} token in {clGetDeviceInfo}. -- @@ -10094,13 +10097,13 @@ image coordinates return the border color. The border color selected depends on the image channel order and can be one of the following values: - * If the image channel order is `CL_A`, `CL_INTENSITY`, `CL_Rx`, - `CL_RA`, `CL_RGx`, `CL_RGBx`, `CL_sRGBx`, `CL_ARGB`, `CL_BGRA`, - `CL_ABGR`, `CL_RGBA`, `CL_sRGBA` or `CL_sBGRA`, the border color is + * If the image channel order is {CL_A}, {CL_INTENSITY}, {CL_Rx}, + {CL_RA}, {CL_RGx}, {CL_RGBx}, {CL_sRGBx}, {CL_ARGB}, {CL_BGRA}, + {CL_ABGR}, {CL_RGBA}, {CL_sRGBA} or {CL_sBGRA}, the border color is `(0.0f, 0.0f, 0.0f, 0.0f)`. - * If the image channel order is `CL_R`, `CL_RG`, `CL_RGB`, or - `CL_LUMINANCE`, the border color is `(0.0f, 0.0f, 0.0f, 1.0f)`. - * If the image channel order is `CL_DEPTH`, the border value is `0.0f`. + * If the image channel order is {CL_R}, {CL_RG}, {CL_RGB}, or + {CL_LUMINANCE}, the border color is `(0.0f, 0.0f, 0.0f, 1.0f)`. + * If the image channel order is {CL_DEPTH}, the border value is `0.0f`. [[srgb-images]] @@ -10148,15 +10151,15 @@ endif::cl_khr_mipmap_image[] *read_imagef* returns floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of - the pre-defined packed formats or `CL_UNORM_INT8`, or - `CL_UNORM_INT16`. + the pre-defined packed formats or {CL_UNORM_INT8}, or + {CL_UNORM_INT16}. *read_imagef* returns floating-point values in the range [-1.0, 1.0] for image objects created with _image_channel_data_type_ set to - `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imagef* returns floating-point values for image objects created - with _image_channel_data_type_ set to `CL_HALF_FLOAT` or `CL_FLOAT`. + with _image_channel_data_type_ set to {CL_HALF_FLOAT} or {CL_FLOAT}. The *read_imagef* calls that take integer coordinates must use a sampler with filter mode set to `CLK_FILTER_NEAREST`, normalized @@ -10179,14 +10182,14 @@ ifdef::cl_khr_fp16[] *read_imageh* returns half-precision floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of the pre-defined packed - formats or `CL_UNORM_INT8`, or `CL_UNORM_INT16`. + formats or {CL_UNORM_INT8}, or {CL_UNORM_INT16}. *read_imageh* returns half-precision floating-point values in the range [-1.0, 1.0] for image objects created with - _image_channel_data_type_ set to `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + _image_channel_data_type_ set to {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imageh* returns half-precision floating-point values for image - objects created with _image_channel_data_type_ set to `CL_HALF_FLOAT`. + objects created with _image_channel_data_type_ set to {CL_HALF_FLOAT}. The *read_imageh* calls that take integer coordinates must use a sampler with filter mode set to `CLK_FILTER_NEAREST`, normalized @@ -10220,9 +10223,9 @@ endif::cl_khr_fp16[] *read_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_SIGNED_INT8`, + - `CL_SIGNED_INT16` and + - `CL_SIGNED_INT32`. + {CL_SIGNED_INT8}, + + {CL_SIGNED_INT16} and + + {CL_SIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imagei* are undefined. @@ -10230,9 +10233,9 @@ endif::cl_khr_fp16[] *read_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_UNSIGNED_INT8`, + - `CL_UNSIGNED_INT16` and + - `CL_UNSIGNED_INT32`. + {CL_UNSIGNED_INT8}, + + {CL_UNSIGNED_INT16} and + + {CL_UNSIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imageui* are undefined. @@ -10257,15 +10260,15 @@ endif::cl_khr_fp16[] *read_imagef* returns floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of - the pre-defined packed formats or `CL_UNORM_INT8`, or - `CL_UNORM_INT16`. + the pre-defined packed formats or {CL_UNORM_INT8}, or + {CL_UNORM_INT16}. *read_imagef* returns floating-point values in the range [-1.0, 1.0] for image objects created with _image_channel_data_type_ set to - `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imagef* returns floating-point values for image objects created - with _image_channel_data_type_ set to `CL_HALF_FLOAT` or `CL_FLOAT`. + with _image_channel_data_type_ set to {CL_HALF_FLOAT} or {CL_FLOAT}. The *read_imagef* calls that take integer coordinates must use a sampler with filter mode set to `CLK_FILTER_NEAREST`, normalized @@ -10289,14 +10292,14 @@ ifdef::cl_khr_fp16[] *read_imageh* returns half-precision floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of the pre-defined packed formats - or `CL_UNORM_INT8`, or `CL_UNORM_INT16`. + or {CL_UNORM_INT8}, or {CL_UNORM_INT16}. *read_imageh* returns half-precision floating-point values in the range [-1.0, 1.0] for image objects created with - _image_channel_data_type_ set to `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + _image_channel_data_type_ set to {CL_SNORM_INT8}, or {CL_SNORM_INT16}. **read_imageh** returns half-precision floating-point values for image - objects created with _image_channel_data_type_ set to `CL_HALF_FLOAT`. + objects created with _image_channel_data_type_ set to {CL_HALF_FLOAT}. The *read_imageh* calls that take integer coordinates must use a sampler with filter mode set to `CLK_FILTER_NEAREST`, normalized @@ -10331,9 +10334,9 @@ endif::cl_khr_fp16[] *read_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_SIGNED_INT8`, + - `CL_SIGNED_INT16` and + - `CL_SIGNED_INT32`. + {CL_SIGNED_INT8}, + + {CL_SIGNED_INT16} and + + {CL_SIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imagei* are undefined. @@ -10341,9 +10344,9 @@ endif::cl_khr_fp16[] *read_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_UNSIGNED_INT8`, + - `CL_UNSIGNED_INT16` and + - `CL_UNSIGNED_INT32`. + {CL_UNSIGNED_INT8}, + + {CL_UNSIGNED_INT16} and + + {CL_UNSIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imageui* are undefined. @@ -10367,15 +10370,15 @@ endif::cl_khr_fp16[] *read_imagef* returns floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of - the pre-defined packed formats or `CL_UNORM_INT8`, or - `CL_UNORM_INT16`. + the pre-defined packed formats or {CL_UNORM_INT8}, or + {CL_UNORM_INT16}. *read_imagef* returns floating-point values in the range [-1.0, 1.0] for image objects created with _image_channel_data_type_ set to - `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imagef* returns floating-point values for image objects created - with _image_channel_data_type_ set to `CL_HALF_FLOAT` or `CL_FLOAT`. + with _image_channel_data_type_ set to {CL_HALF_FLOAT} or {CL_FLOAT}. The *read_imagef* calls that take integer coordinates must use a sampler with filter mode set to `CLK_FILTER_NEAREST`, normalized @@ -10398,14 +10401,14 @@ ifdef::cl_khr_fp16[] *read_imageh* returns half-precision floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of the pre-defined packed formats - or `CL_UNORM_INT8`, or `CL_UNORM_INT16`. + or {CL_UNORM_INT8}, or {CL_UNORM_INT16}. *read_imageh* returns half-precision floating-point values in the range [-1.0, 1.0] for image objects created with - _image_channel_data_type_ set to `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + _image_channel_data_type_ set to {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imageh* returns half-precision floating-point values for image - objects created with _image_channel_data_type_ set to `CL_HALF_FLOAT`. + objects created with _image_channel_data_type_ set to {CL_HALF_FLOAT}. The *read_imageh* calls that take integer coordinates must use a sampler with filter mode set to `CLK_FILTER_NEAREST`, normalized @@ -10439,9 +10442,9 @@ endif::cl_khr_fp16[] *read_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_SIGNED_INT8`, + - `CL_SIGNED_INT16` and + - `CL_SIGNED_INT32`. + {CL_SIGNED_INT8}, + + {CL_SIGNED_INT16} and + + {CL_SIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imagei* are undefined. @@ -10449,9 +10452,9 @@ endif::cl_khr_fp16[] *read_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_UNSIGNED_INT8`, + - `CL_UNSIGNED_INT16` and + - `CL_UNSIGNED_INT32`. + {CL_UNSIGNED_INT8}, + + {CL_UNSIGNED_INT16} and + + {CL_UNSIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imageui* are undefined. @@ -10475,15 +10478,15 @@ endif::cl_khr_fp16[] *read_imagef* returns floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of - the pre-defined packed formats or `CL_UNORM_INT8`, or - `CL_UNORM_INT16`. + the pre-defined packed formats or {CL_UNORM_INT8}, or + {CL_UNORM_INT16}. *read_imagef* returns floating-point values in the range [-1.0, 1.0] for image objects created with _image_channel_data_type_ set to - `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imagef* returns floating-point values for image objects created - with _image_channel_data_type_ set to `CL_HALF_FLOAT` or `CL_FLOAT`. + with _image_channel_data_type_ set to {CL_HALF_FLOAT} or {CL_FLOAT}. The *read_imagef* calls that take integer coordinates must use a sampler with filter mode set to `CLK_FILTER_NEAREST`, normalized @@ -10508,14 +10511,14 @@ ifdef::cl_khr_fp16[] *read_imageh* returns half-precision floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of the pre-defined packed formats - or `CL_UNORM_INT8`, or `CL_UNORM_INT16`. + or {CL_UNORM_INT8}, or {CL_UNORM_INT16}. *read_imageh* returns half-precision floating-point values in the range [-1.0, 1.0] for image objects created with - _image_channel_data_type_ set to `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + _image_channel_data_type_ set to {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imageh* returns half-precision floating-point values for image - objects created with _image_channel_data_type_ set to `CL_HALF_FLOAT`. + objects created with _image_channel_data_type_ set to {CL_HALF_FLOAT}. The *read_imageh* calls that take integer coordinates must use a sampler with filter mode set to `CLK_FILTER_NEAREST`, normalized @@ -10549,9 +10552,9 @@ endif::cl_khr_fp16[] *read_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_SIGNED_INT8`, + - `CL_SIGNED_INT16` and + - `CL_SIGNED_INT32`. + {CL_SIGNED_INT8}, + + {CL_SIGNED_INT16} and + + {CL_SIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imagei* are undefined. @@ -10559,9 +10562,9 @@ endif::cl_khr_fp16[] *read_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_UNSIGNED_INT8`, + - `CL_UNSIGNED_INT16` and + - `CL_UNSIGNED_INT32`. + {CL_UNSIGNED_INT8}, + + {CL_UNSIGNED_INT16} and + + {CL_UNSIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imageui* are undefined. @@ -10587,15 +10590,15 @@ endif::cl_khr_fp16[] *read_imagef* returns floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of - the pre-defined packed formats or `CL_UNORM_INT8`, or - `CL_UNORM_INT16`. + the pre-defined packed formats or {CL_UNORM_INT8}, or + {CL_UNORM_INT16}. *read_imagef* returns floating-point values in the range [-1.0, 1.0] for image objects created with _image_channel_data_type_ set to - `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imagef* returns floating-point values for image objects created - with _image_channel_data_type_ set to `CL_HALF_FLOAT` or `CL_FLOAT`. + with _image_channel_data_type_ set to {CL_HALF_FLOAT} or {CL_FLOAT}. The *read_imagef* calls that take integer coordinates must use a sampler with filter mode set to `CLK_FILTER_NEAREST`, normalized @@ -10620,14 +10623,14 @@ ifdef::cl_khr_fp16[] *read_imageh* returns half-precision floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of the pre-defined packed formats - or `CL_UNORM_INT8`, or `CL_UNORM_INT16`. + or {CL_UNORM_INT8}, or {CL_UNORM_INT16}. *read_imageh* returns half-precision floating-point values in the range [-1.0, 1.0] for image objects created with - _image_channel_data_type_ set to `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + _image_channel_data_type_ set to {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imageh* returns half-precision floating-point values for image - objects created with _image_channel_data_type_ set to `CL_HALF_FLOAT`. + objects created with _image_channel_data_type_ set to {CL_HALF_FLOAT}. The *read_imageh* calls that take integer coordinates must use a sampler with filter mode set to `CLK_FILTER_NEAREST`, normalized @@ -10661,9 +10664,9 @@ endif::cl_khr_fp16[] *read_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_SIGNED_INT8`, + - `CL_SIGNED_INT16` and + - `CL_SIGNED_INT32`. + {CL_SIGNED_INT8}, + + {CL_SIGNED_INT16} and + + {CL_SIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imagei* are undefined. @@ -10671,9 +10674,9 @@ endif::cl_khr_fp16[] *read_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_UNSIGNED_INT8`, + - `CL_UNSIGNED_INT16` and + - `CL_UNSIGNED_INT32`. + {CL_UNSIGNED_INT8}, + + {CL_UNSIGNED_INT16} and + + {CL_UNSIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imageui* are undefined. @@ -10699,10 +10702,10 @@ endif::cl_khr_fp16[] *read_imagef* returns a floating-point value in the range [0.0, 1.0] for depth image objects created with _image_channel_data_type_ set to - `CL_UNORM_INT16` or `CL_UNORM_INT24`. + {CL_UNORM_INT16} or {CL_UNORM_INT24}. *read_imagef* returns a floating-point value for depth image objects - created with _image_channel_data_type_ set to `CL_FLOAT`. + created with _image_channel_data_type_ set to {CL_FLOAT}. The *read_imagef* calls that take integer coordinates must use a sampler with filter mode set to `CLK_FILTER_NEAREST`, normalized @@ -10726,10 +10729,10 @@ endif::cl_khr_fp16[] *read_imagef* returns a floating-point value in the range [0.0, 1.0] for depth image objects created with _image_channel_data_type_ set to - `CL_UNORM_INT16` or `CL_UNORM_INT24`. + {CL_UNORM_INT16} or {CL_UNORM_INT24}. *read_imagef* returns a floating-point value for depth image objects - created with _image_channel_data_type_ set to `CL_FLOAT`. + created with _image_channel_data_type_ set to {CL_FLOAT}. The *read_imagef* calls that take integer coordinates must use a sampler with filter mode set to `CLK_FILTER_NEAREST`, normalized @@ -11062,12 +11065,12 @@ endif::cl_khr_mipmap_image[] ifdef::cl_khr_mipmap_image[] NOTE: If the `<>` extension macro is supported, -`CL_SAMPLER_NORMALIZED_COORDS` must be `CL_TRUE` for built-in functions +{CL_SAMPLER_NORMALIZED_COORDS} must be {CL_TRUE} for built-in functions described in the table above that read from a mipmapped image; otherwise behavior is undefined. The value specified in the _lod_ argument is clamped to the minimum of (actual number of mip levels - 1) in the image or the value specified for -`CL_SAMPLER_LOD_MAX`. +{CL_SAMPLER_LOD_MAX}. endif::cl_khr_mipmap_image[] @@ -11087,7 +11090,7 @@ integer coordinates and a sampler with filter mode set to `CLK_FILTER_NEAREST`, normalized coordinates set to `CLK_NORMALIZED_COORDS_FALSE` and addressing mode to `CLK_ADDRESS_NONE`. There is one exception when the _image_channel_data_type_ is a floating-point -type (such as `CL_FLOAT`). +type (such as {CL_FLOAT}). In this exceptional case, when channel data values are denormalized, the sampler-less image read function may return the denormalized data, while the image read function with a sampler argument may flush the denormalized @@ -11107,15 +11110,15 @@ For sampler-less read functions this may be `read_only` or `read_write`. *read_imagef* returns floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of - the pre-defined packed formats or `CL_UNORM_INT8`, or - `CL_UNORM_INT16`. + the pre-defined packed formats or {CL_UNORM_INT8}, or + {CL_UNORM_INT16}. *read_imagef* returns floating-point values in the range [-1.0, 1.0] for image objects created with _image_channel_data_type_ set to - `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imagef* returns floating-point values for image objects created - with _image_channel_data_type_ set to `CL_HALF_FLOAT` or `CL_FLOAT`. + with _image_channel_data_type_ set to {CL_HALF_FLOAT} or {CL_FLOAT}. Values returned by *read_imagef* for image objects with _image_channel_data_type_ values not specified in the description @@ -11129,14 +11132,14 @@ ifdef::cl_khr_fp16[] *read_imageh* returns half-precision floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of the pre-defined packed formats - or `CL_UNORM_INT8`, or `CL_UNORM_INT16`. + or {CL_UNORM_INT8}, or {CL_UNORM_INT16}. *read_imageh* returns half-precision floating-point values in the range [-1.0, 1.0] for image objects created with - _image_channel_data_type_ set to `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + _image_channel_data_type_ set to {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imageh* returns half-precision floating-point values for image - objects created with _image_channel_data_type_ set to `CL_HALF_FLOAT`. + objects created with _image_channel_data_type_ set to {CL_HALF_FLOAT}. Values returned by *read_imageh* for image objects with _image_channel_data_type_ values not specified in the description @@ -11158,9 +11161,9 @@ endif::cl_khr_fp16[] *read_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_SIGNED_INT8`, + - `CL_SIGNED_INT16` and + - `CL_SIGNED_INT32`. + {CL_SIGNED_INT8}, + + {CL_SIGNED_INT16} and + + {CL_SIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imagei* are undefined. @@ -11168,9 +11171,9 @@ endif::cl_khr_fp16[] *read_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_UNSIGNED_INT8`, + - `CL_UNSIGNED_INT16` and + - `CL_UNSIGNED_INT32`. + {CL_UNSIGNED_INT8}, + + {CL_UNSIGNED_INT16} and + + {CL_UNSIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imageui* are undefined. @@ -11182,15 +11185,15 @@ endif::cl_khr_fp16[] *read_imagef* returns floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of - the pre-defined packed formats or `CL_UNORM_INT8`, or - `CL_UNORM_INT16`. + the pre-defined packed formats or {CL_UNORM_INT8}, or + {CL_UNORM_INT16}. *read_imagef* returns floating-point values in the range [-1.0, 1.0] for image objects created with _image_channel_data_type_ set to - `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imagef* returns floating-point values for image objects created - with _image_channel_data_type_ set to `CL_HALF_FLOAT` or `CL_FLOAT`. + with _image_channel_data_type_ set to {CL_HALF_FLOAT} or {CL_FLOAT}. Values returned by *read_imagef* for image objects with _image_channel_data_type_ values not specified in the description are @@ -11205,14 +11208,14 @@ ifdef::cl_khr_fp16[] *read_imageh* returns half-precision floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of the pre-defined packed formats - or `CL_UNORM_INT8`, or `CL_UNORM_INT16`. + or {CL_UNORM_INT8}, or {CL_UNORM_INT16}. *read_imageh* returns half-precision floating-point values in the range [-1.0, 1.0] for image objects created with - _image_channel_data_type_ set to `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + _image_channel_data_type_ set to {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imageh* returns half-precision floating-point values for image - objects created with _image_channel_data_type_ set to `CL_HALF_FLOAT`. + objects created with _image_channel_data_type_ set to {CL_HALF_FLOAT}. Values returned by *read_imageh* for image objects with _image_channel_data_type_ values not specified in the description are @@ -11235,9 +11238,9 @@ endif::cl_khr_fp16[] *read_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_SIGNED_INT8`, + - `CL_SIGNED_INT16` and + - `CL_SIGNED_INT32`. + {CL_SIGNED_INT8}, + + {CL_SIGNED_INT16} and + + {CL_SIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imagei* are undefined. @@ -11245,9 +11248,9 @@ endif::cl_khr_fp16[] *read_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_UNSIGNED_INT8`, + - `CL_UNSIGNED_INT16` and + - `CL_UNSIGNED_INT32`. + {CL_UNSIGNED_INT8}, + + {CL_UNSIGNED_INT16} and + + {CL_UNSIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imageui* are undefined. @@ -11258,15 +11261,15 @@ endif::cl_khr_fp16[] *read_imagef* returns floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of - the pre-defined packed formats or `CL_UNORM_INT8`, or - `CL_UNORM_INT16`. + the pre-defined packed formats or {CL_UNORM_INT8}, or + {CL_UNORM_INT16}. *read_imagef* returns floating-point values in the range [-1.0, 1.0] for image objects created with _image_channel_data_type_ set to - `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imagef* returns floating-point values for image objects created - with _image_channel_data_type_ set to `CL_HALF_FLOAT` or `CL_FLOAT`. + with _image_channel_data_type_ set to {CL_HALF_FLOAT} or {CL_FLOAT}. Values returned by *read_imagef* for image objects with _image_channel_data_type_ values not specified in the description @@ -11280,14 +11283,14 @@ ifdef::cl_khr_fp16[] *read_imageh* returns half-precision floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of the pre-defined packed formats - or `CL_UNORM_INT8`, or `CL_UNORM_INT16`. + or {CL_UNORM_INT8}, or {CL_UNORM_INT16}. *read_imageh* returns half-precision floating-point values in the range [-1.0, 1.0] for image objects created with - _image_channel_data_type_ set to `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + _image_channel_data_type_ set to {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imageh* returns half-precision floating-point values for image - objects created with _image_channel_data_type_ set to `CL_HALF_FLOAT`. + objects created with _image_channel_data_type_ set to {CL_HALF_FLOAT}. Values returned by *read_imageh* for image objects with _image_channel_data_type_ values not specified in the description @@ -11309,9 +11312,9 @@ endif::cl_khr_fp16[] *read_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_SIGNED_INT8`, + - `CL_SIGNED_INT16` and + - `CL_SIGNED_INT32`. + {CL_SIGNED_INT8}, + + {CL_SIGNED_INT16} and + + {CL_SIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imagei* are undefined. @@ -11319,9 +11322,9 @@ endif::cl_khr_fp16[] *read_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_UNSIGNED_INT8`, + - `CL_UNSIGNED_INT16` and + - `CL_UNSIGNED_INT32`. + {CL_UNSIGNED_INT8}, + + {CL_UNSIGNED_INT16} and + + {CL_UNSIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imageui* are undefined. @@ -11333,15 +11336,15 @@ endif::cl_khr_fp16[] *read_imagef* returns floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of - the pre-defined packed formats or `CL_UNORM_INT8`, or - `CL_UNORM_INT16`. + the pre-defined packed formats or {CL_UNORM_INT8}, or + {CL_UNORM_INT16}. *read_imagef* returns floating-point values in the range [-1.0, 1.0] for image objects created with _image_channel_data_type_ set to - `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imagef* returns floating-point values for image objects created - with _image_channel_data_type_ set to `CL_HALF_FLOAT` or `CL_FLOAT`. + with _image_channel_data_type_ set to {CL_HALF_FLOAT} or {CL_FLOAT}. Values returned by *read_imagef* for image objects with _image_channel_data_type_ values not specified in the description @@ -11356,14 +11359,14 @@ ifdef::cl_khr_fp16[] *read_imageh* returns half-precision floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of the pre-defined packed formats - or `CL_UNORM_INT8`, or `CL_UNORM_INT16`. + or {CL_UNORM_INT8}, or {CL_UNORM_INT16}. *read_imageh* returns half-precision floating-point values in the range [-1.0, 1.0] for image objects created with - _image_channel_data_type_ set to `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + _image_channel_data_type_ set to {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imageh* returns half-precision floating-point values for image - objects created with _image_channel_data_type_ set to `CL_HALF_FLOAT`. + objects created with _image_channel_data_type_ set to {CL_HALF_FLOAT}. Values returned by *read_imageh* for image objects with _image_channel_data_type_ values not specified in the description @@ -11387,9 +11390,9 @@ endif::cl_khr_fp16[] *read_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_SIGNED_INT8`, + - `CL_SIGNED_INT16` and + - `CL_SIGNED_INT32`. + {CL_SIGNED_INT8}, + + {CL_SIGNED_INT16} and + + {CL_SIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imagei* are undefined. @@ -11397,9 +11400,9 @@ endif::cl_khr_fp16[] *read_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_UNSIGNED_INT8`, + - `CL_UNSIGNED_INT16` and + - `CL_UNSIGNED_INT32`. + {CL_UNSIGNED_INT8}, + + {CL_UNSIGNED_INT16} and + + {CL_UNSIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imageui* are undefined. @@ -11410,15 +11413,15 @@ endif::cl_khr_fp16[] *read_imagef* returns floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of - the pre-defined packed formats or `CL_UNORM_INT8`, or - `CL_UNORM_INT16`. + the pre-defined packed formats or {CL_UNORM_INT8}, or + {CL_UNORM_INT16}. *read_imagef* returns floating-point values in the range [-1.0, 1.0] for image objects created with _image_channel_data_type_ set to - `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imagef* returns floating-point values for image objects created - with _image_channel_data_type_ set to `CL_HALF_FLOAT` or `CL_FLOAT`. + with _image_channel_data_type_ set to {CL_HALF_FLOAT} or {CL_FLOAT}. Values returned by *read_imagef* for image objects with _image_channel_data_type_ values not specified in the description @@ -11432,14 +11435,14 @@ ifdef::cl_khr_fp16[] *read_imageh* returns half-precision floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of the pre-defined packed formats - or `CL_UNORM_INT8`, or `CL_UNORM_INT16`. + or {CL_UNORM_INT8}, or {CL_UNORM_INT16}. *read_imageh* returns half-precision floating-point values in the range [-1.0, 1.0] for image objects created with - _image_channel_data_type_ set to `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + _image_channel_data_type_ set to {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imageh* returns half-precision floating-point values for image - objects created with _image_channel_data_type_ set to `CL_HALF_FLOAT`. + objects created with _image_channel_data_type_ set to {CL_HALF_FLOAT}. Values returned by *read_imageh* for image objects with _image_channel_data_type_ values not specified in the description @@ -11461,9 +11464,9 @@ endif::cl_khr_fp16[] *read_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_SIGNED_INT8`, + - `CL_SIGNED_INT16` and + - `CL_SIGNED_INT32`. + {CL_SIGNED_INT8}, + + {CL_SIGNED_INT16} and + + {CL_SIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imagei* are undefined. @@ -11471,9 +11474,9 @@ endif::cl_khr_fp16[] *read_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_UNSIGNED_INT8`, + - `CL_UNSIGNED_INT16` and + - `CL_UNSIGNED_INT32`. + {CL_UNSIGNED_INT8}, + + {CL_UNSIGNED_INT16} and + + {CL_UNSIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imageui* are undefined. @@ -11484,10 +11487,10 @@ endif::cl_khr_fp16[] *read_imagef* returns a floating-point value in the range [0.0, 1.0] for depth image objects created with _image_channel_data_type_ set to - `CL_UNORM_INT16` or `CL_UNORM_INT24`. + {CL_UNORM_INT16} or {CL_UNORM_INT24}. *read_imagef* returns a floating-point value for depth image objects - created with _image_channel_data_type_ set to `CL_FLOAT`. + created with _image_channel_data_type_ set to {CL_FLOAT}. Values returned by *read_imagef* for image objects with _image_channel_data_type_ values not specified in the description @@ -11502,10 +11505,10 @@ endif::cl_khr_fp16[] *read_imagef* returns a floating-point value in the range [0.0, 1.0] for depth image objects created with _image_channel_data_type_ set to - `CL_UNORM_INT16` or `CL_UNORM_INT24`. + {CL_UNORM_INT16} or {CL_UNORM_INT24}. *read_imagef* returns a floating-point value for depth image objects - created with _image_channel_data_type_ set to `CL_FLOAT`. + created with _image_channel_data_type_ set to {CL_FLOAT}. Values returned by *read_imagef* for image objects with _image_channel_data_type_ values not specified in the description @@ -11529,15 +11532,15 @@ float4 read_imagef( *read_imagef* returns floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of - the pre-defined packed formats or `CL_UNORM_INT8`, or - `CL_UNORM_INT16`. + the pre-defined packed formats or {CL_UNORM_INT8}, or + {CL_UNORM_INT16}. *read_imagef* returns floating-point values in the range [-1.0, 1.0] for image objects created with _image_channel_data_type_ set to - `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imagef* returns floating-point values for image objects created - with _image_channel_data_type_ set to `CL_HALF_FLOAT` or `CL_FLOAT`. + with _image_channel_data_type_ set to {CL_HALF_FLOAT} or {CL_FLOAT}. Values returned by *read_imagef* for image objects with _image_channel_data_type_ values not specified in the description @@ -11568,9 +11571,9 @@ uint4 read_imageui( *read_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - * `CL_SIGNED_INT8`, - * `CL_SIGNED_INT16`, and - * `CL_SIGNED_INT32`. + * {CL_SIGNED_INT8}, + * {CL_SIGNED_INT16}, and + * {CL_SIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imagei* are undefined. @@ -11578,9 +11581,9 @@ uint4 read_imageui( *read_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - * `CL_UNSIGNED_INT8`, - * `CL_UNSIGNED_INT16`, and - * `CL_UNSIGNED_INT32`. + * {CL_UNSIGNED_INT8}, + * {CL_UNSIGNED_INT16}, and + * {CL_UNSIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imageui* are undefined. @@ -11600,15 +11603,15 @@ float4 read_imagef( *read_imagef* returns floating-point values in the range [0.0, 1.0] for image objects created with _image_channel_data_type_ set to one of - the pre-defined packed formats or `CL_UNORM_INT8`, or - `CL_UNORM_INT16`. + the pre-defined packed formats or {CL_UNORM_INT8}, or + {CL_UNORM_INT16}. *read_imagef* returns floating-point values in the range [-1.0, 1.0] for image objects created with _image_channel_data_type_ set to - `CL_SNORM_INT8`, or `CL_SNORM_INT16`. + {CL_SNORM_INT8}, or {CL_SNORM_INT16}. *read_imagef* returns floating-point values for image objects created - with _image_channel_data_type_ set to `CL_HALF_FLOAT` or `CL_FLOAT`. + with _image_channel_data_type_ set to {CL_HALF_FLOAT} or {CL_FLOAT}. Values returned by *read_imagef* for image objects with _image_channel_data_type_ values not specified in the description @@ -11639,9 +11642,9 @@ uint4 read_imageui( *read_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - * `CL_SIGNED_INT8`, - * `CL_SIGNED_INT16`, and - * `CL_SIGNED_INT32`. + * {CL_SIGNED_INT8}, + * {CL_SIGNED_INT16}, and + * {CL_SIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imagei* are undefined. @@ -11649,9 +11652,9 @@ uint4 read_imageui( *read_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - * `CL_UNSIGNED_INT8`, - * `CL_UNSIGNED_INT16`, and - * `CL_UNSIGNED_INT32`. + * {CL_UNSIGNED_INT8}, + * {CL_UNSIGNED_INT16}, and + * {CL_UNSIGNED_INT32}. If the _image_channel_data_type_ is not one of the above values, the values returned by *read_imageui* are undefined. @@ -11671,10 +11674,10 @@ float read_imagef( *read_imagef* returns a floating-point value in the range [0.0, 1.0] for depth image objects created with _image_channel_data_type_ set to - `CL_UNORM_INT16` or `CL_UNORM_INT24`. + {CL_UNORM_INT16} or {CL_UNORM_INT24}. *read_imagef* returns a floating-point value for depth image objects - created with _image_channel_data_type_ set to `CL_FLOAT`. + created with _image_channel_data_type_ set to {CL_FLOAT}. Values returned by *read_imagef* for image objects with _image_channel_data_type_ values not specified in the description @@ -11695,10 +11698,10 @@ float read_imagef(image2d_array_msaaa_depth_t image, *read_imagef* returns a floating-point value in the range [0.0, 1.0] for depth image objects created with _image_channel_data_type_ set to - `CL_UNORM_INT16` or `CL_UNORM_INT24`. + {CL_UNORM_INT16} or {CL_UNORM_INT24}. *read_imagef* returns a floating-point value for depth image objects - created with _image_channel_data_type_ set to `CL_FLOAT`. + created with _image_channel_data_type_ set to {CL_FLOAT}. Values returned by *read_imagef* for image objects with _image_channel_data_type_ values not specified in the description @@ -11790,8 +11793,8 @@ endif::cl_khr_fp16[] ifdef::cl_khr_fp16[and *write_imageh*] can only be used with image objects created with _image_channel_data_type_ set to one of the pre-defined packed formats - or set to `CL_SNORM_INT8`, `CL_UNORM_INT8`, `CL_SNORM_INT16`, - `CL_UNORM_INT16`, `CL_HALF_FLOAT` or `CL_FLOAT`. + or set to {CL_SNORM_INT8}, {CL_UNORM_INT8}, {CL_SNORM_INT16}, + {CL_UNORM_INT16}, {CL_HALF_FLOAT} or {CL_FLOAT}. Appropriate data format conversion will be done to convert channel data from a floating-point value to actual data format in which the channels are stored. @@ -11799,16 +11802,16 @@ ifdef::cl_khr_fp16[and *write_imageh*] *write_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_SIGNED_INT8`, + - `CL_SIGNED_INT16` and + - `CL_SIGNED_INT32`. + {CL_SIGNED_INT8}, + + {CL_SIGNED_INT16} and + + {CL_SIGNED_INT32}. *write_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_UNSIGNED_INT8`, + - `CL_UNSIGNED_INT16` and + - `CL_UNSIGNED_INT32`. + {CL_UNSIGNED_INT8}, + + {CL_UNSIGNED_INT16} and + + {CL_UNSIGNED_INT32}. The behavior of *write_imagef*, ifdef::cl_khr_fp16[*write_imageh*,] @@ -11854,8 +11857,8 @@ endif::cl_khr_fp16[] ifdef::cl_khr_fp16[and *write_imageh*] can only be used with image objects created with _image_channel_data_type_ set to one of the pre-defined packed formats - or set to `CL_SNORM_INT8`, `CL_UNORM_INT8`, `CL_SNORM_INT16`, - `CL_UNORM_INT16`, `CL_HALF_FLOAT` or `CL_FLOAT`. + or set to {CL_SNORM_INT8}, {CL_UNORM_INT8}, {CL_SNORM_INT16}, + {CL_UNORM_INT16}, {CL_HALF_FLOAT} or {CL_FLOAT}. Appropriate data format conversion will be done to convert channel data from a floating-point value to actual data format in which the channels are stored. @@ -11863,16 +11866,16 @@ ifdef::cl_khr_fp16[and *write_imageh*] *write_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_SIGNED_INT8`, + - `CL_SIGNED_INT16` and + - `CL_SIGNED_INT32`. + {CL_SIGNED_INT8}, + + {CL_SIGNED_INT16} and + + {CL_SIGNED_INT32}. *write_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_UNSIGNED_INT8`, + - `CL_UNSIGNED_INT16` and + - `CL_UNSIGNED_INT32`. + {CL_UNSIGNED_INT8}, + + {CL_UNSIGNED_INT16} and + + {CL_UNSIGNED_INT32}. The behavior of *write_imagef*, ifdef::cl_khr_fp16[*write_imageh*,] @@ -11935,8 +11938,8 @@ endif::cl_khr_fp16[] ifdef::cl_khr_fp16[and *write_imageh*] can only be used with image objects created with _image_channel_data_type_ set to one of the pre-defined packed formats - or set to `CL_SNORM_INT8`, `CL_UNORM_INT8`, `CL_SNORM_INT16`, - `CL_UNORM_INT16`, `CL_HALF_FLOAT` or `CL_FLOAT`. + or set to {CL_SNORM_INT8}, {CL_UNORM_INT8}, {CL_SNORM_INT16}, + {CL_UNORM_INT16}, {CL_HALF_FLOAT} or {CL_FLOAT}. Appropriate data format conversion will be done to convert channel data from a floating-point value to actual data format in which the channels are stored. @@ -11944,16 +11947,16 @@ ifdef::cl_khr_fp16[and *write_imageh*] *write_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_SIGNED_INT8`, + - `CL_SIGNED_INT16` and + - `CL_SIGNED_INT32`. + {CL_SIGNED_INT8}, + + {CL_SIGNED_INT16} and + + {CL_SIGNED_INT32}. *write_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_UNSIGNED_INT8`, + - `CL_UNSIGNED_INT16` and + - `CL_UNSIGNED_INT32`. + {CL_UNSIGNED_INT8}, + + {CL_UNSIGNED_INT16} and + + {CL_UNSIGNED_INT32}. The behavior of *write_imagef*, ifdef::cl_khr_fp16[*write_imageh*,] @@ -11999,8 +12002,8 @@ endif::cl_khr_fp16[] ifdef::cl_khr_fp16[and *write_imageh*] can only be used with image objects created with _image_channel_data_type_ set to one of the pre-defined packed formats - or set to `CL_SNORM_INT8`, `CL_UNORM_INT8`, `CL_SNORM_INT16`, - `CL_UNORM_INT16`, `CL_HALF_FLOAT` or `CL_FLOAT`. + or set to {CL_SNORM_INT8}, {CL_UNORM_INT8}, {CL_SNORM_INT16}, + {CL_UNORM_INT16}, {CL_HALF_FLOAT} or {CL_FLOAT}. Appropriate data format conversion will be done to convert channel data from a floating-point value to actual data format in which the channels are stored. @@ -12008,16 +12011,16 @@ ifdef::cl_khr_fp16[and *write_imageh*] *write_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_SIGNED_INT8`, + - `CL_SIGNED_INT16` and + - `CL_SIGNED_INT32`. + {CL_SIGNED_INT8}, + + {CL_SIGNED_INT16} and + + {CL_SIGNED_INT32}. *write_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_UNSIGNED_INT8`, + - `CL_UNSIGNED_INT16` and + - `CL_UNSIGNED_INT32`. + {CL_UNSIGNED_INT8}, + + {CL_UNSIGNED_INT16} and + + {CL_UNSIGNED_INT32}. The behavior of *write_imagef*, ifdef::cl_khr_fp16[*write_imageh*,] @@ -12042,8 +12045,8 @@ ifdef::cl_khr_fp16[*write_imageh*,] respectively. *write_imagef* can only be used with image objects created with - _image_channel_data_type_ set to `CL_UNORM_INT16`, `CL_UNORM_INT24` or - `CL_FLOAT`. + _image_channel_data_type_ set to {CL_UNORM_INT16}, {CL_UNORM_INT24} or + {CL_FLOAT}. Appropriate data format conversion will be done to convert depth valye from a floating-point value to actual data format associated with the image. @@ -12071,8 +12074,8 @@ ifdef::cl_khr_fp16[*write_imageh*,] height-1], and [0, image number of layers-1], respectively. *write_imagef* can only be used with image objects created with - _image_channel_data_type_ set to `CL_UNORM_INT16`, `CL_UNORM_INT24` or - `CL_FLOAT`. + _image_channel_data_type_ set to {CL_UNORM_INT16}, {CL_UNORM_INT24} or + {CL_FLOAT}. Appropriate data format conversion will be done to convert depth valye from a floating-point value to actual data format associated with the image. @@ -12116,8 +12119,8 @@ endif::cl_khr_fp16[] ifdef::cl_khr_fp16[and *write_imageh*] can only be used with image objects created with _image_channel_data_type_ set to one of the pre-defined packed formats - or set to `CL_SNORM_INT8`, `CL_UNORM_INT8`, `CL_SNORM_INT16`, - `CL_UNORM_INT16`, `CL_HALF_FLOAT` or `CL_FLOAT`. + or set to {CL_SNORM_INT8}, {CL_UNORM_INT8}, {CL_SNORM_INT16}, + {CL_UNORM_INT16}, {CL_HALF_FLOAT} or {CL_FLOAT}. Appropriate data format conversion will be done to convert channel data from a floating-point value to actual data format in which the channels are stored. @@ -12125,16 +12128,16 @@ ifdef::cl_khr_fp16[and *write_imageh*] *write_imagei* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_SIGNED_INT8`, + - `CL_SIGNED_INT16`, or + - `CL_SIGNED_INT32`. + {CL_SIGNED_INT8}, + + {CL_SIGNED_INT16}, or + + {CL_SIGNED_INT32}. *write_imageui* can only be used with image objects created with _image_channel_data_type_ set to one of the following values: - `CL_UNSIGNED_INT8`, + - `CL_UNSIGNED_INT16`, or + - `CL_UNSIGNED_INT32`. + {CL_UNSIGNED_INT8}, + + {CL_UNSIGNED_INT16}, or + + {CL_UNSIGNED_INT32}. The behavior of *write_imagef*, ifdef::cl_khr_fp16[*write_imageh*,] @@ -12145,7 +12148,7 @@ ifdef::cl_khr_fp16[*write_imageh*,] image depth-1], respectively, is undefined. <> support for OpenCL C 2.0, or OpenCL C 3.0 or - newer and the {c_3d_image_writes} feature, or the + newer and the {opencl_c_3d_image_writes} feature, or the `<>` extension. ifdef::cl_khr_fp16[] @@ -12598,7 +12601,7 @@ Query Functions>> with the `CLK_` prefixes correspond to the `CL_` prefixes used to describe the <> and <> in the <>. -For example, both `CL_UNORM_INT8` and `CLK_UNORM_INT8` refer to an image +For example, both {CL_UNORM_INT8} and `CLK_UNORM_INT8` refer to an image channel data type that is an unnormalized unsigned 8-bit integer. -- @@ -12657,26 +12660,26 @@ and will be set to 1.0 for the alpha channel. [cols=",",options="header",] |==== | Channel Order | `float4`, `int4` or `uint4` components of channel data -| `CL_R`, `CL_Rx` | (r, 0.0, 0.0, 1.0) -| `CL_A` | (0.0, 0.0, 0.0, a) -| `CL_RG`, `CL_RGx` | (r, g, 0.0, 1.0) -| `CL_RA` | (r, 0.0, 0.0, a) -| `CL_RGB`, `CL_RGBx`, `CL_sRGB`, `CL_sRGBx` +| {CL_R}, {CL_Rx} | (r, 0.0, 0.0, 1.0) +| {CL_A} | (0.0, 0.0, 0.0, a) +| {CL_RG}, {CL_RGx} | (r, g, 0.0, 1.0) +| {CL_RA} | (r, 0.0, 0.0, a) +| {CL_RGB}, {CL_RGBx}, {CL_sRGB}, {CL_sRGBx} | (r, g, b, 1.0) -| `CL_RGBA`, `CL_BGRA`, `CL_ARGB`, `CL_ABGR`, `CL_sRGBA`, `CL_sBGRA` +| {CL_RGBA}, {CL_BGRA}, {CL_ARGB}, {CL_ABGR}, {CL_sRGBA}, {CL_sBGRA} | (r, g, b, a) -| `CL_INTENSITY` | (I, I, I, I) -| `CL_LUMINANCE` | (L, L, L, 1.0) +| {CL_INTENSITY} | (I, I, I, I) +| {CL_LUMINANCE} | (L, L, L, 1.0) |==== -For `CL_DEPTH` images, a scalar value is returned by *read_imagef* or +For {CL_DEPTH} images, a scalar value is returned by *read_imagef* or supplied to *write_imagef*. <> support for OpenCL C 2.0 or newer, or for the `<>` extension macro. [NOTE] ==== -A kernel that uses a sampler with the `CL_ADDRESS_CLAMP` addressing mode +A kernel that uses a sampler with the {CL_ADDRESS_CLAMP} addressing mode with multiple images may result in additional samplers being used internally by an implementation. If the same sampler is used with multiple images called via @@ -12685,9 +12688,9 @@ allocate an additional sampler to handle the different border color values that may be needed depending on the image formats being used. These implementation allocated samplers will count against the maximum sampler values supported by the device and given by -`CL_DEVICE_MAX_SAMPLERS`. +{CL_DEVICE_MAX_SAMPLERS}. Enqueuing a kernel that requires more samplers than the implementation can -support will result in a `CL_OUT_OF_RESOURCES` error being returned. +support will result in a {CL_OUT_OF_RESOURCES} error being returned. ==== @@ -13168,7 +13171,7 @@ packets to the pipe. ==== There can only be the value of the <> reservations active +{CL_DEVICE_PIPE_MAX_ACTIVE_RESERVATIONS} device query>> reservations active (i.e. reservation IDs that have been reserved but not committed) per work-item or work-group for a pipe in a kernel executing on a device. @@ -13330,7 +13333,7 @@ Work-items can enqueue multiple blocks to a device queue(s). The *enqueue_kernel* built-in function returns `CLK_SUCCESS` if the block is enqueued successfully and returns `CLK_ENQUEUE_FAILURE` otherwise. If the -g compile option is specified in compiler options passed to -*clCompileProgram* or *clBuildProgram* when compiling or building the parent +{clCompileProgram} or {clBuildProgram} when compiling or building the parent program, the following errors may be returned instead of `CLK_ENQUEUE_FAILURE` to indicate why *enqueue_kernel* failed to enqueue the block: @@ -13633,7 +13636,7 @@ child kernels can begin execution. A parent kernel's execution status is considered to be complete when it and all its child kernels have finished execution. -The execution status of a parent kernel will be `CL_COMPLETE` if this kernel +The execution status of a parent kernel will be {CL_COMPLETE} if this kernel and all its child kernels finish execution successfully. The execution status of the kernel will be an error code (given by a negative integer value) if it or any of its child kernels encounter an @@ -13648,7 +13651,7 @@ with kernel `A` in the `event_wait_list` argument, i.e. wait for kernel `A` to finish execution before kernel `B` can begin execution. Let's assume kernel `A` enqueues kernels `X`, `Y` and `Z`. Kernel `A` is considered to have finished execution, i.e. its execution -status is `CL_COMPLETE`, only after `A` and the kernels `A` enqueued (and +status is {CL_COMPLETE}, only after `A` and the kernels `A` enqueued (and any kernels these enqueued kernels enqueue and so on) have finished execution. @@ -13718,7 +13721,7 @@ The *enqueue_marker* built-in function returns `CLK_SUCCESS` if the marked command is enqueued successfully and returns `CLK_ENQUEUE_FAILURE` otherwise. If the -g compile option is specified in compiler options passed to -*clCompileProgram* or *clBuildProgram*, the following errors may be returned +{clCompileProgram} or {clBuildProgram}, the following errors may be returned instead of `CLK_ENQUEUE_FAILURE` to indicate why *enqueue_marker* failed to enqueue the marker command: @@ -13764,7 +13767,7 @@ events. | Create a user event. Returns the user event. The execution status of the user event created is set to - `CL_SUBMITTED`. + {CL_SUBMITTED}. | bool *is_valid_event*(clk_event_t _event_) | Returns _true_ if _event_ is a valid event. Otherwise returns _false_. @@ -13772,7 +13775,7 @@ events. | Sets the execution status of a user event. Behavior is undefined if _event_ is not a valid event returned by *create_user_event*. - _status_ can be either `CL_COMPLETE` or a negative integer value + _status_ can be either {CL_COMPLETE} or a negative integer value indicating an error. | | | void *capture_event_profiling_info*(clk_event_t _event_, @@ -13792,12 +13795,12 @@ _name_ identifies which profiling information is to be queried and can be: _value_ is a pointer to two 64-bit values. -The first 64-bit value describes the elapsed time `CL_PROFILING_COMMAND_END` -- `CL_PROFLING_COMMAND_START` for the command identified by _event_ in +The first 64-bit value describes the elapsed time {CL_PROFILING_COMMAND_END} +- {CL_PROFILING_COMMAND_START} for the command identified by _event_ in nanoseconds. The second 64-bit value describes the elapsed time -`CL_PROFILING_COMMAND_COMPLETE` - `CL_PROFILING_COMAMND_START` for the +{CL_PROFILING_COMMAND_COMPLETE} - {CL_PROFILING_COMMAND_START} for the command identified by _event_ in nanoseconds. [NOTE] @@ -13811,21 +13814,21 @@ Events can be used to identify commands enqueued to a command-queue from the host. These events created by the OpenCL runtime can only be used on the host, i.e. as events passed in the _event_wait_list_ argument to various -*clEnqueue* APIs or runtime APIs that take events as arguments, such as -*clRetainEvent*, *clReleaseEvent*, and *clGetEventProfilingInfo*. +enqueue APIs or runtime APIs that take events as arguments, such as +{clRetainEvent}, {clReleaseEvent}, and {clGetEventProfilingInfo}. Similarly, events can be used to identify commands enqueued to a device queue (from a kernel). These event objects cannot be passed to the host or used by OpenCL runtime -APIs such as the *clEnqueue* APIs or runtime APIs that take event arguments. +APIs such as the enqueue APIs or runtime APIs that take event arguments. -*clRetainEvent* and *clReleaseEvent* will return `CL_INVALID_OPERATION` if +{clRetainEvent} and {clReleaseEvent} will return {CL_INVALID_OPERATION} if _event_ specified is an event that refers to any kernel enqueued to a device queue using *enqueue_kernel* or *enqueue_marker*, or is a user event created by *create_user_event*. -Similarly, *clSetUserEventStatus* can only be used to set the execution -status of events created using *clCreateUserEvent*. +Similarly, {clSetUserEventStatus} can only be used to set the execution +status of events created using {clCreateUserEvent}. User events created on the device can be set using set_user_event_status built-in function. @@ -15338,7 +15341,7 @@ spec is unsupported. ifdef::cl_khr_fp16[] If the `<>` extension macro is supported, then -if `CL_FP_ROUND_TO_NEAREST` is supported, the default rounding mode for +if {CL_FP_ROUND_TO_NEAREST} is supported, the default rounding mode for half-precision floating-point operations will be round to nearest even; otherwise the default rounding mode will be round to zero. @@ -16681,7 +16684,7 @@ If any of the selected `T_ijk` or `T_ij` in the above equations refers to a location outside the image, the border color is used as the color value for `T_ijk` or `T_ij`. -If the image channel type is `CL_FLOAT` or `CL_HALF_FLOAT` and any of the +If the image channel type is {CL_FLOAT} or {CL_HALF_FLOAT} and any of the image elements `T_ijk` or `T_ij` is `INF` or NaN, the behavior of the built-in image read function is undefined. @@ -16793,7 +16796,7 @@ T = (1 - a) * (1 - b) * T_i0j0 where `T_ij` is the image element at location (_i_,_j_) in the 2D image. -If the image channel type is `CL_FLOAT` or `CL_HALF_FLOAT` and any of the +If the image channel type is {CL_FLOAT} or {CL_HALF_FLOAT} and any of the image elements `T_ijk` or `T_ij` is `INF` or NaN, the behavior of the built-in image read function is undefined. @@ -16921,7 +16924,7 @@ T = (1 - a) * T_i0 where `T_i` is the image element at location (_i_) in the 1D image. -If the image channel type is `CL_FLOAT` or `CL_HALF_FLOAT` and any of the +If the image channel type is {CL_FLOAT} or {CL_HALF_FLOAT} and any of the image elements `T_ijk` or `T_ij` is `INF` or NaN, the behavior of the built-in image read function is undefined. @@ -16967,39 +16970,39 @@ to floating-point values and vice-versa. [[converting-normalized-integer-channel-data-types-to-floating-point-values]] ==== Converting Normalized Integer Channel Data Types to Floating-point Values -For images created with image channel data type of `CL_UNORM_INT8` and -`CL_UNORM_INT16`, *read_imagef* will convert the channel values from an +For images created with image channel data type of {CL_UNORM_INT8} and +{CL_UNORM_INT16}, *read_imagef* will convert the channel values from an 8-bit or 16-bit unsigned integer to normalized floating-point values in the range [`0.0f`, `1.0f`]. -For images created with image channel data type of `CL_SNORM_INT8` and -`CL_SNORM_INT16`, *read_imagef* will convert the channel values from an +For images created with image channel data type of {CL_SNORM_INT8} and +{CL_SNORM_INT16}, *read_imagef* will convert the channel values from an 8-bit or 16-bit signed integer to normalized floating-point values in the range [`-1.0f`, `1.0f`]. These conversions are performed as follows: -`CL_UNORM_INT8` (8-bit unsigned integer) {rightarrow} `float` +{CL_UNORM_INT8} (8-bit unsigned integer) {rightarrow} `float` [none] * normalized `float` value = `(float)c / 255.0f` -`CL_UNORM_INT_101010` (10-bit unsigned integer) {rightarrow} `float` +{CL_UNORM_INT_101010} (10-bit unsigned integer) {rightarrow} `float` [none] * normalized `float` value = `(float)c / 1023.0f` -`CL_UNORM_INT16` (16-bit unsigned integer) {rightarrow} `float` +{CL_UNORM_INT16} (16-bit unsigned integer) {rightarrow} `float` [none] * normalized `float` value = `(float)c / 65535.0f` -`CL_SNORM_INT8` (8-bit signed integer) {rightarrow} `float` +{CL_SNORM_INT8} (8-bit signed integer) {rightarrow} `float` [none] * normalized `float` value = *max*(`-1.0f`, `(float)c / 127.0f`) -`CL_SNORM_INT16` (16-bit signed integer) {rightarrow} `float` +{CL_SNORM_INT16} (16-bit signed integer) {rightarrow} `float` [none] * normalized `float` value = *max*(`-1.0f`, `(float)c / 32767.0f`) @@ -17007,32 +17010,32 @@ These conversions are performed as follows: The precision of the above conversions is \<= 1.5 ulp except for the following cases: -For `CL_UNORM_INT8` +For {CL_UNORM_INT8} [none] * 0 must convert to `0.0f` and * 255 must convert to `1.0f` -For `CL_UNORM_INT_101010` +For {CL_UNORM_INT_101010} [none] * 0 must convert to `0.0f` and * 1023 must convert to `1.0f` -For `CL_UNORM_INT16` +For {CL_UNORM_INT16} [none] * 0 must convert to `0.0f` and * 65535 must convert to `1.0f` -For `CL_SNORM_INT8` +For {CL_SNORM_INT8} [none] * -128 and -127 must convert to `-1.0f`, * 0 must convert to `0.0f` and * 127 must convert to `1.0f` -For `CL_SNORM_INT16` +For {CL_SNORM_INT16} [none] * -32768 and -32767 must convert to `-1.0f`, @@ -17045,39 +17048,39 @@ ifdef::cl_khr_fp16[] ==== Converting Normalized Integer Channel Data Types to Half-Precision Floating-Point Values If the `<>` extension is supported, then -for images created with image channel data type of `CL_UNORM_INT8` and -`CL_UNORM_INT16`, *read_imageh* will convert the channel values from an +for images created with image channel data type of {CL_UNORM_INT8} and +{CL_UNORM_INT16}, *read_imageh* will convert the channel values from an 8-bit or 16-bit unsigned integer to normalized half-precision floating-point values in the range [`0.0h`, `1.0h`]. -For images created with image channel data type of `CL_SNORM_INT8` and -`CL_SNORM_INT16`, *read_imageh* will convert the channel values from an +For images created with image channel data type of {CL_SNORM_INT8} and +{CL_SNORM_INT16}, *read_imageh* will convert the channel values from an 8-bit or 16-bit signed integer to normalized half-precision floating-point values in the range [`-1.0h`, `1.0h`]. These conversions are performed as follows: -`CL_UNORM_INT8` (8-bit unsigned integer) {rightarrow} `half` +{CL_UNORM_INT8} (8-bit unsigned integer) {rightarrow} `half` [none] * normalized `half` value = `round_to_half(c / 255)` -`CL_UNORM_INT_101010` (10-bit unsigned integer) {rightarrow} `half` +{CL_UNORM_INT_101010} (10-bit unsigned integer) {rightarrow} `half` [none] * normalized `half` value = `round_to_half(c / 1023)` -`CL_UNORM_INT16` (16-bit unsigned integer) {rightarrow} `half` +{CL_UNORM_INT16} (16-bit unsigned integer) {rightarrow} `half` [none] * normalized `half` value = `round_to_half(c / 65535)` -`CL_SNORM_INT8` (8-bit signed integer) {rightarrow} `half` +{CL_SNORM_INT8} (8-bit signed integer) {rightarrow} `half` [none] * normalized `half` value = *max*(`-1.0h`, `round_to_half(c / 127)`) -`CL_SNORM_INT16` (16-bit signed integer) {rightarrow} `half` +{CL_SNORM_INT16} (16-bit signed integer) {rightarrow} `half` [none] * normalized `half` value = *max*(`-1.0h`, `round_to_half(c / 32767)`) @@ -17085,32 +17088,32 @@ These conversions are performed as follows: The precision of the above conversions is \<= 1.5 ulp except for the following cases: -For `CL_UNORM_INT8` +For {CL_UNORM_INT8} [none] * 0 must convert to `0.0h` and * 255 must convert to `1.0h` -For `CL_UNORM_INT_101010` +For {CL_UNORM_INT_101010} [none] * 0 must convert to `0.0h` and * 1023 must convert to `1.0h` -For `CL_UNORM_INT16` +For {CL_UNORM_INT16} [none] * 0 must convert to `0.0h` and * 65535 must convert to `1.0h` -For `CL_SNORM_INT8` +For {CL_SNORM_INT8} [none] * -128 and -127 must convert to `-1.0h`, * 0 must convert to `0.0h` and * 127 must convert to `1.0h` -For `CL_SNORM_INT16` +For {CL_SNORM_INT16} [none] * -32768 and -32767 must convert to `-1.0h`, @@ -17122,38 +17125,38 @@ endif::cl_khr_fp16[] [[converting-floating-point-values-to-normalized-integer-channel-data-types]] ==== Converting Floating-Point Values to Normalized Integer Channel Data Types -For images created with image channel data type of `CL_UNORM_INT8` and -`CL_UNORM_INT16`, *write_imagef* will convert the floating-point color value +For images created with image channel data type of {CL_UNORM_INT8} and +{CL_UNORM_INT16}, *write_imagef* will convert the floating-point color value to an 8-bit or 16-bit unsigned integer. -For images created with image channel data type of `CL_SNORM_INT8` and -`CL_SNORM_INT16`, *write_imagef* will convert the floating-point color value +For images created with image channel data type of {CL_SNORM_INT8} and +{CL_SNORM_INT16}, *write_imagef* will convert the floating-point color value to an 8-bit or 16-bit signed integer. The preferred method for how conversions from floating-point values to normalized integer values are performed is as follows: -`float` {rightarrow} `CL_UNORM_INT8` (8-bit unsigned integer) +`float` {rightarrow} {CL_UNORM_INT8} (8-bit unsigned integer) [none] * *convert_uchar_sat_rte*(`f * 255.0f`) -`float` {rightarrow} `CL_UNORM_INT_101010` (10-bit unsigned integer) +`float` {rightarrow} {CL_UNORM_INT_101010} (10-bit unsigned integer) [none] * *min*(*convert_ushort_sat_rte*(`f * 1023.0f`), `0x3ff`) -`float` {rightarrow} `CL_UNORM_INT16` (16-bit unsigned integer) +`float` {rightarrow} {CL_UNORM_INT16} (16-bit unsigned integer) [none] * *convert_ushort_sat_rte*(`f * 65535.0f`) -`float` {rightarrow} `CL_SNORM_INT8` (8-bit signed integer) +`float` {rightarrow} {CL_SNORM_INT8} (8-bit signed integer) [none] * *convert_char_sat_rte*(`f * 127.0f`) -`float` {rightarrow} `CL_SNORM_INT16` (16-bit signed integer) +`float` {rightarrow} {CL_SNORM_INT16} (16-bit signed integer) [none] * *convert_short_sat_rte*(`f * 32767.0f`) @@ -17168,14 +17171,14 @@ absolute error of the implementation dependant rounding mode vs. the result produced by the round to nearest even rounding mode must be {leq} 0.6. -`float` {rightarrow} `CL_UNORM_INT8` (8-bit unsigned integer) +`float` {rightarrow} {CL_UNORM_INT8} (8-bit unsigned integer) [none] * Let f~preferred~ = *convert_uchar_sat_rte*(f * `255.0f`) * Let f~approx~ = *convert_uchar_sat_*(f * `255.0f`) * *fabs*(f~preferred~ - f~approx~) must be \<= 0.6 -`float` {rightarrow} `CL_UNORM_INT_101010` (10-bit unsigned integer) +`float` {rightarrow} {CL_UNORM_INT_101010} (10-bit unsigned integer) [none] * Let f~preferred~ = *convert_ushort_sat_rte*(f * `1023.0f`) @@ -17183,7 +17186,7 @@ the result produced by the round to nearest even rounding mode must be {leq} `1023.0f`) * *fabs*(f~preferred~ - f~approx~) must be \<= 0.6 -`float` {rightarrow} `CL_UNORM_INT16` (16-bit unsigned integer) +`float` {rightarrow} {CL_UNORM_INT16} (16-bit unsigned integer) [none] * Let f~preferred~ = *convert_ushort_sat_rte*(f * `65535.0f`) @@ -17191,14 +17194,14 @@ the result produced by the round to nearest even rounding mode must be {leq} `65535.0f`) * *fabs*(f~preferred~ - f~approx~) must be \<= 0.6 -`float` {rightarrow} `CL_SNORM_INT8` (8-bit signed integer) +`float` {rightarrow} {CL_SNORM_INT8} (8-bit signed integer) [none] * Let f~preferred~ = *convert_char_sat_rte*(f * `127.0f`) * Let f~approx~ = *convert_char_sat_*(f * `127.0f`) * *fabs*(f~preferred~ - f~approx~) must be \<= 0.6 -`float` {rightarrow} `CL_SNORM_INT16` (16-bit signed integer) +`float` {rightarrow} {CL_SNORM_INT16} (16-bit signed integer) [none] * Let f~preferred~ = *convert_short_sat_rte*(f * `32767.0f`) @@ -17212,12 +17215,12 @@ ifdef::cl_khr_fp16[] ==== Converting Half-Precision Floating-point Values to Normalized Integer Channel Data Types If the `<>` extension is supported, then -for images created with image channel data type of `CL_UNORM_INT8` and -`CL_UNORM_INT16`, *write_imageh* will convert the floating-point color value +for images created with image channel data type of {CL_UNORM_INT8} and +{CL_UNORM_INT16}, *write_imageh* will convert the floating-point color value to an 8-bit or 16-bit unsigned integer. -For images created with image channel data type of `CL_SNORM_INT8` and -`CL_SNORM_INT16`, *write_imageh* will convert the floating-point color value +For images created with image channel data type of {CL_SNORM_INT8} and +{CL_SNORM_INT16}, *write_imageh* will convert the floating-point color value to an 8-bit or 16-bit signed integer. The preferred conversion uses the round to nearest even (`_rte`) rounding @@ -17226,7 +17229,7 @@ used in the conversions described below. When approximate rounding is used instead of the preferred rounding, the result of the conversion must satisfy the bound given below. -`half` {rightarrow` `CL_UNORM_INT8` (8-bit unsigned integer) +`half` {rightarrow` {CL_UNORM_INT8} (8-bit unsigned integer) [none] * Let f~exact~ = *max*(`0`, *min*(`f * 255`, `255`)) @@ -17234,7 +17237,7 @@ result of the conversion must satisfy the bound given below. * Let f~approx~ = *convert_uchar_sat_*(`f * 255.0f`) * *fabs*(f~exact~ - f~approx~) must be \<= 0.6 -`half` {rightarrow` `CL_UNORM_INT_101010` (10-bit unsigned integer) +`half` {rightarrow` {CL_UNORM_INT_101010} (10-bit unsigned integer) [none] * Let f~exact~ = *max*(`0`, *min*(`f * 1023`, `1023`)) @@ -17243,7 +17246,7 @@ result of the conversion must satisfy the bound given below. * Let f~approx~ = *convert_ushort_sat_*(`f * 1023.0f`) * *fabs*(f~exact~ - f~approx~) must be \<= 0.6 -`half` {rightarrow` `CL_UNORM_INT16` (16-bit unsigned integer) +`half` {rightarrow` {CL_UNORM_INT16} (16-bit unsigned integer) [none] * Let f~exact~ = *max*(`0`, *min*(`f * 65535`, `65535`)) @@ -17252,7 +17255,7 @@ result of the conversion must satisfy the bound given below. 65535.0f`) * *fabs*(f~exact~ - f~approx~) must be \<= 0.6 -`half` {rightarrow` `CL_SNORM_INT8` (8-bit signed integer) +`half` {rightarrow` {CL_SNORM_INT8} (8-bit signed integer) [none] * Let f~exact~ = *max*(`-128`, *min*(`f * 127`, `127`)) @@ -17260,7 +17263,7 @@ result of the conversion must satisfy the bound given below. * Let f~approx~ = *convert_char_sat_*(`f * 127.0f`) * *fabs*(f~exact~ - f~approx~) must be \<= 0.6 -`half` {rightarrow` `CL_SNORM_INT16` (16-bit signed integer) +`half` {rightarrow` {CL_SNORM_INT16} (16-bit signed integer) [none] * Let f~exact~ = *max*(`-32768`, *min*(`f * 32767`, `32767`)) @@ -17273,7 +17276,7 @@ endif::cl_khr_fp16[] [[conversion-rules-for-half-precision-floating-point-channel-data-type]] === Conversion Rules for Half-Precision Floating-Point Channel Data Type -For images created with a channel data type of `CL_HALF_FLOAT`, the +For images created with a channel data type of {CL_HALF_FLOAT}, the conversions from `half` to `float` are lossless (as described in <>). Conversions from `float` to `half` round the mantissa using the round to @@ -17289,7 +17292,7 @@ type. === Conversion Rules for Floating-Point Channel Data Type The following rules apply for reading and writing images created with -channel data type of `CL_FLOAT`. +channel data type of {CL_FLOAT}. * NaNs may be converted to a NaN value(s) supported by the device. * Denorms can be flushed to zero. @@ -17299,12 +17302,12 @@ channel data type of `CL_FLOAT`. [[conversion-rules-for-signed-and-unsigned-8-bit-16-bit-and-32-bit-integer-channel-data-types]] === Conversion Rules for Signed and Unsigned 8-Bit, 16-Bit and 32-Bit Integer Channel Data Types -Calls to *read_imagei* with channel data type values of `CL_SIGNED_INT8`, -`CL_SIGNED_INT16` and `CL_SIGNED_INT32` return the unmodified integer values +Calls to *read_imagei* with channel data type values of {CL_SIGNED_INT8}, +{CL_SIGNED_INT16} and {CL_SIGNED_INT32} return the unmodified integer values stored in the image at specified location. -Calls to *read_imageui* with channel data type values of `CL_UNSIGNED_INT8`, -`CL_UNSIGNED_INT16` and `CL_UNSIGNED_INT32` return the unmodified integer +Calls to *read_imageui* with channel data type values of {CL_UNSIGNED_INT8}, +{CL_UNSIGNED_INT16} and {CL_UNSIGNED_INT32} return the unmodified integer values stored in the image at specified location. Calls to *write_imagei* will perform one of the following conversions: @@ -17474,7 +17477,7 @@ one of the integers 0, 1, ... h~t~ - 1. References are to sections and tables of this specific version, although other versions exists. . [[opencl-device-queries]] "`Device Queries`" are defined in the - <> for *clGetDeviceInfo*, and the + <> for {clGetDeviceInfo}, and the individual queries are defined in the "`OpenCL Device Queries`" table (4.3) of that Specification. . [[opencl-channel-order,image channel order]] "`Image Channel Order`" is diff --git a/api/cl_khr_extended_versioning.asciidoc b/api/cl_khr_extended_versioning.asciidoc index cf2ea54ee..d67e61f0a 100644 --- a/api/cl_khr_extended_versioning.asciidoc +++ b/api/cl_khr_extended_versioning.asciidoc @@ -47,16 +47,16 @@ Versioning>> section. === New Macro Names - * {CL_VERSION_MAJOR_BITS_KHR} - * {CL_VERSION_MINOR_BITS_KHR} - * {CL_VERSION_PATCH_BITS_KHR} - * `CL_VERSION_MAJOR_MASK_KHR` - * `CL_VERSION_MINOR_MASK_KHR` - * `CL_VERSION_PATCH_MASK_KHR` - * `CL_VERSION_MAJOR_KHR` - * `CL_VERSION_MINOR_KHR` - * `CL_VERSION_PATCH_KHR` - * `CL_MAKE_VERSION_KHR` + * {CL_VERSION_MAJOR_BITS_KHR_anchor} + * {CL_VERSION_MINOR_BITS_KHR_anchor} + * {CL_VERSION_PATCH_BITS_KHR_anchor} + * {CL_VERSION_MAJOR_MASK_KHR_anchor} + * {CL_VERSION_MINOR_MASK_KHR_anchor} + * {CL_VERSION_PATCH_MASK_KHR_anchor} + * {CL_VERSION_MAJOR_KHR_anchor} + * {CL_VERSION_MINOR_KHR_anchor} + * {CL_VERSION_PATCH_KHR_anchor} + * {CL_MAKE_VERSION_KHR_anchor} === New Enums diff --git a/api/opencl_architecture.asciidoc b/api/opencl_architecture.asciidoc index 0a70e6278..d45e84c89 100644 --- a/api/opencl_architecture.asciidoc +++ b/api/opencl_architecture.asciidoc @@ -2220,19 +2220,19 @@ This enables versions to be ordered using standard C/C++ operators. A number of convenience macros are provided by the OpenCL Headers to make working with version numbers easier. - * `CL_VERSION_MAJOR` extracts the _major_ version from a packed + * {CL_VERSION_MAJOR_anchor} extracts the _major_ version from a packed {cl_version_TYPE}. - * `CL_VERSION_MINOR` extracts the _minor_ version from a packed + * {CL_VERSION_MINOR_anchor} extracts the _minor_ version from a packed {cl_version_TYPE}. - * `CL_VERSION_PATCH` extracts the _patch_ version from a packed + * {CL_VERSION_PATCH_anchor} extracts the _patch_ version from a packed {cl_version_TYPE}. - * `CL_MAKE_VERSION` returns a packed {cl_version_TYPE} from a + * {CL_MAKE_VERSION_anchor} returns a packed {cl_version_TYPE} from a _major_, _minor_ and _patch_ version. * {CL_VERSION_MAJOR_BITS_anchor}, {CL_VERSION_MINOR_BITS_anchor}, and {CL_VERSION_PATCH_BITS_anchor} are the number of bits in the corresponding field. - * `CL_VERSION_MAJOR_MASK`, `CL_VERSION_MINOR_MASK`, and - `CL_VERSION_PATCH_MASK` are bitmasks used to extract the + * {CL_VERSION_MAJOR_MASK_anchor}, {CL_VERSION_MINOR_MASK_anchor}, and + {CL_VERSION_PATCH_MASK_anchor} are bitmasks used to extract the corresponding packed fields from the version number. [source,opencl] diff --git a/c/dictionary.asciidoc b/c/dictionary.asciidoc new file mode 100644 index 000000000..bdf9c23c3 --- /dev/null +++ b/c/dictionary.asciidoc @@ -0,0 +1,5 @@ +// Copyright 2017-2024 The Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ + +include::{generated}/api/api-dictionary-no-links.asciidoc[] diff --git a/c/footnotes.asciidoc b/c/footnotes.asciidoc index 6abc922aa..c22db5889 100644 --- a/c/footnotes.asciidoc +++ b/c/footnotes.asciidoc @@ -72,11 +72,11 @@ This is similar to the `GL_ADDRESS_CLAMP_TO_BORDER` addressing mode. \ ] :fn-CLK_UNORM_INT_101010_2: pass:n[ \ -Although `CL_UNORM_INT_101010_2` was added in OpenCL 2.1, because there was no OpenCL C 2.1 this image channel order <> OpenCL 3.0. \ +Although {CL_UNORM_INT_101010_2} was added in OpenCL 2.1, because there was no OpenCL C 2.1 this image channel order <> OpenCL 3.0. \ ] :fn-double: pass:n[ \ -The `double` scalar type is an optional type that is supported if the value of the `CL_DEVICE_DOUBLE_FP_CONFIG` device query is not zero. \ +The `double` scalar type is an optional type that is supported if the value of the {CL_DEVICE_DOUBLE_FP_CONFIG} device query is not zero. \ If this is the case then an OpenCL C 3.0 compiler must also define the {opencl_c_fp64} feature macro. \ ] @@ -86,7 +86,7 @@ In OpenCL C 3.0 this will be indicated by the presence of the {opencl_c_fp64} fe ] :fn-double-vec: pass:n[ \ -The `double__n__` vector type is an optional type that is supported if the value of the `CL_DEVICE_DOUBLE_FP_CONFIG` device query is not zero. \ +The `double__n__` vector type is an optional type that is supported if the value of the {CL_DEVICE_DOUBLE_FP_CONFIG} device query is not zero. \ If this is the case then an OpenCL C 3.0 compiler must also define the {opencl_c_fp64} feature macro. \ ] @@ -167,12 +167,12 @@ Integer promotion is described in < c) ? c : a) \end{aligned} ++++ -If the addressing mode is `CL_ADDRESS_CLAMP` or `CL_ADDRESS_CLAMP_TO_EDGE`, and the selected texel location `(i,j,k)` refers to a location outside the image, the border color is used as the color value for the texel. +If the addressing mode is {CL_ADDRESS_CLAMP} or {CL_ADDRESS_CLAMP_TO_EDGE}, and the selected texel location `(i,j,k)` refers to a location outside the image, the border color is used as the color value for the texel. -Otherwise, if the addressing mode is `CL_ADDRESS_NONE` and the selected texel location `(i,j,k)` refers to a location outside the image, the color value for the texel is undefined. +Otherwise, if the addressing mode is {CL_ADDRESS_NONE} and the selected texel location `(i,j,k)` refers to a location outside the image, the color value for the texel is undefined. [[clamp-linear-filtering]] ===== Linear Filtering -When the filter mode is `CL_FILTER_LINEAR`, a 2 x 2 square of image elements (for a 2D image) or a 2 x 2 x 2 cube of image elements (for a 3D image is selected). +When the filter mode is {CL_FILTER_LINEAR}, a 2 x 2 square of image elements (for a 2D image) or a 2 x 2 x 2 cube of image elements (for a 3D image is selected). This 2 x 2 square or 2 x 2 x 2 cube is obtained as follows. Let: @@ -148,21 +148,21 @@ T &=& (1 - a) \times (1 - b) \times T_{i0j0}\\ where `T~ij~` is the image element at location `(i,j)` in the 2D image. -If the addressing mode is `CL_ADDRESS_CLAMP` or `CL_ADDRESS_CLAMP_TO_EDGE`, and any of the selected `T~ijk~` or `T~ij~` refers to a location outside the image, the border color is used as the image element. +If the addressing mode is {CL_ADDRESS_CLAMP} or {CL_ADDRESS_CLAMP_TO_EDGE}, and any of the selected `T~ijk~` or `T~ij~` refers to a location outside the image, the border color is used as the image element. -Otherwise, if the addressing mode is `CL_ADDRESS_NONE`, and any of the selected `T~ijk~` or `T~ij~` refers to a location outside the image, the color value is undefined. +Otherwise, if the addressing mode is {CL_ADDRESS_NONE}, and any of the selected `T~ijk~` or `T~ij~` refers to a location outside the image, the color value is undefined. -If the image channel type is `CL_FLOAT` or `CL_HALF_FLOAT`, and any of the image elements `T~ijk~` or `T~ij~` is INF or NaN, the color value is undefined. +If the image channel type is {CL_FLOAT} or {CL_HALF_FLOAT}, and any of the image elements `T~ijk~` or `T~ij~` is INF or NaN, the color value is undefined. [[repeat-addressing]] ==== Repeat Addressing Mode -We now discuss how the addressing and filter modes are applied to generate the appropriate sample locations to read from the image if the addressing mode is `CL_ADDRESS_REPEAT`. +We now discuss how the addressing and filter modes are applied to generate the appropriate sample locations to read from the image if the addressing mode is {CL_ADDRESS_REPEAT}. [[repeat-nearest-filtering]] ===== Nearest Filtering -When filter mode is `CL_FILTER_NEAREST`, the result of the image read instruction is the image element that is nearest (in Manhattan distance) to the image element location `(i,j,k)`. +When filter mode is {CL_FILTER_NEAREST}, the result of the image read instruction is the image element that is nearest (in Manhattan distance) to the image element location `(i,j,k)`. The image element location `(i,j,k)` is computed as: [latexmath] @@ -189,7 +189,7 @@ For a 2D image, the image element at location (i, j) becomes the color value. [[repeat-linear-filtering]] ===== Linear Filtering -When filter mode is `CL_FILTER_LINEAR`, a 2 x 2 square of image elements for a 2D image or a 2 x 2 x 2 cube of image elements for a 3D image is selected. +When filter mode is {CL_FILTER_LINEAR}, a 2 x 2 square of image elements for a 2D image or a 2 x 2 x 2 cube of image elements for a 3D image is selected. This 2 x 2 square or 2 x 2 x 2 cube is obtained as follows. Let @@ -256,18 +256,18 @@ T &=&(1 - a) \times (1 - b) \times T_{i0j0}\\ where `T~ij~` is the image element at location `(i,j)` in the 2D image. -If the image channel type is `CL_FLOAT` or `CL_HALF_FLOAT`, and any of the image elements `T~ijk~` or `T~ij~` is INF or NaN, the color value is undefined. +If the image channel type is {CL_FLOAT} or {CL_HALF_FLOAT}, and any of the image elements `T~ijk~` or `T~ij~` is INF or NaN, the color value is undefined. [[mirrored-repeat-addressing]] ==== Mirrored Repeat Addressing Mode -We now discuss how the addressing and filter modes are applied to generate the appropriate sample locations to read from the image if the addressing mode is `CL_ADDRESS_MIRRORED_REPEAT`. -The `CL_ADDRESS_MIRRORED_REPEAT` addressing mode causes the image to be read as if it is tiled at every integer seam, with the interpretation of the image data flipped at each integer crossing. +We now discuss how the addressing and filter modes are applied to generate the appropriate sample locations to read from the image if the addressing mode is {CL_ADDRESS_MIRRORED_REPEAT}. +The {CL_ADDRESS_MIRRORED_REPEAT} addressing mode causes the image to be read as if it is tiled at every integer seam, with the interpretation of the image data flipped at each integer crossing. [[mirrored-repeat-nearest-filtering]] ===== Nearest Filtering -When filter mode is `CL_FILTER_NEAREST`, the result of the image read instruction is the image element that is nearest (in Manhattan distance) to the image element location `(i,j,k)`. +When filter mode is {CL_FILTER_NEAREST}, the result of the image read instruction is the image element that is nearest (in Manhattan distance) to the image element location `(i,j,k)`. The image element location `(i,j,k)` is computed as: [latexmath] @@ -297,7 +297,7 @@ For a 2D image, the image element at location (i, j) becomes the color value. [[mirrored-repeat-linear-filtering]] ===== Linear Filtering -When filter mode is `CL_FILTER_LINEAR`, a 2 x 2 square of image elements for a 2D image or a 2 x 2 x 2 cube of image elements for a 3D image is selected. +When filter mode is {CL_FILTER_LINEAR}, a 2 x 2 square of image elements for a 2D image or a 2 x 2 x 2 cube of image elements for a 3D image is selected. This 2 x 2 square or 2 x 2 x 2 cube is obtained as follows. Let @@ -375,15 +375,15 @@ T &=& (1 - a) \times T_i0 + a \times T_i1 where `T~i~` is the image element at location `(i)` in the 1D image. -If the image channel type is `CL_FLOAT` or `CL_HALF_FLOAT` and any of the image elements `T~ijk~` or `T~ij~` is INF or NaN, the color value is undefined. +If the image channel type is {CL_FLOAT} or {CL_HALF_FLOAT} and any of the image elements `T~ijk~` or `T~ij~` is INF or NaN, the color value is undefined. [[precision-of-addressing-and-filter-modes]] === Precision of Addressing and Filter Modes -If the sampler is specified as using unnormalized coordinates (floating-point or integer coordinates), filter mode set to `CL_FILTER_NEAREST` and addressing mode set to one of the following modes - `CL_ADDRESS_CLAMP`, `CL_ADDRESS_CLAMP_TO_EDGE` or `CL_ADDRESS_NONE` - the location of the image element in the image given by `(i,j,k)` will be computed without any loss of precision. +If the sampler is specified as using unnormalized coordinates (floating-point or integer coordinates), filter mode set to {CL_FILTER_NEAREST} and addressing mode set to one of the following modes - {CL_ADDRESS_CLAMP}, {CL_ADDRESS_CLAMP_TO_EDGE} or {CL_ADDRESS_NONE} - the location of the image element in the image given by `(i,j,k)` will be computed without any loss of precision. For all other sampler combinations of normalized or unnormalized coordinates, filter modes, and addressing modes, the relative error or precision of the addressing mode calculations and the image filter operation are not defined. -To ensure precision of image addressing and filter calculations across any OpenCL device for these sampler combinations, developers may unnormalize the image coordinate in the kernel, and then implement the linear filter in the kernel with appropriate read image instructions with a sampler that uses unnormalized coordinates, filter mode set to `CL_FILTER_NEAREST`, addressing mode set to `CL_ADDRESS_CLAMP`, `CL_ADDRESS_CLAMP_TO_EDGE` or `CL_ADDRESS_NONE`, and finally performing the interpolation of color values read from the image to generate the filtered color value. +To ensure precision of image addressing and filter calculations across any OpenCL device for these sampler combinations, developers may unnormalize the image coordinate in the kernel, and then implement the linear filter in the kernel with appropriate read image instructions with a sampler that uses unnormalized coordinates, filter mode set to {CL_FILTER_NEAREST}, addressing mode set to {CL_ADDRESS_CLAMP}, {CL_ADDRESS_CLAMP_TO_EDGE} or {CL_ADDRESS_NONE}, and finally performing the interpolation of color values read from the image to generate the filtered color value. [[conversion-rules]] === Conversion Rules @@ -398,41 +398,41 @@ In this section we discuss converting normalized integer channel data types to h [[converting-normalized-integer-channel-data-types-to-half-precision-floating-point-values]] ===== Converting Normalized Integer Channel Data Types to Half Precision Floating-point Values -For images created with image channel data type of `CL_UNORM_INT8` and `CL_UNORM_INT16`, image read instructions will convert the channel values from an 8-bit or 16-bit unsigned integer to normalized half precision floating-point values in the range [0.0h ... 1.0h]. +For images created with image channel data type of {CL_UNORM_INT8} and {CL_UNORM_INT16}, image read instructions will convert the channel values from an 8-bit or 16-bit unsigned integer to normalized half precision floating-point values in the range [0.0h ... 1.0h]. -For images created with image channel data type of `CL_SNORM_INT8` and `CL_SNORM_INT16`, image read instructions will convert the channel values from an 8-bit or 16-bit signed integer to normalized half precision floating-point values in the range [-1.0h ... 1.0h]. +For images created with image channel data type of {CL_SNORM_INT8} and {CL_SNORM_INT16}, image read instructions will convert the channel values from an 8-bit or 16-bit signed integer to normalized half precision floating-point values in the range [-1.0h ... 1.0h]. These conversions are performed as follows: -* `CL_UNORM_INT8` (8-bit unsigned integer) -> `half` +* {CL_UNORM_INT8} (8-bit unsigned integer) -> `half` + [latexmath] ++++ normalized\_half\_value(x)=round\_to\_half(\frac{x}{255}) ++++ -* `CL_UNORM_INT_101010` (10-bit unsigned integer) -> `half` +* {CL_UNORM_INT_101010} (10-bit unsigned integer) -> `half` + [latexmath] ++++ normalized\_half\_value(x)=round\_to\_half(\frac{x}{1023}) ++++ -* `CL_UNORM_INT16` (16-bit unsigned integer) -> `half` +* {CL_UNORM_INT16} (16-bit unsigned integer) -> `half` + [latexmath] ++++ normalized\_half\_value(x)=round\_to\_half(\frac{x}{65535}) ++++ -* `CL_SNORM_INT8` (8-bit signed integer) -> `half` +* {CL_SNORM_INT8} (8-bit signed integer) -> `half` + [latexmath] ++++ normalized\_half\_value(x)=max(-1.0h, round\_to\_half(\frac{x}{127})) ++++ -* `CL_SNORM_INT16` (16-bit signed integer) -> `half` +* {CL_SNORM_INT16} (16-bit signed integer) -> `half` + [latexmath] ++++ @@ -441,28 +441,28 @@ normalized\_half\_value(x)=max(-1.0h, round\_to\_half(\frac{x}{32767})) The precision of the above conversions is \<= 1.5 ulp except for the following cases: -For `CL_UNORM_INT8`: +For {CL_UNORM_INT8}: * 0 must convert to 0.0h, and * 255 must convert to 1.0h -For `CL_UNORM_INT_101010`: +For {CL_UNORM_INT_101010}: * 0 must convert to 0.0h, and * 1023 must convert to 1.0h -For `CL_UNORM_INT16`: +For {CL_UNORM_INT16}: * 0 must convert to 0.0h, and * 65535 must convert to 1.0h -For `CL_SNORM_INT8`: +For {CL_SNORM_INT8}: * -128 and -127 must convert to -1.0h, * 0 must convert to 0.0h, and * 127 must convert to 1.0h -For `CL_SNORM_INT16`: +For {CL_SNORM_INT16}: * -32768 and -32767 must convert to -1.0h, * 0 must convert to 0.0h, and @@ -471,16 +471,16 @@ For `CL_SNORM_INT16`: [[converting-half-precision-floating-point-values-to-normalized-integer-channel-data-types]] ===== Converting Half Precision Floating-point Values to Normalized Integer Channel Data Types -For images created with image channel data type of `CL_UNORM_INT8` and `CL_UNORM_INT16`, image write instructions will convert the half precision floating-point color value to an 8-bit or 16-bit unsigned integer. +For images created with image channel data type of {CL_UNORM_INT8} and {CL_UNORM_INT16}, image write instructions will convert the half precision floating-point color value to an 8-bit or 16-bit unsigned integer. -For images created with image channel data type of `CL_SNORM_INT8` and `CL_SNORM_INT16`, image write instructions will convert the half precision floating-point color value to an 8-bit or 16-bit signed integer. +For images created with image channel data type of {CL_SNORM_INT8} and {CL_SNORM_INT16}, image write instructions will convert the half precision floating-point color value to an 8-bit or 16-bit signed integer. OpenCL implementations may choose to approximate the rounding mode used in the conversions described below. When approximate rounding is used instead of the preferred rounding, the result of the conversion must satisfy the bound given below. The conversions from half precision floating-point values to normalized integer values are performed is as follows: - * `half` -> `CL_UNORM_INT8` (8-bit unsigned integer) + * `half` -> {CL_UNORM_INT8} (8-bit unsigned integer) + [latexmath] ++++ @@ -502,7 +502,7 @@ The conversions from half precision floating-point values to normalized integer \end{aligned} ++++ - * `half` -> `CL_UNORM_INT16` (16-bit unsigned integer) + * `half` -> {CL_UNORM_INT16} (16-bit unsigned integer) + [latexmath] ++++ @@ -524,7 +524,7 @@ The conversions from half precision floating-point values to normalized integer \end{aligned} ++++ - * `half` -> `CL_SNORM_INT8` (8-bit signed integer) + * `half` -> {CL_SNORM_INT8} (8-bit signed integer) + [latexmath] ++++ @@ -546,7 +546,7 @@ The conversions from half precision floating-point values to normalized integer \end{aligned} ++++ - * `half` -> `CL_SNORM_INT16` (16-bit signed integer) + * `half` -> {CL_SNORM_INT16} (16-bit signed integer) + [latexmath] ++++ @@ -571,41 +571,41 @@ The conversions from half precision floating-point values to normalized integer [[converting-normalized-integer-channel-data-types-to-floating-point-values]] ===== Converting Normalized Integer Channel Data Types to Floating-point Values -For images created with image channel data type of `CL_UNORM_INT8` and `CL_UNORM_INT16`, image read instructions will convert the channel values from an 8-bit or 16-bit unsigned integer to normalized floating-point values in the range [0.0f ... 1.0f]. +For images created with image channel data type of {CL_UNORM_INT8} and {CL_UNORM_INT16}, image read instructions will convert the channel values from an 8-bit or 16-bit unsigned integer to normalized floating-point values in the range [0.0f ... 1.0f]. -For images created with image channel data type of `CL_SNORM_INT8` and `CL_SNORM_INT16`, image read instructions will convert the channel values from an 8-bit or 16-bit signed integer to normalized floating-point values in the range [-1.0f ... 1.0f]. +For images created with image channel data type of {CL_SNORM_INT8} and {CL_SNORM_INT16}, image read instructions will convert the channel values from an 8-bit or 16-bit signed integer to normalized floating-point values in the range [-1.0f ... 1.0f]. These conversions are performed as follows: - * `CL_UNORM_INT8` (8-bit unsigned integer) -> `float` + * {CL_UNORM_INT8} (8-bit unsigned integer) -> `float` + [latexmath] ++++ normalized\_float\_value(x)=round\_to\_float(\frac{x}{255}) ++++ - * `CL_UNORM_INT_101010` (10-bit unsigned integer) -> `float` + * {CL_UNORM_INT_101010} (10-bit unsigned integer) -> `float` + [latexmath] ++++ normalized\_float\_value(x)=round\_to\_float(\frac{x}{1023}) ++++ - * `CL_UNORM_INT16` (16-bit unsigned integer) -> `float` + * {CL_UNORM_INT16} (16-bit unsigned integer) -> `float` + [latexmath] ++++ normalized\_float\_value(x)=round\_to\_float(\frac{x}{65535}) ++++ - * `CL_SNORM_INT8` (8-bit signed integer) -> `float` + * {CL_SNORM_INT8} (8-bit signed integer) -> `float` + [latexmath] ++++ normalized\_float\_value(x)=max(-1.0f, round\_to\_float(\frac{x}{127})) ++++ - * `CL_SNORM_INT16` (16-bit signed integer) -> `float` + * {CL_SNORM_INT16} (16-bit signed integer) -> `float` + [latexmath] ++++ @@ -614,28 +614,28 @@ normalized\_float\_value(x)=max(-1.0f, round\_to\_float(\frac{x}{32767})) The precision of the above conversions is \<= 1.5 ulp except for the following cases. -For `CL_UNORM_INT8`: +For {CL_UNORM_INT8}: * 0 must convert to 0.0f, and * 255 must convert to 1.0f -For `CL_UNORM_INT_101010`: +For {CL_UNORM_INT_101010}: * 0 must convert to 0.0f, and * 1023 must convert to 1.0f -For `CL_UNORM_INT16`: +For {CL_UNORM_INT16}: * 0 must convert to 0.0f, and * 65535 must convert to 1.0f -For `CL_SNORM_INT8`: +For {CL_SNORM_INT8}: * -128 and -127 must convert to -1.0f, * 0 must convert to 0.0f, and * 127 must convert to 1.0f -For `CL_SNORM_INT16`: +For {CL_SNORM_INT16}: * -32768 and -32767 must convert to -1.0f, * 0 must convert to 0.0f, and @@ -644,16 +644,16 @@ For `CL_SNORM_INT16`: [[converting-floating-point-values-to-normalized-integer-channel-data-types]] ===== Converting Floating-point Values to Normalized Integer Channel Data Types -For images created with image channel data type of `CL_UNORM_INT8` and `CL_UNORM_INT16`, image write instructions will convert the floating-point color value to an 8-bit or 16-bit unsigned integer. +For images created with image channel data type of {CL_UNORM_INT8} and {CL_UNORM_INT16}, image write instructions will convert the floating-point color value to an 8-bit or 16-bit unsigned integer. -For images created with image channel data type of `CL_SNORM_INT8` and `CL_SNORM_INT16`, image write instructions will convert the floating-point color value to an 8-bit or 16-bit signed integer. +For images created with image channel data type of {CL_SNORM_INT8} and {CL_SNORM_INT16}, image write instructions will convert the floating-point color value to an 8-bit or 16-bit signed integer. OpenCL implementations may choose to approximate the rounding mode used in the conversions described below. When approximate rounding is used instead of the preferred rounding, the result of the conversion must satisfy the bound given below. The conversions from half precision floating-point values to normalized integer values are performed is as follows: - * `float` -> `CL_UNORM_INT8` (8-bit unsigned integer) + * `float` -> {CL_UNORM_INT8} (8-bit unsigned integer) + [latexmath] ++++ @@ -675,7 +675,7 @@ The conversions from half precision floating-point values to normalized integer \end{aligned} ++++ - * `float` -> `CL_UNORM_INT_101010` (10-bit unsigned integer) + * `float` -> {CL_UNORM_INT_101010} (10-bit unsigned integer) + [latexmath] ++++ @@ -697,7 +697,7 @@ The conversions from half precision floating-point values to normalized integer \end{aligned} ++++ - * `float` -> `CL_UNORM_INT16` (16-bit unsigned integer) + * `float` -> {CL_UNORM_INT16} (16-bit unsigned integer) + [latexmath] ++++ @@ -719,7 +719,7 @@ The conversions from half precision floating-point values to normalized integer \end{aligned} ++++ - * `float` -> `CL_SNORM_INT8` (8-bit signed integer) + * `float` -> {CL_SNORM_INT8} (8-bit signed integer) + [latexmath] ++++ @@ -741,7 +741,7 @@ The conversions from half precision floating-point values to normalized integer \end{aligned} ++++ - * `float` -> `CL_SNORM_INT16` (16-bit signed integer) + * `float` -> {CL_SNORM_INT16} (16-bit signed integer) + [latexmath] ++++ @@ -766,7 +766,7 @@ The conversions from half precision floating-point values to normalized integer [[conversion-rules-for-half-precision-floating-point-channel-data-type]] ==== Conversion Rules for Half Precision Floating-point Channel Data Type -For images created with a channel data type of `CL_HALF_FLOAT`, the conversions of half to float and half to half are lossless. +For images created with a channel data type of {CL_HALF_FLOAT}, the conversions of half to float and half to half are lossless. Conversions from float to half round the mantissa using the round to nearest even or round to zero rounding mode. Denormalized numbers for the half data type which may be generated when converting a float to a half may be flushed to zero. A float NaN must be converted to an appropriate NaN in the half type. @@ -775,7 +775,7 @@ A float INF must be converted to an appropriate INF in the half type. [[conversion-rules-for-floating-point-channel-data-type]] ==== Conversion Rules for Floating-point Channel Data Type -The following rules apply for reading and writing images created with channel data type of `CL_FLOAT`. +The following rules apply for reading and writing images created with channel data type of {CL_FLOAT}. * NaNs may be converted to a NaN value(s) supported by the device. * Denorms can be flushed to zero. @@ -784,48 +784,48 @@ The following rules apply for reading and writing images created with channel da [[conversion-rules-for-signed-and-unsigned-8-bit-16-bit-and-32-bit-integer-channel-data-types]] ==== Conversion Rules for Signed and Unsigned 8-bit, 16-bit and 32-bit Integer Channel Data Types -For images created with image channel data type of `CL_SIGNED_INT8`, `CL_SIGNED_INT16` and `CL_SIGNED_INT32`, image read instructions will return the unmodified integer values stored in the image at specified location. +For images created with image channel data type of {CL_SIGNED_INT8}, {CL_SIGNED_INT16} and {CL_SIGNED_INT32}, image read instructions will return the unmodified integer values stored in the image at specified location. -Likewise, for images created with image channel data type of `CL_UNSIGNED_INT8`, `CL_UNSIGNED_INT16` and `CL_UNSIGNED_INT32`, image read instructions will return the unmodified unsigned integer values stored in the image at specified location. +Likewise, for images created with image channel data type of {CL_UNSIGNED_INT8}, {CL_UNSIGNED_INT16} and {CL_UNSIGNED_INT32}, image read instructions will return the unmodified unsigned integer values stored in the image at specified location. Image write instructions will perform one of the following conversions: -* 32 bit signed integer -> `CL_SIGNED_INT8` (8-bit signed integer): +* 32 bit signed integer -> {CL_SIGNED_INT8} (8-bit signed integer): + [latexmath] ++++ int8\_value(x) = clamp(x, -128, 127) ++++ -* 32 bit signed integer -> `CL_SIGNED_INT16` (16-bit signed integer): +* 32 bit signed integer -> {CL_SIGNED_INT16} (16-bit signed integer): + [latexmath] ++++ int16\_value(x) = clamp(x, -32768, 32767) ++++ -* 32 bit signed integer -> `CL_SIGNED_INT32` (32-bit signed integer): +* 32 bit signed integer -> {CL_SIGNED_INT32} (32-bit signed integer): + [latexmath] ++++ int32\_value(x) = x \quad \text{(no conversion)} ++++ -* 32 bit unsigned integer -> `CL_UNSIGNED_INT8` (8-bit unsigned integer): +* 32 bit unsigned integer -> {CL_UNSIGNED_INT8} (8-bit unsigned integer): + [latexmath] ++++ uint8\_value(x) = clamp(x, 0, 255) ++++ -* 32 bit unsigned integer -> `CL_UNSIGNED_INT16` (16-bit unsigned integer): +* 32 bit unsigned integer -> {CL_UNSIGNED_INT16} (16-bit unsigned integer): + [latexmath] ++++ uint16\_value(x) = clamp(x, 0, 65535) ++++ -* 32 bit unsigned integer -> `CL_UNSIGNED_INT32` (32-bit unsigned integer): +* 32 bit unsigned integer -> {CL_UNSIGNED_INT32} (32-bit unsigned integer): + [latexmath] ++++ diff --git a/env/numerical_compliance.asciidoc b/env/numerical_compliance.asciidoc index ee339a948..bbb895b73 100644 --- a/env/numerical_compliance.asciidoc +++ b/env/numerical_compliance.asciidoc @@ -29,8 +29,8 @@ IEEE 754 defines four possible rounding modes: * _Round toward zero_ The complete set of rounding modes supported by the device are described by -the `CL_DEVICE_SINGLE_FP_CONFIG`, `CL_DEVICE_HALF_FP_CONFIG`, and -`CL_DEVICE_DOUBLE_FP_CONFIG` device queries. +the {CL_DEVICE_SINGLE_FP_CONFIG}, {CL_DEVICE_HALF_FP_CONFIG}, and +{CL_DEVICE_DOUBLE_FP_CONFIG} device queries. For double precision operations, _Round to nearest even_ is a required rounding mode, and is therefore the default rounding mode for double @@ -98,8 +98,8 @@ Support for denormalized numbers is required for double precision floating-point. Support for INFs, NaNs, and denormalized numbers is described by the -`CL_FP_DENORM` and `CL_FP_INF_NAN` bits in the `CL_DEVICE_SINGLE_FP_CONFIG`, -`CL_DEVICE_HALF_FP_CONFIG`, and `CL_DEVICE_DOUBLE_FP_CONFIG` device queries. +{CL_FP_DENORM} and {CL_FP_INF_NAN} bits in the {CL_DEVICE_SINGLE_FP_CONFIG}, +{CL_DEVICE_HALF_FP_CONFIG}, and {CL_DEVICE_DOUBLE_FP_CONFIG} device queries. === Floating-Point Exceptions diff --git a/ext/introduction.asciidoc b/ext/introduction.asciidoc index 311549b02..9c22399cc 100644 --- a/ext/introduction.asciidoc +++ b/ext/introduction.asciidoc @@ -45,8 +45,8 @@ naming convention: * A unique _name string_ of the form `"*cl_khr_<__name__>*"` is associated with each extension. If the extension is supported by an implementation, this string will be - present in the implementation's `CL_PLATFORM_EXTENSIONS` string or - `CL_DEVICE_EXTENSIONS` string. + present in the implementation's {CL_PLATFORM_EXTENSIONS} string or + {CL_DEVICE_EXTENSIONS} string. * All API functions defined by the extension will have names of the form *cl<__function_name__>KHR*. * All enumerants defined by the extension will have names of the form @@ -55,8 +55,8 @@ naming convention: Functions and enumerants defined by extensions that are promoted to core features will have their *KHR* affix removed. OpenCL implementations of such later revisions must also export the name -strings of promoted extensions in the `CL_PLATFORM_EXTENSIONS` or -`CL_DEVICE_EXTENSIONS` string, and support the *KHR*-affixed versions of +strings of promoted extensions in the {CL_PLATFORM_EXTENSIONS} or +{CL_DEVICE_EXTENSIONS} string, and support the *KHR*-affixed versions of functions and enumerants as a transition aid. Vendor extensions are strongly encouraged to follow a similar naming @@ -65,8 +65,8 @@ convention: * A unique _name string_ of the form `"*cl_<__vendor_name__>_<__name>__*"` is associated with each extension. If the extension is supported by an implementation, this string will be - present in the implementation's `CL_PLATFORM_EXTENSIONS` string or - `CL_DEVICE_EXTENSIONS` string. + present in the implementation's {CL_PLATFORM_EXTENSIONS} string or + {CL_DEVICE_EXTENSIONS} string. * All API functions defined by the vendor extension will have names of the form *cl<__function_name__><__vendor_name__>*. * All enumerants defined by the vendor extension will have names of the @@ -175,12 +175,12 @@ type matching the extension function's definition defined in the appropriate extension specification and header file. A return value of `NULL` indicates that the specified function does not exist for the implementation or _platform_ is not a valid platform. -A non-`NULL` return value for *clGetExtensionFunctionAddressForPlatform* +A non-`NULL` return value for {clGetExtensionFunctionAddressForPlatform} does not guarantee that an extension function is actually supported by the platform. The application must also make a corresponding query using -*clGetPlatformInfo*(platform, CL_PLATFORM_EXTENSIONS, ...) or -*clGetDeviceInfo*(device, CL_DEVICE_EXTENSIONS, ...) to determine if an +{clGetPlatformInfo}(platform, CL_PLATFORM_EXTENSIONS, ...) or +{clGetDeviceInfo}(device, CL_DEVICE_EXTENSIONS, ...) to determine if an extension is supported by the OpenCL implementation. Since there is no way to qualify the query with a @@ -189,10 +189,10 @@ that extension on different devices for a platform. The behavior of calling a device extension function on a device not supporting that extension is undefined. -*clGetExtensionFunctionAddressForPlatform* may not be be used to query for core +{clGetExtensionFunctionAddressForPlatform} may not be be used to query for core (non-extension) functions in OpenCL. For extension functions that may be queried using -*clGetExtensionFunctionAddressForPlatform*, implementations may also choose to +{clGetExtensionFunctionAddressForPlatform}, implementations may also choose to export those functions statically from the object libraries implementing those functions, however, portable applications cannot rely on this behavior. diff --git a/man/static/clGetExtensionFunctionAddressForPlatform.txt b/man/static/clGetExtensionFunctionAddressForPlatform.txt index 0004c2a2d..7a63323cc 100644 --- a/man/static/clGetExtensionFunctionAddressForPlatform.txt +++ b/man/static/clGetExtensionFunctionAddressForPlatform.txt @@ -32,8 +32,8 @@ The pointer returned should be cast to a function pointer type matching the exte A return value of NULL indicates that the specified function does not exist for the implementation or _platform_ is not a valid platform. A non-NULL return value for `clGetExtensionFunctionAddressForPlatform` does not guarantee that an extension function is actually supported by the platform. -The application must also make a corresponding query using flink:clGetPlatformInfo (platform, `CL_PLATFORM_EXTENSIONS`, ... ) or -flink:clGetDeviceInfo (device,`CL_DEVICE_EXTENSIONS`, ... ) to determine if an extension is supported by the OpenCL implementation. +The application must also make a corresponding query using flink:clGetPlatformInfo (platform, {CL_PLATFORM_EXTENSIONS}, ... ) or +flink:clGetDeviceInfo (device,{CL_DEVICE_EXTENSIONS}, ... ) to determine if an extension is supported by the OpenCL implementation. `clGetExtensionFunctionAddressForPlatform` may not be queried for core (non-extension) functions in OpenCL. For functions that are queryable with `clGetExtensionFunctionAddressForPlatform`, implementations may choose to also export those functions statically from the object libraries implementing those functions. diff --git a/scripts/gen_dictionaries.py b/scripts/gen_dictionaries.py index 85d6ffcff..045646c4d 100755 --- a/scripts/gen_dictionaries.py +++ b/scripts/gen_dictionaries.py @@ -162,6 +162,66 @@ def GetFooter(): print('Found ' + str(numberOfEnums) + ' API enumerations.') + # Generate the API macro dictionaries: + + numberOfMacros = 0 + + for types in spec.findall('types'): + for type in types.findall('type'): + name = "" + category = type.get('category') + if category == 'define': + if type.text and type.text.startswith("#define"): + name = type.find('name').text + else: + continue + else: + continue + + #print('found macro: ' +name) + + # Create a variant of the name that precedes underscores with + # "zero width" spaces. This causes some long names to be + # broken at more intuitive places. + htmlName = name[:3] + name[3:].replace("_", "_") + otherName = name[:3] + name[3:].replace("_", "_​") + + # Example with link: + # + # // CL_MAKE_VERSION + #:CL_MAKE_VERSION_label: pass:q[`CL_MAKE_VERSION`] + #:CL_MAKE_VERSION: <> + #:CL_MAKE_VERSION_anchor: [[CL_MAKE_VERSION]]{CL_MAKE_VERSION} + linkFile.write('// ' + name + '\n') + linkFile.write('ifdef::backend-html5[]\n') + linkFile.write(':' + name + '_label: pass:q[`' + htmlName + '`]\n') + linkFile.write('endif::[]\n') + linkFile.write('ifndef::backend-html5[]\n') + linkFile.write(':' + name + '_label: pass:q[`' + otherName + '`]\n') + linkFile.write('endif::[]\n') + linkFile.write(':' + name + ': <<' + name + ',{' + name + '_label}>>\n') + linkFile.write(':' + name + '_anchor: [[' + name + ']]{' + name + '}\n') + linkFile.write('\n') + + # Example without link: + # + # // CL_MAKE_VERSION + #:CL_MAKE_VERSION: pass:q[`CL_MAKE_VERSION`] + #:CL_MAKE_VERSION_anchor: {CL_MAKE_VERSION} + nolinkFile.write('// ' + name + '\n') + nolinkFile.write('ifdef::backend-html5[]\n') + nolinkFile.write(':' + name + ': pass:q[`' + htmlName + '`]\n') + nolinkFile.write('endif::[]\n') + nolinkFile.write('ifndef::backend-html5[]\n') + nolinkFile.write(':' + name + ': pass:q[`' + otherName + '`]\n') + nolinkFile.write('endif::[]\n') + nolinkFile.write(':' + name + '_anchor: {' + name + '}\n') + nolinkFile.write('\n') + + numberOfMacros = numberOfMacros + 1 + + print('Found ' + str(numberOfMacros) + ' API macros.') + # Generate the API types dictionaries: numberOfTypes = 0 @@ -177,6 +237,8 @@ def GetFooter(): addLink = True name = type.get('name') elif category == 'define': + if type.text and type.text.startswith("#define"): + continue name = type.find('name').text else: continue diff --git a/xml/cl.xml b/xml/cl.xml index b0c5cc2ed..63f3145ce 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -323,6 +323,20 @@ server's OpenCL/api-docs repository. cl_uint count char name[CL_QUEUE_FAMILY_MAX_NAME_SIZE_INTEL] + + #define CL_VERSION_MAJOR_MASK ((1 << CL_VERSION_MAJOR_BITS) - 1) + #define CL_VERSION_MINOR_MASK ((1 << CL_VERSION_MINOR_BITS) - 1) + #define CL_VERSION_PATCH_MASK ((1 << CL_VERSION_PATCH_BITS) - 1) + + #define CL_VERSION_MAJOR(version) ((version) >> (CL_VERSION_MINOR_BITS + CL_VERSION_PATCH_BITS)) + #define CL_VERSION_MINOR(version) (((version) >> CL_VERSION_PATCH_BITS) & CL_VERSION_MINOR_MASK) + #define CL_VERSION_PATCH(version) ((version) & CL_VERSION_PATCH_MASK) + + #define CL_MAKE_VERSION(major, minor, patch) \ + ((((major) & CL_VERSION_MAJOR_MASK) << (CL_VERSION_MINOR_BITS + CL_VERSION_PATCH_BITS)) | \ + (((minor) & CL_VERSION_MINOR_MASK) << CL_VERSION_PATCH_BITS) | \ + ((patch) & CL_VERSION_PATCH_MASK)) + #define CL_VERSION_MAJOR_MASK_KHR ((1 << CL_VERSION_MAJOR_BITS_KHR) - 1) #define CL_VERSION_MINOR_MASK_KHR ((1 << CL_VERSION_MINOR_BITS_KHR) - 1) #define CL_VERSION_PATCH_MASK_KHR ((1 << CL_VERSION_PATCH_BITS_KHR) - 1) @@ -335,6 +349,7 @@ server's OpenCL/api-docs repository. ((((major) & CL_VERSION_MAJOR_MASK_KHR) << (CL_VERSION_MINOR_BITS_KHR + CL_VERSION_PATCH_BITS_KHR)) | \ (((minor) & CL_VERSION_MINOR_MASK_KHR) << CL_VERSION_PATCH_BITS_KHR) | \ ((patch) & CL_VERSION_PATCH_MASK_KHR)) + cl_bool signed_accelerated cl_bool unsigned_accelerated @@ -5348,6 +5363,15 @@ server's OpenCL/api-docs repository. + + + + + + + + + From 75df78c0195a3237da96d576c3c72f94b1b6582c Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Tue, 2 Apr 2024 13:03:48 -0700 Subject: [PATCH 24/71] spec source for cl_khr_kernel_clock (#1103) * spec source for cl_khr_kernel_clock * updated after March 26th teleconference Clarified that this is a provisional extension Removed ext from feature names and feature test macros Added undefined behavior description to the SPIR-V environment spec * fix a few more places where the extension should be marked provisional * clarify in a few more places that this extension is provisional * remove provisional_notice.asciidoc, since it should not be used anymore --- OpenCL_API.txt | 2 +- OpenCL_C.txt | 82 +++++++++++++++++++++++++++++- api/appendix_e.asciidoc | 5 ++ api/cl_khr_kernel_clock.asciidoc | 62 ++++++++++++++++++++++ api/opencl_platform_layer.asciidoc | 37 ++++++++++++++ c/feature-dictionary.asciidoc | 24 +++++++++ env/extensions.asciidoc | 16 ++++++ ext/provisional_notice.asciidoc | 12 ----- ext/quick_reference.asciidoc | 4 ++ xml/cl.xml | 27 +++++++++- 10 files changed, 255 insertions(+), 16 deletions(-) create mode 100644 api/cl_khr_kernel_clock.asciidoc delete mode 100644 ext/provisional_notice.asciidoc diff --git a/OpenCL_API.txt b/OpenCL_API.txt index 2be2268ca..e7e67a578 100644 --- a/OpenCL_API.txt +++ b/OpenCL_API.txt @@ -39,7 +39,7 @@ include::config/version-local-links.asciidoc[] // Formatting and links for API functions and enums. include::api/dictionary.asciidoc[] -// Feature Dictionary - used by some extensions. +// Feature Dictionary. include::c/feature-dictionary.asciidoc[] // External Footnotes diff --git a/OpenCL_C.txt b/OpenCL_C.txt index dd372a8bb..0935f4fa7 100644 --- a/OpenCL_C.txt +++ b/OpenCL_C.txt @@ -224,14 +224,28 @@ ifdef::cl_khr_integer_dot_product[] (when the `<>` extension macro is defined) | The OpenCL C compiler supports built-in functions that perform dot -products on 4x8 bit packed integer vectors +products on 4x8 bit packed integer vectors. | {opencl_c_integer_dot_product_input_4x8bit} + (when the `<>` extension macro is defined) | The OpenCL C compiler supports built-in functions that perform dot -products on 4x8 bit integer vectors +products on 4x8 bit integer vectors. endif::cl_khr_integer_dot_product[] +ifdef::cl_khr_kernel_clock[] +| {opencl_c_kernel_clock_scope_device} +| The OpenCL C compiler supports built-in functions that sample the value from a +clock shared by all work-items executing on the device. + +| {opencl_c_kernel_clock_scope_work_group} +| The OpenCL C compiler supports built-in functions that sample the value from a +clock shared by all work-items executing in the same work-group. + +| {opencl_c_kernel_clock_scope_sub_group} +| The OpenCL C compiler supports built-in functions that sample the value from a +clock shared by all work-items executing in the same sub-group. +endif::cl_khr_kernel_clock[] + |==== In OpenCL C 3.0 or newer, feature macros must expand to the value `1` if the @@ -462,6 +476,16 @@ The extension provides new <> operating on these types. endif::cl_khr_integer_dot_product[] +ifdef::cl_khr_kernel_clock[] +[[cl_khr_kernel_clock,cl_khr_kernel_clock]] +==== Kernel Clock + +The `cl_khr_kernel_clock` extension adds support for SPIR-V instructions and +OpenCL C built-in functions to sample the value from one of three clocks +provided by compute units. The extension provides the following functions: + +* <> +endif::cl_khr_kernel_clock[] ifdef::cl_khr_local_int32_base_atomics[] [[cl_khr_local_int32_base_atomics,cl_khr_local_int32_base_atomics]] @@ -15306,6 +15330,60 @@ endif::cl_khr_subgroup_shuffle_relative[] |==== +ifdef::cl_khr_kernel_clock[] +[[kernel-clock-functions]] +=== Kernel Clock Functions + +NOTE: The functionality described in this section <> +support for the `<>` extension. + +The `clock_read_device` and `clock_read_hilo_device` functions require support +for the {opencl_c_kernel_clock_scope_device} feature. +The `clock_read_work_group` and `clock_read_hilo_work_group` functions require +support for the {opencl_c_kernel_clock_scope_work_group} feature. +The `clock_read_sub_group` and `clock_read_hilo_sub_group` functions require +support for the {opencl_c_kernel_clock_scope_sub_group} feature. + +This section describes OpenCL C built-in functions that sample the value from +one of three clocks provided by compute units. + +[[table-kernel-clock-functions]] +.Built-in Kernel Clock Functions +[cols="1a,1",options="header",] +|==== +| Function | Description + +|[source,opencl_c] +---- +ulong clock_read_device(); +ulong clock_read_work_group(); +ulong clock_read_sub_group(); +---- + | Returns a sampled value of a clock as seen by the compute unit. + + An idealized clock is an unbounded unsigned scalar integer tick count + increasing monotonically over time. A clock’s rate of progress may vary + within the lifetime of a work-item, may vary across different + executions of the program, and may be affected by conditions beyond the + control of the programmer. The sampled value read by this function consists of + the least significant bits of the idealized clock’s tick count at the time the + instruction was executed. In particular, an observer may see sampled values wrap + around zero. + +|[source,opencl_c] +---- +uint2 clock_read_hilo_device(); +uint2 clock_read_hilo_work_group(); +uint2 clock_read_hilo_sub_group(); +---- + | Performs the same operation as `clock_read`, but returns the value as a + `uint2` whose `.lo` component contains the 32 least significant bits of the + result and `.hi` component contains the 32 most significant bits of the + result. + +|==== + +endif::cl_khr_kernel_clock[] + [[opencl-numerical-compliance]] = OpenCL Numerical Compliance diff --git a/api/appendix_e.asciidoc b/api/appendix_e.asciidoc index c88b80933..ec6626c2a 100644 --- a/api/appendix_e.asciidoc +++ b/api/appendix_e.asciidoc @@ -598,3 +598,8 @@ Changes from *v3.0.14*: ** Restricted semaphores to a single associated device, see {khronos-opencl-pr}/996[#996]. * `<>`: ** Clarified that only rotating within a subgroup is supported, see {khronos-opencl-pr}/967[#967]. + +Changes from *v3.0.15*: + + * Added new extensions: + ** `<>` (provisional) diff --git a/api/cl_khr_kernel_clock.asciidoc b/api/cl_khr_kernel_clock.asciidoc new file mode 100644 index 000000000..7f4c4a0de --- /dev/null +++ b/api/cl_khr_kernel_clock.asciidoc @@ -0,0 +1,62 @@ +// Copyright 2024 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}cl_khr_kernel_clock.txt[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2024-03-25 +*IP Status*:: + No known IP claims. +*Contributors*:: + - Kevin Petit, Arm Ltd. + + - Paul Fradgley, Imagination Technologies + + - Jeremy Kemp, Imagination Technologies + + - Ben Ashbaugh, Intel + + - Balaji Calidas, Qualcomm Technologies, Inc. + + - Ruihao Zhang, Qualcomm Technologies, Inc. + +=== Description + +`cl_khr_kernel_clock` adds the ability for a kernel to sample the value from one +of three clocks provided by compute units. + +OpenCL C compilers supporting this extension will define the extension macro +`cl_khr_kernel_clock`, and may define corresponding feature macros +{opencl_c_kernel_clock_scope_device}, +{opencl_c_kernel_clock_scope_work_group}, and +{opencl_c_kernel_clock_scope_sub_group} depending on the reported +capabilities. + +See the link:{OpenCLCSpecURL}#cl_khr_kernel_clock[Kernel Clock] section of the +OpenCL C specification for more information. + +=== Interactions With Other Extensions + +On devices that implement the `EMBEDDED` profile, the `cles_khr_int64` extension +is required for the `clock_read_device`, `clock_read_work_group` and +`clock_read_sub_group` functions to be present. + +Support for sub-groups is required for the `clock_read_sub_group` and +`clock_read_hilo_sub_group` functions to be present. + +// The 'New ...' section can be auto-generated + +=== New Types + + * {cl_device_kernel_clock_capabilities_khr_TYPE} + +=== New Enums + + * {cl_device_info_TYPE} + ** {CL_DEVICE_KERNEL_CLOCK_CAPABILITIES_KHR} + * {cl_device_kernel_clock_capabilities_khr_TYPE} + ** {CL_DEVICE_KERNEL_CLOCK_SCOPE_DEVICE_KHR} + ** {CL_DEVICE_KERNEL_CLOCK_SCOPE_WORK_GROUP_KHR} + ** {CL_DEVICE_KERNEL_CLOCK_SCOPE_SUB_GROUP_KHR} + +=== Version History + + * Revision 0.9.0, 2024-03-25 + ** First assigned version (provisional). diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index 6211b1384..7c39cb51e 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -1985,6 +1985,26 @@ include::{generated}/api/version-notes/CL_DEVICE_INTEGER_DOT_PRODUCT_ACCELERATIO is missing before version 2.0 of the extension. endif::cl_khr_integer_dot_product[] +ifdef::cl_khr_kernel_clock[] +| {CL_DEVICE_KERNEL_CLOCK_CAPABILITIES_KHR_anchor} + +include::{generated}/api/version-notes/CL_DEVICE_KERNEL_CLOCK_CAPABILITIES_KHR.asciidoc[] + | {cl_device_kernel_clock_capabilities_khr_TYPE} + | Returns the kernel clock capabilities of the device. + + + {CL_DEVICE_KERNEL_CLOCK_SCOPE_DEVICE_KHR_anchor} is set when kernels are + allowed to call the `clock_read_device` and `clock_read_hilo_device` + OpenCL-C functions. + + {CL_DEVICE_KERNEL_CLOCK_SCOPE_WORK_GROUP_KHR_anchor} is set when kernels + are allowed to call the `clock_read_work_group` and + `clock_read_hilo_work_group` OpenCL-C functions. + + {CL_DEVICE_KERNEL_CLOCK_SCOPE_SUB_GROUP_KHR_anchor} is set when kernels + are allowed to call the `clock_read_sub_group` and + `clock_read_hilo_sub_group` OpenCL-C functions. +endif::cl_khr_kernel_clock[] + ifdef::cl_khr_pci_bus_info[] | {CL_DEVICE_PCI_BUS_INFO_KHR_anchor} @@ -2080,6 +2100,23 @@ returned for {CL_DEVICE_INTEGER_DOT_PRODUCT_CAPABILITIES_KHR}: |==== endif::cl_khr_integer_dot_product[] +ifdef::cl_khr_kernel_clock[] +OpenCL 3 devices must report the following feature macros via +{CL_DEVICE_OPENCL_C_FEATURES} when the corresponding bit is set in the bitfield +returned for {CL_DEVICE_KERNEL_CLOCK_CAPABILITIES_KHR}: + +[cols="1,1",options="header"] +|==== +| Feature Bit | Feature Macro +| {CL_DEVICE_KERNEL_CLOCK_SCOPE_DEVICE_KHR} + | {opencl_c_kernel_clock_scope_device} +| {CL_DEVICE_KERNEL_CLOCK_SCOPE_WORK_GROUP_KHR} + | {opencl_c_kernel_clock_scope_work_group} +| {CL_DEVICE_KERNEL_CLOCK_SCOPE_SUB_GROUP_KHR} + | {opencl_c_kernel_clock_scope_sub_group} +|==== +endif::cl_khr_kernel_clock[] + ifdef::cl_khr_external_semaphore[] One of the two queries {CL_DEVICE_SEMAPHORE_IMPORT_HANDLE_TYPES_KHR} and {CL_DEVICE_SEMAPHORE_EXPORT_HANDLE_TYPES_KHR} must return a non-empty list diff --git a/c/feature-dictionary.asciidoc b/c/feature-dictionary.asciidoc index 4943b36b5..e8375eb57 100644 --- a/c/feature-dictionary.asciidoc +++ b/c/feature-dictionary.asciidoc @@ -145,3 +145,27 @@ endif::[] ifndef::backend-html5[] :opencl_c_integer_dot_product_input_4x8bit_packed: pass:q[`\__opencl_c_​integer_​dot_​product_​input_​4x8bit_​packed`] endif::[] + +// opencl_c_kernel_clock_scope_device +ifdef::backend-html5[] +:opencl_c_kernel_clock_scope_device: pass:q[`\__opencl_c_kernel_clock_scope_device`] +endif::[] +ifndef::backend-html5[] +:opencl_c_kernel_clock_scope_device: pass:q[`\__opencl_c_​kernel_​clock_​scope_​device`] +endif::[] + +// opencl_c_kernel_clock_scope_work_group +ifdef::backend-html5[] +:opencl_c_kernel_clock_scope_work_group: pass:q[`\__opencl_c_kernel_clock_scope_work_group`] +endif::[] +ifndef::backend-html5[] +:opencl_c_kernel_clock_scope_work_group: pass:q[`\__opencl_c_​kernel_​clock_​scope_​work_​group`] +endif::[] + +// opencl_c_kernel_clock_scope_sub_group +ifdef::backend-html5[] +:opencl_c_kernel_clock_scope_sub_group: pass:q[`\__opencl_c_kernel_clock_scope_sub_group`] +endif::[] +ifndef::backend-html5[] +:opencl_c_kernel_clock_scope_sub_group: pass:q[`\__opencl_c_​kernel_​clock_​scope_​sub_​group`] +endif::[] diff --git a/env/extensions.asciidoc b/env/extensions.asciidoc index 4ef4fd7a6..df0259550 100644 --- a/env/extensions.asciidoc +++ b/env/extensions.asciidoc @@ -379,6 +379,22 @@ Otherwise, for the *GroupUniformArithmeticKHR* scan and reduction instructions, ** *OpTypeInt* with _Width_ equal to `32` or `64` (equivalent to `int`, `uint`, `long`, and `ulong`) ** *OpTypeFloat* (equivalent to `half`, `float`, and `double`) +==== `cl_khr_kernel_clock` + +If the OpenCL environment supports the extension `cl_khr_kernel_clock`, then the environment must accept modules that declare use of the extension `SPV_KHR_shader_clock` via *OpExtension*. + +If the OpenCL environment supports the extension `cl_khr_kernel_clock` and use of the SPIR-V extension `SPV_KHR_shader_clock` is declared in the module via *OpExtension*, then the environment must accept modules that declare the following SPIR-V capability: + +* *ShaderClockKHR* + +For the *OpReadClockKHR* instruction requiring this capability, supported values for _Scope_ are: + +* *Device*, if `CL_DEVICE_KERNEL_CLOCK_SCOPE_DEVICE_KHR` is supported +* *Workgroup*, if `CL_DEVICE_KERNEL_CLOCK_SCOPE_WORK_GROUP_KHR` is supported +* *Subgroup*, if `CL_DEVICE_KERNEL_CLOCK_SCOPE_SUB_GROUP_KHR` is supported + +For unsupported _Scope_ values, the behavior of *OpReadClockKHR* is undefined. + === Embedded Profile Extensions ==== `cles_khr_int64` diff --git a/ext/provisional_notice.asciidoc b/ext/provisional_notice.asciidoc deleted file mode 100644 index 0cc0eb0d0..000000000 --- a/ext/provisional_notice.asciidoc +++ /dev/null @@ -1,12 +0,0 @@ -// Copyright 2023-2024 The Khronos Group. This work is licensed under a -// Creative Commons Attribution 4.0 International License; see -// http://creativecommons.org/licenses/by/4.0/ - -[NOTE] -==== -This is a provisional OpenCL extension specification that has been Ratified under the Khronos Intellectual Property Framework. -It is being made publicly available as a provisional extension to enable review and feedback from the community. -While it is a provisional extension features may be added, removed, or changed in non-backward compatible ways. - -If you have feedback please create an issue on: https://github.com/KhronosGroup/OpenCL-Docs/ -==== \ No newline at end of file diff --git a/ext/quick_reference.asciidoc b/ext/quick_reference.asciidoc index 6fddf7120..194c6df9d 100644 --- a/ext/quick_reference.asciidoc +++ b/ext/quick_reference.asciidoc @@ -208,6 +208,10 @@ Language Specifications. | Integer dot product operations | Extension +| [[cl_khr_kernel_clock]] link:{APISpecURL}#cl_khr_kernel_clock[`cl_khr_kernel_clock`] +| Sample Clock Values Within a Kernel +| Extension + | [[cl_khr_mipmap_image]] link:{APISpecURL}#cl_khr_mipmap_image[`cl_khr_mipmap_image`] | Create and Use Images with Mipmaps | Extension diff --git a/xml/cl.xml b/xml/cl.xml index 63f3145ce..6f1ae87bd 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -254,6 +254,7 @@ server's OpenCL/api-docs repository. typedef cl_uint cl_image_requirements_info_ext; 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; Structure types @@ -1386,6 +1387,13 @@ server's OpenCL/api-docs repository. + + + + + + + In order to synchronize vendor IDs across Khronos APIs, Vulkan's vk.xml @@ -1545,7 +1553,8 @@ server's OpenCL/api-docs repository. - + + @@ -7477,5 +7486,21 @@ server's OpenCL/api-docs repository. + + + + + + + + + + + + + + + + From c285aa9580d7071c4887b1858c85046dccc65b23 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Tue, 2 Apr 2024 17:29:40 -0700 Subject: [PATCH 25/71] generate and use an extension dictionary (#1131) * generate and use an extension dictionary * change cl_khr_kernel_clock to use asciidoctor attributes --- OpenCL_C.txt | 332 +++++++++--------- api/appendix_c.asciidoc | 20 +- api/appendix_e.asciidoc | 118 +++---- api/appendix_h.asciidoc | 6 +- api/cl_khr_3d_image_writes.asciidoc | 2 +- ...l_khr_async_work_group_copy_fence.asciidoc | 2 +- api/cl_khr_byte_addressable_store.asciidoc | 2 +- api/cl_khr_command_buffer.asciidoc | 34 +- ...l_khr_command_buffer_multi_device.asciidoc | 6 +- ...r_command_buffer_mutable_dispatch.asciidoc | 10 +- api/cl_khr_create_command_queue.asciidoc | 2 +- api/cl_khr_d3d10_sharing.asciidoc | 2 +- api/cl_khr_d3d11_sharing.asciidoc | 2 +- api/cl_khr_depth_images.asciidoc | 2 +- ...hr_device_enqueue_local_arg_types.asciidoc | 2 +- api/cl_khr_device_uuid.asciidoc | 2 +- api/cl_khr_dx9_media_sharing.asciidoc | 2 +- api/cl_khr_egl_event.asciidoc | 4 +- api/cl_khr_egl_image.asciidoc | 4 +- api/cl_khr_expect_assume.asciidoc | 2 +- api/cl_khr_extended_async_copies.asciidoc | 2 +- api/cl_khr_extended_bit_ops.asciidoc | 2 +- api/cl_khr_extended_versioning.asciidoc | 4 +- api/cl_khr_external_memory.asciidoc | 6 +- api/cl_khr_external_memory_dma_buf.asciidoc | 4 +- api/cl_khr_external_memory_dx.asciidoc | 4 +- api/cl_khr_external_memory_opaque_fd.asciidoc | 4 +- api/cl_khr_external_memory_win32.asciidoc | 4 +- api/cl_khr_external_semaphore.asciidoc | 16 +- ...l_khr_external_semaphore_dx_fence.asciidoc | 4 +- ..._khr_external_semaphore_opaque_fd.asciidoc | 4 +- ...cl_khr_external_semaphore_sync_fd.asciidoc | 6 +- api/cl_khr_external_semaphore_win32.asciidoc | 4 +- api/cl_khr_fp16.asciidoc | 2 +- api/cl_khr_fp64.asciidoc | 2 +- api/cl_khr_gl_depth_images.asciidoc | 4 +- api/cl_khr_gl_event.asciidoc | 2 +- api/cl_khr_gl_msaa_sharing.asciidoc | 4 +- api/cl_khr_gl_sharing.asciidoc | 4 +- api/cl_khr_global_int32_base_atomics.asciidoc | 2 +- ...khr_global_int32_extended_atomics.asciidoc | 2 +- api/cl_khr_icd.asciidoc | 4 +- api/cl_khr_il_program.asciidoc | 2 +- api/cl_khr_image2d_from_buffer.asciidoc | 2 +- api/cl_khr_initialize_memory.asciidoc | 2 +- api/cl_khr_int64_base_atomics.asciidoc | 2 +- api/cl_khr_int64_extended_atomics.asciidoc | 2 +- api/cl_khr_integer_dot_product.asciidoc | 4 +- api/cl_khr_local_int32_base_atomics.asciidoc | 2 +- ..._khr_local_int32_extended_atomics.asciidoc | 2 +- api/cl_khr_mipmap_image.asciidoc | 2 +- api/cl_khr_mipmap_image_writes.asciidoc | 6 +- api/cl_khr_pci_bus_info.asciidoc | 2 +- api/cl_khr_priority_hints.asciidoc | 4 +- api/cl_khr_select_fprounding_mode.asciidoc | 2 +- api/cl_khr_semaphore.asciidoc | 2 +- api/cl_khr_spir.asciidoc | 6 +- api/cl_khr_srgb_image_writes.asciidoc | 2 +- api/cl_khr_subgroup_ballot.asciidoc | 2 +- api/cl_khr_subgroup_clustered_reduce.asciidoc | 2 +- api/cl_khr_subgroup_extended_types.asciidoc | 2 +- api/cl_khr_subgroup_named_barrier.asciidoc | 2 +- ...r_subgroup_non_uniform_arithmetic.asciidoc | 2 +- api/cl_khr_subgroup_non_uniform_vote.asciidoc | 2 +- api/cl_khr_subgroup_rotate.asciidoc | 2 +- api/cl_khr_subgroup_shuffle.asciidoc | 2 +- api/cl_khr_subgroup_shuffle_relative.asciidoc | 2 +- api/cl_khr_subgroups.asciidoc | 2 +- api/cl_khr_suggested_local_work_size.asciidoc | 2 +- api/cl_khr_terminate_context.asciidoc | 2 +- api/cl_khr_throttle_hints.asciidoc | 4 +- ...khr_work_group_uniform_arithmetic.asciidoc | 2 +- api/dictionary.asciidoc | 1 + api/footnotes.asciidoc | 2 +- api/opencl_architecture.asciidoc | 6 +- api/opencl_platform_layer.asciidoc | 62 ++-- api/opencl_runtime_layer.asciidoc | 252 ++++++------- c/dictionary.asciidoc | 1 + c/footnotes.asciidoc | 14 +- env/appendix_a.asciidoc | 20 +- env/common_properties.asciidoc | 4 +- env/dictionary.asciidoc | 1 + env/extensions.asciidoc | 130 +++---- ext/deprecated_extensions.asciidoc | 2 +- ext/dictionary.asciidoc | 1 + ext/introduction.asciidoc | 4 +- ext/quick_reference.asciidoc | 154 ++++---- ext/to_core_features.asciidoc | 66 ++-- scripts/clconventions.py | 1 + scripts/gen_dictionaries.py | 272 +++++++++----- 90 files changed, 909 insertions(+), 804 deletions(-) diff --git a/OpenCL_C.txt b/OpenCL_C.txt index 0935f4fa7..79a27f8f6 100644 --- a/OpenCL_C.txt +++ b/OpenCL_C.txt @@ -221,13 +221,13 @@ operations across a work-group. ifdef::cl_khr_integer_dot_product[] | {opencl_c_integer_dot_product_input_4x8bit_packed} + - (when the `<>` extension macro is defined) + (when the {cl_khr_integer_dot_product_EXT} extension macro is defined) | The OpenCL C compiler supports built-in functions that perform dot products on 4x8 bit packed integer vectors. | {opencl_c_integer_dot_product_input_4x8bit} + - (when the `<>` extension macro is defined) + (when the {cl_khr_integer_dot_product_EXT} extension macro is defined) | The OpenCL C compiler supports built-in functions that perform dot products on 4x8 bit integer vectors. endif::cl_khr_integer_dot_product[] @@ -289,7 +289,7 @@ ifdef::cl_khr_3d_image_writes[] [[cl_khr_3d_image_writes,cl_khr_3d_image_writes]] ==== 3D Image Writes -The `cl_khr_3d_image_writes` extension was promoted to OpenCL 2.0, and to +The {cl_khr_3d_image_writes_EXT} extension was promoted to OpenCL 2.0, and to OpenCL 3.0 as the {opencl_c_3d_image_writes} feature. The extension adds <> that allow a kernel to write to 3D image objects in addition to @@ -301,7 +301,7 @@ ifdef::cl_khr_async_work_group_copy_fence[] [[cl_khr_async_work_group_copy_fence,cl_khr_async_work_group_copy_fence]] ==== Async Work-group Copy Fence -The `cl_khr_async_work_group_copy_fence` extension supports establishing a +The {cl_khr_async_work_group_copy_fence_EXT} extension supports establishing a memory synchronization ordering of asynchronous copies. The extension provides the `async_work_group_copy_fence` function, as described in the <> on pointers to `char`, `uchar`, `char2`, `uchar2`, `short`, `ushort` and `half`, allowing applications to read from and write to pointers to these types. @@ -324,7 +324,7 @@ ifdef::cl_khr_depth_images[] [[cl_khr_depth_images,cl_khr_depth_images]] ==== Depth Images -The `cl_khr_depth_images` extension was promoted to OpenCL 2.0. +The {cl_khr_depth_images_EXT} extension was promoted to OpenCL 2.0. The extension provides new <>, as well as <>, <>, @@ -337,7 +337,7 @@ ifdef::cl_khr_device_enqueue_local_arg_types[] [[cl_khr_device_enqueue_local_arg_types,cl_khr_device_enqueue_local_arg_types]] ==== Device Enqueue Local Argument Types -The `cl_khr_device_enqueue_local_arg_types` extension allows arguments to +The {cl_khr_device_enqueue_local_arg_types_EXT} extension allows arguments to blocks that are passed to the <> and to the <> to be pointers to any type (built-in or @@ -350,7 +350,7 @@ ifdef::cl_khr_extended_async_copies[] [[cl_khr_extended_async_copies,cl_khr_extended_async_copies]] ==== Extended Async Copy Functions -The `cl_khr_extended_async_copies` extension provides additional +The {cl_khr_extended_async_copies_EXT} extension provides additional <> which interpret the source and destination as 2D or 3D images. endif::cl_khr_extended_async_copies[] @@ -360,7 +360,7 @@ ifdef::cl_khr_extended_bit_ops[] [[cl_khr_extended_bit_ops,cl_khr_extended_bit_ops]] ==== Extended Bit Operations -The `cl_khr_extended_bit_ops` extension provides additional +The {cl_khr_extended_bit_ops_EXT} extension provides additional <> including bitfield insert, bitfield extract, and bit reverse. endif::cl_khr_extended_bit_ops[] @@ -370,8 +370,8 @@ ifdef::cl_khr_fp16[] [[cl_khr_fp16,cl_khr_fp16]] ==== Half-Precision Floating-Point -The `cl_khr_fp16` extension was promoted to OpenCL C 1.2 as an optional -feature, and to OpenCL 3.0 as the optional `<>` feature. +The {cl_khr_fp16_EXT} extension was promoted to OpenCL C 1.2 as an optional +feature, and to OpenCL 3.0 as the optional {cl_khr_fp16_EXT} feature. The extension provides 16-bit precision scalar and vector floating-point data types and extends many functions to accept these types. endif::cl_khr_fp16[] @@ -381,8 +381,8 @@ ifdef::cl_khr_fp64[] [[cl_khr_fp64,cl_khr_fp64]] ==== Double-Precision Floating-Point -The `cl_khr_fp64` extension was promoted to OpenCL C 1.2 as an optional -feature, and to OpenCL 3.0 as the optional `<>` feature. +The {cl_khr_fp64_EXT} extension was promoted to OpenCL C 1.2 as an optional +feature, and to OpenCL 3.0 as the optional {cl_khr_fp64_EXT} feature. The extension provides double-precision scalar and vector floating-point data types and extends many functions to accept these types. endif::cl_khr_fp64[] @@ -392,7 +392,7 @@ ifdef::cl_khr_gl_msaa_sharing[] [[cl_khr_gl_msaa_sharing,cl_khr_gl_msaa_sharing]] ==== Multi-Sample Shared OpenCL/OpenGL Images -The `cl_khr_gl_msaa_sharing` extension adds support for multi-sample images +The {cl_khr_gl_msaa_sharing_EXT} extension adds support for multi-sample images shared with OpenGL multi-sample textures. The extension provides new <>, as well as <> table. @@ -458,7 +458,7 @@ ifdef::cl_khr_int64_extended_atomics[] [[cl_khr_int64_extended_atomics,cl_khr_int64_extended_atomics]] ==== 64-Bit Extended Atomics -The `cl_khr_int64_extended_atomics` extension provides extended atomic functions for +The {cl_khr_int64_extended_atomics_EXT} extension provides extended atomic functions for {global} and {local} 64-bit signed and unsigned integer variables, as described in the <> table. @@ -469,7 +469,7 @@ ifdef::cl_khr_integer_dot_product[] [[cl_khr_integer_dot_product,cl_khr_integer_dot_product]] ==== Integer Dot Product -The `cl_khr_integer_dot_product` extension adds support for SPIR-V +The {cl_khr_integer_dot_product_EXT} extension adds support for SPIR-V instructions and OpenCL C built-in functions to compute the dot product of vectors of integers. The extension provides new <> and <> functions operating on these images. @@ -530,8 +530,8 @@ ifdef::cl_khr_mipmap_image_writes[] [[cl_khr_mipmap_image_writes,cl_khr_mipmap_image_writes]] ==== Mipmapped Image Writes -The `cl_khr_mipmap_image_writes` extension adds support for writing to -mipmap images, and requires support for the `<>` +The {cl_khr_mipmap_image_writes_EXT} extension adds support for writing to +mipmap images, and requires support for the {cl_khr_mipmap_image_EXT} extension macro. The extension provides built-in <> functions operating on these images. @@ -542,7 +542,7 @@ ifdef::cl_khr_select_fprounding_mode[] [[cl_khr_select_fprounding_mode,cl_khr_select_fprounding_mode]] ==== Select Floating-Point Rounding Mode -The `cl_khr_select_fprounding_mode` extension allows <> for an instruction or group of instructions in the program source by use of a *#pragma*. @@ -554,7 +554,7 @@ ifdef::cl_khr_srgb_image_writes[] [[cl_khr_srgb_image_writes,cl_khr_srgb_image_writes]] ==== sRGB Image Write Functions -The `cl_khr_srgb_image_writes` extension adds support for writing to sRGB +The {cl_khr_srgb_image_writes_EXT} extension adds support for writing to sRGB images using the <> functions. Color space conversion is performed by the function. endif::cl_khr_srgb_image_writes[] @@ -564,7 +564,7 @@ ifdef::cl_khr_subgroups[] [[cl_khr_subgroups,cl_khr_subgroups]] ==== Sub-Groups -The `cl_khr_subgroups` extension was promoted to OpenCL C 2.1 as the +The {cl_khr_subgroups_EXT} extension was promoted to OpenCL C 2.1 as the {opencl_c_subgroups} feature. The extension provides the following functions: @@ -586,7 +586,7 @@ ifdef::cl_khr_subgroup_ballot[] [[cl_khr_subgroup_ballot,cl_khr_subgroup_ballot]] ==== Sub-Group Ballots -The `cl_khr_subgroup_ballot` extension adds the ability to collect and +The {cl_khr_subgroup_ballot_EXT} extension adds the ability to collect and operate on ballots from work items in a sub-group. The extension provides the following functions: @@ -599,7 +599,7 @@ ifdef::cl_khr_subgroup_clustered_reduce[] [[cl_khr_subgroup_clustered_reduce,cl_khr_subgroup_clustered_reduce]] ==== Sub-Group Clustered Reductions -The `cl_khr_subgroup_clustered_reduce` extension adds support for clustered +The {cl_khr_subgroup_clustered_reduce_EXT} extension adds support for clustered reductions that operate on a subset of work items in the sub-group. The extension provides the following functions: @@ -617,7 +617,7 @@ ifdef::cl_khr_subgroup_extended_types[] [[cl_khr_subgroup_extended_types,cl_khr_subgroup_extended_types]] ==== Sub-Group Extended Types -The `cl_khr_subgroup_extended_types` extension adds <> to the existing <>. @@ -629,7 +629,7 @@ ifdef::cl_khr_subgroup_non_uniform_arithmetic[] [[cl_khr_subgroup_non_uniform_arithmetic,cl_khr_subgroup_non_uniform_arithmetic]] ==== Sub-Group Non-Uniform Arithmetic -The `cl_khr_subgroup_non_uniform_arithmetic` extension adds the ability to +The {cl_khr_subgroup_non_uniform_arithmetic_EXT} extension adds the ability to use some sub-group functions within non-uniform flow control, including additional scan and reduction operators. @@ -649,7 +649,7 @@ ifdef::cl_khr_subgroup_non_uniform_vote[] [[cl_khr_subgroup_non_uniform_vote,cl_khr_subgroup_non_uniform_vote]] ==== Sub-Group Non-Uniform Vote and Election Functions -The `cl_khr_subgroup_non_uniform_vote` extension adds the ability to elect a +The {cl_khr_subgroup_non_uniform_vote_EXT} extension adds the ability to elect a single work item from a sub-group to perform a task and to hold votes among work items in a sub-group. @@ -665,7 +665,7 @@ ifdef::cl_khr_subgroup_rotate[] [[cl_khr_subgroup_rotate,cl_khr_subgroup_rotate]] ==== Sub-Group Rotation -The `cl_khr_subgroup_rotate` extension adds support for a new sub-group data +The {cl_khr_subgroup_rotate_EXT} extension adds support for a new sub-group data exchange operation that makes it possible to rotate values through the work items in a sub-group. @@ -680,7 +680,7 @@ ifdef::cl_khr_subgroup_shuffle[] [[cl_khr_subgroup_shuffle,cl_khr_subgroup_shuffle]] ==== Sub-Group General Purpose Shuffles -The `cl_khr_subgroup_shuffle` extension adds additional ways to exchange +The {cl_khr_subgroup_shuffle_EXT} extension adds additional ways to exchange data among work items in a sub-group. The extension provides the following functions: @@ -694,7 +694,7 @@ ifdef::cl_khr_subgroup_shuffle_relative[] [[cl_khr_subgroup_shuffle_relative,cl_khr_subgroup_shuffle_relative]] ==== Sub-Group Relative Shuffles -The `cl_khr_subgroup_shuffle_relative` extension adds specialized ways to +The {cl_khr_subgroup_shuffle_relative_EXT} extension adds specialized ways to exchange data among work items in a sub-group that may perform better on some implementations. @@ -710,7 +710,7 @@ ifdef::cl_khr_work_group_uniform_arithmetic[] [[cl_khr_work_group_uniform_arithmetic,cl_khr_work_group_uniform_arithmetic]] ==== Work-group Collective Uniform Arithmetic Functions -The `cl_khr_work_group_uniform_arithmetic` extension adds additional +The {cl_khr_work_group_uniform_arithmetic_EXT} extension adds additional work-group collective functions, including work-group scans and reductions for the following operators: @@ -837,7 +837,7 @@ application: ==== Double-Precision Floating-Point Support Double-precision floating-point is supported if -ifdef::cl_khr_fp64[the `<>` extension macro is supported, or if] +ifdef::cl_khr_fp64[the {cl_khr_fp64_EXT} extension macro is supported, or if] OpenCL 1.2 or newer is supported. In OpenCL 3.0, it also requires support for the {opencl_c_fp64} feature, @@ -1033,12 +1033,12 @@ OpenCL. | A 2D depth image. <> support for OpenCL C 2.0 or newer, or for - the `<>` extension macro. + the {cl_khr_depth_images_EXT} extension macro. | `image2d_array_depth_t` footnote:image-functions[] | A 2D depth image array. <> support for OpenCL C 2.0 or newer, or for - the `<>` extension macro. + the {cl_khr_depth_images_EXT} extension macro. | `sampler_t` footnote:image-functions[] | A sampler type. | `queue_t` @@ -1088,7 +1088,7 @@ ifdef::cl_khr_gl_msaa_sharing[] of the built-in functions that use this type. <> support for the - `<>` extension macro. + {cl_khr_gl_msaa_sharing_EXT} extension macro. | `image2d_array_msaa_t` | A 2D multi-sample color image array. Refer to the <> support for the - `<>` extension macro. + {cl_khr_gl_msaa_sharing_EXT} extension macro. | `image2d_msaa_depth_t` | A 2D multi-sample depth image. Refer to the <> support for the - `<>` extension macro. + {cl_khr_gl_msaa_sharing_EXT} extension macro. | `image2d_array_msaa_depth_t` | A 2D multi-sample depth image array. Refer to the <> support for the - `<>` extension macro. + {cl_khr_gl_msaa_sharing_EXT} extension macro. endif::cl_khr_gl_msaa_sharing[] |==== @@ -3887,7 +3887,7 @@ address space qualifiers. . The following restriction only applies to ifndef::cl_khr_byte_addressable_store[OpenCL C 1.0: +] ifdef::cl_khr_byte_addressable_store[] - OpenCL C 1.0, and only if the `<>` + OpenCL C 1.0, and only if the {cl_khr_byte_addressable_store_EXT} extension macro is not supported: + endif::cl_khr_byte_addressable_store[] Built-in types that are less than 32-bits in size, i.e. @@ -3953,7 +3953,7 @@ supported with `{global}` address space qualifier. -- ifdef::cl_khr_initialize_memory[] . [[restrictions-initialize-memory]] The following restriction only - applies if the `<>` extension is supported: + + applies if the {cl_khr_initialize_memory_EXT} extension is supported: + If the context is created with {CL_CONTEXT_MEMORY_INITIALIZE_KHR}, appropriate memory locations as specified by the bit-field are initialized with zeroes, prior to the start of execution of any kernel. @@ -4051,7 +4051,7 @@ The following predefined macro names are available. Used to determine the current rounding mode and is set to rte. Only affects the rounding mode of conversions to a float type. <> OpenCL C 1.1, along with the - `<>` extension. + {cl_khr_select_fprounding_mode_EXT} extension. `+__ENDIAN_LITTLE__+` :: Used to determine if the OpenCL device is a little endian architecture @@ -5065,7 +5065,7 @@ identifier of each work-item when this kernel is being executed on a device. NOTE: The functionality described in the following table <> support for -ifdef::cl_khr_subgroups[the `<>` extension macro; or for] +ifdef::cl_khr_subgroups[the {cl_khr_subgroups_EXT} extension macro; or for] OpenCL C 3.0 or newer and the {opencl_c_subgroups} feature. The following table describes the list of built-in work-item functions that @@ -5181,7 +5181,7 @@ that the function can take any of as the type for the arguments. NOTE: All functions taking or returning `half` types are supported only when -the `<>` extension macro is supported. +the {cl_khr_fp16_EXT} extension macro is supported. endif::cl_khr_fp16[] For any specific use of a function with `gentype*` arguments the actual type @@ -5944,7 +5944,7 @@ double type. |==== ifdef::cl_khr_fp16[] -If the `<>` extension macro is supported, then the following +If the {cl_khr_fp16_EXT} extension macro is supported, then the following macros and constants are also available: The `FP_FAST_FMA_HALF` macro indicates whether the *fma*() family of @@ -6224,7 +6224,7 @@ ifdef::cl_khr_extended_bit_ops[] [open,refpage='extendedBitOperations',desc='Extended Bit Operations',type='freeform',spec='clang',anchor='extended-bit-operations',xrefs='commonFunctions',alias='bitfield_insert bitfield_extract_signed bitfield_extract_unsigned bit_reverse'] -- -If the `<>` extension macro is supported, the +If the {cl_khr_extended_bit_ops_EXT} extension macro is supported, the functions described in the <> table can be used with built-in scalar or vector integer types to perform extended bit operations. @@ -6274,7 +6274,7 @@ gentype bitfield_insert( vector types), the result is undefined. <> support for the - `<>` extension macro. + {cl_khr_extended_bit_ops_EXT} extension macro. a| [source,opencl_c] ---- @@ -6299,7 +6299,7 @@ igentype bitfield_extract_signed( `gentype` (for vector types), the result is undefined. <> support for the - `<>` extension macro. + {cl_khr_extended_bit_ops_EXT} extension macro. a| [source,opencl_c] ---- @@ -6323,7 +6323,7 @@ ugentype bitfield_extract_unsigned( `gentype` (for vector types), the result is undefined. <> support for the - `<>` extension macro. + {cl_khr_extended_bit_ops_EXT} extension macro. a| [source,opencl_c] ---- @@ -6338,7 +6338,7 @@ gentype bit_reverse( vector types). <> support for the - `<>` extension macro. + {cl_khr_extended_bit_ops_EXT} extension macro. |=== -- endif::cl_khr_extended_bit_ops[] @@ -6442,7 +6442,7 @@ that the function can take any of as the type for the arguments. NOTE: All functions taking or returning `half` types are supported only when -the `<>` extension macro is supported. +the {cl_khr_fp16_EXT} extension macro is supported. endif::cl_khr_fp16[] [[table-builtin-common]] @@ -6569,7 +6569,7 @@ that the function can take any of as the type for the arguments. NOTE: All functions taking or returning `half` types are supported only when -the `<>` extension macro is supported. +the {cl_khr_fp16_EXT} extension macro is supported. endif::cl_khr_fp16[] For any specific use of a function with `gentype*` arguments the actual type @@ -6903,7 +6903,7 @@ ifdef::cl_khr_fp16[] NOTE: All functions taking or returning `half` types are supported only when -the `<>` extension macro is supported. +the {cl_khr_fp16_EXT} extension macro is supported. endif::cl_khr_fp16[] as the type for the arguments. @@ -7317,7 +7317,7 @@ in a work-group. NOTE: The functionality described in the following table <> support for -ifdef::cl_khr_subgroups[the `<>` extension macro; or for] +ifdef::cl_khr_subgroups[the {cl_khr_subgroups_EXT} extension macro; or for] OpenCL 3.0 or newer and the {opencl_c_subgroups} feature. The following table describes built-in functions to synchronize the work-items @@ -7525,7 +7525,7 @@ ifdef::cl_khr_fp16[] * `half` footnote:[{fn-half-supported}] or `half__n__` NOTE: All functions taking or returning `half` types are supported only when -the `<>` extension macro is supported. +the {cl_khr_fp16_EXT} extension macro is supported. endif::cl_khr_fp16[] as the type for the arguments unless otherwise stated. @@ -7635,7 +7635,7 @@ void async_work_group_copy_fence( non-uniform work-groups. <> support for the - `<>` extension macro. + {cl_khr_async_work_group_copy_fence_EXT} extension macro. endif::cl_khr_async_work_group_copy_fence[] |==== @@ -7654,7 +7654,7 @@ ifdef::cl_khr_extended_async_copies[] [open,refpage='extendedAsyncCopyFunctions',desc='Extended Async Copy Functions',type='freeform',spec='clang',anchor='extended-async-copies',xrefs='',alias='async_work_group_copy_2D2D async_work_group_copy_3D3D'] -- -If the `<>` extension macro is supported, +If the {cl_khr_extended_async_copies_EXT} extension macro is supported, additional <> are provided which interpret the source and destination as 2D or 3D data. @@ -8053,7 +8053,7 @@ The following table lists the enumeration constants: <> support for OpenCL C 2.0 or newer. | `memory_scope_sub_group` | <> support for -ifdef::cl_khr_subgroups[the `<>` extension macro; or for] +ifdef::cl_khr_subgroups[the {cl_khr_subgroups_EXT} extension macro; or for] OpenCL C 3.0 or newer and the {opencl_c_subgroups} feature. | `memory_scope_work_group` | <> support for OpenCL C 2.0 or newer. @@ -9168,7 +9168,7 @@ Extensions>> table below. |==== | Extension Macro | Supported Functions ifdef::cl_khr_global_int32_base_atomics[] -| `<>` +| {cl_khr_global_int32_base_atomics_EXT} | **atom_add** + **atom_sub** + **atom_xchg** + @@ -9178,7 +9178,7 @@ ifdef::cl_khr_global_int32_base_atomics[] (with {global} parameters) endif::cl_khr_global_int32_base_atomics[] ifdef::cl_khr_global_int32_extended_atomics[] -| `<>` +| {cl_khr_global_int32_extended_atomics_EXT} | **atom_min** + **atom_max** + **atom_and** + @@ -9187,7 +9187,7 @@ ifdef::cl_khr_global_int32_extended_atomics[] (with {global} parameters) endif::cl_khr_global_int32_extended_atomics[] ifdef::cl_khr_local_int32_base_atomics[] -| `<>` +| {cl_khr_local_int32_base_atomics_EXT} | **atom_add** + **atom_sub** + **atom_xchg** + @@ -9197,7 +9197,7 @@ ifdef::cl_khr_local_int32_base_atomics[] (with {local} parameters) endif::cl_khr_local_int32_base_atomics[] ifdef::cl_khr_local_int32_extended_atomics[] -| `<>` +| {cl_khr_local_int32_extended_atomics_EXT} | **atom_min** + **atom_max** + **atom_and** + @@ -9217,7 +9217,7 @@ Similar to the <>, atomic functions operating on 64-bit integers are provided by extensions. ifdef::cl_khr_int64_base_atomics[] -If the `<>` extension macro is supported, it +If the {cl_khr_int64_base_atomics_EXT} extension macro is supported, it provides the functions described in the <> table below. @@ -9285,7 +9285,7 @@ provides the functions described in the <>` extension macro is supported, it +If the {cl_khr_int64_extended_atomics_EXT} extension macro is supported, it provides the functions described in the <> table below. @@ -9389,7 +9389,7 @@ endif::cl_khr_int64_base_atomics,cl_khr_int64_extended_atomics[] newer and the {opencl_c_atomic_order_seq_cst} feature. * Using `memory_scope_sub_group` with any built-in atomic function <> support for -ifdef::cl_khr_subgroups[the `<>` extension macro; or for] +ifdef::cl_khr_subgroups[the {cl_khr_subgroups_EXT} extension macro; or for] OpenCL C 3.0 or newer and the {opencl_c_subgroups} feature. * Using `memory_scope_device` <> support for OpenCL C 2.0, or OpenCL C 3.0 or newer and the @@ -10152,7 +10152,7 @@ The following built-in function calls to read images with a sampler are supported footnote:[{fn-read-image-with-sampler}]. ifdef::cl_khr_mipmap_image[] -If the `<>` extension macro is supported, read +If the {cl_khr_mipmap_image_EXT} extension macro is supported, read functions which do not either * explicitly specify a level of detail _lod_, or @@ -10225,7 +10225,7 @@ ifdef::cl_khr_fp16[] _image_channel_data_type_ values not specified in the description above are undefined. - <> support for the `<>` extension + <> support for the {cl_khr_fp16_EXT} extension macro. endif::cl_khr_fp16[] | | @@ -10335,7 +10335,7 @@ ifdef::cl_khr_fp16[] _image_channel_data_type_ values not specified in the description are undefined. - <> support for the `<>` extension + <> support for the {cl_khr_fp16_EXT} extension macro. endif::cl_khr_fp16[] | | @@ -10444,7 +10444,7 @@ ifdef::cl_khr_fp16[] _image_channel_data_type_ values not specified in the description above are undefined. - <> support for the `<>` extension + <> support for the {cl_khr_fp16_EXT} extension macro. endif::cl_khr_fp16[] | | @@ -10554,7 +10554,7 @@ ifdef::cl_khr_fp16[] _image_channel_data_type_ values not specified in the description above are undefined. - <> support for the `<>` extension + <> support for the {cl_khr_fp16_EXT} extension macro. endif::cl_khr_fp16[] | | @@ -10666,7 +10666,7 @@ ifdef::cl_khr_fp16[] _image_channel_data_type_ values not specified in the description above are undefined. - <> support for the `<>` extension + <> support for the {cl_khr_fp16_EXT} extension macro. endif::cl_khr_fp16[] | | @@ -10742,7 +10742,7 @@ endif::cl_khr_fp16[] above are undefined. <> support for OpenCL C 2.0 or newer, or for - the `<>` extension macro. + the {cl_khr_depth_images_EXT} extension macro. | | | float *read_imagef*(read_only image2d_array_depth_t _image_, sampler_t _sampler_, int4 _coord_) + @@ -10769,7 +10769,7 @@ endif::cl_khr_fp16[] above are undefined. <> support for OpenCL C 2.0 or newer, or for - the `<>` extension macro. + the {cl_khr_depth_images_EXT} extension macro. | | ifdef::cl_khr_mipmap_image[] @@ -10803,7 +10803,7 @@ float read_imagef( | Use the coordinate _coord.xy_ to do an element lookup in the mip level specified by _lod_ in the 2D image object specified by _image_. - <> support for the `<>` + <> support for the {cl_khr_mipmap_image_EXT} extension macro. a| [source,opencl_c] @@ -10840,7 +10840,7 @@ float read_imagef( an element lookup in the mip level specified by the computed lod in the 2D image object specified by _image_. - <> support for the `<>` + <> support for the {cl_khr_mipmap_image_EXT} extension macro. a| [source,opencl_c] @@ -10866,7 +10866,7 @@ uint4 read_imageui( | Use the coordinate _coord_ to do an element lookup in the mip level specified by _lod_ in the 1D image object specified by _image_. - <> support for the `<>` + <> support for the {cl_khr_mipmap_image_EXT} extension macro. a| [source,opencl_c] @@ -10896,7 +10896,7 @@ uint4 read_imageui( element lookup in the mip level specified by the computed lod in the 1D image object specified by _image_. - <> support for the `<>` + <> support for the {cl_khr_mipmap_image_EXT} extension macro. a| [source,opencl_c] @@ -10922,7 +10922,7 @@ uint4 read_imageui( | Use the coordinate _coord.xyz_ to do an element lookup in the mip level specified by _lod_ in the 3D image object specified by _image_. - <> support for the `<>` + <> support for the {cl_khr_mipmap_image_EXT} extension macro. a| [source,opencl_c] @@ -10952,7 +10952,7 @@ uint4 read_imageui( an element lookup in the mip level specified by the computed lod in the 3D image object specified by _image_. - <> support for the `<>` + <> support for the {cl_khr_mipmap_image_EXT} extension macro. a| [source,opencl_c] @@ -10979,7 +10979,7 @@ uint4 read_imageui( identified by _coord.x_ and mip level specified by _lod_ in the 1D image array specified by _image_. - <> support for the `<>` + <> support for the {cl_khr_mipmap_image_EXT} extension macro. a| [source,opencl_c] @@ -11009,7 +11009,7 @@ uint4 read_imageui( element lookup in the mip level specified by the computed lod in the 1D image array specified by _image_. - <> support for the `<>` + <> support for the {cl_khr_mipmap_image_EXT} extension macro. a| [source,opencl_c] @@ -11042,7 +11042,7 @@ float read_imagef( identified by _coord.z_ and mip level specified by _lod_ in the 2D image array specified by _image_. - <> support for the `<>` + <> support for the {cl_khr_mipmap_image_EXT} extension macro. a| [source,opencl_c] @@ -11080,7 +11080,7 @@ float read_imagef( level specified by the computed lod in the 2D image array specified by _image_. - <> support for the `<>` + <> support for the {cl_khr_mipmap_image_EXT} extension macro. endif::cl_khr_mipmap_image[] @@ -11088,7 +11088,7 @@ endif::cl_khr_mipmap_image[] -- ifdef::cl_khr_mipmap_image[] -NOTE: If the `<>` extension macro is supported, +NOTE: If the {cl_khr_mipmap_image_EXT} extension macro is supported, {CL_SAMPLER_NORMALIZED_COORDS} must be {CL_TRUE} for built-in functions described in the table above that read from a mipmapped image; otherwise behavior is undefined. @@ -11169,7 +11169,7 @@ ifdef::cl_khr_fp16[] _image_channel_data_type_ values not specified in the description above are undefined. - <> support for the `<>` extension + <> support for the {cl_khr_fp16_EXT} extension macro. endif::cl_khr_fp16[] | | @@ -11245,7 +11245,7 @@ ifdef::cl_khr_fp16[] _image_channel_data_type_ values not specified in the description are undefined. - <> support for the `<>` extension + <> support for the {cl_khr_fp16_EXT} extension macro. endif::cl_khr_fp16[] | | @@ -11320,7 +11320,7 @@ ifdef::cl_khr_fp16[] _image_channel_data_type_ values not specified in the description above are undefined. - <> support for the `<>` extension + <> support for the {cl_khr_fp16_EXT} extension macro. endif::cl_khr_fp16[] | | @@ -11396,7 +11396,7 @@ ifdef::cl_khr_fp16[] _image_channel_data_type_ values not specified in the description above are undefined. - <> support for the `<>` extension + <> support for the {cl_khr_fp16_EXT} extension macro. endif::cl_khr_fp16[] | | @@ -11472,7 +11472,7 @@ ifdef::cl_khr_fp16[] _image_channel_data_type_ values not specified in the description above are undefined. - <> support for the `<>` extension + <> support for the {cl_khr_fp16_EXT} extension macro. endif::cl_khr_fp16[] | | @@ -11521,7 +11521,7 @@ endif::cl_khr_fp16[] above are undefined. <> support for OpenCL C 2.0 or newer, or for - the `<>` extension macro. + the {cl_khr_depth_images_EXT} extension macro. | | | float *read_imagef*(_aQual_ image2d_array_depth_t _image_, int4 _coord_) | Use _coord.xy_ to do an element lookup in the 2D image identified by @@ -11539,7 +11539,7 @@ endif::cl_khr_fp16[] above are undefined. <> support for OpenCL C 2.0 or newer, or for - the `<>` extension macro. + the {cl_khr_depth_images_EXT} extension macro. | | ifdef::cl_khr_gl_msaa_sharing[] @@ -11571,7 +11571,7 @@ float4 read_imagef( above are undefined. <> support for the - `<>` extension macro. + {cl_khr_gl_msaa_sharing_EXT} extension macro. a| [source,opencl_c] ---- @@ -11613,7 +11613,7 @@ uint4 read_imageui( values returned by *read_imageui* are undefined. <> support for the - `<>` extension macro. + {cl_khr_gl_msaa_sharing_EXT} extension macro. a| [source,opencl_c] ---- @@ -11642,7 +11642,7 @@ float4 read_imagef( above are undefined. <> support for the - `<>` extension macro. + {cl_khr_gl_msaa_sharing_EXT} extension macro. a| [source,opencl_c] ---- @@ -11684,7 +11684,7 @@ uint4 read_imageui( values returned by *read_imageui* are undefined. <> support for the - `<>` extension macro. + {cl_khr_gl_msaa_sharing_EXT} extension macro. a| [source,opencl_c] ---- @@ -11708,7 +11708,7 @@ float read_imagef( above are undefined. <> support for the - `<>` extension macro. + {cl_khr_gl_msaa_sharing_EXT} extension macro. a| [source,c] ---- @@ -11747,7 +11747,7 @@ float read_imagef(image2d_array_msaaa_depth_t image, image is undefined <> support for the - `<>` extension macro. + {cl_khr_gl_msaa_sharing_EXT} extension macro. endif::cl_khr_gl_msaa_sharing[] |==== -- @@ -11764,7 +11764,7 @@ _aQual_ in the following table refers to one of the access qualifiers. For write functions this may be `write_only` or `read_write`. ifdef::cl_khr_mipmap_image_writes[] -If the `<>` extension macro is supported, write +If the {cl_khr_mipmap_image_writes_EXT} extension macro is supported, write functions which do not explicitly specify a level of detail _lod_ write to mip level 0 if _image_ is a mipmapped image. _mipwidth_, _mipheight_, and _mipdepth_ in the table refer to the width, @@ -11774,7 +11774,7 @@ refers to the number of mip levels in _image_. endif::cl_khr_mipmap_image_writes[] ifdef::cl_khr_srgb_image_writes[] -If the `<>` extension macro is supported, the +If the {cl_khr_srgb_image_writes_EXT} extension macro is supported, the *write_imagef* functions described below may write to sRGB images. Linear to sRGB conversion is performed by the function. Only the R, G, and B components are converted from linear to sRGB; the A @@ -11847,7 +11847,7 @@ ifdef::cl_khr_fp16[*write_imageh*,] ifdef::cl_khr_fp16[] *write_imageh* <> support for the - `<>` extension macro. + {cl_khr_fp16_EXT} extension macro. endif::cl_khr_fp16[] | | | void *write_imagef*( + @@ -11912,7 +11912,7 @@ ifdef::cl_khr_fp16[*write_imageh*,] ifdef::cl_khr_fp16[] *write_imageh* <> support for the - `<>` extension macro. + {cl_khr_fp16_EXT} extension macro. endif::cl_khr_fp16[] | | | void *write_imagef*( + @@ -11993,7 +11993,7 @@ ifdef::cl_khr_fp16[*write_imageh*,] ifdef::cl_khr_fp16[] *write_imageh* <> support for the - `<>` extension macro. + {cl_khr_fp16_EXT} extension macro. endif::cl_khr_fp16[] | | | void *write_imagef*( + @@ -12082,7 +12082,7 @@ ifdef::cl_khr_fp16[*write_imageh*,] height-1], respectively, is undefined. <> support for OpenCL C 2.0 or newer, or for - the `<>` extension macro. + the {cl_khr_depth_images_EXT} extension macro. | | | void *write_imagef*( + _aQual_ image2d_array_depth_t _image_, + @@ -12111,7 +12111,7 @@ ifdef::cl_khr_fp16[*write_imageh*,] height-1], [0, image number of layers-1], respectively, is undefined. <> support for OpenCL C 2.0 or newer, or for - the `<>` extension macro. + the {cl_khr_depth_images_EXT} extension macro. | | | void *write_imagef*( + _aQual_ image3d_t _image_, + @@ -12173,11 +12173,11 @@ ifdef::cl_khr_fp16[*write_imageh*,] <> support for OpenCL C 2.0, or OpenCL C 3.0 or newer and the {opencl_c_3d_image_writes} feature, or the - `<>` extension. + {cl_khr_3d_image_writes_EXT} extension. ifdef::cl_khr_fp16[] *write_imageh* <> support for the - `<>` extension macro. + {cl_khr_fp16_EXT} extension macro. endif::cl_khr_fp16[] ifdef::cl_khr_mipmap_image_writes[] @@ -12221,7 +12221,7 @@ void write_imagef( range. <> support for the - `<>` extension macro. + {cl_khr_mipmap_image_writes_EXT} extension macro. a| [source,opencl_c] ---- @@ -12254,7 +12254,7 @@ void write_imageui( Behavior is undefined if _lod_ or _coord_ is not in range. <> support for the - `<>` extension macro. + {cl_khr_mipmap_image_writes_EXT} extension macro. a| [source,opencl_c] ---- @@ -12289,7 +12289,7 @@ void write_imageui( Behavior is undefined if _lod_, _coord.x_, or _coord.y_ is not in range. <> support for the - `<>` extension macro. + {cl_khr_mipmap_image_writes_EXT} extension macro. a| [source,opencl_c] ---- @@ -12331,7 +12331,7 @@ void write_imagef( _lod_, _coord.x_, _coord.y_, or _coord.z_ is not in range. <> support for the - `<>` extension macro. + {cl_khr_mipmap_image_writes_EXT} extension macro. a| [source,opencl_c] ---- @@ -12366,7 +12366,7 @@ void write_imageui( not in range. <> support for the - `<>` extension macro. + {cl_khr_mipmap_image_writes_EXT} extension macro. endif::cl_khr_mipmap_image_writes[] |==== @@ -12400,14 +12400,14 @@ For query functions this may be `read_only`, `write_only` or `read_write`. int *get_image_width*(_aQual_ image1d_array_t _image_) + int *get_image_width*(_aQual_ image2d_array_t _image_) - For OpenCL C 2.0 or newer, or if the `<>` extension + For OpenCL C 2.0 or newer, or if the {cl_khr_depth_images_EXT} extension macro is supported: int *get_image_width*(_aQual_ image2d_depth_t _image_) + int *get_image_width*(_aQual_ image2d_array_depth_t _image_) ifdef::cl_khr_gl_msaa_sharing[] - If the `<>` extension macro is supported: + If the {cl_khr_gl_msaa_sharing_EXT} extension macro is supported: int *get_image_width*(_aQual_ image2d_msaa_t image) + int *get_image_width*(_aQual_ image2d_array_msaa_t image) + @@ -12423,14 +12423,14 @@ endif::cl_khr_gl_msaa_sharing[] int *get_image_height*(_aQual_ image2d_array_t _image_) - For OpenCL C 2.0 or newer, or if the `<>` extension + For OpenCL C 2.0 or newer, or if the {cl_khr_depth_images_EXT} extension macro is supported: int *get_image_height*(_aQual_ image2d_depth_t _image_) + int *get_image_height*(_aQual_ image2d_array_depth_t _image_) ifdef::cl_khr_gl_msaa_sharing[] - If the `<>` extension macro is supported: + If the {cl_khr_gl_msaa_sharing_EXT} extension macro is supported: int *get_image_height*(_aQual_ image2d_msaa_t image) + int *get_image_height*(_aQual_ image2d_array_msaa_t image) + @@ -12454,14 +12454,14 @@ endif::cl_khr_gl_msaa_sharing[] int *get_image_channel_data_type*(_aQual_ image1d_array_t _image_) + int *get_image_channel_data_type*(_aQual_ image2d_array_t _image_) - For OpenCL C 2.0 or newer, or if the `<>` extension + For OpenCL C 2.0 or newer, or if the {cl_khr_depth_images_EXT} extension macro is supported: int *get_image_channel_data_type*(_aQual_ image2d_depth_t _image_) + int *get_image_channel_data_type*(_aQual_ image2d_array_depth_t _image_) ifdef::cl_khr_gl_msaa_sharing[] - If the `<>` extension macro is supported: + If the {cl_khr_gl_msaa_sharing_EXT} extension macro is supported: int *get_image_channel_data_type*(_aQual_ image2d_msaa_t image) + int *get_image_channel_data_type*(_aQual_ image2d_array_msaa_t image) + @@ -12500,14 +12500,14 @@ endif::cl_khr_gl_msaa_sharing[] int *get_image_channel_order*(_aQual_ image1d_array_t _image_) + int *get_image_channel_order*(_aQual_ image2d_array_t _image_) - For OpenCL C 2.0 or newer, or if the `<>` extension + For OpenCL C 2.0 or newer, or if the {cl_khr_depth_images_EXT} extension macro is supported: int *get_image_channel_order*(_aQual_ image2d_depth_t _image_) + int *get_image_channel_order*(_aQual_ image2d_array_depth_t _image_) ifdef::cl_khr_gl_msaa_sharing[] - If the `<>` extension macro is supported: + If the {cl_khr_gl_msaa_sharing_EXT} extension macro is supported: int *get_image_channel_order*(_aQual_ image2d_msaa_t image) + int *get_image_channel_order*(_aQual_ image2d_array_msaa_t image) + @@ -12549,14 +12549,14 @@ endif::cl_khr_gl_msaa_sharing[] int2 *get_image_dim*(_aQual_ image2d_array_t _image_) - For OpenCL C 2.0 or newer, or if the `<>` extension + For OpenCL C 2.0 or newer, or if the {cl_khr_depth_images_EXT} extension macro is supported: int2 *get_image_dim*(_aQual_ image2d_depth_t _image_) + int2 *get_image_dim*(_aQual_ image2d_array_depth_t _image_) ifdef::cl_khr_gl_msaa_sharing[] - If the `<>` extension macro is supported: + If the {cl_khr_gl_msaa_sharing_EXT} extension macro is supported: int2 *get_image_dim*(_aQual_ image2d_msaa_t image) + int2 *get_image_dim*(_aQual_ image2d_array_msaa_t image) + @@ -12576,13 +12576,13 @@ endif::cl_khr_gl_msaa_sharing[] size_t *get_image_array_size*(_aQual_ image2d_array_t _image_) - For OpenCL C 2.0 or newer, or if the `<>` extension + For OpenCL C 2.0 or newer, or if the {cl_khr_depth_images_EXT} extension macro is supported: size_t *get_image_array_size*(_aQual_ image2d_array_depth_t _image_) ifdef::cl_khr_gl_msaa_sharing[] - If the `<>` extension macro is supported: + If the {cl_khr_gl_msaa_sharing_EXT} extension macro is supported: size_t *get_image_array_size*(_aQual_ image2d_array_msaa_depth_t _image_) endif::cl_khr_gl_msaa_sharing[] @@ -12594,7 +12594,7 @@ endif::cl_khr_gl_msaa_sharing[] | Return the number of images in the 1D image array. ifdef::cl_khr_gl_msaa_sharing[] -| If the `<>` extension macro is supported: +| If the {cl_khr_gl_msaa_sharing_EXT} extension macro is supported: int *get_image_num_samples*(_aQual_ image2d_msaa_t _image_) + int *get_image_num_samples*(_aQual_ image2d_array_msaa_t _image_) + @@ -12604,7 +12604,7 @@ ifdef::cl_khr_gl_msaa_sharing[] endif::cl_khr_gl_msaa_sharing[] ifdef::cl_khr_mipmap_image[] -| If the `<>` extension macro is supported: +| If the {cl_khr_mipmap_image_EXT} extension macro is supported: int *get_image_num_mip_levels*(_aQual_ image1d_t _image_) + int *get_image_num_mip_levels*(_aQual_ image2d_t _image_) + @@ -12699,7 +12699,7 @@ and will be set to 1.0 for the alpha channel. For {CL_DEPTH} images, a scalar value is returned by *read_imagef* or supplied to *write_imagef*. <> support for OpenCL C 2.0 or newer, or for -the `<>` extension macro. +the {cl_khr_depth_images_EXT} extension macro. [NOTE] ==== @@ -12840,7 +12840,7 @@ ifdef::cl_khr_work_group_uniform_arithmetic[] [open,refpage='workGroupUniformArithmeticFunctions',desc='Work-group Collective Uniform Arithmetic Functions',type='freeform',spec='clang',anchor='work-group-collective-uniform-arithmetic-functions',xrefs='workGroupFunctions',alias='work_group_all work_group_any work_group_broadcast work_group_reduce work_group_scan_exclusive work_group_scan_inclusive'] -- NOTE: The functionality described in this section <> -support for OpenCL C 2.0 and the `<>` +support for OpenCL C 2.0 and the {cl_khr_work_group_uniform_arithmetic_EXT} extension macro. The <> table describes the OpenCL C @@ -13297,7 +13297,7 @@ The following table describes the list of built-in functions that can be used to enqueue a kernel(s). ifdef::cl_khr_device_enqueue_local_arg_types[] -When the `<>` extension macro is +When the {cl_khr_device_enqueue_local_arg_types_EXT} extension macro is supported, the <> and <> described in this section can use any of the built-in OpenCL C @@ -13307,7 +13307,7 @@ their arguments. This is indicated by the generic type name `gentype` in those function signatures. -When the `<>` extension macro is +When the {cl_khr_device_enqueue_local_arg_types_EXT} extension macro is not supported, the pointee type of these functions must be `void`. :localArgType: gentype @@ -13984,7 +13984,7 @@ foo(queue_t q, ...) -- NOTE: The functionality described in this section <> support for -ifdef::cl_khr_subgroups[the `<>` extension macro; or for] +ifdef::cl_khr_subgroups[the {cl_khr_subgroups_EXT} extension macro; or for] OpenCL C 3.0 or newer and the {opencl_c_subgroups} feature. The <> describes OpenCL C @@ -13998,7 +13998,7 @@ footnote:[{fn-half-supported}], `float`, and `double` footnote:[{fn-double-supported}]. ifdef::cl_khr_subgroup_extended_types[] -NOTE: If the `<>` extension is supported, the +NOTE: If the {cl_khr_subgroup_extended_types_EXT} extension is supported, the generic type name `gentype` may additionally be `char`, `uchar`, `short`, and `ushort`. For the `sub_group_broadcast` function, `gentype` may additionally be one of @@ -14080,7 +14080,7 @@ The order of these floating-point operations is also non-deterministic for a giv NOTE: The functionality described in the following table <> support -ifdef::cl_khr_subgroups[the `<>` extension macro; or for] +ifdef::cl_khr_subgroups[the {cl_khr_subgroups_EXT} extension macro; or for] OpenCL C 3.0 or newer and the {opencl_c_subgroups} and {opencl_c_pipes} features. @@ -14135,7 +14135,7 @@ groups is implementation-defined. NOTE: The functionality described in the following table <> support -ifdef::cl_khr_subgroups[the `<>` extension macro; or for] +ifdef::cl_khr_subgroups[the {cl_khr_subgroups_EXT} extension macro; or for] OpenCL C 3.0 or newer and the {opencl_c_subgroups} and {opencl_c_device_enqueue} features. @@ -14179,7 +14179,7 @@ ifdef::cl_khr_subgroup_ballot[] ==== Built-in Sub-Group Ballot Functions NOTE: The functionality described in this section <> -support for the `<>` extension. +support for the {cl_khr_subgroup_ballot_EXT} extension. The <> describes OpenCL C programming language built-in functions to allow work items in a sub-group @@ -14379,7 +14379,7 @@ ifdef::cl_khr_subgroup_clustered_reduce[] ==== Built-in Sub-Group Clustered Reduction Functions NOTE: The functionality described in this section <> -support for the `<>` extension. +support for the {cl_khr_subgroup_clustered_reduce_EXT} extension. This section describes arithmetic operations that are performed on a subset of work items in a sub-group, referred to as a cluster. @@ -14501,7 +14501,7 @@ ifdef::cl_khr_subgroup_non_uniform_arithmetic[] ==== Built-in Sub-Group Non-Uniform Scan and Reduction Functions NOTE: The functionality described in this section <> -support for the `<>` extension. +support for the {cl_khr_subgroup_non_uniform_arithmetic_EXT} extension. ===== Arithmetic Operations @@ -14536,7 +14536,7 @@ gentype sub_group_non_uniform_reduce_mul( for all active work items in the sub-group. Note: This behavior is the same as the *add*, *min*, and *max* reduction - built-in functions from `<>` and OpenCL 2.1, except + built-in functions from {cl_khr_subgroups_EXT} and OpenCL 2.1, except these functions support additional types and need not be encountered by all work items in the sub-group executing the kernel. |[source,opencl_c] @@ -14556,7 +14556,7 @@ gentype sub_group_non_uniform_scan_inclusive_mul( to this work item's sub-group local ID. Note: This behavior is the same as the *add*, *min*, and *max* inclusive - scan built-in functions from `<>` and OpenCL 2.1, + scan built-in functions from {cl_khr_subgroups_EXT} and OpenCL 2.1, except these functions support additional types and need not be encountered by all work items in the sub-group executing the kernel. |[source,opencl_c] @@ -14586,7 +14586,7 @@ gentype sub_group_non_uniform_scan_exclusive_mul( For *mul*, the identity value is `1`. Note: This behavior is the same as the *add*, *min*, and *max* exclusive - scan built-in functions from `<>` and OpenCL 2.1, + scan built-in functions from {cl_khr_subgroups_EXT} and OpenCL 2.1, except these functions support additional types and need not be encountered by all work items in the sub-group executing the kernel. |==== @@ -14727,7 +14727,7 @@ ifdef::cl_khr_subgroup_non_uniform_vote[] ==== Built-in Sub-Group Non-Uniform Vote Functions NOTE: The functionality described in this section <> -support for the `<>` extension. +support for the {cl_khr_subgroup_non_uniform_vote_EXT} extension. The <> describes the OpenCL C programming language built-in functions to elect a single work item @@ -14765,7 +14765,7 @@ int sub_group_non_uniform_all( items in the sub-group and zero otherwise. Note: This behavior is the same as `sub_group_all` from - `<>` and OpenCL 2.1, except this function need not be + {cl_khr_subgroups_EXT} and OpenCL 2.1, except this function need not be encountered by all work items in the sub-group executing the kernel. |[source,opencl_c] ---- @@ -14777,7 +14777,7 @@ int sub_group_non_uniform_any( item in the sub-group and zero otherwise. Note: This behavior is the same as `sub_group_any` from - `<>` and OpenCL 2.1, except this function need not be + {cl_khr_subgroups_EXT} and OpenCL 2.1, except this function need not be encountered by all work items in the sub-group executing the kernel. |[source,opencl_c] ---- @@ -14800,7 +14800,7 @@ ifdef::cl_khr_subgroup_rotate[] ==== Built-in Sub-Group Rotation Functions NOTE: The functionality described in this section <> -support for the `<>` extension. +support for the {cl_khr_subgroup_rotate_EXT} extension. The <> describes a specialized OpenCL C programming language built-in function that allow work items in a @@ -14861,7 +14861,7 @@ ifdef::cl_khr_subgroup_shuffle[] ==== Built-in Sub-Group General Purpose Shuffle Functions NOTE: The functionality described in this section <> -support for the `<>` extension. +support for the {cl_khr_subgroup_shuffle_EXT} extension. The <> describes the OpenCL C programming language built-in functions that allow work items in a sub-group @@ -14980,7 +14980,7 @@ This section is informational and non-normative. |==== | OpenCL C Function | SPIR-V BuiltIn or Instruction | Enabling SPIR-V Capability -3+| For OpenCL 2.1 or `<>`: +3+| For OpenCL 2.1 or {cl_khr_subgroups_EXT}: | `get_​sub_​group_​size` | *SubgroupSize* @@ -15067,7 +15067,7 @@ This section is informational and non-normative. | *DeviceEnqueue* ifdef::cl_khr_subgroup_ballot[] -3+| For `<>`: +3+| For {cl_khr_subgroup_ballot_EXT}: | `sub_​group_​non_​uniform_​broadcast` | *OpGroupNonUniformBroadcast* @@ -15119,7 +15119,7 @@ ifdef::cl_khr_subgroup_ballot[] endif::cl_khr_subgroup_ballot[] ifdef::cl_khr_subgroup_clustered_reduce[] -3+| For `<>`: +3+| For {cl_khr_subgroup_clustered_reduce_EXT}: | `sub_​group_​clustered_​reduce_​add` | *OpGroupNonUniformIAdd*, *OpGroupNonUniformFAdd* @@ -15154,7 +15154,7 @@ ifdef::cl_khr_subgroup_clustered_reduce[] endif::cl_khr_subgroup_clustered_reduce[] ifdef::cl_khr_subgroup_extended_types[] -3+| For `<>`: + +3+| For {cl_khr_subgroup_extended_types_EXT}: + Note: This extension adds new types to uniform sub-group operations. | `sub_​group_​broadcast` @@ -15193,7 +15193,7 @@ ifdef::cl_khr_subgroup_extended_types[] endif::cl_khr_subgroup_extended_types[] ifdef::cl_khr_subgroup_non_uniform_arithmetic[] -3+| For `<>`: +3+| For {cl_khr_subgroup_non_uniform_arithmetic_EXT}: | `sub_​group_​non_​uniform_​reduce_​add` | *OpGroupNonUniformIAdd*, *OpGroupNonUniformFAdd* @@ -15290,7 +15290,7 @@ ifdef::cl_khr_subgroup_non_uniform_arithmetic[] endif::cl_khr_subgroup_non_uniform_arithmetic[] ifdef::cl_khr_subgroup_non_uniform_vote[] -3+| For `<>`: +3+| For {cl_khr_subgroup_non_uniform_vote_EXT}: | `sub_​group_​elect` | *OpGroupNonUniformElect* @@ -15307,7 +15307,7 @@ ifdef::cl_khr_subgroup_non_uniform_vote[] endif::cl_khr_subgroup_non_uniform_vote[] ifdef::cl_khr_subgroup_shuffle[] -3+| For `<>`: +3+| For {cl_khr_subgroup_shuffle_EXT}: | `sub_​group_​shuffle` | *OpGroupNonUniformShuffle* @@ -15318,7 +15318,7 @@ ifdef::cl_khr_subgroup_shuffle[] endif::cl_khr_subgroup_shuffle[] ifdef::cl_khr_subgroup_shuffle_relative[] -3+| For `<>`: +3+| For {cl_khr_subgroup_shuffle_relative_EXT}: | `sub_​group_​shuffle_​up` | *OpGroupNonUniformShuffleUp* @@ -15335,7 +15335,7 @@ ifdef::cl_khr_kernel_clock[] === Kernel Clock Functions NOTE: The functionality described in this section <> -support for the `<>` extension. + +support for the {cl_khr_kernel_clock_EXT} extension. + The `clock_read_device` and `clock_read_hilo_device` functions require support for the {opencl_c_kernel_clock_scope_device} feature. The `clock_read_work_group` and `clock_read_hilo_work_group` functions require @@ -15418,7 +15418,7 @@ Dynamically reconfiguring the rounding modes as specified by the IEEE 754 spec is unsupported. ifdef::cl_khr_fp16[] -If the `<>` extension macro is supported, then +If the {cl_khr_fp16_EXT} extension macro is supported, then if {CL_FP_ROUND_TO_NEAREST} is supported, the default rounding mode for half-precision floating-point operations will be round to nearest even; otherwise the default rounding mode will be round to zero. @@ -15439,7 +15439,7 @@ ifdef::cl_khr_select_fprounding_mode[] -- [[select-rounding-mode]] -If the `<>` extension macro is supported, the +If the {cl_khr_select_fprounding_mode_EXT} extension macro is supported, the floating-point rounding mode may be specified using the following *#pragma* in the OpenCL program source: @@ -15472,7 +15472,7 @@ condition just before the compound statement. Except where otherwise documented, the callee functions do not inherit the rounding mode of the caller function. -If the `<>` extension is enabled, the +If the {cl_khr_select_fprounding_mode_EXT} extension is enabled, the `\\__ROUNDING_MODE__` preprocessor symbol shall be defined to be one of the following according to the current rounding mode: @@ -15502,7 +15502,7 @@ rounding mode. Conversions from floating-point to integer type always use `rtz` mode, except where the user specifically asks for another rounding mode. -NOTE: The `<>` extension was deprecated in +NOTE: The {cl_khr_select_fprounding_mode_EXT} extension was deprecated in OpenCL 1.1, and its use is not recommended. -- endif::cl_khr_select_fprounding_mode[] @@ -15571,7 +15571,7 @@ Conversion between floating-point formats and <> must be correctly rounded. ifdef::cl_khr_fp16[] -If the `<>` extension macro is supported, +If the {cl_khr_fp16_EXT} extension macro is supported, addition, subtraction, multiplication, fused multiply-add operations on half types are required to be correctly rounded using the default rounding mode for half-precision floating-point operations. @@ -16269,7 +16269,7 @@ is the infinitely precise result. ifdef::cl_khr_fp16[] -If the `<>` extension macro is supported, +If the {cl_khr_fp16_EXT} extension macro is supported, the following table describes the minimum accuracy of half-precision floating-point arithmetic operations given as ULP values. The reference value used to compute the ULP value of an arithmetic operation @@ -17125,7 +17125,7 @@ ifdef::cl_khr_fp16[] [[converting-normalized-integer-channel-data-types-to-half-precision-floating-point-values]] ==== Converting Normalized Integer Channel Data Types to Half-Precision Floating-Point Values -If the `<>` extension is supported, then +If the {cl_khr_fp16_EXT} extension is supported, then for images created with image channel data type of {CL_UNORM_INT8} and {CL_UNORM_INT16}, *read_imageh* will convert the channel values from an 8-bit or 16-bit unsigned integer to normalized half-precision floating-point @@ -17292,7 +17292,7 @@ ifdef::cl_khr_fp16[] [[converting-half-precision-floating-point-values-to-normalized-integer-channel-data-types]] ==== Converting Half-Precision Floating-point Values to Normalized Integer Channel Data Types -If the `<>` extension is supported, then +If the {cl_khr_fp16_EXT} extension is supported, then for images created with image channel data type of {CL_UNORM_INT8} and {CL_UNORM_INT16}, *write_imageh* will convert the floating-point color value to an 8-bit or 16-bit unsigned integer. diff --git a/api/appendix_c.asciidoc b/api/appendix_c.asciidoc index 2531dbb2d..6583f1c72 100644 --- a/api/appendix_c.asciidoc +++ b/api/appendix_c.asciidoc @@ -389,54 +389,54 @@ include::{generated}/api/version-notes/CL_FLT_EPSILON.asciidoc[] | {CL_DBL_DIG_anchor} include::{generated}/api/version-notes/CL_DBL_DIG.asciidoc[] -Also see `<>`. +Also see {cl_khr_fp64_EXT}. | Number of decimal digits of precision for the type {cl_double_TYPE} | {CL_DBL_MANT_DIG_anchor} include::{generated}/api/version-notes/CL_DBL_MANT_DIG.asciidoc[] -Also see `<>`. +Also see {cl_khr_fp64_EXT}. | Number of digits in the mantissa of type {cl_double_TYPE} | {CL_DBL_MAX_10_EXP_anchor} include::{generated}/api/version-notes/CL_DBL_MAX_10_EXP.asciidoc[] -Also see `<>`. +Also see {cl_khr_fp64_EXT}. | Maximum positive integer such that 10 raised to this power minus one can be represented as a normalized floating-point number of type {cl_double_TYPE} | {CL_DBL_MAX_EXP_anchor} include::{generated}/api/version-notes/CL_DBL_MAX_EXP.asciidoc[] -Also see `<>`. +Also see {cl_khr_fp64_EXT}. | Maximum exponent value of type {cl_double_TYPE} | {CL_DBL_MIN_10_EXP_anchor} include::{generated}/api/version-notes/CL_DBL_MIN_10_EXP.asciidoc[] -Also see `<>`. +Also see {cl_khr_fp64_EXT}. | Minimum negative integer such that 10 raised to this power minus one can be represented as a normalized floating-point number of type {cl_double_TYPE} | {CL_DBL_MIN_EXP_anchor} include::{generated}/api/version-notes/CL_DBL_MIN_EXP.asciidoc[] -Also see `<>`. +Also see {cl_khr_fp64_EXT}. | Minimum exponent value of type {cl_double_TYPE} | {CL_DBL_RADIX_anchor} include::{generated}/api/version-notes/CL_DBL_RADIX.asciidoc[] -Also see `<>`. +Also see {cl_khr_fp64_EXT}. | Base value of type {cl_double_TYPE} | {CL_DBL_MAX_anchor} include::{generated}/api/version-notes/CL_DBL_MAX.asciidoc[] -Also see `<>`. +Also see {cl_khr_fp64_EXT}. | Maximum value of type {cl_double_TYPE} | {CL_DBL_MIN_anchor} include::{generated}/api/version-notes/CL_DBL_MIN.asciidoc[] -Also see `<>`. +Also see {cl_khr_fp64_EXT}. | Minimum value of type {cl_double_TYPE} | {CL_DBL_EPSILON_anchor} include::{generated}/api/version-notes/CL_DBL_EPSILON.asciidoc[] -Also see `<>`. +Also see {cl_khr_fp64_EXT}. | Minimum positive floating-point number of type {cl_double_TYPE} such that `1.0 {plus} {CL_DBL_EPSILON} != 1` is true. | {CL_NAN_anchor} diff --git a/api/appendix_e.asciidoc b/api/appendix_e.asciidoc index ec6626c2a..eebc7ff2d 100644 --- a/api/appendix_e.asciidoc +++ b/api/appendix_e.asciidoc @@ -74,11 +74,11 @@ The following features are added to the OpenCL C programming language _section 6.12.3_. ** *async_work_group_strided_copy* defined in section _6.15.11_. ** *vec_step*, *shuffle* and *shuffle2* defined in section _6.15.13_. - * `<>` extension is a core feature. - * `<>`, - `<>`, - `<>` and - `<>` extensions are core features. + * {cl_khr_byte_addressable_store_EXT} extension is a core feature. + * {cl_khr_global_int32_base_atomics_EXT}, + {cl_khr_global_int32_extended_atomics_EXT}, + {cl_khr_local_int32_base_atomics_EXT} and + {cl_khr_local_int32_extended_atomics_EXT} extensions are core features. The built-in atomic function names are changed to use the *atomic_* prefix instead of *atom_*. * Macros `CL_VERSION_1_0` and `CL_VERSION_1_1`. @@ -97,13 +97,13 @@ The following features in OpenCL 1.0 are deprecated (see glossary) in OpenCL * The `-cl-strict-aliasing` build option has been deprecated. It is no longer required after defining type-based aliasing rules. // Bugzilla 5593 and 6068 - * The `<>` extension is deprecated and its + * The {cl_khr_select_fprounding_mode_EXT} extension is deprecated and its use is no longer recommended. The following new extensions are added to _section 9_ in OpenCL 1.1: - * `<>` for creating a CL event object from a GL sync object. - * `<>` for sharing memory objects with Direct3D 10. + * {cl_khr_gl_event_EXT} for creating a CL event object from a GL sync object. + * {cl_khr_d3d10_sharing_EXT} for sharing memory objects with Direct3D 10. The following modifications are made to the OpenCL ES Profile described in _section 10_ in OpenCL 1.1: @@ -146,7 +146,7 @@ runtime (_sections 4 and 5_): a kernel. * {clEnqueueMarkerWithWaitList} and {clEnqueueBarrierWithWaitList} APIs. * {clUnloadPlatformCompiler} to request that a single platform's compiler is - unloaded. This is compatible with the `<>` extension if that is + unloaded. This is compatible with the {cl_khr_icd_EXT} extension if that is supported, unlike {clUnloadCompiler}. The following features are added to the OpenCL C programming language @@ -183,7 +183,7 @@ The following APIs in OpenCL 1.1 are deprecated (see glossary) in OpenCL // Bugzilla 5391 - cl_khr_icd specification * {clUnloadCompiler} and {clGetExtensionFunctionAddress} APIs are deprecated. The {clUnloadPlatformCompiler} and {clGetExtensionFunctionAddressForPlatform} - APIs provide equivalent functionality are compatible with the `<>` + APIs provide equivalent functionality are compatible with the {cl_khr_icd_EXT} extension. The following queries are deprecated (see glossary) in OpenCL 1.2: @@ -465,14 +465,14 @@ Changes from *v3.0.5*: * Fixed the calculation in "mapping work-items onto an ND-range". * Added new extensions: - ** `<>` - ** `<>` - ** `<>` - ** `<>` - ** `<>` - ** `<>` - ** `<>` - ** `<>` + ** {cl_khr_extended_versioning_EXT} + ** {cl_khr_subgroup_extended_types_EXT} + ** {cl_khr_subgroup_non_uniform_vote_EXT} + ** {cl_khr_subgroup_ballot_EXT} + ** {cl_khr_subgroup_non_uniform_arithmetic_EXT} + ** {cl_khr_subgroup_shuffle_EXT} + ** {cl_khr_subgroup_shuffle_relative_EXT} + ** {cl_khr_subgroup_clustered_reduce_EXT} Changes from *v3.0.6*: @@ -481,11 +481,11 @@ Changes from *v3.0.6*: * Clarified the table structure in the backwards compatibility appendix. * Clarified that `-cl-unsafe-math-optimizations` also implies `-cl-denorms-are-zero`. * Added new extensions: - ** `<>` - ** `<>` - ** `<>` - ** `<>` - ** `<>` + ** {cl_khr_extended_bit_ops_EXT} + ** {cl_khr_pci_bus_info_EXT} + ** {cl_khr_spirv_extended_debug_info_EXT} + ** {cl_khr_spirv_linkonce_odr_EXT} + ** {cl_khr_suggested_local_work_size_EXT} Changes from *v3.0.7*: @@ -493,7 +493,7 @@ Changes from *v3.0.7*: * Removed unnecessary phrase from sub-group mask function descriptions. * Added _input_slice_pitch_ error condition for read and write image APIs. * Added new extension: - ** `<>` + ** {cl_khr_integer_dot_product_EXT} Changes from *v3.0.8*: @@ -501,18 +501,18 @@ Changes from *v3.0.8*: * Clarified requirements for {CL_DEVICE_DOUBLE_FP_CONFIG} prior to OpenCL 2.0. * Clarified the behavior of ballot operations for remainder sub-groups. * Added new extensions: - ** `<>` (version 2) - ** `<>` (provisional) - ** `<>` (provisional) - ** `<>` (provisional) - ** `<>` (provisional) - ** `<>` (provisional) - ** `<>` (provisional) - ** `<>` (provisional) - ** `<>` (provisional) - ** `<>` (provisional) - ** `<>` (provisional) - ** `<>` (provisional) + ** {cl_khr_integer_dot_product_EXT} (version 2) + ** {cl_khr_semaphore_EXT} (provisional) + ** {cl_khr_external_semaphore_EXT} (provisional) + ** {cl_khr_external_semaphore_dx_fence_EXT} (provisional) + ** {cl_khr_external_semaphore_opaque_fd_EXT} (provisional) + ** {cl_khr_external_semaphore_sync_fd_EXT} (provisional) + ** {cl_khr_external_semaphore_win32_EXT} (provisional) + ** {cl_khr_external_memory_EXT} (provisional) + ** {cl_khr_external_memory_dma_buf_EXT} (provisional) + ** {cl_khr_external_memory_dx_EXT} (provisional) + ** {cl_khr_external_memory_opaque_fd_EXT} (provisional) + ** {cl_khr_external_memory_win32_EXT} (provisional) Changes from *v3.0.9*: @@ -521,10 +521,10 @@ Changes from *v3.0.9*: * Clarified that {clCompileProgram} is valid for programs created from SPIR. * Documented the possible state of a kernel object after a failed call to {clSetKernelArg}. * Added new extensions: - ** `<>` (final) - ** `<>` (final) - ** `<>` - ** `<>` (provisional) + ** {cl_khr_async_work_group_copy_fence_EXT} (final) + ** {cl_khr_extended_async_copies_EXT} (final) + ** {cl_khr_expect_assume_EXT} + ** {cl_khr_command_buffer_EXT} (provisional) Changes from *v3.0.10*: @@ -537,8 +537,8 @@ Changes from *v3.0.10*: * Clarified that the extended versioning extension is a core OpenCL 3.0 feature. * Clarified sub-group clustered reduction behavior when the cluster size is not an integer constant or a power of two. * Added new extensions: - ** `<>` - ** `<>` + ** {cl_khr_subgroup_rotate_EXT} + ** {cl_khr_work_group_uniform_arithmetic_EXT} Changes from *v3.0.11*: @@ -546,29 +546,29 @@ Changes from *v3.0.11*: * Added a maximum limit for the number of arguments supported by a kernel. * Clarified requirements for comparability and uniqueness of object handles. * Clarified behavior for invalid device-side enqueue `clk_event_t` handles. - * Clarified `<>` interactions with other extensions. + * Clarified {cl_khr_command_buffer_EXT} interactions with other extensions. * Specified error behavior when a command buffer is finalized multiple times. * Added new extension: - ** `<>` (provisional) + ** {cl_khr_command_buffer_mutable_dispatch_EXT} (provisional) Changes from *v3.0.12*: * Fixed the accuracy requirements description for half-precision math functions (those prefixed by `half_`). * Clarified that the semaphore type must always be provided when creating a semaphore. * Removed an unnecessary and contradictory error condition when creating a semaphore. - * Added an issue regarding non-linear image import to the `<>` extension. - * Added missing calls to {clBuildProgram} to the `<>` and `<>` sample code. + * Added an issue regarding non-linear image import to the {cl_khr_external_memory_EXT} extension. + * Added missing calls to {clBuildProgram} to the {cl_khr_command_buffer_EXT} and {cl_khr_command_buffer_mutable_dispatch_EXT} sample code. * Fixed a copy-paste error in the extensions quick reference appendix. * Fixed typos and improved formatting consistency in the extensions spec. Changes from *v3.0.13*: - * Corrected the precision for `cross` and `dot` to be based on `HALF_EPSILON` in `<>`, see {khronos-opencl-pr}/893[#893]. - * Added a context query for command-buffers to `<>`, see {khronos-opencl-pr}/899[#899]. - * Updated the semaphore wait and signal rules for binary semaphores in `<>`, see {khronos-opencl-pr}/882[#882]. - * Removed redundant error conditions from `<>` and `<>`, see {khronos-opencl-pr}/903[#903] and {khronos-opencl-pr}/904[#904]. + * Corrected the precision for `cross` and `dot` to be based on `HALF_EPSILON` in {cl_khr_fp16_EXT}, see {khronos-opencl-pr}/893[#893]. + * Added a context query for command-buffers to {cl_khr_command_buffer_EXT}, see {khronos-opencl-pr}/899[#899]. + * Updated the semaphore wait and signal rules for binary semaphores in {cl_khr_semaphore_EXT}, see {khronos-opencl-pr}/882[#882]. + * Removed redundant error conditions from {cl_khr_external_semaphore_EXT} and {cl_khr_external_memory_EXT}, see {khronos-opencl-pr}/903[#903] and {khronos-opencl-pr}/904[#904]. * Added new extension: - ** `<>` (provisional) + ** {cl_khr_command_buffer_multi_device_EXT} (provisional) Changes from *v3.0.14*: @@ -578,28 +578,28 @@ Changes from *v3.0.14*: * Clarified that {clSetCommandQueueProperty} is only required for OpenCL 1.0 devices and may return an error otherwise, see {khronos-opencl-pr}/980[#980]. * Clarified that the application must ensure the free function passed to {clEnqueueSVMFree} is thread safe, see {khronos-opencl-pr}/1016[#1016]. * Clarified that the application must ensure the user function passed to {clEnqueueNativeKernel} is thread safe, see {khronos-opencl-pr}/1026[#1026]. - * `<>` (provisional): + * {cl_khr_command_buffer_EXT} (provisional): ** Removed the "invalid" command buffer state, see {khronos-opencl-pr}/885[#885]. ** Added support for recording SVM memory copies and memory fills in a command buffer, see {khronos-opencl-pr}/915[#915]. - * `<>` (provisional): + * {cl_khr_command_buffer_multi_device_EXT} (provisional): ** Clarified that the sync devices query should only return root devices, see {khronos-opencl-pr}/925[#925]. - * `<>` (provisional): + * {cl_khr_external_memory_EXT} (provisional): ** Disallowed specifying a device handle list without also specifying an external memory handle, see {khronos-opencl-pr}/922[#922]. ** Added a query to determine the handle types an implementation will assume have a linear memory layout, see {khronos-opencl-pr}/940[#940]. ** Added an external memory-specific device handle list enum, see {khronos-opencl-pr}/956[#956]. ** Clarified that implementations may acquire information about an image from an external memory handle when the image is created, see {khronos-opencl-pr}/970[#970]. - * `<>` (provisional): + * {cl_khr_external_semaphore_EXT} (provisional): ** Added the ability to re-import "sync fd" handles into an existing semaphore, see {khronos-opencl-pr}/939[#939]. ** Clarified that a semaphore may only export one handle type, and that a semaphore created from an external handle cannot also export a handle, see {khronos-opencl-pr}/975[#975]. - ** Clarified that `<>` requires support for `<>`, see {khronos-opencl-pr}/976[#976]. + ** Clarified that {cl_khr_external_semaphore_EXT} requires support for {cl_khr_semaphore_EXT}, see {khronos-opencl-pr}/976[#976]. ** Added a query to determine if a semaphore may export an external handle, see {khronos-opencl-pr}/997[#997]. - * `<>` (provisional): + * {cl_khr_semaphore_EXT} (provisional): ** Added an semaphore-specific device handle list enum, see {khronos-opencl-pr}/956[#956]. ** Restricted semaphores to a single associated device, see {khronos-opencl-pr}/996[#996]. - * `<>`: + * {cl_khr_subgroup_rotate_EXT}: ** Clarified that only rotating within a subgroup is supported, see {khronos-opencl-pr}/967[#967]. Changes from *v3.0.15*: * Added new extensions: - ** `<>` (provisional) + ** {cl_khr_kernel_clock_EXT} (provisional) diff --git a/api/appendix_h.asciidoc b/api/appendix_h.asciidoc index 1bbd6f330..2a2d37598 100644 --- a/api/appendix_h.asciidoc +++ b/api/appendix_h.asciidoc @@ -313,7 +313,7 @@ When creating a 2D image from a buffer is not supported: | {clGetDeviceInfo}, passing + {CL_DEVICE_EXTENSIONS} -| Will not describe support for the `<>` extension if _device_ does not support creating a 2D image from a buffer. +| Will not describe support for the {cl_khr_image2d_from_buffer_EXT} extension if _device_ does not support creating a 2D image from a buffer. | {clCreateImage} or + {clCreateImageWithProperties}, passing + @@ -424,7 +424,7 @@ When sub-groups are not supported: | {clGetDeviceInfo}, passing + {CL_DEVICE_EXTENSIONS} -| Will not describe support for the `<>` extension if _device_ does not support sub-groups. +| Will not describe support for the {cl_khr_subgroups_EXT} extension if _device_ does not support sub-groups. | {clGetKernelSubGroupInfo} | Returns {CL_INVALID_OPERATION} if _device_ does not support sub-groups. @@ -468,7 +468,7 @@ When writing to 3D image objects is not supported: | {clGetDeviceInfo}, passing + {CL_DEVICE_EXTENSIONS} -| Will not describe support for the `<>` extension if _device_ does not support writing to 3D image objects. +| Will not describe support for the {cl_khr_3d_image_writes_EXT} extension if _device_ does not support writing to 3D image objects. | {clGetSupportedImageFormats}, passing + {CL_MEM_OBJECT_IMAGE3D} and one of + diff --git a/api/cl_khr_3d_image_writes.asciidoc b/api/cl_khr_3d_image_writes.asciidoc index 7c980404c..49e388f4b 100644 --- a/api/cl_khr_3d_image_writes.asciidoc +++ b/api/cl_khr_3d_image_writes.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_3d_image_writes.txt[] === Description -`cl_khr_3d_image_writes` adds built-in OpenCL C functions that allow a +{cl_khr_3d_image_writes_EXT} adds built-in OpenCL C functions that allow a kernel to write to 3D image objects in addition to 2D image objects. See the link:{OpenCLCSpecURL}#cl_khr_3d_image_writes[3D Image Writes] diff --git a/api/cl_khr_async_work_group_copy_fence.asciidoc b/api/cl_khr_async_work_group_copy_fence.asciidoc index 3ec9923c7..1c36daccb 100644 --- a/api/cl_khr_async_work_group_copy_fence.asciidoc +++ b/api/cl_khr_async_work_group_copy_fence.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_async_work_group_copy_fence.txt[] === Description -`cl_khr_async_work_group_copy_fence` adds a new built-in OpenCL C function +{cl_khr_async_work_group_copy_fence_EXT} adds a new built-in OpenCL C function to establish a memory synchronization ordering of asynchronous copies. See the link:{OpenCLCSpecURL}#cl_khr_async_work_group_copy_fence[Async diff --git a/api/cl_khr_byte_addressable_store.asciidoc b/api/cl_khr_byte_addressable_store.asciidoc index 56a32e6e2..cdff78462 100644 --- a/api/cl_khr_byte_addressable_store.asciidoc +++ b/api/cl_khr_byte_addressable_store.asciidoc @@ -16,7 +16,7 @@ include::{generated}/meta/{refprefix}cl_khr_byte_addressable_store.txt[] === Description -`cl_khr_byte_addressable_store` relaxes restrictions on pointers to `char`, +{cl_khr_byte_addressable_store_EXT} relaxes restrictions on pointers to `char`, `uchar`, `char2`, `uchar2`, `short`, `ushort` and `half` that were present in _Section 6.8m: Restrictions_ of the OpenCL 1.0 specification. With this extension, applications are able to read from and write to diff --git a/api/cl_khr_command_buffer.asciidoc b/api/cl_khr_command_buffer.asciidoc index e5da09a4f..8234aa43e 100644 --- a/api/cl_khr_command_buffer.asciidoc +++ b/api/cl_khr_command_buffer.asciidoc @@ -36,7 +36,7 @@ include::{generated}/meta/{refprefix}cl_khr_command_buffer.txt[] === Description -`cl_khr_command_buffer` adds the ability to record and replay buffers of +{cl_khr_command_buffer_EXT} adds the ability to record and replay buffers of OpenCL commands. Command-buffers enable a reduction in overhead when enqueuing the same @@ -121,18 +121,18 @@ the capability is optional to enable optimizations on command-buffer recording. === Interactions With Other Extensions The introduction of the command-buffer abstraction enables functionality -beyond what the `cl_khr_command_buffer` extension currently provides, i.e. +beyond what the {cl_khr_command_buffer_EXT} extension currently provides, i.e. the recording of immutable commands to a single queue which can then be executed without commands synchronizing outside the command-buffer. Extra functionality expanding on this is provided as layered extensions on top of -`cl_khr_command_buffer`. The layered extensions that currently exist are: +{cl_khr_command_buffer_EXT}. The layered extensions that currently exist are: -* `<>` -* `<>` +* {cl_khr_command_buffer_multi_device_EXT} +* {cl_khr_command_buffer_mutable_dispatch_EXT} -Having `cl_khr_command_buffer` as a minimal base specification means that the +Having {cl_khr_command_buffer_EXT} as a minimal base specification means that the API defines mechanisms for functionality that is not enabled by this extension, -these are described in the following sub-sections. `cl_khr_command_buffer` will +these are described in the following sub-sections. {cl_khr_command_buffer_EXT} will retain its provisional extension status until other layered extensions are released, as these may reveal modifications needed to the base specification to support their intended use cases. @@ -141,45 +141,45 @@ support their intended use cases. The {clCommandNDRangeKernelKHR} entry-point defines a `properties` parameter of new type {cl_ndrange_kernel_command_properties_khr_TYPE}. No properties are defined -in `cl_khr_command_buffer`, but the parameter enables layered extensions like -`<>` to define properties that inform +in {cl_khr_command_buffer_EXT}, but the parameter enables layered extensions like +{cl_khr_command_buffer_mutable_dispatch_EXT} to define properties that inform the characteristics of the kernel command. ==== Command Handles All command recording entry-points define a {cl_mutable_command_khr_TYPE} output parameter which provides a handle to the specific command being recorded. Use of -these output handles is not enabled by the `cl_khr_command_buffer` extension, +these output handles is not enabled by the {cl_khr_command_buffer_EXT} extension, but the handles allow individual commands in a command-buffer to be referenced by the user. -Use of these handles is enabled in `<>` +Use of these handles is enabled in {cl_khr_command_buffer_mutable_dispatch_EXT} to give the capability for an application to use the handles to modify commands between enqueues of a command-buffer. ==== List of Queues Only a single command-queue can be associated with a command-buffer in the -`cl_khr_command_buffer` extension, but the API is designed so that the layered -`<>` extension can relax this constraint +{cl_khr_command_buffer_EXT} extension, but the API is designed so that the layered +{cl_khr_command_buffer_multi_device_EXT} extension can relax this constraint to allow commands to be recorded across multiple queues in the same command-buffer, providing replay of heterogeneous task graphs. Using multiple queue functionality will result in an error without -`<>` to relax usage of the following API +{cl_khr_command_buffer_multi_device_EXT} to relax usage of the following API features: * When a command-buffer is created the API enables passing a list of queues that the command-buffer will record commands to. Only a single queue is - permitted in `cl_khr_command_buffer`. + permitted in {cl_khr_command_buffer_EXT}. * Individual command recording entry-points define a {cl_command_queue_TYPE} parameter for which of the queues set on command-buffer creation that command - should be record to. This must be passed as NULL in `cl_khr_command_buffer`. + should be record to. This must be passed as NULL in {cl_khr_command_buffer_EXT}. * {clEnqueueCommandBufferKHR} takes a list of queues for command-buffer execution, correspond to those set on creation. Only a single queue is permitted in - `cl_khr_command_buffer`. + {cl_khr_command_buffer_EXT}. // The 'New ...' section can be auto-generated diff --git a/api/cl_khr_command_buffer_multi_device.asciidoc b/api/cl_khr_command_buffer_multi_device.asciidoc index 26d2d72ea..8a595a5b3 100644 --- a/api/cl_khr_command_buffer_multi_device.asciidoc +++ b/api/cl_khr_command_buffer_multi_device.asciidoc @@ -28,20 +28,20 @@ include::{generated}/meta/{refprefix}cl_khr_command_buffer_multi_device.txt[] === Description -The `cl_khr_command_buffer` extension separates command construction from +The {cl_khr_command_buffer_EXT} extension separates command construction from enqueue by providing a mechanism to record a set of commands which can then be repeatedly enqueued. However, the commands in a command-buffer can only be recorded to a single command-queue specified on command-buffer creation. -`cl_khr_command_buffer_multi_device` extends the scope of a command-buffer +{cl_khr_command_buffer_multi_device_EXT} extends the scope of a command-buffer to allow commands to be recorded across multiple queues in the same command-buffer, providing execution of heterogeneous task graphs from command-queues associated with different devices. The ability for a user to deep copy an existing command-buffer so that the commands target a different device is also made possible by -`cl_khr_command_buffer_multi_device`. +{cl_khr_command_buffer_multi_device_EXT}. Depending on platform support the mapping of commands to the new target device can be done either explicitly by the user, or automatically by the OpenCL runtime. diff --git a/api/cl_khr_command_buffer_mutable_dispatch.asciidoc b/api/cl_khr_command_buffer_mutable_dispatch.asciidoc index 8883fc837..13ada6c22 100644 --- a/api/cl_khr_command_buffer_mutable_dispatch.asciidoc +++ b/api/cl_khr_command_buffer_mutable_dispatch.asciidoc @@ -28,13 +28,13 @@ include::{generated}/meta/{refprefix}cl_khr_command_buffer_mutable_dispatch.txt[ === Description -The `<>` extension separates command construction +The {cl_khr_command_buffer_EXT} extension separates command construction from enqueue by providing a mechanism to record a set of commands which can then be repeatedly enqueued. However, the commands recorded to the command-buffer are immutable between enqueues. -`cl_khr_command_buffer_mutable_dispatch` removes this restriction. +{cl_khr_command_buffer_mutable_dispatch_EXT} removes this restriction. In particular, this extension allows the configuration of a kernel execution command in a command-buffer, called a _mutable-dispatch_, to be modified. This allows inputs and outputs to the kernel, as well as work-item sizes and @@ -46,10 +46,10 @@ in a new command-buffer. The {cl_command_buffer_structure_type_khr_TYPE} type has been added to this extension for the purpose of allowing expansion of mutable functionality in future extensions layered on top of -`cl_khr_command_buffer_mutable_dispatch`. +{cl_khr_command_buffer_mutable_dispatch_EXT}. Any parameter that is a structure containing a `void* next` member *must* have a value of `next` that is either `NULL`, or is a pointer to a valid -structure defined by `cl_khr_command_buffer_mutable_dispatch` or an +structure defined by {cl_khr_command_buffer_mutable_dispatch_EXT} or an extension layered on top. To be a valid structure in the pointer chain the first member of the structure *must* be a {cl_command_buffer_structure_type_khr_TYPE} identifier @@ -64,7 +64,7 @@ Vulkan specification. ==== This is designed so that another extension layered on -`cl_khr_command_buffer_mutable_dispatch` could allow modification of +{cl_khr_command_buffer_mutable_dispatch_EXT} could allow modification of commands recorded to a command-buffer other than kernel execution commands. As all command recording entry-points return a {cl_mutable_command_khr_TYPE} handle, and aspects like which {cl_mem_TYPE} object a command uses could diff --git a/api/cl_khr_create_command_queue.asciidoc b/api/cl_khr_create_command_queue.asciidoc index fe6bf0c08..89e22e1d6 100644 --- a/api/cl_khr_create_command_queue.asciidoc +++ b/api/cl_khr_create_command_queue.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_create_command_queue.txt[] === Description -`cl_khr_create_command_queue` allows OpenCL 1.x devices to support an +{cl_khr_create_command_queue_EXT} allows OpenCL 1.x devices to support an equivalent of the {clCreateCommandQueueWithProperties} API that was added in OpenCL 2.0. This allows OpenCL 1.x devices to support other optional extensions or diff --git a/api/cl_khr_d3d10_sharing.asciidoc b/api/cl_khr_d3d10_sharing.asciidoc index 0a69e5e89..96532a430 100644 --- a/api/cl_khr_d3d10_sharing.asciidoc +++ b/api/cl_khr_d3d10_sharing.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_d3d10_sharing.txt[] === Description -`cl_khr_d3d10_sharing` provides interoperability between OpenCL and Direct3D 10. +{cl_khr_d3d10_sharing_EXT} provides interoperability between OpenCL and Direct3D 10. === New Commands diff --git a/api/cl_khr_d3d11_sharing.asciidoc b/api/cl_khr_d3d11_sharing.asciidoc index e0573b296..c3fdd8154 100644 --- a/api/cl_khr_d3d11_sharing.asciidoc +++ b/api/cl_khr_d3d11_sharing.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_d3d11_sharing.txt[] === Description -`cl_khr_d3d11_sharing` provides interoperability between OpenCL and Direct3D 11. +{cl_khr_d3d11_sharing_EXT} provides interoperability between OpenCL and Direct3D 11. === New Commands diff --git a/api/cl_khr_depth_images.asciidoc b/api/cl_khr_depth_images.asciidoc index 73469eecc..61ceb60ae 100644 --- a/api/cl_khr_depth_images.asciidoc +++ b/api/cl_khr_depth_images.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_depth_images.txt[] === Description -`cl_khr_depth_images` adds OpenCL C support for depth images. +{cl_khr_depth_images_EXT} adds OpenCL C support for depth images. See the link:{OpenCLCSpecURL}#cl_khr_depth_images[Depth Images] section of the OpenCL C specification for more information. diff --git a/api/cl_khr_device_enqueue_local_arg_types.asciidoc b/api/cl_khr_device_enqueue_local_arg_types.asciidoc index ee3acb41b..1adcbd60c 100644 --- a/api/cl_khr_device_enqueue_local_arg_types.asciidoc +++ b/api/cl_khr_device_enqueue_local_arg_types.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_device_enqueue_local_arg_types.txt[] === Description -`cl_khr_device_enqueue_local_arg_types` allows arguments to blocks that are +{cl_khr_device_enqueue_local_arg_types_EXT} allows arguments to blocks that are passed to the *enqueue_kernel* built-in OpenCL C function to be pointers to any type (built-in or user-defined) in local memory, instead of requiring arguments to blocks to be pointers to void in local memory. diff --git a/api/cl_khr_device_uuid.asciidoc b/api/cl_khr_device_uuid.asciidoc index 87f803daf..74b4f00b8 100644 --- a/api/cl_khr_device_uuid.asciidoc +++ b/api/cl_khr_device_uuid.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_device_uuid.txt[] === Description -`cl_khr_device_uuid` adds the ability to query a universally unique +{cl_khr_device_uuid_EXT} adds the ability to query a universally unique identifier (UUID) for an OpenCL driver and OpenCL device. The UUIDs returned by the query may be used to identify drivers and devices across processes or APIs. diff --git a/api/cl_khr_dx9_media_sharing.asciidoc b/api/cl_khr_dx9_media_sharing.asciidoc index 91fd3dad4..7f887bcf5 100644 --- a/api/cl_khr_dx9_media_sharing.asciidoc +++ b/api/cl_khr_dx9_media_sharing.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_dx9_media_sharing.txt[] === Description -`cl_khr_dx9_media_sharing` allows applications to use media surfaces as +{cl_khr_dx9_media_sharing_EXT} allows applications to use media surfaces as OpenCL memory objects. This allows efficient sharing of data between OpenCL and selected adapter APIs (only DX9 for now). diff --git a/api/cl_khr_egl_event.asciidoc b/api/cl_khr_egl_event.asciidoc index 106bb82ec..278dec5a2 100644 --- a/api/cl_khr_egl_event.asciidoc +++ b/api/cl_khr_egl_event.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_egl_event.txt[] === Description -`cl_khr_egl_event` allows creating OpenCL event objects linked to EGL fence +{cl_khr_egl_event_EXT} allows creating OpenCL event objects linked to EGL fence sync objects, potentially improving efficiency of sharing images and buffers between the two APIs. The companion `EGL_KHR_cl_event` extension provides the complementary @@ -31,7 +31,7 @@ functionality of creating an EGL sync object from an OpenCL event object. === Issues -Most issues are shared with `<>` and are resolved as +Most issues are shared with {cl_khr_gl_event_EXT} and are resolved as described in that extension. . Should we support implicit synchronization? diff --git a/api/cl_khr_egl_image.asciidoc b/api/cl_khr_egl_image.asciidoc index 0d1b0df27..d31989430 100644 --- a/api/cl_khr_egl_image.asciidoc +++ b/api/cl_khr_egl_image.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_egl_image.txt[] === Description -`cl_khr_egl_image` provides a mechanism to creating OpenCL memory objects +{cl_khr_egl_image_EXT} provides a mechanism to creating OpenCL memory objects from from EGLImages. === New Commands @@ -96,7 +96,7 @@ needed to represent those image types. The basic portable form of synchronization is to use a {clFinish}, as is the case for GL interop. In addition implementations which support the synchronization extensions -`<>` and `EGL_KHR_cl_event` can interoperate more +{cl_khr_egl_event_EXT} and `EGL_KHR_cl_event` can interoperate more efficiently as described in those extensions. -- diff --git a/api/cl_khr_expect_assume.asciidoc b/api/cl_khr_expect_assume.asciidoc index c5559a134..615a0d559 100644 --- a/api/cl_khr_expect_assume.asciidoc +++ b/api/cl_khr_expect_assume.asciidoc @@ -19,7 +19,7 @@ include::{generated}/meta/{refprefix}cl_khr_expect_assume.txt[] === Description -`cl_khr_expect_assume` adds mechanisms to provide information to the +{cl_khr_expect_assume_EXT} adds mechanisms to provide information to the compiler that may improve the performance of some kernels. Specifically, this extension adds the ability to: diff --git a/api/cl_khr_extended_async_copies.asciidoc b/api/cl_khr_extended_async_copies.asciidoc index 0fac1890f..e04cf7a40 100644 --- a/api/cl_khr_extended_async_copies.asciidoc +++ b/api/cl_khr_extended_async_copies.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_extended_async_copies.txt[] === Description -`cl_khr_extended_async_copies` augments built-in OpenCL C asynchronous copy +{cl_khr_extended_async_copies_EXT} augments built-in OpenCL C asynchronous copy functions to support more patterns: . For async copy between 2D source and 2D destination. diff --git a/api/cl_khr_extended_bit_ops.asciidoc b/api/cl_khr_extended_bit_ops.asciidoc index b516f1a23..766306ff4 100644 --- a/api/cl_khr_extended_bit_ops.asciidoc +++ b/api/cl_khr_extended_bit_ops.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_extended_bit_ops.txt[] === Description -`cl_khr_extended_bit_ops` adds built-in OpenCL C functions for performing +{cl_khr_extended_bit_ops_EXT} adds built-in OpenCL C functions for performing extended bit operations. Specifically, the following functions are added: diff --git a/api/cl_khr_extended_versioning.asciidoc b/api/cl_khr_extended_versioning.asciidoc index d67e61f0a..27f651b8b 100644 --- a/api/cl_khr_extended_versioning.asciidoc +++ b/api/cl_khr_extended_versioning.asciidoc @@ -17,7 +17,7 @@ include::{generated}/meta/{refprefix}cl_khr_extended_versioning.txt[] === Description -The `cl_khr_extended_versioning` extension introduces new platform and +The {cl_khr_extended_versioning_EXT} extension introduces new platform and device queries that return detailed version information to applications. It makes it possible to return the exact revision of the specification or intermediate languages supported by an implementation. @@ -131,7 +131,7 @@ there are no elements to return? . Should the queries for which the old-style query doesn't exist in a given OpenCL version be present (e.g. {CL_DEVICE_BUILT_IN_KERNELS_WITH_VERSION_KHR} prior to OpenCL 2.1 or - without support for `<>` or + without support for {cl_khr_il_program_EXT} or {CL_DEVICE_OPENCL_C_NUMERIC_VERSION_KHR} on OpenCL 1.0)? + -- diff --git a/api/cl_khr_external_memory.asciidoc b/api/cl_khr_external_memory.asciidoc index dbe5e6a95..6da4455de 100644 --- a/api/cl_khr_external_memory.asciidoc +++ b/api/cl_khr_external_memory.asciidoc @@ -35,7 +35,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory.txt[] === Description -`cl_khr_external_memory` defines a generic mechanism to share buffer and +{cl_khr_external_memory_EXT} defines a generic mechanism to share buffer and image objects between OpenCL and many other APIs, including: * Optional properties to import external memory exported by other APIs @@ -90,7 +90,7 @@ TODO ==== Example for Creating a CL Buffer From an Exported External Buffer in a Single Device Context -This example also requires use of the `<>` +This example also requires use of the {cl_khr_external_memory_opaque_fd_EXT} extension. [source] @@ -124,7 +124,7 @@ cl_mem extMemBuffer = clCreateBufferWithProperties(/*context*/ clContex ==== Example for Creating a CL Image From an Exported External Image for Single Device Usage in a Multi-Device Context -This example also requires use of the `<>` +This example also requires use of the {cl_khr_external_memory_opaque_fd_EXT} extension. [source] diff --git a/api/cl_khr_external_memory_dma_buf.asciidoc b/api/cl_khr_external_memory_dma_buf.asciidoc index be578969e..071aed992 100644 --- a/api/cl_khr_external_memory_dma_buf.asciidoc +++ b/api/cl_khr_external_memory_dma_buf.asciidoc @@ -7,7 +7,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_dma_buf.txt[] //@ 0.9.3 //@ *Extension and Version Dependencies*:: //@ This extension requires OpenCL 3.0. -//@ This extension requires the `<>` extension. +//@ This extension requires the {cl_khr_external_memory_EXT} extension. === Other Extension Metadata @@ -36,7 +36,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_dma_buf.txt[] === Description -`cl_khr_external_memory_dma_buf` extends +{cl_khr_external_memory_dma_buf_EXT} extends {cl_external_memory_handle_type_khr_TYPE} to support Linux `dma_buf` as an external memory handle type that may be specified when creating a buffer or image memory object. diff --git a/api/cl_khr_external_memory_dx.asciidoc b/api/cl_khr_external_memory_dx.asciidoc index a0be41b1b..ab79949f3 100644 --- a/api/cl_khr_external_memory_dx.asciidoc +++ b/api/cl_khr_external_memory_dx.asciidoc @@ -7,7 +7,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_dx.txt[] //@ 0.9.3 //@ *Extension and Version Dependencies*:: //@ This extension requires OpenCL 3.0. -//@ This extension requires the `<>` extension. +//@ This extension requires the {cl_khr_external_memory_EXT} extension. === Other Extension Metadata @@ -36,7 +36,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_dx.txt[] === Description -`cl_khr_external_memory_dx` extends +{cl_khr_external_memory_dx_EXT} extends {cl_external_memory_handle_type_khr_TYPE} to support Windows handles referring to Direct 3D resources as external memory handle types that may be specified when creating a buffer or image memory object. diff --git a/api/cl_khr_external_memory_opaque_fd.asciidoc b/api/cl_khr_external_memory_opaque_fd.asciidoc index 208b2391b..3d7c059e3 100644 --- a/api/cl_khr_external_memory_opaque_fd.asciidoc +++ b/api/cl_khr_external_memory_opaque_fd.asciidoc @@ -7,7 +7,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_opaque_fd.txt[] //@ 0.9.3 //@ *Extension and Version Dependencies*:: //@ This extension requires OpenCL 3.0. -//@ This extension requires the `<>` extension. +//@ This extension requires the {cl_khr_external_memory_EXT} extension. === Other Extension Metadata @@ -36,7 +36,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_opaque_fd.txt[] === Description -`cl_khr_external_memory_opaque_fd` extends +{cl_khr_external_memory_opaque_fd_EXT} extends {cl_external_memory_handle_type_khr_TYPE} to support a POSIX file descriptor handle as an external memory handle type that may be specified when creating a buffer or image memory object. diff --git a/api/cl_khr_external_memory_win32.asciidoc b/api/cl_khr_external_memory_win32.asciidoc index 65f3dc337..bfb03d853 100644 --- a/api/cl_khr_external_memory_win32.asciidoc +++ b/api/cl_khr_external_memory_win32.asciidoc @@ -7,7 +7,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_win32.txt[] //@ 0.9.3 //@ *Extension and Version Dependencies*:: //@ This extension requires OpenCL 3.0. -//@ This extension requires the `<>` extension. +//@ This extension requires the {cl_khr_external_memory_EXT} extension. === Other Extension Metadata @@ -36,7 +36,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_win32.txt[] === Description -`cl_khr_external_memory_win32` extends +{cl_khr_external_memory_win32_EXT} extends {cl_external_memory_handle_type_khr_TYPE} to support Windows handles as external memory handle types that may be specified when creating a buffer or image memory object. diff --git a/api/cl_khr_external_semaphore.asciidoc b/api/cl_khr_external_semaphore.asciidoc index 0671f544a..c5debcc7f 100644 --- a/api/cl_khr_external_semaphore.asciidoc +++ b/api/cl_khr_external_semaphore.asciidoc @@ -9,7 +9,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_semaphore.txt[] 2021-09-10 *Interactions and External Dependencies*:: * This extension requires OpenCL 1.2. - * The `<>` extension is required as it defines semaphore + * The {cl_khr_semaphore_EXT} extension is required as it defines semaphore objects as well as for wait and signal operations on semaphores. * For OpenCL to be able to import external semaphores from other APIs using this extension, the other API is required to provide below @@ -44,7 +44,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_semaphore.txt[] === Description -`cl_khr_semaphore` introduced semaphores as a new type along with a set of +{cl_khr_semaphore_EXT} introduced semaphores as a new type along with a set of APIs for create, release, retain, wait and signal operations on it. This extension defines APIs and mechanisms to share semaphores created in an external API by importing into and exporting from OpenCL. @@ -65,10 +65,10 @@ This extension defines: semaphores created from different handle types. * API query exportable semaphores handles using specified handle type. -The layered extensions `<>`, -`<>`, -`<>`, and -`<>` define specific external semaphores +The layered extensions {cl_khr_external_semaphore_dx_fence_EXT}, +{cl_khr_external_semaphore_opaque_fd_EXT}, +{cl_khr_external_semaphore_sync_fd_EXT}, and +{cl_khr_external_semaphore_win32_EXT} define specific external semaphores that may be imported into or exported from OpenCL. === New Types @@ -91,7 +91,7 @@ that may be imported into or exported from OpenCL. === Sample Code -The following examples use the `<>` +The following examples use the {cl_khr_external_semaphore_opaque_fd_EXT} extension to obtain an external semaphore. Similar code can be written using the other layered extensions. @@ -281,5 +281,5 @@ while (true) { * Revision 0.9.1, 2023-11-16 ** Added {CL_SEMAPHORE_EXPORTABLE_KHR}. * Revision 0.9.2, 2023-11-21 - ** Added re-import function call to `<>` + ** Added re-import function call to {cl_khr_external_semaphore_sync_fd_EXT} diff --git a/api/cl_khr_external_semaphore_dx_fence.asciidoc b/api/cl_khr_external_semaphore_dx_fence.asciidoc index 1fd274587..e3cc259b3 100644 --- a/api/cl_khr_external_semaphore_dx_fence.asciidoc +++ b/api/cl_khr_external_semaphore_dx_fence.asciidoc @@ -30,9 +30,9 @@ include::{generated}/meta/{refprefix}cl_khr_external_semaphore_dx_fence.txt[] === Description -`cl_khr_external_semaphore_dx_fence` supports importing and exporting a +{cl_khr_external_semaphore_dx_fence_EXT} supports importing and exporting a D3D12 fence as an external semaphore using the APIs introduced by -`<>`. +{cl_khr_external_semaphore_EXT}. === New Enums diff --git a/api/cl_khr_external_semaphore_opaque_fd.asciidoc b/api/cl_khr_external_semaphore_opaque_fd.asciidoc index b74a93884..eb7cc4563 100644 --- a/api/cl_khr_external_semaphore_opaque_fd.asciidoc +++ b/api/cl_khr_external_semaphore_opaque_fd.asciidoc @@ -30,9 +30,9 @@ include::{generated}/meta/{refprefix}cl_khr_external_semaphore_opaque_fd.txt[] === Description -`cl_khr_external_semaphore_opaque_fd` supports importing and exporting a +{cl_khr_external_semaphore_opaque_fd_EXT} supports importing and exporting a restricted POSIX file descriptor as an external semaphore using the APIs -introduced by `<>`. +introduced by {cl_khr_external_semaphore_EXT}. === New Enums diff --git a/api/cl_khr_external_semaphore_sync_fd.asciidoc b/api/cl_khr_external_semaphore_sync_fd.asciidoc index 0368bdee3..4d7e88922 100644 --- a/api/cl_khr_external_semaphore_sync_fd.asciidoc +++ b/api/cl_khr_external_semaphore_sync_fd.asciidoc @@ -30,10 +30,10 @@ include::{generated}/meta/{refprefix}cl_khr_external_semaphore_sync_fd.txt[] === Description -`cl_khr_external_semaphore_sync_fd` supports importing and exporting a POSIX +{cl_khr_external_semaphore_sync_fd_EXT} supports importing and exporting a POSIX file descriptor handle to a Linux Sync File or Android Fence object as an external semaphore using the APIs introduced by -`<>`. +{cl_khr_external_semaphore_EXT}. === New Commands @@ -55,4 +55,4 @@ external semaphore using the APIs introduced by * Revision 0.9.1, 2023-11-16 ** Added {CL_SEMAPHORE_EXPORTABLE_KHR}. * Revision 0.9.2, 2023-11-21 - ** Added re-import function call to `<>` + ** Added re-import function call to {cl_khr_external_semaphore_sync_fd_EXT} diff --git a/api/cl_khr_external_semaphore_win32.asciidoc b/api/cl_khr_external_semaphore_win32.asciidoc index e8b1a772a..725a59966 100644 --- a/api/cl_khr_external_semaphore_win32.asciidoc +++ b/api/cl_khr_external_semaphore_win32.asciidoc @@ -30,9 +30,9 @@ include::{generated}/meta/{refprefix}cl_khr_external_semaphore_win32.txt[] === Description -`cl_khr_external_semaphore_win32` supports importing and exporting an NT +{cl_khr_external_semaphore_win32_EXT} supports importing and exporting an NT handle or global share handle as an external semaphore using the APIs -introduced by `<>`. +introduced by {cl_khr_external_semaphore_EXT}. === New Enums diff --git a/api/cl_khr_fp16.asciidoc b/api/cl_khr_fp16.asciidoc index d2ebcd284..4b7feb139 100644 --- a/api/cl_khr_fp16.asciidoc +++ b/api/cl_khr_fp16.asciidoc @@ -17,7 +17,7 @@ include::{generated}/meta/{refprefix}cl_khr_fp16.txt[] === Description -`cl_khr_fp16` adds support to OpenCL C for half scalar and vector types as +{cl_khr_fp16_EXT} adds support to OpenCL C for half scalar and vector types as built-in types that can be used for arithmetic operations, conversions, etc. See the link:{OpenCLCSpecURL}#cl_khr_fp16[Half-Precision Floating-Point] diff --git a/api/cl_khr_fp64.asciidoc b/api/cl_khr_fp64.asciidoc index 9bb28c3a5..5006d8328 100644 --- a/api/cl_khr_fp64.asciidoc +++ b/api/cl_khr_fp64.asciidoc @@ -17,7 +17,7 @@ include::{generated}/meta/{refprefix}cl_khr_fp64.txt[] === Description -`cl_khr_fp64` adds support to OpenCL C for double-precision scalar and +{cl_khr_fp64_EXT} adds support to OpenCL C for double-precision scalar and vector types as built-in types that can be used for arithmetic operations, conversions, etc. diff --git a/api/cl_khr_gl_depth_images.asciidoc b/api/cl_khr_gl_depth_images.asciidoc index 470af9859..05258a612 100644 --- a/api/cl_khr_gl_depth_images.asciidoc +++ b/api/cl_khr_gl_depth_images.asciidoc @@ -14,8 +14,8 @@ include::{generated}/meta/{refprefix}cl_khr_gl_depth_images.txt[] === Description -`cl_khr_gl_depth_images` extends OpenCL / OpenGL sharing defined by the -`<>` extension to allow an OpenCL image to be created +{cl_khr_gl_depth_images_EXT} extends OpenCL / OpenGL sharing defined by the +{cl_khr_gl_sharing_EXT} extension to allow an OpenCL image to be created from an OpenGL depth or depth-stencil texture. Depth images with an image channel order of {CL_DEPTH_STENCIL} can only be diff --git a/api/cl_khr_gl_event.asciidoc b/api/cl_khr_gl_event.asciidoc index 2ee22f486..1239e79ff 100644 --- a/api/cl_khr_gl_event.asciidoc +++ b/api/cl_khr_gl_event.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_gl_event.txt[] === Description -`cl_khr_gl_event` allows creating OpenCL event objects linked to OpenGL +{cl_khr_gl_event_EXT} allows creating OpenCL event objects linked to OpenGL fence sync objects, potentially improving efficiency of sharing images and buffers between the two APIs. The companion `GL_ARB_cl_event` extension provides the complementary diff --git a/api/cl_khr_gl_msaa_sharing.asciidoc b/api/cl_khr_gl_msaa_sharing.asciidoc index eb0fed1ee..64f4557cd 100644 --- a/api/cl_khr_gl_msaa_sharing.asciidoc +++ b/api/cl_khr_gl_msaa_sharing.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_gl_msaa_sharing.txt[] === Description -`cl_khr_gl_msaa_sharing` extends the `<>` extension to +{cl_khr_gl_msaa_sharing_EXT} extends the {cl_khr_gl_sharing_EXT} extension to allow a shared OpenCL/OpenGL image object to be created from an OpenGL multi-sampled ("`MSAA`") color or depth texture. @@ -22,7 +22,7 @@ This extension adds multi-sample support to {clCreateFromGLTexture} and {clGetGLTextureInfo}, and allows <>. -This extension requires `<>`. +This extension requires {cl_khr_gl_depth_images_EXT}. See the link:{OpenCLCSpecURL}#cl_khr_gl_msaa_sharing[cl_khr_gl_msaa_sharing] section of the OpenCL C specification for more information. diff --git a/api/cl_khr_gl_sharing.asciidoc b/api/cl_khr_gl_sharing.asciidoc index 237d96511..779b94e37 100644 --- a/api/cl_khr_gl_sharing.asciidoc +++ b/api/cl_khr_gl_sharing.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_gl_sharing.txt[] === Description -The `cl_khr_gl_sharing` extension allows use of OpenGL buffer, texture, and +The {cl_khr_gl_sharing_EXT} extension allows use of OpenGL buffer, texture, and renderbuffer objects as OpenCL memory objects, referred to as "`Shared OpenCL/OpenGL Memory Objects`". @@ -217,7 +217,7 @@ binding layer API in use. + -- *RESOLVED*: These were not actual extensions, but the result of splitting -the `cl_khr_gl_sharing` extension language into two separate sections for +the {cl_khr_gl_sharing_EXT} extension language into two separate sections for publication. All extension language has now been integrated into the unified Specification and this distinction is not useful. diff --git a/api/cl_khr_global_int32_base_atomics.asciidoc b/api/cl_khr_global_int32_base_atomics.asciidoc index 36b331670..079a834c5 100644 --- a/api/cl_khr_global_int32_base_atomics.asciidoc +++ b/api/cl_khr_global_int32_base_atomics.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_global_int32_base_atomics.txt[] === Description -`cl_khr_global_int32_base_atomics` allows OpenCL C atomic operations to be +{cl_khr_global_int32_base_atomics_EXT} allows OpenCL C atomic operations to be performed on 32-bit signed and unsigned integers in global memory. This extension became a core feature in OpenCL 1.1, with the built-in atomic diff --git a/api/cl_khr_global_int32_extended_atomics.asciidoc b/api/cl_khr_global_int32_extended_atomics.asciidoc index e4fd74210..59831cb02 100644 --- a/api/cl_khr_global_int32_extended_atomics.asciidoc +++ b/api/cl_khr_global_int32_extended_atomics.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_global_int32_extended_atomics.txt[] === Description -`cl_khr_global_int32_extended_atomics` allows OpenCL C extended atomic +{cl_khr_global_int32_extended_atomics_EXT} allows OpenCL C extended atomic operations to be performed on 32-bit signed and unsigned integers in global memory. diff --git a/api/cl_khr_icd.asciidoc b/api/cl_khr_icd.asciidoc index fb99fb74f..9a4b46cc8 100644 --- a/api/cl_khr_icd.asciidoc +++ b/api/cl_khr_icd.asciidoc @@ -17,7 +17,7 @@ include::{generated}/meta/{refprefix}cl_khr_icd.txt[] === Description -`cl_khr_icd` describes a platform extension which defines a simple mechanism +{cl_khr_icd_EXT} describes a platform extension which defines a simple mechanism through which the Khronos OpenCL installable client driver loader (ICD Loader) may expose multiple separate vendor installable client drivers (Vendor ICDs) for OpenCL. @@ -225,7 +225,7 @@ ignore the library. Next the ICD Loader queries available ICD-enabled platforms in the library using {clIcdGetPlatformIDsKHR}. For each of these platforms, the ICD Loader queries the platform's extension -string to verify that `<>` is supported, then queries the +string to verify that {cl_khr_icd_EXT} is supported, then queries the platform's Vendor ICD extension suffix using {clGetPlatformInfo} with the value {CL_PLATFORM_ICD_SUFFIX_KHR}. diff --git a/api/cl_khr_il_program.asciidoc b/api/cl_khr_il_program.asciidoc index 472823546..b8d0c4846 100644 --- a/api/cl_khr_il_program.asciidoc +++ b/api/cl_khr_il_program.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_il_program.txt[] === Description -`cl_khr_il_program` adds the ability to create programs with intermediate +{cl_khr_il_program_EXT} adds the ability to create programs with intermediate language (IL), usually SPIR-V. Further information about the format and contents of SPIR-V may be found in the SPIR-V Specification. diff --git a/api/cl_khr_image2d_from_buffer.asciidoc b/api/cl_khr_image2d_from_buffer.asciidoc index cb3f29eb0..be7783c35 100644 --- a/api/cl_khr_image2d_from_buffer.asciidoc +++ b/api/cl_khr_image2d_from_buffer.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_image2d_from_buffer.txt[] === Description -`cl_khr_image2d_from_buffer` allows a 2D image to be created from an +{cl_khr_image2d_from_buffer_EXT} allows a 2D image to be created from an existing OpenCL buffer memory object. This extension became a core feature in OpenCL 2.0. diff --git a/api/cl_khr_initialize_memory.asciidoc b/api/cl_khr_initialize_memory.asciidoc index 8eddeedff..f2c0ce800 100644 --- a/api/cl_khr_initialize_memory.asciidoc +++ b/api/cl_khr_initialize_memory.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_initialize_memory.txt[] === Description -`cl_khr_initialize_memory` adds OpenCL C support for initializing local and +{cl_khr_initialize_memory_EXT} adds OpenCL C support for initializing local and private memory before a kernel begins execution. This is accomplished by specifying a flag at context creation time affecting all such memory. diff --git a/api/cl_khr_int64_base_atomics.asciidoc b/api/cl_khr_int64_base_atomics.asciidoc index 8723cab2c..ac688d915 100644 --- a/api/cl_khr_int64_base_atomics.asciidoc +++ b/api/cl_khr_int64_base_atomics.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_int64_base_atomics.txt[] === Description -`cl_khr_int64_base_atomics` adds built-in OpenCL functions supporting atomic +{cl_khr_int64_base_atomics_EXT} adds built-in OpenCL functions supporting atomic operations to be performed on 64-bit signed and unsigned integers in global and local memory. diff --git a/api/cl_khr_int64_extended_atomics.asciidoc b/api/cl_khr_int64_extended_atomics.asciidoc index f4fab1075..69416081c 100644 --- a/api/cl_khr_int64_extended_atomics.asciidoc +++ b/api/cl_khr_int64_extended_atomics.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_int64_extended_atomics.txt[] === Description -`cl_khr_int64_extended_atomics` adds built-in OpenCL functions supporting +{cl_khr_int64_extended_atomics_EXT} adds built-in OpenCL functions supporting extended atomic operations to be performed on 64-bit signed and unsigned integers in global and local memory. diff --git a/api/cl_khr_integer_dot_product.asciidoc b/api/cl_khr_integer_dot_product.asciidoc index 38377238d..257401f9d 100644 --- a/api/cl_khr_integer_dot_product.asciidoc +++ b/api/cl_khr_integer_dot_product.asciidoc @@ -20,11 +20,11 @@ include::{generated}/meta/{refprefix}cl_khr_integer_dot_product.txt[] === Description -`cl_khr_integer_dot_product` adds support for SPIR-V instructions and OpenCL +{cl_khr_integer_dot_product_EXT} adds support for SPIR-V instructions and OpenCL C built-in functions to compute the dot product of vectors of integers. OpenCL C compilers supporting this extension will define the extension macro -`cl_khr_integer_dot_product`, and may define corresponding feature macros +{cl_khr_integer_dot_product_EXT}, and may define corresponding feature macros {opencl_c_integer_dot_product_input_4x8bit} and {opencl_c_integer_dot_product_input_4x8bit_packed} depending on the reported capabilities. diff --git a/api/cl_khr_local_int32_base_atomics.asciidoc b/api/cl_khr_local_int32_base_atomics.asciidoc index 4fba21aa5..51300f0c5 100644 --- a/api/cl_khr_local_int32_base_atomics.asciidoc +++ b/api/cl_khr_local_int32_base_atomics.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_local_int32_base_atomics.txt[] === Description -`cl_khr_local_int32_base_atomics` allows OpenCL C atomic operations to be +{cl_khr_local_int32_base_atomics_EXT} allows OpenCL C atomic operations to be performed on 32-bit signed and unsigned integers in local memory. This extension became a core feature in OpenCL 1.1, with the built-in atomic diff --git a/api/cl_khr_local_int32_extended_atomics.asciidoc b/api/cl_khr_local_int32_extended_atomics.asciidoc index 05b5d0cab..917d2e26a 100644 --- a/api/cl_khr_local_int32_extended_atomics.asciidoc +++ b/api/cl_khr_local_int32_extended_atomics.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_local_int32_extended_atomics.txt[] === Description -`cl_khr_local_int32_extended_atomics` allows OpenCL C extended atomic +{cl_khr_local_int32_extended_atomics_EXT} allows OpenCL C extended atomic operations to be performed on 32-bit signed and unsigned integers in local memory. diff --git a/api/cl_khr_mipmap_image.asciidoc b/api/cl_khr_mipmap_image.asciidoc index ab2a7fe0f..a500ed507 100644 --- a/api/cl_khr_mipmap_image.asciidoc +++ b/api/cl_khr_mipmap_image.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_mipmap_image.txt[] === Description -The `cl_khr_mipmap_image` extension adds the ability to create and access +The {cl_khr_mipmap_image_EXT} extension adds the ability to create and access mipmapped images: * {clCreateImage} is extended to create mipmapped images. diff --git a/api/cl_khr_mipmap_image_writes.asciidoc b/api/cl_khr_mipmap_image_writes.asciidoc index 84278ce60..7051ca598 100644 --- a/api/cl_khr_mipmap_image_writes.asciidoc +++ b/api/cl_khr_mipmap_image_writes.asciidoc @@ -14,11 +14,11 @@ include::{generated}/meta/{refprefix}cl_khr_mipmap_image_writes.txt[] === Description -The `cl_khr_mipmap_image_writes` extension adds OpenCL C built-in functions +The {cl_khr_mipmap_image_writes_EXT} extension adds OpenCL C built-in functions to write to a mipmapped image. -If `cl_khr_mipmap_image_writes` is supported by the OpenCL device, the -`<>` extension must also be supported. +If {cl_khr_mipmap_image_writes_EXT} is supported by the OpenCL device, the +{cl_khr_mipmap_image_EXT} extension must also be supported. See the link:{OpenCLCSpecURL}#cl_khr_mipmap_image_writes[Mipmapped Image Writes] section of the OpenCL C specification for more information. diff --git a/api/cl_khr_pci_bus_info.asciidoc b/api/cl_khr_pci_bus_info.asciidoc index 0f5a87ed4..3477565b5 100644 --- a/api/cl_khr_pci_bus_info.asciidoc +++ b/api/cl_khr_pci_bus_info.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_pci_bus_info.txt[] === Description -The `cl_khr_pci_bus_info` extension adds a new query to obtain PCI bus +The {cl_khr_pci_bus_info_EXT} extension adds a new query to obtain PCI bus information about an OpenCL device. Not all OpenCL devices have PCI bus information, either due to the device diff --git a/api/cl_khr_priority_hints.asciidoc b/api/cl_khr_priority_hints.asciidoc index d36c20831..1e7981dd3 100644 --- a/api/cl_khr_priority_hints.asciidoc +++ b/api/cl_khr_priority_hints.asciidoc @@ -14,14 +14,14 @@ include::{generated}/meta/{refprefix}cl_khr_priority_hints.txt[] === Description -The `cl_khr_priority_hints` extension adds priority hints for OpenCL, but +The {cl_khr_priority_hints_EXT} extension adds priority hints for OpenCL, but does not specify the scheduling behavior or minimum guarantees. It is expected that the the user guides associated with each implementation which supports this extension will describe the scheduling behavior guarantees. Note that the priority hint is orthogonal to functionality defined in the -`<>` extension. +{cl_khr_throttle_hints_EXT} extension. For example, a task may have high priority ({CL_QUEUE_PRIORITY_HIGH_KHR}) but should at the same time be executed at an optimized throttle setting ({CL_QUEUE_THROTTLE_LOW_KHR}). diff --git a/api/cl_khr_select_fprounding_mode.asciidoc b/api/cl_khr_select_fprounding_mode.asciidoc index c97814158..25a1fa4c3 100644 --- a/api/cl_khr_select_fprounding_mode.asciidoc +++ b/api/cl_khr_select_fprounding_mode.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_select_fprounding_mode.txt[] === Description -`cl_khr_select_fprounding_mode` allows an application to specify the +{cl_khr_select_fprounding_mode_EXT} allows an application to specify the rounding mode for an instruction or group of instructions in the OpenCL C program source. diff --git a/api/cl_khr_semaphore.asciidoc b/api/cl_khr_semaphore.asciidoc index 1d3af4634..5328e51c3 100644 --- a/api/cl_khr_semaphore.asciidoc +++ b/api/cl_khr_semaphore.asciidoc @@ -39,7 +39,7 @@ work-submissions, they suffer from following limitations: * They are immutable. * They are not reusable. -`cl_khr_semaphore` introduces a new type of synchronization object to +{cl_khr_semaphore_EXT} introduces a new type of synchronization object to represent _semaphores_ that can be reused, waited on, and signaled multiple times by OpenCL work-submissions. diff --git a/api/cl_khr_spir.asciidoc b/api/cl_khr_spir.asciidoc index 6776a9cc6..d794497d6 100644 --- a/api/cl_khr_spir.asciidoc +++ b/api/cl_khr_spir.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_spir.txt[] === Description -`cl_khr_spir` adds the ability to create an OpenCL program object from a +{cl_khr_spir_EXT} adds the ability to create an OpenCL program object from a Standard Portable Intermediate Representation (SPIR) instance. A SPIR instance is a vendor-neutral non-source representation for OpenCL C programs. @@ -22,8 +22,8 @@ programs. See the <> for information on compiling SPIR binaries. -`cl_khr_spir` has been superseded by the SPIR-V intermediate representation, -which is supported by the `<>` extension, and is a core +{cl_khr_spir_EXT} has been superseded by the SPIR-V intermediate representation, +which is supported by the {cl_khr_il_program_EXT} extension, and is a core feature in OpenCL 2.1. === New Enums diff --git a/api/cl_khr_srgb_image_writes.asciidoc b/api/cl_khr_srgb_image_writes.asciidoc index e12ccb362..95ca39656 100644 --- a/api/cl_khr_srgb_image_writes.asciidoc +++ b/api/cl_khr_srgb_image_writes.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_srgb_image_writes.txt[] === Description -`cl_khr_srgb_image_writes` enables OpenCL C kernels to write to sRGB images +{cl_khr_srgb_image_writes_EXT} enables OpenCL C kernels to write to sRGB images using the *write_imagef* built-in function. The sRGB image formats that may be written to will be returned by {clGetSupportedImageFormats}. diff --git a/api/cl_khr_subgroup_ballot.asciidoc b/api/cl_khr_subgroup_ballot.asciidoc index 0978f2d66..f0cc70d64 100644 --- a/api/cl_khr_subgroup_ballot.asciidoc +++ b/api/cl_khr_subgroup_ballot.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_ballot.txt[] === Description -`cl_khr_subgroup_ballot` adds built-in OpenCL C functions with the ability +{cl_khr_subgroup_ballot_EXT} adds built-in OpenCL C functions with the ability to collect and operate on ballots from work items in a sub-group. See the link:{OpenCLCSpecURL}#cl_khr_subgroup_ballot[Sub-Group Ballots] diff --git a/api/cl_khr_subgroup_clustered_reduce.asciidoc b/api/cl_khr_subgroup_clustered_reduce.asciidoc index a2d60ca89..a6b8b5c65 100644 --- a/api/cl_khr_subgroup_clustered_reduce.asciidoc +++ b/api/cl_khr_subgroup_clustered_reduce.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_clustered_reduce.txt[] === Description -`cl_khr_subgroup_clustered_reduce` adds built-in OpenCL functions for +{cl_khr_subgroup_clustered_reduce_EXT} adds built-in OpenCL functions for clustered reductions that operate on a subset of work items in the sub-group. diff --git a/api/cl_khr_subgroup_extended_types.asciidoc b/api/cl_khr_subgroup_extended_types.asciidoc index b5cfc7939..222b3db32 100644 --- a/api/cl_khr_subgroup_extended_types.asciidoc +++ b/api/cl_khr_subgroup_extended_types.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_extended_types.txt[] === Description -`cl_khr_subgroup_extended_types` adds additional supported OpenCL C data +{cl_khr_subgroup_extended_types_EXT} adds additional supported OpenCL C data types to the existing sub-group broadcast, scan, and reduction functions. See the link:{OpenCLCSpecURL}#cl_khr_subgroup_extended_types[Sub-Group diff --git a/api/cl_khr_subgroup_named_barrier.asciidoc b/api/cl_khr_subgroup_named_barrier.asciidoc index 07df0c863..d9dd17dbc 100644 --- a/api/cl_khr_subgroup_named_barrier.asciidoc +++ b/api/cl_khr_subgroup_named_barrier.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_named_barrier.txt[] === Description -`cl_khr_subgroup_named_barrier` adds barrier operations that cover subsets +{cl_khr_subgroup_named_barrier_EXT} adds barrier operations that cover subsets of an OpenCL work-group. Only the OpenCL API changes are described in this section. Please refer to the SPIR-V specification for information about using diff --git a/api/cl_khr_subgroup_non_uniform_arithmetic.asciidoc b/api/cl_khr_subgroup_non_uniform_arithmetic.asciidoc index 3389abe08..a1bee7e11 100644 --- a/api/cl_khr_subgroup_non_uniform_arithmetic.asciidoc +++ b/api/cl_khr_subgroup_non_uniform_arithmetic.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_non_uniform_arithmetic.txt[ === Description -`cl_khr_subgroup_non_uniform_arithmetic` adds built-in OpenCL C functions +{cl_khr_subgroup_non_uniform_arithmetic_EXT} adds built-in OpenCL C functions providing the ability to use some sub-group functions within non-uniform flow control, including additional scan and reduction operators. diff --git a/api/cl_khr_subgroup_non_uniform_vote.asciidoc b/api/cl_khr_subgroup_non_uniform_vote.asciidoc index f884c58bc..2188866ca 100644 --- a/api/cl_khr_subgroup_non_uniform_vote.asciidoc +++ b/api/cl_khr_subgroup_non_uniform_vote.asciidoc @@ -17,7 +17,7 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_non_uniform_vote.txt[] [[extended-sub-groups]] === Description -`cl_khr_subgroup_non_uniform_vote` adds built-in OpenCL C functions with the +{cl_khr_subgroup_non_uniform_vote_EXT} adds built-in OpenCL C functions with the ability to elect a single work item from a sub-group to perform a task and to hold votes among work items in a sub-group. diff --git a/api/cl_khr_subgroup_rotate.asciidoc b/api/cl_khr_subgroup_rotate.asciidoc index 3f9d04dff..afddda58f 100644 --- a/api/cl_khr_subgroup_rotate.asciidoc +++ b/api/cl_khr_subgroup_rotate.asciidoc @@ -19,7 +19,7 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_rotate.txt[] === Description -`cl_khr_subgroup_rotate` adds built-in OpenCL C functions with support for a +{cl_khr_subgroup_rotate_EXT} adds built-in OpenCL C functions with support for a new sub-group data exchange operation that makes it possible to rotate values through the work items in a sub-group. diff --git a/api/cl_khr_subgroup_shuffle.asciidoc b/api/cl_khr_subgroup_shuffle.asciidoc index f90bd70bc..44981e98d 100644 --- a/api/cl_khr_subgroup_shuffle.asciidoc +++ b/api/cl_khr_subgroup_shuffle.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_shuffle.txt[] === Description -`cl_khr_subgroup_shuffle` adds built-in OpenCL C functions providing +{cl_khr_subgroup_shuffle_EXT} adds built-in OpenCL C functions providing additional ways to exchange data among work items in a sub-group. See the link:{OpenCLCSpecURL}#cl_khr_subgroup_shuffle[General Purpose diff --git a/api/cl_khr_subgroup_shuffle_relative.asciidoc b/api/cl_khr_subgroup_shuffle_relative.asciidoc index 1419828e2..48f5f9723 100644 --- a/api/cl_khr_subgroup_shuffle_relative.asciidoc +++ b/api/cl_khr_subgroup_shuffle_relative.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_shuffle_relative.txt[] === Description -`cl_khr_subgroup_shuffle_relative` adds built-in OpenCL C functions +{cl_khr_subgroup_shuffle_relative_EXT} adds built-in OpenCL C functions providing specialized ways to exchange data among work items in a sub-group that may perform better on some implementations. diff --git a/api/cl_khr_subgroups.asciidoc b/api/cl_khr_subgroups.asciidoc index 44edb39c7..a4f833747 100644 --- a/api/cl_khr_subgroups.asciidoc +++ b/api/cl_khr_subgroups.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_subgroups.txt[] === Description -`cl_khr_subgroups` adds support for implementation-controlled groups of work +{cl_khr_subgroups_EXT} adds support for implementation-controlled groups of work items, known as sub-groups. Sub-groups behave similarly to work-groups and have their own sets of built-ins and synchronization primitives. diff --git a/api/cl_khr_suggested_local_work_size.asciidoc b/api/cl_khr_suggested_local_work_size.asciidoc index 558979623..d5c3faab4 100644 --- a/api/cl_khr_suggested_local_work_size.asciidoc +++ b/api/cl_khr_suggested_local_work_size.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_suggested_local_work_size.txt[] === Description -`cl_khr_suggested_local_work_size` adds the ability to query a suggested +{cl_khr_suggested_local_work_size_EXT} adds the ability to query a suggested local work-group size for a kernel running on a device for a specified global work size and global work offset. The suggested local work-group size will match the work-group size that diff --git a/api/cl_khr_terminate_context.asciidoc b/api/cl_khr_terminate_context.asciidoc index 103f5f7ea..bc89dcc7e 100644 --- a/api/cl_khr_terminate_context.asciidoc +++ b/api/cl_khr_terminate_context.asciidoc @@ -14,7 +14,7 @@ include::{generated}/meta/{refprefix}cl_khr_terminate_context.txt[] === Description -The `cl_khr_terminate_context` extension provides a new query to check +The {cl_khr_terminate_context_EXT} extension provides a new query to check whether a device can terminate an OpenCL context, and adds an API to terminate a context. diff --git a/api/cl_khr_throttle_hints.asciidoc b/api/cl_khr_throttle_hints.asciidoc index af11a1507..0de50159d 100644 --- a/api/cl_khr_throttle_hints.asciidoc +++ b/api/cl_khr_throttle_hints.asciidoc @@ -14,13 +14,13 @@ include::{generated}/meta/{refprefix}cl_khr_throttle_hints.txt[] === Description -The `cl_khr_throttle_hints` extension adds throttle hints for OpenCL, but +The {cl_khr_throttle_hints_EXT} extension adds throttle hints for OpenCL, but does not specify the throttling behavior or minimum guarantees. It is expected that the user guide associated with each implementation which supports this extension will describe the throttling behavior guarantees. Note that the throttle hint is orthogonal to functionality defined in -`<>` extension. +{cl_khr_priority_hints_EXT} extension. For example, a task may have high priority ({CL_QUEUE_PRIORITY_HIGH_KHR}) but should at the same time be executed at an optimized throttle setting ({CL_QUEUE_THROTTLE_LOW_KHR}). diff --git a/api/cl_khr_work_group_uniform_arithmetic.asciidoc b/api/cl_khr_work_group_uniform_arithmetic.asciidoc index 5dfb1281b..6ff2252fd 100644 --- a/api/cl_khr_work_group_uniform_arithmetic.asciidoc +++ b/api/cl_khr_work_group_uniform_arithmetic.asciidoc @@ -15,7 +15,7 @@ include::{generated}/meta/{refprefix}cl_khr_work_group_uniform_arithmetic.txt[] === Description -`cl_khr_work_group_uniform_arithmetic` adds additional built-in work-group +{cl_khr_work_group_uniform_arithmetic_EXT} adds additional built-in work-group collective functions to OpenCL C. Specifically, this extension adds support for work-group scans and reductions for the following operators: diff --git a/api/dictionary.asciidoc b/api/dictionary.asciidoc index a75c7a6df..a714d04b5 100644 --- a/api/dictionary.asciidoc +++ b/api/dictionary.asciidoc @@ -2,3 +2,4 @@ // SPDX-License-Identifier: CC-BY-4.0 include::{generated}/api/api-dictionary.asciidoc[] +include::{generated}/api/ext-dictionary-local-links.asciidoc[] diff --git a/api/footnotes.asciidoc b/api/footnotes.asciidoc index 26e1454f3..cc407d98f 100644 --- a/api/footnotes.asciidoc +++ b/api/footnotes.asciidoc @@ -107,7 +107,7 @@ Rather than attempt to share {cl_kernel_TYPE} objects among multiple host thread ] :fn-readimageh: pass:n[ \ -And *read_imageh*, if the `cl_khr_fp16` extension is supported. \ +And *read_imageh*, if the {cl_khr_fp16_EXT} extension is supported. \ ] :fn-reference-count-usage: pass:n[ \ diff --git a/api/opencl_architecture.asciidoc b/api/opencl_architecture.asciidoc index d45e84c89..2e559530c 100644 --- a/api/opencl_architecture.asciidoc +++ b/api/opencl_architecture.asciidoc @@ -998,9 +998,9 @@ concepts such as _resources_, _reference counts_, and _devices_. Sharing is accomplished by creating an OpenCL context via the context create parameters {CL_CONTEXT_D3D10_DEVICE_KHR} (for Direct3D 10, if the -`<>` extension is supported) or +{cl_khr_d3d10_sharing_EXT} extension is supported) or {CL_CONTEXT_D3D11_DEVICE_KHR} (for Direct3D 11, if the -`<>` extension is supported. +{cl_khr_d3d11_sharing_EXT} extension is supported. An OpenCL memory object created from a Direct3D resource remains valid as long as the corresponding Direct3D resource has not been deleted. @@ -1869,7 +1869,7 @@ function instance. ==== Sub-Group Functions NOTE: Sub-group functions are <> version 2.1. -Also see `<>`. +Also see {cl_khr_subgroups_EXT}. The OpenCL kernel execution model includes collective operations across the work-items within a single sub-group. diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index 7c39cb51e..99a6653cd 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -36,13 +36,13 @@ include::{generated}/api/version-notes/clGetPlatformIDs.asciidoc[] {clGetPlatformIDs} returns {CL_SUCCESS} if the function is executed ifndef::cl_khr_icd[successfully.] ifdef::cl_khr_icd[] -and, if the `<>` extension is supported, there are a non-zero +and, if the {cl_khr_icd_EXT} extension is supported, there are a non-zero number of platforms available. endif::cl_khr_icd[] Otherwise, it returns one of the following errors: ifdef::cl_khr_icd[] - * {CL_PLATFORM_NOT_FOUND_KHR} if the `<>` extension is + * {CL_PLATFORM_NOT_FOUND_KHR} if the {cl_khr_icd_EXT} extension is supported and zero platforms are available. endif::cl_khr_icd[] * {CL_INVALID_VALUE} if _num_entries_ is equal to zero and _platforms_ is @@ -561,7 +561,7 @@ include::{generated}/api/version-notes/CL_DEVICE_MAX_WORK_GROUP_SIZE.asciidoc[] If double precision is not supported, {CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE} must return 0. - If the `<>` extension is not supported, + If the {cl_khr_fp16_EXT} extension is not supported, {CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF} must return 0. | {CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR_anchor} + {CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT_anchor} + @@ -582,7 +582,7 @@ include::{generated}/api/version-notes/CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR.asciid If double precision is not supported, {CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE} must return 0. - If the `<>` extension is not supported, + If the {cl_khr_fp16_EXT} extension is not supported, {CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF} must return 0. | {CL_DEVICE_MAX_CLOCK_FREQUENCY_anchor} @@ -671,7 +671,7 @@ endif::cl_khr_il_program[] value must be `""` (an empty string). ifdef::cl_khr_il_program[] - A device that supports the `<>` extension must + A device that supports the {cl_khr_il_program_EXT} extension must support the `"SPIR-V"` IL prefix. endif::cl_khr_il_program[] | {CL_DEVICE_ILS_WITH_VERSION_anchor} @@ -770,7 +770,7 @@ include::{generated}/api/version-notes/CL_DEVICE_IMAGE_PITCH_ALIGNMENT.asciidoc[ ifdef::cl_khr_image2d_from_buffer[] The equivalent {CL_DEVICE_IMAGE_PITCH_ALIGNMENT_KHR_anchor} may be used if -the `<>` extension is supported. +the {cl_khr_image2d_from_buffer_EXT} extension is supported. endif::cl_khr_image2d_from_buffer[] | {cl_uint_TYPE} | The row pitch alignment size in pixels for 2D images created from a @@ -787,7 +787,7 @@ include::{generated}/api/version-notes/CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT.as ifdef::cl_khr_image2d_from_buffer[] The equivalent {CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT_KHR_anchor} may be used -if the `<>` extension is supported. +if the {cl_khr_image2d_from_buffer_EXT} extension is supported. endif::cl_khr_image2d_from_buffer[] | {cl_uint_TYPE} | This query specifies the minimum alignment in pixels of the host_ptr @@ -888,7 +888,7 @@ include::{generated}/api/version-notes/CL_DEVICE_SINGLE_FP_CONFIG.asciidoc[] include::{generated}/api/version-notes/CL_DEVICE_DOUBLE_FP_CONFIG.asciidoc[] -Also see `<>`. +Also see {cl_khr_fp64_EXT}. | {cl_device_fp_config_TYPE} | Describes double precision floating-point capability of the OpenCL device. @@ -1360,26 +1360,26 @@ include::{generated}/api/version-notes/CL_DEVICE_EXTENSIONS.asciidoc[] The following Khronos extension names must be returned by all devices that support OpenCL 1.1: - `<>` + - `<>` + - `<>` + - `<>` + - `<>` + {cl_khr_fp64_EXT} Additionally, the following Khronos extension names must be returned by all devices that support OpenCL 2.0, OpenCL 2.1, or OpenCL 2.2. For devices that support OpenCL 3.0, these extension names must be returned when and only when the optional feature is supported: - `<>` + - `<>` + - `<>` + {cl_khr_3d_image_writes_EXT} + + {cl_khr_depth_images_EXT} + + {cl_khr_image2d_from_buffer_EXT} Please refer to the OpenCL Extension Specification or vendor provided documentation for a detailed description of these extensions. @@ -1577,7 +1577,7 @@ include::{generated}/api/version-notes/CL_DEVICE_SUB_GROUP_INDEPENDENT_FORWARD_P sub-groups, {CL_FALSE} otherwise. This query must return {CL_TRUE} for devices that support the - `<>` extension, and must return {CL_FALSE} for + {cl_khr_subgroups_EXT} extension, and must return {CL_FALSE} for devices that do not support sub-groups. | {CL_DEVICE_ATOMIC_MEMORY_CAPABILITIES_anchor} @@ -1944,7 +1944,7 @@ include::{generated}/api/version-notes/CL_DEVICE_INTEGER_DOT_PRODUCT_CAPABILITIE {CL_DEVICE_INTEGER_DOT_PRODUCT_INPUT_4x8BIT_PACKED_KHR_anchor} is always set, indicating that all implementations that support - `<>` must support dot product built-in + {cl_khr_integer_dot_product_EXT} must support dot product built-in functions and, when SPIR-V is supported, SPIR-V instructions that take four-component vectors of 8-bit integers packed into 32-bit integers as input. @@ -3117,7 +3117,7 @@ returned in _errcode_ret_: required by the OpenCL implementation on the host. ifdef::cl_khr_dx9_media_sharing[] -The following errors may be returned if the `<>` +The following errors may be returned if the {cl_khr_dx9_media_sharing_EXT} extension is supported: * {CL_INVALID_DX9_MEDIA_ADAPTER_KHR} if any of the values of the @@ -3129,7 +3129,7 @@ extension is supported: endif::cl_khr_dx9_media_sharing[] ifdef::cl_khr_d3d10_sharing[] -The following errors may be returned if the `<>` +The following errors may be returned if the {cl_khr_d3d10_sharing_EXT} extension is supported: * {CL_INVALID_D3D10_DEVICE_KHR} if the value of the property @@ -3142,7 +3142,7 @@ extension is supported: endif::cl_khr_d3d10_sharing[] ifdef::cl_khr_d3d11_sharing[] -The following errors may be returned if the `<>` +The following errors may be returned if the {cl_khr_d3d11_sharing_EXT} extension is supported: * {CL_INVALID_D3D11_DEVICE_KHR} if the value of the property @@ -3155,7 +3155,7 @@ extension is supported: endif::cl_khr_d3d11_sharing[] ifdef::cl_khr_gl_sharing[] -The following errors may be returned if the `<>` +The following errors may be returned if the {cl_khr_gl_sharing_EXT} extension is supported: * {CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR} if a context was specified for @@ -3186,15 +3186,15 @@ extension is supported: ** Any of the devices specified in the _devices_ argument cannot support OpenCL objects which share the data store of an OpenGL object. * {CL_INVALID_PROPERTY} if both {CL_CONTEXT_INTEROP_USER_SYNC}, and any of - the properties defined by the `<>` extension are + the properties defined by the {cl_khr_gl_sharing_EXT} extension are defined in _properties_. endif::cl_khr_gl_sharing[] ifdef::cl_khr_terminate_context[] -The following errors may be returned if the `<>` +The following errors may be returned if the {cl_khr_terminate_context_EXT} extension is supported: - * {CL_INVALID_PROPERTY} if the `<>` extension is + * {CL_INVALID_PROPERTY} if the {cl_khr_terminate_context_EXT} extension is supported and {CL_CONTEXT_TERMINATE_KHR} is set to {CL_TRUE} in _properties_, but not all of the devices associated with the context support the ability to support context termination (i.e. @@ -3272,7 +3272,7 @@ returned in _errcode_ret_: required by the OpenCL implementation on the host. ifdef::cl_khr_dx9_media_sharing[] -The following errors may be returned if the `<>` +The following errors may be returned if the {cl_khr_dx9_media_sharing_EXT} extension is supported: * {CL_INVALID_DX9_MEDIA_ADAPTER_KHR} if any of the values of the @@ -3284,7 +3284,7 @@ extension is supported: endif::cl_khr_dx9_media_sharing[] ifdef::cl_khr_d3d10_sharing[] -The following errors may be returned if the `<>` +The following errors may be returned if the {cl_khr_d3d10_sharing_EXT} extension is supported: * {CL_INVALID_D3D10_DEVICE_KHR} if the value of the property @@ -3297,7 +3297,7 @@ extension is supported: endif::cl_khr_d3d10_sharing[] ifdef::cl_khr_d3d11_sharing[] -The following errors may be returned if the `<>` +The following errors may be returned if the {cl_khr_d3d11_sharing_EXT} extension is supported: * {CL_INVALID_D3D11_DEVICE_KHR} if the value of the property @@ -3310,7 +3310,7 @@ extension is supported: endif::cl_khr_d3d11_sharing[] ifdef::cl_khr_gl_sharing[] -The following errors may be returned if the `<>` +The following errors may be returned if the {cl_khr_gl_sharing_EXT} extension is supported: * {CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR} if a context was specified for @@ -3341,7 +3341,7 @@ extension is supported: ** Any of the devices specified in the _devices_ argument cannot support OpenCL objects which share the data store of an OpenGL object. * {CL_INVALID_PROPERTY} if both {CL_CONTEXT_INTEROP_USER_SYNC}, and any of - the properties defined by the `<>` extension are + the properties defined by the {cl_khr_gl_sharing_EXT} extension are defined in _properties_. endif::cl_khr_gl_sharing[] diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index b349d587a..27788730e 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -70,7 +70,7 @@ include::{generated}/api/version-notes/CL_QUEUE_PROPERTIES.asciidoc[] | {cl_command_queue_properties_TYPE} ifdef::cl_khr_create_command_queue[] -or {cl_bitfield_TYPE} if the `<>` extension is supported +or {cl_bitfield_TYPE} if the {cl_khr_create_command_queue_EXT} extension is supported endif::cl_khr_create_command_queue[] | This is a bitfield and can be set to a combination of the following values: @@ -188,12 +188,12 @@ returned in _errcode_ret_: * {CL_INVALID_QUEUE_PROPERTIES} if values specified in _properties_ are valid but are not supported by the device. ifdef::cl_khr_priority_hints[] - * {CL_INVALID_QUEUE_PROPERTIES} if the `<>` + * {CL_INVALID_QUEUE_PROPERTIES} if the {cl_khr_priority_hints_EXT} extension is supported, the {CL_QUEUE_PRIORITY_KHR} property is specified, and the queue is a {CL_QUEUE_ON_DEVICE}. endif::cl_khr_priority_hints[] ifdef::cl_khr_throttle_hints[] - * {CL_INVALID_QUEUE_PROPERTIES} if the `<>` + * {CL_INVALID_QUEUE_PROPERTIES} if the {cl_khr_throttle_hints_EXT} extension is supported, the {CL_QUEUE_THROTTLE_KHR} property is specified, and the queue is a {CL_QUEUE_ON_DEVICE}. endif::cl_khr_throttle_hints[] @@ -2351,7 +2351,7 @@ include::{generated}/api/version-notes/CL_R.asciidoc[] include::{generated}/api/version-notes/CL_DEPTH.asciidoc[] ifdef::cl_khr_depth_images[] -Also supported if the `<>` extension is supported. +Also supported if the {cl_khr_depth_images_EXT} extension is supported. endif::cl_khr_depth_images[] | A single channel image format where the single channel represents a `DEPTH` component. | {CL_LUMINANCE_anchor} @@ -2450,7 +2450,7 @@ include::{generated}/api/version-notes/CL_UNORM_INT8.asciidoc[] include::{generated}/api/version-notes/CL_UNORM_INT16.asciidoc[] ifdef::cl_khr_depth_images[] -Also supported if the `<>` extension is supported. +Also supported if the {cl_khr_depth_images_EXT} extension is supported. endif::cl_khr_depth_images[] | Each channel component is a normalized unsigned 16-bit integer value | {CL_UNORM_SHORT_565_anchor} @@ -2514,7 +2514,7 @@ include::{generated}/api/version-notes/CL_HALF_FLOAT.asciidoc[] include::{generated}/api/version-notes/CL_FLOAT.asciidoc[] ifdef::cl_khr_depth_images[] -Also supported if the `<>` extension is supported. +Also supported if the {cl_khr_depth_images_EXT} extension is supported. endif::cl_khr_depth_images[] | Each channel component is a single precision floating-point value |==== @@ -2656,7 +2656,7 @@ endif::cl_khr_external_memory[] * _num_mip_levels_ must be ifndef::cl_khr_mipmap_image[0.] ifdef::cl_khr_mipmap_image[] - 0 unless the `<>` extension is supported, in which + 0 unless the {cl_khr_mipmap_image_EXT} extension is supported, in which case it must be a value greater than 1 specifying the number of mipmap levels in the image. endif::cl_khr_mipmap_image[] @@ -2871,7 +2871,7 @@ is: | {CL_DEPTH} footnote:[{fn-depth-image-requirements}] ifdef::cl_khr_depth_images[] -Also supported if the `<>` extension is supported. +Also supported if the {cl_khr_depth_images_EXT} extension is supported. endif::cl_khr_depth_images[] | {CL_UNORM_INT16} + {CL_FLOAT} @@ -3037,7 +3037,7 @@ image formats in that API and the corresponding OpenCL image format. ifdef::cl_khr_dx9_media_sharing[] ==== Image Formats for DirectX 9 Media Surface Sharing -When the `<>` extension is supported, image +When the {cl_khr_dx9_media_sharing_EXT} extension is supported, image objects sharing storage with Direct3D 9 surfaces can be created. This section describes the Direct3D 9 surface formats that are supported when the adapter type is one of the Direct 3D lineage. @@ -3109,7 +3109,7 @@ endif::cl_khr_dx9_media_sharing[] ifdef::cl_khr_d3d10_sharing,cl_khr_d3d11_sharing[] ==== Image Formats for Direct3D Texture Sharing -When the `<>` or `<>` extensions +When the {cl_khr_d3d10_sharing_EXT} or {cl_khr_d3d11_sharing_EXT} extensions are supported, image objects sharing storage with Direct3D 10 and Direct3D 11 textures, respectively, can be created. The <>` extension is supported, image objects +When the {cl_khr_gl_sharing_EXT} extension is supported, image objects sharing storage with OpenGL texture and renderbuffer objects can be created. The <> table describes the supported OpenGL image @@ -3412,7 +3412,7 @@ Otherwise, it returns one of the following errors: * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources required by the OpenCL implementation on the host. ifdef::cl_khr_mipmap_image[] - * {CL_INVALID_MIP_LEVEL} if the `<>` extension is + * {CL_INVALID_MIP_LEVEL} if the {cl_khr_mipmap_image_EXT} extension is supported, and the mip level specified in _origin_ is not a valid level for _image_, endif::cl_khr_mipmap_image[] @@ -3585,7 +3585,7 @@ Otherwise, it returns one of the following errors: * {CL_MEM_COPY_OVERLAP} if _src_image_ and _dst_image_ are the same image object and the source and destination regions overlap. ifdef::cl_khr_mipmap_image[] - * {CL_INVALID_MIP_LEVEL} if the `<>` extension is + * {CL_INVALID_MIP_LEVEL} if the {cl_khr_mipmap_image_EXT} extension is supported, and the mip level specified in _src_origin_ or _dst_origin_ is not a valid level for the corresponding _src_image_ or _dst_image_, endif::cl_khr_mipmap_image[] @@ -3706,7 +3706,7 @@ Otherwise, it returns one of the following errors: * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources required by the OpenCL implementation on the host. ifdef::cl_khr_mipmap_image[] - * {CL_INVALID_MIP_LEVEL} if the `<>` extension is + * {CL_INVALID_MIP_LEVEL} if the {cl_khr_mipmap_image_EXT} extension is supported, and the mip level specified in _origin_ is not a valid level for _image_, endif::cl_khr_mipmap_image[] @@ -3833,7 +3833,7 @@ Otherwise, it returns one of the following errors: * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources required by the OpenCL implementation on the host. ifdef::cl_khr_mipmap_image[] - * {CL_INVALID_MIP_LEVEL} if the `<>` extension is + * {CL_INVALID_MIP_LEVEL} if the {cl_khr_mipmap_image_EXT} extension is supported, and the mip level specified in _src_origin_ is not a valid level for _src_image_, endif::cl_khr_mipmap_image[] @@ -3960,7 +3960,7 @@ Otherwise, it returns one of the following errors: * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources required by the OpenCL implementation on the host. ifdef::cl_khr_mipmap_image[] - * {CL_INVALID_MIP_LEVEL} if the `<>` extension is + * {CL_INVALID_MIP_LEVEL} if the {cl_khr_mipmap_image_EXT} extension is supported, and the mip level specified in _dst_origin_ is not a valid level for _dst_image_, endif::cl_khr_mipmap_image[] @@ -4136,7 +4136,7 @@ ifdef::cl_khr_mipmap_image[] [[image-mipmap-access]] === Specifying Mipmap Levels to Image Operations -When the `<>` extension is supported, the +When the {cl_khr_mipmap_image_EXT} extension is supported, the {clEnqueueReadImage}, {clEnqueueWriteImage}, {clEnqueueMapImage}, {clEnqueueCopyImage}, {clEnqueueCopyImageToBuffer}, {clEnqueueCopyBufferToImage}, and {clEnqueueFillImage} functions described @@ -4322,7 +4322,7 @@ Otherwise, it returns one of the following errors: required by the OpenCL implementation on the host. ifdef::cl_khr_dx9_media_sharing[] -The following errors may be returned if the `<>` +The following errors may be returned if the {cl_khr_dx9_media_sharing_EXT} extension is supported: * {CL_INVALID_DX9_MEDIA_SURFACE_KHR} if _param_name_ is @@ -4331,7 +4331,7 @@ extension is supported: endif::cl_khr_dx9_media_sharing[] ifdef::cl_khr_d3d10_sharing[] -The following errors may be returned if the `<>` +The following errors may be returned if the {cl_khr_d3d10_sharing_EXT} extension is supported: * {CL_INVALID_D3D10_RESOURCE_KHR} if _param_name_ is @@ -4341,7 +4341,7 @@ extension is supported: endif::cl_khr_d3d10_sharing[] ifdef::cl_khr_d3d11_sharing[] -The following errors may be returned if the `<>` +The following errors may be returned if the {cl_khr_d3d11_sharing_EXT} extension is supported: * {CL_INVALID_D3D11_RESOURCE_KHR} if _param_name_ is @@ -4763,7 +4763,7 @@ CL_MEM_READ_WRITE. If OpenCL 1.2 is supported, _flags_ also accepts {CL_MEM_HOST_WRITE_ONLY}, {CL_MEM_HOST_READ_ONLY}, and {CL_MEM_HOST_NO_ACCESS}. -`<>` only requires support for {CL_MEM_READ_ONLY}, and for +{cl_khr_egl_image_EXT} only requires support for {CL_MEM_READ_ONLY}, and for CL_MEM_HOST_NO_ACCESS if OpenCL 1.2 or later is supported. For OpenCL 1.1, a {CL_INVALID_OPERATION} will be returned for images which do not support host mapping. @@ -4831,7 +4831,7 @@ ifdef::cl_khr_gl_msaa_sharing[] `GL_TEXTURE_2D_MULTISAMPLE` and `GL_TEXTURE_2D_MULTISAMPLE_ARRAY` may be specified if an OpenGL implementation supporting multi-sample two-dimensional textures is supported, and the - `<>` extension is supported. + {cl_khr_gl_msaa_sharing_EXT} extension is supported. Refer to the <> section for more information on multi-sample images. endif::cl_khr_gl_msaa_sharing[] @@ -4871,7 +4871,7 @@ endif::cl_khr_gl_msaa_sharing[] * an OpenCL 3D image object from an OpenGL 3D texture object. ifdef::cl_khr_mipmap_image[] -If both the `<>` and `<>` extensions +If both the {cl_khr_mipmap_image_EXT} and {cl_khr_gl_sharing_EXT} extensions are supported by the OpenCL device, {clCreateFromGLTexture} may also be used to create a mipmapped OpenCL image from a mipmapped OpenGL texture by specify a negative value for _miplevel_. @@ -4944,7 +4944,7 @@ ifdef::cl_khr_gl_depth_images[] Depth images with an image channel order of {CL_DEPTH_STENCIL} can only be created using the {clCreateFromGLTexture} API, and only when the -`<>` extension is supported. +{cl_khr_gl_depth_images_EXT} extension is supported. For the image format given by channel order of {CL_DEPTH_STENCIL} and channel data type of {CL_UNORM_INT24}, the depth is stored as an unsigned @@ -5563,7 +5563,7 @@ operation must create a distinct memory object. ==== File Descriptor Handle Types ifdef::cl_khr_external_memory_opaque_fd[] -The `<>` extension extends +The {cl_khr_external_memory_opaque_fd_EXT} extension extends {cl_external_memory_handle_type_khr_TYPE} to support the following new types of handles, and adds as a property that may be specified when creating a buffer or an image memory object from an external handle: @@ -5580,7 +5580,7 @@ buffer or an image memory object from an external handle: endif::cl_khr_external_memory_opaque_fd[] ifdef::cl_khr_external_memory_dma_buf[] -The `<>` extension extends +The {cl_khr_external_memory_dma_buf_EXT} extension extends {cl_external_memory_handle_type_khr_TYPE} to support the following types of handles, and adds as a property that may be specified when creating a buffer or an image memory object from an external handle: @@ -5602,7 +5602,7 @@ The imported memory object holds a reference to its payload. ==== NT Handle Types ifdef::cl_khr_external_memory_dx[] -The `<>` extension extends +The {cl_khr_external_memory_dx_EXT} extension extends {cl_external_memory_handle_type_khr_TYPE} to support the following new types of handles, and adds as a property that may be specified when creating a buffer or an image memory object from an external handle: @@ -5628,7 +5628,7 @@ buffer or an image memory object from an external handle: endif::cl_khr_external_memory_dx[] ifdef::cl_khr_external_memory_win32[] -The `<>` extension extends +The {cl_khr_external_memory_win32_EXT} extension extends {cl_external_memory_handle_type_khr_TYPE} to support the following new types of handles, and adds as a property that may be specified when creating a buffer or an image memory object from an external handle: @@ -6142,7 +6142,7 @@ Otherwise, it returns one of the following errors: required by the OpenCL implementation on the host. ifdef::cl_khr_dx9_media_sharing[] -The following errors may be returned if the `<>` +The following errors may be returned if the {cl_khr_dx9_media_sharing_EXT} extension is supported: * {CL_INVALID_DX9_MEDIA_SURFACE_KHR} if _param_name_ is @@ -6151,7 +6151,7 @@ extension is supported: endif::cl_khr_dx9_media_sharing[] ifdef::cl_khr_d3d10_sharing[] -The following errors may be returned if the `<>` +The following errors may be returned if the {cl_khr_d3d10_sharing_EXT} extension is supported: * {CL_INVALID_D3D10_RESOURCE_KHR} if _param_name_ is @@ -6161,7 +6161,7 @@ extension is supported: endif::cl_khr_d3d10_sharing[] ifdef::cl_khr_d3d11_sharing[] -The following errors may be returned if the `<>` +The following errors may be returned if the {cl_khr_d3d11_sharing_EXT} extension is supported: * {CL_INVALID_D3D11_RESOURCE_KHR} if _param_name_ is @@ -7144,9 +7144,9 @@ Otherwise, it returns one of the following errors: ifdef::cl_khr_egl_image,cl_khr_gl_sharing[] ==== Synchronizing Access to Memory Objects Shared With EGL or OpenGL -When sharing objects such as EGL images (if the `<>` +When sharing objects such as EGL images (if the {cl_khr_egl_image_EXT} extension is supported) or OpenGL buffers, textures, and renderbuffers (if -the `<>` extension is supported), in order to ensure data +the {cl_khr_gl_sharing_EXT} extension is supported), in order to ensure data integrity, the application is responsible for synchronizing access to shared memory objects through the other API with which such objects are shared. @@ -7164,14 +7164,14 @@ extensions which may be used to synchronize with other APIs: ifdef::cl_khr_egl_image[] ===== Synchronization With EGL and EGL Client APIs -When sharing with an EGL context via the `<>` extension, -if the `<>` extension is supported, and the EGL context in +When sharing with an EGL context via the {cl_khr_egl_image_EXT} extension, +if the {cl_khr_egl_event_EXT} extension is supported, and the EGL context in question supports fence sync objects, _explicit synchronization_ with EGL or EGL client APIs can be achieved as described in the <> section. -If the `<>` extension is not supported, completion of EGL +If the {cl_khr_egl_event_EXT} extension is not supported, completion of EGL client API commands may be determined by issuing and waiting for completion of commands such as `glFinish` or `vgFinish` on all client API contexts with pending references to these objects. @@ -7181,18 +7181,18 @@ endif::cl_khr_egl_image[] ifdef::cl_khr_gl_sharing[] ===== Synchronization With OpenGL -When sharing with an OpenGL context via the `<>` +When sharing with an OpenGL context via the {cl_khr_gl_sharing_EXT} extension, the OpenCL implementation will ensure that any such pending OpenGL operations are complete for an OpenGL context bound to the same thread as the OpenCL context. This is referred to as _implicit synchronization_. -If the `<>` extension is supported, and the OpenGL context +If the {cl_khr_gl_event_EXT} extension is supported, and the OpenGL context in question supports fence sync objects, _explicit synchronization_ with OpenGL can be achieved as described in the <> section. -If the `<>` extension is not supported, completion of +If the {cl_khr_gl_event_EXT} extension is not supported, completion of OpenGL commands may be determined by issuing and waiting for completion of a `glFinish` command on all OpenGL contexts with pending references to these objects. @@ -7209,7 +7209,7 @@ Note that no synchronization method other than `glFinish` is portable between all OpenGL implementations and all OpenCL implementations. While this is the only way to ensure completion that is portable to all platforms, `glFinish` is an expensive operation and its use should be -avoided if the `<>` or `<>` extensions +avoided if the {cl_khr_egl_event_EXT} or {cl_khr_gl_event_EXT} extensions are supported on a platform. @@ -8143,7 +8143,7 @@ endif::cl_khr_mipmap_image[] |==== ifdef::cl_khr_mipmap_image[] -NOTE: When the `<>` extension is supported, the sampler +NOTE: When the {cl_khr_mipmap_image_EXT} extension is supported, the sampler properties {CL_SAMPLER_MIP_FILTER_MODE_KHR}, {CL_SAMPLER_LOD_MIN_KHR} and {CL_SAMPLER_LOD_MAX_KHR} cannot be specified with any samplers initialized in the OpenCL program source. @@ -8551,7 +8551,7 @@ The cached executables can be read and loaded by the application, which can help significantly reduce the application initialization time. ifdef::cl_khr_spir[] -If the `<>` extension is supported, {clCreateProgramWithBinary} +If the {cl_khr_spir_EXT} extension is supported, {clCreateProgramWithBinary} can be used to load a SPIR binary. Once a program object has been created from a SPIR binary, {clBuildProgram} can be called to build a program executable or {clCompileProgram} can be @@ -9085,7 +9085,7 @@ Otherwise, it returns one of the following errors: ifdef::cl_khr_il_program[or {clCreateProgramWithILKHR}] ifdef::cl_khr_spir[] ** {clCreateProgramWithBinary} where `-x spir` is present in _options_, - if the `<>` extension is supported. + if the {cl_khr_spir_EXT} extension is supported. endif::cl_khr_spir[] ** {clCreateProgramWithSource} * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required @@ -9571,7 +9571,7 @@ ifdef::cl_khr_spir[] [[spir-compilation-options]] ==== SPIR Compilation Options -If the `<>` extension is supported, the compile option +If the {cl_khr_spir_EXT} extension is supported, the compile option `-x spir` @@ -10254,7 +10254,7 @@ If the argument is of type _queue_t_, the _arg_value_ entry must be a pointer to the device queue object. ifdef::cl_khr_gl_msaa_sharing[] -If the `<>` extension is supported, then: +If the {cl_khr_gl_msaa_sharing_EXT} extension is supported, then: If the argument is a multi-sample 2D image, the _arg_value_ entry must be a pointer to a multi-sample image object. If the argument is a multi-sample 2D depth image, the _arg_value_ entry must @@ -10836,7 +10836,7 @@ To return information about a kernel object, call the function include::{generated}/api/protos/clGetKernelSubGroupInfo.txt[] include::{generated}/api/version-notes/clGetKernelSubGroupInfo.asciidoc[] -Also see `<>`. +Also see {cl_khr_subgroups_EXT}. * _kernel_ specifies the kernel object being queried. * _device_ identifies a specific device in the list of devices associated with @@ -10877,7 +10877,7 @@ include::{generated}/api/version-notes/CL_KERNEL_MAX_SUB_GROUP_SIZE_FOR_NDRANGE. ifdef::cl_khr_subgroups[] The equivalent {CL_KERNEL_MAX_SUB_GROUP_SIZE_FOR_NDRANGE_KHR_anchor} may be used if -the `<>` extension is supported. +the {cl_khr_subgroups_EXT} extension is supported. endif::cl_khr_subgroups[] | {size_t_TYPE}* | {size_t_TYPE} @@ -10897,7 +10897,7 @@ include::{generated}/api/version-notes/CL_KERNEL_SUB_GROUP_COUNT_FOR_NDRANGE.asc ifdef::cl_khr_subgroups[] The equivalent {CL_KERNEL_SUB_GROUP_COUNT_FOR_NDRANGE_KHR_anchor} may be used if -the `<>` extension is supported. +the {cl_khr_subgroups_EXT} extension is supported. endif::cl_khr_subgroups[] | {size_t_TYPE}* | {size_t_TYPE} @@ -10916,7 +10916,7 @@ endif::cl_khr_subgroups[] include::{generated}/api/version-notes/CL_KERNEL_LOCAL_SIZE_FOR_SUB_GROUP_COUNT.asciidoc[] -Also see `<>`. +Also see {cl_khr_subgroups_EXT}. | {size_t_TYPE} | {size_t_TYPE}[] | Returns the local size that will generate the requested number @@ -10937,7 +10937,7 @@ Also see `<>`. include::{generated}/api/version-notes/CL_KERNEL_MAX_NUM_SUB_GROUPS.asciidoc[] -Also see `<>`. +Also see {cl_khr_subgroups_EXT}. | ignored | {size_t_TYPE} | This provides a mechanism for the application to query the @@ -10953,7 +10953,7 @@ Also see `<>`. include::{generated}/api/version-notes/CL_KERNEL_COMPILE_NUM_SUB_GROUPS.asciidoc[] -Also see `<>`. +Also see {cl_khr_subgroups_EXT}. | ignored | {size_t_TYPE} | Returns the number of sub-groups per work-group specified in the kernel @@ -11020,7 +11020,7 @@ ifdef::cl_khr_spir[] * is created with {clCreateProgramWithBinary} and the program executable is built with the `-cl-kernel-arg-info` and `-x spir` options specified in the _options_ argument to {clBuildProgram} or {clCompileProgram}, if - the `<>` extension is supported; or, + the {cl_khr_spir_EXT} extension is supported; or, endif::cl_khr_spir[] * is created with {clCreateProgramWithSource} and the program executable is built with the `-cl-kernel-arg-info option` specified in the @@ -11835,7 +11835,7 @@ include::{generated}/api/version-notes/CL_EVENT_COMMAND_QUEUE.asciidoc[] For user event objects, a `NULL` value is returned. ifdef::cl_khr_command_buffer_multi_device[] - If the `<>` extension is + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported, for events returned by a command-buffer enqueue operation to multiple command-queues, `NULL` is returned. endif::cl_khr_command_buffer_multi_device[] @@ -11876,7 +11876,7 @@ include::{generated}/api/version-notes/CL_EVENT_COMMAND_EXECUTION_STATUS.asciido *errcode_ret* values. ifdef::cl_khr_command_buffer_multi_device[] - If the `<>` extension is + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported, for events returned by a command-buffer enqueue operation to multiple command-queues the semantics of execution status is as follows: @@ -12361,7 +12361,7 @@ include::{generated}/api/protos/clCreateEventFromEGLSyncKHR.txt[] include::{generated}/api/version-notes/clCreateEventFromEGLSyncKHR.asciidoc[] * _context_ is a valid OpenCL context created from an OpenGL context or - share group, using the `<>` extension. + share group, using the {cl_khr_gl_sharing_EXT} extension. * _sync_ is the name of a sync object of type `EGL_SYNC_FENCE_KHR` created with respect to `EGLDisplay` _display_. * _display_ is the `EGLDisplay` handle. @@ -12415,7 +12415,7 @@ returned in _errcode_ret_: [[explicit-sync-using-egl-fences]] ===== Explicit Synchronization Using EGL Fence Sync Objects -If the `<>` extension is supported, event objects created +If the {cl_khr_egl_event_EXT} extension is supported, event objects created with {clCreateEventFromEGLsyncKHR} provide another method of coordinating sharing between EGL / EGL client API objects, and OpenCL. @@ -12452,7 +12452,7 @@ include::{generated}/api/protos/clCreateEventFromGLsyncKHR.txt[] include::{generated}/api/version-notes/clCreateEventFromGLsyncKHR.asciidoc[] * _context_ is a valid OpenCL context created from an OpenGL context or - share group, using the `<>` extension. + share group, using the {cl_khr_gl_sharing_EXT} extension. * _sync_ is the name of a sync object in the GL share group associated with _context_. * _errcode_ret_ will return an appropriate error code. @@ -12505,7 +12505,7 @@ a {CL_INVALID_EVENT} error. [[explicit-sync-using-opengl-fences]] ===== Explicit Synchronization Using OpenGL Fence Sync Objects -If the `<>` extension is supported, event objects created +If the {cl_khr_gl_event_EXT} extension is supported, event objects created with {clCreateEventFromGLsyncKHR} provide another method of coordinating sharing of buffers and images between OpenGL and OpenCL. @@ -12766,7 +12766,7 @@ ifdef::cl_khr_semaphore[] == Semaphores This section describes the semaphore types and functions defined by the -`<>` extension. +{cl_khr_semaphore_EXT} extension. === Semaphore Types @@ -12783,7 +12783,7 @@ This section describes the semaphore types and functions defined by the * {cl_semaphore_info_khr_TYPE} represents queries for additional information about semaphores. ** All enums described in the "`New API Enums`" section of the - `<>` extension for {cl_semaphore_info_khr_TYPE} must + {cl_khr_semaphore_EXT} extension for {cl_semaphore_info_khr_TYPE} must be supported. * {cl_semaphore_payload_khr_TYPE} represents payload values of semaphores. * {cl_semaphore_khr_TYPE} represent semaphore objects. @@ -13015,7 +13015,7 @@ ifdef::cl_khr_external_semaphore_opaque_fd,cl_khr_external_semaphore_sync_fd[] ifdef::cl_khr_external_semaphore_opaque_fd[] -The `<>` extension extends +The {cl_khr_external_semaphore_opaque_fd_EXT} extension extends {cl_external_semaphore_handle_type_khr_TYPE} to support the following new types of handles, and adds as a property that may be specified when creating a semaphore from an external handle: @@ -13034,7 +13034,7 @@ endif::cl_khr_external_semaphore_opaque_fd[] ifdef::cl_khr_external_semaphore_sync_fd[] -The `<>` extension extends +The {cl_khr_external_semaphore_sync_fd_EXT} extension extends {cl_external_semaphore_handle_type_khr_TYPE} to support the following new types of handles, and adds as a property that may be specified when creating a semaphore from an external handle: @@ -13138,7 +13138,7 @@ ifdef::cl_khr_external_semaphore_dx_fence,cl_khr_external_semaphore_win32[] ifdef::cl_khr_external_semaphore_dx_fence[] -The `<>` extension extends +The {cl_khr_external_semaphore_dx_fence_EXT} extension extends {cl_external_semaphore_handle_type_khr_TYPE} to support the following new types of handles, and adds as a property that may be specified when creating a semaphore from an external handle: @@ -13170,7 +13170,7 @@ endif::cl_khr_external_semaphore_dx_fence[] ifdef::cl_khr_external_semaphore_win32[] -The `<>` extension extends +The {cl_khr_external_semaphore_win32_EXT} extension extends {cl_external_semaphore_handle_type_khr_TYPE} to support the following new types of handles, and adds as a property that may be specified when creating a semaphore from an external handle: @@ -13674,7 +13674,7 @@ include::{generated}/api/version-notes/CL_PROFILING_COMMAND_QUEUED.asciidoc[] command-queue by the host. ifdef::cl_khr_command_buffer_multi_device[] - If the `<>` extension is supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported, for events returned by a command-buffer enqueue operation to multiple command-queues, the host time when the command-buffer has been enqueued across the command-queues is used. @@ -13690,7 +13690,7 @@ include::{generated}/api/version-notes/CL_PROFILING_COMMAND_SUBMIT.asciidoc[] command-queue. ifdef::cl_khr_command_buffer_multi_device[] - If the `<>` extension is supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported, for events returned by a command-buffer enqueue operation to multiple command-queues, the host time is used when command-buffer commands have been submitted to any command-queue. @@ -13705,7 +13705,7 @@ include::{generated}/api/version-notes/CL_PROFILING_COMMAND_START.asciidoc[] the device. ifdef::cl_khr_command_buffer_multi_device[] - If the `<>` extension is supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported, for events returned by a command-buffer enqueue operation to multiple command-queues, the host time is used when any device starts executing a command-buffer command. @@ -13720,7 +13720,7 @@ include::{generated}/api/version-notes/CL_PROFILING_COMMAND_END.asciidoc[] execution on the device. ifdef::cl_khr_command_buffer_multi_device[] - If the `<>` extension is supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported, for events returned by a command-buffer enqueue operation to multiple command-queues, the host time is used when the last command-buffer command finishes execution on any device. @@ -13736,7 +13736,7 @@ include::{generated}/api/version-notes/CL_PROFILING_COMMAND_COMPLETE.asciidoc[] execution. ifdef::cl_khr_command_buffer_multi_device[] - If the `<>` extension is supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported, for events returned by a command-buffer enqueue operation to multiple command-queues, the host time is used when the command-buffer has completed execution across all command-queues. @@ -13756,7 +13756,7 @@ incremented. ifdef::cl_khr_command_buffer_multi_device[] [NOTE] ==== -If the `<>` extension is supported, and +If the {cl_khr_command_buffer_multi_device_EXT} extension is supported, and if no reliable device timer sources are available to inform the host side, or parallel runtime scheduling makes it impossible to identify a first/last command, then an implementation may fallback to reporting @@ -13780,7 +13780,7 @@ Otherwise, it returns one of the following errors: {clEnqueueSvmFree}. ifdef::cl_khr_command_buffer_multi_device[] {empty} + - If the `<>` extension is supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported, and if _event_ was created from a call to {clEnqueueCommandBufferKHR}, {CL_PROFILING_INFO_NOT_AVAILABLE} is returned if all the queues passed do not have {CL_QUEUE_PROFILING_ENABLE} set. @@ -13932,7 +13932,7 @@ Undefined behavior may result from the failure to follow this usage requirement for all the command-buffers an object is used as a kernel argument in. -If using layered extension `<>`, +If using layered extension {cl_khr_command_buffer_mutable_dispatch_EXT}, <>. ==== @@ -13941,7 +13941,7 @@ usage>>. ifdef::cl_khr_command_buffer_multi_device[] === Command-Buffers and Multiple Devices -If the `<>` extension is supported, a +If the {cl_khr_command_buffer_multi_device_EXT} extension is supported, a command-buffer can contain commands recorded to the queues of different devices if a vendor provides support for inter-device {cl_sync_point_khr_TYPE} synchronization. @@ -14030,7 +14030,7 @@ include::{generated}/api/protos/clCreateCommandBufferKHR.txt[] include::{generated}/api/version-notes/clCreateCommandBufferKHR.asciidoc[] * _num_queues_ is the number of command-queues listed in _queues_. - If the `<>` extension is not + If the {cl_khr_command_buffer_multi_device_EXT} extension is not supported, this **must** be one. * _queues_ is a pointer to a list of command-queues that the command-buffer commands will be recorded to. @@ -14113,7 +14113,7 @@ endif::cl_khr_command_buffer_mutable_dispatch[] If _errcode_ret_ is `NULL`, no error code is returned. ifdef::cl_khr_command_buffer_multi_device[] -.Summary of command-buffer creation configurations, for the `<>` extension +.Summary of command-buffer creation configurations, for the {cl_khr_command_buffer_multi_device_EXT} extension [width="100%",options="header"] |==== | All Devices Associated With `Queues` can Device-side Sync | Platform Supports Universal Sync | Condition | Result @@ -14174,9 +14174,9 @@ returned in _errcode_ret_: specified by {CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR}. * {CL_INVALID_CONTEXT} if all the command-queues in _queues_ do not have the same OpenCL context. - * {CL_INVALID_VALUE} if the `<>` + * {CL_INVALID_VALUE} if the {cl_khr_command_buffer_multi_device_EXT} extension is supported and _num_queues_ is zero, or if the - `<>` extension is not supported + {cl_khr_command_buffer_multi_device_EXT} extension is not supported and _num_queues_ is not one. * {CL_INVALID_VALUE} if _queues_ is `NULL`. * {CL_INVALID_VALUE} if values specified in _properties_ are not valid, or @@ -14190,7 +14190,7 @@ returned in _errcode_ret_: required by the OpenCL implementation on the host. ifdef::cl_khr_command_buffer_multi_device[] -If the `<>` extension is supported: +If the {cl_khr_command_buffer_multi_device_EXT} extension is supported: * {CL_INCOMPATIBLE_COMMAND_QUEUE_KHR} if _queues_ includes more than one command-queue associated with a device that does not support capability @@ -14465,12 +14465,12 @@ include::{generated}/api/version-notes/clCommandCopyBufferKHR.asciidoc[] * _command_buffer_ refers to a valid command-buffer object. * _command_queue_ specifies the command-queue the command will be recorded to. {empty} + - If the `<>` extension is not supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is not supported, only a single command-queue is supported, and _command_queue_ must be `NULL`. ifdef::cl_khr_command_buffer_multi_device[] {empty} + - If the `<>` extension is supported and + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported and _command_queue_ is `NULL`, then only one command-queue must have been set on _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`. endif::cl_khr_command_buffer_multi_device[] @@ -14512,10 +14512,10 @@ Otherwise, it returns the errors defined by {clEnqueueCopyBuffer} except: {CL_INVALID_COMMAND_QUEUE} is replaced with: * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is not supported and + {cl_khr_command_buffer_multi_device_EXT} extension is not supported and _command_queue_ is not `NULL`. * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is supported; and + {cl_khr_command_buffer_multi_device_EXT} extension is supported; and either _command_queue_ is `NULL` and _command_buffer_ was created with more than one queue, or _command_queue_ is not `NULL` and not a command-queue listed on _command_buffer_ creation. @@ -14552,12 +14552,12 @@ include::{generated}/api/version-notes/clCommandCopyBufferRectKHR.asciidoc[] * _command_buffer_ refers to a valid command-buffer object. * _command_queue_ specifies the command-queue the command will be recorded to. {empty} + - If the `<>` extension is not supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is not supported, only a single command-queue is supported, and _command_queue_ must be `NULL`. ifdef::cl_khr_command_buffer_multi_device[] {empty} + - If the `<>` extension is supported and + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported and _command_queue_ is `NULL`, then only one command-queue must have been set on _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`. endif::cl_khr_command_buffer_multi_device[] @@ -14617,10 +14617,10 @@ except: {CL_INVALID_COMMAND_QUEUE} is replaced with: * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is not supported and + {cl_khr_command_buffer_multi_device_EXT} extension is not supported and _command_queue_ is not `NULL`. * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is supported; and + {cl_khr_command_buffer_multi_device_EXT} extension is supported; and either _command_queue_ is `NULL` and _command_buffer_ was created with more than one queue, or _command_queue_ is not `NULL` and not a command-queue listed on _command_buffer_ creation. @@ -14657,12 +14657,12 @@ include::{generated}/api/version-notes/clCommandCopyBufferToImageKHR.asciidoc[] * _command_buffer_ refers to a valid command-buffer object. * _command_queue_ specifies the command-queue the command will be recorded to. {empty} + - If the `<>` extension is not supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is not supported, only a single command-queue is supported, and _command_queue_ must be `NULL`. ifdef::cl_khr_command_buffer_multi_device[] {empty} + - If the `<>` extension is supported and + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported and _command_queue_ is `NULL`, then only one command-queue must have been set on _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`. endif::cl_khr_command_buffer_multi_device[] @@ -14705,10 +14705,10 @@ except: {CL_INVALID_COMMAND_QUEUE} is replaced with: * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is not supported and + {cl_khr_command_buffer_multi_device_EXT} extension is not supported and _command_queue_ is not `NULL`. * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is supported; and + {cl_khr_command_buffer_multi_device_EXT} extension is supported; and either _command_queue_ is `NULL` and _command_buffer_ was created with more than one queue, or _command_queue_ is not `NULL` and not a command-queue listed on _command_buffer_ creation. @@ -14744,12 +14744,12 @@ include::{generated}/api/version-notes/clCommandCopyImageKHR.asciidoc[] * _command_buffer_ refers to a valid command-buffer object. * _command_queue_ specifies the command-queue the command will be recorded to. {empty} + - If the `<>` extension is not supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is not supported, only a single command-queue is supported, and _command_queue_ must be `NULL`. ifdef::cl_khr_command_buffer_multi_device[] {empty} + - If the `<>` extension is supported and + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported and _command_queue_ is `NULL`, then only one command-queue must have been set on _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`. endif::cl_khr_command_buffer_multi_device[] @@ -14799,10 +14799,10 @@ Otherwise, it returns the errors defined by {clEnqueueCopyImage} except: {CL_INVALID_COMMAND_QUEUE} is replaced with: * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is not supported and + {cl_khr_command_buffer_multi_device_EXT} extension is not supported and _command_queue_ is not `NULL`. * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is supported; and + {cl_khr_command_buffer_multi_device_EXT} extension is supported; and either _command_queue_ is `NULL` and _command_buffer_ was created with more than one queue, or _command_queue_ is not `NULL` and not a command-queue listed on _command_buffer_ creation. @@ -14839,12 +14839,12 @@ include::{generated}/api/version-notes/clCommandCopyImageToBufferKHR.asciidoc[] * _command_buffer_ refers to a valid command-buffer object. * _command_queue_ specifies the command-queue the command will be recorded to. {empty} + - If the `<>` extension is not supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is not supported, only a single command-queue is supported, and _command_queue_ must be `NULL`. ifdef::cl_khr_command_buffer_multi_device[] {empty} + - If the `<>` extension is supported and + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported and _command_queue_ is `NULL`, then only one command-queue must have been set on _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`. endif::cl_khr_command_buffer_multi_device[] @@ -14887,10 +14887,10 @@ except: {CL_INVALID_COMMAND_QUEUE} is replaced with: * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is not supported and + {cl_khr_command_buffer_multi_device_EXT} extension is not supported and _command_queue_ is not `NULL`. * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is supported; and + {cl_khr_command_buffer_multi_device_EXT} extension is supported; and either _command_queue_ is `NULL` and _command_buffer_ was created with more than one queue, or _command_queue_ is not `NULL` and not a command-queue listed on _command_buffer_ creation. @@ -14935,12 +14935,12 @@ value specified when _buffer_ is created is ignored by * _command_buffer_ refers to a valid command-buffer object. * _command_queue_ specifies the command-queue the command will be recorded to. {empty} + - If the `<>` extension is not supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is not supported, only a single command-queue is supported, and _command_queue_ must be `NULL`. ifdef::cl_khr_command_buffer_multi_device[] {empty} + - If the `<>` extension is supported and + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported and _command_queue_ is `NULL`, then only one command-queue must have been set on _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`. endif::cl_khr_command_buffer_multi_device[] @@ -14982,10 +14982,10 @@ Otherwise, it returns the errors defined by {clEnqueueFillBuffer} except: {CL_INVALID_COMMAND_QUEUE} is replaced with: * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is not supported and + {cl_khr_command_buffer_multi_device_EXT} extension is not supported and _command_queue_ is not `NULL`. * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is supported; and + {cl_khr_command_buffer_multi_device_EXT} extension is supported; and either _command_queue_ is `NULL` and _command_buffer_ was created with more than one queue, or _command_queue_ is not `NULL` and not a command-queue listed on _command_buffer_ creation. @@ -15029,12 +15029,12 @@ value specified when image is created is ignored by {clCommandFillImageKHR}. * _command_buffer_ refers to a valid command-buffer object. * _command_queue_ specifies the command-queue the command will be recorded to. {empty} + - If the `<>` extension is not supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is not supported, only a single command-queue is supported, and _command_queue_ must be `NULL`. ifdef::cl_khr_command_buffer_multi_device[] {empty} + - If the `<>` extension is supported and + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported and _command_queue_ is `NULL`, then only one command-queue must have been set on _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`. endif::cl_khr_command_buffer_multi_device[] @@ -15075,10 +15075,10 @@ Otherwise, it returns the errors defined by {clEnqueueFillImage} except: {CL_INVALID_COMMAND_QUEUE} is replaced with: * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is not supported and + {cl_khr_command_buffer_multi_device_EXT} extension is not supported and _command_queue_ is not `NULL`. * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is supported; and + {cl_khr_command_buffer_multi_device_EXT} extension is supported; and either _command_queue_ is `NULL` and _command_buffer_ was created with more than one queue, or _command_queue_ is not `NULL` and not a command-queue listed on _command_buffer_ creation. @@ -15114,12 +15114,12 @@ include::{generated}/api/version-notes/clCommandNDRangeKernelKHR.asciidoc[] * _command_buffer_ refers to a valid command-buffer object. * _command_queue_ specifies the command-queue the command will be recorded to. {empty} + - If the `<>` extension is not supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is not supported, only a single command-queue is supported, and _command_queue_ must be `NULL`. ifdef::cl_khr_command_buffer_multi_device[] {empty} + - If the `<>` extension is supported and + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported and _command_queue_ is `NULL`, then only one command-queue must have been set on _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`. endif::cl_khr_command_buffer_multi_device[] @@ -15133,7 +15133,7 @@ ifdef::cl_khr_command_buffer_mutable_dispatch[] default value will be used. _properties_ may be `NULL`, in which case the default values for supported properties will be used. - The `<>` extension does not define any + The {cl_khr_command_buffer_EXT} extension does not define any properties, but supported properties defined by extensions are defined in the <> table. @@ -15173,7 +15173,7 @@ after the function returns. _sync_point_wait_list_ array. * _mutable_handle_ returns a handle to the command. ifdef::cl_khr_command_buffer_mutable_dispatch[] - If the `<>` extension is + If the {cl_khr_command_buffer_mutable_dispatch_EXT} extension is supported, and _mutable_handle_ is not `NULL`, it can be used in the {cl_mutable_dispatch_config_khr_TYPE} struct to update the command configuration between recordings. @@ -15181,7 +15181,7 @@ ifdef::cl_khr_command_buffer_mutable_dispatch[] that freeing the command-buffer will also free this handle. endif::cl_khr_command_buffer_mutable_dispatch[] ifndef::cl_khr_command_buffer_mutable_dispatch[] - If the `<>` extension is not + If the {cl_khr_command_buffer_mutable_dispatch_EXT} extension is not supported, this parameter is unused, and **must** be `NULL`. endif::cl_khr_command_buffer_mutable_dispatch[] @@ -15319,10 +15319,10 @@ Otherwise, it returns the errors defined by {clEnqueueNDRangeKernel} except: {CL_INVALID_COMMAND_QUEUE} is replaced with: * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is not supported and + {cl_khr_command_buffer_multi_device_EXT} extension is not supported and _command_queue_ is not `NULL`. * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is supported; and + {cl_khr_command_buffer_multi_device_EXT} extension is supported; and either _command_queue_ is `NULL` and _command_buffer_ was created with more than one queue, or _command_queue_ is not `NULL` and not a command-queue listed on _command_buffer_ creation. @@ -15346,7 +15346,7 @@ New errors: command-buffer. * {CL_INVALID_VALUE} if values specified in _properties_ are not valid * {CL_INVALID_OPERATION} if _command_buffer_ has been finalized. - * {CL_INVALID_VALUE} if the `<>` + * {CL_INVALID_VALUE} if the {cl_khr_command_buffer_mutable_dispatch_EXT} extension is not supported and _mutable_handle_ is not `NULL`. * {CL_INVALID_OPERATION} if the device associated with _command_queue_ does not support {CL_COMMAND_BUFFER_CAPABILITY_KERNEL_PRINTF_KHR} and @@ -15356,7 +15356,7 @@ New errors: and _kernel_ contains a kernel-enqueue call. ifdef::cl_khr_command_buffer_mutable_dispatch[] -If the `<>` extension is supported: +If the {cl_khr_command_buffer_mutable_dispatch_EXT} extension is supported: * {CL_INVALID_OPERATION} if the requested {CL_MUTABLE_DISPATCH_UPDATABLE_FIELDS_KHR} properties are not reported @@ -15385,12 +15385,12 @@ include::{generated}/api/version-notes/clCommandSVMMemcpyKHR.asciidoc[] * _command_buffer_ refers to a valid command-buffer object. * _command_queue_ specifies the command-queue the command will be recorded to. {empty} + - If the `<>` extension is not supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is not supported, only a single command-queue is supported, and _command_queue_ must be `NULL`. ifdef::cl_khr_command_buffer_multi_device[] {empty} + - If the `<>` extension is supported and + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported and _command_queue_ is `NULL`, then only one command-queue must have been set on _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`. endif::cl_khr_command_buffer_multi_device[] @@ -15435,10 +15435,10 @@ Otherwise, it returns the errors defined by {clEnqueueSVMMemcpy} except: {CL_INVALID_COMMAND_QUEUE} is replaced with: * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is not supported and + {cl_khr_command_buffer_multi_device_EXT} extension is not supported and _command_queue_ is not `NULL`. * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is supported; and + {cl_khr_command_buffer_multi_device_EXT} extension is supported; and either _command_queue_ is `NULL` and _command_buffer_ was created with more than one queue, or _command_queue_ is not `NULL` and not a command-queue listed on _command_buffer_ creation. @@ -15475,12 +15475,12 @@ include::{generated}/api/version-notes/clCommandSVMMemFillKHR.asciidoc[] * _command_buffer_ refers to a valid command-buffer object. * _command_queue_ specifies the command-queue the command will be recorded to. {empty} + - If the `<>` extension is not supported, + If the {cl_khr_command_buffer_multi_device_EXT} extension is not supported, only a single command-queue is supported, and _command_queue_ must be `NULL`. ifdef::cl_khr_command_buffer_multi_device[] {empty} + - If the `<>` extension is supported and + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported and _command_queue_ is `NULL`, then only one command-queue must have been set on _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`. endif::cl_khr_command_buffer_multi_device[] @@ -15541,10 +15541,10 @@ successfully. Otherwise, it returns the errors defined by {CL_INVALID_COMMAND_QUEUE} is replaced with: * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is not supported and + {cl_khr_command_buffer_multi_device_EXT} extension is not supported and _command_queue_ is not `NULL`. * {CL_INVALID_COMMAND_QUEUE} if the - `<>` extension is supported; and + {cl_khr_command_buffer_multi_device_EXT} extension is supported; and either _command_queue_ is `NULL` and _command_buffer_ was created with more than one queue, or _command_queue_ is not `NULL` and not a command-queue listed on _command_buffer_ creation. @@ -15574,7 +15574,7 @@ New errors: ifdef::cl_khr_command_buffer_multi_device[] === Remapping Command-Buffers -If the `<>` extension is supported, +If the {cl_khr_command_buffer_multi_device_EXT} extension is supported, platforms reporting the {CL_COMMAND_BUFFER_PLATFORM_REMAP_QUEUES_KHR} capability support generating a deep copy of a command-buffer with its commands remapped to a list of command-queues that are potentially @@ -15694,7 +15694,7 @@ ifdef::cl_khr_command_buffer_mutable_dispatch[] A generic {cl_mutable_command_khr_TYPE} handle is called a _mutable-command_ object as it can be returned from any command recording entry-point in the -`<>` family of extensions. +{cl_khr_command_buffer_EXT} family of extensions. The mutable-command handles returned by {clCommandNDRangeKernelKHR} in particular are referred to as _mutable-dispatch_ objects, and can be modified through the fields of {cl_mutable_dispatch_config_khr_TYPE}. @@ -15715,7 +15715,7 @@ kernel object used when the command was recorded, and only influence the [[mutable-dispatch-kernel-argument-safe-usage]] [NOTE] ==== -The base `<>` extension +The base {cl_khr_command_buffer_EXT} extension <> that a command-buffer does not update the reference count of objects set as arguments on kernels recorded into the command-buffer. diff --git a/c/dictionary.asciidoc b/c/dictionary.asciidoc index bdf9c23c3..ef7a9401b 100644 --- a/c/dictionary.asciidoc +++ b/c/dictionary.asciidoc @@ -3,3 +3,4 @@ // http://creativecommons.org/licenses/by/4.0/ include::{generated}/api/api-dictionary-no-links.asciidoc[] +include::{generated}/api/ext-dictionary-no-links.asciidoc[] diff --git a/c/footnotes.asciidoc b/c/footnotes.asciidoc index c22db5889..fc85efc76 100644 --- a/c/footnotes.asciidoc +++ b/c/footnotes.asciidoc @@ -21,17 +21,17 @@ The <> consume operation is not supported. \ ] :fn-atomic-double-supported: pass:n[ \ -The `atomic_double` type is only supported if double precision is supported and the *cl_khr_int64_base_atomics* and *cl_khr_int64_extended_atomics* extensions are supported and have been enabled. \ +The `atomic_double` type is only supported if double precision is supported and the {cl_khr_int64_base_atomics_EXT} and {cl_khr_int64_extended_atomics_EXT} extensions are supported and have been enabled. \ If this is the case then an OpenCL C 3.0 compiler must also define the {opencl_c_fp64} feature. \ ] :fn-atomic-int64-supported: pass:n[ \ -The atomic_long and atomic_ulong types are supported if the *cl_khr_int64_base_atomics* and *cl_khr_int64_extended_atomics* extensions are supported and have been enabled. \ +The atomic_long and atomic_ulong types are supported if the {cl_khr_int64_base_atomics_EXT} and {cl_khr_int64_extended_atomics_EXT} extensions are supported and have been enabled. \ If this is the case then an OpenCL C 3.0 compiler must also define the {opencl_c_int64} feature. \ ] :fn-atomic-size_t-supported: pass:n[ \ -If the device address space is 64-bits, the data types `atomic_intptr_t`, `atomic_uintptr_t`, `atomic_size_t` and `atomic_ptrdiff_t` are supported if the *cl_khr_int64_base_atomics* and *cl_khr_int64_extended_atomics* extensions are supported and have been enabled. \ +If the device address space is 64-bits, the data types `atomic_intptr_t`, `atomic_uintptr_t`, `atomic_size_t` and `atomic_ptrdiff_t` are supported if the {cl_khr_int64_base_atomics_EXT} and {cl_khr_int64_extended_atomics_EXT} extensions are supported and have been enabled. \ ] :fn-atomic-weak-rationale: pass:n[ \ @@ -48,11 +48,11 @@ When any scalar value is converted to `bool`, the result is 0 if the value compa :fn-cl_double: pass:n[ \ <> support for OpenCL C 1.2 or above. \ -Also see extension *cl_khr_fp64*. \ +Also see extension {cl_khr_fp64_EXT}. \ ] :fn-cl_khr_fp16: pass:n[ \ -Unless the *cl_khr_fp16* extension is supported and has been enabled. \ +Unless the {cl_khr_fp16_EXT} extension is supported and has been enabled. \ ] :fn-clang-block-syntax: pass:n[ \ @@ -131,7 +131,7 @@ If an implementation extends this specification to support IEEE-754 flags or exc ] :fn-float-types-supported: pass:n[ \ -The `half` scalar and vector types can only be used if the *cl_khr_fp16* extension is supported and has been enabled. \ +The `half` scalar and vector types can only be used if the {cl_khr_fp16_EXT} extension is supported and has been enabled. \ The `double` scalar and vector types can only be used if `double` precision is supported, e.g. for OpenCL C 3.0 the {opencl_c_fp64} feature macro is present. \ ] @@ -146,7 +146,7 @@ It returns the largest positive floating-point number less than 1.0. \ ] :fn-half-supported: pass:n[ \ -Only if the *cl_khr_fp16* extension is supported and has been enabled. \ +Only if the {cl_khr_fp16_EXT} extension is supported and has been enabled. \ ] :fn-image-functions: pass:n[ \ diff --git a/env/appendix_a.asciidoc b/env/appendix_a.asciidoc index 10ae42123..2c58efbf9 100644 --- a/env/appendix_a.asciidoc +++ b/env/appendix_a.asciidoc @@ -18,13 +18,13 @@ Changes from *v3.0.5*: * Clarified sub-group barrier behavior in non-uniform control flow. * Added required alignment of types. * Added new extensions: - ** `cl_khr_subgroup_extended_types` - ** `cl_khr_subgroup_non_uniform_vote` - ** `cl_khr_subgroup_ballot` - ** `cl_khr_subgroup_non_uniform_arithmetic` - ** `cl_khr_subgroup_shuffle` - ** `cl_khr_subgroup_shuffle_relative` - ** `cl_khr_subgroup_clustered_reduce` + ** {cl_khr_subgroup_extended_types_EXT} + ** {cl_khr_subgroup_non_uniform_vote_EXT} + ** {cl_khr_subgroup_ballot_EXT} + ** {cl_khr_subgroup_non_uniform_arithmetic_EXT} + ** {cl_khr_subgroup_shuffle_EXT} + ** {cl_khr_subgroup_shuffle_relative_EXT} + ** {cl_khr_subgroup_clustered_reduce_EXT} Changes from *v3.0.6*: @@ -32,9 +32,9 @@ Changes from *v3.0.6*: * Added the required type for SPIR-V built-in variables. * Fixed several bugs and formatting in the fast math ULP tables. * Added new extensions: - ** `cl_khr_extended_bit_ops` - ** `cl_khr_spirv_extended_debug_info` - ** `cl_khr_spirv_linkonce_odr` + ** {cl_khr_extended_bit_ops_EXT} + ** {cl_khr_spirv_extended_debug_info_EXT} + ** {cl_khr_spirv_linkonce_odr_EXT} Changes from *v3.0.8*: diff --git a/env/common_properties.asciidoc b/env/common_properties.asciidoc index c8ce83dff..8019b751d 100644 --- a/env/common_properties.asciidoc +++ b/env/common_properties.asciidoc @@ -19,9 +19,9 @@ version number, as described in the SPIR-V specification. An OpenCL environment describes the versions of SPIR-V modules that it supports using the {CL_DEVICE_IL_VERSION} query in OpenCL 2.1 or newer, the {CL_DEVICE_ILS_WITH_VERSION} query in OpenCL 3.0 or newer, or the -{CL_DEVICE_IL_VERSION_KHR} query in the `cl_khr_il_program` extension. +{CL_DEVICE_IL_VERSION_KHR} query in the {cl_khr_il_program_EXT} extension. -OpenCL environments that support the `cl_khr_il_program` extension or +OpenCL environments that support the {cl_khr_il_program_EXT} extension or OpenCL 2.1 must support SPIR-V 1.0 modules. OpenCL environments that support OpenCL 2.2 must support SPIR-V 1.0, 1.1, and 1.2 modules. Use the {CL_DEVICE_IL_VERSION} or {CL_DEVICE_ILS_WITH_VERSION} query diff --git a/env/dictionary.asciidoc b/env/dictionary.asciidoc index bdf9c23c3..ef7a9401b 100644 --- a/env/dictionary.asciidoc +++ b/env/dictionary.asciidoc @@ -3,3 +3,4 @@ // http://creativecommons.org/licenses/by/4.0/ include::{generated}/api/api-dictionary-no-links.asciidoc[] +include::{generated}/api/ext-dictionary-no-links.asciidoc[] diff --git a/env/extensions.asciidoc b/env/extensions.asciidoc index df0259550..f0ffc5d6b 100644 --- a/env/extensions.asciidoc +++ b/env/extensions.asciidoc @@ -35,15 +35,15 @@ in a SPIR-V module using *OpExtension*. === Full and Embedded Profile Extensions -==== `cl_khr_3d_image_writes` +==== {cl_khr_3d_image_writes_EXT} -If the OpenCL environment supports the extension `cl_khr_3d_image_writes`, +If the OpenCL environment supports the extension {cl_khr_3d_image_writes_EXT}, then the environment must accept _Image_ operands to *OpImageWrite* that are declared with with dimensionality _Dim_ equal to *3D*. -==== `cl_khr_depth_images` +==== {cl_khr_depth_images_EXT} -If the OpenCL environment supports the extension `cl_khr_depth_images`, +If the OpenCL environment supports the extension {cl_khr_depth_images_EXT}, then the environment must accept modules that declare 2D depth image types using *OpTypeImage* with dimensionality _Dim_ equal to *2D* and _Depth_ equal to 1, indicating a depth image. 2D depth images may optionally be @@ -54,32 +54,32 @@ Additionally, the following Image Channel Orders may be returned by * *Depth* -==== `cl_khr_device_enqueue_local_arg_types` +==== {cl_khr_device_enqueue_local_arg_types_EXT} If the OpenCL environment supports the extension -`cl_khr_device_enqueue_local_arg_types`, then then environment will allow +{cl_khr_device_enqueue_local_arg_types_EXT}, then then environment will allow _Invoke_ functions to be passed to *OpEnqueueKernel* with *Workgroup* memory pointer parameters of any type. -==== `cl_khr_fp16` +==== {cl_khr_fp16_EXT} -If the OpenCL environment supports the extension `cl_khr_fp16`, then the +If the OpenCL environment supports the extension {cl_khr_fp16_EXT}, then the environment must accept modules that declare the following SPIR-V capabilities: * *Float16* -==== `cl_khr_fp64` +==== {cl_khr_fp64_EXT} -If the OpenCL environment supports the extension `cl_khr_fp64`, then the +If the OpenCL environment supports the extension {cl_khr_fp64_EXT}, then the environment must accept modules that declare the following SPIR-V capabilities: * *Float64* -==== `cl_khr_gl_depth_images` +==== {cl_khr_gl_depth_images_EXT} -If the OpenCL environment supports the extension `cl_khr_gl_depth_images`, +If the OpenCL environment supports the extension {cl_khr_gl_depth_images_EXT}, then the following Image Channel Orders may additionally be returned by *OpImageQueryOrder*: @@ -90,11 +90,11 @@ Also, the following Image Channel Data Types may additionally be returned by * *UnormInt24* -==== `cl_khr_gl_msaa_sharing` +==== {cl_khr_gl_msaa_sharing_EXT} // TODO: How does this affect the *ImageMSArray* capability? This is currently a *Shader* capability. -If the OpenCL environment supports the extension `cl_khr_gl_msaa_sharing`, +If the OpenCL environment supports the extension {cl_khr_gl_msaa_sharing_EXT}, then the environment must accept modules that declare 2D multi-sampled image types using *OpTypeImage* with dimensionality _Dim_ equal to *2D* and _MS_ equal to 1, indicating multi-sampled content. 2D multi-sampled images @@ -108,13 +108,13 @@ The 2D multi-sampled images may be used with the following instructions: * *OpImageQueryOrder* * *OpImageQuerySamples* -//==== `cl_khr_initialize_memory` +//==== {cl_khr_initialize_memory_EXT} // Do we need to say anything about this extension in this spec? -==== `cl_khr_int64_base_atomics` and `cl_khr_int64_extended_atomics` +==== {cl_khr_int64_base_atomics_EXT} and {cl_khr_int64_extended_atomics_EXT} -If the OpenCL environment supports the extension `cl_khr_int64_base_atomics` -or `cl_khr_int64_extended_atomics`, then the environment must accept modules +If the OpenCL environment supports the extension {cl_khr_int64_base_atomics_EXT} +or {cl_khr_int64_extended_atomics_EXT}, then the environment must accept modules that declare the following SPIR-V capabilities: * *Int64Atomics* @@ -123,12 +123,12 @@ When the *Int64Atomics* capability is declared, 64-bit integer types are valid for the _Result Type_ and type of _Value_ for all *Atomic Instructions*. Note: OpenCL environments that consume SPIR-V must support both -`cl_khr_int64_base_atomics` and `cl_khr_int64_extended_atomics` or neither +{cl_khr_int64_base_atomics_EXT} and {cl_khr_int64_extended_atomics_EXT} or neither of these extensions. -==== `cl_khr_mipmap_image` +==== {cl_khr_mipmap_image_EXT} -If the OpenCL environment supports the extension `cl_khr_mipmap_image`, +If the OpenCL environment supports the extension {cl_khr_mipmap_image_EXT}, then the environment must accept non-zero optional *Lod* _Image Operands_ for the following instructions: @@ -136,25 +136,25 @@ for the following instructions: * *OpImageRead* * *OpImageQuerySizeLod* -Note: Implementations that support `cl_khr_mipmap_image` are not guaranteed +Note: Implementations that support {cl_khr_mipmap_image_EXT} are not guaranteed to support the *ImageMipmap* capability, since this extension does not require non-zero optional *Lod* _Image Operands_ for *OpImageWrite*. -==== `cl_khr_mipmap_image_writes` +==== {cl_khr_mipmap_image_writes_EXT} -If the OpenCL environment supports the extension `cl_khr_mipmap_image_writes`, +If the OpenCL environment supports the extension {cl_khr_mipmap_image_writes_EXT}, then the environment must accept non-zero optional *Lod* _Image Operands_ for the following instructions: * *OpImageWrite* -Note: An implementation that supports `cl_khr_mipmap_image_writes` must also -support `cl_khr_mipmap_image`, and support for both extensions does +Note: An implementation that supports {cl_khr_mipmap_image_writes_EXT} must also +support {cl_khr_mipmap_image_EXT}, and support for both extensions does guarantee support for the *ImageMipmap* capability. -==== `cl_khr_subgroups` +==== {cl_khr_subgroups_EXT} -If the OpenCL environment supports the extension `cl_khr_subgroups`, then +If the OpenCL environment supports the extension {cl_khr_subgroups_EXT}, then for all instructions except *OpGroupAsyncCopy* and *OpGroupWaitEvents* the _Scope_ for _Execution_ may be: @@ -165,23 +165,23 @@ OpenCL 1.2 environment, the _Scope_ for _Memory_ may be: * *Subgroup* -==== `cl_khr_subgroup_named_barrier` +==== {cl_khr_subgroup_named_barrier_EXT} If the OpenCL environment supports the extension -`cl_khr_subgroup_named_barrier`, then the environment must accept modules +{cl_khr_subgroup_named_barrier_EXT}, then the environment must accept modules that declare the following SPIR-V capabilities: * *NamedBarrier* -==== `cl_khr_spirv_no_integer_wrap_decoration` +==== {cl_khr_spirv_no_integer_wrap_decoration_EXT} -If the OpenCL environment supports the extension `cl_khr_spirv_no_integer_wrap_decoration`, then the environment must accept modules that declare use of the extension `SPV_KHR_no_integer_wrap_decoration` via *OpExtension*. +If the OpenCL environment supports the extension {cl_khr_spirv_no_integer_wrap_decoration_EXT}, then the environment must accept modules that declare use of the extension `SPV_KHR_no_integer_wrap_decoration` via *OpExtension*. -If the OpenCL environment supports the extension `cl_khr_spirv_no_integer_wrap_decoration` and use of the SPIR-V extension `SPV_KHR_no_integer_wrap_decoration` is declared in the module via *OpExtension*, then the environment must accept modules that include the *NoSignedWrap* or *NoUnsignedWrap* decorations. +If the OpenCL environment supports the extension {cl_khr_spirv_no_integer_wrap_decoration_EXT} and use of the SPIR-V extension `SPV_KHR_no_integer_wrap_decoration` is declared in the module via *OpExtension*, then the environment must accept modules that include the *NoSignedWrap* or *NoUnsignedWrap* decorations. -==== `cl_khr_subgroup_extended_types` +==== {cl_khr_subgroup_extended_types_EXT} -If the OpenCL environment supports the extension `cl_khr_subgroup_extended_types`, then additional types are valid for the following for *Groups* instructions with _Scope_ for _Execution_ equal to *Subgroup*: +If the OpenCL environment supports the extension {cl_khr_subgroup_extended_types_EXT}, then additional types are valid for the following for *Groups* instructions with _Scope_ for _Execution_ equal to *Subgroup*: * *OpGroupBroadcast* * *OpGroupIAdd*, *OpGroupFAdd* @@ -200,9 +200,9 @@ Additionally, for *OpGroupBroadcast*, valid types for _Value_ are: ** *OpTypeInt* (equivalent to `char__n__`, `uchar__n__`, `short__n__`, `ushort__n__`, `int__n__`, `uint__n__`, `long__n__`, and `ulong__n__`) ** *OpTypeFloat* (equivalent to `half__n__`, `float__n__`, and `double__n__`) -==== `cl_khr_subgroup_non_uniform_vote` +==== {cl_khr_subgroup_non_uniform_vote_EXT} -If the OpenCL environment supports the extension `cl_khr_subgroup_non_uniform_vote`, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities: +If the OpenCL environment supports the extension {cl_khr_subgroup_non_uniform_vote_EXT}, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities: * *GroupNonUniform* * *GroupNonUniformVote* @@ -217,9 +217,9 @@ For the instruction *OpGroupNonUniformAllEqual*, valid types for _Value_ are: ** *OpTypeInt* (equivalent to `char`, `uchar`, `short`, `ushort`, `int`, `uint`, `long`, and `ulong`) ** *OpTypeFloat* (equivalent to `half`, `float`, and `double`) -==== `cl_khr_subgroup_ballot` +==== {cl_khr_subgroup_ballot_EXT} -If the OpenCL environment supports the extension `cl_khr_subgroup_ballot`, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities: +If the OpenCL environment supports the extension {cl_khr_subgroup_ballot_EXT}, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities: * *GroupNonUniformBallot* @@ -248,9 +248,9 @@ For the instructions *OpGroupNonUniformInverseBallot*, *OpGroupNonUniformBallotB For built-in variables decorated with *SubgroupEqMask*, *SubgroupGeMask*, *SubgroupGtMask*, *SubgroupLeMask*, or *SubgroupLtMask*, the supported variable type is an *OpTypeVector* with four _Component Count_ components of *OpTypeInt*, with _Width_ equal to 32 and _Signedness_ equal to 0 (equivalent to `uint4`). -==== `cl_khr_subgroup_non_uniform_arithmetic` +==== {cl_khr_subgroup_non_uniform_arithmetic_EXT} -If the OpenCL environment supports the extension `cl_khr_subgroup_non_uniform_arithmetic`, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities: +If the OpenCL environment supports the extension {cl_khr_subgroup_non_uniform_arithmetic_EXT}, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities: * *GroupNonUniformArithmetic* @@ -268,9 +268,9 @@ Otherwise, for the *GroupNonUniformArithmetic* scan and reduction instructions, For the *GroupNonUniformArithmetic* scan and reduction instructions, the optional _ClusterSize_ operand must not be present. -==== `cl_khr_subgroup_shuffle` +==== {cl_khr_subgroup_shuffle_EXT} -If the OpenCL environment supports the extension `cl_khr_subgroup_shuffle`, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities: +If the OpenCL environment supports the extension {cl_khr_subgroup_shuffle_EXT}, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities: * *GroupNonUniformShuffle* @@ -284,9 +284,9 @@ For the instructions *OpGroupNonUniformShuffle* and *OpGroupNonUniformShuffleXor ** *OpTypeInt* (equivalent to `char`, `uchar`, `short`, `ushort`, `int`, `uint`, `long`, and `ulong`) ** *OpTypeFloat* (equivalent to `half`, `float`, and `double`) -==== `cl_khr_subgroup_shuffle_relative` +==== {cl_khr_subgroup_shuffle_relative_EXT} -If the OpenCL environment supports the extension `cl_khr_subgroup_shuffle_relative`, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities: +If the OpenCL environment supports the extension {cl_khr_subgroup_shuffle_relative_EXT}, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities: * *GroupNonUniformShuffleRelative* @@ -300,9 +300,9 @@ For the *GroupNonUniformShuffleRelative* instructions, valid types for _Value_ a ** *OpTypeInt* (equivalent to `char`, `uchar`, `short`, `ushort`, `int`, `uint`, `long`, and `ulong`) ** *OpTypeFloat* (equivalent to `half`, `float`, and `double`) -==== `cl_khr_subgroup_clustered_reduce` +==== {cl_khr_subgroup_clustered_reduce_EXT} -If the OpenCL environment supports the extension `cl_khr_subgroup_clustered_reduce`, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities: +If the OpenCL environment supports the extension {cl_khr_subgroup_clustered_reduce_EXT}, then the environment must accept SPIR-V modules that declare the following SPIR-V capabilities: * *GroupNonUniformClustered* @@ -312,26 +312,26 @@ For instructions requiring these capabilities, _Scope_ for _Execution_ may be: When the *GroupNonUniformClustered* capability is declared, the *GroupNonUniformArithmetic* scan and reduction instructions may include the optional _ClusterSize_ operand. -==== `cl_khr_spirv_extended_debug_info` +==== {cl_khr_spirv_extended_debug_info_EXT} -If the OpenCL environment supports the extension `cl_khr_spirv_extended_debug_info`, then the environment must accept modules +If the OpenCL environment supports the extension {cl_khr_spirv_extended_debug_info_EXT}, then the environment must accept modules that import the `OpenCL.DebugInfo.100` extended instruction set via *OpExtInstImport*. -==== `cl_khr_spirv_linkonce_odr` +==== {cl_khr_spirv_linkonce_odr_EXT} -If the OpenCL environment supports the extension `cl_khr_spirv_linkonce_odr`, then the environment must accept modules that declare use of the extension `SPV_KHR_linkonce_odr` via *OpExtension*. +If the OpenCL environment supports the extension {cl_khr_spirv_linkonce_odr_EXT}, then the environment must accept modules that declare use of the extension `SPV_KHR_linkonce_odr` via *OpExtension*. -If the OpenCL environment supports the extension `cl_khr_spirv_linkonce_odr` and use of the SPIR-V extension `SPV_KHR_linkonce_odr` is declared in the module via *OpExtension*, then the environment must accept modules that include the *LinkOnceODR* linkage type. +If the OpenCL environment supports the extension {cl_khr_spirv_linkonce_odr_EXT} and use of the SPIR-V extension `SPV_KHR_linkonce_odr` is declared in the module via *OpExtension*, then the environment must accept modules that include the *LinkOnceODR* linkage type. -==== `cl_khr_extended_bit_ops` +==== {cl_khr_extended_bit_ops_EXT} -If the OpenCL environment supports the extension `cl_khr_extended_bit_ops`, then the environment must accept modules that declare use of the extension `SPV_KHR_bit_instructions` via *OpExtension*. +If the OpenCL environment supports the extension {cl_khr_extended_bit_ops_EXT}, then the environment must accept modules that declare use of the extension `SPV_KHR_bit_instructions` via *OpExtension*. -If the OpenCL environment supports the extension `cl_khr_extended_bit_ops` and use of the SPIR-V extension `SPV_KHR_bit_instructions` is declared in the module via *OpExtension*, then the environment must accept modules that declare the *BitInstructions* capability. +If the OpenCL environment supports the extension {cl_khr_extended_bit_ops_EXT} and use of the SPIR-V extension `SPV_KHR_bit_instructions` is declared in the module via *OpExtension*, then the environment must accept modules that declare the *BitInstructions* capability. -==== `cl_khr_integer_dot_product` +==== {cl_khr_integer_dot_product_EXT} -If the OpenCL environment supports the extension `cl_khr_integer_dot_product`, +If the OpenCL environment supports the extension {cl_khr_integer_dot_product_EXT}, then the environment must accept modules that require `SPV_KHR_integer_dot_product` and declare the following SPIR-V capabilities: @@ -339,17 +339,17 @@ declare the following SPIR-V capabilities: * *DotProductInput4x8BitKHR* if {CL_DEVICE_INTEGER_DOT_PRODUCT_INPUT_4x8BIT_KHR} is supported * *DotProductInput4x8BitPackedKHR* -==== `cl_khr_expect_assume` +==== {cl_khr_expect_assume_EXT} -If the OpenCL environment supports the extension `cl_khr_expect_assume`, then the environment must accept modules that declare use of the extension `SPV_KHR_expect_assume` via *OpExtension*. +If the OpenCL environment supports the extension {cl_khr_expect_assume_EXT}, then the environment must accept modules that declare use of the extension `SPV_KHR_expect_assume` via *OpExtension*. -If the OpenCL environment supports the extension `cl_khr_expect_assume` and use of the SPIR-V extension `SPV_KHR_expect_assume` is declared in the module via *OpExtension*, then the environment must accept modules that declare the following SPIR-V capabilities: +If the OpenCL environment supports the extension {cl_khr_expect_assume_EXT} and use of the SPIR-V extension `SPV_KHR_expect_assume` is declared in the module via *OpExtension*, then the environment must accept modules that declare the following SPIR-V capabilities: * *ExpectAssumeKHR* -==== `cl_khr_subgroup_rotate` +==== {cl_khr_subgroup_rotate_EXT} -If the OpenCL environment supports the extension `cl_khr_subgroup_rotate`, +If the OpenCL environment supports the extension {cl_khr_subgroup_rotate_EXT}, then the environment accept modules that require `SPV_KHR_subgroup_rotate` and declare the following SPIR-V capabilities: @@ -359,11 +359,11 @@ For instructions requiring these capabilities, _Scope_ for _Execution_ may be: * *Subgroup* -==== `cl_khr_work_group_uniform_arithmetic` +==== {cl_khr_work_group_uniform_arithmetic_EXT} -If the OpenCL environment supports the extension `cl_khr_work_group_uniform_arithmetic`, then the environment must accept modules that declare use of the extension `SPV_KHR_uniform_group_instructions` via *OpExtension*. +If the OpenCL environment supports the extension {cl_khr_work_group_uniform_arithmetic_EXT}, then the environment must accept modules that declare use of the extension `SPV_KHR_uniform_group_instructions` via *OpExtension*. -If the OpenCL environment supports the extension `cl_khr_work_group_uniform_arithmetic` and use of the SPIR-V extension `SPV_KHR_uniform_group_instructions` is declared in the module via *OpExtension*, then the environment must accept modules that declare the following SPIR-V capabilities: +If the OpenCL environment supports the extension {cl_khr_work_group_uniform_arithmetic_EXT} and use of the SPIR-V extension `SPV_KHR_uniform_group_instructions` is declared in the module via *OpExtension*, then the environment must accept modules that declare the following SPIR-V capabilities: * *GroupUniformArithmeticKHR* diff --git a/ext/deprecated_extensions.asciidoc b/ext/deprecated_extensions.asciidoc index 200eda14b..7004cd3d6 100644 --- a/ext/deprecated_extensions.asciidoc +++ b/ext/deprecated_extensions.asciidoc @@ -7,5 +7,5 @@ === For OpenCL 1.1: -* The *cl_khr_select_fprounding_mode* extension has been deprecated. +* The {cl_khr_select_fprounding_mode_EXT} extension has been deprecated. Its use is no longer recommended. diff --git a/ext/dictionary.asciidoc b/ext/dictionary.asciidoc index bdf9c23c3..ef7a9401b 100644 --- a/ext/dictionary.asciidoc +++ b/ext/dictionary.asciidoc @@ -3,3 +3,4 @@ // http://creativecommons.org/licenses/by/4.0/ include::{generated}/api/api-dictionary-no-links.asciidoc[] +include::{generated}/api/ext-dictionary-no-links.asciidoc[] diff --git a/ext/introduction.asciidoc b/ext/introduction.asciidoc index 9c22399cc..4c4cf584e 100644 --- a/ext/introduction.asciidoc +++ b/ext/introduction.asciidoc @@ -145,7 +145,7 @@ extension is supported on a given implementation. *Example*: An extension which adds the extension string `"cl_khr_3d_image_writes"` -should also add a preprocessor `#define` called *`cl_khr_3d_image_writes`*. +should also add a preprocessor `#define` called *cl_khr_3d_image_writes*. A kernel can now use this preprocessor `#define` to do something like: [source,opencl_c] @@ -226,7 +226,7 @@ typedef return_type where `TAG` can be `KHR`, `EXT` or `vendor-specific`. -Consider, for example, the *cl_khr_gl_sharing* extension. +Consider, for example, the {cl_khr_gl_sharing_EXT} extension. This extension would add the following to cl_gl_ext.h: [source,opencl] diff --git a/ext/quick_reference.asciidoc b/ext/quick_reference.asciidoc index 194c6df9d..a040f1333 100644 --- a/ext/quick_reference.asciidoc +++ b/ext/quick_reference.asciidoc @@ -24,287 +24,299 @@ Language Specifications. | Brief Description | Status -| [[cl_khr_3d_image_writes]] link:{APISpecURL}#cl_khr_3d_image_writes[`cl_khr_3d_image_writes`] +| [[cl_khr_3d_image_writes]] link:{APISpecURL}#cl_khr_3d_image_writes[{cl_khr_3d_image_writes_EXT}] | Write to 3D images | Core Feature in OpenCL 2.0 -| [[cl_khr_async_work_group_copy_fence]] link:{APISpecURL}#cl_khr_async_work_group_copy_fence[`cl_khr_async_work_group_copy_fence`] +| [[cl_khr_async_work_group_copy_fence]] link:{APISpecURL}#cl_khr_async_work_group_copy_fence[{cl_khr_async_work_group_copy_fence_EXT}] | Asynchronous Copy Fences | Extension -| [[cl_khr_byte_addressable_store]] link:{APISpecURL}#cl_khr_byte_addressable_store[`cl_khr_byte_addressable_store`] +| [[cl_khr_byte_addressable_store]] link:{APISpecURL}#cl_khr_byte_addressable_store[{cl_khr_byte_addressable_store_EXT}] | Read and write from 8-bit and 16-bit pointers | Core Feature in OpenCL 1.1 -| [[cl_khr_command_buffer]] link:{APISpecURL}#cl_khr_command_buffer[`cl_khr_command_buffer`] +| [[cl_khr_command_buffer]] link:{APISpecURL}#cl_khr_command_buffer[{cl_khr_command_buffer_EXT}] | Record and Replay Commands | Provisional Extension -| [[cl_khr_command_buffer_multi_device]] link:{APISpecURL}#cl_khr_command_buffer_multi_device[`cl_khr_command_buffer_multi_device`] +| [[cl_khr_command_buffer_multi_device]] link:{APISpecURL}#cl_khr_command_buffer_multi_device[{cl_khr_command_buffer_multi_device_EXT}] | Allow a command-buffer to contain commands targeting different devices | Provisional Extension -| [[cl_khr_command_buffer_mutable_dispatch]] link:{APISpecURL}#cl_khr_command_buffer_mutable_dispatch[`cl_khr_command_buffer_mutable_dispatch`] +| [[cl_khr_command_buffer_mutable_dispatch]] link:{APISpecURL}#cl_khr_command_buffer_mutable_dispatch[{cl_khr_command_buffer_mutable_dispatch_EXT}] | Modify kernel execution commands between enqueues of a command-buffer | Provisional Extension -| [[cl_khr_create_command_queue]] link:{APISpecURL}#cl_khr_create_command_queue[`cl_khr_create_command_queue`] +| [[cl_khr_create_command_queue]] link:{APISpecURL}#cl_khr_create_command_queue[{cl_khr_create_command_queue_EXT}] | API to Create Command-Queues with Properties | Core Feature in OpenCL 2.0 -| [[cl_khr_d3d10_sharing]] link:{APISpecURL}#cl_khr_d3d10_sharing[`cl_khr_d3d10_sharing`] +| [[cl_khr_d3d10_sharing]] link:{APISpecURL}#cl_khr_d3d10_sharing[{cl_khr_d3d10_sharing_EXT}] | Share Direct3D 10 Buffers and Textures with OpenCL | Extension -| [[cl_khr_d3d11_sharing]] link:{APISpecURL}#cl_khr_d3d11_sharing[`cl_khr_d3d11_sharing`] +| [[cl_khr_d3d11_sharing]] link:{APISpecURL}#cl_khr_d3d11_sharing[{cl_khr_d3d11_sharing_EXT}] | Share Direct3D 11 Buffers and Textures with OpenCL | Extension -| [[cl_khr_depth_images]] link:{APISpecURL}#cl_khr_depth_images[`cl_khr_depth_images`] +| [[cl_khr_depth_images]] link:{APISpecURL}#cl_khr_depth_images[{cl_khr_depth_images_EXT}] | Single Channel Depth Images | Core Feature in OpenCL 2.0 -| [[cl_khr_device_enqueue_local_arg_types]] link:{APISpecURL}#cl_khr_device_enqueue_local_arg_types[`cl_khr_device_enqueue_local_arg_types`] +| [[cl_khr_device_enqueue_local_arg_types]] link:{APISpecURL}#cl_khr_device_enqueue_local_arg_types[{cl_khr_device_enqueue_local_arg_types_EXT}] | Pass Non-Void Local Pointers to Child Kernels | Extension -| [[cl_khr_device_uuid]] link:{APISpecURL}#cl_khr_device_uuid[`cl_khr_device_uuid`] +| [[cl_khr_device_uuid]] link:{APISpecURL}#cl_khr_device_uuid[{cl_khr_device_uuid_EXT}] | Unique Device and Driver Identifier Queries | Extension -| [[cl_khr_dx9_media_sharing]] link:{APISpecURL}#cl_khr_dx9_media_sharing[`cl_khr_dx9_media_sharing`] +| [[cl_khr_dx9_media_sharing]] link:{APISpecURL}#cl_khr_dx9_media_sharing[{cl_khr_dx9_media_sharing_EXT}] | Share DirectX 9 Media Surfaces with OpenCL | Extension -| [[cl_khr_egl_event]] link:{APISpecURL}#cl_khr_egl_event[`cl_khr_egl_event`] +| [[cl_khr_egl_event]] link:{APISpecURL}#cl_khr_egl_event[{cl_khr_egl_event_EXT}] | Share EGL Sync Objects with OpenCL | Extension -| [[cl_khr_egl_image]] link:{APISpecURL}#cl_khr_egl_image[`cl_khr_egl_image`] +| [[cl_khr_egl_image]] link:{APISpecURL}#cl_khr_egl_image[{cl_khr_egl_image_EXT}] | Share EGL Images with OpenCL | Extension -| [[cl_khr_extended_async_copies]] link:{APISpecURL}#cl_khr_extended_async_copies[`cl_khr_extended_async_copies`] +| [[cl_khr_extended_async_copies]] link:{APISpecURL}#cl_khr_extended_async_copies[{cl_khr_extended_async_copies_EXT}] | 2D and 3D Async Copies | Extension -| [[cl_khr_extended_bit_ops]] link:{APISpecURL}#cl_khr_extended_bit_ops[`cl_khr_extended_bit_ops`] +| [[cl_khr_extended_bit_ops]] link:{APISpecURL}#cl_khr_extended_bit_ops[{cl_khr_extended_bit_ops_EXT}] | Bit Insert, Extract, and Reverse Operations | Extension -| [[cl_khr_extended_versioning]] link:{APISpecURL}#cl_khr_extended_versioning[`cl_khr_extended_versioning`] +| [[cl_khr_extended_versioning]] link:{APISpecURL}#cl_khr_extended_versioning[{cl_khr_extended_versioning_EXT}] | Extend versioning of platform, devices, extensions, etc. | Core Feature in OpenCL 3.0 (with minor changes) -| [[cl_khr_external_memory]] link:{APISpecURL}#cl_khr_external_memory[`cl_khr_external_memory`] +| [[cl_khr_external_memory]] link:{APISpecURL}#cl_khr_external_memory[{cl_khr_external_memory_EXT}] | Common Functionality for External Memory Sharing | Provisional Extension -| [[cl_khr_external_memory_dma_buf]] link:{APISpecURL}#cl_khr_external_memory[`cl_khr_external_memory_dma_buf`] +| [[cl_khr_external_memory_dma_buf]] link:{APISpecURL}#cl_khr_external_memory[{cl_khr_external_memory_dma_buf_EXT}] | dma_buf External Memory Handles | Provisional Extension -| [[cl_khr_external_memory_dx]] link:{APISpecURL}#cl_khr_external_memory[`cl_khr_external_memory_dx`] +| [[cl_khr_external_memory_dx]] link:{APISpecURL}#cl_khr_external_memory[{cl_khr_external_memory_dx_EXT}] | Direct3D 11 and 12 External Memory Handles | Provisional Extension -| [[cl_khr_external_memory_opaque_fd]] link:{APISpecURL}#cl_khr_external_memory[`cl_khr_external_memory_opaque_fd`] +| [[cl_khr_external_memory_opaque_fd]] link:{APISpecURL}#cl_khr_external_memory[{cl_khr_external_memory_opaque_fd_EXT}] | Opaque File Descriptor External Memory Handles | Provisional Extension -| [[cl_khr_external_memory_win32]] link:{APISpecURL}#cl_khr_external_memory[`cl_khr_external_memory_win32`] +| [[cl_khr_external_memory_win32]] link:{APISpecURL}#cl_khr_external_memory[{cl_khr_external_memory_win32_EXT}] | NT Handle External Memory Handles | Provisional Extension -| [[cl_khr_expect_assume]] link:{APISpecURL}#cl_khr_expect_assume[`cl_khr_expect_assume`] +| [[cl_khr_expect_assume]] link:{APISpecURL}#cl_khr_expect_assume[{cl_khr_expect_assume_EXT}] | Kernel Optimization Hints | Extension -| [[cl_khr_external_semaphore]] link:{APISpecURL}#cl_khr_external_semaphore[`cl_khr_external_semaphore`] +| [[cl_khr_external_semaphore]] link:{APISpecURL}#cl_khr_external_semaphore[{cl_khr_external_semaphore_EXT}] | Common Functionality for External Semaphore Sharing | Provisional Extension -| [[cl_khr_external_semaphore_dx_fence]] link:{APISpecURL}#cl_khr_external_semaphore[`cl_khr_external_semaphore_dx_fence`] +| [[cl_khr_external_semaphore_dx_fence]] link:{APISpecURL}#cl_khr_external_semaphore[{cl_khr_external_semaphore_dx_fence_EXT}] | Direct3D 12 External Semaphore Handles | Provisional Extension -| [[cl_khr_external_semaphore_opaque_fd]] link:{APISpecURL}#cl_khr_external_semaphore[`cl_khr_external_semaphore_opaque_fd`] +| [[cl_khr_external_semaphore_opaque_fd]] link:{APISpecURL}#cl_khr_external_semaphore[{cl_khr_external_semaphore_opaque_fd_EXT}] | Opaque File Descriptor External Semaphore Handles | Provisional Extension -| [[cl_khr_external_semaphore_sync_fd]] link:{APISpecURL}#cl_khr_external_semaphore[`cl_khr_external_semaphore_sync_fd`] +| [[cl_khr_external_semaphore_sync_fd]] link:{APISpecURL}#cl_khr_external_semaphore[{cl_khr_external_semaphore_sync_fd_EXT}] | Sync FD External Semaphore Handles | Provisional Extension -| [[cl_khr_external_semaphore_win32]] link:{APISpecURL}#cl_khr_external_semaphore[`cl_khr_external_semaphore_win32`] +| [[cl_khr_external_semaphore_win32]] link:{APISpecURL}#cl_khr_external_semaphore[{cl_khr_external_semaphore_win32_EXT}] | NT Handle External Semaphore Handles | Provisional Extension -| [[cl_khr_fp16]] link:{APISpecURL}#cl_khr_fp16[`cl_khr_fp16`] +| [[cl_khr_fp16]] link:{APISpecURL}#cl_khr_fp16[{cl_khr_fp16_EXT}] | Operations on 16-bit Floating-Point Values | Extension -| [[cl_khr_fp64]] link:{APISpecURL}#cl_khr_fp64[`cl_khr_fp64`] +| [[cl_khr_fp64]] link:{APISpecURL}#cl_khr_fp64[{cl_khr_fp64_EXT}] | Operations on 64-bit Floating-Point Values | Optional Core Feature in OpenCL 1.2 -| [[cl_khr_gl_depth_images]] link:{APISpecURL}#cl_khr_gl_depth_images[`cl_khr_gl_depth_images`] +| [[cl_khr_gl_depth_images]] link:{APISpecURL}#cl_khr_gl_depth_images[{cl_khr_gl_depth_images_EXT}] | Share OpenGL Depth Images with OpenCL | Extension -| [[cl_khr_gl_event]] link:{APISpecURL}#cl_khr_gl_event[`cl_khr_gl_event`] +| [[cl_khr_gl_event]] link:{APISpecURL}#cl_khr_gl_event[{cl_khr_gl_event_EXT}] | Share OpenGL Fence Sync Objects with OpenCL | Extension -| [[cl_khr_gl_msaa_sharing]] link:{APISpecURL}#cl_khr_gl_msaa_sharing[`cl_khr_gl_msaa_sharing`] +| [[cl_khr_gl_msaa_sharing]] link:{APISpecURL}#cl_khr_gl_msaa_sharing[{cl_khr_gl_msaa_sharing_EXT}] | Share OpenGL MSAA Textures with OpenCL | Extension -| [[cl_khr_gl_sharing]] link:{APISpecURL}#cl_khr_gl_sharing[`cl_khr_gl_sharing`] +| [[cl_khr_gl_sharing]] link:{APISpecURL}#cl_khr_gl_sharing[{cl_khr_gl_sharing_EXT}] | Sharing OpenGL Buffers and Textures with OpenCL | Extension -| [[cl_khr_global_int32_base_atomics]] link:{APISpecURL}#cl_khr_int32_atomics[`cl_khr_global_int32_base_atomics`] +| [[cl_khr_global_int32_base_atomics]] link:{APISpecURL}#cl_khr_int32_atomics[{cl_khr_global_int32_base_atomics_EXT}] | Basic Atomic Operations on 32-bit Integers in Global Memory | Core Feature in OpenCL 1.1 -| [[cl_khr_global_int32_extended_atomics]] link:{APISpecURL}#cl_khr_int32_atomics[`cl_khr_global_int32_extended_atomics`] +| [[cl_khr_global_int32_extended_atomics]] link:{APISpecURL}#cl_khr_int32_atomics[{cl_khr_global_int32_extended_atomics_EXT}] | Extended Atomic Operations on 32-bit Integers in Global Memory | Core Feature in OpenCL 1.1 -| [[cl_khr_icd]] link:{APISpecURL}#cl_khr_icd[`cl_khr_icd`] +| [[cl_khr_icd]] link:{APISpecURL}#cl_khr_icd[{cl_khr_icd_EXT}] | Installable Client Drivers | Extension -| [[cl_khr_il_program]] link:{APISpecURL}#cl_khr_il_program[`cl_khr_il_program`] +| [[cl_khr_il_program]] link:{APISpecURL}#cl_khr_il_program[{cl_khr_il_program_EXT}] | Support for Intermediate Language (IL) Programs (SPIR-V) | Core Feature in OpenCL 2.1 -| [[cl_khr_image2d_from_buffer]] link:{APISpecURL}#cl_khr_image2d_from_buffer[`cl_khr_image2d_from_buffer`] +| [[cl_khr_image2d_from_buffer]] link:{APISpecURL}#cl_khr_image2d_from_buffer[{cl_khr_image2d_from_buffer_EXT}] | Create 2D Images from Buffers | Core Feature in OpenCL 2.0 -| [[cl_khr_initialize_memory]] link:{APISpecURL}#cl_khr_initialize_memory[`cl_khr_initialize_memory`] +| [[cl_khr_initialize_memory]] link:{APISpecURL}#cl_khr_initialize_memory[{cl_khr_initialize_memory_EXT}] | Initialize Local and Private Memory on Allocation | Extension -| [[cl_khr_int64_base_atomics]] link:{APISpecURL}#cl_khr_int64_atomics[`cl_khr_int64_base_atomics`] +| [[cl_khr_int64_base_atomics]] link:{APISpecURL}#cl_khr_int64_atomics[{cl_khr_int64_base_atomics_EXT}] | Basic Atomic Operations on 64-bit Integers in Global and Local Memory | Extension -| [[cl_khr_int64_extended_atomics]] link:{APISpecURL}#cl_khr_int64_atomics[`cl_khr_int64_extended_atomics`] +| [[cl_khr_int64_extended_atomics]] link:{APISpecURL}#cl_khr_int64_atomics[{cl_khr_int64_extended_atomics_EXT}] | Extended Atomic Operations on 64-bit Integers in Global and Local Memory | Extension -| [[cl_khr_local_int32_base_atomics]] link:{APISpecURL}#cl_khr_int32_atomics[`cl_khr_local_int32_base_atomics`] +| [[cl_khr_local_int32_base_atomics]] link:{APISpecURL}#cl_khr_int32_atomics[{cl_khr_local_int32_base_atomics_EXT}] | Basic Atomic Operations on 32-bit Integers in Local Memory | Core Feature in OpenCL 1.1 -| [[cl_khr_local_int32_extended_atomics]] link:{APISpecURL}#cl_khr_int32_atomics[`cl_khr_local_int32_extended_atomics`] +| [[cl_khr_local_int32_extended_atomics]] link:{APISpecURL}#cl_khr_int32_atomics[{cl_khr_local_int32_extended_atomics_EXT}] | Extended Atomic Operations on 32-bit Integers in Local Memory | Core Feature in OpenCL 1.1 -| [[cl_khr_integer_dot_product]] link:{APISpecURL}#cl_khr_integer_dot_product[`cl_khr_integer_dot_product`] +| [[cl_khr_integer_dot_product]] link:{APISpecURL}#cl_khr_integer_dot_product[{cl_khr_integer_dot_product_EXT}] | Integer dot product operations | Extension -| [[cl_khr_kernel_clock]] link:{APISpecURL}#cl_khr_kernel_clock[`cl_khr_kernel_clock`] +| [[cl_khr_kernel_clock]] link:{APISpecURL}#cl_khr_kernel_clock[{cl_khr_kernel_clock_EXT}] | Sample Clock Values Within a Kernel | Extension -| [[cl_khr_mipmap_image]] link:{APISpecURL}#cl_khr_mipmap_image[`cl_khr_mipmap_image`] +| [[cl_khr_mipmap_image]] link:{APISpecURL}#cl_khr_mipmap_image[{cl_khr_mipmap_image_EXT}] | Create and Use Images with Mipmaps | Extension -| [[cl_khr_pci_bus_info]] link:{APISpecURL}#cl_khr_pci_bus_info[`cl_khr_pci_bus_info`] +| [[cl_khr_pci_bus_info]] link:{APISpecURL}#cl_khr_pci_bus_info[{cl_khr_pci_bus_info_EXT}] | Query PCI Bus Information for an OpenCL Device | Extension -| [[cl_khr_priority_hints]] link:{APISpecURL}#cl_khr_priority_hints[`cl_khr_priority_hints`] +| [[cl_khr_priority_hints]] link:{APISpecURL}#cl_khr_priority_hints[{cl_khr_priority_hints_EXT}] | Create Command-Queues with Different Priorities | Extension -| [[cl_khr_select_fprounding_mode]] link:{APISpecURL}#cl_khr_select_fprounding_mode[`cl_khr_select_fprounding_mode`] +| [[cl_khr_select_fprounding_mode]] link:{APISpecURL}#cl_khr_select_fprounding_mode[{cl_khr_select_fprounding_mode_EXT}] | Set the Current Kernel Rounding Mode | DEPRECATED -| [[cl_khr_semaphore]] link:{APISpecURL}#cl_khr_semaphore[`cl_khr_semaphore`] +| [[cl_khr_semaphore]] link:{APISpecURL}#cl_khr_semaphore[{cl_khr_semaphore_EXT}] | Semaphore Synchronization Primitives | Provisional Extension -| [[cl_khr_spir]] link:{APISpecURL}#cl_khr_spir[`cl_khr_spir`] +| [[cl_khr_spir]] link:{APISpecURL}#cl_khr_spir[{cl_khr_spir_EXT}] | Standard Portable Intermediate Representation Programs | Extension, Superseded by IL Programs / SPIR-V -| [[cl_khr_spirv_extended_debug_info]] link:{APISpecURL}#cl_khr_spirv_extended_debug_info[`cl_khr_spirv_extended_debug_info`] +| [[cl_khr_spirv_extended_debug_info]] link:{APISpecURL}#cl_khr_spirv_extended_debug_info[{cl_khr_spirv_extended_debug_info_EXT}] | Allows Use of the SPIR-V `OpenCL.DebugInfo.100` Extended Instruction Set | Extension -| [[cl_khr_spirv_linkonce_odr]] link:{APISpecURL}#cl_khr_spirv_linkonce_odr[`cl_khr_spirv_linkonce_odr`] +| [[cl_khr_spirv_linkonce_odr]] link:{APISpecURL}#cl_khr_spirv_linkonce_odr[{cl_khr_spirv_linkonce_odr_EXT}] | Allows Use of the SPIR-V `SPV_KHR_linkonce_odr` Extension | Extension -| [[cl_khr_spirv_no_integer_wrap_decoration]] link:{APISpecURL}#cl_khr_spirv_no_integer_wrap_decoration[`cl_khr_spirv_no_integer_wrap_decoration`] +| [[cl_khr_spirv_no_integer_wrap_decoration]] link:{APISpecURL}#cl_khr_spirv_no_integer_wrap_decoration[{cl_khr_spirv_no_integer_wrap_decoration_EXT}] | Allows Use of the SPIR-V `SPV_KHR_no_integer_wrap_decoration` Extension | Extension -| [[cl_khr_srgb_image_writes]] link:{APISpecURL}#cl_khr_srgb_image_writes[`cl_khr_srgb_image_writes`] +| [[cl_khr_spirv_extended_debug_info]] link:{APISpecURL}#cl_khr_spirv_extended_debug_info[{cl_khr_spirv_extended_debug_info_EXT}] +| Allows Use of the SPIR-V `OpenCL.DebugInfo.100` Extended Instruction Set +| Extension + +| [[cl_khr_spirv_linkonce_odr]] link:{APISpecURL}#cl_khr_spirv_linkonce_odr[{cl_khr_spirv_linkonce_odr_EXT}] +| Allows Use of the SPIR-V `SPV_KHR_linkonce_odr` Extension +| Extension + +| [[cl_khr_spirv_no_integer_wrap_decoration]] link:{APISpecURL}#cl_khr_spirv_no_integer_wrap_decoration[{cl_khr_spirv_no_integer_wrap_decoration_EXT}] +| Allows Use of the SPIR-V `SPV_KHR_no_integer_wrap_decoration` Extension +| Extension + +| [[cl_khr_srgb_image_writes]] link:{APISpecURL}#cl_khr_srgb_image_writes[{cl_khr_srgb_image_writes_EXT}] | Write to sRGB Images | Extension -| [[cl_khr_subgroups]] link:{APISpecURL}#cl_khr_subgroups[`cl_khr_subgroups`] +| [[cl_khr_subgroups]] link:{APISpecURL}#cl_khr_subgroups[{cl_khr_subgroups_EXT}] | Sub-Groupings of Work Items | Core Feature in OpenCL 2.1 (with minor changes) -| [[cl_khr_subgroup_ballot]] link:{APISpecURL}#cl_khr_subgroup_ballot[`cl_khr_subgroup_ballot`] +| [[cl_khr_subgroup_ballot]] link:{APISpecURL}#cl_khr_subgroup_ballot[{cl_khr_subgroup_ballot_EXT}] | Exchange Ballots Among Sub-Groupings of Work Items | Extension -| [[cl_khr_subgroup_clustered_reduce]] link:{APISpecURL}#cl_khr_subgroup_clustered_reduce[`cl_khr_subgroup_clustered_reduce`] +| [[cl_khr_subgroup_clustered_reduce]] link:{APISpecURL}#cl_khr_subgroup_clustered_reduce[{cl_khr_subgroup_clustered_reduce_EXT}] | Clustered Reductions for Sub-Groupings of Work Items | Extension -| [[cl_khr_subgroup_extended_types]] link:{APISpecURL}#cl_khr_subgroup_extended_types[`cl_khr_subgroup_extended_types`] +| [[cl_khr_subgroup_extended_types]] link:{APISpecURL}#cl_khr_subgroup_extended_types[{cl_khr_subgroup_extended_types_EXT}] | Additional Type Support for Sub-group Functions | Extension -| [[cl_khr_subgroup_named_barrier]] link:{APISpecURL}#cl_khr_subgroup_named_barrier[`cl_khr_subgroup_named_barrier`] +| [[cl_khr_subgroup_named_barrier]] link:{APISpecURL}#cl_khr_subgroup_named_barrier[{cl_khr_subgroup_named_barrier_EXT}] | Barriers for Subsets of a Work-group | Extension -| [[cl_khr_subgroup_non_uniform_arithmetic]] link:{APISpecURL}#cl_khr_subgroup_non_uniform_arithmetic[`cl_khr_subgroup_non_uniform_arithmetic`] +| [[cl_khr_subgroup_non_uniform_arithmetic]] link:{APISpecURL}#cl_khr_subgroup_non_uniform_arithmetic[{cl_khr_subgroup_non_uniform_arithmetic_EXT}] | Sub-group Arithmetic Functions in Non-Uniform Control Flow | Extension -| [[cl_khr_subgroup_non_uniform_vote]] link:{APISpecURL}#cl_khr_subgroup_non_uniform_vote[`cl_khr_subgroup_non_uniform_vote`] +| [[cl_khr_subgroup_non_uniform_vote]] link:{APISpecURL}#cl_khr_subgroup_non_uniform_vote[{cl_khr_subgroup_non_uniform_vote_EXT}] | Hold Votes Among Sub-Groupings of Work Items | Extension -| [[cl_khr_subgroup_rotate]] link:{APISpecURL}#cl_khr_subgroup_rotate[`cl_khr_subgroup_rotate`] +| [[cl_khr_subgroup_rotate]] link:{APISpecURL}#cl_khr_subgroup_rotate[{cl_khr_subgroup_rotate_EXT}] | Rotation Among Sub-Groupings of Work Items | Extension -| [[cl_khr_subgroup_shuffle]] link:{APISpecURL}#cl_khr_subgroup_shuffle[`cl_khr_subgroup_shuffle`] +| [[cl_khr_subgroup_shuffle]] link:{APISpecURL}#cl_khr_subgroup_shuffle[{cl_khr_subgroup_shuffle_EXT}] | General-Purpose Shuffles Among Sub-Groupings of Work Items | Extension -| [[cl_khr_subgroup_shuffle_relative]] link:{APISpecURL}#cl_khr_subgroup_shuffle_relative[`cl_khr_subgroup_shuffle_relative`] +| [[cl_khr_subgroup_shuffle_relative]] link:{APISpecURL}#cl_khr_subgroup_shuffle_relative[{cl_khr_subgroup_shuffle_relative_EXT}] | Relative Shuffles Among Sub-Groupings of Work Items | Extension -| [[cl_khr_suggested_local_work_size]] link:{APISpecURL}#cl_khr_suggested_local_work_size[`cl_khr_suggested_local_work_size`] +| [[cl_khr_suggested_local_work_size]] link:{APISpecURL}#cl_khr_suggested_local_work_size[{cl_khr_suggested_local_work_size_EXT}] | Query a Suggested Local Work Size | Extension -| [[cl_khr_terminate_context]] link:{APISpecURL}#cl_khr_terminate_context[`cl_khr_terminate_context`] +| [[cl_khr_terminate_context]] link:{APISpecURL}#cl_khr_terminate_context[{cl_khr_terminate_context_EXT}] | Terminate an OpenCL Context | Extension -| [[cl_khr_throttle_hints]] link:{APISpecURL}#cl_khr_throttle_hints[`cl_khr_throttle_hints`] +| [[cl_khr_throttle_hints]] link:{APISpecURL}#cl_khr_throttle_hints[{cl_khr_throttle_hints_EXT}] | Create Command-Queues with Different Throttle Policies | Extension -| [[cl_khr_work_group_uniform_arithmetic]] link:{APISpecURL}#cl_khr_work_group_uniform_arithmetic[`cl_khr_work_group_uniform_arithmetic`] +| [[cl_khr_work_group_uniform_arithmetic]] link:{APISpecURL}#cl_khr_work_group_uniform_arithmetic[{cl_khr_work_group_uniform_arithmetic_EXT}] | Work-group Uniform Arithmetic | Extension diff --git a/ext/to_core_features.asciidoc b/ext/to_core_features.asciidoc index f6b6d5baf..58c799fbc 100644 --- a/ext/to_core_features.asciidoc +++ b/ext/to_core_features.asciidoc @@ -7,57 +7,57 @@ === For OpenCL 1.1: -//* The OpenCL KHR extension *cl_khr_d3d10_sharing* has been added. -//* The OpenCL KHR extension *cl_khr_gl_event* has been added. +//* The OpenCL KHR extension {cl_khr_d3d10_sharing_EXT} has been added. +//* The OpenCL KHR extension {cl_khr_gl_event_EXT} has been added. -* The functionality previously described by *cl_khr_byte_addressable_store* is now part of the core feature set. -* The functionality previously described by *cl_khr_global_int32_base_atomics*, *cl_khr_global_int32_extended_atomics*, *cl_khr_local_int32_base_atomics*, and *cl_khr_local_int32_extended_atomics* is now part of the core feature set. +* The functionality previously described by {cl_khr_byte_addressable_store_EXT} is now part of the core feature set. +* The functionality previously described by {cl_khr_global_int32_base_atomics_EXT}, {cl_khr_global_int32_extended_atomics_EXT}, {cl_khr_local_int32_base_atomics_EXT}, and {cl_khr_local_int32_extended_atomics_EXT} is now part of the core feature set. === For OpenCL 1.2: -//* The OpenCL KHR extension *cl_khr_d3d11_sharing* has been added. -//* The OpenCL KHR extension *cl_khr_depth_images* has been added. -//* The OpenCL KHR extension *cl_khr_dx9_media_sharing* has been added. -//* The OpenCL KHR extension *cl_khr_egl_event* has been added. -//* The OpenCL KHR extension *cl_khr_egl_image* has been added. -//* The OpenCL KHR extension *cl_khr_gl_depth_images* has been added. -//* The OpenCL KHR extension *cl_khr_gl_msaa_sharing* has been added. -//* The OpenCL KHR extension *cl_khr_il_program* has been added. -//* The OpenCL KHR extension *cl_khr_image2d_from_buffer* has been added. -//* The OpenCL KHR extension *cl_khr_initialize_memory* has been added. -//* The OpenCL KHR extension *cl_khr_spir* has been added. -//* The OpenCL KHR extension *cl_khr_terminate_context* has been added. - -* The functionality previously described by *cl_khr_fp64* is now an optional core feature. +//* The OpenCL KHR extension {cl_khr_d3d11_sharing_EXT} has been added. +//* The OpenCL KHR extension {cl_khr_depth_images_EXT} has been added. +//* The OpenCL KHR extension {cl_khr_dx9_media_sharing_EXT} has been added. +//* The OpenCL KHR extension {cl_khr_egl_event_EXT} has been added. +//* The OpenCL KHR extension {cl_khr_egl_image_EXT} has been added. +//* The OpenCL KHR extension {cl_khr_gl_depth_images_EXT} has been added. +//* The OpenCL KHR extension {cl_khr_gl_msaa_sharing_EXT} has been added. +//* The OpenCL KHR extension {cl_khr_il_program_EXT} has been added. +//* The OpenCL KHR extension {cl_khr_image2d_from_buffer_EXT} has been added. +//* The OpenCL KHR extension {cl_khr_initialize_memory_EXT} has been added. +//* The OpenCL KHR extension {cl_khr_spir_EXT} has been added. +//* The OpenCL KHR extension {cl_khr_terminate_context_EXT} has been added. + +* The functionality previously described by {cl_khr_fp64_EXT} is now an optional core feature. === For OpenCL 2.0: -//* The OpenCL KHR extension *cl_khr_device_enqueue_local_arg_types* has been added. -//* The OpenCL KHR extensions *cl_khr_mipmap_image* and *cl_khr_mipmap_image_writes* have been added. -//* The OpenCL KHR extension *cl_khr_subgroups* has been added. +//* The OpenCL KHR extension {cl_khr_device_enqueue_local_arg_types_EXT} has been added. +//* The OpenCL KHR extensions {cl_khr_mipmap_image_EXT} and {cl_khr_mipmap_image_writes_EXT} have been added. +//* The OpenCL KHR extension {cl_khr_subgroups_EXT} has been added. -* The functionality described by *cl_khr_3d_image_writes* is part of the core feature set. -* The functionality described by *cl_khr_create_command_queue* is part of the core feature set. -* The functionality described by *cl_khr_depth_images* is now part of the core feature set. -* The functionality described by *cl_khr_image2d_from_buffer* is now part of the core feature set. +* The functionality described by {cl_khr_3d_image_writes_EXT} is part of the core feature set. +* The functionality described by {cl_khr_create_command_queue_EXT} is part of the core feature set. +* The functionality described by {cl_khr_depth_images_EXT} is now part of the core feature set. +* The functionality described by {cl_khr_image2d_from_buffer_EXT} is now part of the core feature set. === For OpenCL 2.1: -//* The OpenCL KHR extension *cl_khr_priority_hints* has been added. -//* The OpenCL KHR extension *cl_khr_throttle_hints* has been added. +//* The OpenCL KHR extension {cl_khr_priority_hints_EXT} has been added. +//* The OpenCL KHR extension {cl_khr_throttle_hints_EXT} has been added. // I recall having this discussion but I don't see this extension mentioned anywhere // in the OpenCL 2.1 spec, and it would be a language change anyhow. -//* The functionality described in *cl_khr_device_enqueue_local_arg_types* is now part of the core feature set. +//* The functionality described in {cl_khr_device_enqueue_local_arg_types_EXT} is now part of the core feature set. -* The functionality described by *cl_khr_il_program* is now part of the core feature set. -* The API functionality described by *cl_khr_subgroups* is now part of the core API feature set, but the built-in functions described by *cl_khr_subgroups* must still be accessed as an extension to the OpenCL 2.0 C Language specification. +* The functionality described by {cl_khr_il_program_EXT} is now part of the core feature set. +* The API functionality described by {cl_khr_subgroups_EXT} is now part of the core API feature set, but the built-in functions described by {cl_khr_subgroups_EXT} must still be accessed as an extension to the OpenCL 2.0 C Language specification. //=== For OpenCL 2.2: // -//* The OpenCL KHR extension *cl_khr_subgroup_named_barrier* has been added. +//* The OpenCL KHR extension {cl_khr_subgroup_named_barrier_EXT} has been added. === For OpenCL 3.0: -* The API functionality described by *cl_khr_extended_versioning* is now part of the core API feature set, with minor modifications. -* The built-in functions described by *cl_khr_subgroups* are now supported in OpenCL C 3.0 when the {opencl_c_subgroups} feature is supported. \ No newline at end of file +* The API functionality described by {cl_khr_extended_versioning_EXT} is now part of the core API feature set, with minor modifications. +* The built-in functions described by {cl_khr_subgroups_EXT} are now supported in OpenCL C 3.0 when the {opencl_c_subgroups} feature is supported. \ No newline at end of file diff --git a/scripts/clconventions.py b/scripts/clconventions.py index 2e601519b..c561eb73d 100644 --- a/scripts/clconventions.py +++ b/scripts/clconventions.py @@ -209,6 +209,7 @@ def extra_refpage_headers(self): 'include::{config}/opencl.asciidoc[]\n' + \ 'include::{config}/version-full-links.asciidoc[]\n' + \ 'include::{generated}/api/api-dictionary-no-links.asciidoc[]\n' + \ + 'include::{generated}/api/ext-dictionary-no-links.asciidoc[]\n' + \ 'include::{cspec}/feature-dictionary.asciidoc[]\n' + \ 'include::{apispec}/footnotes.asciidoc[]\n' + \ 'include::{cspec}/footnotes.asciidoc[]\n' diff --git a/scripts/gen_dictionaries.py b/scripts/gen_dictionaries.py index 045646c4d..142fe55a4 100755 --- a/scripts/gen_dictionaries.py +++ b/scripts/gen_dictionaries.py @@ -41,9 +41,13 @@ def GetFooter(): args = parser.parse_args() - linkFileName = args.directory + '/api-dictionary.asciidoc' - nolinkFileName = args.directory + '/api-dictionary-no-links.asciidoc' - typeFileName = args.directory + '/api-types.txt' + apiLinkFileName = args.directory + '/api-dictionary.asciidoc' + apiNoLinkFileName = args.directory + '/api-dictionary-no-links.asciidoc' + apiTypeFileName = args.directory + '/api-types.txt' + + extNoLinkFileName = args.directory + '/ext-dictionary-no-links.asciidoc' + extFullLinkFileName = args.directory + '/ext-dictionary-full-links.asciidoc' + extLocalLinkFileName = args.directory + '/ext-dictionary-local-links.asciidoc' specpath = args.registry #specpath = "https://raw.githubusercontent.com/KhronosGroup/OpenCL-Registry/main/xml/cl.xml" @@ -52,11 +56,18 @@ def GetFooter(): spec = parse_xml(specpath) - linkFile = open(linkFileName, 'w') - nolinkFile = open(nolinkFileName, 'w') - linkFile.write( GetHeader() ) - nolinkFile.write( GetHeader() ) - typeFile = open(typeFileName, 'w') + apiLinkFile = open(apiLinkFileName, 'w') + apiNoLinkFile = open(apiNoLinkFileName, 'w') + apiLinkFile.write( GetHeader() ) + apiNoLinkFile.write( GetHeader() ) + apiTypeFile = open(apiTypeFileName, 'w') + + extNoLinkFile = open(extNoLinkFileName, 'w') + extNoLinkFile.write( GetHeader() ) + extFullLinkFile = open(extFullLinkFileName, 'w') + extFullLinkFile.write( GetHeader() ) + extLocalLinkFile = open(extLocalLinkFileName, 'w') + extLocalLinkFile.write( GetHeader() ) # Generate the API functions dictionaries: @@ -73,18 +84,18 @@ def GetFooter(): # // clEnqueueNDRangeKernel # :clEnqueueNDRangeKernel_label: pass:q[*clEnqueueNDRangeKernel*] # :clEnqueueNDRangeKernel: <> - linkFile.write('// ' + name + '\n') - linkFile.write(':' + name + '_label: pass:q[*' + name + '*]\n') - linkFile.write(':' + name + ': <<' + name + ',{' + name + '_label}>>\n') - linkFile.write('\n') + apiLinkFile.write('// ' + name + '\n') + apiLinkFile.write(':' + name + '_label: pass:q[*' + name + '*]\n') + apiLinkFile.write(':' + name + ': <<' + name + ',{' + name + '_label}>>\n') + apiLinkFile.write('\n') # Example without link: # # // clEnqueueNDRangeKernel # :clEnqueueNDRangeKernel: pass:q[*clEnqueueNDRangeKernel*] - nolinkFile.write('// ' + name + '\n') - nolinkFile.write(':' + name + ': pass:q[*' + name + '*]\n') - nolinkFile.write('\n') + apiNoLinkFile.write('// ' + name + '\n') + apiNoLinkFile.write(':' + name + ': pass:q[*' + name + '*]\n') + apiNoLinkFile.write('\n') numberOfFuncs = numberOfFuncs + 1 @@ -98,13 +109,13 @@ def GetFooter(): # # // clGetGLObjectInfo # :clGetGLObjectInfo: pass:q[*clGetGLObjectInfo*] - linkFile.write('// ' + name + '\n') - linkFile.write(':' + name + ': pass:q[*' + name + '*]\n') - linkFile.write('\n') + apiLinkFile.write('// ' + name + '\n') + apiLinkFile.write(':' + name + ': pass:q[*' + name + '*]\n') + apiLinkFile.write('\n') - nolinkFile.write('// ' + name + '\n') - nolinkFile.write(':' + name + ': pass:q[*' + name + '*]\n') - nolinkFile.write('\n') + apiNoLinkFile.write('// ' + name + '\n') + apiNoLinkFile.write(':' + name + ': pass:q[*' + name + '*]\n') + apiNoLinkFile.write('\n') numberOfFuncs = numberOfFuncs + 1 @@ -132,31 +143,31 @@ def GetFooter(): #:CL_MEM_READ_ONLY_label: pass:q[`CL_MEM_READ_ONLY`] #:CL_MEM_READ_ONLY: <> #:CL_MEM_READ_ONLY_anchor: [[CL_MEM_READ_ONLY]]{CL_MEM_READ_ONLY} - linkFile.write('// ' + name + '\n') - linkFile.write('ifdef::backend-html5[]\n') - linkFile.write(':' + name + '_label: pass:q[`' + htmlName + '`]\n') - linkFile.write('endif::[]\n') - linkFile.write('ifndef::backend-html5[]\n') - linkFile.write(':' + name + '_label: pass:q[`' + otherName + '`]\n') - linkFile.write('endif::[]\n') - linkFile.write(':' + name + ': <<' + name + ',{' + name + '_label}>>\n') - linkFile.write(':' + name + '_anchor: [[' + name + ']]{' + name + '}\n') - linkFile.write('\n') + apiLinkFile.write('// ' + name + '\n') + apiLinkFile.write('ifdef::backend-html5[]\n') + apiLinkFile.write(':' + name + '_label: pass:q[`' + htmlName + '`]\n') + apiLinkFile.write('endif::[]\n') + apiLinkFile.write('ifndef::backend-html5[]\n') + apiLinkFile.write(':' + name + '_label: pass:q[`' + otherName + '`]\n') + apiLinkFile.write('endif::[]\n') + apiLinkFile.write(':' + name + ': <<' + name + ',{' + name + '_label}>>\n') + apiLinkFile.write(':' + name + '_anchor: [[' + name + ']]{' + name + '}\n') + apiLinkFile.write('\n') # Example without link: # # // CL_MEM_READ_ONLY #:CL_MEM_READ_ONLY: pass:q[`CL_MEM_READ_ONLY`] #:CL_MEM_READ_ONLY_anchor: {CL_MEM_READ_ONLY} - nolinkFile.write('// ' + name + '\n') - nolinkFile.write('ifdef::backend-html5[]\n') - nolinkFile.write(':' + name + ': pass:q[`' + htmlName + '`]\n') - nolinkFile.write('endif::[]\n') - nolinkFile.write('ifndef::backend-html5[]\n') - nolinkFile.write(':' + name + ': pass:q[`' + otherName + '`]\n') - nolinkFile.write('endif::[]\n') - nolinkFile.write(':' + name + '_anchor: {' + name + '}\n') - nolinkFile.write('\n') + apiNoLinkFile.write('// ' + name + '\n') + apiNoLinkFile.write('ifdef::backend-html5[]\n') + apiNoLinkFile.write(':' + name + ': pass:q[`' + htmlName + '`]\n') + apiNoLinkFile.write('endif::[]\n') + apiNoLinkFile.write('ifndef::backend-html5[]\n') + apiNoLinkFile.write(':' + name + ': pass:q[`' + otherName + '`]\n') + apiNoLinkFile.write('endif::[]\n') + apiNoLinkFile.write(':' + name + '_anchor: {' + name + '}\n') + apiNoLinkFile.write('\n') numberOfEnums = numberOfEnums + 1 @@ -192,31 +203,31 @@ def GetFooter(): #:CL_MAKE_VERSION_label: pass:q[`CL_MAKE_VERSION`] #:CL_MAKE_VERSION: <> #:CL_MAKE_VERSION_anchor: [[CL_MAKE_VERSION]]{CL_MAKE_VERSION} - linkFile.write('// ' + name + '\n') - linkFile.write('ifdef::backend-html5[]\n') - linkFile.write(':' + name + '_label: pass:q[`' + htmlName + '`]\n') - linkFile.write('endif::[]\n') - linkFile.write('ifndef::backend-html5[]\n') - linkFile.write(':' + name + '_label: pass:q[`' + otherName + '`]\n') - linkFile.write('endif::[]\n') - linkFile.write(':' + name + ': <<' + name + ',{' + name + '_label}>>\n') - linkFile.write(':' + name + '_anchor: [[' + name + ']]{' + name + '}\n') - linkFile.write('\n') + apiLinkFile.write('// ' + name + '\n') + apiLinkFile.write('ifdef::backend-html5[]\n') + apiLinkFile.write(':' + name + '_label: pass:q[`' + htmlName + '`]\n') + apiLinkFile.write('endif::[]\n') + apiLinkFile.write('ifndef::backend-html5[]\n') + apiLinkFile.write(':' + name + '_label: pass:q[`' + otherName + '`]\n') + apiLinkFile.write('endif::[]\n') + apiLinkFile.write(':' + name + ': <<' + name + ',{' + name + '_label}>>\n') + apiLinkFile.write(':' + name + '_anchor: [[' + name + ']]{' + name + '}\n') + apiLinkFile.write('\n') # Example without link: # # // CL_MAKE_VERSION #:CL_MAKE_VERSION: pass:q[`CL_MAKE_VERSION`] #:CL_MAKE_VERSION_anchor: {CL_MAKE_VERSION} - nolinkFile.write('// ' + name + '\n') - nolinkFile.write('ifdef::backend-html5[]\n') - nolinkFile.write(':' + name + ': pass:q[`' + htmlName + '`]\n') - nolinkFile.write('endif::[]\n') - nolinkFile.write('ifndef::backend-html5[]\n') - nolinkFile.write(':' + name + ': pass:q[`' + otherName + '`]\n') - nolinkFile.write('endif::[]\n') - nolinkFile.write(':' + name + '_anchor: {' + name + '}\n') - nolinkFile.write('\n') + apiNoLinkFile.write('// ' + name + '\n') + apiNoLinkFile.write('ifdef::backend-html5[]\n') + apiNoLinkFile.write(':' + name + ': pass:q[`' + htmlName + '`]\n') + apiNoLinkFile.write('endif::[]\n') + apiNoLinkFile.write('ifndef::backend-html5[]\n') + apiNoLinkFile.write(':' + name + ': pass:q[`' + otherName + '`]\n') + apiNoLinkFile.write('endif::[]\n') + apiNoLinkFile.write(':' + name + '_anchor: {' + name + '}\n') + apiNoLinkFile.write('\n') numberOfMacros = numberOfMacros + 1 @@ -269,51 +280,128 @@ def GetFooter(): # // cl_image_desc # :cl_image_desc_TYPE_label: pass:q[`cl_image_desc`] # :cl_image_desc_TYPE: <> - linkFile.write('// ' + name + '\n') + apiLinkFile.write('// ' + name + '\n') if addLink: - linkFile.write('ifdef::backend-html5[]\n') - linkFile.write(':' + attribName + '_label: pass:q[`' + htmlName + '`]\n') - linkFile.write('endif::[]\n') - linkFile.write('ifndef::backend-html5[]\n') - linkFile.write(':' + attribName + '_label: pass:q[`' + otherName + '`]\n') - linkFile.write('endif::[]\n') - linkFile.write(':' + attribName + ': <<' + name + ',{' + attribName + '_label}>>\n') + apiLinkFile.write('ifdef::backend-html5[]\n') + apiLinkFile.write(':' + attribName + '_label: pass:q[`' + htmlName + '`]\n') + apiLinkFile.write('endif::[]\n') + apiLinkFile.write('ifndef::backend-html5[]\n') + apiLinkFile.write(':' + attribName + '_label: pass:q[`' + otherName + '`]\n') + apiLinkFile.write('endif::[]\n') + apiLinkFile.write(':' + attribName + ': <<' + name + ',{' + attribName + '_label}>>\n') else: - linkFile.write('ifdef::backend-html5[]\n') - linkFile.write(':' + attribName + ': pass:q[`' + htmlName + '`]\n') - linkFile.write('endif::[]\n') - linkFile.write('ifndef::backend-html5[]\n') - linkFile.write(':' + attribName + ': pass:q[`' + otherName + '`]\n') - linkFile.write('endif::[]\n') - linkFile.write('\n') + apiLinkFile.write('ifdef::backend-html5[]\n') + apiLinkFile.write(':' + attribName + ': pass:q[`' + htmlName + '`]\n') + apiLinkFile.write('endif::[]\n') + apiLinkFile.write('ifndef::backend-html5[]\n') + apiLinkFile.write(':' + attribName + ': pass:q[`' + otherName + '`]\n') + apiLinkFile.write('endif::[]\n') + apiLinkFile.write('\n') # // cl_image_desc # :cl_image_desc_TYPE: pass:q[`cl_image_desc`] - nolinkFile.write('// ' + name + '\n') - nolinkFile.write('ifdef::backend-html5[]\n') - nolinkFile.write(':' + attribName + ': pass:q[`' + htmlName + '`]\n') - nolinkFile.write('endif::[]\n') - nolinkFile.write('ifndef::backend-html5[]\n') - nolinkFile.write(':' + attribName + ': pass:q[`' + otherName + '`]\n') - nolinkFile.write('endif::[]\n') - nolinkFile.write('\n') + apiNoLinkFile.write('// ' + name + '\n') + apiNoLinkFile.write('ifdef::backend-html5[]\n') + apiNoLinkFile.write(':' + attribName + ': pass:q[`' + htmlName + '`]\n') + apiNoLinkFile.write('endif::[]\n') + apiNoLinkFile.write('ifndef::backend-html5[]\n') + apiNoLinkFile.write(':' + attribName + ': pass:q[`' + otherName + '`]\n') + apiNoLinkFile.write('endif::[]\n') + apiNoLinkFile.write('\n') # Print the type list to a file for custom syntax highlighting. # For this we only care about CL types, not base types. if category != 'basetype': - typeFile.write(' ' + name + '\n') + apiTypeFile.write(' ' + name + '\n') numberOfTypes = numberOfTypes + 1 print('Found ' + str(numberOfTypes) + ' API types.') - linkFile.write( GetFooter() ) - linkFile.close() - nolinkFile.write( GetFooter() ) - nolinkFile.close() - typeFile.close() - - print('Successfully generated file: ' + linkFileName) - print('Successfully generated file: ' + nolinkFileName) - print('Successfully generated file: ' + typeFileName) + # Generate the extension dictionaries: + + numberOfExtensions = 0 + + for extension in spec.findall('extensions/extension'): + name = extension.get('name') + #print('found extension: ' + name) + + # Create a variant of the name that precedes underscores with + # "zero width" spaces. This causes some long names to be + # broken at more intuitive places. + htmlName = name[:3] + name[3:].replace("_", "_") + otherName = name[:3] + name[3:].replace("_", "_​") + + # Append the extension suffix for disambiguation, since we use + # the extension name as an attribute to enable and disable + # inclusion of the extension. + attribName = name + "_EXT" + + # Example with no link: + # + # // cl_khr_fp64 + #:cl_khr_fp64_EXT_label: pass:q[`cl_khr_fp64`] + #:cl_khr_fp64_EXT: [{cl_khr_fp64_EXT_label}] + extNoLinkFile.write('// ' + name + '\n') + extNoLinkFile.write('ifdef::backend-html5[]\n') + extNoLinkFile.write(':' + attribName + ': pass:q[`' + htmlName + '`]\n') + extNoLinkFile.write('endif::[]\n') + extNoLinkFile.write('ifndef::backend-html5[]\n') + extNoLinkFile.write(':' + attribName + ': pass:q[`' + otherName + '`]\n') + extNoLinkFile.write('endif::[]\n') + extNoLinkFile.write('\n') + + # Example with full link: + # + # // cl_khr_fp64 + #:cl_khr_fp64_EXT_label: pass:q[`cl_khr_fp64`] + #:cl_khr_fp64_EXT: https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_API.html#cl_khr_fp64[{cl_khr_fp64_EXT_label}^] + extFullLinkFile.write('// ' + name + '\n') + extFullLinkFile.write('ifdef::backend-html5[]\n') + extFullLinkFile.write(':' + attribName + '_label: pass:q[`' + htmlName + '`]\n') + extFullLinkFile.write('endif::[]\n') + extFullLinkFile.write('ifndef::backend-html5[]\n') + extFullLinkFile.write(':' + attribName + '_label: pass:q[`' + otherName + '`]\n') + extFullLinkFile.write('endif::[]\n') + extFullLinkFile.write(':' + attribName + ': https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_API.html#' + name + '[{' + attribName + '_label}^]\n') + extFullLinkFile.write('\n') + + # Example with local link: + # + # // cl_khr_fp64 + #:cl_khr_fp64_EXT_label: pass:q[`cl_khr_fp64`] + #:cl_khr_fp64_EXT: <> + extLocalLinkFile.write('// ' + name + '\n') + extLocalLinkFile.write('ifdef::backend-html5[]\n') + extLocalLinkFile.write(':' + attribName + '_label: pass:q[`' + htmlName + '`]\n') + extLocalLinkFile.write('endif::[]\n') + extLocalLinkFile.write('ifndef::backend-html5[]\n') + extLocalLinkFile.write(':' + attribName + '_label: pass:q[`' + otherName + '`]\n') + extLocalLinkFile.write('endif::[]\n') + extLocalLinkFile.write(':' + attribName + ': <<' + name + ',{' + attribName + '_label}>>\n') + extLocalLinkFile.write('\n') + + numberOfExtensions = numberOfExtensions + 1 + + print('Found ' + str(numberOfExtensions) + ' extensions.') + + apiLinkFile.write( GetFooter() ) + apiLinkFile.close() + apiNoLinkFile.write( GetFooter() ) + apiNoLinkFile.close() + apiTypeFile.close() + + extNoLinkFile.write( GetFooter() ) + extNoLinkFile.close() + extFullLinkFile.write( GetFooter() ) + extFullLinkFile.close() + extLocalLinkFile.write( GetFooter() ) + extLocalLinkFile.close() + + print('Successfully generated file: ' + apiLinkFileName) + print('Successfully generated file: ' + apiNoLinkFileName) + print('Successfully generated file: ' + apiTypeFileName) + print('Successfully generated file: ' + extNoLinkFileName) + print('Successfully generated file: ' + extFullLinkFileName) + print('Successfully generated file: ' + extLocalLinkFileName) From 88c23e452f33e2499862255ddefc44b7eed46910 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Tue, 2 Apr 2024 18:04:25 -0700 Subject: [PATCH 26/71] adding missing anchor for CL_MEM_DEVICE_HANDLE_LIST_END_KHR (#1134) --- api/opencl_runtime_layer.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 27788730e..015322282 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -595,8 +595,8 @@ ifdef::cl_khr_external_memory[] include::{generated}/api/version-notes/CL_MEM_DEVICE_HANDLE_LIST_KHR.asciidoc[] | {cl_device_id_TYPE}[] | Specifies the list of OpenCL devices (terminated with - {CL_MEM_DEVICE_HANDLE_LIST_END_KHR}) to associate with the external - memory handle. + {CL_MEM_DEVICE_HANDLE_LIST_END_KHR_anchor}) to associate with the + external memory handle. endif::cl_khr_external_memory[] |==== From 38979f687bb4bfb81a892340412fd5d3ce3b2259 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Tue, 2 Apr 2024 22:28:08 -0700 Subject: [PATCH 27/71] remove nextafter TODO (#1140) --- OpenCL_C.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/OpenCL_C.txt b/OpenCL_C.txt index 79a27f8f6..7e2fc8a12 100644 --- a/OpenCL_C.txt +++ b/OpenCL_C.txt @@ -5469,8 +5469,6 @@ endif::cl_khr_fp16[] | Returns a quiet NaN. The _nancode_ may be placed in the significand of the resulting NaN. | gentype *nextafter*(gentype _x_, gentype _y_) -// TODO shouldn't this be "next representable FP value of the precision of -// its arguments"? See the OpenCL-Docs issue. | Computes the next representable floating-point value following _x_ in the direction of _y_. Thus, if _y_ is less than _x_, *nextafter*() returns the largest From e63670e8a00fc1565a13631b649fe911f557e03d Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Wed, 3 Apr 2024 07:09:44 -0700 Subject: [PATCH 28/71] briefly describe cl_mutable_base_config_khr structure (#1139) --- api/opencl_runtime_layer.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 015322282..b3b9d8f61 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -15838,8 +15838,8 @@ defined conditions: [open,refpage='cl_mutable_base_config_khr',desc='DESC',type='structs'] -- -The {cl_mutable_base_config_khr_TYPE} structure is TODO Add fuller -description here and is defined as: +The {cl_mutable_base_config_khr_TYPE} structure encapsulates all aspects of +mutation and is defined as: include::{generated}/api/structs/cl_mutable_base_config_khr.txt[] From da1282c772a3dcecf9441cd449f551b721df9e6f Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Wed, 3 Apr 2024 14:19:12 -0700 Subject: [PATCH 29/71] update non-provisional extensions to version 1.0.0 (#1133) * update non-provisional extensions to version 1.0.0 * update a few other revision comments, just in case * remove leftover conversion comments --- api/cl_khr_external_memory.asciidoc | 9 +++------ api/cl_khr_external_memory_dma_buf.asciidoc | 10 +++------- api/cl_khr_external_memory_dx.asciidoc | 6 ------ api/cl_khr_external_memory_opaque_fd.asciidoc | 10 +++------- api/cl_khr_external_memory_win32.asciidoc | 10 +++------- api/cl_khr_external_semaphore.asciidoc | 5 +++-- api/cl_khr_external_semaphore_opaque_fd.asciidoc | 4 +++- api/cl_khr_external_semaphore_sync_fd.asciidoc | 4 +++- api/cl_khr_semaphore.asciidoc | 6 +++--- 9 files changed, 24 insertions(+), 40 deletions(-) diff --git a/api/cl_khr_external_memory.asciidoc b/api/cl_khr_external_memory.asciidoc index 6da4455de..e06839996 100644 --- a/api/cl_khr_external_memory.asciidoc +++ b/api/cl_khr_external_memory.asciidoc @@ -3,15 +3,10 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory.txt[] -//@ *Revision*:: -//@ 0.9.3 -//@ *Extension and Version Dependencies*:: -//@ This extension requires OpenCL 3.0. - === Other Extension Metadata *Last Modified Date*:: - 2023-08-29 + 2024-03-15 *IP Status*:: No known IP claims. *Contributors*:: @@ -308,3 +303,5 @@ while (true) { ** Added query for {CL_DEVICE_EXTERNAL_MEMORY_IMPORT_ASSUME_LINEAR_IMAGES_HANDLE_TYPES_KHR} (provisional). + * Revision 1.0.0, 2024-03-15 + ** First non-provisional version. diff --git a/api/cl_khr_external_memory_dma_buf.asciidoc b/api/cl_khr_external_memory_dma_buf.asciidoc index 071aed992..0e01a9f46 100644 --- a/api/cl_khr_external_memory_dma_buf.asciidoc +++ b/api/cl_khr_external_memory_dma_buf.asciidoc @@ -3,16 +3,10 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_dma_buf.txt[] -//@ *Revision*:: -//@ 0.9.3 -//@ *Extension and Version Dependencies*:: -//@ This extension requires OpenCL 3.0. -//@ This extension requires the {cl_khr_external_memory_EXT} extension. - === Other Extension Metadata *Last Modified Date*:: - 2023-08-29 + 2024-03-15 *IP Status*:: No known IP claims. *Contributors*:: @@ -74,3 +68,5 @@ TODO ** Added query for {CL_DEVICE_EXTERNAL_MEMORY_IMPORT_ASSUME_LINEAR_IMAGES_HANDLE_TYPES_KHR} (provisional). + * Revision 1.0.0, 2024-03-15 + ** First non-provisional version. diff --git a/api/cl_khr_external_memory_dx.asciidoc b/api/cl_khr_external_memory_dx.asciidoc index ab79949f3..0f310c138 100644 --- a/api/cl_khr_external_memory_dx.asciidoc +++ b/api/cl_khr_external_memory_dx.asciidoc @@ -3,12 +3,6 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_dx.txt[] -//@ *Revision*:: -//@ 0.9.3 -//@ *Extension and Version Dependencies*:: -//@ This extension requires OpenCL 3.0. -//@ This extension requires the {cl_khr_external_memory_EXT} extension. - === Other Extension Metadata *Last Modified Date*:: diff --git a/api/cl_khr_external_memory_opaque_fd.asciidoc b/api/cl_khr_external_memory_opaque_fd.asciidoc index 3d7c059e3..392db9b9a 100644 --- a/api/cl_khr_external_memory_opaque_fd.asciidoc +++ b/api/cl_khr_external_memory_opaque_fd.asciidoc @@ -3,16 +3,10 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_opaque_fd.txt[] -//@ *Revision*:: -//@ 0.9.3 -//@ *Extension and Version Dependencies*:: -//@ This extension requires OpenCL 3.0. -//@ This extension requires the {cl_khr_external_memory_EXT} extension. - === Other Extension Metadata *Last Modified Date*:: - 2023-08-29 + 2024-03-15 *IP Status*:: No known IP claims. *Contributors*:: @@ -74,3 +68,5 @@ TODO ** Added query for {CL_DEVICE_EXTERNAL_MEMORY_IMPORT_ASSUME_LINEAR_IMAGES_HANDLE_TYPES_KHR} (provisional). + * Revision 1.0.0, 2024-03-15 + ** First non-provisional version. diff --git a/api/cl_khr_external_memory_win32.asciidoc b/api/cl_khr_external_memory_win32.asciidoc index bfb03d853..bddf7b55b 100644 --- a/api/cl_khr_external_memory_win32.asciidoc +++ b/api/cl_khr_external_memory_win32.asciidoc @@ -3,16 +3,10 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_win32.txt[] -//@ *Revision*:: -//@ 0.9.3 -//@ *Extension and Version Dependencies*:: -//@ This extension requires OpenCL 3.0. -//@ This extension requires the {cl_khr_external_memory_EXT} extension. - === Other Extension Metadata *Last Modified Date*:: - 2023-08-29 + 2024-03-15 *IP Status*:: No known IP claims. *Contributors*:: @@ -75,3 +69,5 @@ TODO ** Added query for {CL_DEVICE_EXTERNAL_MEMORY_IMPORT_ASSUME_LINEAR_IMAGES_HANDLE_TYPES_KHR} (provisional). + * Revision 1.0.0, 2024-03-15 + ** First non-provisional version. diff --git a/api/cl_khr_external_semaphore.asciidoc b/api/cl_khr_external_semaphore.asciidoc index c5debcc7f..2b466ad5c 100644 --- a/api/cl_khr_external_semaphore.asciidoc +++ b/api/cl_khr_external_semaphore.asciidoc @@ -6,7 +6,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_semaphore.txt[] === Other Extension Metadata *Last Modified Date*:: - 2021-09-10 + 2024-03-15 *Interactions and External Dependencies*:: * This extension requires OpenCL 1.2. * The {cl_khr_semaphore_EXT} extension is required as it defines semaphore @@ -282,4 +282,5 @@ while (true) { ** Added {CL_SEMAPHORE_EXPORTABLE_KHR}. * Revision 0.9.2, 2023-11-21 ** Added re-import function call to {cl_khr_external_semaphore_sync_fd_EXT} - + * Revision 1.0.0, 2024-03-15 + ** First non-provisional version. diff --git a/api/cl_khr_external_semaphore_opaque_fd.asciidoc b/api/cl_khr_external_semaphore_opaque_fd.asciidoc index eb7cc4563..7e40df3ef 100644 --- a/api/cl_khr_external_semaphore_opaque_fd.asciidoc +++ b/api/cl_khr_external_semaphore_opaque_fd.asciidoc @@ -6,7 +6,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_semaphore_opaque_fd.txt[] === Other Extension Metadata *Last Modified Date*:: - 2021-09-10 + 2024-03-15 *IP Status*:: No known IP claims. *Contributors*:: @@ -43,3 +43,5 @@ introduced by {cl_khr_external_semaphore_EXT}. * Revision 0.9.0, 2021-09-10 ** Initial version (provisional). + * Revision 1.0.0, 2024-03-15 + ** First non-provisional version. diff --git a/api/cl_khr_external_semaphore_sync_fd.asciidoc b/api/cl_khr_external_semaphore_sync_fd.asciidoc index 4d7e88922..f8203ce90 100644 --- a/api/cl_khr_external_semaphore_sync_fd.asciidoc +++ b/api/cl_khr_external_semaphore_sync_fd.asciidoc @@ -6,7 +6,7 @@ include::{generated}/meta/{refprefix}cl_khr_external_semaphore_sync_fd.txt[] === Other Extension Metadata *Last Modified Date*:: - 2021-09-10 + 2024-03-15 *IP Status*:: No known IP claims. *Contributors*:: @@ -56,3 +56,5 @@ external semaphore using the APIs introduced by ** Added {CL_SEMAPHORE_EXPORTABLE_KHR}. * Revision 0.9.2, 2023-11-21 ** Added re-import function call to {cl_khr_external_semaphore_sync_fd_EXT} + * Revision 1.0.0, 2024-03-15 + ** First non-provisional version. diff --git a/api/cl_khr_semaphore.asciidoc b/api/cl_khr_semaphore.asciidoc index 5328e51c3..4a9a259bc 100644 --- a/api/cl_khr_semaphore.asciidoc +++ b/api/cl_khr_semaphore.asciidoc @@ -6,7 +6,7 @@ include::{generated}/meta/{refprefix}cl_khr_semaphore.txt[] === Other Extension Metadata *Last Modified Date*:: - 2023-08-01 + 2024-03-15 *IP Status*:: No known IP claims. *Contributors*:: @@ -254,5 +254,5 @@ while (true) { * Revision 0.9.1, 2023-08-01 ** Changed device handle list enum to the semaphore-specific {CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR} (provisional). - - + * Revision 1.0.0, 2024-03-15 + ** First non-provisional version. From 82b67ddadb9008d3c5e9342914b4bdb4b2091783 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Wed, 3 Apr 2024 14:47:01 -0700 Subject: [PATCH 30/71] fix fract for double and half arguments (#1136) --- OpenCL_C.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/OpenCL_C.txt b/OpenCL_C.txt index 7e2fc8a12..b7a0d788f 100644 --- a/OpenCL_C.txt +++ b/OpenCL_C.txt @@ -5282,9 +5282,9 @@ ifdef::cl_khr_fp16[gentypeh *fmax*(gentypeh _x_, half _y_)] {opencl_c_generic_address_space} feature: gentype *fract*(gentype _x_, gentype _*iptr_) -// TODO The fp16 extension uses the constant `0x1.ffcp-1f` below - unclear -// why, see the OpenCL-Docs issue. - | Returns *fmin*(_x_ - *floor*(_x_), `0x1.fffffep-1f`). + | Returns *fmin*(_x_ - *floor*(_x_), `C`), where `C` is the constant + `0x1.fffffep-1f` for `float` aguments, `0x1.fffffffffffffp-1` for `double` + arguments, and `0x1.ffcp-1h` for `half` arguments. *floor*(x) is returned in _iptr_. footnote:[{fn-fract-min}] ifdef::cl_khr_fp16[] From f09a9c218377d906a1b2c83201a5d86e9a1384aa Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Wed, 3 Apr 2024 14:53:45 -0700 Subject: [PATCH 31/71] remove TODO and TBD placeholders (#1135) --- api/cl_khr_3d_image_writes.asciidoc | 2 -- api/cl_khr_async_work_group_copy_fence.asciidoc | 2 -- api/cl_khr_byte_addressable_store.asciidoc | 2 -- api/cl_khr_create_command_queue.asciidoc | 2 -- api/cl_khr_d3d10_sharing.asciidoc | 2 -- api/cl_khr_d3d11_sharing.asciidoc | 2 -- api/cl_khr_depth_images.asciidoc | 2 -- ...cl_khr_device_enqueue_local_arg_types.asciidoc | 2 -- api/cl_khr_device_uuid.asciidoc | 4 +--- api/cl_khr_dx9_media_sharing.asciidoc | 2 -- api/cl_khr_egl_event.asciidoc | 2 -- api/cl_khr_egl_image.asciidoc | 2 -- api/cl_khr_expect_assume.asciidoc | 2 -- api/cl_khr_extended_async_copies.asciidoc | 2 -- api/cl_khr_extended_bit_ops.asciidoc | 2 -- api/cl_khr_external_memory.asciidoc | 15 --------------- api/cl_khr_external_memory_dma_buf.asciidoc | 14 -------------- api/cl_khr_external_memory_dx.asciidoc | 14 -------------- api/cl_khr_external_memory_opaque_fd.asciidoc | 14 -------------- api/cl_khr_external_memory_win32.asciidoc | 14 -------------- api/cl_khr_fp16.asciidoc | 2 -- api/cl_khr_fp64.asciidoc | 2 -- api/cl_khr_gl_depth_images.asciidoc | 2 -- api/cl_khr_gl_event.asciidoc | 2 -- api/cl_khr_gl_msaa_sharing.asciidoc | 2 -- api/cl_khr_gl_sharing.asciidoc | 2 -- api/cl_khr_global_int32_base_atomics.asciidoc | 2 -- api/cl_khr_global_int32_extended_atomics.asciidoc | 2 -- api/cl_khr_icd.asciidoc | 12 ------------ api/cl_khr_il_program.asciidoc | 2 -- api/cl_khr_image2d_from_buffer.asciidoc | 2 -- api/cl_khr_initialize_memory.asciidoc | 2 -- api/cl_khr_int64_base_atomics.asciidoc | 2 -- api/cl_khr_int64_extended_atomics.asciidoc | 2 -- api/cl_khr_local_int32_base_atomics.asciidoc | 2 -- api/cl_khr_local_int32_extended_atomics.asciidoc | 2 -- api/cl_khr_mipmap_image.asciidoc | 2 -- api/cl_khr_mipmap_image_writes.asciidoc | 2 -- api/cl_khr_pci_bus_info.asciidoc | 2 -- api/cl_khr_priority_hints.asciidoc | 2 -- api/cl_khr_select_fprounding_mode.asciidoc | 2 -- api/cl_khr_semaphore.asciidoc | 1 - api/cl_khr_spir.asciidoc | 2 -- api/cl_khr_spirv_extended_debug_info.asciidoc | 2 -- api/cl_khr_spirv_linkonce_odr.asciidoc | 2 -- ..._khr_spirv_no_integer_wrap_decoration.asciidoc | 2 -- api/cl_khr_srgb_image_writes.asciidoc | 2 -- api/cl_khr_subgroup_ballot.asciidoc | 2 -- api/cl_khr_subgroup_clustered_reduce.asciidoc | 2 -- api/cl_khr_subgroup_extended_types.asciidoc | 2 -- api/cl_khr_subgroup_named_barrier.asciidoc | 2 -- ...l_khr_subgroup_non_uniform_arithmetic.asciidoc | 2 -- api/cl_khr_subgroup_non_uniform_vote.asciidoc | 2 -- api/cl_khr_subgroup_shuffle.asciidoc | 2 -- api/cl_khr_subgroup_shuffle_relative.asciidoc | 2 -- api/cl_khr_subgroups.asciidoc | 2 -- api/cl_khr_suggested_local_work_size.asciidoc | 2 -- api/cl_khr_terminate_context.asciidoc | 2 -- api/cl_khr_throttle_hints.asciidoc | 2 -- 59 files changed, 1 insertion(+), 189 deletions(-) diff --git a/api/cl_khr_3d_image_writes.asciidoc b/api/cl_khr_3d_image_writes.asciidoc index 49e388f4b..8495fa692 100644 --- a/api/cl_khr_3d_image_writes.asciidoc +++ b/api/cl_khr_3d_image_writes.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_3d_image_writes.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_async_work_group_copy_fence.asciidoc b/api/cl_khr_async_work_group_copy_fence.asciidoc index 1c36daccb..321cb1a90 100644 --- a/api/cl_khr_async_work_group_copy_fence.asciidoc +++ b/api/cl_khr_async_work_group_copy_fence.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_async_work_group_copy_fence.txt[] 2021-11-10 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_byte_addressable_store.asciidoc b/api/cl_khr_byte_addressable_store.asciidoc index cdff78462..7637d79b7 100644 --- a/api/cl_khr_byte_addressable_store.asciidoc +++ b/api/cl_khr_byte_addressable_store.asciidoc @@ -11,8 +11,6 @@ include::{generated}/meta/{refprefix}cl_khr_byte_addressable_store.txt[] - Promoted to OpenCL 1.1 core *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_create_command_queue.asciidoc b/api/cl_khr_create_command_queue.asciidoc index 89e22e1d6..1905b7e34 100644 --- a/api/cl_khr_create_command_queue.asciidoc +++ b/api/cl_khr_create_command_queue.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_create_command_queue.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_d3d10_sharing.asciidoc b/api/cl_khr_d3d10_sharing.asciidoc index 96532a430..32d9dc517 100644 --- a/api/cl_khr_d3d10_sharing.asciidoc +++ b/api/cl_khr_d3d10_sharing.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_d3d10_sharing.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_d3d11_sharing.asciidoc b/api/cl_khr_d3d11_sharing.asciidoc index c3fdd8154..d57b904f8 100644 --- a/api/cl_khr_d3d11_sharing.asciidoc +++ b/api/cl_khr_d3d11_sharing.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_d3d11_sharing.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_depth_images.asciidoc b/api/cl_khr_depth_images.asciidoc index 61ceb60ae..895202496 100644 --- a/api/cl_khr_depth_images.asciidoc +++ b/api/cl_khr_depth_images.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_depth_images.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_device_enqueue_local_arg_types.asciidoc b/api/cl_khr_device_enqueue_local_arg_types.asciidoc index 1adcbd60c..f241a7d7a 100644 --- a/api/cl_khr_device_enqueue_local_arg_types.asciidoc +++ b/api/cl_khr_device_enqueue_local_arg_types.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_device_enqueue_local_arg_types.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_device_uuid.asciidoc b/api/cl_khr_device_uuid.asciidoc index 74b4f00b8..7b669c135 100644 --- a/api/cl_khr_device_uuid.asciidoc +++ b/api/cl_khr_device_uuid.asciidoc @@ -6,11 +6,9 @@ include::{generated}/meta/{refprefix}cl_khr_device_uuid.txt[] === Other Extension Metadata *Last Modified Date*:: - DateTBD + 2020-08-27 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_dx9_media_sharing.asciidoc b/api/cl_khr_dx9_media_sharing.asciidoc index 7f887bcf5..455fd4359 100644 --- a/api/cl_khr_dx9_media_sharing.asciidoc +++ b/api/cl_khr_dx9_media_sharing.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_dx9_media_sharing.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_egl_event.asciidoc b/api/cl_khr_egl_event.asciidoc index 278dec5a2..463ca2633 100644 --- a/api/cl_khr_egl_event.asciidoc +++ b/api/cl_khr_egl_event.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_egl_event.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_egl_image.asciidoc b/api/cl_khr_egl_image.asciidoc index d31989430..42e03b71e 100644 --- a/api/cl_khr_egl_image.asciidoc +++ b/api/cl_khr_egl_image.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_egl_image.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_expect_assume.asciidoc b/api/cl_khr_expect_assume.asciidoc index 615a0d559..704f87aab 100644 --- a/api/cl_khr_expect_assume.asciidoc +++ b/api/cl_khr_expect_assume.asciidoc @@ -14,8 +14,6 @@ include::{generated}/meta/{refprefix}cl_khr_expect_assume.txt[] describes how this extension modifies the OpenCL SPIR-V environment. *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_extended_async_copies.asciidoc b/api/cl_khr_extended_async_copies.asciidoc index e04cf7a40..3ac6bc321 100644 --- a/api/cl_khr_extended_async_copies.asciidoc +++ b/api/cl_khr_extended_async_copies.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_extended_async_copies.txt[] 2021-11-10 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_extended_bit_ops.asciidoc b/api/cl_khr_extended_bit_ops.asciidoc index 766306ff4..0bea6218f 100644 --- a/api/cl_khr_extended_bit_ops.asciidoc +++ b/api/cl_khr_extended_bit_ops.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_extended_bit_ops.txt[] 2021-04-22 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_external_memory.asciidoc b/api/cl_khr_external_memory.asciidoc index e06839996..cd572a8fb 100644 --- a/api/cl_khr_external_memory.asciidoc +++ b/api/cl_khr_external_memory.asciidoc @@ -41,21 +41,6 @@ image objects between OpenCL and many other APIs, including: Other related extensions define specific external memory types that may be imported into OpenCL. - -==== Background - -TODO - -==== Rationale - -TODO - -=== Interactions With Other Extensions - -TODO - -// The 'New ...' section can be auto-generated - === New Commands * {clEnqueueAcquireExternalMemObjectsKHR} diff --git a/api/cl_khr_external_memory_dma_buf.asciidoc b/api/cl_khr_external_memory_dma_buf.asciidoc index 0e01a9f46..193f1a712 100644 --- a/api/cl_khr_external_memory_dma_buf.asciidoc +++ b/api/cl_khr_external_memory_dma_buf.asciidoc @@ -35,20 +35,6 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_dma_buf.txt[] external memory handle type that may be specified when creating a buffer or image memory object. -==== Background - -TODO - -==== Rationale - -TODO - -=== Interactions With Other Extensions - -TODO - -// The 'New ...' section can be auto-generated - === New Enums * {cl_external_memory_handle_type_khr_TYPE} diff --git a/api/cl_khr_external_memory_dx.asciidoc b/api/cl_khr_external_memory_dx.asciidoc index 0f310c138..ab742fea5 100644 --- a/api/cl_khr_external_memory_dx.asciidoc +++ b/api/cl_khr_external_memory_dx.asciidoc @@ -35,20 +35,6 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_dx.txt[] referring to Direct 3D resources as external memory handle types that may be specified when creating a buffer or image memory object. -==== Background - -TODO - -==== Rationale - -TODO - -=== Interactions With Other Extensions - -TODO - -// The 'New ...' section can be auto-generated - === New Enums * {cl_external_memory_handle_type_khr_TYPE} diff --git a/api/cl_khr_external_memory_opaque_fd.asciidoc b/api/cl_khr_external_memory_opaque_fd.asciidoc index 392db9b9a..92a3ab0ea 100644 --- a/api/cl_khr_external_memory_opaque_fd.asciidoc +++ b/api/cl_khr_external_memory_opaque_fd.asciidoc @@ -35,20 +35,6 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_opaque_fd.txt[] handle as an external memory handle type that may be specified when creating a buffer or image memory object. -==== Background - -TODO - -==== Rationale - -TODO - -=== Interactions With Other Extensions - -TODO - -// The 'New ...' section can be auto-generated - === New Enums * {cl_external_memory_handle_type_khr_TYPE} diff --git a/api/cl_khr_external_memory_win32.asciidoc b/api/cl_khr_external_memory_win32.asciidoc index bddf7b55b..005c9278f 100644 --- a/api/cl_khr_external_memory_win32.asciidoc +++ b/api/cl_khr_external_memory_win32.asciidoc @@ -35,20 +35,6 @@ include::{generated}/meta/{refprefix}cl_khr_external_memory_win32.txt[] external memory handle types that may be specified when creating a buffer or image memory object. -==== Background - -TODO - -==== Rationale - -TODO - -=== Interactions With Other Extensions - -TODO - -// The 'New ...' section can be auto-generated - === New Enums * {cl_external_memory_handle_type_khr_TYPE} diff --git a/api/cl_khr_fp16.asciidoc b/api/cl_khr_fp16.asciidoc index 4b7feb139..aa6a2e801 100644 --- a/api/cl_khr_fp16.asciidoc +++ b/api/cl_khr_fp16.asciidoc @@ -12,8 +12,6 @@ include::{generated}/meta/{refprefix}cl_khr_fp16.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_fp64.asciidoc b/api/cl_khr_fp64.asciidoc index 5006d8328..e56a03f1c 100644 --- a/api/cl_khr_fp64.asciidoc +++ b/api/cl_khr_fp64.asciidoc @@ -12,8 +12,6 @@ include::{generated}/meta/{refprefix}cl_khr_fp64.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_gl_depth_images.asciidoc b/api/cl_khr_gl_depth_images.asciidoc index 05258a612..6bd403900 100644 --- a/api/cl_khr_gl_depth_images.asciidoc +++ b/api/cl_khr_gl_depth_images.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_gl_depth_images.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_gl_event.asciidoc b/api/cl_khr_gl_event.asciidoc index 1239e79ff..64e13ef66 100644 --- a/api/cl_khr_gl_event.asciidoc +++ b/api/cl_khr_gl_event.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_gl_event.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_gl_msaa_sharing.asciidoc b/api/cl_khr_gl_msaa_sharing.asciidoc index 64f4557cd..20042fe9f 100644 --- a/api/cl_khr_gl_msaa_sharing.asciidoc +++ b/api/cl_khr_gl_msaa_sharing.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_gl_msaa_sharing.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_gl_sharing.asciidoc b/api/cl_khr_gl_sharing.asciidoc index 779b94e37..124f6d770 100644 --- a/api/cl_khr_gl_sharing.asciidoc +++ b/api/cl_khr_gl_sharing.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_gl_sharing.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_global_int32_base_atomics.asciidoc b/api/cl_khr_global_int32_base_atomics.asciidoc index 079a834c5..0451eaa52 100644 --- a/api/cl_khr_global_int32_base_atomics.asciidoc +++ b/api/cl_khr_global_int32_base_atomics.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_global_int32_base_atomics.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_global_int32_extended_atomics.asciidoc b/api/cl_khr_global_int32_extended_atomics.asciidoc index 59831cb02..0733e27fd 100644 --- a/api/cl_khr_global_int32_extended_atomics.asciidoc +++ b/api/cl_khr_global_int32_extended_atomics.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_global_int32_extended_atomics.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_icd.asciidoc b/api/cl_khr_icd.asciidoc index 9a4b46cc8..39d4125f3 100644 --- a/api/cl_khr_icd.asciidoc +++ b/api/cl_khr_icd.asciidoc @@ -12,8 +12,6 @@ include::{generated}/meta/{refprefix}cl_khr_icd.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description @@ -260,11 +258,6 @@ Loader. . How are OpenCL extension to be handled? + -- -// TODO: This seems out-of-date and incorrect. -//RESOLVED: OpenCL extension functions may be added to the ICD Loader as soon as they -//are implemented by any vendor. -//The suffix mechanism provides access for vendor extensions which are not yet -//added to the ICD Loader. *RESOLVED*: Extension APIs must be queried using {clGetExtensionFunctionAddressForPlatform}. -- @@ -274,11 +267,6 @@ Loader. -- *RESOLVED*: The ICD will by default choose the first enumerated platform as the `NULL` platform. -// TODO: This seems out-of-date and incorrect. -//The user can override this default by setting an environment variable -//OPENCL_ICD_DEFAULT_PLATFORM to the desired platform index. -//The API calls that deal with platforms will return {CL_INVALID_PLATFORM} if -//the index is not between zero and (number of platforms - 1), both inclusive. -- . There exists no mechanism to unload the ICD Loader, should there be one? diff --git a/api/cl_khr_il_program.asciidoc b/api/cl_khr_il_program.asciidoc index b8d0c4846..ba99d2c9d 100644 --- a/api/cl_khr_il_program.asciidoc +++ b/api/cl_khr_il_program.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_il_program.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_image2d_from_buffer.asciidoc b/api/cl_khr_image2d_from_buffer.asciidoc index be7783c35..a698ce04e 100644 --- a/api/cl_khr_image2d_from_buffer.asciidoc +++ b/api/cl_khr_image2d_from_buffer.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_image2d_from_buffer.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_initialize_memory.asciidoc b/api/cl_khr_initialize_memory.asciidoc index f2c0ce800..ac0310242 100644 --- a/api/cl_khr_initialize_memory.asciidoc +++ b/api/cl_khr_initialize_memory.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_initialize_memory.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_int64_base_atomics.asciidoc b/api/cl_khr_int64_base_atomics.asciidoc index ac688d915..6026c1624 100644 --- a/api/cl_khr_int64_base_atomics.asciidoc +++ b/api/cl_khr_int64_base_atomics.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_int64_base_atomics.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_int64_extended_atomics.asciidoc b/api/cl_khr_int64_extended_atomics.asciidoc index 69416081c..6eeedca0c 100644 --- a/api/cl_khr_int64_extended_atomics.asciidoc +++ b/api/cl_khr_int64_extended_atomics.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_int64_extended_atomics.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_local_int32_base_atomics.asciidoc b/api/cl_khr_local_int32_base_atomics.asciidoc index 51300f0c5..cdffd332a 100644 --- a/api/cl_khr_local_int32_base_atomics.asciidoc +++ b/api/cl_khr_local_int32_base_atomics.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_local_int32_base_atomics.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_local_int32_extended_atomics.asciidoc b/api/cl_khr_local_int32_extended_atomics.asciidoc index 917d2e26a..e78b7a872 100644 --- a/api/cl_khr_local_int32_extended_atomics.asciidoc +++ b/api/cl_khr_local_int32_extended_atomics.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_local_int32_extended_atomics.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_mipmap_image.asciidoc b/api/cl_khr_mipmap_image.asciidoc index a500ed507..203694a3f 100644 --- a/api/cl_khr_mipmap_image.asciidoc +++ b/api/cl_khr_mipmap_image.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_mipmap_image.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_mipmap_image_writes.asciidoc b/api/cl_khr_mipmap_image_writes.asciidoc index 7051ca598..194e0c977 100644 --- a/api/cl_khr_mipmap_image_writes.asciidoc +++ b/api/cl_khr_mipmap_image_writes.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_mipmap_image_writes.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_pci_bus_info.asciidoc b/api/cl_khr_pci_bus_info.asciidoc index 3477565b5..0279a5191 100644 --- a/api/cl_khr_pci_bus_info.asciidoc +++ b/api/cl_khr_pci_bus_info.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_pci_bus_info.txt[] 2021-04-19 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_priority_hints.asciidoc b/api/cl_khr_priority_hints.asciidoc index 1e7981dd3..dfd29df15 100644 --- a/api/cl_khr_priority_hints.asciidoc +++ b/api/cl_khr_priority_hints.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_priority_hints.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_select_fprounding_mode.asciidoc b/api/cl_khr_select_fprounding_mode.asciidoc index 25a1fa4c3..1d9951826 100644 --- a/api/cl_khr_select_fprounding_mode.asciidoc +++ b/api/cl_khr_select_fprounding_mode.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_select_fprounding_mode.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_semaphore.asciidoc b/api/cl_khr_semaphore.asciidoc index 4a9a259bc..721a3da2e 100644 --- a/api/cl_khr_semaphore.asciidoc +++ b/api/cl_khr_semaphore.asciidoc @@ -89,7 +89,6 @@ In particular, this extension defines: ** {CL_SEMAPHORE_TYPE_KHR} ** {CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR} ** {CL_SEMAPHORE_DEVICE_HANDLE_LIST_END_KHR} -// TODO these are not described anywhere in the extension spec document * {cl_command_type_TYPE} ** {CL_COMMAND_SEMAPHORE_WAIT_KHR} ** {CL_COMMAND_SEMAPHORE_SIGNAL_KHR} diff --git a/api/cl_khr_spir.asciidoc b/api/cl_khr_spir.asciidoc index d794497d6..16573d170 100644 --- a/api/cl_khr_spir.asciidoc +++ b/api/cl_khr_spir.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_spir.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_spirv_extended_debug_info.asciidoc b/api/cl_khr_spirv_extended_debug_info.asciidoc index 5e280fb1a..d63208501 100644 --- a/api/cl_khr_spirv_extended_debug_info.asciidoc +++ b/api/cl_khr_spirv_extended_debug_info.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_spirv_extended_debug_info.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_spirv_linkonce_odr.asciidoc b/api/cl_khr_spirv_linkonce_odr.asciidoc index f35df832f..887b5e74a 100644 --- a/api/cl_khr_spirv_linkonce_odr.asciidoc +++ b/api/cl_khr_spirv_linkonce_odr.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_spirv_linkonce_odr.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_spirv_no_integer_wrap_decoration.asciidoc b/api/cl_khr_spirv_no_integer_wrap_decoration.asciidoc index d8456b6ab..2f0ca0122 100644 --- a/api/cl_khr_spirv_no_integer_wrap_decoration.asciidoc +++ b/api/cl_khr_spirv_no_integer_wrap_decoration.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_spirv_no_integer_wrap_decoration.txt 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_srgb_image_writes.asciidoc b/api/cl_khr_srgb_image_writes.asciidoc index 95ca39656..79c3ea16d 100644 --- a/api/cl_khr_srgb_image_writes.asciidoc +++ b/api/cl_khr_srgb_image_writes.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_srgb_image_writes.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_subgroup_ballot.asciidoc b/api/cl_khr_subgroup_ballot.asciidoc index f0cc70d64..ae17ced98 100644 --- a/api/cl_khr_subgroup_ballot.asciidoc +++ b/api/cl_khr_subgroup_ballot.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_ballot.txt[] 2020-12-15 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_subgroup_clustered_reduce.asciidoc b/api/cl_khr_subgroup_clustered_reduce.asciidoc index a6b8b5c65..9e6b7a078 100644 --- a/api/cl_khr_subgroup_clustered_reduce.asciidoc +++ b/api/cl_khr_subgroup_clustered_reduce.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_clustered_reduce.txt[] 2020-12-15 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_subgroup_extended_types.asciidoc b/api/cl_khr_subgroup_extended_types.asciidoc index 222b3db32..3f73839af 100644 --- a/api/cl_khr_subgroup_extended_types.asciidoc +++ b/api/cl_khr_subgroup_extended_types.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_extended_types.txt[] 2020-12-15 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_subgroup_named_barrier.asciidoc b/api/cl_khr_subgroup_named_barrier.asciidoc index d9dd17dbc..d8f8da0e0 100644 --- a/api/cl_khr_subgroup_named_barrier.asciidoc +++ b/api/cl_khr_subgroup_named_barrier.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_named_barrier.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_subgroup_non_uniform_arithmetic.asciidoc b/api/cl_khr_subgroup_non_uniform_arithmetic.asciidoc index a1bee7e11..cc0657cdb 100644 --- a/api/cl_khr_subgroup_non_uniform_arithmetic.asciidoc +++ b/api/cl_khr_subgroup_non_uniform_arithmetic.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_non_uniform_arithmetic.txt[ 2020-12-15 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_subgroup_non_uniform_vote.asciidoc b/api/cl_khr_subgroup_non_uniform_vote.asciidoc index 2188866ca..5803cf26b 100644 --- a/api/cl_khr_subgroup_non_uniform_vote.asciidoc +++ b/api/cl_khr_subgroup_non_uniform_vote.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_non_uniform_vote.txt[] 2020-12-15 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_subgroup_shuffle.asciidoc b/api/cl_khr_subgroup_shuffle.asciidoc index 44981e98d..12d4f6774 100644 --- a/api/cl_khr_subgroup_shuffle.asciidoc +++ b/api/cl_khr_subgroup_shuffle.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_shuffle.txt[] 2020-12-15 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_subgroup_shuffle_relative.asciidoc b/api/cl_khr_subgroup_shuffle_relative.asciidoc index 48f5f9723..f297be5a9 100644 --- a/api/cl_khr_subgroup_shuffle_relative.asciidoc +++ b/api/cl_khr_subgroup_shuffle_relative.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_subgroup_shuffle_relative.txt[] 2020-12-15 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_subgroups.asciidoc b/api/cl_khr_subgroups.asciidoc index a4f833747..56c3191c1 100644 --- a/api/cl_khr_subgroups.asciidoc +++ b/api/cl_khr_subgroups.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_subgroups.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_suggested_local_work_size.asciidoc b/api/cl_khr_suggested_local_work_size.asciidoc index d5c3faab4..b1f46baab 100644 --- a/api/cl_khr_suggested_local_work_size.asciidoc +++ b/api/cl_khr_suggested_local_work_size.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_suggested_local_work_size.txt[] 2021-04-22 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_terminate_context.asciidoc b/api/cl_khr_terminate_context.asciidoc index bc89dcc7e..2bc9de8b0 100644 --- a/api/cl_khr_terminate_context.asciidoc +++ b/api/cl_khr_terminate_context.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_terminate_context.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description diff --git a/api/cl_khr_throttle_hints.asciidoc b/api/cl_khr_throttle_hints.asciidoc index 0de50159d..4155f1edf 100644 --- a/api/cl_khr_throttle_hints.asciidoc +++ b/api/cl_khr_throttle_hints.asciidoc @@ -9,8 +9,6 @@ include::{generated}/meta/{refprefix}cl_khr_throttle_hints.txt[] 2020-04-21 *IP Status*:: No known IP claims. -*Contributors*:: - TBD === Description From 49a8bd8ada57db583e5a864b5ea370f6a688cfc3 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Thu, 4 Apr 2024 07:32:22 -0700 Subject: [PATCH 32/71] tidy up cl_khr_create_command_queue (#1138) Removes unneeded special-case text regarding the type accepted for CL_QUEUE_PROPERTIES. Calling this a cl_bitfield was a bug all along, and using cl_command_queue_properties is fine because it is a bitfield anyhow. Generalizes some text so it is not specific to OpenCL 2.x devices. Removes a TODO - no changes required. --- api/cl_khr_create_command_queue.asciidoc | 18 +++--------------- api/opencl_runtime_layer.asciidoc | 4 ---- 2 files changed, 3 insertions(+), 19 deletions(-) diff --git a/api/cl_khr_create_command_queue.asciidoc b/api/cl_khr_create_command_queue.asciidoc index 1905b7e34..7ac0a9ad6 100644 --- a/api/cl_khr_create_command_queue.asciidoc +++ b/api/cl_khr_create_command_queue.asciidoc @@ -24,21 +24,11 @@ No new command-queue properties are required by this extension. Applications may use the existing {CL_DEVICE_QUEUE_PROPERTIES} query to determine command-queue properties that are supported by the device. -OpenCL 2.x devices may support this extension for compatibility. +Newer OpenCL devices may support this extension for compatibility. In this scenario, the function added by this extension will have the same capabilities as the core {clCreateCommandQueueWithProperties} API. -Applications that only target OpenCL 2.x devices should use the core OpenCL -2.x {clCreateCommandQueueWithProperties} API instead of this extension API. - -NOTE: The type of the property value passed as {CL_QUEUE_PROPERTIES} to -{clCreateCommandQueueWithPropertiesKHR} is specified as -{cl_bitfield_TYPE} while the type passed to -{clCreateCommandQueueWithProperties} is -{cl_command_queue_properties_TYPE}. -While this is not a promotion in terms of the suffixing, both types -are aliased to {cl_ulong_TYPE}, so no ABI or compiler issues should -result if the extension and core APIs are supported. - +Applications that only target newer OpenCL devices should use the core +{clCreateCommandQueueWithProperties} API instead of this extension API. === New Commands @@ -48,8 +38,6 @@ result if the extension and core APIs are supported. * {cl_queue_properties_khr_TYPE} -//@ TODO Missing bitfield values allowed for CL_QUEUE_PROPERTIES? - === Version History * Revision 1.0.0, 2020-04-21 diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index b3b9d8f61..b8b7733c3 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -68,10 +68,6 @@ endif::cl_khr_create_command_queue[] include::{generated}/api/version-notes/CL_QUEUE_PROPERTIES.asciidoc[] | {cl_command_queue_properties_TYPE} - -ifdef::cl_khr_create_command_queue[] -or {cl_bitfield_TYPE} if the {cl_khr_create_command_queue_EXT} extension is supported -endif::cl_khr_create_command_queue[] | This is a bitfield and can be set to a combination of the following values: From 1fd459f09551abae6c02970a116d0fe3b06fbcb3 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Thu, 4 Apr 2024 07:35:45 -0700 Subject: [PATCH 33/71] bugfix: the geometric functions do not operate componentwise (#1137) --- OpenCL_C.txt | 5 ----- 1 file changed, 5 deletions(-) diff --git a/OpenCL_C.txt b/OpenCL_C.txt index b7a0d788f..5c27f1049 100644 --- a/OpenCL_C.txt +++ b/OpenCL_C.txt @@ -6537,13 +6537,8 @@ endif::cl_khr_fp16[] [open,refpage='geometricFunctions',desc='Geometric Functions',type='freeform',spec='clang',anchor='geometric-functions',xrefs='integerFunctions',alias='cross dot distance length normalize fast_distance fast_length fast_normalize'] -- -// TODO It is not actually true that these functions operate - -// TODO in general they *combine* components. - The <> describes the list of built-in geometric functions. -These all operate component-wise. -The description is per-component. The generic type name `gentypef` indicates that the function can take any of From 6892acbc5c9f002c673af9f2554a4292dfb06ec4 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Thu, 4 Apr 2024 11:18:29 -0700 Subject: [PATCH 34/71] update the quick reference list for finalized extensions (#1144) --- ext/quick_reference.asciidoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/ext/quick_reference.asciidoc b/ext/quick_reference.asciidoc index a040f1333..d583e39a1 100644 --- a/ext/quick_reference.asciidoc +++ b/ext/quick_reference.asciidoc @@ -98,11 +98,11 @@ Language Specifications. | [[cl_khr_external_memory]] link:{APISpecURL}#cl_khr_external_memory[{cl_khr_external_memory_EXT}] | Common Functionality for External Memory Sharing -| Provisional Extension +| Extension | [[cl_khr_external_memory_dma_buf]] link:{APISpecURL}#cl_khr_external_memory[{cl_khr_external_memory_dma_buf_EXT}] | dma_buf External Memory Handles -| Provisional Extension +| Extension | [[cl_khr_external_memory_dx]] link:{APISpecURL}#cl_khr_external_memory[{cl_khr_external_memory_dx_EXT}] | Direct3D 11 and 12 External Memory Handles @@ -110,11 +110,11 @@ Language Specifications. | [[cl_khr_external_memory_opaque_fd]] link:{APISpecURL}#cl_khr_external_memory[{cl_khr_external_memory_opaque_fd_EXT}] | Opaque File Descriptor External Memory Handles -| Provisional Extension +| Extension | [[cl_khr_external_memory_win32]] link:{APISpecURL}#cl_khr_external_memory[{cl_khr_external_memory_win32_EXT}] | NT Handle External Memory Handles -| Provisional Extension +| Extension | [[cl_khr_expect_assume]] link:{APISpecURL}#cl_khr_expect_assume[{cl_khr_expect_assume_EXT}] | Kernel Optimization Hints @@ -122,7 +122,7 @@ Language Specifications. | [[cl_khr_external_semaphore]] link:{APISpecURL}#cl_khr_external_semaphore[{cl_khr_external_semaphore_EXT}] | Common Functionality for External Semaphore Sharing -| Provisional Extension +| Extension | [[cl_khr_external_semaphore_dx_fence]] link:{APISpecURL}#cl_khr_external_semaphore[{cl_khr_external_semaphore_dx_fence_EXT}] | Direct3D 12 External Semaphore Handles @@ -130,11 +130,11 @@ Language Specifications. | [[cl_khr_external_semaphore_opaque_fd]] link:{APISpecURL}#cl_khr_external_semaphore[{cl_khr_external_semaphore_opaque_fd_EXT}] | Opaque File Descriptor External Semaphore Handles -| Provisional Extension +| Extension | [[cl_khr_external_semaphore_sync_fd]] link:{APISpecURL}#cl_khr_external_semaphore[{cl_khr_external_semaphore_sync_fd_EXT}] | Sync FD External Semaphore Handles -| Provisional Extension +| Extension | [[cl_khr_external_semaphore_win32]] link:{APISpecURL}#cl_khr_external_semaphore[{cl_khr_external_semaphore_win32_EXT}] | NT Handle External Semaphore Handles @@ -230,7 +230,7 @@ Language Specifications. | [[cl_khr_semaphore]] link:{APISpecURL}#cl_khr_semaphore[{cl_khr_semaphore_EXT}] | Semaphore Synchronization Primitives -| Provisional Extension +| Extension | [[cl_khr_spir]] link:{APISpecURL}#cl_khr_spir[{cl_khr_spir_EXT}] | Standard Portable Intermediate Representation Programs From 16880f9276828e66bb97017f10f34f97423d1bcf Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Thu, 4 Apr 2024 11:28:56 -0700 Subject: [PATCH 35/71] change log with changes from v3.0.15 (#1126) * initial change log with changes from v3.0.15 * update cl_khr_kernel_clock link in a few other places * final change log updates --- api/appendix_e.asciidoc | 21 ++++++++++++++++++++- c/appendix_a.asciidoc | 9 +++++++++ env/appendix_a.asciidoc | 7 +++++++ 3 files changed, 36 insertions(+), 1 deletion(-) diff --git a/api/appendix_e.asciidoc b/api/appendix_e.asciidoc index eebc7ff2d..9df39d32f 100644 --- a/api/appendix_e.asciidoc +++ b/api/appendix_e.asciidoc @@ -601,5 +601,24 @@ Changes from *v3.0.14*: Changes from *v3.0.15*: - * Added new extensions: + * Moved all KHR extension text out of the OpenCL Extension specification and into the main specifications. + The OpenCL Extension specification will be removed in a subsequent revision. + * Clarified several error conditions that could return {CL_INVALID_PLATFORM}, see {khronos-opencl-pr}/1063[#1063]. + * Strengthened requirements for the {CL_DEVICE_TYPE} query, see {khronos-opencl-pr}/1069[#1069]. + * Clarified {clSetEventCallback} behavior for command errors, see {khronos-opencl-pr}/1071[#1071]. + * Moved footnote text for {CL_KERNEL_ARG_TYPE_QUALIFIER} into the main spec, see {khronos-opencl-pr}/1097[#1097]. + * {cl_khr_command_buffer_mutable_dispatch_EXT} (provisional): + ** Added {CL_MUTABLE_DISPATCH_ASSERTS_KHR}, see {khronos-opencl-pr}/992[#992]. + * {cl_khr_semaphore_EXT}: + ** Removed a redundant error condition, see {khronos-opencl-pr}/1052[#1052] + * The following extensions have been finalized and are no longer provisional: + ** {cl_khr_semaphore_EXT} + ** {cl_khr_external_semaphore_EXT} + ** {cl_khr_external_semaphore_opaque_fd_EXT} + ** {cl_khr_external_semaphore_sync_fd_EXT} + ** {cl_khr_external_memory_EXT} + ** {cl_khr_external_memory_dma_buf_EXT} + ** {cl_khr_external_memory_opaque_fd_EXT} + ** {cl_khr_external_memory_win32_EXT} + * Added new extension: ** {cl_khr_kernel_clock_EXT} (provisional) diff --git a/c/appendix_a.asciidoc b/c/appendix_a.asciidoc index 711fe7c39..2492e585d 100644 --- a/c/appendix_a.asciidoc +++ b/c/appendix_a.asciidoc @@ -43,3 +43,12 @@ Changes from *v3.0.14*: * Clarified that the *nextafter* built-in function works with all floating-point types, see {khronos-opencl-pr}/953[#953]. * Clarified that the async copy and wait group events built-in functions must be called within converged control flow, see {khronos-opencl-pr}/1015[#1015]. * Removed unnecessary rounding mode text from the descriptions of the geometric and common functions, see {khronos-opencl-pr}/1027[#1027]. + +Changes from *v3.0.15*: + + * Moved all KHR extension text out of the OpenCL Extension specification and into the main specifications. + The OpenCL Extension specification will be removed in a subsequent revision. + * Fixed the derived formula for `atanh`, see {khronos-opencl-pr}/1048[#1048]. + * Removed an incorrect statement about geometric functions operating component-wise, see {khronos-opencl-pr}/1137[#1137]. + * Added new extension: + ** {cl_khr_kernel_clock_EXT} (provisional) diff --git a/env/appendix_a.asciidoc b/env/appendix_a.asciidoc index 2c58efbf9..e385a0e45 100644 --- a/env/appendix_a.asciidoc +++ b/env/appendix_a.asciidoc @@ -43,3 +43,10 @@ Changes from *v3.0.8*: Changes from *v3.0.14*: * Fixed several numerical compliance bugs, see {khronos-opencl-pr}/937[#937]. + +Changes from *v3.0.15*: + + * Clarified that 16-bit and 64-bit floats can be passed as kernel arguments to SPIR-V kernels, see {khronos-opencl-pr}/1049[#1049]. + * Adds the numerical value of the image channel order and image channel data type to several tables, see {khronos-opencl-pr}/1050[#1050]. + * Added new extension: + ** {cl_khr_kernel_clock_EXT} (provisional) From 26712b2dcc6581c871a412e5db8b8348348391ba Mon Sep 17 00:00:00 2001 From: Jon Leech <4693344+oddhack@users.noreply.github.com> Date: Mon, 8 Apr 2024 09:34:11 -0700 Subject: [PATCH 36/71] Fix a typo in the category ToC for the refpages (#1148) * Fix a typo in the category ToC for the refpages * Also fix a typo * One more typo --- man/toctail | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/man/toctail b/man/toctail index 82092a1ce..608ff7913 100644 --- a/man/toctail +++ b/man/toctail @@ -299,7 +299,7 @@
  • create_user_event
  • is_valid_event
  • set_user_event_status
    • -
  • capture_event_profiling_info
    • +
  • capture_event_profiling_info
    • @@ -363,7 +363,7 @@
  • mad24
  • mad_hi
  • mad_sat
    • -
  • ma
    • +
  • max
  • min
  • mul24
  • mul_hi
    • @@ -412,7 +412,7 @@
  • fdim
  • floor
  • fma
    • -
  • fma
    • +
  • fmax
  • fmin
  • fmod
  • fract
    • From b6c9d441a946c660765daa1b5ecf5bc06a5ae75b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Tue, 14 May 2024 13:38:40 +0100 Subject: [PATCH 37/71] Add two missing extensions to extension.txt (#1162) Change-Id: I44c78179ad6cfe9fc6da656aee72cae7adc0bf90 Signed-off-by: Kevin Petit --- extensions/extensions.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/extensions/extensions.txt b/extensions/extensions.txt index acf843e84..573ec1169 100644 --- a/extensions/extensions.txt +++ b/extensions/extensions.txt @@ -40,6 +40,8 @@ include::cl_ext_float_atomics.asciidoc[] <<< include::cl_ext_image_from_buffer.asciidoc[] <<< +include::cl_ext_image_raw10_raw12.asciidoc[] +<<< include::cl_ext_image_requirements_info.asciidoc[] // Vendor Extensions @@ -61,6 +63,8 @@ include::cl_arm_scheduling_controls.asciidoc[] <<< include::cl_img_cached_allocations.asciidoc[] <<< +include::cl_img_cancel_command.asciidoc[] +<<< include::cl_img_generate_mipmap.asciidoc[] <<< include::cl_img_mem_properties.asciidoc[] From b041b2f84cbe6b9a17f0540d6b2449d3b4bf1b20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Tue, 14 May 2024 17:13:29 +0100 Subject: [PATCH 38/71] Define extension macros in environment specification (#1163) This was missed during the spec unification work. Change-Id: I23107b104431abdac2eaf8a3b1ebedd10303fc12 Signed-off-by: Kevin Petit --- OpenCL_Env.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/OpenCL_Env.txt b/OpenCL_Env.txt index 96b07f4ee..d504cd504 100644 --- a/OpenCL_Env.txt +++ b/OpenCL_Env.txt @@ -2,6 +2,10 @@ // Creative Commons Attribution 4.0 International License; see // http://creativecommons.org/licenses/by/4.0/ +// Extensions to enable +// Must be included before the header and attribs.txt +include::{generated}/specattribs.adoc[] + = The OpenCL^(TM)^ SPIR-V Environment Specification :R: pass:q,r[^(R)^] Khronos{R} OpenCL Working Group From ffa3f8e92bac3b3427cca51a215190c253875ae1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Tue, 14 May 2024 18:12:48 +0100 Subject: [PATCH 39/71] Remove unused cl_khr_external_memory_dx and cl_khr_external_semaphore_dx_fence extensions (#1160) No implementers (and no interest expressed), no CTS tests. These extensions should not be part of the specification. Change-Id: I064076c8075b5947ef9109558c4b03da426e4505 Signed-off-by: Kevin Petit --- api/cl_khr_external_memory_dx.asciidoc | 59 ---------------- api/cl_khr_external_semaphore.asciidoc | 3 +- ...l_khr_external_semaphore_dx_fence.asciidoc | 45 ------------ api/opencl_runtime_layer.asciidoc | 70 +------------------ ext/quick_reference.asciidoc | 8 --- xml/cl.xml | 26 +------ 6 files changed, 5 insertions(+), 206 deletions(-) delete mode 100644 api/cl_khr_external_memory_dx.asciidoc delete mode 100644 api/cl_khr_external_semaphore_dx_fence.asciidoc diff --git a/api/cl_khr_external_memory_dx.asciidoc b/api/cl_khr_external_memory_dx.asciidoc deleted file mode 100644 index ab742fea5..000000000 --- a/api/cl_khr_external_memory_dx.asciidoc +++ /dev/null @@ -1,59 +0,0 @@ -// Copyright 2021-2024 The Khronos Group Inc. -// SPDX-License-Identifier: CC-BY-4.0 - -include::{generated}/meta/{refprefix}cl_khr_external_memory_dx.txt[] - -=== Other Extension Metadata - -*Last Modified Date*:: - 2023-08-29 -*IP Status*:: - No known IP claims. -*Contributors*:: - - Ajit Hakke-Patil, NVIDIA - - Amit Rao, NVIDIA - - Balaji Calidas, QUALCOMM - - Ben Ashbaugh, INTEL - - Carsten Rohde, NVIDIA - - Christoph Kubisch, NVIDIA - - Debalina Bhattacharjee, NVIDIA - - Faith Ekstrand, INTEL - - James Jones, NVIDIA - - Jeremy Kemp, IMAGINATION - - Joshua Kelly, QUALCOMM - - Karthik Raghavan Ravi, NVIDIA - - Kedar Patil, NVIDIA - - Kevin Petit, ARM - - Nikhil Joshi, NVIDIA - - Sharan Ashwathnarayan, NVIDIA - - Vivek Kini, NVIDIA - -=== Description - -{cl_khr_external_memory_dx_EXT} extends -{cl_external_memory_handle_type_khr_TYPE} to support Windows handles -referring to Direct 3D resources as external memory handle types that may be -specified when creating a buffer or image memory object. - -=== New Enums - - * {cl_external_memory_handle_type_khr_TYPE} - ** {CL_EXTERNAL_MEMORY_HANDLE_D3D11_TEXTURE_KHR} - ** {CL_EXTERNAL_MEMORY_HANDLE_D3D11_TEXTURE_KMT_KHR} - ** {CL_EXTERNAL_MEMORY_HANDLE_D3D12_HEAP_KHR} - ** {CL_EXTERNAL_MEMORY_HANDLE_D3D12_RESOURCE_KHR} - -=== Version History - - * Revision 0.9.0, 2021-09-10 - ** Initial version (provisional). - * Revision 0.9.1, 2023-05-04 - ** Clarified device handle list enum cannot be specified without an - external memory handle (provisional). - * Revision 0.9.2, 2023-08-01 - ** Changed device handle list enum to the memory-specific - {CL_MEM_DEVICE_HANDLE_LIST_KHR} (provisional). - * Revision 0.9.3, 2023-08-29 - ** Added query for - {CL_DEVICE_EXTERNAL_MEMORY_IMPORT_ASSUME_LINEAR_IMAGES_HANDLE_TYPES_KHR} - (provisional). diff --git a/api/cl_khr_external_semaphore.asciidoc b/api/cl_khr_external_semaphore.asciidoc index 2b466ad5c..1bbf56796 100644 --- a/api/cl_khr_external_semaphore.asciidoc +++ b/api/cl_khr_external_semaphore.asciidoc @@ -65,8 +65,7 @@ This extension defines: semaphores created from different handle types. * API query exportable semaphores handles using specified handle type. -The layered extensions {cl_khr_external_semaphore_dx_fence_EXT}, -{cl_khr_external_semaphore_opaque_fd_EXT}, +The layered extensions {cl_khr_external_semaphore_opaque_fd_EXT}, {cl_khr_external_semaphore_sync_fd_EXT}, and {cl_khr_external_semaphore_win32_EXT} define specific external semaphores that may be imported into or exported from OpenCL. diff --git a/api/cl_khr_external_semaphore_dx_fence.asciidoc b/api/cl_khr_external_semaphore_dx_fence.asciidoc deleted file mode 100644 index e3cc259b3..000000000 --- a/api/cl_khr_external_semaphore_dx_fence.asciidoc +++ /dev/null @@ -1,45 +0,0 @@ -// Copyright 2021-2024 The Khronos Group Inc. -// SPDX-License-Identifier: CC-BY-4.0 - -include::{generated}/meta/{refprefix}cl_khr_external_semaphore_dx_fence.txt[] - -=== Other Extension Metadata - -*Last Modified Date*:: - 2021-09-10 -*IP Status*:: - No known IP claims. -*Contributors*:: - - Ajit Hakke-Patil, NVIDIA - - Amit Rao, NVIDIA - - Balaji Calidas, QUALCOMM - - Ben Ashbaugh, INTEL - - Carsten Rohde, NVIDIA - - Christoph Kubisch, NVIDIA - - Debalina Bhattacharjee, NVIDIA - - Faith Ekstrand, INTEL - - James Jones, NVIDIA - - Jeremy Kemp, IMAGINATION - - Joshua Kelly, QUALCOMM - - Karthik Raghavan Ravi, NVIDIA - - Kedar Patil, NVIDIA - - Kevin Petit, ARM - - Nikhil Joshi, NVIDIA - - Sharan Ashwathnarayan, NVIDIA - - Vivek Kini, NVIDIA - -=== Description - -{cl_khr_external_semaphore_dx_fence_EXT} supports importing and exporting a -D3D12 fence as an external semaphore using the APIs introduced by -{cl_khr_external_semaphore_EXT}. - -=== New Enums - - * {cl_external_semaphore_handle_type_khr_TYPE} - ** {CL_SEMAPHORE_HANDLE_D3D12_FENCE_KHR} - -=== Version History - - * Revision 0.9.0, 2021-09-10 - ** Initial version (provisional). diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index b8b7733c3..bfa16ffd1 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -5597,32 +5597,6 @@ The imported memory object holds a reference to its payload. ==== NT Handle Types -ifdef::cl_khr_external_memory_dx[] -The {cl_khr_external_memory_dx_EXT} extension extends -{cl_external_memory_handle_type_khr_TYPE} to support the following new types -of handles, and adds as a property that may be specified when creating a -buffer or an image memory object from an external handle: - - * {CL_EXTERNAL_MEMORY_HANDLE_D3D11_TEXTURE_KHR_anchor} specifies an NT handle - returned by `IDXGIResource1::CreateSharedHandle` referring to a Direct3D - 10 or 11 texture resource. - It owns a reference to the memory used by the Direct3D resource. - * {CL_EXTERNAL_MEMORY_HANDLE_D3D11_TEXTURE_KMT_KHR_anchor} specifies a global - share handle returned by `IDXGIResource::GetSharedHandle` referring to a - Direct3D 10 or 11 texture resource. - It does not own a reference to the underlying Direct3D resource, and - will therefore become invalid when all memory objects and Direct3D - resources associated with it are destroyed. - * {CL_EXTERNAL_MEMORY_HANDLE_D3D12_HEAP_KHR_anchor} specifies an NT handle - returned by `ID3D12Device::CreateSharedHandle` referring to a Direct3D - 12 heap resource. - It owns a reference to the resources used by the Direct3D heap. - * {CL_EXTERNAL_MEMORY_HANDLE_D3D12_RESOURCE_KHR_anchor} specifies an NT handle - returned by `ID3D12Device::CreateSharedHandle` referring to a Direct3D - 12 committed resource. - It owns a reference to the memory used by the Direct3D resource. -endif::cl_khr_external_memory_dx[] - ifdef::cl_khr_external_memory_win32[] The {cl_khr_external_memory_win32_EXT} extension extends {cl_external_memory_handle_type_khr_TYPE} to support the following new types @@ -13128,42 +13102,10 @@ endif::cl_khr_external_semaphore_sync_fd[] endif::cl_khr_external_semaphore_opaque_fd,cl_khr_external_semaphore_sync_fd[] -ifdef::cl_khr_external_semaphore_dx_fence,cl_khr_external_semaphore_win32[] +ifdef::cl_khr_external_semaphore_win32[] ==== NT Handle Types -ifdef::cl_khr_external_semaphore_dx_fence[] - -The {cl_khr_external_semaphore_dx_fence_EXT} extension extends -{cl_external_semaphore_handle_type_khr_TYPE} to support the following new -types of handles, and adds as a property that may be specified when creating -a semaphore from an external handle: - - * {CL_SEMAPHORE_HANDLE_D3D12_FENCE_KHR} specifies an NT handle returned by - `ID3D12Device::CreateSharedHandle` referring to a Direct3D 12 fence, or - `ID3D11Device5::CreateFence` referring to a Direct3D 11 fence. - It owns a reference to the underlying synchronization primitive - associated with the Direct3D fence. - -When waiting on semaphores using {clEnqueueWaitSemaphoresKHR} or signaling -semaphores using {clEnqueueSignalSemaphoresKHR}, the semaphore payload must -be provided for semaphores created from -{CL_SEMAPHORE_HANDLE_D3D12_FENCE_KHR}. - - * If _sema_objects_ list has a mix of semaphores obtained from - {CL_SEMAPHORE_HANDLE_D3D12_FENCE_KHR} and other handle types, then the - _sema_payload_list_ should point to a list of _num_sema_objects_ payload - values for each semaphore in _sema_objects_. - However, the payload values corresponding to semaphores with type - {CL_SEMAPHORE_TYPE_BINARY_KHR} can be set to 0 or will be ignored. - -{clEnqueueWaitSemaphoresKHR} and {clEnqueueSignalSemaphoresKHR} may return -{CL_INVALID_VALUE} if _sema_objects_ list has one or more semaphores -obtained from {CL_SEMAPHORE_HANDLE_D3D12_FENCE_KHR} and _sema_payload_list_ -is NULL. - -endif::cl_khr_external_semaphore_dx_fence[] - ifdef::cl_khr_external_semaphore_win32[] The {cl_khr_external_semaphore_win32_EXT} extension extends @@ -13193,14 +13135,6 @@ endif::cl_khr_external_semaphore_win32[] |==== | Handle Type | Transference | Permanence -ifdef::cl_khr_external_semaphore_dx_fence[] -| {CL_SEMAPHORE_HANDLE_D3D12_FENCE_KHR_anchor} - -include::{generated}/api/version-notes/CL_SEMAPHORE_HANDLE_D3D12_FENCE_KHR.asciidoc[] - | Reference - | Temporary, Permanent -endif::cl_khr_external_semaphore_dx_fence[] - ifdef::cl_khr_external_semaphore_win32[] | {CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KHR_anchor} @@ -13223,7 +13157,7 @@ For handle types defined as NT handles, the application must release ownership using the `CloseHandle` system call when the handle is no longer needed. -endif::cl_khr_external_semaphore_dx_fence,cl_khr_external_semaphore_win32[] +endif::cl_khr_external_semaphore_win32[] endif::cl_khr_external_semaphore[] diff --git a/ext/quick_reference.asciidoc b/ext/quick_reference.asciidoc index d583e39a1..804c30fae 100644 --- a/ext/quick_reference.asciidoc +++ b/ext/quick_reference.asciidoc @@ -104,10 +104,6 @@ Language Specifications. | dma_buf External Memory Handles | Extension -| [[cl_khr_external_memory_dx]] link:{APISpecURL}#cl_khr_external_memory[{cl_khr_external_memory_dx_EXT}] -| Direct3D 11 and 12 External Memory Handles -| Provisional Extension - | [[cl_khr_external_memory_opaque_fd]] link:{APISpecURL}#cl_khr_external_memory[{cl_khr_external_memory_opaque_fd_EXT}] | Opaque File Descriptor External Memory Handles | Extension @@ -124,10 +120,6 @@ Language Specifications. | Common Functionality for External Semaphore Sharing | Extension -| [[cl_khr_external_semaphore_dx_fence]] link:{APISpecURL}#cl_khr_external_semaphore[{cl_khr_external_semaphore_dx_fence_EXT}] -| Direct3D 12 External Semaphore Handles -| Provisional Extension - | [[cl_khr_external_semaphore_opaque_fd]] link:{APISpecURL}#cl_khr_external_semaphore[{cl_khr_external_semaphore_opaque_fd_EXT}] | Opaque File Descriptor External Semaphore Handles | Extension diff --git a/xml/cl.xml b/xml/cl.xml index 6f1ae87bd..7700355ad 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -1888,14 +1888,11 @@ server's OpenCL/api-docs repository. - + - - - - + @@ -7057,14 +7054,6 @@ server's OpenCL/api-docs repository.     - - - - - - - - @@ -7131,17 +7120,6 @@ server's OpenCL/api-docs repository. - - - - - - - - - - - From 0483627299b70d42c4d19bb6acc8b1edcd3a2704 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Tue, 14 May 2024 19:01:17 +0100 Subject: [PATCH 40/71] Mention dependency on SPV_EXT_shader_atomic_float16_add in cl_ext_float_atomics (#1153) The AtomicFloat16AddEXT capability it defines is referred to. Change-Id: Icbae5f1ad02561e11517a47e9640eea4bc6a4283 Signed-off-by: Kevin Petit --- extensions/cl_ext_float_atomics.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/cl_ext_float_atomics.asciidoc b/extensions/cl_ext_float_atomics.asciidoc index ad4ab26fc..c3ae27883 100644 --- a/extensions/cl_ext_float_atomics.asciidoc +++ b/extensions/cl_ext_float_atomics.asciidoc @@ -93,7 +93,7 @@ The functionality added by this extension uses the OpenCL C 2.0 atomic syntax an This extension interacts with `cl_khr_fp16` by optionally adding the ability to atomically operate on 16-bit floating-point values in memory. -This extension depends on `SPV_EXT_shader_atomic_float_add` and `SPV_EXT_shader_atomic_float_min_max` for implementations that support SPIR-V and floating-point atomic add, min, or max operations. +This extension depends on `SPV_EXT_shader_atomic_float_add`, `SPV_EXT_shader_atomic_float16_add`, and `SPV_EXT_shader_atomic_float_min_max` for implementations that support SPIR-V and floating-point atomic add, min, or max operations. == Overview From 6c8fcb44f3068e03b30c8d60bb67109a9b433ae4 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 20 May 2024 21:39:54 -0700 Subject: [PATCH 41/71] remove an extra character in an OpenCL C example (#1172) --- OpenCL_C.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OpenCL_C.txt b/OpenCL_C.txt index 5c27f1049..610b54e3c 100644 --- a/OpenCL_C.txt +++ b/OpenCL_C.txt @@ -1534,7 +1534,7 @@ For example: ---------- float8 vf; -float *f = &vf.x; m // is illegal +float *f = &vf.x; // is illegal float2 *f2 = &vf.s07; // is illegal float4 *odd = &vf.odd; // is illegal From 13ecb483a89755c2d5ece3032bea946a59a3c195 Mon Sep 17 00:00:00 2001 From: Ewan Crawford Date: Tue, 21 May 2024 17:47:46 +0100 Subject: [PATCH 42/71] Add revision to XML extensions (#1161) This extension adds the revision field to the XML tag for extensions. This allows a version macro to be generated with: * https://github.com/KhronosGroup/OpenCL-Headers/pull/251 * https://github.com/KhronosGroup/OpenCL-Headers/issues/248 KHR extensions are given a revision based on the semantic version of the spec. However other extensions don't use semantic versioning, and so are given a placeholder `0.0.0` value until they can be updated by the owner. The XML schema is also updated to make the revision field mandatory in the XML entry for extensions and the existence of the macro this enables is advertised to users in the spec. --- api/opencl_architecture.asciidoc | 19 +++ xml/cl.xml | 254 +++++++++++++++---------------- xml/registry.rnc | 4 +- 3 files changed, 148 insertions(+), 129 deletions(-) diff --git a/api/opencl_architecture.asciidoc b/api/opencl_architecture.asciidoc index 2e559530c..57cc2c17d 100644 --- a/api/opencl_architecture.asciidoc +++ b/api/opencl_architecture.asciidoc @@ -2263,6 +2263,25 @@ typedef cl_uint cl_version; ((patch) & CL_VERSION_PATCH_MASK)) ---- +[NOTE] +-- +The available version of an extension is exposed to the user via a macro +defined by the OpenCL Headers. This macro takes the format of the uppercase +extension name followed by the `_EXTENSION_VERSION` suffix. For example, +`CL_KHR_SEMAPHORE_EXTENSION_VERSION` is the macro defining the version of the +{cl_khr_semaphore_EXT} extension. + +The value of this macro is set to the {cl_version_TYPE} of the extension using +the semantic version of the extension. If no semantic version is defined for +the extension, then the value of the macro is set to `0` to represent semantic +version `0.0.0`. + +Applications can use these version macros along with the convience macros +defined in this section to guard their code against breaking changes to the API +of extensions, in particular provisional KHR extensions which have yet to +finalize an API. +-- + [[version-name-pairing]] ==== Version-Name Pairing diff --git a/xml/cl.xml b/xml/cl.xml index 7700355ad..bca2621d9 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -5389,7 +5389,7 @@ server's OpenCL/api-docs repository. - + @@ -5436,7 +5436,7 @@ server's OpenCL/api-docs repository. - + @@ -5483,7 +5483,7 @@ server's OpenCL/api-docs repository. - + @@ -5532,7 +5532,7 @@ server's OpenCL/api-docs repository. - + @@ -5560,7 +5560,7 @@ server's OpenCL/api-docs repository. - + @@ -5574,7 +5574,7 @@ server's OpenCL/api-docs repository. - + @@ -5582,7 +5582,7 @@ server's OpenCL/api-docs repository. - + @@ -5590,7 +5590,7 @@ server's OpenCL/api-docs repository. - + @@ -5598,7 +5598,7 @@ server's OpenCL/api-docs repository. - + @@ -5608,7 +5608,7 @@ server's OpenCL/api-docs repository. - + @@ -5622,7 +5622,7 @@ server's OpenCL/api-docs repository. - + @@ -5642,7 +5642,7 @@ server's OpenCL/api-docs repository. - + @@ -5659,7 +5659,7 @@ server's OpenCL/api-docs repository. - + @@ -5673,13 +5673,13 @@ server's OpenCL/api-docs repository. - + - + @@ -5694,7 +5694,7 @@ server's OpenCL/api-docs repository. - + @@ -5717,7 +5717,7 @@ server's OpenCL/api-docs repository. - + @@ -5728,7 +5728,7 @@ server's OpenCL/api-docs repository. - + @@ -5739,7 +5739,7 @@ server's OpenCL/api-docs repository. - + @@ -5753,7 +5753,7 @@ server's OpenCL/api-docs repository. - + @@ -5781,7 +5781,7 @@ server's OpenCL/api-docs repository. - + @@ -5790,7 +5790,7 @@ server's OpenCL/api-docs repository. - + @@ -5834,7 +5834,7 @@ server's OpenCL/api-docs repository. - + @@ -5851,7 +5851,7 @@ server's OpenCL/api-docs repository. - + @@ -5880,7 +5880,7 @@ server's OpenCL/api-docs repository. - + @@ -5888,7 +5888,7 @@ server's OpenCL/api-docs repository. - + @@ -5900,7 +5900,7 @@ server's OpenCL/api-docs repository. - + @@ -5912,7 +5912,7 @@ server's OpenCL/api-docs repository. - + @@ -5921,7 +5921,7 @@ server's OpenCL/api-docs repository. - + @@ -5930,7 +5930,7 @@ server's OpenCL/api-docs repository. - + @@ -5940,7 +5940,7 @@ server's OpenCL/api-docs repository. - + @@ -5960,7 +5960,7 @@ server's OpenCL/api-docs repository. - + @@ -5975,7 +5975,7 @@ server's OpenCL/api-docs repository. - + @@ -5991,7 +5991,7 @@ server's OpenCL/api-docs repository. - + @@ -6007,7 +6007,7 @@ server's OpenCL/api-docs repository. - + @@ -6015,7 +6015,7 @@ server's OpenCL/api-docs repository. - + @@ -6053,7 +6053,7 @@ server's OpenCL/api-docs repository. - + @@ -6101,7 +6101,7 @@ server's OpenCL/api-docs repository. - + @@ -6109,7 +6109,7 @@ server's OpenCL/api-docs repository. - + @@ -6118,13 +6118,13 @@ server's OpenCL/api-docs repository. - + - + @@ -6149,7 +6149,7 @@ server's OpenCL/api-docs repository. - + @@ -6176,7 +6176,7 @@ server's OpenCL/api-docs repository. - + @@ -6236,18 +6236,18 @@ server's OpenCL/api-docs repository. - + - + - + @@ -6255,7 +6255,7 @@ server's OpenCL/api-docs repository. - + @@ -6266,7 +6266,7 @@ server's OpenCL/api-docs repository. - + @@ -6278,7 +6278,7 @@ server's OpenCL/api-docs repository. - + @@ -6291,7 +6291,7 @@ server's OpenCL/api-docs repository. - + @@ -6443,7 +6443,7 @@ server's OpenCL/api-docs repository. - + @@ -6454,7 +6454,7 @@ server's OpenCL/api-docs repository. - + @@ -6495,7 +6495,7 @@ server's OpenCL/api-docs repository. - + @@ -6541,7 +6541,7 @@ server's OpenCL/api-docs repository. - + @@ -6552,7 +6552,7 @@ server's OpenCL/api-docs repository. - + @@ -6562,7 +6562,7 @@ server's OpenCL/api-docs repository. - + @@ -6623,7 +6623,7 @@ server's OpenCL/api-docs repository. - + @@ -6696,7 +6696,7 @@ server's OpenCL/api-docs repository. - + @@ -6709,7 +6709,7 @@ server's OpenCL/api-docs repository. - + @@ -6717,12 +6717,12 @@ server's OpenCL/api-docs repository. - + - + @@ -6733,7 +6733,7 @@ server's OpenCL/api-docs repository. - + @@ -6767,17 +6767,17 @@ server's OpenCL/api-docs repository. - + - + - + @@ -6785,7 +6785,7 @@ server's OpenCL/api-docs repository. - + @@ -6823,7 +6823,7 @@ server's OpenCL/api-docs repository. - + @@ -6838,7 +6838,7 @@ server's OpenCL/api-docs repository. - + @@ -6857,7 +6857,7 @@ server's OpenCL/api-docs repository. - + @@ -6882,7 +6882,7 @@ server's OpenCL/api-docs repository. - + @@ -6922,7 +6922,7 @@ server's OpenCL/api-docs repository. - + @@ -6933,7 +6933,7 @@ server's OpenCL/api-docs repository. - + @@ -6941,7 +6941,7 @@ server's OpenCL/api-docs repository. - + @@ -6980,7 +6980,7 @@ server's OpenCL/api-docs repository. - + @@ -7027,7 +7027,7 @@ server's OpenCL/api-docs repository. - + @@ -7054,7 +7054,7 @@ server's OpenCL/api-docs repository. - + @@ -7062,7 +7062,7 @@ server's OpenCL/api-docs repository. - + @@ -7085,7 +7085,7 @@ server's OpenCL/api-docs repository. - + @@ -7112,7 +7112,7 @@ server's OpenCL/api-docs repository. - + @@ -7120,7 +7120,7 @@ server's OpenCL/api-docs repository. - + @@ -7128,7 +7128,7 @@ server's OpenCL/api-docs repository. - + @@ -7137,37 +7137,37 @@ server's OpenCL/api-docs repository. - + - + - + - + - + - + - + @@ -7246,12 +7246,12 @@ server's OpenCL/api-docs repository. - + - + @@ -7272,7 +7272,7 @@ server's OpenCL/api-docs repository. - + @@ -7289,7 +7289,7 @@ server's OpenCL/api-docs repository. - + @@ -7306,12 +7306,12 @@ server's OpenCL/api-docs repository. - + - + @@ -7382,12 +7382,12 @@ server's OpenCL/api-docs repository. - + - + @@ -7422,41 +7422,41 @@ server's OpenCL/api-docs repository. - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -7464,7 +7464,7 @@ server's OpenCL/api-docs repository. - + diff --git a/xml/registry.rnc b/xml/registry.rnc index 210073c24..ff85c0d1d 100644 --- a/xml/registry.rnc +++ b/xml/registry.rnc @@ -445,7 +445,7 @@ Extensions = element extensions { # exactly match an API being generated (implicit ^$ surrounding). # name - extension name string # number - extension number (positive integer, should be unique) -# revision - extension spec revision (text, usually numeric major.minor.patch) +# revision - extension spec revision, must be numeric 'major.minor.patch' # sortorder - order relative to other extensions, default 0 # protect - C preprocessor symbol to conditionally define the interface # platform - should be one of the platform names defined in the @@ -479,8 +479,8 @@ Extensions = element extensions { # Not a regular expression. Extension = element extension { Name , + attribute revision { text }, attribute number { Integer } ? , - attribute revision { text } ? , attribute sortorder { xsd:integer } ?, attribute protect { text } ? , attribute platform { text } ? , From f37a8680e13a4ea965f33fbe3f944ca94c436705 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Tue, 4 Jun 2024 19:54:08 +0100 Subject: [PATCH 43/71] Fix links to commands in API specification (#1179) Links were not created for commands defined by extensions. With this changes all uses of e.g. {clCreateSemaphoreWithPropertiesKHR} link to the definition of the command which makes navigating the specification much easier. Change-Id: I4a9458609f4ba3229b66e3d169a68cb4564e2538 Signed-off-by: Kevin Petit --- scripts/gen_dictionaries.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/scripts/gen_dictionaries.py b/scripts/gen_dictionaries.py index 142fe55a4..4f220aa14 100755 --- a/scripts/gen_dictionaries.py +++ b/scripts/gen_dictionaries.py @@ -99,7 +99,7 @@ def GetFooter(): numberOfFuncs = numberOfFuncs + 1 - # Add extension API functions without links: + # Add extension API functions with and without links: for extension in spec.findall('extensions/extension/require'): for api in extension.findall('command'): name = api.get('name') @@ -110,7 +110,8 @@ def GetFooter(): # // clGetGLObjectInfo # :clGetGLObjectInfo: pass:q[*clGetGLObjectInfo*] apiLinkFile.write('// ' + name + '\n') - apiLinkFile.write(':' + name + ': pass:q[*' + name + '*]\n') + apiLinkFile.write(':' + name + '_label: pass:q[*' + name + '*]\n') + apiLinkFile.write(':' + name + ': <<' + name + ',{' + name + '_label}>>\n') apiLinkFile.write('\n') apiNoLinkFile.write('// ' + name + '\n') From f50c45856ca8c9789063a1dd2f3838b7ebc0db44 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Tue, 2 Jul 2024 17:08:30 +0100 Subject: [PATCH 44/71] Clarify the definition of prerequisites to commands (#923) * Clarify the definition of prerequisites to commands - Reword the first source of prerequisites so the wording is symmetrical with respect to the others (i.e. the first/second/third ...). - Broaden the first source of prerequisites to cover all implicit dependencies and provide an exhaustive list of how they arise: either because of barriers or because of ordering in in-order command-queues. Signed-off-by: Kevin Petit Change-Id: Ic464066261fe13756347bafb4878cd6ffb5a8427 * Update api/opencl_architecture.asciidoc --------- Signed-off-by: Kevin Petit --- api/opencl_architecture.asciidoc | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/api/opencl_architecture.asciidoc b/api/opencl_architecture.asciidoc index 57cc2c17d..63dc7d503 100644 --- a/api/opencl_architecture.asciidoc +++ b/api/opencl_architecture.asciidoc @@ -198,10 +198,12 @@ A command submitted to a device will not launch until prerequisites that constrain the order of commands have been resolved. These prerequisites have three sources: - * They may arise from commands submitted to a command-queue that constrain - the order in which commands are launched. - For example, commands that follow a command-queue barrier will not - launch until all commands prior to the barrier are complete. + * The first source of prerequisites is implicit dependencies between commands + enqueued to the same command-queue which arise as follows: + ** Commands enqueued after a command-queue barrier have the preceding barrier command + as a prerequisite. + ** Commands enqueued in an in-order command-queue have the command enqueued + before them as a prerequisite. * The second source of prerequisites is dependencies between commands expressed through events. A command may include an optional list of events. From c75e07fa6c254244b29358b5d8004f4659f91eb8 Mon Sep 17 00:00:00 2001 From: Jon Leech <4693344+oddhack@users.noreply.github.com> Date: Tue, 9 Jul 2024 08:54:27 -0700 Subject: [PATCH 45/71] Use Khronos asciidoctor-spec Docker image in CI (#1196) * Use Khronos asciidoctor-spec Docker image in CI Per discussion with $bashbaug N.b. at present the CI script has less parallelism than it could, at least as I understand Actions. Some of the 'steps' could be split off into 'jobs'. Might try that next once the basic build is working. Net performance is still somewhat faster than current CI since it's generally faster to load the container than to add needed packages at each invocation, and the spec build is pretty fast, so there's not much to be gained. There was odd error behavior from shifting to the container which I have never seen in Vulkan CI, having to do with mixed ownership of files in the checked-out repository. I inserted a brute-force workaround right after the checkout action. * Update image (SHA changed, though not contents) * Update to 20240702 Docker image which sets HOME=/tmp to avoid asciidoctor-pdf permission problems with tmpfiles in home directory / * Fix SHA and remove fixed parallel job limit on manhtmlpages build * Switch to '#!/usr/bin/env python3' shebang lines Since the Docker build image runs a python virtual environment now. Also added 'scripts/runDocker' script which will invoke docker locally with the same image used in Github CI, for testing. Note this script will pull over a GB of Docker stuff onto the machine it's invoked on, if the image is not already cached. * Empty commit to try and re-trigger the 'fatal' message... ... which appears sporadic, not easily replicable. * Try to bulletproof the git invocations in Makefile * Remove diagnostic job stage after bulletproofing (hopefully) the Makefile For future reference, some of the git operations in CI and the Makefile appear to *sporadically* fail in CI because of different checked-out repo configurations. I modified the 'git symbolic-ref' and 'git log' operations invoked from the Makefile to detect errors and substitute a placeholder message, based on similar changes to the Vulkan Makefile a while back. This (appears) to eliminate the sporadic 'fatal' messages. We may need to do that to the 'git describe' as well. None of this reads on the generated artifacts, except that they may or may not contain accurate tag / commit comments. --- .github/workflows/presubmit.yml | 55 ++++++++++++++++------------ Makefile | 6 ++- scripts/apiconventions.py | 2 +- scripts/cgenerator.py | 2 +- scripts/checklinks.py | 2 +- scripts/clconventions.py | 2 +- scripts/docgenerator.py | 2 +- scripts/extensionmetadocgenerator.py | 2 +- scripts/genRef.py | 2 +- scripts/gen_dictionaries.py | 2 +- scripts/gen_version_notes.py | 2 +- scripts/gencl.py | 2 +- scripts/generator.py | 2 +- scripts/parse_dependency.py | 2 +- scripts/pygenerator.py | 2 +- scripts/realign.py | 2 +- scripts/reflib.py | 2 +- scripts/reg.py | 2 +- scripts/runDocker | 30 +++++++++++++++ scripts/scriptgenerator.py | 2 +- scripts/spec_tools/conventions.py | 2 +- 21 files changed, 83 insertions(+), 44 deletions(-) create mode 100755 scripts/runDocker diff --git a/.github/workflows/presubmit.yml b/.github/workflows/presubmit.yml index 605571254..6a2d54b32 100644 --- a/.github/workflows/presubmit.yml +++ b/.github/workflows/presubmit.yml @@ -3,47 +3,54 @@ name: Presubmit permissions: contents: read -on: [push, pull_request] +# Controls when the action will run. +on: + push: + workflow_dispatch: + pull_request: +# These jobs are potentially parallelizeable jobs: build: - name: Build all specs + name: Build spec artifacts runs-on: ubuntu-latest + # Refer to the build container by its SHA instead of the name, to + # prevent caching problems when updating the image. + # container: khronosgroup/docker-images:asciidoctor-spec.20240702 + container: khronosgroup/docker-images@sha256:4aab96a03ef292439c9bd0f972adfa29cdf838d0909b1cb4ec2a6d7b2d14a37f steps: - uses: actions/checkout@v4 with: - fetch-depth: 0 submodules: recursive + # If fetch-depth: 0 is not specified, then + # git describe --tags --dirty + # below fails. + # This could also affect SPECREVISION in the Makefile. + fetch-depth: 0 - - name: Install required packages + # Ownerships in the working directory are odd. + # . is owned by UID 1001, while repo files are owned by root. + # This leads to many odd messages like + # fatal: detected dubious ownership in repository at '/__w/OpenCL-Docs/OpenCL-Docs' + # The 'git config' is a brute-force workaround. + - name: Git safe directory workaround run: | - sudo apt-get install -y libpango1.0-dev libwebp-dev ghostscript fonts-lyx jing libavalon-framework-java libbatik-java python3-pyparsing - sudo gem install asciidoctor -v 2.0.16 - sudo gem install coderay -v 1.1.1 - sudo gem install rouge -v 3.19.0 - sudo gem install ttfunk -v 1.7.0 - sudo gem install hexapdf -v 0.27.0 - sudo gem install asciidoctor-pdf -v 2.3.4 - sudo gem install asciidoctor-mathematical -v 0.3.5 - sudo pip install pyparsing - - - name: List git tag + git config --global --add safe.directory '*' + ls -lda . .. .git Makefile + + - name: Validate XML run: | - git describe --tags --dirty + make -C xml validate - name: Generate core specs (HTML and PDF) run: | - python3 makeSpec -clean -spec core OUTDIR=out.core -j 5 api c env ext cxx4opencl - + python3 makeSpec -clean -spec core OUTDIR=out.core -j 5 -O api c env ext cxx4opencl + - name: Generate core + extension specs (HTML) run: | - python3 makeSpec -clean -spec khr OUTDIR=out.khr -j 12 html + python3 makeSpec -clean -spec khr OUTDIR=out.khr -j -O html - name: Generate reference pages run: | - python3 makeSpec -spec khr OUTDIR=out.refpages -j 12 manhtmlpages - - - name: Validate XML - run: | - make -C xml validate + python3 makeSpec -spec khr OUTDIR=out.refpages -j -O manhtmlpages diff --git a/Makefile b/Makefile index 1540b8343..c2e00d073 100644 --- a/Makefile +++ b/Makefile @@ -14,6 +14,7 @@ EXTOPTIONS := $(foreach ext,$(EXTS),-extension $(ext)) QUIET ?= VERYQUIET ?= @ +PYTHON ?= python3 ASCIIDOCTOR ?= asciidoctor RM = rm -f RMRF = rm -rf @@ -72,8 +73,8 @@ SPECREVISION = $(shell echo `git describe --tags --dirty`) # This used to be a dependency in the spec html/pdf targets, # but that's likely to lead to merge conflicts. Just regenerate # when pushing a new spec for review to the sandbox. -SPECREMARK = from git branch: $(shell echo `git symbolic-ref --short HEAD`) \ - commit: $(shell echo `git log -1 --format="%H"`) +SPECREMARK = from git branch: $(shell echo `git symbolic-ref --short HEAD 2> /dev/null || echo Git branch not available`) \ + commit: $(shell echo `git log -1 --format="%H" 2> /dev/null || echo Git commit not available`) endif # The C++ for OpenCL document revision scheme is aligned with its release date. # Revision naming scheme is as follows: @@ -545,6 +546,7 @@ $(METADEPEND): $(APIXML) $(GENSCRIPT) attribs: $(ATTRIBFILE) $(ATTRIBFILE): + $(QUIET)$(MKDIR) $(dir $@) for attrib in $(EXTS) ; do \ echo ":$${attrib}:" ; \ done > $@ diff --git a/scripts/apiconventions.py b/scripts/apiconventions.py index 4d27d04f9..f16dcd479 100644 --- a/scripts/apiconventions.py +++ b/scripts/apiconventions.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 -i +#!/usr/bin/env python3 -i # # Copyright 2021-2024 The Khronos Group Inc. # SPDX-License-Identifier: Apache-2.0 diff --git a/scripts/cgenerator.py b/scripts/cgenerator.py index f86658ee0..713113c02 100644 --- a/scripts/cgenerator.py +++ b/scripts/cgenerator.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 -i +#!/usr/bin/env python3 -i # # Copyright 2013-2024 The Khronos Group Inc. # diff --git a/scripts/checklinks.py b/scripts/checklinks.py index 816f601a7..5d79a676c 100755 --- a/scripts/checklinks.py +++ b/scripts/checklinks.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 +#!/usr/bin/env python3 # # Copyright 2013-2024 The Khronos Group Inc. # SPDX-License-Identifier: Apache-2.0 diff --git a/scripts/clconventions.py b/scripts/clconventions.py index c561eb73d..734041ae1 100644 --- a/scripts/clconventions.py +++ b/scripts/clconventions.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 -i +#!/usr/bin/env python3 -i # # Copyright 2013-2024 The Khronos Group Inc. # SPDX-License-Identifier: Apache-2.0 diff --git a/scripts/docgenerator.py b/scripts/docgenerator.py index b714ef7c4..b8c2afd0a 100644 --- a/scripts/docgenerator.py +++ b/scripts/docgenerator.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 -i +#!/usr/bin/env python3 -i # # Copyright 2013-2024 The Khronos Group Inc. # diff --git a/scripts/extensionmetadocgenerator.py b/scripts/extensionmetadocgenerator.py index a200bab95..9f93a29e8 100644 --- a/scripts/extensionmetadocgenerator.py +++ b/scripts/extensionmetadocgenerator.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 -i +#!/usr/bin/env python3 -i # # Copyright 2013-2024 The Khronos Group Inc. # diff --git a/scripts/genRef.py b/scripts/genRef.py index 9b78fd0dc..2eabd231e 100755 --- a/scripts/genRef.py +++ b/scripts/genRef.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 +#!/usr/bin/env python3 # # Copyright 2016-2024 The Khronos Group Inc. # diff --git a/scripts/gen_dictionaries.py b/scripts/gen_dictionaries.py index 4f220aa14..e513385f6 100755 --- a/scripts/gen_dictionaries.py +++ b/scripts/gen_dictionaries.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 +#!/usr/bin/env python3 # Copyright 2019-2024 The Khronos Group Inc. # SPDX-License-Identifier: Apache-2.0 diff --git a/scripts/gen_version_notes.py b/scripts/gen_version_notes.py index 21271643d..d5cd81ff0 100755 --- a/scripts/gen_version_notes.py +++ b/scripts/gen_version_notes.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 +#!/usr/bin/env python3 # Copyright 2019-2024 The Khronos Group Inc. # SPDX-License-Identifier: Apache-2.0 diff --git a/scripts/gencl.py b/scripts/gencl.py index 04f821ced..9cc8a1d2c 100755 --- a/scripts/gencl.py +++ b/scripts/gencl.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 +#!/usr/bin/env python3 # # Copyright 2013-2024 The Khronos Group Inc. # diff --git a/scripts/generator.py b/scripts/generator.py index dea2ffa37..c534faf85 100644 --- a/scripts/generator.py +++ b/scripts/generator.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 -i +#!/usr/bin/env python3 -i # # Copyright 2013-2024 The Khronos Group Inc. # diff --git a/scripts/parse_dependency.py b/scripts/parse_dependency.py index 5d204959c..071d7b3c3 100755 --- a/scripts/parse_dependency.py +++ b/scripts/parse_dependency.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 +#!/usr/bin/env python3 # Copyright 2022-2024 The Khronos Group Inc. # Copyright 2003-2019 Paul McGuire diff --git a/scripts/pygenerator.py b/scripts/pygenerator.py index 6656b4605..8656587e9 100644 --- a/scripts/pygenerator.py +++ b/scripts/pygenerator.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 -i +#!/usr/bin/env python3 -i # # Copyright 2013-2024 The Khronos Group Inc. # diff --git a/scripts/realign.py b/scripts/realign.py index 495cb74ba..71f9f85eb 100755 --- a/scripts/realign.py +++ b/scripts/realign.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 +#!/usr/bin/env python3 # # Copyright 2013-2024 The Khronos Group Inc. # SPDX-License-Identifier: Apache-2.0 diff --git a/scripts/reflib.py b/scripts/reflib.py index 41fec4928..bd873a365 100644 --- a/scripts/reflib.py +++ b/scripts/reflib.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 +#!/usr/bin/env python3 # # Copyright 2016-2024 The Khronos Group Inc. # diff --git a/scripts/reg.py b/scripts/reg.py index b8f8af7ce..d5495212c 100755 --- a/scripts/reg.py +++ b/scripts/reg.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 -i +#!/usr/bin/env python3 -i # # Copyright 2013-2024 The Khronos Group Inc. # diff --git a/scripts/runDocker b/scripts/runDocker new file mode 100755 index 000000000..19bf00588 --- /dev/null +++ b/scripts/runDocker @@ -0,0 +1,30 @@ +#!/bin/bash +# Copyright 2022-2024 The Khronos Group Inc. +# SPDX-License-Identifier: Apache-2.0 + +# runDocker - run the Khronos `asciidoctor-spec` Docker image with a local +# clone of the specification repository. +# The following command-line tools are required to run this script: +# awk dirname docker grep id realpath +# These are all normal Linux developer tools except for 'docker' itself. + +# Determine path to repository root directory +scriptpath=`dirname $0` +repopath=`realpath $scriptpath/..` + +# Get SHA256 of the asciidoctor-spec image build used by CI. +image=`grep -m 1 khronosgroup/docker-images@sha256: $repopath/.github/workflows/presubmit.yml | \ + awk '{print $2}'` + +uid=`id -u` +gid=`id -g` +echo "Executing Docker with spec build image and mounted spec repository root:" + +# --user causes Docker to run as the specified UID:GID instead of as root +# -it runs interactively and uses a pseudotty +# --rm removes the container on exit +# -v mounts the repository clone as /vulkan in the container +# $image is image to run +# /bin/bash drops into a shell in the container +set -x +docker run --network=host --user ${uid}:${gid} -it --rm -v ${repopath}:/opencl $image /bin/bash diff --git a/scripts/scriptgenerator.py b/scripts/scriptgenerator.py index f5ed14d00..27339b26f 100644 --- a/scripts/scriptgenerator.py +++ b/scripts/scriptgenerator.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 -i +#!/usr/bin/env python3 -i # # Copyright 2013-2024 The Khronos Group Inc. # diff --git a/scripts/spec_tools/conventions.py b/scripts/spec_tools/conventions.py index 50ca75d41..190bd3b88 100644 --- a/scripts/spec_tools/conventions.py +++ b/scripts/spec_tools/conventions.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 -i +#!/usr/bin/env python3 -i # # Copyright 2013-2024 The Khronos Group Inc. # From fb2a15c2bb99860a3850cf3009f961185275bcb5 Mon Sep 17 00:00:00 2001 From: Sven van Haastregt Date: Tue, 9 Jul 2024 18:09:07 +0200 Subject: [PATCH 46/71] Fix typo in clCreateProgramWithSource introduction (#1204) Signed-off-by: Sven van Haastregt --- api/opencl_runtime_layer.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index bfa16ffd1..9609c2466 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -8362,7 +8362,7 @@ A program object encapsulates the following information: [open,refpage='clCreateProgramWithSource',desc='Creates a program object for a context, and loads source code specified by text strings into the program object.',type='protos'] -- -To creates a program object for a context and load source code into that +To create a program object for a context and load source code into that object, call the function include::{generated}/api/protos/clCreateProgramWithSource.txt[] From b6abbbdb13637076f651ab9237f87ee242a7d43a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Tue, 9 Jul 2024 17:25:03 +0100 Subject: [PATCH 47/71] Update extension template (#1197) - Update format for specification versions. We now use MAJOR.MINOR.PATCH as opposed to MAJOR.MINOR Revision PATCH. - Include generated dictionaries by default. Change-Id: Ie2cd8fc08ae6ec71d340bf9f274ffb17d8ebb118 Signed-off-by: Kevin Petit --- extensions/cl_extension_template.asciidoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/extensions/cl_extension_template.asciidoc b/extensions/cl_extension_template.asciidoc index 2020299c7..6666c6a96 100644 --- a/extensions/cl_extension_template.asciidoc +++ b/extensions/cl_extension_template.asciidoc @@ -5,6 +5,7 @@ :data-uri: :icons: font include::../config/attribs.txt[] +include::{generated}/api/api-dictionary.asciidoc[] :source-highlighter: coderay = cl_khr_extension_template @@ -137,8 +138,7 @@ Write dates in https://en.wikipedia.org/wiki/ISO_8601[ISO 8601] date format. == Dependencies -This extension is written against the OpenCL Specification -Version 1.0, Revision 1. +This extension is written against the OpenCL Specification version 3.X.Y. This extension requires OpenCL 1.0. @@ -498,6 +498,7 @@ best not to renumber issues, either. | 0.6.0 | 2020-04-20 | Alastair Murray | Use naming conventions in the new type example. | 0.7.0 | 2021-10-05 | Ben Ashbaugh | Added recommendation for bits in bitfields. | 0.8.0 | 2021-12-13 | Ben Ashbaugh | Added OpenCL C feature names section +| 0.9.0 | 2024-07-01 | Kévin Petit | Update format for spec version and include generated definitions. |==== **** From 40fbb793b6adfc1378469c4c2f83265ead69107b Mon Sep 17 00:00:00 2001 From: Sreelakshmi Haridas Maruthur Date: Tue, 9 Jul 2024 10:31:00 -0600 Subject: [PATCH 48/71] cl_khr_external_semaphore: Clarify language (#938) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * cl_khr_external_semaphore: Clarify language Refined the cl_khr_external_semaphore spec. Removed references to permanence which appear to have been leveraged from the Vulkan spec but don’t apply to the OpenCL spec in its current form. * Fix table format --- api/opencl_runtime_layer.asciidoc | 81 +++++++++---------------------- 1 file changed, 23 insertions(+), 58 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 9609c2466..cb32ecab4 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -12866,6 +12866,10 @@ ifdef::cl_khr_external_semaphore[] [open,refpage='clGetSemaphoreHandleForTypeKHR',desc='Export external handle from a semaphore',type='protos'] -- + +Export operations have the same transference as the specified handle type's import operations. Additionally, exporting a semaphore payload to a handle with copy transference has the same side effects on the source semaphore's payload as executing a semaphore wait operation. + +Please refer to handle specific documentation for more details on transference requirements per handle type. To export an external handle from a semaphore, call the function include::{generated}/api/protos/clGetSemaphoreHandleForTypeKHR.txt[] @@ -12919,53 +12923,19 @@ Otherwise, it returns one of the following errors: === Importing Semaphore External Handles -Applications can import a semaphore payload into an existing semaphore using -an external semaphore handle. -The effects of the import operation will be either temporary or permanent, -as specified by the application. -If the import is temporary, the implementation must restore the semaphore to -its prior permanent state after submitting the next semaphore wait -operation. -Performing a subsequent temporary import on a semaphore before performing a -semaphore wait has no effect on this requirement; the next wait submitted on -the semaphore must still restore its last permanent state. -A permanent payload import behaves as if the target semaphore was destroyed, -and a new semaphore was created with the same handle but the imported -payload. -Because importing a semaphore payload temporarily or permanently detaches -the existing payload from a semaphore, similar usage restrictions to those -applied to {clReleaseSemaphoreKHR} are applied to any command that imports a -semaphore payload. -Which of these import types is used is referred to as the import operation's -permanence. -Each handle type supports either one or both types of permanence. - -The implementation must perform the import operation by either referencing -or copying the payload referred to by the specified external semaphore -handle, depending on the handle's type. -The import method used is referred to as the handle type's transference. -When using handle types with reference transference, importing a payload to -a semaphore adds the semaphore to the set of all semaphores sharing that -payload. -This set includes the semaphore from which the payload was exported. -Semaphore signaling and waiting operations performed on any semaphore in the -set must behave as if the set were a single semaphore. -Importing a payload using handle types with copy transference creates a -duplicate copy of the payload at the time of import, but makes no further -reference to it. -Semaphore signaling and waiting operations performed on the target of copy -imports must not affect any other semaphore or payload. - -Export operations have the same transference as the specified handle type's -import operations. -Additionally, exporting a semaphore payload to a handle with copy -transference has the same side effects on the source semaphore's payload as -executing a semaphore wait operation. -If the semaphore was using a temporarily imported payload, the semaphore's -prior permanent payload will be restored. - -Please refer to handle specific specifications for more details on -transference and permanence requirements specific to handle type. +Applications can import a semaphore payload by creating a semaphore from an external handle. The +implementation must perform the import operation by either referencing or copying the payload +referred to by the specified external semaphore handle, depending on the handle's type. When using +handle types with reference transference, importing a payload to a semaphore adds the semaphore to +the set of all semaphores sharing that payload. This set includes the semaphore from which the payload +was exported. Semaphore signaling and waiting operations performed on any semaphore in the set must +behave as if the set were a single semaphore. Importing a payload using handle types with copy +transference creates a duplicate copy of the payload at the time of import, but makes no further +reference to it. Semaphore signaling and waiting operations performed on the target of copy imports +must not affect any other semaphore or payload. + +Please refer to handle specific documentation for more details on transference requirements per +handle type. === Descriptions of External Semaphore Handle Types @@ -13034,17 +13004,16 @@ descriptor when exporting a {CL_SEMAPHORE_HANDLE_SYNC_FD_KHR} from a endif::cl_khr_external_semaphore_sync_fd[] -.Transference and Permanence Properties for File Descriptor Handles -[width="100%",cols="60%,<20%,<20%",options="header"] +.Transference Properties for File Descriptor Handles +[width="100%",cols="60%,<40%",options="header"] |==== -| Handle Type | Transference | Permanence +| Handle Type | Transference ifdef::cl_khr_external_semaphore_opaque_fd[] | {CL_SEMAPHORE_HANDLE_OPAQUE_FD_KHR_anchor} include::{generated}/api/version-notes/CL_SEMAPHORE_HANDLE_OPAQUE_FD_KHR.asciidoc[] | Reference - | Temporary, Permanent endif::cl_khr_external_semaphore_opaque_fd[] ifdef::cl_khr_external_semaphore_sync_fd[] @@ -13052,7 +13021,6 @@ ifdef::cl_khr_external_semaphore_sync_fd[] include::{generated}/api/version-notes/CL_SEMAPHORE_HANDLE_SYNC_FD_KHR.asciidoc[] | Copy - | Temporary endif::cl_khr_external_semaphore_sync_fd[] |==== @@ -13130,24 +13098,21 @@ a semaphore from an external handle: endif::cl_khr_external_semaphore_win32[] -.Transference and Permanence Properties for NT Handle Types -[width="100%",cols="60%,<20%,<20%",options="header"] +.Transference Properties for NT Handle Types +[width="100%",cols="60%,<40%",options="header"] |==== -| Handle Type | Transference | Permanence +| Handle Type | Transference ifdef::cl_khr_external_semaphore_win32[] | {CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KHR_anchor} include::{generated}/api/version-notes/CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KHR.asciidoc[] | Reference - | Temporary, Permanent | {CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KMT_KHR_anchor} include::{generated}/api/version-notes/CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KMT_KHR.asciidoc[] | Reference - | Temporary, Permanent endif::cl_khr_external_semaphore_win32[] -|==== // TODO Why "Windows handles" here but "NT handles" elsewhere? From 92c3de30762550f1a06a0160f23787b86fdcbf2e Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Tue, 9 Jul 2024 09:46:47 -0700 Subject: [PATCH 49/71] clarify CL_DEVICE_TYPE_DEFAULT and CL_DEVICE_TYPE_ALL for custom devices (#1117) --- api/opencl_platform_layer.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index 99a6653cd..ceb6e3193 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -395,13 +395,13 @@ include::{generated}/api/version-notes/CL_DEVICE_TYPE_DEFAULT.asciidoc[] {clGetDeviceIDs} or to create OpenCL contexts using {clCreateContextFromType}, and will never be returned in {CL_DEVICE_TYPE} for any OpenCL device. - The default OpenCL device must not be a {CL_DEVICE_TYPE_CUSTOM} device. + The default OpenCL device must not be a {CL_DEVICE_TYPE_CUSTOM} device + unless it is the only device in the platform. | {CL_DEVICE_TYPE_ALL_anchor} include::{generated}/api/version-notes/CL_DEVICE_TYPE_ALL.asciidoc[] - | All OpenCL devices available in the platform, except for - {CL_DEVICE_TYPE_CUSTOM} devices. + | All OpenCL devices in the platform. {CL_DEVICE_TYPE_ALL} is only used to query OpenCL devices using {clGetDeviceIDs} or to create OpenCL contexts using {clCreateContextFromType}, and will never be returned in {CL_DEVICE_TYPE} From 51c80762194a259bc686760006da5e7e138c3fe8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Wed, 10 Jul 2024 16:20:10 +0100 Subject: [PATCH 50/71] Fix typos in description of clReImportSemaphoreSyncFdKHR (#1208) Also add to list of new commands in extension appendix. Change-Id: I80b1d25368c2cefb0967120bdc429a8187c518c7 Signed-off-by: Kevin Petit --- api/cl_khr_external_semaphore_sync_fd.asciidoc | 1 + api/opencl_runtime_layer.asciidoc | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/api/cl_khr_external_semaphore_sync_fd.asciidoc b/api/cl_khr_external_semaphore_sync_fd.asciidoc index f8203ce90..aee60ec16 100644 --- a/api/cl_khr_external_semaphore_sync_fd.asciidoc +++ b/api/cl_khr_external_semaphore_sync_fd.asciidoc @@ -38,6 +38,7 @@ external semaphore using the APIs introduced by === New Commands * {clGetSemaphoreHandleForTypeKHR} + * {clReImportSemaphoreSyncFdKHR} === New Types diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index cb32ecab4..66e889320 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -13032,7 +13032,7 @@ a successful import. ifdef::cl_khr_external_semaphore_sync_fd[] [open,refpage='clReImportSemaphoreSyncFdKHR',desc='Re-import sync fd handle into an existing semaphore',type='protos'] -- -To re-imported a handle of type {CL_SEMAPHORE_HANDLE_SYNC_FD_KHR} into an +To re-import a handle of type {CL_SEMAPHORE_HANDLE_SYNC_FD_KHR} into an existing semaphore, call the function: include::{generated}/api/protos/clReImportSemaphoreSyncFdKHR.txt[] @@ -13051,7 +13051,7 @@ of type {CL_SEMAPHORE_HANDLE_SYNC_FD_KHR}. // refError -{clGetSemaphoreHandleForTypeKHR} returns {CL_SUCCESS} if the semaphore +{clReImportSemaphoreSyncFdKHR} returns {CL_SUCCESS} if the semaphore handle is re-imported successfully. Otherwise, it returns one of the following errors: From 110a2262e55ff8d25928665ad88e0c3d88cac427 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Wed, 10 Jul 2024 16:20:53 +0100 Subject: [PATCH 51/71] Add missing table end (#1206) Introduced by #938 Change-Id: Ibef16bceb5398c49a14e88818a45236d0e17acf0 Signed-off-by: Kevin Petit --- api/opencl_runtime_layer.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 66e889320..7adab199e 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -13113,6 +13113,7 @@ include::{generated}/api/version-notes/CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KHR.asci include::{generated}/api/version-notes/CL_SEMAPHORE_HANDLE_OPAQUE_WIN32_KMT_KHR.asciidoc[] | Reference endif::cl_khr_external_semaphore_win32[] +|==== // TODO Why "Windows handles" here but "NT handles" elsewhere? From 735396cb51e76a0b268afd547c7b6a9238205294 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Wed, 10 Jul 2024 17:38:08 +0100 Subject: [PATCH 52/71] Fail spec creation if asciidoctor errors are encountered (#1205) * Fail spec creation if asciidoctor errors are encountered This would have enabled the CI to catch a markup issue introduced by #938. Signed-off-by: Kevin Petit Change-Id: I49de3eaf623117f7c29d1019dedf5b342766a029 * attempt to fix asciidoctor errors in API spec Change-Id: I0f9cbeddb72e0d76ba508b336d91c4ee640d77ad --------- Signed-off-by: Kevin Petit --- Makefile | 2 +- api/opencl_runtime_layer.asciidoc | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index c2e00d073..6aef16a92 100644 --- a/Makefile +++ b/Makefile @@ -117,7 +117,7 @@ ADOCCOMMONOPTS = -a apispec="$(CURDIR)/api" \ -a cspec="$(CURDIR)/c" \ -a images="$(CURDIR)/images" \ $(ATTRIBOPTS) $(NOTEOPTS) $(VERBOSE) $(ADOCEXTS) -ADOCOPTS = -d book $(ADOCCOMMONOPTS) +ADOCOPTS = --failure-level ERROR -d book $(ADOCCOMMONOPTS) # Asciidoctor options to build refpages # diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 7adab199e..d6d23bdf2 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -2524,14 +2524,14 @@ The memory layout of this image format is described below: [width="60%",cols="<10%,<10%,<10%,<10%,<60%"] |==== -| R | G | B | A | ... | +| R | G | B | A | ... |==== with the corresponding byte offsets [width="60%",cols="<10%,<10%,<10%,<10%,<60%"] |==== -| 0 | 1 | 2 | 3 | ... | +| 0 | 1 | 2 | 3 | ... |==== Similar, if `image_channel_order` = {CL_RGBA} and `image_channel_data_type` = @@ -2539,14 +2539,14 @@ Similar, if `image_channel_order` = {CL_RGBA} and `image_channel_data_type` = [width="60%",cols="<10%,<10%,<10%,<10%,<60%"] |==== -| R | G | B | A | ... | +| R | G | B | A | ... |==== with the corresponding byte offsets [width="60%",cols="<10%,<10%,<10%,<10%,<60%"] |==== -| 0 | 2 | 4 | 6 | ... | +| 0 | 2 | 4 | 6 | ... |==== `image_channel_data_type` values of {CL_UNORM_SHORT_565}, {CL_UNORM_SHORT_555}, From bed6c84b0a22328fdfc6c14627801e9f7c586d51 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Thu, 11 Jul 2024 15:38:32 +0100 Subject: [PATCH 53/71] xml: require CL/GL types for cl_khr_gl_sharing (#1210) So the type definitions are included in the generated cl_gl.h Change-Id: I65a666dde8066958897acf13fb755ae2a3f3b52d Signed-off-by: Kevin Petit --- xml/cl.xml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/xml/cl.xml b/xml/cl.xml index bca2621d9..ac7236c12 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -6566,6 +6566,11 @@ server's OpenCL/api-docs repository. + + + + + From 85f50320dbf2c4f0342cc24387aa5dad4fb55e23 Mon Sep 17 00:00:00 2001 From: Ewan Crawford Date: Tue, 16 Jul 2024 17:28:08 +0100 Subject: [PATCH 54/71] Add multi-device wording to clCommandBarrierWithWaitListKHR (#1146) `clCommandBarrierWithWaitListKHR` does not having wording for the `command_queue` parameter regarding when `cl_khr_command_buffer_multi_device` is enabled. --- api/opencl_runtime_layer.asciidoc | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index d6d23bdf2..fc26bc289 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -14281,10 +14281,17 @@ include::{generated}/api/protos/clCommandBarrierWithWaitListKHR.txt[] include::{generated}/api/version-notes/clCommandBarrierWithWaitListKHR.asciidoc[] * _command_buffer_ refers to a valid command-buffer object. - * _command_queue_ specifies the command-queue the command will be recorded - to. - This parameter is unused, as only a single - command-queue is supported, and **must** be `NULL`. + * _command_queue_ specifies the command-queue the command will be recorded to. + {empty} + + If the {cl_khr_command_buffer_multi_device_EXT} extension is not supported, + only a single command-queue is supported, and _command_queue_ must be + `NULL`. +ifdef::cl_khr_command_buffer_multi_device[] + {empty} + + If the {cl_khr_command_buffer_multi_device_EXT} extension is supported and + _command_queue_ is `NULL`, then only one command-queue must have been set on + _command_buffer_ creation; otherwise, _command_queue_ must not be `NULL`. +endif::cl_khr_command_buffer_multi_device[] * _sync_point_wait_list_, _num_sync_points_in_wait_list_ specify synchronization-points that need to complete before this particular command can be executed. @@ -14332,7 +14339,14 @@ recorded after it do not execute until it completes. executed successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not `NULL`. + * {CL_INVALID_COMMAND_QUEUE} if the + {cl_khr_command_buffer_multi_device_EXT} extension is not supported and + _command_queue_ is not `NULL`. + * {CL_INVALID_COMMAND_QUEUE} if the + {cl_khr_command_buffer_multi_device_EXT} extension is supported; and + either _command_queue_ is `NULL` and _command_buffer_ was created with + more than one queue, or _command_queue_ is not `NULL` and not a + command-queue listed on _command_buffer_ creation. * {CL_INVALID_COMMAND_BUFFER_KHR} if _command_buffer_ is not a valid command-buffer. * {CL_INVALID_CONTEXT} if the context associated with _command_queue_ and From fed48e7e3ec3eedc6da3f527545051686a043c0d Mon Sep 17 00:00:00 2001 From: Ewan Crawford Date: Tue, 16 Jul 2024 17:29:03 +0100 Subject: [PATCH 55/71] Fix CL_INVALID_CONTEXT command-buffer error definitions (#1149) * Fix CL_INVALID_CONTEXT command-buffer error definitions See issue https://github.com/KhronosGroup/OpenCL-Docs/issues/1147 documenting that the error specification for `CL_INVALID_CONTEXT` doesn't take into account the variation when `cl_khr_command_buffer_multi_device` is enabled. Doing this change also picked up that the error wording for `clCommandSVMMemcpyKHR` and `clCommandSVMMemFillKHR` referenced the _kernel_ parameter which doesn't exist. * Address review feedback * Remove extraneous `cl_khr_command_buffer_multi_device` precondition from error wording. * Change "enabled" terminology to "supported" with regards to extensions. --- api/opencl_runtime_layer.asciidoc | 91 +++++++++++++++++++++++-------- 1 file changed, 69 insertions(+), 22 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index fc26bc289..21ea41524 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -14349,8 +14349,10 @@ Otherwise, it returns one of the following errors: command-queue listed on _command_buffer_ creation. * {CL_INVALID_COMMAND_BUFFER_KHR} if _command_buffer_ is not a valid command-buffer. - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_ and - _command_buffer_ is not the same. +ifdef::cl_khr_command_buffer_multi_device[] + * {CL_INVALID_CONTEXT} if _command_queue_ is not `NULL`, and the context + associated with _command_queue_ and _command_buffer_ is not the same. +endif::cl_khr_command_buffer_multi_device[] * {CL_INVALID_OPERATION} if _command_buffer_ has been finalized. * {CL_INVALID_VALUE} if _mutable_handle_ is not `NULL`. * {CL_INVALID_SYNC_POINT_WAIT_LIST_KHR} if _sync_point_wait_list_ is @@ -14432,8 +14434,12 @@ Otherwise, it returns the errors defined by {clEnqueueCopyBuffer} except: {CL_INVALID_CONTEXT} is replaced with: - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_, - _command_buffer_, _src_buffer_, and _dst_buffer_ are not the same. + * {CL_INVALID_CONTEXT} if the context associated with _command_buffer_, + _src_buffer_, and _dst_buffer_ is not the same. +ifdef::cl_khr_command_buffer_multi_device[] + * {CL_INVALID_CONTEXT} if _command_queue_ is not `NULL`, and the context + associated with _command_queue_ and _command_buffer_ is not the same. +endif::cl_khr_command_buffer_multi_device[] {CL_INVALID_EVENT_WAIT_LIST} is replaced with: @@ -14537,8 +14543,12 @@ except: {CL_INVALID_CONTEXT} is replaced with: - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_, - _command_buffer_, _src_buffer_, and _dst_buffer_ are not the same. + * {CL_INVALID_CONTEXT} if the context associated with _command_buffer_, + _src_buffer_, and _dst_buffer_ is not the same. +ifdef::cl_khr_command_buffer_multi_device[] + * {CL_INVALID_CONTEXT} if _command_queue_ is not `NULL`, and the context + associated with _command_queue_ and _command_buffer_ is not the same. +endif::cl_khr_command_buffer_multi_device[] {CL_INVALID_EVENT_WAIT_LIST} is replaced with: @@ -14625,8 +14635,12 @@ except: {CL_INVALID_CONTEXT} is replaced with: - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_, - _command_buffer_, _src_buffer_, and _dst_image_ are not the same. + * {CL_INVALID_CONTEXT} if the context associated with _command_buffer_, + _src_buffer_, and _dst_image_ is not the same. +ifdef::cl_khr_command_buffer_multi_device[] + * {CL_INVALID_CONTEXT} if _command_queue_ is not `NULL`, and the context + associated with _command_queue_ and _command_buffer_ is not the same. +endif::cl_khr_command_buffer_multi_device[] {CL_INVALID_EVENT_WAIT_LIST} is replaced with: @@ -14719,8 +14733,12 @@ Otherwise, it returns the errors defined by {clEnqueueCopyImage} except: {CL_INVALID_CONTEXT} is replaced with: - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_, - _command_buffer_, _src_image_, and _dst_image_ are not the same. + * {CL_INVALID_CONTEXT} if the context associated with _command_buffer_, + _src_image_, and _dst_image_ is not the same. +ifdef::cl_khr_command_buffer_multi_device[] + * {CL_INVALID_CONTEXT} if _command_queue_ is not `NULL`, and the context + associated with _command_queue_ and _command_buffer_ is not the same. +endif::cl_khr_command_buffer_multi_device[] {CL_INVALID_EVENT_WAIT_LIST} is replaced with: @@ -14807,8 +14825,12 @@ except: {CL_INVALID_CONTEXT} is replaced with: - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_, - _command_buffer_, _src_image_, and _dst_buffer_ are not the same. + * {CL_INVALID_CONTEXT} if the context associated with _command_buffer_, + _src_image_, and _dst_buffer_ is not the same. +ifdef::cl_khr_command_buffer_multi_device[] + * {CL_INVALID_CONTEXT} _command_queue_ is not `NULL`, and the context + associated with _command_queue_ and _command_buffer_ is not the same. +endif::cl_khr_command_buffer_multi_device[] {CL_INVALID_EVENT_WAIT_LIST} is replaced with: @@ -14902,8 +14924,12 @@ Otherwise, it returns the errors defined by {clEnqueueFillBuffer} except: {CL_INVALID_CONTEXT} is replaced with: - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_, - _command_buffer_, and _buffer_ are not the same. + * {CL_INVALID_CONTEXT} if the context associated with _command_buffer_ and + _buffer_ is not the same. +ifdef::cl_khr_command_buffer_multi_device[] + * {CL_INVALID_CONTEXT} if _command_queue_ is not `NULL`, and the context + associated with _command_queue_ and _command_buffer_ is not the same. +endif::cl_khr_command_buffer_multi_device[] {CL_INVALID_EVENT_WAIT_LIST} is replaced with: @@ -14995,8 +15021,12 @@ Otherwise, it returns the errors defined by {clEnqueueFillImage} except: {CL_INVALID_CONTEXT} is replaced with: - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_, - _command_buffer_, and _image_ are not the same. + * {CL_INVALID_CONTEXT} if the context associated with _command_buffer_ and + _image_ is not the same. +ifdef::cl_khr_command_buffer_multi_device[] + * {CL_INVALID_CONTEXT} if _command_queue_ is not `NULL`, and the context + associated with _command_queue_ and _command_buffer_ is not the same. +endif::cl_khr_command_buffer_multi_device[] {CL_INVALID_EVENT_WAIT_LIST} is replaced with: @@ -15239,8 +15269,12 @@ Otherwise, it returns the errors defined by {clEnqueueNDRangeKernel} except: {CL_INVALID_CONTEXT} is replaced with: - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_, - _command_buffer_, and _kernel_ are not the same. + * {CL_INVALID_CONTEXT} if the context associated with _command_buffer_ and + _kernel_ is not the same. +ifdef::cl_khr_command_buffer_multi_device[] + * {CL_INVALID_CONTEXT} if _command_queue_ is not `NULL`, and the context + associated with _command_queue_ and _command_buffer_ is not the same. +endif::cl_khr_command_buffer_multi_device[] {CL_INVALID_EVENT_WAIT_LIST} is replaced with: @@ -15353,10 +15387,17 @@ Otherwise, it returns the errors defined by {clEnqueueSVMMemcpy} except: more than one queue, or _command_queue_ is not `NULL` and not a command-queue listed on _command_buffer_ creation. +ifdef::cl_khr_command_buffer_multi_device[] {CL_INVALID_CONTEXT} is replaced with: - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_, - _command_buffer_, and _kernel_ are not the same. + * {CL_INVALID_CONTEXT} if _command_queue_ is not `NULL`, and the context + associated with _command_queue_ and _command_buffer_ is not the same. + +endif::cl_khr_command_buffer_multi_device[] + +ifndef::cl_khr_command_buffer_multi_device[] +{CL_INVALID_CONTEXT} error case is removed. +endif::cl_khr_command_buffer_multi_device[] {CL_INVALID_EVENT_WAIT_LIST} is replaced with: @@ -15459,10 +15500,16 @@ successfully. Otherwise, it returns the errors defined by more than one queue, or _command_queue_ is not `NULL` and not a command-queue listed on _command_buffer_ creation. +ifdef::cl_khr_command_buffer_multi_device[] {CL_INVALID_CONTEXT} is replaced with: - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_, - _command_buffer_, and _kernel_ are not the same. + * {CL_INVALID_CONTEXT} if _command_queue_ is not `NULL`, and the context + associated with _command_queue_ and _command_buffer_ is not the same. +endif::cl_khr_command_buffer_multi_device[] + +ifndef::cl_khr_command_buffer_multi_device[] +{CL_INVALID_CONTEXT} error case is removed. +endif::cl_khr_command_buffer_multi_device[] {CL_INVALID_EVENT_WAIT_LIST} is replaced with: From c6cceb1787b7364bd0f4783ebb0d284d21aca33f Mon Sep 17 00:00:00 2001 From: Ewan Crawford Date: Tue, 16 Jul 2024 17:33:16 +0100 Subject: [PATCH 56/71] Use array for clUpdateMutableCommandsKHR. (#1045) Proposal to pass the update configs to `clUpdateMutableCommandsKHR` as an array, rather than pointer changed linked list. See https://github.com/KhronosGroup/OpenCL-Docs/issues/1041 for motivation. --- ...r_command_buffer_mutable_dispatch.asciidoc | 60 +++++------- api/opencl_runtime_layer.asciidoc | 93 +++++++++---------- xml/cl.xml | 34 +++---- 3 files changed, 80 insertions(+), 107 deletions(-) diff --git a/api/cl_khr_command_buffer_mutable_dispatch.asciidoc b/api/cl_khr_command_buffer_mutable_dispatch.asciidoc index 13ada6c22..486d01d12 100644 --- a/api/cl_khr_command_buffer_mutable_dispatch.asciidoc +++ b/api/cl_khr_command_buffer_mutable_dispatch.asciidoc @@ -6,7 +6,7 @@ include::{generated}/meta/{refprefix}cl_khr_command_buffer_mutable_dispatch.txt[ === Other Extension Metadata *Last Modified Date*:: - 2022-08-31 + 2024-06-19 *IP Status*:: No known IP claims. *Contributors*:: @@ -43,32 +43,15 @@ in a new command-buffer. === Interactions With Other Extensions -The {cl_command_buffer_structure_type_khr_TYPE} type has been added to this -extension for the purpose of allowing expansion of mutable functionality in -future extensions layered on top of -{cl_khr_command_buffer_mutable_dispatch_EXT}. -Any parameter that is a structure containing a `void* next` member *must* -have a value of `next` that is either `NULL`, or is a pointer to a valid -structure defined by {cl_khr_command_buffer_mutable_dispatch_EXT} or an -extension layered on top. -To be a valid structure in the pointer chain the first member of the -structure *must* be a {cl_command_buffer_structure_type_khr_TYPE} identifier -for the structure being iterated through, and the second member a `void* -next` pointer to the next structure in the chain. - -[NOTE] -==== -This approach is based on structure pointer chains in Vulkan, for more -details see the "`Valid Usage for Structure Pointer Chains`" section of the -Vulkan specification. -==== - -This is designed so that another extension layered on -{cl_khr_command_buffer_mutable_dispatch_EXT} could allow modification of -commands recorded to a command-buffer other than kernel execution commands. -As all command recording entry-points return a {cl_mutable_command_khr_TYPE} -handle, and aspects like which {cl_mem_TYPE} object a command uses could -also be updated between enqueues of the command-buffer. +The {clUpdateMutableCommandsKHR} entry-point has been designed for the purpose +of allowing expansion of mutable functionality in future extensions layered on +top of `cl_khr_command_buffer_mutable_dispatch`. + +A new extension can define its own structure type to specify the update +configuration it requires, with a matching +{cl_command_buffer_update_type_khr_TYPE} value. This new structure type can +then be passed to {clUpdateMutableCommandsKHR} where it is reinterpreted from a +void pointer using {cl_command_buffer_update_type_khr_TYPE}. === New Commands @@ -79,8 +62,7 @@ also be updated between enqueues of the command-buffer. * {cl_mutable_dispatch_fields_khr_TYPE} * {cl_mutable_command_info_khr_TYPE} - * {cl_command_buffer_structure_type_khr_TYPE} - * {cl_mutable_base_config_khr_TYPE} + * {cl_command_buffer_update_type_khr_TYPE} * {cl_mutable_dispatch_asserts_khr_TYPE} * {cl_mutable_dispatch_config_khr_TYPE} * {cl_mutable_dispatch_exec_info_khr_TYPE} @@ -115,8 +97,7 @@ also be updated between enqueues of the command-buffer. ** {CL_COMMAND_BUFFER_MUTABLE_KHR} * {cl_command_buffer_properties_khr_TYPE} ** {CL_COMMAND_BUFFER_MUTABLE_DISPATCH_ASSERTS_KHR} - * {cl_command_buffer_structure_type_khr_TYPE} - ** {CL_STRUCTURE_TYPE_MUTABLE_BASE_CONFIG_KHR} + * {cl_command_buffer_update_type_khr_TYPE} ** {CL_STRUCTURE_TYPE_MUTABLE_DISPATCH_CONFIG_KHR} * New Error Codes ** {CL_INVALID_MUTABLE_COMMAND_KHR} @@ -274,8 +255,6 @@ kernel void vector_addition(global int* tile1, global int* tile2, cl_mutable_dispatch_arg_khr arg_2{2, sizeof(cl_mem), &output_buffer}; cl_mutable_dispatch_arg_khr args[] = {arg_0, arg_1, arg_2}; cl_mutable_dispatch_config_khr dispatch_config{ - CL_STRUCTURE_TYPE_MUTABLE_DISPATCH_CONFIG_KHR, - nullptr, command_handle, 3 /* num_args */, 0 /* num_svm_arg */, @@ -287,12 +266,16 @@ kernel void vector_addition(global int* tile1, global int* tile2, nullptr /* global_work_offset */, nullptr /* global_work_size */, nullptr /* local_work_size */}; - cl_mutable_base_config_khr mutable_config{ - CL_STRUCTURE_TYPE_MUTABLE_BASE_CONFIG_KHR, nullptr, 1, - &dispatch_config}; // Update the command buffer with the mutable configuration - error = clUpdateMutableCommandsKHR(command_buffer, &mutable_config); + cl_uint num_configs = 1; + cl_command_buffer_update_type_khr config_types[1] = { + CL_STRUCTURE_TYPE_MUTABLE_DISPATCH_CONFIG_KHR + }; + const void* configs[1] = {&dispatch_config}; + error = clUpdateMutableCommandsKHR(command_buffer, num_configs, + config_types, configs); + CL_CHECK(error); } @@ -374,3 +357,6 @@ may be a introduced as a stand alone extension. * Revision 0.9.1, 2023-11-07 ** Add type {cl_mutable_dispatch_asserts_khr_TYPE} and its possible values (provisional). + * Revision 0.9.2, 2024-06-19 + ** Change {clUpdateMutableCommandsKHR} API to pass configs as an array rather + than linked list (provisional). diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 21ea41524..29e69e7b3 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -15647,7 +15647,7 @@ endif::cl_khr_command_buffer_multi_device[] ifdef::cl_khr_command_buffer_mutable_dispatch[] [[mutable-commands]] -=== Mutable Commands: +=== Mutable Commands A generic {cl_mutable_command_khr_TYPE} handle is called a _mutable-command_ object as it can be returned from any command recording entry-point in the @@ -15658,11 +15658,10 @@ modified through the fields of {cl_mutable_dispatch_config_khr_TYPE}. Mutable-command handles are updated between enqueues using entry-point {clUpdateMutableCommandsKHR}. -To enable performant usage, all aspects of mutation are encapsulated inside -a single {cl_mutable_base_config_khr_TYPE} parameter. -This means that the runtime has access to all the information about how the -command-buffer will change, allowing the command-buffer to be rebuilt as -efficiently as possible. +To enable performant usage, all aspects of mutation can be passed in a single +call using an array. This means that the runtime has access to all the +information about how the command-buffer will change, allowing the +command-buffer to be rebuilt as efficiently as possible. Any modifications to the arguments or execution info of a mutable-dispatch handle using {cl_mutable_dispatch_arg_khr_TYPE} or {cl_mutable_dispatch_exec_info_khr_TYPE} have no affect on the original @@ -15703,8 +15702,13 @@ include::{generated}/api/protos/clUpdateMutableCommandsKHR.txt[] include::{generated}/api/version-notes/clUpdateMutableCommandsKHR.asciidoc[] * _command_buffer_ refers to a valid command-buffer object. - * _mutable_config_ is a pointer to a {cl_mutable_base_config_khr_TYPE} - structure defining updates to make to mutable-commands. + * _num_configs_ Number of elements in the _config_types_ and _config_ arrays. + * _config_types_ An array of length _num_configs_ with each element identifying + the type of each config in _configs_ at the same array index. + * _configs_ An array of length _num_configs_ containing structs which define how a + mutable-command handle in _command_buffer_ is to be updated, each of which is + interpreted using _config_types_ at the same index with the mapping defined + in the <> section. // refError @@ -15718,16 +15722,13 @@ one of the errors below is returned: * {CL_INVALID_OPERATION} if _command_buffer_ has not been finalized. * {CL_INVALID_OPERATION} if _command_buffer_ was not created with the {CL_COMMAND_BUFFER_MUTABLE_KHR} flag. - * {CL_INVALID_VALUE} if the _type_ member of _mutable_config_ is not - {CL_STRUCTURE_TYPE_MUTABLE_BASE_CONFIG_KHR}. - * {CL_INVALID_VALUE} if the _mutable_dispatch_list_ member of - _mutable_config_ is `NULL` and _num_mutable_dispatch_ > 0, or - _mutable_dispatch_list_ is not `NULL` and _num_mutable_dispatch_ is 0. - * {CL_INVALID_VALUE} if the _next_ member of _mutable_config_ is not - `NULL` and any iteration of the structure pointer chain does not contain - valid _type_ and _next_ members. - * {CL_INVALID_VALUE} if _mutable_config_ is `NULL`, or if both _next_ and - _mutable_dispatch_list_ members of _mutable_config_ are `NULL`. + * {CL_INVALID_VALUE} if _config_types_ is `NULL` and _num_configs_ > 0, or + _config_types_ is not `NULL` and _num_configs_ is 0. + * {CL_INVALID_VALUE} if _configs_ is `NULL` and _num_configs_ > 0, or + _configs_ is not `NULL` and _num_configs_ is 0. + * {CL_INVALID_VALUE} if any element of _config_types_ is not a valid + {cl_command_buffer_update_type_khr_TYPE} enum. + * {CL_INVALID_VALUE} if any element of _configs_ is NULL. * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required by the OpenCL implementation on the device. * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources @@ -15753,19 +15754,17 @@ parameters are updated so that the new number of work-groups exceeds the number when the ND-range command was recorded, the behavior is undefined. ==== -If the _mutable_dispatch_list_ member of _mutable_config_ is non-`NULL`, -then errors defined by {clEnqueueNDRangeKernel}, {clSetKernelExecInfo}, -{clSetKernelArg}, and {clSetKernelArgSVMPointer} are returned by -{clUpdateMutableCommandsKHR} if any of the array elements are set to an -invalid value. -Additionally, the following errors are returned if any -{cl_mutable_dispatch_config_khr_TYPE} element of the array violates the -defined conditions: +If _configs_ is non-`NULL`, then for any {cl_mutable_dispatch_config_khr_TYPE} +element of the array the errors defined by {clEnqueueNDRangeKernel}, +{clSetKernelExecInfo}, {clSetKernelArg}, and {clSetKernelArgSVMPointer} are +returned by {clUpdateMutableCommandsKHR} if any of the struct elements are set +to an invalid value. Additionally, the following errors are returned if any +{cl_mutable_dispatch_config_khr_TYPE} element of the array violates the defined +conditions: * {CL_INVALID_MUTABLE_COMMAND_KHR} if _command_ is not a valid mutable - command object, or created from _command_buffer_. - * {CL_INVALID_VALUE} if _type_ is not - {CL_STRUCTURE_TYPE_MUTABLE_DISPATCH_CONFIG_KHR}. + command object returned from {clCommandNDRangeKernelKHR}, or created from + _command_buffer_. * {CL_INVALID_OPERATION} if the values of _local_work_size_ and/or _global_work_size_ result in a change to work-group uniformity. * {CL_INVALID_OPERATION} if the _work_dim_ is different from the @@ -15793,24 +15792,25 @@ defined conditions: 0, or _exec_info_list_ is not `NULL` and _num_exec_infos_ is 0. -- -[open,refpage='cl_mutable_base_config_khr',desc='DESC',type='structs'] --- -The {cl_mutable_base_config_khr_TYPE} structure encapsulates all aspects of -mutation and is defined as: +[[mutable-commands-update-structs]] +==== Mutable Command Update Structs -include::{generated}/api/structs/cl_mutable_base_config_khr.txt[] +The following table defines the mapping of +{cl_command_buffer_update_type_khr_TYPE} values to the structs they define +reinterpreting a void pointer as when passed to {clUpdateMutableCommandsKHR}. - * _type_ is the type of this structure, and must be - {CL_STRUCTURE_TYPE_MUTABLE_BASE_CONFIG_KHR_anchor} - * _next_ is `NULL` or a pointer to an extending structure. - * _num_mutable_dispatch_ is the number of mutable-dispatch objects to - configure in this enqueue of the command-buffer. - * _mutable_dispatch_list_ is an array containing _num_mutable_dispatch_ - elements describing the configurations of mutable kernel execution - commands in the command-buffer. - For a description of struct members making up each array element see - {cl_mutable_dispatch_config_khr_TYPE}. --- +[[update-config-mapping]] +[cols=",,",options="header",] +|==== +| Enum Value | Struct Type | Entry Point + +| {CL_STRUCTURE_TYPE_MUTABLE_DISPATCH_CONFIG_KHR_anchor} +| {cl_mutable_dispatch_config_khr_TYPE} +| {clCommandNDRangeKernelKHR} + +|==== + +==== Kernel Command Update Structs [open,refpage='cl_mutable_dispatch_config_khr',desc='Set kernel configuration of a mutable clCommandNDRangeKernelKHR command',type='structs'] -- @@ -15820,9 +15820,6 @@ The {cl_mutable_dispatch_arg_khr_TYPE} structure is passed to include::{generated}/api/structs/cl_mutable_dispatch_config_khr.txt[] - * _type_ is the type of this structure, and must be - {CL_STRUCTURE_TYPE_MUTABLE_DISPATCH_CONFIG_KHR_anchor}. - * _next_ is `NULL` or a pointer to an extending structure. * _command_ is a mutable-command object returned by {clCommandNDRangeKernelKHR} representing a kernel execution as part of a command-buffer. diff --git a/xml/cl.xml b/xml/cl.xml index ac7236c12..53b9a9be4 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -249,7 +249,7 @@ server's OpenCL/api-docs repository. typedef struct _cl_mutable_command_khr* cl_mutable_command_khr; typedef cl_bitfield cl_mutable_dispatch_fields_khr; typedef cl_uint cl_mutable_command_info_khr; - typedef cl_uint cl_command_buffer_structure_type_khr; + typedef cl_uint cl_command_buffer_update_type_khr; typedef cl_bitfield cl_device_fp_atomic_capabilities_ext; typedef cl_uint cl_image_requirements_info_ext; typedef cl_bitfield cl_platform_command_buffer_capabilities_khr; @@ -370,8 +370,6 @@ server's OpenCL/api-docs repository. const void* param_value - cl_command_buffer_structure_type_khr type - const void* next cl_mutable_command_khr command cl_uint num_args cl_uint num_svm_args @@ -384,13 +382,6 @@ server's OpenCL/api-docs repository. const size_t* global_work_size const size_t* local_work_size - - - cl_command_buffer_structure_type_khr type - const void* next - cl_uint num_mutable_dispatch - const cl_mutable_dispatch_config_khr* mutable_dispatch_list - @@ -1370,10 +1361,9 @@ server's OpenCL/api-docs repository. - - - - + + + @@ -3280,9 +3270,11 @@ server's OpenCL/api-docs repository. size_t* param_value_size_ret - cl_int clUpdateMutableCommandsKHR - cl_command_buffer_khr command_buffer - const cl_mutable_base_config_khr* mutable_config + cl_int clUpdateMutableCommandsKHR + cl_command_buffer_khr command_buffer + cl_uint num_configs + const cl_command_buffer_update_type_khr* config_types + const void** configs cl_int clGetMutableCommandInfoKHR @@ -7324,18 +7316,17 @@ server's OpenCL/api-docs repository. - + - + - @@ -7369,8 +7360,7 @@ server's OpenCL/api-docs repository. - - + From 6be4f45e06624c45d5c49b9325535e4ba387c2dc Mon Sep 17 00:00:00 2001 From: Nikhil Joshi Date: Tue, 16 Jul 2024 22:42:05 +0530 Subject: [PATCH 57/71] Clarify Acquire/Release behavior for external memory (#1176) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Clarify Acquire/Release behavior for external memory Clarify Acquire/Release behavior for external memory specs to call out the scope of operations as well as the behavior in case of multiple acquire/release calls. Fixes #1078, #1086 * Updates to Acquire/Release clarifications (#1183) Address review comments on PR#1176 Fixes #1078, #1086 * Address left-over comments (#1194) Address some of the comments that were left out in earlier update. * Fix the typo for "acquired" Fix the typo suggested by Kevin to replace aquired to acquired. Co-authored-by: Kévin Petit --------- Co-authored-by: Kévin Petit --- api/opencl_runtime_layer.asciidoc | 34 +++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 29e69e7b3..b4e3e5087 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -5427,6 +5427,23 @@ handle is used by an OpenCL command queued to a command-queue without being acquired. This is to guarantee that the state of the memory objects is up-to-date and they are accessible to OpenCL. + +The following restrictions shall apply - + * Each memory object must be acquired only once. Acquiring a memory object + multiple times without releasing it results in implementation-defined + behavior. + * The acquire must be performed on a command-queue associated with a device + that was one of the devices specified via {CL_MEM_DEVICE_HANDLE_LIST_KHR} + when the memory object was imported using {clCreateBufferWithProperties} or + {clCreateImageWithProperties}. If {CL_MEM_DEVICE_HANDLE_LIST_KHR} was not + specified, the acquire can be performed on a command-queue associated with + any device in the context. + * The memory object will be acquired for all devices specified + via {CL_MEM_DEVICE_HANDLE_LIST_KHR} when the memory object was imported + using {clCreateBufferWithProperties} or {clCreateImageWithProperties}. + If {CL_MEM_DEVICE_HANDLE_LIST_KHR} was not specified, the memory object + will be acquired for all devices in the context. + See <> for more details on how to use this API. @@ -5503,6 +5520,23 @@ Applications must release the memory objects that are acquired using commands in the other API. This is to guarantee that the state of memory objects is up-to-date and they are accessible to the other API. + +The following restrictions shall apply - + * Each memory object must be released only once. Releasing a memory object + multiple times without acquiring it results in implementation-defined + behavior. + * The release must be performed on a command-queue associated with a device + that was one of the devices specified via {CL_MEM_DEVICE_HANDLE_LIST_KHR} + when the memory object was imported using {clCreateBufferWithProperties} or + {clCreateImageWithProperties}. If {CL_MEM_DEVICE_HANDLE_LIST_KHR} was not + specified, the release can be performed on a command-queue associated with + any device in the context. + * The memory object will be released for all devices specified via + {CL_MEM_DEVICE_HANDLE_LIST_KHR} when the memory object was imported + using {clCreateBufferWithProperties} or {clCreateImageWithProperties}. + If {CL_MEM_DEVICE_HANDLE_LIST_KHR} was not specified, the memory object + will be released for all devices in the context. + See "`Example with Acquire / Release`" provided in <> for more details on how to use this API. From bbd474757265746e751fd748d0caefa84ce8da06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Fri, 9 Aug 2024 00:13:42 +0100 Subject: [PATCH 58/71] Fix typo in description of clGetSemaphoreHandleForTypeKHR (#1220) Change-Id: I694d985147ae8a78c25e6a29c49381e58faa3d8b Signed-off-by: Kevin Petit --- api/opencl_runtime_layer.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index b4e3e5087..3027cc730 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -12918,7 +12918,7 @@ include::{generated}/api/protos/clGetSemaphoreHandleForTypeKHR.txt[] * _handle_size_ specifies the size of memory pointed by _handle_ptr_. * _handle_ptr_ is a pointer to memory where the exported external handle is returned. - If _param_value_ is `NULL`, it is ignored. + If _handle_ptr_ is `NULL`, it is ignored. * _handle_size_ret_ returns the actual size in bytes for the external handle. If _handle_size_ret_ is `NULL`, it is ignored. From 4df7df5d61a3ab0a1135d1d7d2b14adb17636e86 Mon Sep 17 00:00:00 2001 From: Grzegorz Wawiorko Date: Fri, 9 Aug 2024 01:14:02 +0200 Subject: [PATCH 59/71] New Intel extension cl_intel_subgroup_buffer_prefetch (#1195) --- ...cl_intel_subgroup_buffer_prefetch.asciidoc | 241 ++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 extensions/cl_intel_subgroup_buffer_prefetch.asciidoc diff --git a/extensions/cl_intel_subgroup_buffer_prefetch.asciidoc b/extensions/cl_intel_subgroup_buffer_prefetch.asciidoc new file mode 100644 index 000000000..142bef7ce --- /dev/null +++ b/extensions/cl_intel_subgroup_buffer_prefetch.asciidoc @@ -0,0 +1,241 @@ += cl_intel_subgroup_buffer_prefetch + +// This section needs to be after the document title. +:doctype: book +:toc2: +:toc: left +:encoding: utf-8 +:lang: en + +:blank: pass:[ +] + +// Set the default source code type in this document to C, +// for syntax highlighting purposes. +:language: c + +== Name Strings + +`cl_intel_subgroup_buffer_prefetch` + +== Contact + +Grzegorz Wawiorko Intel (grzegorz 'dot' wawiorko 'at' intel 'dot' com) + +== Contributors + +// spell-checker: disable +Grzegorz Wawiorko, Intel + +Ben Ashbaugh, Intel + +Andrzej Ratajewski, Intel + +// spell-checker: enable + +== Notice + +Copyright (c) 2024 Intel Corporation. All rights reserved. + +== Status + +Complete + +== Version + +Built On: {docdate} + +Revision: 1 + +== Dependencies + +OpenCL 1.2 and support for `cl_intel_subgroups` is required. + +This extension requires OpenCL support for SPIR-V, either via OpenCL 2.1 or via the `cl_khr_il_program` extension. + +This extension is written against the OpenCL 3.0 C Language specification, V3.0.16. + +== Overview + +The extension adds the ability to prefetch data from a buffer as a sub-group operation. +The functionality added by this extension can improve the performance of some kernels by prefetching data into a cache, so future reads of the data are from a fast cache rather than slower memory. + +The new block prefetch operations are supported both in the OpenCL C kernel programming language and in the SPIR-V intermediate language. + +The prefetch functions are companions to the sub-group block reads described by the extensions `cl_intel_subgroups`, `cl_intel_subgroups_char`, `cl_intel_subgroups_short` and `cl_intel_subgroups_long`. + + +== New API Functions + +None. + +== New API Enums + +None. + +== New OpenCL C Functions + +Add `uchar` variants of the sub-group block prefetch functions: :: ++ +-- +[source] +---- +void intel_sub_group_block_prefetch_uc( const __global uchar* p ) +void intel_sub_group_block_prefetch_uc2( const __global uchar* p ) +void intel_sub_group_block_prefetch_uc4( const __global uchar* p ) +void intel_sub_group_block_prefetch_uc8( const __global uchar* p ) +void intel_sub_group_block_prefetch_uc16( const __global uchar* p ) +---- +-- + +Add `ushort` variants of the sub-group block prefetch functions: :: ++ +-- +[source] +---- +void intel_sub_group_block_prefetch_us( const __global ushort* p ) +void intel_sub_group_block_prefetch_us2( const __global ushort* p ) +void intel_sub_group_block_prefetch_us4( const __global ushort* p ) +void intel_sub_group_block_prefetch_us8( const __global ushort* p ) +void intel_sub_group_block_prefetch_us16( const __global ushort* p ) +---- +-- + +Add `uint` variants of the sub-group block prefetch functions: :: ++ +-- +[source] +---- +void intel_sub_group_block_prefetch_ui( const __global uint* p ) +void intel_sub_group_block_prefetch_ui2( const __global uint* p ) +void intel_sub_group_block_prefetch_ui4( const __global uint* p ) +void intel_sub_group_block_prefetch_ui8( const __global uint* p ) +---- +-- + +Add `ulong` variants of the sub-group block prefetch functions: :: ++ +-- +[source] +---- +void intel_sub_group_block_prefetch_ul( const __global ulong* p ) +void intel_sub_group_block_prefetch_ul2( const __global ulong* p ) +void intel_sub_group_block_prefetch_ul4( const __global ulong* p ) +void intel_sub_group_block_prefetch_ul8( const __global ulong* p ) +---- +-- + +== Modifications to the OpenCL C Specification + +=== Add a new Section 6.15.X - "Sub-group Prefetch Functions" + +-- +[cols="5a,4",options="header"] +|================================== +|*Function* +|*Description* + +|[source,c] +---- +void intel_sub_group_block_prefetch_uc( + const __global uchar* p ) +void intel_sub_group_block_prefetch_uc2( + const __global uchar* p ) +void intel_sub_group_block_prefetch_uc4( + const __global uchar* p ) +void intel_sub_group_block_prefetch_uc8( + const __global uchar* p ) +void intel_sub_group_block_prefetch_uc16( + const __global uchar* p ) +---- + +| Takes 1, 2, 4, 8 or 16 uchars of data for each work item in the sub-group from the specified pointer as a block operation and saves it in the global cache memory. + +Prefetches have no effect on the behavior of the program but can change its performance characteristics. + +|[source,c] +---- +void intel_sub_group_block_prefetch_us( + const __global ushort* p ) +void intel_sub_group_block_prefetch_us2( + const __global ushort* p ) +void intel_sub_group_block_prefetch_us4( + const __global ushort* p ) +void intel_sub_group_block_prefetch_us8( + const __global ushort* p ) +void intel_sub_group_block_prefetch_us16( + const __global ushort* p ) +---- + +| Takes 1, 2, 4, 8 or 16 ushorts of data for each work item in the sub-group from the specified pointer as a block operation and saves it in the global cache memory. + +Prefetches have no effect on the behavior of the program but can change its performance characteristics. + +|[source,c] +---- +void intel_sub_group_block_prefetch_ui( + const __global uint* p ) +void intel_sub_group_block_prefetch_ui2( + const __global uint* p ) +void intel_sub_group_block_prefetch_ui4( + const __global uint* p ) +void intel_sub_group_block_prefetch_ui8( + const __global uint* p ) +---- + +| Takes 1, 2, 4 or 8 uints of data for each work item in the sub-group from the specified pointer as a block operation and saves it in the global cache memory. + +Prefetches have no effect on the behavior of the program but can change its performance characteristics. + +|[source,c] +---- +void intel_sub_group_block_prefetch_ul( + const __global ulong* p ) +void intel_sub_group_block_prefetch_ul2( + const __global ulong* p ) +void intel_sub_group_block_prefetch_ul4( + const __global ulong* p ) +void intel_sub_group_block_prefetch_ul8( + const __global ulong* p ) +---- + +| Takes 1, 2, 4 or 8 ulongs of data for each work item in the sub-group from the specified pointer as a block operation and saves it in the global cache memory. + +Prefetches have no effect on the behavior of the program but can change its performance characteristics. + +|================================== +-- + +== Modifications to the OpenCL SPIR-V Environment Specification + +=== Add a new section 5.2.X - `cl_intel_subgroup_buffer_prefetch` + +If the OpenCL environment supports the extension `cl_intel_subgroup_buffer_prefetch`, then the environment must accept modules that declare use of the extension `SPV_INTEL_subgroup_buffer_prefetch` via *OpExtension*. + +If the OpenCL environment supports the extension `cl_intel_subgroup_buffer_prefetch` and use of the SPIR-V extension `SPV_INTEL_subgroup_buffer_prefetch` is declared in the module via *OpExtension*, then the environment must accept modules that declare the *SubgroupBufferPrefetchINTEL* capability. + +Note that the restrictions described in Section 7.1.X.3 - _Notes and Restrictions_ in the `cl_intel_spirv_subgroups` extension are unchanged and continue to apply for this extension. + +== Issues + +None. + +//. Issue? +//+ +//-- +//`STATUS`: Description. +//-- + +== Revision History + +[cols="5,15,15,70"] +[grid="rows"] +[options="header"] +|======================================== +|Rev|Date|Author|Changes +|1|2024-06-28|Grzegorz Wawiorko|*First public revision.* +|======================================== + +//************************************************************************ +//Other formatting suggestions: +// +//* Use *bold* text for host APIs, or [source] syntax highlighting. +//* Use `mono` text for device APIs, or [source] syntax highlighting. +//* Use `mono` text for extension names, types, or enum values. +//* Use _italics_ for parameters. +//************************************************************************ From 2b99fdbb5d7d10452b7ee4e8fc8b693e1fe13c9a Mon Sep 17 00:00:00 2001 From: tomasz-platek <165791413+tomasz-platek@users.noreply.github.com> Date: Fri, 9 Aug 2024 01:14:37 +0200 Subject: [PATCH 60/71] Publish the cl_img_matrix_multiply extension specification. (#1199) * Publish cl_img_matrix_multiply extension specification. * The final draft of the cl_img_matrix_multiply extension. * Publish the cl_img_bitwise_ops extension specification. * Revert "Publish the cl_img_bitwise_ops extension specification." This reverts commit b17a1f7b3596601b314bdd3dd599c5b1afd85afd. * Update extensions/cl_img_matrix_multiply.asciidoc Listing the initial extension version. Co-authored-by: Ben Ashbaugh * Update cl_img_matrix_multiply.asciidoc Adding execution results to the coding samples --------- Co-authored-by: Ben Ashbaugh --- extensions/cl_img_matrix_multiply.asciidoc | 303 +++++++++++++++++++++ extensions/extensions.txt | 2 + 2 files changed, 305 insertions(+) create mode 100644 extensions/cl_img_matrix_multiply.asciidoc diff --git a/extensions/cl_img_matrix_multiply.asciidoc b/extensions/cl_img_matrix_multiply.asciidoc new file mode 100644 index 000000000..068830280 --- /dev/null +++ b/extensions/cl_img_matrix_multiply.asciidoc @@ -0,0 +1,303 @@ +:data-uri: +:icons: font +include::../config/attribs.txt[] +:source-highlighter: coderay + += cl_img_matrix_multiply + +== Name Strings + +`cl_img_matrix_multiply` + +== Contact + +Imagination Technologies Developer Forum: + +https://forums.imgtec.com/ + +Tomasz Platek, Imagination Technologies (Tomasz.Platek 'at' imgtec.com) + +== Contributors + +CY Cheng, Imagination Technologies. + +Joe Molleson, Imagination Technologies. + +Tomasz Platek, Imagination Technologies. + +== Notice + +Copyright (c) 2024 Imagination Technologies Ltd. All Rights Reserved. + +== Status + +Final Draft + +== Version + +Built On: {docdate} + +Version: 1.0.0 + +== Dependencies + +This extension is written against the OpenCL C Specification Version V3.0.16. + +This extension requires the `cl_khr_fp16` extension. + +== Overview + +This extension adds built-in functions that exercise hardware capabilities of Imagination GPU IP and allow to implement matrix multiplication in highly efficient and performant manner. + +== New OpenCL C Feature Names + +[source,c] +---- +__opencl_img_dot_interleaved +__opencl_img_matmul_2x4_4x4 +---- + +== New OpenCL C Functions + +Perform the interleaved dot product operation: + +[source,c] +---- +float2 img_dot_interleaved(float a,__local float2 * b); +float2 img_dot_interleaved(float2 a,__local float4 * b); +float2 img_dot_interleaved(float4 a,__local float8 * b); +float2 img_dot_interleaved(float8 a,__local float16 * b); +float2 img_dot_interleaved_acc(float a,__local float2 * b, float2 acc); +float2 img_dot_interleaved_acc(float2 a,__local float4 * b, float2 acc); +float2 img_dot_interleaved_acc(float4 a,__local float8 * b, float2 acc); +float2 img_dot_interleaved_acc(float8 a,__local float16 * b, float2 acc); +---- + +Perform the matrix multiplication operation: + +[source,c] +---- +float8 img_matmul_2x4_4x4f(half4 a0, half4 a1,__local half16 * b); +half8 img_matmul_2x4_4x4h(half4 a0, half4 a1,__local half16 * b); +float8 img_matmul_acc_2x4_4x4f(half4 a0, half4 a1,__local half16 * b, float4 acc0, float4 acc1); +half8 img_matmul_acc_2x4_4x4h(half4 a0, half4 a1,__local half16 * b, half4 acc0, half4 acc1); +float8 img_matmul_2x4_4x4transposedf(half4 a0, half4 a1,__local half16 * b); +half8 img_matmul_2x4_4x4transposedh(half4 a0, half4 a1,__local half16 * b); +float8 img_matmul_acc_2x4_4x4transposedf(half4 a0, half4 a1,__local half16 * b, float4 acc0, float4 acc1); +half8 img_matmul_acc_2x4_4x4transposedh(half4 a0, half4 a1,__local half16 * b, half4 acc0, half4 acc1); +---- + +== Modifications to the OpenCL C Specification + +(Add to Table 11 - Built-in Scalar and Vector Argument Math Functions in Section 6.15.2 - Math Functions) :: ++ +-- +[cols="1,2",options="header"] +|==== +| Function | Description +| float2 *img_dot_interleaved*(float _a_,pass:[__local] float2 * _b_) + + float2 *img_dot_interleaved*(float2 _a_,pass:[__local] float4 * _b_) + + float2 *img_dot_interleaved*(float4 _a_,pass:[__local] float8 * _b_) + + float2 *img_dot_interleaved*(float8 _a_,pass:[__local] float16 * _b_) + a| `img_dot_interleaved` performs the dual dot product operation. + The input vectors of the first dot product are `a` and the vector containing the even-indexed elements of `b`. The result is stored into the first element of the output vector. + The input vectors of the second dot product are `a` and the vector containing the odd-indexed elements of `b`. The result is stored into the second element of the output vector. + +For example, given: + +---- +a = [a0 a1] +b = [b0 b1 b2 b3] +---- + +the output vector is: + +---- +[res0 res1] = [a0 a1] x [b0 b1] + [b2 b3] +---- + +Requires that the `__opencl_img_dot_interleaved` feature macro is defined. +| float2 *img_dot_interleaved_acc*(float _a_,pass:[__local] float2 * _b_, float2 _acc_) + + float2 *img_dot_interleaved_acc*(float2 _a_,pass:[__local] float4 * _b_, float2 _acc_) + + float2 *img_dot_interleaved_acc*(float4 _a_,pass:[__local] float8 * _b_, float2 _acc_) + + float2 *img_dot_interleaved_acc*(float8 _a_,pass:[__local] float16 * _b_, float2 _acc_) + a| `img_dot_interleaved_acc` performs the dual dot product operation with the accumulator `acc`. + The input vectors of the first dot product are `a` and the vector containing the even-indexed elements of `b`. The result is stored into the first element of the output vector. + The input vectors of the second dot product are `a` and the vector containing the odd-indexed elements of `b`. The result is stored into the second element of the output vector. + +For example, given: + +---- +a = [a0 a1] +b = [b0 b1 b2 b3] +acc = [acc0 acc1] +---- + +the output vector is: + +---- +[res0 res1] = [a0 a1] x [b0 b1] + [acc0 acc1] + [b2 b3] +---- + +Requires that the `__opencl_img_dot_interleaved` feature macro is defined. +| float8 *img_matmul_2x4_4x4f*(half4 _a0_, half4 _a1_,pass:[__local] half16 * _b_) + + half8 *img_matmul_2x4_4x4h*(half4 _a0_, half4 _a1_,pass:[__local] half16 * _b_) + a| `img_matmul_2x4_4x4f` and `img_matmul_2x4_4x4h` perform the matrix multiplication operation of matrices A and B of dimensions 2x4 and 4x4, where `a0` is the first row and `a1` is the second row of the matrix A. + The first row of the matrix B is represented by the elements 0-3 of `b`, the second row by the elements 4-7, the third row by the elements 8-11, and the fourth row by the elements 12-15. + +For example, given: + +---- +A = [a00 a01 a02 a03] + [a10 a11 a12 a13] +B = [b0 b1 b2 b3] + [b4 b5 b6 b7] + [b8 b9 b10 b11] + [b12 b13 b14 b15] +---- + +the output vector is: + +---- +[res0 res1 res2 res3] = A x B +[res4 res5 res6 res7] +---- + +Requires that the `__opencl_img_matmul_2x4_4x4` feature macro is defined. +| float8 *img_matmul_acc_2x4_4x4f*(half4 _a0_, half4 _a1_,pass:[__local] half16 _b_, float4 _acc0_, float4 _acc1_) + + half8 *img_matmul_acc_2x4_4x4h*(half4 _a0_, half4 _a1_,pass:[__local] half16 _b_, half4 _acc0_, half4 _acc1_) + a| `img_matmul_acc_2x4_4x4f` and `img_matmul_acc_2x4_4x4h` perform the matrix multiplication operation with the accumulator of matrices A and B of dimensions 2x4 and 4x4, where `a0` is the first row and `a1` is the second row of the matrix A, and where `acc0` is the first row and `acc1` is the second row of the accumulator. + The first row of the matrix B is represented by the elements 0-3 of `b`, the second row by the elements 4-7, the third row by the elements 8-11, and the fourth row by the elements 12-15. + +For example, given: + +---- +A = [a00 a01 a02 a03] + [a10 a11 a12 a13] +B = [b0 b1 b2 b3] + [b4 b5 b6 b7] + [b8 b9 b10 b11] + [b12 b13 b14 b15] +C = [acc00 acc01 acc02 acc03] + [acc10 acc11 acc12 acc13] +---- + +the output vector is: + +---- +[res0 res1 res2 res3] = A x B + C +[res4 res5 res6 res7] +---- + +Requires that the `__opencl_img_matmul_2x4_4x4` feature macro is defined. + +| float8 *img_matmul_2x4_4x4transposedf*(half4 _a0_, half4 _a1_,pass:[__local] half16 * _b_) + + half8 *img_matmul_2x4_4x4transposedh*(half4 _a0_, half4 _a1_,pass:[__local] half16 * _b_) + a| `img_matmul_2x4_4x4transposedf` and `img_matmul_2x4_4x4transposedh` perform the matrix multiplication operation of matrix A and transposed matrix B of dimensions 2x4 and 4x4, where `a0` is the first row and `a1` is the second row of the matrix A. + The first row of the matrix B is represented by the elements 0-3 of `b`, the second row by the elements 4-7, the third row by the elements 8-11, and the fourth row by the elements 12-15. + +For example, given: + +---- +A = [a00 a01 a02 a03] + [a10 a11 a12 a13] +BT = [b0 b4 b8 b12] + [b1 b5 b9 b13] + [b2 b6 b10 b14] + [b3 b7 b11 b15] +---- + +the output vector is: + +---- +[res0 res1 res2 res3] = A x BT +[res4 res5 res6 res7] +---- + +Requires that the `__opencl_img_matmul_2x4_4x4` feature macro is defined. +| float8 *img_matmul_acc_2x4_4x4transposedf*(half4 _a0_, half4 _a1_,pass:[__local] half16 * _b_, float4 _acc0_, float4 _acc1_) + + half8 *img_matmul_acc_2x4_4x4transposedh*(half4 _a0_, half4 _a1_,pass:[__local] half16 * _b_, half4 _acc0_, half4 _acc1_) + a| `img_matmul_acc_2x4_4x4transposedf` and `img_matmul_acc_2x4_4x4transposedh` perform the matrix multiplication operation with the accumulator of matrix A and transposed matrix B of dimensions 2x4 and 4x4, where `a0` is the first row and `a1` is the second row of the matrix A, and where `acc0` is the first row and `acc1` is the second row of the accumulator. + The first row of the matrix B is represented by the elements 0-3 of `b`, the second row by the elements 4-7, the third row by the elements 8-11, and the fourth row by the elements 12-15. + +For example, given: + +---- +A = [a00 a01 a02 a03] + [a10 a11 a12 a13] +BT = [b0 b4 b8 b12] + [b1 b5 b9 b13] + [b2 b6 b10 b14] + [b3 b7 b11 b15] +C = [acc00 acc01 acc02 acc03] + [acc10 acc11 acc12 acc13] +---- + +the output vector is: + +---- +[res0 res1 res2 res3] = A x BT + C +[res4 res5 res6 res7] +---- + +Requires that the `__opencl_img_matmul_2x4_4x4` feature macro is defined. +|==== +-- + +== Coding Sample + +This coding sample shows how to initialize the input vectors, use the *img_dot_interleaved_acc* function, and access the output vector: +[source] +---- +float4 a = (float4) (1.0f, 1.0f, 1.0f, 1.0f); +__local float8 b; +b = (float8) (0.0f, 1.0f, 0.0f, 1.0f, 0.0f, 1.0f, 0.0f, 1.0f); + +float2 acc = (float2) (1.0f, 1.0f); +float2 res = img_dot_interleaved_acc(a, &b, acc); + +printf("res = [ %f %f ]\n", res.s0, res.s1); +---- + +Executing a work-item containing this code gives the following result: +[source] +---- +res = [ 1.000000 5.000000 ] +---- + +This coding sample shows how to initialize the input vectors, use the *img_matmul_acc_2x4_4x4f* function, and access the output vector: +[source] +---- +half4 a0 = (half4) (1.0h, 0.0h, 0.0h, 0.0h); +half4 a1 = (half4) (0.0h, 1.0h, 0.0h, 0.0h); + +local half16 b; +b = (half16) (0.0h, 1.0h, 2.0h, 3.0h, + 4.0h, 5.0h, 6.0h, 7.0h, + 8.0h, 9.0h, 10.0h, 11.0h, + 12.0h, 13.0h, 14.0h, 15.0h); + +float4 acc0 = (float4) (1.0f, 1.0f, 1.0f, 1.0f); +float4 acc1 = (float4) (1.0f, 1.0f, 1.0f, 1.0f); + +float8 res = img_matmul_acc_2x4_4x4f(a0, a1, &b, acc0, acc1); + +printf("res = [ %f %f %f %f ]\n", res.s0, res.s1, res.s2, res.s3); +printf(" [ %f %f %f %f ]\n", res.s4, res.s5, res.s6, res.s7); +---- + +Executing a work-item containing this code gives the following result: +[source] +---- +res = [ 1.000000 2.000000 3.000000 4.000000 ] + [ 5.000000 6.000000 7.000000 8.000000 ] +---- + +== Version History + +[cols="5,15,15,70"] +[grid="rows"] +[options="header"] +|==== +| Version | Date | Author | Changes +| 1.0.0 | 2024-06-07 | Tomasz Platek | *Initial revision* +|==== + diff --git a/extensions/extensions.txt b/extensions/extensions.txt index 573ec1169..46596b9f8 100644 --- a/extensions/extensions.txt +++ b/extensions/extensions.txt @@ -67,6 +67,8 @@ include::cl_img_cancel_command.asciidoc[] <<< include::cl_img_generate_mipmap.asciidoc[] <<< +include::cl_img_matrix_multiply.asciidoc[] +<<< include::cl_img_mem_properties.asciidoc[] <<< include::cl_img_use_gralloc_ptr.asciidoc[] From b648551c43cb5fe867924701086046a04bd38e99 Mon Sep 17 00:00:00 2001 From: tomasz-platek <165791413+tomasz-platek@users.noreply.github.com> Date: Fri, 9 Aug 2024 01:14:53 +0200 Subject: [PATCH 61/71] Publish the cl_img_bitwise_ops extension specification. (#1200) * Publish the cl_img_bitwise_ops extension specification. * Update extensions/cl_img_bitwise_ops.asciidoc Listing the initial extension version. Co-authored-by: Ben Ashbaugh --------- Co-authored-by: Ben Ashbaugh --- extensions/cl_img_bitwise_ops.asciidoc | 118 +++++++++++++++++++++++++ extensions/extensions.txt | 2 + 2 files changed, 120 insertions(+) create mode 100644 extensions/cl_img_bitwise_ops.asciidoc diff --git a/extensions/cl_img_bitwise_ops.asciidoc b/extensions/cl_img_bitwise_ops.asciidoc new file mode 100644 index 000000000..fbbd370fa --- /dev/null +++ b/extensions/cl_img_bitwise_ops.asciidoc @@ -0,0 +1,118 @@ +:data-uri: +:icons: font +include::../config/attribs.txt[] +:source-highlighter: coderay + += cl_img_bitwise_ops + +== Name Strings + +`cl_img_bitwise_ops` + +== Contact + +Imagination Technologies Developer Forum: + +https://forums.imgtec.com/ + +Tomasz Platek, Imagination Technologies (Tomasz.Platek 'at' imgtec.com) + +== Contributors + +CY Cheng, Imagination Technologies. + +Tomasz Platek, Imagination Technologies. + +== Notice + +Copyright (c) 2024 Imagination Technologies Ltd. All Rights Reserved. + +== Status + +Final Draft + +== Version + +Built On: {docdate} + +Version: 1.0.0 + +== Dependencies + +This extension is written against the OpenCL C Specification Version V3.0.16. + +== Overview + +This extension adds built-in functions that expose the bitwise operations of Imagination GPU IP that are not accessible by standard OpenCL C functions. + +== New OpenCL C Feature Names + +[source,c] +---- +__opencl_img_bit_interleave +---- + +== New OpenCL C Functions + +Performs the bit interleave operation: + +[source,c] +---- +gentype img_bit_interleave(gentype a, gentype b); +---- + +== Modifications to the OpenCL C Specification + +(Add to Table 16 - Built-in Scalar and Vector Argument Common Functions in Section 6.15.4 - Common Functions) :: ++ +-- +[cols="1,2",options="header"] +|==== +| Function | Description +| gentype *img_bit_interleave*(gentype a, gentype b) + a| `img_bit_interleave` interleaves the first `n` bits from two sources where `n` is half of the size of gentype in bits. + +For `a` and `b`, where a0 and b0 are the least significant bits: +[source] +---- +a = a(N-1)\|a(N-2)\|a(N-3)\|...\|a3\|a2\|a1\|a0 +b = b(N-1)\|b(N-2)\|b(N-3)\|...\|b3\|b2\|b1\|b0 +---- + +the output is: +[source] +---- +res = b(N/2-1)\|a(N/2-1)\|b(N/2-2)\|a(N/2-2)\|b(N/2-3)\|a(N/2-3)\|...\|b3\|a3\|b2\|a2\|b1\|a1\|b0\|a0 +---- +so the sizes of `a`,`b`, and `res` are equal. + +Requires that the `__opencl_img_bit_interleave` feature macro is defined. +|==== +-- + +== Coding Sample + +This coding sample shows how to use the *img_bit_interleave* function: +[source] +---- +int4 a = (int4) ( 0x00000000, 0x00000000, 0x0000FFFF, 0xFFFFFFFF); +int4 b = (int4) ( 0xFFFFFFFF, 0x0000FFFF, 0x00000000, 0x00000000); + +int4 res = img_bit_interleave(a,b); + +printf("res = [ 0x%x 0x%x 0x%x 0x%x]\n", res.s0, res.s1, res.s2, res.s3); +---- + +Executing a work-item of this kernel gives the following result: +[source] +---- +res = [ 0xaaaaaaaa 0xaaaaaaaa 0x55555555 0x55555555] +---- + +== Version History + +[cols="5,15,15,70"] +[grid="rows"] +[options="header"] +|==== +| Version | Date | Author | Changes +| 1.0.0 | 2024-06-19 | Tomasz Platek | *Initial revision* +|==== + diff --git a/extensions/extensions.txt b/extensions/extensions.txt index 46596b9f8..aae06c841 100644 --- a/extensions/extensions.txt +++ b/extensions/extensions.txt @@ -61,6 +61,8 @@ include::cl_arm_scheduling_controls.asciidoc[] == Imagination Technologies Extensions :leveloffset: 2 <<< +include::cl_img_bitwise_ops.asciidoc[] +<<< include::cl_img_cached_allocations.asciidoc[] <<< include::cl_img_cancel_command.asciidoc[] From b6f65dd81c3d2e982fbe8727940fceaf3470ee9b Mon Sep 17 00:00:00 2001 From: tomasz-platek <165791413+tomasz-platek@users.noreply.github.com> Date: Fri, 9 Aug 2024 01:15:09 +0200 Subject: [PATCH 62/71] Publish the cl_img_swap_ops extension specification. (#1201) * Publish the cl_img_swap_ops extension specification. * Update extensions/cl_img_swap_ops.asciidoc Listing the initial extension version. Co-authored-by: Ben Ashbaugh * Update cl_img_swap_ops.asciidoc Defining behavior as undefined for cases when the number of work-items is not evenly divisible by four and if some work-items in the block of four are inactive, defining 1-dimensional local ID as a base for grouping work-items. --------- Co-authored-by: Ben Ashbaugh --- extensions/cl_img_swap_ops.asciidoc | 134 ++++++++++++++++++++++++++++ extensions/extensions.txt | 2 + 2 files changed, 136 insertions(+) create mode 100644 extensions/cl_img_swap_ops.asciidoc diff --git a/extensions/cl_img_swap_ops.asciidoc b/extensions/cl_img_swap_ops.asciidoc new file mode 100644 index 000000000..ea9578022 --- /dev/null +++ b/extensions/cl_img_swap_ops.asciidoc @@ -0,0 +1,134 @@ +:data-uri: +:icons: font +include::../config/attribs.txt[] +:source-highlighter: coderay + += cl_img_swap_ops + +== Name Strings + +`cl_img_swap_ops` + +== Contact + +Imagination Technologies Developer Forum: + +https://forums.imgtec.com/ + +Tomasz Platek, Imagination Technologies (Tomasz.Platek 'at' imgtec.com) + +== Contributors + +CY Cheng, Imagination Technologies. + +Tomasz Platek, Imagination Technologies. + +== Notice + +Copyright (c) 2024 Imagination Technologies Ltd. All Rights Reserved. + +== Status + +Final Draft + +== Version + +Built On: {docdate} + +Version: 1.0.0 + +== Dependencies + +This extension is written against the OpenCL C Specification Version V3.0.16. + +== Overview + +This extension adds built-in functions that exercise hardware capabilities of Imagination GPU IP and expose cross work-items swap functions. + +== New OpenCL C Feature Names + +[source,c] +---- +__opencl_img_swap +---- + +== New OpenCL C Functions + +Perform the swap operation: + +[source,c] +---- +gentype img_swap_x(gentype value); +gentype img_swap_y(gentype value); +---- + +== Modifications to the OpenCL C Specification + +(Add to Table 16 - Built-in Scalar and Vector Argument Common Functions in Section 6.15.4 - Common Functions) :: ++ +-- +[cols="1,2",options="header"] +|==== +| Function | Description +| gentype *img_swap_x*(gentype value) + a| `img_swap_x` swaps `values` between work-items in the following way: all work-items are divided into blocks of four consecutive elements. For each block: + +* In the first work-item, `img_swap_x` returns `value` passed as an argument in the second work-item. +* In the second work-item, `img_swap_x` returns `value` passed as an argument in the first work-item. +* In the third work-item, `img_swap_x` returns `value` passed as an argument in the fourth work-item. +* In the fourth work-item, `img_swap_x` returns `value` passed as an argument in the third work-item. + +The work-items are assigned into blocks based on their 1-dimensional local ID (see `get_local_linear_id`). + +The number of work-items that make up a work-group must be evenly divisible by four; otherwise, the behaviour is undefined. + +The function must be called in all four work-items of the block; otherwise, the behaviour is undefined. + +Requires that the `__opencl_img_swap` feature macro is defined. +| gentype *img_swap_y*(gentype value) + a| `img_swap_y` swaps `values` between work-items in the following way: all work-items are divided into blocks of four consecutive elements. For each block: + +* In the first work-item, `img_swap_y` returns `value` passed as an argument in the third work-item. +* In the third work-item, `img_swap_y` returns `value` passed as an argument in the first work-item. +* In the second work-item, `img_swap_y` returns `value` passed as an argument in the fourth work-item. +* In the fourth work-item, `img_swap_y` returns `value` passed as an argument in the second work-item. + +The work-items are assigned into blocks based on their 1-dimensional local ID (see `get_local_linear_id`). + +The number of work-items that make up a work-group must be evenly divisible by four; otherwise, the behaviour is undefined. + +The function must be called in all four work-items of the block; otherwise, the behaviour is undefined. + +Requires that the `__opencl_img_swap` feature macro is defined. +|==== +-- + +== Coding Sample + +This coding sample shows how to use the *img_swap_x* function: +[source] +---- +__kernel void swap() { + int i = get_global_id(0); + int res = img_swap_x(i); + + printf("id: %d, res = [ %d ]\n", i, res); +} +---- + +Executing four work-items of this kernel in one work-group gives the following result: +[source] +---- +id: 0, res = [ 1 ] +id: 1, res = [ 0 ] +id: 2, res = [ 3 ] +id: 3, res = [ 2 ] +---- + +== Version History + +[cols="5,15,15,70"] +[grid="rows"] +[options="header"] +|==== +| Version | Date | Author | Changes +| 1.0.0 | 2024-06-19 | Tomasz Platek | *Initial revision* +|==== + diff --git a/extensions/extensions.txt b/extensions/extensions.txt index aae06c841..cc4849ccc 100644 --- a/extensions/extensions.txt +++ b/extensions/extensions.txt @@ -73,6 +73,8 @@ include::cl_img_matrix_multiply.asciidoc[] <<< include::cl_img_mem_properties.asciidoc[] <<< +include::cl_img_swap_ops.asciidoc[] +<<< include::cl_img_use_gralloc_ptr.asciidoc[] <<< include::cl_img_yuv_image.asciidoc[] From aca37502a49cfd8f5cba03fdb65e105968c60ef3 Mon Sep 17 00:00:00 2001 From: tomasz-platek <165791413+tomasz-platek@users.noreply.github.com> Date: Fri, 9 Aug 2024 01:24:36 +0200 Subject: [PATCH 63/71] Publish the cl_img_memory_management extension specification. (#1202) * Publish the cl_img_memory_management extension specification. * Update extensions/cl_img_memory_management.asciidoc Listing the initial extension version. Co-authored-by: Ben Ashbaugh * Update cl_img_memory_management.asciidoc Status changed to Final Draft * Update cl_img_memory_management.asciidoc Fix typo (unnecessary "new_alloc" in the enum item name). --------- Co-authored-by: Ben Ashbaugh --- extensions/cl_img_memory_management.asciidoc | 247 +++++++++++++++++++ extensions/extensions.txt | 2 + 2 files changed, 249 insertions(+) create mode 100644 extensions/cl_img_memory_management.asciidoc diff --git a/extensions/cl_img_memory_management.asciidoc b/extensions/cl_img_memory_management.asciidoc new file mode 100644 index 000000000..f9aa61e83 --- /dev/null +++ b/extensions/cl_img_memory_management.asciidoc @@ -0,0 +1,247 @@ +:data-uri: +:icons: font +include::../config/attribs.txt[] +:source-highlighter: coderay + += cl_img_memory_management + +== Name Strings + +`cl_img_memory_management` + +== Contact + +Imagination Technologies Developer Forum: + +https://forums.imgtec.com/ + +Tomasz Platek, Imagination Technologies (Tomasz.Platek 'at' imgtec.com) + +== Contributors + +CY Cheng, Imagination Technologies. + +Tomasz Platek, Imagination Technologies. + +== Notice + +Copyright (c) 2024 Imagination Technologies Ltd. All Rights Reserved. + +== Status + +Final Draft + +== Version + +Built On: {docdate} + +Version: 1.0.0 + +== Dependencies + +This extension is written against the OpenCL C Specification Version V3.0.16. + +== Overview + +This extension adds built-in functions that expose the low-level memory and cache control instructions of Imagination GPU IP that are not accessible by standard OpenCL C functions. + +== New OpenCL C Feature Names + +[source,c] +---- +__opencl_img_fence +__opencl_img_cache +__opencl_img_load_store +---- + +== New OpenCL C Functions + +Issues a data fence: + +[source,c] +---- +void img_fence(cache_target_img target); +---- + +Perform the cache flush/invalidate operation: + +[source,c] +---- +void img_cache_flush(cache_target_img target); +void img_cache_invalidate(cache_target_img target); +void img_cache_flush_invalidate(cache_target_img target); +---- + +Load to/store from memory: + +[source,c] +---- +gentype img_load(gentype *p, cache_coherence_img coherence, L2_cache_policy_img policy, cache_persistence_level_img persistence, bool volatile); +gentype img_load(const gentype *p, cache_coherence_img coherence, L2_cache_policy_img policy, cache_persistence_level_img persistence, bool volatile); +void img_store(gentype *p, gentype value, cache_coherence_img coherence, L2_cache_policy_img policy, cache_persistence_level_img persistence, bool volatile); +---- + +== Modifications to the OpenCL C Specification + +(Add to Table 4 - Other Built-in Data Types in Section 6.3.3. Other Built-in Data Types) :: ++ +[cols=",",options="header",] +|==== +| Type | Description +| `cache_target_img` + | Target of the cache control functions. Refer to the Low-level Memory and Cache Control Functions section for a detailed description + of the built-in functions that use this enum. + +Requires that the `__opencl_img_fence` or the `__opencl_img_cache` feature macro is defined. +| `cache_coherence_img` + | Level of cache coherence. Refer to the Low-level Memory and Cache Control Functions section for a detailed description + of the built-in functions that use this enum. + +Requires that the `__opencl_img_load_store` feature macro is defined. +| `L2_cache_policy_img` + | Cache policy for the L2 cache. Refer to the Low-level Memory and Cache Control Functions section for a detailed description + of the built-in functions that use this enum. + +Requires that the `__opencl_img_load_store` feature macro is defined. +| `cache_persistence_level_img` + | Level of cache persistence. Refer to the Low-level Memory and Cache Control Functions section for a detailed description + of the built-in functions that use this enum. + +Requires that the `__opencl_img_load_store` feature macro is defined. +|==== + +(Add a new Section 6.15.22, *Low-level Memory and Cache Control Functions*) :: ++ +-- +The OpenCL C programming language implements the following built-in functions +to perform low-level memory and cache control operations: + +[cols="1,2",options="header"] +|==== +| Function | Description +| void *img_fence*(cache_target_img target) + a| `img_fence` issues a data fence as far as the specified `target`. For example, using `cache_target_L2_img` issues a data fence for the L1 and L2 caches. + +Requires that the `__opencl_img_fence` feature macro is defined. +| void *img_cache_flush*(cache_target_img target) + a| `img_cache_flush` flushes cache, `target` determines how far through the memory hierarchy caches are flushed. For example, using `cache_target_L2_img` flushes the L1 and L2 caches. + +Requires that the `__opencl_img_cache` feature macro is defined. +| void *img_cache_invalidate*(cache_target_img target) + a| `img_cache_invalidate` invalidates cache, `target` determines how far through the memory hierarchy caches are invalidated. For example, using `cache_target_L2_img` invalidates the L1 and L2 caches. + +Requires that the `__opencl_img_cache` feature macro is defined. +| void *img_cache_flush_invalidate*(cache_target_img target) + a| `img_cache_flush_invalidate` flushes and invalidates cache, `target` determines how far through the memory hierarchy caches are flushed and invalidated. For example, using `cache_target_L2_img` flushes and invalidates the L1 and L2 caches. + +Requires that the `__opencl_img_cache` feature macro is defined. +| gentype *img_load*(gentype pass:[*]p, cache_coherence_img coherence, L2_cache_policy_img policy, cache_persistence_level_img persistence, bool volatile) + + gentype *img_load*(const gentype pass:[*]p, cache_coherence_img coherence, L2_cache_policy_img policy, cache_persistence_level_img persistence, bool volatile) + a| `img_load` returns sizeof(gentype) bytes of data from `p`, where `coherence` specifies the level of cache coherence, `policy` specifies the cache policy for the L2 cache, `persistence` specifies the level of cache persistence, and `volatile` specifies volatility. + +Requires that the `__opencl_img_load_store` feature macro is defined. +| void *img_store*(gentype pass:[*]p, gentype value, cache_coherence_img coherence, L2_cache_policy_img policy, cache_persistence_level_img persistence, bool volatile) + a| `img_store` writes 'value' to `p`, where `coherence` specifies the level of cache coherence, `policy` specifies the cache policy for the L2 cache, `persistence` specifies the level of cache persistence, and `volatile` specifies volatility. + +Requires that the `__opencl_img_load_store` feature macro is defined. +|==== +-- + +=== Cache Target + +The enumerated type `cache_target_img` specifies the target of the cache control functions. +The following table lists the enumeration constants: + +[cols=",",options="header",] +|==== +| Cache Target | Additional Notes +| `cache_target_L1_img` + | Performs the operation on the L1 cache. + +Requires that the `__opencl_img_fence` or the `__opencl_img_cache` feature macro is defined. +| `cache_target_L2_img` + | Performs the operation on the L1 and L2 caches. + +Requires that the `__opencl_img_fence` or the `__opencl_img_cache` feature macro is defined. +| `cache_target_external_img` + | Performs the operation on the L1, L2, and external caches. + +Requires that the `__opencl_img_fence` or the `__opencl_img_cache` feature macro is defined. +|==== + +=== Cache Persistence +Cache persistence modifies the priority of the request in the cache where low level means that requests are evicted quickly and high level means that requests remain in cache for a long time. +The enumerated type `cache_persistence_level_img` specifies the level of cache persistence. +The following table lists the enumeration constants: + +[cols=",",options="header",] +|==== +| Cache Persistence | Additional Notes +| `cache_persistence_level_default_img` + | `cache_persistence_level_min_img` is the default persistence level. + +Requires that the `__opencl_img_load_store` feature macro is defined. +| `cache_persistence_level_min_img` + | Requires that the `__opencl_img_load_store` feature macro is defined. +| `cache_persistence_level_low_img` + | Requires that the `__opencl_img_load_store` feature macro is defined. +| `cache_persistence_level_high_img` + | Requires that the `__opencl_img_load_store` feature macro is defined. +| `cache_persistence_level_max_img` + | Requires that the `__opencl_img_load_store` feature macro is defined. +|==== + +[[cache-coherence]] +==== Cache Coherence +The enumerated type `cache_coherence_img` specifies the level of cache coherence. +The following table lists the enumeration constants: + +[cols=",",options="header",] +|==== +| Cache Coherence | Additional Notes +| `cache_coherence_L1_img` + | Cache coherence is guaranteed at the L1 level. Explicit flush or invalidate may be needed to ensure data coherency at higher levels. + +Requires that the `__opencl_img_load_store` feature macro is defined. +| `cache_coherence_L2_img` + | Cache coherence is guaranteed at the L2 level. Explicit flush or invalidate may be needed to ensure data coherency at higher levels. + +Requires that the `__opencl_img_load_store` feature macro is defined. +|==== + +=== L2 Cache Policy +The enumerated type `L2_cache_policy_img` specifies the cache policy for the L2 cache. +The following table lists the enumeration constants: + +[cols=",",options="header",] +|==== +| L2 Cache Policy | Additional Notes +| `L2_cache_policy_new_alloc_img` + | Allocates a new cache line on a cache miss. + +Requires that the `__opencl_img_load_store` feature macro is defined. +| `L2_cache_policy_bypass_img` + | Permits to bypass the cache and access memory directly. + +Requires that the `__opencl_img_load_store` feature macro is defined. +|==== + +== Coding Sample + +This coding sample shows how to use the *img_load* and *img_store* functions: +[source] +---- +__kernel void test(__global int *in, __global int *out) { + int a = img_load(in, cache_coherence_L1_img, L2_cache_policy_new_alloc_img, cache_persistence_level_min_img, true); + a += 1; + img_store(out, a, cache_coherence_L1_img, L2_cache_policy_new_alloc_img, cache_persistence_level_min_img, true); +} +---- + +== Version History + +[cols="5,15,15,70"] +[grid="rows"] +[options="header"] +|==== +| Version | Date | Author | Changes +| 1.0.0 | 2024-06-19 | Tomasz Platek | *Initial revision* +|==== + diff --git a/extensions/extensions.txt b/extensions/extensions.txt index cc4849ccc..1e1e98049 100644 --- a/extensions/extensions.txt +++ b/extensions/extensions.txt @@ -71,6 +71,8 @@ include::cl_img_generate_mipmap.asciidoc[] <<< include::cl_img_matrix_multiply.asciidoc[] <<< +include::cl_img_memory_management.asciidoc[] +<<< include::cl_img_mem_properties.asciidoc[] <<< include::cl_img_swap_ops.asciidoc[] From 47dd74937ce61fedf5b8b6337a6c851be305ef6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Tue, 13 Aug 2024 01:54:29 +0100 Subject: [PATCH 64/71] Generate OpenCL C feature dictionary (#1212) * Generate OpenCL C feature dictionary Features are stored in a text file for now. Ultimately, we probably want to use the XML registry for this. Generation script taken from #1174 with a few modifications. Contributes to #1166. Signed-off-by: Ben Ashbaugh Signed-off-by: Kevin Petit Change-Id: Ie2c14148d75457030aa1a97cf601daba2c007397 * Update scripts/gen_c_feature_dictionary.py Co-authored-by: Ben Ashbaugh * define __opencl_c_ outside of the list of features Signed-off-by: Kevin Petit Change-Id: I8e0947c30775338dd70803d09c7059d340e86f5a --------- Signed-off-by: Ben Ashbaugh Signed-off-by: Kevin Petit Co-authored-by: Ben Ashbaugh --- Makefile | 3 + c/feature-dictionary.asciidoc | 160 +--------------------------- c/features.txt | 20 ++++ scripts/gen_c_feature_dictionary.py | 87 +++++++++++++++ 4 files changed, 111 insertions(+), 159 deletions(-) create mode 100644 c/features.txt create mode 100644 scripts/gen_c_feature_dictionary.py diff --git a/Makefile b/Makefile index 6aef16a92..5dcaae6f9 100644 --- a/Makefile +++ b/Makefile @@ -512,9 +512,11 @@ $(MANHTMLDIR)/intro.html: $(REFPATH)/intro.txt $(MANCOPYRIGHT) REGISTRY = $(ROOTDIR)/xml APIXML = $(REGISTRY)/cl.xml +CFEATURES = c/features.txt GENSCRIPT = $(SCRIPTS)/gencl.py DICTSCRIPT = $(SCRIPTS)/gen_dictionaries.py VERSIONSCRIPT = $(SCRIPTS)/gen_version_notes.py +CFEATSCRIPT = $(SCRIPTS)/gen_c_feature_dictionary.py GENSCRIPTOPTS = $(VERSIONOPTIONS) $(EXTOPTIONS) $(GENSCRIPTEXTRA) -registry $(APIXML) GENSCRIPTEXTRA = @@ -540,6 +542,7 @@ extinc: $(METADEPEND) $(METADEPEND): $(APIXML) $(GENSCRIPT) $(QUIET)$(MKDIR) $(METAPATH) $(QUIET)$(PYTHON) $(GENSCRIPT) $(GENSCRIPTOPTS) -o $(METAPATH) extinc + $(QUIET)$(PYTHON) $(CFEATSCRIPT) -features $(CFEATURES) -o $(METAPATH)/c-feature-dictionary.asciidoc # This generates a single file containing asciidoc attributes for each # extension in the spec being built. diff --git a/c/feature-dictionary.asciidoc b/c/feature-dictionary.asciidoc index e8375eb57..6e558f24c 100644 --- a/c/feature-dictionary.asciidoc +++ b/c/feature-dictionary.asciidoc @@ -10,162 +10,4 @@ ifndef::backend-html5[] :opencl_c_feature_name: pass:q[`\__opencl_c_​<feature_​name>`] endif::[] -// opencl_c_3d_image_writes -ifdef::backend-html5[] -:opencl_c_3d_image_writes: pass:q[`\__opencl_c_3d_image_writes`] -endif::[] -ifndef::backend-html5[] -:opencl_c_3d_image_writes: pass:q[`\__opencl_c_​3d_​image_​writes`] -endif::[] - -// opencl_c_atomic_order_acq_rel -ifdef::backend-html5[] -:opencl_c_atomic_order_acq_rel: pass:q[`\__opencl_c_atomic_order_acq_rel`] -endif::[] -ifndef::backend-html5[] -:opencl_c_atomic_order_acq_rel: pass:q[`\__opencl_c_​atomic_​order_​​`] -endif::[] - -// opencl_c_atomic_order_seq_cst -ifdef::backend-html5[] -:opencl_c_atomic_order_seq_cst: pass:q[`\__opencl_c_atomic_order_seq_cst`] -endif::[] -ifndef::backend-html5[] -:opencl_c_atomic_order_seq_cst: pass:q[`\__opencl_c_​atomic_​order_​seq_​cst`] -endif::[] - -// opencl_c_atomic_scope_device -ifdef::backend-html5[] -:opencl_c_atomic_scope_device: pass:q[`\__opencl_c_atomic_scope_device`] -endif::[] -ifndef::backend-html5[] -:opencl_c_atomic_scope_device: pass:q[`\__opencl_c_​atomic_​scope_​device`] -endif::[] - -// opencl_c_atomic_scope_all_devices -ifdef::backend-html5[] -:opencl_c_atomic_scope_all_devices: pass:q[`\__opencl_c_atomic_scope_all_devices`] -endif::[] -ifndef::backend-html5[] -:opencl_c_atomic_scope_all_devices: pass:q[`\__opencl_c_​atomic_​scope_​all_​devices`] -endif::[] - -// opencl_c_device_enqueue -ifdef::backend-html5[] -:opencl_c_device_enqueue: pass:q[`\__opencl_c_device_enqueue`] -endif::[] -ifndef::backend-html5[] -:opencl_c_device_enqueue: pass:q[`\__opencl_c_​device_​enqueue`] -endif::[] - -// opencl_c_generic_address_space -ifdef::backend-html5[] -:opencl_c_generic_address_space: pass:q[`\__opencl_c_generic_address_space`] -endif::[] -ifndef::backend-html5[] -:opencl_c_generic_address_space: pass:q[`\__opencl_c_​generic_​address_​space`] -endif::[] - -// opencl_c_fp64 -ifdef::backend-html5[] -:opencl_c_fp64: pass:q[`\__opencl_c_fp64`] -endif::[] -ifndef::backend-html5[] -:opencl_c_fp64: pass:q[`\__opencl_c_​fp64`] -endif::[] - -// opencl_c_images -ifdef::backend-html5[] -:opencl_c_images: pass:q[`\__opencl_c_images`] -endif::[] -ifndef::backend-html5[] -:opencl_c_images: pass:q[`\__opencl_c_​images`] -endif::[] - -// opencl_c_int64 -ifdef::backend-html5[] -:opencl_c_int64: pass:q[`\__opencl_c_int64`] -endif::[] -ifndef::backend-html5[] -:opencl_c_int64: pass:q[`\__opencl_c_​int64`] -endif::[] - -// opencl_c_pipes -ifdef::backend-html5[] -:opencl_c_pipes: pass:q[`\__opencl_c_pipes`] -endif::[] -ifndef::backend-html5[] -:opencl_c_pipes: pass:q[`\__opencl_c_​pipes`] -endif::[] - -// opencl_c_program_scope_global_variables -ifdef::backend-html5[] -:opencl_c_program_scope_global_variables: pass:q[`\__opencl_c_program_scope_global_variables`] -endif::[] -ifndef::backend-html5[] -:opencl_c_program_scope_global_variables: pass:q[`\__opencl_c_​program_​scope_​global_​variables`] -endif::[] - -// opencl_c_read_write_images -ifdef::backend-html5[] -:opencl_c_read_write_images: pass:q[`\__opencl_c_read_write_images`] -endif::[] -ifndef::backend-html5[] -:opencl_c_read_write_images: pass:q[`\__opencl_c_​read_​write_​images`] -endif::[] - -// opencl_c_subgroups -ifdef::backend-html5[] -:opencl_c_subgroups: pass:q[`\__opencl_c_subgroups`] -endif::[] -ifndef::backend-html5[] -:opencl_c_subgroups: pass:q[`\__opencl_c_​subgroups`] -endif::[] - -// opencl_c_work_group_collective_functions -ifdef::backend-html5[] -:opencl_c_work_group_collective_functions: pass:q[`\__opencl_c_work_group_collective_functions`] -endif::[] -ifndef::backend-html5[] -:opencl_c_work_group_collective_functions: pass:q[`\__opencl_c_​work_​group_​collective_​functions`] -endif::[] - -// opencl_c_integer_dot_product_input_4x8bit -ifdef::backend-html5[] -:opencl_c_integer_dot_product_input_4x8bit: pass:q[`\__opencl_c_integer_dot_product_input_4x8bit`] -endif::[] -ifndef::backend-html5[] -:opencl_c_integer_dot_product_input_4x8bit: pass:q[`\__opencl_c_​integer_​dot_​product_​input_​4x8bit`] -endif::[] - -// opencl_c_integer_dot_product_input_4x8bit_packed -ifdef::backend-html5[] -:opencl_c_integer_dot_product_input_4x8bit_packed: pass:q[`\__opencl_c_integer_dot_product_input_4x8bit_packed`] -endif::[] -ifndef::backend-html5[] -:opencl_c_integer_dot_product_input_4x8bit_packed: pass:q[`\__opencl_c_​integer_​dot_​product_​input_​4x8bit_​packed`] -endif::[] - -// opencl_c_kernel_clock_scope_device -ifdef::backend-html5[] -:opencl_c_kernel_clock_scope_device: pass:q[`\__opencl_c_kernel_clock_scope_device`] -endif::[] -ifndef::backend-html5[] -:opencl_c_kernel_clock_scope_device: pass:q[`\__opencl_c_​kernel_​clock_​scope_​device`] -endif::[] - -// opencl_c_kernel_clock_scope_work_group -ifdef::backend-html5[] -:opencl_c_kernel_clock_scope_work_group: pass:q[`\__opencl_c_kernel_clock_scope_work_group`] -endif::[] -ifndef::backend-html5[] -:opencl_c_kernel_clock_scope_work_group: pass:q[`\__opencl_c_​kernel_​clock_​scope_​work_​group`] -endif::[] - -// opencl_c_kernel_clock_scope_sub_group -ifdef::backend-html5[] -:opencl_c_kernel_clock_scope_sub_group: pass:q[`\__opencl_c_kernel_clock_scope_sub_group`] -endif::[] -ifndef::backend-html5[] -:opencl_c_kernel_clock_scope_sub_group: pass:q[`\__opencl_c_​kernel_​clock_​scope_​sub_​group`] -endif::[] +include::{generated}/meta/c-feature-dictionary.asciidoc[] diff --git a/c/features.txt b/c/features.txt new file mode 100644 index 000000000..b7e636dda --- /dev/null +++ b/c/features.txt @@ -0,0 +1,20 @@ +__opencl_c_3d_image_writes +__opencl_c_atomic_order_acq_rel +__opencl_c_atomic_order_seq_cst +__opencl_c_atomic_scope_device +__opencl_c_atomic_scope_all_devices +__opencl_c_device_enqueue +__opencl_c_generic_address_space +__opencl_c_fp64 +__opencl_c_images +__opencl_c_int64 +__opencl_c_pipes +__opencl_c_program_scope_global_variables +__opencl_c_read_write_images +__opencl_c_subgroups +__opencl_c_work_group_collective_functions +__opencl_c_integer_dot_product_input_4x8bit +__opencl_c_integer_dot_product_input_4x8bit_packed +__opencl_c_kernel_clock_scope_device +__opencl_c_kernel_clock_scope_work_group +__opencl_c_kernel_clock_scope_sub_group diff --git a/scripts/gen_c_feature_dictionary.py b/scripts/gen_c_feature_dictionary.py new file mode 100644 index 000000000..f9b071735 --- /dev/null +++ b/scripts/gen_c_feature_dictionary.py @@ -0,0 +1,87 @@ +#!/usr/bin/python3 + +# Copyright 2024 The Khronos Group Inc. +# SPDX-License-Identifier: Apache-2.0 + +from collections import OrderedDict + +import argparse +import sys + +if __name__ == "__main__": + parser = argparse.ArgumentParser() + + parser.add_argument('-features', action='store', + default='', + help='File with OpenCL C features to generate, one per line') + parser.add_argument('-o', action='store', default='', + help='Output file in which to store the feature dictionary. stdout is used if no file is provided.') + + args = parser.parse_args() + + features = [] + if len(args.features) > 0: + print('Generating feature dictionaries from: ' + args.features) + with open(args.features) as f: + features = f.readlines() + else: + print('Reading feature dictionaries from stdin...') + for line in sys.stdin: + features.append(line) + print('Generating...\n') + + numberOfFeatures = 0 + + if args.o: + outfile = open(args.o, 'w') + else: + outfile = sys.stdout + + for name in features: + name = name.strip() + if len(name) == 0: + continue + + # OpenCL C features start with __opencl_c + if name.startswith('__opencl_c'): + #print('found enum: ' + name) + + # Create a variant of the name that precedes underscores with + # "zero width" spaces. This causes some long names to be + # broken at more intuitive places. + htmlName = name[:10] + name[10:].replace("_", "_") + otherName = name[:10] + name[10:].replace("_", "_​") + + # Remove the leading underscores. + name = name[2:] + + # Example: + # + # // opencl_c_images + # ifdef::backend-html5[] + # :opencl_c_images: pass:q[`\__opencl_c_images`] + # endif::[] + # ifndef::backend-html5[] + # :opencl_c_images: pass:q[`\__opencl_c_​images`] + # endif::[] + outfile.write('// ' + name + '\n') + outfile.write('ifdef::backend-html5[]\n') + outfile.write(':' + name + ': pass:q[`\\' + htmlName + '`]\n') + outfile.write('endif::[]\n') + outfile.write('ifndef::backend-html5[]\n') + outfile.write(':' + name + ': pass:q[`\\' + otherName + '`]\n') + outfile.write('endif::[]\n') + + numberOfFeatures = numberOfFeatures + 1 + + # everything else is a function + else: + print('Unexpected feature name: ' + name + ', features should start with __opencl_c!') + sys.exit(1) + + outfile.write('\n') + + if args.o: + outfile.close() + + print('Found ' + str(numberOfFeatures) + ' features.') From e250fcdb71a9e977a590497913d3654d71fd3473 Mon Sep 17 00:00:00 2001 From: Karol Herbst Date: Tue, 13 Aug 2024 18:40:56 +0200 Subject: [PATCH 65/71] further clarify a clCreateBuffer with SVM pointer error condition (#1189) It should also be invalid to use SVM host_ptr smaller than `size` in the CL_MEM_COPY_HOST_PTR case --- api/opencl_runtime_layer.asciidoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 3027cc730..1e7c97126 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -628,8 +628,9 @@ returned in _errcode_ret_: in the <> table. * {CL_INVALID_BUFFER_SIZE} if _size_ is 0, or if _size_ is greater than {CL_DEVICE_MAX_MEM_ALLOC_SIZE} for all devices in _context_, or if - {CL_MEM_USE_HOST_PTR} is set in _flags_ and _host_ptr_ is a pointer returned by - {clSVMAlloc} and _size_ is greater than the size passed to {clSVMAlloc}. + {CL_MEM_USE_HOST_PTR} or {CL_MEM_COPY_HOST_PTR} is set in _flags_ and + _host_ptr_ is a pointer returned by {clSVMAlloc} and _size_ is greater than + the size passed to {clSVMAlloc}. * {CL_INVALID_HOST_PTR} if _host_ptr_ is `NULL` and {CL_MEM_USE_HOST_PTR} or {CL_MEM_COPY_HOST_PTR} are set in _flags_ or if _host_ptr_ is not `NULL` but {CL_MEM_COPY_HOST_PTR} or {CL_MEM_USE_HOST_PTR} are not set in _flags_. From a26e00b504534607646f0844777791663bab1b00 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Tue, 13 Aug 2024 17:42:02 +0100 Subject: [PATCH 66/71] Begin integration of EXT extensions into the unified specification (#1213) * Begin integration of EXT extensions into the unified specification - Add a khr+ext spec type to makeSpec and cover in CI - Document the version and dependencies of all EXT extensions in the XML - Integrate cl_ext_cxx_for_opencl into the unified specification - Add placeholder descriptions for all EXT extensions linking to either core/KHR features that supersede old extensions that were never part of the specification or the OpenCL Extensions document. This enables us to integrate EXT extensions incrementally and integrate future EXT extensions directly into the unified specification. Change-Id: Ic634ce000ad3ebfb56e56bce91f9c0de3e786383 Signed-off-by: Kevin Petit * Update api/cl_ext_cxx_for_opencl.asciidoc Co-authored-by: Ewan Crawford * remove dangling links in cl_ext_migrate_memobject appendix Change-Id: I13b4860dfcd3d6d865b269847c5876bf75516e87 * add links to latest published ext specs Change-Id: Ifddbbc47ddb0ac9be6327d9925682b96829d0946 --------- Signed-off-by: Kevin Petit Co-authored-by: Ewan Crawford --- .github/workflows/presubmit.yml | 6 +- api/cl_ext_cxx_for_opencl.asciidoc | 59 ++++++++ api/cl_ext_device_fission.asciidoc | 20 +++ api/cl_ext_float_atomics.asciidoc | 21 +++ api/cl_ext_image_from_buffer.asciidoc | 21 +++ api/cl_ext_image_raw10_raw12.asciidoc | 21 +++ api/cl_ext_image_requirements_info.asciidoc | 21 +++ api/cl_ext_migrate_memobject.asciidoc | 20 +++ api/opencl_platform_layer.asciidoc | 10 ++ api/opencl_runtime_layer.asciidoc | 11 ++ extensions/cl_ext_cxx_for_opencl.asciidoc | 152 -------------------- extensions/extensions.txt | 2 - makeSpec | 9 +- scripts/extdependency.py | 8 ++ xml/cl.xml | 14 +- 15 files changed, 230 insertions(+), 165 deletions(-) create mode 100644 api/cl_ext_cxx_for_opencl.asciidoc create mode 100644 api/cl_ext_device_fission.asciidoc create mode 100644 api/cl_ext_float_atomics.asciidoc create mode 100644 api/cl_ext_image_from_buffer.asciidoc create mode 100644 api/cl_ext_image_raw10_raw12.asciidoc create mode 100644 api/cl_ext_image_requirements_info.asciidoc create mode 100644 api/cl_ext_migrate_memobject.asciidoc delete mode 100644 extensions/cl_ext_cxx_for_opencl.asciidoc diff --git a/.github/workflows/presubmit.yml b/.github/workflows/presubmit.yml index 6a2d54b32..8d446b606 100644 --- a/.github/workflows/presubmit.yml +++ b/.github/workflows/presubmit.yml @@ -47,10 +47,14 @@ jobs: run: | python3 makeSpec -clean -spec core OUTDIR=out.core -j 5 -O api c env ext cxx4opencl - - name: Generate core + extension specs (HTML) + - name: Generate core + KHR extension specs (HTML) run: | python3 makeSpec -clean -spec khr OUTDIR=out.khr -j -O html + - name: Generate core + KHR + EXT extension specs (HTML) + run: | + python3 makeSpec -clean -spec khr+ext OUTDIR=out.khr+ext -j -O html + - name: Generate reference pages run: | python3 makeSpec -spec khr OUTDIR=out.refpages -j -O manhtmlpages diff --git a/api/cl_ext_cxx_for_opencl.asciidoc b/api/cl_ext_cxx_for_opencl.asciidoc new file mode 100644 index 000000000..51ead70cb --- /dev/null +++ b/api/cl_ext_cxx_for_opencl.asciidoc @@ -0,0 +1,59 @@ +// Copyright 2018-2024 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}cl_ext_cxx_for_opencl.txt[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2020-08-25 +*IP Status*:: + No known IP claims. +*Contributors*:: + - Kevin Petit, Arm Ltd. + + - Sven Van Haastregt, Arm Ltd. + + - Anastasia Stulova, Arm Ltd. + + - Marco Antognini, Arm Ltd. + + - Neil Hickey, Arm Ltd. + + - Alastair Murray, Codeplay + + +=== Description + +This extension adds support for building programs written using the C++ for +OpenCL kernel language documented in the *OpenCL-Docs* repository +(https://github.com/KhronosGroup/OpenCL-Docs) +with stable versions published in releases of the repository. + +This extension also enables applications to query the version of the language +supported by the device compiler. + +=== New Enums + + * {cl_device_info_TYPE} + ** {CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT} + +=== New build option + +This extension adds support for a new `CLC++` value to be passed to the +`-cl-std` build option accepted by {clBuildProgram} and {clCompileProgram}. + +=== Preprocessor Macros + +This extension defines a new language, instead of extending an existing +language. As such, there will be no preprocessor `#define` matching the +extension name string. Instead, dedicated preprocessor macros conveying +language version information are available as described in the C++ for +OpenCL Programming Language Documentation, section 2.2.2.2 "Predefined +macros". + +=== Conformance tests + +. Test that a program can successfully be compiled with `-cl-std=CLC++`. +. Test with a program compiled with `-cl-std=CLC++` that the value of the + +__OPENCL_CPP_VERSION__+ macro agrees with the version returned by + `CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT`. + +=== Version History + + * Revision 1.0.0, 2020-08-24 + ** Initial version. diff --git a/api/cl_ext_device_fission.asciidoc b/api/cl_ext_device_fission.asciidoc new file mode 100644 index 000000000..8b038ef68 --- /dev/null +++ b/api/cl_ext_device_fission.asciidoc @@ -0,0 +1,20 @@ +// Copyright 2018-2024 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}cl_ext_device_fission.txt[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2024-07-17 +*IP Status*:: + No known IP claims. + +=== Description + +Precursor to the functionality described in <>. + +=== Version History + + * Revision 1.0.0, 2024-07-17 + ** First version. diff --git a/api/cl_ext_float_atomics.asciidoc b/api/cl_ext_float_atomics.asciidoc new file mode 100644 index 000000000..473feb40e --- /dev/null +++ b/api/cl_ext_float_atomics.asciidoc @@ -0,0 +1,21 @@ +// Copyright 2018-2024 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}cl_ext_float_atomics.txt[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2020-08-12 +*IP Status*:: + No known IP claims. + +=== Description + +The latest published specification for this extension is available on +the https://registry.khronos.org/OpenCL/extensions/ext/cl_ext_float_atomics.html[OpenCL registry]. + +=== Version History + + * Revision 1.0.0, 2020-08-12 + ** First version. diff --git a/api/cl_ext_image_from_buffer.asciidoc b/api/cl_ext_image_from_buffer.asciidoc new file mode 100644 index 000000000..6bd6fa9bd --- /dev/null +++ b/api/cl_ext_image_from_buffer.asciidoc @@ -0,0 +1,21 @@ +// Copyright 2018-2024 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}cl_ext_image_from_buffer.txt[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2022-01-25 +*IP Status*:: + No known IP claims. + +=== Description + +The latest published specification for this extension is available on +the https://registry.khronos.org/OpenCL/extensions/ext/cl_ext_image_from_buffer.html[OpenCL registry]. + +=== Version History + + * Revision 1.0.0, 2022-01-25 + ** First version. diff --git a/api/cl_ext_image_raw10_raw12.asciidoc b/api/cl_ext_image_raw10_raw12.asciidoc new file mode 100644 index 000000000..d7d36b55d --- /dev/null +++ b/api/cl_ext_image_raw10_raw12.asciidoc @@ -0,0 +1,21 @@ +// Copyright 2018-2024 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}cl_ext_image_raw10_raw12.txt[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2023-05-03 +*IP Status*:: + No known IP claims. + +=== Description + +The latest published specification for this extension is available on +the https://registry.khronos.org/OpenCL/extensions/ext/cl_ext_image_raw10_raw12.html[OpenCL registry]. + +=== Version History + + * Revision 1.0.0, 2023-05-03 + ** First version. diff --git a/api/cl_ext_image_requirements_info.asciidoc b/api/cl_ext_image_requirements_info.asciidoc new file mode 100644 index 000000000..6de780853 --- /dev/null +++ b/api/cl_ext_image_requirements_info.asciidoc @@ -0,0 +1,21 @@ +// Copyright 2018-2024 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}cl_ext_image_requirements_info.txt[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2022-01-18 +*IP Status*:: + No known IP claims. + +=== Description + +The latest published specification for this extension is available on +the https://registry.khronos.org/OpenCL/extensions/ext/cl_ext_image_requirements_info.html[OpenCL registry]. + +=== Version History + + * Revision 0.5.0, 2022-01-18 + ** First version. diff --git a/api/cl_ext_migrate_memobject.asciidoc b/api/cl_ext_migrate_memobject.asciidoc new file mode 100644 index 000000000..b987f48f2 --- /dev/null +++ b/api/cl_ext_migrate_memobject.asciidoc @@ -0,0 +1,20 @@ +// Copyright 2024 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}cl_ext_migrate_memobject.txt[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2024-07-17 +*IP Status*:: + No known IP claims. + +=== Description + +Precursor to {clEnqueueMigrateMemObjects}. + +=== Version History + + * Revision 1.0.0, 2024-07-17 + ** Initial version. diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index ceb6e3193..2b1ae266d 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -2083,6 +2083,15 @@ include::{generated}/api/version-notes/CL_DEVICE_TERMINATE_CAPABILITY_KHR.asciid {CL_DEVICE_TERMINATE_CAPABILITY_CONTEXT_KHR_anchor} - Indicates that context termination is supported. endif::cl_khr_terminate_context[] + +ifdef::cl_ext_cxx_for_opencl[] +| {CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT_anchor} + +include::{generated}/api/version-notes/CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT.asciidoc[] + | {cl_version_TYPE} + | Returns the version of the C++ for OpenCL language supported by the + device compiler. +endif::cl_ext_cxx_for_opencl[] |==== ifdef::cl_khr_integer_dot_product[] @@ -2630,6 +2639,7 @@ Otherwise it may return endif::cl_khr_d3d11_sharing[] +[[platform-device-partitioning]] == Partitioning a Device NOTE: Partitioning devices is <> version 1.2. diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 1e7c97126..4925edd62 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -8427,6 +8427,10 @@ header or implementation-defined source for custom devices that support an online compiler. OpenCL {cpp} is not supported as an online-compiled kernel language through this interface. +ifdef::cl_ext_cxx_for_opencl[] +If the {cl_ext_cxx_for_opencl_EXT} extension is supported, the source code +specified by _strings_ may also be a C++ for OpenCL program source or header. +endif::cl_ext_cxx_for_opencl[] // refError @@ -9519,6 +9523,13 @@ IMPORTANT: Debugging options are <> version 2.0. built-in functions that allow you to enqueue commands on a device (refer to OpenCL kernel languages specifications). +ifdef::cl_ext_cxx_for_opencl[] +==== C++ for OpenCL + +Applications may pass `-cl-std=CLC\++` to {clCompileProgram} or {clBuildProgram} +for programs created using {clCreateProgramFromSource} to request the program +be built as C++ for OpenCL. +endif::cl_ext_cxx_for_opencl[] [[linker-options]] === Linker Options diff --git a/extensions/cl_ext_cxx_for_opencl.asciidoc b/extensions/cl_ext_cxx_for_opencl.asciidoc deleted file mode 100644 index 12bd4406f..000000000 --- a/extensions/cl_ext_cxx_for_opencl.asciidoc +++ /dev/null @@ -1,152 +0,0 @@ -// Copyright 2018-2024 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_ext_cxx_for_opencl -:R: pass:q,r[^(R)^] -Khronos{R} OpenCL Working Group - -== Name Strings - -`cl_ext_cxx_for_opencl` - -== Contact - -Please see the *Issues* list in the Khronos *OpenCL-Docs* repository: + -https://github.com/KhronosGroup/OpenCL-Docs - -== Contributors - -Kevin Petit, Arm Ltd. + -Sven Van Haastregt, Arm Ltd. + -Anastasia Stulova, Arm Ltd. + -Marco Antognini, Arm Ltd. + -Neil Hickey, Arm Ltd. + -Alastair Murray, Codeplay + - -== Notice - -include::../copyrights.txt[] - -== Version - -Built On: {docdate} + -Version: 1.0.0 - -== Dependencies - -This extension is written against the OpenCL Specification -Version 3.0.3. - -This extension requires OpenCL 3.0 with OpenCL C 2.0 support or OpenCL 2.x and -`cl_khr_extended_versioning`. - -== Overview - -This extension adds support for building programs written using the C++ for -OpenCL kernel language documented in the *OpenCL-Docs* repository -(https://github.com/KhronosGroup/OpenCL-Docs) -with stable versions published in releases of the repository. - -This extension also enables applications to query the version of the language -supported by the device compiler. - -== New build option - -This extension adds support for a new `CLC++` value to be passed to the -`-cl-std` build option accepted by *clBuildProgram* and *clCompileProgram*. - -== New API Enums - -Accepted value for the _param_name_ parameter to *clGetDeviceInfo*: - -[source,c] ----- -CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT 0x4230 ----- - -== Preprocessor Macros - -This extension defines a new language, instead of extending an existing -language. As such, there will be no preprocessor `#define` matching the -extension name string. Instead, dedicated preprocessor macros conveying -language version information are available as described in the C++ for -OpenCL Programming Language Documentation, section 2.2.2.2 "Predefined -macros". - - -== Modifications to the OpenCL API Specification - -(Modify Section 4.2, *Querying Devices*) :: -+ --- - -(Add the following to Table 4.3, _Device Queries_) :: -+ --- - -[cols="1,1,4",options="header"] -|==== -| cl_device_info -| Return Type -| Description - -| `CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT` -| `cl_version` -| Returns the version of the C++ for OpenCL language supported by the - device compiler. - -|==== - --- --- - -(Modify Section 5.8.1, *Creating Program Objects*) :: -+ --- -Add the following text to the description for *clCreateProgramWithSource*: - -The source code specified by _strings_ may also be a C++ for OpenCL program source -or header. --- - -(Modify section to 5.8.6, *Compiler Options*) :: -+ --- - -(Add subsection, *C++ for OpenCL*) :: -+ --- -Applications may pass `-cl-std=CLC\++` to *clCompileProgram* and *clBuildProgram* -for programs created using *clCreateProgramFromSource* to request the program -be built as C++ for OpenCL. --- - --- - -== Conformance tests - -. Test that a program can successfully be compiled with `-cl-std=CLC++`. -. Test with a program compiled with `-cl-std=CLC++` that the value of the - +__OPENCL_CPP_VERSION__+ macro agrees with the version returned by - `CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_EXT`. - -== Issues - -None. - -== Version History - -[cols="5,15,15,70"] -[grid="rows"] -[options="header"] -|==== -| Version | Date | Author | Changes -| 1.0.0 | 2020-08-25 | Kevin Petit | *Initial revision* -|==== - diff --git a/extensions/extensions.txt b/extensions/extensions.txt index 1e1e98049..d28468b9c 100644 --- a/extensions/extensions.txt +++ b/extensions/extensions.txt @@ -34,8 +34,6 @@ Khronos{R} OpenCL Working Group == Multi-Vendor Extensions :leveloffset: 2 <<< -include::cl_ext_cxx_for_opencl.asciidoc[] -<<< include::cl_ext_float_atomics.asciidoc[] <<< include::cl_ext_image_from_buffer.asciidoc[] diff --git a/makeSpec b/makeSpec index 4c3decf3c..ac17ffb34 100755 --- a/makeSpec +++ b/makeSpec @@ -42,7 +42,7 @@ if __name__ == '__main__': default='gen', help='Path to directory containing generated files') parser.add_argument('-spec', action='store', - choices=[ 'core', 'khr', 'all' ], + choices=[ 'core', 'khr', 'khr+ext', 'all' ], default='core', help='Type of spec to generate') parser.add_argument('-registry', action='store', @@ -79,8 +79,8 @@ if __name__ == '__main__': # extension appendices yet. if results.spec == 'all': - results.spec = 'khr' - print("WARNING: 'all' argument to -results interpreted as 'khr' at present", file=sys.stderr) + results.spec = 'khr+ext' + print("WARNING: 'all' argument to -results interpreted as 'khr+ext' at present", file=sys.stderr) if results.spec == 'core': title = '' @@ -88,6 +88,9 @@ if __name__ == '__main__': elif results.spec == 'khr': title = 'with all KHR extensions' exts = set(deps.khrExtensions()) + elif results.spec == 'khr+ext': + title = 'with all KHR and EXT extensions' + exts = set(deps.khrAndextExtensions()) elif results.spec == 'all': title = 'with all registered extensions' exts = set(deps.allExtensions()) diff --git a/scripts/extdependency.py b/scripts/extdependency.py index 69dbec3cc..59bfc8381 100755 --- a/scripts/extdependency.py +++ b/scripts/extdependency.py @@ -106,6 +106,7 @@ def __init__(self, self.allExts = set() self.khrExts = set() + self.extExts = set() self.ratifiedExts = set() self.graph = DiGraph() self.extensions = {} @@ -133,6 +134,9 @@ def __init__(self, if conventions.KHR_prefix in name: self.khrExts.add(name) + if conventions.EXT_prefix in name: + self.extExts.add(name) + if api_name in ratified.split(','): self.ratifiedExts.add(name) @@ -159,6 +163,10 @@ def khrExtensions(self): """Returns a set of all KHR extensions in the graph""" return self.khrExts + def khrAndextExtensions(self): + """Returns a set of all KHR and EXT extensions in the graph""" + return self.khrExts | self.extExts + def ratifiedExtensions(self): """Returns a set of all ratified extensions in the graph""" return self.ratifiedExts diff --git a/xml/cl.xml b/xml/cl.xml index 53b9a9be4..e07843004 100644 --- a/xml/cl.xml +++ b/xml/cl.xml @@ -5782,7 +5782,7 @@ server's OpenCL/api-docs repository. - + @@ -5826,7 +5826,7 @@ server's OpenCL/api-docs repository. - + @@ -6764,7 +6764,7 @@ server's OpenCL/api-docs repository. - + @@ -7248,7 +7248,7 @@ server's OpenCL/api-docs repository. - + @@ -7286,7 +7286,7 @@ server's OpenCL/api-docs repository. - + @@ -7377,7 +7377,7 @@ server's OpenCL/api-docs repository. - + @@ -7417,7 +7417,7 @@ server's OpenCL/api-docs repository. - + From b32ac1bdd06027f1514c8f8a27324a94142f580e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Tue, 13 Aug 2024 18:04:51 +0100 Subject: [PATCH 67/71] Clarify what re-import properties are accepted by clReImportSemaphoreSyncFdKHR (#1219) Align the language to clCreateBufferWithProperties. Change-Id: I58659fc9cd7fd3ae5178826285fd84d6932b29d8 Signed-off-by: Kevin Petit --- api/cl_khr_external_semaphore_sync_fd.asciidoc | 2 ++ api/opencl_runtime_layer.asciidoc | 5 ++++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/api/cl_khr_external_semaphore_sync_fd.asciidoc b/api/cl_khr_external_semaphore_sync_fd.asciidoc index aee60ec16..ae1bc7891 100644 --- a/api/cl_khr_external_semaphore_sync_fd.asciidoc +++ b/api/cl_khr_external_semaphore_sync_fd.asciidoc @@ -59,3 +59,5 @@ external semaphore using the APIs introduced by ** Added re-import function call to {cl_khr_external_semaphore_sync_fd_EXT} * Revision 1.0.0, 2024-03-15 ** First non-provisional version. + * Revision 1.0.1, 2024-08-06 + ** Clarify what re-import properties are accepted by {clReImportSemaphoreSyncFdKHR}. diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 4925edd62..263ca1854 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -13085,7 +13085,10 @@ include::{generated}/api/protos/clReImportSemaphoreSyncFdKHR.txt[] * _sema_object_ specifies a valid semaphore object with importable properties. - * _reimport_props_ must be `NULL`, and is reserved for future use. + * _reimport_props_ is an optional list of properties that affect the + re-import behavior. The list is terminated with the special property `0`. + If no properties are required, _reimport_props_ may be `NULL`. This extension + does not define any optional properties. * _fd_ specifies an external file descriptor handle to import Calling {clReImportSemaphoreSyncFdKHR} is equivalent to destroying From d039fc14673e2a9072370a53c20604b35e531980 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Sat, 17 Aug 2024 16:00:14 -0700 Subject: [PATCH 68/71] fix EPSILON typo (#1225) --- OpenCL_C.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/OpenCL_C.txt b/OpenCL_C.txt index 610b54e3c..bfd658f92 100644 --- a/OpenCL_C.txt +++ b/OpenCL_C.txt @@ -5845,7 +5845,7 @@ the application. | `FLT_RADIX` | {CL_FLT_RADIX} | `FLT_MAX` | {CL_FLT_MAX} | `FLT_MIN` | {CL_FLT_MIN} -| `FLT_EPSILSON` | {CL_FLT_EPSILON} +| `FLT_EPSILON` | {CL_FLT_EPSILON} |==== The following macros shall expand to integer constant expressions whose @@ -5916,7 +5916,7 @@ the application. | `DBL_MIN_EXP` | {CL_DBL_MIN_EXP} | `DBL_MAX` | {CL_DBL_MAX} | `DBL_MIN` | {CL_DBL_MIN} -| `DBL_EPSILSON` | {CL_DBL_EPSILON} +| `DBL_EPSILON` | {CL_DBL_EPSILON} |==== The following constants are also available. @@ -5986,7 +5986,7 @@ the application. | `HALF_RADIX` | {CL_HALF_RADIX} | `HALF_MAX` | {CL_HALF_MAX} | `HALF_MIN` | {CL_HALF_MIN} -| `HALF_EPSILSON` | {CL_HALF_EPSILON} +| `HALF_EPSILON` | {CL_HALF_EPSILON} |==== The following constants are also available. From cf1c656d397d472d3ff174c4cf81f7d5ba6b52f5 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Sat, 17 Aug 2024 17:26:06 -0700 Subject: [PATCH 69/71] remove duplicated extensions from quick reference table (#1229) --- ext/quick_reference.asciidoc | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/ext/quick_reference.asciidoc b/ext/quick_reference.asciidoc index 804c30fae..86f979c82 100644 --- a/ext/quick_reference.asciidoc +++ b/ext/quick_reference.asciidoc @@ -240,18 +240,6 @@ Language Specifications. | Allows Use of the SPIR-V `SPV_KHR_no_integer_wrap_decoration` Extension | Extension -| [[cl_khr_spirv_extended_debug_info]] link:{APISpecURL}#cl_khr_spirv_extended_debug_info[{cl_khr_spirv_extended_debug_info_EXT}] -| Allows Use of the SPIR-V `OpenCL.DebugInfo.100` Extended Instruction Set -| Extension - -| [[cl_khr_spirv_linkonce_odr]] link:{APISpecURL}#cl_khr_spirv_linkonce_odr[{cl_khr_spirv_linkonce_odr_EXT}] -| Allows Use of the SPIR-V `SPV_KHR_linkonce_odr` Extension -| Extension - -| [[cl_khr_spirv_no_integer_wrap_decoration]] link:{APISpecURL}#cl_khr_spirv_no_integer_wrap_decoration[{cl_khr_spirv_no_integer_wrap_decoration_EXT}] -| Allows Use of the SPIR-V `SPV_KHR_no_integer_wrap_decoration` Extension -| Extension - | [[cl_khr_srgb_image_writes]] link:{APISpecURL}#cl_khr_srgb_image_writes[{cl_khr_srgb_image_writes_EXT}] | Write to sRGB Images | Extension From 5ad74a27e41a31cc689ddfa9de99a7dcb74ac772 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Thu, 22 Aug 2024 15:53:16 -0700 Subject: [PATCH 70/71] fix asciidoctor rightarrow typo (#1234) --- OpenCL_C.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/OpenCL_C.txt b/OpenCL_C.txt index bfd658f92..c6a096a7d 100644 --- a/OpenCL_C.txt +++ b/OpenCL_C.txt @@ -17300,7 +17300,7 @@ used in the conversions described below. When approximate rounding is used instead of the preferred rounding, the result of the conversion must satisfy the bound given below. -`half` {rightarrow` {CL_UNORM_INT8} (8-bit unsigned integer) +`half` {rightarrow} {CL_UNORM_INT8} (8-bit unsigned integer) [none] * Let f~exact~ = *max*(`0`, *min*(`f * 255`, `255`)) @@ -17308,7 +17308,7 @@ result of the conversion must satisfy the bound given below. * Let f~approx~ = *convert_uchar_sat_*(`f * 255.0f`) * *fabs*(f~exact~ - f~approx~) must be \<= 0.6 -`half` {rightarrow` {CL_UNORM_INT_101010} (10-bit unsigned integer) +`half` {rightarrow} {CL_UNORM_INT_101010} (10-bit unsigned integer) [none] * Let f~exact~ = *max*(`0`, *min*(`f * 1023`, `1023`)) @@ -17317,7 +17317,7 @@ result of the conversion must satisfy the bound given below. * Let f~approx~ = *convert_ushort_sat_*(`f * 1023.0f`) * *fabs*(f~exact~ - f~approx~) must be \<= 0.6 -`half` {rightarrow` {CL_UNORM_INT16} (16-bit unsigned integer) +`half` {rightarrow} {CL_UNORM_INT16} (16-bit unsigned integer) [none] * Let f~exact~ = *max*(`0`, *min*(`f * 65535`, `65535`)) @@ -17326,7 +17326,7 @@ result of the conversion must satisfy the bound given below. 65535.0f`) * *fabs*(f~exact~ - f~approx~) must be \<= 0.6 -`half` {rightarrow` {CL_SNORM_INT8} (8-bit signed integer) +`half` {rightarrow} {CL_SNORM_INT8} (8-bit signed integer) [none] * Let f~exact~ = *max*(`-128`, *min*(`f * 127`, `127`)) @@ -17334,7 +17334,7 @@ result of the conversion must satisfy the bound given below. * Let f~approx~ = *convert_char_sat_*(`f * 127.0f`) * *fabs*(f~exact~ - f~approx~) must be \<= 0.6 -`half` {rightarrow` {CL_SNORM_INT16} (16-bit signed integer) +`half` {rightarrow} {CL_SNORM_INT16} (16-bit signed integer) [none] * Let f~exact~ = *max*(`-32768`, *min*(`f * 32767`, `32767`)) From 0fd19442d06a0f26580ccac0d800c8e76fadd826 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Fri, 23 Aug 2024 10:00:23 -0700 Subject: [PATCH 71/71] update SPIR-V spec reference to SPIR-V 1.6 (#1237) --- env/references.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/env/references.asciidoc b/env/references.asciidoc index f5dabc473..6de0c4e4a 100644 --- a/env/references.asciidoc +++ b/env/references.asciidoc @@ -36,7 +36,7 @@ 3.0, Unified`", https://www.khronos.org/registry/OpenCL/ . // References are to sections and tables of this specific version, although // other versions exists. - . [[spirv-spec]] "`SPIR-V Specification, Version 1.5, Unified`", + . [[spirv-spec]] "`SPIR-V Specification, Version 1.6, Unified`", https://www.khronos.org/registry/spir-v/ . . [[opencl-extended-instruction-set]] "`OpenCL Extended Instruction Set Specification`", https://www.khronos.org/registry/spir-v/ .