Merge pull request #724 from kbenzie/benie/unsupported-native-handles

[ur] Allow native handles to be unsupported

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."