Skip to content

Commit 504d3b6

Browse files
BensuoBensuo
committed
[EXP][CMDBUF] Make command handle behaviour consistent
- Attempting to obtain a command handle when the command buffer is not updatable is now an error across all adapters - command-buffer spec and adapter code update to reflect this - invalid_update CTS test updated to reflect new behaviour - Add ability to query command-buffer descriptor properties
1 parent cfada6f commit 504d3b6

File tree

15 files changed

+124
-29
lines changed

15 files changed

+124
-29
lines changed

‎include/ur_api.h

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8233,6 +8233,10 @@ typedef enum ur_exp_command_buffer_info_t {
82338233
///< The reference count returned should be considered immediately stale.
82348234
///< It is unsuitable for general use in applications. This feature is
82358235
///< provided for identifying memory leaks.
8236+
UR_EXP_COMMAND_BUFFER_INFO_DESCRIPTOR = 1, ///< [::ur_exp_command_buffer_desc_t] Returns a ::ur_exp_command_buffer_desc_t
8237+
///< with the properties of the command-buffer. Returned values may differ
8238+
///< from those passed on construction if the property was ignored by the
8239+
///< adapter.
82368240
/// @cond
82378241
UR_EXP_COMMAND_BUFFER_INFO_FORCE_UINT32 = 0x7fffffff
82388242
/// @endcond
@@ -8489,6 +8493,7 @@ urCommandBufferFinalizeExp(
84898493
/// + If the device associated with `hCommandBuffer` does not support UR_DEVICE_INFO_COMMAND_BUFFER_EVENT_SUPPORT_EXP and either `phEvent` or `phEventWaitList` are not NULL.
84908494
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
84918495
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
8496+
/// - ::UR_RESULT_ERROR_INVALID_OPERATION - "phCommand is not NULL and hCommandBuffer is not updatable."
84928497
UR_APIEXPORT ur_result_t UR_APICALL
84938498
urCommandBufferAppendKernelLaunchExp(
84948499
ur_exp_command_buffer_handle_t hCommandBuffer, ///< [in] Handle of the command-buffer object.
@@ -8517,7 +8522,8 @@ urCommandBufferAppendKernelLaunchExp(
85178522
ur_event_handle_t *phEvent, ///< [out][optional] return an event object that will be signaled by the
85188523
///< completion of this command in the next execution of the
85198524
///< command-buffer.
8520-
ur_exp_command_buffer_command_handle_t *phCommand ///< [out][optional] Handle to this command.
8525+
ur_exp_command_buffer_command_handle_t *phCommand ///< [out][optional] Handle to this command. Only available if the
8526+
///< command-buffer is updatable.
85218527
);
85228528

85238529
///////////////////////////////////////////////////////////////////////////////
@@ -9289,7 +9295,7 @@ urCommandBufferUpdateWaitEventsExp(
92899295
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
92909296
/// + `NULL == hCommandBuffer`
92919297
/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
9292-
/// + `::UR_EXP_COMMAND_BUFFER_INFO_REFERENCE_COUNT < propName`
9298+
/// + `::UR_EXP_COMMAND_BUFFER_INFO_DESCRIPTOR < propName`
92939299
/// - ::UR_RESULT_ERROR_UNSUPPORTED_ENUMERATION
92949300
/// + If `propName` is not supported by the adapter.
92959301
/// - ::UR_RESULT_ERROR_INVALID_SIZE

‎include/ur_print.hpp

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9847,6 +9847,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_exp_command_buffer_inf
98479847
case UR_EXP_COMMAND_BUFFER_INFO_REFERENCE_COUNT:
98489848
os << "UR_EXP_COMMAND_BUFFER_INFO_REFERENCE_COUNT";
98499849
break;
9850+
case UR_EXP_COMMAND_BUFFER_INFO_DESCRIPTOR:
9851+
os << "UR_EXP_COMMAND_BUFFER_INFO_DESCRIPTOR";
9852+
break;
98509853
default:
98519854
os << "unknown enumerator";
98529855
break;
@@ -9875,6 +9878,18 @@ inline ur_result_t printTagged(std::ostream &os, const void *ptr, ur_exp_command
98759878

98769879
os << ")";
98779880
} break;
9881+
case UR_EXP_COMMAND_BUFFER_INFO_DESCRIPTOR: {
9882+
const ur_exp_command_buffer_desc_t *tptr = (const ur_exp_command_buffer_desc_t *)ptr;
9883+
if (sizeof(ur_exp_command_buffer_desc_t) > size) {
9884+
os << "invalid size (is: " << size << ", expected: >=" << sizeof(ur_exp_command_buffer_desc_t) << ")";
9885+
return UR_RESULT_ERROR_INVALID_SIZE;
9886+
}
9887+
os << (const void *)(tptr) << " (";
9888+
9889+
os << *tptr;
9890+
9891+
os << ")";
9892+
} break;
98789893
default:
98799894
os << "unknown enumerator";
98809895
return UR_RESULT_ERROR_INVALID_ENUMERATION;

‎scripts/core/EXP-COMMAND-BUFFER.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -447,6 +447,7 @@ Enums
447447
* ${X}_FUNCTION_COMMAND_BUFFER_UPDATE_KERNEL_LAUNCH_EXP
448448
* ${x}_exp_command_buffer_info_t
449449
* ${X}_EXP_COMMAND_BUFFER_INFO_REFERENCE_COUNT
450+
* ${X}_EXP_COMMAND_BUFFER_INFO_DESCRIPTOR
450451
* ${x}_exp_command_buffer_command_info_t
451452
* ${X}_EXP_COMMAND_BUFFER_COMMAND_INFO_REFERENCE_COUNT
452453

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

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,12 @@ etors:
111111
[uint32_t] Reference count of the command-buffer object.
112112
The reference count returned should be considered immediately stale.
113113
It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
114+
- name: DESCRIPTOR
115+
desc: |
116+
[$x_exp_command_buffer_desc_t] Returns a $x_exp_command_buffer_desc_t
117+
with the properties of the command-buffer. Returned values may differ
118+
from those passed on construction if the property was ignored by the
119+
adapter.
114120
--- #--------------------------------------------------------------------------
115121
type: enum
116122
desc: "Command-buffer command query information type"
@@ -380,7 +386,8 @@ params:
380386
desc: "[out][optional] return an event object that will be signaled by the completion of this command in the next execution of the command-buffer."
381387
- type: "$x_exp_command_buffer_command_handle_t*"
382388
name: phCommand
383-
desc: "[out][optional] Handle to this command."
389+
desc: "[out][optional] Handle to this command. Only available if the
390+
command-buffer is updatable."
384391
returns:
385392
- $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
386393
- $X_RESULT_ERROR_INVALID_KERNEL
@@ -403,6 +410,8 @@ returns:
403410
- "If the device associated with `hCommandBuffer` does not support UR_DEVICE_INFO_COMMAND_BUFFER_EVENT_SUPPORT_EXP and either `phEvent` or `phEventWaitList` are not NULL."
404411
- $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
405412
- $X_RESULT_ERROR_OUT_OF_RESOURCES
413+
- $X_RESULT_ERROR_INVALID_OPERATION
414+
- "phCommand is not NULL and hCommandBuffer is not updatable."
406415
--- #--------------------------------------------------------------------------
407416
type: function
408417
desc: "Append a USM memcpy command to a command-buffer object."

‎source/adapters/cuda/command_buffer.cpp

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -432,6 +432,9 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendKernelLaunchExp(
432432
ur_exp_command_buffer_sync_point_t *pSyncPoint, ur_event_handle_t *phEvent,
433433
ur_exp_command_buffer_command_handle_t *phCommand) {
434434
// Preconditions
435+
// Command handles can only be obtained from updatable command-buffers
436+
UR_ASSERT(!(phCommand && !hCommandBuffer->IsUpdatable),
437+
UR_RESULT_ERROR_INVALID_OPERATION);
435438
UR_ASSERT(hCommandBuffer->Context == hKernel->getContext(),
436439
UR_RESULT_ERROR_INVALID_KERNEL);
437440
UR_ASSERT(workDim > 0, UR_RESULT_ERROR_INVALID_WORK_DIMENSION);
@@ -1479,6 +1482,16 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferGetInfoExp(
14791482
switch (propName) {
14801483
case UR_EXP_COMMAND_BUFFER_INFO_REFERENCE_COUNT:
14811484
return ReturnValue(hCommandBuffer->getExternalReferenceCount());
1485+
case UR_EXP_COMMAND_BUFFER_INFO_DESCRIPTOR: {
1486+
ur_exp_command_buffer_desc_t Descriptor{};
1487+
Descriptor.stype = UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC;
1488+
Descriptor.pNext = nullptr;
1489+
Descriptor.isUpdatable = hCommandBuffer->IsUpdatable;
1490+
Descriptor.isInOrder = false;
1491+
Descriptor.enableProfiling = false;
1492+
1493+
return ReturnValue(Descriptor);
1494+
}
14821495
default:
14831496
assert(!"Command-buffer info request not implemented");
14841497
}

‎source/adapters/hip/command_buffer.cpp

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -330,6 +330,9 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendKernelLaunchExp(
330330
std::ignore = phEventWaitList;
331331
std::ignore = phEvent;
332332
// Preconditions
333+
// Command handles can only be obtained from updatable command-buffers
334+
UR_ASSERT(!(phCommand && !hCommandBuffer->IsUpdatable),
335+
UR_RESULT_ERROR_INVALID_OPERATION);
333336
UR_ASSERT(hCommandBuffer->Context == hKernel->getContext(),
334337
UR_RESULT_ERROR_INVALID_KERNEL);
335338
UR_ASSERT(workDim > 0, UR_RESULT_ERROR_INVALID_WORK_DIMENSION);
@@ -1128,6 +1131,15 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferGetInfoExp(
11281131
switch (propName) {
11291132
case UR_EXP_COMMAND_BUFFER_INFO_REFERENCE_COUNT:
11301133
return ReturnValue(hCommandBuffer->getExternalReferenceCount());
1134+
case UR_EXP_COMMAND_BUFFER_INFO_DESCRIPTOR: {
1135+
ur_exp_command_buffer_desc_t Descriptor{};
1136+
Descriptor.stype = UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC;
1137+
Descriptor.pNext = nullptr;
1138+
Descriptor.isUpdatable = hCommandBuffer->IsUpdatable;
1139+
Descriptor.isInOrder = false, Descriptor.enableProfiling = false;
1140+
1141+
return ReturnValue(Descriptor);
1142+
}
11311143
default:
11321144
assert(!"Command-buffer info request not implemented");
11331145
}

‎source/adapters/level_zero/command_buffer.cpp

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -754,6 +754,9 @@ ur_result_t urCommandBufferAppendKernelLaunchExp(
754754
std::ignore = Event;
755755

756756
UR_ASSERT(Kernel->Program, UR_RESULT_ERROR_INVALID_NULL_POINTER);
757+
// Command handles can only be obtained from updatable command-buffers
758+
UR_ASSERT(!(Command && !CommandBuffer->IsUpdatable),
759+
UR_RESULT_ERROR_INVALID_OPERATION);
757760

758761
// Lock automatically releases when this goes out of scope.
759762
std::scoped_lock<ur_shared_mutex, ur_shared_mutex, ur_shared_mutex> Lock(
@@ -784,7 +787,7 @@ ur_result_t urCommandBufferAppendKernelLaunchExp(
784787
// reference count on the kernel, using the kernel saved in CommandData.
785788
UR_CALL(ur::level_zero::urKernelRetain(Kernel));
786789

787-
if (Command && CommandBuffer->IsUpdatable) {
790+
if (Command) {
788791
UR_CALL(createCommandHandle(CommandBuffer, Kernel, WorkDim, LocalWorkSize,
789792
*Command));
790793
}
@@ -1687,14 +1690,14 @@ ur_result_t updateKernelCommand(
16871690
ur_result_t urCommandBufferUpdateKernelLaunchExp(
16881691
ur_exp_command_buffer_command_handle_t Command,
16891692
const ur_exp_command_buffer_update_kernel_launch_desc_t *CommandDesc) {
1693+
UR_ASSERT(Command->CommandBuffer->IsUpdatable,
1694+
UR_RESULT_ERROR_INVALID_OPERATION);
16901695
UR_ASSERT(Command->Kernel, UR_RESULT_ERROR_INVALID_NULL_HANDLE);
16911696

16921697
// Lock command, kernel and command buffer for update.
16931698
std::scoped_lock<ur_shared_mutex, ur_shared_mutex, ur_shared_mutex> Guard(
16941699
Command->Mutex, Command->CommandBuffer->Mutex, Command->Kernel->Mutex);
16951700

1696-
UR_ASSERT(Command->CommandBuffer->IsUpdatable,
1697-
UR_RESULT_ERROR_INVALID_OPERATION);
16981701
UR_ASSERT(Command->CommandBuffer->IsFinalized,
16991702
UR_RESULT_ERROR_INVALID_OPERATION);
17001703

@@ -1739,6 +1742,16 @@ urCommandBufferGetInfoExp(ur_exp_command_buffer_handle_t hCommandBuffer,
17391742
switch (propName) {
17401743
case UR_EXP_COMMAND_BUFFER_INFO_REFERENCE_COUNT:
17411744
return ReturnValue(uint32_t{hCommandBuffer->RefCount.load()});
1745+
case UR_EXP_COMMAND_BUFFER_INFO_DESCRIPTOR: {
1746+
ur_exp_command_buffer_desc_t Descriptor{};
1747+
Descriptor.stype = UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC;
1748+
Descriptor.pNext = nullptr;
1749+
Descriptor.isUpdatable = hCommandBuffer->IsUpdatable;
1750+
Descriptor.isInOrder = hCommandBuffer->IsInOrderCmdList;
1751+
Descriptor.enableProfiling = hCommandBuffer->IsProfilingEnabled;
1752+
1753+
return ReturnValue(Descriptor);
1754+
}
17421755
default:
17431756
assert(!"Command-buffer info request not implemented");
17441757
}

‎source/adapters/mock/ur_mockddi.cpp

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8399,8 +8399,9 @@ __urdlllocal ur_result_t UR_APICALL urCommandBufferAppendKernelLaunchExp(
83998399
phEvent, ///< [out][optional] return an event object that will be signaled by the
84008400
///< completion of this command in the next execution of the
84018401
///< command-buffer.
8402-
ur_exp_command_buffer_command_handle_t
8403-
*phCommand ///< [out][optional] Handle to this command.
8402+
ur_exp_command_buffer_command_handle_t *
8403+
phCommand ///< [out][optional] Handle to this command. Only available if the
8404+
///< command-buffer is updatable.
84048405
) try {
84058406
ur_result_t result = UR_RESULT_SUCCESS;
84068407

‎source/adapters/opencl/command_buffer.cpp

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,10 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferAppendKernelLaunchExp(
152152
(void)phEventWaitList;
153153
(void)phEvent;
154154

155+
// Command handles can only be obtained from updatable command-buffers
156+
UR_ASSERT(!(phCommandHandle && !hCommandBuffer->IsUpdatable),
157+
UR_RESULT_ERROR_INVALID_OPERATION);
158+
155159
cl_context CLContext = cl_adapter::cast<cl_context>(hCommandBuffer->hContext);
156160
cl_ext::clCommandNDRangeKernelKHR_fn clCommandNDRangeKernelKHR = nullptr;
157161
UR_RETURN_ON_FAILURE(
@@ -646,6 +650,16 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferGetInfoExp(
646650
switch (propName) {
647651
case UR_EXP_COMMAND_BUFFER_INFO_REFERENCE_COUNT:
648652
return ReturnValue(hCommandBuffer->getExternalReferenceCount());
653+
case UR_EXP_COMMAND_BUFFER_INFO_DESCRIPTOR: {
654+
ur_exp_command_buffer_desc_t Descriptor{};
655+
Descriptor.stype = UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC;
656+
Descriptor.pNext = nullptr;
657+
Descriptor.isUpdatable = hCommandBuffer->IsUpdatable;
658+
Descriptor.isInOrder = false;
659+
Descriptor.enableProfiling = false;
660+
661+
return ReturnValue(Descriptor);
662+
}
649663
default:
650664
assert(!"Command-buffer info request not implemented");
651665
}

‎source/loader/layers/tracing/ur_trcddi.cpp

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7185,8 +7185,9 @@ __urdlllocal ur_result_t UR_APICALL urCommandBufferAppendKernelLaunchExp(
71857185
phEvent, ///< [out][optional] return an event object that will be signaled by the
71867186
///< completion of this command in the next execution of the
71877187
///< command-buffer.
7188-
ur_exp_command_buffer_command_handle_t
7189-
*phCommand ///< [out][optional] Handle to this command.
7188+
ur_exp_command_buffer_command_handle_t *
7189+
phCommand ///< [out][optional] Handle to this command. Only available if the
7190+
///< command-buffer is updatable.
71907191
) {
71917192
auto pfnAppendKernelLaunchExp =
71927193
getContext()->urDdiTable.CommandBufferExp.pfnAppendKernelLaunchExp;

0 commit comments

Comments
 (0)