NAME¶

llvm-offload-binary - LLVM Offload Binary Packager

SYNOPSIS¶

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

DESCRIPTION¶

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.

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.

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.

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¶

# 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¶

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.

Offloading Binary Header¶

Each offload entry describes a bundled image along with its associated metadata.

Offloading Entry Table¶

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¶

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:

Image Kind¶

Offload Kind¶

COMMON WORKFLOWS¶

Workflow 1: Explore Executable Contents

Extract all embedded offload images to see what's inside:

$ 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

Extract only images for a specific target:

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

Workflow 3: Create Device Image Archive

Extract filtered images 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 and validate SPIR-V binaries:

$ 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

Create a fat binary from multiple device images:

$ 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

Extract images from one binary and rebundle with modifications:

$ 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¶

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/).

Copyright¶

2003-2026, LLVM Project