* minsyms.h: Rearrange. Document header and all functions.

	* minsyms.c: Move some comments to minsyms.h.

3 files changed, 196 insertions, 70 deletions

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index 5bcccf635d3..8b6b7180dd0 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,5 +1,10 @@
 2011-12-21  Tom Tromey  <tromey@redhat.com>
 
+	* minsyms.h: Rearrange.  Document header and all functions.
+	* minsyms.c: Move some comments to minsyms.h.
+
+2011-12-21  Tom Tromey  <tromey@redhat.com>
+
 	* 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 18cf6720335..0d2f5de6284 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 614f124c1ef..e6e2c8b4f65 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,