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
20namespace lldb_private {
21class Address;
22class Breakpoint;
23class CompileUnit;
24class Status;
25class Function;
26class ModuleList;
27class SearchFilter;
28class Stream;
29class SymbolContext;
30class Target;
31}
32
33namespace 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
42class Searcher {
43public:
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
83class SearchFilter {
84public:
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
207 virtual StructuredData::ObjectSP SerializeToStructuredData() {
208 return StructuredData::ObjectSP();
209 }
210
211 static const char *GetSerializationKey() { return "SearchFilter"; }
212
213 static const char *GetSerializationSubclassKey() { return "Type"; }
214
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
229 enum FilterTy GetFilterTy() {
230 if (SubclassID > FilterTy::LastKnownFilterType)
231 return FilterTy::UnknownFilter;
232 else
233 return (enum FilterTy)SubclassID;
234 }
235
236 const char *GetFilterName() { return FilterTyToName(GetFilterTy()); }
237
238 static const char *FilterTyToName(enum FilterTy);
239
240 static FilterTy NameToFilterTy(llvm::StringRef name);
241
242protected:
243 // Serialization of SearchFilter options:
244 enum OptionNames { ModList = 0, CUList, LanguageName, LastOptionName };
245 static const char *g_option_names[LastOptionName];
246
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
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.
281private:
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.
289class SearchFilterForUnconstrainedSearches : public SearchFilter {
290public:
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
307protected:
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
314class SearchFilterByModule : public SearchFilter {
315public:
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
349protected:
350 lldb::SearchFilterSP DoCreateCopy() override;
351
352private:
353 FileSpec m_module_spec;
354};
355
356class SearchFilterByModuleList : public SearchFilter {
357public:
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
398protected:
399 lldb::SearchFilterSP DoCreateCopy() override;
400
401 FileSpecList m_module_spec_list;
402};
403
404class SearchFilterByModuleListAndCU : public SearchFilterByModuleList {
405public:
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
435protected:
436 lldb::SearchFilterSP DoCreateCopy() override;
437
438private:
439 FileSpecList m_cu_spec_list;
440};
441
442} // namespace lldb_private
443
444#endif // LLDB_CORE_SEARCHFILTER_H
445

source code of lldb/include/lldb/Core/SearchFilter.h