Clang 卸载打包器¶

简介 ¶

此工具将设备文件捆绑到一个包含必要元数据的单个映像中。我们使用自定义二进制格式将所有设备映像捆绑在一起。映像格式是一个围绕字符串映射的小标题。此工具创建捆绑的二进制文件，以便可以将其嵌入到主机中以创建胖二进制文件。

二进制格式 ¶

二进制格式由 0x10FF10AD 魔术字节标记，后面跟着一个版本。每个创建的二进制文件都包含它自己的魔术字节。这使我们能够即使在链接器可能已将它们合并之后（例如，使用可重定位链接时）也能定位所有嵌入式卸载部分。从概念上讲，此二进制格式是字符串映射和映像缓冲区的序列化。二进制头在以下表中描述。

卸载二进制头¶
类型	标识符	描述
uint8_t	magic	二进制格式的魔术字节（0x10FF10AD）
uint32_t	version	此格式的版本（当前版本 1）
uint64_t	size	此二进制文件的大小（以字节为单位）
uint64_t	entry offset	卸载条目（以字节为单位）的绝对偏移量
uint64_t	entry size	卸载条目（以字节为单位）的大小

一旦通过魔术字节识别，我们使用大小字段获取包含单个卸载映像信息的二进制块的切片。然后，我们可以使用偏移量字段找到包含映像和元数据的实际卸载条目。卸载条目包含有关设备映像的信息。它包含以下表中所示的字段。

卸载条目表¶
类型	标识符	描述
uint16_t	image kind	设备映像的类型（例如 bc、cubin）
uint16_t	offload kind	映像的生产者（例如 openmp、cuda）
uint32_t	flags	映像的通用标志
uint64_t	string offset	字符串元数据表的绝对偏移量
uint64_t	num strings	表中字符串条目的数量
uint64_t	image offset	设备映像（以字节为单位）的绝对偏移量
uint64_t	image size	设备映像（以字节为单位）的大小

此表包含字符串表的偏移量以及设备映像本身的偏移量，以及其他一些整数信息。映像类型使我们能够轻松识别存储在此处的映像类型，而无需检查二进制文件。卸载类型用于确定此映像所需的哪个注册代码或链接语义。这些存储为枚举，卸载类型和映像类型使用以下值。

映像类型¶
名称	值	描述
IMG_None	0x00	未提供映像信息
IMG_Object	0x01	映像是一个通用目标文件
IMG_Bitcode	0x02	映像是一个 LLVM-IR 位代码文件
IMG_Cubin	0x03	映像是一个 CUDA 目标文件
IMG_Fatbinary	0x04	映像是一个 CUDA 胖二进制文件
IMG_PTX	0x05	映像是一个 CUDA PTX 文件

卸载类型¶
名称	值	描述
OFK_None	0x00	未提供卸载信息
OFK_OpenMP	0x01	生产者是 OpenMP 卸载
OFK_CUDA	0x02	生产者是 CUDA
OFK_HIP	0x03	生产者是 HIP

标志用于表示某些条件，例如调试信息的 presence 或是否使用了 LTO。字符串条目表用于一般地包含任何任意键值对。它存储为字符串条目格式的数组。

卸载字符串条目¶
类型	标识符	描述
uint64_t	key offset	字符串表中键的绝对字节偏移量
uint64_t	value offset	字符串表中值的绝对字节偏移量

字符串条目只提供字符串表中键值对的偏移量。字符串表只是一个包含空终止字符串的集合，在映像中定义了偏移量。字符串条目使我们能够从该字符串表中创建键值对。这用于将任意参数传递给映像，例如三元组和架构。

所有这些结构组合在一起形成一个单一的二进制块，由于使用绝对偏移量，顺序无关紧要。这使得将来更容易扩展。如前所述，多个卸载映像通过简单地将它们以这种格式连接在一起进行捆绑。因为我们有了每个映像的魔术字节和大小，所以我们可以根据需要提取它们。

用法 ¶

此工具可以与以下参数一起使用。通常，信息作为键值对传递给 image= 参数。 file 和 triple 参数被认为是创建有效映像的必需参数。建议使用 arch 参数。

OVERVIEW: A utility for bundling several object files into a single binary.
The output binary can then be embedded into the host section table
to create a fatbinary containing offloading code.

USAGE: clang-offload-packager [options]

OPTIONS:

Generic Options:

  --help                      - Display available options (--help-hidden for more)
  --help-list                 - Display list of available options (--help-list-hidden for more)
  --version                   - Display the version of this program

clang-offload-packager options:

  --image=<<key>=<value>,...> - List of key and value arguments. Required
                                keywords are 'file' and 'triple'.
  -o <file>                   - Write output to <file>.

示例 ¶

此工具只是从 image 选项获取许多输入文件，并创建一个包含所有组合映像的单个输出文件。

clang-offload-packager -o out.bin --image=file=input.o,triple=nvptx64,arch=sm_70

相反的操作可以通过将打包的二进制文件作为输入来执行。在此模式下，匹配的映像将被放置在由 file 选项指定的输出中。如果没有提供 file 参数，将为每个匹配的映像生成一个名称。

clang-offload-packager in.bin --image=file=output.o,triple=nvptx64,arch=sm_70

Clang 卸载打包器¶

简介¶

二进制格式¶

用法¶

示例¶

简介 ¶

二进制格式 ¶

用法 ¶

示例 ¶