1 /* "Quick" symbol functions 2 3 Copyright (C) 2021-2024 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 /* Callback for quick_symbol_functions->map_symbol_filenames. */ 34 35 typedef void (symbol_filename_ftype) (const char *filename, 36 const char *fullname); 37 38 /* Callback for quick_symbol_functions->expand_symtabs_matching 39 to match a file name. */ 40 41 typedef bool (expand_symtabs_file_matcher_ftype) (const char *filename, 42 bool basenames); 43 44 /* Callback for quick_symbol_functions->expand_symtabs_matching 45 to match a symbol name. */ 46 47 typedef bool (expand_symtabs_symbol_matcher_ftype) (const char *name); 48 49 /* Callback for quick_symbol_functions->expand_symtabs_matching 50 to match a language. */ 51 52 typedef bool (expand_symtabs_lang_matcher_ftype) (enum language lang); 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 sorts of symbols 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_search_flags 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 /* Expand all symbol tables in OBJFILE matching some criteria. 129 130 If LANG_MATCHER returns false, expansion of the symbol table may be 131 skipped. It may also not be skipped, which the caller needs to take into 132 account. 133 134 FILE_MATCHER is called for each file in OBJFILE. The file name 135 is passed to it. If the matcher returns false, the file is 136 skipped. If FILE_MATCHER is NULL the file is not skipped. If 137 BASENAMES is true the matcher should consider only file base 138 names (the passed file name is already only the lbasename'd 139 part). 140 141 If the file is not skipped, and SYMBOL_MATCHER and LOOKUP_NAME are NULL, 142 the symbol table is expanded. 143 144 Otherwise, individual symbols are considered. 145 146 If DOMAIN does not match, the symbol is skipped. 147 148 If the symbol name does not match LOOKUP_NAME, the symbol is skipped. 149 150 If SYMBOL_MATCHER returns false, then the symbol is skipped. 151 Note that if SYMBOL_MATCHER is non-NULL, then LOOKUP_NAME must 152 also be provided. 153 154 Otherwise, the symbol's symbol table is expanded and the 155 notification function is called. If the notification function 156 returns false, execution stops and this method returns false. 157 Otherwise, more files are considered. This method will return 158 true if all calls to the notification function return true. */ 159 virtual bool expand_symtabs_matching 160 (struct objfile *objfile, 161 gdb::function_view<expand_symtabs_file_matcher_ftype> file_matcher, 162 const lookup_name_info *lookup_name, 163 gdb::function_view<expand_symtabs_symbol_matcher_ftype> symbol_matcher, 164 gdb::function_view<expand_symtabs_exp_notify_ftype> expansion_notify, 165 block_search_flags search_flags, 166 domain_search_flags domain, 167 gdb::function_view<expand_symtabs_lang_matcher_ftype> lang_matcher 168 = nullptr) = 0; 169 170 /* Return the comp unit from OBJFILE that contains PC and 171 SECTION. Return NULL if there is no such compunit. This 172 should return the compunit that contains a symbol whose 173 address exactly matches PC, or, if there is no exact match, the 174 compunit that contains a symbol whose address is closest to 175 PC. */ 176 virtual struct compunit_symtab *find_pc_sect_compunit_symtab 177 (struct objfile *objfile, bound_minimal_symbol msymbol, CORE_ADDR pc, 178 struct obj_section *section, int warn_if_readin) = 0; 179 180 /* Return the comp unit from OBJFILE that contains a symbol at 181 ADDRESS. Return NULL if there is no such comp unit. Unlike 182 find_pc_sect_compunit_symtab, any sort of symbol (not just text 183 symbols) can be considered, and only exact address matches are 184 considered. */ 185 virtual struct compunit_symtab *find_compunit_symtab_by_address 186 (struct objfile *objfile, CORE_ADDR address) = 0; 187 188 /* Call a callback for every file defined in OBJFILE whose symtab is 189 not already read in. FUN is the callback. It is passed the 190 file's FILENAME and the file's FULLNAME (if need_fullname is 191 non-zero). */ 192 virtual void map_symbol_filenames 193 (struct objfile *objfile, 194 gdb::function_view<symbol_filename_ftype> fun, 195 bool need_fullname) = 0; 196 197 /* Compute the name and language of the main function for the given 198 objfile. Normally this is done during symbol reading, but this 199 method exists in case this work is done in a worker thread and 200 must be waited for. The implementation can call 201 set_objfile_main_name if results are found. */ 202 virtual void compute_main_name (struct objfile *objfile) 203 { 204 } 205 }; 206 207 typedef std::unique_ptr<quick_symbol_functions> quick_symbol_functions_up; 208 209 #endif /* GDB_QUICK_SYMBOL_H */ 210
Indexes created Sun Jul 05 00:25:41 UTC 2026