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