FYI: minsyms documentation

Tom Tromey
2011-12-22T02:34:31Z

I am checking this in on the trunk.

Today I decided to try to document the minsyms API more or less the way
I would like APIs to be documented in general. This patch implements
that; it move documentation from function definitions to minsyms.h, adds
an introductory comment about minsyms there as well, and it rearranges
the header into a more logical order.

My view is that gdbint.texinfo should eventually hold a high-level
overview of the different modules in GDB, but that each individual
module should be documented in the relevant header files. My reason for
this is just that it is simpler to update documentation when it is in
the form of comments. I think gdbint.texinfo should also hold
documentation on our procedures, coding styles, and other things that
are not directly related to some piece of code.

In the past people have mentioned using something like Doxygen to
extract an actual document from the sources. I am not opposed to this,
but I think that, as GDB is a program and not a library, such
documentation is of limited value; and in any case there are known
licensing issues with any such scheme -- see the archives of the GCC
lists for details.

Tom

2011-12-21 Tom Tromey <tromey@redhat.com>

* minsyms.h: Rearrange. Document header and all functions.
* minsyms.c: Move some comments to minsyms.h.

Index: minsyms.c
===================================================================
RCS file: /cvs/src/src/gdb/minsyms.c,v
retrieving revision 1.87
diff -u -r1.87 minsyms.c
--- minsyms.c 21 Dec 2011 21:51:56 -0000 1.87
+++ minsyms.c 21 Dec 2011 22:03:34 -0000
@@ -78,7 +78,7 @@

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 @@
return hash;
}

-/* Compute a hash code for a string. */
+/* See minsyms.h. */

unsigned int
msymbol_hash (const char *string)
@@ -141,8 +141,8 @@
}
}

+/* See minsyms.h. */

-/* Return OBJFILE where minimal symbol SYM is defined. */
struct objfile *
msymbol_objfile (struct minimal_symbol *sym)
{
@@ -310,13 +310,7 @@
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 @@
}
}

-/* 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 @@
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 @@
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 @@
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 @@

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 @@
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 @@
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 @@
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 @@
}
}

+/* See minsyms.h. */
+
struct cleanup *
make_cleanup_discard_minimal_symbols (void)
{
@@ -1322,9 +1301,7 @@
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)
Index: minsyms.h
===================================================================
RCS file: /cvs/src/src/gdb/minsyms.h,v
retrieving revision 1.1
diff -u -r1.1 minsyms.h
--- minsyms.h 21 Dec 2011 21:51:56 -0000 1.1
+++ minsyms.h 21 Dec 2011 22:03:34 -0000
@@ -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.
+
+ 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 prim_record_minimal_symbol (const char *, CORE_ADDR,
- enum minimal_symbol_type,
- struct objfile *);
+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 @@
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);
+
+\f
+
+/* 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 @@
#define SYMBOL_HASH_NEXT(hash, c) \
((hash) * 67 + tolower ((unsigned char) (c)) - 113)

+\f
+
+/* 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);

+\f
+
+/* 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);
-
-void init_minimal_symbol_collection (void);
-
-struct cleanup *make_cleanup_discard_minimal_symbols (void);
+/* 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 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,