[UR] Allow loader to skip adapters based on prefilter device type. (#17072)

Addresses URT-855

Author: aarongreig

sycl/test-e2e/FilterSelector/select_device_cpu.cpp

@@ -25,8 +25,9 @@ int main() {
   {
     device d(default_selector_v);
     string name = d.get_platform().get_info<info::platform::name>();
-    assert(name.find("OpenCL") != string::npos &&
-           "default_selector failed to find cpu device");
+    assert((name.find("OpenCL") != string::npos) ||
+           (name.find("NATIVE_CPU") != string::npos) &&
+               "default_selector failed to find cpu device");
   }
   {
     try {

unified-runtime/scripts/YaML.md

@@ -9,7 +9,7 @@ This document describes the YaML format used by the scripts for the API specific
 
 ## YML Syntax
 * Each document in the yml file represents an entry in the specification.
-* Every document must have a `type` scalar: {`header`, `macro`, `typedef`, `const`, `enum`, `struct`, `handle`, `function`, `class`}
+* Every document must have a `type` scalar: {`header`, `macro`, `typedef`, `const`, `enum`, `struct`, `handle`, `function`, `class`, `manifest`}
 * All scalars must be strings. The document writer is responsible for using explicit string notification where the yml parser may perform implicit conversion.
 * Custom names must be tagged using `$` followed by the tag name. The tag names are defined in the `config.ini` section. There are two tag variations for replacement:
     - `$x` : lower_case
@@ -831,6 +831,17 @@ namespace ur {
 </td></tr>
 </table>
 
+#### type: manifest
+* A manifest encodes meta information about an adapter library.
+* These don't cause anything to be added to the spec or headers, they're intended to generate code for the loader.
+* A manifest requires the following scalar fields: {`name`, `backend`}
+  - `name` must be a string unique to the adapter.
+  - `name` should be identical to how the name appears in the adapter's library name. E.g. `libur_adapter_my_adapter` should have the name string `my_adapter`.
+  - `backend` must be an etor of `$x_adapter_backend_t`.
+  - `backend` must not be `$X_ADAPTER_BACKEND_UNKNOWN`.
+* a manifest requires the following sequence of scalars: {`device_types`}
+  - `device_types` must be an etor of `$x_device_type_t`
+
 ## Extensions
 * Each extensions must be defined in a unique `.yml` file
 * The extension file must be added to the section being extended; i.e. extensions to core APIs must be added to the `core` folder, etc.

unified-runtime/scripts/core/CONTRIB.rst

@@ -357,3 +357,16 @@ to easily differentiate experimental feature symbols, the following conventions
 *   All structures, enumerations, and other types must follow
     ``${x}_exp_name_t`` name case convention.
 ## --validate=on
+
+New Adapters
+============
+
+The UR loader will only load UR adapter libraries made known to it via entries
+in `scripts/core/manifests.yml`_. New adapters must have their own entry in that
+file before the loader will recognize them. See `YaML.md`_ for details about
+manifest semantics.
+
+.. _scripts/core/manifests.yml:
+   https://github.com/intel/llvm/blob/sycl/unified-runtime/scripts/core/manifests.yml
+.. _YaML.md:
+   https://github.com/intel/llvm/blob/sycl/unified-runtime/scripts/YaML.md

unified-runtime/scripts/core/manifests.yml

@@ -0,0 +1,40 @@
+--- #--------------------------------------------------------------------------
+type: header
+desc: "Intel $OneApi Unified Runtime adapter manifests"
+ordinal: "99"
+--- #--------------------------------------------------------------------------
+type: manifest
+name: opencl
+backend: $X_ADAPTER_BACKEND_OPENCL
+device_types:
+    - $X_DEVICE_TYPE_ALL
+--- #--------------------------------------------------------------------------
+type: manifest
+name: cuda
+backend: $X_ADAPTER_BACKEND_CUDA
+device_types:
+    - $X_DEVICE_TYPE_GPU
+--- #--------------------------------------------------------------------------
+type: manifest
+name: hip
+backend: $X_ADAPTER_BACKEND_HIP
+device_types:
+    - $X_DEVICE_TYPE_GPU
+--- #--------------------------------------------------------------------------
+type: manifest
+name: level_zero
+backend: $X_ADAPTER_BACKEND_LEVEL_ZERO
+device_types:
+    - $X_DEVICE_TYPE_ALL
+--- #--------------------------------------------------------------------------
+type: manifest
+name: level_zero_v2
+backend: $X_ADAPTER_BACKEND_LEVEL_ZERO
+device_types:
+    - $X_DEVICE_TYPE_ALL
+--- #--------------------------------------------------------------------------
+type: manifest
+name: native_cpu
+backend: $X_ADAPTER_BACKEND_NATIVE_CPU
+device_types:
+    - $X_DEVICE_TYPE_CPU

unified-runtime/scripts/generate_code.py

@@ -225,6 +225,26 @@ def _mako_lib_cpp(path, namespace, tags, version, specs, meta):
         specs=specs,
         meta=meta,
     )
+
+    template = "manifests.hpp.mako"
+    fin = os.path.join(templates_dir, template)
+
+    name = "%s_manifests" % (namespace)
+    filename = "%s.hpp" % name
+    fout = os.path.join(path, filename)
+
+    print("Generating %s..." % fout)
+    loc += util.makoWrite(
+        fin,
+        fout,
+        name=name,
+        ver=version,
+        namespace=namespace,
+        tags=tags,
+        specs=specs,
+        meta=meta,
+    )
+
     return loc
 
 

unified-runtime/scripts/templates/api.h.mako

@@ -41,14 +41,16 @@ extern "C" {
 #endif
 
 %for spec in specs:
-%if len(spec['objects']):
+%if len(spec['objects']) and 'manifest' not in spec['name']:
 // ${th.subt(n, tags, spec['header']['desc'])}
 #if !defined(__GNUC__)
 #pragma region ${spec['name'].replace(' ', '_')}
 #endif
 %endif
 %for obj in spec['objects']:
-%if not re.match(r"class", obj['type']):
+%if "manifest" in obj['type']:
+<%continue%>
+%elif not re.match(r"class", obj['type']):
 ///////////////////////////////////////////////////////////////////////////////
 ## MACRO ######################################################################
 %if re.match(r"macro", obj['type']):
@@ -142,7 +144,7 @@ typedef struct ${th.subt(n, tags, obj['name'])}_ *${th.subt(n, tags, obj['name']
 
 %endif  # not re.match(r"class", obj['type'])
 %endfor # obj in spec['objects']
-%if len(spec['objects']):
+%if len(spec['objects']) and 'manifest' not in spec['name']:
 #if !defined(__GNUC__)
 #pragma endregion
 #endif

unified-runtime/scripts/templates/helper.py

@@ -739,6 +739,20 @@ def get_adapter_handles(specs):
     return objs
 
 
+"""
+Public:
+    returns a list of all adapter manifests
+"""
+
+
+def get_adapter_manifests(specs):
+    objs = []
+    for s in specs:
+        for obj in s["objects"]:
+            if "manifest" in obj["type"]:
+                objs.append(obj)
+    return objs
+
 """
 Public:
     returns a list of all loader API functions' names

unified-runtime/scripts/templates/manifests.hpp.mako

@@ -0,0 +1,49 @@
+<%!
+from templates import helper as th
+%>/*
+ *
+ * Copyright (C) 2025 Intel Corporation
+ *
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
+ * See LICENSE.TXT
+ *
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+ *
+ * @file ${name}.hpp
+ *
+ */
+
+ // Auto-generated file, do not edit.
+
+#pragma once
+
+#include <string>
+#include <vector>
+
+#include "ur_util.hpp"
+#include <ur_api.h>
+
+namespace ur_loader {
+struct ur_adapter_manifest {
+  std::string name;
+  std::string library;
+  ur_adapter_backend_t backend;
+  std::vector<ur_device_type_t> device_types;
+};
+
+const std::vector<ur_adapter_manifest> ur_adapter_manifests = {
+%for manifest in th.get_adapter_manifests(specs):
+{
+  "${manifest['name']}",
+  MAKE_LIBRARY_NAME("ur_adapter_${manifest['name']}", "0"),
+  ${th.subt(namespace, tags, manifest['backend'])},
+  {
+  %for device_type in manifest['device_types']:
+    ${th.subt(namespace, tags, device_type)},
+  %endfor
+  }
+},
+%endfor
+};
+}

unified-runtime/source/common/ur_util.hpp

@@ -207,14 +207,17 @@ using EnvVarMap = std::map<std::string, std::vector<std::string>>;
 ///             map[param_1] = [value_1, value_2]
 ///             map[param_2] = [value_1]
 /// @param env_var_name name of an environment variable to be parsed
+/// @param reject_empy whether to throw an error on discovering an empty value
+/// @param allow_duplicate whether to allow multiple pairs with the same key
 /// @return std::optional with a possible map with parsed parameters as keys and
 ///         vectors of strings containing parsed values as keys.
 ///         Otherwise, optional is set to std::nullopt when the environment
 ///         variable is not set or is empty.
 /// @throws std::invalid_argument() when the parsed environment variable has
 /// wrong format
 inline std::optional<EnvVarMap> getenv_to_map(const char *env_var_name,
-                                              bool reject_empty = true) {
+                                              bool reject_empty = true,
+                                              bool allow_duplicate = false) {
   char main_delim = ';';
   char key_value_delim = ':';
   char values_delim = ',';
@@ -247,7 +250,7 @@ inline std::optional<EnvVarMap> getenv_to_map(const char *env_var_name,
     std::getline(kv_ss, key, key_value_delim);
     std::getline(kv_ss, values);
     if (key.empty() || (reject_empty && values.empty()) ||
-        map.find(key) != map.end()) {
+        (map.find(key) != map.end() && !allow_duplicate)) {
       throw_wrong_format_map(env_var_name, *env_var);
     }
 
@@ -264,7 +267,11 @@ inline std::optional<EnvVarMap> getenv_to_map(const char *env_var_name,
       }
       values_vec.push_back(value);
     }
-    map[key] = values_vec;
+    if (map.find(key) != map.end()) {
+      map[key].insert(map[key].end(), values_vec.begin(), values_vec.end());
+    } else {
+      map[key] = values_vec;
+    }
   }
   return map;
 }