include/llvm/DebugInfo/GSYM/FunctionInfo.h

   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/Range.h"
  16 #include "llvm/DebugInfo/GSYM/StringTable.h"
  17 #include <tuple>
  18 #include <vector>
  19
  20 namespace llvm {
  21 class raw_ostream;
  22 namespace gsym {
  23
  24 /// Function information in GSYM files encodes information for one contiguous
  25 /// address range. If a function has discontiguous address ranges, they will
  26 /// need to be encoded using multiple FunctionInfo objects.
  27 ///
  28 /// ENCODING
  29 ///
  30 /// The function information gets the function start address as an argument
  31 /// to the FunctionInfo::decode(...) function. This information is calculated
  32 /// from the GSYM header and an address offset from the GSYM address offsets
  33 /// table. The encoded FunctionInfo information must be alinged to a 4 byte
  34 /// boundary.
  35 ///
  36 /// The encoded data for a FunctionInfo starts with fixed data that all
  37 /// function info objects have:
  38 ///
  39 /// ENCODING  NAME        DESCRIPTION
  40 /// ========= =========== ====================================================
  41 /// uint32_t  Size        The size in bytes of this function.
  42 /// uint32_t  Name        The string table offset of the function name.
  43 ///
  44 /// The optional data in a FunctionInfo object follows this fixed information
  45 /// and consists of a stream of tuples that consist of:
  46 ///
  47 /// ENCODING  NAME        DESCRIPTION
  48 /// ========= =========== ====================================================
  49 /// uint32_t  InfoType    An "InfoType" enumeration that describes the type
  50 ///                       of optional data that is encoded.
  51 /// uint32_t  InfoLength  The size in bytes of the encoded data that
  52 ///                       immediately follows this length if this value is
  53 ///                       greater than zero.
  54 /// uint8_t[] InfoData    Encoded bytes that represent the data for the
  55 ///                       "InfoType". These bytes are only present if
  56 ///                       "InfoLength" is greater than zero.
  57 ///
  58 /// The "InfoType" is an enumeration:
  59 ///
  60 ///   enum InfoType {
  61 ///     EndOfList = 0u,
  62 ///     LineTableInfo = 1u,
  63 ///     InlineInfo = 2u
  64 ///   };
  65 ///
  66 /// This stream of tuples is terminated by a "InfoType" whose value is
  67 /// InfoType::EndOfList and a zero for "InfoLength". This signifies the end of
  68 /// the optional information list. This format allows us to add new optional
  69 /// information data to a FunctionInfo object over time and allows older
  70 /// clients to still parse the format and skip over any data that they don't
  71 /// understand or want to parse.
  72 ///
  73 /// So the function information encoding essientially looks like:
  74 ///
  75 /// struct {
  76 ///   uint32_t Size;
  77 ///   uint32_t Name;
  78 ///   struct {
  79 ///     uint32_t InfoType;
  80 ///     uint32_t InfoLength;
  81 ///     uint8_t InfoData[InfoLength];
  82 ///   }[N];
  83 /// }
  84 ///
  85 /// Where "N" is the number of tuples.
  86 struct FunctionInfo {
  87   AddressRange Range;
  88   uint32_t Name; ///< String table offset in the string table.
  89   llvm::Optional<LineTable> OptLineTable;
  90   llvm::Optional<InlineInfo> Inline;
  91
  92   FunctionInfo(uint64_t Addr = 0, uint64_t Size = 0, uint32_t N = 0)
  93       : Range(Addr, Addr + Size), Name(N) {}
  94
  95   /// Query if a FunctionInfo has rich debug info.
  96   ///
  97   /// \returns A bool that indicates if this object has something else than
  98   /// range and name. When converting information from a symbol table and from
  99   /// debug info, we might end up with multiple FunctionInfo objects for the
 100   /// same range and we need to be able to tell which one is the better object
 101   /// to use.
 102   bool hasRichInfo() const {
 103     return OptLineTable.hasValue() || Inline.hasValue();
 104   }
 105
 106   /// Query if a FunctionInfo object is valid.
 107   ///
 108   /// Address and size can be zero and there can be no line entries for a
 109   /// symbol so the only indication this entry is valid is if the name is
 110   /// not zero. This can happen when extracting information from symbol
 111   /// tables that do not encode symbol sizes. In that case only the
 112   /// address and name will be filled in.
 113   ///
 114   /// \returns A boolean indicating if this FunctionInfo is valid.
 115   bool isValid() const {
 116     return Name != 0;
 117   }
 118
 119   /// Decode an object from a binary data stream.
 120   ///
 121   /// \param Data The binary stream to read the data from. This object must
 122   /// have the data for the object starting at offset zero. The data
 123   /// can contain more data than needed.
 124   ///
 125   /// \param BaseAddr The FunctionInfo's start address and will be used as the
 126   /// base address when decoding any contained information like the line table
 127   /// and the inline info.
 128   ///
 129   /// \returns An FunctionInfo or an error describing the issue that was
 130   /// encountered during decoding.
 131   static llvm::Expected<FunctionInfo> decode(DataExtractor &Data,
 132                                              uint64_t BaseAddr);
 133
 134   /// Encode this object into FileWriter stream.
 135   ///
 136   /// \param O The binary stream to write the data to at the current file
 137   /// position.
 138   ///
 139   /// \returns An error object that indicates failure or the offset of the
 140   /// function info that was successfully written into the stream.
 141   llvm::Expected<uint64_t> encode(FileWriter &O) const;
 142
 143   uint64_t startAddress() const { return Range.Start; }
 144   uint64_t endAddress() const { return Range.End; }
 145   uint64_t size() const { return Range.size(); }
 146   void setStartAddress(uint64_t Addr) { Range.Start = Addr; }
 147   void setEndAddress(uint64_t Addr) { Range.End = Addr; }
 148   void setSize(uint64_t Size) { Range.End = Range.Start + Size; }
 149
 150   void clear() {
 151     Range = {0, 0};
 152     Name = 0;
 153     OptLineTable = None;
 154     Inline = None;
 155   }
 156 };
 157
 158 inline bool operator==(const FunctionInfo &LHS, const FunctionInfo &RHS) {
 159   return LHS.Range == RHS.Range && LHS.Name == RHS.Name &&
 160          LHS.OptLineTable == RHS.OptLineTable && LHS.Inline == RHS.Inline;
 161 }
 162 inline bool operator!=(const FunctionInfo &LHS, const FunctionInfo &RHS) {
 163   return !(LHS == RHS);
 164 }
 165 /// This sorting will order things consistently by address range first, but then
 166 /// followed by inlining being valid and line tables. We might end up with a
 167 /// FunctionInfo from debug info that will have the same range as one from the
 168 /// symbol table, but we want to quickly be able to sort and use the best version
 169 /// when creating the final GSYM file.
 170 inline bool operator<(const FunctionInfo &LHS, const FunctionInfo &RHS) {
 171   // First sort by address range
 172   if (LHS.Range != RHS.Range)
 173     return LHS.Range < RHS.Range;
 174
 175   // Then sort by inline
 176   if (LHS.Inline.hasValue() != RHS.Inline.hasValue())
 177     return RHS.Inline.hasValue();
 178
 179   return LHS.OptLineTable < RHS.OptLineTable;
 180 }
 181
 182 raw_ostream &operator<<(raw_ostream &OS, const FunctionInfo &R);
 183
 184 } // namespace gsym
 185 } // namespace llvm
 186
 187 #endif // #ifndef LLVM_DEBUGINFO_GSYM_FUNCTIONINFO_H