add UR loader, null adapter and basic example

The components this patch implements are mostly derived from
the ones implemented by level-zero.

This patch otherwise makes only the minimal amount of changes
required for loader:
 - adds new CI that builds the loader
 - updates cmake scripts to build and install the loader
 - adds generate and check-generated custom cmake targets
 - adds a tiny hello-world example to verify loader functionality

Co-authored-by: Brandon Yates <[email protected]>
Co-authored-by: Lisanna Dettwyler <[email protected]>
Co-authored-by: Patryk Kaminski <[email protected]>
Co-authored-by: Krzysztof Swiecicki <[email protected]>

.github/workflows/cmake.yml

@@ -0,0 +1,36 @@
+name: CMake
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+env:
+  BUILD_TYPE: Release
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Install apt package
+      run: sudo apt-get install -y doxygen
+
+    - name: Install pip packages
+      run: pip install -r third_party/requirements.txt
+
+    - name: Configure CMake
+      run: cmake -B ${{github.workspace}}/build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
+
+    - name: Generate source from spec, check for uncommitted diff
+      run: cmake --build ${{github.workspace}}/build --target check-generated
+
+    - name: Build
+      run: cmake --build ${{github.workspace}}/build
+
+    - name: Test
+      working-directory: ${{github.workspace}}/build
+      run: ctest -C ${{env.BUILD_TYPE}} --output-on-failure

.gitignore

@@ -53,6 +53,10 @@
 # Debug files
 scripts/**/*.json
 
+# Python cache
+__pycache__/
+*.py[cod]
+
 # Generated docs
 docs/
 

CHANGELOG.md

@@ -0,0 +1,4 @@
+# Unified Runtime changelog
+
+## v.X.X.X
+* Placeholder for first release

CMakeLists.txt

@@ -1,13 +1,19 @@
-cmake_minimum_required(VERSION 3.2.0 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.8.0 FATAL_ERROR)
 project(unified-runtime VERSION 0.5.0)
 
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)
+include(CTest)
+
+find_package(Python3 COMPONENTS Interpreter)
 
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
 
+# define rpath for libraries so that adapters can be found automatically
+set(CMAKE_BUILD_RPATH "${CMAKE_LIBRARY_OUTPUT_DIRECTORY}")
+
 #Define a path for custom commands to work around MSVC
 set(CUSTOM_COMMAND_BINARY_DIR ${CMAKE_RUNTIME_OUTPUT_DIRECTORY})
 if(MSVC)
@@ -70,6 +76,8 @@ install(
     EXPORT ${PROJECT_NAME}-targets)
 
 add_subdirectory(source)
+add_subdirectory(examples)
+add_subdirectory(test)
 
 # Add the list of installed targets to the install. This includes the namespace
 # which all installed targets will be prefixed with, e.g. for the headers
@@ -90,9 +98,32 @@ configure_package_config_file(
     ${PROJECT_SOURCE_DIR}/cmake/${PROJECT_NAME}-config.cmake.in
     ${PROJECT_BINARY_DIR}/cmake/${PROJECT_NAME}-config.cmake
     INSTALL_DESTINATION lib/cmake/${PROJECT_NAME})
+
 # Add the package files to the install.
 install(
     FILES
         ${PROJECT_BINARY_DIR}/cmake/${PROJECT_NAME}-config.cmake
         ${PROJECT_BINARY_DIR}/cmake/${PROJECT_NAME}-config-version.cmake
     DESTINATION lib/cmake/${PROJECT_NAME})
+
+set(API_JSON_FILE ${PROJECT_BINARY_DIR}/unified_runtime.json)
+
+# generate source from the specification
+add_custom_command (
+    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/scripts
+    DEPENDS ${CMAKE_SOURCE_DIR}/scripts/*
+    OUTPUT ${API_JSON_FILE}
+    COMMAND ${Python3_EXECUTABLE} run.py --api-json ${API_JSON_FILE}
+    COMMAND ${Python3_EXECUTABLE} json2src.py --api-json ${API_JSON_FILE} ${CMAKE_SOURCE_DIR}
+)
+
+add_custom_target(generate ALL
+    DEPENDS ${API_JSON_FILE}
+)
+
+# generate source and check for uncommitted diffs
+add_custom_target(check-generated
+    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+    COMMAND git diff --exit-code
+    DEPENDS generate
+)

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 Intel Corporation
+Copyright (C) 2022 Intel Corporation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,11 +1,15 @@
 # Unified Runtime
 
+[![GHA build status](https://github.com/oneapi-src/unified-runtime/actions/workflows/cmake.yml/badge.svg?branch=main)](https://github.com/oneapi-src/unified-runtime/actions)
+
 ## Contents
 
 This repo contains the following:
 
 - API specification in YaML
 - API programming guide in RST
+- Loader and a null adapter implementation (partially generated)
+- Example applications
 - API C/C++ header files (generated)
 - API Python module (generated)
 - Sample C++ wrapper (generated)
@@ -33,7 +37,7 @@ target_link_libraries(example PUBLIC unified-runtime::headers)
 
 ## Source Code Generation
 
-Code is generated using included [Python scripts](/scripts/README.md).  
+Code is generated using included [Python scripts](/scripts/README.md).
 
 ## Documentation
 
@@ -48,22 +52,31 @@ Tools can be acquired via instructions in [third_party](/third_party/README.md).
 Project is defined using [CMake](https://cmake.org/).
 
 **Windows**:
+
 Generating Visual Studio Project.  EXE and binaries will be in **build/bin/{build_config}**
 
 ~~~~
-mkdir build
-cd build
-cmake {path_to_source_dir} -G "Visual Studio 15 2017 Win64"
+$ mkdir build
+$ cd build
+$ cmake {path_to_source_dir} -G "Visual Studio 15 2017 Win64"
 ~~~~
 
 **Linux**:
 
 Executable and binaries will be in **build/bin**
 
 ~~~~
-mkdir build
-cd build
-cmake {path_to_source_dir}
-make
+$ mkdir build
+$ cd build
+$ cmake {path_to_source_dir}
+$ make
+~~~~
+
+**General**:
+
+If you've made modifications to the specification, you can also run a custom `generate` target prior to building.
+~~~~
+$ make generate
 ~~~~
 
+This call will automatically generate the source code.

SECURITY.md

@@ -0,0 +1,11 @@
+# Security Policy
+
+## Report a Vulnerability
+
+Please report security issues or vulnerabilities to the [Intel Security Center].
+
+For more information on how Intel works to resolve security issues, see [Vulnerability Handling Guidelines].
+
+[Intel Security Center]:https://www.intel.com/security
+
+[Vulnerability Handling Guidelines]:https://www.intel.com/content/www/us/en/security-center/vulnerability-handling-guidelines.html

examples/CMakeLists.txt

@@ -0,0 +1,3 @@
+include_directories(${CMAKE_CURRENT_SOURCE_DIR}/include)
+
+add_subdirectory(hello_world)

examples/hello_world/CMakeLists.txt

@@ -0,0 +1,22 @@
+set(TARGET_NAME hello_world)
+
+add_executable(${TARGET_NAME}
+    ${CMAKE_CURRENT_SOURCE_DIR}/hello_world.cpp
+)
+
+target_include_directories(${TARGET_NAME} PRIVATE
+    ${CMAKE_SOURCE_DIR}/include
+)
+
+if(MSVC)
+    set_target_properties(${TARGET_NAME}
+        PROPERTIES
+            VS_DEBUGGER_COMMAND_ARGUMENTS ""
+            VS_DEBUGGER_WORKING_DIRECTORY "$(OutDir)"
+    )
+endif()
+
+target_link_libraries(${TARGET_NAME}
+    ${PROJECT_NAME}::loader
+    ${CMAKE_DL_LIBS}
+)

examples/hello_world/hello_world.cpp

@@ -0,0 +1,94 @@
+/*
+ *
+ * Copyright (C) 2020-2021 Intel Corporation
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ */
+#include <stdlib.h>
+#include <memory>
+#include <iostream>
+#include <vector>
+
+#include "ur_api.h"
+
+//////////////////////////////////////////////////////////////////////////
+int main(int argc, char *argv[])
+{
+    ur_result_t status;
+
+    ur_platform_handle_t platform = nullptr;
+    ur_device_handle_t pDevice = nullptr;
+
+    // Initialize the platform
+    status = urInit(0, 0);
+    if (status != UR_RESULT_SUCCESS)
+    {
+        std::cout << "urInit failed with return code: " << status << std::endl;
+        return 1;
+    }
+    std::cout << "Platform initialized.\n";
+
+    uint32_t platformCount = 0;
+    std::vector<ur_platform_handle_t> platforms;
+
+    status = urPlatformGet(1, nullptr, &platformCount);
+    if (status != UR_RESULT_SUCCESS)
+    {
+        std::cout << "urPlatformGet failed with return code: " << status << std::endl;
+        goto out;
+    }
+
+    platforms.resize(platformCount);
+    status = urPlatformGet(platformCount, platforms.data(), nullptr);
+    if (status != UR_RESULT_SUCCESS)
+    {
+        std::cout << "urPlatformGet failed with return code: " << status << std::endl;
+        goto out;
+    }
+
+    for (auto p : platforms)
+    {
+        uint32_t deviceCount = 0;
+        status = urDeviceGet(p, UR_DEVICE_TYPE_GPU, 0, nullptr, &deviceCount);
+        if (status != UR_RESULT_SUCCESS)
+        {
+            std::cout << "urDeviceGet failed with return code: " << status << std::endl;
+            goto out;
+        }
+
+        std::vector<ur_device_handle_t> devices(deviceCount);
+        status = urDeviceGet(p, UR_DEVICE_TYPE_GPU, deviceCount, devices.data(), nullptr);
+        if (status != UR_RESULT_SUCCESS)
+        {
+            std::cout << "urDeviceGet failed with return code: " << status << std::endl;
+            goto out;
+        }
+        for (auto d : devices)
+        {
+            ur_device_type_t device_type;
+            status = urDeviceGetInfo(d, UR_DEVICE_INFO_TYPE, sizeof(ur_device_type_t), static_cast<void *>(&device_type), nullptr);
+            if (status != UR_RESULT_SUCCESS)
+            {
+                std::cout << "urDeviceGet failed with return code: " << status << std::endl;
+                goto out;
+            }
+            static const size_t DEVICE_NAME_MAX_LEN = 1024;
+            char device_name[DEVICE_NAME_MAX_LEN] = {0};
+            status = urDeviceGetInfo(d, UR_DEVICE_INFO_NAME, DEVICE_NAME_MAX_LEN - 1, static_cast<void *>(&device_name), nullptr);
+            if (status != UR_RESULT_SUCCESS)
+            {
+                std::cout << "urDeviceGet failed with return code: " << status << std::endl;
+                goto out;
+            }
+            if (device_type == UR_DEVICE_TYPE_GPU)
+            {
+                std::cout << "Found a " << device_name << " gpu.\n";
+            }
+        }
+    }
+
+out:
+    urTearDown(nullptr);
+    return status == UR_RESULT_SUCCESS ? 0 : 1;
+}