1 //===- tools/dsymutil/MachODebugMapParser.cpp - Parse STABS debug maps ----===//
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
7 //===----------------------------------------------------------------------===//
9 #include "BinaryHolder.h"
11 #include "MachOUtils.h"
12 #include "llvm/ADT/Optional.h"
13 #include "llvm/Object/MachO.h"
14 #include "llvm/Support/Path.h"
15 #include "llvm/Support/WithColor.h"
16 #include "llvm/Support/raw_ostream.h"
20 using namespace llvm::dsymutil
;
21 using namespace llvm::object
;
23 class MachODebugMapParser
{
25 MachODebugMapParser(StringRef BinaryPath
, ArrayRef
<std::string
> Archs
,
26 StringRef PathPrefix
= "",
27 bool PaperTrailWarnings
= false, bool Verbose
= false)
28 : BinaryPath(BinaryPath
), Archs(Archs
.begin(), Archs
.end()),
29 PathPrefix(PathPrefix
), PaperTrailWarnings(PaperTrailWarnings
),
30 BinHolder(Verbose
), CurrentDebugMapObject(nullptr) {}
32 /// Parses and returns the DebugMaps of the input binary. The binary contains
33 /// multiple maps in case it is a universal binary.
34 /// \returns an error in case the provided BinaryPath doesn't exist
35 /// or isn't of a supported type.
36 ErrorOr
<std::vector
<std::unique_ptr
<DebugMap
>>> parse();
38 /// Walk the symbol table and dump it.
42 std::string BinaryPath
;
43 SmallVector
<StringRef
, 1> Archs
;
44 std::string PathPrefix
;
45 bool PaperTrailWarnings
;
47 /// Owns the MemoryBuffer for the main binary.
48 BinaryHolder BinHolder
;
49 /// Map of the binary symbol addresses.
50 StringMap
<uint64_t> MainBinarySymbolAddresses
;
51 StringRef MainBinaryStrings
;
52 /// The constructed DebugMap.
53 std::unique_ptr
<DebugMap
> Result
;
55 /// Map of the currently processed object file symbol addresses.
56 StringMap
<Optional
<uint64_t>> CurrentObjectAddresses
;
57 /// Element of the debug map corresponding to the current object file.
58 DebugMapObject
*CurrentDebugMapObject
;
60 /// Holds function info while function scope processing.
61 const char *CurrentFunctionName
;
62 uint64_t CurrentFunctionAddress
;
64 std::unique_ptr
<DebugMap
> parseOneBinary(const MachOObjectFile
&MainBinary
,
65 StringRef BinaryPath
);
68 switchToNewDebugMapObject(StringRef Filename
,
69 sys::TimePoint
<std::chrono::seconds
> Timestamp
);
70 void resetParserState();
71 uint64_t getMainBinarySymbolAddress(StringRef Name
);
72 std::vector
<StringRef
> getMainBinarySymbolNames(uint64_t Value
);
73 void loadMainBinarySymbols(const MachOObjectFile
&MainBinary
);
74 void loadCurrentObjectFileSymbols(const object::MachOObjectFile
&Obj
);
75 void handleStabSymbolTableEntry(uint32_t StringIndex
, uint8_t Type
,
76 uint8_t SectionIndex
, uint16_t Flags
,
79 template <typename STEType
> void handleStabDebugMapEntry(const STEType
&STE
) {
80 handleStabSymbolTableEntry(STE
.n_strx
, STE
.n_type
, STE
.n_sect
, STE
.n_desc
,
84 /// Dump the symbol table output header.
85 void dumpSymTabHeader(raw_ostream
&OS
, StringRef Arch
);
87 /// Dump the contents of nlist entries.
88 void dumpSymTabEntry(raw_ostream
&OS
, uint64_t Index
, uint32_t StringIndex
,
89 uint8_t Type
, uint8_t SectionIndex
, uint16_t Flags
,
92 template <typename STEType
>
93 void dumpSymTabEntry(raw_ostream
&OS
, uint64_t Index
, const STEType
&STE
) {
94 dumpSymTabEntry(OS
, Index
, STE
.n_strx
, STE
.n_type
, STE
.n_sect
, STE
.n_desc
,
97 void dumpOneBinaryStab(const MachOObjectFile
&MainBinary
,
98 StringRef BinaryPath
);
100 void Warning(const Twine
&Msg
, StringRef File
= StringRef()) {
101 WithColor::warning() << "("
102 << MachOUtils::getArchName(
103 Result
->getTriple().getArchName())
104 << ") " << File
<< " " << Msg
<< "\n";
106 if (PaperTrailWarnings
) {
108 Result
->addDebugMapObject(File
, sys::TimePoint
<std::chrono::seconds
>());
109 if (Result
->end() != Result
->begin())
110 (*--Result
->end())->addWarning(Msg
.str());
115 } // anonymous namespace
117 /// Reset the parser state corresponding to the current object
118 /// file. This is to be called after an object file is finished
120 void MachODebugMapParser::resetParserState() {
121 CurrentObjectAddresses
.clear();
122 CurrentDebugMapObject
= nullptr;
125 /// Create a new DebugMapObject. This function resets the state of the
126 /// parser that was referring to the last object file and sets
127 /// everything up to add symbols to the new one.
128 void MachODebugMapParser::switchToNewDebugMapObject(
129 StringRef Filename
, sys::TimePoint
<std::chrono::seconds
> Timestamp
) {
132 SmallString
<80> Path(PathPrefix
);
133 sys::path::append(Path
, Filename
);
135 auto ObjectEntry
= BinHolder
.getObjectEntry(Path
, Timestamp
);
137 auto Err
= ObjectEntry
.takeError();
138 Warning("unable to open object file: " + toString(std::move(Err
)),
143 auto Object
= ObjectEntry
->getObjectAs
<MachOObjectFile
>(Result
->getTriple());
145 auto Err
= Object
.takeError();
146 Warning("unable to open object file: " + toString(std::move(Err
)),
151 CurrentDebugMapObject
=
152 &Result
->addDebugMapObject(Path
, Timestamp
, MachO::N_OSO
);
153 loadCurrentObjectFileSymbols(*Object
);
156 static std::string
getArchName(const object::MachOObjectFile
&Obj
) {
157 Triple T
= Obj
.getArchTriple();
158 return T
.getArchName();
161 std::unique_ptr
<DebugMap
>
162 MachODebugMapParser::parseOneBinary(const MachOObjectFile
&MainBinary
,
163 StringRef BinaryPath
) {
164 loadMainBinarySymbols(MainBinary
);
165 ArrayRef
<uint8_t> UUID
= MainBinary
.getUuid();
166 Result
= std::make_unique
<DebugMap
>(MainBinary
.getArchTriple(), BinaryPath
, UUID
);
167 MainBinaryStrings
= MainBinary
.getStringTableData();
168 for (const SymbolRef
&Symbol
: MainBinary
.symbols()) {
169 const DataRefImpl
&DRI
= Symbol
.getRawDataRefImpl();
170 if (MainBinary
.is64Bit())
171 handleStabDebugMapEntry(MainBinary
.getSymbol64TableEntry(DRI
));
173 handleStabDebugMapEntry(MainBinary
.getSymbolTableEntry(DRI
));
177 return std::move(Result
);
180 // Table that maps Darwin's Mach-O stab constants to strings to allow printing.
181 // llvm-nm has very similar code, the strings used here are however slightly
182 // different and part of the interface of dsymutil (some project's build-systems
183 // parse the ouptut of dsymutil -s), thus they shouldn't be changed.
184 struct DarwinStabName
{
189 static const struct DarwinStabName DarwinStabNames
[] = {
190 {MachO::N_GSYM
, "N_GSYM"}, {MachO::N_FNAME
, "N_FNAME"},
191 {MachO::N_FUN
, "N_FUN"}, {MachO::N_STSYM
, "N_STSYM"},
192 {MachO::N_LCSYM
, "N_LCSYM"}, {MachO::N_BNSYM
, "N_BNSYM"},
193 {MachO::N_PC
, "N_PC"}, {MachO::N_AST
, "N_AST"},
194 {MachO::N_OPT
, "N_OPT"}, {MachO::N_RSYM
, "N_RSYM"},
195 {MachO::N_SLINE
, "N_SLINE"}, {MachO::N_ENSYM
, "N_ENSYM"},
196 {MachO::N_SSYM
, "N_SSYM"}, {MachO::N_SO
, "N_SO"},
197 {MachO::N_OSO
, "N_OSO"}, {MachO::N_LSYM
, "N_LSYM"},
198 {MachO::N_BINCL
, "N_BINCL"}, {MachO::N_SOL
, "N_SOL"},
199 {MachO::N_PARAMS
, "N_PARAM"}, {MachO::N_VERSION
, "N_VERS"},
200 {MachO::N_OLEVEL
, "N_OLEV"}, {MachO::N_PSYM
, "N_PSYM"},
201 {MachO::N_EINCL
, "N_EINCL"}, {MachO::N_ENTRY
, "N_ENTRY"},
202 {MachO::N_LBRAC
, "N_LBRAC"}, {MachO::N_EXCL
, "N_EXCL"},
203 {MachO::N_RBRAC
, "N_RBRAC"}, {MachO::N_BCOMM
, "N_BCOMM"},
204 {MachO::N_ECOMM
, "N_ECOMM"}, {MachO::N_ECOML
, "N_ECOML"},
205 {MachO::N_LENG
, "N_LENG"}, {0, nullptr}};
207 static const char *getDarwinStabString(uint8_t NType
) {
208 for (unsigned i
= 0; DarwinStabNames
[i
].Name
; i
++) {
209 if (DarwinStabNames
[i
].NType
== NType
)
210 return DarwinStabNames
[i
].Name
;
215 void MachODebugMapParser::dumpSymTabHeader(raw_ostream
&OS
, StringRef Arch
) {
216 OS
<< "-----------------------------------"
217 "-----------------------------------\n";
218 OS
<< "Symbol table for: '" << BinaryPath
<< "' (" << Arch
.data() << ")\n";
219 OS
<< "-----------------------------------"
220 "-----------------------------------\n";
221 OS
<< "Index n_strx n_type n_sect n_desc n_value\n";
222 OS
<< "======== -------- ------------------ ------ ------ ----------------\n";
225 void MachODebugMapParser::dumpSymTabEntry(raw_ostream
&OS
, uint64_t Index
,
226 uint32_t StringIndex
, uint8_t Type
,
227 uint8_t SectionIndex
, uint16_t Flags
,
230 OS
<< '[' << format_decimal(Index
, 6)
233 << format_hex_no_prefix(StringIndex
, 8)
236 << format_hex_no_prefix(Type
, 2) << " (";
238 if (Type
& MachO::N_STAB
)
239 OS
<< left_justify(getDarwinStabString(Type
), 13);
241 if (Type
& MachO::N_PEXT
)
245 switch (Type
& MachO::N_TYPE
) {
246 case MachO::N_UNDF
: // 0x0 undefined, n_sect == NO_SECT
249 case MachO::N_ABS
: // 0x2 absolute, n_sect == NO_SECT
252 case MachO::N_SECT
: // 0xe defined in section number n_sect
255 case MachO::N_PBUD
: // 0xc prebound undefined (defined in a dylib)
258 case MachO::N_INDR
: // 0xa indirect
262 OS
<< format_hex_no_prefix(Type
, 2) << " ";
265 if (Type
& MachO::N_EXT
)
273 << format_hex_no_prefix(SectionIndex
, 2)
276 << format_hex_no_prefix(Flags
, 4)
279 << format_hex_no_prefix(Value
, 16);
281 const char *Name
= &MainBinaryStrings
.data()[StringIndex
];
283 OS
<< " '" << Name
<< "'";
288 void MachODebugMapParser::dumpOneBinaryStab(const MachOObjectFile
&MainBinary
,
289 StringRef BinaryPath
) {
290 loadMainBinarySymbols(MainBinary
);
291 MainBinaryStrings
= MainBinary
.getStringTableData();
292 raw_ostream
&OS(llvm::outs());
294 dumpSymTabHeader(OS
, getArchName(MainBinary
));
296 for (const SymbolRef
&Symbol
: MainBinary
.symbols()) {
297 const DataRefImpl
&DRI
= Symbol
.getRawDataRefImpl();
298 if (MainBinary
.is64Bit())
299 dumpSymTabEntry(OS
, Idx
, MainBinary
.getSymbol64TableEntry(DRI
));
301 dumpSymTabEntry(OS
, Idx
, MainBinary
.getSymbolTableEntry(DRI
));
309 static bool shouldLinkArch(SmallVectorImpl
<StringRef
> &Archs
, StringRef Arch
) {
310 if (Archs
.empty() || is_contained(Archs
, "all") || is_contained(Archs
, "*"))
313 if (Arch
.startswith("arm") && Arch
!= "arm64" && is_contained(Archs
, "arm"))
316 SmallString
<16> ArchName
= Arch
;
317 if (Arch
.startswith("thumb"))
318 ArchName
= ("arm" + Arch
.substr(5)).str();
320 return is_contained(Archs
, ArchName
);
323 bool MachODebugMapParser::dumpStab() {
324 auto ObjectEntry
= BinHolder
.getObjectEntry(BinaryPath
);
326 auto Err
= ObjectEntry
.takeError();
327 WithColor::error() << "cannot load '" << BinaryPath
328 << "': " << toString(std::move(Err
)) << '\n';
332 auto Objects
= ObjectEntry
->getObjectsAs
<MachOObjectFile
>();
334 auto Err
= Objects
.takeError();
335 WithColor::error() << "cannot get '" << BinaryPath
336 << "' as MachO file: " << toString(std::move(Err
))
341 for (const auto *Object
: *Objects
)
342 if (shouldLinkArch(Archs
, Object
->getArchTriple().getArchName()))
343 dumpOneBinaryStab(*Object
, BinaryPath
);
348 /// This main parsing routine tries to open the main binary and if
349 /// successful iterates over the STAB entries. The real parsing is
350 /// done in handleStabSymbolTableEntry.
351 ErrorOr
<std::vector
<std::unique_ptr
<DebugMap
>>> MachODebugMapParser::parse() {
352 auto ObjectEntry
= BinHolder
.getObjectEntry(BinaryPath
);
354 return errorToErrorCode(ObjectEntry
.takeError());
357 auto Objects
= ObjectEntry
->getObjectsAs
<MachOObjectFile
>();
359 return errorToErrorCode(ObjectEntry
.takeError());
362 std::vector
<std::unique_ptr
<DebugMap
>> Results
;
363 for (const auto *Object
: *Objects
)
364 if (shouldLinkArch(Archs
, Object
->getArchTriple().getArchName()))
365 Results
.push_back(parseOneBinary(*Object
, BinaryPath
));
367 return std::move(Results
);
370 /// Interpret the STAB entries to fill the DebugMap.
371 void MachODebugMapParser::handleStabSymbolTableEntry(uint32_t StringIndex
,
373 uint8_t SectionIndex
,
376 if (!(Type
& MachO::N_STAB
))
379 const char *Name
= &MainBinaryStrings
.data()[StringIndex
];
381 // An N_OSO entry represents the start of a new object file description.
382 if (Type
== MachO::N_OSO
)
383 return switchToNewDebugMapObject(Name
, sys::toTimePoint(Value
));
385 if (Type
== MachO::N_AST
) {
386 SmallString
<80> Path(PathPrefix
);
387 sys::path::append(Path
, Name
);
388 Result
->addDebugMapObject(Path
, sys::toTimePoint(Value
), Type
);
392 // If the last N_OSO object file wasn't found, CurrentDebugMapObject will be
393 // null. Do not update anything until we find the next valid N_OSO entry.
394 if (!CurrentDebugMapObject
)
400 // This is a global variable. We need to query the main binary
401 // symbol table to find its address as it might not be in the
402 // debug map (for common symbols).
403 Value
= getMainBinarySymbolAddress(Name
);
406 // Functions are scopes in STABS. They have an end marker that
407 // contains the function size.
408 if (Name
[0] == '\0') {
410 Value
= CurrentFunctionAddress
;
411 Name
= CurrentFunctionName
;
414 CurrentFunctionName
= Name
;
415 CurrentFunctionAddress
= Value
;
424 auto ObjectSymIt
= CurrentObjectAddresses
.find(Name
);
426 // If the name of a (non-static) symbol is not in the current object, we
427 // check all its aliases from the main binary.
428 if (ObjectSymIt
== CurrentObjectAddresses
.end() && Type
!= MachO::N_STSYM
) {
429 for (const auto &Alias
: getMainBinarySymbolNames(Value
)) {
430 ObjectSymIt
= CurrentObjectAddresses
.find(Alias
);
431 if (ObjectSymIt
!= CurrentObjectAddresses
.end())
436 if (ObjectSymIt
== CurrentObjectAddresses
.end()) {
437 Warning("could not find object file symbol for symbol " + Twine(Name
));
441 if (!CurrentDebugMapObject
->addSymbol(Name
, ObjectSymIt
->getValue(), Value
,
443 Warning(Twine("failed to insert symbol '") + Name
+ "' in the debug map.");
448 /// Load the current object file symbols into CurrentObjectAddresses.
449 void MachODebugMapParser::loadCurrentObjectFileSymbols(
450 const object::MachOObjectFile
&Obj
) {
451 CurrentObjectAddresses
.clear();
453 for (auto Sym
: Obj
.symbols()) {
454 uint64_t Addr
= Sym
.getValue();
455 Expected
<StringRef
> Name
= Sym
.getName();
457 // TODO: Actually report errors helpfully.
458 consumeError(Name
.takeError());
461 // The value of some categories of symbols isn't meaningful. For
462 // example common symbols store their size in the value field, not
463 // their address. Absolute symbols have a fixed address that can
464 // conflict with standard symbols. These symbols (especially the
465 // common ones), might still be referenced by relocations. These
466 // relocations will use the symbol itself, and won't need an
467 // object file address. The object file address field is optional
468 // in the DebugMap, leave it unassigned for these symbols.
469 if (Sym
.getFlags() & (SymbolRef::SF_Absolute
| SymbolRef::SF_Common
))
470 CurrentObjectAddresses
[*Name
] = None
;
472 CurrentObjectAddresses
[*Name
] = Addr
;
476 /// Lookup a symbol address in the main binary symbol table. The
477 /// parser only needs to query common symbols, thus not every symbol's
478 /// address is available through this function.
479 uint64_t MachODebugMapParser::getMainBinarySymbolAddress(StringRef Name
) {
480 auto Sym
= MainBinarySymbolAddresses
.find(Name
);
481 if (Sym
== MainBinarySymbolAddresses
.end())
486 /// Get all symbol names in the main binary for the given value.
487 std::vector
<StringRef
>
488 MachODebugMapParser::getMainBinarySymbolNames(uint64_t Value
) {
489 std::vector
<StringRef
> Names
;
490 for (const auto &Entry
: MainBinarySymbolAddresses
) {
491 if (Entry
.second
== Value
)
492 Names
.push_back(Entry
.first());
497 /// Load the interesting main binary symbols' addresses into
498 /// MainBinarySymbolAddresses.
499 void MachODebugMapParser::loadMainBinarySymbols(
500 const MachOObjectFile
&MainBinary
) {
501 section_iterator Section
= MainBinary
.section_end();
502 MainBinarySymbolAddresses
.clear();
503 for (const auto &Sym
: MainBinary
.symbols()) {
504 Expected
<SymbolRef::Type
> TypeOrErr
= Sym
.getType();
506 // TODO: Actually report errors helpfully.
507 consumeError(TypeOrErr
.takeError());
510 SymbolRef::Type Type
= *TypeOrErr
;
511 // Skip undefined and STAB entries.
512 if ((Type
== SymbolRef::ST_Debug
) || (Type
== SymbolRef::ST_Unknown
))
514 // In theory, the only symbols of interest are the global variables. These
515 // are the only ones that need to be queried because the address of common
516 // data won't be described in the debug map. All other addresses should be
517 // fetched for the debug map. In reality, by playing with 'ld -r' and
518 // export lists, you can get symbols described as N_GSYM in the debug map,
519 // but associated with a local symbol. Gather all the symbols, but prefer
522 MainBinary
.getSymbolTableEntry(Sym
.getRawDataRefImpl()).n_type
;
523 bool Extern
= SymType
& (MachO::N_EXT
| MachO::N_PEXT
);
524 Expected
<section_iterator
> SectionOrErr
= Sym
.getSection();
526 // TODO: Actually report errors helpfully.
527 consumeError(SectionOrErr
.takeError());
530 Section
= *SectionOrErr
;
531 if (Section
== MainBinary
.section_end() || Section
->isText())
533 uint64_t Addr
= Sym
.getValue();
534 Expected
<StringRef
> NameOrErr
= Sym
.getName();
536 // TODO: Actually report errors helpfully.
537 consumeError(NameOrErr
.takeError());
540 StringRef Name
= *NameOrErr
;
541 if (Name
.size() == 0 || Name
[0] == '\0')
543 // Override only if the new key is global.
545 MainBinarySymbolAddresses
[Name
] = Addr
;
547 MainBinarySymbolAddresses
.try_emplace(Name
, Addr
);
553 llvm::ErrorOr
<std::vector
<std::unique_ptr
<DebugMap
>>>
554 parseDebugMap(StringRef InputFile
, ArrayRef
<std::string
> Archs
,
555 StringRef PrependPath
, bool PaperTrailWarnings
, bool Verbose
,
558 return DebugMap::parseYAMLDebugMap(InputFile
, PrependPath
, Verbose
);
560 MachODebugMapParser
Parser(InputFile
, Archs
, PrependPath
, PaperTrailWarnings
,
562 return Parser
.parse();
565 bool dumpStab(StringRef InputFile
, ArrayRef
<std::string
> Archs
,
566 StringRef PrependPath
) {
567 MachODebugMapParser
Parser(InputFile
, Archs
, PrependPath
, false);
568 return Parser
.dumpStab();
570 } // namespace dsymutil