gdb/objfiles.h

   1 /* Definitions for symbol file management in GDB.
   2    Copyright (C) 1992 Free Software Foundation, Inc.
   3
   4 This file is part of GDB.
   5
   6 This program is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2 of the License, or
   9 (at your option) any later version.
  10
  11 This program is distributed in the hope that it will be useful,
  12 but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 GNU General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with this program; if not, write to the Free Software
  18 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
  19
  20 #if !defined (OBJFILES_H)
  21 #define OBJFILES_H
  22
  23 /* This structure maintains information on a per-objfile basis about the
  24    "entry point" of the objfile, and the scope within which the entry point
  25    exists.  It is possible that gdb will see more than one objfile that is
  26    executable, each with it's own entry point.
  27
  28    For example, for dynamically linked executables in SVR4, the dynamic linker
  29    code is contained within the shared C library, which is actually executable
  30    and is run by the kernel first when an exec is done of a user executable
  31    that is dynamically linked.  The dynamic linker within the shared C library
  32    then maps in the various program segments in the user executable and jumps
  33    to the user executable's recorded entry point, as if the call had been made
  34    directly by the kernel.
  35
  36    The traditional gdb method of using this info is to use the recorded entry
  37    point to set the variables entry_file_lowpc and entry_file_highpc from
  38    the debugging information, where these values are the starting address
  39    (inclusive) and ending address (exclusive) of the instruction space in the
  40    executable which correspond to the "startup file", I.E. crt0.o in most
  41    cases.  This file is assumed to be a startup file and frames with pc's
  42    inside it are treated as nonexistent.  Setting these variables is necessary
  43    so that backtraces do not fly off the bottom of the stack (or top, depending
  44    upon your stack orientation).
  45
  46    Gdb also supports an alternate method to avoid running off the top/bottom
  47    of the stack.
  48
  49    There are two frames that are "special", the frame for the function
  50    containing the process entry point, since it has no predecessor frame,
  51    and the frame for the function containing the user code entry point
  52    (the main() function), since all the predecessor frames are for the
  53    process startup code.  Since we have no guarantee that the linked
  54    in startup modules have any debugging information that gdb can use,
  55    we need to avoid following frame pointers back into frames that might
  56    have been built in the startup code, as we might get hopelessly
  57    confused.  However, we almost always have debugging information
  58    available for main().
  59
  60    These variables are used to save the range of PC values which are valid
  61    within the main() function and within the function containing the process
  62    entry point.  If we always consider the frame for main() as the outermost
  63    frame when debugging user code, and the frame for the process entry
  64    point function as the outermost frame when debugging startup code, then
  65    all we have to do is have FRAME_CHAIN_VALID return false whenever a
  66    frame's current PC is within the range specified by these variables.
  67    In essence, we set "ceilings" in the frame chain beyond which we will
  68    not proceed when following the frame chain back up the stack.
  69
  70    A nice side effect is that we can still debug startup code without
  71    running off the end of the frame chain, assuming that we have usable
  72    debugging information in the startup modules, and if we choose to not
  73    use the block at main, or can't find it for some reason, everything
  74    still works as before.  And if we have no startup code debugging
  75    information but we do have usable information for main(), backtraces
  76    from user code don't go wandering off into the startup code.
  77
  78    To use this method, define your FRAME_CHAIN_VALID macro like:
  79
  80         #define FRAME_CHAIN_VALID(chain, thisframe)     \
  81           (chain != 0                                   \
  82            && !(inside_main_func ((thisframe)->pc))     \
  83            && !(inside_entry_func ((thisframe)->pc)))
  84
  85    and add initializations of the four scope controlling variables inside
  86    the object file / debugging information processing modules.  */
  87
  88 struct entry_info
  89 {
  90
  91   /* The value we should use for this objects entry point.
  92      The illegal/unknown value needs to be something other than 0, ~0
  93      for instance, which is much less likely than 0. */
  94
  95   CORE_ADDR entry_point;
  96
  97   /* Start (inclusive) and end (exclusive) of function containing the
  98      entry point. */
  99
 100   CORE_ADDR entry_func_lowpc;
 101   CORE_ADDR entry_func_highpc;
 102
 103   /* Start (inclusive) and end (exclusive) of object file containing the
 104      entry point. */
 105
 106   CORE_ADDR entry_file_lowpc;
 107   CORE_ADDR entry_file_highpc;
 108
 109   /* Start (inclusive) and end (exclusive) of the user code main() function. */
 110
 111   CORE_ADDR main_func_lowpc;
 112   CORE_ADDR main_func_highpc;
 113
 114 };
 115
 116
 117 /* Master structure for keeping track of each input file from which
 118    gdb reads symbols.  One of these is allocated for each such file we
 119    access, e.g. the exec_file, symbol_file, and any shared library object
 120    files. */
 121
 122 struct objfile
 123 {
 124
 125   /* All struct objfile's are chained together by their next pointers.
 126      The global variable "object_files" points to the first link in this
 127      chain.
 128
 129      FIXME:  There is a problem here if the objfile is reusable, and if
 130      multiple users are to be supported.  The problem is that the objfile
 131      list is linked through a member of the objfile struct itself, which
 132      is only valid for one gdb process.  The list implementation needs to
 133      be changed to something like:
 134
 135      struct list {struct list *next; struct objfile *objfile};
 136
 137      where the list structure is completely maintained separately within
 138      each gdb process. */
 139
 140   struct objfile *next;
 141
 142   /* The object file's name.  Malloc'd; free it if you free this struct.  */
 143
 144   char *name;
 145
 146   /* Some flag bits for this objfile. */
 147
 148   unsigned short flags;
 149
 150   /* Each objfile points to a linked list of symtabs derived from this file,
 151      one symtab structure for each compilation unit (source file).  Each link
 152      in the symtab list contains a backpointer to this objfile. */
 153
 154   struct symtab *symtabs;
 155
 156   /* Each objfile points to a linked list of partial symtabs derived from
 157      this file, one partial symtab structure for each compilation unit
 158      (source file). */
 159
 160   struct partial_symtab *psymtabs;
 161
 162   /* List of freed partial symtabs, available for re-use */
 163
 164   struct partial_symtab *free_psymtabs;
 165
 166   /* The object file's BFD.  Can be null, in which case bfd_open (name) and
 167      put the result here.  */
 168
 169   bfd *obfd;
 170
 171   /* The modification timestamp of the object file, as of the last time
 172      we read its symbols.  */
 173
 174   long mtime;
 175
 176   /* Obstacks to hold objects that should be freed when we load a new symbol
 177      table from this object file. */
 178
 179   struct obstack psymbol_obstack;       /* Partial symbols */
 180   struct obstack symbol_obstack;        /* Full symbols */
 181   struct obstack type_obstack;          /* Types */
 182
 183   /* Vectors of all partial symbols read in from file.  The actual data
 184      is stored in the psymbol_obstack. */
 185
 186   struct psymbol_allocation_list global_psymbols;
 187   struct psymbol_allocation_list static_psymbols;
 188
 189   /* Each file contains a pointer to an array of minimal symbols for all
 190      global symbols that are defined within the file.  The array is terminated
 191      by a "null symbol", one that has a NULL pointer for the name and a zero
 192      value for the address.  This makes it easy to walk through the array
 193      when passed a pointer to somewhere in the middle of it.  There is also
 194      a count of the number of symbols, which does include the terminating
 195      null symbol.  The array itself, as well as all the data that it points
 196      to, should be allocated on the symbol_obstack for this file. */
 197
 198   struct minimal_symbol *msymbols;
 199   int minimal_symbol_count;
 200
 201   /* For object file formats which don't specify fundamental types, gdb
 202      can create such types.  For now, it maintains a vector of pointers
 203      to these internally created fundamental types on a per objfile basis,
 204      however it really should ultimately keep them on a per-compilation-unit
 205      basis, to account for linkage-units that consist of a number of
 206      compilation units that may have different fundamental types, such as
 207      linking C modules with ADA modules, or linking C modules that are
 208      compiled with 32-bit ints with C modules that are compiled with 64-bit
 209      ints (not inherently evil with a smarter linker). */
 210
 211   struct type **fundamental_types;
 212
 213   /* The mmalloc() malloc-descriptor for this objfile if we are using
 214      the memory mapped malloc() package to manage storage for this objfile's
 215      data.  NULL if we are not. */
 216
 217   PTR md;
 218
 219   /* The file descriptor that was used to obtain the mmalloc descriptor
 220      for this objfile.  If we call mmalloc_detach with the malloc descriptor
 221      we should then close this file descriptor. */
 222
 223   int mmfd;
 224
 225   /* Structure which keeps track of functions that manipulate objfile's
 226      of the same type as this objfile.  I.E. the function to read partial
 227      symbols for example.  Note that this structure is in statically
 228      allocated memory, and is shared by all objfiles that use the
 229      object module reader of this type. */
 230
 231   struct sym_fns *sf;
 232
 233   /* The per-objfile information about the entry point, the scope (file/func)
 234      containing the entry point, and the scope of the user's main() func. */
 235
 236   struct entry_info ei;
 237
 238   /* Hook for information which is shared by sym_init and sym_read for
 239      this objfile.  It is typically a pointer to malloc'd memory.  */
 240
 241   PTR sym_private;
 242
 243 };
 244
 245 /* Defines for the objfile flag word. */
 246
 247 /* Gdb can arrange to allocate storage for all objects related to a
 248    particular objfile in a designated section of it's address space,
 249    managed at a low level by mmap() and using a special version of
 250    malloc that handles malloc/free/realloc on top of the mmap() interface.
 251    This allows the "internal gdb state" for a particular objfile to be
 252    dumped to a gdb state file and subsequently reloaded at a later time. */
 253
 254 #define OBJF_MAPPED     (1 << 0)        /* Objfile data is mmap'd */
 255
 256 /* When using mapped/remapped predigested gdb symbol information, we need
 257    a flag that indicates that we have previously done an initial symbol
 258    table read from this particular objfile.  We can't just look for the
 259    absence of any of the three symbol tables (msymbols, psymtab, symtab)
 260    because if the file has no symbols for example, none of these will
 261    exist. */
 262
 263 #define OBJF_SYMS       (1 << 1)        /* Have tried to read symbols */
 264
 265 /* The object file that the main symbol table was loaded from (e.g. the
 266    argument to the "symbol-file" or "file" command).  */
 267
 268 extern struct objfile *symfile_objfile;
 269
 270 /* When we need to allocate a new type, we need to know which type_obstack
 271    to allocate the type on, since there is one for each objfile.  The places
 272    where types are allocated are deeply buried in function call hierarchies
 273    which know nothing about objfiles, so rather than trying to pass a
 274    particular objfile down to them, we just do an end run around them and
 275    set current_objfile to be whatever objfile we expect to be using at the
 276    time types are being allocated.  For instance, when we start reading
 277    symbols for a particular objfile, we set current_objfile to point to that
 278    objfile, and when we are done, we set it back to NULL, to ensure that we
 279    never put a type someplace other than where we are expecting to put it.
 280    FIXME:  Maybe we should review the entire type handling system and
 281    see if there is a better way to avoid this problem. */
 282
 283 extern struct objfile *current_objfile;
 284
 285 /* All known objfiles are kept in a linked list.  This points to the
 286    root of this list. */
 287
 288 extern struct objfile *object_files;
 289
 290 /* Declarations for functions defined in objfiles.c */
 291
 292 extern struct objfile *
 293 allocate_objfile PARAMS ((bfd *, int));
 294
 295 extern void
 296 unlink_objfile PARAMS ((struct objfile *));
 297
 298 extern void
 299 free_objfile PARAMS ((struct objfile *));
 300
 301 extern void
 302 free_all_objfiles PARAMS ((void));
 303
 304 extern int
 305 have_partial_symbols PARAMS ((void));
 306
 307 extern int
 308 have_full_symbols PARAMS ((void));
 309
 310 /* Functions for dealing with the minimal symbol table, really a misc
 311    address<->symbol mapping for things we don't have debug symbols for.  */
 312
 313 extern int
 314 have_minimal_symbols PARAMS ((void));
 315
 316
 317 /* Traverse all object files.  ALL_OBJFILES_SAFE works even if you delete
 318    the objfile during the traversal.  */
 319
 320 #define ALL_OBJFILES(obj) \
 321   for ((obj) = object_files; (obj) != NULL; (obj) = (obj)->next)
 322
 323 #define ALL_OBJFILES_SAFE(obj,nxt) \
 324   for ((obj) = object_files;       \
 325        (obj) != NULL? ((nxt)=(obj)->next,1) :0; \
 326        (obj) = (nxt))
 327
 328 /* Traverse all symtabs in all objfiles.  */
 329
 330 #define ALL_SYMTABS(objfile, s) \
 331   ALL_OBJFILES (objfile)         \
 332     for ((s) = (objfile) -> symtabs; (s) != NULL; (s) = (s) -> next)
 333
 334 /* Traverse all psymtabs in all objfiles.  */
 335
 336 #define ALL_PSYMTABS(objfile, p) \
 337   ALL_OBJFILES (objfile)         \
 338     for ((p) = (objfile) -> psymtabs; (p) != NULL; (p) = (p) -> next)
 339
 340 /* Traverse all minimal symbols in all objfiles.  */
 341
 342 #define ALL_MSYMBOLS(objfile, m) \
 343   ALL_OBJFILES (objfile)         \
 344     for ((m) = (objfile) -> msymbols; (m)->name != NULL; (m)++)
 345
 346 #endif  /* !defined (OBJFILES_H) */