1 /* Minimal symbol table definitions for GDB. 2 3 Copyright (C) 2011-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 MINSYMS_H 21 #define MINSYMS_H 22 23 struct type; 24 25 /* Several lookup functions return both a minimal symbol and the 26 objfile in which it is found. This structure is used in these 27 cases. */ 28 29 struct bound_minimal_symbol 30 { bound_minimal_symbolbound_minimal_symbol31 bound_minimal_symbol (struct minimal_symbol *msym, struct objfile *objf) 32 : minsym (msym), 33 objfile (objf) 34 { 35 } 36 37 bound_minimal_symbol () = default; 38 39 /* Return the address of the minimal symbol in the context of the objfile. */ 40 value_addressbound_minimal_symbol41 CORE_ADDR value_address () const 42 { 43 return this->minsym->value_address (this->objfile); 44 } 45 46 /* The minimal symbol that was found, or NULL if no minimal symbol 47 was found. */ 48 49 struct minimal_symbol *minsym = nullptr; 50 51 /* If MINSYM is not NULL, then this is the objfile in which the 52 symbol is defined. */ 53 54 struct objfile *objfile = nullptr; 55 56 /* Return the obj_section from OBJFILE for MINSYM. */ 57 obj_sectionbound_minimal_symbol58 struct obj_section *obj_section () const 59 { 60 return minsym->obj_section (objfile); 61 } 62 }; 63 64 /* This header declares most of the API for dealing with minimal 65 symbols and minimal symbol tables. A few things are declared 66 elsewhere; see below. 67 68 A minimal symbol is a symbol for which there is no direct debug 69 information. For example, for an ELF binary, minimal symbols are 70 created from the ELF symbol table. 71 72 For the definition of the minimal symbol structure, see struct 73 minimal_symbol in symtab.h. 74 75 Minimal symbols are stored in tables attached to an objfile; see 76 objfiles.h for details. Code should generally treat these tables 77 as opaque and use functions provided by minsyms.c to inspect them. 78 */ 79 80 struct msym_bunch; 81 82 /* An RAII-based object that is used to record minimal symbols while 83 they are being read. */ 84 class minimal_symbol_reader 85 { 86 public: 87 88 /* Prepare to start collecting minimal symbols. This should be 89 called by a symbol reader to initialize the minimal symbol 90 module. */ 91 92 explicit minimal_symbol_reader (struct objfile *); 93 94 ~minimal_symbol_reader (); 95 96 /* Install the minimal symbols that have been collected into the 97 given objfile. */ 98 99 void install (); 100 101 /* Record a new minimal symbol. This is the "full" entry point; 102 simpler convenience entry points are also provided below. 103 104 This returns a new minimal symbol. It is ok to modify the returned 105 minimal symbol (though generally not necessary). It is not ok, 106 though, to stash the pointer anywhere; as minimal symbols may be 107 moved after creation. The memory for the returned minimal symbol 108 is still owned by the minsyms.c code, and should not be freed. 109 110 Arguments are: 111 112 NAME - the symbol's name 113 COPY_NAME - if true, the minsym code must make a copy of NAME. If 114 false, then NAME must be NUL-terminated, and must have a lifetime 115 that is at least as long as OBJFILE's lifetime. 116 ADDRESS - the address of the symbol 117 MS_TYPE - the type of the symbol 118 SECTION - the symbol's section 119 */ 120 121 struct minimal_symbol *record_full (std::string_view name, 122 bool copy_name, 123 unrelocated_addr address, 124 enum minimal_symbol_type ms_type, 125 int section); 126 127 /* Like record_full, but: 128 - computes the length of NAME 129 - passes COPY_NAME = true, 130 - and passes a default SECTION, depending on the type 131 132 This variant does not return the new symbol. */ 133 134 void record (const char *name, unrelocated_addr address, 135 enum minimal_symbol_type ms_type); 136 137 /* Like record_full, but: 138 - computes the length of NAME 139 - passes COPY_NAME = true. 140 141 This variant does not return the new symbol. */ 142 record_with_info(const char * name,unrelocated_addr address,enum minimal_symbol_type ms_type,int section)143 void record_with_info (const char *name, unrelocated_addr address, 144 enum minimal_symbol_type ms_type, 145 int section) 146 { 147 record_full (name, true, address, ms_type, section); 148 } 149 150 private: 151 152 DISABLE_COPY_AND_ASSIGN (minimal_symbol_reader); 153 154 struct objfile *m_objfile; 155 156 /* Bunch currently being filled up. 157 The next field points to chain of filled bunches. */ 158 159 struct msym_bunch *m_msym_bunch; 160 161 /* Number of slots filled in current bunch. */ 162 163 int m_msym_bunch_index; 164 165 /* Total number of minimal symbols recorded so far for the 166 objfile. */ 167 168 int m_msym_count; 169 }; 170 171 172 173 /* Return whether MSYMBOL is a function/method. If FUNC_ADDRESS_P is 174 non-NULL, and the MSYMBOL is a function, then *FUNC_ADDRESS_P is 175 set to the function's address, already resolved if MINSYM points to 176 a function descriptor. */ 177 178 bool msymbol_is_function (struct objfile *objfile, 179 minimal_symbol *minsym, 180 CORE_ADDR *func_address_p = NULL); 181 182 /* Compute a hash code for the string argument. Unlike htab_hash_string, 183 this is a case-insensitive hash to support "set case-sensitive off". */ 184 185 unsigned int msymbol_hash (const char *); 186 187 /* Like msymbol_hash, but compute a hash code that is compatible with 188 strcmp_iw. */ 189 190 unsigned int msymbol_hash_iw (const char *); 191 192 /* Compute the next hash value from previous HASH and the character C. This 193 is only a GDB in-memory computed value with no external files compatibility 194 requirements. */ 195 196 #define SYMBOL_HASH_NEXT(hash, c) \ 197 ((hash) * 67 + TOLOWER ((unsigned char) (c)) - 113) 198 199 200 201 /* Look through all the current minimal symbol tables and find the 202 first minimal symbol that matches NAME. If OBJF is non-NULL, limit 203 the search to that objfile. If SFILE is non-NULL, the only 204 file-scope symbols considered will be from that source file (global 205 symbols are still preferred). Returns a bound minimal symbol that 206 matches, or an empty bound minimal symbol if no match is found. */ 207 208 struct bound_minimal_symbol lookup_minimal_symbol (const char *, 209 const char *, 210 struct objfile *); 211 212 /* Like lookup_minimal_symbol, but searches all files and 213 objfiles. */ 214 215 struct bound_minimal_symbol lookup_bound_minimal_symbol (const char *); 216 217 /* Look through all the current minimal symbol tables and find the 218 first minimal symbol that matches NAME and has text type. If OBJF 219 is non-NULL, limit the search to that objfile. Returns a bound 220 minimal symbol that matches, or an "empty" bound minimal symbol 221 otherwise. 222 223 This function only searches the mangled (linkage) names. */ 224 225 struct bound_minimal_symbol lookup_minimal_symbol_text (const char *, 226 struct objfile *); 227 228 /* Look through the minimal symbols in OBJF (and its separate debug 229 objfiles) for a global (not file-local) minsym whose linkage name 230 is NAME. This is somewhat similar to lookup_minimal_symbol_text, 231 only data symbols (not text symbols) are considered, and a non-NULL 232 objfile is not accepted. Returns a bound minimal symbol that 233 matches, or an "empty" bound minimal symbol otherwise. */ 234 235 extern struct bound_minimal_symbol lookup_minimal_symbol_linkage 236 (const char *name, struct objfile *objf) 237 ATTRIBUTE_NONNULL (1) ATTRIBUTE_NONNULL (2); 238 239 /* A variant of lookup_minimal_symbol_linkage that iterates over all 240 objfiles. If ONLY_MAIN is true, then only an objfile with 241 OBJF_MAINLINE will be considered. */ 242 243 extern struct bound_minimal_symbol lookup_minimal_symbol_linkage 244 (const char *name, bool only_main) 245 ATTRIBUTE_NONNULL (1); 246 247 /* Look through all the current minimal symbol tables and find the 248 first minimal symbol that matches NAME and PC. If OBJF is non-NULL, 249 limit the search to that objfile. Returns a pointer to the minimal 250 symbol that matches, or NULL if no match is found. */ 251 252 struct minimal_symbol *lookup_minimal_symbol_by_pc_name 253 (CORE_ADDR, const char *, struct objfile *); 254 255 enum class lookup_msym_prefer 256 { 257 /* Prefer mst_text symbols. */ 258 TEXT, 259 260 /* Prefer mst_solib_trampoline symbols when there are text and 261 trampoline symbols at the same address. Otherwise prefer 262 mst_text symbols. */ 263 TRAMPOLINE, 264 265 /* Prefer mst_text_gnu_ifunc symbols when there are text and ifunc 266 symbols at the same address. Otherwise prefer mst_text 267 symbols. */ 268 GNU_IFUNC, 269 }; 270 271 /* Search through the minimal symbol table for each objfile and find 272 the symbol whose address is the largest address that is still less 273 than or equal to PC_IN, and which matches SECTION. A matching symbol 274 must either be zero sized and have address PC_IN, or PC_IN must fall 275 within the range of addresses covered by the matching symbol. 276 277 If SECTION is NULL, this uses the result of find_pc_section 278 instead. 279 280 The result has a non-NULL 'minsym' member if such a symbol is 281 found, or NULL if PC is not in a suitable range. 282 283 See definition of lookup_msym_prefer for description of PREFER. By 284 default mst_text symbols are preferred. 285 286 If the PREVIOUS pointer is non-NULL, and no matching symbol is found, 287 then the contents will be set to reference the closest symbol before 288 PC_IN. */ 289 290 struct bound_minimal_symbol lookup_minimal_symbol_by_pc_section 291 (CORE_ADDR pc_in, 292 struct obj_section *section, 293 lookup_msym_prefer prefer = lookup_msym_prefer::TEXT, 294 bound_minimal_symbol *previous = nullptr); 295 296 /* Backward compatibility: search through the minimal symbol table 297 for a matching PC (no section given). 298 299 This is a wrapper that calls lookup_minimal_symbol_by_pc_section 300 with a NULL section argument. */ 301 302 struct bound_minimal_symbol lookup_minimal_symbol_by_pc (CORE_ADDR); 303 304 /* Iterate over all the minimal symbols in the objfile OBJF which 305 match NAME. Both the ordinary and demangled names of each symbol 306 are considered. The caller is responsible for canonicalizing NAME, 307 should that need to be done. 308 309 For each matching symbol, CALLBACK is called with the symbol. */ 310 311 void iterate_over_minimal_symbols 312 (struct objfile *objf, const lookup_name_info &name, 313 gdb::function_view<bool (struct minimal_symbol *)> callback); 314 315 /* Compute the upper bound of MINSYM. The upper bound is the last 316 address thought to be part of the symbol. If the symbol has a 317 size, it is used. Otherwise use the lesser of the next minimal 318 symbol in the same section, or the end of the section, as the end 319 of the function. */ 320 321 CORE_ADDR minimal_symbol_upper_bound (struct bound_minimal_symbol minsym); 322 323 /* Return the type of MSYMBOL, a minimal symbol of OBJFILE. If 324 ADDRESS_P is not NULL, set it to the MSYMBOL's resolved 325 address. */ 326 327 type *find_minsym_type_and_address (minimal_symbol *msymbol, objfile *objf, 328 CORE_ADDR *address_p); 329 330 #endif /* MINSYMS_H */ 331