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