Update spec to have less errors

Author: Fábio Mestre

include/ur_api.h

@@ -8275,9 +8275,11 @@ typedef struct ur_exp_command_buffer_update_kernel_launch_desc_t {
     ur_structure_type_t stype;                                                 ///< [in] type of this structure, must be
                                                                                ///< ::UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_UPDATE_KERNEL_LAUNCH_DESC
     const void *pNext;                                                         ///< [in][optional] pointer to extension-specific structure
-    ur_kernel_handle_t hNewKernel;                                             ///< [in] The new kernel handle. If this value is equal to the current
-                                                                               ///< kernel handle associated
-                                                                               ///< with the command, then only the arguments to the kernel will be updated.
+    ur_kernel_handle_t hNewKernel;                                             ///< [in][optional] The new kernel handle. If this parameter is nullptr,
+                                                                               ///< the current kernel handle in `hCommand`
+                                                                               ///< will be used. If a kernel handle is passed, it must be a valid kernel
+                                                                               ///< alternative as defined in
+                                                                               ///< ::urCommandBufferAppendKernelLaunchExp.
     uint32_t numNewMemObjArgs;                                                 ///< [in] Length of pNewMemObjArgList.
     uint32_t numNewPointerArgs;                                                ///< [in] Length of pNewPointerArgList.
     uint32_t numNewValueArgs;                                                  ///< [in] Length of pNewValueArgList.
@@ -8289,13 +8291,25 @@ typedef struct ur_exp_command_buffer_update_kernel_launch_desc_t {
     const ur_exp_command_buffer_update_value_arg_desc_t *pNewValueArgList;     ///< [in][optional][range(0, numNewValueArgs)] An array describing the new
                                                                                ///< kernel value arguments for the command.
     size_t *pNewGlobalWorkOffset;                                              ///< [in][optional][range(0, newWorkDim)] Array of newWorkDim unsigned
-                                                                               ///< values that describe the offset used to calculate the global ID.
+                                                                               ///< values that describe the offset used
+                                                                               ///< to calculate the global ID. If this parameter is nullptr, the current
+                                                                               ///< global work offset will be used. This parameter is required if
+                                                                               ///< `newWorkDim` is different from the current work dimensions
+                                                                               ///< in the command.
     size_t *pNewGlobalWorkSize;                                                ///< [in][optional][range(0, newWorkDim)] Array of newWorkDim unsigned
-                                                                               ///< values that describe the number of global work-items.
+                                                                               ///< values that describe the number of
+                                                                               ///< global work-items. If this parameter is nullptr, the current global
+                                                                               ///< work size in `hCommand` will be used.
+                                                                               ///< This parameter is required if `newWorkDim` is different from the
+                                                                               ///< current work dimensions in the command.
     size_t *pNewLocalWorkSize;                                                 ///< [in][optional][range(0, newWorkDim)] Array of newWorkDim unsigned
-                                                                               ///< values that describe the number of work-items that make up a
-                                                                               ///< work-group. If pNewLocalWorkSize is nullptr, then the local work size
-                                                                               ///< is unchanged.
+                                                                               ///< values that describe the number of
+                                                                               ///< work-items that make up a work-group. If `pNewGlobalWorkSize` is set
+                                                                               ///< and `pNewLocalWorkSize` is nullptr,
+                                                                               ///< then the runtime implementation will choose the local work size. If
+                                                                               ///< `pNewGlobalWorkSize` is nullptr and
+                                                                               ///< `pNewLocalWorkSize` is nullptr, the current local work size in the
+                                                                               ///< command will be used.
 
 } ur_exp_command_buffer_update_kernel_launch_desc_t;
 
@@ -8438,8 +8452,8 @@ urCommandBufferAppendKernelLaunchExp(
                                                                   ///< implementation.
     uint32_t numKernelAlternatives,                               ///< [in] The number of kernel alternatives provided in
                                                                   ///< phKernelAlternatives.
-    ur_kernel_handle_t *phKernelAlternatives,                     ///< [in][optional][range(0, numKernelAlternatives)] List of kernels
-                                                                  ///< handles that might be used to update the kernel in this
+    ur_kernel_handle_t *phKernelAlternatives,                     ///< [in][optional][range(0, numKernelAlternatives)] List of kernel handles
+                                                                  ///< that might be used to update the kernel in this
                                                                   ///< command after the command-buffer is finalized. The default kernel
                                                                   ///< `hKernel` is implicitly marked as an alternative. It's
                                                                   ///< invalid to specify it as part of this list.
@@ -8950,26 +8964,69 @@ urCommandBufferReleaseCommandExp(
 ///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
 ///         + `NULL == hCommand`
-///         + `NULL == pUpdateKernelLaunch->hNewKernel`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == pUpdateKernelLaunch`
 ///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
 ///         + If update functionality is not supported by the device.
 ///     - ::UR_RESULT_ERROR_INVALID_OPERATION
 ///         + If ::ur_exp_command_buffer_desc_t::isUpdatable was not set to true on creation of the command buffer `hCommand` belongs to.
 ///         + If the command-buffer `hCommand` belongs to has not been finalized.
-///         + `pUpdateKernelLaunch->pNewLocalWorkSize != NULL && pUpdateKernelLaunch->pNewGlobalWorkSize == NULL`
-///         + If `pUpdateKernellaunch->hNewKernel` is equal to the currently active kernel in `hCommand`, and `pUpdateKernellaunch->newWorkDim` is different from the work-dim currently associated with `hCommand`.
 ///     - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_COMMAND_HANDLE_EXP
 ///     - ::UR_RESULT_ERROR_INVALID_MEM_OBJECT
 ///     - ::UR_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_INDEX
 ///     - ::UR_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_SIZE
 ///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
 ///     - ::UR_RESULT_ERROR_INVALID_WORK_DIMENSION
-///         + `pUpdateKernelLaunch->newWorkDim < 0 || pUpdateKernelLaunch->newWorkDim > 3`
+///         + `pUpdateKernelLaunch->newWorkDim < 1 || pUpdateKernelLaunch->newWorkDim > 3`
 ///     - ::UR_RESULT_ERROR_INVALID_WORK_GROUP_SIZE
 ///     - ::UR_RESULT_ERROR_INVALID_VALUE
-///         + If `pUpdateKernelLaunch->hNewKernel` was not passed to the `hKernel` or `phKernelAlternatives` parameters of ::urCommandBufferAppendKernelLaunchExp when this command was created.
+///         + *
+///         +
+///         + I
+///         + f
+///         + `
+///         + p
+///         + U
+///         + d
+///         + a
+///         + t
+///         + e
+///         + K
+///         + r
+///         + n
+///         + l
+///         + L
+///         + u
+///         + c
+///         + h
+///         + -
+///         + >
+///         + N
+///         + w
+///         + s
+///         + o
+///         + A
+///         + i
+///         + v
+///         +
+
+///         + m
+///         + $
+///         + x
+///         + C
+///         + B
+///         + E
+///         + .
+///         + "
+///         + W
+///         + k
+///         + D
+///         + ,
+///         + G
+///         + b
+///         + S
+///         + z
+///         + O
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 ///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
 UR_APIEXPORT ur_result_t UR_APICALL

scripts/core/exp-command-buffer.yml

@@ -195,8 +195,9 @@ members:
     - type: $x_kernel_handle_t
       name: hNewKernel
       desc: |
-        [in] The new kernel handle. If this value is equal to the current kernel handle associated 
-        with the command, then only the arguments to the kernel will be updated.
+        [in][optional] The new kernel handle. If this parameter is nullptr, the current kernel handle in `hCommand`
+        will be used. If a kernel handle is passed, it must be a valid kernel alternative as defined in
+        $xCommandBufferAppendKernelLaunchExp.
     - type: uint32_t
       name: numNewMemObjArgs
       desc: "[in] Length of pNewMemObjArgList."
@@ -220,13 +221,23 @@ members:
       desc: "[in][optional][range(0, numNewValueArgs)] An array describing the new kernel value arguments for the command."
     - type: "size_t*"
       name: pNewGlobalWorkOffset
-      desc: "[in][optional][range(0, newWorkDim)] Array of newWorkDim unsigned values that describe the offset used to calculate the global ID."
+      desc: |
+        [in][optional][range(0, newWorkDim)] Array of newWorkDim unsigned values that describe the offset used
+        to calculate the global ID. If this parameter is nullptr, the current global work offset will be used. This parameter is required if `newWorkDim` is different from the current work dimensions
+        in the command.
     - type: "size_t*"
       name: pNewGlobalWorkSize
-      desc: "[in][optional][range(0, newWorkDim)] Array of newWorkDim unsigned values that describe the number of global work-items."
+      desc: |
+        [in][optional][range(0, newWorkDim)] Array of newWorkDim unsigned values that describe the number of
+        global work-items. If this parameter is nullptr, the current global work size in `hCommand` will be used.
+        This parameter is required if `newWorkDim` is different from the current work dimensions in the command.
     - type: "size_t*"
       name: pNewLocalWorkSize
-      desc: "[in][optional][range(0, newWorkDim)] Array of newWorkDim unsigned values that describe the number of work-items that make up a work-group. If pNewLocalWorkSize is nullptr, then the local work size is unchanged."
+      desc: |
+        [in][optional][range(0, newWorkDim)] Array of newWorkDim unsigned values that describe the number of
+        work-items that make up a work-group. If `pNewGlobalWorkSize` is set and `pNewLocalWorkSize` is nullptr,
+        then the runtime implementation will choose the local work size. If `pNewGlobalWorkSize` is nullptr and
+        `pNewLocalWorkSize` is nullptr, the current local work size in the command will be used.
 --- #--------------------------------------------------------------------------
 type: typedef
 desc: "A value that identifies a command inside of a command-buffer, used for defining dependencies between commands in the same command-buffer."
@@ -340,7 +351,7 @@ params:
     - type: $x_kernel_handle_t*
       name: "phKernelAlternatives"
       desc: |
-            [in][optional][range(0, numKernelAlternatives)] List of kernels handles that might be used to update the kernel in this 
+            [in][optional][range(0, numKernelAlternatives)] List of kernel handles that might be used to update the kernel in this
             command after the command-buffer is finalized. The default kernel `hKernel` is implicitly marked as an alternative. It's
             invalid to specify it as part of this list.
     - type: uint32_t
@@ -954,18 +965,19 @@ returns:
     - $X_RESULT_ERROR_INVALID_OPERATION:
         - "If $x_exp_command_buffer_desc_t::isUpdatable was not set to true on creation of the command buffer `hCommand` belongs to."
         - "If the command-buffer `hCommand` belongs to has not been finalized."
-        - "`pUpdateKernelLaunch->pNewLocalWorkSize != NULL && pUpdateKernelLaunch->pNewGlobalWorkSize == NULL`"
-        - "If `pUpdateKernellaunch->hNewKernel` is equal to the currently active kernel in `hCommand`, and `pUpdateKernellaunch->newWorkDim` is different from the work-dim currently associated with `hCommand`."
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_COMMAND_HANDLE_EXP
     - $X_RESULT_ERROR_INVALID_MEM_OBJECT
     - $X_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_INDEX
     - $X_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_SIZE
     - $X_RESULT_ERROR_INVALID_ENUMERATION
     - $X_RESULT_ERROR_INVALID_WORK_DIMENSION:
-        - "`pUpdateKernelLaunch->newWorkDim < 0 || pUpdateKernelLaunch->newWorkDim > 3`"
+        - "`pUpdateKernelLaunch->newWorkDim < 1 || pUpdateKernelLaunch->newWorkDim > 3`"
     - $X_RESULT_ERROR_INVALID_WORK_GROUP_SIZE
-    - $X_RESULT_ERROR_INVALID_VALUE:
-        - "If `pUpdateKernelLaunch->hNewKernel` was not passed to the `hKernel` or `phKernelAlternatives` parameters of $xCommandBufferAppendKernelLaunchExp when this command was created."
+    - $X_RESULT_ERROR_INVALID_VALUE: |
+        * If `pUpdateKernelLaunch->hNewKernel` was not passed to the `hKernel` or `phKernelAlternatives`
+        parameters of $xCommandBufferAppendKernelLaunchExp when this command was created.
+        * "If `pUpdateKernelLaunch->newWorkDim` is different from the current workDim in `hCommand` and,
+        pUpdateKernelLaunch->pNewGlobalWorkSize, or pUpdateKernelLaunch->pNewGlobalWorkOffset are nullptr.
     - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
     - $X_RESULT_ERROR_OUT_OF_RESOURCES
 --- #--------------------------------------------------------------------------

source/adapters/cuda/command_buffer.cpp

@@ -877,22 +877,19 @@ validateCommandDesc(ur_exp_command_buffer_command_handle_t Command,
 
   auto CommandBuffer = Command->CommandBuffer;
 
-  // Update requires command-buffer to be finalized
-  if (!CommandBuffer->CudaGraphExec) {
-    return UR_RESULT_ERROR_INVALID_OPERATION;
-  }
-
-  // Update requires command-buffer to be created with update enabled
-  if (!CommandBuffer->IsUpdatable) {
+  // Update requires the command-buffer to be finalized and updatable.
+  if (!CommandBuffer->CudaGraphExec || !CommandBuffer->IsUpdatable) {
     return UR_RESULT_ERROR_INVALID_OPERATION;
   }
 
   if (UpdateCommandDesc->newWorkDim != Command->WorkDim &&
-      Command->Kernel == UpdateCommandDesc->hNewKernel) {
-    return UR_RESULT_ERROR_INVALID_OPERATION;
+      (!UpdateCommandDesc->pNewGlobalWorkOffset ||
+       !UpdateCommandDesc->pNewGlobalWorkSize)) {
+    return UR_RESULT_ERROR_INVALID_VALUE;
   }
 
-  if (!Command->ValidKernelHandles.count(UpdateCommandDesc->hNewKernel)) {
+  if (UpdateCommandDesc->hNewKernel &&
+      !Command->ValidKernelHandles.count(UpdateCommandDesc->hNewKernel)) {
     return UR_RESULT_ERROR_INVALID_VALUE;
   }
   return UR_RESULT_SUCCESS;
@@ -987,7 +984,9 @@ updateCommand(ur_exp_command_buffer_command_handle_t Command,
               const ur_exp_command_buffer_update_kernel_launch_desc_t
                   *UpdateCommandDesc) {
 
-  Command->Kernel = UpdateCommandDesc->hNewKernel;
+  if (UpdateCommandDesc->hNewKernel) {
+    Command->Kernel = UpdateCommandDesc->hNewKernel;
+  }
 
   if (UpdateCommandDesc->newWorkDim) {
     Command->WorkDim = UpdateCommandDesc->newWorkDim;
@@ -999,6 +998,9 @@ updateCommand(ur_exp_command_buffer_command_handle_t Command,
 
   if (UpdateCommandDesc->pNewGlobalWorkSize) {
     Command->setGlobalSize(UpdateCommandDesc->pNewGlobalWorkSize);
+    if (!UpdateCommandDesc->pNewLocalWorkSize) {
+      Command->setNullLocalSize();
+    }
   }
 
   if (UpdateCommandDesc->pNewLocalWorkSize) {

source/adapters/cuda/command_buffer.hpp

@@ -75,6 +75,10 @@ struct ur_exp_command_buffer_command_handle_t_ {
     }
   }
 
+  void setNullLocalSize() noexcept {
+    std::memset(LocalWorkSize, 0, sizeof(size_t) * 3);
+  }
+
   bool isNullLocalSize() const noexcept {
     const size_t Zeros[3] = {0, 0, 0};
     return 0 == std::memcmp(LocalWorkSize, Zeros, sizeof(LocalWorkSize));

source/adapters/hip/command_buffer.cpp

@@ -862,22 +862,19 @@ validateCommandDesc(ur_exp_command_buffer_command_handle_t Command,
 
   auto CommandBuffer = Command->CommandBuffer;
 
-  // Update requires command-buffer to be finalized
-  if (!CommandBuffer->HIPGraphExec) {
-    return UR_RESULT_ERROR_INVALID_OPERATION;
-  }
-
-  // Update requires command-buffer to be created with update enabled
-  if (!CommandBuffer->IsUpdatable) {
+  // Update requires the command-buffer to be finalized and updatable.
+  if (!CommandBuffer->HIPGraphExec || !CommandBuffer->IsUpdatable) {
     return UR_RESULT_ERROR_INVALID_OPERATION;
   }
 
   if (UpdateCommandDesc->newWorkDim != Command->WorkDim &&
-      Command->Kernel == UpdateCommandDesc->hNewKernel) {
-    return UR_RESULT_ERROR_INVALID_OPERATION;
+      (!UpdateCommandDesc->pNewGlobalWorkOffset ||
+       !UpdateCommandDesc->pNewGlobalWorkSize)) {
+    return UR_RESULT_ERROR_INVALID_VALUE;
   }
 
-  if (!Command->ValidKernelHandles.count(UpdateCommandDesc->hNewKernel)) {
+  if (UpdateCommandDesc->hNewKernel &&
+      !Command->ValidKernelHandles.count(UpdateCommandDesc->hNewKernel)) {
     return UR_RESULT_ERROR_INVALID_VALUE;
   }
 
@@ -967,7 +964,9 @@ updateCommand(ur_exp_command_buffer_command_handle_t Command,
               const ur_exp_command_buffer_update_kernel_launch_desc_t
                   *UpdateCommandDesc) {
 
-  Command->Kernel = UpdateCommandDesc->hNewKernel;
+  if (UpdateCommandDesc->hNewKernel) {
+    Command->Kernel = UpdateCommandDesc->hNewKernel;
+  }
 
   if (UpdateCommandDesc->hNewKernel) {
     Command->WorkDim = UpdateCommandDesc->newWorkDim;
@@ -979,6 +978,9 @@ updateCommand(ur_exp_command_buffer_command_handle_t Command,
 
   if (UpdateCommandDesc->pNewGlobalWorkSize) {
     Command->setGlobalSize(UpdateCommandDesc->pNewGlobalWorkSize);
+    if (!UpdateCommandDesc->pNewLocalWorkSize) {
+      Command->setNullLocalSize();
+    }
   }
 
   if (UpdateCommandDesc->pNewLocalWorkSize) {

source/adapters/hip/command_buffer.hpp

@@ -74,6 +74,10 @@ struct ur_exp_command_buffer_command_handle_t_ {
     }
   }
 
+  void setNullLocalSize() noexcept {
+    std::memset(LocalWorkSize, 0, sizeof(size_t) * 3);
+  }
+
   bool isNullLocalSize() const noexcept {
     const size_t Zeros[3] = {0, 0, 0};
     return 0 == std::memcmp(LocalWorkSize, Zeros, sizeof(LocalWorkSize));

source/adapters/level_zero/command_buffer.cpp

@@ -1325,10 +1325,10 @@ ur_result_t validateCommandDesc(
     return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
   }
 
-  // Error if work dim changes
-  if (CommandDesc->hNewKernel == Command->Kernel &&
-      CommandDesc->newWorkDim != Command->WorkDim) {
-    return UR_RESULT_ERROR_INVALID_OPERATION;
+  if (CommandDesc->newWorkDim != Command->WorkDim &&
+      (!CommandDesc->pNewGlobalWorkOffset ||
+       !CommandDesc->pNewGlobalWorkSize)) {
+    return UR_RESULT_ERROR_INVALID_VALUE;
   }
 
   // Check if new global offset is provided.