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.
  44
  45    Gdb also supports an alternate method to avoid running off the bottom
  46    of the stack.
  47
  48    There are two frames that are "special", the frame for the function
  49    containing the process entry point, since it has no predecessor frame,
  50    and the frame for the function containing the user code entry point
  51    (the main() function), since all the predecessor frames are for the
  52    process startup code.  Since we have no guarantee that the linked
  53    in startup modules have any debugging information that gdb can use,
  54    we need to avoid following frame pointers back into frames that might
  55    have been built in the startup code, as we might get hopelessly
  56    confused.  However, we almost always have debugging information
  57    available for main().
  58
  59    These variables are used to save the range of PC values which are valid
  60    within the main() function and within the function containing the process
  61    entry point.  If we always consider the frame for main() as the outermost
  62    frame when debugging user code, and the frame for the process entry
  63    point function as the outermost frame when debugging startup code, then
  64    all we have to do is have FRAME_CHAIN_VALID return false whenever a
  65    frame's current PC is within the range specified by these variables.
  66    In essence, we set "ceilings" in the frame chain beyond which we will
  67    not proceed when following the frame chain back up the stack.
  68
  69    A nice side effect is that we can still debug startup code without
  70    running off the end of the frame chain, assuming that we have usable
  71    debugging information in the startup modules, and if we choose to not
  72    use the block at main, or can't find it for some reason, everything
  73    still works as before.  And if we have no startup code debugging
  74    information but we do have usable information for main(), backtraces
  75    from user code don't go wandering off into the startup code.
  76
  77    To use this method, define your FRAME_CHAIN_VALID macro like:
  78
  79         #define FRAME_CHAIN_VALID(chain, thisframe)     \
  80           (chain != 0                                   \
  81            && !(inside_main_func ((thisframe)->pc))     \
  82            && !(inside_entry_func ((thisframe)->pc)))
  83
  84    and add initializations of the four scope controlling variables inside
  85    the object file / debugging information processing modules.  */
  86
  87 struct entry_info
  88 {
  89
  90   /* The value we should use for this objects entry point.
  91      The illegal/unknown value needs to be something other than 0, ~0
  92      for instance, which is much less likely than 0. */
  93
  94   CORE_ADDR entry_point;
  95
  96 #define INVALID_ENTRY_POINT (~0) /* ~0 will not be in any file, we hope.  */
  97
  98   /* Start (inclusive) and end (exclusive) of function containing the
  99      entry point. */
 100
 101   CORE_ADDR entry_func_lowpc;
 102   CORE_ADDR entry_func_highpc;
 103
 104   /* Start (inclusive) and end (exclusive) of object file containing the
 105      entry point. */
 106
 107   CORE_ADDR entry_file_lowpc;
 108   CORE_ADDR entry_file_highpc;
 109
 110   /* Start (inclusive) and end (exclusive) of the user code main() function. */
 111
 112   CORE_ADDR main_func_lowpc;
 113   CORE_ADDR main_func_highpc;
 114
 115 /* Use these values when any of the above ranges is invalid.  */
 116
 117 /* We use these values because it guarantees that there is no number that is
 118    both >= LOWPC && < HIGHPC.  It is also highly unlikely that 3 is a valid
 119    module or function start address (as opposed to 0).  */
 120
 121 #define INVALID_ENTRY_LOWPC (3)
 122 #define INVALID_ENTRY_HIGHPC (1)
 123
 124 };
 125
 126
 127 /* Sections in an objfile.
 128
 129    It is strange that we have both this notion of "sections"
 130    and the one used by section_offsets.  Section as used
 131    here, (currently at least) means a BFD section, and the sections
 132    are set up from the BFD sections in allocate_objfile.
 133
 134    The sections in section_offsets have their meaning determined by
 135    the symbol format, and they are set up by the sym_offsets function
 136    for that symbol file format.
 137
 138    I'm not sure this could or should be changed, however.  */
 139
 140 struct obj_section {
 141   CORE_ADDR     addr;    /* lowest address in section */
 142   CORE_ADDR     endaddr; /* 1+highest address in section */
 143
 144   /* This field is being used for nefarious purposes by syms_from_objfile.
 145      It is said to be redundant with section_offsets; it's not really being
 146      used that way, however, it's some sort of hack I don't understand
 147      and am not going to try to eliminate (yet, anyway).  FIXME.
 148
 149      It was documented as "offset between (end)addr and actual memory
 150      addresses", but that's not true; addr & endaddr are actual memory
 151      addresses.  */
 152   CORE_ADDR offset;
 153
 154   sec_ptr the_bfd_section; /* BFD section pointer */
 155
 156   /* Objfile this section is part of.  */
 157   struct objfile *objfile;
 158 };
 159
 160 /* Master structure for keeping track of each file from which
 161    gdb reads symbols.  There are several ways these get allocated: 1.
 162    The main symbol file, symfile_objfile, set by the symbol-file command,
 163    2.  Additional symbol files added by the add-symbol-file command,
 164    3.  Shared library objfiles, added by ADD_SOLIB,  4.  symbol files
 165    for modules that were loaded when GDB attached to a remote system
 166    (see remote-vx.c).  */
 167
 168 struct objfile
 169 {
 170
 171   /* All struct objfile's are chained together by their next pointers.
 172      The global variable "object_files" points to the first link in this
 173      chain.
 174
 175      FIXME:  There is a problem here if the objfile is reusable, and if
 176      multiple users are to be supported.  The problem is that the objfile
 177      list is linked through a member of the objfile struct itself, which
 178      is only valid for one gdb process.  The list implementation needs to
 179      be changed to something like:
 180
 181      struct list {struct list *next; struct objfile *objfile};
 182
 183      where the list structure is completely maintained separately within
 184      each gdb process. */
 185
 186   struct objfile *next;
 187
 188   /* The object file's name.  Malloc'd; free it if you free this struct.  */
 189
 190   char *name;
 191
 192   /* Some flag bits for this objfile. */
 193
 194   unsigned short flags;
 195
 196   /* Each objfile points to a linked list of symtabs derived from this file,
 197      one symtab structure for each compilation unit (source file).  Each link
 198      in the symtab list contains a backpointer to this objfile. */
 199
 200   struct symtab *symtabs;
 201
 202   /* Each objfile points to a linked list of partial symtabs derived from
 203      this file, one partial symtab structure for each compilation unit
 204      (source file). */
 205
 206   struct partial_symtab *psymtabs;
 207
 208   /* List of freed partial symtabs, available for re-use */
 209
 210   struct partial_symtab *free_psymtabs;
 211
 212   /* The object file's BFD.  Can be null, in which case bfd_open (name) and
 213      put the result here.  */
 214
 215   bfd *obfd;
 216
 217   /* The modification timestamp of the object file, as of the last time
 218      we read its symbols.  */
 219
 220   long mtime;
 221
 222   /* Obstacks to hold objects that should be freed when we load a new symbol
 223      table from this object file. */
 224
 225   struct obstack psymbol_obstack;       /* Partial symbols */
 226   struct obstack symbol_obstack;        /* Full symbols */
 227   struct obstack type_obstack;          /* Types */
 228
 229   /* Vectors of all partial symbols read in from file.  The actual data
 230      is stored in the psymbol_obstack. */
 231
 232   struct psymbol_allocation_list global_psymbols;
 233   struct psymbol_allocation_list static_psymbols;
 234
 235   /* Each file contains a pointer to an array of minimal symbols for all
 236      global symbols that are defined within the file.  The array is terminated
 237      by a "null symbol", one that has a NULL pointer for the name and a zero
 238      value for the address.  This makes it easy to walk through the array
 239      when passed a pointer to somewhere in the middle of it.  There is also
 240      a count of the number of symbols, which does include the terminating
 241      null symbol.  The array itself, as well as all the data that it points
 242      to, should be allocated on the symbol_obstack for this file. */
 243
 244   struct minimal_symbol *msymbols;
 245   int minimal_symbol_count;
 246
 247   /* For object file formats which don't specify fundamental types, gdb
 248      can create such types.  For now, it maintains a vector of pointers
 249      to these internally created fundamental types on a per objfile basis,
 250      however it really should ultimately keep them on a per-compilation-unit
 251      basis, to account for linkage-units that consist of a number of
 252      compilation units that may have different fundamental types, such as
 253      linking C modules with ADA modules, or linking C modules that are
 254      compiled with 32-bit ints with C modules that are compiled with 64-bit
 255      ints (not inherently evil with a smarter linker). */
 256
 257   struct type **fundamental_types;
 258
 259   /* The mmalloc() malloc-descriptor for this objfile if we are using
 260      the memory mapped malloc() package to manage storage for this objfile's
 261      data.  NULL if we are not. */
 262
 263   PTR md;
 264
 265   /* The file descriptor that was used to obtain the mmalloc descriptor
 266      for this objfile.  If we call mmalloc_detach with the malloc descriptor
 267      we should then close this file descriptor. */
 268
 269   int mmfd;
 270
 271   /* Structure which keeps track of functions that manipulate objfile's
 272      of the same type as this objfile.  I.E. the function to read partial
 273      symbols for example.  Note that this structure is in statically
 274      allocated memory, and is shared by all objfiles that use the
 275      object module reader of this type. */
 276
 277   struct sym_fns *sf;
 278
 279   /* The per-objfile information about the entry point, the scope (file/func)
 280      containing the entry point, and the scope of the user's main() func. */
 281
 282   struct entry_info ei;
 283
 284   /* Information about stabs.  Will be filled in with a dbx_symfile_info
 285      struct by those readers that need it. */
 286
 287   PTR sym_stab_info;
 288
 289   /* Hook for information for use by the symbol reader (currently used
 290      for information shared by sym_init and sym_read).  It is
 291      typically a pointer to malloc'd memory.  The symbol reader's finish
 292      function is responsible for freeing the memory thusly allocated.  */
 293
 294   PTR sym_private;
 295
 296   /* Hook for target-architecture-specific information.  This must
 297      point to memory allocated on one of the obstacks in this objfile,
 298      so that it gets freed automatically when reading a new object
 299      file. */
 300
 301   PTR obj_private;
 302
 303   /* Set of relocation offsets to apply to each section.
 304      Currently on the psymbol_obstack (which makes no sense, but I'm
 305      not sure it's harming anything).
 306
 307      These offsets indicate that all symbols (including partial and
 308      minimal symbols) which have been read have been relocated by this
 309      much.  Symbols which are yet to be read need to be relocated by
 310      it.  */
 311
 312   struct section_offsets *section_offsets;
 313   int num_sections;
 314
 315   /* set of section begin and end addresses used to map pc addresses
 316      into sections.  Currently on the psymbol_obstack (which makes no
 317      sense, but I'm not sure it's harming anything).  */
 318
 319   struct obj_section
 320     *sections,
 321     *sections_end;
 322
 323   /* two auxiliary fields, used to hold the fp of separate symbol files */
 324   FILE *auxf1, *auxf2;
 325 };
 326
 327 /* Defines for the objfile flag word. */
 328
 329 /* Gdb can arrange to allocate storage for all objects related to a
 330    particular objfile in a designated section of it's address space,
 331    managed at a low level by mmap() and using a special version of
 332    malloc that handles malloc/free/realloc on top of the mmap() interface.
 333    This allows the "internal gdb state" for a particular objfile to be
 334    dumped to a gdb state file and subsequently reloaded at a later time. */
 335
 336 #define OBJF_MAPPED     (1 << 0)        /* Objfile data is mmap'd */
 337
 338 /* When using mapped/remapped predigested gdb symbol information, we need
 339    a flag that indicates that we have previously done an initial symbol
 340    table read from this particular objfile.  We can't just look for the
 341    absence of any of the three symbol tables (msymbols, psymtab, symtab)
 342    because if the file has no symbols for example, none of these will
 343    exist. */
 344
 345 #define OBJF_SYMS       (1 << 1)        /* Have tried to read symbols */
 346
 347 /* The object file that the main symbol table was loaded from (e.g. the
 348    argument to the "symbol-file" or "file" command).  */
 349
 350 extern struct objfile *symfile_objfile;
 351
 352 /* When we need to allocate a new type, we need to know which type_obstack
 353    to allocate the type on, since there is one for each objfile.  The places
 354    where types are allocated are deeply buried in function call hierarchies
 355    which know nothing about objfiles, so rather than trying to pass a
 356    particular objfile down to them, we just do an end run around them and
 357    set current_objfile to be whatever objfile we expect to be using at the
 358    time types are being allocated.  For instance, when we start reading
 359    symbols for a particular objfile, we set current_objfile to point to that
 360    objfile, and when we are done, we set it back to NULL, to ensure that we
 361    never put a type someplace other than where we are expecting to put it.
 362    FIXME:  Maybe we should review the entire type handling system and
 363    see if there is a better way to avoid this problem. */
 364
 365 extern struct objfile *current_objfile;
 366
 367 /* All known objfiles are kept in a linked list.  This points to the
 368    root of this list. */
 369
 370 extern struct objfile *object_files;
 371
 372 /* Declarations for functions defined in objfiles.c */
 373
 374 extern struct objfile *allocate_objfile PARAMS ((bfd *, int));
 375
 376 int build_objfile_section_table PARAMS ((struct objfile *));
 377
 378 extern void unlink_objfile PARAMS ((struct objfile *));
 379
 380 extern void free_objfile PARAMS ((struct objfile *));
 381
 382 extern void
 383 free_all_objfiles PARAMS ((void));
 384
 385 extern void
 386 objfile_relocate PARAMS ((struct objfile *, struct section_offsets *));
 387
 388 extern int
 389 have_partial_symbols PARAMS ((void));
 390
 391 extern int
 392 have_full_symbols PARAMS ((void));
 393
 394 /* Functions for dealing with the minimal symbol table, really a misc
 395    address<->symbol mapping for things we don't have debug symbols for.  */
 396
 397 extern int
 398 have_minimal_symbols PARAMS ((void));
 399
 400 extern struct obj_section *
 401 find_pc_section PARAMS((CORE_ADDR pc));
 402
 403 /* Traverse all object files.  ALL_OBJFILES_SAFE works even if you delete
 404    the objfile during the traversal.  */
 405
 406 #define ALL_OBJFILES(obj) \
 407   for ((obj) = object_files; (obj) != NULL; (obj) = (obj)->next)
 408
 409 #define ALL_OBJFILES_SAFE(obj,nxt) \
 410   for ((obj) = object_files;       \
 411        (obj) != NULL? ((nxt)=(obj)->next,1) :0; \
 412        (obj) = (nxt))
 413
 414
 415 /* Traverse all symtabs in one objfile.  */
 416
 417 #define ALL_OBJFILE_SYMTABS(objfile, s) \
 418     for ((s) = (objfile) -> symtabs; (s) != NULL; (s) = (s) -> next)
 419
 420 /* Traverse all psymtabs in one objfile.  */
 421
 422 #define ALL_OBJFILE_PSYMTABS(objfile, p) \
 423     for ((p) = (objfile) -> psymtabs; (p) != NULL; (p) = (p) -> next)
 424
 425 /* Traverse all minimal symbols in one objfile.  */
 426
 427 #define ALL_OBJFILE_MSYMBOLS(objfile, m) \
 428     for ((m) = (objfile) -> msymbols; SYMBOL_NAME(m) != NULL; (m)++)
 429
 430
 431 /* Traverse all symtabs in all objfiles.  */
 432
 433 #define ALL_SYMTABS(objfile, s) \
 434   ALL_OBJFILES (objfile)         \
 435     ALL_OBJFILE_SYMTABS (objfile, s)
 436
 437 /* Traverse all psymtabs in all objfiles.  */
 438
 439 #define ALL_PSYMTABS(objfile, p) \
 440   ALL_OBJFILES (objfile)         \
 441     ALL_OBJFILE_PSYMTABS (objfile, p)
 442
 443 /* Traverse all minimal symbols in all objfiles.  */
 444
 445 #define ALL_MSYMBOLS(objfile, m) \
 446   ALL_OBJFILES (objfile)         \
 447     if ((objfile)->msymbols)     \
 448       ALL_OBJFILE_MSYMBOLS (objfile, m)
 449
 450 #endif  /* !defined (OBJFILES_H) */