include/llvm/DebugInfo/DWARF/DWARFDebugFrame.h

   1 //===- DWARFDebugFrame.h - Parsing of .debug_frame --------------*- 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_DWARF_DWARFDEBUGFRAME_H
  10 #define LLVM_DEBUGINFO_DWARF_DWARFDEBUGFRAME_H
  11
  12 #include "llvm/ADT/ArrayRef.h"
  13 #include "llvm/ADT/iterator.h"
  14 #include "llvm/ADT/SmallString.h"
  15 #include "llvm/ADT/Triple.h"
  16 #include "llvm/DebugInfo/DWARF/DWARFDataExtractor.h"
  17 #include "llvm/DebugInfo/DWARF/DWARFExpression.h"
  18 #include "llvm/Support/Error.h"
  19 #include <memory>
  20 #include <vector>
  21
  22 namespace llvm {
  23
  24 class raw_ostream;
  25
  26 namespace dwarf {
  27
  28 /// Represent a sequence of Call Frame Information instructions that, when read
  29 /// in order, construct a table mapping PC to frame state. This can also be
  30 /// referred to as "CFI rules" in DWARF literature to avoid confusion with
  31 /// computer programs in the broader sense, and in this context each instruction
  32 /// would be a rule to establish the mapping. Refer to pg. 172 in the DWARF5
  33 /// manual, "6.4.1 Structure of Call Frame Information".
  34 class CFIProgram {
  35 public:
  36   typedef SmallVector<uint64_t, 2> Operands;
  37
  38   /// An instruction consists of a DWARF CFI opcode and an optional sequence of
  39   /// operands. If it refers to an expression, then this expression has its own
  40   /// sequence of operations and operands handled separately by DWARFExpression.
  41   struct Instruction {
  42     Instruction(uint8_t Opcode) : Opcode(Opcode) {}
  43
  44     uint8_t Opcode;
  45     Operands Ops;
  46     // Associated DWARF expression in case this instruction refers to one
  47     Optional<DWARFExpression> Expression;
  48   };
  49
  50   using InstrList = std::vector<Instruction>;
  51   using iterator = InstrList::iterator;
  52   using const_iterator = InstrList::const_iterator;
  53
  54   iterator begin() { return Instructions.begin(); }
  55   const_iterator begin() const { return Instructions.begin(); }
  56   iterator end() { return Instructions.end(); }
  57   const_iterator end() const { return Instructions.end(); }
  58
  59   unsigned size() const { return (unsigned)Instructions.size(); }
  60   bool empty() const { return Instructions.empty(); }
  61
  62   CFIProgram(uint64_t CodeAlignmentFactor, int64_t DataAlignmentFactor,
  63              Triple::ArchType Arch)
  64       : CodeAlignmentFactor(CodeAlignmentFactor),
  65         DataAlignmentFactor(DataAlignmentFactor),
  66         Arch(Arch) {}
  67
  68   /// Parse and store a sequence of CFI instructions from Data,
  69   /// starting at *Offset and ending at EndOffset. *Offset is updated
  70   /// to EndOffset upon successful parsing, or indicates the offset
  71   /// where a problem occurred in case an error is returned.
  72   Error parse(DWARFDataExtractor Data, uint64_t *Offset, uint64_t EndOffset);
  73
  74   void dump(raw_ostream &OS, const MCRegisterInfo *MRI, bool IsEH,
  75             unsigned IndentLevel = 1) const;
  76
  77 private:
  78   std::vector<Instruction> Instructions;
  79   const uint64_t CodeAlignmentFactor;
  80   const int64_t DataAlignmentFactor;
  81   Triple::ArchType Arch;
  82
  83   /// Convenience method to add a new instruction with the given opcode.
  84   void addInstruction(uint8_t Opcode) {
  85     Instructions.push_back(Instruction(Opcode));
  86   }
  87
  88   /// Add a new single-operand instruction.
  89   void addInstruction(uint8_t Opcode, uint64_t Operand1) {
  90     Instructions.push_back(Instruction(Opcode));
  91     Instructions.back().Ops.push_back(Operand1);
  92   }
  93
  94   /// Add a new instruction that has two operands.
  95   void addInstruction(uint8_t Opcode, uint64_t Operand1, uint64_t Operand2) {
  96     Instructions.push_back(Instruction(Opcode));
  97     Instructions.back().Ops.push_back(Operand1);
  98     Instructions.back().Ops.push_back(Operand2);
  99   }
 100
 101   /// Types of operands to CFI instructions
 102   /// In DWARF, this type is implicitly tied to a CFI instruction opcode and
 103   /// thus this type doesn't need to be explictly written to the file (this is
 104   /// not a DWARF encoding). The relationship of instrs to operand types can
 105   /// be obtained from getOperandTypes() and is only used to simplify
 106   /// instruction printing.
 107   enum OperandType {
 108     OT_Unset,
 109     OT_None,
 110     OT_Address,
 111     OT_Offset,
 112     OT_FactoredCodeOffset,
 113     OT_SignedFactDataOffset,
 114     OT_UnsignedFactDataOffset,
 115     OT_Register,
 116     OT_Expression
 117   };
 118
 119   /// Retrieve the array describing the types of operands according to the enum
 120   /// above. This is indexed by opcode.
 121   static ArrayRef<OperandType[2]> getOperandTypes();
 122
 123   /// Print \p Opcode's operand number \p OperandIdx which has value \p Operand.
 124   void printOperand(raw_ostream &OS, const MCRegisterInfo *MRI, bool IsEH,
 125                     const Instruction &Instr, unsigned OperandIdx,
 126                     uint64_t Operand) const;
 127 };
 128
 129 /// An entry in either debug_frame or eh_frame. This entry can be a CIE or an
 130 /// FDE.
 131 class FrameEntry {
 132 public:
 133   enum FrameKind { FK_CIE, FK_FDE };
 134
 135   FrameEntry(FrameKind K, uint64_t Offset, uint64_t Length, uint64_t CodeAlign,
 136              int64_t DataAlign, Triple::ArchType Arch)
 137       : Kind(K), Offset(Offset), Length(Length),
 138         CFIs(CodeAlign, DataAlign, Arch) {}
 139
 140   virtual ~FrameEntry() {}
 141
 142   FrameKind getKind() const { return Kind; }
 143   uint64_t getOffset() const { return Offset; }
 144   uint64_t getLength() const { return Length; }
 145   const CFIProgram &cfis() const { return CFIs; }
 146   CFIProgram &cfis() { return CFIs; }
 147
 148   /// Dump the instructions in this CFI fragment
 149   virtual void dump(raw_ostream &OS, const MCRegisterInfo *MRI,
 150                     bool IsEH) const = 0;
 151
 152 protected:
 153   const FrameKind Kind;
 154
 155   /// Offset of this entry in the section.
 156   const uint64_t Offset;
 157
 158   /// Entry length as specified in DWARF.
 159   const uint64_t Length;
 160
 161   CFIProgram CFIs;
 162 };
 163
 164 /// DWARF Common Information Entry (CIE)
 165 class CIE : public FrameEntry {
 166 public:
 167   // CIEs (and FDEs) are simply container classes, so the only sensible way to
 168   // create them is by providing the full parsed contents in the constructor.
 169   CIE(uint64_t Offset, uint64_t Length, uint8_t Version,
 170       SmallString<8> Augmentation, uint8_t AddressSize,
 171       uint8_t SegmentDescriptorSize, uint64_t CodeAlignmentFactor,
 172       int64_t DataAlignmentFactor, uint64_t ReturnAddressRegister,
 173       SmallString<8> AugmentationData, uint32_t FDEPointerEncoding,
 174       uint32_t LSDAPointerEncoding, Optional<uint64_t> Personality,
 175       Optional<uint32_t> PersonalityEnc, Triple::ArchType Arch)
 176       : FrameEntry(FK_CIE, Offset, Length, CodeAlignmentFactor,
 177                    DataAlignmentFactor, Arch),
 178         Version(Version), Augmentation(std::move(Augmentation)),
 179         AddressSize(AddressSize), SegmentDescriptorSize(SegmentDescriptorSize),
 180         CodeAlignmentFactor(CodeAlignmentFactor),
 181         DataAlignmentFactor(DataAlignmentFactor),
 182         ReturnAddressRegister(ReturnAddressRegister),
 183         AugmentationData(std::move(AugmentationData)),
 184         FDEPointerEncoding(FDEPointerEncoding),
 185         LSDAPointerEncoding(LSDAPointerEncoding), Personality(Personality),
 186         PersonalityEnc(PersonalityEnc) {}
 187
 188   static bool classof(const FrameEntry *FE) { return FE->getKind() == FK_CIE; }
 189
 190   StringRef getAugmentationString() const { return Augmentation; }
 191   uint64_t getCodeAlignmentFactor() const { return CodeAlignmentFactor; }
 192   int64_t getDataAlignmentFactor() const { return DataAlignmentFactor; }
 193   uint8_t getVersion() const { return Version; }
 194   uint64_t getReturnAddressRegister() const { return ReturnAddressRegister; }
 195   Optional<uint64_t> getPersonalityAddress() const { return Personality; }
 196   Optional<uint32_t> getPersonalityEncoding() const { return PersonalityEnc; }
 197
 198   uint32_t getFDEPointerEncoding() const { return FDEPointerEncoding; }
 199
 200   uint32_t getLSDAPointerEncoding() const { return LSDAPointerEncoding; }
 201
 202   void dump(raw_ostream &OS, const MCRegisterInfo *MRI,
 203             bool IsEH) const override;
 204
 205 private:
 206   /// The following fields are defined in section 6.4.1 of the DWARF standard v4
 207   const uint8_t Version;
 208   const SmallString<8> Augmentation;
 209   const uint8_t AddressSize;
 210   const uint8_t SegmentDescriptorSize;
 211   const uint64_t CodeAlignmentFactor;
 212   const int64_t DataAlignmentFactor;
 213   const uint64_t ReturnAddressRegister;
 214
 215   // The following are used when the CIE represents an EH frame entry.
 216   const SmallString<8> AugmentationData;
 217   const uint32_t FDEPointerEncoding;
 218   const uint32_t LSDAPointerEncoding;
 219   const Optional<uint64_t> Personality;
 220   const Optional<uint32_t> PersonalityEnc;
 221 };
 222
 223 /// DWARF Frame Description Entry (FDE)
 224 class FDE : public FrameEntry {
 225 public:
 226   // Each FDE has a CIE it's "linked to". Our FDE contains is constructed with
 227   // an offset to the CIE (provided by parsing the FDE header). The CIE itself
 228   // is obtained lazily once it's actually required.
 229   FDE(uint64_t Offset, uint64_t Length, int64_t LinkedCIEOffset,
 230       uint64_t InitialLocation, uint64_t AddressRange, CIE *Cie,
 231       Optional<uint64_t> LSDAAddress, Triple::ArchType Arch)
 232       : FrameEntry(FK_FDE, Offset, Length,
 233                    Cie ? Cie->getCodeAlignmentFactor() : 0,
 234                    Cie ? Cie->getDataAlignmentFactor() : 0,
 235                    Arch),
 236         LinkedCIEOffset(LinkedCIEOffset), InitialLocation(InitialLocation),
 237         AddressRange(AddressRange), LinkedCIE(Cie), LSDAAddress(LSDAAddress) {}
 238
 239   ~FDE() override = default;
 240
 241   const CIE *getLinkedCIE() const { return LinkedCIE; }
 242   uint64_t getInitialLocation() const { return InitialLocation; }
 243   uint64_t getAddressRange() const { return AddressRange; }
 244   Optional<uint64_t> getLSDAAddress() const { return LSDAAddress; }
 245
 246   void dump(raw_ostream &OS, const MCRegisterInfo *MRI,
 247             bool IsEH) const override;
 248
 249   static bool classof(const FrameEntry *FE) { return FE->getKind() == FK_FDE; }
 250
 251 private:
 252   /// The following fields are defined in section 6.4.1 of the DWARF standard v3
 253   const uint64_t LinkedCIEOffset;
 254   const uint64_t InitialLocation;
 255   const uint64_t AddressRange;
 256   const CIE *LinkedCIE;
 257   const Optional<uint64_t> LSDAAddress;
 258 };
 259
 260 } // end namespace dwarf
 261
 262 /// A parsed .debug_frame or .eh_frame section
 263 class DWARFDebugFrame {
 264   const Triple::ArchType Arch;
 265   // True if this is parsing an eh_frame section.
 266   const bool IsEH;
 267   // Not zero for sane pointer values coming out of eh_frame
 268   const uint64_t EHFrameAddress;
 269
 270   std::vector<std::unique_ptr<dwarf::FrameEntry>> Entries;
 271   using iterator = pointee_iterator<decltype(Entries)::const_iterator>;
 272
 273   /// Return the entry at the given offset or nullptr.
 274   dwarf::FrameEntry *getEntryAtOffset(uint64_t Offset) const;
 275
 276 public:
 277   // If IsEH is true, assume it is a .eh_frame section. Otherwise,
 278   // it is a .debug_frame section. EHFrameAddress should be different
 279   // than zero for correct parsing of .eh_frame addresses when they
 280   // use a PC-relative encoding.
 281   DWARFDebugFrame(Triple::ArchType Arch,
 282                   bool IsEH = false, uint64_t EHFrameAddress = 0);
 283   ~DWARFDebugFrame();
 284
 285   /// Dump the section data into the given stream.
 286   void dump(raw_ostream &OS, const MCRegisterInfo *MRI,
 287             Optional<uint64_t> Offset) const;
 288
 289   /// Parse the section from raw data. \p Data is assumed to contain the whole
 290   /// frame section contents to be parsed.
 291   void parse(DWARFDataExtractor Data);
 292
 293   /// Return whether the section has any entries.
 294   bool empty() const { return Entries.empty(); }
 295
 296   /// DWARF Frame entries accessors
 297   iterator begin() const { return Entries.begin(); }
 298   iterator end() const { return Entries.end(); }
 299   iterator_range<iterator> entries() const {
 300     return iterator_range<iterator>(Entries.begin(), Entries.end());
 301   }
 302
 303   uint64_t getEHFrameAddress() const { return EHFrameAddress; }
 304 };
 305
 306 } // end namespace llvm
 307
 308 #endif // LLVM_DEBUGINFO_DWARF_DWARFDEBUGFRAME_H