1254721Semaste//===-- SearchFilter.h ------------------------------------------*- C++ -*-===// 2254721Semaste// 3353358Sdim// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4353358Sdim// See https://llvm.org/LICENSE.txt for license information. 5353358Sdim// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6254721Semaste// 7254721Semaste//===----------------------------------------------------------------------===// 8254721Semaste 9254721Semaste#ifndef liblldb_SearchFilter_h_ 10254721Semaste#define liblldb_SearchFilter_h_ 11254721Semaste 12314564Sdim#include "lldb/Core/FileSpecList.h" 13321369Sdim#include "lldb/Utility/StructuredData.h" 14254721Semaste 15344779Sdim#include "lldb/Utility/FileSpec.h" 16344779Sdim#include "lldb/lldb-forward.h" 17321369Sdim 18344779Sdim#include <stdint.h> 19321369Sdim 20254721Semastenamespace lldb_private { 21321369Sdimclass Address; 22321369Sdimclass Breakpoint; 23321369Sdimclass CompileUnit; 24321369Sdimclass Status; 25321369Sdimclass Function; 26321369Sdimclass ModuleList; 27321369Sdimclass SearchFilter; 28321369Sdimclass Stream; 29321369Sdimclass SymbolContext; 30321369Sdimclass Target; 31321369Sdim} 32254721Semaste 33321369Sdimnamespace lldb_private { 34321369Sdim 35353358Sdim/// \class Searcher SearchFilter.h "lldb/Core/SearchFilter.h" Class that is 36341825Sdim/// driven by the SearchFilter to search the SymbolContext space of the target 37341825Sdim/// program. 38254721Semaste 39254721Semaste/// General Outline: 40254721Semaste/// Provides the callback and search depth for the SearchFilter search. 41254721Semaste 42314564Sdimclass Searcher { 43254721Semastepublic: 44353358Sdim enum CallbackReturn { 45314564Sdim eCallbackReturnStop = 0, // Stop the iteration 46314564Sdim eCallbackReturnContinue, // Continue the iteration 47314564Sdim eCallbackReturnPop // Pop one level up and continue iterating 48353358Sdim }; 49254721Semaste 50314564Sdim Searcher(); 51254721Semaste 52314564Sdim virtual ~Searcher(); 53254721Semaste 54314564Sdim virtual CallbackReturn SearchCallback(SearchFilter &filter, 55360784Sdim SymbolContext &context, 56360784Sdim Address *addr) = 0; 57254721Semaste 58344779Sdim virtual lldb::SearchDepth GetDepth() = 0; 59254721Semaste 60314564Sdim /// Prints a canonical description for the searcher to the stream \a s. 61314564Sdim /// 62353358Sdim /// \param[in] s 63314564Sdim /// Stream to which the output is copied. 64314564Sdim virtual void GetDescription(Stream *s); 65254721Semaste}; 66254721Semaste 67353358Sdim/// \class SearchFilter SearchFilter.h "lldb/Core/SearchFilter.h" Class 68341825Sdim/// descends through the SymbolContext space of the target, applying a filter 69341825Sdim/// at each stage till it reaches the depth specified by the GetDepth method 70341825Sdim/// of the searcher, and calls its callback at that point. 71254721Semaste 72254721Semaste/// General Outline: 73254721Semaste/// Provides the callback and search depth for the SearchFilter search. 74254721Semaste/// 75314564Sdim/// The search is done by cooperation between the search filter and the 76341825Sdim/// searcher. The search filter does the heavy work of recursing through the 77341825Sdim/// SymbolContext space of the target program's symbol space. The Searcher 78341825Sdim/// specifies the depth at which it wants its callback to be invoked. Note 79341825Sdim/// that since the resolution of the Searcher may be greater than that of the 80341825Sdim/// SearchFilter, before the Searcher qualifies an address it should pass it 81341825Sdim/// to "AddressPasses." The default implementation is "Everything Passes." 82254721Semaste 83314564Sdimclass SearchFilter { 84254721Semastepublic: 85314564Sdim /// The basic constructor takes a Target, which gives the space to search. 86314564Sdim /// 87360784Sdim /// \param[in] target_sp 88314564Sdim /// The Target that provides the module list to search. 89314564Sdim SearchFilter(const lldb::TargetSP &target_sp); 90254721Semaste 91314564Sdim SearchFilter(const lldb::TargetSP &target_sp, unsigned char filterType); 92254721Semaste 93314564Sdim virtual ~SearchFilter(); 94254721Semaste 95314564Sdim /// Call this method with a file spec to see if that spec passes the filter. 96314564Sdim /// 97353358Sdim /// \param[in] spec 98314564Sdim /// The file spec to check against the filter. 99353358Sdim /// \return 100314564Sdim /// \b true if \a spec passes, and \b false otherwise. 101314564Sdim virtual bool ModulePasses(const FileSpec &spec); 102254721Semaste 103314564Sdim /// Call this method with a Module to see if that module passes the filter. 104314564Sdim /// 105360784Sdim /// \param[in] module_sp 106314564Sdim /// The Module to check against the filter. 107314564Sdim /// 108353358Sdim /// \return 109314564Sdim /// \b true if \a module passes, and \b false otherwise. 110314564Sdim virtual bool ModulePasses(const lldb::ModuleSP &module_sp); 111254721Semaste 112314564Sdim /// Call this method with a Address to see if \a address passes the filter. 113314564Sdim /// 114353358Sdim /// \param[in] addr 115314564Sdim /// The address to check against the filter. 116314564Sdim /// 117353358Sdim /// \return 118314564Sdim /// \b true if \a address passes, and \b false otherwise. 119314564Sdim virtual bool AddressPasses(Address &addr); 120254721Semaste 121341825Sdim /// Call this method with a FileSpec to see if \a file spec passes the 122341825Sdim /// filter as the name of a compilation unit. 123314564Sdim /// 124353358Sdim /// \param[in] fileSpec 125314564Sdim /// The file spec to check against the filter. 126314564Sdim /// 127353358Sdim /// \return 128314564Sdim /// \b true if \a file spec passes, and \b false otherwise. 129314564Sdim virtual bool CompUnitPasses(FileSpec &fileSpec); 130254721Semaste 131314564Sdim /// Call this method with a CompileUnit to see if \a comp unit passes the 132314564Sdim /// filter. 133314564Sdim /// 134353358Sdim /// \param[in] compUnit 135314564Sdim /// The CompileUnit to check against the filter. 136314564Sdim /// 137353358Sdim /// \return 138314564Sdim /// \b true if \a Comp Unit passes, and \b false otherwise. 139314564Sdim virtual bool CompUnitPasses(CompileUnit &compUnit); 140254721Semaste 141344779Sdim /// Call this method with a Function to see if \a function passes the 142344779Sdim /// filter. 143344779Sdim /// 144353358Sdim /// \param[in] function 145344779Sdim /// The Functions to check against the filter. 146344779Sdim /// 147353358Sdim /// \return 148344779Sdim /// \b true if \a function passes, and \b false otherwise. 149344779Sdim virtual bool FunctionPasses(Function &function); 150344779Sdim 151314564Sdim /// Call this method to do the search using the Searcher. 152314564Sdim /// 153353358Sdim /// \param[in] searcher 154314564Sdim /// The searcher to drive with this search. 155314564Sdim /// 156314564Sdim virtual void Search(Searcher &searcher); 157254721Semaste 158314564Sdim /// Call this method to do the search using the Searcher in the module list 159314564Sdim /// \a modules. 160314564Sdim /// 161353358Sdim /// \param[in] searcher 162314564Sdim /// The searcher to drive with this search. 163314564Sdim /// 164353358Sdim /// \param[in] modules 165314564Sdim /// The module list within which to restrict the search. 166314564Sdim /// 167314564Sdim virtual void SearchInModuleList(Searcher &searcher, ModuleList &modules); 168254721Semaste 169341825Sdim /// This determines which items are REQUIRED for the filter to pass. For 170341825Sdim /// instance, if you are filtering by Compilation Unit, obviously symbols 171341825Sdim /// that have no compilation unit can't pass So return eSymbolContextCU and 172341825Sdim /// search callbacks can then short cut the search to avoid looking at 173314564Sdim /// things that obviously won't pass. 174314564Sdim /// 175353358Sdim /// \return 176314564Sdim /// The required elements for the search, which is an or'ed together 177314564Sdim /// set of lldb:SearchContextItem enum's. 178314564Sdim /// 179314564Sdim virtual uint32_t GetFilterRequiredItems(); 180254721Semaste 181314564Sdim /// Prints a canonical description for the search filter to the stream \a s. 182314564Sdim /// 183353358Sdim /// \param[in] s 184314564Sdim /// Stream to which the output is copied. 185314564Sdim virtual void GetDescription(Stream *s); 186254721Semaste 187314564Sdim /// Standard "Dump" method. At present it does nothing. 188314564Sdim virtual void Dump(Stream *s) const; 189280031Sdim 190314564Sdim lldb::SearchFilterSP CopyForBreakpoint(Breakpoint &breakpoint); 191314564Sdim 192314564Sdim static lldb::SearchFilterSP 193314564Sdim CreateFromStructuredData(Target &target, 194314564Sdim const StructuredData::Dictionary &data_dict, 195321369Sdim Status &error); 196314564Sdim 197314564Sdim virtual StructuredData::ObjectSP SerializeToStructuredData() { 198314564Sdim return StructuredData::ObjectSP(); 199314564Sdim } 200314564Sdim 201314564Sdim static const char *GetSerializationKey() { return "SearchFilter"; } 202314564Sdim 203314564Sdim static const char *GetSerializationSubclassKey() { return "Type"; } 204314564Sdim 205314564Sdim static const char *GetSerializationSubclassOptionsKey() { return "Options"; } 206314564Sdim 207314564Sdim enum FilterTy { 208314564Sdim Unconstrained = 0, 209314564Sdim Exception, 210314564Sdim ByModule, 211314564Sdim ByModules, 212314564Sdim ByModulesAndCU, 213314564Sdim LastKnownFilterType = ByModulesAndCU, 214314564Sdim UnknownFilter 215314564Sdim }; 216314564Sdim 217314564Sdim static const char *g_ty_to_name[LastKnownFilterType + 2]; 218314564Sdim 219314564Sdim enum FilterTy GetFilterTy() { 220314564Sdim if (SubclassID > FilterTy::LastKnownFilterType) 221314564Sdim return FilterTy::UnknownFilter; 222314564Sdim else 223314564Sdim return (enum FilterTy)SubclassID; 224314564Sdim } 225314564Sdim 226314564Sdim const char *GetFilterName() { return FilterTyToName(GetFilterTy()); } 227314564Sdim 228314564Sdim static const char *FilterTyToName(enum FilterTy); 229314564Sdim 230321369Sdim static FilterTy NameToFilterTy(llvm::StringRef name); 231314564Sdim 232254721Semasteprotected: 233314564Sdim // Serialization of SearchFilter options: 234314564Sdim enum OptionNames { ModList = 0, CUList, LanguageName, LastOptionName }; 235314564Sdim static const char *g_option_names[LastOptionName]; 236254721Semaste 237314564Sdim static const char *GetKey(enum OptionNames enum_value) { 238314564Sdim return g_option_names[enum_value]; 239314564Sdim } 240254721Semaste 241314564Sdim StructuredData::DictionarySP 242314564Sdim WrapOptionsDict(StructuredData::DictionarySP options_dict_sp); 243254721Semaste 244314564Sdim void SerializeFileSpecList(StructuredData::DictionarySP &options_dict_sp, 245314564Sdim OptionNames name, FileSpecList &file_list); 246254721Semaste 247314564Sdim // These are utility functions to assist with the search iteration. They are 248341825Sdim // used by the default Search method. 249254721Semaste 250314564Sdim Searcher::CallbackReturn DoModuleIteration(const SymbolContext &context, 251314564Sdim Searcher &searcher); 252280031Sdim 253314564Sdim Searcher::CallbackReturn DoModuleIteration(const lldb::ModuleSP &module_sp, 254314564Sdim Searcher &searcher); 255280031Sdim 256314564Sdim Searcher::CallbackReturn DoCUIteration(const lldb::ModuleSP &module_sp, 257314564Sdim const SymbolContext &context, 258314564Sdim Searcher &searcher); 259314564Sdim 260314564Sdim Searcher::CallbackReturn DoFunctionIteration(Function *function, 261314564Sdim const SymbolContext &context, 262314564Sdim Searcher &searcher); 263314564Sdim 264314564Sdim virtual lldb::SearchFilterSP DoCopyForBreakpoint(Breakpoint &breakpoint) = 0; 265314564Sdim 266314564Sdim void SetTarget(lldb::TargetSP &target_sp) { m_target_sp = target_sp; } 267314564Sdim 268314564Sdim lldb::TargetSP 269314564Sdim m_target_sp; // Every filter has to be associated with a target for 270314564Sdim // now since you need a starting place for the search. 271314564Sdimprivate: 272314564Sdim unsigned char SubclassID; 273254721Semaste}; 274254721Semaste 275353358Sdim/// \class SearchFilterForUnconstrainedSearches SearchFilter.h 276341825Sdim/// "lldb/Core/SearchFilter.h" This is a SearchFilter that searches through 277341825Sdim/// all modules. It also consults the 278341825Sdim/// Target::ModuleIsExcludedForUnconstrainedSearches. 279314564Sdimclass SearchFilterForUnconstrainedSearches : public SearchFilter { 280254721Semastepublic: 281314564Sdim SearchFilterForUnconstrainedSearches(const lldb::TargetSP &target_sp) 282314564Sdim : SearchFilter(target_sp, FilterTy::Unconstrained) {} 283280031Sdim 284314564Sdim ~SearchFilterForUnconstrainedSearches() override = default; 285314564Sdim 286314564Sdim bool ModulePasses(const FileSpec &module_spec) override; 287314564Sdim 288314564Sdim bool ModulePasses(const lldb::ModuleSP &module_sp) override; 289314564Sdim 290314564Sdim static lldb::SearchFilterSP 291314564Sdim CreateFromStructuredData(Target &target, 292314564Sdim const StructuredData::Dictionary &data_dict, 293321369Sdim Status &error); 294314564Sdim 295314564Sdim StructuredData::ObjectSP SerializeToStructuredData() override; 296314564Sdim 297280031Sdimprotected: 298314564Sdim lldb::SearchFilterSP DoCopyForBreakpoint(Breakpoint &breakpoint) override; 299254721Semaste}; 300254721Semaste 301353358Sdim/// \class SearchFilterByModule SearchFilter.h "lldb/Core/SearchFilter.h" This 302341825Sdim/// is a SearchFilter that restricts the search to a given module. 303254721Semaste 304314564Sdimclass SearchFilterByModule : public SearchFilter { 305254721Semastepublic: 306314564Sdim /// The basic constructor takes a Target, which gives the space to search, 307314564Sdim /// and the module to restrict the search to. 308314564Sdim /// 309360784Sdim /// \param[in] targetSP 310314564Sdim /// The Target that provides the module list to search. 311314564Sdim /// 312353358Sdim /// \param[in] module 313314564Sdim /// The Module that limits the search. 314314564Sdim SearchFilterByModule(const lldb::TargetSP &targetSP, const FileSpec &module); 315254721Semaste 316314564Sdim ~SearchFilterByModule() override; 317254721Semaste 318314564Sdim bool ModulePasses(const lldb::ModuleSP &module_sp) override; 319254721Semaste 320314564Sdim bool ModulePasses(const FileSpec &spec) override; 321254721Semaste 322314564Sdim bool AddressPasses(Address &address) override; 323254721Semaste 324314564Sdim bool CompUnitPasses(FileSpec &fileSpec) override; 325254721Semaste 326314564Sdim bool CompUnitPasses(CompileUnit &compUnit) override; 327254721Semaste 328314564Sdim void GetDescription(Stream *s) override; 329254721Semaste 330314564Sdim uint32_t GetFilterRequiredItems() override; 331254721Semaste 332314564Sdim void Dump(Stream *s) const override; 333254721Semaste 334314564Sdim void Search(Searcher &searcher) override; 335254721Semaste 336314564Sdim static lldb::SearchFilterSP 337314564Sdim CreateFromStructuredData(Target &target, 338314564Sdim const StructuredData::Dictionary &data_dict, 339321369Sdim Status &error); 340314564Sdim 341314564Sdim StructuredData::ObjectSP SerializeToStructuredData() override; 342314564Sdim 343280031Sdimprotected: 344314564Sdim lldb::SearchFilterSP DoCopyForBreakpoint(Breakpoint &breakpoint) override; 345280031Sdim 346254721Semasteprivate: 347314564Sdim FileSpec m_module_spec; 348254721Semaste}; 349254721Semaste 350314564Sdimclass SearchFilterByModuleList : public SearchFilter { 351254721Semastepublic: 352314564Sdim /// The basic constructor takes a Target, which gives the space to search, 353314564Sdim /// and the module list to restrict the search to. 354314564Sdim /// 355360784Sdim /// \param[in] targetSP 356314564Sdim /// The Target that provides the module list to search. 357314564Sdim /// 358360784Sdim /// \param[in] module_list 359314564Sdim /// The Module that limits the search. 360314564Sdim SearchFilterByModuleList(const lldb::TargetSP &targetSP, 361314564Sdim const FileSpecList &module_list); 362254721Semaste 363314564Sdim SearchFilterByModuleList(const lldb::TargetSP &targetSP, 364314564Sdim const FileSpecList &module_list, 365314564Sdim enum FilterTy filter_ty); 366254721Semaste 367314564Sdim ~SearchFilterByModuleList() override; 368254721Semaste 369314564Sdim bool ModulePasses(const lldb::ModuleSP &module_sp) override; 370254721Semaste 371314564Sdim bool ModulePasses(const FileSpec &spec) override; 372254721Semaste 373314564Sdim bool AddressPasses(Address &address) override; 374254721Semaste 375314564Sdim bool CompUnitPasses(FileSpec &fileSpec) override; 376254721Semaste 377314564Sdim bool CompUnitPasses(CompileUnit &compUnit) override; 378254721Semaste 379314564Sdim void GetDescription(Stream *s) override; 380254721Semaste 381314564Sdim uint32_t GetFilterRequiredItems() override; 382254721Semaste 383314564Sdim void Dump(Stream *s) const override; 384314564Sdim 385314564Sdim void Search(Searcher &searcher) override; 386314564Sdim 387314564Sdim static lldb::SearchFilterSP 388314564Sdim CreateFromStructuredData(Target &target, 389314564Sdim const StructuredData::Dictionary &data_dict, 390321369Sdim Status &error); 391314564Sdim 392314564Sdim StructuredData::ObjectSP SerializeToStructuredData() override; 393314564Sdim 394314564Sdim void SerializeUnwrapped(StructuredData::DictionarySP &options_dict_sp); 395314564Sdim 396280031Sdimprotected: 397314564Sdim lldb::SearchFilterSP DoCopyForBreakpoint(Breakpoint &breakpoint) override; 398280031Sdim 399296417Sdimprotected: 400314564Sdim FileSpecList m_module_spec_list; 401254721Semaste}; 402254721Semaste 403314564Sdimclass SearchFilterByModuleListAndCU : public SearchFilterByModuleList { 404254721Semastepublic: 405314564Sdim /// The basic constructor takes a Target, which gives the space to search, 406314564Sdim /// and the module list to restrict the search to. 407314564Sdim SearchFilterByModuleListAndCU(const lldb::TargetSP &targetSP, 408314564Sdim const FileSpecList &module_list, 409314564Sdim const FileSpecList &cu_list); 410254721Semaste 411314564Sdim ~SearchFilterByModuleListAndCU() override; 412254721Semaste 413314564Sdim bool AddressPasses(Address &address) override; 414254721Semaste 415314564Sdim bool CompUnitPasses(FileSpec &fileSpec) override; 416254721Semaste 417314564Sdim bool CompUnitPasses(CompileUnit &compUnit) override; 418254721Semaste 419314564Sdim void GetDescription(Stream *s) override; 420254721Semaste 421314564Sdim uint32_t GetFilterRequiredItems() override; 422254721Semaste 423314564Sdim void Dump(Stream *s) const override; 424254721Semaste 425314564Sdim void Search(Searcher &searcher) override; 426314564Sdim 427314564Sdim static lldb::SearchFilterSP 428314564Sdim CreateFromStructuredData(Target &target, 429314564Sdim const StructuredData::Dictionary &data_dict, 430321369Sdim Status &error); 431314564Sdim 432314564Sdim StructuredData::ObjectSP SerializeToStructuredData() override; 433314564Sdim 434280031Sdimprotected: 435314564Sdim lldb::SearchFilterSP DoCopyForBreakpoint(Breakpoint &breakpoint) override; 436254721Semaste 437254721Semasteprivate: 438314564Sdim FileSpecList m_cu_spec_list; 439254721Semaste}; 440254721Semaste 441254721Semaste} // namespace lldb_private 442254721Semaste 443296417Sdim#endif // liblldb_SearchFilter_h_ 444