contrib/llvm/tools/lldb/include/lldb/Expression/DWARFExpression.h

   1 //===-- DWARFExpression.h ---------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef liblldb_DWARFExpression_h_
  11 #define liblldb_DWARFExpression_h_
  12
  13 #include "lldb/lldb-private.h"
  14 #include "lldb/Core/Address.h"
  15 #include "lldb/Core/DataExtractor.h"
  16 #include "lldb/Core/Error.h"
  17 #include "lldb/Core/Scalar.h"
  18
  19 class DWARFCompileUnit;
  20
  21 namespace lldb_private {
  22
  23 class ClangExpressionDeclMap;
  24 class ClangExpressionVariable;
  25 class ClangExpressionVariableList;
  26
  27
  28 //----------------------------------------------------------------------
  29 /// @class DWARFExpression DWARFExpression.h "lldb/Expression/DWARFExpression.h"
  30 /// @brief Encapsulates a DWARF location expression and interprets it.
  31 ///
  32 /// DWARF location expressions are used in two ways by LLDB.  The first
  33 /// use is to find entities specified in the debug information, since
  34 /// their locations are specified in precisely this language.  The second
  35 /// is to interpret expressions without having to run the target in cases
  36 /// where the overhead from copying JIT-compiled code into the target is
  37 /// too high or where the target cannot be run.  This class encapsulates
  38 /// a single DWARF location expression or a location list and interprets
  39 /// it.
  40 //----------------------------------------------------------------------
  41 class DWARFExpression
  42 {
  43 public:
  44     enum LocationListFormat : uint8_t
  45     {
  46         NonLocationList,        // Not a location list
  47         RegularLocationList,    // Location list format used in non-split dwarf files
  48         SplitDwarfLocationList, // Location list format used in split dwarf files
  49     };
  50
  51     //------------------------------------------------------------------
  52     /// Constructor
  53     //------------------------------------------------------------------
  54     explicit DWARFExpression(DWARFCompileUnit* dwarf_cu);
  55
  56     //------------------------------------------------------------------
  57     /// Constructor
  58     ///
  59     /// @param[in] data
  60     ///     A data extractor configured to read the DWARF location expression's
  61     ///     bytecode.
  62     ///
  63     /// @param[in] data_offset
  64     ///     The offset of the location expression in the extractor.
  65     ///
  66     /// @param[in] data_length
  67     ///     The byte length of the location expression.
  68     //------------------------------------------------------------------
  69     DWARFExpression(lldb::ModuleSP module,
  70                     const DataExtractor& data,
  71                     DWARFCompileUnit* dwarf_cu,
  72                     lldb::offset_t data_offset,
  73                     lldb::offset_t data_length);
  74
  75     //------------------------------------------------------------------
  76     /// Copy constructor
  77     //------------------------------------------------------------------
  78     DWARFExpression(const DWARFExpression& rhs);
  79
  80     //------------------------------------------------------------------
  81     /// Destructor
  82     //------------------------------------------------------------------
  83     virtual
  84     ~DWARFExpression();
  85
  86     //------------------------------------------------------------------
  87     /// Print the description of the expression to a stream
  88     ///
  89     /// @param[in] s
  90     ///     The stream to print to.
  91     ///
  92     /// @param[in] level
  93     ///     The level of verbosity to use.
  94     ///
  95     /// @param[in] location_list_base_addr
  96     ///     If this is a location list based expression, this is the
  97     ///     address of the object that owns it. NOTE: this value is
  98     ///     different from the DWARF version of the location list base
  99     ///     address which is compile unit relative. This base address
 100     ///     is the address of the object that owns the location list.
 101     ///
 102     /// @param[in] abi
 103     ///     An optional ABI plug-in that can be used to resolve register
 104     ///     names.
 105     //------------------------------------------------------------------
 106     void
 107     GetDescription (Stream *s,
 108                     lldb::DescriptionLevel level,
 109                     lldb::addr_t location_list_base_addr,
 110                     ABI *abi) const;
 111
 112     //------------------------------------------------------------------
 113     /// Return true if the location expression contains data
 114     //------------------------------------------------------------------
 115     bool
 116     IsValid() const;
 117
 118     //------------------------------------------------------------------
 119     /// Return true if a location list was provided
 120     //------------------------------------------------------------------
 121     bool
 122     IsLocationList() const;
 123
 124     //------------------------------------------------------------------
 125     /// Search for a load address in the location list
 126     ///
 127     /// @param[in] process
 128     ///     The process to use when resolving the load address
 129     ///
 130     /// @param[in] addr
 131     ///     The address to resolve
 132     ///
 133     /// @return
 134     ///     True if IsLocationList() is true and the address was found;
 135     ///     false otherwise.
 136     //------------------------------------------------------------------
 137 //    bool
 138 //    LocationListContainsLoadAddress (Process* process, const Address &addr) const;
 139 //
 140     bool
 141     LocationListContainsAddress (lldb::addr_t loclist_base_addr, lldb::addr_t addr) const;
 142
 143     //------------------------------------------------------------------
 144     /// If a location is not a location list, return true if the location
 145     /// contains a DW_OP_addr () opcode in the stream that matches \a
 146     /// file_addr. If file_addr is LLDB_INVALID_ADDRESS, the this
 147     /// function will return true if the variable there is any DW_OP_addr
 148     /// in a location that (yet still is NOT a location list). This helps
 149     /// us detect if a variable is a global or static variable since
 150     /// there is no other indication from DWARF debug info.
 151     ///
 152     /// @param[in] op_addr_idx
 153     ///     The DW_OP_addr index to retrieve in case there is more than
 154     ///     one DW_OP_addr opcode in the location byte stream.
 155     ///
 156     /// @param[out] error
 157     ///     If the location stream contains unknown DW_OP opcodes or the
 158     ///     data is missing, \a error will be set to \b true.
 159     ///
 160     /// @return
 161     ///     LLDB_INVALID_ADDRESS if the location doesn't contain a
 162     ///     DW_OP_addr for \a op_addr_idx, otherwise a valid file address
 163     //------------------------------------------------------------------
 164     lldb::addr_t
 165     GetLocation_DW_OP_addr (uint32_t op_addr_idx, bool &error) const;
 166
 167     bool
 168     Update_DW_OP_addr (lldb::addr_t file_addr);
 169
 170     //------------------------------------------------------------------
 171     /// Make the expression parser read its location information from a
 172     /// given data source.  Does not change the offset and length
 173     ///
 174     /// @param[in] data
 175     ///     A data extractor configured to read the DWARF location expression's
 176     ///     bytecode.
 177     //------------------------------------------------------------------
 178     void
 179     SetOpcodeData(const DataExtractor& data);
 180
 181     //------------------------------------------------------------------
 182     /// Make the expression parser read its location information from a
 183     /// given data source
 184     ///
 185     /// @param[in] module_sp
 186     ///     The module that defines the DWARF expression.
 187     ///
 188     /// @param[in] data
 189     ///     A data extractor configured to read the DWARF location expression's
 190     ///     bytecode.
 191     ///
 192     /// @param[in] data_offset
 193     ///     The offset of the location expression in the extractor.
 194     ///
 195     /// @param[in] data_length
 196     ///     The byte length of the location expression.
 197     //------------------------------------------------------------------
 198     void
 199     SetOpcodeData(lldb::ModuleSP module_sp, const DataExtractor& data, lldb::offset_t data_offset, lldb::offset_t data_length);
 200
 201     //------------------------------------------------------------------
 202     /// Copy the DWARF location expression into a local buffer.
 203     ///
 204     /// It is a good idea to copy the data so we don't keep the entire
 205     /// object file worth of data around just for a few bytes of location
 206     /// expression. LLDB typically will mmap the entire contents of debug
 207     /// information files, and if we use SetOpcodeData, it will get a
 208     /// shared reference to all of this data for the and cause the object
 209     /// file to have to stay around. Even worse, a very very large ".a"
 210     /// that contains one or more .o files could end up being referenced.
 211     /// Location lists are typically small so even though we are copying
 212     /// the data, it shouldn't amount to that much for the variables we
 213     /// end up parsing.
 214     ///
 215     /// @param[in] module_sp
 216     ///     The module that defines the DWARF expression.
 217     ///
 218     /// @param[in] data
 219     ///     A data extractor configured to read and copy the DWARF
 220     ///     location expression's bytecode.
 221     ///
 222     /// @param[in] data_offset
 223     ///     The offset of the location expression in the extractor.
 224     ///
 225     /// @param[in] data_length
 226     ///     The byte length of the location expression.
 227     //------------------------------------------------------------------
 228     void
 229     CopyOpcodeData (lldb::ModuleSP module_sp,
 230                     const DataExtractor& data,
 231                     lldb::offset_t data_offset,
 232                     lldb::offset_t data_length);
 233
 234     void
 235     CopyOpcodeData (const void *data,
 236                     lldb::offset_t data_length,
 237                     lldb::ByteOrder byte_order,
 238                     uint8_t addr_byte_size);
 239
 240     void
 241     CopyOpcodeData (uint64_t const_value,
 242                     lldb::offset_t const_value_byte_size,
 243                     uint8_t addr_byte_size);
 244
 245
 246     //------------------------------------------------------------------
 247     /// Tells the expression that it refers to a location list.
 248     ///
 249     /// @param[in] slide
 250     ///     This value should be a slide that is applied to any values
 251     ///     in the location list data so the values become zero based
 252     ///     offsets into the object that owns the location list. We need
 253     ///     to make location lists relative to the objects that own them
 254     ///     so we can relink addresses on the fly.
 255     //------------------------------------------------------------------
 256     void
 257     SetLocationListSlide (lldb::addr_t slide);
 258
 259     //------------------------------------------------------------------
 260     /// Return the call-frame-info style register kind
 261     //------------------------------------------------------------------
 262     int
 263     GetRegisterKind ();
 264
 265     //------------------------------------------------------------------
 266     /// Set the call-frame-info style register kind
 267     ///
 268     /// @param[in] reg_kind
 269     ///     The register kind.
 270     //------------------------------------------------------------------
 271     void
 272     SetRegisterKind (lldb::RegisterKind reg_kind);
 273
 274     //------------------------------------------------------------------
 275     /// Wrapper for the static evaluate function that accepts an
 276     /// ExecutionContextScope instead of an ExecutionContext and uses
 277     /// member variables to populate many operands
 278     //------------------------------------------------------------------
 279     bool
 280     Evaluate (ExecutionContextScope *exe_scope,
 281               ClangExpressionVariableList *expr_locals,
 282               ClangExpressionDeclMap *decl_map,
 283               lldb::addr_t loclist_base_load_addr,
 284               const Value* initial_value_ptr,
 285               Value& result,
 286               Error *error_ptr) const;
 287
 288     //------------------------------------------------------------------
 289     /// Wrapper for the static evaluate function that uses member
 290     /// variables to populate many operands
 291     //------------------------------------------------------------------
 292     bool
 293     Evaluate (ExecutionContext *exe_ctx,
 294               ClangExpressionVariableList *expr_locals,
 295               ClangExpressionDeclMap *decl_map,
 296               RegisterContext *reg_ctx,
 297               lldb::addr_t loclist_base_load_addr,
 298               const Value* initial_value_ptr,
 299               Value& result,
 300               Error *error_ptr) const;
 301
 302     //------------------------------------------------------------------
 303     /// Evaluate a DWARF location expression in a particular context
 304     ///
 305     /// @param[in] exe_ctx
 306     ///     The execution context in which to evaluate the location
 307     ///     expression.  The location expression may access the target's
 308     ///     memory, especially if it comes from the expression parser.
 309     ///
 310     /// @param[in] opcode_ctx
 311     ///     The module which defined the expression.
 312     ///
 313     /// @param[in] opcodes
 314     ///     This is a static method so the opcodes need to be provided
 315     ///     explicitly.
 316     ///
 317     /// @param[in] expr_locals
 318     ///     If the location expression was produced by the expression parser,
 319     ///     the list of local variables referenced by the DWARF expression.
 320     ///     This list should already have been populated during parsing;
 321     ///     the DWARF expression refers to variables by index.  Can be NULL if
 322     ///     the location expression uses no locals.
 323     ///
 324     /// @param[in] decl_map
 325     ///     If the location expression was produced by the expression parser,
 326     ///     the list of external variables referenced by the location
 327     ///     expression.  Can be NULL if the location expression uses no
 328     ///     external variables.
 329     ///
 330     ///  @param[in] reg_ctx
 331     ///     An optional parameter which provides a RegisterContext for use
 332     ///     when evaluating the expression (i.e. for fetching register values).
 333     ///     Normally this will come from the ExecutionContext's StackFrame but
 334     ///     in the case where an expression needs to be evaluated while building
 335     ///     the stack frame list, this short-cut is available.
 336     ///
 337     /// @param[in] offset
 338     ///     The offset of the location expression in the data extractor.
 339     ///
 340     /// @param[in] length
 341     ///     The length in bytes of the location expression.
 342     ///
 343     /// @param[in] reg_set
 344     ///     The call-frame-info style register kind.
 345     ///
 346     /// @param[in] initial_value_ptr
 347     ///     A value to put on top of the interpreter stack before evaluating
 348     ///     the expression, if the expression is parametrized.  Can be NULL.
 349     ///
 350     /// @param[in] result
 351     ///     A value into which the result of evaluating the expression is
 352     ///     to be placed.
 353     ///
 354     /// @param[in] error_ptr
 355     ///     If non-NULL, used to report errors in expression evaluation.
 356     ///
 357     /// @return
 358     ///     True on success; false otherwise.  If error_ptr is non-NULL,
 359     ///     details of the failure are provided through it.
 360     //------------------------------------------------------------------
 361     static bool
 362     Evaluate (ExecutionContext *exe_ctx,
 363               ClangExpressionVariableList *expr_locals,
 364               ClangExpressionDeclMap *decl_map,
 365               RegisterContext *reg_ctx,
 366               lldb::ModuleSP opcode_ctx,
 367               const DataExtractor& opcodes,
 368               DWARFCompileUnit* dwarf_cu,
 369               const lldb::offset_t offset,
 370               const lldb::offset_t length,
 371               const lldb::RegisterKind reg_set,
 372               const Value* initial_value_ptr,
 373               Value& result,
 374               Error *error_ptr);
 375
 376     //------------------------------------------------------------------
 377     /// Loads a ClangExpressionVariableList into the object
 378     ///
 379     /// @param[in] locals
 380     ///     If non-NULL, the list of locals used by this expression.
 381     ///     See Evaluate().
 382     //------------------------------------------------------------------
 383     void
 384     SetExpressionLocalVariableList (ClangExpressionVariableList *locals);
 385
 386     //------------------------------------------------------------------
 387     /// Loads a ClangExpressionDeclMap into the object
 388     ///
 389     /// @param[in] locals
 390     ///     If non-NULL, the list of external variables used by this
 391     ///     expression.  See Evaluate().
 392     //------------------------------------------------------------------
 393     void
 394     SetExpressionDeclMap (ClangExpressionDeclMap *decl_map);
 395
 396     bool
 397     GetExpressionData (DataExtractor &data) const
 398     {
 399         data = m_data;
 400         return data.GetByteSize() > 0;
 401     }
 402
 403     bool
 404     DumpLocationForAddress (Stream *s,
 405                             lldb::DescriptionLevel level,
 406                             lldb::addr_t loclist_base_load_addr,
 407                             lldb::addr_t address,
 408                             ABI *abi);
 409
 410     static size_t
 411     LocationListSize(const DWARFCompileUnit* dwarf_cu,
 412                      const DataExtractor& debug_loc_data,
 413                      lldb::offset_t offset);
 414
 415     static bool
 416     PrintDWARFExpression(Stream &s,
 417                          const DataExtractor& data,
 418                          int address_size,
 419                          int dwarf_ref_size,
 420                          bool location_expression);
 421
 422     static void
 423     PrintDWARFLocationList(Stream &s,
 424                            const DWARFCompileUnit* cu,
 425                            const DataExtractor& debug_loc_data,
 426                            lldb::offset_t offset);
 427
 428 protected:
 429     //------------------------------------------------------------------
 430     /// Pretty-prints the location expression to a stream
 431     ///
 432     /// @param[in] stream
 433     ///     The stream to use for pretty-printing.
 434     ///
 435     /// @param[in] offset
 436     ///     The offset into the data buffer of the opcodes to be printed.
 437     ///
 438     /// @param[in] length
 439     ///     The length in bytes of the opcodes to be printed.
 440     ///
 441     /// @param[in] level
 442     ///     The level of detail to use in pretty-printing.
 443     ///
 444     /// @param[in] abi
 445     ///     An optional ABI plug-in that can be used to resolve register
 446     ///     names.
 447     //------------------------------------------------------------------
 448     void
 449     DumpLocation(Stream *s,
 450                  lldb::offset_t offset,
 451                  lldb::offset_t length,
 452                  lldb::DescriptionLevel level,
 453                  ABI *abi) const;
 454
 455     bool
 456     GetLocation (lldb::addr_t base_addr,
 457                  lldb::addr_t pc,
 458                  lldb::offset_t &offset,
 459                  lldb::offset_t &len);
 460
 461     static bool
 462     AddressRangeForLocationListEntry(const DWARFCompileUnit* dwarf_cu,
 463                                      const DataExtractor& debug_loc_data,
 464                                      lldb::offset_t* offset_ptr,
 465                                      lldb::addr_t& low_pc,
 466                                      lldb::addr_t& high_pc);
 467
 468     //------------------------------------------------------------------
 469     /// Classes that inherit from DWARFExpression can see and modify these
 470     //------------------------------------------------------------------
 471
 472     lldb::ModuleWP m_module_wp;                 ///< Module which defined this expression.
 473     DataExtractor m_data;                       ///< A data extractor capable of reading opcode bytes
 474     DWARFCompileUnit* m_dwarf_cu;               ///< The DWARF compile unit this expression belongs to. It is used
 475                                                 ///< to evaluate values indexing into the .debug_addr section (e.g.
 476                                                 ///< DW_OP_GNU_addr_index, DW_OP_GNU_const_index)
 477     lldb::RegisterKind m_reg_kind;              ///< One of the defines that starts with LLDB_REGKIND_
 478     lldb::addr_t m_loclist_slide;               ///< A value used to slide the location list offsets so that
 479                                                 ///< they are relative to the object that owns the location list
 480                                                 ///< (the function for frame base and variable location lists)
 481 };
 482
 483 } // namespace lldb_private
 484
 485 #endif  // liblldb_DWARFExpression_h_