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