contrib/llvm/tools/lldb/include/lldb/Core/Module.h

   1 //===-- Module.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_Module_h_
  11 #define liblldb_Module_h_
  12
  13 #include "lldb/Core/ArchSpec.h"
  14 #include "lldb/Core/UUID.h"
  15 #include "lldb/Host/FileSpec.h"
  16 #include "lldb/Host/Mutex.h"
  17 #include "lldb/Host/TimeValue.h"
  18 #include "lldb/Symbol/ClangASTContext.h"
  19 #include "lldb/Symbol/SymbolContextScope.h"
  20 #include "lldb/Target/PathMappingList.h"
  21
  22 namespace lldb_private {
  23
  24 //----------------------------------------------------------------------
  25 /// @class Module Module.h "lldb/Core/Module.h"
  26 /// @brief A class that describes an executable image and its associated
  27 ///        object and symbol files.
  28 ///
  29 /// The module is designed to be able to select a single slice of an
  30 /// executable image as it would appear on disk and during program
  31 /// execution.
  32 ///
  33 /// Modules control when and if information is parsed according to which
  34 /// accessors are called. For example the object file (ObjectFile)
  35 /// representation will only be parsed if the object file is requested
  36 /// using the Module::GetObjectFile() is called. The debug symbols
  37 /// will only be parsed if the symbol vendor (SymbolVendor) is
  38 /// requested using the Module::GetSymbolVendor() is called.
  39 ///
  40 /// The module will parse more detailed information as more queries are
  41 /// made.
  42 //----------------------------------------------------------------------
  43 class Module :
  44     public std::enable_shared_from_this<Module>,
  45     public SymbolContextScope
  46 {
  47 public:
  48         // Static functions that can track the lifetime of module objects.
  49         // This is handy because we might have Module objects that are in
  50         // shared pointers that aren't in the global module list (from
  51         // ModuleList). If this is the case we need to know about it.
  52     // The modules in the global list maintained by these functions
  53     // can be viewed using the "target modules list" command using the
  54     // "--global" (-g for short).
  55     static size_t
  56     GetNumberAllocatedModules ();
  57
  58     static Module *
  59     GetAllocatedModuleAtIndex (size_t idx);
  60
  61     static Mutex *
  62     GetAllocationModuleCollectionMutex();
  63
  64     //------------------------------------------------------------------
  65     /// Construct with file specification and architecture.
  66     ///
  67     /// Clients that wish to share modules with other targets should
  68     /// use ModuleList::GetSharedModule().
  69     ///
  70     /// @param[in] file_spec
  71     ///     The file specification for the on disk repesentation of
  72     ///     this executable image.
  73     ///
  74     /// @param[in] arch
  75     ///     The architecture to set as the current architecture in
  76     ///     this module.
  77     ///
  78     /// @param[in] object_name
  79     ///     The name of an object in a module used to extract a module
  80     ///     within a module (.a files and modules that contain multiple
  81     ///     architectures).
  82     ///
  83     /// @param[in] object_offset
  84     ///     The offset within an existing module used to extract a
  85     ///     module within a module (.a files and modules that contain
  86     ///     multiple architectures).
  87     //------------------------------------------------------------------
  88     Module (const FileSpec& file_spec,
  89             const ArchSpec& arch,
  90             const ConstString *object_name = NULL,
  91             off_t object_offset = 0,
  92             const TimeValue *object_mod_time_ptr = NULL);
  93
  94     Module (const ModuleSpec &module_spec);
  95     //------------------------------------------------------------------
  96     /// Destructor.
  97     //------------------------------------------------------------------
  98     virtual
  99     ~Module ();
 100
 101     bool
 102     MatchesModuleSpec (const ModuleSpec &module_ref);
 103
 104     //------------------------------------------------------------------
 105     /// Set the load address for all sections in a module to be the
 106     /// file address plus \a slide.
 107     ///
 108     /// Many times a module will be loaded in a target with a constant
 109     /// offset applied to all top level sections. This function can
 110     /// set the load address for all top level sections to be the
 111     /// section file address + offset.
 112     ///
 113     /// @param[in] target
 114     ///     The target in which to apply the section load addresses.
 115     ///
 116     /// @param[in] value
 117     ///     if \a value_is_offset is true, then value is the offset to
 118     ///     apply to all file addresses for all top level sections in
 119     ///     the object file as each section load address is being set.
 120     ///     If \a value_is_offset is false, then "value" is the new
 121     ///     absolute base address for the image.
 122     ///
 123     /// @param[in] value_is_offset
 124     ///     If \b true, then \a value is an offset to apply to each
 125     ///     file address of each top level section.
 126     ///     If \b false, then \a value is the image base address that
 127     ///     will be used to rigidly slide all loadable sections.
 128     ///
 129     /// @param[out] changed
 130     ///     If any section load addresses were changed in \a target,
 131     ///     then \a changed will be set to \b true. Else \a changed
 132     ///     will be set to false. This allows this function to be
 133     ///     called multiple times on the same module for the same
 134     ///     target. If the module hasn't moved, then \a changed will
 135     ///     be false and no module updated notification will need to
 136     ///     be sent out.
 137     ///
 138     /// @return
 139     ///     /b True if any sections were successfully loaded in \a target,
 140     ///     /b false otherwise.
 141     //------------------------------------------------------------------
 142     bool
 143     SetLoadAddress (Target &target,
 144                     lldb::addr_t value,
 145                     bool value_is_offset,
 146                     bool &changed);
 147
 148     //------------------------------------------------------------------
 149     /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
 150     ///
 151     /// @see SymbolContextScope
 152     //------------------------------------------------------------------
 153     virtual void
 154     CalculateSymbolContext (SymbolContext* sc);
 155
 156     virtual lldb::ModuleSP
 157     CalculateSymbolContextModule ();
 158
 159     void
 160     GetDescription (Stream *s,
 161                     lldb::DescriptionLevel level = lldb::eDescriptionLevelFull);
 162
 163     //------------------------------------------------------------------
 164     /// Get the module path and object name.
 165     ///
 166     /// Modules can refer to object files. In this case the specification
 167     /// is simple and would return the path to the file:
 168     ///
 169     ///     "/usr/lib/foo.dylib"
 170     ///
 171     /// Modules can be .o files inside of a BSD archive (.a file). In
 172     /// this case, the object specification will look like:
 173     ///
 174     ///     "/usr/lib/foo.a(bar.o)"
 175     ///
 176     /// There are many places where logging wants to log this fully
 177     /// qualified specification, so we centralize this functionality
 178     /// here.
 179     ///
 180     /// @return
 181     ///     The object path + object name if there is one.
 182     //------------------------------------------------------------------
 183     std::string
 184     GetSpecificationDescription () const;
 185
 186     //------------------------------------------------------------------
 187     /// Dump a description of this object to a Stream.
 188     ///
 189     /// Dump a description of the contents of this object to the
 190     /// supplied stream \a s. The dumped content will be only what has
 191     /// been loaded or parsed up to this point at which this function
 192     /// is called, so this is a good way to see what has been parsed
 193     /// in a module.
 194     ///
 195     /// @param[in] s
 196     ///     The stream to which to dump the object descripton.
 197     //------------------------------------------------------------------
 198     void
 199     Dump (Stream *s);
 200
 201     //------------------------------------------------------------------
 202     /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
 203     ///
 204     /// @see SymbolContextScope
 205     //------------------------------------------------------------------
 206     virtual void
 207     DumpSymbolContext (Stream *s);
 208
 209
 210     //------------------------------------------------------------------
 211     /// Find a symbol in the object file's symbol table.
 212     ///
 213     /// @param[in] name
 214     ///     The name of the symbol that we are looking for.
 215     ///
 216     /// @param[in] symbol_type
 217     ///     If set to eSymbolTypeAny, find a symbol of any type that
 218     ///     has a name that matches \a name. If set to any other valid
 219     ///     SymbolType enumeration value, then search only for
 220     ///     symbols that match \a symbol_type.
 221     ///
 222     /// @return
 223     ///     Returns a valid symbol pointer if a symbol was found,
 224     ///     NULL otherwise.
 225     //------------------------------------------------------------------
 226     const Symbol *
 227     FindFirstSymbolWithNameAndType (const ConstString &name,
 228                                     lldb::SymbolType symbol_type = lldb::eSymbolTypeAny);
 229
 230     size_t
 231     FindSymbolsWithNameAndType (const ConstString &name,
 232                                 lldb::SymbolType symbol_type,
 233                                 SymbolContextList &sc_list);
 234
 235     size_t
 236     FindSymbolsMatchingRegExAndType (const RegularExpression &regex,
 237                                      lldb::SymbolType symbol_type,
 238                                      SymbolContextList &sc_list);
 239
 240     //------------------------------------------------------------------
 241     /// Find a funciton symbols in the object file's symbol table.
 242     ///
 243     /// @param[in] name
 244     ///     The name of the symbol that we are looking for.
 245     ///
 246     /// @param[in] name_type_mask
 247     ///     A mask that has one or more bitwise OR'ed values from the
 248     ///     lldb::FunctionNameType enumeration type that indicate what
 249     ///     kind of names we are looking for.
 250     ///
 251     /// @param[out] sc_list
 252     ///     A list to append any matching symbol contexts to.
 253     ///
 254     /// @return
 255     ///     The number of symbol contexts that were added to \a sc_list
 256     //------------------------------------------------------------------
 257     size_t
 258     FindFunctionSymbols (const ConstString &name,
 259                          uint32_t name_type_mask,
 260                          SymbolContextList& sc_list);
 261
 262     //------------------------------------------------------------------
 263     /// Find compile units by partial or full path.
 264     ///
 265     /// Finds all compile units that match \a path in all of the modules
 266     /// and returns the results in \a sc_list.
 267     ///
 268     /// @param[in] path
 269     ///     The name of the function we are looking for.
 270     ///
 271     /// @param[in] append
 272     ///     If \b true, then append any compile units that were found
 273     ///     to \a sc_list. If \b false, then the \a sc_list is cleared
 274     ///     and the contents of \a sc_list are replaced.
 275     ///
 276     /// @param[out] sc_list
 277     ///     A symbol context list that gets filled in with all of the
 278     ///     matches.
 279     ///
 280     /// @return
 281     ///     The number of matches added to \a sc_list.
 282     //------------------------------------------------------------------
 283     size_t
 284     FindCompileUnits (const FileSpec &path,
 285                       bool append,
 286                       SymbolContextList &sc_list);
 287
 288
 289     //------------------------------------------------------------------
 290     /// Find functions by name.
 291     ///
 292     /// If the function is an inlined function, it will have a block,
 293     /// representing the inlined function, and the function will be the
 294     /// containing function.  If it is not inlined, then the block will
 295     /// be NULL.
 296     ///
 297     /// @param[in] name
 298     ///     The name of the compile unit we are looking for.
 299     ///
 300     /// @param[in] namespace_decl
 301     ///     If valid, a namespace to search in.
 302     ///
 303     /// @param[in] name_type_mask
 304     ///     A bit mask of bits that indicate what kind of names should
 305     ///     be used when doing the lookup. Bits include fully qualified
 306     ///     names, base names, C++ methods, or ObjC selectors.
 307     ///     See FunctionNameType for more details.
 308     ///
 309     /// @param[in] append
 310     ///     If \b true, any matches will be appended to \a sc_list, else
 311     ///     matches replace the contents of \a sc_list.
 312     ///
 313     /// @param[out] sc_list
 314     ///     A symbol context list that gets filled in with all of the
 315     ///     matches.
 316     ///
 317     /// @return
 318     ///     The number of matches added to \a sc_list.
 319     //------------------------------------------------------------------
 320     size_t
 321     FindFunctions (const ConstString &name,
 322                    const ClangNamespaceDecl *namespace_decl,
 323                    uint32_t name_type_mask,
 324                    bool symbols_ok,
 325                    bool inlines_ok,
 326                    bool append,
 327                    SymbolContextList& sc_list);
 328
 329     //------------------------------------------------------------------
 330     /// Find functions by name.
 331     ///
 332     /// If the function is an inlined function, it will have a block,
 333     /// representing the inlined function, and the function will be the
 334     /// containing function.  If it is not inlined, then the block will
 335     /// be NULL.
 336     ///
 337     /// @param[in] regex
 338     ///     A regular expression to use when matching the name.
 339     ///
 340     /// @param[in] append
 341     ///     If \b true, any matches will be appended to \a sc_list, else
 342     ///     matches replace the contents of \a sc_list.
 343     ///
 344     /// @param[out] sc_list
 345     ///     A symbol context list that gets filled in with all of the
 346     ///     matches.
 347     ///
 348     /// @return
 349     ///     The number of matches added to \a sc_list.
 350     //------------------------------------------------------------------
 351     size_t
 352     FindFunctions (const RegularExpression& regex,
 353                    bool symbols_ok,
 354                    bool inlines_ok,
 355                    bool append,
 356                    SymbolContextList& sc_list);
 357
 358     //------------------------------------------------------------------
 359     /// Find addresses by file/line
 360     ///
 361     /// @param[in] target_sp
 362     ///     The target the addresses are desired for.
 363     ///
 364     /// @param[in] file
 365     ///     Source file to locate.
 366     ///
 367     /// @param[in] line
 368     ///     Source line to locate.
 369     ///
 370     /// @param[in] function
 371     ///     Optional filter function. Addresses within this function will be
 372     ///     added to the 'local' list. All others will be added to the 'extern' list.
 373     ///
 374     /// @param[out] output_local
 375     ///     All matching addresses within 'function'
 376     ///
 377     /// @param[out] output_extern
 378     ///     All matching addresses not within 'function'
 379     void FindAddressesForLine (const lldb::TargetSP target_sp,
 380                                const FileSpec &file, uint32_t line,
 381                                Function *function,
 382                                std::vector<Address> &output_local, std::vector<Address> &output_extern);
 383
 384     //------------------------------------------------------------------
 385     /// Find global and static variables by name.
 386     ///
 387     /// @param[in] name
 388     ///     The name of the global or static variable we are looking
 389     ///     for.
 390     ///
 391     /// @param[in] namespace_decl
 392     ///     If valid, a namespace to search in.
 393     ///
 394     /// @param[in] append
 395     ///     If \b true, any matches will be appended to \a
 396     ///     variable_list, else matches replace the contents of
 397     ///     \a variable_list.
 398     ///
 399     /// @param[in] max_matches
 400     ///     Allow the number of matches to be limited to \a
 401     ///     max_matches. Specify UINT32_MAX to get all possible matches.
 402     ///
 403     /// @param[in] variable_list
 404     ///     A list of variables that gets the matches appended to (if
 405     ///     \a append it \b true), or replace (if \a append is \b false).
 406     ///
 407     /// @return
 408     ///     The number of matches added to \a variable_list.
 409     //------------------------------------------------------------------
 410     size_t
 411     FindGlobalVariables (const ConstString &name,
 412                          const ClangNamespaceDecl *namespace_decl,
 413                          bool append,
 414                          size_t max_matches,
 415                          VariableList& variable_list);
 416
 417     //------------------------------------------------------------------
 418     /// Find global and static variables by regular exression.
 419     ///
 420     /// @param[in] regex
 421     ///     A regular expression to use when matching the name.
 422     ///
 423     /// @param[in] append
 424     ///     If \b true, any matches will be appended to \a
 425     ///     variable_list, else matches replace the contents of
 426     ///     \a variable_list.
 427     ///
 428     /// @param[in] max_matches
 429     ///     Allow the number of matches to be limited to \a
 430     ///     max_matches. Specify UINT32_MAX to get all possible matches.
 431     ///
 432     /// @param[in] variable_list
 433     ///     A list of variables that gets the matches appended to (if
 434     ///     \a append it \b true), or replace (if \a append is \b false).
 435     ///
 436     /// @return
 437     ///     The number of matches added to \a variable_list.
 438     //------------------------------------------------------------------
 439     size_t
 440     FindGlobalVariables (const RegularExpression& regex,
 441                          bool append,
 442                          size_t max_matches,
 443                          VariableList& variable_list);
 444
 445     //------------------------------------------------------------------
 446     /// Find types by name.
 447     ///
 448     /// Type lookups in modules go through the SymbolVendor (which will
 449     /// use one or more SymbolFile subclasses). The SymbolFile needs to
 450     /// be able to lookup types by basename and not the fully qualified
 451     /// typename. This allows the type accelerator tables to stay small,
 452     /// even with heavily templatized C++. The type search will then
 453     /// narrow down the search results. If "exact_match" is true, then
 454     /// the type search will only match exact type name matches. If
 455     /// "exact_match" is false, the type will match as long as the base
 456     /// typename matches and as long as any immediate containing
 457     /// namespaces/class scopes that are specified match. So to search
 458     /// for a type "d" in "b::c", the name "b::c::d" can be specified
 459     /// and it will match any class/namespace "b" which contains a
 460     /// class/namespace "c" which contains type "d". We do this to
 461     /// allow users to not always have to specify complete scoping on
 462     /// all expressions, but it also allows for exact matching when
 463     /// required.
 464     ///
 465     /// @param[in] sc
 466     ///     A symbol context that scopes where to extract a type list
 467     ///     from.
 468     ///
 469     /// @param[in] type_name
 470     ///     The name of the type we are looking for that is a fully
 471     ///     or partially qualfieid type name.
 472     ///
 473     /// @param[in] exact_match
 474     ///     If \b true, \a type_name is fully qualifed and must match
 475     ///     exactly. If \b false, \a type_name is a partially qualfied
 476     ///     name where the leading namespaces or classes can be
 477     ///     omitted to make finding types that a user may type
 478     ///     easier.
 479     ///
 480     /// @param[out] type_list
 481     ///     A type list gets populated with any matches.
 482     ///
 483     /// @return
 484     ///     The number of matches added to \a type_list.
 485     //------------------------------------------------------------------
 486     size_t
 487     FindTypes (const SymbolContext& sc,
 488                const ConstString &type_name,
 489                bool exact_match,
 490                size_t max_matches,
 491                TypeList& types);
 492
 493     lldb::TypeSP
 494     FindFirstType (const SymbolContext& sc,
 495                    const ConstString &type_name,
 496                    bool exact_match);
 497
 498     //------------------------------------------------------------------
 499     /// Find types by name that are in a namespace. This function is
 500     /// used by the expression parser when searches need to happen in
 501     /// an exact namespace scope.
 502     ///
 503     /// @param[in] sc
 504     ///     A symbol context that scopes where to extract a type list
 505     ///     from.
 506     ///
 507     /// @param[in] type_name
 508     ///     The name of a type within a namespace that should not include
 509     ///     any qualifying namespaces (just a type basename).
 510     ///
 511     /// @param[in] namespace_decl
 512     ///     The namespace declaration that this type must exist in.
 513     ///
 514     /// @param[out] type_list
 515     ///     A type list gets populated with any matches.
 516     ///
 517     /// @return
 518     ///     The number of matches added to \a type_list.
 519     //------------------------------------------------------------------
 520     size_t
 521     FindTypesInNamespace (const SymbolContext& sc,
 522                           const ConstString &type_name,
 523                           const ClangNamespaceDecl *namespace_decl,
 524                           size_t max_matches,
 525                           TypeList& type_list);
 526
 527     //------------------------------------------------------------------
 528     /// Get const accessor for the module architecture.
 529     ///
 530     /// @return
 531     ///     A const reference to the architecture object.
 532     //------------------------------------------------------------------
 533     const ArchSpec&
 534     GetArchitecture () const;
 535
 536     //------------------------------------------------------------------
 537     /// Get const accessor for the module file specification.
 538     ///
 539     /// This function returns the file for the module on the host system
 540     /// that is running LLDB. This can differ from the path on the
 541     /// platform since we might be doing remote debugging.
 542     ///
 543     /// @return
 544     ///     A const reference to the file specification object.
 545     //------------------------------------------------------------------
 546     const FileSpec &
 547     GetFileSpec () const
 548     {
 549         return m_file;
 550     }
 551
 552     //------------------------------------------------------------------
 553     /// Get accessor for the module platform file specification.
 554     ///
 555     /// Platform file refers to the path of the module as it is known on
 556     /// the remote system on which it is being debugged. For local
 557     /// debugging this is always the same as Module::GetFileSpec(). But
 558     /// remote debugging might mention a file "/usr/lib/liba.dylib"
 559     /// which might be locally downloaded and cached. In this case the
 560     /// platform file could be something like:
 561     /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib"
 562     /// The file could also be cached in a local developer kit directory.
 563     ///
 564     /// @return
 565     ///     A const reference to the file specification object.
 566     //------------------------------------------------------------------
 567     const FileSpec &
 568     GetPlatformFileSpec () const
 569     {
 570         if (m_platform_file)
 571             return m_platform_file;
 572         return m_file;
 573     }
 574
 575     void
 576     SetPlatformFileSpec (const FileSpec &file)
 577     {
 578         m_platform_file = file;
 579     }
 580
 581     const FileSpec &
 582     GetRemoteInstallFileSpec () const
 583     {
 584         return m_remote_install_file;
 585     }
 586
 587     void
 588     SetRemoteInstallFileSpec (const FileSpec &file)
 589     {
 590         m_remote_install_file = file;
 591     }
 592
 593     const FileSpec &
 594     GetSymbolFileFileSpec () const
 595     {
 596         return m_symfile_spec;
 597     }
 598
 599     void
 600     SetSymbolFileFileSpec (const FileSpec &file);
 601
 602     const TimeValue &
 603     GetModificationTime () const
 604     {
 605         return m_mod_time;
 606     }
 607
 608     const TimeValue &
 609     GetObjectModificationTime () const
 610     {
 611         return m_object_mod_time;
 612     }
 613
 614     void
 615     SetObjectModificationTime (const TimeValue &mod_time)
 616     {
 617         m_mod_time = mod_time;
 618     }
 619
 620     //------------------------------------------------------------------
 621     /// Tells whether this module is capable of being the main executable
 622     /// for a process.
 623     ///
 624     /// @return
 625     ///     \b true if it is, \b false otherwise.
 626     //------------------------------------------------------------------
 627     bool
 628     IsExecutable ();
 629
 630     //------------------------------------------------------------------
 631     /// Tells whether this module has been loaded in the target passed in.
 632     /// This call doesn't distinguish between whether the module is loaded
 633     /// by the dynamic loader, or by a "target module add" type call.
 634     ///
 635     /// @param[in] target
 636     ///    The target to check whether this is loaded in.
 637     ///
 638     /// @return
 639     ///     \b true if it is, \b false otherwise.
 640     //------------------------------------------------------------------
 641     bool
 642     IsLoadedInTarget (Target *target);
 643
 644     bool
 645     LoadScriptingResourceInTarget (Target *target,
 646                                    Error& error,
 647                                    Stream* feedback_stream = NULL);
 648
 649     //------------------------------------------------------------------
 650     /// Get the number of compile units for this module.
 651     ///
 652     /// @return
 653     ///     The number of compile units that the symbol vendor plug-in
 654     ///     finds.
 655     //------------------------------------------------------------------
 656     size_t
 657     GetNumCompileUnits();
 658
 659     lldb::CompUnitSP
 660     GetCompileUnitAtIndex (size_t idx);
 661
 662     const ConstString &
 663     GetObjectName() const;
 664
 665     uint64_t
 666     GetObjectOffset() const
 667     {
 668         return m_object_offset;
 669     }
 670
 671     //------------------------------------------------------------------
 672     /// Get the object file representation for the current architecture.
 673     ///
 674     /// If the object file has not been located or parsed yet, this
 675     /// function will find the best ObjectFile plug-in that can parse
 676     /// Module::m_file.
 677     ///
 678     /// @return
 679     ///     If Module::m_file does not exist, or no plug-in was found
 680     ///     that can parse the file, or the object file doesn't contain
 681     ///     the current architecture in Module::m_arch, NULL will be
 682     ///     returned, else a valid object file interface will be
 683     ///     returned. The returned pointer is owned by this object and
 684     ///     remains valid as long as the object is around.
 685     //------------------------------------------------------------------
 686     virtual ObjectFile *
 687     GetObjectFile ();
 688
 689     //------------------------------------------------------------------
 690     /// Get the unified section list for the module. This is the section
 691     /// list created by the module's object file and any debug info and
 692     /// symbol files created by the symbol vendor.
 693     ///
 694     /// If the symbol vendor has not been loaded yet, this function
 695     /// will return the section list for the object file.
 696     ///
 697     /// @return
 698     ///     Unified module section list.
 699     //------------------------------------------------------------------
 700     virtual SectionList *
 701     GetSectionList ();
 702
 703     uint32_t
 704     GetVersion (uint32_t *versions, uint32_t num_versions);
 705
 706     // Load an object file from memory.
 707     ObjectFile *
 708     GetMemoryObjectFile (const lldb::ProcessSP &process_sp,
 709                          lldb::addr_t header_addr,
 710                          Error &error);
 711     //------------------------------------------------------------------
 712     /// Get the symbol vendor interface for the current architecture.
 713     ///
 714     /// If the symbol vendor file has not been located yet, this
 715     /// function will find the best SymbolVendor plug-in that can
 716     /// use the current object file.
 717     ///
 718     /// @return
 719     ///     If this module does not have a valid object file, or no
 720     ///     plug-in can be found that can use the object file, NULL will
 721     ///     be returned, else a valid symbol vendor plug-in interface
 722     ///     will be returned. The returned pointer is owned by this
 723     ///     object and remains valid as long as the object is around.
 724     //------------------------------------------------------------------
 725     virtual SymbolVendor*
 726     GetSymbolVendor(bool can_create = true,
 727                     lldb_private::Stream *feedback_strm = NULL);
 728
 729     //------------------------------------------------------------------
 730     /// Get accessor the type list for this module.
 731     ///
 732     /// @return
 733     ///     A valid type list pointer, or NULL if there is no valid
 734     ///     symbol vendor for this module.
 735     //------------------------------------------------------------------
 736     TypeList*
 737     GetTypeList ();
 738
 739     //------------------------------------------------------------------
 740     /// Get a pointer to the UUID value contained in this object.
 741     ///
 742     /// If the executable image file doesn't not have a UUID value built
 743     /// into the file format, an MD5 checksum of the entire file, or
 744     /// slice of the file for the current architecture should be used.
 745     ///
 746     /// @return
 747     ///     A const pointer to the internal copy of the UUID value in
 748     ///     this module if this module has a valid UUID value, NULL
 749     ///     otherwise.
 750     //------------------------------------------------------------------
 751     const lldb_private::UUID &
 752     GetUUID ();
 753
 754     //------------------------------------------------------------------
 755     /// A debugging function that will cause everything in a module to
 756     /// be parsed.
 757     ///
 758     /// All compile units will be pasred, along with all globals and
 759     /// static variables and all functions for those compile units.
 760     /// All types, scopes, local variables, static variables, global
 761     /// variables, and line tables will be parsed. This can be used
 762     /// prior to dumping a module to see a complete list of the
 763     /// resuling debug information that gets parsed, or as a debug
 764     /// function to ensure that the module can consume all of the
 765     /// debug data the symbol vendor provides.
 766     //------------------------------------------------------------------
 767     void
 768     ParseAllDebugSymbols();
 769
 770     bool
 771     ResolveFileAddress (lldb::addr_t vm_addr, Address& so_addr);
 772
 773     //------------------------------------------------------------------
 774     /// Resolve the symbol context for the given address.
 775     ///
 776     /// Tries to resolve the matching symbol context based on a lookup
 777     /// from the current symbol vendor.  If the lazy lookup fails,
 778     /// an attempt is made to parse the eh_frame section to handle
 779     /// stripped symbols.  If this fails, an attempt is made to resolve
 780     /// the symbol to the previous address to handle the case of a
 781     /// function with a tail call.
 782     ///
 783     /// Use properties of the modified SymbolContext to inspect any
 784     /// resolved target, module, compilation unit, symbol, function,
 785     /// function block or line entry.  Use the return value to determine
 786     /// which of these properties have been modified.
 787     ///
 788     /// @param[in] so_addr
 789     ///     A load address to resolve.
 790     ///
 791     /// @param[in] resolve_scope
 792     ///     The scope that should be resolved (see SymbolContext::Scope).
 793     ///     A combination of flags from the enumeration SymbolContextItem
 794     ///     requesting a resolution depth.  Note that the flags that are
 795     ///     actually resolved may be a superset of the requested flags.
 796     ///     For instance, eSymbolContextSymbol requires resolution of
 797     ///     eSymbolContextModule, and eSymbolContextFunction requires
 798     ///     eSymbolContextSymbol.
 799     ///
 800     /// @param[out] sc
 801     ///     The SymbolContext that is modified based on symbol resolution.
 802     ///
 803     /// @param[in] resolve_tail_call_address
 804     ///     Determines if so_addr should resolve to a symbol in the case
 805     ///     of a function whose last instruction is a call.  In this case,
 806     ///     the PC can be one past the address range of the function.
 807     ///
 808     /// @return
 809     ///     The scope that has been resolved (see SymbolContext::Scope).
 810     ///
 811     /// @see SymbolContext::Scope
 812     //------------------------------------------------------------------
 813     uint32_t
 814     ResolveSymbolContextForAddress (const Address& so_addr, uint32_t resolve_scope,
 815                                     SymbolContext& sc, bool resolve_tail_call_address = false);
 816
 817     //------------------------------------------------------------------
 818     /// Resolve items in the symbol context for a given file and line.
 819     ///
 820     /// Tries to resolve \a file_path and \a line to a list of matching
 821     /// symbol contexts.
 822     ///
 823     /// The line table entries contains addresses that can be used to
 824     /// further resolve the values in each match: the function, block,
 825     /// symbol. Care should be taken to minimize the amount of
 826     /// information that is requested to only what is needed --
 827     /// typically the module, compile unit, line table and line table
 828     /// entry are sufficient.
 829     ///
 830     /// @param[in] file_path
 831     ///     A path to a source file to match. If \a file_path does not
 832     ///     specify a directory, then this query will match all files
 833     ///     whose base filename matches. If \a file_path does specify
 834     ///     a directory, the fullpath to the file must match.
 835     ///
 836     /// @param[in] line
 837     ///     The source line to match, or zero if just the compile unit
 838     ///     should be resolved.
 839     ///
 840     /// @param[in] check_inlines
 841     ///     Check for inline file and line number matches. This option
 842     ///     should be used sparingly as it will cause all line tables
 843     ///     for every compile unit to be parsed and searched for
 844     ///     matching inline file entries.
 845     ///
 846     /// @param[in] resolve_scope
 847     ///     The scope that should be resolved (see
 848     ///     SymbolContext::Scope).
 849     ///
 850     /// @param[out] sc_list
 851     ///     A symbol context list that gets matching symbols contexts
 852     ///     appended to.
 853     ///
 854     /// @return
 855     ///     The number of matches that were added to \a sc_list.
 856     ///
 857     /// @see SymbolContext::Scope
 858     //------------------------------------------------------------------
 859     uint32_t
 860     ResolveSymbolContextForFilePath (const char *file_path, uint32_t line, bool check_inlines, uint32_t resolve_scope, SymbolContextList& sc_list);
 861
 862     //------------------------------------------------------------------
 863     /// Resolve items in the symbol context for a given file and line.
 864     ///
 865     /// Tries to resolve \a file_spec and \a line to a list of matching
 866     /// symbol contexts.
 867     ///
 868     /// The line table entries contains addresses that can be used to
 869     /// further resolve the values in each match: the function, block,
 870     /// symbol. Care should be taken to minimize the amount of
 871     /// information that is requested to only what is needed --
 872     /// typically the module, compile unit, line table and line table
 873     /// entry are sufficient.
 874     ///
 875     /// @param[in] file_spec
 876     ///     A file spec to a source file to match. If \a file_path does
 877     ///     not specify a directory, then this query will match all
 878     ///     files whose base filename matches. If \a file_path does
 879     ///     specify a directory, the fullpath to the file must match.
 880     ///
 881     /// @param[in] line
 882     ///     The source line to match, or zero if just the compile unit
 883     ///     should be resolved.
 884     ///
 885     /// @param[in] check_inlines
 886     ///     Check for inline file and line number matches. This option
 887     ///     should be used sparingly as it will cause all line tables
 888     ///     for every compile unit to be parsed and searched for
 889     ///     matching inline file entries.
 890     ///
 891     /// @param[in] resolve_scope
 892     ///     The scope that should be resolved (see
 893     ///     SymbolContext::Scope).
 894     ///
 895     /// @param[out] sc_list
 896     ///     A symbol context list that gets filled in with all of the
 897     ///     matches.
 898     ///
 899     /// @return
 900     ///     A integer that contains SymbolContext::Scope bits set for
 901     ///     each item that was successfully resolved.
 902     ///
 903     /// @see SymbolContext::Scope
 904     //------------------------------------------------------------------
 905     uint32_t
 906     ResolveSymbolContextsForFileSpec (const FileSpec &file_spec, uint32_t line, bool check_inlines, uint32_t resolve_scope, SymbolContextList& sc_list);
 907
 908
 909     void
 910     SetFileSpecAndObjectName (const FileSpec &file,
 911                               const ConstString &object_name);
 912
 913     bool
 914     GetIsDynamicLinkEditor () const
 915     {
 916         return m_is_dynamic_loader_module;
 917     }
 918
 919     void
 920     SetIsDynamicLinkEditor (bool b)
 921     {
 922         m_is_dynamic_loader_module = b;
 923     }
 924
 925     ClangASTContext &
 926     GetClangASTContext ();
 927
 928     // Special error functions that can do printf style formatting that will prepend the message with
 929     // something appropriate for this module (like the architecture, path and object name (if any)).
 930     // This centralizes code so that everyone doesn't need to format their error and log messages on
 931     // their own and keeps the output a bit more consistent.
 932     void
 933     LogMessage (Log *log, const char *format, ...) __attribute__ ((format (printf, 3, 4)));
 934
 935     void
 936     LogMessageVerboseBacktrace (Log *log, const char *format, ...) __attribute__ ((format (printf, 3, 4)));
 937
 938     void
 939     ReportWarning (const char *format, ...) __attribute__ ((format (printf, 2, 3)));
 940
 941     void
 942     ReportError (const char *format, ...) __attribute__ ((format (printf, 2, 3)));
 943
 944     // Only report an error once when the module is first detected to be modified
 945     // so we don't spam the console with many messages.
 946     void
 947     ReportErrorIfModifyDetected (const char *format, ...) __attribute__ ((format (printf, 2, 3)));
 948
 949     //------------------------------------------------------------------
 950     // Return true if the file backing this module has changed since the
 951     // module was originally created  since we saved the intial file
 952     // modification time when the module first gets created.
 953     //------------------------------------------------------------------
 954     bool
 955     FileHasChanged () const;
 956
 957     //------------------------------------------------------------------
 958     // SymbolVendor, SymbolFile and ObjectFile member objects should
 959     // lock the module mutex to avoid deadlocks.
 960     //------------------------------------------------------------------
 961     Mutex &
 962     GetMutex () const
 963     {
 964         return m_mutex;
 965     }
 966
 967     PathMappingList &
 968     GetSourceMappingList ()
 969     {
 970         return m_source_mappings;
 971     }
 972
 973     const PathMappingList &
 974     GetSourceMappingList () const
 975     {
 976         return m_source_mappings;
 977     }
 978
 979     //------------------------------------------------------------------
 980     /// Finds a source file given a file spec using the module source
 981     /// path remappings (if any).
 982     ///
 983     /// Tries to resolve \a orig_spec by checking the module source path
 984     /// remappings. It makes sure the file exists, so this call can be
 985     /// expensive if the remappings are on a network file system, so
 986     /// use this function sparingly (not in a tight debug info parsing
 987     /// loop).
 988     ///
 989     /// @param[in] orig_spec
 990     ///     The original source file path to try and remap.
 991     ///
 992     /// @param[out] new_spec
 993     ///     The newly remapped filespec that is guaranteed to exist.
 994     ///
 995     /// @return
 996     ///     /b true if \a orig_spec was successfully located and
 997     ///     \a new_spec is filled in with an existing file spec,
 998     ///     \b false otherwise.
 999     //------------------------------------------------------------------
1000     bool
1001     FindSourceFile (const FileSpec &orig_spec, FileSpec &new_spec) const;
1002
1003     //------------------------------------------------------------------
1004     /// Remaps a source file given \a path into \a new_path.
1005     ///
1006     /// Remaps \a path if any source remappings match. This function
1007     /// does NOT stat the file system so it can be used in tight loops
1008     /// where debug info is being parsed.
1009     ///
1010     /// @param[in] path
1011     ///     The original source file path to try and remap.
1012     ///
1013     /// @param[out] new_path
1014     ///     The newly remapped filespec that is may or may not exist.
1015     ///
1016     /// @return
1017     ///     /b true if \a path was successfully located and \a new_path
1018     ///     is filled in with a new source path, \b false otherwise.
1019     //------------------------------------------------------------------
1020     bool
1021     RemapSourceFile (const char *path, std::string &new_path) const;
1022
1023
1024     //------------------------------------------------------------------
1025     /// Prepare to do a function name lookup.
1026     ///
1027     /// Looking up functions by name can be a tricky thing. LLDB requires
1028     /// that accelerator tables contain full names for functions as well
1029     /// as function basenames which include functions, class methods and
1030     /// class functions. When the user requests that an action use a
1031     /// function by name, we are sometimes asked to automatically figure
1032     /// out what a name could possibly map to. A user might request a
1033     /// breakpoint be set on "count". If no options are supplied to limit
1034     /// the scope of where to search for count, we will by default match
1035     /// any function names named "count", all class and instance methods
1036     /// named "count" (no matter what the namespace or contained context)
1037     /// and any selectors named "count". If a user specifies "a::b" we
1038     /// will search for the basename "b", and then prune the results that
1039     /// don't match "a::b" (note that "c::a::b" and "d::e::a::b" will
1040     /// match a query of "a::b".
1041     ///
1042     /// @param[in] name
1043     ///     The user supplied name to use in the lookup
1044     ///
1045     /// @param[in] name_type_mask
1046     ///     The mask of bits from lldb::FunctionNameType enumerations
1047     ///     that tell us what kind of name we are looking for.
1048     ///
1049     /// @param[out] lookup_name
1050     ///     The actual name that will be used when calling
1051     ///     SymbolVendor::FindFunctions() or Symtab::FindFunctionSymbols()
1052     ///
1053     /// @param[out] lookup_name_type_mask
1054     ///     The actual name mask that should be used in the calls to
1055     ///     SymbolVendor::FindFunctions() or Symtab::FindFunctionSymbols()
1056     ///
1057     /// @param[out] match_name_after_lookup
1058     ///     A boolean that indicates if we need to iterate through any
1059     ///     match results obtained from SymbolVendor::FindFunctions() or
1060     ///     Symtab::FindFunctionSymbols() to see if the name contains
1061     ///     \a name. For example if \a name is "a::b", this function will
1062     ///     return a \a lookup_name of "b", with \a match_name_after_lookup
1063     ///     set to true to indicate any matches will need to be checked
1064     ///     to make sure they contain \a name.
1065     //------------------------------------------------------------------
1066     static void
1067     PrepareForFunctionNameLookup (const ConstString &name,
1068                                   uint32_t name_type_mask,
1069                                   ConstString &lookup_name,
1070                                   uint32_t &lookup_name_type_mask,
1071                                   bool &match_name_after_lookup);
1072
1073 protected:
1074     //------------------------------------------------------------------
1075     // Member Variables
1076     //------------------------------------------------------------------
1077     mutable Mutex               m_mutex;        ///< A mutex to keep this object happy in multi-threaded environments.
1078     TimeValue                   m_mod_time;     ///< The modification time for this module when it was created.
1079     ArchSpec                    m_arch;         ///< The architecture for this module.
1080     lldb_private::UUID          m_uuid;         ///< Each module is assumed to have a unique identifier to help match it up to debug symbols.
1081     FileSpec                    m_file;         ///< The file representation on disk for this module (if there is one).
1082     FileSpec                    m_platform_file;///< The path to the module on the platform on which it is being debugged
1083     FileSpec                    m_remote_install_file;  ///< If set when debugging on remote platforms, this module will be installed at this location
1084     FileSpec                    m_symfile_spec; ///< If this path is valid, then this is the file that _will_ be used as the symbol file for this module
1085     ConstString                 m_object_name;  ///< The name an object within this module that is selected, or empty of the module is represented by \a m_file.
1086     uint64_t                    m_object_offset;
1087     TimeValue                   m_object_mod_time;
1088     lldb::ObjectFileSP          m_objfile_sp;   ///< A shared pointer to the object file parser for this module as it may or may not be shared with the SymbolFile
1089     std::unique_ptr<SymbolVendor> m_symfile_ap;   ///< A pointer to the symbol vendor for this module.
1090     ClangASTContext             m_ast;          ///< The AST context for this module.
1091     PathMappingList             m_source_mappings; ///< Module specific source remappings for when you have debug info for a module that doesn't match where the sources currently are
1092     std::unique_ptr<lldb_private::SectionList> m_sections_ap; ///< Unified section list for module that is used by the ObjectFile and and ObjectFile instances for the debug info
1093
1094     bool                        m_did_load_objfile:1,
1095                                 m_did_load_symbol_vendor:1,
1096                                 m_did_parse_uuid:1,
1097                                 m_did_init_ast:1,
1098                                 m_is_dynamic_loader_module:1;
1099     mutable bool                m_file_has_changed:1,
1100                                 m_first_file_changed_log:1;   /// See if the module was modified after it was initially opened.
1101
1102     //------------------------------------------------------------------
1103     /// Resolve a file or load virtual address.
1104     ///
1105     /// Tries to resolve \a vm_addr as a file address (if \a
1106     /// vm_addr_is_file_addr is true) or as a load address if \a
1107     /// vm_addr_is_file_addr is false) in the symbol vendor.
1108     /// \a resolve_scope indicates what clients wish to resolve
1109     /// and can be used to limit the scope of what is parsed.
1110     ///
1111     /// @param[in] vm_addr
1112     ///     The load virtual address to resolve.
1113     ///
1114     /// @param[in] vm_addr_is_file_addr
1115     ///     If \b true, \a vm_addr is a file address, else \a vm_addr
1116     ///     if a load address.
1117     ///
1118     /// @param[in] resolve_scope
1119     ///     The scope that should be resolved (see
1120     ///     SymbolContext::Scope).
1121     ///
1122     /// @param[out] so_addr
1123     ///     The section offset based address that got resolved if
1124     ///     any bits are returned.
1125     ///
1126     /// @param[out] sc
1127     //      The symbol context that has objects filled in. Each bit
1128     ///     in the \a resolve_scope pertains to a member in the \a sc.
1129     ///
1130     /// @return
1131     ///     A integer that contains SymbolContext::Scope bits set for
1132     ///     each item that was successfully resolved.
1133     ///
1134     /// @see SymbolContext::Scope
1135     //------------------------------------------------------------------
1136     uint32_t
1137     ResolveSymbolContextForAddress (lldb::addr_t vm_addr,
1138                                     bool vm_addr_is_file_addr,
1139                                     uint32_t resolve_scope,
1140                                     Address& so_addr,
1141                                     SymbolContext& sc);
1142
1143     void
1144     SymbolIndicesToSymbolContextList (Symtab *symtab,
1145                                       std::vector<uint32_t> &symbol_indexes,
1146                                       SymbolContextList &sc_list);
1147
1148     bool
1149     SetArchitecture (const ArchSpec &new_arch);
1150
1151     SectionList *
1152     GetUnifiedSectionList();
1153
1154     friend class ModuleList;
1155     friend class ObjectFile;
1156     friend class SymbolFile;
1157
1158 private:
1159
1160     size_t
1161     FindTypes_Impl (const SymbolContext& sc,
1162                     const ConstString &name,
1163                     const ClangNamespaceDecl *namespace_decl,
1164                     bool append,
1165                     size_t max_matches,
1166                     TypeList& types);
1167
1168
1169     DISALLOW_COPY_AND_ASSIGN (Module);
1170 };
1171
1172 } // namespace lldb_private
1173
1174 #endif  // liblldb_Module_h_