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