[ur] Introduce urinfo tool

`urinfo` is a command-line tool for inspecting the current execution
environment:

```console
$ build/bin/urinfo --help
usage: build/bin/urinfo [-h] [-v] [-V]

This tool enumerates Unified Runtime layers, adapters, platforms, and
devices which are currently visible in the local execution environment.

options:
  -h, --help            show this help message and exit
  --version             show version number and exit
  -v, --verbose         print additional information
```

scripts/generate_code.py

@@ -296,6 +296,25 @@ def _mako_params_hpp(path, namespace, tags, version, specs, meta):
         specs=specs,
         meta=meta)
 
+"""
+Entry-point:
+    generates tools code
+"""
+def _mako_info_hpp(path, namespace, tags, version, specs, meta):
+    fin = os.path.join(templates_dir, "tools-info.hpp.mako")
+    name = f"{namespace}info"
+    filename = f"{name}.hpp"
+    fout = os.path.join(path, filename)
+    print("Generating %s..." % fout)
+    return util.makoWrite(
+        fin, fout,
+        name=name,
+        ver=version,
+        namespace=namespace,
+        tags=tags,
+        specs=specs,
+        meta=meta)
+
 """
 Entry-point:
     generates lib code
@@ -364,3 +383,15 @@ def generate_common(path, section, namespace, tags, version, specs, meta):
     loc += _mako_params_hpp(layer_dstpath, namespace, tags, version, specs, meta)
     print("COMMON Generated %s lines of code.\n"%loc)
 
+"""
+Entry-point:
+    generates tools for unified_runtime
+"""
+def generate_tools(path, section, namespace, tags, version, specs, meta):
+    loc = 0
+
+    infodir = os.path.join(path, f"{namespace}info")
+    os.makedirs(infodir, exist_ok=True)
+    loc += _mako_info_hpp(infodir, namespace, tags, version, specs, meta)
+
+    print("TOOLS Generated %s lines of code.\n" % loc)

scripts/json2src.py

@@ -57,6 +57,7 @@ def strip_loader_meta(meta):
     add_argument(parser, "layers", "generation of layer files.", True)
     add_argument(parser, "adapters", "generation of null adapter files.", True)
     add_argument(parser, "common", "generation of common files.", True)
+    add_argument(parser, "tools", "generation of common files.", True)
     parser.add_argument("--debug", action='store_true', help="dump intermediate data to disk.")
     parser.add_argument("--sections", type=list, default=None, help="Optional list of sections for which to generate source, default is all")
     parser.add_argument("--ver", type=str, default="1.0", help="specification version to generate.")
@@ -69,6 +70,7 @@ def strip_loader_meta(meta):
     start = time.time()
 
     srcpath = os.path.join(args.out_dir, "source")
+    toolspath = os.path.join(args.out_dir, "tools")
 
     for idx, specs in enumerate(input['specs']):
         config = input['configs'][idx]
@@ -86,6 +88,8 @@ def strip_loader_meta(meta):
                 generate_code.generate_adapters(srcpath, config['name'], config['namespace'], config['tags'], args.ver, specs, input['meta'])
             if args.common:
                 generate_code.generate_common(srcpath, config['name'], config['namespace'], config['tags'], args.ver, specs, input['meta'])
+            if args.tools:
+                generate_code.generate_tools(toolspath, config['name'], config['namespace'], config['tags'], args.ver, specs, input['meta'])
 
     if args.debug:
         util.makoFileListWrite("generated.json")

scripts/templates/tools-info.hpp.mako

@@ -0,0 +1,75 @@
+<%!
+import re
+from templates import helper as th
+%><%
+    n=namespace
+    N=n.upper()
+
+    x=tags['$x']
+    X=x.upper()
+%>/*
+ *
+ * Copyright (C) 2023 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}.cpp
+ *
+ */
+
+#pragma once
+
+#include <ur_api.h>
+#include "utils.hpp"
+#include <cstdlib>
+#include <string_view>
+
+namespace urinfo {
+%for obj in th.extract_objs(specs, r"enum"):
+## TODO: For some reason the runtime spec isn't in specs.
+## %if obj["name"] == '$x_loader_config_info_t':
+## inline void printLoaderConfigInfo(${x}_loader_config_t hLoaderConfig,
+##                                   std::string_view prefix = "") {
+## %for etor in obj['etors']:
+## %if 'REFERENCE_COUNT' not in etor['name']:
+##     std::cout << prefix;
+##     printLoaderConfigInfo<${etor['desc'][1:etor['desc'].find(' ')-1].replace('$x', x)}>(hLoaderConfig, ${etor['name'].replace('$X', X)});
+## %endif
+## %endfor
+## }
+## %endif
+%if obj["name"] == '$x_adapter_info_t':
+inline void printAdapterInfos(${x}_adapter_handle_t hAdapter,
+                             std::string_view prefix = "    ") {
+%for etor in obj['etors']:
+%if 'REFERENCE_COUNT' not in etor['name']:
+    std::cout << prefix;
+    printAdapterInfo<${etor['desc'][1:etor['desc'].find(' ')-1].replace('$x', x)}>(hAdapter, ${etor['name'].replace('$X', X)});
+%endif
+%endfor
+}
+
+%endif
+%if obj["name"] == '$x_platform_info_t':
+inline void printPlatformInfos(${x}_platform_handle_t hPlatform,
+                               std::string_view prefix = "        ") {
+%for etor in obj['etors']:
+    std::cout << prefix;
+    printPlatformInfo<${etor['desc'][1:etor['desc'].find(' ')-1].replace('$x', x)}>(hPlatform, ${etor['name'].replace('$X', X)});
+%endfor
+}
+
+%endif
+%if obj['name'] == '$x_device_info_t':
+inline void printDeviceInfos(${x}_device_handle_t hDevice,
+                             std::string_view prefix = "            ") {
+%for etor in obj['etors']:
+    std::cout << prefix;
+    printDeviceInfo<${etor['desc'][1:etor['desc'].find(' ')-1].replace('$x', x)}>(hDevice, ${etor['name'].replace('$X', X)});
+%endfor
+}
+%endif
+%endfor
+}  // namespace urinfo

tools/CMakeLists.txt

@@ -3,8 +3,7 @@
 # See LICENSE.TXT
 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
-include_directories(${CMAKE_CURRENT_SOURCE_DIR}/include)
-
+add_subdirectory(urinfo)
 if(UR_ENABLE_TRACING)
     add_subdirectory(urtrace)
 endif()

tools/urinfo/CMakeLists.txt

@@ -0,0 +1,20 @@
+# Copyright (C) 2023 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
+
+add_executable(urinfo
+    urinfo.hpp
+    utils.hpp
+    urinfo.cpp
+)
+target_compile_definitions(urinfo PRIVATE
+    UR_VERSION="${PROJECT_VERSION}"
+)
+target_include_directories(urinfo PRIVATE
+    ${PROJECT_SOURCE_DIR}/source/common
+)
+target_link_libraries(urinfo PRIVATE
+    ${PROJECT_NAME}::headers
+    ${PROJECT_NAME}::loader
+)

tools/urinfo/urinfo.cpp

@@ -0,0 +1,197 @@
+// Copyright (C) 2023 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
+
+#include "urinfo.hpp"
+#include <cstdlib>
+#include <iostream>
+#include <string>
+#include <string_view>
+#include <unordered_map>
+#include <vector>
+
+namespace urinfo {
+struct app {
+    bool verbose = false;
+    ur_loader_config_handle_t loaderConfig = nullptr;
+    std::vector<ur_adapter_handle_t> adapters;
+    std::unordered_map<ur_adapter_handle_t, std::vector<ur_platform_handle_t>>
+        adapterPlatformsMap;
+    std::unordered_map<ur_platform_handle_t, std::vector<ur_device_handle_t>>
+        platformDevicesMap;
+
+    app(int argc, const char **argv) {
+        parseArgs(argc, argv);
+        UR_CHECK(urLoaderConfigCreate(&loaderConfig));
+        UR_CHECK(urInit(0, loaderConfig));
+        enumerateDevices();
+    }
+
+    void parseArgs(int argc, const char **argv) {
+        static const char *usage = R"(usage: %s [-h] [-v] [-V]
+
+This tool enumerates Unified Runtime layers, adapters, platforms, and
+devices which are currently visible in the local execution environment.
+
+options:
+  -h, --help            show this help message and exit
+  --version             show version number and exit
+  -v, --verbose         print additional information
+)";
+        for (int argi = 1; argi < argc; argi++) {
+            std::string_view arg{argv[argi]};
+            if (arg == "-h" || arg == "--help") {
+                std::printf(usage, argv[0]);
+                std::exit(0);
+            } else if (arg == "--version") {
+                std::printf("%s v%s\n", argv[0], UR_VERSION);
+                std::exit(0);
+            } else if (arg == "-v" || arg == "--verbose") {
+                verbose = true;
+            } else {
+                std::fprintf(stderr, "error: invalid argument: %s\n",
+                             argv[argi]);
+                std::fprintf(stderr, usage, argv[0]);
+                std::exit(1);
+            }
+        }
+    }
+
+    void enumerateDevices() {
+        // Enumerate adapters.
+        uint32_t numAdapters = 0;
+        UR_CHECK(urAdapterGet(0, nullptr, &numAdapters));
+        if (numAdapters == 0) {
+            std::cout << "No adapters found.\n";
+            std::exit(0);
+        }
+        adapters.resize(numAdapters);
+        UR_CHECK(urAdapterGet(numAdapters, adapters.data(), nullptr));
+
+        for (auto adapter : adapters) {
+            // Enumerate platforms
+            uint32_t numPlatforms = 0;
+            UR_CHECK(urPlatformGet(adapters.data(), numAdapters, 0, nullptr,
+                                   &numPlatforms));
+            if (numPlatforms == 0) {
+                std::cout << "No platforms found.\n";
+                std::exit(0);
+            }
+            adapterPlatformsMap[adapter].resize(numAdapters);
+            UR_CHECK(urPlatformGet(adapters.data(), numAdapters, numPlatforms,
+                                   adapterPlatformsMap[adapter].data(),
+                                   nullptr));
+
+            for (auto platform : adapterPlatformsMap[adapter]) {
+                // Enumerate devices
+                uint32_t numDevices = 0;
+                UR_CHECK(urDeviceGet(platform, UR_DEVICE_TYPE_ALL, 0, nullptr,
+                                     &numDevices));
+                if (numDevices == 0) {
+                    std::cout << "No devices found.\n";
+                    continue;
+                }
+                platformDevicesMap[platform].resize(numDevices);
+                UR_CHECK(urDeviceGet(platform, UR_DEVICE_TYPE_ALL, numDevices,
+                                     platformDevicesMap[platform].data(),
+                                     nullptr));
+            }
+        }
+    }
+
+    void printSummary() {
+        for (size_t adapterIndex = 0; adapterIndex < adapters.size();
+             adapterIndex++) {
+            auto adapter = adapters[adapterIndex];
+            auto &platforms = adapterPlatformsMap[adapter];
+            for (size_t platformIndex = 0; platformIndex < platforms.size();
+                 platformIndex++) {
+                auto platform = platforms[platformIndex];
+                auto &devices = platformDevicesMap[platform];
+                for (size_t deviceIndex = 0; deviceIndex < devices.size();
+                     deviceIndex++) {
+                    auto device = devices[deviceIndex];
+                    std::cout << "[adapter(" << adapterIndex << ","
+                              << urinfo::getAdapterBackend(adapter) << "):"
+                              << "platform(" << platformIndex << "):"
+                              << "device(" << deviceIndex << ","
+                              << urinfo::getDeviceType(device) << ")] "
+                              << urinfo::getPlatformName(platform) << ", "
+                              << urinfo::getDeviceName(device) << " "
+                              << urinfo::getDeviceVersion(device) << " "
+                              << "[" << urinfo::getDeviceDriverVersion(device)
+                              << "]\n";
+                }
+            }
+        }
+    }
+
+    void printDetail() {
+        size_t availableLayersSize = 0;
+        UR_CHECK(urLoaderConfigGetInfo(loaderConfig,
+                                       UR_LOADER_CONFIG_INFO_AVAILABLE_LAYERS,
+                                       0, nullptr, &availableLayersSize));
+        // TODO: Generate loader config info printer
+        std::string availableLayers;
+        if (availableLayersSize != 0) {
+            availableLayers.resize(availableLayersSize);
+            UR_CHECK(urLoaderConfigGetInfo(
+                loaderConfig, UR_LOADER_CONFIG_INFO_AVAILABLE_LAYERS,
+                availableLayersSize, availableLayers.data(), nullptr));
+        }
+        std::cout << "\n"
+                  << "[loader]:"
+                  << "\n"
+                  << "  UR_LOADER_CONFIG_INFO_AVAILABLE_LAYERS: "
+                  << availableLayers << "\n";
+
+        std::string adapterPrefix = "  ";
+        std::string platformPrefix = "    ";
+        std::string devicePrefix = "      ";
+
+        for (size_t adapterI = 0; adapterI < adapters.size(); adapterI++) {
+            auto adapter = adapters[adapterI];
+            std::cout << "\n"
+                      << "[adapter(" << adapterI << ")]:"
+                      << "\n";
+            urinfo::printAdapterInfos(adapter, adapterPrefix);
+
+            size_t numPlatforms = adapterPlatformsMap[adapter].size();
+            for (size_t platformI = 0; platformI < numPlatforms; platformI++) {
+                auto platform = adapterPlatformsMap[adapter][platformI];
+                std::cout << "\n"
+                          << "[adapter(" << adapterI << "),"
+                          << "platform(" << platformI << ")]:"
+                          << "\n";
+                urinfo::printPlatformInfos(platform, platformPrefix);
+
+                size_t numDevices = platformDevicesMap[platform].size();
+                for (size_t deviceI = 0; deviceI < numDevices; deviceI++) {
+                    auto device = platformDevicesMap[platform][deviceI];
+                    std::cout << "\n"
+                              << "[adapter(" << adapterI << "),"
+                              << "platform(" << platformI << "),"
+                              << "device(" << deviceI << ")]:"
+                              << "\n";
+                    urinfo::printDeviceInfos(device, devicePrefix);
+                }
+            }
+        }
+    }
+
+    ~app() {
+        UR_CHECK(urLoaderConfigRelease(loaderConfig));
+        UR_CHECK(urTearDown(nullptr));
+    }
+};
+} // namespace urinfo
+
+int main(int argc, const char **argv) {
+    auto app = urinfo::app{argc, argv};
+    app.printSummary();
+    if (app.verbose) {
+        app.printDetail();
+    }
+    return 0;
+}