Commit | Line | Data |
---|---|---|
9b99dcc8 TT |
1 | /* "Quick" symbol functions |
2 | ||
3 | Copyright (C) 2021 Free Software Foundation, Inc. | |
4 | ||
5 | This file is part of GDB. | |
6 | ||
7 | This program is free software; you can redistribute it and/or modify | |
8 | it under the terms of the GNU General Public License as published by | |
9 | the Free Software Foundation; either version 3 of the License, or | |
10 | (at your option) any later version. | |
11 | ||
12 | This program is distributed in the hope that it will be useful, | |
13 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
15 | GNU General Public License for more details. | |
16 | ||
17 | You should have received a copy of the GNU General Public License | |
18 | along with this program. If not, see <http://www.gnu.org/licenses/>. */ | |
19 | ||
20 | #ifndef GDB_QUICK_SYMBOL_H | |
21 | #define GDB_QUICK_SYMBOL_H | |
22 | ||
e357e990 TT |
23 | /* Like block_enum, but used as flags to pass to lookup functions. */ |
24 | ||
25 | enum block_search_flag_values | |
26 | { | |
27 | SEARCH_GLOBAL_BLOCK = 1, | |
28 | SEARCH_STATIC_BLOCK = 2 | |
29 | }; | |
30 | ||
31 | DEF_ENUM_FLAGS_TYPE (enum block_search_flag_values, block_search_flags); | |
32 | ||
9b99dcc8 TT |
33 | /* Comparison function for symbol look ups. */ |
34 | ||
35 | typedef int (symbol_compare_ftype) (const char *string1, | |
36 | const char *string2); | |
37 | ||
38 | /* Callback for quick_symbol_functions->map_symbol_filenames. */ | |
39 | ||
40 | typedef void (symbol_filename_ftype) (const char *filename, | |
f4655dee | 41 | const char *fullname); |
9b99dcc8 TT |
42 | |
43 | /* Callback for quick_symbol_functions->expand_symtabs_matching | |
44 | to match a file name. */ | |
45 | ||
46 | typedef bool (expand_symtabs_file_matcher_ftype) (const char *filename, | |
47 | bool basenames); | |
48 | ||
49 | /* Callback for quick_symbol_functions->expand_symtabs_matching | |
50 | to match a symbol name. */ | |
51 | ||
52 | typedef bool (expand_symtabs_symbol_matcher_ftype) (const char *name); | |
53 | ||
54 | /* Callback for quick_symbol_functions->expand_symtabs_matching | |
df35e626 TT |
55 | to be called after a symtab has been expanded. If this returns |
56 | true, more symtabs are checked; if it returns false, iteration | |
57 | stops. */ | |
9b99dcc8 | 58 | |
df35e626 | 59 | typedef bool (expand_symtabs_exp_notify_ftype) (compunit_symtab *symtab); |
9b99dcc8 TT |
60 | |
61 | /* The "quick" symbol functions exist so that symbol readers can | |
62 | avoiding an initial read of all the symbols. For example, symbol | |
63 | readers might choose to use the "partial symbol table" utilities, | |
64 | which is one implementation of the quick symbol functions. | |
65 | ||
66 | The quick symbol functions are generally opaque: the underlying | |
67 | representation is hidden from the caller. | |
68 | ||
69 | In general, these functions should only look at whatever special | |
70 | index the symbol reader creates -- looking through the symbol | |
71 | tables themselves is handled by generic code. If a function is | |
72 | defined as returning a "symbol table", this means that the function | |
73 | should only return a newly-created symbol table; it should not | |
74 | examine pre-existing ones. | |
75 | ||
76 | The exact list of functions here was determined in an ad hoc way | |
77 | based on gdb's history. */ | |
78 | ||
79 | struct quick_symbol_functions | |
80 | { | |
39298a5d TT |
81 | virtual ~quick_symbol_functions () |
82 | { | |
83 | } | |
84 | ||
9b99dcc8 TT |
85 | /* Return true if this objfile has any "partial" symbols |
86 | available. */ | |
39298a5d | 87 | virtual bool has_symbols (struct objfile *objfile) = 0; |
9b99dcc8 TT |
88 | |
89 | /* Return the symbol table for the "last" file appearing in | |
90 | OBJFILE. */ | |
39298a5d | 91 | virtual struct symtab *find_last_source_symtab (struct objfile *objfile) = 0; |
9b99dcc8 TT |
92 | |
93 | /* Forget all cached full file names for OBJFILE. */ | |
39298a5d | 94 | virtual void forget_cached_source_info (struct objfile *objfile) = 0; |
9b99dcc8 TT |
95 | |
96 | /* Expand and iterate over each "partial" symbol table in OBJFILE | |
97 | where the source file is named NAME. | |
98 | ||
99 | If NAME is not absolute, a match after a '/' in the symbol table's | |
100 | file name will also work, REAL_PATH is NULL then. If NAME is | |
101 | absolute then REAL_PATH is non-NULL absolute file name as resolved | |
102 | via gdb_realpath from NAME. | |
103 | ||
104 | If a match is found, the "partial" symbol table is expanded. | |
105 | Then, this calls iterate_over_some_symtabs (or equivalent) over | |
106 | all newly-created symbol tables, passing CALLBACK to it. | |
107 | The result of this call is returned. */ | |
39298a5d | 108 | virtual bool map_symtabs_matching_filename |
9b99dcc8 | 109 | (struct objfile *objfile, const char *name, const char *real_path, |
39298a5d | 110 | gdb::function_view<bool (symtab *)> callback) = 0; |
9b99dcc8 TT |
111 | |
112 | /* Check to see if the symbol is defined in a "partial" symbol table | |
113 | of OBJFILE. BLOCK_INDEX should be either GLOBAL_BLOCK or STATIC_BLOCK, | |
114 | depending on whether we want to search global symbols or static | |
115 | symbols. NAME is the name of the symbol to look for. DOMAIN | |
116 | indicates what sort of symbol to search for. | |
117 | ||
118 | Returns the newly-expanded compunit in which the symbol is | |
119 | defined, or NULL if no such symbol table exists. If OBJFILE | |
120 | contains !TYPE_OPAQUE symbol prefer its compunit. If it contains | |
121 | only TYPE_OPAQUE symbol(s), return at least that compunit. */ | |
39298a5d TT |
122 | virtual struct compunit_symtab *lookup_symbol (struct objfile *objfile, |
123 | block_enum block_index, | |
124 | const char *name, | |
125 | domain_enum domain) = 0; | |
9b99dcc8 TT |
126 | |
127 | /* Check to see if the global symbol is defined in a "partial" symbol table | |
128 | of OBJFILE. NAME is the name of the symbol to look for. DOMAIN | |
129 | indicates what sort of symbol to search for. | |
130 | ||
131 | If found, sets *symbol_found_p to true and returns the symbol language. | |
132 | defined, or NULL if no such symbol table exists. */ | |
39298a5d TT |
133 | virtual enum language lookup_global_symbol_language |
134 | (struct objfile *objfile, | |
135 | const char *name, | |
136 | domain_enum domain, | |
137 | bool *symbol_found_p) = 0; | |
9b99dcc8 TT |
138 | |
139 | /* Print statistics about any indices loaded for OBJFILE. The | |
140 | statistics should be printed to gdb_stdout. This is used for | |
4829711b TT |
141 | "maint print statistics". Statistics are printed in two |
142 | sections. PRINT_BCACHE is false when printing the first section | |
143 | of general statistics, and true when printing bcache statistics. */ | |
144 | virtual void print_stats (struct objfile *objfile, bool print_bcache) = 0; | |
9b99dcc8 TT |
145 | |
146 | /* Dump any indices loaded for OBJFILE. The dump should go to | |
147 | gdb_stdout. This is used for "maint print objfiles". */ | |
39298a5d | 148 | virtual void dump (struct objfile *objfile) = 0; |
9b99dcc8 TT |
149 | |
150 | /* Find all the symbols in OBJFILE named FUNC_NAME, and ensure that | |
151 | the corresponding symbol tables are loaded. */ | |
39298a5d TT |
152 | virtual void expand_symtabs_for_function (struct objfile *objfile, |
153 | const char *func_name) = 0; | |
9b99dcc8 TT |
154 | |
155 | /* Read all symbol tables associated with OBJFILE. */ | |
39298a5d | 156 | virtual void expand_all_symtabs (struct objfile *objfile) = 0; |
9b99dcc8 TT |
157 | |
158 | /* Read all symbol tables associated with OBJFILE which have | |
159 | symtab_to_fullname equal to FULLNAME. | |
160 | This is for the purposes of examining code only, e.g., expand_line_sal. | |
161 | The routine may ignore debug info that is known to not be useful with | |
162 | code, e.g., DW_TAG_type_unit for dwarf debug info. */ | |
39298a5d TT |
163 | virtual void expand_symtabs_with_fullname (struct objfile *objfile, |
164 | const char *fullname) = 0; | |
9b99dcc8 TT |
165 | |
166 | /* Find global or static symbols in all tables that are in DOMAIN | |
167 | and for which MATCH (symbol name, NAME) == 0, passing each to | |
168 | CALLBACK, reading in partial symbol tables as needed. Look | |
169 | through global symbols if GLOBAL and otherwise static symbols. | |
170 | Passes NAME and NAMESPACE to CALLBACK with each symbol | |
171 | found. After each block is processed, passes NULL to CALLBACK. | |
172 | MATCH must be weaker than strcmp_iw_ordered in the sense that | |
173 | strcmp_iw_ordered(x,y) == 0 --> MATCH(x,y) == 0. ORDERED_COMPARE, | |
174 | if non-null, must be an ordering relation compatible with | |
175 | strcmp_iw_ordered in the sense that | |
176 | strcmp_iw_ordered(x,y) == 0 --> ORDERED_COMPARE(x,y) == 0 | |
177 | and | |
178 | strcmp_iw_ordered(x,y) <= 0 --> ORDERED_COMPARE(x,y) <= 0 | |
179 | (allowing strcmp_iw_ordered(x,y) < 0 while ORDERED_COMPARE(x, y) == 0). | |
180 | CALLBACK returns true to indicate that the scan should continue, or | |
181 | false to indicate that the scan should be terminated. */ | |
182 | ||
39298a5d | 183 | virtual void map_matching_symbols |
9b99dcc8 TT |
184 | (struct objfile *, |
185 | const lookup_name_info &lookup_name, | |
186 | domain_enum domain, | |
187 | int global, | |
188 | gdb::function_view<symbol_found_callback_ftype> callback, | |
39298a5d | 189 | symbol_compare_ftype *ordered_compare) = 0; |
9b99dcc8 TT |
190 | |
191 | /* Expand all symbol tables in OBJFILE matching some criteria. | |
192 | ||
193 | FILE_MATCHER is called for each file in OBJFILE. The file name | |
194 | is passed to it. If the matcher returns false, the file is | |
195 | skipped. If FILE_MATCHER is NULL the file is not skipped. If | |
196 | BASENAMES is true the matcher should consider only file base | |
197 | names (the passed file name is already only the lbasename'd | |
198 | part). | |
199 | ||
200 | If the file is not skipped, and SYMBOL_MATCHER and LOOKUP_NAME are NULL, | |
201 | the symbol table is expanded. | |
202 | ||
203 | Otherwise, individual symbols are considered. | |
204 | ||
3bfa51a7 TT |
205 | If DOMAIN or KIND do not match, the symbol is skipped. |
206 | If DOMAIN is UNDEF_DOMAIN, that is treated as a wildcard. | |
9b99dcc8 TT |
207 | |
208 | If the symbol name does not match LOOKUP_NAME, the symbol is skipped. | |
209 | ||
210 | If SYMBOL_MATCHER returns false, then the symbol is skipped. | |
211 | ||
df35e626 TT |
212 | Otherwise, the symbol's symbol table is expanded and the |
213 | notification function is called. If the notification function | |
214 | returns false, execution stops and this method returns false. | |
215 | Otherwise, more files are considered. This method will return | |
216 | true if all calls to the notification function return true. */ | |
217 | virtual bool expand_symtabs_matching | |
9b99dcc8 TT |
218 | (struct objfile *objfile, |
219 | gdb::function_view<expand_symtabs_file_matcher_ftype> file_matcher, | |
220 | const lookup_name_info *lookup_name, | |
221 | gdb::function_view<expand_symtabs_symbol_matcher_ftype> symbol_matcher, | |
222 | gdb::function_view<expand_symtabs_exp_notify_ftype> expansion_notify, | |
03a8ea51 | 223 | block_search_flags search_flags, |
3bfa51a7 | 224 | domain_enum domain, |
39298a5d | 225 | enum search_domain kind) = 0; |
9b99dcc8 TT |
226 | |
227 | /* Return the comp unit from OBJFILE that contains PC and | |
228 | SECTION. Return NULL if there is no such compunit. This | |
229 | should return the compunit that contains a symbol whose | |
230 | address exactly matches PC, or, if there is no exact match, the | |
231 | compunit that contains a symbol whose address is closest to | |
232 | PC. */ | |
39298a5d | 233 | virtual struct compunit_symtab *find_pc_sect_compunit_symtab |
9b99dcc8 | 234 | (struct objfile *objfile, struct bound_minimal_symbol msymbol, |
39298a5d | 235 | CORE_ADDR pc, struct obj_section *section, int warn_if_readin) = 0; |
9b99dcc8 TT |
236 | |
237 | /* Return the comp unit from OBJFILE that contains a symbol at | |
238 | ADDRESS. Return NULL if there is no such comp unit. Unlike | |
239 | find_pc_sect_compunit_symtab, any sort of symbol (not just text | |
240 | symbols) can be considered, and only exact address matches are | |
39298a5d TT |
241 | considered. */ |
242 | virtual struct compunit_symtab *find_compunit_symtab_by_address | |
243 | (struct objfile *objfile, CORE_ADDR address) = 0; | |
9b99dcc8 TT |
244 | |
245 | /* Call a callback for every file defined in OBJFILE whose symtab is | |
f4655dee TT |
246 | not already read in. FUN is the callback. It is passed the |
247 | file's FILENAME and the file's FULLNAME (if need_fullname is | |
248 | non-zero). */ | |
249 | virtual void map_symbol_filenames | |
250 | (struct objfile *objfile, | |
251 | gdb::function_view<symbol_filename_ftype> fun, | |
252 | bool need_fullname) = 0; | |
75336a5a TT |
253 | |
254 | /* This is called when the objfile is relocated. It can be used to | |
255 | clean up any internal caches. */ | |
256 | virtual void relocated () | |
257 | { | |
258 | /* Do nothing. */ | |
259 | } | |
eb00e468 TT |
260 | |
261 | /* Return true if this class can lazily read the symbols. This may | |
262 | only return true if there are in fact symbols to be read, because | |
263 | this is used in the implementation of 'has_partial_symbols'. */ | |
264 | virtual bool can_lazily_read_symbols () | |
265 | { | |
266 | return false; | |
267 | } | |
268 | ||
269 | /* Read the partial symbols for OBJFILE. This will only ever be | |
270 | called if can_lazily_read_symbols returns true. */ | |
271 | virtual void read_partial_symbols (struct objfile *objfile) | |
272 | { | |
273 | } | |
9b99dcc8 TT |
274 | }; |
275 | ||
39298a5d TT |
276 | typedef std::unique_ptr<quick_symbol_functions> quick_symbol_functions_up; |
277 | ||
9b99dcc8 | 278 | #endif /* GDB_QUICK_SYMBOL_H */ |