LLVM 20.0.0git
DIContext.h
Go to the documentation of this file.
1//===- DIContext.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// This file defines DIContext, an abstract data structure that holds
10// debug information data.
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_DEBUGINFO_DICONTEXT_H
15#define LLVM_DEBUGINFO_DICONTEXT_H
16
21#include <cassert>
22#include <cstdint>
23#include <memory>
24#include <optional>
25#include <string>
26#include <tuple>
27#include <utility>
28
29namespace llvm {
30
31/// A format-neutral container for source line information.
32struct DILineInfo {
33 static constexpr const char *const ApproxString = "(approximate)";
34 // DILineInfo contains "<invalid>" for function/filename it cannot fetch.
35 static constexpr const char *const BadString = "<invalid>";
36 // Use "??" instead of "<invalid>" to make our output closer to addr2line.
37 static constexpr const char *const Addr2LineBadString = "??";
38 std::string FileName;
39 std::string FunctionName;
40 std::string StartFileName;
41 // Full source corresponding to `FileName`
42 std::optional<StringRef> Source;
43 // Source code for this particular line
44 // (in case if `Source` is not available)
45 std::optional<StringRef> LineSource;
49 std::optional<uint64_t> StartAddress;
50
51 // DWARF-specific.
53
54 bool IsApproximateLine = false;
57 }
58
59 bool operator==(const DILineInfo &RHS) const {
60 return Line == RHS.Line && Column == RHS.Column &&
61 FileName == RHS.FileName && FunctionName == RHS.FunctionName &&
62 StartFileName == RHS.StartFileName && StartLine == RHS.StartLine &&
63 Discriminator == RHS.Discriminator;
64 }
65
66 bool operator!=(const DILineInfo &RHS) const { return !(*this == RHS); }
67
68 bool operator<(const DILineInfo &RHS) const {
69 return std::tie(FileName, FunctionName, StartFileName, Line, Column,
71 std::tie(RHS.FileName, RHS.FunctionName, RHS.StartFileName, RHS.Line,
72 RHS.Column, RHS.StartLine, RHS.Discriminator);
73 }
74
75 explicit operator bool() const { return *this != DILineInfo(); }
76
78 OS << "Line info: ";
79 if (FileName != BadString)
80 OS << "file '" << FileName << "', ";
82 OS << "function '" << FunctionName << "', ";
83 OS << "line " << Line << ", ";
84 OS << "column " << Column << ", ";
86 OS << "start file '" << StartFileName << "', ";
87 OS << "start line " << StartLine << '\n';
88 }
89};
90
92
93/// A format-neutral container for inlined code description.
96
97public:
98 DIInliningInfo() = default;
99
100 /// Returns the frame at `Index`. Frames are stored in bottom-up
101 /// (leaf-to-root) order with increasing index.
102 const DILineInfo &getFrame(unsigned Index) const {
103 assert(Index < Frames.size());
104 return Frames[Index];
105 }
106
108 assert(Index < Frames.size());
109 return &Frames[Index];
110 }
111
112 uint32_t getNumberOfFrames() const { return Frames.size(); }
113
114 void addFrame(const DILineInfo &Frame) { Frames.push_back(Frame); }
115
116 void resize(unsigned i) { Frames.resize(i); }
117};
118
119/// Container for description of a global variable.
120struct DIGlobal {
121 std::string Name;
124 std::string DeclFile;
126
127 DIGlobal() : Name(DILineInfo::BadString) {}
128};
129
130struct DILocal {
131 std::string FunctionName;
132 std::string Name;
133 std::string DeclFile;
135 std::optional<int64_t> FrameOffset;
136 std::optional<uint64_t> Size;
137 std::optional<uint64_t> TagOffset;
138};
139
140/// A DINameKind is passed to name search methods to specify a
141/// preference regarding the type of name resolution the caller wants.
143
144/// Controls which fields of DILineInfo container should be filled
145/// with data.
147 enum class FileLineInfoKind {
148 None,
149 // RawValue is whatever the compiler stored in the filename table. Could be
150 // a full path, could be something else.
151 RawValue,
153 // Relative to the compilation directory.
156 };
161
162 DILineInfoSpecifier(FileLineInfoKind FLIKind = FileLineInfoKind::RawValue,
163 FunctionNameKind FNKind = FunctionNameKind::None,
164 bool ApproximateLine = false)
166
167 inline bool operator==(const DILineInfoSpecifier &RHS) const {
168 return FLIKind == RHS.FLIKind && FNKind == RHS.FNKind;
169 }
170};
171
172/// This is just a helper to programmatically construct DIDumpType.
174#define HANDLE_DWARF_SECTION(ENUM_NAME, ELF_NAME, CMDLINE_NAME, OPTION) \
175 DIDT_ID_##ENUM_NAME,
176#include "llvm/BinaryFormat/Dwarf.def"
177#undef HANDLE_DWARF_SECTION
181static_assert(DIDT_ID_Count <= 32, "section types overflow storage");
182
183/// Selects which debug sections get dumped.
184enum DIDumpType : unsigned {
186 DIDT_All = ~0U,
187#define HANDLE_DWARF_SECTION(ENUM_NAME, ELF_NAME, CMDLINE_NAME, OPTION) \
188 DIDT_##ENUM_NAME = 1U << DIDT_ID_##ENUM_NAME,
189#include "llvm/BinaryFormat/Dwarf.def"
190#undef HANDLE_DWARF_SECTION
192};
193
194/// Container for dump options that control which debug information will be
195/// dumped.
197 unsigned DumpType = DIDT_All;
198 unsigned ChildRecurseDepth = -1U;
199 unsigned ParentRecurseDepth = -1U;
200 uint16_t Version = 0; // DWARF version to assume when extracting.
201 uint8_t AddrSize = 4; // Address byte size to assume when extracting.
202 bool ShowAddresses = true;
203 bool ShowChildren = false;
204 bool ShowParents = false;
205 bool ShowForm = false;
206 bool SummarizeTypes = false;
207 bool Verbose = false;
208 bool DisplayRawContents = false;
209 bool IsEH = false;
210 bool DumpNonSkeleton = false;
213 std::function<llvm::StringRef(uint64_t DwarfRegNum, bool IsEH)>
215
216 /// Return default option set for printing a single DIE without children.
218 DIDumpOptions Opts;
219 Opts.ChildRecurseDepth = 0;
220 Opts.ParentRecurseDepth = 0;
221 return Opts;
222 }
223
224 /// Return the options with RecurseDepth set to 0 unless explicitly required.
226 DIDumpOptions Opts = *this;
227 if (ChildRecurseDepth == -1U && !ShowChildren)
228 Opts.ChildRecurseDepth = 0;
229 if (ParentRecurseDepth == -1U && !ShowParents)
230 Opts.ParentRecurseDepth = 0;
231 return Opts;
232 }
233
234 std::function<void(Error)> RecoverableErrorHandler =
237};
238
240public:
242
243 DIContext(DIContextKind K) : Kind(K) {}
244 virtual ~DIContext() = default;
245
246 DIContextKind getKind() const { return Kind; }
247
248 virtual void dump(raw_ostream &OS, DIDumpOptions DumpOpts) = 0;
249
250 virtual bool verify(raw_ostream &OS, DIDumpOptions DumpOpts = {}) {
251 // No verifier? Just say things went well.
252 return true;
253 }
254
257 DILineInfoSpecifier Specifier = DILineInfoSpecifier()) = 0;
258 virtual DILineInfo
262 DILineInfoSpecifier Specifier = DILineInfoSpecifier()) = 0;
265 DILineInfoSpecifier Specifier = DILineInfoSpecifier()) = 0;
266
267 virtual std::vector<DILocal>
269
270private:
271 const DIContextKind Kind;
272};
273
274/// An inferface for inquiring the load address of a loaded object file
275/// to be used by the DIContext implementations when applying relocations
276/// on the fly.
278protected:
279 LoadedObjectInfo() = default;
281
282public:
283 virtual ~LoadedObjectInfo() = default;
284
285 /// Obtain the Load Address of a section by SectionRef.
286 ///
287 /// Calculate the address of the given section.
288 /// The section need not be present in the local address space. The addresses
289 /// need to be consistent with the addresses used to query the DIContext and
290 /// the output of this function should be deterministic, i.e. repeated calls
291 /// with the same Sec should give the same address.
293 return 0;
294 }
295
296 /// If conveniently available, return the content of the given Section.
297 ///
298 /// When the section is available in the local address space, in relocated
299 /// (loaded) form, e.g. because it was relocated by a JIT for execution, this
300 /// function should provide the contents of said section in `Data`. If the
301 /// loaded section is not available, or the cost of retrieving it would be
302 /// prohibitive, this function should return false. In that case, relocations
303 /// will be read from the local (unrelocated) object file and applied on the
304 /// fly. Note that this method is used purely for optimzation purposes in the
305 /// common case of JITting in the local address space, so returning false
306 /// should always be correct.
308 StringRef &Data) const {
309 return false;
310 }
311
312 // FIXME: This is untested and unused anywhere in the LLVM project, it's
313 // used/needed by Julia (an external project). It should have some coverage
314 // (at least tests, but ideally example functionality).
315 /// Obtain a copy of this LoadedObjectInfo.
316 virtual std::unique_ptr<LoadedObjectInfo> clone() const = 0;
317};
318
319template <typename Derived, typename Base = LoadedObjectInfo>
321protected:
324
325public:
326 template <typename... Ts>
327 LoadedObjectInfoHelper(Ts &&...Args) : Base(std::forward<Ts>(Args)...) {}
328
329 std::unique_ptr<llvm::LoadedObjectInfo> clone() const override {
330 return std::make_unique<Derived>(static_cast<const Derived &>(*this));
331 }
332};
333
334} // end namespace llvm
335
336#endif // LLVM_DEBUGINFO_DICONTEXT_H
uint64_t Size
assert(ImpDefSCC.getReg()==AMDGPU::SCC &&ImpDefSCC.isDef())
raw_pwrite_stream & OS
This file defines the SmallVector class.
Value * RHS
virtual std::vector< DILocal > getLocalsForAddress(object::SectionedAddress Address)=0
virtual DIInliningInfo getInliningInfoForAddress(object::SectionedAddress Address, DILineInfoSpecifier Specifier=DILineInfoSpecifier())=0
virtual DILineInfo getLineInfoForDataAddress(object::SectionedAddress Address)=0
virtual DILineInfo getLineInfoForAddress(object::SectionedAddress Address, DILineInfoSpecifier Specifier=DILineInfoSpecifier())=0
virtual DILineInfoTable getLineInfoForAddressRange(object::SectionedAddress Address, uint64_t Size, DILineInfoSpecifier Specifier=DILineInfoSpecifier())=0
virtual bool verify(raw_ostream &OS, DIDumpOptions DumpOpts={})
Definition: DIContext.h:250
virtual ~DIContext()=default
virtual void dump(raw_ostream &OS, DIDumpOptions DumpOpts)=0
DIContextKind getKind() const
Definition: DIContext.h:246
DIContext(DIContextKind K)
Definition: DIContext.h:243
A format-neutral container for inlined code description.
Definition: DIContext.h:94
DIInliningInfo()=default
const DILineInfo & getFrame(unsigned Index) const
Returns the frame at Index.
Definition: DIContext.h:102
uint32_t getNumberOfFrames() const
Definition: DIContext.h:112
void addFrame(const DILineInfo &Frame)
Definition: DIContext.h:114
DILineInfo * getMutableFrame(unsigned Index)
Definition: DIContext.h:107
void resize(unsigned i)
Definition: DIContext.h:116
Lightweight error class with error context and mandatory checking.
Definition: Error.h:160
An inferface for inquiring the load address of a loaded object file to be used by the DIContext imple...
Definition: DIContext.h:277
virtual std::unique_ptr< LoadedObjectInfo > clone() const =0
Obtain a copy of this LoadedObjectInfo.
LoadedObjectInfo(const LoadedObjectInfo &)=default
virtual bool getLoadedSectionContents(const object::SectionRef &Sec, StringRef &Data) const
If conveniently available, return the content of the given Section.
Definition: DIContext.h:307
virtual ~LoadedObjectInfo()=default
virtual uint64_t getSectionLoadAddress(const object::SectionRef &Sec) const
Obtain the Load Address of a section by SectionRef.
Definition: DIContext.h:292
size_t size() const
Definition: SmallVector.h:92
void resize(size_type N)
Definition: SmallVector.h:652
void push_back(const T &Elt)
Definition: SmallVector.h:427
This is a 'vector' (really, a variable-sized array), optimized for the case when the array is small.
Definition: SmallVector.h:1210
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:50
static void defaultWarningHandler(Error Warning)
Implement default handling for Warning.
Definition: WithColor.cpp:164
static void defaultErrorHandler(Error Err)
Implement default handling for Error.
Definition: WithColor.cpp:158
This is a value type class that represents a single section in the list of sections in the object fil...
Definition: ObjectFile.h:81
This class implements an extremely fast bulk output stream that can only output to a stream.
Definition: raw_ostream.h:52
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:142
DIDumpTypeCounter
This is just a helper to programmatically construct DIDumpType.
Definition: DIContext.h:173
@ DIDT_ID_Count
Definition: DIContext.h:179
@ DIDT_ID_UUID
Definition: DIContext.h:178
DIDumpType
Selects which debug sections get dumped.
Definition: DIContext.h:184
@ DIDT_All
Definition: DIContext.h:186
@ DIDT_UUID
Definition: DIContext.h:191
@ DIDT_Null
Definition: DIContext.h:185
Implement std::hash so that hash_code can be used in STL containers.
Definition: BitVector.h:858
Container for dump options that control which debug information will be dumped.
Definition: DIContext.h:196
std::function< void(Error)> WarningHandler
Definition: DIContext.h:236
std::function< void(Error)> RecoverableErrorHandler
Definition: DIContext.h:234
static DIDumpOptions getForSingleDIE()
Return default option set for printing a single DIE without children.
Definition: DIContext.h:217
std::string JsonErrSummaryFile
Definition: DIContext.h:212
std::function< llvm::StringRef(uint64_t DwarfRegNum, bool IsEH)> GetNameForDWARFReg
Definition: DIContext.h:214
DIDumpOptions noImplicitRecursion() const
Return the options with RecurseDepth set to 0 unless explicitly required.
Definition: DIContext.h:225
unsigned ChildRecurseDepth
Definition: DIContext.h:198
unsigned ParentRecurseDepth
Definition: DIContext.h:199
Container for description of a global variable.
Definition: DIContext.h:120
uint64_t Size
Definition: DIContext.h:123
uint64_t Start
Definition: DIContext.h:122
std::string Name
Definition: DIContext.h:121
std::string DeclFile
Definition: DIContext.h:124
uint64_t DeclLine
Definition: DIContext.h:125
Controls which fields of DILineInfo container should be filled with data.
Definition: DIContext.h:146
FileLineInfoKind FLIKind
Definition: DIContext.h:158
DILineInfoSpecifier(FileLineInfoKind FLIKind=FileLineInfoKind::RawValue, FunctionNameKind FNKind=FunctionNameKind::None, bool ApproximateLine=false)
Definition: DIContext.h:162
bool operator==(const DILineInfoSpecifier &RHS) const
Definition: DIContext.h:167
FunctionNameKind FNKind
Definition: DIContext.h:159
A format-neutral container for source line information.
Definition: DIContext.h:32
static constexpr const char *const BadString
Definition: DIContext.h:35
bool IsApproximateLine
Definition: DIContext.h:54
void dump(raw_ostream &OS)
Definition: DIContext.h:77
std::optional< uint64_t > StartAddress
Definition: DIContext.h:49
uint32_t Discriminator
Definition: DIContext.h:52
bool operator!=(const DILineInfo &RHS) const
Definition: DIContext.h:66
static constexpr const char *const Addr2LineBadString
Definition: DIContext.h:37
static constexpr const char *const ApproxString
Definition: DIContext.h:33
uint32_t Line
Definition: DIContext.h:46
bool operator==(const DILineInfo &RHS) const
Definition: DIContext.h:59
std::optional< StringRef > Source
Definition: DIContext.h:42
std::string FileName
Definition: DIContext.h:38
std::string FunctionName
Definition: DIContext.h:39
uint32_t Column
Definition: DIContext.h:47
uint32_t StartLine
Definition: DIContext.h:48
bool operator<(const DILineInfo &RHS) const
Definition: DIContext.h:68
std::string StartFileName
Definition: DIContext.h:40
std::optional< StringRef > LineSource
Definition: DIContext.h:45
std::optional< uint64_t > Size
Definition: DIContext.h:136
std::optional< uint64_t > TagOffset
Definition: DIContext.h:137
std::string DeclFile
Definition: DIContext.h:133
std::optional< int64_t > FrameOffset
Definition: DIContext.h:135
uint64_t DeclLine
Definition: DIContext.h:134
std::string Name
Definition: DIContext.h:132
std::string FunctionName
Definition: DIContext.h:131
LoadedObjectInfoHelper(const LoadedObjectInfoHelper &)=default
LoadedObjectInfoHelper(Ts &&...Args)
Definition: DIContext.h:327
std::unique_ptr< llvm::LoadedObjectInfo > clone() const override
Obtain a copy of this LoadedObjectInfo.
Definition: DIContext.h:329