LLVM 19.0.0git
FunctionInfo.h
Go to the documentation of this file.
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
18#include <cstdint>
19
20namespace llvm {
21class raw_ostream;
22
23namespace gsym {
24
25class 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.
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.
97
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.
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.
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.
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.
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
197inline 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}
201inline 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.
218inline 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
227raw_ostream &operator<<(raw_ostream &OS, const FunctionInfo &R);
228
229} // namespace gsym
230} // namespace llvm
231
232#endif // LLVM_DEBUGINFO_GSYM_FUNCTIONINFO_H
uint64_t Addr
uint64_t Size
raw_pwrite_stream & OS
This file defines the SmallString class.
Value * RHS
Value * LHS
A class that represents an address range.
Definition: AddressRanges.h:22
uint64_t start() const
Definition: AddressRanges.h:28
uint64_t end() const
Definition: AddressRanges.h:29
uint64_t size() const
Definition: AddressRanges.h:30
Tagged union holding either a T or a Error.
Definition: Error.h:474
SmallString - A SmallString is just a SmallVector with methods and accessors that make it work better...
Definition: SmallString.h:26
A simplified binary data writer class that doesn't require targets, target definitions,...
Definition: FileWriter.h:29
GsymReader is used to read GSYM data from a file or buffer.
Definition: GsymReader.h:44
This class implements an extremely fast bulk output stream that can only output to a stream.
Definition: raw_ostream.h:52
raw_ostream & operator<<(raw_ostream &OS, const FunctionInfo &R)
bool operator<(const FunctionInfo &LHS, const FunctionInfo &RHS)
This sorting will order things consistently by address range first, but then followed by increasing l...
Definition: FunctionInfo.h:218
bool operator==(const FunctionInfo &LHS, const FunctionInfo &RHS)
Definition: FunctionInfo.h:197
bool operator!=(const FunctionInfo &LHS, const FunctionInfo &RHS)
Definition: FunctionInfo.h:201
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
#define N
Function information in GSYM files encodes information for one contiguous address range.
Definition: FunctionInfo.h:88
std::optional< InlineInfo > Inline
Definition: FunctionInfo.h:92
uint64_t startAddress() const
Definition: FunctionInfo.h:185
uint64_t endAddress() const
Definition: FunctionInfo.h:186
bool isValid() const
Query if a FunctionInfo object is valid.
Definition: FunctionInfo.h:119
bool hasRichInfo() const
Query if a FunctionInfo has rich debug info.
Definition: FunctionInfo.h:108
uint64_t size() const
Definition: FunctionInfo.h:187
static llvm::Expected< LookupResult > lookup(DataExtractor &Data, const GsymReader &GR, uint64_t FuncAddr, uint64_t Addr)
Lookup an address within a FunctionInfo object's data stream.
uint64_t cacheEncoding()
Encode this function info into the internal byte cache and return the size in bytes.
uint32_t Name
String table offset in the string table.
Definition: FunctionInfo.h:90
SmallString< 32 > EncodingCache
If we encode a FunctionInfo during segmenting so we know its size, we can cache that encoding here so...
Definition: FunctionInfo.h:96
std::optional< LineTable > OptLineTable
Definition: FunctionInfo.h:91
llvm::Expected< uint64_t > encode(FileWriter &O) const
Encode this object into FileWriter stream.
FunctionInfo(uint64_t Addr=0, uint64_t Size=0, uint32_t N=0)
Definition: FunctionInfo.h:98
static llvm::Expected< FunctionInfo > decode(DataExtractor &Data, uint64_t BaseAddr)
Decode an object from a binary data stream.