186 lines · plain
1llvm-offload-binary - LLVM Offload Binary Packager2==================================================3 4.. program:: llvm-offload-binary5 6SYNOPSIS7--------8 9:program:`llvm-offload-binary` [*options*] [*input files...*]10 11DESCRIPTION12-----------13 14:program:`llvm-offload-binary` is a utility for bundling multiple device object15files into a single binary container. The resulting binary can then be embedded16into the host section table to form a fat binary containing offloading code for17different targets. Conversely, it can also extract previously bundled device18images.19 20The binary format begins with the magic bytes ``0x10FF10AD``, followed by a21version and size. Each binary contains its own header, allowing tools to locate22offloading sections even when merged by a linker. Each offload entry includes23metadata such as the device image kind, producer kind, and key-value string24metadata. Multiple offloading images are concatenated to form a fat binary.25 26EXAMPLE27-------28 29.. code-block:: console30 31 # Package multiple device images into a fat binary:32 $ llvm-offload-binary -o out.bin \33 --image=file=input.o,triple=nvptx64,arch=sm_7034 35 # Extract a matching image from a fat binary:36 $ llvm-offload-binary in.bin \37 --image=file=output.o,triple=nvptx64,arch=sm_7038 39 # Extract and archive images into a static library:40 $ llvm-offload-binary in.bin --archive -o libdevice.a41 42OPTIONS43-------44 45.. option:: --archive46 47 When extracting from an input binary, write all extracted images into a static48 archive instead of separate files.49 50.. option:: --image=<<key>=<value>,...>51 52 Specify a set of arbitrary key-value arguments describing an image.53 Commonly used optional keys include ``arch`` (e.g. ``sm_70`` for CUDA) and54 ``triple`` (e.g. nvptx64-nvidia-cuda).55 56.. option:: -o <file>57 58 Write output to <file>. When bundling, this specifies the fat binary filename.59 When extracting, this specifies the archive or output file destination.60 61.. option:: --help, -h62 63 Display available options. Use ``--help-hidden`` to show hidden options.64 65.. option:: --help-list66 67 Display a list of all options. Use ``--help-list-hidden`` to show hidden ones.68 69.. option:: --version70 71 Display the version of the :program:`llvm-offload-binary` executable.72 73.. option:: @<FILE>74 75 Read command-line options from response file `<FILE>`.76 77BINARY FORMAT78-------------79 80The binary format is marked by the magic bytes ``0x10FF10AD``, followed by a81version number. Each created binary contains its own header. This allows tools82to locate offloading sections even after linker operations such as relocatable83linking. Conceptually, this binary format is a serialization of a string map and84an image buffer.85 86.. table:: Offloading Binary Header87 :name: table-binary_header88 89 +----------+--------------+----------------------------------------------------+90 | Type | Identifier | Description |91 +==========+==============+====================================================+92 | uint8_t | magic | The magic bytes for the binary format (0x10FF10AD) |93 +----------+--------------+----------------------------------------------------+94 | uint32_t | version | Version of this format (currently version 1) |95 +----------+--------------+----------------------------------------------------+96 | uint64_t | size | Size of this binary in bytes |97 +----------+--------------+----------------------------------------------------+98 | uint64_t | entry offset | Absolute offset of the offload entries in bytes |99 +----------+--------------+----------------------------------------------------+100 | uint64_t | entry size | Size of the offload entries in bytes |101 +----------+--------------+----------------------------------------------------+102 103Each offload entry describes a bundled image along with its associated metadata.104 105.. table:: Offloading Entry Table106 :name: table-binary_entry107 108 +----------+---------------+----------------------------------------------------+109 | Type | Identifier | Description |110 +==========+===============+====================================================+111 | uint16_t | image kind | The kind of the device image (e.g. bc, cubin) |112 +----------+---------------+----------------------------------------------------+113 | uint16_t | offload kind | The producer of the image (e.g. openmp, cuda) |114 +----------+---------------+----------------------------------------------------+115 | uint32_t | flags | Generic flags for the image |116 +----------+---------------+----------------------------------------------------+117 | uint64_t | string offset | Absolute offset of the string metadata table |118 +----------+---------------+----------------------------------------------------+119 | uint64_t | num strings | Number of string entries in the table |120 +----------+---------------+----------------------------------------------------+121 | uint64_t | image offset | Absolute offset of the device image in bytes |122 +----------+---------------+----------------------------------------------------+123 | uint64_t | image size | Size of the device image in bytes |124 +----------+---------------+----------------------------------------------------+125 126The entry table refers to both a string table and the raw device image itself.127The string table provides arbitrary key-value metadata.128 129.. table:: Offloading String Entry130 :name: table-binary_string131 132 +----------+--------------+-------------------------------------------------------+133 | Type | Identifier | Description |134 +==========+==============+=======================================================+135 | uint64_t | key offset | Absolute byte offset of the key in the string table |136 +----------+--------------+-------------------------------------------------------+137 | uint64_t | value offset | Absolute byte offset of the value in the string table |138 +----------+--------------+-------------------------------------------------------+139 140The string table is a collection of null-terminated strings stored in the image.141Offsets allow string entries to be interpreted as key-value pairs, enabling142flexible metadata such as architecture or target triple.143 144The enumerated values for ``image kind`` and ``offload kind`` are:145 146.. table:: Image Kind147 :name: table-image_kind148 149 +---------------+-------+---------------------------------------+150 | Name | Value | Description |151 +===============+=======+=======================================+152 | IMG_None | 0x00 | No image information provided |153 +---------------+-------+---------------------------------------+154 | IMG_Object | 0x01 | The image is a generic object file |155 +---------------+-------+---------------------------------------+156 | IMG_Bitcode | 0x02 | The image is an LLVM-IR bitcode file |157 +---------------+-------+---------------------------------------+158 | IMG_Cubin | 0x03 | The image is a CUDA object file |159 +---------------+-------+---------------------------------------+160 | IMG_Fatbinary | 0x04 | The image is a CUDA fatbinary file |161 +---------------+-------+---------------------------------------+162 | IMG_PTX | 0x05 | The image is a CUDA PTX file |163 +---------------+-------+---------------------------------------+164 165.. table:: Offload Kind166 :name: table-offload_kind167 168 +------------+-------+---------------------------------------+169 | Name | Value | Description |170 +============+=======+=======================================+171 | OFK_None | 0x00 | No offloading information provided |172 +------------+-------+---------------------------------------+173 | OFK_OpenMP | 0x01 | The producer was OpenMP offloading |174 +------------+-------+---------------------------------------+175 | OFK_CUDA | 0x02 | The producer was CUDA |176 +------------+-------+---------------------------------------+177 | OFK_HIP | 0x03 | The producer was HIP |178 +------------+-------+---------------------------------------+179 | OFK_SYCL | 0x04 | The producer was SYCL |180 +------------+-------+---------------------------------------+181 182SEE ALSO183--------184 185:manpage:`clang(1)`, :manpage:`llvm-objdump(1)`186