include/llvm/DebugInfo/GSYM/InlineInfo.h

   1 //===- InlineInfo.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_INLINEINFO_H
  10 #define LLVM_DEBUGINFO_GSYM_INLINEINFO_H
  11
  12 #include "llvm/ADT/Optional.h"
  13 #include "llvm/DebugInfo/GSYM/Range.h"
  14 #include "llvm/Support/Error.h"
  15 #include <stdint.h>
  16 #include <vector>
  17
  18
  19 namespace llvm {
  20 class raw_ostream;
  21
  22 namespace gsym {
  23
  24 /// Inline information stores the name of the inline function along with
  25 /// an array of address ranges. It also stores the call file and call line
  26 /// that called this inline function. This allows us to unwind inline call
  27 /// stacks back to the inline or concrete function that called this
  28 /// function. Inlined functions contained in this function are stored in the
  29 /// "Children" variable. All address ranges must be sorted and all address
  30 /// ranges of all children must be contained in the ranges of this function.
  31 /// Any clients that encode information will need to ensure the ranges are
  32 /// all contined correctly or lookups could fail. Add ranges in these objects
  33 /// must be contained in the top level FunctionInfo address ranges as well.
  34 ///
  35 /// ENCODING
  36 ///
  37 /// When saved to disk, the inline info encodes all ranges to be relative to
  38 /// a parent address range. This will be the FunctionInfo's start address if
  39 /// the InlineInfo is directly contained in a FunctionInfo, or a the start
  40 /// address of the containing parent InlineInfo's first "Ranges" member. This
  41 /// allows address ranges to be efficiently encoded using ULEB128 encodings as
  42 /// we encode the offset and size of each range instead of full addresses. This
  43 /// also makes any encoded addresses easy to relocate as we just need to
  44 /// relocate the FunctionInfo's start address.
  45 ///
  46 /// - The AddressRanges member "Ranges" is encoded using an approriate base
  47 ///   address as described above.
  48 /// - UINT8 boolean value that specifies if the InlineInfo object has children.
  49 /// - UINT32 string table offset that points to the name of the inline
  50 ///   function.
  51 /// - ULEB128 integer that specifies the file of the call site that called
  52 ///   this function.
  53 /// - ULEB128 integer that specifies the source line of the call site that
  54 ///   called this function.
  55 /// - if this object has children, enocode each child InlineInfo using the
  56 ///   the first address range's start address as the base address.
  57 ///
  58 struct InlineInfo {
  59
  60   uint32_t Name; ///< String table offset in the string table.
  61   uint32_t CallFile; ///< 1 based file index in the file table.
  62   uint32_t CallLine; ///< Source line number.
  63   AddressRanges Ranges;
  64   std::vector<InlineInfo> Children;
  65   InlineInfo() : Name(0), CallFile(0), CallLine(0) {}
  66   void clear() {
  67     Name = 0;
  68     CallFile = 0;
  69     CallLine = 0;
  70     Ranges.clear();
  71     Children.clear();
  72   }
  73   bool isValid() const { return !Ranges.empty(); }
  74
  75   using InlineArray = std::vector<const InlineInfo *>;
  76
  77   /// Lookup an address in the InlineInfo object
  78   ///
  79   /// This function is used to symbolicate an inline call stack and can
  80   /// turn one address in the program into one or more inline call stacks
  81   /// and have the stack trace show the original call site from
  82   /// non-inlined code.
  83   ///
  84   /// \param Addr the address to lookup
  85   ///
  86   /// \returns optional vector of InlineInfo objects that describe the
  87   /// inline call stack for a given address, false otherwise.
  88   llvm::Optional<InlineArray> getInlineStack(uint64_t Addr) const;
  89
  90   /// Decode an InlineInfo object from a binary data stream.
  91   ///
  92   /// \param Data The binary stream to read the data from. This object must
  93   /// have the data for the InlineInfo object starting at offset zero. The data
  94   /// can contain more data than needed.
  95   ///
  96   /// \param BaseAddr The base address to use when decoding all address ranges.
  97   /// This will be the FunctionInfo's start address if this object is directly
  98   /// contained in a FunctionInfo object, or the start address of the first
  99   /// address range in an InlineInfo object of this object is a child of
 100   /// another InlineInfo object.
 101   /// \returns An InlineInfo or an error describing the issue that was
 102   /// encountered during decoding.
 103   static llvm::Expected<InlineInfo> decode(DataExtractor &Data,
 104                                            uint64_t BaseAddr);
 105
 106   /// Encode this InlineInfo object into FileWriter stream.
 107   ///
 108   /// \param O The binary stream to write the data to at the current file
 109   /// position.
 110   ///
 111   /// \param BaseAddr The base address to use when encoding all address ranges.
 112   /// This will be the FunctionInfo's start address if this object is directly
 113   /// contained in a FunctionInfo object, or the start address of the first
 114   /// address range in an InlineInfo object of this object is a child of
 115   /// another InlineInfo object.
 116   ///
 117   /// \returns An error object that indicates success or failure or the
 118   /// encoding process.
 119   llvm::Error encode(FileWriter &O, uint64_t BaseAddr) const;
 120 };
 121
 122 inline bool operator==(const InlineInfo &LHS, const InlineInfo &RHS) {
 123   return LHS.Name == RHS.Name && LHS.CallFile == RHS.CallFile &&
 124          LHS.CallLine == RHS.CallLine && LHS.Ranges == RHS.Ranges &&
 125          LHS.Children == RHS.Children;
 126 }
 127
 128 raw_ostream &operator<<(raw_ostream &OS, const InlineInfo &FI);
 129
 130 } // namespace gsym
 131 } // namespace llvm
 132
 133 #endif // #ifndef LLVM_DEBUGINFO_GSYM_INLINEINFO_H