Add a little documentation for the register kinds

and the method to convert between them.

llvm-svn: 216372

2 files changed, 40 insertions, 2 deletions

diff --git a/lldb/include/lldb/Target/RegisterContext.h b/lldb/include/lldb/Target/RegisterContext.h
index 2b5a8da17bd..9108d457525 100644
--- a/lldb/include/lldb/Target/RegisterContext.h
+++ b/lldb/include/lldb/Target/RegisterContext.h
@@ -86,7 +86,42 @@ public:
     
     bool
     CopyFromRegisterContext (lldb::RegisterContextSP context);
-    
+
+    //------------------------------------------------------------------
+    /// Convert from a given register numbering scheme to the lldb register 
+    /// numbering scheme
+    ///
+    /// There may be multiple ways to enumerate the registers for a given
+    /// architecture.  ABI references will specify one to be used with
+    /// DWARF, the register numberings from stabs (aka "gcc"), there may
+    /// be a variation used for eh_frame unwind instructions (e.g. on Darwin),
+    /// and so on.  Register 5 by itself is meaningless - RegisterKind
+    /// enumeration tells you what context that number should be translated as.
+    ///
+    /// Inside lldb, register numbers are in the eRegisterKindLLDB scheme;
+    /// arguments which take a register number should take one in that
+    /// scheme.
+    ///
+    /// eRegisterKindGeneric is a special numbering scheme which gives us 
+    /// constant values for the pc, frame register, stack register, etc., for
+    /// use within lldb.  They may not be defined for all architectures but
+    /// it allows generic code to translate these common registers into the
+    /// lldb numbering scheme.
+    ///
+    /// This method translates a given register kind + register number into
+    /// the eRegisterKindLLDB register numbering.
+    ///
+    /// @param [in] kind
+    ///     The register numbering scheme (RegisterKind) that the following
+    ///     register number is in.
+    ///
+    /// @param [in] num
+    ///     A register number in the 'kind' register numbering scheme.
+    ///
+    /// @return
+    ///     The equivalent register number in the eRegisterKindLLDB
+    ///     numbering scheme, if possible, else LLDB_INVALID_REGNUM.
+    //------------------------------------------------------------------
     virtual uint32_t
     ConvertRegisterKindToRegisterNumber (lldb::RegisterKind kind, uint32_t num) = 0;
 
diff --git a/lldb/include/lldb/lldb-enumerations.h b/lldb/include/lldb/lldb-enumerations.h
index 2fe5b2b4ef5..24ff7918c1b 100644
--- a/lldb/include/lldb/lldb-enumerations.h
+++ b/lldb/include/lldb/lldb-enumerations.h
@@ -157,13 +157,16 @@ namespace lldb {
 
     //----------------------------------------------------------------------
     // Register numbering types
+    // See RegisterContext::ConvertRegisterKindToRegisterNumber to convert
+    // any of these to the lldb internal register numbering scheme 
+    // (eRegisterKindLLDB).
     //----------------------------------------------------------------------
     typedef enum RegisterKind
     {
         eRegisterKindGCC = 0,    // the register numbers seen in eh_frame
         eRegisterKindDWARF,      // the register numbers seen DWARF
         eRegisterKindGeneric,    // insn ptr reg, stack ptr reg, etc not specific to any particular target
-        eRegisterKindGDB,        // the register numbers gdb uses (matches stabs numbers?)
+        eRegisterKindGDB,        // the register numbers gdb uses (matches stabs numbers)
         eRegisterKindLLDB,       // lldb's internal register numbers
         kNumRegisterKinds
     } RegisterKind;