Skip to content

Commit 1cccb50

Browse files
mfrancepilloismfrancepillois
committed
[EXP][CMDBUF] Add Prefetch and Advise commands to cmd buffer experimental feature
Adds USM Prefetch and Advise append commands Update feature spec for new commands
1 parent fe4402d commit 1cccb50

File tree

13 files changed

+818
-0
lines changed

13 files changed

+818
-0
lines changed

‎include/ur.py

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -200,6 +200,8 @@ class ur_function_v(IntEnum):
200200
COMMAND_BUFFER_APPEND_MEM_BUFFER_FILL_EXP = 192 ## Enumerator for ::urCommandBufferAppendMemBufferFillExp
201201
ENQUEUE_COOPERATIVE_KERNEL_LAUNCH_EXP = 193 ## Enumerator for ::urEnqueueCooperativeKernelLaunchExp
202202
KERNEL_SUGGEST_MAX_COOPERATIVE_GROUP_COUNT_EXP = 194## Enumerator for ::urKernelSuggestMaxCooperativeGroupCountExp
203+
COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP = 195 ## Enumerator for ::urCommandBufferAppendUSMPrefetchExp
204+
COMMAND_BUFFER_APPEND_USM_ADVISE_EXP = 196 ## Enumerator for ::urCommandBufferAppendUSMAdviseExp
203205

204206
class ur_function_t(c_int):
205207
def __str__(self):
@@ -3616,6 +3618,20 @@ class ur_usm_exp_dditable_t(Structure):
36163618
else:
36173619
_urCommandBufferAppendMemBufferFillExp_t = CFUNCTYPE( ur_result_t, ur_exp_command_buffer_handle_t, ur_mem_handle_t, c_void_p, c_size_t, c_size_t, c_size_t, c_ulong, POINTER(ur_exp_command_buffer_sync_point_t), POINTER(ur_exp_command_buffer_sync_point_t) )
36183620

3621+
###############################################################################
3622+
## @brief Function-pointer for urCommandBufferAppendUSMPrefetchExp
3623+
if __use_win_types:
3624+
_urCommandBufferAppendUSMPrefetchExp_t = WINFUNCTYPE( ur_result_t, ur_exp_command_buffer_handle_t, c_void_p, c_size_t, ur_usm_migration_flags_t, c_ulong, POINTER(ur_exp_command_buffer_sync_point_t), POINTER(ur_exp_command_buffer_sync_point_t) )
3625+
else:
3626+
_urCommandBufferAppendUSMPrefetchExp_t = CFUNCTYPE( ur_result_t, ur_exp_command_buffer_handle_t, c_void_p, c_size_t, ur_usm_migration_flags_t, c_ulong, POINTER(ur_exp_command_buffer_sync_point_t), POINTER(ur_exp_command_buffer_sync_point_t) )
3627+
3628+
###############################################################################
3629+
## @brief Function-pointer for urCommandBufferAppendUSMAdviseExp
3630+
if __use_win_types:
3631+
_urCommandBufferAppendUSMAdviseExp_t = WINFUNCTYPE( ur_result_t, ur_exp_command_buffer_handle_t, c_void_p, c_size_t, ur_usm_advice_flags_t, POINTER(ur_exp_command_buffer_sync_point_t) )
3632+
else:
3633+
_urCommandBufferAppendUSMAdviseExp_t = CFUNCTYPE( ur_result_t, ur_exp_command_buffer_handle_t, c_void_p, c_size_t, ur_usm_advice_flags_t, POINTER(ur_exp_command_buffer_sync_point_t) )
3634+
36193635
###############################################################################
36203636
## @brief Function-pointer for urCommandBufferEnqueueExp
36213637
if __use_win_types:
@@ -3642,6 +3658,8 @@ class ur_command_buffer_exp_dditable_t(Structure):
36423658
("pfnAppendMemBufferWriteRectExp", c_void_p), ## _urCommandBufferAppendMemBufferWriteRectExp_t
36433659
("pfnAppendMemBufferReadRectExp", c_void_p), ## _urCommandBufferAppendMemBufferReadRectExp_t
36443660
("pfnAppendMemBufferFillExp", c_void_p), ## _urCommandBufferAppendMemBufferFillExp_t
3661+
("pfnAppendUSMPrefetchExp", c_void_p), ## _urCommandBufferAppendUSMPrefetchExp_t
3662+
("pfnAppendUSMAdviseExp", c_void_p), ## _urCommandBufferAppendUSMAdviseExp_t
36453663
("pfnEnqueueExp", c_void_p) ## _urCommandBufferEnqueueExp_t
36463664
]
36473665

@@ -4162,6 +4180,8 @@ def __init__(self, version : ur_api_version_t):
41624180
self.urCommandBufferAppendMemBufferWriteRectExp = _urCommandBufferAppendMemBufferWriteRectExp_t(self.__dditable.CommandBufferExp.pfnAppendMemBufferWriteRectExp)
41634181
self.urCommandBufferAppendMemBufferReadRectExp = _urCommandBufferAppendMemBufferReadRectExp_t(self.__dditable.CommandBufferExp.pfnAppendMemBufferReadRectExp)
41644182
self.urCommandBufferAppendMemBufferFillExp = _urCommandBufferAppendMemBufferFillExp_t(self.__dditable.CommandBufferExp.pfnAppendMemBufferFillExp)
4183+
self.urCommandBufferAppendUSMPrefetchExp = _urCommandBufferAppendUSMPrefetchExp_t(self.__dditable.CommandBufferExp.pfnAppendUSMPrefetchExp)
4184+
self.urCommandBufferAppendUSMAdviseExp = _urCommandBufferAppendUSMAdviseExp_t(self.__dditable.CommandBufferExp.pfnAppendUSMAdviseExp)
41654185
self.urCommandBufferEnqueueExp = _urCommandBufferEnqueueExp_t(self.__dditable.CommandBufferExp.pfnEnqueueExp)
41664186

41674187
# call driver to get function pointers

‎include/ur_api.h

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -209,6 +209,8 @@ typedef enum ur_function_t {
209209
UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_FILL_EXP = 192, ///< Enumerator for ::urCommandBufferAppendMemBufferFillExp
210210
UR_FUNCTION_ENQUEUE_COOPERATIVE_KERNEL_LAUNCH_EXP = 193, ///< Enumerator for ::urEnqueueCooperativeKernelLaunchExp
211211
UR_FUNCTION_KERNEL_SUGGEST_MAX_COOPERATIVE_GROUP_COUNT_EXP = 194, ///< Enumerator for ::urKernelSuggestMaxCooperativeGroupCountExp
212+
UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP = 195, ///< Enumerator for ::urCommandBufferAppendUSMPrefetchExp
213+
UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP = 196, ///< Enumerator for ::urCommandBufferAppendUSMAdviseExp
212214
/// @cond
213215
UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
214216
/// @endcond
@@ -8159,6 +8161,73 @@ urCommandBufferAppendMemBufferFillExp(
81598161
ur_exp_command_buffer_sync_point_t *pSyncPoint ///< [out][optional] sync point associated with this command.
81608162
);
81618163

8164+
///////////////////////////////////////////////////////////////////////////////
8165+
/// @brief Append a USM Prefetch command to a command-buffer object
8166+
///
8167+
/// @returns
8168+
/// - ::UR_RESULT_SUCCESS
8169+
/// - ::UR_RESULT_ERROR_UNINITIALIZED
8170+
/// - ::UR_RESULT_ERROR_DEVICE_LOST
8171+
/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
8172+
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
8173+
/// + `NULL == hCommandBuffer`
8174+
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
8175+
/// + `NULL == pMemory`
8176+
/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
8177+
/// + `::UR_USM_MIGRATION_FLAGS_MASK & flags`
8178+
/// - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
8179+
/// - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
8180+
/// - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP
8181+
/// + `pSyncPointWaitList == NULL && numSyncPointsInWaitList > 0`
8182+
/// + `pSyncPointWaitList != NULL && numSyncPointsInWaitList == 0`
8183+
/// - ::UR_RESULT_ERROR_INVALID_MEM_OBJECT
8184+
/// - ::UR_RESULT_ERROR_INVALID_SIZE
8185+
/// + `size == 0`
8186+
/// + If `size` is higher than the allocation size of `pMemory`
8187+
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
8188+
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
8189+
UR_APIEXPORT ur_result_t UR_APICALL
8190+
urCommandBufferAppendUSMPrefetchExp(
8191+
ur_exp_command_buffer_handle_t hCommandBuffer, ///< [in] handle of the command-buffer object.
8192+
void *pMemory, ///< [in] pointer to USM allocated memory to prefetch.
8193+
size_t size, ///< [in] size in bytes to be fetched.
8194+
ur_usm_migration_flags_t flags, ///< [in] USM prefetch flags
8195+
uint32_t numSyncPointsInWaitList, ///< [in] The number of sync points in the provided dependency list.
8196+
const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ///< [in][optional] A list of sync points that this command depends on.
8197+
ur_exp_command_buffer_sync_point_t *pSyncPoint ///< [out][optional] sync point associated with this command.
8198+
);
8199+
8200+
///////////////////////////////////////////////////////////////////////////////
8201+
/// @brief Append a USM Advise command to a command-buffer object
8202+
///
8203+
/// @returns
8204+
/// - ::UR_RESULT_SUCCESS
8205+
/// - ::UR_RESULT_ERROR_UNINITIALIZED
8206+
/// - ::UR_RESULT_ERROR_DEVICE_LOST
8207+
/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
8208+
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
8209+
/// + `NULL == hCommandBuffer`
8210+
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
8211+
/// + `NULL == pMemory`
8212+
/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
8213+
/// + `::UR_USM_ADVICE_FLAGS_MASK & advice`
8214+
/// - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
8215+
/// - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
8216+
/// - ::UR_RESULT_ERROR_INVALID_MEM_OBJECT
8217+
/// - ::UR_RESULT_ERROR_INVALID_SIZE
8218+
/// + `size == 0`
8219+
/// + If `size` is higher than the allocation size of `pMemory`
8220+
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
8221+
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
8222+
UR_APIEXPORT ur_result_t UR_APICALL
8223+
urCommandBufferAppendUSMAdviseExp(
8224+
ur_exp_command_buffer_handle_t hCommandBuffer, ///< [in] handle of the command-buffer object.
8225+
void *pMemory, ///< [in] pointer to the USM memory object.
8226+
size_t size, ///< [in] size in bytes to be advised.
8227+
ur_usm_advice_flags_t advice, ///< [in] USM memory advice
8228+
ur_exp_command_buffer_sync_point_t *pSyncPoint ///< [out][optional] sync point associated with this command.
8229+
);
8230+
81628231
///////////////////////////////////////////////////////////////////////////////
81638232
/// @brief Submit a command-buffer for execution on a queue.
81648233
///
@@ -10332,6 +10401,32 @@ typedef struct ur_command_buffer_append_mem_buffer_fill_exp_params_t {
1033210401
ur_exp_command_buffer_sync_point_t **ppSyncPoint;
1033310402
} ur_command_buffer_append_mem_buffer_fill_exp_params_t;
1033410403

10404+
///////////////////////////////////////////////////////////////////////////////
10405+
/// @brief Function parameters for urCommandBufferAppendUSMPrefetchExp
10406+
/// @details Each entry is a pointer to the parameter passed to the function;
10407+
/// allowing the callback the ability to modify the parameter's value
10408+
typedef struct ur_command_buffer_append_usm_prefetch_exp_params_t {
10409+
ur_exp_command_buffer_handle_t *phCommandBuffer;
10410+
void **ppMemory;
10411+
size_t *psize;
10412+
ur_usm_migration_flags_t *pflags;
10413+
uint32_t *pnumSyncPointsInWaitList;
10414+
const ur_exp_command_buffer_sync_point_t **ppSyncPointWaitList;
10415+
ur_exp_command_buffer_sync_point_t **ppSyncPoint;
10416+
} ur_command_buffer_append_usm_prefetch_exp_params_t;
10417+
10418+
///////////////////////////////////////////////////////////////////////////////
10419+
/// @brief Function parameters for urCommandBufferAppendUSMAdviseExp
10420+
/// @details Each entry is a pointer to the parameter passed to the function;
10421+
/// allowing the callback the ability to modify the parameter's value
10422+
typedef struct ur_command_buffer_append_usm_advise_exp_params_t {
10423+
ur_exp_command_buffer_handle_t *phCommandBuffer;
10424+
void **ppMemory;
10425+
size_t *psize;
10426+
ur_usm_advice_flags_t *padvice;
10427+
ur_exp_command_buffer_sync_point_t **ppSyncPoint;
10428+
} ur_command_buffer_append_usm_advise_exp_params_t;
10429+
1033510430
///////////////////////////////////////////////////////////////////////////////
1033610431
/// @brief Function parameters for urCommandBufferEnqueueExp
1033710432
/// @details Each entry is a pointer to the parameter passed to the function;

‎include/ur_ddi.h

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1923,6 +1923,26 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferFillExp_t)(
19231923
const ur_exp_command_buffer_sync_point_t *,
19241924
ur_exp_command_buffer_sync_point_t *);
19251925

1926+
///////////////////////////////////////////////////////////////////////////////
1927+
/// @brief Function-pointer for urCommandBufferAppendUSMPrefetchExp
1928+
typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendUSMPrefetchExp_t)(
1929+
ur_exp_command_buffer_handle_t,
1930+
void *,
1931+
size_t,
1932+
ur_usm_migration_flags_t,
1933+
uint32_t,
1934+
const ur_exp_command_buffer_sync_point_t *,
1935+
ur_exp_command_buffer_sync_point_t *);
1936+
1937+
///////////////////////////////////////////////////////////////////////////////
1938+
/// @brief Function-pointer for urCommandBufferAppendUSMAdviseExp
1939+
typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendUSMAdviseExp_t)(
1940+
ur_exp_command_buffer_handle_t,
1941+
void *,
1942+
size_t,
1943+
ur_usm_advice_flags_t,
1944+
ur_exp_command_buffer_sync_point_t *);
1945+
19261946
///////////////////////////////////////////////////////////////////////////////
19271947
/// @brief Function-pointer for urCommandBufferEnqueueExp
19281948
typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferEnqueueExp_t)(
@@ -1949,6 +1969,8 @@ typedef struct ur_command_buffer_exp_dditable_t {
19491969
ur_pfnCommandBufferAppendMemBufferWriteRectExp_t pfnAppendMemBufferWriteRectExp;
19501970
ur_pfnCommandBufferAppendMemBufferReadRectExp_t pfnAppendMemBufferReadRectExp;
19511971
ur_pfnCommandBufferAppendMemBufferFillExp_t pfnAppendMemBufferFillExp;
1972+
ur_pfnCommandBufferAppendUSMPrefetchExp_t pfnAppendUSMPrefetchExp;
1973+
ur_pfnCommandBufferAppendUSMAdviseExp_t pfnAppendUSMAdviseExp;
19521974
ur_pfnCommandBufferEnqueueExp_t pfnEnqueueExp;
19531975
} ur_command_buffer_exp_dditable_t;
19541976

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,8 @@ Currently only the following commands are supported:
101101
* ${x}CommandBufferAppendMemBufferWriteExp
102102
* ${x}CommandBufferAppendMemBufferWriteRectExp
103103
* ${x}CommandBufferAppendMemBufferFillExp
104+
* ${x}CommandBufferAppendUSMPrefetchExp
105+
* ${x}CommandBufferAppendUSMAdviseExp
104106

105107
It is planned to eventually support any command type from the Core API which can
106108
actually be appended to the equiavalent adapter native constructs.
@@ -178,6 +180,8 @@ Enums
178180
* ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_WRITE_EXP
179181
* ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_WRITE_RECT_EXP
180182
* ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_FILL_EXP
183+
* ${X}_FUNCTION_COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP
184+
* ${X}_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP
181185

182186

183187

@@ -204,6 +208,8 @@ Functions
204208
* ${x}CommandBufferAppendMemBufferWriteExp
205209
* ${x}CommandBufferAppendMemBufferWriteRectExp
206210
* ${x}CommandBufferAppendMemBufferFillExp
211+
* ${x}CommandBufferAppendUSMPrefetchExp
212+
* ${x}CommandBufferAppendUSMAdviseExp
207213
* ${x}CommandBufferEnqueueExp
208214

209215
Changelog
@@ -218,6 +224,9 @@ Changelog
218224
+-----------+-------------------------------------------------------+
219225
| 1.2 | Add function definitions for fill commands |
220226
+-----------+-------------------------------------------------------+
227+
| 1.2 | Add function definitions for Prefetch and Advise |
228+
| | commands |
229+
+-----------+-------------------------------------------------------+
221230

222231
Contributors
223232
--------------------------------------------------------------------------------

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

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -588,6 +588,75 @@ returns:
588588
- $X_RESULT_ERROR_OUT_OF_RESOURCES
589589
--- #--------------------------------------------------------------------------
590590
type: function
591+
desc: "Append a USM Prefetch command to a command-buffer object"
592+
class: $xCommandBuffer
593+
name: AppendUSMPrefetchExp
594+
params:
595+
- type: $x_exp_command_buffer_handle_t
596+
name: hCommandBuffer
597+
desc: "[in] handle of the command-buffer object."
598+
- type: "void*"
599+
name: pMemory
600+
desc: "[in] pointer to USM allocated memory to prefetch."
601+
- type: "size_t"
602+
name: size
603+
desc: "[in] size in bytes to be fetched."
604+
- type: $x_usm_migration_flags_t
605+
name: flags
606+
desc: "[in] USM prefetch flags"
607+
- type: uint32_t
608+
name: numSyncPointsInWaitList
609+
desc: "[in] The number of sync points in the provided dependency list."
610+
- type: "const $x_exp_command_buffer_sync_point_t*"
611+
name: pSyncPointWaitList
612+
desc: "[in][optional] A list of sync points that this command depends on."
613+
- type: "$x_exp_command_buffer_sync_point_t*"
614+
name: pSyncPoint
615+
desc: "[out][optional] sync point associated with this command."
616+
returns:
617+
- $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
618+
- $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
619+
- $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP:
620+
- "`pSyncPointWaitList == NULL && numSyncPointsInWaitList > 0`"
621+
- "`pSyncPointWaitList != NULL && numSyncPointsInWaitList == 0`"
622+
- $X_RESULT_ERROR_INVALID_MEM_OBJECT
623+
- $X_RESULT_ERROR_INVALID_SIZE:
624+
- "`size == 0`"
625+
- "If `size` is higher than the allocation size of `pMemory`"
626+
- $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
627+
- $X_RESULT_ERROR_OUT_OF_RESOURCES
628+
--- #--------------------------------------------------------------------------
629+
type: function
630+
desc: "Append a USM Advise command to a command-buffer object"
631+
class: $xCommandBuffer
632+
name: AppendUSMAdviseExp
633+
params:
634+
- type: $x_exp_command_buffer_handle_t
635+
name: hCommandBuffer
636+
desc: "[in] handle of the command-buffer object."
637+
- type: "void*"
638+
name: pMemory
639+
desc: "[in] pointer to the USM memory object."
640+
- type: "size_t"
641+
name: size
642+
desc: "[in] size in bytes to be advised."
643+
- type: $x_usm_advice_flags_t
644+
name: advice
645+
desc: "[in] USM memory advice"
646+
- type: "$x_exp_command_buffer_sync_point_t*"
647+
name: pSyncPoint
648+
desc: "[out][optional] sync point associated with this command."
649+
returns:
650+
- $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
651+
- $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
652+
- $X_RESULT_ERROR_INVALID_MEM_OBJECT
653+
- $X_RESULT_ERROR_INVALID_SIZE:
654+
- "`size == 0`"
655+
- "If `size` is higher than the allocation size of `pMemory`"
656+
- $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
657+
- $X_RESULT_ERROR_OUT_OF_RESOURCES
658+
--- #--------------------------------------------------------------------------
659+
type: function
591660
desc: "Submit a command-buffer for execution on a queue."
592661
class: $xCommandBuffer
593662
name: EnqueueExp

‎scripts/core/registry.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -541,6 +541,12 @@ etors:
541541
- name: KERNEL_SUGGEST_MAX_COOPERATIVE_GROUP_COUNT_EXP
542542
desc: Enumerator for $xKernelSuggestMaxCooperativeGroupCountExp
543543
value: '194'
544+
- name: COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP
545+
desc: Enumerator for $xCommandBufferAppendUSMPrefetchExp
546+
value: '195'
547+
- name: COMMAND_BUFFER_APPEND_USM_ADVISE_EXP
548+
desc: Enumerator for $xCommandBufferAppendUSMAdviseExp
549+
value: '196'
544550
---
545551
type: enum
546552
desc: Defines structure types

0 commit comments

Comments
 (0)