1//===- ExportTrie.cpp -----------------------------------------------------===//
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 is a partial implementation of the Mach-O export trie format. It's
10// essentially a symbol table encoded as a compressed prefix trie, meaning that
11// the common prefixes of each symbol name are shared for a more compact
12// representation. The prefixes are stored on the edges of the trie, and one
13// edge can represent multiple characters. For example, given two exported
14// symbols _bar and _baz, we will have a trie like this (terminal nodes are
15// marked with an asterisk):
16//
17// +-+-+
18// | | // root node
19// +-+-+
20// |
21// | _ba
22// |
23// +-+-+
24// | |
25// +-+-+
26// r / \ z
27// / \
28// +-+-+ +-+-+
29// | * | | * |
30// +-+-+ +-+-+
31//
32// More documentation of the format can be found in
33// llvm/tools/obj2yaml/macho2yaml.cpp.
34//
35//===----------------------------------------------------------------------===//
36
37#include "ExportTrie.h"
38#include "Symbols.h"
39
40#include "lld/Common/ErrorHandler.h"
41#include "llvm/ADT/DenseMap.h"
42#include "llvm/BinaryFormat/MachO.h"
43#include "llvm/Support/LEB128.h"
44#include <optional>
45
46using namespace llvm;
47using namespace lld;
48using namespace lld::macho;
49
50namespace {
51
52struct Edge {
53 Edge(StringRef s, TrieNode *node) : substring(s), child(node) {}
54
55 StringRef substring;
56 struct TrieNode *child;
57};
58
59struct ExportInfo {
60 uint64_t address;
61 uint64_t ordinal = 0;
62 uint8_t flags = 0;
63 ExportInfo(const Symbol &sym, uint64_t imageBase)
64 : address(sym.getVA() - imageBase) {
65 using namespace llvm::MachO;
66 if (sym.isWeakDef())
67 flags |= EXPORT_SYMBOL_FLAGS_WEAK_DEFINITION;
68 if (sym.isTlv())
69 flags |= EXPORT_SYMBOL_FLAGS_KIND_THREAD_LOCAL;
70 // TODO: Add proper support for stub-and-resolver flags.
71
72 if (auto *defined = dyn_cast<Defined>(Val: &sym)) {
73 if (defined->isAbsolute())
74 flags |= EXPORT_SYMBOL_FLAGS_KIND_ABSOLUTE;
75 } else if (auto *dysym = dyn_cast<DylibSymbol>(Val: &sym)) {
76 flags |= EXPORT_SYMBOL_FLAGS_REEXPORT;
77 if (!dysym->isDynamicLookup())
78 ordinal = dysym->getFile()->ordinal;
79 }
80 }
81};
82
83} // namespace
84
85struct macho::TrieNode {
86 std::vector<Edge> edges;
87 std::optional<ExportInfo> info;
88 // Estimated offset from the start of the serialized trie to the current node.
89 // This will converge to the true offset when updateOffset() is run to a
90 // fixpoint.
91 size_t offset = 0;
92
93 uint32_t getTerminalSize() const;
94 // Returns whether the new estimated offset differs from the old one.
95 bool updateOffset(size_t &nextOffset);
96 void writeTo(uint8_t *buf) const;
97};
98
99// For regular symbols, the node layout (excluding the children) is
100//
101// uleb128 terminalSize;
102// uleb128 flags;
103// uleb128 address;
104//
105// For re-exported symbols, the layout is
106//
107// uleb128 terminalSize;
108// uleb128 flags;
109// uleb128 ordinal;
110// char[] originalName;
111//
112// If libfoo.dylib is linked against libbar.dylib, and libfoo exports an alias
113// _foo to a symbol _bar in libbar, then originalName will be "_bar". If libfoo
114// re-exports _bar directly (i.e. not via an alias), then originalName will be
115// the empty string.
116//
117// TODO: Support aliased re-exports. (Since we don't yet support these,
118// originalName will always be the empty string.)
119//
120// For stub-and-resolver nodes, the layout is
121//
122// uleb128 terminalSize;
123// uleb128 flags;
124// uleb128 stubAddress;
125// uleb128 resolverAddress;
126//
127// TODO: Support stub-and-resolver nodes.
128uint32_t TrieNode::getTerminalSize() const {
129 uint32_t size = getULEB128Size(Value: info->flags);
130 if (info->flags & MachO::EXPORT_SYMBOL_FLAGS_REEXPORT)
131 size += getULEB128Size(Value: info->ordinal) + 1; // + 1 for the null-terminator
132 else
133 size += getULEB128Size(Value: info->address);
134 return size;
135}
136
137bool TrieNode::updateOffset(size_t &nextOffset) {
138 // Size of the whole node (including the terminalSize and the outgoing edges.)
139 // In contrast, terminalSize only records the size of the other data in the
140 // node.
141 size_t nodeSize;
142 if (info) {
143 uint32_t terminalSize = getTerminalSize();
144 // Overall node size so far is the uleb128 size of the length of the symbol
145 // info + the symbol info itself.
146 nodeSize = terminalSize + getULEB128Size(Value: terminalSize);
147 } else {
148 nodeSize = 1; // Size of terminalSize (which has a value of 0)
149 }
150 // Compute size of all child edges.
151 ++nodeSize; // Byte for number of children.
152 for (const Edge &edge : edges) {
153 nodeSize += edge.substring.size() + 1 // String length.
154 + getULEB128Size(Value: edge.child->offset); // Offset len.
155 }
156 // On input, 'nextOffset' is the new preferred location for this node.
157 bool result = (offset != nextOffset);
158 // Store new location in node object for use by parents.
159 offset = nextOffset;
160 nextOffset += nodeSize;
161 return result;
162}
163
164void TrieNode::writeTo(uint8_t *buf) const {
165 buf += offset;
166 if (info) {
167 uint32_t terminalSize = getTerminalSize();
168 buf += encodeULEB128(Value: terminalSize, p: buf);
169 buf += encodeULEB128(Value: info->flags, p: buf);
170 if (info->flags & MachO::EXPORT_SYMBOL_FLAGS_REEXPORT) {
171 buf += encodeULEB128(Value: info->ordinal, p: buf);
172 *buf++ = 0; // empty originalName string
173 } else {
174 buf += encodeULEB128(Value: info->address, p: buf);
175 }
176 } else {
177 // TrieNode with no Symbol info.
178 *buf++ = 0; // terminalSize
179 }
180 // Add number of children. TODO: Handle case where we have more than 256.
181 assert(edges.size() < 256);
182 *buf++ = edges.size();
183 // Append each child edge substring and node offset.
184 for (const Edge &edge : edges) {
185 memcpy(dest: buf, src: edge.substring.data(), n: edge.substring.size());
186 buf += edge.substring.size();
187 *buf++ = '\0';
188 buf += encodeULEB128(Value: edge.child->offset, p: buf);
189 }
190}
191
192TrieBuilder::~TrieBuilder() {
193 for (TrieNode *node : nodes)
194 delete node;
195}
196
197TrieNode *TrieBuilder::makeNode() {
198 auto *node = new TrieNode();
199 nodes.emplace_back(args&: node);
200 return node;
201}
202
203// Like operator[], but returns -1 when pos is past the end of the name. -1
204// sorts below every byte, so "_foo" sorts before "_foobar".
205static int charAt(const Symbol *sym, size_t pos) {
206 StringRef str = sym->getName();
207 if (pos >= str.size())
208 return -1;
209 return static_cast<unsigned char>(str[pos]);
210}
211
212// Build the trie by performing a three-way radix quicksort: We start by sorting
213// the strings by their first characters, then sort the strings with the same
214// first characters by their second characters, and so on recursively. Each
215// time the prefixes diverge, we add a node to the trie.
216//
217// node: The most recently created node along this path in the trie (i.e.
218// the furthest from the root.)
219// lastPos: The prefix length of the most recently created node, i.e. the number
220// of characters along its path from the root.
221// pos: The string index we are currently sorting on. Note that each symbol
222// S contained in vec has the same prefix S[0...pos).
223void TrieBuilder::sortAndBuild(MutableArrayRef<const Symbol *> vec,
224 TrieNode *node, size_t lastPos, size_t pos) {
225tailcall:
226 if (vec.empty())
227 return;
228
229 // Create singletons in one go instead of doing a tail call per character.
230 if (vec.size() == 1) {
231 const Symbol *sym = vec.front();
232 StringRef suffix = sym->getName().drop_front(N: lastPos);
233 if (!suffix.empty()) {
234 TrieNode *newNode = makeNode();
235 node->edges.emplace_back(args&: suffix, args&: newNode);
236 node = newNode;
237 }
238 node->info = ExportInfo(*sym, imageBase);
239 return;
240 }
241
242 // Partition items so that items in [0, i) are less than the pivot,
243 // [i, j) are the same as the pivot, and [j, vec.size()) are greater than
244 // the pivot.
245 const Symbol *pivotSymbol = vec[vec.size() / 2];
246 int pivot = charAt(sym: pivotSymbol, pos);
247 size_t i = 0;
248 size_t j = vec.size();
249 for (size_t k = 0; k < j;) {
250 int c = charAt(sym: vec[k], pos);
251 if (c < pivot)
252 std::swap(a&: vec[i++], b&: vec[k++]);
253 else if (c > pivot)
254 std::swap(a&: vec[--j], b&: vec[k]);
255 else
256 k++;
257 }
258
259 bool isTerminal = pivot == -1;
260 bool prefixesDiverge = i != 0 || j != vec.size();
261 if (lastPos != pos && (isTerminal || prefixesDiverge)) {
262 TrieNode *newNode = makeNode();
263 node->edges.emplace_back(args: pivotSymbol->getName().slice(Start: lastPos, End: pos),
264 args&: newNode);
265 node = newNode;
266 lastPos = pos;
267 }
268
269 sortAndBuild(vec: vec.slice(N: 0, M: i), node, lastPos, pos);
270 sortAndBuild(vec: vec.slice(N: j), node, lastPos, pos);
271
272 if (isTerminal) {
273 assert(j - i == 1); // no duplicate symbols
274 node->info = ExportInfo(*pivotSymbol, imageBase);
275 } else {
276 // This is the tail-call-optimized version of the following:
277 // sortAndBuild(vec.slice(i, j - i), node, lastPos, pos + 1);
278 vec = vec.slice(N: i, M: j - i);
279 ++pos;
280 // Skip the rest of a common prefix instead of doing a tail call per
281 // character.
282 if (vec.size() > 1) {
283 StringRef firstName = vec.front()->getName();
284 size_t commonEnd = firstName.size();
285 for (const Symbol *sym : vec.drop_front()) {
286 StringRef name = sym->getName();
287 commonEnd = std::min(a: commonEnd, b: name.size());
288 size_t commonPos = pos;
289 while (commonPos < commonEnd && firstName[commonPos] == name[commonPos])
290 ++commonPos;
291 commonEnd = commonPos;
292 }
293 pos = commonEnd;
294 }
295 goto tailcall;
296 }
297}
298
299size_t TrieBuilder::build() {
300 if (exported.empty())
301 return 0;
302
303 TrieNode *root = makeNode();
304 sortAndBuild(vec: exported, node: root, lastPos: 0, pos: 0);
305
306 // Assign each node in the vector an offset in the trie stream, iterating
307 // until all uleb128 sizes have stabilized.
308 size_t offset;
309 bool more;
310 do {
311 offset = 0;
312 more = false;
313 for (TrieNode *node : nodes)
314 more |= node->updateOffset(nextOffset&: offset);
315 } while (more);
316
317 return offset;
318}
319
320void TrieBuilder::writeTo(uint8_t *buf) const {
321 for (TrieNode *node : nodes)
322 node->writeTo(buf);
323}
324
325namespace {
326
327// Parse a serialized trie and invoke a callback for each entry.
328class TrieParser {
329public:
330 TrieParser(const std::string &fileName, const uint8_t *buf, size_t size,
331 const TrieEntryCallback &callback)
332 : fileName(fileName), start(buf), end(start + size), callback(callback) {}
333
334 void parse(const uint8_t *buf, const Twine &cumulativeString,
335 DenseSet<size_t> &visited);
336
337 void parse() {
338 DenseSet<size_t> visited;
339 parse(buf: start, cumulativeString: "", visited);
340 }
341
342 const std::string fileName;
343 const uint8_t *start;
344 const uint8_t *end;
345 const TrieEntryCallback &callback;
346};
347
348} // namespace
349
350void TrieParser::parse(const uint8_t *buf, const Twine &cumulativeString,
351 DenseSet<size_t> &visited) {
352 if (buf >= end)
353 fatal(msg: fileName + ": export trie node offset points outside export section");
354
355 size_t currentOffset = buf - start;
356 visited.insert(V: currentOffset);
357
358 unsigned ulebSize;
359 uint64_t terminalSize = decodeULEB128(p: buf, n: &ulebSize);
360 buf += ulebSize;
361 uint64_t flags = 0;
362 size_t offset;
363 if (terminalSize != 0) {
364 flags = decodeULEB128(p: buf, n: &ulebSize);
365 callback(cumulativeString, flags);
366 }
367 buf += terminalSize;
368 uint8_t numEdges = *buf++;
369 for (uint8_t i = 0; i < numEdges; ++i) {
370 const char *cbuf = reinterpret_cast<const char *>(buf);
371 StringRef substring = StringRef(cbuf, strnlen(string: cbuf, maxlen: end - buf));
372 buf += substring.size() + 1;
373 offset = decodeULEB128(p: buf, n: &ulebSize);
374 buf += ulebSize;
375 if (visited.find(V: offset) != visited.end())
376 fatal(msg: fileName + ": export trie child node infinite loop");
377 parse(buf: start + offset, cumulativeString: cumulativeString + substring, visited);
378 }
379
380 visited.erase(V: currentOffset);
381}
382
383void macho::parseTrie(const std::string &fileName, const uint8_t *buf,
384 size_t size, const TrieEntryCallback &callback) {
385 if (size == 0)
386 return;
387
388 TrieParser(fileName, buf, size, callback).parse();
389}
390