Skip to content

Commit b2ac58f

Browse files
kbenziekbenzie
authored
Merge pull request oneapi-src#2462 from Bensuo/cmd-buf_update_errors
Improve specification of command-buffer update errors
2 parents 3472b5b + ead3d07 commit b2ac58f

File tree

10 files changed

+449
-42
lines changed

10 files changed

+449
-42
lines changed

‎include/ur_api.h‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8508,8 +8508,8 @@ typedef struct ur_exp_command_buffer_command_handle_t_ *ur_exp_command_buffer_co
85088508
/// + `NULL == phCommandBuffer`
85098509
/// - ::UR_RESULT_ERROR_INVALID_CONTEXT
85108510
/// - ::UR_RESULT_ERROR_INVALID_DEVICE
8511-
/// - ::UR_RESULT_ERROR_INVALID_OPERATION
8512-
/// + If `pCommandBufferDesc->isUpdatable` is true and `hDevice` does not support UR_DEVICE_INFO_COMMAND_BUFFER_UPDATE_SUPPORT_EXP.
8511+
/// - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
8512+
/// + If `pCommandBufferDesc->isUpdatable` is true and `hDevice` returns 0 for the ::UR_DEVICE_INFO_COMMAND_BUFFER_UPDATE_CAPABILITIES_EXP query.
85138513
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
85148514
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
85158515
UR_APIEXPORT ur_result_t UR_APICALL
@@ -9315,11 +9315,17 @@ urCommandBufferReleaseCommandExp(
93159315
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
93169316
/// + `NULL == pUpdateKernelLaunch`
93179317
/// - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
9318-
/// + If update functionality is not supported by the device.
9318+
/// + If ::UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_KERNEL_ARGUMENTS is not supported by the device, but any of `pUpdateKernelLaunch->numNewMemObjArgs`, `pUpdateKernelLaunch->numNewPointerArgs`, or `pUpdateKernelLaunch->numNewValueArgs` are not zero.
9319+
/// + If ::UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_LOCAL_WORK_SIZE is not supported by the device but `pUpdateKernelLaunch->pNewLocalWorkSize` is not nullptr.
9320+
/// + If ::UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_LOCAL_WORK_SIZE is not supported by the device but `pUpdateKernelLaunch->pNewLocalWorkSize` is nullptr and `pUpdateKernelLaunch->pNewGlobalWorkSize` is not nullptr.
9321+
/// + If ::UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_GLOBAL_WORK_SIZE is not supported by the device but `pUpdateKernelLaunch->pNewGlobalWorkSize` is not nullptr
9322+
/// + If ::UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_GLOBAL_WORK_OFFSET is not supported by the device but `pUpdateKernelLaunch->pNewGlobalWorkOffset` is not nullptr.
9323+
/// + If ::UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_KERNEL_HANDLE is not supported by the device but `pUpdateKernelLaunch->hNewKernel` is not nullptr.
93199324
/// - ::UR_RESULT_ERROR_INVALID_OPERATION
93209325
/// + If ::ur_exp_command_buffer_desc_t::isUpdatable was not set to true on creation of the command buffer `hCommand` belongs to.
93219326
/// + If the command-buffer `hCommand` belongs to has not been finalized.
9322-
/// - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_COMMAND_HANDLE_EXP - "If `hCommand` is not a kernel execution command."
9327+
/// - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_COMMAND_HANDLE_EXP
9328+
/// + If `hCommand` is not a kernel execution command.
93239329
/// - ::UR_RESULT_ERROR_INVALID_MEM_OBJECT
93249330
/// - ::UR_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_INDEX
93259331
/// - ::UR_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_SIZE
@@ -9329,7 +9335,7 @@ urCommandBufferReleaseCommandExp(
93299335
/// - ::UR_RESULT_ERROR_INVALID_WORK_GROUP_SIZE
93309336
/// - ::UR_RESULT_ERROR_INVALID_VALUE
93319337
/// + If `pUpdateKernelLaunch->hNewKernel` was not passed to the `hKernel` or `phKernelAlternatives` parameters of ::urCommandBufferAppendKernelLaunchExp when this command was created.
9332-
/// + If `pUpdateKernelLaunch->newWorkDim` is different from the current workDim in `hCommand` and, pUpdateKernelLaunch->pNewGlobalWorkSize, or pUpdateKernelLaunch->pNewGlobalWorkOffset are nullptr.
9338+
/// + If `pUpdateKernelLaunch->newWorkDim` is different from the current workDim in `hCommand` and, `pUpdateKernelLaunch->pNewGlobalWorkSize`, or `pUpdateKernelLaunch->pNewGlobalWorkOffset` are nullptr.
93339339
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
93349340
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
93359341
UR_APIEXPORT ur_result_t UR_APICALL
@@ -9355,7 +9361,7 @@ urCommandBufferUpdateKernelLaunchExp(
93559361
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
93569362
/// + `NULL == phSignalEvent`
93579363
/// - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
9358-
/// + If UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_EVENTS is not supported by the device associated with `hCommand`.
9364+
/// + If ::UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_EVENTS is not supported by the device associated with `hCommand`.
93599365
/// - ::UR_RESULT_ERROR_INVALID_OPERATION
93609366
/// + If ::ur_exp_command_buffer_desc_t::isUpdatable was not set to true on creation of the command buffer `hCommand` belongs to.
93619367
/// + If the command-buffer `hCommand` belongs to has not been finalized.
@@ -9382,7 +9388,7 @@ urCommandBufferUpdateSignalEventExp(
93829388
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
93839389
/// + `NULL == hCommand`
93849390
/// - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
9385-
/// + If UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_EVENTS is not supported by the device associated with `hCommand`.
9391+
/// + If ::UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_EVENTS is not supported by the device associated with `hCommand`.
93869392
/// - ::UR_RESULT_ERROR_INVALID_OPERATION
93879393
/// + If ::ur_exp_command_buffer_desc_t::isUpdatable was not set to true on creation of the command buffer `hCommand` belongs to.
93889394
/// + If the command-buffer `hCommand` belongs to has not been finalized.

‎scripts/core/exp-command-buffer.yml‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -289,8 +289,9 @@ params:
289289
returns:
290290
- $X_RESULT_ERROR_INVALID_CONTEXT
291291
- $X_RESULT_ERROR_INVALID_DEVICE
292-
- $X_RESULT_ERROR_INVALID_OPERATION:
293-
- "If `pCommandBufferDesc->isUpdatable` is true and `hDevice` does not support UR_DEVICE_INFO_COMMAND_BUFFER_UPDATE_SUPPORT_EXP."
292+
- $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
293+
- "If `pCommandBufferDesc->isUpdatable` is true and `hDevice` returns 0
294+
for the $X_DEVICE_INFO_COMMAND_BUFFER_UPDATE_CAPABILITIES_EXP query."
294295
- $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
295296
- $X_RESULT_ERROR_OUT_OF_RESOURCES
296297
--- #--------------------------------------------------------------------------
@@ -1203,11 +1204,16 @@ params:
12031204
desc: "[in] Struct defining how the kernel command is to be updated."
12041205
returns:
12051206
- $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
1206-
- "If update functionality is not supported by the device."
1207+
- "If $X_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_KERNEL_ARGUMENTS is not supported by the device, but any of `pUpdateKernelLaunch->numNewMemObjArgs`, `pUpdateKernelLaunch->numNewPointerArgs`, or `pUpdateKernelLaunch->numNewValueArgs` are not zero."
1208+
- "If $X_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_LOCAL_WORK_SIZE is not supported by the device but `pUpdateKernelLaunch->pNewLocalWorkSize` is not nullptr."
1209+
- "If $X_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_LOCAL_WORK_SIZE is not supported by the device but `pUpdateKernelLaunch->pNewLocalWorkSize` is nullptr and `pUpdateKernelLaunch->pNewGlobalWorkSize` is not nullptr."
1210+
- "If $X_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_GLOBAL_WORK_SIZE is not supported by the device but `pUpdateKernelLaunch->pNewGlobalWorkSize` is not nullptr"
1211+
- "If $X_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_GLOBAL_WORK_OFFSET is not supported by the device but `pUpdateKernelLaunch->pNewGlobalWorkOffset` is not nullptr."
1212+
- "If $X_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_KERNEL_HANDLE is not supported by the device but `pUpdateKernelLaunch->hNewKernel` is not nullptr."
12071213
- $X_RESULT_ERROR_INVALID_OPERATION:
12081214
- "If $x_exp_command_buffer_desc_t::isUpdatable was not set to true on creation of the command buffer `hCommand` belongs to."
12091215
- "If the command-buffer `hCommand` belongs to has not been finalized."
1210-
- $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_COMMAND_HANDLE_EXP
1216+
- $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_COMMAND_HANDLE_EXP:
12111217
- "If `hCommand` is not a kernel execution command."
12121218
- $X_RESULT_ERROR_INVALID_MEM_OBJECT
12131219
- $X_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_INDEX
@@ -1218,7 +1224,7 @@ returns:
12181224
- $X_RESULT_ERROR_INVALID_WORK_GROUP_SIZE
12191225
- $X_RESULT_ERROR_INVALID_VALUE:
12201226
- "If `pUpdateKernelLaunch->hNewKernel` was not passed to the `hKernel` or `phKernelAlternatives` parameters of $xCommandBufferAppendKernelLaunchExp when this command was created."
1221-
- "If `pUpdateKernelLaunch->newWorkDim` is different from the current workDim in `hCommand` and, pUpdateKernelLaunch->pNewGlobalWorkSize, or pUpdateKernelLaunch->pNewGlobalWorkOffset are nullptr."
1227+
- "If `pUpdateKernelLaunch->newWorkDim` is different from the current workDim in `hCommand` and, `pUpdateKernelLaunch->pNewGlobalWorkSize`, or `pUpdateKernelLaunch->pNewGlobalWorkOffset` are nullptr."
12221228
- $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
12231229
- $X_RESULT_ERROR_OUT_OF_RESOURCES
12241230
--- #--------------------------------------------------------------------------
@@ -1236,7 +1242,7 @@ params:
12361242
desc: "[out] Event to be signaled."
12371243
returns:
12381244
- $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
1239-
- "If UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_EVENTS is not supported by the device associated with `hCommand`."
1245+
- "If $X_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_EVENTS is not supported by the device associated with `hCommand`."
12401246
- $X_RESULT_ERROR_INVALID_OPERATION:
12411247
- "If $x_exp_command_buffer_desc_t::isUpdatable was not set to true on creation of the command buffer `hCommand` belongs to."
12421248
- "If the command-buffer `hCommand` belongs to has not been finalized."
@@ -1262,7 +1268,7 @@ params:
12621268
desc: "[in][optional][range(0, numEventsInWaitList)] pointer to a list of events that must be complete before the command execution. If nullptr, the numEventsInWaitList must be 0, indicating no wait events."
12631269
returns:
12641270
- $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
1265-
- "If UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_EVENTS is not supported by the device associated with `hCommand`."
1271+
- "If $X_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_EVENTS is not supported by the device associated with `hCommand`."
12661272
- $X_RESULT_ERROR_INVALID_OPERATION:
12671273
- "If $x_exp_command_buffer_desc_t::isUpdatable was not set to true on creation of the command buffer `hCommand` belongs to."
12681274
- "If the command-buffer `hCommand` belongs to has not been finalized."

‎source/adapters/opencl/command_buffer.cpp‎

Lines changed: 61 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferCreateExp(
7878
bool DeviceSupportsUpdate = UpdateCapabilities > 0;
7979

8080
if (IsUpdatable && !DeviceSupportsUpdate) {
81-
return UR_RESULT_ERROR_INVALID_OPERATION;
81+
return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
8282
}
8383

8484
cl_command_buffer_properties_khr Properties[3] = {
@@ -92,7 +92,7 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferCreateExp(
9292

9393
try {
9494
auto URCommandBuffer = std::make_unique<ur_exp_command_buffer_handle_t_>(
95-
Queue, hContext, CLCommandBuffer, IsUpdatable);
95+
Queue, hContext, hDevice, CLCommandBuffer, IsUpdatable);
9696
*phCommandBuffer = URCommandBuffer.release();
9797
} catch (...) {
9898
return UR_RESULT_ERROR_OUT_OF_RESOURCES;
@@ -540,18 +540,72 @@ void updateKernelArgs(std::vector<cl_mutable_dispatch_arg_khr> &CLArgs,
540540
}
541541
}
542542

543+
ur_result_t validateCommandDesc(
544+
ur_exp_command_buffer_command_handle_t Command,
545+
const ur_exp_command_buffer_update_kernel_launch_desc_t *UpdateDesc) {
546+
// Kernel handle updates are not yet supported.
547+
if (UpdateDesc->hNewKernel && UpdateDesc->hNewKernel != Command->Kernel) {
548+
return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
549+
}
550+
551+
// Error if work-dim has changed but a new global size/offset hasn't been set
552+
if (UpdateDesc->newWorkDim != Command->WorkDim &&
553+
(!UpdateDesc->pNewGlobalWorkOffset || !UpdateDesc->pNewGlobalWorkSize)) {
554+
return UR_RESULT_ERROR_INVALID_OPERATION;
555+
}
556+
557+
// Verify that the device supports updating the aspects of the kernel that
558+
// the user is requesting.
559+
ur_device_handle_t URDevice = Command->hCommandBuffer->hDevice;
560+
cl_device_id CLDevice = cl_adapter::cast<cl_device_id>(URDevice);
561+
562+
ur_device_command_buffer_update_capability_flags_t UpdateCapabilities = 0;
563+
CL_RETURN_ON_FAILURE(
564+
getDeviceCommandBufferUpdateCapabilities(CLDevice, UpdateCapabilities));
565+
566+
size_t *NewGlobalWorkOffset = UpdateDesc->pNewGlobalWorkOffset;
567+
UR_ASSERT(
568+
!NewGlobalWorkOffset ||
569+
(UpdateCapabilities &
570+
UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_GLOBAL_WORK_OFFSET),
571+
UR_RESULT_ERROR_UNSUPPORTED_FEATURE);
572+
573+
size_t *NewLocalWorkSize = UpdateDesc->pNewLocalWorkSize;
574+
UR_ASSERT(
575+
!NewLocalWorkSize ||
576+
(UpdateCapabilities &
577+
UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_LOCAL_WORK_SIZE),
578+
UR_RESULT_ERROR_UNSUPPORTED_FEATURE);
579+
580+
size_t *NewGlobalWorkSize = UpdateDesc->pNewGlobalWorkSize;
581+
UR_ASSERT(
582+
!NewGlobalWorkSize ||
583+
(UpdateCapabilities &
584+
UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_GLOBAL_WORK_SIZE),
585+
UR_RESULT_ERROR_UNSUPPORTED_FEATURE);
586+
UR_ASSERT(
587+
!(NewGlobalWorkSize && !NewLocalWorkSize) ||
588+
(UpdateCapabilities &
589+
UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_LOCAL_WORK_SIZE),
590+
UR_RESULT_ERROR_UNSUPPORTED_FEATURE);
591+
592+
UR_ASSERT(
593+
(!UpdateDesc->numNewMemObjArgs && !UpdateDesc->numNewPointerArgs &&
594+
!UpdateDesc->numNewValueArgs) ||
595+
(UpdateCapabilities &
596+
UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_KERNEL_ARGUMENTS),
597+
UR_RESULT_ERROR_UNSUPPORTED_FEATURE);
598+
599+
return UR_RESULT_SUCCESS;
600+
}
543601
} // end anonymous namespace
544602

545603
UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferUpdateKernelLaunchExp(
546604
ur_exp_command_buffer_command_handle_t hCommand,
547605
const ur_exp_command_buffer_update_kernel_launch_desc_t
548606
*pUpdateKernelLaunch) {
549607

550-
// Kernel handle updates are not yet supported.
551-
if (pUpdateKernelLaunch->hNewKernel &&
552-
pUpdateKernelLaunch->hNewKernel != hCommand->Kernel) {
553-
return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
554-
}
608+
UR_RETURN_ON_FAILURE(validateCommandDesc(hCommand, pUpdateKernelLaunch));
555609

556610
ur_exp_command_buffer_handle_t hCommandBuffer = hCommand->hCommandBuffer;
557611
cl_context CLContext = cl_adapter::cast<cl_context>(hCommandBuffer->hContext);
@@ -565,12 +619,6 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferUpdateKernelLaunchExp(
565619
if (!hCommandBuffer->IsFinalized || !hCommandBuffer->IsUpdatable)
566620
return UR_RESULT_ERROR_INVALID_OPERATION;
567621

568-
if (pUpdateKernelLaunch->newWorkDim != hCommand->WorkDim &&
569-
(!pUpdateKernelLaunch->pNewGlobalWorkOffset ||
570-
!pUpdateKernelLaunch->pNewGlobalWorkSize)) {
571-
return UR_RESULT_ERROR_INVALID_OPERATION;
572-
}
573-
574622
// Find the CL USM pointer arguments to the kernel to update
575623
std::vector<cl_mutable_dispatch_arg_khr> CLUSMArgs;
576624
updateKernelPointerArgs(CLUSMArgs, pUpdateKernelLaunch);

‎source/adapters/opencl/command_buffer.hpp‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,8 @@ struct ur_exp_command_buffer_handle_t_ {
6464
ur_queue_handle_t hInternalQueue;
6565
/// Context the command-buffer is created for.
6666
ur_context_handle_t hContext;
67+
/// Device the command-buffer is created for.
68+
ur_device_handle_t hDevice;
6769
/// OpenCL command-buffer object.
6870
cl_command_buffer_khr CLCommandBuffer;
6971
/// Set to true if the kernel commands in the command-buffer can be updated,
@@ -83,9 +85,10 @@ struct ur_exp_command_buffer_handle_t_ {
8385

8486
ur_exp_command_buffer_handle_t_(ur_queue_handle_t hQueue,
8587
ur_context_handle_t hContext,
88+
ur_device_handle_t hDevice,
8689
cl_command_buffer_khr CLCommandBuffer,
8790
bool IsUpdatable)
88-
: hInternalQueue(hQueue), hContext(hContext),
91+
: hInternalQueue(hQueue), hContext(hContext), hDevice(hDevice),
8992
CLCommandBuffer(CLCommandBuffer), IsUpdatable(IsUpdatable),
9093
IsFinalized(false), RefCountInternal(0), RefCountExternal(0) {}
9194

0 commit comments

Comments
 (0)