140 lines · plain
1====================2Clang Linker Wrapper3====================4 5.. contents::6 :local:7 8.. _clang-linker-wrapper:9 10Introduction11============12 13This tool works as a wrapper of the normal host linking job. This tool is used14to create linked device images for offloading and the necessary runtime calls to15register them. It works by first scanning the linker's input for embedded device16offloading data stored at the ``.llvm.offloading`` section. This section17contains binary data created by the ``llvm-offload-binary`` utility. The18extracted device files will then be linked. The linked modules will then be19wrapped into a new object file containing the code necessary to register it with20the offloading runtime.21 22Usage23=====24 25This tool can be used with the following options. Any arguments not intended26only for the linker wrapper will be forwarded to the wrapped linker job.27 28.. code-block:: console29 30 USAGE: clang-linker-wrapper [options] -- <options to pass to the linker>31 32 OPTIONS:33 --cuda-path=<dir> Set the system CUDA path34 --device-debug Use debugging35 --device-linker=<value> or <triple>=<value>36 Arguments to pass to the device linker invocation37 --dry-run Print program arguments without running38 --help-hidden Display all available options39 --help Display available options (--help-hidden for more)40 --host-triple=<triple> Triple to use for the host compilation41 --linker-path=<path> The linker executable to invoke42 -L <dir> Add <dir> to the library search path43 -l <libname> Search for library <libname>44 --opt-level=<O0, O1, O2, or O3>45 Optimization level for LTO46 --override-image=<kind=file>47 Uses the provided file as if it were the output of the device link step48 -o <path> Path to file to write output49 --pass-remarks-analysis=<value>50 Pass remarks for LTO51 --pass-remarks-missed=<value>52 Pass remarks for LTO53 --pass-remarks=<value> Pass remarks for LTO54 --print-wrapped-module Print the wrapped module's IR for testing55 --ptxas-arg=<value> Argument to pass to the 'ptxas' invocation56 --relocatable Link device code to create a relocatable offloading application57 --save-temps Save intermediate results58 --sysroot<value> Set the system root59 --verbose Verbose output from tools60 --v Display the version number and exit61 -- The separator for the wrapped linker arguments62 63The linker wrapper will generate the appropriate runtime calls to register the64generated device binary with the offloading runtime. To do this step manually we65provide the ``llvm-offload-wrapper`` utility.66 67Relocatable Linking68===================69 70The ``clang-linker-wrapper`` handles linking embedded device code and then71registering it with the appropriate runtime. Normally, this is only done when72the executable is created so other files containing device code can be linked73together. This can be somewhat problematic for users who wish to ship static74libraries that contain offloading code to users without a compatible offloading75toolchain.76 77When using a relocatable link with ``-r``, the ``clang-linker-wrapper`` will78perform the device linking and registration eagerly. This will remove the79embedded device code and register it correctly with the runtime. Semantically,80this is similar to creating a shared library object. If standard relocatable81linking is desired, simply do not run the binaries through the82``clang-linker-wrapper``. This will simply append the embedded device code so83that it can be linked later.84 85Matching86========87 88The linker wrapper will link extracted device code that is compatible with each89other. Generally, this requires that the target triple and architecture match.90An exception is made when the architecture is listed as ``generic``, which will91cause it be linked with any other device code with the same target triple.92 93Debugging94=========95 96The linker wrapper performs a lot of steps internally, such as input matching,97symbol resolution, and image registration. This makes it difficult to debug in98some scenarios. The behavior of the linker-wrapper is controlled mostly through99metadata, described in `clang documentation100<https://clang.llvm.org/docs/OffloadingDesign.html>`_. Intermediate output can101be obtained from the linker-wrapper using the ``--save-temps`` flag. These files102can then be modified.103 104.. code-block:: sh105 106 $> clang openmp.c -fopenmp --offload-arch=gfx90a -c107 $> clang openmp.o -fopenmp --offload-arch=gfx90a -Wl,--save-temps108 $> ; Modify temp files.109 $> llvm-objcopy --update-section=.llvm.offloading=out.bc openmp.o110 111Doing this will allow you to override one of the input files by replacing its112embedded offloading metadata with a user-modified version. However, this will be113more difficult when there are multiple input files. For a very large hammer, the114``--override-image=<kind>=<file>`` flag can be used.115 116In the following example, we use the ``--save-temps`` to obtain the LLVM-IR just117before running the backend. We then modify it to test altered behavior, and then118compile it to a binary. This can then be passed to the linker-wrapper which will119then ignore all embedded metadata and use the provided image as if it were the120result of the device linking phase.121 122.. code-block:: sh123 124 $> clang openmp.c -fopenmp --offload-arch=gfx90a -Wl,--save-temps125 $> ; Modify temp files.126 $> clang --target=amdgcn-amd-amdhsa -mcpu=gfx90a -nogpulib out.bc -o a.out127 $> clang openmp.c -fopenmp --offload-arch=gfx90a -Wl,--override-image=openmp=a.out128 129Example130=======131 132This tool links object files with offloading images embedded within it using the133``-fembed-offload-object`` flag in Clang. Given an input file containing the134magic section we can pass it to this tool to extract the data contained at that135section and run a device linking job on it.136 137.. code-block:: console138 139 clang-linker-wrapper --host-triple=x86_64 --linker-path=/usr/bin/ld -- <Args>140