Merge pull request #2193 from aarongreig/aaron/clarifyIsNativeHandleOwned

Clarify spec around isNativeHandleOwned.

Author: kbenzie

include/ur_api.h

@@ -1615,9 +1615,9 @@ typedef struct ur_platform_native_properties_t {
   ur_structure_type_t stype;
   /// [in,out][optional] pointer to extension-specific structure
   void *pNext;
-  /// [in] Indicates UR owns the native handle or if it came from an
-  /// interoperability operation in the application that asked to not
-  /// transfer the ownership to the unified-runtime.
+  /// [in] If true then ownership of the native handle is transferred to
+  /// the resultant object. This means the object will be responsible for
+  /// releasing the native resources at the end of its lifetime.
   bool isNativeHandleOwned;
 
 } ur_platform_native_properties_t;
@@ -2699,9 +2699,9 @@ typedef struct ur_device_native_properties_t {
   ur_structure_type_t stype;
   /// [in,out][optional] pointer to extension-specific structure
   void *pNext;
-  /// [in] Indicates UR owns the native handle or if it came from an
-  /// interoperability operation in the application that asked to not
-  /// transfer the ownership to the unified-runtime.
+  /// [in] If true then ownership of the native handle is transferred to
+  /// the resultant object. This means the object will be responsible for
+  /// releasing the native resources at the end of its lifetime.
   bool isNativeHandleOwned;
 
 } ur_device_native_properties_t;
@@ -3079,9 +3079,9 @@ typedef struct ur_context_native_properties_t {
   ur_structure_type_t stype;
   /// [in,out][optional] pointer to extension-specific structure
   void *pNext;
-  /// [in] Indicates UR owns the native handle or if it came from an
-  /// interoperability operation in the application that asked to not transfer
-  /// the ownership to the unified-runtime.
+  /// [in] If true then ownership of the native handle is transferred to
+  /// the resultant object. This means the object will be responsible for
+  /// releasing the native resources at the end of its lifetime.
   bool isNativeHandleOwned;
 
 } ur_context_native_properties_t;
@@ -3700,9 +3700,9 @@ typedef struct ur_mem_native_properties_t {
   ur_structure_type_t stype;
   /// [in,out][optional] pointer to extension-specific structure
   void *pNext;
-  /// [in] Indicates UR owns the native handle or if it came from an
-  /// interoperability operation in the application that asked to not
-  /// transfer the ownership to the unified-runtime.
+  /// [in] If true then ownership of the native handle is transferred to
+  /// the resultant object. This means the object will be responsible for
+  /// releasing the native resources at the end of its lifetime.
   bool isNativeHandleOwned;
 
 } ur_mem_native_properties_t;
@@ -4106,9 +4106,9 @@ typedef struct ur_sampler_native_properties_t {
   ur_structure_type_t stype;
   /// [in,out][optional] pointer to extension-specific structure
   void *pNext;
-  /// [in] Indicates UR owns the native handle or if it came from an
-  /// interoperability operation in the application that asked to not
-  /// transfer the ownership to the unified-runtime.
+  /// [in] If true then ownership of the native handle is transferred to
+  /// the resultant object. This means the object will be responsible for
+  /// releasing the native resources at the end of its lifetime.
   bool isNativeHandleOwned;
 
 } ur_sampler_native_properties_t;
@@ -5821,9 +5821,9 @@ typedef struct ur_program_native_properties_t {
   ur_structure_type_t stype;
   /// [in,out][optional] pointer to extension-specific structure
   void *pNext;
-  /// [in] Indicates UR owns the native handle or if it came from an
-  /// interoperability operation in the application that asked to not
-  /// transfer the ownership to the unified-runtime.
+  /// [in] If true then ownership of the native handle is transferred to
+  /// the resultant object. This means the object will be responsible for
+  /// releasing the native resources at the end of its lifetime.
   bool isNativeHandleOwned;
 
 } ur_program_native_properties_t;
@@ -6490,9 +6490,9 @@ typedef struct ur_kernel_native_properties_t {
   ur_structure_type_t stype;
   /// [in,out][optional] pointer to extension-specific structure
   void *pNext;
-  /// [in] Indicates UR owns the native handle or if it came from an
-  /// interoperability operation in the application that asked to not transfer
-  /// the ownership to the unified-runtime.
+  /// [in] If true then ownership of the native handle is transferred to
+  /// the resultant object. This means the object will be responsible for
+  /// releasing the native resources at the end of its lifetime.
   bool isNativeHandleOwned;
 
 } ur_kernel_native_properties_t;
@@ -6885,9 +6885,9 @@ typedef struct ur_queue_native_properties_t {
   ur_structure_type_t stype;
   /// [in,out][optional] pointer to extension-specific structure
   void *pNext;
-  /// [in] Indicates UR owns the native handle or if it came from an
-  /// interoperability operation in the application that asked to not transfer
-  /// the ownership to the unified-runtime.
+  /// [in] If true then ownership of the native handle is transferred to
+  /// the resultant object. This means the object will be responsible for
+  /// releasing the native resources at the end of its lifetime.
   bool isNativeHandleOwned;
 
 } ur_queue_native_properties_t;
@@ -7311,9 +7311,9 @@ typedef struct ur_event_native_properties_t {
   ur_structure_type_t stype;
   /// [in,out][optional] pointer to extension-specific structure
   void *pNext;
-  /// [in] Indicates UR owns the native handle or if it came from an
-  /// interoperability operation in the application that asked to not transfer
-  /// the ownership to the unified-runtime.
+  /// [in] If true then ownership of the native handle is transferred to
+  /// the resultant object. This means the object will be responsible for
+  /// releasing the native resources at the end of its lifetime.
   bool isNativeHandleOwned;
 
 } ur_event_native_properties_t;

scripts/core/PROG.rst

@@ -287,17 +287,6 @@ ${x}QueueRetain. An application must call ${x}QueueRelease
 when a queue object is no longer needed. When a queue object's reference count becomes
 zero, it is deleted by the runtime.
 
-Native Driver Access
-----------------------------------
-
-The runtime API provides accessors for native handles.
-For example, given a ${x}_program_handle_t, we can
-call ${x}ProgramGetNativeHandle to retrieve a ${x}_native_handle_t.
-We can then leverage a platform extension to convert the
-native handle to a driver handle. For example, OpenCL platform
-may expose an extension ${x}ProgramCreateWithNativeHandle to retrieve
-a cl_program.
-
 Memory
 ======
 
@@ -340,3 +329,38 @@ through ${x}_usm_desc_t structure. Allocations that specify different pool handl
 isolated and not reside on the same page. Memory pool is subject to limits specified during pool creation.
 
 Even if no ${x}_usm_pool_handle_t is provided to an allocation function, each adapter may still perform memory pooling.
+
+Native Handles
+==============
+
+In addition to the regular object creation APIs, ${X} objects can be
+constructed with handles obtained directly from an adapter's associated
+backend. This is achieved by casting the backend handle to a
+${x}_native_handle_t and passing it to the relevant ``CreateWithNativeHandle``
+entry point.
+
+
+.. note::
+   Not all backends have a 1:1 equivalent for every ${X} handle type, as such
+   any ``CreateWithNativeHandle`` or ``GetNativeHandle`` entry point *may* fail
+   with the error code ${X}_RESULT_ERROR_UNSUPPORTED_FEATURE for a given
+   adapter.
+
+Native Handle Ownership
+-----------------------
+
+By default a ${X} object constructed from a native handle doesn't own the
+native handle, it is guaranteed not to retain a reference to the native handle,
+or cause its resources to be released. A ${X} object that doesn't own its
+associated native handle **must** be destroyed before the native handle is.
+
+Ownership of the native handle can be transferred to the ${X} object by passing
+``isNativeHandleOwned = true`` in the native properties struct when calling the
+``CreateWithNativeHandle`` entry point. A ${X} object that owns a native handle
+will attempt to release the native resources associated with that handle on
+destruction. The same native handle **must not** have its ownership transferred
+to more than one ${X} object.
+
+Ownership of a native handle obtained from a ${X} object via a
+``GetNativeHandle`` entry point **must not** be transferred to a new ${X}
+object.

scripts/core/context.yml

@@ -209,9 +209,9 @@ members:
     - type: bool
       name: isNativeHandleOwned
       desc: |
-            [in] Indicates UR owns the native handle or if it came from an interoperability
-            operation in the application that asked to not transfer the ownership to
-            the unified-runtime.
+            [in] If true then ownership of the native handle is transferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime context object from native context handle."

scripts/core/device.yml

@@ -805,10 +805,10 @@ base: $x_base_properties_t
 members:
     - type: bool
       name: isNativeHandleOwned
-      desc: >
-          [in] Indicates UR owns the native handle or if it came from an
-          interoperability operation in the application that asked to not
-          transfer the ownership to the unified-runtime.
+      desc: |
+            [in] If true then ownership of the native handle is transferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime device object from native device handle."

scripts/core/event.yml

@@ -289,9 +289,9 @@ members:
     - type: bool
       name: isNativeHandleOwned
       desc: |
-            [in] Indicates UR owns the native handle or if it came from an interoperability
-            operation in the application that asked to not transfer the ownership to
-            the unified-runtime.
+            [in] If true then ownership of the native handle is transferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime event object from native event handle."

scripts/core/kernel.yml

@@ -513,9 +513,9 @@ members:
     - type: bool
       name: isNativeHandleOwned
       desc: |
-            [in] Indicates UR owns the native handle or if it came from an interoperability
-            operation in the application that asked to not transfer the ownership to
-            the unified-runtime.
+            [in] If true then ownership of the native handle is transferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime kernel object from native kernel handle."

scripts/core/memory.yml

@@ -474,10 +474,10 @@ base: $x_base_properties_t
 members:
     - type: bool
       name: isNativeHandleOwned
-      desc: >
-        [in] Indicates UR owns the native handle or if it came from an
-        interoperability operation in the application that asked to not
-        transfer the ownership to the unified-runtime.
+      desc: |
+            [in] If true then ownership of the native handle is transferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime buffer memory object from native memory handle."

scripts/core/platform.yml

@@ -202,10 +202,10 @@ base: $x_base_properties_t
 members:
     - type: bool
       name: isNativeHandleOwned
-      desc: >
-          [in] Indicates UR owns the native handle or if it came from an
-          interoperability operation in the application that asked to not
-          transfer the ownership to the unified-runtime.
+      desc: |
+            [in] If true then ownership of the native handle is transferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime platform object from native platform handle."

scripts/core/program.yml

@@ -587,10 +587,10 @@ base: $x_base_properties_t
 members:
     - type: bool
       name: isNativeHandleOwned
-      desc: >
-          [in] Indicates UR owns the native handle or if it came from an
-          interoperability operation in the application that asked to not
-          transfer the ownership to the unified-runtime.
+      desc: |
+            [in] If true then ownership of the native handle is transferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime program object from native program handle."

scripts/core/queue.yml

@@ -262,9 +262,9 @@ members:
     - type: bool
       name: isNativeHandleOwned
       desc: |
-            [in] Indicates UR owns the native handle or if it came from an interoperability
-            operation in the application that asked to not transfer the ownership to
-            the unified-runtime.
+            [in] If true then ownership of the native handle is transferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime queue object from native queue handle."