Add comments to the CFI instructions and reformat with clang-format. No functionality change.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@189864 91177308-0d34-0410-b5e6-96231b3b80d8

include/llvm/MC/MCDwarf.h

@@ -23,19 +23,19 @@
 #include <vector>
 
 namespace llvm {
-  class MCContext;
-  class MCSection;
-  class MCStreamer;
-  class MCSymbol;
-  class SourceMgr;
-  class SMLoc;
+class MCContext;
+class MCSection;
+class MCStreamer;
+class MCSymbol;
+class SourceMgr;
+class SMLoc;
 
-  /// MCDwarfFile - Instances of this class represent the name of the dwarf
-  /// .file directive and its associated dwarf file number in the MC file,
-  /// and MCDwarfFile's are created and unique'd by the MCContext class where
-  /// the file number for each is its index into the vector of DwarfFiles (note
-  /// index 0 is not used and not a valid dwarf file number).
-  class MCDwarfFile {
+/// MCDwarfFile - Instances of this class represent the name of the dwarf
+/// .file directive and its associated dwarf file number in the MC file,
+/// and MCDwarfFile's are created and unique'd by the MCContext class where
+/// the file number for each is its index into the vector of DwarfFiles (note
+/// index 0 is not used and not a valid dwarf file number).
+class MCDwarfFile {
   // Name - the base name of the file without its directory path.
   // The StringRef references memory allocated in the MCContext.
   StringRef Name;
@@ -43,36 +43,36 @@ namespace llvm {
   // DirIndex - the index into the list of directory names for this file name.
   unsigned DirIndex;
 
-  private:  // MCContext creates and uniques these.
+private: // MCContext creates and uniques these.
   friend class MCContext;
   MCDwarfFile(StringRef name, unsigned dirIndex)
       : Name(name), DirIndex(dirIndex) {}
 
-    MCDwarfFile(const MCDwarfFile&) LLVM_DELETED_FUNCTION;
-    void operator=(const MCDwarfFile&) LLVM_DELETED_FUNCTION;
-  public:
+  MCDwarfFile(const MCDwarfFile &) LLVM_DELETED_FUNCTION;
+  void operator=(const MCDwarfFile &) LLVM_DELETED_FUNCTION;
+
+public:
   /// getName - Get the base name of this MCDwarfFile.
   StringRef getName() const { return Name; }
 
   /// getDirIndex - Get the dirIndex of this MCDwarfFile.
   unsigned getDirIndex() const { return DirIndex; }
 
-
   /// print - Print the value to the stream \p OS.
   void print(raw_ostream &OS) const;
 
   /// dump - Print the value to stderr.
   void dump() const;
-  };
+};
 
-  inline raw_ostream &operator<<(raw_ostream &OS, const MCDwarfFile &DwarfFile){
+inline raw_ostream &operator<<(raw_ostream &OS, const MCDwarfFile &DwarfFile) {
   DwarfFile.print(OS);
   return OS;
-  }
+}
 
-  /// MCDwarfLoc - Instances of this class represent the information from a
-  /// dwarf .loc directive.
-  class MCDwarfLoc {
+/// MCDwarfLoc - Instances of this class represent the information from a
+/// dwarf .loc directive.
+class MCDwarfLoc {
   // FileNum - the file number.
   unsigned FileNum;
   // Line - the line number.
@@ -94,7 +94,7 @@ namespace llvm {
 #define DWARF2_FLAG_PROLOGUE_END (1 << 2)
 #define DWARF2_FLAG_EPILOGUE_BEGIN (1 << 3)
 
-  private:  // MCContext manages these
+private: // MCContext manages these
   friend class MCContext;
   friend class MCLineEntry;
   MCDwarfLoc(unsigned fileNum, unsigned line, unsigned column, unsigned flags,
@@ -105,7 +105,7 @@ namespace llvm {
   // Allow the default copy constructor and assignment operator to be used
   // for an MCDwarfLoc object.
 
-  public:
+public:
   /// getFileNum - Get the FileNum of this MCDwarfLoc.
   unsigned getFileNum() const { return FileNum; }
 
@@ -143,24 +143,24 @@ namespace llvm {
   void setDiscriminator(unsigned discriminator) {
     Discriminator = discriminator;
   }
-  };
+};
 
-  /// MCLineEntry - Instances of this class represent the line information for
-  /// the dwarf line table entries.  Which is created after a machine
-  /// instruction is assembled and uses an address from a temporary label
-  /// created at the current address in the current section and the info from
-  /// the last .loc directive seen as stored in the context.
-  class MCLineEntry : public MCDwarfLoc {
+/// MCLineEntry - Instances of this class represent the line information for
+/// the dwarf line table entries.  Which is created after a machine
+/// instruction is assembled and uses an address from a temporary label
+/// created at the current address in the current section and the info from
+/// the last .loc directive seen as stored in the context.
+class MCLineEntry : public MCDwarfLoc {
   MCSymbol *Label;
 
-  private:
+private:
   // Allow the default copy constructor and assignment operator to be used
   // for an MCLineEntry object.
 
-  public:
+public:
   // Constructor to create an MCLineEntry given a symbol and the dwarf loc.
-    MCLineEntry(MCSymbol *label, const MCDwarfLoc loc) : MCDwarfLoc(loc),
-                Label(label) {}
+  MCLineEntry(MCSymbol *label, const MCDwarfLoc loc)
+      : MCDwarfLoc(loc), Label(label) {}
 
   MCSymbol *getLabel() const { return Label; }
 
@@ -168,19 +168,19 @@ namespace llvm {
   // section and if there is information from the last .loc directive that
   // has yet to have a line entry made for it is made.
   static void Make(MCStreamer *MCOS, const MCSection *Section);
-  };
+};
 
-  /// MCLineSection - Instances of this class represent the line information
-  /// for a section where machine instructions have been assembled after seeing
-  /// .loc directives.  This is the information used to build the dwarf line
-  /// table for a section.
-  class MCLineSection {
+/// MCLineSection - Instances of this class represent the line information
+/// for a section where machine instructions have been assembled after seeing
+/// .loc directives.  This is the information used to build the dwarf line
+/// table for a section.
+class MCLineSection {
 
-  private:
-    MCLineSection(const MCLineSection&) LLVM_DELETED_FUNCTION;
-    void operator=(const MCLineSection&) LLVM_DELETED_FUNCTION;
+private:
+  MCLineSection(const MCLineSection &) LLVM_DELETED_FUNCTION;
+  void operator=(const MCLineSection &) LLVM_DELETED_FUNCTION;
 
-  public:
+public:
   // Constructor to create an MCLineSection with an empty MCLineEntries
   // vector.
   MCLineSection() {}
@@ -195,11 +195,11 @@ namespace llvm {
   typedef MCLineEntryCollection::const_iterator const_iterator;
   typedef std::map<unsigned, MCLineEntryCollection> MCLineDivisionMap;
 
-  private:
+private:
   // A collection of MCLineEntry for each Compile Unit ID.
   MCLineDivisionMap MCLineDivisions;
 
-  public:
+public:
   // Returns whether MCLineSection contains entries for a given Compile
   // Unit ID.
   bool containEntriesForID(unsigned CUID) const {
@@ -211,10 +211,10 @@ namespace llvm {
     assert(CIter != MCLineDivisions.end());
     return CIter->second;
   }
-  };
+};
 
-  class MCDwarfFileTable {
-  public:
+class MCDwarfFileTable {
+public:
   //
   // This emits the Dwarf file and the line tables for all Compile Units.
   //
@@ -223,32 +223,31 @@ namespace llvm {
   // This emits the Dwarf file and the line tables for a given Compile Unit.
   //
   static const MCSymbol *EmitCU(MCStreamer *MCOS, unsigned ID);
-  };
+};
 
-  class MCDwarfLineAddr {
-  public:
+class MCDwarfLineAddr {
+public:
   /// Utility function to encode a Dwarf pair of LineDelta and AddrDeltas.
-    static void Encode(MCContext &Context, int64_t LineDelta,
-                       uint64_t AddrDelta, raw_ostream &OS);
+  static void Encode(MCContext &Context, int64_t LineDelta, uint64_t AddrDelta,
+                     raw_ostream &OS);
 
   /// Utility function to emit the encoding to a streamer.
-    static void Emit(MCStreamer *MCOS,
-                     int64_t LineDelta,uint64_t AddrDelta);
-  };
+  static void Emit(MCStreamer *MCOS, int64_t LineDelta, uint64_t AddrDelta);
+};
 
-  class MCGenDwarfInfo {
-  public:
+class MCGenDwarfInfo {
+public:
   //
   // When generating dwarf for assembly source files this emits the Dwarf
   // sections.
   //
   static void Emit(MCStreamer *MCOS, const MCSymbol *LineSectionSymbol);
-  };
+};
 
-  // When generating dwarf for assembly source files this is the info that is
-  // needed to be gathered for each symbol that will have a dwarf label.
-  class MCGenDwarfLabelEntry {
-  private:
+// When generating dwarf for assembly source files this is the info that is
+// needed to be gathered for each symbol that will have a dwarf label.
+class MCGenDwarfLabelEntry {
+private:
   // Name of the symbol without a leading underbar, if any.
   StringRef Name;
   // The dwarf file number this symbol is in.
@@ -258,10 +257,11 @@ namespace llvm {
   // The low_pc for the dwarf label is taken from this symbol.
   MCSymbol *Label;
 
-  public:
-    MCGenDwarfLabelEntry(StringRef name, unsigned fileNumber,
-                         unsigned lineNumber, MCSymbol *label) :
-      Name(name), FileNumber(fileNumber), LineNumber(lineNumber), Label(label){}
+public:
+  MCGenDwarfLabelEntry(StringRef name, unsigned fileNumber, unsigned lineNumber,
+                       MCSymbol *label)
+      : Name(name), FileNumber(fileNumber), LineNumber(lineNumber),
+        Label(label) {}
 
   StringRef getName() const { return Name; }
   unsigned getFileNumber() const { return FileNumber; }
@@ -272,15 +272,27 @@ namespace llvm {
   // assembly source files.
   static void Make(MCSymbol *Symbol, MCStreamer *MCOS, SourceMgr &SrcMgr,
                    SMLoc &Loc);
+};
+
+class MCCFIInstruction {
+public:
+  enum OpType {
+    OpSameValue,
+    OpRememberState,
+    OpRestoreState,
+    OpOffset,
+    OpDefCfaRegister,
+    OpDefCfaOffset,
+    OpDefCfa,
+    OpRelOffset,
+    OpAdjustCfaOffset,
+    OpEscape,
+    OpRestore,
+    OpUndefined,
+    OpRegister
   };
 
-  class MCCFIInstruction {
-  public:
-    enum OpType { OpSameValue, OpRememberState, OpRestoreState, OpOffset,
-                  OpDefCfaRegister, OpDefCfaOffset, OpDefCfa, OpRelOffset,
-                  OpAdjustCfaOffset, OpEscape, OpRestore, OpUndefined,
-                  OpRegister };
-  private:
+private:
   OpType Operation;
   MCSymbol *Label;
   unsigned Register;
@@ -290,76 +302,103 @@ namespace llvm {
   };
   std::vector<char> Values;
 
-    MCCFIInstruction(OpType Op, MCSymbol *L, unsigned R, int O, StringRef V) :
-      Operation(Op), Label(L), Register(R), Offset(O),
+  MCCFIInstruction(OpType Op, MCSymbol *L, unsigned R, int O, StringRef V)
+      : Operation(Op), Label(L), Register(R), Offset(O),
         Values(V.begin(), V.end()) {
     assert(Op != OpRegister);
   }
 
-    MCCFIInstruction(OpType Op, MCSymbol *L, unsigned R1, unsigned R2) :
-      Operation(Op), Label(L), Register(R1), Register2(R2) {
+  MCCFIInstruction(OpType Op, MCSymbol *L, unsigned R1, unsigned R2)
+      : Operation(Op), Label(L), Register(R1), Register2(R2) {
     assert(Op == OpRegister);
   }
 
-  public:
-    static MCCFIInstruction
-    createOffset(MCSymbol *L, unsigned Register, int Offset) {
-      return MCCFIInstruction(OpOffset, L, Register, Offset, "");
+public:
+  /// \brief .cfi_def_cfa defines a rule for computing CFA as: take address from
+  /// \param Register and add \param Offset to it.
+  static MCCFIInstruction createDefCfa(MCSymbol *L, unsigned Register,
+                                       int Offset) {
+    return MCCFIInstruction(OpDefCfa, L, Register, -Offset, "");
   }
 
-    static MCCFIInstruction
-    createDefCfaRegister(MCSymbol *L, unsigned Register) {
+  /// \brief .cfi_def_cfa_register modifies a rule for computing CFA. From now
+  /// on \param Register will be used instead of the old one. Offset remains the
+  /// same.
+  static MCCFIInstruction createDefCfaRegister(MCSymbol *L, unsigned Register) {
     return MCCFIInstruction(OpDefCfaRegister, L, Register, 0, "");
   }
 
+  /// \brief .cfi_def_cfa_offset modifies a rule for computing CFA. Register
+  /// remains the same, but offset is new. Note that it is the absolute offset
+  /// that will be added to a defined register to the compute CFA address.
   static MCCFIInstruction createDefCfaOffset(MCSymbol *L, int Offset) {
     return MCCFIInstruction(OpDefCfaOffset, L, 0, -Offset, "");
   }
 
-    static MCCFIInstruction
-    createDefCfa(MCSymbol *L, unsigned Register, int Offset) {
-      return MCCFIInstruction(OpDefCfa, L, Register, -Offset, "");
+  /// \brief .cfi_adjust_cfa_offset Same as .cfi_def_cfa_offset, but \param
+  /// Offset is a relative value that is added/subtracted from the previous
+  /// offset.
+  static MCCFIInstruction createAdjustCfaOffset(MCSymbol *L, int Adjustment) {
+    return MCCFIInstruction(OpAdjustCfaOffset, L, 0, Adjustment, "");
   }
 
-    static MCCFIInstruction createUndefined(MCSymbol *L, unsigned Register) {
-      return MCCFIInstruction(OpUndefined, L, Register, 0, "");
+  /// \brief .cfi_offset Previous value of \param Register is saved at offset
+  /// \param Offset from CFA.
+  static MCCFIInstruction createOffset(MCSymbol *L, unsigned Register,
+                                       int Offset) {
+    return MCCFIInstruction(OpOffset, L, Register, Offset, "");
   }
 
+  /// \brief .cfi_rel_offset Previous value of \param Register is saved at
+  /// offset \param Offset from the current CFA register. This is transformed to
+  /// .cfi_offset using the known displacement of the CFA register from the CFA.
+  static MCCFIInstruction createRelOffset(MCSymbol *L, unsigned Register,
+                                          int Offset) {
+    return MCCFIInstruction(OpRelOffset, L, Register, Offset, "");
+  }
+
+  /// \brief .cfi_register Previous value of \param Register1 is saved in
+  /// register \param Register2.
+  static MCCFIInstruction createRegister(MCSymbol *L, unsigned Register1,
+                                         unsigned Register2) {
+    return MCCFIInstruction(OpRegister, L, Register1, Register2);
+  }
+
+  /// \brief .cfi_restore says that the rule for \param Register is now the same
+  /// as it was at the beginning of the function, after all initial instructions
+  /// added by .cfi_startproc were executed.
   static MCCFIInstruction createRestore(MCSymbol *L, unsigned Register) {
     return MCCFIInstruction(OpRestore, L, Register, 0, "");
   }
 
+  /// \brief .cfi_undefined From now on the previous value of \param Register
+  /// can't be restored anymore.
+  static MCCFIInstruction createUndefined(MCSymbol *L, unsigned Register) {
+    return MCCFIInstruction(OpUndefined, L, Register, 0, "");
+  }
+
+  /// \brief .cfi_same_value Current value of \param Register is the same as
+  /// in the previous frame. I.e., no restoration is needed.
   static MCCFIInstruction createSameValue(MCSymbol *L, unsigned Register) {
     return MCCFIInstruction(OpSameValue, L, Register, 0, "");
   }
 
-    static MCCFIInstruction createRestoreState(MCSymbol *L) {
-      return MCCFIInstruction(OpRestoreState, L, 0, 0, "");
-    }
-
+  /// \brief .cfi_remember_state Save all current rules for all registers.
   static MCCFIInstruction createRememberState(MCSymbol *L) {
     return MCCFIInstruction(OpRememberState, L, 0, 0, "");
   }
 
-    static MCCFIInstruction
-    createRelOffset(MCSymbol *L, unsigned Register, int Offset) {
-      return MCCFIInstruction(OpRelOffset, L, Register, Offset, "");
-    }
-
-    static MCCFIInstruction
-    createAdjustCfaOffset(MCSymbol *L, int Adjustment) {
-      return MCCFIInstruction(OpAdjustCfaOffset, L, 0, Adjustment, "");
+  /// \brief .cfi_restore_state Restore the previously saved state.
+  static MCCFIInstruction createRestoreState(MCSymbol *L) {
+    return MCCFIInstruction(OpRestoreState, L, 0, 0, "");
   }
 
+  /// \brief .cfi_escape Allows the user to add arbitrary bytes to the unwind
+  /// info.
   static MCCFIInstruction createEscape(MCSymbol *L, StringRef Vals) {
     return MCCFIInstruction(OpEscape, L, 0, 0, Vals);
   }
 
-   static MCCFIInstruction
-   createRegister(MCSymbol *L, unsigned Register1, unsigned Register2) {
-      return MCCFIInstruction(OpRegister, L, Register1, Register2);
-    }
-
   OpType getOperation() const { return Operation; }
   MCSymbol *getLabel() const { return Label; }
 
@@ -387,12 +426,12 @@ namespace llvm {
     assert(Operation == OpEscape);
     return StringRef(&Values[0], Values.size());
   }
-  };
+};
 
-  struct MCDwarfFrameInfo {
-    MCDwarfFrameInfo() : Begin(0), End(0), Personality(0), Lsda(0),
-                         Function(0), Instructions(), PersonalityEncoding(),
-                         LsdaEncoding(0), CompactUnwindEncoding(0),
+struct MCDwarfFrameInfo {
+  MCDwarfFrameInfo()
+      : Begin(0), End(0), Personality(0), Lsda(0), Function(0), Instructions(),
+        PersonalityEncoding(), LsdaEncoding(0), CompactUnwindEncoding(0),
         IsSignalFrame(false) {}
   MCSymbol *Begin;
   MCSymbol *End;
@@ -404,19 +443,18 @@ namespace llvm {
   unsigned LsdaEncoding;
   uint32_t CompactUnwindEncoding;
   bool IsSignalFrame;
-  };
+};
 
-  class MCDwarfFrameEmitter {
-  public:
+class MCDwarfFrameEmitter {
+public:
   //
   // This emits the frame info section.
   //
-    static void Emit(MCStreamer &streamer, bool usingCFI,
-                     bool isEH);
+  static void Emit(MCStreamer &streamer, bool usingCFI, bool isEH);
   static void EmitAdvanceLoc(MCStreamer &Streamer, uint64_t AddrDelta);
   static void EncodeAdvanceLoc(MCContext &Context, uint64_t AddrDelta,
                                raw_ostream &OS);
-  };
+};
 } // end namespace llvm
 
 #endif