FunctionInfo.h revision 360784
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" 13#include "llvm/DebugInfo/GSYM/InlineInfo.h" 14#include "llvm/DebugInfo/GSYM/LineTable.h" 15#include "llvm/DebugInfo/GSYM/LookupResult.h" 16#include "llvm/DebugInfo/GSYM/Range.h" 17#include "llvm/DebugInfo/GSYM/StringTable.h" 18#include <tuple> 19#include <vector> 20 21namespace llvm { 22class raw_ostream; 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. 88struct FunctionInfo { 89 AddressRange Range; 90 uint32_t Name; ///< String table offset in the string table. 91 llvm::Optional<LineTable> OptLineTable; 92 llvm::Optional<InlineInfo> Inline; 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. 133 static llvm::Expected<FunctionInfo> decode(DataExtractor &Data, 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. 143 llvm::Expected<uint64_t> encode(FileWriter &O) const; 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. 167 static llvm::Expected<LookupResult> lookup(DataExtractor &Data, 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 187inline 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} 191inline 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. 199inline 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 211raw_ostream &operator<<(raw_ostream &OS, const FunctionInfo &R); 212 213} // namespace gsym 214} // namespace llvm 215 216#endif // #ifndef LLVM_DEBUGINFO_GSYM_FUNCTIONINFO_H 217