LLVM 24.0.0git
OffloadBinary.h
Go to the documentation of this file.
1//===- OffloadBinary.h - Utilities for handling offloading code -----------===//
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 file contains the binary format used for bundling device metadata with
10// an associated device image. The data can then be stored inside a host object
11// file to create a fat binary and read by the linker. This is intended to be a
12// thin wrapper around the image itself. If this format becomes sufficiently
13// complex it should be moved to a standard binary format like msgpack or ELF.
14//
15//===----------------------------------------------------------------------===//
16
17#ifndef LLVM_OBJECT_OFFLOADBINARY_H
18#define LLVM_OBJECT_OFFLOADBINARY_H
19
20#include "llvm/ADT/ArrayRef.h"
21#include "llvm/ADT/MapVector.h"
23#include "llvm/ADT/StringRef.h"
24#include "llvm/Object/Binary.h"
27#include "llvm/Support/Error.h"
29#include <memory>
30
31namespace llvm {
32
33namespace object {
34
35/// The producer of the associated offloading image.
38 OFK_FIRST = (1 << 0),
39 OFK_OpenMP = (1 << 0),
40 OFK_Cuda = (1 << 1),
41 OFK_HIP = (1 << 2),
42 OFK_SYCL = (1 << 3),
43 OFK_OpenACC = (1 << 4),
44 OFK_LAST = (1 << 5),
45};
46
47/// The type of contents the offloading image contains.
59
60/// Flags associated with the Entry.
63 // Entry doesn't contain an image. Used to keep metadata only entries.
64 OIF_Metadata = (1 << 0),
65};
66
67/// A simple binary serialization of an offloading file. We use this format to
68/// embed the offloading image into the host executable so it can be extracted
69/// and used by the linker.
70///
71/// Many of these could be stored in the same section by the time the linker
72/// sees it so we mark this information with a header. The version is used to
73/// detect ABI stability and the size is used to find other offloading entries
74/// that may exist in the same section. All offsets are given as absolute byte
75/// offsets from the beginning of the file.
76class OffloadBinary : public Binary {
77public:
80
81 /// The current version of the binary used for backwards compatibility.
82 static const uint32_t Version = 3;
83
84 /// The offloading metadata that will be serialized to a memory buffer.
92
93 struct Header {
94 uint8_t Magic[4] = {0x10, 0xFF, 0x10, 0xAD}; // 0x10FF10AD magic bytes.
95 uint32_t Version = OffloadBinary::Version; // Version identifier.
96 uint64_t Size; // Size in bytes of this entire binary.
97 uint64_t EntriesOffset; // Offset in bytes to the start of entries block.
98 uint64_t EntriesCount; // Number of metadata entries in the binary.
99 uint64_t InflatedSize; // Original size of the binary if compressed.
100 };
101
102 struct Entry {
103 ImageKind TheImageKind; // The kind of the image stored.
104 OffloadKind TheOffloadKind; // The producer of this image.
105 uint32_t Flags; // Additional flags associated with the entry.
106 uint64_t StringOffset; // Offset in bytes to the string map.
107 uint64_t NumStrings; // Number of entries in the string map.
108 uint64_t ImageOffset; // Offset in bytes of the actual binary image.
109 uint64_t ImageSize; // Size in bytes of the binary image.
110 };
111
112 struct StringEntry {
115 uint64_t ValueSize; // Size of the value in bytes.
116 };
117
122
123 /// True if \p Buf is a compressed offload package, false otherwise.
124 LLVM_ABI static bool isCompressed(MemoryBufferRef Buf);
125
126 /// Attempt to extract and validate the header from the offloading binary in
127 /// \p Buf.
130
131 /// Attempt to parse the offloading binary stored in \p Buf.
132 /// For version 1 binaries, always returns a single OffloadBinary.
133 /// For version 2+ binaries:
134 /// - If \p Index is provided, returns the OffloadBinary at that index.
135 /// - If \p Index is std::nullopt, returns all OffloadBinary entries.
136 /// \param Buf The memory buffer containing the offload binary.
137 /// \param Index Optional index to select a specific entry. If not provided,
138 /// all entries are returned (version 2+ only).
139 /// \returns An array of unique pointers to OffloadBinary objects, or an
140 /// error.
142 create(MemoryBufferRef Buf, std::optional<uint64_t> Index = std::nullopt);
143
144 /// Serialize the contents of \p OffloadingData to a binary buffer to be read
145 /// later.
147 write(ArrayRef<OffloadingImage> OffloadingData);
148
149 /// Serialize \p OffloadingData to a compressed binary with \p Compress.
151 write(ArrayRef<OffloadingImage> OffloadingData, compression::Params Compress);
152
153 static uint64_t getAlignment() { return 8; }
154
155 ImageKind getImageKind() const { return TheEntry->TheImageKind; }
156 OffloadKind getOffloadKind() const { return TheEntry->TheOffloadKind; }
157 uint32_t getVersion() const { return TheHeader->Version; }
158 uint32_t getFlags() const { return TheEntry->Flags; }
159 uint64_t getSize() const { return TheHeader->Size; }
160 uint64_t getIndex() const { return Index; }
161
162 StringRef getTriple() const { return getString("triple"); }
163 StringRef getArch() const { return getString("arch"); }
165 return StringRef(&Buffer[TheEntry->ImageOffset], TheEntry->ImageSize);
166 }
167
168 // Iterator over all the key and value pairs in the binary.
169 string_iterator_range strings() const { return StringData; }
170
171 StringRef getString(StringRef Key) const { return StringData.lookup(Key); }
172
173 static bool classof(const Binary *V) { return V->isOffloadFile(); }
174
175private:
176 OffloadBinary(std::shared_ptr<MemoryBuffer> Owned, const Header *TheHeader,
177 const Entry *TheEntry, const uint64_t Index = 0)
178 : Binary(Binary::ID_Offload, *Owned), OwnedBuffer(std::move(Owned)),
179 Buffer(OwnedBuffer->getBufferStart()), TheHeader(TheHeader),
180 TheEntry(TheEntry), Index(Index) {
181 // StringEntryV1 and StringEntry have ABI compatible Key/ValueOffset fields,
182 // but different sizes, so we need to manually calculate offset.
183 const char *StringMapBegin = &Buffer[TheEntry->StringOffset];
184 const size_t StringEntrySize =
185 TheHeader->Version == 1 ? sizeof(StringEntryV1) : sizeof(StringEntry);
186 for (uint64_t I = 0, E = TheEntry->NumStrings; I != E; ++I) {
187 const char *StringEntryPtr = StringMapBegin + I * StringEntrySize;
188 const StringEntryV1 *EntryV1 =
189 reinterpret_cast<const StringEntryV1 *>(StringEntryPtr);
190 StringRef Key = &Buffer[EntryV1->KeyOffset];
191 if (TheHeader->Version == 1) {
192 StringData[Key] = &Buffer[EntryV1->ValueOffset];
193 } else {
194 const StringEntry *Entry =
195 reinterpret_cast<const StringEntry *>(StringEntryPtr);
196 StringData[Key] =
197 StringRef(&Buffer[Entry->ValueOffset], Entry->ValueSize);
198 }
199 }
200 }
201
202 OffloadBinary(const OffloadBinary &Other) = delete;
203
204 /// Owned uncompressed binary. Shared between entries parsed from one blob.
205 std::shared_ptr<MemoryBuffer> OwnedBuffer;
206 /// Map from keys to offsets in the binary.
207 MapVector<StringRef, StringRef> StringData;
208 /// Raw pointer to the MemoryBufferRef for convenience.
209 const char *Buffer;
210 /// Location of the header within the binary.
211 const Header *TheHeader;
212 /// Location of the metadata entries within the binary.
213 const Entry *TheEntry;
214 /// Index of the entry in the list of entries serialized in the Buffer.
215 const uint64_t Index;
216};
217
218/// A handle to a single OffloadBinary.
220public:
221 using TargetID = std::pair<StringRef, StringRef>;
222
223 OffloadFile() = default;
224 OffloadFile(std::unique_ptr<OffloadBinary> Binary)
225 : Binary(std::move(Binary)) {}
226
227 OffloadBinary *getBinary() { return Binary.get(); }
228 const OffloadBinary *getBinary() const { return Binary.get(); }
229
230 /// Make a deep copy of this offloading file.
232 auto NewBinaryOrErr = OffloadBinary::create(
233 getBinary()->getMemoryBufferRef(), getBinary()->getIndex());
234 assert(NewBinaryOrErr && "Failed to parse a copy of the binary?");
235 if (!NewBinaryOrErr)
236 llvm::consumeError(NewBinaryOrErr.takeError());
237 return OffloadFile(std::move((*NewBinaryOrErr)[0]));
238 }
239
240 /// We use the Triple and Architecture pair to group linker inputs together.
241 /// This conversion function lets us use these inputs in a hash-map.
242 operator TargetID() const {
243 return std::make_pair(getBinary()->getTriple(), getBinary()->getArch());
244 }
245
246private:
247 std::unique_ptr<OffloadBinary> Binary;
248};
249
250/// Extracts embedded device offloading code from a memory \p Buffer to a list
251/// of \p Binaries.
252LLVM_ABI Error extractOffloadBinaries(MemoryBufferRef Buffer,
254
255/// Convert a string \p Name to an image kind.
256LLVM_ABI ImageKind getImageKind(StringRef Name);
257
258/// Convert an image kind to its string representation.
259LLVM_ABI StringRef getImageKindName(ImageKind Name);
260
261/// Convert a string \p Name to an offload kind.
262LLVM_ABI OffloadKind getOffloadKind(StringRef Name);
263
264/// Convert an offload kind to its string representation.
265LLVM_ABI StringRef getOffloadKindName(OffloadKind Name);
266
267/// Returns true if an image built for target \p Provided can provide the device
268/// code for a request for target \p Requested. This is directional: a
269/// feature-unspecified or generic image serves a more specific request (e.g. a
270/// generic static-archive member pulled into a specific device-image group),
271/// but not vice versa. For AMDGPU a target id is a string conforming to the
272/// following BNF syntax:
273///
274/// target-id ::= '<arch> ( : <feature> ( '+' | '-' ) )*'
275///
276/// The features 'xnack' and 'sramecc' are currently supported. These can be in
277/// the state of on, off, and any when unspecified. A provided target marked as
278/// any can bind with either on or off.
279LLVM_ABI bool areTargetsCompatible(const OffloadFile::TargetID &Provided,
280 const OffloadFile::TargetID &Requested);
281
282/// Returns true if \p LHS and \p RHS denote the same logical target, i.e. the
283/// same processor and features.
284LLVM_ABI bool areTargetsEquivalent(const OffloadFile::TargetID &LHS,
285 const OffloadFile::TargetID &RHS);
286
287} // namespace object
288
289} // namespace llvm
290#endif
assert(UImm &&(UImm !=~static_cast< T >(0)) &&"Invalid immediate!")
uint64_t uint64_t
static GCRegistry::Add< CoreCLRGC > E("coreclr", "CoreCLR-compatible GC")
#define LLVM_ABI
Definition Compiler.h:211
#define I(x, y, z)
Definition MD5.cpp:57
This file implements a map that provides insertion order iteration.
This file defines the SmallString class.
Value * RHS
Value * LHS
Represent a constant reference to an array (0 or more elements consecutively in memory),...
Definition ArrayRef.h:40
Lightweight error class with error context and mandatory checking.
Definition Error.h:159
Tagged union holding either a T or a Error.
Definition Error.h:485
This class implements a map that also provides access to all stored values in a deterministic order.
Definition MapVector.h:39
typename VectorType::const_iterator const_iterator
Definition MapVector.h:46
SmallString - A SmallString is just a SmallVector with methods and accessors that make it work better...
Definition SmallString.h:28
This class consists of common code factored out of the SmallVector class to reduce code duplication b...
Represent a constant reference to a string, i.e.
Definition StringRef.h:56
A range adaptor for a pair of iterators.
Binary(unsigned int Type, MemoryBufferRef Source)
Definition Binary.cpp:20
A simple binary serialization of an offloading file.
static uint64_t getAlignment()
OffloadKind getOffloadKind() const
iterator_range< string_iterator > string_iterator_range
static LLVM_ABI Expected< SmallVector< std::unique_ptr< OffloadBinary > > > create(MemoryBufferRef Buf, std::optional< uint64_t > Index=std::nullopt)
Attempt to parse the offloading binary stored in Buf.
static LLVM_ABI SmallString< 0 > write(ArrayRef< OffloadingImage > OffloadingData)
Serialize the contents of OffloadingData to a binary buffer to be read later.
StringRef getString(StringRef Key) const
static LLVM_ABI bool isCompressed(MemoryBufferRef Buf)
True if Buf is a compressed offload package, false otherwise.
static LLVM_ABI Expected< const Header * > extractHeader(MemoryBufferRef Buf)
Attempt to extract and validate the header from the offloading binary in Buf.
StringRef getTriple() const
ImageKind getImageKind() const
static bool classof(const Binary *V)
string_iterator_range strings() const
static const uint32_t Version
The current version of the binary used for backwards compatibility.
MapVector< StringRef, StringRef >::const_iterator string_iterator
const OffloadBinary * getBinary() const
std::pair< StringRef, StringRef > TargetID
OffloadFile copy() const
Make a deep copy of this offloading file.
OffloadFile(std::unique_ptr< OffloadBinary > Binary)
OffloadBinary * getBinary()
StringMapEntry< EmptyStringSetTag > StringEntry
StringEntry keeps data of the string: the length, external offset and a string body which is placed r...
Definition StringPool.h:23
OffloadEntryFlags
Flags associated with the Entry.
OffloadKind
The producer of the associated offloading image.
ImageKind
The type of contents the offloading image contains.
This is an optimization pass for GlobalISel generic memory operations.
LLVM_ATTRIBUTE_VISIBILITY_DEFAULT AnalysisKey InnerAnalysisManagerProxy< AnalysisManagerT, IRUnitT, ExtraArgTs... >::Key
@ Other
Any other memory.
Definition ModRef.h:68
OutputIt move(R &&Range, OutputIt Out)
Provide wrappers to std::move which take ranges instead of having to pass begin/end explicitly.
Definition STLExtras.h:1933
void consumeError(Error Err)
Consume a Error without doing anything.
Definition Error.h:1106
Implement std::hash so that hash_code can be used in STL containers.
Definition BitVector.h:879
The offloading metadata that will be serialized to a memory buffer.
std::unique_ptr< MemoryBuffer > Image
MapVector< StringRef, StringRef > StringData