llvm-offload-binary - LLVM Offload Binary Packager ================================================== .. program:: llvm-offload-binary SYNOPSIS -------- :program:`llvm-offload-binary` [*options*] [*input files...*] DESCRIPTION ----------- :program:`llvm-offload-binary` is a utility for bundling multiple device object files into a single binary container. The resulting binary can then be embedded into the host section table to form a fat binary containing offloading code for different targets. Conversely, it can also extract previously bundled device images. The binary format begins with the magic bytes ``0x10FF10AD``, followed by a version and size. Each binary contains its own header, allowing tools to locate offloading sections even when merged by a linker. Each offload entry includes metadata such as the device image kind, producer kind, and key-value string metadata. Multiple offloading images are concatenated to form a fat binary. EXAMPLE ------- .. code-block:: console # Package multiple device images into a fat binary: $ llvm-offload-binary -o out.bin \ --image=file=input.o,triple=nvptx64,arch=sm_70 # Extract a matching image from a fat binary: $ llvm-offload-binary in.bin \ --image=file=output.o,triple=nvptx64,arch=sm_70 # Extract and archive images into a static library: $ llvm-offload-binary in.bin --archive -o libdevice.a OPTIONS ------- .. option:: --archive When extracting from an input binary, write all extracted images into a static archive instead of separate files. .. option:: --image=<=,...> Specify a set of arbitrary key-value arguments describing an image. Commonly used optional keys include ``arch`` (e.g. ``sm_70`` for CUDA) and ``triple`` (e.g. nvptx64-nvidia-cuda). .. option:: -o Write output to . When bundling, this specifies the fat binary filename. When extracting, this specifies the archive or output file destination. .. option:: --help, -h Display available options. Use ``--help-hidden`` to show hidden options. .. option:: --help-list Display a list of all options. Use ``--help-list-hidden`` to show hidden ones. .. option:: --version Display the version of the :program:`llvm-offload-binary` executable. .. option:: @ Read command-line options from response file ``. BINARY FORMAT ------------- The binary format is marked by the magic bytes ``0x10FF10AD``, followed by a version number. Each created binary contains its own header. This allows tools to locate offloading sections even after linker operations such as relocatable linking. Conceptually, this binary format is a serialization of a string map and an image buffer. .. table:: Offloading Binary Header :name: table-binary_header +----------+--------------+----------------------------------------------------+ | Type | Identifier | Description | +==========+==============+====================================================+ | uint8_t | magic | The magic bytes for the binary format (0x10FF10AD) | +----------+--------------+----------------------------------------------------+ | uint32_t | version | Version of this format (currently version 1) | +----------+--------------+----------------------------------------------------+ | uint64_t | size | Size of this binary in bytes | +----------+--------------+----------------------------------------------------+ | uint64_t | entry offset | Absolute offset of the offload entries in bytes | +----------+--------------+----------------------------------------------------+ | uint64_t | entry size | Size of the offload entries in bytes | +----------+--------------+----------------------------------------------------+ Each offload entry describes a bundled image along with its associated metadata. .. table:: Offloading Entry Table :name: table-binary_entry +----------+---------------+----------------------------------------------------+ | Type | Identifier | Description | +==========+===============+====================================================+ | uint16_t | image kind | The kind of the device image (e.g. bc, cubin) | +----------+---------------+----------------------------------------------------+ | uint16_t | offload kind | The producer of the image (e.g. openmp, cuda) | +----------+---------------+----------------------------------------------------+ | uint32_t | flags | Generic flags for the image | +----------+---------------+----------------------------------------------------+ | uint64_t | string offset | Absolute offset of the string metadata table | +----------+---------------+----------------------------------------------------+ | uint64_t | num strings | Number of string entries in the table | +----------+---------------+----------------------------------------------------+ | uint64_t | image offset | Absolute offset of the device image in bytes | +----------+---------------+----------------------------------------------------+ | uint64_t | image size | Size of the device image in bytes | +----------+---------------+----------------------------------------------------+ The entry table refers to both a string table and the raw device image itself. The string table provides arbitrary key-value metadata. .. table:: Offloading String Entry :name: table-binary_string +----------+--------------+-------------------------------------------------------+ | Type | Identifier | Description | +==========+==============+=======================================================+ | uint64_t | key offset | Absolute byte offset of the key in the string table | +----------+--------------+-------------------------------------------------------+ | uint64_t | value offset | Absolute byte offset of the value in the string table | +----------+--------------+-------------------------------------------------------+ The string table is a collection of null-terminated strings stored in the image. Offsets allow string entries to be interpreted as key-value pairs, enabling flexible metadata such as architecture or target triple. The enumerated values for ``image kind`` and ``offload kind`` are: .. table:: Image Kind :name: table-image_kind +---------------+-------+---------------------------------------+ | Name | Value | Description | +===============+=======+=======================================+ | IMG_None | 0x00 | No image information provided | +---------------+-------+---------------------------------------+ | IMG_Object | 0x01 | The image is a generic object file | +---------------+-------+---------------------------------------+ | IMG_Bitcode | 0x02 | The image is an LLVM-IR bitcode file | +---------------+-------+---------------------------------------+ | IMG_Cubin | 0x03 | The image is a CUDA object file | +---------------+-------+---------------------------------------+ | IMG_Fatbinary | 0x04 | The image is a CUDA fatbinary file | +---------------+-------+---------------------------------------+ | IMG_PTX | 0x05 | The image is a CUDA PTX file | +---------------+-------+---------------------------------------+ .. table:: Offload Kind :name: table-offload_kind +------------+-------+---------------------------------------+ | Name | Value | Description | +============+=======+=======================================+ | OFK_None | 0x00 | No offloading information provided | +------------+-------+---------------------------------------+ | OFK_OpenMP | 0x01 | The producer was OpenMP offloading | +------------+-------+---------------------------------------+ | OFK_CUDA | 0x02 | The producer was CUDA | +------------+-------+---------------------------------------+ | OFK_HIP | 0x03 | The producer was HIP | +------------+-------+---------------------------------------+ | OFK_SYCL | 0x04 | The producer was SYCL | +------------+-------+---------------------------------------+ SEE ALSO -------- :manpage:`clang(1)`, :manpage:`llvm-objdump(1)`