LLVM-OFFLOAD-BINARY(1)

📦
version 22.1.8 · 6 versions
, in fedora 44

💖 LLVM-OFFLOAD-BINARY(1) 💖

okay bestie, welcome to the LLVM manual, girlies, this is llvm-offload-binary and she is that utility. sit down, get comfy, we're bundling device objects. 🦋

✨ NAME ✨

llvm-offload-binary — the LLVM Offload Binary Packager, no cap 💅

✨ SYNOPSIS ✨

llvm-offload-binary [options] [input files...]

✨ DESCRIPTION ✨

so llvm-offload-binary is a little utility that's literally obsessed with bundling a whole bunch of device object files into one single binary container. like, imagine a group chat but for object files. 💖

the resulting binary can then get embedded into the host section table to form a fat binary that carries offloading code for different targets. and conversely (yes, conversely, we're being fancy), it can also extract previously bundled device images back out. it's giving dual-threat. ✨

now let's talk format, because the format is the moment. the binary format begins with the magic bytes 0x10FF10AD, and after that comes a version and a size. every single binary carries its own header, which means tools can locate offloading sections even when they get merged by a linker. iconic behavior honestly. each offload entry comes with metadata like the device image kind, the producer kind, and key-value string metadata. and multiple offloading images are just concatenated together to form that fat binary. 🎀

✨ EXAMPLE ✨

# 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

periodt. 📌

✨ OPTIONS ✨

  • --archive — when you're extracting from an input binary, this makes all the extracted images get written into a static archive instead of being dumped out as separate files. so organized of her. 🧚
  • --image=<<key>=<value>,...> — specify a set of arbitrary key-value arguments that describe an image. the commonly used optional keys include arch (like sm_70 for CUDA, iykyk) and triple (like nvptx64-nvidia-cuda). 💜
  • -o <file> — write output to <file>. when bundling, this is the fat binary filename. when extracting, this is the archive or output file destination. she's flexible like that. 💅
  • --help, -h — display the available options. use --help-hidden to show the hidden options (the secret menu, lowkey). 🔥
  • --help-list — display a list of all the options. use --help-list-hidden to show the hidden ones too. 👑
  • --version — display the version of the llvm-offload-binary executable. 💫
  • @<FILE> — read command-line options from a response file <FILE>. 🌸

✨ BINARY FORMAT ✨

okay this is the part where we get into the lore. the binary format is marked by the magic bytes 0x10FF10AD, followed by a version number. every binary that gets created contains its own header, which is exactly what lets tools locate offloading sections even after linker operations like relocatable linking. conceptually, this binary format is a serialization of a string map and an image buffer. that's the whole vibe. 🦋

💖 Offloading Binary Header 💖

  • 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. 💅

💖 Offloading Entry Table 💖

  • 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. 🎀

💖 Offloading String Entry 💖

  • 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. the offsets are what allow string entries to be interpreted as key-value pairs, which is how you get flexible metadata like architecture or target triple. slay. ✨

the enumerated values for image kind and offload kind are:

🎀 Image Kind 🎀

ok so this is the little enum that tells you what flavour of image you're looking at. every single value, no skips, bestie:

  • IMG_None — 0x00 — no image information provided. literally nothing, she's empty 💀
  • 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

🦋 Offload Kind 🦋

and this one is who made you — the producer vibes check. all five, verbatim:

  • 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 👀

go read your siblings, they're iconic too:

💖 Author 💖

maintained by the LLVM Team (https://llvm.org/). they keep the whole thing running, periodt ✨

2003-2026, LLVM Project. that's a two-decade glow-up, no cap 🫶

ok bestie that's the whole page, you made it to the end 🎉 this was LLVM-OFFLOAD-BINARY(1), page 22, dated 2026-07-16 — go offload something cute, drink some water, and remember: the binary format was never the enemy, it was just ✨ undocumented ✨ 💅🌸🦋

📦 where this page comes from