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