Skip to content

Commit

Permalink
Refactor command update API to take a list
Browse files Browse the repository at this point in the history 
Update the `urCommandBufferUpdateKernelLaunchExp` API for updating
commands in a command-buffer to take a list of commands.

The current API operates on a single command, this means that the
SYCL-Graph `update(std::vector<nodes>)` API needs to serialize
the list into N calls to the UR API. Given that both OpenCL
`clUpdateMutableCommandsKHR` and Level-Zero
`zeCommandListUpdateMutableCommandsExp` can operate on a list of
commands, this serialization at the UR layer of the stack
introduces extra host API calls.

This PR improves the `urCommandBufferUpdateKernelLaunchExp` API
so that a list of commands is passed all the way from SYCL to the
native backend API.
  • Loading branch information
@EwanC
EwanC committed Feb 6, 2025
1 parent 87d4a32 commit de05080
Show file tree
Hide file tree
Showing 26 changed files with 950 additions and 662 deletions.
113 changes: 63 additions & 50 deletions include/ur_api.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9962,6 +9962,21 @@ typedef struct ur_exp_command_buffer_desc_t {

} ur_exp_command_buffer_desc_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief A value that identifies a command inside of a command-buffer, used
/// for
/// defining dependencies between commands in the same command-buffer.
typedef uint32_t ur_exp_command_buffer_sync_point_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of Command-Buffer object
typedef struct ur_exp_command_buffer_handle_t_ *ur_exp_command_buffer_handle_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of a Command-Buffer command
typedef struct ur_exp_command_buffer_command_handle_t_
*ur_exp_command_buffer_command_handle_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Descriptor type for updating a kernel command memobj argument.
typedef struct ur_exp_command_buffer_update_memobj_arg_desc_t {
Expand Down Expand Up @@ -10025,6 +10040,8 @@ typedef struct ur_exp_command_buffer_update_kernel_launch_desc_t {
ur_structure_type_t stype;
/// [in][optional] pointer to extension-specific structure
const void *pNext;
/// [in] Handle of the command-buffer kernel command to update.
ur_exp_command_buffer_command_handle_t hCommand;
/// [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
Expand Down Expand Up @@ -10074,21 +10091,6 @@ typedef struct ur_exp_command_buffer_update_kernel_launch_desc_t {

} ur_exp_command_buffer_update_kernel_launch_desc_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief A value that identifies a command inside of a command-buffer, used
/// for
/// defining dependencies between commands in the same command-buffer.
typedef uint32_t ur_exp_command_buffer_sync_point_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of Command-Buffer object
typedef struct ur_exp_command_buffer_handle_t_ *ur_exp_command_buffer_handle_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Handle of a Command-Buffer command
typedef struct ur_exp_command_buffer_command_handle_t_
*ur_exp_command_buffer_command_handle_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Create a Command-Buffer object
///
Expand Down Expand Up @@ -11035,74 +11037,84 @@ UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferEnqueueExp(
///
/// @details
/// This entry-point is synchronous and may block if the command-buffer is
/// executing when the entry-point is called.
/// executing when the entry-point is called. On error, none of the updates to
/// mutable-command objects are preserved.
///
/// @returns
/// - ::UR_RESULT_SUCCESS
/// - ::UR_RESULT_ERROR_UNINITIALIZED
/// - ::UR_RESULT_ERROR_DEVICE_LOST
/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
/// + `NULL == hCommand`
/// + `NULL == hCommandBuffer`
/// + `NULL == pUpdateKernelLaunch->hCommand`
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
/// + `NULL == pUpdateKernelLaunch`
/// - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
/// - ::UR_RESULT_ERROR_INVALID_SIZE
/// + `numKernelUpdates == 0`
/// - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
/// + 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.
/// is not supported by the device, and for any of any element of
/// `pUpdateKernelLaunch` the `numNewMemObjArgs`, `numNewPointerArgs`,
/// or `numNewValueArgs` members are not zero.
/// + If
/// ::UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_LOCAL_WORK_SIZE is
/// not supported by the device but
/// `pUpdateKernelLaunch->pNewLocalWorkSize` is not nullptr.
/// not supported by the device, and for any element of
/// `pUpdateKernelLaunch` the `pNewLocalWorkSize` member is not nullptr.
/// + 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.
/// not supported by the device, and for any element of
/// `pUpdateKernelLaunch` the `pNewLocalWorkSize` member is nullptr and
/// `pNewGlobalWorkSize` is not nullptr.
/// + If
/// ::UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_GLOBAL_WORK_SIZE
/// is not supported by the device but
/// `pUpdateKernelLaunch->pNewGlobalWorkSize` is not nullptr
/// is not supported by the device, and for any element of
/// `pUpdateKernelLaunch` the `pNewGlobalWorkSize` member is not nullptr
/// + If
/// ::UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_GLOBAL_WORK_OFFSET
/// is not supported by the device but
/// `pUpdateKernelLaunch->pNewGlobalWorkOffset` is not nullptr.
/// is not supported by the device, and for any element of
/// `pUpdateKernelLaunch` the `pNewGlobalWorkOffset` member is not
/// nullptr.
/// + If ::UR_DEVICE_COMMAND_BUFFER_UPDATE_CAPABILITY_FLAG_KERNEL_HANDLE
/// is not supported by the device but `pUpdateKernelLaunch->hNewKernel`
/// is not nullptr.
/// is not supported by the device, and for any element of
/// `pUpdateKernelLaunch` the `hNewKernel` member is not nullptr.
/// - ::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.
/// on creation of the `hCommandBuffer`.
/// + If `hCommandBuffer` has not been finalized.
/// - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_COMMAND_HANDLE_EXP
/// + If `hCommand` is not a kernel execution command.
/// + If for any element of `pUpdateKernelLaunch` the `hCommand` member
/// is not a kernel execution command.
/// + If for any element of `pUpdateKernelLaunch` the `hCommand` member
/// was not created from `hCommandBuffer`.
/// - ::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 < 1 ||
/// pUpdateKernelLaunch->newWorkDim > 3`
/// + If for any element of `pUpdateKernelLaunch` the `newWorkDim`
/// member is less than 1 or greater than 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.
/// + If `pUpdateKernelLaunch->newWorkDim` is different from the current
/// workDim in `hCommand` and,
/// `pUpdateKernelLaunch->pNewGlobalWorkSize`, or
/// `pUpdateKernelLaunch->pNewGlobalWorkOffset` are nullptr.
/// + If for any element of `pUpdateKernelLaunch` the `hNewKernel`
/// member was not passed to the `hKernel` or `phKernelAlternatives`
/// parameters of ::urCommandBufferAppendKernelLaunchExp when the
/// command was created.
/// + If for any element of `pUpdateKernelLaunch` the `newWorkDim`
/// member is different from the current workDim in the `hCommand`
/// member, and `pNewGlobalWorkSize` or `pNewGlobalWorkOffset` are
/// nullptr.
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
UR_APIEXPORT ur_result_t UR_APICALL urCommandBufferUpdateKernelLaunchExp(
/// [in] Handle of the command-buffer kernel command to update.
ur_exp_command_buffer_command_handle_t hCommand,
/// [in] Struct defining how the kernel command is to be updated.
/// [in] Handle of the command-buffer object.
ur_exp_command_buffer_handle_t hCommandBuffer,
/// [in] Length of pUpdateKernelLaunch.
uint32_t numKernelUpdates,
/// [in][range(0, numKernelUpdates)] List of structs defining how a
/// kernel commands are to be updated.
const ur_exp_command_buffer_update_kernel_launch_desc_t
*pUpdateKernelLaunch);

Expand Down Expand Up @@ -14191,7 +14203,8 @@ typedef struct ur_command_buffer_enqueue_exp_params_t {
/// @details Each entry is a pointer to the parameter passed to the function;
/// allowing the callback the ability to modify the parameter's value
typedef struct ur_command_buffer_update_kernel_launch_exp_params_t {
ur_exp_command_buffer_command_handle_t *phCommand;
ur_exp_command_buffer_handle_t *phCommandBuffer;
uint32_t *pnumKernelUpdates;
const ur_exp_command_buffer_update_kernel_launch_desc_t *
*ppUpdateKernelLaunch;
} ur_command_buffer_update_kernel_launch_exp_params_t;
Expand Down
2 changes: 1 addition & 1 deletion include/ur_ddi.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1599,7 +1599,7 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferEnqueueExp_t)(
///////////////////////////////////////////////////////////////////////////////
/// @brief Function-pointer for urCommandBufferUpdateKernelLaunchExp
typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferUpdateKernelLaunchExp_t)(
ur_exp_command_buffer_command_handle_t,
ur_exp_command_buffer_handle_t, uint32_t,
const ur_exp_command_buffer_update_kernel_launch_desc_t *);

///////////////////////////////////////////////////////////////////////////////
Expand Down
27 changes: 24 additions & 3 deletions include/ur_print.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11201,6 +11201,11 @@ inline std::ostream &operator<<(

ur::details::printStruct(os, (params.pNext));

os << ", ";
os << ".hCommand = ";

ur::details::printPtr(os, (params.hCommand));

os << ", ";
os << ".hNewKernel = ";

Expand Down Expand Up @@ -18691,14 +18696,30 @@ inline std::ostream &
operator<<(std::ostream &os, [[maybe_unused]] const struct
ur_command_buffer_update_kernel_launch_exp_params_t *params) {

os << ".hCommand = ";
os << ".hCommandBuffer = ";

ur::details::printPtr(os, *(params->phCommand));
ur::details::printPtr(os, *(params->phCommandBuffer));

os << ", ";
os << ".numKernelUpdates = ";

os << *(params->pnumKernelUpdates);

os << ", ";
os << ".pUpdateKernelLaunch = ";
ur::details::printPtr(
os, reinterpret_cast<const void *>(*(params->ppUpdateKernelLaunch)));
if (*(params->ppUpdateKernelLaunch) != NULL) {
os << " {";
for (size_t i = 0; i < *params->pnumKernelUpdates; ++i) {
if (i != 0) {
os << ", ";
}

ur::details::printPtr(os, *(params->ppUpdateKernelLaunch));
os << (*(params->ppUpdateKernelLaunch))[i];
}
os << "}";
}

return os;
}
Expand Down
7 changes: 5 additions & 2 deletions scripts/core/EXP-COMMAND-BUFFER.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -309,7 +309,8 @@ ${x}CommandBufferUpdateKernelLaunchExp.
${x}_exp_command_buffer_update_kernel_launch_desc_t update {
UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_UPDATE_KERNEL_LAUNCH_DESC, // stype
nullptr, // pNext
hNewKernel // hNewKernel
hCommand, // hCommand
hNewKernel, // hNewKernel
2, // numNewMemobjArgs
0, // numNewPointerArgs
0, // numNewValueArgs
Expand All @@ -325,7 +326,7 @@ ${x}CommandBufferUpdateKernelLaunchExp.
};
// Perform the update
${x}CommandBufferUpdateKernelLaunchExp(hCommand, &update);
${x}CommandBufferUpdateKernelLaunchExp(hCommandBuffer, 1, &update);
Command Event Update
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Expand Down Expand Up @@ -514,6 +515,8 @@ Changelog
+-----------+-------------------------------------------------------+
| 1.7 | Remove command handle reference counting and querying |
+-----------+-------------------------------------------------------+
| 1.8 | Change Kernel command update API to take a list |
+-----------+-------------------------------------------------------+

Contributors
--------------------------------------------------------------------------------
Expand Down
Loading

0 comments on commit de05080

Please sign in to comment.