Add experimental USM Import/Release APIs.

include/ur.py

@@ -1971,6 +1971,8 @@ class ur_function_v(IntEnum):
     PHYSICAL_MEM_CREATE = 160                       ## Enumerator for ::urPhysicalMemCreate
     PHYSICAL_MEM_RETAIN = 161                       ## Enumerator for ::urPhysicalMemRetain
     PHYSICAL_MEM_RELEASE = 162                      ## Enumerator for ::urPhysicalMemRelease
+    USM_IMPORT_EXP = 163                            ## Enumerator for ::urUSMImportExp
+    USM_RELEASE_EXP = 164                           ## Enumerator for ::urUSMReleaseExp
 
 class ur_function_t(c_int):
     def __str__(self):
@@ -3193,12 +3195,28 @@ class ur_usm_dditable_t(Structure):
 else:
     _urUSMPitchedAllocExp_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, ur_device_handle_t, POINTER(ur_usm_desc_t), ur_usm_pool_handle_t, c_size_t, c_size_t, c_size_t, POINTER(c_void_p), POINTER(c_size_t) )
 
+###############################################################################
+## @brief Function-pointer for urUSMImportExp
+if __use_win_types:
+    _urUSMImportExp_t = WINFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p, c_size_t )
+else:
+    _urUSMImportExp_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p, c_size_t )
+
+###############################################################################
+## @brief Function-pointer for urUSMReleaseExp
+if __use_win_types:
+    _urUSMReleaseExp_t = WINFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p )
+else:
+    _urUSMReleaseExp_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p )
+
 
 ###############################################################################
 ## @brief Table of USMExp functions pointers
 class ur_usm_exp_dditable_t(Structure):
     _fields_ = [
-        ("pfnPitchedAllocExp", c_void_p)                                ## _urUSMPitchedAllocExp_t
+        ("pfnPitchedAllocExp", c_void_p),                               ## _urUSMPitchedAllocExp_t
+        ("pfnImportExp", c_void_p),                                     ## _urUSMImportExp_t
+        ("pfnReleaseExp", c_void_p)                                     ## _urUSMReleaseExp_t
     ]
 
 ###############################################################################
@@ -3728,6 +3746,8 @@ def __init__(self, version : ur_api_version_t):
 
         # attach function interface to function address
         self.urUSMPitchedAllocExp = _urUSMPitchedAllocExp_t(self.__dditable.USMExp.pfnPitchedAllocExp)
+        self.urUSMImportExp = _urUSMImportExp_t(self.__dditable.USMExp.pfnImportExp)
+        self.urUSMReleaseExp = _urUSMReleaseExp_t(self.__dditable.USMExp.pfnReleaseExp)
 
         # call driver to get function pointers
         CommandBufferExp = ur_command_buffer_exp_dditable_t()

include/ur_api.h

@@ -5163,6 +5163,8 @@ typedef enum ur_function_t {
     UR_FUNCTION_PHYSICAL_MEM_CREATE = 160,                                     ///< Enumerator for ::urPhysicalMemCreate
     UR_FUNCTION_PHYSICAL_MEM_RETAIN = 161,                                     ///< Enumerator for ::urPhysicalMemRetain
     UR_FUNCTION_PHYSICAL_MEM_RELEASE = 162,                                    ///< Enumerator for ::urPhysicalMemRelease
+    UR_FUNCTION_USM_IMPORT_EXP = 163,                                          ///< Enumerator for ::urUSMImportExp
+    UR_FUNCTION_USM_RELEASE_EXP = 164,                                         ///< Enumerator for ::urUSMReleaseExp
     /// @cond
     UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -7226,6 +7228,57 @@ urCommandBufferEnqueueExp(
                                                    ///< command-buffer execution instance.
 );
 
+#if !defined(__GNUC__)
+#pragma endregion
+#endif
+// Intel 'oneAPI' USM Import/Release Extension APIs
+#if !defined(__GNUC__)
+#pragma region usm import release(experimental)
+#endif
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Import memory into USM
+///
+/// @details
+///     - Import memory into USM
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `NULL == hContext`
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == pMem`
+///     - ::UR_RESULT_ERROR_INVALID_CONTEXT
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+UR_APIEXPORT ur_result_t UR_APICALL
+urUSMImportExp(
+    ur_context_handle_t hContext, ///< [in] handle of the context object
+    void *pMem,                   ///< [in] pointer to host memory object
+    size_t size                   ///< [in] size in bytes of the host memory object to be imported
+);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Release memory from USM
+///
+/// @details
+///     - Release memory from USM
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `NULL == hContext`
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == pMem`
+///     - ::UR_RESULT_ERROR_INVALID_CONTEXT
+UR_APIEXPORT ur_result_t UR_APICALL
+urUSMReleaseExp(
+    ur_context_handle_t hContext, ///< [in] handle of the context object
+    void *pMem                    ///< [in] pointer to host memory object
+);
+
 #if !defined(__GNUC__)
 #pragma endregion
 #endif
@@ -8727,6 +8780,25 @@ typedef struct ur_usm_pitched_alloc_exp_params_t {
     size_t **ppResultPitch;
 } ur_usm_pitched_alloc_exp_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urUSMImportExp
+/// @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_usm_import_exp_params_t {
+    ur_context_handle_t *phContext;
+    void **ppMem;
+    size_t *psize;
+} ur_usm_import_exp_params_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urUSMReleaseExp
+/// @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_usm_release_exp_params_t {
+    ur_context_handle_t *phContext;
+    void **ppMem;
+} ur_usm_release_exp_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urCommandBufferCreateExp
 /// @details Each entry is a pointer to the parameter passed to the function;

include/ur_ddi.h

@@ -1568,10 +1568,25 @@ typedef ur_result_t(UR_APICALL *ur_pfnUSMPitchedAllocExp_t)(
     void **,
     size_t *);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urUSMImportExp
+typedef ur_result_t(UR_APICALL *ur_pfnUSMImportExp_t)(
+    ur_context_handle_t,
+    void *,
+    size_t);
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urUSMReleaseExp
+typedef ur_result_t(UR_APICALL *ur_pfnUSMReleaseExp_t)(
+    ur_context_handle_t,
+    void *);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Table of USMExp functions pointers
 typedef struct ur_usm_exp_dditable_t {
     ur_pfnUSMPitchedAllocExp_t pfnPitchedAllocExp;
+    ur_pfnUSMImportExp_t pfnImportExp;
+    ur_pfnUSMReleaseExp_t pfnReleaseExp;
 } ur_usm_exp_dditable_t;
 
 ///////////////////////////////////////////////////////////////////////////////

scripts/core/EXP-USM-IMPORT-RELEASE.rst

@@ -0,0 +1,58 @@
+
+<%
+    OneApi=tags['$OneApi']
+    x=tags['$x']
+    X=x.upper()
+%>
+.. _experimental-usm-import-release:
+
+==================
+USM Import/Release
+==================
+
+.. warning::
+
+    Experimental features:
+
+    *   May be replaced, updated, or removed at any time.
+    *   Do not require maintaining API/ABI stability of their own additions over
+        time.
+    *   Do not require conformance testing of their own additions.
+
+
+Data transfer between Host and Device is most efficient when source and
+destination are both allocated in USM memory.
+In situations where host data will participate in host/device transfers
+and the host data allocation is under user control, USM functions
+such as malloc_host could be used to allocate USM memory instead of
+system memory.
+However, this is not always possible if the source code where the allocation
+is made is not available, or source code changes are prohibited for portability
+reasons.
+In these situations a mechanism to temporarily promote system memory to USM
+for the duration of the host/device data transfers is useful for maximizing
+data transfer rate.
+
+
+Import Host Memory into USM
+===========================
+
+Import a range of host memory into USM.
+
+.. parsed-literal::
+
+    // Import into USM
+    ${x}USMImportExp(hContext, hostPtr, size);
+
+Release Host Memory Previously Imported into USM
+================================================
+
+Release from USM a range of memory that had been previously imported
+into USM.
+
+
+.. parsed-literal::
+
+    // Release from USM
+    ${x}USMReleaseExp(hContext, hostPtr);
+

scripts/core/exp-usm-import-release.yml

@@ -0,0 +1,40 @@
+--- #--------------------------------------------------------------------------
+type: header
+desc: "Intel $OneApi USM Import/Release Extension APIs"
+ordinal: "99"
+--- #--------------------------------------------------------------------------
+type: function
+desc: "Import memory into USM"
+class: $xUSM
+name: ImportExp
+details:
+    - "Import memory into USM"
+params:
+    - type: $x_context_handle_t
+      name: hContext
+      desc: "[in] handle of the context object"
+    - type: "void*"
+      name: pMem
+      desc: "[in] pointer to host memory object"
+    - type: "size_t"
+      name: size
+      desc: "[in] size in bytes of the host memory object to be imported"
+returns:
+    - $X_RESULT_ERROR_INVALID_CONTEXT
+    - $X_RESULT_ERROR_INVALID_SIZE
+--- #--------------------------------------------------------------------------
+type: function
+desc: "Release memory from USM"
+class: $xUSM
+name: ReleaseExp
+details:
+    - "Release memory from USM"
+params:
+    - type: $x_context_handle_t
+      name: hContext
+      desc: "[in] handle of the context object"
+    - type: "void*"
+      name: pMem
+      desc: "[in] pointer to host memory object"
+returns:
+    - $X_RESULT_ERROR_INVALID_CONTEXT

scripts/core/registry.yml

@@ -475,3 +475,9 @@ etors:
 - name: PHYSICAL_MEM_RELEASE
   desc: Enumerator for $xPhysicalMemRelease
   value: '162'
+- name: USM_IMPORT_EXP
+  desc: Enumerator for $xUSMImportExp
+  value: '163'
+- name: USM_RELEASE_EXP
+  desc: Enumerator for $xUSMReleaseExp
+  value: '164'

source/adapters/null/ur_nullddi.cpp

@@ -4572,6 +4572,49 @@ __urdlllocal ur_result_t UR_APICALL urCommandBufferEnqueueExp(
     return exceptionToResult(std::current_exception());
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Intercept function for urUSMImportExp
+__urdlllocal ur_result_t UR_APICALL urUSMImportExp(
+    ur_context_handle_t hContext, ///< [in] handle of the context object
+    void *pMem,                   ///< [in] pointer to host memory object
+    size_t size ///< [in] size in bytes of the host memory object to be imported
+    ) try {
+    ur_result_t result = UR_RESULT_SUCCESS;
+
+    // if the driver has created a custom function, then call it instead of using the generic path
+    auto pfnImportExp = d_context.urDdiTable.USMExp.pfnImportExp;
+    if (nullptr != pfnImportExp) {
+        result = pfnImportExp(hContext, pMem, size);
+    } else {
+        // generic implementation
+    }
+
+    return result;
+} catch (...) {
+    return exceptionToResult(std::current_exception());
+}
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Intercept function for urUSMReleaseExp
+__urdlllocal ur_result_t UR_APICALL urUSMReleaseExp(
+    ur_context_handle_t hContext, ///< [in] handle of the context object
+    void *pMem                    ///< [in] pointer to host memory object
+    ) try {
+    ur_result_t result = UR_RESULT_SUCCESS;
+
+    // if the driver has created a custom function, then call it instead of using the generic path
+    auto pfnReleaseExp = d_context.urDdiTable.USMExp.pfnReleaseExp;
+    if (nullptr != pfnReleaseExp) {
+        result = pfnReleaseExp(hContext, pMem);
+    } else {
+        // generic implementation
+    }
+
+    return result;
+} catch (...) {
+    return exceptionToResult(std::current_exception());
+}
+
 } // namespace driver
 
 #if defined(__cplusplus)
@@ -5300,6 +5343,10 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetUSMExpProcAddrTable(
 
     pDdiTable->pfnPitchedAllocExp = driver::urUSMPitchedAllocExp;
 
+    pDdiTable->pfnImportExp = driver::urUSMImportExp;
+
+    pDdiTable->pfnReleaseExp = driver::urUSMReleaseExp;
+
     return result;
 } catch (...) {
     return exceptionToResult(std::current_exception());