1//===-- llvm-offload-binary.cpp - offload binary management utility -------===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This tool takes several device object files and bundles them into a single
10// binary image using a custom binary format. This is intended to be used to
11// embed many device files into an application to create a fat binary. It also
12// supports extracting these files from a known location.
13//
14//===----------------------------------------------------------------------===//
15
16#include "llvm/ADT/StringExtras.h"
17#include "llvm/BinaryFormat/Magic.h"
18#include "llvm/Object/ArchiveWriter.h"
19#include "llvm/Object/OffloadBinary.h"
20#include "llvm/Support/CommandLine.h"
21#include "llvm/Support/Compression.h"
22#include "llvm/Support/FileOutputBuffer.h"
23#include "llvm/Support/MemoryBuffer.h"
24#include "llvm/Support/Path.h"
25#include "llvm/Support/Signals.h"
26#include "llvm/Support/StringSaver.h"
27#include "llvm/Support/WithColor.h"
28
29using namespace llvm;
30using namespace llvm::object;
31
32static cl::OptionCategory OffloadBinaryCategory("llvm-offload-binary options");
33
34static cl::opt<std::string> OutputFile("o", cl::desc("Write output to <file>."),
35 cl::value_desc("file"),
36 cl::cat(OffloadBinaryCategory));
37
38static cl::opt<std::string> InputFile(cl::Positional,
39 cl::desc("Extract from <file>."),
40 cl::value_desc("file"),
41 cl::cat(OffloadBinaryCategory));
42
43static cl::list<std::string>
44 DeviceImages("image",
45 cl::desc("List of key and value arguments. Required keywords "
46 "are 'file' and 'triple'."),
47 cl::value_desc("<key>=<value>,..."),
48 cl::cat(OffloadBinaryCategory));
49
50static cl::opt<bool>
51 CreateArchive("archive",
52 cl::desc("Write extracted files to a static archive"),
53 cl::cat(OffloadBinaryCategory));
54
55static cl::opt<bool> Compress("compress",
56 cl::desc("Compress the packaged offload binary"),
57 cl::cat(OffloadBinaryCategory));
58
59static cl::opt<compression::Format> CompressionFormat(
60 "compression-format", cl::desc("Format used with --compress"),
61 cl::values(
62 clEnumValN(compression::Format::Zstd, "zstd", "Zstandard compression"),
63 clEnumValN(compression::Format::Zlib, "zlib", "zlib compression")),
64 cl::init(Val: compression::Format::Zstd), cl::cat(OffloadBinaryCategory));
65
66static cl::opt<int>
67 CompressionLevel("compression-level",
68 cl::desc("Compression level used with --compress. "
69 "Requires --compression-format"),
70 cl::init(Val: -1), cl::cat(OffloadBinaryCategory));
71
72/// Path of the current binary.
73static const char *PackagerExecutable;
74
75// Get a map containing all the arguments for the image. Repeated arguments will
76// be placed in a comma separated list.
77static DenseMap<StringRef, StringRef> getImageArguments(StringRef Image,
78 StringSaver &Saver) {
79 DenseMap<StringRef, StringRef> Args;
80 for (StringRef Arg : llvm::split(Str: Image, Separator: ",")) {
81 auto [Key, Value] = Arg.split(Separator: "=");
82 auto [It, Inserted] = Args.try_emplace(Key, Args&: Value);
83 if (!Inserted)
84 It->second = Saver.save(S: It->second + "," + Value);
85 }
86
87 return Args;
88}
89
90static constexpr int ZlibMinCompressionLevel = -1;
91static constexpr int ZstdMinCompressionLevel = -131072;
92static constexpr int ZstdMaxCompressionLevel = 22;
93
94static Error checkCompressionLevel(compression::Format Format, int Level) {
95 int Lo, Hi;
96 const char *Name;
97 if (Format == compression::Format::Zlib) {
98 Lo = ZlibMinCompressionLevel;
99 Hi = compression::zlib::BestSizeCompression;
100 Name = "zlib";
101 } else {
102 Lo = ZstdMinCompressionLevel;
103 Hi = ZstdMaxCompressionLevel;
104 Name = "zstd";
105 }
106 if (Level < Lo || Level > Hi)
107 return createStringError(
108 EC: inconvertibleErrorCode(),
109 Fmt: "invalid %s compression level %d; expected a value "
110 "in [%d, %d]",
111 Vals: Name, Vals: Level, Vals: Lo, Vals: Hi);
112 return Error::success();
113}
114
115static Error writeFile(StringRef Filename, StringRef Data) {
116 Expected<std::unique_ptr<FileOutputBuffer>> OutputOrErr =
117 FileOutputBuffer::create(FilePath: Filename, Size: Data.size());
118 if (!OutputOrErr)
119 return OutputOrErr.takeError();
120 std::unique_ptr<FileOutputBuffer> Output = std::move(*OutputOrErr);
121 llvm::copy(Range&: Data, Out: Output->getBufferStart());
122 if (Error E = Output->commit())
123 return E;
124 return Error::success();
125}
126
127static Error bundleImages() {
128 SmallVector<OffloadBinary::OffloadingImage> AllImages;
129 BumpPtrAllocator Alloc;
130 StringSaver Saver(Alloc);
131 for (StringRef Image : DeviceImages) {
132 DenseMap<StringRef, StringRef> Args = getImageArguments(Image, Saver);
133
134 if (!Args.count(Val: "file"))
135 return createStringError(EC: inconvertibleErrorCode(),
136 S: "'file' is a required image arguments");
137
138 // Permit using multiple instances of `file` in a single string.
139 for (auto &File : llvm::split(Str: Args["file"], Separator: ",")) {
140 OffloadBinary::OffloadingImage ImageBinary{};
141
142 llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>> ObjectOrErr =
143 llvm::MemoryBuffer::getFileOrSTDIN(Filename: File);
144 if (std::error_code EC = ObjectOrErr.getError())
145 return errorCodeToError(EC);
146
147 // Clang uses the '.o' suffix for LTO bitcode.
148 if (identify_magic(magic: (*ObjectOrErr)->getBuffer()) == file_magic::bitcode)
149 ImageBinary.TheImageKind = object::IMG_Bitcode;
150 else if (sys::path::has_extension(path: File))
151 ImageBinary.TheImageKind =
152 getImageKind(Name: sys::path::extension(path: File).drop_front());
153 else
154 ImageBinary.TheImageKind = IMG_None;
155 ImageBinary.Image = std::move(*ObjectOrErr);
156 for (const auto &[Key, Value] : Args) {
157 if (Key == "kind") {
158 ImageBinary.TheOffloadKind = getOffloadKind(Name: Value);
159 } else if (Key != "file") {
160 ImageBinary.StringData[Key] = Value;
161 }
162 }
163 AllImages.emplace_back(Args: std::move(ImageBinary));
164 }
165 }
166
167 SmallString<0> Buffer;
168 if (Compress) {
169 compression::Format Format = CompressionFormat;
170 if (!CompressionFormat.getNumOccurrences() &&
171 !compression::zstd::isAvailable())
172 Format = compression::Format::Zlib;
173 if (const char *Reason = compression::getReasonIfUnsupported(F: Format))
174 return createStringError(EC: inconvertibleErrorCode(), S: Reason);
175 compression::Params Params(Format);
176 if (CompressionLevel.getNumOccurrences()) {
177 if (!CompressionFormat.getNumOccurrences())
178 return createStringError(
179 EC: inconvertibleErrorCode(),
180 S: "--compression-level requires --compression-format");
181 if (Error E = checkCompressionLevel(Format, Level: CompressionLevel))
182 return E;
183 Params.level = CompressionLevel;
184 }
185 Expected<SmallString<0>> CompressedOrErr =
186 OffloadBinary::write(OffloadingData: AllImages, Compress: Params);
187 if (!CompressedOrErr)
188 return CompressedOrErr.takeError();
189 Buffer = std::move(*CompressedOrErr);
190 } else {
191 Buffer = OffloadBinary::write(OffloadingData: AllImages);
192 }
193 if (Buffer.size() % OffloadBinary::getAlignment() != 0)
194 return createStringError(EC: inconvertibleErrorCode(),
195 S: "Offload binary has invalid size alignment");
196
197 if (Error E = writeFile(Filename: OutputFile, Data: StringRef(Buffer.data(), Buffer.size())))
198 return E;
199 return Error::success();
200}
201
202// Extract a single OffloadBinary, recursively handling nested OffloadBinaries.
203static Error extractBinary(const OffloadBinary *Binary, StringRef InputFile,
204 uint64_t &Idx, StringSaver &Saver) {
205 StringRef ImageData = Binary->getImage();
206
207 // Check if the image contains a nested OffloadBinary.
208 if (identify_magic(magic: ImageData) == file_magic::offload_binary) {
209 // Parse nested OffloadBinary.
210 MemoryBufferRef InnerBuffer(ImageData, "nested-offload-binary");
211 SmallVector<OffloadFile> InnerBinaries;
212 if (Error Err = extractOffloadBinaries(Buffer: InnerBuffer, Binaries&: InnerBinaries))
213 return Err;
214
215 // Recursively extract each nested binary.
216 for (const auto &InnerBinary : InnerBinaries) {
217 if (Error E =
218 extractBinary(Binary: InnerBinary.getBinary(), InputFile, Idx, Saver))
219 return E;
220 }
221 return Error::success();
222 }
223
224 // Base case: extract the actual device image.
225 std::string Filename;
226 raw_string_ostream SS(Filename);
227 SS << sys::path::stem(path: InputFile) << "-" << Binary->getTriple();
228 StringRef Arch = Binary->getArch();
229 if (!Arch.empty())
230 SS << "-" << Arch;
231 SS << "." << Idx++ << "." << getImageKindName(Name: Binary->getImageKind());
232
233 if (Error E = writeFile(Filename: Saver.save(S: Filename), Data: ImageData))
234 return E;
235
236 outs() << "Extracted: " << Filename << "\n";
237 return Error::success();
238}
239
240static Error unbundleImages() {
241 ErrorOr<std::unique_ptr<MemoryBuffer>> BufferOrErr =
242 MemoryBuffer::getFileOrSTDIN(Filename: InputFile);
243 if (std::error_code EC = BufferOrErr.getError())
244 return createFileError(F: InputFile, EC);
245 std::unique_ptr<MemoryBuffer> Buffer = std::move(*BufferOrErr);
246
247 // This data can be misaligned if extracted from an archive.
248 if (!isAddrAligned(Lhs: Align(OffloadBinary::getAlignment()),
249 Addr: Buffer->getBufferStart()))
250 Buffer = MemoryBuffer::getMemBufferCopy(InputData: Buffer->getBuffer(),
251 BufferName: Buffer->getBufferIdentifier());
252
253 SmallVector<OffloadFile> Binaries;
254 if (Error Err = extractOffloadBinaries(Buffer: *Buffer, Binaries))
255 return Err;
256
257 // If no filters specified, extract all images.
258 if (DeviceImages.empty()) {
259 BumpPtrAllocator Alloc;
260 StringSaver Saver(Alloc);
261 uint64_t Idx = 0;
262 for (const OffloadFile &File : Binaries) {
263 if (Error E = extractBinary(Binary: File.getBinary(), InputFile, Idx, Saver))
264 return E;
265 }
266 return Error::success();
267 }
268
269 // Try to extract each device image specified by the user from the input file.
270 for (StringRef Image : DeviceImages) {
271 BumpPtrAllocator Alloc;
272 StringSaver Saver(Alloc);
273 auto Args = getImageArguments(Image, Saver);
274
275 SmallVector<const OffloadBinary *> Extracted;
276 for (const OffloadFile &File : Binaries) {
277 const auto *Binary = File.getBinary();
278 // We handle the 'file', 'kind', and 'member' identifiers differently.
279 bool Match = llvm::all_of(Range&: Args, P: [&](auto &Arg) {
280 const auto [Key, Value] = Arg;
281 if (Key == "file")
282 return true;
283 if (Key == "kind")
284 return Binary->getOffloadKind() == getOffloadKind(Value);
285 if (Key == "member")
286 return sys::path::filename(
287 path: Binary->getMemoryBufferRef().getBufferIdentifier()) ==
288 Value;
289 return Binary->getString(Key) == Value;
290 });
291 if (Match)
292 Extracted.push_back(Elt: Binary);
293 }
294
295 if (Extracted.empty())
296 continue;
297
298 if (CreateArchive) {
299 if (!Args.count(Val: "file"))
300 return createStringError(EC: inconvertibleErrorCode(),
301 S: "Image must have a 'file' argument.");
302
303 SmallVector<NewArchiveMember> Members;
304 for (const OffloadBinary *Binary : Extracted)
305 Members.emplace_back(Args: MemoryBufferRef(
306 Binary->getImage(),
307 Binary->getMemoryBufferRef().getBufferIdentifier()));
308
309 if (Error E = writeArchive(
310 ArcName: Args["file"], NewMembers: Members, WriteSymtab: SymtabWritingMode::NormalSymtab,
311 Kind: Archive::getDefaultKind(), Deterministic: true, Thin: false, OldArchiveBuf: nullptr))
312 return E;
313 } else if (auto It = Args.find(Val: "file"); It != Args.end()) {
314 if (Extracted.size() > 1)
315 WithColor::warning(OS&: errs(), Prefix: PackagerExecutable)
316 << "Multiple inputs match to a single file, '" << It->second
317 << "'\n";
318 if (Error E = writeFile(Filename: It->second, Data: Extracted.back()->getImage()))
319 return E;
320 } else {
321 uint64_t Idx = 0;
322 for (const OffloadBinary *Binary : Extracted) {
323 if (Error E = extractBinary(Binary, InputFile, Idx, Saver))
324 return E;
325 }
326 }
327 }
328
329 return Error::success();
330}
331
332int main(int argc, const char **argv) {
333 sys::PrintStackTraceOnErrorSignal(Argv0: argv[0]);
334 cl::HideUnrelatedOptions(Category&: OffloadBinaryCategory);
335 cl::ParseCommandLineOptions(
336 argc, argv,
337 Overview: "A utility for bundling several object files into a single binary.\n"
338 "The output binary can then be embedded into the host section table\n"
339 "to create a fatbinary containing offloading code.\n");
340
341 if (sys::path::stem(path: argv[0]).ends_with(Suffix: "clang-offload-packager"))
342 WithColor::warning(OS&: errs(), Prefix: PackagerExecutable)
343 << "'clang-offload-packager' is deprecated. Use 'llvm-offload-binary' "
344 "instead.\n";
345
346 if (OutputFile.empty() && InputFile.empty()) {
347 cl::PrintHelpMessage();
348 return EXIT_SUCCESS;
349 }
350
351 PackagerExecutable = argv[0];
352 auto reportError = [argv](Error E) {
353 logAllUnhandledErrors(E: std::move(E), OS&: WithColor::error(OS&: errs(), Prefix: argv[0]));
354 return EXIT_FAILURE;
355 };
356
357 if (!InputFile.empty() && !OutputFile.empty())
358 return reportError(
359 createStringError(EC: inconvertibleErrorCode(),
360 S: "Packaging to an output file and extracting from an "
361 "input file are mutually exclusive."));
362
363 if (!OutputFile.empty()) {
364 if (Error Err = bundleImages())
365 return reportError(std::move(Err));
366 } else if (!InputFile.empty()) {
367 if (Error Err = unbundleImages())
368 return reportError(std::move(Err));
369 }
370
371 return EXIT_SUCCESS;
372}
373