1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
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)`
|
