Implement ONEAPI_DEVICE_SELECTOR in UR

include/ur_api.h

@@ -220,6 +220,7 @@ typedef enum ur_function_t {
     UR_FUNCTION_COMMAND_BUFFER_RELEASE_COMMAND_EXP = 217,                      ///< Enumerator for ::urCommandBufferReleaseCommandExp
     UR_FUNCTION_COMMAND_BUFFER_GET_INFO_EXP = 218,                             ///< Enumerator for ::urCommandBufferGetInfoExp
     UR_FUNCTION_COMMAND_BUFFER_COMMAND_GET_INFO_EXP = 219,                     ///< Enumerator for ::urCommandBufferCommandGetInfoExp
+    UR_FUNCTION_DEVICE_GET_SELECTED = 220,                                     ///< Enumerator for ::urDeviceGetSelected
     /// @cond
     UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -1387,6 +1388,46 @@ urDeviceGet(
                                     ///< pNumDevices will be updated with the total number of devices available.
 );
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Retrieves devices within a platform selected by ONEAPI_DEVICE_SELECTOR
+///
+/// @details
+///     - Multiple calls to this function will return identical device handles,
+///       in the same order.
+///     - The number and order of handles returned from this function will be
+///       affected by environment variables that filter or select which devices
+///       are exposed through this API.
+///     - A reference is taken for each returned device and must be released
+///       with a subsequent call to ::urDeviceRelease.
+///     - The application may call this function from simultaneous threads, the
+///       implementation must be thread-safe.
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `NULL == hPlatform`
+///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
+///         + `::UR_DEVICE_TYPE_VPU < DeviceType`
+///     - ::UR_RESULT_ERROR_INVALID_VALUE
+UR_APIEXPORT ur_result_t UR_APICALL
+urDeviceGetSelected(
+    ur_platform_handle_t hPlatform, ///< [in] handle of the platform instance
+    ur_device_type_t DeviceType,    ///< [in] the type of the devices.
+    uint32_t NumEntries,            ///< [in] the number of devices to be added to phDevices.
+                                    ///< If phDevices in not NULL then NumEntries should be greater than zero,
+                                    ///< otherwise ::UR_RESULT_ERROR_INVALID_VALUE,
+                                    ///< will be returned.
+    ur_device_handle_t *phDevices,  ///< [out][optional][range(0, NumEntries)] array of handle of devices.
+                                    ///< If NumEntries is less than the number of devices available, then only
+                                    ///< that number of devices will be retrieved.
+    uint32_t *pNumDevices           ///< [out][optional] pointer to the number of devices.
+                                    ///< pNumDevices will be updated with the total number of selected devices
+                                    ///< available for the given platform.
+);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Supported device info
 typedef enum ur_device_info_t {
@@ -11148,6 +11189,18 @@ typedef struct ur_device_get_params_t {
     uint32_t **ppNumDevices;
 } ur_device_get_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urDeviceGetSelected
+/// @details Each entry is a pointer to the parameter passed to the function;
+///     allowing the callback the ability to modify the parameter's value
+typedef struct ur_device_get_selected_params_t {
+    ur_platform_handle_t *phPlatform;
+    ur_device_type_t *pDeviceType;
+    uint32_t *pNumEntries;
+    ur_device_handle_t **pphDevices;
+    uint32_t **ppNumDevices;
+} ur_device_get_selected_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urDeviceGetInfo
 /// @details Each entry is a pointer to the parameter passed to the function;

include/ur_print.h

@@ -2450,6 +2450,14 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintVirtualMemGetInfoParams(const struct
 ///         - `buff_size < out_size`
 UR_APIEXPORT ur_result_t UR_APICALL urPrintDeviceGetParams(const struct ur_device_get_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_device_get_selected_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintDeviceGetSelectedParams(const struct ur_device_get_selected_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_device_get_info_params_t struct
 /// @returns

include/ur_print.hpp

@@ -909,6 +909,9 @@ inline std::ostream &operator<<(std::ostream &os, ur_function_t value) {
     case UR_FUNCTION_COMMAND_BUFFER_COMMAND_GET_INFO_EXP:
         os << "UR_FUNCTION_COMMAND_BUFFER_COMMAND_GET_INFO_EXP";
         break;
+    case UR_FUNCTION_DEVICE_GET_SELECTED:
+        os << "UR_FUNCTION_DEVICE_GET_SELECTED";
+        break;
     default:
         os << "unknown enumerator";
         break;
@@ -16282,6 +16285,48 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
     return os;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_device_get_selected_params_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_device_get_selected_params_t *params) {
+
+    os << ".hPlatform = ";
+
+    ur::details::printPtr(os,
+                          *(params->phPlatform));
+
+    os << ", ";
+    os << ".DeviceType = ";
+
+    os << *(params->pDeviceType);
+
+    os << ", ";
+    os << ".NumEntries = ";
+
+    os << *(params->pNumEntries);
+
+    os << ", ";
+    os << ".phDevices = {";
+    for (size_t i = 0; *(params->pphDevices) != NULL && i < *params->pNumEntries; ++i) {
+        if (i != 0) {
+            os << ", ";
+        }
+
+        ur::details::printPtr(os,
+                              (*(params->pphDevices))[i]);
+    }
+    os << "}";
+
+    os << ", ";
+    os << ".pNumDevices = ";
+
+    ur::details::printPtr(os,
+                          *(params->ppNumDevices));
+
+    return os;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_device_get_info_params_t type
 /// @returns
@@ -17080,6 +17125,9 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os, ur_function_
     case UR_FUNCTION_DEVICE_GET: {
         os << (const struct ur_device_get_params_t *)params;
     } break;
+    case UR_FUNCTION_DEVICE_GET_SELECTED: {
+        os << (const struct ur_device_get_selected_params_t *)params;
+    } break;
     case UR_FUNCTION_DEVICE_GET_INFO: {
         os << (const struct ur_device_get_info_params_t *)params;
     } break;

scripts/core/device.yml

@@ -150,6 +150,45 @@ returns:
         - "`NumEntries > 0 && phDevices == NULL`"
     - $X_RESULT_ERROR_INVALID_VALUE
 --- #--------------------------------------------------------------------------
+type: function
+desc: "Retrieves devices within a platform selected by ONEAPI_DEVICE_SELECTOR"
+class: $xDevice
+loader_only: True
+name: GetSelected
+decl: static
+ordinal: "0"
+details:
+    - "Multiple calls to this function will return identical device handles, in the same order."
+    - "The number and order of handles returned from this function will be affected by environment variables that filter or select which devices are exposed through this API."
+    - "A reference is taken for each returned device and must be released with a subsequent call to $xDeviceRelease."
+    - "The application may call this function from simultaneous threads, the implementation must be thread-safe."
+params:
+    - type: $x_platform_handle_t
+      name: hPlatform
+      desc: "[in] handle of the platform instance"
+    - type: "$x_device_type_t"
+      name: DeviceType
+      desc: |
+            [in] the type of the devices.
+    - type: "uint32_t"
+      name: NumEntries
+      desc: |
+            [in] the number of devices to be added to phDevices.
+            If phDevices in not NULL then NumEntries should be greater than zero, otherwise $X_RESULT_ERROR_INVALID_VALUE,
+            will be returned.
+    - type: "$x_device_handle_t*"
+      name: phDevices
+      desc: |
+            [out][optional][range(0, NumEntries)] array of handle of devices.
+            If NumEntries is less than the number of devices available, then only that number of devices will be retrieved.
+    - type: "uint32_t*"
+      name: pNumDevices
+      desc: |
+            [out][optional] pointer to the number of devices.
+            pNumDevices will be updated with the total number of selected devices available for the given platform.
+returns:
+    - $X_RESULT_ERROR_INVALID_VALUE
+--- #--------------------------------------------------------------------------
 type: enum
 desc: "Supported device info"
 class: $xDevice

scripts/core/registry.yml

@@ -574,6 +574,9 @@ etors:
 - name: COMMAND_BUFFER_COMMAND_GET_INFO_EXP
   desc: Enumerator for $xCommandBufferCommandGetInfoExp
   value: '219'
+- name: DEVICE_GET_SELECTED
+  desc: Enumerator for $xDeviceGetSelected
+  value: '220'
 ---
 type: enum
 desc: Defines structure types