LLVM 20.0.0git
DWARFListTable.h
Go to the documentation of this file.
1//===- DWARFListTable.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#ifndef LLVM_DEBUGINFO_DWARF_DWARFLISTTABLE_H
10#define LLVM_DEBUGINFO_DWARF_DWARFLISTTABLE_H
11
15#include "llvm/Support/Errc.h"
16#include "llvm/Support/Error.h"
18#include <cstdint>
19#include <map>
20#include <vector>
21
22namespace llvm {
23
24/// A base class for DWARF list entries, such as range or location list
25/// entries.
27 /// The offset at which the entry is located in the section.
29 /// The DWARF encoding (DW_RLE_* or DW_LLE_*).
30 uint8_t EntryKind;
31 /// The index of the section this entry belongs to.
33};
34
35/// A base class for lists of entries that are extracted from a particular
36/// section, such as range lists or location lists.
37template <typename ListEntryType> class DWARFListType {
38 using EntryType = ListEntryType;
39 using ListEntries = std::vector<EntryType>;
40
41protected:
42 ListEntries Entries;
43
44public:
45 const ListEntries &getEntries() const { return Entries; }
46 bool empty() const { return Entries.empty(); }
47 void clear() { Entries.clear(); }
49 uint64_t *OffsetPtr, StringRef SectionName,
50 StringRef ListStringName);
51};
52
53/// A class representing the header of a list table such as the range list
54/// table in the .debug_rnglists section.
56 struct Header {
57 /// The total length of the entries for this table, not including the length
58 /// field itself.
59 uint64_t Length = 0;
60 /// The DWARF version number.
61 uint16_t Version;
62 /// The size in bytes of an address on the target architecture. For
63 /// segmented addressing, this is the size of the offset portion of the
64 /// address.
65 uint8_t AddrSize;
66 /// The size in bytes of a segment selector on the target architecture.
67 /// If the target system uses a flat address space, this value is 0.
68 uint8_t SegSize;
69 /// The number of offsets that follow the header before the range lists.
70 uint32_t OffsetEntryCount;
71 };
72
73 Header HeaderData;
74 /// The table's format, either DWARF32 or DWARF64.
75 dwarf::DwarfFormat Format;
76 /// The offset at which the header (and hence the table) is located within
77 /// its section.
78 uint64_t HeaderOffset;
79 /// The name of the section the list is located in.
81 /// A characterization of the list for dumping purposes, e.g. "range" or
82 /// "location".
83 StringRef ListTypeString;
84
85public:
87 : SectionName(SectionName), ListTypeString(ListTypeString) {}
88
89 void clear() {
90 HeaderData = {};
91 }
92 uint64_t getHeaderOffset() const { return HeaderOffset; }
93 uint8_t getAddrSize() const { return HeaderData.AddrSize; }
94 uint64_t getLength() const { return HeaderData.Length; }
95 uint16_t getVersion() const { return HeaderData.Version; }
96 uint32_t getOffsetEntryCount() const { return HeaderData.OffsetEntryCount; }
98 StringRef getListTypeString() const { return ListTypeString; }
99 dwarf::DwarfFormat getFormat() const { return Format; }
100
101 /// Return the size of the table header including the length but not including
102 /// the offsets.
103 static uint8_t getHeaderSize(dwarf::DwarfFormat Format) {
104 switch (Format) {
106 return 12;
108 return 20;
109 }
110 llvm_unreachable("Invalid DWARF format (expected DWARF32 or DWARF64");
111 }
112
114 DIDumpOptions DumpOpts = {}) const;
115 std::optional<uint64_t> getOffsetEntry(DataExtractor Data,
116 uint32_t Index) const {
117 if (Index >= HeaderData.OffsetEntryCount)
118 return std::nullopt;
119
120 return getOffsetEntry(Data, getHeaderOffset() + getHeaderSize(Format), Format, Index);
121 }
122
123 static std::optional<uint64_t> getOffsetEntry(DataExtractor Data,
124 uint64_t OffsetTableOffset,
125 dwarf::DwarfFormat Format,
126 uint32_t Index) {
127 uint8_t OffsetByteSize = Format == dwarf::DWARF64 ? 8 : 4;
128 uint64_t Offset = OffsetTableOffset + OffsetByteSize * Index;
129 auto R = Data.getUnsigned(&Offset, OffsetByteSize);
130 return R;
131 }
132
133 /// Extract the table header and the array of offsets.
135
136 /// Returns the length of the table, including the length field, or 0 if the
137 /// length has not been determined (e.g. because the table has not yet been
138 /// parsed, or there was a problem in parsing).
139 uint64_t length() const;
140};
141
142/// A class representing a table of lists as specified in the DWARF v5
143/// standard for location lists and range lists. The table consists of a header
144/// followed by an array of offsets into a DWARF section, followed by zero or
145/// more list entries. The list entries are kept in a map where the keys are
146/// the lists' section offsets.
147template <typename DWARFListType> class DWARFListTableBase {
149 /// A mapping between file offsets and lists. It is used to find a particular
150 /// list based on an offset (obtained from DW_AT_ranges, for example).
151 std::map<uint64_t, DWARFListType> ListMap;
152 /// This string is displayed as a heading before the list is dumped
153 /// (e.g. "ranges:").
154 StringRef HeaderString;
155
156protected:
158 StringRef ListTypeString)
159 : Header(SectionName, ListTypeString), HeaderString(HeaderString) {}
160
161public:
162 void clear() {
163 Header.clear();
164 ListMap.clear();
165 }
166 /// Extract the table header and the array of offsets.
168 return Header.extract(Data, OffsetPtr);
169 }
170 /// Extract an entire table, including all list entries.
172 /// Look up a list based on a given offset. Extract it and enter it into the
173 /// list map if necessary.
175 uint64_t Offset) const;
176
177 uint64_t getHeaderOffset() const { return Header.getHeaderOffset(); }
178 uint8_t getAddrSize() const { return Header.getAddrSize(); }
179 uint32_t getOffsetEntryCount() const { return Header.getOffsetEntryCount(); }
180 dwarf::DwarfFormat getFormat() const { return Header.getFormat(); }
181
182 void
184 llvm::function_ref<std::optional<object::SectionedAddress>(uint32_t)>
185 LookupPooledAddress,
186 DIDumpOptions DumpOpts = {}) const;
187
188 /// Return the contents of the offset entry designated by a given index.
189 std::optional<uint64_t> getOffsetEntry(DataExtractor Data,
190 uint32_t Index) const {
191 return Header.getOffsetEntry(Data, Index);
192 }
193 /// Return the size of the table header including the length but not including
194 /// the offsets. This is dependent on the table format, which is unambiguously
195 /// derived from parsing the table.
196 uint8_t getHeaderSize() const {
198 }
199
200 uint64_t length() { return Header.length(); }
201};
202
203template <typename DWARFListType>
205 uint64_t *OffsetPtr) {
206 clear();
207 if (Error E = extractHeaderAndOffsets(Data, OffsetPtr))
208 return E;
209
210 Data.setAddressSize(Header.getAddrSize());
211 Data = DWARFDataExtractor(Data, getHeaderOffset() + Header.length());
212 while (Data.isValidOffset(*OffsetPtr)) {
213 DWARFListType CurrentList;
214 uint64_t Off = *OffsetPtr;
215 if (Error E = CurrentList.extract(Data, getHeaderOffset(), OffsetPtr,
216 Header.getSectionName(),
217 Header.getListTypeString()))
218 return E;
219 ListMap[Off] = CurrentList;
220 }
221
222 assert(*OffsetPtr == Data.size() &&
223 "mismatch between expected length of table and length "
224 "of extracted data");
225 return Error::success();
226}
227
228template <typename ListEntryType>
230 uint64_t HeaderOffset,
231 uint64_t *OffsetPtr,
233 StringRef ListTypeString) {
234 if (*OffsetPtr < HeaderOffset || *OffsetPtr >= Data.size())
236 "invalid %s list offset 0x%" PRIx64,
237 ListTypeString.data(), *OffsetPtr);
238 Entries.clear();
239 while (Data.isValidOffset(*OffsetPtr)) {
240 ListEntryType Entry;
241 if (Error E = Entry.extract(Data, OffsetPtr))
242 return E;
243 Entries.push_back(Entry);
244 if (Entry.isSentinel())
245 return Error::success();
246 }
248 "no end of list marker detected at end of %s table "
249 "starting at offset 0x%" PRIx64,
250 SectionName.data(), HeaderOffset);
251}
252
253template <typename DWARFListType>
256 llvm::function_ref<std::optional<object::SectionedAddress>(uint32_t)>
257 LookupPooledAddress,
258 DIDumpOptions DumpOpts) const {
259 Header.dump(Data, OS, DumpOpts);
260 OS << HeaderString << "\n";
261
262 // Determine the length of the longest encoding string we have in the table,
263 // so we can align the output properly. We only need this in verbose mode.
264 size_t MaxEncodingStringLength = 0;
265 if (DumpOpts.Verbose) {
266 for (const auto &List : ListMap)
267 for (const auto &Entry : List.second.getEntries())
268 MaxEncodingStringLength =
269 std::max(MaxEncodingStringLength,
270 dwarf::RangeListEncodingString(Entry.EntryKind).size());
271 }
272
273 uint64_t CurrentBase = 0;
274 for (const auto &List : ListMap)
275 for (const auto &Entry : List.second.getEntries())
276 Entry.dump(OS, getAddrSize(), MaxEncodingStringLength, CurrentBase,
277 DumpOpts, LookupPooledAddress);
278}
279
280template <typename DWARFListType>
283 uint64_t Offset) const {
284 // Extract the list from the section and enter it into the list map.
286 if (Header.length())
287 Data = DWARFDataExtractor(Data, getHeaderOffset() + Header.length());
288 if (Error E =
289 List.extract(Data, Header.length() ? getHeaderOffset() : 0, &Offset,
290 Header.getSectionName(), Header.getListTypeString()))
291 return std::move(E);
292 return List;
293}
294
295} // end namespace llvm
296
297#endif // LLVM_DEBUGINFO_DWARF_DWARFLISTTABLE_H
static GCRegistry::Add< CoreCLRGC > E("coreclr", "CoreCLR-compatible GC")
static void clear(coro::Shape &Shape)
Definition: Coroutines.cpp:148
This file contains constants used for implementing Dwarf debug support.
loop extract
assert(ImpDefSCC.getReg()==AMDGPU::SCC &&ImpDefSCC.isDef())
raw_pwrite_stream & OS
A DataExtractor (typically for an in-memory copy of an object-file section) plus a relocation map for...
A class representing a table of lists as specified in the DWARF v5 standard for location lists and ra...
uint8_t getHeaderSize() const
Return the size of the table header including the length but not including the offsets.
std::optional< uint64_t > getOffsetEntry(DataExtractor Data, uint32_t Index) const
Return the contents of the offset entry designated by a given index.
uint32_t getOffsetEntryCount() const
uint64_t getHeaderOffset() const
uint8_t getAddrSize() const
Expected< DWARFListType > findList(DWARFDataExtractor Data, uint64_t Offset) const
Look up a list based on a given offset.
dwarf::DwarfFormat getFormat() const
Error extractHeaderAndOffsets(DWARFDataExtractor Data, uint64_t *OffsetPtr)
Extract the table header and the array of offsets.
Error extract(DWARFDataExtractor Data, uint64_t *OffsetPtr)
Extract an entire table, including all list entries.
void dump(DWARFDataExtractor Data, raw_ostream &OS, llvm::function_ref< std::optional< object::SectionedAddress >(uint32_t)> LookupPooledAddress, DIDumpOptions DumpOpts={}) const
DWARFListTableBase(StringRef SectionName, StringRef HeaderString, StringRef ListTypeString)
A class representing the header of a list table such as the range list table in the ....
static std::optional< uint64_t > getOffsetEntry(DataExtractor Data, uint64_t OffsetTableOffset, dwarf::DwarfFormat Format, uint32_t Index)
uint64_t getLength() const
DWARFListTableHeader(StringRef SectionName, StringRef ListTypeString)
static uint8_t getHeaderSize(dwarf::DwarfFormat Format)
Return the size of the table header including the length but not including the offsets.
std::optional< uint64_t > getOffsetEntry(DataExtractor Data, uint32_t Index) const
void dump(DataExtractor Data, raw_ostream &OS, DIDumpOptions DumpOpts={}) const
dwarf::DwarfFormat getFormat() const
uint32_t getOffsetEntryCount() const
StringRef getSectionName() const
uint64_t getHeaderOffset() const
uint64_t length() const
Returns the length of the table, including the length field, or 0 if the length has not been determin...
StringRef getListTypeString() const
uint8_t getAddrSize() const
uint16_t getVersion() const
A base class for lists of entries that are extracted from a particular section, such as range lists o...
const ListEntries & getEntries() const
Error extract(DWARFDataExtractor Data, uint64_t HeaderOffset, uint64_t *OffsetPtr, StringRef SectionName, StringRef ListStringName)
bool empty() const
Lightweight error class with error context and mandatory checking.
Definition: Error.h:160
static ErrorSuccess success()
Create a success value.
Definition: Error.h:337
Tagged union holding either a T or a Error.
Definition: Error.h:481
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:50
constexpr size_t size() const
size - Get the string size.
Definition: StringRef.h:137
constexpr const char * data() const
data - Get a pointer to the start of the string (which may not be null terminated).
Definition: StringRef.h:131
An efficient, type-erasing, non-owning reference to a callable.
This class implements an extremely fast bulk output stream that can only output to a stream.
Definition: raw_ostream.h:52
StringRef RangeListEncodingString(unsigned Encoding)
Definition: Dwarf.cpp:591
#define llvm_unreachable(msg)
Marks that the current location is not supposed to be reachable.
DwarfFormat
Constants that define the DWARF format as 32 or 64 bit.
Definition: Dwarf.h:91
@ DWARF64
Definition: Dwarf.h:91
@ DWARF32
Definition: Dwarf.h:91
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
@ Offset
Definition: DWP.cpp:480
@ Length
Definition: DWP.cpp:480
Error createStringError(std::error_code EC, char const *Fmt, const Ts &... Vals)
Create formatted StringError object.
Definition: Error.h:1286
@ illegal_byte_sequence
Container for dump options that control which debug information will be dumped.
Definition: DIContext.h:196
A base class for DWARF list entries, such as range or location list entries.
uint64_t SectionIndex
The index of the section this entry belongs to.
uint8_t EntryKind
The DWARF encoding (DW_RLE_* or DW_LLE_*).
uint64_t Offset
The offset at which the entry is located in the section.