[CMDBUF] Add fill commands to cmd buffer exp feature

- Adds USM and Buffer fill append commands - Update feature spec for new commands - Align naming conventions for Append* commands with core equivalents
oneapi-src · Aug 28, 2023 · 40a6846 · 40a6846
1 parent 2118102
commit 40a6846
Show file tree

Hide file tree

Showing 13 changed files with 1,493 additions and 523 deletions.
diff --git a/include/ur.py b/include/ur.py
diff --git a/include/ur_api.h b/include/ur_api.h
diff --git a/include/ur_ddi.h b/include/ur_ddi.h
@@ -1727,8 +1727,8 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendKernelLaunchExp_t)(
  ur_exp_command_buffer_sync_point_t *);
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Function-pointer for urCommandBufferAppendMemcpyUSMExp
-typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemcpyUSMExp_t)(
+/// @brief Function-pointer for urCommandBufferAppendUSMMemcpyExp
+typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendUSMMemcpyExp_t)(
  ur_exp_command_buffer_handle_t,
  void *,
  const void *,
@@ -1738,8 +1738,20 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemcpyUSMExp_t)(
  ur_exp_command_buffer_sync_point_t *);
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Function-pointer for urCommandBufferAppendMembufferCopyExp
-typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMembufferCopyExp_t)(
+/// @brief Function-pointer for urCommandBufferAppendUSMFillExp
+typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendUSMFillExp_t)(
+ ur_exp_command_buffer_handle_t,
+ void *,
+ const void *,
+ size_t,
+ size_t,
+ uint32_t,
+ const ur_exp_command_buffer_sync_point_t *,
+ ur_exp_command_buffer_sync_point_t *);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urCommandBufferAppendMemBufferCopyExp
+typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferCopyExp_t)(
  ur_exp_command_buffer_handle_t,
  ur_mem_handle_t,
  ur_mem_handle_t,
@@ -1751,8 +1763,8 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMembufferCopyExp_t)(
  ur_exp_command_buffer_sync_point_t *);
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Function-pointer for urCommandBufferAppendMembufferWriteExp
-typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMembufferWriteExp_t)(
+/// @brief Function-pointer for urCommandBufferAppendMemBufferWriteExp
+typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferWriteExp_t)(
  ur_exp_command_buffer_handle_t,
  ur_mem_handle_t,
  size_t,
@@ -1763,8 +1775,8 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMembufferWriteExp_t)(
  ur_exp_command_buffer_sync_point_t *);
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Function-pointer for urCommandBufferAppendMembufferReadExp
-typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMembufferReadExp_t)(
+/// @brief Function-pointer for urCommandBufferAppendMemBufferReadExp
+typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferReadExp_t)(
  ur_exp_command_buffer_handle_t,
  ur_mem_handle_t,
  size_t,
@@ -1775,8 +1787,8 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMembufferReadExp_t)(
  ur_exp_command_buffer_sync_point_t *);
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Function-pointer for urCommandBufferAppendMembufferCopyRectExp
-typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMembufferCopyRectExp_t)(
+/// @brief Function-pointer for urCommandBufferAppendMemBufferCopyRectExp
+typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferCopyRectExp_t)(
  ur_exp_command_buffer_handle_t,
  ur_mem_handle_t,
  ur_mem_handle_t,
@@ -1792,8 +1804,8 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMembufferCopyRectExp_t)
  ur_exp_command_buffer_sync_point_t *);
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Function-pointer for urCommandBufferAppendMembufferWriteRectExp
-typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMembufferWriteRectExp_t)(
+/// @brief Function-pointer for urCommandBufferAppendMemBufferWriteRectExp
+typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferWriteRectExp_t)(
  ur_exp_command_buffer_handle_t,
  ur_mem_handle_t,
  ur_rect_offset_t,
@@ -1809,8 +1821,8 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMembufferWriteRectExp_t
  ur_exp_command_buffer_sync_point_t *);
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Function-pointer for urCommandBufferAppendMembufferReadRectExp
-typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMembufferReadRectExp_t)(
+/// @brief Function-pointer for urCommandBufferAppendMemBufferReadRectExp
+typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferReadRectExp_t)(
  ur_exp_command_buffer_handle_t,
  ur_mem_handle_t,
  ur_rect_offset_t,
@@ -1825,6 +1837,19 @@ typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMembufferReadRectExp_t)
  const ur_exp_command_buffer_sync_point_t *,
  ur_exp_command_buffer_sync_point_t *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urCommandBufferAppendMemBufferFillExp
+typedef ur_result_t(UR_APICALL *ur_pfnCommandBufferAppendMemBufferFillExp_t)(
+ ur_exp_command_buffer_handle_t,
+ ur_mem_handle_t,
+ const void *,
+ size_t,
+ size_t,
+ size_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)(
@@ -1842,13 +1867,15 @@ typedef struct ur_command_buffer_exp_dditable_t {
  ur_pfnCommandBufferReleaseExp_t pfnReleaseExp;
  ur_pfnCommandBufferFinalizeExp_t pfnFinalizeExp;
  ur_pfnCommandBufferAppendKernelLaunchExp_t pfnAppendKernelLaunchExp;
- ur_pfnCommandBufferAppendMemcpyUSMExp_t pfnAppendMemcpyUSMExp;
- ur_pfnCommandBufferAppendMembufferCopyExp_t pfnAppendMembufferCopyExp;
- ur_pfnCommandBufferAppendMembufferWriteExp_t pfnAppendMembufferWriteExp;
- ur_pfnCommandBufferAppendMembufferReadExp_t pfnAppendMembufferReadExp;
- ur_pfnCommandBufferAppendMembufferCopyRectExp_t pfnAppendMembufferCopyRectExp;
- ur_pfnCommandBufferAppendMembufferWriteRectExp_t pfnAppendMembufferWriteRectExp;
- ur_pfnCommandBufferAppendMembufferReadRectExp_t pfnAppendMembufferReadRectExp;
+ ur_pfnCommandBufferAppendUSMMemcpyExp_t pfnAppendUSMMemcpyExp;
+ ur_pfnCommandBufferAppendUSMFillExp_t pfnAppendUSMFillExp;
+ ur_pfnCommandBufferAppendMemBufferCopyExp_t pfnAppendMemBufferCopyExp;
+ ur_pfnCommandBufferAppendMemBufferWriteExp_t pfnAppendMemBufferWriteExp;
+ ur_pfnCommandBufferAppendMemBufferReadExp_t pfnAppendMemBufferReadExp;
+ ur_pfnCommandBufferAppendMemBufferCopyRectExp_t pfnAppendMemBufferCopyRectExp;
+ ur_pfnCommandBufferAppendMemBufferWriteRectExp_t pfnAppendMemBufferWriteRectExp;
+ ur_pfnCommandBufferAppendMemBufferReadRectExp_t pfnAppendMemBufferReadRectExp;
+ ur_pfnCommandBufferAppendMemBufferFillExp_t pfnAppendMemBufferFillExp;
  ur_pfnCommandBufferEnqueueExp_t pfnEnqueueExp;
 } ur_command_buffer_exp_dditable_t;
 

diff --git a/scripts/core/EXP-COMMAND-BUFFER.rst b/scripts/core/EXP-COMMAND-BUFFER.rst
@@ -92,13 +92,15 @@ of event handles.
 Currently only the following commands are supported:
 
 * ${x}CommandBufferAppendKernelLaunchExp
-* ${x}CommandBufferAppendMemcpyUSMExp
-* ${x}CommandBufferAppendMembufferCopyExp
-* ${x}CommandBufferAppendMembufferCopyRectExp
-* ${x}CommandBufferAppendMembufferReadExp
-* ${x}CommandBufferAppendMembufferReadRectExp
-* ${x}CommandBufferAppendMembufferWriteExp
-* ${x}CommandBufferAppendMembufferWriteRectExp
+* ${x}CommandBufferAppendUSMMemcpyExp
+* ${x}CommandBufferAppendUSMFillExp
+* ${x}CommandBufferAppendMemBufferCopyExp
+* ${x}CommandBufferAppendMemBufferCopyRectExp
+* ${x}CommandBufferAppendMemBufferReadExp
+* ${x}CommandBufferAppendMemBufferReadRectExp
+* ${x}CommandBufferAppendMemBufferWriteExp
+* ${x}CommandBufferAppendMemBufferWriteRectExp
+* ${x}CommandBufferAppendMemBufferFillExp
 
 It is planned to eventually support any command type from the Core API which can
 actually be appended to the equiavalent adapter native constructs.
@@ -118,7 +120,7 @@ were obtained from.
  // Append a memcpy with no sync-point dependencies
  ${x}_exp_command_buffer_sync_point_t syncPoint;
 
- ${x}CommandBufferAppendMemcpyUSMExp(hCommandBuffer, pDst, pSrc, size, 0, 
+ ${x}CommandBufferAppendUSMMemcpyExp(hCommandBuffer, pDst, pSrc, size, 0, 
  nullptr, &syncPoint);
  
  // Append a kernel launch with syncPoint as a dependency, ignore returned
@@ -167,13 +169,15 @@ Enums
  * ${X}_FUNCTION_COMMAND_BUFFER_FINALIZE_EXP
  * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_KERNEL_LAUNCH_EXP
  * ${X}_FUNCTION_COMMAND_BUFFER_ENQUEUE_EXP
- * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEMCPY_USM_EXP
- * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEMBUFFER_COPY_EXP
- * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEMBUFFER_COPY_RECT_EXP
- * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEMBUFFER_READ_EXP
- * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEMBUFFER_READ_RECT_EXP
- * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEMBUFFER_WRITE_EXP
- * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEMBUFFER_WRITE_RECT_EXP
+ * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_USM_MEMCPY_EXP
+ * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_USM_FILL_EXP
+ * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_COPY_EXP
+ * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_COPY_RECT_EXP
+ * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_READ_EXP
+ * ${X}_FUNCTION_COMMAND_BUFFER_APPEND_MEM_BUFFER_READ_RECT_EXP
+ * ${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
 
 
 
@@ -191,13 +195,15 @@ Functions
 * ${x}CommandBufferReleaseExp
 * ${x}CommandBufferFinalizeExp
 * ${x}CommandBufferAppendKernelLaunchExp
-* ${x}CommandBufferAppendMemcpyUSMExp
-* ${x}CommandBufferAppendMembufferCopyExp
-* ${x}CommandBufferAppendMembufferCopyRectExp
-* ${x}CommandBufferAppendMembufferReadExp
-* ${x}CommandBufferAppendMembufferReadRectExp
-* ${x}CommandBufferAppendMembufferWriteExp
-* ${x}CommandBufferAppendMembufferWriteRectExp
+* ${x}CommandBufferAppendUSMMemcpyExp
+* ${x}CommandBufferAppendUSMFillExp
+* ${x}CommandBufferAppendMemBufferCopyExp
+* ${x}CommandBufferAppendMemBufferCopyRectExp
+* ${x}CommandBufferAppendMemBufferReadExp
+* ${x}CommandBufferAppendMemBufferReadRectExp
+* ${x}CommandBufferAppendMemBufferWriteExp
+* ${x}CommandBufferAppendMemBufferWriteRectExp
+* ${x}CommandBufferAppendMemBufferFillExp
 * ${x}CommandBufferEnqueueExp
 
 Changelog
@@ -208,7 +214,9 @@ Changelog
 +===========+=======================================================+
 | 1.0 | Initial Draft |
 +-----------+-------------------------------------------------------+
-| 1.1 | add function definitions for buffer read and write |
+| 1.1 | Add function definitions for buffer read and write |
++-----------+-------------------------------------------------------+
+| 1.2 | Add function definitions for fill commands |
 +-----------+-------------------------------------------------------+
 
 Contributors

diff --git a/scripts/core/exp-command-buffer.yml b/scripts/core/exp-command-buffer.yml
@@ -180,7 +180,7 @@ returns:
 type: function
 desc: "Append a USM memcpy command to a command-buffer object"
 class: $xCommandBuffer
-name: AppendMemcpyUSMExp
+name: AppendUSMMemcpyExp
 params:
  - type: $x_exp_command_buffer_handle_t
  name: hCommandBuffer
@@ -217,9 +217,54 @@ returns:
  - $X_RESULT_ERROR_OUT_OF_RESOURCES
 --- #--------------------------------------------------------------------------
 type: function
+desc: "Append a USM fill command to a command-buffer object"
+class: $xCommandBuffer
+name: AppendUSMFillExp
+params:
+ - type: $x_exp_command_buffer_handle_t
+ name: hCommandBuffer
+ desc: "[in] handle of the command-buffer object."
+ - type: "void*"
+ name: pMemory
+ desc: "[in] pointer to USM allocated memory to fill."
+ - type: "const void*"
+ name: pPattern
+ desc: "[in] pointer to the fill pattern."
+ - type: "size_t"
+ name: patternSize
+ desc: "[in] size in bytes of the pattern."
+ - type: "size_t"
+ name: size
+ desc: "[in] fill size in bytes, must be a multiple of patternSize."
+ - 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_SIZE:
+ - "`patternSize == 0 || size == 0`"
+ - "`patternSize > size`"
+ - "`(patternSize & (patternSize - 1)) != 0`"
+ - "`size % patternSize != 0`"
+ - "If `size` is higher than the allocation size of `ptr`"
+ - $X_RESULT_ERROR_INVALID_MEM_OBJECT
+ - $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_OUT_OF_HOST_MEMORY
+ - $X_RESULT_ERROR_OUT_OF_RESOURCES
+--- #--------------------------------------------------------------------------
+type: function
 desc: "Append a memory copy command to a command-buffer object"
 class: $xCommandBuffer
-name: AppendMembufferCopyExp
+name: AppendMemBufferCopyExp
 params:
  - type: $x_exp_command_buffer_handle_t
  name: hCommandBuffer
@@ -261,7 +306,7 @@ returns:
 type: function
 desc: "Append a memory write command to a command-buffer object"
 class: $xCommandBuffer
-name: AppendMembufferWriteExp
+name: AppendMemBufferWriteExp
 params:
  - type: $x_exp_command_buffer_handle_t
  name: hCommandBuffer
@@ -300,7 +345,7 @@ returns:
 type: function
 desc: "Append a memory read command to a command-buffer object"
 class: $xCommandBuffer
-name: AppendMembufferReadExp
+name: AppendMemBufferReadExp
 params:
  - type: $x_exp_command_buffer_handle_t
  name: hCommandBuffer
@@ -339,7 +384,7 @@ returns:
 type: function
 desc: "Append a rectangular memory copy command to a command-buffer object"
 class: $xCommandBuffer
-name: AppendMembufferCopyRectExp
+name: AppendMemBufferCopyRectExp
 params:
  - type: $x_exp_command_buffer_handle_t
  name: hCommandBuffer
@@ -393,7 +438,7 @@ returns:
 type: function
 desc: "Append a rectangular memory write command to a command-buffer object"
 class: $xCommandBuffer
-name: AppendMembufferWriteRectExp
+name: AppendMemBufferWriteRectExp
 params:
  - type: $x_exp_command_buffer_handle_t
  name: hCommandBuffer
@@ -447,7 +492,7 @@ returns:
 type: function
 desc: "Append a rectangular memory read command to a command-buffer object"
 class: $xCommandBuffer
-name: AppendMembufferReadRectExp
+name: AppendMemBufferReadRectExp
 params:
  - type: $x_exp_command_buffer_handle_t
  name: hCommandBuffer
@@ -499,6 +544,50 @@ returns:
  - $X_RESULT_ERROR_OUT_OF_RESOURCES
 --- #--------------------------------------------------------------------------
 type: function
+desc: "Append a memory fill command to a command-buffer object"
+class: $xCommandBuffer
+name: AppendMemBufferFillExp
+params:
+ - type: $x_exp_command_buffer_handle_t
+ name: hCommandBuffer
+ desc: "[in] handle of the command-buffer object."
+ - type: $x_mem_handle_t
+ name: hBuffer
+ desc: "[in] handle of the buffer object."
+ - type: "const void*"
+ name: pPattern
+ desc: "[in] pointer to the fill pattern."
+ - type: "size_t"
+ name: patternSize
+ desc: "[in] size in bytes of the pattern."
+ - type: "size_t"
+ name: offset
+ desc: "[in] offset into the buffer."
+ - type: "size_t"
+ name: size
+ desc: "[in] fill size in bytes, must be a multiple of patternSize."
+ - 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:
+ - "If `offset + size` results in an out-of-bounds access."
+ - $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