[EXP][Command-Buffer] Add kernel command update

This change introduces a new API that allows the
kernel commands of a command-buffer to be updated
with a new configuration. For example, modified
arguments or ND-Range. The only implemented adapter
is CUDA.

See
[cl_khr_command_buffer_mutable_dispatch](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#cl_khr_command_buffer_mutable_dispatch)
as prior art. The differences between the proposed API and the above
are:

* Only the append kernel entry-point returns a command handle. I imagine
  this will be changed in future to enable other commands to do update.
* Only USM and buffer arguments can be updated, there is not equivalent
  update struct for `urKernelSetArgLocal`, `urKernelSetArgValue`, or
  `urKernelSetArgSampler`
* There is no granularity of optional support for update, an implementer
  must either implement all the ways to update a kernel configuration,
  or none of them.

Author: EwanC

include/ur.py

@@ -187,6 +187,7 @@ class ur_function_v(IntEnum):
     ADAPTER_RETAIN = 179                            ## Enumerator for ::urAdapterRetain
     ADAPTER_GET_LAST_ERROR = 180                    ## Enumerator for ::urAdapterGetLastError
     ADAPTER_GET_INFO = 181                          ## Enumerator for ::urAdapterGetInfo
+    COMMAND_BUFFER_UPDATE_KERNEL_LAUNCH_EXP = 182   ## Enumerator for ::urCommandBufferUpdateKernelLaunchExp
     PROGRAM_BUILD_EXP = 197                         ## Enumerator for ::urProgramBuildExp
     PROGRAM_COMPILE_EXP = 198                       ## Enumerator for ::urProgramCompileExp
     PROGRAM_LINK_EXP = 199                          ## Enumerator for ::urProgramLinkExp
@@ -250,6 +251,10 @@ class ur_structure_type_v(IntEnum):
     KERNEL_ARG_VALUE_PROPERTIES = 32                ## ::ur_kernel_arg_value_properties_t
     KERNEL_ARG_LOCAL_PROPERTIES = 33                ## ::ur_kernel_arg_local_properties_t
     EXP_COMMAND_BUFFER_DESC = 0x1000                ## ::ur_exp_command_buffer_desc_t
+    EXP_COMMAND_BUFFER_UPDATE_KERNEL_LAUNCH_DESC = 0x1001   ## ::ur_exp_command_buffer_update_kernel_launch_desc_t
+    EXP_COMMAND_BUFFER_UPDATE_MEMOBJ_ARG_DESC = 0x1002  ## ::ur_exp_command_buffer_update_memobj_arg_desc_t
+    EXP_COMMAND_BUFFER_UPDATE_POINTER_ARG_DESC = 0x1003 ## ::ur_exp_command_buffer_update_pointer_arg_desc_t
+    EXP_COMMAND_BUFFER_UPDATE_EXEC_INFO_DESC = 0x1004   ## ::ur_exp_command_buffer_update_exec_info_desc_t
     EXP_SAMPLER_MIP_PROPERTIES = 0x2000             ## ::ur_exp_sampler_mip_properties_t
     EXP_INTEROP_MEM_DESC = 0x2001                   ## ::ur_exp_interop_mem_desc_t
     EXP_INTEROP_SEMAPHORE_DESC = 0x2002             ## ::ur_exp_interop_semaphore_desc_t
@@ -455,6 +460,7 @@ class ur_result_v(IntEnum):
     ERROR_INVALID_COMMAND_BUFFER_EXP = 0x1000       ## Invalid Command-Buffer
     ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP = 0x1001## Sync point is not valid for the command-buffer
     ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP = 0x1002  ## Sync point wait list is invalid
+    ERROR_INVALID_COMMAND_BUFFER_COMMAND_HANDLE_EXP = 0x1003## Handle to command-buffer command is invalid
     ERROR_UNKNOWN = 0x7ffffffe                      ## Unknown or internal error
 
 class ur_result_t(c_int):
@@ -865,6 +871,10 @@ class ur_device_info_v(IntEnum):
                                                     ## version than older devices.
     VIRTUAL_MEMORY_SUPPORT = 114                    ## [::ur_bool_t] return true if the device supports virtual memory.
     ESIMD_SUPPORT = 115                             ## [::ur_bool_t] return true if the device supports ESIMD.
+    COMMAND_BUFFER_SUPPORT_EXP = 0x1000             ## [::ur_bool_t] returns true if the device supports the use of
+                                                    ## command-buffers.
+    COMMAND_BUFFER_UPDATE_SUPPORT_EXP = 0x1001      ## [::ur_bool_t] returns true if the device supports updating the
+                                                    ## commands in a command-buffer.
     BINDLESS_IMAGES_SUPPORT_EXP = 0x2000            ## [::ur_bool_t] returns true if the device supports the creation of
                                                     ## bindless images
     BINDLESS_IMAGES_SHARED_USM_SUPPORT_EXP = 0x2001 ## [::ur_bool_t] returns true if the device supports the creation of
@@ -2300,7 +2310,71 @@ class ur_exp_command_buffer_desc_t(Structure):
     _fields_ = [
         ("stype", ur_structure_type_t),                                 ## [in] type of this structure, must be
                                                                         ## ::UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC
-        ("pNext", c_void_p)                                             ## [in][optional] pointer to extension-specific structure
+        ("pNext", c_void_p),                                            ## [in][optional] pointer to extension-specific structure
+        ("isUpdatable", ur_c_bool_t)                                    ## [in] Commands in a finalized command-buffer can be updated.
+    ]
+
+###############################################################################
+## @brief Descriptor type for updating a kernel command memobj argument.
+class ur_exp_command_buffer_update_memobj_arg_desc_t(Structure):
+    _fields_ = [
+        ("stype", ur_structure_type_t),                                 ## [in] type of this structure, must be
+                                                                        ## ::UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_UPDATE_MEMOBJ_ARG_DESC
+        ("pNext", c_void_p),                                            ## [in][optional] pointer to extension-specific structure
+        ("argIndex", c_ulong),                                          ## [in] Argument index.
+        ("pProperties", *),                                             ## [in][optinal] Pointer to memory object properties.
+        ("hArgValue", ur_mem_handle_t)                                  ## [in][optional] Handle of memory object.
+    ]
+
+###############################################################################
+## @brief Descriptor type for updating a kernel command pointer argument.
+class ur_exp_command_buffer_update_pointer_arg_desc_t(Structure):
+    _fields_ = [
+        ("stype", ur_structure_type_t),                                 ## [in] type of this structure, must be
+                                                                        ## ::UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_UPDATE_POINTER_ARG_DESC
+        ("pNext", c_void_p),                                            ## [in][optional] pointer to extension-specific structure
+        ("argIndex", c_ulong),                                          ## [in] Argument index.
+        ("pProperties", *),                                             ## [in][optinal] Pointer to USM pointer properties.
+        ("pArgValue", *)                                                ## [in][optional] USM pointer to memory location holding the argument
+                                                                        ## value.
+    ]
+
+###############################################################################
+## @brief Descriptor type for updating kernel command execution info.
+class ur_exp_command_buffer_update_exec_info_desc_t(Structure):
+    _fields_ = [
+        ("stype", ur_structure_type_t),                                 ## [in] type of this structure, must be
+                                                                        ## ::UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_UPDATE_EXEC_INFO_DESC
+        ("pNext", c_void_p),                                            ## [in][optional] pointer to extension-specific structure
+        ("propName", ur_kernel_exec_info_t),                            ## [in] Name of execution attribute.
+        ("propSize", c_size_t),                                         ## [in] Size of execution attribute.
+        ("pProperties", *),                                             ## [in][optional] Pointer to execution info properties.
+        ("pPropValue", *)                                               ## [in] Pointer to memory location holding the property value.
+    ]
+
+###############################################################################
+## @brief Descriptor type for updating a kernel launch command.
+class ur_exp_command_buffer_update_kernel_launch_desc_t(Structure):
+    _fields_ = [
+        ("stype", ur_structure_type_t),                                 ## [in] type of this structure, must be
+                                                                        ## ::UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_UPDATE_KERNEL_LAUNCH_DESC
+        ("pNext", c_void_p),                                            ## [in][optional] pointer to extension-specific structure
+        ("numMemobjArgs", c_ulong),                                     ## [in] Length of pArgMemobjList.
+        ("numPointerArgs", c_ulong),                                    ## [in] Length of pArgPointerList.
+        ("numExecInfos", c_ulong),                                      ## [in] Length of pExecInfoList.
+        ("workDim", c_ulong),                                           ## [in] Number of work dimensions in the kernel ND-range, from 1-3.
+        ("pArgMemobjList", POINTER(ur_exp_command_buffer_update_memobj_arg_desc_t)),## [in] An array describing the new kernel mem obj arguments for the
+                                                                        ## command.
+        ("pArgPointerList", POINTER(ur_exp_command_buffer_update_pointer_arg_desc_t)),  ## [in] An array describing the new kernel pointer arguments for the
+                                                                        ## command.
+        ("pArgExecInfoList", POINTER(ur_exp_command_buffer_update_exec_info_desc_t)),   ## [in] An array describing the execution info objects for the command.
+        ("pGlobalWorkOffset", POINTER(c_size_t)),                       ## [in] Array of workDim unsigned values that describe the offset used to
+                                                                        ## calculate the global ID.
+        ("pGlobalWorkSize", POINTER(c_size_t)),                         ## [in] Array of workDim unsigned values that describe the number of
+                                                                        ## global work-items.
+        ("pLocalWorkSize", POINTER(c_size_t))                           ## [in] Array of workDim unsigned values that describe the number of
+                                                                        ## work-items that make up a work-group. If nullptr, the runtime
+                                                                        ## implementation will choose the work-group size.
     ]
 
 ###############################################################################
@@ -2314,6 +2388,11 @@ class ur_exp_command_buffer_sync_point_t(c_ulong):
 class ur_exp_command_buffer_handle_t(c_void_p):
     pass
 
+###############################################################################
+## @brief Handle of a Command-Buffer command
+class ur_exp_command_buffer_command_handle_t(c_void_p):
+    pass
+
 ###############################################################################
 ## @brief The extension string which defines support for cooperative-kernels
 ##        which is returned when querying device extensions.
@@ -3610,9 +3689,9 @@ class ur_usm_exp_dditable_t(Structure):
 ###############################################################################
 ## @brief Function-pointer for urCommandBufferAppendKernelLaunchExp
 if __use_win_types:
-    _urCommandBufferAppendKernelLaunchExp_t = WINFUNCTYPE( ur_result_t, ur_exp_command_buffer_handle_t, ur_kernel_handle_t, c_ulong, POINTER(c_size_t), POINTER(c_size_t), POINTER(c_size_t), c_ulong, POINTER(ur_exp_command_buffer_sync_point_t), POINTER(ur_exp_command_buffer_sync_point_t) )
+    _urCommandBufferAppendKernelLaunchExp_t = WINFUNCTYPE( ur_result_t, ur_exp_command_buffer_handle_t, ur_kernel_handle_t, c_ulong, POINTER(c_size_t), POINTER(c_size_t), POINTER(c_size_t), c_ulong, POINTER(ur_exp_command_buffer_sync_point_t), POINTER(ur_exp_command_buffer_sync_point_t), POINTER(ur_exp_command_buffer_command_handle_t) )
 else:
-    _urCommandBufferAppendKernelLaunchExp_t = CFUNCTYPE( ur_result_t, ur_exp_command_buffer_handle_t, ur_kernel_handle_t, c_ulong, POINTER(c_size_t), POINTER(c_size_t), POINTER(c_size_t), c_ulong, POINTER(ur_exp_command_buffer_sync_point_t), POINTER(ur_exp_command_buffer_sync_point_t) )
+    _urCommandBufferAppendKernelLaunchExp_t = CFUNCTYPE( ur_result_t, ur_exp_command_buffer_handle_t, ur_kernel_handle_t, c_ulong, POINTER(c_size_t), POINTER(c_size_t), POINTER(c_size_t), c_ulong, POINTER(ur_exp_command_buffer_sync_point_t), POINTER(ur_exp_command_buffer_sync_point_t), POINTER(ur_exp_command_buffer_command_handle_t) )
 
 ###############################################################################
 ## @brief Function-pointer for urCommandBufferAppendUSMMemcpyExp
@@ -3698,6 +3777,13 @@ class ur_usm_exp_dditable_t(Structure):
 else:
     _urCommandBufferEnqueueExp_t = CFUNCTYPE( ur_result_t, ur_exp_command_buffer_handle_t, ur_queue_handle_t, c_ulong, POINTER(ur_event_handle_t), POINTER(ur_event_handle_t) )
 
+###############################################################################
+## @brief Function-pointer for urCommandBufferUpdateKernelLaunchExp
+if __use_win_types:
+    _urCommandBufferUpdateKernelLaunchExp_t = WINFUNCTYPE( ur_result_t, ur_exp_command_buffer_command_handle_t, POINTER(ur_exp_command_buffer_update_kernel_launch_desc_t) )
+else:
+    _urCommandBufferUpdateKernelLaunchExp_t = CFUNCTYPE( ur_result_t, ur_exp_command_buffer_command_handle_t, POINTER(ur_exp_command_buffer_update_kernel_launch_desc_t) )
+
 
 ###############################################################################
 ## @brief Table of CommandBufferExp functions pointers
@@ -3719,7 +3805,8 @@ class ur_command_buffer_exp_dditable_t(Structure):
         ("pfnAppendMemBufferFillExp", c_void_p),                        ## _urCommandBufferAppendMemBufferFillExp_t
         ("pfnAppendUSMPrefetchExp", c_void_p),                          ## _urCommandBufferAppendUSMPrefetchExp_t
         ("pfnAppendUSMAdviseExp", c_void_p),                            ## _urCommandBufferAppendUSMAdviseExp_t
-        ("pfnEnqueueExp", c_void_p)                                     ## _urCommandBufferEnqueueExp_t
+        ("pfnEnqueueExp", c_void_p),                                    ## _urCommandBufferEnqueueExp_t
+        ("pfnUpdateKernelLaunchExp", c_void_p)                          ## _urCommandBufferUpdateKernelLaunchExp_t
     ]
 
 ###############################################################################
@@ -4255,6 +4342,7 @@ def __init__(self, version : ur_api_version_t):
         self.urCommandBufferAppendUSMPrefetchExp = _urCommandBufferAppendUSMPrefetchExp_t(self.__dditable.CommandBufferExp.pfnAppendUSMPrefetchExp)
         self.urCommandBufferAppendUSMAdviseExp = _urCommandBufferAppendUSMAdviseExp_t(self.__dditable.CommandBufferExp.pfnAppendUSMAdviseExp)
         self.urCommandBufferEnqueueExp = _urCommandBufferEnqueueExp_t(self.__dditable.CommandBufferExp.pfnEnqueueExp)
+        self.urCommandBufferUpdateKernelLaunchExp = _urCommandBufferUpdateKernelLaunchExp_t(self.__dditable.CommandBufferExp.pfnUpdateKernelLaunchExp)
 
         # call driver to get function pointers
         UsmP2PExp = ur_usm_p2p_exp_dditable_t()