[Offload] Rename and move 'clang-offload-packager' -> 'llvm-offload-binary' #161438

jhuber6 · 2025-09-30T20:36:57Z

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.

llvmbot · 2025-09-30T20:37:28Z

@llvm/pr-subscribers-flang-driver
@llvm/pr-subscribers-llvm-binary-utilities

@llvm/pr-subscribers-backend-amdgpu

Author: Joseph Huber (jhuber6)

Changes

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.

Patch is 67.28 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/161438.diff

30 Files Affected:

(removed) clang/docs/ClangOffloadPackager.rst (-193)
(modified) clang/lib/Driver/Action.cpp (+1-1)
(modified) clang/lib/Driver/ToolChains/Clang.h (+1-1)
(modified) clang/test/CMakeLists.txt (+1-1)
(modified) clang/test/Driver/amdgpu-openmp-sanitize-options.c (+1-1)
(modified) clang/test/Driver/amdgpu-openmp-toolchain.c (+2-2)
(modified) clang/test/Driver/cuda-phases.cu (+2-2)
(modified) clang/test/Driver/hip-phases.hip (+2-2)
(modified) clang/test/Driver/hip-toolchain-no-rdc.hip (+2-2)
(modified) clang/test/Driver/linker-wrapper-image.c (+4-4)
(modified) clang/test/Driver/linker-wrapper.c (+24-24)
(modified) clang/test/Driver/offload-packager.c (+10-10)
(modified) clang/test/Driver/openmp-offload-gpu.c (+3-3)
(modified) clang/test/Driver/openmp-offload-jit.c (+1-1)
(modified) clang/test/Driver/openmp-offload.c (+3-3)
(modified) clang/test/Driver/spirv-openmp-toolchain.c (+1-1)
(modified) clang/test/Driver/sycl-offload-jit.cpp (+3-3)
(modified) clang/test/Tooling/clang-linker-wrapper-spirv-elf.cpp (+1-1)
(modified) clang/test/lit.cfg.py (+1-1)
(modified) clang/tools/CMakeLists.txt (-1)
(removed) clang/tools/clang-offload-packager/CMakeLists.txt (-17)
(modified) llvm/docs/CommandGuide/index.rst (+1)
(added) llvm/docs/CommandGuide/llvm-offload-binary.rst (+185)
(modified) llvm/runtimes/CMakeLists.txt (+4-4)
(modified) llvm/test/CMakeLists.txt (+1)
(added) llvm/test/Other/llvm-offload-binary.ll (+10)
(added) llvm/tools/llvm-offload-binary/CMakeLists.txt (+13)
(renamed) llvm/tools/llvm-offload-binary/llvm-offload-binary.cpp (+23-24)
(removed) llvm/utils/gn/secondary/clang/tools/clang-offload-packager/BUILD.gn (-10)
(modified) llvm/utils/gn/secondary/clang/tools/driver/BUILD.gn (-1)

diff --git a/clang/docs/ClangOffloadPackager.rst b/clang/docs/ClangOffloadPackager.rst
deleted file mode 100644
index 481069b5e4235..0000000000000
--- a/clang/docs/ClangOffloadPackager.rst
+++ /dev/null
@@ -1,193 +0,0 @@
-======================
-Clang Offload Packager
-======================
-
-.. contents::
-   :local:
-
-.. _clang-offload-packager:
-
-Introduction
-============
-
-This tool bundles device files into a single image containing necessary
-metadata. We use a custom binary format for bundling all the device images
-together. The image format is a small header wrapping around a string map. This
-tool creates bundled binaries so that they can be embedded into the host to
-create a fat-binary.
-
-Binary Format
-=============
-
-The binary format is marked by the ``0x10FF10AD`` magic bytes, followed by a
-version. Each created binary contains its own magic bytes. This allows us to
-locate all the embedded offloading sections even after they may have been merged
-by the linker, such as when using relocatable linking. Conceptually, this binary
-format is a serialization of a string map and an image buffer. The binary header
-is described in the following :ref:`table<table-binary_header>`.
-
-.. 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               |
-    +----------+--------------+----------------------------------------------------+
-
-Once identified through the magic bytes, we use the size field to take a slice
-of the binary blob containing the information for a single offloading image. We
-can then use the offset field to find the actual offloading entries containing
-the image and metadata. The offload entry contains information about the device
-image. It contains the fields shown in the following
-:ref:`table<table-binary_entry>`.
-
-.. 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                  |
-    +----------+---------------+----------------------------------------------------+
-
-This table contains the offsets of the string table and the device image itself
-along with some other integer information. The image kind lets us easily
-identify the type of image stored here without needing to inspect the binary.
-The offloading kind is used to determine which registration code or linking
-semantics are necessary for this image. These are stored as enumerations with
-the following values for the :ref:`offload kind<table-offload_kind>` and the
-:ref:`image kind<table-image_kind>`.
-
-.. 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                 |
-    +------------+-------+---------------------------------------+
-
-The flags are used to signify certain conditions, such as the presence of
-debugging information or whether or not LTO was used. The string entry table is
-used to generically contain any arbitrary key-value pair. This is stored as an
-array of the :ref:`string entry<table-binary_string>` format.
-
-.. 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 entries simply provide offsets to a key and value pair in the
-binary images string table. The string table is simply a collection of null
-terminated strings with defined offsets in the image. The string entry allows us
-to create a key-value pair from this string table. This is used for passing
-arbitrary arguments to the image, such as the triple and architecture.
-
-All of these structures are combined to form a single binary blob, the order
-does not matter because of the use of absolute offsets. This makes it easier to
-extend in the future. As mentioned previously, multiple offloading images are
-bundled together by simply concatenating them in this format. Because we have
-the magic bytes and size of each image, we can extract them as-needed.
-
-Usage
-=====
-
-This tool can be used with the following arguments. Generally information is
-passed as a key-value pair to the ``image=`` argument. The ``file`` and
-``triple``, arguments are considered mandatory to make a valid image.
-The ``arch`` argument is suggested.
-
-.. code-block:: console
-
-  OVERVIEW: A utility for bundling several object files into a single binary.
-  The output binary can then be embedded into the host section table
-  to create a fatbinary containing offloading code.
-
-  USAGE: clang-offload-packager [options]
-
-  OPTIONS:
-
-  Generic Options:
-
-    --help                      - Display available options (--help-hidden for more)
-    --help-list                 - Display list of available options (--help-list-hidden for more)
-    --version                   - Display the version of this program
-
-  clang-offload-packager options:
-
-    --image=<<key>=<value>,...> - List of key and value arguments. Required
-                                  keywords are 'file' and 'triple'.
-    -o <file>                   - Write output to <file>.
-
-Example
-=======
-
-This tool simply takes many input files from the ``image`` option and creates a
-single output file with all the images combined.
-
-.. code-block:: console
-
-  clang-offload-packager -o out.bin --image=file=input.o,triple=nvptx64,arch=sm_70
-
-The inverse operation can be performed instead by passing the packaged binary as
-input. In this mode the matching images will either be placed in the output
-specified by the ``file`` option. If no ``file`` argument is provided a name
-will be generated for each matching image.
-
-.. code-block:: console
-
-  clang-offload-packager in.bin --image=file=output.o,triple=nvptx64,arch=sm_70
diff --git a/clang/lib/Driver/Action.cpp b/clang/lib/Driver/Action.cpp
index e19daa9cb7abf..72a42a6f957ee 100644
--- a/clang/lib/Driver/Action.cpp
+++ b/clang/lib/Driver/Action.cpp
@@ -43,7 +43,7 @@ const char *Action::getClassName(ActionClass AC) {
   case OffloadUnbundlingJobClass:
     return "clang-offload-unbundler";
   case OffloadPackagerJobClass:
-    return "clang-offload-packager";
+    return "llvm-offload-binary";
   case LinkerWrapperJobClass:
     return "clang-linker-wrapper";
   case StaticLibJobClass:
diff --git a/clang/lib/Driver/ToolChains/Clang.h b/clang/lib/Driver/ToolChains/Clang.h
index c22789591e00a..9adad5c5430f2 100644
--- a/clang/lib/Driver/ToolChains/Clang.h
+++ b/clang/lib/Driver/ToolChains/Clang.h
@@ -163,7 +163,7 @@ class LLVM_LIBRARY_VISIBILITY OffloadBundler final : public Tool {
 class LLVM_LIBRARY_VISIBILITY OffloadPackager final : public Tool {
 public:
   OffloadPackager(const ToolChain &TC)
-      : Tool("Offload::Packager", "clang-offload-packager", TC) {}
+      : Tool("Offload::Packager", "llvm-offload-binary", TC) {}
 
   bool hasIntegratedCPP() const override { return false; }
   void ConstructJob(Compilation &C, const JobAction &JA,
diff --git a/clang/test/CMakeLists.txt b/clang/test/CMakeLists.txt
index e9f4f83f98923..bcb6bd68fafc2 100644
--- a/clang/test/CMakeLists.txt
+++ b/clang/test/CMakeLists.txt
@@ -103,7 +103,6 @@ list(APPEND CLANG_TEST_DEPS
   clang-linker-wrapper
   clang-nvlink-wrapper
   clang-offload-bundler
-  clang-offload-packager
   clang-sycl-linker
   diagtool
   hmaptool
@@ -173,6 +172,7 @@ if( NOT CLANG_BUILT_STANDALONE )
     llvm-strip
     llvm-symbolizer
     llvm-windres
+    llvm-offload-binary
     obj2yaml
     opt
     split-file
diff --git a/clang/test/Driver/amdgpu-openmp-sanitize-options.c b/clang/test/Driver/amdgpu-openmp-sanitize-options.c
index 985eca1692802..914e01873089c 100644
--- a/clang/test/Driver/amdgpu-openmp-sanitize-options.c
+++ b/clang/test/Driver/amdgpu-openmp-sanitize-options.c
@@ -59,6 +59,6 @@
 // GPUSAN: {{"[^"]*clang[^"]*" "-cc1" "-triple" "amdgcn-amd-amdhsa" "-aux-triple" "x86_64-unknown-linux-gnu".* "-emit-llvm-bc".* "-mlink-bitcode-file" "[^"]*asanrtl.bc".* "-mlink-bitcode-file" "[^"]*ockl.bc".* "-target-cpu" "(gfx908|gfx900)".* "-fopenmp".* "-fsanitize=address".* "-x" "c".*}}
 // NOGPUSAN: {{"[^"]*clang[^"]*" "-cc1" "-triple" "amdgcn-amd-amdhsa" "-aux-triple" "x86_64-unknown-linux-gnu".* "-emit-llvm-bc".* "-target-cpu" "(gfx908|gfx900)".* "-fopenmp".* "-x" "c".*}}
 
-// SAN: {{"[^"]*clang-offload-packager[^"]*" "-o".* "--image=file=.*.bc,triple=amdgcn-amd-amdhsa,arch=gfx908(:xnack\-|:xnack\+)?,kind=openmp(,feature=(\-xnack|\+xnack))?"}}
+// SAN: {{"[^"]*llvm-offload-binary[^"]*" "-o".* "--image=file=.*.bc,triple=amdgcn-amd-amdhsa,arch=gfx908(:xnack\-|:xnack\+)?,kind=openmp(,feature=(\-xnack|\+xnack))?"}}
 // SAN: {{"[^"]*clang[^"]*" "-cc1" "-triple" "x86_64-unknown-linux-gnu".* "-fopenmp".* "-fsanitize=address".* "--offload-targets=amdgcn-amd-amdhsa".* "-x" "ir".*}}
 // SAN: {{"[^"]*clang-linker-wrapper[^"]*".* "--host-triple=x86_64-unknown-linux-gnu".* "--linker-path=[^"]*".* "--whole-archive" "[^"]*(libclang_rt.asan_static.a|libclang_rt.asan_static-x86_64.a)".* "--whole-archive" "[^"]*(libclang_rt.asan.a|libclang_rt.asan-x86_64.a)".*}}
diff --git a/clang/test/Driver/amdgpu-openmp-toolchain.c b/clang/test/Driver/amdgpu-openmp-toolchain.c
index 1091e6e372ac0..5e73e2d6833fe 100644
--- a/clang/test/Driver/amdgpu-openmp-toolchain.c
+++ b/clang/test/Driver/amdgpu-openmp-toolchain.c
@@ -22,7 +22,7 @@
 // CHECK-PHASES: 6: offload, "host-openmp (x86_64-unknown-linux-gnu)" {2}, "device-openmp (amdgcn-amd-amdhsa:gfx906)" {5}, ir
 // CHECK-PHASES: 7: backend, {6}, ir, (device-openmp, gfx906)
 // CHECK-PHASES: 8: offload, "device-openmp (amdgcn-amd-amdhsa:gfx906)" {7}, ir
-// CHECK-PHASES: 9: clang-offload-packager, {8}, image, (device-openmp)
+// CHECK-PHASES: 9: llvm-offload-binary, {8}, image, (device-openmp)
 // CHECK-PHASES: 10: offload, "host-openmp (x86_64-unknown-linux-gnu)" {2}, "device-openmp (x86_64-unknown-linux-gnu)" {9}, ir
 // CHECK-PHASES: 11: backend, {10}, assembler, (host-openmp)
 // CHECK-PHASES: 12: assembler, {11}, object, (host-openmp)
@@ -64,7 +64,7 @@
 // RUN: %clang -### -target x86_64-pc-linux-gnu -fopenmp --offload-arch=gfx90a:sramecc-:xnack+ \
 // RUN:   -nogpulib %s 2>&1 | FileCheck %s --check-prefix=CHECK-TARGET-ID
 // CHECK-TARGET-ID: "-cc1" "-triple" "amdgcn-amd-amdhsa" {{.*}} "-target-cpu" "gfx90a" "-target-feature" "-sramecc" "-target-feature" "+xnack"
-// CHECK-TARGET-ID: clang-offload-packager{{.*}}arch=gfx90a:sramecc-:xnack+,kind=openmp
+// CHECK-TARGET-ID: llvm-offload-binary{{.*}}arch=gfx90a:sramecc-:xnack+,kind=openmp
 
 // RUN: not %clang -### -target x86_64-pc-linux-gnu -fopenmp --offload-arch=gfx90a,gfx90a:xnack+ \
 // RUN:   -nogpulib %s 2>&1 | FileCheck %s --check-prefix=CHECK-TARGET-ID-ERROR
diff --git a/clang/test/Driver/cuda-phases.cu b/clang/test/Driver/cuda-phases.cu
index 220a320e32705..db7d29e0c78c3 100644
--- a/clang/test/Driver/cuda-phases.cu
+++ b/clang/test/Driver/cuda-phases.cu
@@ -235,7 +235,7 @@
 // NEW-DRIVER-RDC-NEXT: 12: backend, {11}, assembler, (device-cuda, sm_70)
 // NEW-DRIVER-RDC-NEXT: 13: assembler, {12}, object, (device-cuda, sm_70)
 // NEW-DRIVER-RDC-NEXT: 14: offload, "device-cuda (nvptx64-nvidia-cuda:sm_70)" {13}, object
-// NEW-DRIVER-RDC-NEXT: 15: clang-offload-packager, {8, 14}, image, (device-cuda)
+// NEW-DRIVER-RDC-NEXT: 15: llvm-offload-binary, {8, 14}, image, (device-cuda)
 // NEW-DRIVER-RDC-NEXT: 16: offload, "host-cuda (powerpc64le-ibm-linux-gnu)" {2}, "device-cuda (powerpc64le-ibm-linux-gnu)" {15}, ir
 // NEW-DRIVER-RDC-NEXT: 17: backend, {16}, assembler, (host-cuda)
 // NEW-DRIVER-RDC-NEXT: 18: assembler, {17}, object, (host-cuda)
@@ -312,7 +312,7 @@
 // LTO-NEXT: 10: compiler, {9}, ir, (device-cuda, sm_70)
 // LTO-NEXT: 11: backend, {10}, lto-bc, (device-cuda, sm_70)
 // LTO-NEXT: 12: offload, "device-cuda (nvptx64-nvidia-cuda:sm_70)" {11}, lto-bc
-// LTO-NEXT: 13: clang-offload-packager, {7, 12}, image, (device-cuda)
+// LTO-NEXT: 13: llvm-offload-binary, {7, 12}, image, (device-cuda)
 // LTO-NEXT: 14: offload, "host-cuda (powerpc64le-ibm-linux-gnu)" {2}, "device-cuda (powerpc64le-ibm-linux-gnu)" {13}, ir
 // LTO-NEXT: 15: backend, {14}, assembler, (host-cuda)
 // LTO-NEXT: 16: assembler, {15}, object, (host-cuda)
diff --git a/clang/test/Driver/hip-phases.hip b/clang/test/Driver/hip-phases.hip
index 6bac97ab8064b..13f682f18a3ab 100644
--- a/clang/test/Driver/hip-phases.hip
+++ b/clang/test/Driver/hip-phases.hip
@@ -40,7 +40,7 @@
 // OLD-DAG: [[P9:[0-9]+]]: offload, "device-[[T]] (amdgcn-amd-amdhsa:[[ARCH]])" {[[P8]]}, image
 // NEW-DAG: [[P9:[0-9]+]]: offload, "device-[[T]] (amdgcn-amd-amdhsa:[[ARCH]])" {[[P6]]}, ir
 // OLDN-DAG: [[P10:[0-9]+]]: linker, {[[P9]]}, hip-fatbin, (device-[[T]])
-// NEW-DAG: [[P10:[0-9]+]]: clang-offload-packager, {[[P9]]}, image, (device-[[T]])
+// NEW-DAG: [[P10:[0-9]+]]: llvm-offload-binary, {[[P9]]}, image, (device-[[T]])
 // OLDR-DAG: [[P10:[0-9]+]]: linker, {[[P9]]}, object, (device-[[T]])
 
 // OLDN-DAG: [[P11:[0-9]+]]: offload, "host-[[T]] (x86_64-unknown-linux-gnu)" {[[P2]]}, "device-[[T]] (amdgcn-amd-amdhsa)" {[[P10]]}, ir
@@ -665,7 +665,7 @@
 // LTO-NEXT: 10: compiler, {9}, ir, (device-hip, gfx90a)
 // LTO-NEXT: 11: backend, {10}, lto-bc, (device-hip, gfx90a)
 // LTO-NEXT: 12: offload, "device-hip (amdgcn-amd-amdhsa:gfx90a)" {11}, lto-bc
-// LTO-NEXT: 13: clang-offload-packager, {7, 12}, image, (device-hip)
+// LTO-NEXT: 13: llvm-offload-binary, {7, 12}, image, (device-hip)
 // LTO-NEXT: 14: offload, "host-hip (x86_64-unknown-linux-gnu)" {2}, "device-hip (x86_64-unknown-linux-gnu)" {13}, ir
 // LTO-NEXT: 15: backend, {14}, assembler, (host-hip)
 // LTO-NEXT: 16: assembler, {15}, object, (host-hip)
diff --git a/clang/test/Driver/hip-toolchain-no-rdc.hip b/clang/test/Driver/hip-toolchain-no-rdc.hip
index dc8f0a97ad371..a94299eb2d4db 100644
--- a/clang/test/Driver/hip-toolchain-no-rdc.hip
+++ b/clang/test/Driver/hip-toolchain-no-rdc.hip
@@ -97,7 +97,7 @@
 // OLD-SAME: "-targets={{.*}},hipv4-amdgcn-amd-amdhsa--gfx803,hipv4-amdgcn-amd-amdhsa--gfx900"
 // OLD-SAME: "-input={{.*}}" "-input=[[IMG_DEV_A_803]]" "-input=[[IMG_DEV_A_900]]" "-output=[[BUNDLE_A:.*hipfb]]"
 
-// NEW: [[PACKAGER:".*clang-offload-packager"]] "-o" "[[PACKAGE_A:.*.out]]"
+// NEW: [[PACKAGER:".*llvm-offload-binary"]] "-o" "[[PACKAGE_A:.*.out]]"
 // NEW-SAME: "--image=file=[[OBJ_DEV_A_803]],triple=amdgcn-amd-amdhsa,arch=gfx803,kind=hip"
 // NEW-SAME: "--image=file=[[OBJ_DEV_A_900]],triple=amdgcn-amd-amdhsa,arch=gfx900,kind=hip"
 
@@ -169,7 +169,7 @@
 // OLD-SAME: "-targets={{.*}},hipv4-amdgcn-amd-amdhsa--gfx803,hipv4-amdgcn-amd-amdhsa--gfx900"
 // OLD-SAME: "-input={{.*}}" "-input=[[IMG_DEV_B_803]]" "-input=[[IMG_DEV_B_900]]" "-output=[[BUNDLE_B:.*hipfb]]"
 
-// NEW: [[PACKAGER:".*clang-offload-packager"]] "-o" "[[PACKAGE_B:.*.out]]"
+// NEW: [[PACKAGER:".*llvm-offload-binary"]] "-o" "[[PACKAGE_B:.*.out]]"
 // NEW-SAME: "--image=file=[[OBJ_DEV_B_803]],triple=amdgcn-amd-amdhsa,arch=gfx803,kind=hip"
 // NEW-SAME: "--image=file=[[OBJ_DEV_B_900]],triple=amdgcn-amd-amdhsa,arch=gfx900,kind=hip"
 
diff --git a/clang/test/Driver/linker-wrapper-image.c b/clang/test/Driver/linker-wrapper-image.c
index 31476173cd370..b9327121edcf9 100644
--- a/clang/test/Driver/linker-wrapper-image.c
+++ b/clang/test/Driver/linker-wrapper-image.c
@@ -5,7 +5,7 @@
 
 // RUN: %clang -cc1 %s -triple x86_64-unknown-linux-gnu -emit-obj -o %t.elf.o
 
-// RUN: clang-offload-packager -o %t.out --image=file=%t.elf.o,kind=openmp,triple=nvptx64-nvidia-cuda,arch=sm_70
+// RUN: llvm-offload-binary -o %t.out --image=file=%t.elf.o,kind=openmp,triple=nvptx64-nvidia-cuda,arch=sm_70
 // RUN: %clang -cc1 %s -triple x86_64-unknown-linux-gnu -emit-obj -o %t.o \
 // RUN:   -fembed-offload-object=%t.out
 // RUN: clang-linker-wrapper --print-wrapped-module --dry-run --host-triple=x86_64-unknown-linux-...
[truncated]

llvmbot · 2025-09-30T20:37:28Z

@llvm/pr-subscribers-clang

Author: Joseph Huber (jhuber6)

Changes

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.

Patch is 67.28 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/161438.diff

30 Files Affected:

(removed) clang/docs/ClangOffloadPackager.rst (-193)
(modified) clang/lib/Driver/Action.cpp (+1-1)
(modified) clang/lib/Driver/ToolChains/Clang.h (+1-1)
(modified) clang/test/CMakeLists.txt (+1-1)
(modified) clang/test/Driver/amdgpu-openmp-sanitize-options.c (+1-1)
(modified) clang/test/Driver/amdgpu-openmp-toolchain.c (+2-2)
(modified) clang/test/Driver/cuda-phases.cu (+2-2)
(modified) clang/test/Driver/hip-phases.hip (+2-2)
(modified) clang/test/Driver/hip-toolchain-no-rdc.hip (+2-2)
(modified) clang/test/Driver/linker-wrapper-image.c (+4-4)
(modified) clang/test/Driver/linker-wrapper.c (+24-24)
(modified) clang/test/Driver/offload-packager.c (+10-10)
(modified) clang/test/Driver/openmp-offload-gpu.c (+3-3)
(modified) clang/test/Driver/openmp-offload-jit.c (+1-1)
(modified) clang/test/Driver/openmp-offload.c (+3-3)
(modified) clang/test/Driver/spirv-openmp-toolchain.c (+1-1)
(modified) clang/test/Driver/sycl-offload-jit.cpp (+3-3)
(modified) clang/test/Tooling/clang-linker-wrapper-spirv-elf.cpp (+1-1)
(modified) clang/test/lit.cfg.py (+1-1)
(modified) clang/tools/CMakeLists.txt (-1)
(removed) clang/tools/clang-offload-packager/CMakeLists.txt (-17)
(modified) llvm/docs/CommandGuide/index.rst (+1)
(added) llvm/docs/CommandGuide/llvm-offload-binary.rst (+185)
(modified) llvm/runtimes/CMakeLists.txt (+4-4)
(modified) llvm/test/CMakeLists.txt (+1)
(added) llvm/test/Other/llvm-offload-binary.ll (+10)
(added) llvm/tools/llvm-offload-binary/CMakeLists.txt (+13)
(renamed) llvm/tools/llvm-offload-binary/llvm-offload-binary.cpp (+23-24)
(removed) llvm/utils/gn/secondary/clang/tools/clang-offload-packager/BUILD.gn (-10)
(modified) llvm/utils/gn/secondary/clang/tools/driver/BUILD.gn (-1)

diff --git a/clang/docs/ClangOffloadPackager.rst b/clang/docs/ClangOffloadPackager.rst
deleted file mode 100644
index 481069b5e4235..0000000000000
--- a/clang/docs/ClangOffloadPackager.rst
+++ /dev/null
@@ -1,193 +0,0 @@
-======================
-Clang Offload Packager
-======================
-
-.. contents::
-   :local:
-
-.. _clang-offload-packager:
-
-Introduction
-============
-
-This tool bundles device files into a single image containing necessary
-metadata. We use a custom binary format for bundling all the device images
-together. The image format is a small header wrapping around a string map. This
-tool creates bundled binaries so that they can be embedded into the host to
-create a fat-binary.
-
-Binary Format
-=============
-
-The binary format is marked by the ``0x10FF10AD`` magic bytes, followed by a
-version. Each created binary contains its own magic bytes. This allows us to
-locate all the embedded offloading sections even after they may have been merged
-by the linker, such as when using relocatable linking. Conceptually, this binary
-format is a serialization of a string map and an image buffer. The binary header
-is described in the following :ref:`table<table-binary_header>`.
-
-.. 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               |
-    +----------+--------------+----------------------------------------------------+
-
-Once identified through the magic bytes, we use the size field to take a slice
-of the binary blob containing the information for a single offloading image. We
-can then use the offset field to find the actual offloading entries containing
-the image and metadata. The offload entry contains information about the device
-image. It contains the fields shown in the following
-:ref:`table<table-binary_entry>`.
-
-.. 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                  |
-    +----------+---------------+----------------------------------------------------+
-
-This table contains the offsets of the string table and the device image itself
-along with some other integer information. The image kind lets us easily
-identify the type of image stored here without needing to inspect the binary.
-The offloading kind is used to determine which registration code or linking
-semantics are necessary for this image. These are stored as enumerations with
-the following values for the :ref:`offload kind<table-offload_kind>` and the
-:ref:`image kind<table-image_kind>`.
-
-.. 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                 |
-    +------------+-------+---------------------------------------+
-
-The flags are used to signify certain conditions, such as the presence of
-debugging information or whether or not LTO was used. The string entry table is
-used to generically contain any arbitrary key-value pair. This is stored as an
-array of the :ref:`string entry<table-binary_string>` format.
-
-.. 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 entries simply provide offsets to a key and value pair in the
-binary images string table. The string table is simply a collection of null
-terminated strings with defined offsets in the image. The string entry allows us
-to create a key-value pair from this string table. This is used for passing
-arbitrary arguments to the image, such as the triple and architecture.
-
-All of these structures are combined to form a single binary blob, the order
-does not matter because of the use of absolute offsets. This makes it easier to
-extend in the future. As mentioned previously, multiple offloading images are
-bundled together by simply concatenating them in this format. Because we have
-the magic bytes and size of each image, we can extract them as-needed.
-
-Usage
-=====
-
-This tool can be used with the following arguments. Generally information is
-passed as a key-value pair to the ``image=`` argument. The ``file`` and
-``triple``, arguments are considered mandatory to make a valid image.
-The ``arch`` argument is suggested.
-
-.. code-block:: console
-
-  OVERVIEW: A utility for bundling several object files into a single binary.
-  The output binary can then be embedded into the host section table
-  to create a fatbinary containing offloading code.
-
-  USAGE: clang-offload-packager [options]
-
-  OPTIONS:
-
-  Generic Options:
-
-    --help                      - Display available options (--help-hidden for more)
-    --help-list                 - Display list of available options (--help-list-hidden for more)
-    --version                   - Display the version of this program
-
-  clang-offload-packager options:
-
-    --image=<<key>=<value>,...> - List of key and value arguments. Required
-                                  keywords are 'file' and 'triple'.
-    -o <file>                   - Write output to <file>.
-
-Example
-=======
-
-This tool simply takes many input files from the ``image`` option and creates a
-single output file with all the images combined.
-
-.. code-block:: console
-
-  clang-offload-packager -o out.bin --image=file=input.o,triple=nvptx64,arch=sm_70
-
-The inverse operation can be performed instead by passing the packaged binary as
-input. In this mode the matching images will either be placed in the output
-specified by the ``file`` option. If no ``file`` argument is provided a name
-will be generated for each matching image.
-
-.. code-block:: console
-
-  clang-offload-packager in.bin --image=file=output.o,triple=nvptx64,arch=sm_70
diff --git a/clang/lib/Driver/Action.cpp b/clang/lib/Driver/Action.cpp
index e19daa9cb7abf..72a42a6f957ee 100644
--- a/clang/lib/Driver/Action.cpp
+++ b/clang/lib/Driver/Action.cpp
@@ -43,7 +43,7 @@ const char *Action::getClassName(ActionClass AC) {
   case OffloadUnbundlingJobClass:
     return "clang-offload-unbundler";
   case OffloadPackagerJobClass:
-    return "clang-offload-packager";
+    return "llvm-offload-binary";
   case LinkerWrapperJobClass:
     return "clang-linker-wrapper";
   case StaticLibJobClass:
diff --git a/clang/lib/Driver/ToolChains/Clang.h b/clang/lib/Driver/ToolChains/Clang.h
index c22789591e00a..9adad5c5430f2 100644
--- a/clang/lib/Driver/ToolChains/Clang.h
+++ b/clang/lib/Driver/ToolChains/Clang.h
@@ -163,7 +163,7 @@ class LLVM_LIBRARY_VISIBILITY OffloadBundler final : public Tool {
 class LLVM_LIBRARY_VISIBILITY OffloadPackager final : public Tool {
 public:
   OffloadPackager(const ToolChain &TC)
-      : Tool("Offload::Packager", "clang-offload-packager", TC) {}
+      : Tool("Offload::Packager", "llvm-offload-binary", TC) {}
 
   bool hasIntegratedCPP() const override { return false; }
   void ConstructJob(Compilation &C, const JobAction &JA,
diff --git a/clang/test/CMakeLists.txt b/clang/test/CMakeLists.txt
index e9f4f83f98923..bcb6bd68fafc2 100644
--- a/clang/test/CMakeLists.txt
+++ b/clang/test/CMakeLists.txt
@@ -103,7 +103,6 @@ list(APPEND CLANG_TEST_DEPS
   clang-linker-wrapper
   clang-nvlink-wrapper
   clang-offload-bundler
-  clang-offload-packager
   clang-sycl-linker
   diagtool
   hmaptool
@@ -173,6 +172,7 @@ if( NOT CLANG_BUILT_STANDALONE )
     llvm-strip
     llvm-symbolizer
     llvm-windres
+    llvm-offload-binary
     obj2yaml
     opt
     split-file
diff --git a/clang/test/Driver/amdgpu-openmp-sanitize-options.c b/clang/test/Driver/amdgpu-openmp-sanitize-options.c
index 985eca1692802..914e01873089c 100644
--- a/clang/test/Driver/amdgpu-openmp-sanitize-options.c
+++ b/clang/test/Driver/amdgpu-openmp-sanitize-options.c
@@ -59,6 +59,6 @@
 // GPUSAN: {{"[^"]*clang[^"]*" "-cc1" "-triple" "amdgcn-amd-amdhsa" "-aux-triple" "x86_64-unknown-linux-gnu".* "-emit-llvm-bc".* "-mlink-bitcode-file" "[^"]*asanrtl.bc".* "-mlink-bitcode-file" "[^"]*ockl.bc".* "-target-cpu" "(gfx908|gfx900)".* "-fopenmp".* "-fsanitize=address".* "-x" "c".*}}
 // NOGPUSAN: {{"[^"]*clang[^"]*" "-cc1" "-triple" "amdgcn-amd-amdhsa" "-aux-triple" "x86_64-unknown-linux-gnu".* "-emit-llvm-bc".* "-target-cpu" "(gfx908|gfx900)".* "-fopenmp".* "-x" "c".*}}
 
-// SAN: {{"[^"]*clang-offload-packager[^"]*" "-o".* "--image=file=.*.bc,triple=amdgcn-amd-amdhsa,arch=gfx908(:xnack\-|:xnack\+)?,kind=openmp(,feature=(\-xnack|\+xnack))?"}}
+// SAN: {{"[^"]*llvm-offload-binary[^"]*" "-o".* "--image=file=.*.bc,triple=amdgcn-amd-amdhsa,arch=gfx908(:xnack\-|:xnack\+)?,kind=openmp(,feature=(\-xnack|\+xnack))?"}}
 // SAN: {{"[^"]*clang[^"]*" "-cc1" "-triple" "x86_64-unknown-linux-gnu".* "-fopenmp".* "-fsanitize=address".* "--offload-targets=amdgcn-amd-amdhsa".* "-x" "ir".*}}
 // SAN: {{"[^"]*clang-linker-wrapper[^"]*".* "--host-triple=x86_64-unknown-linux-gnu".* "--linker-path=[^"]*".* "--whole-archive" "[^"]*(libclang_rt.asan_static.a|libclang_rt.asan_static-x86_64.a)".* "--whole-archive" "[^"]*(libclang_rt.asan.a|libclang_rt.asan-x86_64.a)".*}}
diff --git a/clang/test/Driver/amdgpu-openmp-toolchain.c b/clang/test/Driver/amdgpu-openmp-toolchain.c
index 1091e6e372ac0..5e73e2d6833fe 100644
--- a/clang/test/Driver/amdgpu-openmp-toolchain.c
+++ b/clang/test/Driver/amdgpu-openmp-toolchain.c
@@ -22,7 +22,7 @@
 // CHECK-PHASES: 6: offload, "host-openmp (x86_64-unknown-linux-gnu)" {2}, "device-openmp (amdgcn-amd-amdhsa:gfx906)" {5}, ir
 // CHECK-PHASES: 7: backend, {6}, ir, (device-openmp, gfx906)
 // CHECK-PHASES: 8: offload, "device-openmp (amdgcn-amd-amdhsa:gfx906)" {7}, ir
-// CHECK-PHASES: 9: clang-offload-packager, {8}, image, (device-openmp)
+// CHECK-PHASES: 9: llvm-offload-binary, {8}, image, (device-openmp)
 // CHECK-PHASES: 10: offload, "host-openmp (x86_64-unknown-linux-gnu)" {2}, "device-openmp (x86_64-unknown-linux-gnu)" {9}, ir
 // CHECK-PHASES: 11: backend, {10}, assembler, (host-openmp)
 // CHECK-PHASES: 12: assembler, {11}, object, (host-openmp)
@@ -64,7 +64,7 @@
 // RUN: %clang -### -target x86_64-pc-linux-gnu -fopenmp --offload-arch=gfx90a:sramecc-:xnack+ \
 // RUN:   -nogpulib %s 2>&1 | FileCheck %s --check-prefix=CHECK-TARGET-ID
 // CHECK-TARGET-ID: "-cc1" "-triple" "amdgcn-amd-amdhsa" {{.*}} "-target-cpu" "gfx90a" "-target-feature" "-sramecc" "-target-feature" "+xnack"
-// CHECK-TARGET-ID: clang-offload-packager{{.*}}arch=gfx90a:sramecc-:xnack+,kind=openmp
+// CHECK-TARGET-ID: llvm-offload-binary{{.*}}arch=gfx90a:sramecc-:xnack+,kind=openmp
 
 // RUN: not %clang -### -target x86_64-pc-linux-gnu -fopenmp --offload-arch=gfx90a,gfx90a:xnack+ \
 // RUN:   -nogpulib %s 2>&1 | FileCheck %s --check-prefix=CHECK-TARGET-ID-ERROR
diff --git a/clang/test/Driver/cuda-phases.cu b/clang/test/Driver/cuda-phases.cu
index 220a320e32705..db7d29e0c78c3 100644
--- a/clang/test/Driver/cuda-phases.cu
+++ b/clang/test/Driver/cuda-phases.cu
@@ -235,7 +235,7 @@
 // NEW-DRIVER-RDC-NEXT: 12: backend, {11}, assembler, (device-cuda, sm_70)
 // NEW-DRIVER-RDC-NEXT: 13: assembler, {12}, object, (device-cuda, sm_70)
 // NEW-DRIVER-RDC-NEXT: 14: offload, "device-cuda (nvptx64-nvidia-cuda:sm_70)" {13}, object
-// NEW-DRIVER-RDC-NEXT: 15: clang-offload-packager, {8, 14}, image, (device-cuda)
+// NEW-DRIVER-RDC-NEXT: 15: llvm-offload-binary, {8, 14}, image, (device-cuda)
 // NEW-DRIVER-RDC-NEXT: 16: offload, "host-cuda (powerpc64le-ibm-linux-gnu)" {2}, "device-cuda (powerpc64le-ibm-linux-gnu)" {15}, ir
 // NEW-DRIVER-RDC-NEXT: 17: backend, {16}, assembler, (host-cuda)
 // NEW-DRIVER-RDC-NEXT: 18: assembler, {17}, object, (host-cuda)
@@ -312,7 +312,7 @@
 // LTO-NEXT: 10: compiler, {9}, ir, (device-cuda, sm_70)
 // LTO-NEXT: 11: backend, {10}, lto-bc, (device-cuda, sm_70)
 // LTO-NEXT: 12: offload, "device-cuda (nvptx64-nvidia-cuda:sm_70)" {11}, lto-bc
-// LTO-NEXT: 13: clang-offload-packager, {7, 12}, image, (device-cuda)
+// LTO-NEXT: 13: llvm-offload-binary, {7, 12}, image, (device-cuda)
 // LTO-NEXT: 14: offload, "host-cuda (powerpc64le-ibm-linux-gnu)" {2}, "device-cuda (powerpc64le-ibm-linux-gnu)" {13}, ir
 // LTO-NEXT: 15: backend, {14}, assembler, (host-cuda)
 // LTO-NEXT: 16: assembler, {15}, object, (host-cuda)
diff --git a/clang/test/Driver/hip-phases.hip b/clang/test/Driver/hip-phases.hip
index 6bac97ab8064b..13f682f18a3ab 100644
--- a/clang/test/Driver/hip-phases.hip
+++ b/clang/test/Driver/hip-phases.hip
@@ -40,7 +40,7 @@
 // OLD-DAG: [[P9:[0-9]+]]: offload, "device-[[T]] (amdgcn-amd-amdhsa:[[ARCH]])" {[[P8]]}, image
 // NEW-DAG: [[P9:[0-9]+]]: offload, "device-[[T]] (amdgcn-amd-amdhsa:[[ARCH]])" {[[P6]]}, ir
 // OLDN-DAG: [[P10:[0-9]+]]: linker, {[[P9]]}, hip-fatbin, (device-[[T]])
-// NEW-DAG: [[P10:[0-9]+]]: clang-offload-packager, {[[P9]]}, image, (device-[[T]])
+// NEW-DAG: [[P10:[0-9]+]]: llvm-offload-binary, {[[P9]]}, image, (device-[[T]])
 // OLDR-DAG: [[P10:[0-9]+]]: linker, {[[P9]]}, object, (device-[[T]])
 
 // OLDN-DAG: [[P11:[0-9]+]]: offload, "host-[[T]] (x86_64-unknown-linux-gnu)" {[[P2]]}, "device-[[T]] (amdgcn-amd-amdhsa)" {[[P10]]}, ir
@@ -665,7 +665,7 @@
 // LTO-NEXT: 10: compiler, {9}, ir, (device-hip, gfx90a)
 // LTO-NEXT: 11: backend, {10}, lto-bc, (device-hip, gfx90a)
 // LTO-NEXT: 12: offload, "device-hip (amdgcn-amd-amdhsa:gfx90a)" {11}, lto-bc
-// LTO-NEXT: 13: clang-offload-packager, {7, 12}, image, (device-hip)
+// LTO-NEXT: 13: llvm-offload-binary, {7, 12}, image, (device-hip)
 // LTO-NEXT: 14: offload, "host-hip (x86_64-unknown-linux-gnu)" {2}, "device-hip (x86_64-unknown-linux-gnu)" {13}, ir
 // LTO-NEXT: 15: backend, {14}, assembler, (host-hip)
 // LTO-NEXT: 16: assembler, {15}, object, (host-hip)
diff --git a/clang/test/Driver/hip-toolchain-no-rdc.hip b/clang/test/Driver/hip-toolchain-no-rdc.hip
index dc8f0a97ad371..a94299eb2d4db 100644
--- a/clang/test/Driver/hip-toolchain-no-rdc.hip
+++ b/clang/test/Driver/hip-toolchain-no-rdc.hip
@@ -97,7 +97,7 @@
 // OLD-SAME: "-targets={{.*}},hipv4-amdgcn-amd-amdhsa--gfx803,hipv4-amdgcn-amd-amdhsa--gfx900"
 // OLD-SAME: "-input={{.*}}" "-input=[[IMG_DEV_A_803]]" "-input=[[IMG_DEV_A_900]]" "-output=[[BUNDLE_A:.*hipfb]]"
 
-// NEW: [[PACKAGER:".*clang-offload-packager"]] "-o" "[[PACKAGE_A:.*.out]]"
+// NEW: [[PACKAGER:".*llvm-offload-binary"]] "-o" "[[PACKAGE_A:.*.out]]"
 // NEW-SAME: "--image=file=[[OBJ_DEV_A_803]],triple=amdgcn-amd-amdhsa,arch=gfx803,kind=hip"
 // NEW-SAME: "--image=file=[[OBJ_DEV_A_900]],triple=amdgcn-amd-amdhsa,arch=gfx900,kind=hip"
 
@@ -169,7 +169,7 @@
 // OLD-SAME: "-targets={{.*}},hipv4-amdgcn-amd-amdhsa--gfx803,hipv4-amdgcn-amd-amdhsa--gfx900"
 // OLD-SAME: "-input={{.*}}" "-input=[[IMG_DEV_B_803]]" "-input=[[IMG_DEV_B_900]]" "-output=[[BUNDLE_B:.*hipfb]]"
 
-// NEW: [[PACKAGER:".*clang-offload-packager"]] "-o" "[[PACKAGE_B:.*.out]]"
+// NEW: [[PACKAGER:".*llvm-offload-binary"]] "-o" "[[PACKAGE_B:.*.out]]"
 // NEW-SAME: "--image=file=[[OBJ_DEV_B_803]],triple=amdgcn-amd-amdhsa,arch=gfx803,kind=hip"
 // NEW-SAME: "--image=file=[[OBJ_DEV_B_900]],triple=amdgcn-amd-amdhsa,arch=gfx900,kind=hip"
 
diff --git a/clang/test/Driver/linker-wrapper-image.c b/clang/test/Driver/linker-wrapper-image.c
index 31476173cd370..b9327121edcf9 100644
--- a/clang/test/Driver/linker-wrapper-image.c
+++ b/clang/test/Driver/linker-wrapper-image.c
@@ -5,7 +5,7 @@
 
 // RUN: %clang -cc1 %s -triple x86_64-unknown-linux-gnu -emit-obj -o %t.elf.o
 
-// RUN: clang-offload-packager -o %t.out --image=file=%t.elf.o,kind=openmp,triple=nvptx64-nvidia-cuda,arch=sm_70
+// RUN: llvm-offload-binary -o %t.out --image=file=%t.elf.o,kind=openmp,triple=nvptx64-nvidia-cuda,arch=sm_70
 // RUN: %clang -cc1 %s -triple x86_64-unknown-linux-gnu -emit-obj -o %t.o \
 // RUN:   -fembed-offload-object=%t.out
 // RUN: clang-linker-wrapper --print-wrapped-module --dry-run --host-triple=x86_64-unknown-linux-...
[truncated]

llvmbot · 2025-09-30T20:37:29Z

@llvm/pr-subscribers-clang-driver

Author: Joseph Huber (jhuber6)

Changes

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.

Patch is 67.28 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/161438.diff

30 Files Affected:

(removed) clang/docs/ClangOffloadPackager.rst (-193)
(modified) clang/lib/Driver/Action.cpp (+1-1)
(modified) clang/lib/Driver/ToolChains/Clang.h (+1-1)
(modified) clang/test/CMakeLists.txt (+1-1)
(modified) clang/test/Driver/amdgpu-openmp-sanitize-options.c (+1-1)
(modified) clang/test/Driver/amdgpu-openmp-toolchain.c (+2-2)
(modified) clang/test/Driver/cuda-phases.cu (+2-2)
(modified) clang/test/Driver/hip-phases.hip (+2-2)
(modified) clang/test/Driver/hip-toolchain-no-rdc.hip (+2-2)
(modified) clang/test/Driver/linker-wrapper-image.c (+4-4)
(modified) clang/test/Driver/linker-wrapper.c (+24-24)
(modified) clang/test/Driver/offload-packager.c (+10-10)
(modified) clang/test/Driver/openmp-offload-gpu.c (+3-3)
(modified) clang/test/Driver/openmp-offload-jit.c (+1-1)
(modified) clang/test/Driver/openmp-offload.c (+3-3)
(modified) clang/test/Driver/spirv-openmp-toolchain.c (+1-1)
(modified) clang/test/Driver/sycl-offload-jit.cpp (+3-3)
(modified) clang/test/Tooling/clang-linker-wrapper-spirv-elf.cpp (+1-1)
(modified) clang/test/lit.cfg.py (+1-1)
(modified) clang/tools/CMakeLists.txt (-1)
(removed) clang/tools/clang-offload-packager/CMakeLists.txt (-17)
(modified) llvm/docs/CommandGuide/index.rst (+1)
(added) llvm/docs/CommandGuide/llvm-offload-binary.rst (+185)
(modified) llvm/runtimes/CMakeLists.txt (+4-4)
(modified) llvm/test/CMakeLists.txt (+1)
(added) llvm/test/Other/llvm-offload-binary.ll (+10)
(added) llvm/tools/llvm-offload-binary/CMakeLists.txt (+13)
(renamed) llvm/tools/llvm-offload-binary/llvm-offload-binary.cpp (+23-24)
(removed) llvm/utils/gn/secondary/clang/tools/clang-offload-packager/BUILD.gn (-10)
(modified) llvm/utils/gn/secondary/clang/tools/driver/BUILD.gn (-1)

diff --git a/clang/docs/ClangOffloadPackager.rst b/clang/docs/ClangOffloadPackager.rst
deleted file mode 100644
index 481069b5e4235..0000000000000
--- a/clang/docs/ClangOffloadPackager.rst
+++ /dev/null
@@ -1,193 +0,0 @@
-======================
-Clang Offload Packager
-======================
-
-.. contents::
-   :local:
-
-.. _clang-offload-packager:
-
-Introduction
-============
-
-This tool bundles device files into a single image containing necessary
-metadata. We use a custom binary format for bundling all the device images
-together. The image format is a small header wrapping around a string map. This
-tool creates bundled binaries so that they can be embedded into the host to
-create a fat-binary.
-
-Binary Format
-=============
-
-The binary format is marked by the ``0x10FF10AD`` magic bytes, followed by a
-version. Each created binary contains its own magic bytes. This allows us to
-locate all the embedded offloading sections even after they may have been merged
-by the linker, such as when using relocatable linking. Conceptually, this binary
-format is a serialization of a string map and an image buffer. The binary header
-is described in the following :ref:`table<table-binary_header>`.
-
-.. 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               |
-    +----------+--------------+----------------------------------------------------+
-
-Once identified through the magic bytes, we use the size field to take a slice
-of the binary blob containing the information for a single offloading image. We
-can then use the offset field to find the actual offloading entries containing
-the image and metadata. The offload entry contains information about the device
-image. It contains the fields shown in the following
-:ref:`table<table-binary_entry>`.
-
-.. 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                  |
-    +----------+---------------+----------------------------------------------------+
-
-This table contains the offsets of the string table and the device image itself
-along with some other integer information. The image kind lets us easily
-identify the type of image stored here without needing to inspect the binary.
-The offloading kind is used to determine which registration code or linking
-semantics are necessary for this image. These are stored as enumerations with
-the following values for the :ref:`offload kind<table-offload_kind>` and the
-:ref:`image kind<table-image_kind>`.
-
-.. 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                 |
-    +------------+-------+---------------------------------------+
-
-The flags are used to signify certain conditions, such as the presence of
-debugging information or whether or not LTO was used. The string entry table is
-used to generically contain any arbitrary key-value pair. This is stored as an
-array of the :ref:`string entry<table-binary_string>` format.
-
-.. 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 entries simply provide offsets to a key and value pair in the
-binary images string table. The string table is simply a collection of null
-terminated strings with defined offsets in the image. The string entry allows us
-to create a key-value pair from this string table. This is used for passing
-arbitrary arguments to the image, such as the triple and architecture.
-
-All of these structures are combined to form a single binary blob, the order
-does not matter because of the use of absolute offsets. This makes it easier to
-extend in the future. As mentioned previously, multiple offloading images are
-bundled together by simply concatenating them in this format. Because we have
-the magic bytes and size of each image, we can extract them as-needed.
-
-Usage
-=====
-
-This tool can be used with the following arguments. Generally information is
-passed as a key-value pair to the ``image=`` argument. The ``file`` and
-``triple``, arguments are considered mandatory to make a valid image.
-The ``arch`` argument is suggested.
-
-.. code-block:: console
-
-  OVERVIEW: A utility for bundling several object files into a single binary.
-  The output binary can then be embedded into the host section table
-  to create a fatbinary containing offloading code.
-
-  USAGE: clang-offload-packager [options]
-
-  OPTIONS:
-
-  Generic Options:
-
-    --help                      - Display available options (--help-hidden for more)
-    --help-list                 - Display list of available options (--help-list-hidden for more)
-    --version                   - Display the version of this program
-
-  clang-offload-packager options:
-
-    --image=<<key>=<value>,...> - List of key and value arguments. Required
-                                  keywords are 'file' and 'triple'.
-    -o <file>                   - Write output to <file>.
-
-Example
-=======
-
-This tool simply takes many input files from the ``image`` option and creates a
-single output file with all the images combined.
-
-.. code-block:: console
-
-  clang-offload-packager -o out.bin --image=file=input.o,triple=nvptx64,arch=sm_70
-
-The inverse operation can be performed instead by passing the packaged binary as
-input. In this mode the matching images will either be placed in the output
-specified by the ``file`` option. If no ``file`` argument is provided a name
-will be generated for each matching image.
-
-.. code-block:: console
-
-  clang-offload-packager in.bin --image=file=output.o,triple=nvptx64,arch=sm_70
diff --git a/clang/lib/Driver/Action.cpp b/clang/lib/Driver/Action.cpp
index e19daa9cb7abf..72a42a6f957ee 100644
--- a/clang/lib/Driver/Action.cpp
+++ b/clang/lib/Driver/Action.cpp
@@ -43,7 +43,7 @@ const char *Action::getClassName(ActionClass AC) {
   case OffloadUnbundlingJobClass:
     return "clang-offload-unbundler";
   case OffloadPackagerJobClass:
-    return "clang-offload-packager";
+    return "llvm-offload-binary";
   case LinkerWrapperJobClass:
     return "clang-linker-wrapper";
   case StaticLibJobClass:
diff --git a/clang/lib/Driver/ToolChains/Clang.h b/clang/lib/Driver/ToolChains/Clang.h
index c22789591e00a..9adad5c5430f2 100644
--- a/clang/lib/Driver/ToolChains/Clang.h
+++ b/clang/lib/Driver/ToolChains/Clang.h
@@ -163,7 +163,7 @@ class LLVM_LIBRARY_VISIBILITY OffloadBundler final : public Tool {
 class LLVM_LIBRARY_VISIBILITY OffloadPackager final : public Tool {
 public:
   OffloadPackager(const ToolChain &TC)
-      : Tool("Offload::Packager", "clang-offload-packager", TC) {}
+      : Tool("Offload::Packager", "llvm-offload-binary", TC) {}
 
   bool hasIntegratedCPP() const override { return false; }
   void ConstructJob(Compilation &C, const JobAction &JA,
diff --git a/clang/test/CMakeLists.txt b/clang/test/CMakeLists.txt
index e9f4f83f98923..bcb6bd68fafc2 100644
--- a/clang/test/CMakeLists.txt
+++ b/clang/test/CMakeLists.txt
@@ -103,7 +103,6 @@ list(APPEND CLANG_TEST_DEPS
   clang-linker-wrapper
   clang-nvlink-wrapper
   clang-offload-bundler
-  clang-offload-packager
   clang-sycl-linker
   diagtool
   hmaptool
@@ -173,6 +172,7 @@ if( NOT CLANG_BUILT_STANDALONE )
     llvm-strip
     llvm-symbolizer
     llvm-windres
+    llvm-offload-binary
     obj2yaml
     opt
     split-file
diff --git a/clang/test/Driver/amdgpu-openmp-sanitize-options.c b/clang/test/Driver/amdgpu-openmp-sanitize-options.c
index 985eca1692802..914e01873089c 100644
--- a/clang/test/Driver/amdgpu-openmp-sanitize-options.c
+++ b/clang/test/Driver/amdgpu-openmp-sanitize-options.c
@@ -59,6 +59,6 @@
 // GPUSAN: {{"[^"]*clang[^"]*" "-cc1" "-triple" "amdgcn-amd-amdhsa" "-aux-triple" "x86_64-unknown-linux-gnu".* "-emit-llvm-bc".* "-mlink-bitcode-file" "[^"]*asanrtl.bc".* "-mlink-bitcode-file" "[^"]*ockl.bc".* "-target-cpu" "(gfx908|gfx900)".* "-fopenmp".* "-fsanitize=address".* "-x" "c".*}}
 // NOGPUSAN: {{"[^"]*clang[^"]*" "-cc1" "-triple" "amdgcn-amd-amdhsa" "-aux-triple" "x86_64-unknown-linux-gnu".* "-emit-llvm-bc".* "-target-cpu" "(gfx908|gfx900)".* "-fopenmp".* "-x" "c".*}}
 
-// SAN: {{"[^"]*clang-offload-packager[^"]*" "-o".* "--image=file=.*.bc,triple=amdgcn-amd-amdhsa,arch=gfx908(:xnack\-|:xnack\+)?,kind=openmp(,feature=(\-xnack|\+xnack))?"}}
+// SAN: {{"[^"]*llvm-offload-binary[^"]*" "-o".* "--image=file=.*.bc,triple=amdgcn-amd-amdhsa,arch=gfx908(:xnack\-|:xnack\+)?,kind=openmp(,feature=(\-xnack|\+xnack))?"}}
 // SAN: {{"[^"]*clang[^"]*" "-cc1" "-triple" "x86_64-unknown-linux-gnu".* "-fopenmp".* "-fsanitize=address".* "--offload-targets=amdgcn-amd-amdhsa".* "-x" "ir".*}}
 // SAN: {{"[^"]*clang-linker-wrapper[^"]*".* "--host-triple=x86_64-unknown-linux-gnu".* "--linker-path=[^"]*".* "--whole-archive" "[^"]*(libclang_rt.asan_static.a|libclang_rt.asan_static-x86_64.a)".* "--whole-archive" "[^"]*(libclang_rt.asan.a|libclang_rt.asan-x86_64.a)".*}}
diff --git a/clang/test/Driver/amdgpu-openmp-toolchain.c b/clang/test/Driver/amdgpu-openmp-toolchain.c
index 1091e6e372ac0..5e73e2d6833fe 100644
--- a/clang/test/Driver/amdgpu-openmp-toolchain.c
+++ b/clang/test/Driver/amdgpu-openmp-toolchain.c
@@ -22,7 +22,7 @@
 // CHECK-PHASES: 6: offload, "host-openmp (x86_64-unknown-linux-gnu)" {2}, "device-openmp (amdgcn-amd-amdhsa:gfx906)" {5}, ir
 // CHECK-PHASES: 7: backend, {6}, ir, (device-openmp, gfx906)
 // CHECK-PHASES: 8: offload, "device-openmp (amdgcn-amd-amdhsa:gfx906)" {7}, ir
-// CHECK-PHASES: 9: clang-offload-packager, {8}, image, (device-openmp)
+// CHECK-PHASES: 9: llvm-offload-binary, {8}, image, (device-openmp)
 // CHECK-PHASES: 10: offload, "host-openmp (x86_64-unknown-linux-gnu)" {2}, "device-openmp (x86_64-unknown-linux-gnu)" {9}, ir
 // CHECK-PHASES: 11: backend, {10}, assembler, (host-openmp)
 // CHECK-PHASES: 12: assembler, {11}, object, (host-openmp)
@@ -64,7 +64,7 @@
 // RUN: %clang -### -target x86_64-pc-linux-gnu -fopenmp --offload-arch=gfx90a:sramecc-:xnack+ \
 // RUN:   -nogpulib %s 2>&1 | FileCheck %s --check-prefix=CHECK-TARGET-ID
 // CHECK-TARGET-ID: "-cc1" "-triple" "amdgcn-amd-amdhsa" {{.*}} "-target-cpu" "gfx90a" "-target-feature" "-sramecc" "-target-feature" "+xnack"
-// CHECK-TARGET-ID: clang-offload-packager{{.*}}arch=gfx90a:sramecc-:xnack+,kind=openmp
+// CHECK-TARGET-ID: llvm-offload-binary{{.*}}arch=gfx90a:sramecc-:xnack+,kind=openmp
 
 // RUN: not %clang -### -target x86_64-pc-linux-gnu -fopenmp --offload-arch=gfx90a,gfx90a:xnack+ \
 // RUN:   -nogpulib %s 2>&1 | FileCheck %s --check-prefix=CHECK-TARGET-ID-ERROR
diff --git a/clang/test/Driver/cuda-phases.cu b/clang/test/Driver/cuda-phases.cu
index 220a320e32705..db7d29e0c78c3 100644
--- a/clang/test/Driver/cuda-phases.cu
+++ b/clang/test/Driver/cuda-phases.cu
@@ -235,7 +235,7 @@
 // NEW-DRIVER-RDC-NEXT: 12: backend, {11}, assembler, (device-cuda, sm_70)
 // NEW-DRIVER-RDC-NEXT: 13: assembler, {12}, object, (device-cuda, sm_70)
 // NEW-DRIVER-RDC-NEXT: 14: offload, "device-cuda (nvptx64-nvidia-cuda:sm_70)" {13}, object
-// NEW-DRIVER-RDC-NEXT: 15: clang-offload-packager, {8, 14}, image, (device-cuda)
+// NEW-DRIVER-RDC-NEXT: 15: llvm-offload-binary, {8, 14}, image, (device-cuda)
 // NEW-DRIVER-RDC-NEXT: 16: offload, "host-cuda (powerpc64le-ibm-linux-gnu)" {2}, "device-cuda (powerpc64le-ibm-linux-gnu)" {15}, ir
 // NEW-DRIVER-RDC-NEXT: 17: backend, {16}, assembler, (host-cuda)
 // NEW-DRIVER-RDC-NEXT: 18: assembler, {17}, object, (host-cuda)
@@ -312,7 +312,7 @@
 // LTO-NEXT: 10: compiler, {9}, ir, (device-cuda, sm_70)
 // LTO-NEXT: 11: backend, {10}, lto-bc, (device-cuda, sm_70)
 // LTO-NEXT: 12: offload, "device-cuda (nvptx64-nvidia-cuda:sm_70)" {11}, lto-bc
-// LTO-NEXT: 13: clang-offload-packager, {7, 12}, image, (device-cuda)
+// LTO-NEXT: 13: llvm-offload-binary, {7, 12}, image, (device-cuda)
 // LTO-NEXT: 14: offload, "host-cuda (powerpc64le-ibm-linux-gnu)" {2}, "device-cuda (powerpc64le-ibm-linux-gnu)" {13}, ir
 // LTO-NEXT: 15: backend, {14}, assembler, (host-cuda)
 // LTO-NEXT: 16: assembler, {15}, object, (host-cuda)
diff --git a/clang/test/Driver/hip-phases.hip b/clang/test/Driver/hip-phases.hip
index 6bac97ab8064b..13f682f18a3ab 100644
--- a/clang/test/Driver/hip-phases.hip
+++ b/clang/test/Driver/hip-phases.hip
@@ -40,7 +40,7 @@
 // OLD-DAG: [[P9:[0-9]+]]: offload, "device-[[T]] (amdgcn-amd-amdhsa:[[ARCH]])" {[[P8]]}, image
 // NEW-DAG: [[P9:[0-9]+]]: offload, "device-[[T]] (amdgcn-amd-amdhsa:[[ARCH]])" {[[P6]]}, ir
 // OLDN-DAG: [[P10:[0-9]+]]: linker, {[[P9]]}, hip-fatbin, (device-[[T]])
-// NEW-DAG: [[P10:[0-9]+]]: clang-offload-packager, {[[P9]]}, image, (device-[[T]])
+// NEW-DAG: [[P10:[0-9]+]]: llvm-offload-binary, {[[P9]]}, image, (device-[[T]])
 // OLDR-DAG: [[P10:[0-9]+]]: linker, {[[P9]]}, object, (device-[[T]])
 
 // OLDN-DAG: [[P11:[0-9]+]]: offload, "host-[[T]] (x86_64-unknown-linux-gnu)" {[[P2]]}, "device-[[T]] (amdgcn-amd-amdhsa)" {[[P10]]}, ir
@@ -665,7 +665,7 @@
 // LTO-NEXT: 10: compiler, {9}, ir, (device-hip, gfx90a)
 // LTO-NEXT: 11: backend, {10}, lto-bc, (device-hip, gfx90a)
 // LTO-NEXT: 12: offload, "device-hip (amdgcn-amd-amdhsa:gfx90a)" {11}, lto-bc
-// LTO-NEXT: 13: clang-offload-packager, {7, 12}, image, (device-hip)
+// LTO-NEXT: 13: llvm-offload-binary, {7, 12}, image, (device-hip)
 // LTO-NEXT: 14: offload, "host-hip (x86_64-unknown-linux-gnu)" {2}, "device-hip (x86_64-unknown-linux-gnu)" {13}, ir
 // LTO-NEXT: 15: backend, {14}, assembler, (host-hip)
 // LTO-NEXT: 16: assembler, {15}, object, (host-hip)
diff --git a/clang/test/Driver/hip-toolchain-no-rdc.hip b/clang/test/Driver/hip-toolchain-no-rdc.hip
index dc8f0a97ad371..a94299eb2d4db 100644
--- a/clang/test/Driver/hip-toolchain-no-rdc.hip
+++ b/clang/test/Driver/hip-toolchain-no-rdc.hip
@@ -97,7 +97,7 @@
 // OLD-SAME: "-targets={{.*}},hipv4-amdgcn-amd-amdhsa--gfx803,hipv4-amdgcn-amd-amdhsa--gfx900"
 // OLD-SAME: "-input={{.*}}" "-input=[[IMG_DEV_A_803]]" "-input=[[IMG_DEV_A_900]]" "-output=[[BUNDLE_A:.*hipfb]]"
 
-// NEW: [[PACKAGER:".*clang-offload-packager"]] "-o" "[[PACKAGE_A:.*.out]]"
+// NEW: [[PACKAGER:".*llvm-offload-binary"]] "-o" "[[PACKAGE_A:.*.out]]"
 // NEW-SAME: "--image=file=[[OBJ_DEV_A_803]],triple=amdgcn-amd-amdhsa,arch=gfx803,kind=hip"
 // NEW-SAME: "--image=file=[[OBJ_DEV_A_900]],triple=amdgcn-amd-amdhsa,arch=gfx900,kind=hip"
 
@@ -169,7 +169,7 @@
 // OLD-SAME: "-targets={{.*}},hipv4-amdgcn-amd-amdhsa--gfx803,hipv4-amdgcn-amd-amdhsa--gfx900"
 // OLD-SAME: "-input={{.*}}" "-input=[[IMG_DEV_B_803]]" "-input=[[IMG_DEV_B_900]]" "-output=[[BUNDLE_B:.*hipfb]]"
 
-// NEW: [[PACKAGER:".*clang-offload-packager"]] "-o" "[[PACKAGE_B:.*.out]]"
+// NEW: [[PACKAGER:".*llvm-offload-binary"]] "-o" "[[PACKAGE_B:.*.out]]"
 // NEW-SAME: "--image=file=[[OBJ_DEV_B_803]],triple=amdgcn-amd-amdhsa,arch=gfx803,kind=hip"
 // NEW-SAME: "--image=file=[[OBJ_DEV_B_900]],triple=amdgcn-amd-amdhsa,arch=gfx900,kind=hip"
 
diff --git a/clang/test/Driver/linker-wrapper-image.c b/clang/test/Driver/linker-wrapper-image.c
index 31476173cd370..b9327121edcf9 100644
--- a/clang/test/Driver/linker-wrapper-image.c
+++ b/clang/test/Driver/linker-wrapper-image.c
@@ -5,7 +5,7 @@
 
 // RUN: %clang -cc1 %s -triple x86_64-unknown-linux-gnu -emit-obj -o %t.elf.o
 
-// RUN: clang-offload-packager -o %t.out --image=file=%t.elf.o,kind=openmp,triple=nvptx64-nvidia-cuda,arch=sm_70
+// RUN: llvm-offload-binary -o %t.out --image=file=%t.elf.o,kind=openmp,triple=nvptx64-nvidia-cuda,arch=sm_70
 // RUN: %clang -cc1 %s -triple x86_64-unknown-linux-gnu -emit-obj -o %t.o \
 // RUN:   -fembed-offload-object=%t.out
 // RUN: clang-linker-wrapper --print-wrapped-module --dry-run --host-triple=x86_64-unknown-linux-...
[truncated]

sarnex · 2025-09-30T20:52:18Z

clang/lib/Driver/Action.cpp

    return "clang-offload-unbundler";
  case OffloadPackagerJobClass:
-    return "clang-offload-packager";
+    return "llvm-offload-binary";


the new name doesn't have a verb (or whatever packager is) so it's somewhat unclear what it does, is llvm-offload-binary-packager too long?

That's quite the mouthful, it'd just be llvm-offload-packager if we needed it to be a verb, but since the format is just 'offload binary' I don't think it needs to strictly be a verb.

i would actually prefer llvm-offload-packager, but i'm happy to go with the consensus

…inary' 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.

jhuber6 requested review from arsenm, Artem-B, estewart08, JonChesterfield, MaskRay, sarnex, shiltian and yxsamliu September 30, 2025 20:36

llvmbot added clang Clang issues not falling into any other category backend:AMDGPU clang:driver 'clang' and 'clang++' user-facing binaries. Not 'clang-cl' llvm:binary-utilities labels Sep 30, 2025

sarnex reviewed Sep 30, 2025

View reviewed changes

jhuber6 force-pushed the offload-binary branch from 1967d97 to 5162fa4 Compare September 30, 2025 21:10

llvmbot added flang:driver flang Flang issues not falling into any other category labels Sep 30, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Offload] Rename and move 'clang-offload-packager' -> 'llvm-offload-binary' #161438

[Offload] Rename and move 'clang-offload-packager' -> 'llvm-offload-binary' #161438

Uh oh!

jhuber6 commented Sep 30, 2025

Uh oh!

llvmbot commented Sep 30, 2025 •

edited

Loading

Uh oh!

llvmbot commented Sep 30, 2025

Uh oh!

llvmbot commented Sep 30, 2025

Uh oh!

sarnex Sep 30, 2025

Uh oh!

jhuber6 Sep 30, 2025

Uh oh!

sarnex Sep 30, 2025

Uh oh!

Uh oh!

[Offload] Rename and move 'clang-offload-packager' -> 'llvm-offload-binary' #161438

Are you sure you want to change the base?

[Offload] Rename and move 'clang-offload-packager' -> 'llvm-offload-binary' #161438

Uh oh!

Conversation

jhuber6 commented Sep 30, 2025

Uh oh!

llvmbot commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

llvmbot commented Sep 30, 2025

Uh oh!

llvmbot commented Sep 30, 2025

Uh oh!

sarnex Sep 30, 2025

Choose a reason for hiding this comment

Uh oh!

jhuber6 Sep 30, 2025

Choose a reason for hiding this comment

Uh oh!

sarnex Sep 30, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

llvmbot commented Sep 30, 2025 •

edited

Loading