mirrors/llvm-project
0
0
Fork 0
mirror of https://github.com/llvm/llvm-project.git synced 2025-04-22 10:06:08 +00:00
Code Issues Projects Releases Wiki Activity
main
llvm-project/clang/docs/ClangLinkerWrapper.rst

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

136 lines
5.8 KiB
ReStructuredText
Raw Permalink Normal View History

[Clang] Introduce Clang Linker Wrapper Tool This patch introduces a linker wrapper tool that allows us to preprocess files before they are sent to the linker. This adds a dummy action and job to the driver stage that builds the linker command as usual and then replaces the command line with the wrapper tool. Depends on D116543 Reviewed By: JonChesterfield Differential Revision: https://reviews.llvm.org/D116544
2021-12-30 16:41:36 -05:00
====================
Clang Linker Wrapper
====================
.. contents::
:local:
.. _clang-linker-wrapper:
Introduction
============
[Clang][Docs] Update the clang-linker-wrapper documentation.
2022-07-08 14:29:04 -04:00
This tool works as a wrapper of the normal host linking job. This tool is used
to create linked device images for offloading and the necessary runtime calls to
register them. It works by first scanning the linker's input for embedded device
offloading data stored at the ``.llvm.offloading`` section. This section
contains binary data created by the :doc:`ClangOffloadPackager`. The extracted
device files will then be linked. The linked modules will then be wrapped into a
new object file containing the code necessary to register it with the offloading
runtime.
[Clang] Introduce Clang Linker Wrapper Tool This patch introduces a linker wrapper tool that allows us to preprocess files before they are sent to the linker. This adds a dummy action and job to the driver stage that builds the linker command as usual and then replaces the command line with the wrapper tool. Depends on D116543 Reviewed By: JonChesterfield Differential Revision: https://reviews.llvm.org/D116544
2021-12-30 16:41:36 -05:00
Usage
=====
[Clang][Docs] Update the clang-linker-wrapper documentation.
2022-07-08 14:29:04 -04:00
This tool can be used with the following options. Any arguments not intended
only for the linker wrapper will be forwarded to the wrapped linker job.
[Clang] Introduce Clang Linker Wrapper Tool This patch introduces a linker wrapper tool that allows us to preprocess files before they are sent to the linker. This adds a dummy action and job to the driver stage that builds the linker command as usual and then replaces the command line with the wrapper tool. Depends on D116543 Reviewed By: JonChesterfield Differential Revision: https://reviews.llvm.org/D116544
2021-12-30 16:41:36 -05:00
.. code-block:: console
[Clang][Docs] Update the clang-linker-wrapper documentation.
2022-07-08 14:29:04 -04:00
USAGE: clang-linker-wrapper [options] -- <options to passed to the linker>
[clang][NFC] Remove trailing whitespaces and enforce it in lib, include and docs A lot of editors remove trailing whitespaces. This patch removes any trailing whitespaces and makes sure that no new ones are added. Reviewed By: erichkeane, paulkirth, #libc, philnik Spies: wangpc, aheejin, MaskRay, pcwang-thead, cfe-commits, libcxx-commits, dschuff, nemanjai, arichardson, kbarton, asb, rbar, johnrusso, simoncook, sabuasal, niosHD, jrtc27, zzheng, edward-jones, rogfer01, MartinMosbeck, brucehoult, the_o, PkmX, jocewei, Jim, s.egerton, sameer.abuasal, apazos, luismarques, martong, frasercrmck, steakhal, luke Differential Revision: https://reviews.llvm.org/D151963
2023-06-25 18:59:56 -07:00
[Clang] Introduce Clang Linker Wrapper Tool This patch introduces a linker wrapper tool that allows us to preprocess files before they are sent to the linker. This adds a dummy action and job to the driver stage that builds the linker command as usual and then replaces the command line with the wrapper tool. Depends on D116543 Reviewed By: JonChesterfield Differential Revision: https://reviews.llvm.org/D116544
2021-12-30 16:41:36 -05:00
OPTIONS:
[Clang][Docs] Update the clang-linker-wrapper documentation.
2022-07-08 14:29:04 -04:00
--cuda-path=<dir> Set the system CUDA path
--device-debug Use debugging
--device-linker=<value> or <triple>=<value>
Arguments to pass to the device linker invocation
--dry-run Print program arguments without running
--help-hidden Display all available options
--help Display available options (--help-hidden for more)
--host-triple=<triple> Triple to use for the host compilation
--linker-path=<path> The linker executable to invoke
-L <dir> Add <dir> to the library search path
-l <libname> Search for library <libname>
--opt-level=<O0, O1, O2, or O3>
Optimization level for LTO
[LinkerWrapper] Add an overriding option for debugging (#91984) Summary: One of the downsides of the linker wrapper is that it made debugging more difficult. It is very powerful in that it can resolve a lot of input matching and library handling that could not be done before. However, the old method allowed users to simply copy-paste the script files to modify the output and test it. This patch attempts to make it easier to debug changes by letting the user override all the linker inputs. That is, we provide a user-created binary that is treated like the final output of the device link step. The intended use-case is for using `-save-temps` to get some IR, then modifying the IR and sticking it back in to see if it exhibits the old failures.
2024-05-14 18:39:48 -05:00
--override-image=<kind=file>
Uses the provided file as if it were the output of the device link step
[Clang][Docs] Update the clang-linker-wrapper documentation.
2022-07-08 14:29:04 -04:00
-o <path> Path to file to write output
--pass-remarks-analysis=<value>
Pass remarks for LTO
--pass-remarks-missed=<value>
Pass remarks for LTO
--pass-remarks=<value> Pass remarks for LTO
--print-wrapped-module Print the wrapped module's IR for testing
--ptxas-arg=<value> Argument to pass to the 'ptxas' invocation
[LinkerWrapper] Support relocatable linking for offloading (#80066) Summary: The standard GPU compilation process embeds each intermediate object file into the host file at the `.llvm.offloading` section so it can be linked later. We also use a special section called something like `omp_offloading_entries` to store all the globals that need to be registered by the runtime. The linker-wrapper's job is to link the embedded device code stored at this section and then emit code to register the linked image and the kernels and globals in the offloading entry section. One downside to RDC linking is that it can become quite big for very large projects that wish to make use of static linking. This patch changes the support for relocatable linking via `-r` to support a kind of "partial" RDC compilation for offloading languages. This primarily requires manually editing the embedded data in the output object file for the relocatable link. We need to rename the output section to make it distinct from the input sections that will be merged. We then delete the old embedded object code so it won't be linked further. We then need to rename the old offloading section so that it is private to the module. A runtime solution could also be done to defer entries that don't belong to the given GPU executable, but this is easier. Note that this does not work with COFF linking, only the ELF method for handling offloading entries, that could be made to work similarly. Given this support, the following compilation path should produce two distinct images for OpenMP offloading. ``` $ clang foo.c -fopenmp --offload-arch=native -c $ clang foo.c -lomptarget.devicertl --offload-link -r -o merged.o $ clang main.c merged.o -fopenmp --offload-arch=native $ ./a.out ``` Or similarly for HIP to effectively perform non-RDC mode compilation for a subset of files. ``` $ clang -x hip foo.c --offload-arch=native --offload-new-driver -fgpu-rdc -c $ clang -x hip foo.c -lomptarget.devicertl --offload-link -r -o merged.o $ clang -x hip main.c merged.o --offload-arch=native --offload-new-driver -fgpu-rdc $ ./a.out ``` One question is whether or not this should be the default behavior of `-r` when run through the linker-wrapper or a special option. Standard `-r` behavior is still possible if used without invoking the linker-wrapper and it guaranteed to be correct.
2024-02-07 08:20:07 -06:00
--relocatable Link device code to create a relocatable offloading application
[Clang][Docs] Update the clang-linker-wrapper documentation.
2022-07-08 14:29:04 -04:00
--save-temps Save intermediate results
--sysroot<value> Set the system root
--verbose Verbose output from tools
--v Display the version number and exit
-- The separator for the wrapped linker arguments
[LinkerWrapper] Support relocatable linking for offloading (#80066) Summary: The standard GPU compilation process embeds each intermediate object file into the host file at the `.llvm.offloading` section so it can be linked later. We also use a special section called something like `omp_offloading_entries` to store all the globals that need to be registered by the runtime. The linker-wrapper's job is to link the embedded device code stored at this section and then emit code to register the linked image and the kernels and globals in the offloading entry section. One downside to RDC linking is that it can become quite big for very large projects that wish to make use of static linking. This patch changes the support for relocatable linking via `-r` to support a kind of "partial" RDC compilation for offloading languages. This primarily requires manually editing the embedded data in the output object file for the relocatable link. We need to rename the output section to make it distinct from the input sections that will be merged. We then delete the old embedded object code so it won't be linked further. We then need to rename the old offloading section so that it is private to the module. A runtime solution could also be done to defer entries that don't belong to the given GPU executable, but this is easier. Note that this does not work with COFF linking, only the ELF method for handling offloading entries, that could be made to work similarly. Given this support, the following compilation path should produce two distinct images for OpenMP offloading. ``` $ clang foo.c -fopenmp --offload-arch=native -c $ clang foo.c -lomptarget.devicertl --offload-link -r -o merged.o $ clang main.c merged.o -fopenmp --offload-arch=native $ ./a.out ``` Or similarly for HIP to effectively perform non-RDC mode compilation for a subset of files. ``` $ clang -x hip foo.c --offload-arch=native --offload-new-driver -fgpu-rdc -c $ clang -x hip foo.c -lomptarget.devicertl --offload-link -r -o merged.o $ clang -x hip main.c merged.o --offload-arch=native --offload-new-driver -fgpu-rdc $ ./a.out ``` One question is whether or not this should be the default behavior of `-r` when run through the linker-wrapper or a special option. Standard `-r` behavior is still possible if used without invoking the linker-wrapper and it guaranteed to be correct.
2024-02-07 08:20:07 -06:00
Relocatable Linking
===================
[Clang][Docs] Fix trailing whitespace warnings
2024-02-07 13:03:14 -06:00
The ``clang-linker-wrapper`` handles linking embedded device code and then
registering it with the appropriate runtime. Normally, this is only done when
the executable is created so other files containing device code can be linked
together. This can be somewhat problematic for users who wish to ship static
libraries that contain offloading code to users without a compatible offloading
[LinkerWrapper] Support relocatable linking for offloading (#80066) Summary: The standard GPU compilation process embeds each intermediate object file into the host file at the `.llvm.offloading` section so it can be linked later. We also use a special section called something like `omp_offloading_entries` to store all the globals that need to be registered by the runtime. The linker-wrapper's job is to link the embedded device code stored at this section and then emit code to register the linked image and the kernels and globals in the offloading entry section. One downside to RDC linking is that it can become quite big for very large projects that wish to make use of static linking. This patch changes the support for relocatable linking via `-r` to support a kind of "partial" RDC compilation for offloading languages. This primarily requires manually editing the embedded data in the output object file for the relocatable link. We need to rename the output section to make it distinct from the input sections that will be merged. We then delete the old embedded object code so it won't be linked further. We then need to rename the old offloading section so that it is private to the module. A runtime solution could also be done to defer entries that don't belong to the given GPU executable, but this is easier. Note that this does not work with COFF linking, only the ELF method for handling offloading entries, that could be made to work similarly. Given this support, the following compilation path should produce two distinct images for OpenMP offloading. ``` $ clang foo.c -fopenmp --offload-arch=native -c $ clang foo.c -lomptarget.devicertl --offload-link -r -o merged.o $ clang main.c merged.o -fopenmp --offload-arch=native $ ./a.out ``` Or similarly for HIP to effectively perform non-RDC mode compilation for a subset of files. ``` $ clang -x hip foo.c --offload-arch=native --offload-new-driver -fgpu-rdc -c $ clang -x hip foo.c -lomptarget.devicertl --offload-link -r -o merged.o $ clang -x hip main.c merged.o --offload-arch=native --offload-new-driver -fgpu-rdc $ ./a.out ``` One question is whether or not this should be the default behavior of `-r` when run through the linker-wrapper or a special option. Standard `-r` behavior is still possible if used without invoking the linker-wrapper and it guaranteed to be correct.
2024-02-07 08:20:07 -06:00
toolchain.
[Clang][Docs] Fix trailing whitespace warnings
2024-02-07 13:03:14 -06:00
When using a relocatable link with ``-r``, the ``clang-linker-wrapper`` will
perform the device linking and registration eagerly. This will remove the
embedded device code and register it correctly with the runtime. Semantically,
this is similar to creating a shared library object. If standard relocatable
linking is desired, simply do not run the binaries through the
``clang-linker-wrapper``. This will simply append the embedded device code so
[LinkerWrapper] Support relocatable linking for offloading (#80066) Summary: The standard GPU compilation process embeds each intermediate object file into the host file at the `.llvm.offloading` section so it can be linked later. We also use a special section called something like `omp_offloading_entries` to store all the globals that need to be registered by the runtime. The linker-wrapper's job is to link the embedded device code stored at this section and then emit code to register the linked image and the kernels and globals in the offloading entry section. One downside to RDC linking is that it can become quite big for very large projects that wish to make use of static linking. This patch changes the support for relocatable linking via `-r` to support a kind of "partial" RDC compilation for offloading languages. This primarily requires manually editing the embedded data in the output object file for the relocatable link. We need to rename the output section to make it distinct from the input sections that will be merged. We then delete the old embedded object code so it won't be linked further. We then need to rename the old offloading section so that it is private to the module. A runtime solution could also be done to defer entries that don't belong to the given GPU executable, but this is easier. Note that this does not work with COFF linking, only the ELF method for handling offloading entries, that could be made to work similarly. Given this support, the following compilation path should produce two distinct images for OpenMP offloading. ``` $ clang foo.c -fopenmp --offload-arch=native -c $ clang foo.c -lomptarget.devicertl --offload-link -r -o merged.o $ clang main.c merged.o -fopenmp --offload-arch=native $ ./a.out ``` Or similarly for HIP to effectively perform non-RDC mode compilation for a subset of files. ``` $ clang -x hip foo.c --offload-arch=native --offload-new-driver -fgpu-rdc -c $ clang -x hip foo.c -lomptarget.devicertl --offload-link -r -o merged.o $ clang -x hip main.c merged.o --offload-arch=native --offload-new-driver -fgpu-rdc $ ./a.out ``` One question is whether or not this should be the default behavior of `-r` when run through the linker-wrapper or a special option. Standard `-r` behavior is still possible if used without invoking the linker-wrapper and it guaranteed to be correct.
2024-02-07 08:20:07 -06:00
that it can be linked later.
[Clang] Introduce Clang Linker Wrapper Tool This patch introduces a linker wrapper tool that allows us to preprocess files before they are sent to the linker. This adds a dummy action and job to the driver stage that builds the linker command as usual and then replaces the command line with the wrapper tool. Depends on D116543 Reviewed By: JonChesterfield Differential Revision: https://reviews.llvm.org/D116544
2021-12-30 16:41:36 -05:00
[LinkerWrapper][NFC] Rename 'all' to 'generic' for architecture agnostic IR Summary: A previous patch introduced `all` as a special architecture. I have decided I do not like this name and have changed it to `generic`.
2024-02-12 08:14:54 -06:00
Matching
========
The linker wrapper will link extracted device code that is compatible with each
other. Generally, this requires that the target triple and architecture match.
An exception is made when the architecture is listed as ``generic``, which will
cause it be linked with any other device code with the same target triple.
[LinkerWrapper] Add an overriding option for debugging (#91984) Summary: One of the downsides of the linker wrapper is that it made debugging more difficult. It is very powerful in that it can resolve a lot of input matching and library handling that could not be done before. However, the old method allowed users to simply copy-paste the script files to modify the output and test it. This patch attempts to make it easier to debug changes by letting the user override all the linker inputs. That is, we provide a user-created binary that is treated like the final output of the device link step. The intended use-case is for using `-save-temps` to get some IR, then modifying the IR and sticking it back in to see if it exhibits the old failures.
2024-05-14 18:39:48 -05:00
Debugging
=========
The linker wrapper performs a lot of steps internally, such as input matching,
symbol resolution, and image registration. This makes it difficult to debug in
some scenarios. The behavior of the linker-wrapper is controlled mostly through
metadata, described in `clang documentation
<https://clang.llvm.org/docs/OffloadingDesign.html>`_. Intermediate output can
be obtained from the linker-wrapper using the ``--save-temps`` flag. These files
can then be modified.
.. code-block:: sh
$> clang openmp.c -fopenmp --offload-arch=gfx90a -c
$> clang openmp.o -fopenmp --offload-arch=gfx90a -Wl,--save-temps
$> ; Modify temp files.
$> llvm-objcopy --update-section=.llvm.offloading=out.bc openmp.o
Doing this will allow you to override one of the input files by replacing its
embedded offloading metadata with a user-modified version. However, this will be
more difficult when there are multiple input files. For a very large hammer, the
``--override-image=<kind>=<file>`` flag can be used.
In the following example, we use the ``--save-temps`` to obtain the LLVM-IR just
before running the backend. We then modify it to test altered behavior, and then
compile it to a binary. This can then be passed to the linker-wrapper which will
then ignore all embedded metadata and use the provided image as if it were the
result of the device linking phase.
.. code-block:: sh
$> clang openmp.c -fopenmp --offload-arch=gfx90a -Wl,--save-temps
$> ; Modify temp files.
$> clang --target=amdgcn-amd-amdhsa -mcpu=gfx90a -nogpulib out.bc -o a.out
$> clang openmp.c -fopenmp --offload-arch=gfx90a -Wl,--override-image=openmp=a.out
[Clang] Introduce Clang Linker Wrapper Tool This patch introduces a linker wrapper tool that allows us to preprocess files before they are sent to the linker. This adds a dummy action and job to the driver stage that builds the linker command as usual and then replaces the command line with the wrapper tool. Depends on D116543 Reviewed By: JonChesterfield Differential Revision: https://reviews.llvm.org/D116544
2021-12-30 16:41:36 -05:00
Example
=======
This tool links object files with offloading images embedded within it using the
``-fembed-offload-object`` flag in Clang. Given an input file containing the
magic section we can pass it to this tool to extract the data contained at that
section and run a device linking job on it.
.. code-block:: console
[Clang][Docs] Update the clang-linker-wrapper documentation.
2022-07-08 14:29:04 -04:00
clang-linker-wrapper --host-triple=x86_64 --linker-path=/usr/bin/ld -- <Args>
Reference in New Issue Copy Permalink