[ur] Allow native handles to be unsupported

Some adapters do not map directly to Unified Runtime's set of API
objects and as such are unable to support getting the underlying native
handle or creating objects from native handles. This patch adds the
`UR_RESULT_ERROR_UNSUPPORTED_FEATURE` to all native handle entry-points
and updates the conformance tests to match.

Author: kbenzie

include/ur_api.h

@@ -1071,6 +1071,8 @@ urPlatformGetApiVersion(
 ///         + `NULL == hPlatform`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phNativePlatform`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urPlatformGetNativeHandle(
     ur_platform_handle_t hPlatform,      ///< [in] handle of the platform.
@@ -1105,6 +1107,8 @@ typedef struct ur_platform_native_properties_t {
 ///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phPlatform`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urPlatformCreateWithNativeHandle(
     ur_native_handle_t hNativePlatform,                 ///< [in][nocheck] the native handle of the platform.
@@ -1822,6 +1826,8 @@ typedef enum ur_device_exec_capability_flag_t {
 ///         + `NULL == hDevice`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phNativeDevice`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urDeviceGetNativeHandle(
     ur_device_handle_t hDevice,        ///< [in] handle of the device.
@@ -1858,6 +1864,8 @@ typedef struct ur_device_native_properties_t {
 ///         + `NULL == hPlatform`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phDevice`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urDeviceCreateWithNativeHandle(
     ur_native_handle_t hNativeDevice,                 ///< [in][nocheck] the native handle of the device.
@@ -2157,6 +2165,8 @@ urContextGetInfo(
 ///         + `NULL == hContext`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phNativeContext`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urContextGetNativeHandle(
     ur_context_handle_t hContext,       ///< [in] handle of the context.
@@ -2192,6 +2202,8 @@ typedef struct ur_context_native_properties_t {
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phDevices`
 ///         + `NULL == phContext`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urContextCreateWithNativeHandle(
     ur_native_handle_t hNativeContext,                 ///< [in][nocheck] the native handle of the context.
@@ -2633,6 +2645,8 @@ urMemBufferPartition(
 ///         + `NULL == hMem`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phNativeMem`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urMemGetNativeHandle(
     ur_mem_handle_t hMem,           ///< [in] handle of the mem.
@@ -2668,6 +2682,8 @@ typedef struct ur_mem_native_properties_t {
 ///         + `NULL == hContext`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phMem`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urMemBufferCreateWithNativeHandle(
     ur_native_handle_t hNativeMem,                 ///< [in][nocheck] the native handle to the memory.
@@ -2695,6 +2711,8 @@ urMemBufferCreateWithNativeHandle(
 ///         + `NULL == pImageFormat`
 ///         + `NULL == pImageDesc`
 ///         + `NULL == phMem`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urMemImageCreateWithNativeHandle(
     ur_native_handle_t hNativeMem,                 ///< [in][nocheck] the native handle to the memory.
@@ -2993,6 +3011,8 @@ urSamplerGetInfo(
 ///         + `NULL == hSampler`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phNativeSampler`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urSamplerGetNativeHandle(
     ur_sampler_handle_t hSampler,       ///< [in] handle of the sampler.
@@ -3029,6 +3049,8 @@ typedef struct ur_sampler_native_properties_t {
 ///         + `NULL == hContext`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phSampler`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urSamplerCreateWithNativeHandle(
     ur_native_handle_t hNativeSampler,                 ///< [in][nocheck] the native handle of the sampler.
@@ -4325,6 +4347,8 @@ urProgramSetSpecializationConstants(
 ///         + `NULL == hProgram`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phNativeProgram`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urProgramGetNativeHandle(
     ur_program_handle_t hProgram,       ///< [in] handle of the program.
@@ -4361,6 +4385,8 @@ typedef struct ur_program_native_properties_t {
 ///         + `NULL == hContext`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phProgram`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urProgramCreateWithNativeHandle(
     ur_native_handle_t hNativeProgram,                 ///< [in][nocheck] the native handle of the program.
@@ -4904,6 +4930,8 @@ urKernelSetSpecializationConstants(
 ///         + `NULL == hKernel`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phNativeKernel`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urKernelGetNativeHandle(
     ur_kernel_handle_t hKernel,        ///< [in] handle of the kernel.
@@ -4941,6 +4969,8 @@ typedef struct ur_kernel_native_properties_t {
 ///         + `NULL == hProgram`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phKernel`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urKernelCreateWithNativeHandle(
     ur_native_handle_t hNativeKernel,                 ///< [in][nocheck] the native handle of the kernel.
@@ -5195,6 +5225,8 @@ typedef struct ur_queue_native_desc_t {
 ///         + `NULL == hQueue`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phNativeQueue`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urQueueGetNativeHandle(
     ur_queue_handle_t hQueue,         ///< [in] handle of the queue.
@@ -5233,6 +5265,8 @@ typedef struct ur_queue_native_properties_t {
 ///         + `NULL == hDevice`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phQueue`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urQueueCreateWithNativeHandle(
     ur_native_handle_t hNativeQueue,                 ///< [in][nocheck] the native handle of the queue.
@@ -5557,6 +5591,8 @@ urEventRelease(
 ///         + `NULL == hEvent`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phNativeEvent`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urEventGetNativeHandle(
     ur_event_handle_t hEvent,         ///< [in] handle of the event.
@@ -5593,6 +5629,8 @@ typedef struct ur_event_native_properties_t {
 ///         + `NULL == hContext`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phEvent`
+///     - ::UR_RESULT_ERROR_UNSUPPORTED_FEATURE
+///         + If the adapter has no underlying equivalent handle.
 UR_APIEXPORT ur_result_t UR_APICALL
 urEventCreateWithNativeHandle(
     ur_native_handle_t hNativeEvent,                 ///< [in][nocheck] the native handle of the event.

scripts/core/context.yml

@@ -196,6 +196,9 @@ params:
       name: phNativeContext
       desc: |
             [out] a pointer to the native handle of the context.
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Properties for for $xContextCreateWithNativeHandle."
@@ -238,6 +241,9 @@ params:
       name: phContext
       desc: |
             [out] pointer to the handle of the context object created.
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: fptr_typedef
 desc: "Context's extended deleter callback function with user data."

scripts/core/device.yml

@@ -731,6 +731,9 @@ params:
       name: phNativeDevice
       desc: |
             [out] a pointer to the native handle of the device.
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Native device creation properties"
@@ -768,6 +771,9 @@ params:
     - type: "$x_device_handle_t*"
       name: phDevice
       desc: "[out] pointer to the handle of the device object created."
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Returns synchronized Host and Device global timestamps."

scripts/core/event.yml

@@ -266,6 +266,9 @@ params:
       name: phNativeEvent
       desc: |
             [out] a pointer to the native handle of the event.
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Properties for for $xEventCreateWithNativeHandle."
@@ -305,6 +308,9 @@ params:
       name: phEvent
       desc: |
             [out] pointer to the handle of the event object created.
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "Event states for all events."

scripts/core/kernel.yml

@@ -487,6 +487,9 @@ params:
       name: phNativeKernel
       desc: |
             [out] a pointer to the native handle of the kernel.
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Properties for for $xKernelCreateWithNativeHandle."
@@ -529,3 +532,6 @@ params:
       name: phKernel
       desc: |
             [out] pointer to the handle of the kernel object created.
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."

scripts/core/memory.yml

@@ -436,6 +436,9 @@ params:
       name: phNativeMem
       desc: |
             [out] a pointer to the native handle of the mem.
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Native memory object creation properties"
@@ -473,6 +476,9 @@ params:
     - type: $x_mem_handle_t*
       name: phMem
       desc: "[out] pointer to handle of buffer memory object created."
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime image memory object from native memory handle."
@@ -503,6 +509,9 @@ params:
     - type: $x_mem_handle_t*
       name: phMem
       desc: "[out] pointer to handle of image memory object created."
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Retrieve information about a memory object."

scripts/core/platform.yml

@@ -167,6 +167,9 @@ params:
       name: phNativePlatform
       desc: |
             [out] a pointer to the native handle of the platform.
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Native platform creation properties"
@@ -201,6 +204,9 @@ params:
     - type: "$x_platform_handle_t*"
       name: phPlatform
       desc: "[out] pointer to the handle of the platform object created."
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Get the platform specific compiler backend option from a generic frontend option."

scripts/core/program.yml

@@ -514,6 +514,9 @@ params:
       name: phNativeProgram
       desc: |
             [out] a pointer to the native handle of the program.
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Native program creation properties"
@@ -551,3 +554,6 @@ params:
     - type: "$x_program_handle_t*"
       name: phProgram
       desc: "[out] pointer to the handle of the program object created."
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."

scripts/core/queue.yml

@@ -244,6 +244,9 @@ params:
       name: phNativeQueue
       desc: |
             [out] a pointer to the native handle of the queue.
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Properties for for $xQueueCreateWithNativeHandle."
@@ -286,6 +289,9 @@ params:
       name: phQueue
       desc: |
             [out] pointer to the handle of the queue object created.
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Blocks until all previously issued commands to the command queue are finished."

scripts/core/sampler.yml

@@ -194,6 +194,9 @@ params:
       name: phNativeSampler
       desc: |
             [out] a pointer to the native handle of the sampler.
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Native sampler creation properties"
@@ -231,3 +234,6 @@ params:
     - type: "$x_sampler_handle_t*"
       name: phSampler
       desc: "[out] pointer to the handle of the sampler object created."
+returns:
+    - $X_RESULT_ERROR_UNSUPPORTED_FEATURE:
+        - "If the adapter has no underlying equivalent handle."