Skip to content

Commit

Permalink
Remove command-buffer command handle ref counting
Browse files Browse the repository at this point in the history 
The handles to individual commands returned from command-buffer
append entry-points currently need reference counted by the user.
However this isn't a model that maps to OpenCL/CUDA/HIP/Level-Zero
where the lifetime of commands is tied to the lifetime of the parent
command-buffer/graph/command-list.

Remove this idiom from the command-buffer UR API, adapters, and CTS.
The APIs that are removed are
* `urCommandBufferCommandGetInfoExp`
* `urCommandBufferReleaseCommandExp`
* `urCommandBufferRetainCommandExp`
  • Loading branch information
@EwanC
EwanC committed Jan 17, 2025
1 parent 30d183a commit ef1de22
Show file tree
Hide file tree
Showing 49 changed files with 78 additions and 1,691 deletions.
101 changes: 0 additions & 101 deletions include/ur_api.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -202,11 +202,8 @@ typedef enum ur_function_t {
UR_FUNCTION_KERNEL_SUGGEST_MAX_COOPERATIVE_GROUP_COUNT_EXP = 215, ///< Enumerator for ::urKernelSuggestMaxCooperativeGroupCountExp
UR_FUNCTION_PROGRAM_GET_GLOBAL_VARIABLE_POINTER = 216, ///< Enumerator for ::urProgramGetGlobalVariablePointer
UR_FUNCTION_DEVICE_GET_SELECTED = 217, ///< Enumerator for ::urDeviceGetSelected
UR_FUNCTION_COMMAND_BUFFER_RETAIN_COMMAND_EXP = 218, ///< Enumerator for ::urCommandBufferRetainCommandExp
UR_FUNCTION_COMMAND_BUFFER_RELEASE_COMMAND_EXP = 219, ///< Enumerator for ::urCommandBufferReleaseCommandExp
UR_FUNCTION_COMMAND_BUFFER_UPDATE_KERNEL_LAUNCH_EXP = 220, ///< Enumerator for ::urCommandBufferUpdateKernelLaunchExp
UR_FUNCTION_COMMAND_BUFFER_GET_INFO_EXP = 221, ///< Enumerator for ::urCommandBufferGetInfoExp
UR_FUNCTION_COMMAND_BUFFER_COMMAND_GET_INFO_EXP = 222, ///< Enumerator for ::urCommandBufferCommandGetInfoExp
UR_FUNCTION_ENQUEUE_TIMESTAMP_RECORDING_EXP = 223, ///< Enumerator for ::urEnqueueTimestampRecordingExp
UR_FUNCTION_ENQUEUE_KERNEL_LAUNCH_CUSTOM_EXP = 224, ///< Enumerator for ::urEnqueueKernelLaunchCustomExp
UR_FUNCTION_KERNEL_GET_SUGGESTED_LOCAL_WORK_SIZE = 225, ///< Enumerator for ::urKernelGetSuggestedLocalWorkSize
Expand Down Expand Up @@ -9261,43 +9258,6 @@ urCommandBufferEnqueueExp(
///< not NULL, phEvent must not refer to an element of the phEventWaitList array.
);

///////////////////////////////////////////////////////////////////////////////
/// @brief Increment the command object's reference count.
///
/// @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`
/// - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_COMMAND_HANDLE_EXP
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
UR_APIEXPORT ur_result_t UR_APICALL
urCommandBufferRetainCommandExp(
ur_exp_command_buffer_command_handle_t hCommand ///< [in][retain] Handle of the command-buffer command.
);

///////////////////////////////////////////////////////////////////////////////
/// @brief Decrement the command object's reference count and delete the command
/// object if the reference count becomes zero.
///
/// @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`
/// - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_COMMAND_HANDLE_EXP
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
UR_APIEXPORT ur_result_t UR_APICALL
urCommandBufferReleaseCommandExp(
ur_exp_command_buffer_command_handle_t hCommand ///< [in][release] Handle of the command-buffer command.
);

///////////////////////////////////////////////////////////////////////////////
/// @brief Update a kernel launch command in a finalized command-buffer.
///
Expand Down Expand Up @@ -9441,39 +9401,6 @@ urCommandBufferGetInfoExp(
size_t *pPropSizeRet ///< [out][optional] bytes returned in command-buffer property
);

///////////////////////////////////////////////////////////////////////////////
/// @brief Get command-buffer object information.
///
/// @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`
/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
/// + `::UR_EXP_COMMAND_BUFFER_COMMAND_INFO_REFERENCE_COUNT < propName`
/// - ::UR_RESULT_ERROR_UNSUPPORTED_ENUMERATION
/// + If `propName` is not supported by the adapter.
/// - ::UR_RESULT_ERROR_INVALID_SIZE
/// + `propSize == 0 && pPropValue != NULL`
/// + If `propSize` is less than the real number of bytes needed to return the info.
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
/// + `propSize != 0 && pPropValue == NULL`
/// + `pPropValue == NULL && pPropSizeRet == NULL`
/// - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_COMMAND_HANDLE_EXP
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
UR_APIEXPORT ur_result_t UR_APICALL
urCommandBufferCommandGetInfoExp(
ur_exp_command_buffer_command_handle_t hCommand, ///< [in] handle of the command-buffer command object
ur_exp_command_buffer_command_info_t propName, ///< [in] the name of the command-buffer command property to query
size_t propSize, ///< [in] size in bytes of the command-buffer command property value
void *pPropValue, ///< [out][optional][typename(propName, propSize)] value of the
///< command-buffer command property
size_t *pPropSizeRet ///< [out][optional] bytes returned in command-buffer command property
);

#if !defined(__GNUC__)
#pragma endregion
#endif
Expand Down Expand Up @@ -12561,22 +12488,6 @@ typedef struct ur_command_buffer_enqueue_exp_params_t {
ur_event_handle_t **pphEvent;
} ur_command_buffer_enqueue_exp_params_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Function parameters for urCommandBufferRetainCommandExp
/// @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_retain_command_exp_params_t {
ur_exp_command_buffer_command_handle_t *phCommand;
} ur_command_buffer_retain_command_exp_params_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Function parameters for urCommandBufferReleaseCommandExp
/// @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_release_command_exp_params_t {
ur_exp_command_buffer_command_handle_t *phCommand;
} ur_command_buffer_release_command_exp_params_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Function parameters for urCommandBufferUpdateKernelLaunchExp
/// @details Each entry is a pointer to the parameter passed to the function;
Expand Down Expand Up @@ -12617,18 +12528,6 @@ typedef struct ur_command_buffer_get_info_exp_params_t {
size_t **ppPropSizeRet;
} ur_command_buffer_get_info_exp_params_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Function parameters for urCommandBufferCommandGetInfoExp
/// @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_command_get_info_exp_params_t {
ur_exp_command_buffer_command_handle_t *phCommand;
ur_exp_command_buffer_command_info_t *ppropName;
size_t *ppropSize;
void **ppPropValue;
size_t **ppPropSizeRet;
} ur_command_buffer_command_get_info_exp_params_t;

///////////////////////////////////////////////////////////////////////////////
/// @brief Function parameters for urTensorMapEncodeIm2ColExp
/// @details Each entry is a pointer to the parameter passed to the function;
Expand Down
3 changes: 0 additions & 3 deletions include/ur_api_funcs.def
View file
Original file line number Diff line number Diff line change
Expand Up @@ -179,13 +179,10 @@ _UR_API(urCommandBufferAppendMemBufferFillExp)
_UR_API(urCommandBufferAppendUSMPrefetchExp)
_UR_API(urCommandBufferAppendUSMAdviseExp)
_UR_API(urCommandBufferEnqueueExp)
_UR_API(urCommandBufferRetainCommandExp)
_UR_API(urCommandBufferReleaseCommandExp)
_UR_API(urCommandBufferUpdateKernelLaunchExp)
_UR_API(urCommandBufferUpdateSignalEventExp)
_UR_API(urCommandBufferUpdateWaitEventsExp)
_UR_API(urCommandBufferGetInfoExp)
_UR_API(urCommandBufferCommandGetInfoExp)
_UR_API(urTensorMapEncodeIm2ColExp)
_UR_API(urTensorMapEncodeTiledExp)
_UR_API(urUsmP2PEnablePeerAccessExp)
Expand Down
22 changes: 0 additions & 22 deletions include/ur_ddi.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2164,16 +2164,6 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferEnqueueExp_t)(
const ur_event_handle_t *,
ur_event_handle_t *);

///////////////////////////////////////////////////////////////////////////////
/// @brief Function-pointer for urCommandBufferRetainCommandExp
typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferRetainCommandExp_t)(
ur_exp_command_buffer_command_handle_t);

///////////////////////////////////////////////////////////////////////////////
/// @brief Function-pointer for urCommandBufferReleaseCommandExp
typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferReleaseCommandExp_t)(
ur_exp_command_buffer_command_handle_t);

///////////////////////////////////////////////////////////////////////////////
/// @brief Function-pointer for urCommandBufferUpdateKernelLaunchExp
typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferUpdateKernelLaunchExp_t)(
Expand Down Expand Up @@ -2202,15 +2192,6 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferGetInfoExp_t)(
void *,
size_t *);

///////////////////////////////////////////////////////////////////////////////
/// @brief Function-pointer for urCommandBufferCommandGetInfoExp
typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferCommandGetInfoExp_t)(
ur_exp_command_buffer_command_handle_t,
ur_exp_command_buffer_command_info_t,
size_t,
void *,
size_t *);

///////////////////////////////////////////////////////////////////////////////
/// @brief Table of CommandBufferExp functions pointers
typedef struct ur_command_buffer_exp_dditable_t {
Expand All @@ -2231,13 +2212,10 @@ typedef struct ur_command_buffer_exp_dditable_t {
ur_pfnCommandBufferAppendUSMPrefetchExp_t pfnAppendUSMPrefetchExp;
ur_pfnCommandBufferAppendUSMAdviseExp_t pfnAppendUSMAdviseExp;
ur_pfnCommandBufferEnqueueExp_t pfnEnqueueExp;
ur_pfnCommandBufferRetainCommandExp_t pfnRetainCommandExp;
ur_pfnCommandBufferReleaseCommandExp_t pfnReleaseCommandExp;
ur_pfnCommandBufferUpdateKernelLaunchExp_t pfnUpdateKernelLaunchExp;
ur_pfnCommandBufferUpdateSignalEventExp_t pfnUpdateSignalEventExp;
ur_pfnCommandBufferUpdateWaitEventsExp_t pfnUpdateWaitEventsExp;
ur_pfnCommandBufferGetInfoExp_t pfnGetInfoExp;
ur_pfnCommandBufferCommandGetInfoExp_t pfnCommandGetInfoExp;
} ur_command_buffer_exp_dditable_t;

///////////////////////////////////////////////////////////////////////////////
Expand Down
24 changes: 0 additions & 24 deletions include/ur_print.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2522,22 +2522,6 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintCommandBufferAppendUsmAdviseExpParams
/// - `buff_size < out_size`
UR_APIEXPORT ur_result_t UR_APICALL urPrintCommandBufferEnqueueExpParams(const struct ur_command_buffer_enqueue_exp_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);

///////////////////////////////////////////////////////////////////////////////
/// @brief Print ur_command_buffer_retain_command_exp_params_t struct
/// @returns
/// - ::UR_RESULT_SUCCESS
/// - ::UR_RESULT_ERROR_INVALID_SIZE
/// - `buff_size < out_size`
UR_APIEXPORT ur_result_t UR_APICALL urPrintCommandBufferRetainCommandExpParams(const struct ur_command_buffer_retain_command_exp_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);

///////////////////////////////////////////////////////////////////////////////
/// @brief Print ur_command_buffer_release_command_exp_params_t struct
/// @returns
/// - ::UR_RESULT_SUCCESS
/// - ::UR_RESULT_ERROR_INVALID_SIZE
/// - `buff_size < out_size`
UR_APIEXPORT ur_result_t UR_APICALL urPrintCommandBufferReleaseCommandExpParams(const struct ur_command_buffer_release_command_exp_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);

///////////////////////////////////////////////////////////////////////////////
/// @brief Print ur_command_buffer_update_kernel_launch_exp_params_t struct
/// @returns
Expand Down Expand Up @@ -2570,14 +2554,6 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintCommandBufferUpdateWaitEventsExpParam
/// - `buff_size < out_size`
UR_APIEXPORT ur_result_t UR_APICALL urPrintCommandBufferGetInfoExpParams(const struct ur_command_buffer_get_info_exp_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);

///////////////////////////////////////////////////////////////////////////////
/// @brief Print ur_command_buffer_command_get_info_exp_params_t struct
/// @returns
/// - ::UR_RESULT_SUCCESS
/// - ::UR_RESULT_ERROR_INVALID_SIZE
/// - `buff_size < out_size`
UR_APIEXPORT ur_result_t UR_APICALL urPrintCommandBufferCommandGetInfoExpParams(const struct ur_command_buffer_command_get_info_exp_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);

///////////////////////////////////////////////////////////////////////////////
/// @brief Print ur_tensor_map_encode_im_2_col_exp_params_t struct
/// @returns
Expand Down
80 changes: 0 additions & 80 deletions include/ur_print.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -905,21 +905,12 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
case UR_FUNCTION_DEVICE_GET_SELECTED:
os << "UR_FUNCTION_DEVICE_GET_SELECTED";
break;
case UR_FUNCTION_COMMAND_BUFFER_RETAIN_COMMAND_EXP:
os << "UR_FUNCTION_COMMAND_BUFFER_RETAIN_COMMAND_EXP";
break;
case UR_FUNCTION_COMMAND_BUFFER_RELEASE_COMMAND_EXP:
os << "UR_FUNCTION_COMMAND_BUFFER_RELEASE_COMMAND_EXP";
break;
case UR_FUNCTION_COMMAND_BUFFER_UPDATE_KERNEL_LAUNCH_EXP:
os << "UR_FUNCTION_COMMAND_BUFFER_UPDATE_KERNEL_LAUNCH_EXP";
break;
case UR_FUNCTION_COMMAND_BUFFER_GET_INFO_EXP:
os << "UR_FUNCTION_COMMAND_BUFFER_GET_INFO_EXP";
break;
case UR_FUNCTION_COMMAND_BUFFER_COMMAND_GET_INFO_EXP:
os << "UR_FUNCTION_COMMAND_BUFFER_COMMAND_GET_INFO_EXP";
break;
case UR_FUNCTION_ENQUEUE_TIMESTAMP_RECORDING_EXP:
os << "UR_FUNCTION_ENQUEUE_TIMESTAMP_RECORDING_EXP";
break;
Expand Down Expand Up @@ -18494,34 +18485,6 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
return os;
}

///////////////////////////////////////////////////////////////////////////////
/// @brief Print operator for the ur_command_buffer_retain_command_exp_params_t type
/// @returns
/// std::ostream &
inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_command_buffer_retain_command_exp_params_t *params) {

os << ".hCommand = ";

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

return os;
}

///////////////////////////////////////////////////////////////////////////////
/// @brief Print operator for the ur_command_buffer_release_command_exp_params_t type
/// @returns
/// std::ostream &
inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_command_buffer_release_command_exp_params_t *params) {

os << ".hCommand = ";

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

return os;
}

///////////////////////////////////////////////////////////////////////////////
/// @brief Print operator for the ur_command_buffer_update_kernel_launch_exp_params_t type
/// @returns
Expand Down Expand Up @@ -18631,40 +18594,6 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
return os;
}

///////////////////////////////////////////////////////////////////////////////
/// @brief Print operator for the ur_command_buffer_command_get_info_exp_params_t type
/// @returns
/// std::ostream &
inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_command_buffer_command_get_info_exp_params_t *params) {

os << ".hCommand = ";

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

os << ", ";
os << ".propName = ";

os << *(params->ppropName);

os << ", ";
os << ".propSize = ";

os << *(params->ppropSize);

os << ", ";
os << ".pPropValue = ";
ur::details::printTagged(os, *(params->ppPropValue), *(params->ppropName), *(params->ppropSize));

os << ", ";
os << ".pPropSizeRet = ";

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

return os;
}

///////////////////////////////////////////////////////////////////////////////
/// @brief Print operator for the ur_tensor_map_encode_im_2_col_exp_params_t type
/// @returns
Expand Down Expand Up @@ -20071,12 +20000,6 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os, ur_function_
case UR_FUNCTION_COMMAND_BUFFER_ENQUEUE_EXP: {
os << (const struct ur_command_buffer_enqueue_exp_params_t *)params;
} break;
case UR_FUNCTION_COMMAND_BUFFER_RETAIN_COMMAND_EXP: {
os << (const struct ur_command_buffer_retain_command_exp_params_t *)params;
} break;
case UR_FUNCTION_COMMAND_BUFFER_RELEASE_COMMAND_EXP: {
os << (const struct ur_command_buffer_release_command_exp_params_t *)params;
} break;
case UR_FUNCTION_COMMAND_BUFFER_UPDATE_KERNEL_LAUNCH_EXP: {
os << (const struct ur_command_buffer_update_kernel_launch_exp_params_t *)params;
} break;
Expand All @@ -20089,9 +20012,6 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os, ur_function_
case UR_FUNCTION_COMMAND_BUFFER_GET_INFO_EXP: {
os << (const struct ur_command_buffer_get_info_exp_params_t *)params;
} break;
case UR_FUNCTION_COMMAND_BUFFER_COMMAND_GET_INFO_EXP: {
os << (const struct ur_command_buffer_command_get_info_exp_params_t *)params;
} break;
case UR_FUNCTION_TENSOR_MAP_ENCODE_IM_2_COL_EXP: {
os << (const struct ur_tensor_map_encode_im_2_col_exp_params_t *)params;
} break;
Expand Down
5 changes: 2 additions & 3 deletions scripts/core/EXP-COMMAND-BUFFER.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -486,13 +486,10 @@ Functions
* ${x}CommandBufferAppendUSMPrefetchExp
* ${x}CommandBufferAppendUSMAdviseExp
* ${x}CommandBufferEnqueueExp
* ${x}CommandBufferRetainCommandExp
* ${x}CommandBufferReleaseCommandExp
* ${x}CommandBufferUpdateKernelLaunchExp
* ${x}CommandBufferUpdateSignalEventExp
* ${x}CommandBufferUpdateWaitEventsExp
* ${x}CommandBufferGetInfoExp
* ${x}CommandBufferCommandGetInfoExp

Changelog
--------------------------------------------------------------------------------
Expand All @@ -515,6 +512,8 @@ Changelog
+-----------+-------------------------------------------------------+
| 1.6 | Command level synchronization with event objects |
+-----------+-------------------------------------------------------+
| 1.7 | Remove command handle reference counting and querying |
+-----------+-------------------------------------------------------+

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

0 comments on commit ef1de22

Please sign in to comment.