Merge branch 'main' into yc/new-api-suggestgroupsize

Author: yingcong-wu

.github/workflows/e2e_core.yml

@@ -138,7 +138,7 @@ jobs:
       # Remove after fixing SYCL test :: abi/layout_handler.cpp
       # This issue does not affect further execution of e2e with UR.
       continue-on-error: true
-      run: cmake --build ${{github.workspace}}/sycl_build --target check-sycl
+      run: cmake --build ${{github.workspace}}/sycl_build --target check-sycl -j6
 
     - name: Set additional env. vars
       run: |

README.md

@@ -2,6 +2,7 @@
 
 [![Build and test](https://github.com/oneapi-src/unified-runtime/actions/workflows/cmake.yml/badge.svg)](https://github.com/oneapi-src/unified-runtime/actions/workflows/cmake.yml)
 [![E2E Cuda](https://github.com/oneapi-src/unified-runtime/actions/workflows/e2e_cuda.yml/badge.svg)](https://github.com/oneapi-src/unified-runtime/actions/workflows/e2e_cuda.yml)
+[![E2E OpenCL](https://github.com/oneapi-src/unified-runtime/actions/workflows/e2e_opencl.yml/badge.svg)](https://github.com/oneapi-src/unified-runtime/actions/workflows/e2e_opencl.yml)
 [![CodeQL](https://github.com/oneapi-src/unified-runtime/actions/workflows/codeql.yml/badge.svg)](https://github.com/oneapi-src/unified-runtime/actions/workflows/codeql.yml)
 [![Bandit](https://github.com/oneapi-src/unified-runtime/actions/workflows/bandit.yml/badge.svg)](https://github.com/oneapi-src/unified-runtime/actions/workflows/bandit.yml)
 [![Coverity](https://scan.coverity.com/projects/28213/badge.svg)](https://scan.coverity.com/projects/oneapi-src-unified-runtime)

include/ur_api.h

@@ -3449,7 +3449,7 @@ urUSMHostAlloc(
     ur_context_handle_t hContext,  ///< [in] handle of the context object
     const ur_usm_desc_t *pUSMDesc, ///< [in][optional] USM memory allocation descriptor
     ur_usm_pool_handle_t pool,     ///< [in][optional] Pointer to a pool created using urUSMPoolCreate
-    size_t size,                   ///< [in] size in bytes of the USM memory object to be allocated
+    size_t size,                   ///< [in] minimum size in bytes of the USM memory object to be allocated
     void **ppMem                   ///< [out] pointer to USM host memory object
 );
 
@@ -3497,7 +3497,7 @@ urUSMDeviceAlloc(
     ur_device_handle_t hDevice,    ///< [in] handle of the device object
     const ur_usm_desc_t *pUSMDesc, ///< [in][optional] USM memory allocation descriptor
     ur_usm_pool_handle_t pool,     ///< [in][optional] Pointer to a pool created using urUSMPoolCreate
-    size_t size,                   ///< [in] size in bytes of the USM memory object to be allocated
+    size_t size,                   ///< [in] minimum size in bytes of the USM memory object to be allocated
     void **ppMem                   ///< [out] pointer to USM device memory object
 );
 
@@ -3546,7 +3546,7 @@ urUSMSharedAlloc(
     ur_device_handle_t hDevice,    ///< [in] handle of the device object
     const ur_usm_desc_t *pUSMDesc, ///< [in][optional] Pointer to USM memory allocation descriptor.
     ur_usm_pool_handle_t pool,     ///< [in][optional] Pointer to a pool created using urUSMPoolCreate
-    size_t size,                   ///< [in] size in bytes of the USM memory object to be allocated
+    size_t size,                   ///< [in] minimum size in bytes of the USM memory object to be allocated
     void **ppMem                   ///< [out] pointer to USM shared memory object
 );
 
@@ -4077,6 +4077,8 @@ typedef struct ur_program_properties_t {
 ///
 /// @details
 ///     - The application may call this function from simultaneous threads.
+///     - The adapter may (but is not required to) perform validation of the
+///       provided module during this call.
 ///
 /// @remarks
 ///   _Analogues_
@@ -4117,6 +4119,10 @@ urProgramCreateWithIL(
 ///     - Following a successful call to this entry point, `phProgram` will
 ///       contain a binary of type ::UR_PROGRAM_BINARY_TYPE_COMPILED_OBJECT or
 ///       ::UR_PROGRAM_BINARY_TYPE_LIBRARY for `hDevice`.
+///     - The device specified by `hDevice` must be device associated with
+///       context.
+///     - The adapter may (but is not required to) perform validation of the
+///       provided module during this call.
 ///
 /// @remarks
 ///   _Analogues_
@@ -8017,6 +8023,9 @@ typedef struct ur_exp_command_buffer_desc_t {
                                ///< ::UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC
     const void *pNext;         ///< [in][optional] pointer to extension-specific structure
     ur_bool_t isUpdatable;     ///< [in] Commands in a finalized command-buffer can be updated.
+    ur_bool_t isInOrder;       ///< [in] Commands in a command-buffer may be executed in-order without
+                               ///< explicit dependencies.
+    ur_bool_t enableProfiling; ///< [in] Command-buffer profiling is enabled.
 
 } ur_exp_command_buffer_desc_t;
 
@@ -8221,7 +8230,8 @@ urCommandBufferAppendKernelLaunchExp(
     const size_t *pGlobalWorkSize,                                ///< [in] Global work size to use when executing kernel.
     const size_t *pLocalWorkSize,                                 ///< [in][optional] Local work size to use when executing kernel.
     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.
+    const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ///< [in][optional] A list of sync points that this command depends on. May
+                                                                  ///< be ignored if command-buffer is in-order.
     ur_exp_command_buffer_sync_point_t *pSyncPoint,               ///< [out][optional] Sync point associated with this command.
     ur_exp_command_buffer_command_handle_t *phCommand             ///< [out][optional] Handle to this command.
 );
@@ -8257,7 +8267,8 @@ urCommandBufferAppendUSMMemcpyExp(
     const void *pSrc,                                             ///< [in] The data to be copied.
     size_t size,                                                  ///< [in] The number of bytes to copy.
     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.
+    const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ///< [in][optional] A list of sync points that this command depends on. May
+                                                                  ///< be ignored if command-buffer is in-order.
     ur_exp_command_buffer_sync_point_t *pSyncPoint                ///< [out][optional] Sync point associated with this command.
 );
 
@@ -8296,7 +8307,8 @@ urCommandBufferAppendUSMFillExp(
     size_t patternSize,                                           ///< [in] size in bytes of the pattern.
     size_t size,                                                  ///< [in] fill size in bytes, must be a multiple of patternSize.
     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.
+    const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ///< [in][optional] A list of sync points that this command depends on. May
+                                                                  ///< be ignored if command-buffer is in-order.
     ur_exp_command_buffer_sync_point_t *pSyncPoint                ///< [out][optional] sync point associated with this command.
 );
 
@@ -8329,7 +8341,8 @@ urCommandBufferAppendMemBufferCopyExp(
     size_t dstOffset,                                             ///< [in] Offset into the destination memory
     size_t size,                                                  ///< [in] The number of bytes to be copied.
     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.
+    const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ///< [in][optional] A list of sync points that this command depends on. May
+                                                                  ///< be ignored if command-buffer is in-order.
     ur_exp_command_buffer_sync_point_t *pSyncPoint                ///< [out][optional] Sync point associated with this command.
 );
 
@@ -8362,7 +8375,8 @@ urCommandBufferAppendMemBufferWriteExp(
     size_t size,                                                  ///< [in] Size in bytes of data being written.
     const void *pSrc,                                             ///< [in] Pointer to host memory where data is to be written from.
     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.
+    const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ///< [in][optional] A list of sync points that this command depends on. May
+                                                                  ///< be ignored if command-buffer is in-order.
     ur_exp_command_buffer_sync_point_t *pSyncPoint                ///< [out][optional] Sync point associated with this command.
 );
 
@@ -8395,7 +8409,8 @@ urCommandBufferAppendMemBufferReadExp(
     size_t size,                                                  ///< [in] Size in bytes of data being written.
     void *pDst,                                                   ///< [in] Pointer to host memory where data is to be written to.
     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.
+    const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ///< [in][optional] A list of sync points that this command depends on. May
+                                                                  ///< be ignored if command-buffer is in-order.
     ur_exp_command_buffer_sync_point_t *pSyncPoint                ///< [out][optional] Sync point associated with this command.
 );
 
@@ -8432,7 +8447,8 @@ urCommandBufferAppendMemBufferCopyRectExp(
     size_t dstRowPitch,                                           ///< [in] Row pitch of the destination memory.
     size_t dstSlicePitch,                                         ///< [in] Slice pitch of the destination memory.
     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.
+    const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ///< [in][optional] A list of sync points that this command depends on. May
+                                                                  ///< be ignored if command-buffer is in-order.
     ur_exp_command_buffer_sync_point_t *pSyncPoint                ///< [out][optional] Sync point associated with this command.
 );
 
@@ -8473,7 +8489,8 @@ urCommandBufferAppendMemBufferWriteRectExp(
                                                                   ///< pointed to by pSrc.
     void *pSrc,                                                   ///< [in] Pointer to host memory where data is to be written from.
     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.
+    const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ///< [in][optional] A list of sync points that this command depends on. May
+                                                                  ///< be ignored if command-buffer is in-order.
     ur_exp_command_buffer_sync_point_t *pSyncPoint                ///< [out][optional] Sync point associated with this command.
 );
 
@@ -8513,7 +8530,8 @@ urCommandBufferAppendMemBufferReadRectExp(
                                                                   ///< pointed to by pDst.
     void *pDst,                                                   ///< [in] Pointer to host memory where data is to be read into.
     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.
+    const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ///< [in][optional] A list of sync points that this command depends on. May
+                                                                  ///< be ignored if command-buffer is in-order.
     ur_exp_command_buffer_sync_point_t *pSyncPoint                ///< [out][optional] Sync point associated with this command.
 );
 
@@ -8549,7 +8567,8 @@ urCommandBufferAppendMemBufferFillExp(
     size_t offset,                                                ///< [in] offset into the buffer.
     size_t size,                                                  ///< [in] fill size in bytes, must be a multiple of patternSize.
     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.
+    const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ///< [in][optional] A list of sync points that this command depends on. May
+                                                                  ///< be ignored if command-buffer is in-order.
     ur_exp_command_buffer_sync_point_t *pSyncPoint                ///< [out][optional] sync point associated with this command.
 );
 
@@ -8590,7 +8609,8 @@ urCommandBufferAppendUSMPrefetchExp(
     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.
+    const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ///< [in][optional] A list of sync points that this command depends on. May
+                                                                  ///< be ignored if command-buffer is in-order.
     ur_exp_command_buffer_sync_point_t *pSyncPoint                ///< [out][optional] sync point associated with this command.
 );
 
@@ -8631,7 +8651,8 @@ urCommandBufferAppendUSMAdviseExp(
     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.
+    const ur_exp_command_buffer_sync_point_t *pSyncPointWaitList, ///< [in][optional] A list of sync points that this command depends on. May
+                                                                  ///< be ignored if command-buffer is in-order.
     ur_exp_command_buffer_sync_point_t *pSyncPoint                ///< [out][optional] sync point associated with this command.
 );
 

include/ur_print.hpp

@@ -9499,6 +9499,16 @@ inline std::ostream &operator<<(std::ostream &os, const struct ur_exp_command_bu
 
     os << (params.isUpdatable);
 
+    os << ", ";
+    os << ".isInOrder = ";
+
+    os << (params.isInOrder);
+
+    os << ", ";
+    os << ".enableProfiling = ";
+
+    os << (params.enableProfiling);
+
     os << "}";
     return os;
 }

scripts/core/EXP-COMMAND-BUFFER.rst

@@ -77,9 +77,13 @@ Command-Buffer Creation
 Command-Buffers are tied to a specific ${x}_context_handle_t and
 ${x}_device_handle_t. ${x}CommandBufferCreateExp optionally takes a descriptor
 to provide additional properties for how the command-buffer should be
-constructed. The only unique member defined in ${x}_exp_command_buffer_desc_t
-is ``isUpdatable``, which should be set to ``true`` to support :ref:`updating
+constructed. The members defined in ${x}_exp_command_buffer_desc_t are:
+* ``isUpdatable``, which should be set to ``true`` to support :ref:`updating
 command-buffer commands`.
+* ``isInOrder``, which should be set to ``true`` to enable commands enqueued to
+a command-buffer to be executed in an in-order fashion where possible.
+* ``enableProfiling``, which should be set to ``true`` to enable profiling of
+the command-buffer.
 
 Command-buffers are reference counted and can be retained and released by
 calling ${x}CommandBufferRetainExp and ${x}CommandBufferReleaseExp respectively.
@@ -123,7 +127,8 @@ Sync-Points
 A sync-point is a value which represents a command inside of a command-buffer
 which is returned from command-buffer append function calls. These can be
 optionally passed to these functions to define execution dependencies on other
-commands within the command-buffer.
+commands within the command-buffer. Sync-points passed to functions may be
+ignored if the command-buffer was created in-order.
 
 Sync-points are unique and valid for use only within the command-buffer they
 were obtained from.