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

   1 //===-- SearchFilter.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_SearchFilter_h_
  11 #define liblldb_SearchFilter_h_
  12
  13 #include "lldb/Core/FileSpecList.h"
  14 #include "lldb/Utility/StructuredData.h"
  15
  16 #include "lldb/Utility/FileSpec.h" // for FileSpec
  17 #include "lldb/lldb-forward.h"     // for SearchFilterSP, TargetSP, Modu...
  18
  19 #include <stdint.h> // for uint32_t
  20
  21 namespace lldb_private {
  22 class Address;
  23 }
  24 namespace lldb_private {
  25 class Breakpoint;
  26 }
  27 namespace lldb_private {
  28 class CompileUnit;
  29 }
  30 namespace lldb_private {
  31 class Status;
  32 }
  33 namespace lldb_private {
  34 class Function;
  35 }
  36 namespace lldb_private {
  37 class ModuleList;
  38 }
  39 namespace lldb_private {
  40 class SearchFilter;
  41 }
  42 namespace lldb_private {
  43 class Stream;
  44 }
  45 namespace lldb_private {
  46 class SymbolContext;
  47 }
  48 namespace lldb_private {
  49 class Target;
  50 }
  51
  52 namespace lldb_private {
  53
  54 //----------------------------------------------------------------------
  55 /// @class Searcher SearchFilter.h "lldb/Core/SearchFilter.h"
  56 /// @brief Class that is driven by the SearchFilter to search the
  57 /// SymbolContext space of the target program.
  58 //----------------------------------------------------------------------
  59
  60 //----------------------------------------------------------------------
  61 /// General Outline:
  62 /// Provides the callback and search depth for the SearchFilter search.
  63 //----------------------------------------------------------------------
  64
  65 class Searcher {
  66 public:
  67   typedef enum {
  68     eCallbackReturnStop = 0, // Stop the iteration
  69     eCallbackReturnContinue, // Continue the iteration
  70     eCallbackReturnPop       // Pop one level up and continue iterating
  71   } CallbackReturn;
  72
  73   typedef enum {
  74     eDepthTarget,
  75     eDepthModule,
  76     eDepthCompUnit,
  77     eDepthFunction,
  78     eDepthBlock,
  79     eDepthAddress
  80   } Depth;
  81
  82   Searcher();
  83
  84   virtual ~Searcher();
  85
  86   virtual CallbackReturn SearchCallback(SearchFilter &filter,
  87                                         SymbolContext &context, Address *addr,
  88                                         bool complete) = 0;
  89
  90   virtual Depth GetDepth() = 0;
  91
  92   //------------------------------------------------------------------
  93   /// Prints a canonical description for the searcher to the stream \a s.
  94   ///
  95   /// @param[in] s
  96   ///   Stream to which the output is copied.
  97   //------------------------------------------------------------------
  98   virtual void GetDescription(Stream *s);
  99 };
 100
 101 //----------------------------------------------------------------------
 102 /// @class SearchFilter SearchFilter.h "lldb/Core/SearchFilter.h"
 103 /// @brief Class descends through the SymbolContext space of the target,
 104 /// applying a filter at each stage till it reaches the depth specified by
 105 /// the GetDepth method of the searcher, and calls its callback at that point.
 106 //----------------------------------------------------------------------
 107
 108 //----------------------------------------------------------------------
 109 /// General Outline:
 110 /// Provides the callback and search depth for the SearchFilter search.
 111 ///
 112 /// The search is done by cooperation between the search filter and the
 113 /// searcher.
 114 /// The search filter does the heavy work of recursing through the SymbolContext
 115 /// space of the target program's symbol space.  The Searcher specifies the
 116 /// depth
 117 /// at which it wants its callback to be invoked.  Note that since the
 118 /// resolution
 119 /// of the Searcher may be greater than that of the SearchFilter, before the
 120 /// Searcher qualifies an address it should pass it to "AddressPasses."
 121 /// The default implementation is "Everything Passes."
 122 //----------------------------------------------------------------------
 123
 124 class SearchFilter {
 125 public:
 126   //------------------------------------------------------------------
 127   /// The basic constructor takes a Target, which gives the space to search.
 128   ///
 129   /// @param[in] target
 130   ///    The Target that provides the module list to search.
 131   //------------------------------------------------------------------
 132   SearchFilter(const lldb::TargetSP &target_sp);
 133
 134   SearchFilter(const SearchFilter &rhs);
 135
 136   SearchFilter(const lldb::TargetSP &target_sp, unsigned char filterType);
 137
 138   virtual ~SearchFilter();
 139
 140   SearchFilter &operator=(const SearchFilter &rhs);
 141
 142   //------------------------------------------------------------------
 143   /// Call this method with a file spec to see if that spec passes the filter.
 144   ///
 145   /// @param[in] spec
 146   ///    The file spec to check against the filter.
 147   /// @return
 148   ///    \b true if \a spec passes, and \b false otherwise.
 149   //------------------------------------------------------------------
 150   virtual bool ModulePasses(const FileSpec &spec);
 151
 152   //------------------------------------------------------------------
 153   /// Call this method with a Module to see if that module passes the filter.
 154   ///
 155   /// @param[in] module
 156   ///    The Module to check against the filter.
 157   ///
 158   /// @return
 159   ///    \b true if \a module passes, and \b false otherwise.
 160   //------------------------------------------------------------------
 161   virtual bool ModulePasses(const lldb::ModuleSP &module_sp);
 162
 163   //------------------------------------------------------------------
 164   /// Call this method with a Address to see if \a address passes the filter.
 165   ///
 166   /// @param[in] addr
 167   ///    The address to check against the filter.
 168   ///
 169   /// @return
 170   ///    \b true if \a address passes, and \b false otherwise.
 171   //------------------------------------------------------------------
 172   virtual bool AddressPasses(Address &addr);
 173
 174   //------------------------------------------------------------------
 175   /// Call this method with a FileSpec to see if \a file spec passes the filter
 176   /// as the name of a compilation unit.
 177   ///
 178   /// @param[in] fileSpec
 179   ///    The file spec to check against the filter.
 180   ///
 181   /// @return
 182   ///    \b true if \a file spec passes, and \b false otherwise.
 183   //------------------------------------------------------------------
 184   virtual bool CompUnitPasses(FileSpec &fileSpec);
 185
 186   //------------------------------------------------------------------
 187   /// Call this method with a CompileUnit to see if \a comp unit passes the
 188   /// filter.
 189   ///
 190   /// @param[in] compUnit
 191   ///    The CompileUnit to check against the filter.
 192   ///
 193   /// @return
 194   ///    \b true if \a Comp Unit passes, and \b false otherwise.
 195   //------------------------------------------------------------------
 196   virtual bool CompUnitPasses(CompileUnit &compUnit);
 197
 198   //------------------------------------------------------------------
 199   /// Call this method to do the search using the Searcher.
 200   ///
 201   /// @param[in] searcher
 202   ///    The searcher to drive with this search.
 203   ///
 204   //------------------------------------------------------------------
 205   virtual void Search(Searcher &searcher);
 206
 207   //------------------------------------------------------------------
 208   /// Call this method to do the search using the Searcher in the module list
 209   /// \a modules.
 210   ///
 211   /// @param[in] searcher
 212   ///    The searcher to drive with this search.
 213   ///
 214   /// @param[in] modules
 215   ///    The module list within which to restrict the search.
 216   ///
 217   //------------------------------------------------------------------
 218   virtual void SearchInModuleList(Searcher &searcher, ModuleList &modules);
 219
 220   //------------------------------------------------------------------
 221   /// This determines which items are REQUIRED for the filter to pass.
 222   /// For instance, if you are filtering by Compilation Unit, obviously
 223   /// symbols that have no compilation unit can't pass  So return
 224   /// eSymbolContextCU
 225   /// and search callbacks can then short cut the search to avoid looking at
 226   /// things that obviously won't pass.
 227   ///
 228   /// @return
 229   ///    The required elements for the search, which is an or'ed together
 230   ///    set of lldb:SearchContextItem enum's.
 231   ///
 232   //------------------------------------------------------------------
 233   virtual uint32_t GetFilterRequiredItems();
 234
 235   //------------------------------------------------------------------
 236   /// Prints a canonical description for the search filter to the stream \a s.
 237   ///
 238   /// @param[in] s
 239   ///   Stream to which the output is copied.
 240   //------------------------------------------------------------------
 241   virtual void GetDescription(Stream *s);
 242
 243   //------------------------------------------------------------------
 244   /// Standard "Dump" method.  At present it does nothing.
 245   //------------------------------------------------------------------
 246   virtual void Dump(Stream *s) const;
 247
 248   lldb::SearchFilterSP CopyForBreakpoint(Breakpoint &breakpoint);
 249
 250   static lldb::SearchFilterSP
 251   CreateFromStructuredData(Target &target,
 252                            const StructuredData::Dictionary &data_dict,
 253                            Status &error);
 254
 255   virtual StructuredData::ObjectSP SerializeToStructuredData() {
 256     return StructuredData::ObjectSP();
 257   }
 258
 259   static const char *GetSerializationKey() { return "SearchFilter"; }
 260
 261   static const char *GetSerializationSubclassKey() { return "Type"; }
 262
 263   static const char *GetSerializationSubclassOptionsKey() { return "Options"; }
 264
 265   enum FilterTy {
 266     Unconstrained = 0,
 267     Exception,
 268     ByModule,
 269     ByModules,
 270     ByModulesAndCU,
 271     LastKnownFilterType = ByModulesAndCU,
 272     UnknownFilter
 273   };
 274
 275   static const char *g_ty_to_name[LastKnownFilterType + 2];
 276
 277   enum FilterTy GetFilterTy() {
 278     if (SubclassID > FilterTy::LastKnownFilterType)
 279       return FilterTy::UnknownFilter;
 280     else
 281       return (enum FilterTy)SubclassID;
 282   }
 283
 284   const char *GetFilterName() { return FilterTyToName(GetFilterTy()); }
 285
 286   static const char *FilterTyToName(enum FilterTy);
 287
 288   static FilterTy NameToFilterTy(llvm::StringRef name);
 289
 290 protected:
 291   // Serialization of SearchFilter options:
 292   enum OptionNames { ModList = 0, CUList, LanguageName, LastOptionName };
 293   static const char *g_option_names[LastOptionName];
 294
 295   static const char *GetKey(enum OptionNames enum_value) {
 296     return g_option_names[enum_value];
 297   }
 298
 299   StructuredData::DictionarySP
 300   WrapOptionsDict(StructuredData::DictionarySP options_dict_sp);
 301
 302   void SerializeFileSpecList(StructuredData::DictionarySP &options_dict_sp,
 303                              OptionNames name, FileSpecList &file_list);
 304
 305   // These are utility functions to assist with the search iteration.  They are
 306   // used by the
 307   // default Search method.
 308
 309   Searcher::CallbackReturn DoModuleIteration(const SymbolContext &context,
 310                                              Searcher &searcher);
 311
 312   Searcher::CallbackReturn DoModuleIteration(const lldb::ModuleSP &module_sp,
 313                                              Searcher &searcher);
 314
 315   Searcher::CallbackReturn DoCUIteration(const lldb::ModuleSP &module_sp,
 316                                          const SymbolContext &context,
 317                                          Searcher &searcher);
 318
 319   Searcher::CallbackReturn DoFunctionIteration(Function *function,
 320                                                const SymbolContext &context,
 321                                                Searcher &searcher);
 322
 323   virtual lldb::SearchFilterSP DoCopyForBreakpoint(Breakpoint &breakpoint) = 0;
 324
 325   void SetTarget(lldb::TargetSP &target_sp) { m_target_sp = target_sp; }
 326
 327   lldb::TargetSP
 328       m_target_sp; // Every filter has to be associated with a target for
 329                    // now since you need a starting place for the search.
 330 private:
 331   unsigned char SubclassID;
 332 };
 333
 334 //----------------------------------------------------------------------
 335 /// @class SearchFilterForUnconstrainedSearches SearchFilter.h
 336 /// "lldb/Core/SearchFilter.h"
 337 /// @brief This is a SearchFilter that searches through all modules.  It also
 338 /// consults the Target::ModuleIsExcludedForUnconstrainedSearches.
 339 //----------------------------------------------------------------------
 340 class SearchFilterForUnconstrainedSearches : public SearchFilter {
 341 public:
 342   SearchFilterForUnconstrainedSearches(const lldb::TargetSP &target_sp)
 343       : SearchFilter(target_sp, FilterTy::Unconstrained) {}
 344
 345   ~SearchFilterForUnconstrainedSearches() override = default;
 346
 347   bool ModulePasses(const FileSpec &module_spec) override;
 348
 349   bool ModulePasses(const lldb::ModuleSP &module_sp) override;
 350
 351   static lldb::SearchFilterSP
 352   CreateFromStructuredData(Target &target,
 353                            const StructuredData::Dictionary &data_dict,
 354                            Status &error);
 355
 356   StructuredData::ObjectSP SerializeToStructuredData() override;
 357
 358 protected:
 359   lldb::SearchFilterSP DoCopyForBreakpoint(Breakpoint &breakpoint) override;
 360 };
 361
 362 //----------------------------------------------------------------------
 363 /// @class SearchFilterByModule SearchFilter.h "lldb/Core/SearchFilter.h"
 364 /// @brief This is a SearchFilter that restricts the search to a given module.
 365 //----------------------------------------------------------------------
 366
 367 class SearchFilterByModule : public SearchFilter {
 368 public:
 369   //------------------------------------------------------------------
 370   /// The basic constructor takes a Target, which gives the space to search,
 371   /// and the module to restrict the search to.
 372   ///
 373   /// @param[in] target
 374   ///    The Target that provides the module list to search.
 375   ///
 376   /// @param[in] module
 377   ///    The Module that limits the search.
 378   //------------------------------------------------------------------
 379   SearchFilterByModule(const lldb::TargetSP &targetSP, const FileSpec &module);
 380
 381   SearchFilterByModule(const SearchFilterByModule &rhs);
 382
 383   ~SearchFilterByModule() override;
 384
 385   SearchFilterByModule &operator=(const SearchFilterByModule &rhs);
 386
 387   bool ModulePasses(const lldb::ModuleSP &module_sp) override;
 388
 389   bool ModulePasses(const FileSpec &spec) override;
 390
 391   bool AddressPasses(Address &address) override;
 392
 393   bool CompUnitPasses(FileSpec &fileSpec) override;
 394
 395   bool CompUnitPasses(CompileUnit &compUnit) override;
 396
 397   void GetDescription(Stream *s) override;
 398
 399   uint32_t GetFilterRequiredItems() override;
 400
 401   void Dump(Stream *s) const override;
 402
 403   void Search(Searcher &searcher) override;
 404
 405   static lldb::SearchFilterSP
 406   CreateFromStructuredData(Target &target,
 407                            const StructuredData::Dictionary &data_dict,
 408                            Status &error);
 409
 410   StructuredData::ObjectSP SerializeToStructuredData() override;
 411
 412 protected:
 413   lldb::SearchFilterSP DoCopyForBreakpoint(Breakpoint &breakpoint) override;
 414
 415 private:
 416   FileSpec m_module_spec;
 417 };
 418
 419 class SearchFilterByModuleList : public SearchFilter {
 420 public:
 421   //------------------------------------------------------------------
 422   /// The basic constructor takes a Target, which gives the space to search,
 423   /// and the module list to restrict the search to.
 424   ///
 425   /// @param[in] target
 426   ///    The Target that provides the module list to search.
 427   ///
 428   /// @param[in] module
 429   ///    The Module that limits the search.
 430   //------------------------------------------------------------------
 431   SearchFilterByModuleList(const lldb::TargetSP &targetSP,
 432                            const FileSpecList &module_list);
 433
 434   SearchFilterByModuleList(const lldb::TargetSP &targetSP,
 435                            const FileSpecList &module_list,
 436                            enum FilterTy filter_ty);
 437
 438   SearchFilterByModuleList(const SearchFilterByModuleList &rhs);
 439
 440   ~SearchFilterByModuleList() override;
 441
 442   SearchFilterByModuleList &operator=(const SearchFilterByModuleList &rhs);
 443
 444   bool ModulePasses(const lldb::ModuleSP &module_sp) override;
 445
 446   bool ModulePasses(const FileSpec &spec) override;
 447
 448   bool AddressPasses(Address &address) override;
 449
 450   bool CompUnitPasses(FileSpec &fileSpec) override;
 451
 452   bool CompUnitPasses(CompileUnit &compUnit) override;
 453
 454   void GetDescription(Stream *s) override;
 455
 456   uint32_t GetFilterRequiredItems() override;
 457
 458   void Dump(Stream *s) const override;
 459
 460   void Search(Searcher &searcher) override;
 461
 462   static lldb::SearchFilterSP
 463   CreateFromStructuredData(Target &target,
 464                            const StructuredData::Dictionary &data_dict,
 465                            Status &error);
 466
 467   StructuredData::ObjectSP SerializeToStructuredData() override;
 468
 469   void SerializeUnwrapped(StructuredData::DictionarySP &options_dict_sp);
 470
 471 protected:
 472   lldb::SearchFilterSP DoCopyForBreakpoint(Breakpoint &breakpoint) override;
 473
 474 protected:
 475   FileSpecList m_module_spec_list;
 476 };
 477
 478 class SearchFilterByModuleListAndCU : public SearchFilterByModuleList {
 479 public:
 480   //------------------------------------------------------------------
 481   /// The basic constructor takes a Target, which gives the space to search,
 482   /// and the module list to restrict the search to.
 483   ///
 484   /// @param[in] target
 485   ///    The Target that provides the module list to search.
 486   ///
 487   /// @param[in] module
 488   ///    The Module that limits the search.
 489   //------------------------------------------------------------------
 490   SearchFilterByModuleListAndCU(const lldb::TargetSP &targetSP,
 491                                 const FileSpecList &module_list,
 492                                 const FileSpecList &cu_list);
 493
 494   SearchFilterByModuleListAndCU(const SearchFilterByModuleListAndCU &rhs);
 495
 496   ~SearchFilterByModuleListAndCU() override;
 497
 498   SearchFilterByModuleListAndCU &
 499   operator=(const SearchFilterByModuleListAndCU &rhs);
 500
 501   bool AddressPasses(Address &address) override;
 502
 503   bool CompUnitPasses(FileSpec &fileSpec) override;
 504
 505   bool CompUnitPasses(CompileUnit &compUnit) override;
 506
 507   void GetDescription(Stream *s) override;
 508
 509   uint32_t GetFilterRequiredItems() override;
 510
 511   void Dump(Stream *s) const override;
 512
 513   void Search(Searcher &searcher) override;
 514
 515   static lldb::SearchFilterSP
 516   CreateFromStructuredData(Target &target,
 517                            const StructuredData::Dictionary &data_dict,
 518                            Status &error);
 519
 520   StructuredData::ObjectSP SerializeToStructuredData() override;
 521
 522 protected:
 523   lldb::SearchFilterSP DoCopyForBreakpoint(Breakpoint &breakpoint) override;
 524
 525 private:
 526   FileSpecList m_cu_spec_list;
 527 };
 528
 529 } // namespace lldb_private
 530
 531 #endif // liblldb_SearchFilter_h_