1//===- DWARFUnitIndex.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_DWARFUNITINDEX_H
10#define LLVM_DEBUGINFO_DWARF_DWARFUNITINDEX_H
11
12#include "llvm/ADT/ArrayRef.h"
13#include "llvm/ADT/StringRef.h"
14#include "llvm/Support/DataExtractor.h"
15#include <cstdint>
16#include <memory>
17
18namespace llvm {
19
20class raw_ostream;
21
22/// The enum of section identifiers to be used in internal interfaces.
23///
24/// Pre-standard implementation of package files defined a number of section
25/// identifiers with values that clash definitions in the DWARFv5 standard.
26/// See https://gcc.gnu.org/wiki/DebugFissionDWP and Section 7.3.5.3 in DWARFv5.
27///
28/// The following identifiers are the same in the proposal and in DWARFv5:
29/// - DW_SECT_INFO = 1 (.debug_info.dwo)
30/// - DW_SECT_ABBREV = 3 (.debug_abbrev.dwo)
31/// - DW_SECT_LINE = 4 (.debug_line.dwo)
32/// - DW_SECT_STR_OFFSETS = 6 (.debug_str_offsets.dwo)
33///
34/// The following identifiers are defined only in DWARFv5:
35/// - DW_SECT_LOCLISTS = 5 (.debug_loclists.dwo)
36/// - DW_SECT_RNGLISTS = 8 (.debug_rnglists.dwo)
37///
38/// The following identifiers are defined only in the GNU proposal:
39/// - DW_SECT_TYPES = 2 (.debug_types.dwo)
40/// - DW_SECT_LOC = 5 (.debug_loc.dwo)
41/// - DW_SECT_MACINFO = 7 (.debug_macinfo.dwo)
42///
43/// DW_SECT_MACRO for the .debug_macro.dwo section is defined in both standards,
44/// but with different values, 8 in GNU and 7 in DWARFv5.
45///
46/// This enum defines constants to represent the identifiers of both sets.
47/// For DWARFv5 ones, the values are the same as defined in the standard.
48/// For pre-standard ones that correspond to sections being deprecated in
49/// DWARFv5, the values are chosen arbitrary and a tag "_EXT_" is added to
50/// the names.
51///
52/// The enum is for internal use only. The user should not expect the values
53/// to correspond to any input/output constants. Special conversion functions,
54/// serializeSectionKind() and deserializeSectionKind(), should be used for
55/// the translation.
56enum DWARFSectionKind {
57 /// Denotes a value read from an index section that does not correspond
58 /// to any of the supported standards.
59 DW_SECT_EXT_unknown = 0,
60#define HANDLE_DW_SECT(ID, NAME) DW_SECT_##NAME = ID,
61#include "llvm/BinaryFormat/Dwarf.def"
62 DW_SECT_EXT_TYPES = 2,
63 DW_SECT_EXT_LOC = 9,
64 DW_SECT_EXT_MACINFO = 10,
65};
66
67/// Convert the internal value for a section kind to an on-disk value.
68///
69/// The conversion depends on the version of the index section.
70/// IndexVersion is expected to be either 2 for pre-standard GNU proposal
71/// or 5 for DWARFv5 package file.
72uint32_t serializeSectionKind(DWARFSectionKind Kind, unsigned IndexVersion);
73
74/// Convert a value read from an index section to the internal representation.
75///
76/// The conversion depends on the index section version, which is expected
77/// to be either 2 for pre-standard GNU proposal or 5 for DWARFv5 package file.
78DWARFSectionKind deserializeSectionKind(uint32_t Value, unsigned IndexVersion);
79
80class DWARFUnitIndex {
81 struct Header {
82 uint32_t Version;
83 uint32_t NumColumns;
84 uint32_t NumUnits;
85 uint32_t NumBuckets = 0;
86
87 bool parse(DataExtractor IndexData, uint64_t *OffsetPtr);
88 void dump(raw_ostream &OS) const;
89 };
90
91public:
92 class Entry {
93 public:
94 struct SectionContribution {
95 uint32_t Offset;
96 uint32_t Length;
97 };
98
99 private:
100 const DWARFUnitIndex *Index;
101 uint64_t Signature;
102 std::unique_ptr<SectionContribution[]> Contributions;
103 friend class DWARFUnitIndex;
104
105 public:
106 const SectionContribution *getContribution(DWARFSectionKind Sec) const;
107 const SectionContribution *getContribution() const;
108
109 const SectionContribution *getContributions() const {
110 return Contributions.get();
111 }
112
113 uint64_t getSignature() const { return Signature; }
114 };
115
116private:
117 struct Header Header;
118
119 DWARFSectionKind InfoColumnKind;
120 int InfoColumn = -1;
121 std::unique_ptr<DWARFSectionKind[]> ColumnKinds;
122 // This is a parallel array of section identifiers as they read from the input
123 // file. The mapping from raw values to DWARFSectionKind is not revertable in
124 // case of unknown identifiers, so we keep them here.
125 std::unique_ptr<uint32_t[]> RawSectionIds;
126 std::unique_ptr<Entry[]> Rows;
127 mutable std::vector<Entry *> OffsetLookup;
128
129 static StringRef getColumnHeader(DWARFSectionKind DS);
130
131 bool parseImpl(DataExtractor IndexData);
132
133public:
134 DWARFUnitIndex(DWARFSectionKind InfoColumnKind)
135 : InfoColumnKind(InfoColumnKind) {}
136
137 explicit operator bool() const { return Header.NumBuckets; }
138
139 bool parse(DataExtractor IndexData);
140 void dump(raw_ostream &OS) const;
141
142 uint32_t getVersion() const { return Header.Version; }
143
144 const Entry *getFromOffset(uint32_t Offset) const;
145 const Entry *getFromHash(uint64_t Offset) const;
146
147 ArrayRef<DWARFSectionKind> getColumnKinds() const {
148 return makeArrayRef(ColumnKinds.get(), Header.NumColumns);
149 }
150
151 ArrayRef<Entry> getRows() const {
152 return makeArrayRef(Rows.get(), Header.NumBuckets);
153 }
154};
155
156} // end namespace llvm
157
158#endif // LLVM_DEBUGINFO_DWARF_DWARFUNITINDEX_H
159