Merge branch 'main' into cl_img_memory_management

KhronosGroup · Aug 8, 2024 · 6de353d · 6de353d
2 parents 1c057a3 + b6f65dd
commit 6de353d
Show file tree

Hide file tree

Showing 32 changed files with 1,131 additions and 249 deletions.
diff --git 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
@@ -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:
@@ -116,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
 #
@@ -545,6 +546,7 @@ $(METADEPEND): $(APIXML) $(GENSCRIPT)
 attribs: $(ATTRIBFILE)
 
 $(ATTRIBFILE):
+	$(QUIET)$(MKDIR) $(dir $@)
 	for attrib in $(EXTS) ; do \
 	    echo ":$${attrib}:" ; \
 	done > $@

diff --git 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/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_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}