Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor command update API to take a list of configurations #2666

Closed
wants to merge 3 commits into from
Closed

Refactor command update API to take a list of configurations #2666

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f55f193
Refactor command update API to take a list
EwanC Feb 4, 2025
737f344
Add handle translation for entry-point struct list
EwanC Feb 18, 2025
d6e02a1
Specify command state as undefined on update error
EwanC Feb 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 63 additions & 50 deletions include/ur_api.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9969,6 +9969,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 @@ -10032,6 +10047,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 @@ -10081,21 +10098,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 @@ -11042,74 +11044,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, the state of the
/// command-buffer commands being updated is undefined.
///
/// @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 @@ -14200,7 +14212,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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Loading