Cleanups to spec

include/ur_api.h

@@ -1537,9 +1537,9 @@ typedef enum ur_device_info_t {
  ///< version than older devices.
  UR_DEVICE_INFO_VIRTUAL_MEMORY_SUPPORT = 114, ///< [::ur_bool_t] return true if the device supports virtual memory.
  UR_DEVICE_INFO_ESIMD_SUPPORT = 115, ///< [::ur_bool_t] return true if the device supports ESIMD.
- UR_DEVICE_INFO_COMMAND_BUFFER_SUPPORT_EXP = 0x1000, ///< [::ur_bool_t] returns true if the device supports the use of
+ UR_DEVICE_INFO_COMMAND_BUFFER_SUPPORT_EXP = 0x1000, ///< [::ur_bool_t] Returns true if the device supports the use of
  ///< command-buffers.
- UR_DEVICE_INFO_COMMAND_BUFFER_UPDATE_SUPPORT_EXP = 0x1001, ///< [::ur_bool_t] returns true if the device supports updating the
+ UR_DEVICE_INFO_COMMAND_BUFFER_UPDATE_SUPPORT_EXP = 0x1001, ///< [::ur_bool_t] Returns true if the device supports updating the kernel
  ///< commands in a command-buffer.
  UR_DEVICE_INFO_BINDLESS_IMAGES_SUPPORT_EXP = 0x2000, ///< [::ur_bool_t] returns true if the device supports the creation of
  ///< bindless images
@@ -7807,7 +7807,7 @@ typedef struct ur_exp_command_buffer_update_value_arg_desc_t {
  const void *pNext; ///< [in][optional] pointer to extension-specific structure
  uint32_t argIndex; ///< [in] Argument index.
  uint32_t argSize; ///< [in] Argument size.
- const ur_kernel_arg_value_properties_t *pProperties; ///< [in][optinal] Pointer to memory object properties.
+ const ur_kernel_arg_value_properties_t *pProperties; ///< [in][optinal] Pointer to value properties.
  const void *pArgValue; ///< [in][optional] Argument value representing kernel arg type.
 
 } ur_exp_command_buffer_update_value_arg_desc_t;
@@ -8461,7 +8461,7 @@ urCommandBufferEnqueueExp(
 UR_APIEXPORT ur_result_t UR_APICALL
 urCommandBufferUpdateKernelLaunchExp(
  ur_exp_command_buffer_command_handle_t hCommand, ///< [in] Handle of the command-buffer kernel command to update.
- const ur_exp_command_buffer_update_kernel_launch_desc_t *pUpdateKernelLaunch ///< [in] Handle of the command-buffer kernel command to update.
+ const ur_exp_command_buffer_update_kernel_launch_desc_t *pUpdateKernelLaunch ///< [in] Struct defining how the kernel command is to be updated.
 );
 
 #if !defined(__GNUC__)

scripts/core/EXP-COMMAND-BUFFER.rst

@@ -162,32 +162,32 @@ Updating Command-Buffers Commands
 
 An adapter implementing the command-buffer experimental feature can optionally
 support updating the configuration of kernel commands recorded to a
-command-buffer. Support of this is reported by returning true in the
+command-buffer. Support for this is reported by returning true in the
 ${X}_DEVICE_INFO_COMMAND_BUFFER_UPDATE_SUPPORT_EXP query.
 
 Updating kernel commands is done by passing the new kernel configuration
 to ${x}CommandBufferUpdateKernelLaunchExp along with the command handle of
 the kernel command to update. Configurations that can be changed are the
-kernels ND-Range and parameters.
+parameters to the kernel and the execution ND-Range.
 
 .. parsed-literal::
 
  // Create a command-buffer with update enabled.
  ${x}_exp_command_buffer_desc_t desc {
  ${X}_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC,
  nullptr,
- true
+ true // isUpdatable
  };
  ${x}_exp_command_buffer_handle_t hCommandBuffer;
- ${x}CommandBufferCreateExp(hContext, hDevice, &desc, &handle);
+ ${x}CommandBufferCreateExp(hContext, hDevice, &desc, &hCommandBuffer);
 
  // Append a kernel command which has two buffer parameters, an input
  // and an output.
- ${x}_exp_command_buffer_command_handle_t handle;
+ ${x}_exp_command_buffer_command_handle_t hCommand;
  ${x}CommandBufferAppendKernelLaunchExp(hCommandBuffer, hKernel, workDim,
  pGlobalWorkOffset, pGlobalWorkSize,
  pLocalWorkSize, 0, nullptr,
- nullptr, &handle);
+ nullptr, &hCommand);
 
  // Close the command-buffer before updating
  ${x}CommandBufferFinalizeExp(hCommandBuffer);
@@ -230,7 +230,7 @@ kernels ND-Range and parameters.
  };
 
  // Perform the update
- ${x}CommandBufferUpdateKernelLaunchExp(handle, &update);
+ ${x}CommandBufferUpdateKernelLaunchExp(hCommand, &update);
 
 
 API
@@ -255,6 +255,7 @@ Enums
  * ${X}_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_UPDATE_KERNEL_LAUNCH_DESC
  * ${X}_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_UPDATE_MEMOBJ_ARG_DESC
  * ${X}_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_UPDATE_POINTER_ARG_DESC
+ * ${X}_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_UPDATE_VALUE_ARG_DESC
  * ${X}_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_UPDATE_EXEC_INFO_DESC
 * ${x}_command_t
  * ${X}_COMMAND_COMMAND_BUFFER_ENQUEUE_EXP
@@ -284,6 +285,7 @@ Types
 * ${x}_exp_command_buffer_update_kernel_launch_desc_t
 * ${x}_exp_command_buffer_update_memobj_arg_desc_t
 * ${x}_exp_command_buffer_update_pointer_arg_desc_t
+* ${x}_exp_command_buffer_update_value_arg_desc_t
 * ${x}_exp_command_buffer_update_exec_info_desc_t
 * ${x}_exp_command_buffer_sync_point_t
 * ${x}_exp_command_buffer_handle_t

scripts/core/exp-command-buffer.yml

@@ -20,10 +20,10 @@ name: $x_device_info_t
 etors:
  - name: COMMAND_BUFFER_SUPPORT_EXP
  value: "0x1000"
- desc: "[$x_bool_t] returns true if the device supports the use of command-buffers."
+ desc: "[$x_bool_t] Returns true if the device supports the use of command-buffers."
  - name: COMMAND_BUFFER_UPDATE_SUPPORT_EXP
  value: "0x1001"
- desc: "[$x_bool_t] returns true if the device supports updating the commands in a command-buffer."
+ desc: "[$x_bool_t] Returns true if the device supports updating the kernel commands in a command-buffer."
 
 --- #--------------------------------------------------------------------------
 type: enum
@@ -135,7 +135,7 @@ members:
  desc: "[in] Argument size."
  - type: "const ur_kernel_arg_value_properties_t *"
  name: pProperties
- desc: "[in][optinal] Pointer to memory object properties."
+ desc: "[in][optinal] Pointer to value properties."
  - type: "const void *"
  name: pArgValue
  desc: "[in][optional] Argument value representing kernel arg type."
@@ -872,7 +872,7 @@ params:
  desc: "[in] Handle of the command-buffer kernel command to update."
  - type: "const $x_exp_command_buffer_update_kernel_launch_desc_t*"
  name: pUpdateKernelLaunch
- desc: "[in] Handle of the command-buffer kernel command to update."
+ desc: "[in] Struct defining how the kernel command is to be updated."
 
 returns:
  - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:

source/adapters/cuda/command_buffer.hpp

@@ -175,9 +175,11 @@ static inline const char *getUrResultString(ur_result_t Result) {
  fprintf(stderr, "UR <--- %s(%s)\n", #Call, getUrResultString(Result)); \
  }
 
-// Handle type specific to kernel command. Will need to
-// be refactored when handles can be returned from other
-// command types.
+// Handle to a kernel command.
+//
+// Struct that stores all the information related to a kernel command in a
+// command-buffer, such that the command can be recreated. When handles can
+// be returned from other command types this struct will need refactored.
 struct ur_exp_command_buffer_command_handle_t_ {
  ur_exp_command_buffer_command_handle_t_(
  ur_exp_command_buffer_handle_t CommandBuffer, ur_kernel_handle_t Kernel,
@@ -218,11 +220,11 @@ struct ur_exp_command_buffer_command_handle_t_ {
  }
 
  void SetLocalSize(const size_t *pLocalWorkSize) {
- const size_t copy_size = sizeof(size_t) * WorkDim;
- std::memcpy(LocalWorkSize, pLocalWorkSize, copy_size);
+ const size_t CopySize = sizeof(size_t) * WorkDim;
+ std::memcpy(LocalWorkSize, pLocalWorkSize, CopySize);
  if (WorkDim < 3) {
- const size_t zero_size = sizeof(size_t) * (3 - WorkDim);
- std::memset(LocalWorkSize + WorkDim, 0, zero_size);
+ const size_t ZeroSize = sizeof(size_t) * (3 - WorkDim);
+ std::memset(LocalWorkSize + WorkDim, 0, ZeroSize);
  }
  }
 
@@ -267,7 +269,11 @@ struct ur_exp_command_buffer_handle_t_ {
  // Creates a UR command handle
  // @param[in] Kernel UR kernel associated with this command.
  // @param[in] Node CUDA Graph node associated with this command.
- // @param[in] Params Kernel configuration associated with this node.
+ // @param[in] Params CUDA Kernel configuration associated with this node.
+ // @param[in] WorkDim Dimensions of the kernel execution.
+ // @param[in] GlobalWorkOffset Work item offset of the kernel execution.
+ // @param[in] GlobalWorkSize Global work size of the kernel execution.
+ // @param[in] LocalWorkSize Local work size of the kernel execution.
  // @return Shared pointer to the created handle.
  std::shared_ptr<ur_exp_command_buffer_command_handle_t_>
  AddCommandHandle(ur_kernel_handle_t Kernel, std::shared_ptr<CUgraphNode> Node,

source/adapters/null/ur_nullddi.cpp

@@ -5029,7 +5029,7 @@ __urdlllocal ur_result_t UR_APICALL urCommandBufferUpdateKernelLaunchExp(
  ur_exp_command_buffer_command_handle_t
  hCommand, ///< [in] Handle of the command-buffer kernel command to update.
  const ur_exp_command_buffer_update_kernel_launch_desc_t *
- pUpdateKernelLaunch ///< [in] Handle of the command-buffer kernel command to update.
+ pUpdateKernelLaunch ///< [in] Struct defining how the kernel command is to be updated.
  ) try {
  ur_result_t result = UR_RESULT_SUCCESS;
 

source/loader/layers/tracing/ur_trcddi.cpp

@@ -5815,7 +5815,7 @@ __urdlllocal ur_result_t UR_APICALL urCommandBufferUpdateKernelLaunchExp(
  ur_exp_command_buffer_command_handle_t
  hCommand, ///< [in] Handle of the command-buffer kernel command to update.
  const ur_exp_command_buffer_update_kernel_launch_desc_t *
- pUpdateKernelLaunch ///< [in] Handle of the command-buffer kernel command to update.
+ pUpdateKernelLaunch ///< [in] Struct defining how the kernel command is to be updated.
 ) {
  auto pfnUpdateKernelLaunchExp =
  context.urDdiTable.CommandBufferExp.pfnUpdateKernelLaunchExp;

source/loader/layers/validation/ur_valddi.cpp

@@ -7623,7 +7623,7 @@ __urdlllocal ur_result_t UR_APICALL urCommandBufferUpdateKernelLaunchExp(
  ur_exp_command_buffer_command_handle_t
  hCommand, ///< [in] Handle of the command-buffer kernel command to update.
  const ur_exp_command_buffer_update_kernel_launch_desc_t *
- pUpdateKernelLaunch ///< [in] Handle of the command-buffer kernel command to update.
+ pUpdateKernelLaunch ///< [in] Struct defining how the kernel command is to be updated.
 ) {
  auto pfnUpdateKernelLaunchExp =
  context.urDdiTable.CommandBufferExp.pfnUpdateKernelLaunchExp;

source/loader/ur_ldrddi.cpp

@@ -6866,7 +6866,7 @@ __urdlllocal ur_result_t UR_APICALL urCommandBufferUpdateKernelLaunchExp(
  ur_exp_command_buffer_command_handle_t
  hCommand, ///< [in] Handle of the command-buffer kernel command to update.
  const ur_exp_command_buffer_update_kernel_launch_desc_t *
- pUpdateKernelLaunch ///< [in] Handle of the command-buffer kernel command to update.
+ pUpdateKernelLaunch ///< [in] Struct defining how the kernel command is to be updated.
 ) {
  ur_result_t result = UR_RESULT_SUCCESS;
 
@@ -6885,19 +6885,6 @@ __urdlllocal ur_result_t UR_APICALL urCommandBufferUpdateKernelLaunchExp(
  reinterpret_cast<ur_exp_command_buffer_command_object_t *>(hCommand)
  ->handle;
 
- uint32_t NumMemobjArgs = pUpdateKernelLaunch->numMemobjArgs;
- if (NumMemobjArgs) {
- for (uint32_t i = 0; i < NumMemobjArgs; i++) {
- auto &MemobjArgDesc = pUpdateKernelLaunch->pArgMemobjList[i];
- ur_mem_handle_t &ArgValue =
- const_cast<ur_mem_handle_t &>(MemobjArgDesc.hArgValue);
- ArgValue =
- (ArgValue)
- ? reinterpret_cast<ur_mem_object_t *>(ArgValue)->handle
- : nullptr;
- }
- }
-
  // forward to device-platform
  result = pfnUpdateKernelLaunchExp(hCommand, pUpdateKernelLaunch);
 

source/loader/ur_libapi.cpp

@@ -7864,7 +7864,7 @@ ur_result_t UR_APICALL urCommandBufferUpdateKernelLaunchExp(
  ur_exp_command_buffer_command_handle_t
  hCommand, ///< [in] Handle of the command-buffer kernel command to update.
  const ur_exp_command_buffer_update_kernel_launch_desc_t *
- pUpdateKernelLaunch ///< [in] Handle of the command-buffer kernel command to update.
+ pUpdateKernelLaunch ///< [in] Struct defining how the kernel command is to be updated.
  ) try {
  auto pfnUpdateKernelLaunchExp =
  ur_lib::context->urDdiTable.CommandBufferExp.pfnUpdateKernelLaunchExp;

source/ur_api.cpp

@@ -6649,7 +6649,7 @@ ur_result_t UR_APICALL urCommandBufferUpdateKernelLaunchExp(
  ur_exp_command_buffer_command_handle_t
  hCommand, ///< [in] Handle of the command-buffer kernel command to update.
  const ur_exp_command_buffer_update_kernel_launch_desc_t *
- pUpdateKernelLaunch ///< [in] Handle of the command-buffer kernel command to update.
+ pUpdateKernelLaunch ///< [in] Struct defining how the kernel command is to be updated.
 ) {
  ur_result_t result = UR_RESULT_SUCCESS;
  return result;

test/conformance/testing/include/uur/fixtures.h

@@ -1255,7 +1255,7 @@ struct urBaseKernelExecutionTest : urBaseKernelTest {
 };
 
 struct urKernelExecutionTest : urBaseKernelExecutionTest {
- void SetUp() override {
+ void SetUp() {
  UUR_RETURN_ON_FATAL_FAILURE(urBaseKernelExecutionTest::SetUp());
  Build();
  }