Skip to content

Commit ae677c7

Browse files
author
Hugh Delaney
committed
Add initial spec for async alloc entry points
First basic work in progress spec.
1 parent e3eeb4e commit ae677c7

23 files changed

+2468
-4
lines changed

include/ur_api.h

Lines changed: 218 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -230,6 +230,10 @@ typedef enum ur_function_t {
230230
UR_FUNCTION_COMMAND_BUFFER_UPDATE_SIGNAL_EVENT_EXP = 243, ///< Enumerator for ::urCommandBufferUpdateSignalEventExp
231231
UR_FUNCTION_COMMAND_BUFFER_UPDATE_WAIT_EVENTS_EXP = 244, ///< Enumerator for ::urCommandBufferUpdateWaitEventsExp
232232
UR_FUNCTION_BINDLESS_IMAGES_MAP_EXTERNAL_LINEAR_MEMORY_EXP = 245, ///< Enumerator for ::urBindlessImagesMapExternalLinearMemoryExp
233+
UR_FUNCTION_ENQUEUE_USM_DEVICE_ALLOC_EXP = 246, ///< Enumerator for ::urEnqueueUSMDeviceAllocExp
234+
UR_FUNCTION_ENQUEUE_USM_SHARED_ALLOC_EXP = 247, ///< Enumerator for ::urEnqueueUSMSharedAllocExp
235+
UR_FUNCTION_ENQUEUE_USM_HOST_ALLOC_EXP = 248, ///< Enumerator for ::urEnqueueUSMHostAllocExp
236+
UR_FUNCTION_ENQUEUE_USM_FREE_EXP = 249, ///< Enumerator for ::urEnqueueUSMFreeExp
233237
/// @cond
234238
UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
235239
/// @endcond
@@ -288,6 +292,7 @@ typedef enum ur_structure_type_t {
288292
UR_STRUCTURE_TYPE_EXP_SAMPLER_CUBEMAP_PROPERTIES = 0x2006, ///< ::ur_exp_sampler_cubemap_properties_t
289293
UR_STRUCTURE_TYPE_EXP_IMAGE_COPY_REGION = 0x2007, ///< ::ur_exp_image_copy_region_t
290294
UR_STRUCTURE_TYPE_EXP_ENQUEUE_NATIVE_COMMAND_PROPERTIES = 0x3000, ///< ::ur_exp_enqueue_native_command_properties_t
295+
UR_STRUCTURE_TYPE_EXP_ENQUEUE_USM_ALLOC_PROPERTIES = 0x3001, ///< ::ur_exp_async_usm_alloc_properties_t
291296
/// @cond
292297
UR_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff
293298
/// @endcond
@@ -1697,6 +1702,8 @@ typedef enum ur_device_info_t {
16971702
///< backed 2D sampled image data.
16981703
UR_DEVICE_INFO_ENQUEUE_NATIVE_COMMAND_SUPPORT_EXP = 0x2020, ///< [::ur_bool_t] returns true if the device supports enqueueing of native
16991704
///< work
1705+
UR_DEVICE_INFO_ASYNC_USM_ALLOCATIONS_EXP = 0x2021, ///< [::ur_bool_t] returns true if the device supports enqueueing of native
1706+
///< work
17001707
/// @cond
17011708
UR_DEVICE_INFO_FORCE_UINT32 = 0x7fffffff
17021709
/// @endcond
@@ -1722,7 +1729,7 @@ typedef enum ur_device_info_t {
17221729
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
17231730
/// + `NULL == hDevice`
17241731
/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
1725-
/// + `::UR_DEVICE_INFO_ENQUEUE_NATIVE_COMMAND_SUPPORT_EXP < propName`
1732+
/// + `::UR_DEVICE_INFO_ASYNC_USM_ALLOCATIONS_EXP < propName`
17261733
/// - ::UR_RESULT_ERROR_UNSUPPORTED_ENUMERATION
17271734
/// + If `propName` is not supported by the adapter.
17281735
/// - ::UR_RESULT_ERROR_INVALID_SIZE
@@ -5768,6 +5775,10 @@ typedef enum ur_command_t {
57685775
UR_COMMAND_EXTERNAL_SEMAPHORE_SIGNAL_EXP = 0x2001, ///< Event created by ::urBindlessImagesSignalExternalSemaphoreExp
57695776
UR_COMMAND_TIMESTAMP_RECORDING_EXP = 0x2002, ///< Event created by ::urEnqueueTimestampRecordingExp
57705777
UR_COMMAND_ENQUEUE_NATIVE_EXP = 0x2004, ///< Event created by ::urEnqueueNativeCommandExp
5778+
UR_COMMAND_ENQUEUE_USM_DEVICE_ALLOC_EXP = 0x2008, ///< Event created by ::urEnqueueDeviceAllocExp
5779+
UR_COMMAND_ENQUEUE_USM_SHARED_ALLOC_EXP = 0x2010, ///< Event created by ::urEnqueueSharedAllocExp
5780+
UR_COMMAND_ENQUEUE_USM_HOST_ALLOC_EXP = 0x2011, ///< Event created by ::urEnqueueHostAllocExp
5781+
UR_COMMAND_ENQUEUE_USM_FREE_EXP = 0x2012, ///< Event created by ::urEnqueueFreeExp
57715782
/// @cond
57725783
UR_COMMAND_FORCE_UINT32 = 0x7fffffff
57735784
/// @endcond
@@ -7395,6 +7406,154 @@ urEnqueueWriteHostPipe(
73957406
///< an element of the phEventWaitList array.
73967407
);
73977408

7409+
#if !defined(__GNUC__)
7410+
#pragma endregion
7411+
#endif
7412+
// Intel 'oneAPI' Unified Runtime Experimental API for asynchronous allocations
7413+
#if !defined(__GNUC__)
7414+
#pragma region async_alloc_(experimental)
7415+
#endif
7416+
///////////////////////////////////////////////////////////////////////////////
7417+
/// @brief Async alloc properties
7418+
typedef uint32_t ur_exp_async_usm_alloc_flags_t;
7419+
typedef enum ur_exp_async_usm_alloc_flag_t {
7420+
UR_EXP_ASYNC_USM_ALLOC_FLAG_TBD = UR_BIT(0), ///< reserved for future use.
7421+
/// @cond
7422+
UR_EXP_ASYNC_USM_ALLOC_FLAG_FORCE_UINT32 = 0x7fffffff
7423+
/// @endcond
7424+
7425+
} ur_exp_async_usm_alloc_flag_t;
7426+
/// @brief Bit Mask for validating ur_exp_async_usm_alloc_flags_t
7427+
#define UR_EXP_ASYNC_USM_ALLOC_FLAGS_MASK 0xfffffffe
7428+
7429+
///////////////////////////////////////////////////////////////////////////////
7430+
/// @brief Async alloc properties
7431+
typedef struct ur_exp_async_usm_alloc_properties_t {
7432+
ur_structure_type_t stype; ///< [in] type of this structure, must be
7433+
///< ::UR_STRUCTURE_TYPE_EXP_ASYNC_USM_ALLOC_PROPERTIES
7434+
void *pNext; ///< [in,out][optional] pointer to extension-specific structure
7435+
ur_exp_async_usm_alloc_flags_t flags; ///< [in] async alloc flags
7436+
7437+
} ur_exp_async_usm_alloc_properties_t;
7438+
7439+
///////////////////////////////////////////////////////////////////////////////
7440+
/// @brief Enqueue an async device allocation
7441+
///
7442+
/// @returns
7443+
/// - ::UR_RESULT_SUCCESS
7444+
/// - ::UR_RESULT_ERROR_UNINITIALIZED
7445+
/// - ::UR_RESULT_ERROR_DEVICE_LOST
7446+
/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
7447+
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
7448+
/// + `NULL == hQueue`
7449+
/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
7450+
/// + `NULL != pProperties && ::UR_EXP_ASYNC_USM_ALLOC_FLAGS_MASK & pProperties->flags`
7451+
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
7452+
/// + `NULL == ppMem`
7453+
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
7454+
/// - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
7455+
UR_APIEXPORT ur_result_t UR_APICALL
7456+
urEnqueueUSMDeviceAllocExp(
7457+
ur_queue_handle_t hQueue, ///< [in] handle of the queue object
7458+
ur_usm_pool_handle_t pPool, ///< [in][optional] USM pool descriptor
7459+
const size_t size, ///< [in] minimum size in bytes of the USM memory object to be allocated
7460+
const ur_exp_async_usm_alloc_properties_t *pProperties, ///< [in][optional] pointer to the enqueue async alloc properties
7461+
uint32_t numEventsInWaitList, ///< [in] size of the event wait list
7462+
const ur_event_handle_t *phEventWaitList, ///< [in][optional][range(0, numEventsInWaitList)] pointer to a list of
7463+
///< events that must be complete before the kernel execution.
7464+
///< If nullptr, the numEventsInWaitList must be 0, indicating no wait events.
7465+
void **ppMem, ///< [out] pointer to USM memory object
7466+
ur_event_handle_t *phEvent ///< [out][optional] return an event object that identifies the async alloc
7467+
);
7468+
7469+
///////////////////////////////////////////////////////////////////////////////
7470+
/// @brief Enqueue an async shared allocation
7471+
///
7472+
/// @returns
7473+
/// - ::UR_RESULT_SUCCESS
7474+
/// - ::UR_RESULT_ERROR_UNINITIALIZED
7475+
/// - ::UR_RESULT_ERROR_DEVICE_LOST
7476+
/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
7477+
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
7478+
/// + `NULL == hQueue`
7479+
/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
7480+
/// + `NULL != pProperties && ::UR_EXP_ASYNC_USM_ALLOC_FLAGS_MASK & pProperties->flags`
7481+
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
7482+
/// + `NULL == ppMem`
7483+
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
7484+
/// - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
7485+
UR_APIEXPORT ur_result_t UR_APICALL
7486+
urEnqueueUSMSharedAllocExp(
7487+
ur_queue_handle_t hQueue, ///< [in] handle of the queue object
7488+
ur_usm_pool_handle_t pPool, ///< [in][optional] USM pool descriptor
7489+
const size_t size, ///< [in] minimum size in bytes of the USM memory object to be allocated
7490+
const ur_exp_async_usm_alloc_properties_t *pProperties, ///< [in][optional] pointer to the enqueue async alloc properties
7491+
uint32_t numEventsInWaitList, ///< [in] size of the event wait list
7492+
const ur_event_handle_t *phEventWaitList, ///< [in][optional][range(0, numEventsInWaitList)] pointer to a list of
7493+
///< events that must be complete before the kernel execution.
7494+
///< If nullptr, the numEventsInWaitList must be 0, indicating no wait events.
7495+
void **ppMem, ///< [out] pointer to USM memory object
7496+
ur_event_handle_t *phEvent ///< [out][optional] return an event object that identifies the async alloc
7497+
);
7498+
7499+
///////////////////////////////////////////////////////////////////////////////
7500+
/// @brief Enqueue an async host allocation
7501+
///
7502+
/// @returns
7503+
/// - ::UR_RESULT_SUCCESS
7504+
/// - ::UR_RESULT_ERROR_UNINITIALIZED
7505+
/// - ::UR_RESULT_ERROR_DEVICE_LOST
7506+
/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
7507+
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
7508+
/// + `NULL == hQueue`
7509+
/// - ::UR_RESULT_ERROR_INVALID_ENUMERATION
7510+
/// + `NULL != pProperties && ::UR_EXP_ASYNC_USM_ALLOC_FLAGS_MASK & pProperties->flags`
7511+
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
7512+
/// + `NULL == ppMem`
7513+
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
7514+
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
7515+
/// - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
7516+
UR_APIEXPORT ur_result_t UR_APICALL
7517+
urEnqueueUSMHostAllocExp(
7518+
ur_queue_handle_t hQueue, ///< [in] handle of the queue object
7519+
ur_usm_pool_handle_t pPool, ///< [in][optional] USM pool descriptor
7520+
const size_t size, ///< [in] minimum size in bytes of the USM memory object to be allocated
7521+
const ur_exp_async_usm_alloc_properties_t *pProperties, ///< [in][optional] pointer to the enqueue async alloc properties
7522+
uint32_t numEventsInWaitList, ///< [in] size of the event wait list
7523+
const ur_event_handle_t *phEventWaitList, ///< [in][optional][range(0, numEventsInWaitList)] pointer to a list of
7524+
///< events that must be complete before the kernel execution.
7525+
///< If nullptr, the numEventsInWaitList must be 0, indicating no wait events.
7526+
void **ppMem, ///< [out] pointer to USM memory object
7527+
ur_event_handle_t *phEvent ///< [out][optional] return an event object that identifies the async alloc
7528+
);
7529+
7530+
///////////////////////////////////////////////////////////////////////////////
7531+
/// @brief Enqueue an async host allocation
7532+
///
7533+
/// @returns
7534+
/// - ::UR_RESULT_SUCCESS
7535+
/// - ::UR_RESULT_ERROR_UNINITIALIZED
7536+
/// - ::UR_RESULT_ERROR_DEVICE_LOST
7537+
/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
7538+
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
7539+
/// + `NULL == hQueue`
7540+
/// - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
7541+
/// + `NULL == pMem`
7542+
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
7543+
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
7544+
/// - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
7545+
UR_APIEXPORT ur_result_t UR_APICALL
7546+
urEnqueueUSMFreeExp(
7547+
ur_queue_handle_t hQueue, ///< [in] handle of the queue object
7548+
ur_usm_pool_handle_t pPool, ///< [in][optional] USM pool descriptor
7549+
void *pMem, ///< [in] pointer to USM memory object
7550+
uint32_t numEventsInWaitList, ///< [in] size of the event wait list
7551+
const ur_event_handle_t *phEventWaitList, ///< [in][optional][range(0, numEventsInWaitList)] pointer to a list of
7552+
///< events that must be complete before the kernel execution.
7553+
///< If nullptr, the numEventsInWaitList must be 0, indicating no wait events.
7554+
ur_event_handle_t *phEvent ///< [out][optional] return an event object that identifies the async alloc
7555+
);
7556+
73987557
#if !defined(__GNUC__)
73997558
#pragma endregion
74007559
#endif
@@ -11423,6 +11582,64 @@ typedef struct ur_enqueue_kernel_launch_custom_exp_params_t {
1142311582
ur_event_handle_t **pphEvent;
1142411583
} ur_enqueue_kernel_launch_custom_exp_params_t;
1142511584

11585+
///////////////////////////////////////////////////////////////////////////////
11586+
/// @brief Function parameters for urEnqueueUSMDeviceAllocExp
11587+
/// @details Each entry is a pointer to the parameter passed to the function;
11588+
/// allowing the callback the ability to modify the parameter's value
11589+
typedef struct ur_enqueue_usm_device_alloc_exp_params_t {
11590+
ur_queue_handle_t *phQueue;
11591+
ur_usm_pool_handle_t *ppPool;
11592+
const size_t *psize;
11593+
const ur_exp_async_usm_alloc_properties_t **ppProperties;
11594+
uint32_t *pnumEventsInWaitList;
11595+
const ur_event_handle_t **pphEventWaitList;
11596+
void ***pppMem;
11597+
ur_event_handle_t **pphEvent;
11598+
} ur_enqueue_usm_device_alloc_exp_params_t;
11599+
11600+
///////////////////////////////////////////////////////////////////////////////
11601+
/// @brief Function parameters for urEnqueueUSMSharedAllocExp
11602+
/// @details Each entry is a pointer to the parameter passed to the function;
11603+
/// allowing the callback the ability to modify the parameter's value
11604+
typedef struct ur_enqueue_usm_shared_alloc_exp_params_t {
11605+
ur_queue_handle_t *phQueue;
11606+
ur_usm_pool_handle_t *ppPool;
11607+
const size_t *psize;
11608+
const ur_exp_async_usm_alloc_properties_t **ppProperties;
11609+
uint32_t *pnumEventsInWaitList;
11610+
const ur_event_handle_t **pphEventWaitList;
11611+
void ***pppMem;
11612+
ur_event_handle_t **pphEvent;
11613+
} ur_enqueue_usm_shared_alloc_exp_params_t;
11614+
11615+
///////////////////////////////////////////////////////////////////////////////
11616+
/// @brief Function parameters for urEnqueueUSMHostAllocExp
11617+
/// @details Each entry is a pointer to the parameter passed to the function;
11618+
/// allowing the callback the ability to modify the parameter's value
11619+
typedef struct ur_enqueue_usm_host_alloc_exp_params_t {
11620+
ur_queue_handle_t *phQueue;
11621+
ur_usm_pool_handle_t *ppPool;
11622+
const size_t *psize;
11623+
const ur_exp_async_usm_alloc_properties_t **ppProperties;
11624+
uint32_t *pnumEventsInWaitList;
11625+
const ur_event_handle_t **pphEventWaitList;
11626+
void ***pppMem;
11627+
ur_event_handle_t **pphEvent;
11628+
} ur_enqueue_usm_host_alloc_exp_params_t;
11629+
11630+
///////////////////////////////////////////////////////////////////////////////
11631+
/// @brief Function parameters for urEnqueueUSMFreeExp
11632+
/// @details Each entry is a pointer to the parameter passed to the function;
11633+
/// allowing the callback the ability to modify the parameter's value
11634+
typedef struct ur_enqueue_usm_free_exp_params_t {
11635+
ur_queue_handle_t *phQueue;
11636+
ur_usm_pool_handle_t *ppPool;
11637+
void **ppMem;
11638+
uint32_t *pnumEventsInWaitList;
11639+
const ur_event_handle_t **pphEventWaitList;
11640+
ur_event_handle_t **pphEvent;
11641+
} ur_enqueue_usm_free_exp_params_t;
11642+
1142611643
///////////////////////////////////////////////////////////////////////////////
1142711644
/// @brief Function parameters for urEnqueueCooperativeKernelLaunchExp
1142811645
/// @details Each entry is a pointer to the parameter passed to the function;

include/ur_api_funcs.def

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,10 @@ _UR_API(urEnqueueDeviceGlobalVariableRead)
127127
_UR_API(urEnqueueReadHostPipe)
128128
_UR_API(urEnqueueWriteHostPipe)
129129
_UR_API(urEnqueueKernelLaunchCustomExp)
130+
_UR_API(urEnqueueUSMDeviceAllocExp)
131+
_UR_API(urEnqueueUSMSharedAllocExp)
132+
_UR_API(urEnqueueUSMHostAllocExp)
133+
_UR_API(urEnqueueUSMFreeExp)
130134
_UR_API(urEnqueueCooperativeKernelLaunchExp)
131135
_UR_API(urEnqueueTimestampRecordingExp)
132136
_UR_API(urEnqueueNativeCommandExp)

include/ur_ddi.h

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1462,6 +1462,52 @@ typedef ur_result_t(UR_APICALL *ur_pfnEnqueueKernelLaunchCustomExp_t)(
14621462
const ur_event_handle_t *,
14631463
ur_event_handle_t *);
14641464

1465+
///////////////////////////////////////////////////////////////////////////////
1466+
/// @brief Function-pointer for urEnqueueUSMDeviceAllocExp
1467+
typedef ur_result_t(UR_APICALL *ur_pfnEnqueueUSMDeviceAllocExp_t)(
1468+
ur_queue_handle_t,
1469+
ur_usm_pool_handle_t,
1470+
const size_t,
1471+
const ur_exp_async_usm_alloc_properties_t *,
1472+
uint32_t,
1473+
const ur_event_handle_t *,
1474+
void **,
1475+
ur_event_handle_t *);
1476+
1477+
///////////////////////////////////////////////////////////////////////////////
1478+
/// @brief Function-pointer for urEnqueueUSMSharedAllocExp
1479+
typedef ur_result_t(UR_APICALL *ur_pfnEnqueueUSMSharedAllocExp_t)(
1480+
ur_queue_handle_t,
1481+
ur_usm_pool_handle_t,
1482+
const size_t,
1483+
const ur_exp_async_usm_alloc_properties_t *,
1484+
uint32_t,
1485+
const ur_event_handle_t *,
1486+
void **,
1487+
ur_event_handle_t *);
1488+
1489+
///////////////////////////////////////////////////////////////////////////////
1490+
/// @brief Function-pointer for urEnqueueUSMHostAllocExp
1491+
typedef ur_result_t(UR_APICALL *ur_pfnEnqueueUSMHostAllocExp_t)(
1492+
ur_queue_handle_t,
1493+
ur_usm_pool_handle_t,
1494+
const size_t,
1495+
const ur_exp_async_usm_alloc_properties_t *,
1496+
uint32_t,
1497+
const ur_event_handle_t *,
1498+
void **,
1499+
ur_event_handle_t *);
1500+
1501+
///////////////////////////////////////////////////////////////////////////////
1502+
/// @brief Function-pointer for urEnqueueUSMFreeExp
1503+
typedef ur_result_t(UR_APICALL *ur_pfnEnqueueUSMFreeExp_t)(
1504+
ur_queue_handle_t,
1505+
ur_usm_pool_handle_t,
1506+
void *,
1507+
uint32_t,
1508+
const ur_event_handle_t *,
1509+
ur_event_handle_t *);
1510+
14651511
///////////////////////////////////////////////////////////////////////////////
14661512
/// @brief Function-pointer for urEnqueueCooperativeKernelLaunchExp
14671513
typedef ur_result_t(UR_APICALL *ur_pfnEnqueueCooperativeKernelLaunchExp_t)(
@@ -1501,6 +1547,10 @@ typedef ur_result_t(UR_APICALL *ur_pfnEnqueueNativeCommandExp_t)(
15011547
/// @brief Table of EnqueueExp functions pointers
15021548
typedef struct ur_enqueue_exp_dditable_t {
15031549
ur_pfnEnqueueKernelLaunchCustomExp_t pfnKernelLaunchCustomExp;
1550+
ur_pfnEnqueueUSMDeviceAllocExp_t pfnUSMDeviceAllocExp;
1551+
ur_pfnEnqueueUSMSharedAllocExp_t pfnUSMSharedAllocExp;
1552+
ur_pfnEnqueueUSMHostAllocExp_t pfnUSMHostAllocExp;
1553+
ur_pfnEnqueueUSMFreeExp_t pfnUSMFreeExp;
15041554
ur_pfnEnqueueCooperativeKernelLaunchExp_t pfnCooperativeKernelLaunchExp;
15051555
ur_pfnEnqueueTimestampRecordingExp_t pfnTimestampRecordingExp;
15061556
ur_pfnEnqueueNativeCommandExp_t pfnNativeCommandExp;

0 commit comments

Comments
 (0)