SymbolContext.h revision b3a1a2bba41281ba56a99fe64887a8a04760784c
1//===-- SymbolContext.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 11#ifndef liblldb_SymbolContext_h_ 12#define liblldb_SymbolContext_h_ 13 14#include <vector> 15 16#include "lldb/lldb-private.h" 17#include "lldb/Core/Address.h" 18#include "lldb/Core/Mangled.h" 19#include "lldb/Symbol/ClangASTType.h" 20#include "lldb/Symbol/LineEntry.h" 21 22namespace lldb_private { 23 24class SymbolContextScope; 25//---------------------------------------------------------------------- 26/// @class SymbolContext SymbolContext.h "lldb/Symbol/SymbolContext.h" 27/// @brief Defines a symbol context baton that can be handed other debug 28/// core functions. 29/// 30/// Many debugger functions require a context when doing lookups. This 31/// class provides a common structure that can be used as the result 32/// of a query that can contain a single result. Examples of such 33/// queries include 34/// @li Looking up a load address. 35//---------------------------------------------------------------------- 36class SymbolContext 37{ 38public: 39 40 //------------------------------------------------------------------ 41 /// Default constructor. 42 /// 43 /// Initialize all pointer members to NULL and all struct members 44 /// to their default state. 45 //------------------------------------------------------------------ 46 SymbolContext (); 47 48 //------------------------------------------------------------------ 49 /// Construct with an object that knows how to reconstruct its 50 /// symbol context. 51 /// 52 /// @param[in] sc_scope 53 /// A symbol context scope object that knows how to reconstruct 54 /// it's context. 55 //------------------------------------------------------------------ 56 explicit 57 SymbolContext (SymbolContextScope *sc_scope); 58 59 //------------------------------------------------------------------ 60 /// Construct with module, and optional compile unit, function, 61 /// block, line table, line entry and symbol. 62 /// 63 /// Initialize all pointer to the specified values. 64 /// 65 /// @param[in] module 66 /// A Module pointer to the module for this context. 67 /// 68 /// @param[in] comp_unit 69 /// A CompileUnit pointer to the compile unit for this context. 70 /// 71 /// @param[in] function 72 /// A Function pointer to the function for this context. 73 /// 74 /// @param[in] block 75 /// A Block pointer to the deepest block for this context. 76 /// 77 /// @param[in] line_entry 78 /// A LineEntry pointer to the line entry for this context. 79 /// 80 /// @param[in] symbol 81 /// A Symbol pointer to the symbol for this context. 82 //------------------------------------------------------------------ 83 explicit 84 SymbolContext (const lldb::TargetSP &target_sp, 85 const lldb::ModuleSP &module_sp, 86 CompileUnit *comp_unit = NULL, 87 Function *function = NULL, 88 Block *block = NULL, 89 LineEntry *line_entry = NULL, 90 Symbol *symbol = NULL); 91 92 // This version sets the target to a NULL TargetSP if you don't know it. 93 explicit 94 SymbolContext (const lldb::ModuleSP &module_sp, 95 CompileUnit *comp_unit = NULL, 96 Function *function = NULL, 97 Block *block = NULL, 98 LineEntry *line_entry = NULL, 99 Symbol *symbol = NULL); 100 101 ~SymbolContext (); 102 //------------------------------------------------------------------ 103 /// Copy constructor 104 /// 105 /// Makes a copy of the another SymbolContext object \a rhs. 106 /// 107 /// @param[in] rhs 108 /// A const SymbolContext object reference to copy. 109 //------------------------------------------------------------------ 110 SymbolContext (const SymbolContext& rhs); 111 112 //------------------------------------------------------------------ 113 /// Assignment operator. 114 /// 115 /// Copies the address value from another SymbolContext object \a 116 /// rhs into \a this object. 117 /// 118 /// @param[in] rhs 119 /// A const SymbolContext object reference to copy. 120 /// 121 /// @return 122 /// A const SymbolContext object reference to \a this. 123 //------------------------------------------------------------------ 124 const SymbolContext& 125 operator= (const SymbolContext& rhs); 126 127 //------------------------------------------------------------------ 128 /// Clear the object's state. 129 /// 130 /// Resets all pointer members to NULL, and clears any class objects 131 /// to their default state. 132 //------------------------------------------------------------------ 133 void 134 Clear (); 135 136 //------------------------------------------------------------------ 137 /// Dump a description of this object to a Stream. 138 /// 139 /// Dump a description of the contents of this object to the 140 /// supplied stream \a s. 141 /// 142 /// @param[in] s 143 /// The stream to which to dump the object descripton. 144 //------------------------------------------------------------------ 145 void 146 Dump (Stream *s, Target *target) const; 147 148 //------------------------------------------------------------------ 149 /// Dump the stop context in this object to a Stream. 150 /// 151 /// Dump the best description of this object to the stream. The 152 /// information displayed depends on the amount and quality of the 153 /// information in this context. If a module, function, file and 154 /// line number are available, they will be dumped. If only a 155 /// module and function or symbol name with offset is available, 156 /// that will be ouput. Else just the address at which the target 157 /// was stopped will be displayed. 158 /// 159 /// @param[in] s 160 /// The stream to which to dump the object descripton. 161 /// 162 /// @param[in] so_addr 163 /// The resolved section offset address. 164 //------------------------------------------------------------------ 165 bool 166 DumpStopContext (Stream *s, 167 ExecutionContextScope *exe_scope, 168 const Address &so_addr, 169 bool show_fullpaths, 170 bool show_module, 171 bool show_inlined_frames) const; 172 173 //------------------------------------------------------------------ 174 /// Get the address range contained within a symbol context. 175 /// 176 /// Address range priority is as follows: 177 /// - line_entry address range if line_entry is valid and eSymbolContextLineEntry is set in \a scope 178 /// - block address range if block is not NULL and eSymbolContextBlock is set in \a scope 179 /// - function address range if function is not NULL and eSymbolContextFunction is set in \a scope 180 /// - symbol address range if symbol is not NULL and eSymbolContextSymbol is set in \a scope 181 /// 182 /// @param[in] scope 183 /// A mask of symbol context bits telling this function which 184 /// address ranges it can use when trying to extract one from 185 /// the valid (non-NULL) symbol context classes. 186 /// 187 /// @param[in] range_idx 188 /// The address range index to grab. Since many functions and 189 /// blocks are not always contiguous, they may have more than 190 /// one address range. 191 /// 192 /// @param[in] use_inline_block_range 193 /// If \a scope has the eSymbolContextBlock bit set, and there 194 /// is a valid block in the symbol context, return the block 195 /// address range for the containing inline function block, not 196 /// the deepest most block. This allows us to extract information 197 /// for the address range of the inlined function block, not 198 /// the deepest lexical block. 199 /// 200 /// @param[out] range 201 /// An address range object that will be filled in if \b true 202 /// is returned. 203 /// 204 /// @return 205 /// \b True if this symbol context contains items that describe 206 /// an address range, \b false otherwise. 207 //------------------------------------------------------------------ 208 bool 209 GetAddressRange (uint32_t scope, 210 uint32_t range_idx, 211 bool use_inline_block_range, 212 AddressRange &range) const; 213 214 215 void 216 GetDescription(Stream *s, 217 lldb::DescriptionLevel level, 218 Target *target) const; 219 220 uint32_t 221 GetResolvedMask () const; 222 223 224 //------------------------------------------------------------------ 225 /// Find a block that defines the function represented by this 226 /// symbol context. 227 /// 228 /// If this symbol context points to a block that is an inlined 229 /// function, or is contained within an inlined function, the block 230 /// that defines the inlined function is returned. 231 /// 232 /// If this symbol context has no block in it, or the block is not 233 /// itself an inlined function block or contained within one, we 234 /// return the top level function block. 235 /// 236 /// This is a handy function to call when you want to get the block 237 /// whose variable list will include the arguments for the function 238 /// that is represented by this symbol context (whether the function 239 /// is an inline function or not). 240 /// 241 /// @return 242 /// The block object pointer that defines the function that is 243 /// represented by this symbol context object, NULL otherwise. 244 //------------------------------------------------------------------ 245 Block * 246 GetFunctionBlock (); 247 248 249 //------------------------------------------------------------------ 250 /// If this symbol context represents a function that is a method, 251 /// return true and provide information about the method. 252 /// 253 /// @param[out] language 254 /// If \b true is returned, the language for the method. 255 /// 256 /// @param[out] is_instance_method 257 /// If \b true is returned, \b true if this is a instance method, 258 /// \b false if this is a static/class function. 259 /// 260 /// @param[out] language_object_name 261 /// If \b true is returned, the name of the artificial variable 262 /// for the language ("this" for C++, "self" for ObjC). 263 /// 264 /// @return 265 /// \b True if this symbol context represents a function that 266 /// is a method of a class, \b false otherwise. 267 //------------------------------------------------------------------ 268 bool 269 GetFunctionMethodInfo (lldb::LanguageType &language, 270 bool &is_instance_method, 271 ConstString &language_object_name); 272 273 //------------------------------------------------------------------ 274 /// Find a name of the innermost function for the symbol context. 275 /// 276 /// For instance, if the symbol context contains an inlined block, 277 /// it will return the inlined function name. 278 /// 279 /// @param[in] prefer_mangled 280 /// if \btrue, then the mangled name will be returned if there 281 /// is one. Otherwise the unmangled name will be returned if it 282 /// is available. 283 /// 284 /// @return 285 /// The name of the function represented by this symbol context. 286 //------------------------------------------------------------------ 287 ConstString 288 GetFunctionName (Mangled::NamePreference preference = Mangled::ePreferDemangled); 289 290 //------------------------------------------------------------------ 291 /// Find the block containing the inlined block that contains this block. 292 /// 293 /// For instance, if the symbol context contains an inlined block, 294 /// it will return the inlined function name. 295 /// 296 /// @param[in] curr_frame_pc 297 /// The address within the block of this object. 298 /// 299 /// @param[out] next_frame_sc 300 /// A new symbol context that does what the title says it does. 301 /// 302 /// @param[out] next_frame_addr 303 /// This is what you should report as the PC in \a next_frame_sc. 304 /// 305 /// @return 306 /// \b true if this SymbolContext specifies a block contained in an 307 /// inlined block. If this returns \b true, \a next_frame_sc and 308 /// \a next_frame_addr will be filled in correctly. 309 //------------------------------------------------------------------ 310 bool 311 GetParentOfInlinedScope (const Address &curr_frame_pc, 312 SymbolContext &next_frame_sc, 313 Address &inlined_frame_addr) const; 314 315 //------------------------------------------------------------------ 316 // Member variables 317 //------------------------------------------------------------------ 318 lldb::TargetSP target_sp; ///< The Target for a given query 319 lldb::ModuleSP module_sp; ///< The Module for a given query 320 CompileUnit * comp_unit; ///< The CompileUnit for a given query 321 Function * function; ///< The Function for a given query 322 Block * block; ///< The Block for a given query 323 LineEntry line_entry; ///< The LineEntry for a given query 324 Symbol * symbol; ///< The Symbol for a given query 325}; 326 327 328class SymbolContextSpecifier 329{ 330public: 331 typedef enum SpecificationType 332 { 333 eNothingSpecified = 0, 334 eModuleSpecified = 1 << 0, 335 eFileSpecified = 1 << 1, 336 eLineStartSpecified = 1 << 2, 337 eLineEndSpecified = 1 << 3, 338 eFunctionSpecified = 1 << 4, 339 eClassOrNamespaceSpecified = 1 << 5, 340 eAddressRangeSpecified = 1 << 6 341 } SpecificationType; 342 343 // This one produces a specifier that matches everything... 344 SymbolContextSpecifier (const lldb::TargetSP& target_sp); 345 346 ~SymbolContextSpecifier(); 347 348 bool 349 AddSpecification (const char *spec_string, SpecificationType type); 350 351 bool 352 AddLineSpecification (uint32_t line_no, SpecificationType type); 353 354 void 355 Clear(); 356 357 bool 358 SymbolContextMatches(SymbolContext &sc); 359 360 bool 361 AddressMatches(lldb::addr_t addr); 362 363 void 364 GetDescription (Stream *s, lldb::DescriptionLevel level) const; 365 366private: 367 lldb::TargetSP m_target_sp; 368 std::string m_module_spec; 369 lldb::ModuleSP m_module_sp; 370 std::auto_ptr<FileSpec> m_file_spec_ap; 371 size_t m_start_line; 372 size_t m_end_line; 373 std::string m_function_spec; 374 std::string m_class_name; 375 std::auto_ptr<AddressRange> m_address_range_ap; 376 uint32_t m_type; // Or'ed bits from SpecificationType 377 378}; 379 380//---------------------------------------------------------------------- 381/// @class SymbolContextList SymbolContext.h "lldb/Symbol/SymbolContext.h" 382/// @brief Defines a list of symbol context objects. 383/// 384/// This class provides a common structure that can be used to contain 385/// the result of a query that can contain a multiple results. Examples 386/// of such queries include: 387/// @li Looking up a function by name. 388/// @li Finding all addressses for a specified file and line number. 389//---------------------------------------------------------------------- 390class SymbolContextList 391{ 392public: 393 //------------------------------------------------------------------ 394 /// Default constructor. 395 /// 396 /// Initialize with an empty list. 397 //------------------------------------------------------------------ 398 SymbolContextList (); 399 400 //------------------------------------------------------------------ 401 /// Destructor. 402 //------------------------------------------------------------------ 403 ~SymbolContextList (); 404 405 //------------------------------------------------------------------ 406 /// Append a new symbol context to the list. 407 /// 408 /// @param[in] sc 409 /// A symbol context to append to the list. 410 //------------------------------------------------------------------ 411 void 412 Append (const SymbolContext& sc); 413 414 void 415 Append (const SymbolContextList& sc_list); 416 417 bool 418 AppendIfUnique (const SymbolContext& sc, 419 bool merge_symbol_into_function); 420 421 uint32_t 422 AppendIfUnique (const SymbolContextList& sc_list, 423 bool merge_symbol_into_function); 424 //------------------------------------------------------------------ 425 /// Clear the object's state. 426 /// 427 /// Clears the symbol context list. 428 //------------------------------------------------------------------ 429 void 430 Clear(); 431 432 //------------------------------------------------------------------ 433 /// Dump a description of this object to a Stream. 434 /// 435 /// Dump a description of the contents of each symbol context in 436 /// the list to the supplied stream \a s. 437 /// 438 /// @param[in] s 439 /// The stream to which to dump the object descripton. 440 //------------------------------------------------------------------ 441 void 442 Dump(Stream *s, Target *target) const; 443 444 //------------------------------------------------------------------ 445 /// Get accessor for a symbol context at index \a idx. 446 /// 447 /// Dump a description of the contents of each symbol context in 448 /// the list to the supplied stream \a s. 449 /// 450 /// @param[in] idx 451 /// The zero based index into the symbol context list. 452 /// 453 /// @param[out] sc 454 /// A reference to the symbol context to fill in. 455 /// 456 /// @return 457 /// Returns \b true if \a idx was a valid index into this 458 /// symbol context list and \a sc was filled in, \b false 459 /// otherwise. 460 //------------------------------------------------------------------ 461 bool 462 GetContextAtIndex(uint32_t idx, SymbolContext& sc) const; 463 464 bool 465 RemoveContextAtIndex (uint32_t idx); 466 //------------------------------------------------------------------ 467 /// Get accessor for a symbol context list size. 468 /// 469 /// @return 470 /// Returns the number of symbol context objects in the list. 471 //------------------------------------------------------------------ 472 uint32_t 473 GetSize() const; 474 475 uint32_t 476 NumLineEntriesWithLine (uint32_t line) const; 477 478 void 479 GetDescription(Stream *s, 480 lldb::DescriptionLevel level, 481 Target *target) const; 482 483protected: 484 typedef std::vector<SymbolContext> collection; ///< The collection type for the list. 485 486 //------------------------------------------------------------------ 487 // Member variables. 488 //------------------------------------------------------------------ 489 collection m_symbol_contexts; ///< The list of symbol contexts. 490}; 491 492bool operator== (const SymbolContext& lhs, const SymbolContext& rhs); 493bool operator!= (const SymbolContext& lhs, const SymbolContext& rhs); 494 495bool operator== (const SymbolContextList& lhs, const SymbolContextList& rhs); 496bool operator!= (const SymbolContextList& lhs, const SymbolContextList& rhs); 497 498} // namespace lldb_private 499 500#endif // liblldb_SymbolContext_h_ 501