Skip to content

[UR][Offload] Add README for the Offload adapter and tidy cmake #19504

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: sycl
Choose a base branch
from
Open

[UR][Offload] Add README for the Offload adapter and tidy cmake #19504

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
563b80f
[UR][Offload] Add README for the Offload adapter
callumfare Jul 17, 2025
6fd232f
Apply suggestion
callumfare Jul 17, 2025
1c1cfec
Apply suggestion
callumfare Jul 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 1 addition & 6 deletions unified-runtime/source/adapters/offload/CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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}/../../"
)
50 changes: 50 additions & 0 deletions unified-runtime/source/adapters/offload/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# 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 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
example CMake configuration is:
```sh
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
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=<path to upstream llvm install>
```

## 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=<build-target>
```
where `<build-target>` is one of `target-nvidia` or `target-amdgpu`, depending
on the available device.
Loading