Merge pull request #885 from Bensuo/mfrancepillois/cmd-buffer-prefetc…

…h-memadvice

[EXP][CMDBUF] Add Prefetch and Advise commands to cmd buffer experimental feature

include/ur.py

@@ -200,6 +200,8 @@ class ur_function_v(IntEnum):
     COMMAND_BUFFER_APPEND_MEM_BUFFER_FILL_EXP = 192 ## Enumerator for ::urCommandBufferAppendMemBufferFillExp
     ENQUEUE_COOPERATIVE_KERNEL_LAUNCH_EXP = 193     ## Enumerator for ::urEnqueueCooperativeKernelLaunchExp
     KERNEL_SUGGEST_MAX_COOPERATIVE_GROUP_COUNT_EXP = 194## Enumerator for ::urKernelSuggestMaxCooperativeGroupCountExp
+    COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP = 195    ## Enumerator for ::urCommandBufferAppendUSMPrefetchExp
+    COMMAND_BUFFER_APPEND_USM_ADVISE_EXP = 196      ## Enumerator for ::urCommandBufferAppendUSMAdviseExp
 
 class ur_function_t(c_int):
     def __str__(self):
@@ -3616,6 +3618,20 @@ class ur_usm_exp_dditable_t(Structure):
 else:
     _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) )
 
+###############################################################################
+## @brief Function-pointer for urCommandBufferAppendUSMPrefetchExp
+if __use_win_types:
+    _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) )
+else:
+    _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) )
+
+###############################################################################
+## @brief Function-pointer for urCommandBufferAppendUSMAdviseExp
+if __use_win_types:
+    _urCommandBufferAppendUSMAdviseExp_t = WINFUNCTYPE( ur_result_t, ur_exp_command_buffer_handle_t, c_void_p, c_size_t, ur_usm_advice_flags_t, c_ulong, POINTER(ur_exp_command_buffer_sync_point_t), POINTER(ur_exp_command_buffer_sync_point_t) )
+else:
+    _urCommandBufferAppendUSMAdviseExp_t = CFUNCTYPE( ur_result_t, ur_exp_command_buffer_handle_t, c_void_p, c_size_t, ur_usm_advice_flags_t, c_ulong, POINTER(ur_exp_command_buffer_sync_point_t), POINTER(ur_exp_command_buffer_sync_point_t) )
+
 ###############################################################################
 ## @brief Function-pointer for urCommandBufferEnqueueExp
 if __use_win_types:
@@ -3642,6 +3658,8 @@ class ur_command_buffer_exp_dditable_t(Structure):
         ("pfnAppendMemBufferWriteRectExp", c_void_p),                   ## _urCommandBufferAppendMemBufferWriteRectExp_t
         ("pfnAppendMemBufferReadRectExp", c_void_p),                    ## _urCommandBufferAppendMemBufferReadRectExp_t
         ("pfnAppendMemBufferFillExp", c_void_p),                        ## _urCommandBufferAppendMemBufferFillExp_t
+        ("pfnAppendUSMPrefetchExp", c_void_p),                          ## _urCommandBufferAppendUSMPrefetchExp_t
+        ("pfnAppendUSMAdviseExp", c_void_p),                            ## _urCommandBufferAppendUSMAdviseExp_t
         ("pfnEnqueueExp", c_void_p)                                     ## _urCommandBufferEnqueueExp_t
     ]
 
@@ -4162,6 +4180,8 @@ def __init__(self, version : ur_api_version_t):
         self.urCommandBufferAppendMemBufferWriteRectExp = _urCommandBufferAppendMemBufferWriteRectExp_t(self.__dditable.CommandBufferExp.pfnAppendMemBufferWriteRectExp)
         self.urCommandBufferAppendMemBufferReadRectExp = _urCommandBufferAppendMemBufferReadRectExp_t(self.__dditable.CommandBufferExp.pfnAppendMemBufferReadRectExp)
         self.urCommandBufferAppendMemBufferFillExp = _urCommandBufferAppendMemBufferFillExp_t(self.__dditable.CommandBufferExp.pfnAppendMemBufferFillExp)
+        self.urCommandBufferAppendUSMPrefetchExp = _urCommandBufferAppendUSMPrefetchExp_t(self.__dditable.CommandBufferExp.pfnAppendUSMPrefetchExp)
+        self.urCommandBufferAppendUSMAdviseExp = _urCommandBufferAppendUSMAdviseExp_t(self.__dditable.CommandBufferExp.pfnAppendUSMAdviseExp)
         self.urCommandBufferEnqueueExp = _urCommandBufferEnqueueExp_t(self.__dditable.CommandBufferExp.pfnEnqueueExp)
 
         # call driver to get function pointers

include/ur_api.h

@@ -209,6 +209,8 @@ typedef enum ur_function_t {
     UR_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_FILL_EXP = 192,               ///< Enumerator for ::urCommandBufferAppendMemBufferFillExp
     UR_FUNCTION_ENQUEUE_COOPERATIVE_KERNEL_LAUNCH_EXP = 193,                   ///< Enumerator for ::urEnqueueCooperativeKernelLaunchExp
     UR_FUNCTION_KERNEL_SUGGEST_MAX_COOPERATIVE_GROUP_COUNT_EXP = 194,          ///< Enumerator for ::urKernelSuggestMaxCooperativeGroupCountExp
+    UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP = 195,                  ///< Enumerator for ::urCommandBufferAppendUSMPrefetchExp
+    UR_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP = 196,                    ///< Enumerator for ::urCommandBufferAppendUSMAdviseExp
     /// @cond
     UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -8159,6 +8161,88 @@ urCommandBufferAppendMemBufferFillExp(
     ur_exp_command_buffer_sync_point_t *pSyncPoint                ///< [out][optional] sync point associated with this command.
 );
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Append a USM Prefetch command to a command-buffer object
+///
+/// @details
+///     - Prefetching may not be supported for all devices or allocation types.
+///       If memory prefetching is not supported, the prefetch hint will be
+///       ignored.
+///
+/// @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 == hCommandBuffer`
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == pMemory`
+///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
+///         + `::UR_USM_MIGRATION_FLAGS_MASK & flags`
+///     - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
+///     - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
+///     - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP
+///         + `pSyncPointWaitList == NULL && numSyncPointsInWaitList > 0`
+///         + `pSyncPointWaitList != NULL && numSyncPointsInWaitList == 0`
+///     - ::UR_RESULT_ERROR_INVALID_MEM_OBJECT
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         + `size == 0`
+///         + If `size` is higher than the allocation size of `pMemory`
+///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
+///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
+UR_APIEXPORT ur_result_t UR_APICALL
+urCommandBufferAppendUSMPrefetchExp(
+    ur_exp_command_buffer_handle_t hCommandBuffer,                ///< [in] handle of the command-buffer object.
+    const void *pMemory,                                          ///< [in] pointer to USM allocated memory to prefetch.
+    size_t size,                                                  ///< [in] size in bytes to be fetched.
+    ur_usm_migration_flags_t flags,                               ///< [in] USM prefetch flags
+    uint32_t numSyncPointsInWaitList,                             ///< [in] The number of sync points in the provided dependency list.
+    const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ///< [in][optional] A list of sync points that this command depends on.
+    ur_exp_command_buffer_sync_point_t *pSyncPoint                ///< [out][optional] sync point associated with this command.
+);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Append a USM Advise command to a command-buffer object
+///
+/// @details
+///     - Not all memory advice hints may be supported for all devices or
+///       allocation types. If a memory advice hint is not supported, it will be
+///       ignored.
+///
+/// @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 == hCommandBuffer`
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == pMemory`
+///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
+///         + `::UR_USM_ADVICE_FLAGS_MASK & advice`
+///     - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
+///     - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
+///     - ::UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP
+///         + `pSyncPointWaitList == NULL && numSyncPointsInWaitList > 0`
+///         + `pSyncPointWaitList != NULL && numSyncPointsInWaitList == 0`
+///     - ::UR_RESULT_ERROR_INVALID_MEM_OBJECT
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         + `size == 0`
+///         + If `size` is higher than the allocation size of `pMemory`
+///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
+///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
+UR_APIEXPORT ur_result_t UR_APICALL
+urCommandBufferAppendUSMAdviseExp(
+    ur_exp_command_buffer_handle_t hCommandBuffer,                ///< [in] handle of the command-buffer object.
+    const void *pMemory,                                          ///< [in] pointer to the USM memory object.
+    size_t size,                                                  ///< [in] size in bytes to be advised.
+    ur_usm_advice_flags_t advice,                                 ///< [in] USM memory advice
+    uint32_t numSyncPointsInWaitList,                             ///< [in] The number of sync points in the provided dependency list.
+    const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ///< [in][optional] A list of sync points that this command depends on.
+    ur_exp_command_buffer_sync_point_t *pSyncPoint                ///< [out][optional] sync point associated with this command.
+);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Submit a command-buffer for execution on a queue.
 ///
@@ -10332,6 +10416,34 @@ typedef struct ur_command_buffer_append_mem_buffer_fill_exp_params_t {
     ur_exp_command_buffer_sync_point_t **ppSyncPoint;
 } ur_command_buffer_append_mem_buffer_fill_exp_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urCommandBufferAppendUSMPrefetchExp
+/// @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_append_usm_prefetch_exp_params_t {
+    ur_exp_command_buffer_handle_t *phCommandBuffer;
+    const void **ppMemory;
+    size_t *psize;
+    ur_usm_migration_flags_t *pflags;
+    uint32_t *pnumSyncPointsInWaitList;
+    const ur_exp_command_buffer_sync_point_t **ppSyncPointWaitList;
+    ur_exp_command_buffer_sync_point_t **ppSyncPoint;
+} ur_command_buffer_append_usm_prefetch_exp_params_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urCommandBufferAppendUSMAdviseExp
+/// @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_append_usm_advise_exp_params_t {
+    ur_exp_command_buffer_handle_t *phCommandBuffer;
+    const void **ppMemory;
+    size_t *psize;
+    ur_usm_advice_flags_t *padvice;
+    uint32_t *pnumSyncPointsInWaitList;
+    const ur_exp_command_buffer_sync_point_t **ppSyncPointWaitList;
+    ur_exp_command_buffer_sync_point_t **ppSyncPoint;
+} ur_command_buffer_append_usm_advise_exp_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urCommandBufferEnqueueExp
 /// @details Each entry is a pointer to the parameter passed to the function;

include/ur_ddi.h

@@ -1923,6 +1923,28 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferFillExp_t)(
     const ur_exp_command_buffer_sync_point_t *,
     ur_exp_command_buffer_sync_point_t *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urCommandBufferAppendUSMPrefetchExp
+typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendUSMPrefetchExp_t)(
+    ur_exp_command_buffer_handle_t,
+    const void *,
+    size_t,
+    ur_usm_migration_flags_t,
+    uint32_t,
+    const ur_exp_command_buffer_sync_point_t *,
+    ur_exp_command_buffer_sync_point_t *);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urCommandBufferAppendUSMAdviseExp
+typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendUSMAdviseExp_t)(
+    ur_exp_command_buffer_handle_t,
+    const void *,
+    size_t,
+    ur_usm_advice_flags_t,
+    uint32_t,
+    const ur_exp_command_buffer_sync_point_t *,
+    ur_exp_command_buffer_sync_point_t *);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function-pointer for urCommandBufferEnqueueExp
 typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferEnqueueExp_t)(
@@ -1949,6 +1971,8 @@ typedef struct ur_command_buffer_exp_dditable_t {
     ur_pfnCommandBufferAppendMemBufferWriteRectExp_t pfnAppendMemBufferWriteRectExp;
     ur_pfnCommandBufferAppendMemBufferReadRectExp_t pfnAppendMemBufferReadRectExp;
     ur_pfnCommandBufferAppendMemBufferFillExp_t pfnAppendMemBufferFillExp;
+    ur_pfnCommandBufferAppendUSMPrefetchExp_t pfnAppendUSMPrefetchExp;
+    ur_pfnCommandBufferAppendUSMAdviseExp_t pfnAppendUSMAdviseExp;
     ur_pfnCommandBufferEnqueueExp_t pfnEnqueueExp;
 } ur_command_buffer_exp_dditable_t;
 

scripts/core/EXP-COMMAND-BUFFER.rst

@@ -101,6 +101,8 @@ Currently only the following commands are supported:
 * ${x}CommandBufferAppendMemBufferWriteExp
 * ${x}CommandBufferAppendMemBufferWriteRectExp
 * ${x}CommandBufferAppendMemBufferFillExp
+* ${x}CommandBufferAppendUSMPrefetchExp
+* ${x}CommandBufferAppendUSMAdviseExp
 
 It is planned to eventually support any command type from the Core API which can
 actually be appended to the equiavalent adapter native constructs.
@@ -178,6 +180,8 @@ Enums
     * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_WRITE_EXP
     * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_WRITE_RECT_EXP
     * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_FILL_EXP
+    * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP
+    * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_USM_ADVISE_EXP
 
 
 
@@ -204,6 +208,8 @@ Functions
 * ${x}CommandBufferAppendMemBufferWriteExp
 * ${x}CommandBufferAppendMemBufferWriteRectExp
 * ${x}CommandBufferAppendMemBufferFillExp
+* ${x}CommandBufferAppendUSMPrefetchExp
+* ${x}CommandBufferAppendUSMAdviseExp
 * ${x}CommandBufferEnqueueExp
 
 Changelog
@@ -218,6 +224,9 @@ Changelog
 +-----------+-------------------------------------------------------+
 | 1.2       | Add function definitions for fill commands            |
 +-----------+-------------------------------------------------------+
+| 1.3       | Add function definitions for Prefetch and Advise      |
+|           | commands                                              |
++-----------+-------------------------------------------------------+
 
 Contributors
 --------------------------------------------------------------------------------

scripts/core/exp-command-buffer.yml

@@ -588,6 +588,90 @@ returns:
     - $X_RESULT_ERROR_OUT_OF_RESOURCES
 --- #--------------------------------------------------------------------------
 type: function
+desc: "Append a USM Prefetch command to a command-buffer object"
+class: $xCommandBuffer
+name: AppendUSMPrefetchExp
+details:
+    - "Prefetching may not be supported for all devices or allocation types. If memory prefetching 
+    is not supported, the prefetch hint will be ignored."
+params:
+    - type: $x_exp_command_buffer_handle_t
+      name: hCommandBuffer
+      desc: "[in] handle of the command-buffer object."
+    - type: "const void*"
+      name: pMemory
+      desc: "[in] pointer to USM allocated memory to prefetch."
+    - type: "size_t"
+      name: size
+      desc: "[in] size in bytes to be fetched."
+    - type: $x_usm_migration_flags_t
+      name: flags
+      desc: "[in] USM prefetch flags"
+    - type: uint32_t
+      name: numSyncPointsInWaitList
+      desc: "[in] The number of sync points in the provided dependency list."
+    - type: "const $x_exp_command_buffer_sync_point_t*"
+      name: pSyncPointWaitList
+      desc: "[in][optional] A list of sync points that this command depends on."
+    - type: "$x_exp_command_buffer_sync_point_t*"
+      name: pSyncPoint
+      desc: "[out][optional] sync point associated with this command."
+returns:
+    - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
+    - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
+    - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP:
+        - "`pSyncPointWaitList == NULL && numSyncPointsInWaitList > 0`"
+        - "`pSyncPointWaitList != NULL && numSyncPointsInWaitList == 0`"
+    - $X_RESULT_ERROR_INVALID_MEM_OBJECT
+    - $X_RESULT_ERROR_INVALID_SIZE:
+        - "`size == 0`"
+        - "If `size` is higher than the allocation size of `pMemory`"
+    - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
+    - $X_RESULT_ERROR_OUT_OF_RESOURCES
+--- #--------------------------------------------------------------------------
+type: function
+desc: "Append a USM Advise command to a command-buffer object"
+class: $xCommandBuffer
+name: AppendUSMAdviseExp
+details:
+    - "Not all memory advice hints may be supported for all devices or allocation types. 
+    If a memory advice hint is not supported, it will be ignored."
+params:
+    - type: $x_exp_command_buffer_handle_t
+      name: hCommandBuffer
+      desc: "[in] handle of the command-buffer object."
+    - type: "const void*"
+      name: pMemory
+      desc: "[in] pointer to the USM memory object."
+    - type: "size_t"
+      name: size
+      desc: "[in] size in bytes to be advised."
+    - type: $x_usm_advice_flags_t
+      name: advice
+      desc: "[in] USM memory advice"
+    - type: uint32_t
+      name: numSyncPointsInWaitList
+      desc: "[in] The number of sync points in the provided dependency list."
+    - type: "const $x_exp_command_buffer_sync_point_t*"
+      name: pSyncPointWaitList
+      desc: "[in][optional] A list of sync points that this command depends on."
+    - type: "$x_exp_command_buffer_sync_point_t*"
+      name: pSyncPoint
+      desc: "[out][optional] sync point associated with this command."
+returns:
+    - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
+    - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
+    - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP:
+        - "`pSyncPointWaitList == NULL && numSyncPointsInWaitList > 0`"
+        - "`pSyncPointWaitList != NULL && numSyncPointsInWaitList == 0`"
+    - $X_RESULT_ERROR_INVALID_MEM_OBJECT
+    - $X_RESULT_ERROR_INVALID_SIZE:
+        - "`size == 0`"
+        - "If `size` is higher than the allocation size of `pMemory`"
+    - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY
+    - $X_RESULT_ERROR_OUT_OF_RESOURCES
+--- #--------------------------------------------------------------------------
+type: function
 desc: "Submit a command-buffer for execution on a queue."
 class: $xCommandBuffer
 name: EnqueueExp

scripts/core/registry.yml

@@ -541,6 +541,12 @@ etors:
 - name: KERNEL_SUGGEST_MAX_COOPERATIVE_GROUP_COUNT_EXP
   desc: Enumerator for $xKernelSuggestMaxCooperativeGroupCountExp
   value: '194'
+- name: COMMAND_BUFFER_APPEND_USM_PREFETCH_EXP
+  desc: Enumerator for $xCommandBufferAppendUSMPrefetchExp
+  value: '195'
+- name: COMMAND_BUFFER_APPEND_USM_ADVISE_EXP
+  desc: Enumerator for $xCommandBufferAppendUSMAdviseExp
+  value: '196'
 ---
 type: enum
 desc: Defines structure types