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