1 /* "Quick" symbol functions 2 3 Copyright (C) 2021-2023 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 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 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, 41 const char *fullname); 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 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. */ 58 59 typedef bool (expand_symtabs_exp_notify_ftype) (compunit_symtab *symtab); 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 { 81 virtual ~quick_symbol_functions () 82 { 83 } 84 85 /* Return true if this objfile has any "partial" symbols 86 available. */ 87 virtual bool has_symbols (struct objfile *objfile) = 0; 88 89 /* Return true if OBJFILE has any unexpanded symtabs. A return value of 90 false indicates there are no unexpanded symtabs, this might mean that 91 all of the symtabs have been expanded (full debug has been read in), 92 or it might been that OBJFILE has no debug information. */ 93 virtual bool has_unexpanded_symtabs (struct objfile *objfile) = 0; 94 95 /* Return the symbol table for the "last" file appearing in 96 OBJFILE. */ 97 virtual struct symtab *find_last_source_symtab (struct objfile *objfile) = 0; 98 99 /* Forget all cached full file names for OBJFILE. */ 100 virtual void forget_cached_source_info (struct objfile *objfile) = 0; 101 102 /* Check to see if the global symbol is defined in a "partial" symbol table 103 of OBJFILE. NAME is the name of the symbol to look for. DOMAIN 104 indicates what sort of symbol to search for. 105 106 If found, sets *symbol_found_p to true and returns the symbol language. 107 defined, or NULL if no such symbol table exists. */ 108 virtual enum language lookup_global_symbol_language 109 (struct objfile *objfile, 110 const char *name, 111 domain_enum domain, 112 bool *symbol_found_p) = 0; 113 114 /* Print statistics about any indices loaded for OBJFILE. The 115 statistics should be printed to gdb_stdout. This is used for 116 "maint print statistics". Statistics are printed in two 117 sections. PRINT_BCACHE is false when printing the first section 118 of general statistics, and true when printing bcache statistics. */ 119 virtual void print_stats (struct objfile *objfile, bool print_bcache) = 0; 120 121 /* Dump any indices loaded for OBJFILE. The dump should go to 122 gdb_stdout. This is used for "maint print objfiles". */ 123 virtual void dump (struct objfile *objfile) = 0; 124 125 /* Read all symbol tables associated with OBJFILE. */ 126 virtual void expand_all_symtabs (struct objfile *objfile) = 0; 127 128 /* Find global or static symbols in all tables that are in DOMAIN 129 and for which MATCH (symbol name, NAME) == 0, reading in partial 130 symbol tables as needed. Look through global symbols if GLOBAL 131 and otherwise static symbols. 132 133 MATCH must be weaker than strcmp_iw_ordered in the sense that 134 strcmp_iw_ordered(x,y) == 0 --> MATCH(x,y) == 0. ORDERED_COMPARE, 135 if non-null, must be an ordering relation compatible with 136 strcmp_iw_ordered in the sense that 137 strcmp_iw_ordered(x,y) == 0 --> ORDERED_COMPARE(x,y) == 0 138 and 139 strcmp_iw_ordered(x,y) <= 0 --> ORDERED_COMPARE(x,y) <= 0 140 (allowing strcmp_iw_ordered(x,y) < 0 while ORDERED_COMPARE(x, y) == 0). 141 */ 142 143 virtual void expand_matching_symbols 144 (struct objfile *, 145 const lookup_name_info &lookup_name, 146 domain_enum domain, 147 int global, 148 symbol_compare_ftype *ordered_compare) = 0; 149 150 /* Expand all symbol tables in OBJFILE matching some criteria. 151 152 FILE_MATCHER is called for each file in OBJFILE. The file name 153 is passed to it. If the matcher returns false, the file is 154 skipped. If FILE_MATCHER is NULL the file is not skipped. If 155 BASENAMES is true the matcher should consider only file base 156 names (the passed file name is already only the lbasename'd 157 part). 158 159 If the file is not skipped, and SYMBOL_MATCHER and LOOKUP_NAME are NULL, 160 the symbol table is expanded. 161 162 Otherwise, individual symbols are considered. 163 164 If DOMAIN or KIND do not match, the symbol is skipped. 165 If DOMAIN is UNDEF_DOMAIN, that is treated as a wildcard. 166 167 If the symbol name does not match LOOKUP_NAME, the symbol is skipped. 168 169 If SYMBOL_MATCHER returns false, then the symbol is skipped. 170 Note that if SYMBOL_MATCHER is non-NULL, then LOOKUP_NAME must 171 also be provided. 172 173 Otherwise, the symbol's symbol table is expanded and the 174 notification function is called. If the notification function 175 returns false, execution stops and this method returns false. 176 Otherwise, more files are considered. This method will return 177 true if all calls to the notification function return true. */ 178 virtual bool expand_symtabs_matching 179 (struct objfile *objfile, 180 gdb::function_view<expand_symtabs_file_matcher_ftype> file_matcher, 181 const lookup_name_info *lookup_name, 182 gdb::function_view<expand_symtabs_symbol_matcher_ftype> symbol_matcher, 183 gdb::function_view<expand_symtabs_exp_notify_ftype> expansion_notify, 184 block_search_flags search_flags, 185 domain_enum domain, 186 enum search_domain kind) = 0; 187 188 /* Return the comp unit from OBJFILE that contains PC and 189 SECTION. Return NULL if there is no such compunit. This 190 should return the compunit that contains a symbol whose 191 address exactly matches PC, or, if there is no exact match, the 192 compunit that contains a symbol whose address is closest to 193 PC. */ 194 virtual struct compunit_symtab *find_pc_sect_compunit_symtab 195 (struct objfile *objfile, struct bound_minimal_symbol msymbol, 196 CORE_ADDR pc, struct obj_section *section, int warn_if_readin) = 0; 197 198 /* Return the comp unit from OBJFILE that contains a symbol at 199 ADDRESS. Return NULL if there is no such comp unit. Unlike 200 find_pc_sect_compunit_symtab, any sort of symbol (not just text 201 symbols) can be considered, and only exact address matches are 202 considered. */ 203 virtual struct compunit_symtab *find_compunit_symtab_by_address 204 (struct objfile *objfile, CORE_ADDR address) = 0; 205 206 /* Call a callback for every file defined in OBJFILE whose symtab is 207 not already read in. FUN is the callback. It is passed the 208 file's FILENAME and the file's FULLNAME (if need_fullname is 209 non-zero). */ 210 virtual void map_symbol_filenames 211 (struct objfile *objfile, 212 gdb::function_view<symbol_filename_ftype> fun, 213 bool need_fullname) = 0; 214 215 /* This is called when the objfile is relocated. It can be used to 216 clean up any internal caches. */ 217 virtual void relocated () 218 { 219 /* Do nothing. */ 220 } 221 222 /* Return true if this class can lazily read the symbols. This may 223 only return true if there are in fact symbols to be read, because 224 this is used in the implementation of 'has_partial_symbols'. */ 225 virtual bool can_lazily_read_symbols () 226 { 227 return false; 228 } 229 230 /* Read the partial symbols for OBJFILE. This will only ever be 231 called if can_lazily_read_symbols returns true. */ 232 virtual void read_partial_symbols (struct objfile *objfile) 233 { 234 } 235 }; 236 237 typedef std::unique_ptr<quick_symbol_functions> quick_symbol_functions_up; 238 239 #endif /* GDB_QUICK_SYMBOL_H */ 240