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

@@ -50,6 +50,7 @@ namespace llvm {
 
   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; }
@@ -57,7 +58,6 @@ namespace llvm {
   /// 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;
 
@@ -159,8 +159,8 @@ namespace llvm {
 
 public:
   // Constructor to create an MCLineEntry given a symbol and the dwarf loc.
-    MCLineEntry(MCSymbol *label, const MCDwarfLoc loc) : MCDwarfLoc(loc),
+  MCLineEntry(MCSymbol *label, const MCDwarfLoc loc)
-                Label(label) {}
+      : MCDwarfLoc(loc), Label(label) {}
 
   MCSymbol *getLabel() const { return Label; }
 
@@ -228,12 +228,11 @@ namespace llvm {
 class MCDwarfLineAddr {
 public:
   /// Utility function to encode a Dwarf pair of LineDelta and AddrDeltas.
-    static void Encode(MCContext &Context, int64_t LineDelta,
+  static void Encode(MCContext &Context, int64_t LineDelta, uint64_t AddrDelta,
-                       uint64_t AddrDelta, raw_ostream &OS);
+                     raw_ostream &OS);
 
   /// Utility function to emit the encoding to a streamer.
-    static void Emit(MCStreamer *MCOS,
+  static void Emit(MCStreamer *MCOS, int64_t LineDelta, uint64_t AddrDelta);
-                     int64_t LineDelta,uint64_t AddrDelta);
 };
 
 class MCGenDwarfInfo {
@@ -259,9 +258,10 @@ namespace llvm {
   MCSymbol *Label;
 
 public:
-    MCGenDwarfLabelEntry(StringRef name, unsigned fileNumber,
+  MCGenDwarfLabelEntry(StringRef name, unsigned fileNumber, unsigned lineNumber,
-                         unsigned lineNumber, MCSymbol *label) :
+                       MCSymbol *label)
-      Name(name), FileNumber(fileNumber), LineNumber(lineNumber), Label(label){}
+      : Name(name), FileNumber(fileNumber), LineNumber(lineNumber),
+        Label(label) {}
 
   StringRef getName() const { return Name; }
   unsigned getFileNumber() const { return FileNumber; }
@@ -276,10 +276,22 @@ namespace llvm {
 
 class MCCFIInstruction {
 public:
-    enum OpType { OpSameValue, OpRememberState, OpRestoreState, OpOffset,
+  enum OpType {
-                  OpDefCfaRegister, OpDefCfaOffset, OpDefCfa, OpRelOffset,
+    OpSameValue,
-                  OpAdjustCfaOffset, OpEscape, OpRestore, OpUndefined,
+    OpRememberState,
-                  OpRegister };
+    OpRestoreState,
+    OpOffset,
+    OpDefCfaRegister,
+    OpDefCfaOffset,
+    OpDefCfa,
+    OpRelOffset,
+    OpAdjustCfaOffset,
+    OpEscape,
+    OpRestore,
+    OpUndefined,
+    OpRegister
+  };
+
 private:
   OpType Operation;
   MCSymbol *Label;
@@ -290,76 +302,103 @@ namespace llvm {
   };
   std::vector<char> Values;
 
-    MCCFIInstruction(OpType Op, MCSymbol *L, unsigned R, int O, StringRef V) :
+  MCCFIInstruction(OpType Op, MCSymbol *L, unsigned R, int O, StringRef V)
-      Operation(Op), Label(L), Register(R), Offset(O),
+      : 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) :
+  MCCFIInstruction(OpType Op, MCSymbol *L, unsigned R1, unsigned R2)
-      Operation(Op), Label(L), Register(R1), Register2(R2) {
+      : Operation(Op), Label(L), Register(R1), Register2(R2) {
     assert(Op == OpRegister);
   }
 
 public:
-    static MCCFIInstruction
+  /// \brief .cfi_def_cfa defines a rule for computing CFA as: take address from
-    createOffset(MCSymbol *L, unsigned Register, int Offset) {
+  /// \param Register and add \param Offset to it.
-      return MCCFIInstruction(OpOffset, L, Register, Offset, "");
+  static MCCFIInstruction createDefCfa(MCSymbol *L, unsigned Register,
+                                       int Offset) {
+    return MCCFIInstruction(OpDefCfa, L, Register, -Offset, "");
   }
 
-    static MCCFIInstruction
+  /// \brief .cfi_def_cfa_register modifies a rule for computing CFA. From now
-    createDefCfaRegister(MCSymbol *L, unsigned Register) {
+  /// 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
+  /// \brief .cfi_adjust_cfa_offset Same as .cfi_def_cfa_offset, but \param
-    createDefCfa(MCSymbol *L, unsigned Register, int Offset) {
+  /// Offset is a relative value that is added/subtracted from the previous
-      return MCCFIInstruction(OpDefCfa, L, Register, -Offset, "");
+  /// offset.
+  static MCCFIInstruction createAdjustCfaOffset(MCSymbol *L, int Adjustment) {
+    return MCCFIInstruction(OpAdjustCfaOffset, L, 0, Adjustment, "");
   }
 
-    static MCCFIInstruction createUndefined(MCSymbol *L, unsigned Register) {
+  /// \brief .cfi_offset Previous value of \param Register is saved at offset
-      return MCCFIInstruction(OpUndefined, L, Register, 0, "");
+  /// \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) {
+  /// \brief .cfi_remember_state Save all current rules for all registers.
-      return MCCFIInstruction(OpRestoreState, L, 0, 0, "");
-    }
-
   static MCCFIInstruction createRememberState(MCSymbol *L) {
     return MCCFIInstruction(OpRememberState, L, 0, 0, "");
   }
 
-    static MCCFIInstruction
+  /// \brief .cfi_restore_state Restore the previously saved state.
-    createRelOffset(MCSymbol *L, unsigned Register, int Offset) {
+  static MCCFIInstruction createRestoreState(MCSymbol *L) {
-      return MCCFIInstruction(OpRelOffset, L, Register, Offset, "");
+    return MCCFIInstruction(OpRestoreState, L, 0, 0, "");
-    }
-
-    static MCCFIInstruction
-    createAdjustCfaOffset(MCSymbol *L, int Adjustment) {
-      return MCCFIInstruction(OpAdjustCfaOffset, L, 0, Adjustment, "");
   }
 
+  /// \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; }
 
@@ -390,9 +429,9 @@ namespace llvm {
 };
 
 struct MCDwarfFrameInfo {
-    MCDwarfFrameInfo() : Begin(0), End(0), Personality(0), Lsda(0),
+  MCDwarfFrameInfo()
-                         Function(0), Instructions(), PersonalityEncoding(),
+      : Begin(0), End(0), Personality(0), Lsda(0), Function(0), Instructions(),
-                         LsdaEncoding(0), CompactUnwindEncoding(0),
+        PersonalityEncoding(), LsdaEncoding(0), CompactUnwindEncoding(0),
         IsSignalFrame(false) {}
   MCSymbol *Begin;
   MCSymbol *End;
@@ -411,8 +450,7 @@ namespace llvm {
   //
   // This emits the frame info section.
   //
-    static void Emit(MCStreamer &streamer, bool usingCFI,
+  static void Emit(MCStreamer &streamer, bool usingCFI, bool isEH);
-                     bool isEH);
   static void EmitAdvanceLoc(MCStreamer &Streamer, uint64_t AddrDelta);
   static void EncodeAdvanceLoc(MCContext &Context, uint64_t AddrDelta,
                                raw_ostream &OS);