Documented DWARFExpression.

llvm-svn: 111276

1 files changed, 212 insertions, 13 deletions

diff --git a/lldb/include/lldb/Expression/DWARFExpression.h b/lldb/include/lldb/Expression/DWARFExpression.h
index 072697659fa..fb1f3b5ae7b 100644
--- a/lldb/include/lldb/Expression/DWARFExpression.h
+++ b/lldb/include/lldb/Expression/DWARFExpression.h
@@ -25,56 +25,165 @@ namespace lldb_private {
 class ClangExpressionDeclMap;
 
 //----------------------------------------------------------------------
-// A class designed to evaluate the DWARF expression opcodes. We will
-// likely augment its abilities to handle features not supported by
-// the DWARF expression engine.
+/// @class DWARFExpression DWARFExpression.h "lldb/Expression/DWARFExpression.h"
+/// @brief Encapsulates a DWARF location expression and interprets it.
+///
+/// DWARF location expressions are used in two ways by LLDB.  The first 
+/// use is to find entities specified in the debug information, since
+/// their locations are specified in precisely this language.  The second
+/// is to interpret expressions without having to run the target in cases
+/// where the overhead from copying JIT-compiled code into the target is
+/// too high or where the target cannot be run.  This class encapsulates
+/// a single DWARF location expression or a location list and interprets
+/// it.
 //----------------------------------------------------------------------
 class DWARFExpression
 {
 public:
-
     //------------------------------------------------------------------
-    // Constructors and Destructors
+    /// Constructor
     //------------------------------------------------------------------
     DWARFExpression();
 
+    //------------------------------------------------------------------
+    /// Constructor
+    ///
+    /// @param[in] data
+    ///     A data extractor configured to read the DWARF location expression's
+    ///     bytecode.
+    ///
+    /// @param[in] data_offset
+    ///     The offset of the location expression in the extractor.
+    ///
+    /// @param[in] data_length
+    ///     The byte length of the location expression.
+    ///
+    /// @param[in] loclist_base_addr_ptr
+    ///     If non-NULL, the address of the location list in the target 
+    ///     process's .debug_loc section.
+    //------------------------------------------------------------------
     DWARFExpression(const DataExtractor& data,
                     uint32_t data_offset,
                     uint32_t data_length,
                     const Address* loclist_base_addr_ptr);
 
+    //------------------------------------------------------------------
+    /// Copy constructor
+    //------------------------------------------------------------------
     DWARFExpression(const DWARFExpression& rhs);
 
+    //------------------------------------------------------------------
+    /// Destructor
+    //------------------------------------------------------------------
     virtual
     ~DWARFExpression();
 
+    //------------------------------------------------------------------
+    /// Print the description of the expression to a stream
+    ///
+    /// @param[in] s
+    ///     The stream to print to.
+    ///
+    /// @param[in] level
+    ///     The level of verbosity to use.
+    //------------------------------------------------------------------
     void
     GetDescription (Stream *s, lldb::DescriptionLevel level) const;
 
+    //------------------------------------------------------------------
+    /// Return true if the location expression contains data
+    //------------------------------------------------------------------
     bool
     IsValid() const;
 
+    //------------------------------------------------------------------
+    /// Return true if a location list was provided
+    //------------------------------------------------------------------
     bool
     IsLocationList() const;
 
+    //------------------------------------------------------------------
+    /// Search for a load address in the location list
+    ///
+    /// @param[in] process
+    ///     The process to use when resolving the load address
+    ///
+    /// @param[in] addr
+    ///     The address to resolve
+    ///
+    /// @return
+    ///     True if IsLocationList() is true and the address was found;
+    ///     false otherwise.
+    //------------------------------------------------------------------
     bool
     LocationListContainsLoadAddress (Process* process, const Address &addr) const;
 
+    //------------------------------------------------------------------
+    /// Make the expression parser read its location information from a
+    /// given data source.  Does not change the offset and length
+    ///
+    /// @param[in] data
+    ///     A data extractor configured to read the DWARF location expression's
+    ///     bytecode.
+    ///
+    /// @param[in] loclist_base_addr_ptr
+    ///     If non-NULL, the address of the location list in the target 
+    ///     process's .debug_loc section.
+    //------------------------------------------------------------------
     void
     SetOpcodeData(const DataExtractor& data, const Address* loclist_base_addr_ptr);
 
+    //------------------------------------------------------------------
+    /// Make the expression parser read its location information from a
+    /// given data source
+    ///
+    /// @param[in] data
+    ///     A data extractor configured to read the DWARF location expression's
+    ///     bytecode.
+    ///
+    /// @param[in] data_offset
+    ///     The offset of the location expression in the extractor.
+    ///
+    /// @param[in] data_length
+    ///     The byte length of the location expression.
+    ///
+    /// @param[in] loclist_base_addr_ptr
+    ///     If non-NULL, the address of the location list in the target 
+    ///     process's .debug_loc section.
+    //------------------------------------------------------------------
     void
     SetOpcodeData(const DataExtractor& data, uint32_t data_offset, uint32_t data_length, const Address* loclist_base_addr_ptr);
 
+    //------------------------------------------------------------------
+    /// Make the expression parser refer to a location list
+    ///
+    /// @param[in] base_addr
+    ///     The address of the location list in the target process's .debug_loc
+    ///     section.
+    //------------------------------------------------------------------
     void
     SetLocationListBaseAddress(Address& base_addr);
 
+    //------------------------------------------------------------------
+    /// Return the call-frame-info style register kind
+    //------------------------------------------------------------------
     int
     GetRegisterKind ();
 
+    //------------------------------------------------------------------
+    /// Set the call-frame-info style register kind
+    ///
+    /// @param[in] reg_kind
+    ///     The register kind.
+    //------------------------------------------------------------------
     void
     SetRegisterKind (int reg_kind);
 
+    //------------------------------------------------------------------
+    /// Wrapper for the static evaluate function that accepts an
+    /// ExecutionContextScope instead of an ExecutionContext and uses
+    /// member variables to populate many operands
+    //------------------------------------------------------------------
     bool
     Evaluate (ExecutionContextScope *exe_scope,
               clang::ASTContext *ast_context,
@@ -82,6 +191,10 @@ public:
               Value& result,
               Error *error_ptr) const;
 
+    //------------------------------------------------------------------
+    /// Wrapper for the static evaluate function that uses member 
+    /// variables to populate many operands
+    //------------------------------------------------------------------
     bool
     Evaluate (ExecutionContext *exe_ctx,
               clang::ASTContext *ast_context,
@@ -89,6 +202,58 @@ public:
               Value& result,
               Error *error_ptr) const;
 
+    //------------------------------------------------------------------
+    /// Evaluate a DWARF location expression in a particular context
+    ///
+    /// @param[in] exe_ctx
+    ///     The execution context in which to evaluate the location
+    ///     expression.  The location expression may access the target's
+    ///     memory, especially if it comes from the expression parser.
+    ///
+    /// @param[in] ast_context
+    ///     The context in which to interpret types.
+    ///
+    /// @param[in] opcodes
+    ///     This is a static method so the opcodes need to be provided
+    ///     explicitly.
+    ///
+    /// @param[in] expr_locals
+    ///     If the location expression was produced by the expression parser,
+    ///     the list of local variables referenced by the DWARF expression.
+    ///     This list should already have been populated during parsing;
+    ///     the DWARF expression refers to variables by index.  Can be NULL if
+    ///     the location expression uses no locals.
+    ///
+    /// @param[in] decl_map
+    ///     If the location expression was produced by the expression parser,
+    ///     the list of external variables referenced by the location 
+    ///     expression.  Can be NULL if the location expression uses no
+    ///     external variables.
+    ///
+    /// @param[in] offset
+    ///     The offset of the location expression in the data extractor.
+    ///
+    /// @param[in] length
+    ///     The length in bytes of the location expression.
+    ///
+    /// @param[in] reg_set
+    ///     The call-frame-info style register kind.
+    ///
+    /// @param[in] initial_value_ptr
+    ///     A value to put on top of the interpreter stack before evaluating
+    ///     the expression, if the expression is parametrized.  Can be NULL.
+    ///
+    /// @param[in] result
+    ///     A value into which the result of evaluating the expression is
+    ///     to be placed.
+    ///
+    /// @param[in] error_ptr
+    ///     If non-NULL, used to report errors in expression evaluation.
+    ///
+    /// @return
+    ///     True on success; false otherwise.  If error_ptr is non-NULL,
+    ///     details of the failure are provided through it.
+    //------------------------------------------------------------------
     static bool
     Evaluate (ExecutionContext *exe_ctx,
               clang::ASTContext *ast_context,
@@ -102,23 +267,57 @@ public:
               Value& result,
               Error *error_ptr);
 
+    //------------------------------------------------------------------
+    /// Loads a ClangExpressionVariableList into the object
+    ///
+    /// @param[in] locals
+    ///     If non-NULL, the list of locals used by this expression.
+    ///     See Evaluate().
+    //------------------------------------------------------------------
     void
     SetExpressionLocalVariableList (ClangExpressionVariableList *locals);
     
+    //------------------------------------------------------------------
+    /// Loads a ClangExpressionDeclMap into the object
+    ///
+    /// @param[in] locals
+    ///     If non-NULL, the list of external variables used by this 
+    ///     expression.  See Evaluate().
+    //------------------------------------------------------------------
     void
     SetExpressionDeclMap (ClangExpressionDeclMap *decl_map);
 
 protected:
-
-    void DumpLocation(Stream *s, uint32_t offset, uint32_t length, lldb::DescriptionLevel level) const;
     //------------------------------------------------------------------
-    // Classes that inherit from DWARFExpression can see and modify these
+    /// Pretty-prints the location expression to a stream
+    ///
+    /// @param[in] stream
+    ///     The stream to use for pretty-printing.
+    ///
+    /// @param[in] offset
+    ///     The offset into the data buffer of the opcodes to be printed.
+    ///
+    /// @param[in] length
+    ///     The length in bytes of the opcodes to be printed.
+    ///
+    /// @param[in] level
+    ///     The level of detail to use in pretty-printing.
     //------------------------------------------------------------------
-    DataExtractor   m_data;
-    int m_reg_kind; // One of the defines that starts with LLDB_REGKIND_
-    Address m_loclist_base_addr; // Base address needed for location lists
-    ClangExpressionVariableList *m_expr_locals;
-    ClangExpressionDeclMap *m_decl_map;
+    void
+    DumpLocation(Stream *s, 
+                 uint32_t offset, 
+                 uint32_t length, 
+                 lldb::DescriptionLevel level) const;
+    
+    //------------------------------------------------------------------
+    /// Classes that inherit from DWARFExpression can see and modify these
+    //------------------------------------------------------------------
+    
+    DataExtractor m_data;                       ///< A data extractor capable of reading opcode bytes
+    int m_reg_kind;                             ///< One of the defines that starts with LLDB_REGKIND_
+    Address m_loclist_base_addr;                ///< Base address needed for location lists
+    ClangExpressionVariableList *m_expr_locals; ///< The locals used by this expression.  See Evaluate()
+    ClangExpressionDeclMap *m_decl_map;         ///< The external variables used by this expression.  See Evaluate()
 };
 
 } // namespace lldb_private