Add urUSMPoolFree function to spec

To free previously allocated USM memory urUSMFree accepts a context
handle and pointer. If it's memory from a pool we need to identify the
pool from which the memory was allocated. We can avoid this overhead
by having a function that accepts pool handle.

include/ur.py

@@ -196,6 +196,7 @@ class ur_function_v(IntEnum):
     ADAPTER_RETAIN = 179                            ## Enumerator for ::urAdapterRetain
     ADAPTER_GET_LAST_ERROR = 180                    ## Enumerator for ::urAdapterGetLastError
     ADAPTER_GET_INFO = 181                          ## Enumerator for ::urAdapterGetInfo
+    USM_POOL_FREE = 182                             ## Enumerator for ::urUSMPoolFree
 
 class ur_function_t(c_int):
     def __str__(self):
@@ -1548,7 +1549,7 @@ class ur_usm_pool_limits_desc_t(Structure):
 ## @brief Get USM memory pool information
 class ur_usm_pool_info_v(IntEnum):
     REFERENCE_COUNT = 0                             ## [uint32_t] Reference count of the pool object.
-                                                    ## The reference count returned should be considered immediately stale. 
+                                                    ## The reference count returned should be considered immediately stale.
                                                     ## It is unsuitable for general use in applications. This feature is
                                                     ## provided for identifying memory leaks.
     CONTEXT = 1                                     ## [::ur_context_handle_t] USM memory pool context info
@@ -3359,6 +3360,13 @@ class ur_bindless_images_exp_dditable_t(Structure):
 else:
     _urUSMFree_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, c_void_p )
 
+###############################################################################
+## @brief Function-pointer for urUSMPoolFree
+if __use_win_types:
+    _urUSMPoolFree_t = WINFUNCTYPE( ur_result_t, ur_usm_pool_handle_t, c_void_p )
+else:
+    _urUSMPoolFree_t = CFUNCTYPE( ur_result_t, ur_usm_pool_handle_t, c_void_p )
+
 ###############################################################################
 ## @brief Function-pointer for urUSMGetMemAllocInfo
 if __use_win_types:
@@ -3403,6 +3411,7 @@ class ur_usm_dditable_t(Structure):
         ("pfnDeviceAlloc", c_void_p),                                   ## _urUSMDeviceAlloc_t
         ("pfnSharedAlloc", c_void_p),                                   ## _urUSMSharedAlloc_t
         ("pfnFree", c_void_p),                                          ## _urUSMFree_t
+        ("pfnPoolFree", c_void_p),                                      ## _urUSMPoolFree_t
         ("pfnGetMemAllocInfo", c_void_p),                               ## _urUSMGetMemAllocInfo_t
         ("pfnPoolCreate", c_void_p),                                    ## _urUSMPoolCreate_t
         ("pfnPoolRetain", c_void_p),                                    ## _urUSMPoolRetain_t
@@ -4057,6 +4066,7 @@ def __init__(self, version : ur_api_version_t):
         self.urUSMDeviceAlloc = _urUSMDeviceAlloc_t(self.__dditable.USM.pfnDeviceAlloc)
         self.urUSMSharedAlloc = _urUSMSharedAlloc_t(self.__dditable.USM.pfnSharedAlloc)
         self.urUSMFree = _urUSMFree_t(self.__dditable.USM.pfnFree)
+        self.urUSMPoolFree = _urUSMPoolFree_t(self.__dditable.USM.pfnPoolFree)
         self.urUSMGetMemAllocInfo = _urUSMGetMemAllocInfo_t(self.__dditable.USM.pfnGetMemAllocInfo)
         self.urUSMPoolCreate = _urUSMPoolCreate_t(self.__dditable.USM.pfnPoolCreate)
         self.urUSMPoolRetain = _urUSMPoolRetain_t(self.__dditable.USM.pfnPoolRetain)

include/ur_api.h

@@ -205,6 +205,7 @@ typedef enum ur_function_t {
     UR_FUNCTION_ADAPTER_RETAIN = 179,                                          ///< Enumerator for ::urAdapterRetain
     UR_FUNCTION_ADAPTER_GET_LAST_ERROR = 180,                                  ///< Enumerator for ::urAdapterGetLastError
     UR_FUNCTION_ADAPTER_GET_INFO = 181,                                        ///< Enumerator for ::urAdapterGetInfo
+    UR_FUNCTION_USM_POOL_FREE = 182,                                           ///< Enumerator for ::urUSMPoolFree
     /// @cond
     UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -3386,6 +3387,30 @@ urUSMFree(
     void *pMem                    ///< [in] pointer to USM memory object
 );
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Free the USM memory object from the pool
+///
+/// @details
+///     - Calling this function is equivalent to urUSMFree but without the pool
+///       look-up overhead.
+///
+/// @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 == pool`
+///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
+///         + `NULL == pMem`
+///     - ::UR_RESULT_ERROR_INVALID_MEM_OBJECT
+///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
+UR_APIEXPORT ur_result_t UR_APICALL
+urUSMPoolFree(
+    ur_usm_pool_handle_t pool, ///< [in] Pointer to a pool created using urUSMPoolCreate
+    void *pMem                 ///< [in] pointer to USM memory object
+);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Get USM memory object allocation information
 ///
@@ -9719,6 +9744,15 @@ typedef struct ur_usm_free_params_t {
     void **ppMem;
 } ur_usm_free_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urUSMPoolFree
+/// @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_pool_free_params_t {
+    ur_usm_pool_handle_t *ppool;
+    void **ppMem;
+} ur_usm_pool_free_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urUSMGetMemAllocInfo
 /// @details Each entry is a pointer to the parameter passed to the function;