From 563b80fe96120d2991b5ad3d482eb60a17edf2e0 Mon Sep 17 00:00:00 2001 From: Callum Fare Date: Thu, 17 Jul 2025 17:36:57 +0100 Subject: [PATCH 1/3] [UR][Offload] Add README for the Offload adapter --- .../source/adapters/offload/CMakeLists.txt | 7 +-- .../source/adapters/offload/README.md | 46 +++++++++++++++++++ 2 files changed, 47 insertions(+), 6 deletions(-) create mode 100644 unified-runtime/source/adapters/offload/README.md diff --git a/unified-runtime/source/adapters/offload/CMakeLists.txt b/unified-runtime/source/adapters/offload/CMakeLists.txt index 70336c6b24cd5..423330faf4952 100644 --- a/unified-runtime/source/adapters/offload/CMakeLists.txt +++ b/unified-runtime/source/adapters/offload/CMakeLists.txt @@ -10,11 +10,6 @@ if (UR_OFFLOAD_INSTALL_DIR STREQUAL "") message(FATAL_ERROR "UR_OFFLOAD_INSTALL_DIR must be defined for the Offload adapter") endif() -set(UR_OFFLOAD_INCLUDE_DIR "" CACHE PATH "Path to the directory containing LLVM headers") -if (UR_OFFLOAD_INCLUDE_DIR STREQUAL "") - message(FATAL_ERROR "UR_OFFLOAD_INCLUDE_DIR must be defined for the Offload adapter") -endif() - # When targetting CUDA devices, we need a workaround to avoid sending PTX to # liboffload as the CUDA plugin doesn't support it yet. The workaround is to # simply always link the incoming program so it ends up as CUBIN. Try to find @@ -68,6 +63,6 @@ target_link_libraries(${TARGET_NAME} PRIVATE ) target_include_directories(${TARGET_NAME} PRIVATE - "${UR_OFFLOAD_INCLUDE_DIR}/offload" + "${UR_OFFLOAD_INSTALL_DIR}/include/offload" "${CMAKE_CURRENT_SOURCE_DIR}/../../" ) diff --git a/unified-runtime/source/adapters/offload/README.md b/unified-runtime/source/adapters/offload/README.md new file mode 100644 index 0000000000000..3dc6e5b54e34b --- /dev/null +++ b/unified-runtime/source/adapters/offload/README.md @@ -0,0 +1,46 @@ +# Offload Adapter + +The Offload adapter is an experimental adapter built on top of LLVM's liboffload +runtime. + +The main purpose of the adapter is to drive development of liboffload, and +identify gaps that need addressed for full SYCL support. + +The long-term goal of the project is to replace Unified Runtime with liboffload. + +The adapter should be used with an upstream build of LLVM with the `offload` +runtime enabled. The in-tree version is unlikely to be usable, as there are +frequent breaking API changes. + +## Building upstream LLVM with Offload enabled +The `liboffload` library will be built if the `offload` runtime is enabled. An +example CMake configuration is: +```sh +cmake -S llvm -B build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS='clang;clang-tools-extra;lldb;lld;' -DLLVM_PARALLEL_LINK_JOBS=4 -DLLVM_ENABLE_RUNTIMES='offload;openmp' -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_INSTALL_PREFIX=$PWD/build/install +``` + +Because Offload's API header is generated with tablegen at build time, the +runtime must be installed rather than just built so it gets copied into the +correct location. From either the top-level build or runtime build directory: +```sh +$ ninja install +``` + +## Building the adapter +Build UR/DPC++ with the following additional flags: +``` + -DUR_BUILD_ADAPTER_OFFLOAD=ON + -DUR_OFFLOAD_INSTALL_DIR= +``` + +## Testing the adapter +The adapter can be tested with UR CTS via the +`check-unified-runtime-conformance-offload` target. + +It is also possible to run the SYCL E2E tests by configuring with +```sh + -DSYCL_TEST_E2E_TARGETS=offload:gpu + -DOFFLOAD_BUILD_TARGET= +``` +where `` is one of `target-nvidia` or `target-amdgpu`, depending +on the available device. From 6fd232fc45931cedfd881986d4ddd9a5929051cd Mon Sep 17 00:00:00 2001 From: Callum Fare Date: Thu, 17 Jul 2025 17:52:19 +0100 Subject: [PATCH 2/3] Apply suggestion Co-authored-by: Kenneth Benzie (Benie) --- unified-runtime/source/adapters/offload/README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/unified-runtime/source/adapters/offload/README.md b/unified-runtime/source/adapters/offload/README.md index 3dc6e5b54e34b..760d8522df566 100644 --- a/unified-runtime/source/adapters/offload/README.md +++ b/unified-runtime/source/adapters/offload/README.md @@ -16,7 +16,11 @@ frequent breaking API changes. The `liboffload` library will be built if the `offload` runtime is enabled. An example CMake configuration is: ```sh -cmake -S llvm -B build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS='clang;clang-tools-extra;lldb;lld;' -DLLVM_PARALLEL_LINK_JOBS=4 -DLLVM_ENABLE_RUNTIMES='offload;openmp' -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_INSTALL_PREFIX=$PWD/build/install +cmake -S llvm -B build -GNinja \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_INSTALL_PREFIX=$PWD/build/install + -DLLVM_ENABLE_PROJECTS='clang;clang-tools-extra;lldb;lld;' \ + -DLLVM_ENABLE_RUNTIMES='offload;openmp' ``` Because Offload's API header is generated with tablegen at build time, the From 1c1cfec64a19ea23538ade4d5784c68cc1c190f1 Mon Sep 17 00:00:00 2001 From: Callum Fare Date: Thu, 17 Jul 2025 17:52:31 +0100 Subject: [PATCH 3/3] Apply suggestion Co-authored-by: Kenneth Benzie (Benie) --- unified-runtime/source/adapters/offload/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/unified-runtime/source/adapters/offload/README.md b/unified-runtime/source/adapters/offload/README.md index 760d8522df566..b94e7465b954e 100644 --- a/unified-runtime/source/adapters/offload/README.md +++ b/unified-runtime/source/adapters/offload/README.md @@ -10,7 +10,7 @@ The long-term goal of the project is to replace Unified Runtime with liboffload. The adapter should be used with an upstream build of LLVM with the `offload` runtime enabled. The in-tree version is unlikely to be usable, as there are -frequent breaking API changes. +frequent breaking API changes which happen out-of-sync with pulldowns. ## Building upstream LLVM with Offload enabled The `liboffload` library will be built if the `offload` runtime is enabled. An