2499fe1ac4
Summary: This tool is pretty much a generic interface into creating and managing the offloading binary format. The binary format itself is just a fat binary block used to create heterogeneous objects. This should be made more general than just `clang` since it's likely going to be used for larger offloading projects and is the expected way to extract heterogeneous objects from offloading code. Relatively straightforward rename, a few tweaks and documentation changes. Kept in `clang-offload-packager` for legacy compatibility as we looked this tool up by name in places, will probably delete it next release.
186 lines
8.4 KiB
ReStructuredText
186 lines
8.4 KiB
ReStructuredText
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=<<key>=<value>,...>
|
|
|
|
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 <file>
|
|
|
|
Write output to <file>. 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:: @<FILE>
|
|
|
|
Read command-line options from response file `<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)`
|