LLVM-OFFLOAD-BINARY(1)

📦
version 23.1.4 · 8 versions
, in arch rolling

💅 llvm-offload-binary 💅

LLVM-OFFLOAD-BINARY(1) — yes bestie, that's the manual name, folded in right here at the top 🫶

🌸 NAME 🌸

llvm-offload-binary — LLVM Offload Binary Packager. That's the whole main-character job description, no cap 💖

✨ SYNOPSIS ✨

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

🦋 DESCRIPTION 🦋

okay so 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 from offload binaries. It's giving "pack and unpack, but make it LLVM" ✨

When extracting images, if no --image filters are specified, all offload images are automatically extracted with descriptive filenames. When --image filters are provided, only matching images are extracted. Lowkey the cleanest vibe check ever 💅

The tool supports nested OffloadBinary format, where device images can be wrapped in an inner OffloadBinary container. When extracting, the tool automatically detects and unwraps nested OffloadBinary images, making the format transparent to users. Obsessed with the transparency, fr fr 🫶

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. That's the tea ☕

🎀 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 all offload images from an executable (no filters):
$ llvm-offload-binary in.bin
# Output:
# Extracted: in-nvptx64-nvidia-cuda-sm_70.0.bc
# Extracted: in-spirv64-intel-unknown.0.spv

# Extract only SPIR-V images using filters:
$ llvm-offload-binary in.bin --image=triple=spirv64-intel
# Output:
# Extracted: in-spirv64-intel-unknown.0.spv

# Extract filtered images to a specific file:
$ llvm-offload-binary in.bin --image=file=output.bc,arch=sm_70

# Extract filtered images to an archive:
$ llvm-offload-binary in.bin --image=file=output.a,triple=nvptx64 --archive

💜 OPTIONS 💜

  • --archive — when extracting from an input binary, write all extracted images into a static archive instead of separate files. Archive girlie behavior, and honestly? Iconic 🧚
  • --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).

When bundling, this option specifies images to include in the output binary. When extracting, this option acts as a filter: only images matching the specified keys are extracted. If no --image options are provided during extraction, all images are automatically extracted with descriptive filenames.

When extracting from a static archive, the member key restricts the output to a single archive member for cases when --archive is insufficient, e.g. --image=member=foo.o,triple=nvptx64,arch=sm_70,file=out.o. Slay that precise member selection ✨

  • -o <file> — write output to <file>. When bundling, this specifies the fat binary filename. When extracting, this specifies the archive or output file destination. One flag, two moods, both valid 💅
  • --help, -h — display available options. Use --help-hidden to show hidden options. The peek-behind-the-curtain feature, iykyk 🔥
  • --help-list — display a list of all options. Use --help-list-hidden to show hidden ones. A whole list of options? Not me being fed information 😭💖
  • --version — display the version of the llvm-offload-binary executable. Version check, but make it cute ⭐
  • @<FILE> — read command-line options from response file <FILE>. Response-file realness, periodt 🎀

🌈 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. No cap, that's the whole structural 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. Main character metadata energy, honestly 👑

💀 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. It's giving "strings and image, holding hands" 🫶

🍓 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. Offsets allow string entries to be interpreted as key-value pairs, enabling flexible metadata such as architecture or target triple. Literally the metadata glow-up we deserve 🌟

The enumerated values for image kind and offload kind are:

💫 Image Kind 💫

okay so every image in there has a kind, and it's giving "what even is this file, bestie?" energy. here's the whole roster:

  • IMG_None — 0x00 — literally no image information provided. it's giving empty vibes 🫥
  • 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 tells you which producer made the image — like, who's the parent, yk? 🌈

  • 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

🌸 COMMON WORKFLOWS 🌸

bestie this is the part you actually came for, fr fr. six little recipes, pick your fighter 💅

✨ Workflow 1: Explore Executable Contents

extract all the embedded offload images so you can peek at what's inside (nosy girl behavior, and honestly? valid 👀):

$ clang++ -fopenmp -fopenmp-targets=nvptx64,spirv64-intel app.cpp -o myapp
$ llvm-offload-binary myapp
# Output:
# Extracted: myapp-nvptx64-nvidia-cuda-sm_70.0.bc
# Extracted: myapp-spirv64-intel-unknown.1.spv

✨ Workflow 2: Extract Specific Target

only want one target's images? filter it, periodt:

$ llvm-offload-binary myapp --image=triple=spirv64-intel
# Output:
# Extracted: myapp-spirv64-intel-unknown.0.spv

✨ Workflow 3: Create Device Image Archive

grab your filtered images and yeet 'em into a static archive 🎀:

$ llvm-offload-binary myapp --image=file=nvptx.a,triple=nvptx64 --archive
$ ar t nvptx.a
# Shows extracted CUDA images

✨ Workflow 4: Validate SPIR-V

extract, then validate, then disassemble — the full glow-up routine ✨:

$ llvm-offload-binary myapp --image=triple=spirv64-intel
$ spirv-val myapp-spirv64-intel-unknown.0.spv
$ spirv-dis myapp-spirv64-intel-unknown.0.spv -o kernel.spvasm

✨ Workflow 5: Bundle Multiple Targets

build a fat binary out of a bunch of device images because why choose 💁‍♀️:

$ clang++ -fopenmp -fopenmp-targets=nvptx64 --offload-device-only kernel.cpp -o kernel_nvptx.bc
$ clang++ -fopenmp -fopenmp-targets=spirv64-intel --offload-device-only kernel.cpp -o kernel_spirv.bc
$ llvm-offload-binary -o bundle.bin \
    --image=file=kernel_nvptx.bc,triple=nvptx64,arch=sm_70 \
    --image=file=kernel_spirv.bc,triple=spirv64-intel

✨ Workflow 6: Extract and Rebundle

take the images out of one binary and rebundle them with your own edits — remix culture 🧚:

$ llvm-offload-binary old_app
$ llvm-offload-binary -o new_bundle.bin \
    --image=file=old_app-nvptx64-nvidia-cuda-sm_70.0.bc,triple=nvptx64,arch=sm_70 \
    --image=file=new_kernel.bc,triple=nvptx64,arch=sm_80

👑 SEE ALSO 👑

go read these next, they're iconic and they're literally right there:

  • clang(1) (clang.html)
  • llvm-objdump(1) (llvm-objdump.html)
  • spirv-val(1) (spirv-val.html)
  • spirv-dis(1) (spirv-dis.html)

🌈 Author 🌈

maintained by the LLVM Team (https://llvm.org/) — they're the main characters of this whole saga, no cap 🫶

2003-2026, LLVM Project

okay that's the whole page, bestie!! now go extract something slay 💅✨

and hmm one last lil thing — if you're squinting at the footer wondering where this came from: it's from page 23, dated 2026-10-20, filed under LLVM-OFFLOAD-BINARY(1). iconic of the manpage to have a birthday tbh 🎂🎀 bye bestie, mwah 💜

📦 where this page comes from