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