Add ur_usm_pool_buffer_desc_t extension (#17634)

Add extension to ur_usm_pool_desc_t structure chain that allows the user
to specify a buffer and its size that should by used for pool creation
in urUSMPoolCreate or urUSMPoolCreateEx function.

Author: kswiecicki

include/ur_api.h

@@ -23,10 +23,10 @@ Async Allocation Functions
 Motivation
 --------------------------------------------------------------------------------
 
-Asynchronous allocations can allow queues to allocate and free memory between 
-UR command enqueues without forcing synchronization points in the asynchronous 
+Asynchronous allocations can allow queues to allocate and free memory between
+UR command enqueues without forcing synchronization points in the asynchronous
 command DAG associated with a queue. Through the enqueue-ordering semantics,
-memory allocated within a pool can be reused so as to avoid expensive and 
+memory allocated within a pool can be reused so as to avoid expensive and
 redundant calls into the OS, which can improve performance.
 
 API
@@ -60,6 +60,7 @@ Types
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * ${x}_exp_async_usm_alloc_properties_t
+* ${x}_usm_pool_buffer_desc_t
 
 Functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -97,6 +98,9 @@ Changelog
 | 1.3      | Remove USMPoolSetThresholdExp                            |
 |          | Replace with USMPoolSetInfoExp                           |
 +----------+----------------------------------------------------------+
+| 1.4      | Introduce usm_pool_buffer_desc_t to enable pool          |
+|          | creation from a USM memory object                        |
++----------+----------------------------------------------------------+
 
 Support
 --------------------------------------------------------------------------------
@@ -110,3 +114,4 @@ Contributors
 
 * Hugh Delaney `hugh.delaney@codeplay.com <hugh.delaney@codeplay.com>`_
 * Sean Stirling `sean.stirling@codeplay.com <sean.stirling@codeplay.com>`_
+* Krzysztof Swiecicki `krzysztof.swiecicki@intel.com <krzysztof.swiecicki@intel.com>`_

include/ur_print.h

@@ -37,7 +37,7 @@ etors:
     - name: READ_ONLY_EXP
       value: "$X_BIT(2)"
       desc: |
-            Performance hint asserting that all memory allocations from the 
+            Performance hint asserting that all memory allocations from the
             memory pool will only ever be read from within SYCL kernel functions
 
 --- #--------------------------------------------------------------------------
@@ -114,6 +114,29 @@ members:
       name: flags
       desc: "[in] async alloc flags"
 
+--- #--------------------------------------------------------------------------
+type: struct
+desc: "USM pool buffer descriptor type"
+details:
+  - Used for pool creation from USM memory object. Specify these properties in
+    $xUSMPoolCreate or $xUSMPoolCreateExp via $x_usm_pool_desc_t as part of a `pNext` chain.
+class: $xUSM
+name: $x_usm_pool_buffer_desc_t
+base: $x_base_desc_t
+members:
+    - type: "void*"
+      name:  pMem
+      desc: "[in] USM memory object"
+    - type: "size_t"
+      name:  size
+      desc: "[in] size of USM memory object"
+    - type: "$x_usm_type_t"
+      name:  memType
+      desc: "[in] type of USM memory object"
+    - type: "$x_device_handle_t"
+      name:  device
+      desc: "[in][optional] device associated with the USM memory object"
+
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Enqueue an async device allocation"
@@ -261,7 +284,7 @@ returns:
     - $X_RESULT_ERROR_INVALID_NULL_HANDLE
     - $X_RESULT_ERROR_INVALID_NULL_POINTER
     - $X_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
-    
+
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create USM memory pool with desired properties."

include/ur_print.hpp

@@ -753,3 +753,6 @@ etors:
 - name: USM_ALLOC_LOCATION_DESC
   desc: $x_usm_alloc_location_desc_t
   value: '35'
+- name: USM_POOL_BUFFER_DESC
+  desc: $x_usm_pool_buffer_desc_t
+  value: '36'