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 SerializeToStructuredData()254 virtual StructuredData::ObjectSP SerializeToStructuredData() { 255 return StructuredData::ObjectSP(); 256 } 257 GetSerializationKey()258 static const char *GetSerializationKey() { return "SearchFilter"; } 259 GetSerializationSubclassKey()260 static const char *GetSerializationSubclassKey() { return "Type"; } 261 GetSerializationSubclassOptionsKey()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 GetFilterTy()276 enum FilterTy GetFilterTy() { 277 if (SubclassID > FilterTy::LastKnownFilterType) 278 return FilterTy::UnknownFilter; 279 else 280 return (enum FilterTy)SubclassID; 281 } 282 GetFilterName()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 GetKey(enum OptionNames enum_value)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 SetTarget(lldb::TargetSP & target_sp)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: SearchFilterForUnconstrainedSearches(const lldb::TargetSP & target_sp)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_ 530