xref: /external/lldb/include/lldb/Expression/DWARFExpression.h

//===-- DWARFExpression.h ---------------------------------------*- C++ -*-===//
//
//                     The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//

#ifndef liblldb_DWARFExpression_h_
#define liblldb_DWARFExpression_h_

#include "lldb/lldb-private.h"
#include "lldb/Core/ClangForward.h"
#include "lldb/Core/Address.h"
#include "lldb/Core/DataExtractor.h"
#include "lldb/Core/Error.h"
#include "lldb/Core/Scalar.h"

namespace lldb_private {

class ClangExpressionVariable;
class ClangExpressionVariableList;

class ClangExpressionDeclMap;

//----------------------------------------------------------------------
/// @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:
    //------------------------------------------------------------------
    /// 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.
    //------------------------------------------------------------------
    DWARFExpression(const DataExtractor& data,
                    lldb::offset_t data_offset,
                    lldb::offset_t data_length);

    //------------------------------------------------------------------
    /// 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.
    ///
    /// @param[in] location_list_base_addr
    ///     If this is a location list based expression, this is the
    ///     address of the object that owns it. NOTE: this value is
    ///     different from the DWARF version of the location list base
    ///     address which is compile unit relative. This base address
    ///     is the address of the object that owns the location list.
    ///
    /// @param[in] abi
    ///     An optional ABI plug-in that can be used to resolve register
    ///     names.
    //------------------------------------------------------------------
    void
    GetDescription (Stream *s,
                    lldb::DescriptionLevel level,
                    lldb::addr_t location_list_base_addr,
                    ABI *abi) 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;
//
    bool
    LocationListContainsAddress (lldb::addr_t loclist_base_addr, lldb::addr_t addr) const;

    //------------------------------------------------------------------
    /// If a location is not a location list, return true if the location
    /// contains a DW_OP_addr () opcode in the stream that matches \a
    /// file_addr. If file_addr is LLDB_INVALID_ADDRESS, the this
    /// function will return true if the variable there is any DW_OP_addr
    /// in a location that (yet still is NOT a location list). This helps
    /// us detect if a variable is a global or static variable since
    /// there is no other indication from DWARF debug info.
    ///
    /// @param[in] op_addr_idx
    ///     The DW_OP_addr index to retrieve in case there is more than
    ///     one DW_OP_addr opcode in the location byte stream.
    ///
    /// @param[out] error
    ///     If the location stream contains unknown DW_OP opcodes or the
    ///     data is missing, \a error will be set to \b true.
    ///
    /// @return
    ///     LLDB_INVALID_ADDRESS if the location doesn't contain a
    ///     DW_OP_addr for \a op_addr_idx, otherwise a valid file address
    //------------------------------------------------------------------
    lldb::addr_t
    GetLocation_DW_OP_addr (uint32_t op_addr_idx, bool &error) const;

    bool
    Update_DW_OP_addr (lldb::addr_t file_addr);

    //------------------------------------------------------------------
    /// 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.
    //------------------------------------------------------------------
    void
    SetOpcodeData(const DataExtractor& data);

    //------------------------------------------------------------------
    /// 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.
    //------------------------------------------------------------------
    void
    SetOpcodeData(const DataExtractor& data, lldb::offset_t data_offset, lldb::offset_t data_length);

    //------------------------------------------------------------------
    /// Copy the DWARF location expression into a local buffer.
    ///
    /// It is a good idea to copy the data so we don't keep the entire
    /// object file worth of data around just for a few bytes of location
    /// expression. LLDB typically will mmap the entire contents of debug
    /// information files, and if we use SetOpcodeData, it will get a
    /// shared reference to all of this data for the and cause the object
    /// file to have to stay around. Even worse, a very very large ".a"
    /// that contains one or more .o files could end up being referenced.
    /// Location lists are typically small so even though we are copying
    /// the data, it shouldn't amount to that much for the variables we
    /// end up parsing.
    ///
    /// @param[in] data
    ///     A data extractor configured to read and copy 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.
    //------------------------------------------------------------------
    void
    CopyOpcodeData (const DataExtractor& data,
                    lldb::offset_t data_offset,
                    lldb::offset_t data_length);


    //------------------------------------------------------------------
    /// Tells the expression that it refers to a location list.
    ///
    /// @param[in] slide
    ///     This value should be a slide that is applied to any values
    ///     in the location list data so the values become zero based
    ///     offsets into the object that owns the location list. We need
    ///     to make location lists relative to the objects that own them
    ///     so we can relink addresses on the fly.
    //------------------------------------------------------------------
    void
    SetLocationListSlide (lldb::addr_t slide);

    //------------------------------------------------------------------
    /// 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 (lldb::RegisterKind 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,
              ClangExpressionVariableList *expr_locals,
              ClangExpressionDeclMap *decl_map,
              lldb::addr_t loclist_base_load_addr,
              const Value* initial_value_ptr,
              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,
              ClangExpressionVariableList *expr_locals,
              ClangExpressionDeclMap *decl_map,
              RegisterContext *reg_ctx,
              lldb::addr_t loclist_base_load_addr,
              const Value* initial_value_ptr,
              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] 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] reg_ctx
    ///     An optional parameter which provides a RegisterContext for use
    ///     when evaluating the expression (i.e. for fetching register values).
    ///     Normally this will come from the ExecutionContext's StackFrame but
    ///     in the case where an expression needs to be evaluated while building
    ///     the stack frame list, this short-cut is available.
    ///
    /// @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,
              ClangExpressionVariableList *expr_locals,
              ClangExpressionDeclMap *decl_map,
              RegisterContext *reg_ctx,
              const DataExtractor& opcodes,
              const lldb::offset_t offset,
              const lldb::offset_t length,
              const uint32_t reg_set,
              const Value* initial_value_ptr,
              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);

    bool
    GetExpressionData (DataExtractor &data) const
    {
        data = m_data;
        return data.GetByteSize() > 0;
    }

    bool
    DumpLocationForAddress (Stream *s,
                            lldb::DescriptionLevel level,
                            lldb::addr_t loclist_base_load_addr,
                            lldb::addr_t address,
                            ABI *abi);

protected:
    //------------------------------------------------------------------
    /// 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.
    ///
    /// @param[in] abi
    ///     An optional ABI plug-in that can be used to resolve register
    ///     names.
    //------------------------------------------------------------------
    void
    DumpLocation(Stream *s,
                 lldb::offset_t offset,
                 lldb::offset_t length,
                 lldb::DescriptionLevel level,
                 ABI *abi) const;

    bool
    GetLocation (lldb::addr_t base_addr,
                 lldb::addr_t pc,
                 lldb::offset_t &offset,
                 lldb::offset_t &len);

    //------------------------------------------------------------------
    /// Classes that inherit from DWARFExpression can see and modify these
    //------------------------------------------------------------------

    DataExtractor m_data;                       ///< A data extractor capable of reading opcode bytes
    lldb::RegisterKind m_reg_kind;              ///< One of the defines that starts with LLDB_REGKIND_
    lldb::addr_t m_loclist_slide;               ///< A value used to slide the location list offsets so that
                                                ///< they are relative to the object that owns the location list
                                                ///< (the function for frame base and variable location lists)

};

} // namespace lldb_private

#endif  // liblldb_DWARFExpression_h_