Clang 链接器包装器¶

简介 ¶

此工具作为正常主机链接作业的包装器。该工具用于为卸载创建链接的设备映像，以及注册这些映像所需的运行时调用。它的工作原理是首先扫描链接器的输入，以查找存储在 .llvm.offloading 部分的嵌入式设备卸载数据。此部分包含由 Clang 卸载打包器创建的二进制数据。然后将提取的设备文件链接起来。然后，将链接的模块包装到一个新的目标文件中，该目标文件包含在卸载运行时注册它所需的代码。

用法 ¶

此工具可以使用以下选项。任何不专用于链接器包装器的参数将被转发到包装的链接器作业。

USAGE: clang-linker-wrapper [options] -- <options to passed to the linker>

OPTIONS:
  --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
  --override-image=<kind=file>
                          Uses the provided file as if it were the output of the device link step
  -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
  --relocatable           Link device code to create a relocatable offloading application
  --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

可重定位链接 ¶

clang-linker-wrapper 处理链接嵌入式设备代码，然后将其注册到相应的运行时。通常，这仅在创建可执行文件时完成，以便可以将包含设备代码的其他文件链接在一起。对于希望将包含卸载代码的静态库交付给没有兼容卸载工具链的用户来说，这可能有点问题。

当使用 -r 进行可重定位链接时，clang-linker-wrapper 将积极地执行设备链接和注册。这将删除嵌入式设备代码并将其正确注册到运行时。从语义上讲，这类似于创建共享库对象。如果需要标准的可重定位链接，只需不要通过 clang-linker-wrapper 运行二进制文件即可。这只会附加嵌入式设备代码，以便以后可以链接它。

匹配 ¶

链接器包装器将链接彼此兼容的提取的设备代码。通常，这要求目标三元组和体系结构匹配。当体系结构列为 generic 时会例外，这将导致它与具有相同目标三元组的任何其他设备代码链接在一起。

调试 ¶

链接器包装器在内部执行许多步骤，例如输入匹配、符号解析和映像注册。这使得在某些情况下难以调试。链接器包装器的行为主要通过元数据控制，如 clang 文档中所述。可以使用 --save-temps 标志从链接器包装器获取中间输出。然后可以修改这些文件。

$> 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

这样做将允许您通过用用户修改的版本替换其嵌入式卸载元数据来覆盖输入文件之一。但是，当有多个输入文件时，这将更加困难。对于非常大的锤子，可以使用 --override-image=<kind>=<file> 标志。

在以下示例中，我们使用 --save-temps 在运行后端之前获取 LLVM-IR。然后我们修改它以测试更改后的行为，然后将其编译为二进制文件。然后将其传递给链接器包装器，它将忽略所有嵌入式元数据，并将提供的映像用作设备链接阶段的结果。

$> 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 中的 -fembed-offload-object 标志链接包含嵌入式卸载映像的目标文件。给定包含魔术部分的输入文件，我们可以将其传递给此工具以提取该部分中包含的数据，并在其上运行设备链接作业。

clang-linker-wrapper --host-triple=x86_64 --linker-path=/usr/bin/ld -- <Args>