83 lines · plain
1=======================2Clang SYCL Linker3=======================4 5.. contents::6 :local:7 8.. _clang-sycl-linker:9 10Introduction11============12 13This tool works as a wrapper around the SYCL device code linking process.14The purpose of this tool is to provide an interface to link SYCL device bitcode15in LLVM IR format, SYCL device bitcode in SPIR-V IR format, and native binary16objects, and then use the SPIR-V LLVM Translator tool on fully linked device17objects to produce the final output.18After the linking stage, the fully linked device code in LLVM IR format may19undergo several SYCL-specific finalization steps before the SPIR-V code20generation step.21The tool will also support the Ahead-Of-Time (AOT) compilation flow. AOT22compilation is the process of invoking the back-end at compile time to produce23the final binary, as opposed to just-in-time (JIT) compilation when final code24generation is deferred until application runtime.25 26Device code linking for SYCL offloading has several known quirks that27make it difficult to use in a unified offloading setting. Two of the primary28issues are:291. Several finalization steps are required to be run on the fully linked LLVM30IR bitcode to guarantee conformance to SYCL standards. This step is unique to31the SYCL offloading compilation flow.322. The SPIR-V LLVM Translator tool is an external tool and hence SPIR-V IR code33generation cannot be done as part of LTO. This limitation can be lifted once34the SPIR-V backend is available as a viable LLVM backend.35 36This tool has been proposed to work around these issues.37 38Usage39=====40 41This tool can be used with the following options. Several of these options will42be passed down to downstream tools like 'llvm-link', 'llvm-spirv', etc.43 44.. code-block:: console45 46 OVERVIEW: A utility that wraps around the SYCL device code linking process.47 This enables linking and code generation for SPIR-V JIT targets and AOT48 targets.49 50 USAGE: clang-sycl-linker [options]51 52 OPTIONS:53 --arch <value> Specify the name of the target architecture.54 --dry-run Print generated commands without running.55 -g Specify that this was a debug compile.56 -help-hidden Display all available options57 -help Display available options (--help-hidden for more)58 --library-path=<dir> Set the library path for SYCL device libraries59 --device-libs=<value> A comma separated list of device libraries that are linked during the device link60 -o <path> Path to file to write output61 --save-temps Save intermediate results62 --triple <value> Specify the target triple.63 --version Display the version number and exit64 -v Print verbose information65 -spirv-dump-device-code=<dir> Directory to dump SPIR-V IR code into66 -is-windows-msvc-env Specify if we are compiling under windows environment67 -llvm-spirv-options=<value> Pass options to llvm-spirv tool68 --llvm-spirv-path=<dir> Set the system llvm-spirv path69 70Example71=======72 73This tool is intended to be invoked when targeting any of the target offloading74toolchains. When the --sycl-link option is passed to the clang driver, the75driver will invoke the linking job of the target offloading toolchain, which in76turn will invoke this tool. This tool can be used to create one or more fully77linked device images that are ready to be wrapped and linked with host code to78generate the final executable.79 80.. code-block:: console81 82 clang-sycl-linker --triple spirv64 --arch native input.bc83