1 | //===- FunctionInfo.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_GSYM_FUNCTIONINFO_H |
10 | #define LLVM_DEBUGINFO_GSYM_FUNCTIONINFO_H |
11 | |
12 | #include "llvm/ADT/SmallString.h" |
13 | #include "llvm/DebugInfo/GSYM/ExtractRanges.h" |
14 | #include "llvm/DebugInfo/GSYM/InlineInfo.h" |
15 | #include "llvm/DebugInfo/GSYM/LineTable.h" |
16 | #include "llvm/DebugInfo/GSYM/LookupResult.h" |
17 | #include "llvm/DebugInfo/GSYM/StringTable.h" |
18 | #include <cstdint> |
19 | |
20 | namespace llvm { |
21 | class raw_ostream; |
22 | |
23 | namespace gsym { |
24 | |
25 | class GsymReader; |
26 | /// Function information in GSYM files encodes information for one contiguous |
27 | /// address range. If a function has discontiguous address ranges, they will |
28 | /// need to be encoded using multiple FunctionInfo objects. |
29 | /// |
30 | /// ENCODING |
31 | /// |
32 | /// The function information gets the function start address as an argument |
33 | /// to the FunctionInfo::decode(...) function. This information is calculated |
34 | /// from the GSYM header and an address offset from the GSYM address offsets |
35 | /// table. The encoded FunctionInfo information must be aligned to a 4 byte |
36 | /// boundary. |
37 | /// |
38 | /// The encoded data for a FunctionInfo starts with fixed data that all |
39 | /// function info objects have: |
40 | /// |
41 | /// ENCODING NAME DESCRIPTION |
42 | /// ========= =========== ==================================================== |
43 | /// uint32_t Size The size in bytes of this function. |
44 | /// uint32_t Name The string table offset of the function name. |
45 | /// |
46 | /// The optional data in a FunctionInfo object follows this fixed information |
47 | /// and consists of a stream of tuples that consist of: |
48 | /// |
49 | /// ENCODING NAME DESCRIPTION |
50 | /// ========= =========== ==================================================== |
51 | /// uint32_t InfoType An "InfoType" enumeration that describes the type |
52 | /// of optional data that is encoded. |
53 | /// uint32_t InfoLength The size in bytes of the encoded data that |
54 | /// immediately follows this length if this value is |
55 | /// greater than zero. |
56 | /// uint8_t[] InfoData Encoded bytes that represent the data for the |
57 | /// "InfoType". These bytes are only present if |
58 | /// "InfoLength" is greater than zero. |
59 | /// |
60 | /// The "InfoType" is an enumeration: |
61 | /// |
62 | /// enum InfoType { |
63 | /// EndOfList = 0u, |
64 | /// LineTableInfo = 1u, |
65 | /// InlineInfo = 2u |
66 | /// }; |
67 | /// |
68 | /// This stream of tuples is terminated by a "InfoType" whose value is |
69 | /// InfoType::EndOfList and a zero for "InfoLength". This signifies the end of |
70 | /// the optional information list. This format allows us to add new optional |
71 | /// information data to a FunctionInfo object over time and allows older |
72 | /// clients to still parse the format and skip over any data that they don't |
73 | /// understand or want to parse. |
74 | /// |
75 | /// So the function information encoding essientially looks like: |
76 | /// |
77 | /// struct { |
78 | /// uint32_t Size; |
79 | /// uint32_t Name; |
80 | /// struct { |
81 | /// uint32_t InfoType; |
82 | /// uint32_t InfoLength; |
83 | /// uint8_t InfoData[InfoLength]; |
84 | /// }[N]; |
85 | /// } |
86 | /// |
87 | /// Where "N" is the number of tuples. |
88 | struct FunctionInfo { |
89 | AddressRange Range; |
90 | uint32_t Name; ///< String table offset in the string table. |
91 | std::optional<LineTable> OptLineTable; |
92 | std::optional<InlineInfo> Inline; |
93 | /// If we encode a FunctionInfo during segmenting so we know its size, we can |
94 | /// cache that encoding here so we don't need to re-encode it when saving the |
95 | /// GSYM file. |
96 | SmallString<32> EncodingCache; |
97 | |
98 | FunctionInfo(uint64_t Addr = 0, uint64_t Size = 0, uint32_t N = 0) |
99 | : Range(Addr, Addr + Size), Name(N) {} |
100 | |
101 | /// Query if a FunctionInfo has rich debug info. |
102 | /// |
103 | /// \returns A bool that indicates if this object has something else than |
104 | /// range and name. When converting information from a symbol table and from |
105 | /// debug info, we might end up with multiple FunctionInfo objects for the |
106 | /// same range and we need to be able to tell which one is the better object |
107 | /// to use. |
108 | bool hasRichInfo() const { return OptLineTable || Inline; } |
109 | |
110 | /// Query if a FunctionInfo object is valid. |
111 | /// |
112 | /// Address and size can be zero and there can be no line entries for a |
113 | /// symbol so the only indication this entry is valid is if the name is |
114 | /// not zero. This can happen when extracting information from symbol |
115 | /// tables that do not encode symbol sizes. In that case only the |
116 | /// address and name will be filled in. |
117 | /// |
118 | /// \returns A boolean indicating if this FunctionInfo is valid. |
119 | bool isValid() const { |
120 | return Name != 0; |
121 | } |
122 | |
123 | /// Decode an object from a binary data stream. |
124 | /// |
125 | /// \param Data The binary stream to read the data from. This object must |
126 | /// have the data for the object starting at offset zero. The data |
127 | /// can contain more data than needed. |
128 | /// |
129 | /// \param BaseAddr The FunctionInfo's start address and will be used as the |
130 | /// base address when decoding any contained information like the line table |
131 | /// and the inline info. |
132 | /// |
133 | /// \returns An FunctionInfo or an error describing the issue that was |
134 | /// encountered during decoding. |
135 | static llvm::Expected<FunctionInfo> (DataExtractor &Data, |
136 | uint64_t BaseAddr); |
137 | |
138 | /// Encode this object into FileWriter stream. |
139 | /// |
140 | /// \param O The binary stream to write the data to at the current file |
141 | /// position. |
142 | /// |
143 | /// \returns An error object that indicates failure or the offset of the |
144 | /// function info that was successfully written into the stream. |
145 | llvm::Expected<uint64_t> encode(FileWriter &O) const; |
146 | |
147 | /// Encode this function info into the internal byte cache and return the size |
148 | /// in bytes. |
149 | /// |
150 | /// When segmenting GSYM files we need to know how big each FunctionInfo will |
151 | /// encode into so we can generate segments of the right size. We don't want |
152 | /// to have to encode a FunctionInfo twice, so we can cache the encoded bytes |
153 | /// and re-use then when calling FunctionInfo::encode(...). |
154 | /// |
155 | /// \returns The size in bytes of the FunctionInfo if it were to be encoded |
156 | /// into a byte stream. |
157 | uint64_t cacheEncoding(); |
158 | |
159 | /// Lookup an address within a FunctionInfo object's data stream. |
160 | /// |
161 | /// Instead of decoding an entire FunctionInfo object when doing lookups, |
162 | /// we can decode only the information we need from the FunctionInfo's data |
163 | /// for the specific address. The lookup result information is returned as |
164 | /// a LookupResult. |
165 | /// |
166 | /// \param Data The binary stream to read the data from. This object must |
167 | /// have the data for the object starting at offset zero. The data |
168 | /// can contain more data than needed. |
169 | /// |
170 | /// \param GR The GSYM reader that contains the string and file table that |
171 | /// will be used to fill in information in the returned result. |
172 | /// |
173 | /// \param FuncAddr The function start address decoded from the GsymReader. |
174 | /// |
175 | /// \param Addr The address to lookup. |
176 | /// |
177 | /// \returns An LookupResult or an error describing the issue that was |
178 | /// encountered during decoding. An error should only be returned if the |
179 | /// address is not contained in the FunctionInfo or if the data is corrupted. |
180 | static llvm::Expected<LookupResult> (DataExtractor &Data, |
181 | const GsymReader &GR, |
182 | uint64_t FuncAddr, |
183 | uint64_t Addr); |
184 | |
185 | uint64_t startAddress() const { return Range.start(); } |
186 | uint64_t endAddress() const { return Range.end(); } |
187 | uint64_t size() const { return Range.size(); } |
188 | |
189 | void clear() { |
190 | Range = {0, 0}; |
191 | Name = 0; |
192 | OptLineTable = std::nullopt; |
193 | Inline = std::nullopt; |
194 | } |
195 | }; |
196 | |
197 | inline bool operator==(const FunctionInfo &LHS, const FunctionInfo &RHS) { |
198 | return LHS.Range == RHS.Range && LHS.Name == RHS.Name && |
199 | LHS.OptLineTable == RHS.OptLineTable && LHS.Inline == RHS.Inline; |
200 | } |
201 | inline bool operator!=(const FunctionInfo &LHS, const FunctionInfo &RHS) { |
202 | return !(LHS == RHS); |
203 | } |
204 | /// This sorting will order things consistently by address range first, but |
205 | /// then followed by increasing levels of debug info like inline information |
206 | /// and line tables. We might end up with a FunctionInfo from debug info that |
207 | /// will have the same range as one from the symbol table, but we want to |
208 | /// quickly be able to sort and use the best version when creating the final |
209 | /// GSYM file. This function compares the inline information as we have seen |
210 | /// cases where LTO can generate a wide array of differing inline information, |
211 | /// mostly due to messing up the address ranges for inlined functions, so the |
212 | /// inline information with the most entries will appeear last. If the inline |
213 | /// information match, either by both function infos not having any or both |
214 | /// being exactly the same, we will then compare line tables. Comparing line |
215 | /// tables allows the entry with the most line entries to appear last. This |
216 | /// ensures we are able to save the FunctionInfo with the most debug info into |
217 | /// the GSYM file. |
218 | inline bool operator<(const FunctionInfo &LHS, const FunctionInfo &RHS) { |
219 | // First sort by address range |
220 | if (LHS.Range != RHS.Range) |
221 | return LHS.Range < RHS.Range; |
222 | if (LHS.Inline == RHS.Inline) |
223 | return LHS.OptLineTable < RHS.OptLineTable; |
224 | return LHS.Inline < RHS.Inline; |
225 | } |
226 | |
227 | raw_ostream &operator<<(raw_ostream &OS, const FunctionInfo &R); |
228 | |
229 | } // namespace gsym |
230 | } // namespace llvm |
231 | |
232 | #endif // LLVM_DEBUGINFO_GSYM_FUNCTIONINFO_H |
233 | |