clang/docs/ClangSYCLLinker.rst

   1 =======================
   2 Clang SYCL Linker
   3 =======================
   4
   5 .. contents::
   6    :local:
   7
   8 .. _clang-sycl-linker:
   9
  10 Introduction
  11 ============
  12
  13 This tool works as a wrapper around the SYCL device code linking process.
  14 The purpose of this tool is to provide an interface to link SYCL device bitcode
  15 in LLVM IR format, SYCL device bitcode in SPIR-V IR format, and native binary
  16 objects, and then use the SPIR-V LLVM Translator tool on fully linked device
  17 objects to produce the final output.
  18 After the linking stage, the fully linked device code in LLVM IR format may
  19 undergo several SYCL-specific finalization steps before the SPIR-V code
  20 generation step.
  21 The tool will also support the Ahead-Of-Time (AOT) compilation flow. AOT
  22 compilation is the process of invoking the back-end at compile time to produce
  23 the final binary, as opposed to just-in-time (JIT) compilation when final code
  24 generation is deferred until application runtime.
  25
  26 Device code linking for SYCL offloading has several known quirks that
  27 make it difficult to use in a unified offloading setting. Two of the primary
  28 issues are:
  29 1. Several finalization steps are required to be run on the fully linked LLVM
  30 IR bitcode to guarantee conformance to SYCL standards. This step is unique to
  31 the SYCL offloading compilation flow.
  32 2. The SPIR-V LLVM Translator tool is an external tool and hence SPIR-V IR code
  33 generation cannot be done as part of LTO. This limitation can be lifted once
  34 the SPIR-V backend is available as a viable LLVM backend.
  35
  36 This tool has been proposed to work around these issues.
  37
  38 Usage
  39 =====
  40
  41 This tool can be used with the following options. Several of these options will
  42 be passed down to downstream tools like 'llvm-link', 'llvm-spirv', etc.
  43
  44 .. code-block:: console
  45
  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 AOT
  48   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 options
  57     -help                         Display available options (--help-hidden for more)
  58     --library-path=<dir>          Set the library path for SYCL device libraries
  59     --device-libs=<value>         A comma separated list of device libraries that are linked during the device link
  60     -o <path>                     Path to file to write output
  61     --save-temps                  Save intermediate results
  62     --triple <value>              Specify the target triple.
  63     --version                     Display the version number and exit
  64     -v                            Print verbose information
  65     -spirv-dump-device-code=<dir> Directory to dump SPIR-V IR code into
  66     -is-windows-msvc-env          Specify if we are compiling under windows environment
  67     -llvm-spirv-options=<value>   Pass options to llvm-spirv tool
  68     --llvm-spirv-path=<dir>       Set the system llvm-spirv path
  69
  70 Example
  71 =======
  72
  73 This tool is intended to be invoked when targeting any of the target offloading
  74 toolchains. When the --sycl-link option is passed to the clang driver, the
  75 driver will invoke the linking job of the target offloading toolchain, which in
  76 turn will invoke this tool. This tool can be used to create one or more fully
  77 linked device images that are ready to be wrapped and linked with host code to
  78 generate the final executable.
  79
  80 .. code-block:: console
  81
  82   clang-sycl-linker --triple spirv64 --arch native input.bc