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