Merge pull request #327 from veselypeta/petr/252/binary-structs

[UR] `urDeviceSelectBinary` spec changes

Author: veselypeta

include/ur.py

@@ -209,6 +209,7 @@ class ur_structure_type_v(IntEnum):
     USM_DESC = 7                                    ## ::ur_usm_desc_t
     USM_POOL_DESC = 8                               ## ::ur_usm_pool_desc_t
     USM_POOL_LIMITS_DESC = 9                        ## ::ur_usm_pool_limits_desc_t
+    DEVICE_BINARY = 10                              ## ::ur_device_binary_t
 
 class ur_structure_type_t(c_int):
     def __str__(self):
@@ -293,6 +294,61 @@ def __str__(self):
         return str(ur_api_version_v(self.value))
 
 
+###############################################################################
+## @brief Target identification strings for
+##        ::ur_device_binary_t.pDeviceTargetSpec 
+##        A device type represented by a particular target triple requires
+##        specific 
+##        binary images. We need to map the image type onto the device target triple
+UR_DEVICE_BINARY_TARGET_UNKNOWN = "<unknown>"
+
+###############################################################################
+## @brief SPIR-V 32-bit image <-> "spir", 32-bit OpenCL device
+UR_DEVICE_BINARY_TARGET_SPIRV32 = "spir"
+
+###############################################################################
+## @brief SPIR-V 64-bit image <-> "spir64", 64-bit OpenCL device
+UR_DEVICE_BINARY_TARGET_SPIRV64 = "spir64"
+
+###############################################################################
+## @brief Device-specific binary images produced from SPIR-V 64-bit <-> various 
+##        "spir64_*" triples for specific 64-bit OpenCL CPU devices
+UR_DEVICE_BINARY_TARGET_SPIRV64_X86_64 = "spir64_x86_64"
+
+###############################################################################
+## @brief Generic GPU device (64-bit OpenCL)
+UR_DEVICE_BINARY_TARGET_SPIRV64_GEN = "spir64_gen"
+
+###############################################################################
+## @brief 64-bit OpenCL FPGA device
+UR_DEVICE_BINARY_TARGET_SPIRV64_FPGA = "spir64_fpga"
+
+###############################################################################
+## @brief PTX 64-bit image <-> "nvptx64", 64-bit NVIDIA PTX device
+UR_DEVICE_BINARY_TARGET_NVPTX64 = "nvptx64"
+
+###############################################################################
+## @brief AMD GCN
+UR_DEVICE_BINARY_TARGET_AMDGCN = "amdgcn"
+
+###############################################################################
+## @brief Device Binary Type
+class ur_device_binary_t(Structure):
+    _fields_ = [
+        ("stype", ur_structure_type_t),                                 ## [in] type of this structure, must be ::UR_STRUCTURE_TYPE_DEVICE_BINARY
+        ("pNext", c_void_p),                                            ## [in][optional] pointer to extension-specific structure
+        ("pDeviceTargetSpec", c_char_p)                                 ## [in] null-terminated string representation of the device's target architecture.
+                                                                        ## For example: 
+                                                                        ## + ::UR_DEVICE_BINARY_TARGET_UNKNOWN
+                                                                        ## + ::UR_DEVICE_BINARY_TARGET_SPIRV32
+                                                                        ## + ::UR_DEVICE_BINARY_TARGET_SPIRV64
+                                                                        ## + ::UR_DEVICE_BINARY_TARGET_SPIRV64_X86_64
+                                                                        ## + ::UR_DEVICE_BINARY_TARGET_SPIRV64_GEN
+                                                                        ## + ::UR_DEVICE_BINARY_TARGET_SPIRV64_FPGA
+                                                                        ## + ::UR_DEVICE_BINARY_TARGET_NVPTX64
+                                                                        ## + ::UR_DEVICE_BINARY_TARGET_AMDGCN
+    ]
+
 ###############################################################################
 ## @brief Supported device types
 class ur_device_type_v(IntEnum):
@@ -2386,9 +2442,9 @@ class ur_usm_dditable_t(Structure):
 ###############################################################################
 ## @brief Function-pointer for urDeviceSelectBinary
 if __use_win_types:
-    _urDeviceSelectBinary_t = WINFUNCTYPE( ur_result_t, ur_device_handle_t, POINTER(POINTER(c_ubyte)), c_ulong, POINTER(c_ulong) )
+    _urDeviceSelectBinary_t = WINFUNCTYPE( ur_result_t, ur_device_handle_t, POINTER(ur_device_binary_t), c_ulong, POINTER(c_ulong) )
 else:
-    _urDeviceSelectBinary_t = CFUNCTYPE( ur_result_t, ur_device_handle_t, POINTER(POINTER(c_ubyte)), c_ulong, POINTER(c_ulong) )
+    _urDeviceSelectBinary_t = CFUNCTYPE( ur_result_t, ur_device_handle_t, POINTER(ur_device_binary_t), c_ulong, POINTER(c_ulong) )
 
 ###############################################################################
 ## @brief Function-pointer for urDeviceGetNativeHandle

include/ur_api.h

@@ -233,6 +233,7 @@ typedef enum ur_structure_type_t {
     UR_STRUCTURE_TYPE_USM_DESC = 7,                         ///< ::ur_usm_desc_t
     UR_STRUCTURE_TYPE_USM_POOL_DESC = 8,                    ///< ::ur_usm_pool_desc_t
     UR_STRUCTURE_TYPE_USM_POOL_LIMITS_DESC = 9,             ///< ::ur_usm_pool_limits_desc_t
+    UR_STRUCTURE_TYPE_DEVICE_BINARY = 10,                   ///< ::ur_device_binary_t
     /// @cond
     UR_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -548,6 +549,77 @@ urGetLastResult(
 #if !defined(__GNUC__)
 #pragma region device
 #endif
+///////////////////////////////////////////////////////////////////////////////
+#ifndef UR_DEVICE_BINARY_TARGET_UNKNOWN
+/// @brief Target identification strings for
+///        ::ur_device_binary_t.pDeviceTargetSpec
+///        A device type represented by a particular target triple requires
+///        specific
+///        binary images. We need to map the image type onto the device target triple
+#define UR_DEVICE_BINARY_TARGET_UNKNOWN "<unknown>"
+#endif // UR_DEVICE_BINARY_TARGET_UNKNOWN
+
+///////////////////////////////////////////////////////////////////////////////
+#ifndef UR_DEVICE_BINARY_TARGET_SPIRV32
+/// @brief SPIR-V 32-bit image <-> "spir", 32-bit OpenCL device
+#define UR_DEVICE_BINARY_TARGET_SPIRV32 "spir"
+#endif // UR_DEVICE_BINARY_TARGET_SPIRV32
+
+///////////////////////////////////////////////////////////////////////////////
+#ifndef UR_DEVICE_BINARY_TARGET_SPIRV64
+/// @brief SPIR-V 64-bit image <-> "spir64", 64-bit OpenCL device
+#define UR_DEVICE_BINARY_TARGET_SPIRV64 "spir64"
+#endif // UR_DEVICE_BINARY_TARGET_SPIRV64
+
+///////////////////////////////////////////////////////////////////////////////
+#ifndef UR_DEVICE_BINARY_TARGET_SPIRV64_X86_64
+/// @brief Device-specific binary images produced from SPIR-V 64-bit <-> various
+///        "spir64_*" triples for specific 64-bit OpenCL CPU devices
+#define UR_DEVICE_BINARY_TARGET_SPIRV64_X86_64 "spir64_x86_64"
+#endif // UR_DEVICE_BINARY_TARGET_SPIRV64_X86_64
+
+///////////////////////////////////////////////////////////////////////////////
+#ifndef UR_DEVICE_BINARY_TARGET_SPIRV64_GEN
+/// @brief Generic GPU device (64-bit OpenCL)
+#define UR_DEVICE_BINARY_TARGET_SPIRV64_GEN "spir64_gen"
+#endif // UR_DEVICE_BINARY_TARGET_SPIRV64_GEN
+
+///////////////////////////////////////////////////////////////////////////////
+#ifndef UR_DEVICE_BINARY_TARGET_SPIRV64_FPGA
+/// @brief 64-bit OpenCL FPGA device
+#define UR_DEVICE_BINARY_TARGET_SPIRV64_FPGA "spir64_fpga"
+#endif // UR_DEVICE_BINARY_TARGET_SPIRV64_FPGA
+
+///////////////////////////////////////////////////////////////////////////////
+#ifndef UR_DEVICE_BINARY_TARGET_NVPTX64
+/// @brief PTX 64-bit image <-> "nvptx64", 64-bit NVIDIA PTX device
+#define UR_DEVICE_BINARY_TARGET_NVPTX64 "nvptx64"
+#endif // UR_DEVICE_BINARY_TARGET_NVPTX64
+
+///////////////////////////////////////////////////////////////////////////////
+#ifndef UR_DEVICE_BINARY_TARGET_AMDGCN
+/// @brief AMD GCN
+#define UR_DEVICE_BINARY_TARGET_AMDGCN "amdgcn"
+#endif // UR_DEVICE_BINARY_TARGET_AMDGCN
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Device Binary Type
+typedef struct ur_device_binary_t {
+    ur_structure_type_t stype;     ///< [in] type of this structure, must be ::UR_STRUCTURE_TYPE_DEVICE_BINARY
+    const void *pNext;             ///< [in][optional] pointer to extension-specific structure
+    const char *pDeviceTargetSpec; ///< [in] null-terminated string representation of the device's target architecture.
+                                   ///< For example:
+                                   ///< + ::UR_DEVICE_BINARY_TARGET_UNKNOWN
+                                   ///< + ::UR_DEVICE_BINARY_TARGET_SPIRV32
+                                   ///< + ::UR_DEVICE_BINARY_TARGET_SPIRV64
+                                   ///< + ::UR_DEVICE_BINARY_TARGET_SPIRV64_X86_64
+                                   ///< + ::UR_DEVICE_BINARY_TARGET_SPIRV64_GEN
+                                   ///< + ::UR_DEVICE_BINARY_TARGET_SPIRV64_FPGA
+                                   ///< + ::UR_DEVICE_BINARY_TARGET_NVPTX64
+                                   ///< + ::UR_DEVICE_BINARY_TARGET_AMDGCN
+
+} ur_device_binary_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Supported device types
 typedef enum ur_device_type_t {
@@ -896,18 +968,19 @@ urDevicePartition(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
 ///         + `NULL == hDevice`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
-///         + `NULL == ppBinaries`
+///         + `NULL == pBinaries`
 ///         + `NULL == pSelectedBinary`
-///     - ::UR_RESULT_ERROR_INVALID_VALUE
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         + `NumBinaries == 0`
 UR_APIEXPORT ur_result_t UR_APICALL
 urDeviceSelectBinary(
-    ur_device_handle_t hDevice, ///< [in] handle of the device to select binary for.
-    const uint8_t **ppBinaries, ///< [in] the array of binaries to select from.
-    uint32_t NumBinaries,       ///< [in] the number of binaries passed in ppBinaries.
-                                ///< Must greater than or equal to zero otherwise
-                                ///< ::UR_RESULT_ERROR_INVALID_VALUE is returned.
-    uint32_t *pSelectedBinary   ///< [out] the index of the selected binary in the input array of binaries.
-                                ///< If a suitable binary was not found the function returns ${X}_INVALID_BINARY.
+    ur_device_handle_t hDevice,          ///< [in] handle of the device to select binary for.
+    const ur_device_binary_t *pBinaries, ///< [in] the array of binaries to select from.
+    uint32_t NumBinaries,                ///< [in] the number of binaries passed in ppBinaries.
+                                         ///< Must greater than or equal to zero otherwise
+                                         ///< ::UR_RESULT_ERROR_INVALID_VALUE is returned.
+    uint32_t *pSelectedBinary            ///< [out] the index of the selected binary in the input array of binaries.
+                                         ///< If a suitable binary was not found the function returns ::UR_RESULT_ERROR_INVALID_BINARY.
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -7922,7 +7995,7 @@ typedef void(UR_APICALL *ur_pfnDevicePartitionCb_t)(
 ///     allowing the callback the ability to modify the parameter's value
 typedef struct ur_device_select_binary_params_t {
     ur_device_handle_t *phDevice;
-    const uint8_t ***pppBinaries;
+    const ur_device_binary_t **ppBinaries;
     uint32_t *pNumBinaries;
     uint32_t **ppSelectedBinary;
 } ur_device_select_binary_params_t;

include/ur_ddi.h

@@ -1331,7 +1331,7 @@ typedef ur_result_t(UR_APICALL *ur_pfnDevicePartition_t)(
 /// @brief Function-pointer for urDeviceSelectBinary
 typedef ur_result_t(UR_APICALL *ur_pfnDeviceSelectBinary_t)(
     ur_device_handle_t,
-    const uint8_t **,
+    const ur_device_binary_t *,
     uint32_t,
     uint32_t *);
 

scripts/core/common.yml

@@ -282,6 +282,8 @@ etors:
       desc: $x_usm_pool_desc_t
     - name: USM_POOL_LIMITS_DESC
       desc: $x_usm_pool_limits_desc_t
+    - name: DEVICE_BINARY
+      desc: "$x_device_binary_t"
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Base for all properties types"

scripts/core/device.yml

@@ -11,6 +11,73 @@ type: header
 desc: "Intel $OneApi Unified Runtime APIs for Device"
 ordinal: "2"
 --- #--------------------------------------------------------------------------
+type: macro
+desc: |
+      Target identification strings for $x_device_binary_t.pDeviceTargetSpec 
+      A device type represented by a particular target triple requires specific 
+      binary images. We need to map the image type onto the device target triple
+name: "$X_DEVICE_BINARY_TARGET_UNKNOWN"
+value: "\"<unknown>\""
+--- #--------------------------------------------------------------------------
+type: macro
+desc: |
+     SPIR-V 32-bit image <-> "spir", 32-bit OpenCL device
+name: "$X_DEVICE_BINARY_TARGET_SPIRV32"
+value: "\"spir\""
+--- #--------------------------------------------------------------------------
+type: macro
+desc: |
+      SPIR-V 64-bit image <-> "spir64", 64-bit OpenCL device
+name: "$X_DEVICE_BINARY_TARGET_SPIRV64"
+value: "\"spir64\""
+--- #--------------------------------------------------------------------------
+type: macro
+desc: |
+      Device-specific binary images produced from SPIR-V 64-bit <-> various 
+      "spir64_*" triples for specific 64-bit OpenCL CPU devices
+name: "$X_DEVICE_BINARY_TARGET_SPIRV64_X86_64"
+value: "\"spir64_x86_64\""
+--- #--------------------------------------------------------------------------
+type: macro
+desc: "Generic GPU device (64-bit OpenCL)"
+name: "$X_DEVICE_BINARY_TARGET_SPIRV64_GEN"
+value: "\"spir64_gen\""
+--- #--------------------------------------------------------------------------
+type: macro
+desc: "64-bit OpenCL FPGA device"
+name: "$X_DEVICE_BINARY_TARGET_SPIRV64_FPGA"
+value: "\"spir64_fpga\""
+--- #--------------------------------------------------------------------------
+type: macro
+desc: |
+      PTX 64-bit image <-> "nvptx64", 64-bit NVIDIA PTX device
+name: "$X_DEVICE_BINARY_TARGET_NVPTX64"
+value: "\"nvptx64\""
+--- #--------------------------------------------------------------------------
+type: macro
+desc: "AMD GCN"
+name: "$X_DEVICE_BINARY_TARGET_AMDGCN"
+value: "\"amdgcn\""
+--- #--------------------------------------------------------------------------
+type: struct
+desc: "Device Binary Type"
+name: $x_device_binary_t
+base: $x_base_desc_t
+members:
+    - type: const char*
+      name: pDeviceTargetSpec
+      desc: |
+            [in] null-terminated string representation of the device's target architecture.
+            For example: 
+            + $X_DEVICE_BINARY_TARGET_UNKNOWN
+            + $X_DEVICE_BINARY_TARGET_SPIRV32
+            + $X_DEVICE_BINARY_TARGET_SPIRV64
+            + $X_DEVICE_BINARY_TARGET_SPIRV64_X86_64
+            + $X_DEVICE_BINARY_TARGET_SPIRV64_GEN
+            + $X_DEVICE_BINARY_TARGET_SPIRV64_FPGA
+            + $X_DEVICE_BINARY_TARGET_NVPTX64
+            + $X_DEVICE_BINARY_TARGET_AMDGCN
+--- #--------------------------------------------------------------------------
 type: enum
 desc: "Supported device types"
 class: $xDevice
@@ -440,8 +507,8 @@ params:
       name: hDevice
       desc: |
             [in] handle of the device to select binary for.
-    - type: "const uint8_t**"
-      name: ppBinaries
+    - type: "const $x_device_binary_t*"
+      name: pBinaries
       desc: |
             [in] the array of binaries to select from.
     - type: "uint32_t"
@@ -453,9 +520,10 @@ params:
       name: pSelectedBinary
       desc: |
             [out] the index of the selected binary in the input array of binaries.
-            If a suitable binary was not found the function returns ${X}_INVALID_BINARY.
+            If a suitable binary was not found the function returns $X_RESULT_ERROR_INVALID_BINARY.
 returns:
-    - $X_RESULT_ERROR_INVALID_VALUE
+    - $X_RESULT_ERROR_INVALID_SIZE:
+      - "`NumBinaries == 0`"
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "FP capabilities"

source/drivers/null/ur_nullddi.cpp

@@ -329,21 +329,22 @@ __urdlllocal ur_result_t UR_APICALL urDevicePartition(
 __urdlllocal ur_result_t UR_APICALL urDeviceSelectBinary(
     ur_device_handle_t
         hDevice, ///< [in] handle of the device to select binary for.
-    const uint8_t **ppBinaries, ///< [in] the array of binaries to select from.
+    const ur_device_binary_t
+        *pBinaries,       ///< [in] the array of binaries to select from.
     uint32_t NumBinaries, ///< [in] the number of binaries passed in ppBinaries.
                           ///< Must greater than or equal to zero otherwise
                           ///< ::UR_RESULT_ERROR_INVALID_VALUE is returned.
     uint32_t *
         pSelectedBinary ///< [out] the index of the selected binary in the input array of binaries.
-    ///< If a suitable binary was not found the function returns ${X}_INVALID_BINARY.
+    ///< If a suitable binary was not found the function returns ::UR_RESULT_ERROR_INVALID_BINARY.
 ) {
     ur_result_t result = UR_RESULT_SUCCESS;
 
     // if the driver has created a custom function, then call it instead of using the generic path
     auto pfnSelectBinary = d_context.urDdiTable.Device.pfnSelectBinary;
     if (nullptr != pfnSelectBinary) {
         result =
-            pfnSelectBinary(hDevice, ppBinaries, NumBinaries, pSelectedBinary);
+            pfnSelectBinary(hDevice, pBinaries, NumBinaries, pSelectedBinary);
     } else {
         // generic implementation
     }

source/loader/layers/tracing/ur_trcddi.cpp

@@ -392,27 +392,28 @@ __urdlllocal ur_result_t UR_APICALL urDevicePartition(
 __urdlllocal ur_result_t UR_APICALL urDeviceSelectBinary(
     ur_device_handle_t
         hDevice, ///< [in] handle of the device to select binary for.
-    const uint8_t **ppBinaries, ///< [in] the array of binaries to select from.
+    const ur_device_binary_t
+        *pBinaries,       ///< [in] the array of binaries to select from.
     uint32_t NumBinaries, ///< [in] the number of binaries passed in ppBinaries.
                           ///< Must greater than or equal to zero otherwise
                           ///< ::UR_RESULT_ERROR_INVALID_VALUE is returned.
     uint32_t *
         pSelectedBinary ///< [out] the index of the selected binary in the input array of binaries.
-    ///< If a suitable binary was not found the function returns ${X}_INVALID_BINARY.
+    ///< If a suitable binary was not found the function returns ::UR_RESULT_ERROR_INVALID_BINARY.
 ) {
     auto pfnSelectBinary = context.urDdiTable.Device.pfnSelectBinary;
 
     if (nullptr == pfnSelectBinary) {
         return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
     }
 
-    ur_device_select_binary_params_t params = {&hDevice, &ppBinaries,
+    ur_device_select_binary_params_t params = {&hDevice, &pBinaries,
                                                &NumBinaries, &pSelectedBinary};
     uint64_t instance = context.notify_begin(UR_FUNCTION_DEVICE_SELECT_BINARY,
                                              "urDeviceSelectBinary", &params);
 
     ur_result_t result =
-        pfnSelectBinary(hDevice, ppBinaries, NumBinaries, pSelectedBinary);
+        pfnSelectBinary(hDevice, pBinaries, NumBinaries, pSelectedBinary);
 
     context.notify_end(UR_FUNCTION_DEVICE_SELECT_BINARY, "urDeviceSelectBinary",
                        &params, &result, instance);