Merge branch 'main' into change-log-from-3-0.15

bashbaug · Apr 2, 2024 · 20bd4f1 · 20bd4f1
2 parents 8b3578c + 75df78c
commit 20bd4f1
Show file tree

Hide file tree

Showing 39 changed files with 1,113 additions and 582 deletions.
diff --git 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/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
diff --git 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/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:
-      ** `<<cl_khr_async_copy_fence>>` (final)
+      ** `<<cl_khr_async_work_group_copy_fence>>` (final)
       ** `<<cl_khr_extended_async_copies>>` (final)
       ** `<<cl_khr_expect_assume>>`
       ** `<<cl_khr_command_buffer>>` (provisional)

diff --git 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,11 +326,129 @@ 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 <<valid-object-definition,valid command-buffer>>.
+
+| {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 <<valid-object-definition,valid mutable-command object>>.
+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}
 
 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 <<valid-object-definition,valid semaphore>>.
+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
@@ -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 <<error_codes, Error Codes>>
+  * 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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_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/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
@@ -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_kernel_clock.asciidoc 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/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