LLVM 18.0.0git
Symbolize.h
Go to the documentation of this file.
1//===- Symbolize.h ----------------------------------------------*- C++ -*-===//
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// Header for LLVM symbolization library.
10//
11//===----------------------------------------------------------------------===//
12
13#ifndef LLVM_DEBUGINFO_SYMBOLIZE_SYMBOLIZE_H
14#define LLVM_DEBUGINFO_SYMBOLIZE_SYMBOLIZE_H
15
16#include "llvm/ADT/StringMap.h"
17#include "llvm/ADT/ilist_node.h"
20#include "llvm/Object/Binary.h"
21#include "llvm/Object/BuildID.h"
22#include "llvm/Support/Error.h"
23#include <algorithm>
24#include <cstdint>
25#include <map>
26#include <memory>
27#include <string>
28#include <utility>
29#include <vector>
30
31namespace llvm {
32namespace object {
33class ELFObjectFileBase;
34class MachOObjectFile;
35class ObjectFile;
36struct SectionedAddress;
37} // namespace object
38
39namespace symbolize {
40
41class SymbolizableModule;
42
43using namespace object;
44
47
48class CachedBinary;
49
51public:
52 struct Options {
53 FunctionNameKind PrintFunctions = FunctionNameKind::LinkageName;
54 FileLineInfoKind PathStyle = FileLineInfoKind::AbsoluteFilePath;
55 bool UseSymbolTable = true;
56 bool Demangle = true;
57 bool RelativeAddresses = false;
58 bool UntagAddresses = false;
59 bool UseDIA = false;
60 std::string DefaultArch;
61 std::vector<std::string> DsymHints;
62 std::string FallbackDebugPath;
63 std::string DWPName;
64 std::vector<std::string> DebugFileDirectory;
65 size_t MaxCacheSize =
66 sizeof(size_t) == 4
67 ? 512 * 1024 * 1024 /* 512 MiB */
68 : static_cast<size_t>(4ULL * 1024 * 1024 * 1024) /* 4 GiB */;
69 };
70
72 LLVMSymbolizer(const Options &Opts);
73
75
76 // Overloads accepting ObjectFile does not support COFF currently
78 object::SectionedAddress ModuleOffset);
80 object::SectionedAddress ModuleOffset);
82 object::SectionedAddress ModuleOffset);
85 object::SectionedAddress ModuleOffset);
87 symbolizeInlinedCode(const std::string &ModuleName,
88 object::SectionedAddress ModuleOffset);
91 object::SectionedAddress ModuleOffset);
92
94 object::SectionedAddress ModuleOffset);
96 object::SectionedAddress ModuleOffset);
98 object::SectionedAddress ModuleOffset);
100 symbolizeFrame(const ObjectFile &Obj, object::SectionedAddress ModuleOffset);
102 symbolizeFrame(const std::string &ModuleName,
103 object::SectionedAddress ModuleOffset);
106 object::SectionedAddress ModuleOffset);
107 void flush();
108
109 // Evict entries from the binary cache until it is under the maximum size
110 // given in the options. Calling this invalidates references in the DI...
111 // objects returned by the methods above.
112 void pruneCache();
113
114 static std::string
115 DemangleName(const std::string &Name,
116 const SymbolizableModule *DbiModuleDescriptor);
117
118 void setBuildIDFetcher(std::unique_ptr<BuildIDFetcher> Fetcher) {
119 BIDFetcher = std::move(Fetcher);
120 }
121
122 /// Returns a SymbolizableModule or an error if loading debug info failed.
123 /// Only one attempt is made to load a module, and errors during loading are
124 /// only reported once. Subsequent calls to get module info for a module that
125 /// failed to load will return nullptr.
127 getOrCreateModuleInfo(const std::string &ModuleName);
128
129private:
130 // Bundles together object file with code/data and object file with
131 // corresponding debug info. These objects can be the same.
132 using ObjectPair = std::pair<const ObjectFile *, const ObjectFile *>;
133
134 template <typename T>
136 symbolizeCodeCommon(const T &ModuleSpecifier,
137 object::SectionedAddress ModuleOffset);
138 template <typename T>
140 symbolizeInlinedCodeCommon(const T &ModuleSpecifier,
141 object::SectionedAddress ModuleOffset);
142 template <typename T>
143 Expected<DIGlobal> symbolizeDataCommon(const T &ModuleSpecifier,
144 object::SectionedAddress ModuleOffset);
145 template <typename T>
147 symbolizeFrameCommon(const T &ModuleSpecifier,
148 object::SectionedAddress ModuleOffset);
149
151
152 /// Returns a SymbolizableModule or an error if loading debug info failed.
153 /// Unlike the above, errors are reported each time, since they are more
154 /// likely to be transient.
157
159 createModuleInfo(const ObjectFile *Obj, std::unique_ptr<DIContext> Context,
161
162 ObjectFile *lookUpDsymFile(const std::string &Path,
163 const MachOObjectFile *ExeObj,
164 const std::string &ArchName);
165 ObjectFile *lookUpDebuglinkObject(const std::string &Path,
166 const ObjectFile *Obj,
167 const std::string &ArchName);
168 ObjectFile *lookUpBuildIDObject(const std::string &Path,
169 const ELFObjectFileBase *Obj,
170 const std::string &ArchName);
171
172 bool findDebugBinary(const std::string &OrigPath,
173 const std::string &DebuglinkName, uint32_t CRCHash,
174 std::string &Result);
175
176 bool getOrFindDebugBinary(const ArrayRef<uint8_t> BuildID,
177 std::string &Result);
178
179 /// Returns pair of pointers to object and debug object.
180 Expected<ObjectPair> getOrCreateObjectPair(const std::string &Path,
181 const std::string &ArchName);
182
183 /// Return a pointer to object file at specified path, for a specified
184 /// architecture (e.g. if path refers to a Mach-O universal binary, only one
185 /// object file from it will be returned).
186 Expected<ObjectFile *> getOrCreateObject(const std::string &Path,
187 const std::string &ArchName);
188
189 /// Update the LRU cache order when a binary is accessed.
190 void recordAccess(CachedBinary &Bin);
191
192 std::map<std::string, std::unique_ptr<SymbolizableModule>, std::less<>>
193 Modules;
194 StringMap<std::string> BuildIDPaths;
195
196 /// Contains cached results of getOrCreateObjectPair().
197 std::map<std::pair<std::string, std::string>, ObjectPair>
198 ObjectPairForPathArch;
199
200 /// Contains parsed binary for each path, or parsing error.
201 std::map<std::string, CachedBinary> BinaryForPath;
202
203 /// A list of cached binaries in LRU order.
204 simple_ilist<CachedBinary> LRUBinaries;
205 /// Sum of the sizes of the cached binaries.
206 size_t CacheSize = 0;
207
208 /// Parsed object file for path/architecture pair, where "path" refers
209 /// to Mach-O universal binary.
210 std::map<std::pair<std::string, std::string>, std::unique_ptr<ObjectFile>>
211 ObjectForUBPathAndArch;
212
213 Options Opts;
214
215 std::unique_ptr<BuildIDFetcher> BIDFetcher;
216};
217
218// A binary intrusively linked into a LRU cache list. If the binary is empty,
219// then the entry marks that an error occurred, and it is not part of the LRU
220// list.
221class CachedBinary : public ilist_node<CachedBinary> {
222public:
223 CachedBinary() = default;
225
228
229 // Add an action to be performed when the binary is evicted, before all
230 // previously registered evictors.
231 void pushEvictor(std::function<void()> Evictor);
232
233 // Run all registered evictors in the reverse of the order in which they were
234 // added.
235 void evict() {
236 if (Evictor)
237 Evictor();
238 }
239
240 size_t size() { return Bin.getBinary()->getData().size(); }
241
242private:
244 std::function<void()> Evictor;
245};
246
247} // end namespace symbolize
248} // end namespace llvm
249
250#endif // LLVM_DEBUGINFO_SYMBOLIZE_SYMBOLIZE_H
This file defines the StringMap class.
This file declares a library for handling Build IDs and using them to find debug info.
DILineInfoSpecifier::FunctionNameKind FunctionNameKind
std::string Name
const char LLVMTargetMachineRef LLVMPassBuilderOptionsRef Options
ArrayRef - Represent a constant reference to an array (0 or more elements consecutively in memory),...
Definition: ArrayRef.h:41
Tagged union holding either a T or a Error.
Definition: Error.h:474
This is a 'vector' (really, a variable-sized array), optimized for the case when the array is small.
Definition: SmallVector.h:1200
StringMap - This is an unconventional map that is specialized for handling keys that are "strings",...
Definition: StringMap.h:112
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:50
This class is the base class for all object file types.
Definition: ObjectFile.h:229
A simple intrusive list implementation.
Definition: simple_ilist.h:81
CachedBinary(OwningBinary< Binary > Bin)
Definition: Symbolize.h:224
OwningBinary< Binary > * operator->()
Definition: Symbolize.h:227
void pushEvictor(std::function< void()> Evictor)
Definition: Symbolize.cpp:740
OwningBinary< Binary > & operator*()
Definition: Symbolize.h:226
Expected< DIInliningInfo > symbolizeInlinedCode(const ObjectFile &Obj, object::SectionedAddress ModuleOffset)
Definition: Symbolize.cpp:131
Expected< SymbolizableModule * > getOrCreateModuleInfo(const std::string &ModuleName)
Returns a SymbolizableModule or an error if loading debug info failed.
Definition: Symbolize.cpp:555
Expected< DILineInfo > symbolizeCode(const ObjectFile &Obj, object::SectionedAddress ModuleOffset)
Definition: Symbolize.cpp:82
static std::string DemangleName(const std::string &Name, const SymbolizableModule *DbiModuleDescriptor)
Definition: Symbolize.cpp:691
Expected< DIGlobal > symbolizeData(const ObjectFile &Obj, object::SectionedAddress ModuleOffset)
Definition: Symbolize.cpp:176
Expected< std::vector< DILocal > > symbolizeFrame(const ObjectFile &Obj, object::SectionedAddress ModuleOffset)
Definition: Symbolize.cpp:217
void setBuildIDFetcher(std::unique_ptr< BuildIDFetcher > Fetcher)
Definition: Symbolize.h:118
This file defines the ilist_node class template, which is a convenient base class for creating classe...
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
DINameKind
A DINameKind is passed to name search methods to specify a preference regarding the type of name reso...
Definition: DIContext.h:140
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:1854
Implement std::hash so that hash_code can be used in STL containers.
Definition: BitVector.h:858
DINameKind FunctionNameKind
Definition: DIContext.h:155
std::vector< std::string > DebugFileDirectory
Definition: Symbolize.h:64
std::vector< std::string > DsymHints
Definition: Symbolize.h:61