From: Tom Tromey Date: Thu, 22 Dec 2011 02:34:34 +0000 (+0000) Subject: * minsyms.h: Rearrange. Document header and all functions. X-Git-Tag: sid-snapshot-20120101~47 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=b19686e08b06fc87494cc72e9df6d5993401831a;p=platform%2Fupstream%2Fbinutils.git * minsyms.h: Rearrange. Document header and all functions. * minsyms.c: Move some comments to minsyms.h. --- diff --git a/gdb/ChangeLog b/gdb/ChangeLog index 5bcccf6..8b6b718 100644 --- a/gdb/ChangeLog +++ b/gdb/ChangeLog @@ -1,5 +1,10 @@ 2011-12-21 Tom Tromey + * minsyms.h: Rearrange. Document header and all functions. + * minsyms.c: Move some comments to minsyms.h. + +2011-12-21 Tom Tromey + * symtab.h: Include minsyms.h. (prim_record_minimal_symbol, prim_record_minimal_symbol_full) (prim_record_minimal_symbol_and_info, msymbol_hash_iw) diff --git a/gdb/minsyms.c b/gdb/minsyms.c index 18cf672..0d2f5de 100644 --- a/gdb/minsyms.c +++ b/gdb/minsyms.c @@ -78,7 +78,7 @@ static int msym_bunch_index; static int msym_count; -/* Compute a hash code based using the same criteria as `strcmp_iw'. */ +/* See minsyms.h. */ unsigned int msymbol_hash_iw (const char *string) @@ -98,7 +98,7 @@ msymbol_hash_iw (const char *string) return hash; } -/* Compute a hash code for a string. */ +/* See minsyms.h. */ unsigned int msymbol_hash (const char *string) @@ -141,8 +141,8 @@ add_minsym_to_demangled_hash_table (struct minimal_symbol *sym, } } +/* See minsyms.h. */ -/* Return OBJFILE where minimal symbol SYM is defined. */ struct objfile * msymbol_objfile (struct minimal_symbol *sym) { @@ -310,13 +310,7 @@ lookup_minimal_symbol (const char *name, const char *sfile, return NULL; } -/* Iterate over all the minimal symbols in the objfile OBJF which - match NAME. Both the ordinary and demangled names of each symbol - are considered. The caller is responsible for canonicalizing NAME, - should that need to be done. - - For each matching symbol, CALLBACK is called with the symbol and - USER_DATA as arguments. */ +/* See minsyms.h. */ void iterate_over_minimal_symbols (struct objfile *objf, const char *name, @@ -350,12 +344,7 @@ iterate_over_minimal_symbols (struct objfile *objf, const char *name, } } -/* Look through all the current minimal symbol tables and find the - first minimal symbol that matches NAME and has text type. If OBJF - is non-NULL, limit the search to that objfile. Returns a pointer - to the minimal symbol that matches, or NULL if no match is found. - - This function only searches the mangled (linkage) names. */ +/* See minsyms.h. */ struct minimal_symbol * lookup_minimal_symbol_text (const char *name, struct objfile *objf) @@ -407,10 +396,7 @@ lookup_minimal_symbol_text (const char *name, struct objfile *objf) return NULL; } -/* Look through all the current minimal symbol tables and find the - first minimal symbol that matches NAME and PC. If OBJF is non-NULL, - limit the search to that objfile. Returns a pointer to the minimal - symbol that matches, or NULL if no match is found. */ +/* See minsyms.h. */ struct minimal_symbol * lookup_minimal_symbol_by_pc_name (CORE_ADDR pc, const char *name, @@ -442,13 +428,7 @@ lookup_minimal_symbol_by_pc_name (CORE_ADDR pc, const char *name, return NULL; } -/* Look through all the current minimal symbol tables and find the - first minimal symbol that matches NAME and is a solib trampoline. - If OBJF is non-NULL, limit the search to that objfile. Returns a - pointer to the minimal symbol that matches, or NULL if no match is - found. - - This function only searches the mangled (linkage) names. */ +/* See minsyms.h. */ struct minimal_symbol * lookup_minimal_symbol_solib_trampoline (const char *name, @@ -734,8 +714,7 @@ lookup_minimal_symbol_by_pc_section (CORE_ADDR pc, struct obj_section *section) return lookup_minimal_symbol_by_pc_section_1 (pc, section, 0); } -/* Backward compatibility: search through the minimal symbol table - for a matching PC (no section given). */ +/* See minsyms.h. */ struct minimal_symbol * lookup_minimal_symbol_by_pc (CORE_ADDR pc) @@ -806,10 +785,7 @@ static const struct gnu_ifunc_fns stub_gnu_ifunc_fns = const struct gnu_ifunc_fns *gnu_ifunc_fns_p = &stub_gnu_ifunc_fns; -/* Find the minimal symbol named NAME, and return both the minsym - struct and its objfile. This only checks the linkage name. Sets - *OBJFILE_P and returns the minimal symbol, if it is found. If it - is not found, returns NULL. */ +/* See minsyms.h. */ struct minimal_symbol * lookup_minimal_symbol_and_objfile (const char *name, @@ -853,18 +829,21 @@ get_symbol_leading_char (bfd *abfd) return 0; } -/* Prepare to start collecting minimal symbols. Note that presetting - msym_bunch_index to BUNCH_SIZE causes the first call to save a minimal - symbol to allocate the memory for the first bunch. */ +/* See minsyms.h. */ void init_minimal_symbol_collection (void) { msym_count = 0; msym_bunch = NULL; + /* Note that presetting msym_bunch_index to BUNCH_SIZE causes the + first call to save a minimal symbol to allocate the memory for + the first bunch. */ msym_bunch_index = BUNCH_SIZE; } +/* See minsyms.h. */ + void prim_record_minimal_symbol (const char *name, CORE_ADDR address, enum minimal_symbol_type ms_type, @@ -896,8 +875,7 @@ prim_record_minimal_symbol (const char *name, CORE_ADDR address, section, NULL, objfile); } -/* Record a minimal symbol in the msym bunches. Returns the symbol - newly created. */ +/* See minsyms.h. */ struct minimal_symbol * prim_record_minimal_symbol_full (const char *name, int name_len, int copy_name, @@ -974,8 +952,7 @@ prim_record_minimal_symbol_full (const char *name, int name_len, int copy_name, return msymbol; } -/* Record a minimal symbol in the msym bunches. Returns the symbol - newly created. */ +/* See minsyms.h. */ struct minimal_symbol * prim_record_minimal_symbol_and_info (const char *name, CORE_ADDR address, @@ -1048,6 +1025,8 @@ do_discard_minimal_symbols_cleanup (void *arg) } } +/* See minsyms.h. */ + struct cleanup * make_cleanup_discard_minimal_symbols (void) { @@ -1322,9 +1301,7 @@ msymbols_sort (struct objfile *objfile) build_minimal_symbol_hash_tables (objfile); } -/* Check if PC is in a shared library trampoline code stub. - Return minimal symbol for the trampoline entry or NULL if PC is not - in a trampoline code stub. */ +/* See minsyms.h. */ struct minimal_symbol * lookup_solib_trampoline_symbol_by_pc (CORE_ADDR pc) diff --git a/gdb/minsyms.h b/gdb/minsyms.h index 614f124..e6e2c8b 100644 --- a/gdb/minsyms.h +++ b/gdb/minsyms.h @@ -20,20 +20,86 @@ #ifndef MINSYMS_H #define MINSYMS_H -/* Functions for dealing with the minimal symbol table, really a misc - address<->symbol mapping for things we don't have debug symbols for. */ +/* This header declares most of the API for dealing with minimal + symbols and minimal symbol tables. A few things are declared + elsewhere; see below. -void prim_record_minimal_symbol (const char *, CORE_ADDR, - enum minimal_symbol_type, - struct objfile *); + A minimal symbol is a symbol for which there is no direct debug + information. For example, for an ELF binary, minimal symbols are + created from the ELF symbol table. + + For the definition of the minimal symbol structure, see struct + minimal_symbol in symtab.h. + + Minimal symbols are stored in tables attached to an objfile; see + objfiles.h for details. Code should generally treat these tables + as opaque and use functions provided by minsyms.c to inspect them. +*/ + +/* Prepare to start collecting minimal symbols. This should be called + by a symbol reader to initialize the minimal symbol module. + Currently, minimal symbol table creation is not reentrant; it + relies on global (static) variables in minsyms.c. */ + +void init_minimal_symbol_collection (void); + +/* Return a cleanup which is used to clean up the global state left + over by minimal symbol creation. After calling + init_minimal_symbol_collection, a symbol reader should call this + function. Then, after all minimal symbols have been read, + regardless of whether they are installed or not, the cleanup + returned by this function should be run. */ + +struct cleanup *make_cleanup_discard_minimal_symbols (void); + +/* Record a new minimal symbol. This is the "full" entry point; + simpler convenience entry points are also provided below. + + This returns a new minimal symbol. It is ok to modify the returned + minimal symbol (though generally not necessary). It is not ok, + though, to stash the pointer anywhere; as minimal symbols may be + moved after creation. The memory for the returned minimal symbol + is still owned by the minsyms.c code, and should not be freed. + + Arguments are: + + NAME - the symbol's name + NAME_LEN - the length of the name + COPY_NAME - if true, the minsym code must make a copy of NAME. If + false, then NAME must be NUL-terminated, and must have a lifetime + that is at least as long as OBJFILE's lifetime. + ADDRESS - the address of the symbol + MS_TYPE - the type of the symbol + SECTION - the symbol's section + BFD_SECTION - the symbol's BFD section; used to find the + appropriate obj_section for the minimal symbol. This can be NULL. + OBJFILE - the objfile associated with the minimal symbol. */ struct minimal_symbol *prim_record_minimal_symbol_full - (const char *, - int, int, CORE_ADDR, - enum minimal_symbol_type, + (const char *name, + int name_len, + int copy_name, + CORE_ADDR address, + enum minimal_symbol_type ms_type, int section, asection *bfd_section, - struct objfile *); + struct objfile *objfile); + +/* Like prim_record_minimal_symbol_full, but: + - uses strlen to compute NAME_LEN, + - passes COPY_NAME = 0, + - passes SECTION = 0, + - and passes BFD_SECTION = NULL. + + This variant does not return the new symbol. */ + +void prim_record_minimal_symbol (const char *, CORE_ADDR, + enum minimal_symbol_type, + struct objfile *); + +/* Like prim_record_minimal_symbol_full, but: + - uses strlen to compute NAME_LEN, + - passes COPY_NAME = 0. */ struct minimal_symbol *prim_record_minimal_symbol_and_info (const char *, @@ -43,10 +109,37 @@ struct minimal_symbol *prim_record_minimal_symbol_and_info asection *bfd_section, struct objfile *); -unsigned int msymbol_hash_iw (const char *); +/* Install the minimal symbols that have been collected into the given + objfile. After this is called, the cleanup returned by + make_cleanup_discard_minimal_symbols should be run in order to + clean up global state. */ + +void install_minimal_symbols (struct objfile *); + +/* Create the terminating entry of OBJFILE's minimal symbol table. + If OBJFILE->msymbols is zero, allocate a single entry from + OBJFILE->objfile_obstack; otherwise, just initialize + OBJFILE->msymbols[OBJFILE->minimal_symbol_count]. */ + +void terminate_minimal_symbol_table (struct objfile *objfile); + +/* Sort all the minimal symbols in OBJFILE. This should be only be + called after relocating symbols; it ensures that the minimal + symbols are properly sorted by address. */ + +void msymbols_sort (struct objfile *objfile); + + + +/* Compute a hash code for the string argument. */ unsigned int msymbol_hash (const char *); +/* Like msymbol_hash, but compute a hash code that is compatible with + strcmp_iw. */ + +unsigned int msymbol_hash_iw (const char *); + /* Compute the next hash value from previous HASH and the character C. This is only a GDB in-memory computed value with no external files compatibility requirements. */ @@ -54,49 +147,100 @@ unsigned int msymbol_hash (const char *); #define SYMBOL_HASH_NEXT(hash, c) \ ((hash) * 67 + tolower ((unsigned char) (c)) - 113) + + +/* Return the objfile that holds the minimal symbol SYM. Every + minimal symbols is held by some objfile; this will never return + NULL. */ + struct objfile *msymbol_objfile (struct minimal_symbol *sym); + + +/* Look through all the current minimal symbol tables and find the + first minimal symbol that matches NAME. If OBJF is non-NULL, limit + the search to that objfile. If SFILE is non-NULL, the only file-scope + symbols considered will be from that source file (global symbols are + still preferred). Returns a pointer to the minimal symbol that + matches, or NULL if no match is found. */ + struct minimal_symbol *lookup_minimal_symbol (const char *, const char *, struct objfile *); +/* Find the minimal symbol named NAME, and return both the minsym + struct and its objfile. This only checks the linkage name. Sets + *OBJFILE_P and returns the minimal symbol, if it is found. If it + is not found, returns NULL. */ + +struct minimal_symbol *lookup_minimal_symbol_and_objfile (const char *, + struct objfile **); + +/* Look through all the current minimal symbol tables and find the + first minimal symbol that matches NAME and has text type. If OBJF + is non-NULL, limit the search to that objfile. Returns a pointer + to the minimal symbol that matches, or NULL if no match is found. + + This function only searches the mangled (linkage) names. */ + struct minimal_symbol *lookup_minimal_symbol_text (const char *, struct objfile *); +/* Look through all the current minimal symbol tables and find the + first minimal symbol that matches NAME and is a solib trampoline. + If OBJF is non-NULL, limit the search to that objfile. Returns a + pointer to the minimal symbol that matches, or NULL if no match is + found. + + This function only searches the mangled (linkage) names. */ + struct minimal_symbol *lookup_minimal_symbol_solib_trampoline (const char *, struct objfile *); +/* Look through all the current minimal symbol tables and find the + first minimal symbol that matches NAME and PC. If OBJF is non-NULL, + limit the search to that objfile. Returns a pointer to the minimal + symbol that matches, or NULL if no match is found. */ + struct minimal_symbol *lookup_minimal_symbol_by_pc_name -(CORE_ADDR, const char *, struct objfile *); + (CORE_ADDR, const char *, struct objfile *); -struct minimal_symbol *lookup_minimal_symbol_by_pc (CORE_ADDR); +/* Search through the minimal symbol table for each objfile and find + the symbol whose address is the largest address that is still less + than or equal to PC, and which matches SECTION. -struct minimal_symbol *lookup_minimal_symbol_and_objfile (const char *, - struct objfile **); + If SECTION is NULL, this uses the result of find_pc_section + instead. + + Returns a pointer to the minimal symbol if such a symbol is found, + or NULL if PC is not in a suitable range. */ struct minimal_symbol *lookup_minimal_symbol_by_pc_section (CORE_ADDR, struct obj_section *); -struct minimal_symbol *lookup_solib_trampoline_symbol_by_pc (CORE_ADDR); +/* Backward compatibility: search through the minimal symbol table + for a matching PC (no section given). + + This is a wrapper that calls lookup_minimal_symbol_by_pc_section + with a NULL section argument. */ -void init_minimal_symbol_collection (void); - -struct cleanup *make_cleanup_discard_minimal_symbols (void); - -void install_minimal_symbols (struct objfile *); +struct minimal_symbol *lookup_minimal_symbol_by_pc (CORE_ADDR); -/* Sort all the minimal symbols in OBJFILE. */ +/* Check if PC is in a shared library trampoline code stub. + Return minimal symbol for the trampoline entry or NULL if PC is not + in a trampoline code stub. */ -void msymbols_sort (struct objfile *objfile); +struct minimal_symbol *lookup_solib_trampoline_symbol_by_pc (CORE_ADDR); -/* Create the terminating entry of OBJFILE's minimal symbol table. - If OBJFILE->msymbols is zero, allocate a single entry from - OBJFILE->objfile_obstack; otherwise, just initialize - OBJFILE->msymbols[OBJFILE->minimal_symbol_count]. */ +/* Iterate over all the minimal symbols in the objfile OBJF which + match NAME. Both the ordinary and demangled names of each symbol + are considered. The caller is responsible for canonicalizing NAME, + should that need to be done. -void terminate_minimal_symbol_table (struct objfile *objfile); + For each matching symbol, CALLBACK is called with the symbol and + USER_DATA as arguments. */ void iterate_over_minimal_symbols (struct objfile *objf, const char *name,