LLVM  12.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 
12 #include "llvm/ADT/Optional.h"
18 #include <tuple>
19 #include <vector>
20 
21 namespace llvm {
22 class raw_ostream;
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 {
90  uint32_t Name; ///< String table offset in the string table.
93 
94  FunctionInfo(uint64_t Addr = 0, uint64_t Size = 0, uint32_t N = 0)
95  : Range(Addr, Addr + Size), Name(N) {}
96 
97  /// Query if a FunctionInfo has rich debug info.
98  ///
99  /// \returns A bool that indicates if this object has something else than
100  /// range and name. When converting information from a symbol table and from
101  /// debug info, we might end up with multiple FunctionInfo objects for the
102  /// same range and we need to be able to tell which one is the better object
103  /// to use.
104  bool hasRichInfo() const {
105  return OptLineTable.hasValue() || Inline.hasValue();
106  }
107 
108  /// Query if a FunctionInfo object is valid.
109  ///
110  /// Address and size can be zero and there can be no line entries for a
111  /// symbol so the only indication this entry is valid is if the name is
112  /// not zero. This can happen when extracting information from symbol
113  /// tables that do not encode symbol sizes. In that case only the
114  /// address and name will be filled in.
115  ///
116  /// \returns A boolean indicating if this FunctionInfo is valid.
117  bool isValid() const {
118  return Name != 0;
119  }
120 
121  /// Decode an object from a binary data stream.
122  ///
123  /// \param Data The binary stream to read the data from. This object must
124  /// have the data for the object starting at offset zero. The data
125  /// can contain more data than needed.
126  ///
127  /// \param BaseAddr The FunctionInfo's start address and will be used as the
128  /// base address when decoding any contained information like the line table
129  /// and the inline info.
130  ///
131  /// \returns An FunctionInfo or an error describing the issue that was
132  /// encountered during decoding.
134  uint64_t BaseAddr);
135 
136  /// Encode this object into FileWriter stream.
137  ///
138  /// \param O The binary stream to write the data to at the current file
139  /// position.
140  ///
141  /// \returns An error object that indicates failure or the offset of the
142  /// function info that was successfully written into the stream.
144 
145 
146  /// Lookup an address within a FunctionInfo object's data stream.
147  ///
148  /// Instead of decoding an entire FunctionInfo object when doing lookups,
149  /// we can decode only the information we need from the FunctionInfo's data
150  /// for the specific address. The lookup result information is returned as
151  /// a LookupResult.
152  ///
153  /// \param Data The binary stream to read the data from. This object must
154  /// have the data for the object starting at offset zero. The data
155  /// can contain more data than needed.
156  ///
157  /// \param GR The GSYM reader that contains the string and file table that
158  /// will be used to fill in information in the returned result.
159  ///
160  /// \param FuncAddr The function start address decoded from the GsymReader.
161  ///
162  /// \param Addr The address to lookup.
163  ///
164  /// \returns An LookupResult or an error describing the issue that was
165  /// encountered during decoding. An error should only be returned if the
166  /// address is not contained in the FunctionInfo or if the data is corrupted.
168  const GsymReader &GR,
169  uint64_t FuncAddr,
170  uint64_t Addr);
171 
172  uint64_t startAddress() const { return Range.Start; }
173  uint64_t endAddress() const { return Range.End; }
174  uint64_t size() const { return Range.size(); }
175  void setStartAddress(uint64_t Addr) { Range.Start = Addr; }
176  void setEndAddress(uint64_t Addr) { Range.End = Addr; }
177  void setSize(uint64_t Size) { Range.End = Range.Start + Size; }
178 
179  void clear() {
180  Range = {0, 0};
181  Name = 0;
182  OptLineTable = None;
183  Inline = None;
184  }
185 };
186 
187 inline bool operator==(const FunctionInfo &LHS, const FunctionInfo &RHS) {
188  return LHS.Range == RHS.Range && LHS.Name == RHS.Name &&
189  LHS.OptLineTable == RHS.OptLineTable && LHS.Inline == RHS.Inline;
190 }
191 inline bool operator!=(const FunctionInfo &LHS, const FunctionInfo &RHS) {
192  return !(LHS == RHS);
193 }
194 /// This sorting will order things consistently by address range first, but then
195 /// followed by inlining being valid and line tables. We might end up with a
196 /// FunctionInfo from debug info that will have the same range as one from the
197 /// symbol table, but we want to quickly be able to sort and use the best version
198 /// when creating the final GSYM file.
199 inline bool operator<(const FunctionInfo &LHS, const FunctionInfo &RHS) {
200  // First sort by address range
201  if (LHS.Range != RHS.Range)
202  return LHS.Range < RHS.Range;
203 
204  // Then sort by inline
205  if (LHS.Inline.hasValue() != RHS.Inline.hasValue())
206  return RHS.Inline.hasValue();
207 
208  return LHS.OptLineTable < RHS.OptLineTable;
209 }
210 
212 
213 } // namespace gsym
214 } // namespace llvm
215 
216 #endif // #ifndef LLVM_DEBUGINFO_GSYM_FUNCTIONINFO_H
GsymReader is used to read GSYM data from a file or buffer.
Definition: GsymReader.h:47
const NoneType None
Definition: None.h:23
llvm::Optional< LineTable > OptLineTable
Definition: FunctionInfo.h:91
void setStartAddress(uint64_t Addr)
Definition: FunctionInfo.h:175
This class represents lattice values for constants.
Definition: AllocatorList.h:23
bool operator!=(const FunctionInfo &LHS, const FunctionInfo &RHS)
Definition: FunctionInfo.h:191
llvm::Optional< InlineInfo > Inline
Definition: FunctionInfo.h:92
Function information in GSYM files encodes information for one contiguous address range...
Definition: FunctionInfo.h:88
uint64_t size() const
Definition: FunctionInfo.h:174
uint64_t startAddress() const
Definition: FunctionInfo.h:172
static llvm::Expected< LookupResult > lookup(DataExtractor &Data, const GsymReader &GR, uint64_t FuncAddr, uint64_t Addr)
Lookup an address within a FunctionInfo object&#39;s data stream.
bool operator<(const FunctionInfo &LHS, const FunctionInfo &RHS)
This sorting will order things consistently by address range first, but then followed by inlining bei...
Definition: FunctionInfo.h:199
Tagged union holding either a T or a Error.
Definition: APFloat.h:42
bool isValid() const
Query if a FunctionInfo object is valid.
Definition: FunctionInfo.h:117
A simplified binary data writer class that doesn&#39;t require targets, target definitions, architectures, or require any other optional compile time libraries to be enabled via the build process.
Definition: FileWriter.h:29
A class that represents an address range.
Definition: Range.h:33
bool operator==(const FunctionInfo &LHS, const FunctionInfo &RHS)
Definition: FunctionInfo.h:187
bool hasRichInfo() const
Query if a FunctionInfo has rich debug info.
Definition: FunctionInfo.h:104
FunctionInfo(uint64_t Addr=0, uint64_t Size=0, uint32_t N=0)
Definition: FunctionInfo.h:94
bool hasValue() const
Definition: Optional.h:259
static llvm::Expected< FunctionInfo > decode(DataExtractor &Data, uint64_t BaseAddr)
Decode an object from a binary data stream.
uint32_t Name
String table offset in the string table.
Definition: FunctionInfo.h:90
llvm::Expected< uint64_t > encode(FileWriter &O) const
Encode this object into FileWriter stream.
#define N
uint32_t Size
Definition: Profile.cpp:46
uint64_t endAddress() const
Definition: FunctionInfo.h:173
void setEndAddress(uint64_t Addr)
Definition: FunctionInfo.h:176
uint64_t size() const
Definition: Range.h:38
This class implements an extremely fast bulk output stream that can only output to a stream...
Definition: raw_ostream.h:46
raw_ostream & operator<<(raw_ostream &OS, const FunctionInfo &R)
void setSize(uint64_t Size)
Definition: FunctionInfo.h:177