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   struct objfile *next;
 130
 131   /* The object file's name.  Malloc'd; free it if you free this struct.  */
 132
 133   char *name;
 134
 135   /* Some flag bits for this objfile. */
 136
 137   unsigned short flags;
 138
 139   /* Each objfile points to a linked list of symtabs derived from this file,
 140      one symtab structure for each compilation unit (source file).  Each link
 141      in the symtab list contains a backpointer to this objfile. */
 142
 143   struct symtab *symtabs;
 144
 145   /* Each objfile points to a linked list of partial symtabs derived from
 146      this file, one partial symtab structure for each compilation unit
 147      (source file). */
 148
 149   struct partial_symtab *psymtabs;
 150
 151   /* List of freed partial symtabs, available for re-use */
 152
 153   struct partial_symtab *free_psymtabs;
 154
 155   /* The object file's BFD.  Can be null, in which case bfd_open (name) and
 156      put the result here.  */
 157
 158   bfd *obfd;
 159
 160   /* The modification timestamp of the object file, as of the last time
 161      we read its symbols.  */
 162
 163   long mtime;
 164
 165   /* Obstacks to hold objects that should be freed when we load a new symbol
 166      table from this object file. */
 167
 168   struct obstack psymbol_obstack;       /* Partial symbols */
 169   struct obstack symbol_obstack;        /* Full symbols */
 170   struct obstack type_obstack;          /* Types */
 171
 172   /* Vectors of all partial symbols read in from file.  The actual data
 173      is stored in the psymbol_obstack. */
 174
 175   struct psymbol_allocation_list global_psymbols;
 176   struct psymbol_allocation_list static_psymbols;
 177
 178   /* Each file contains a pointer to an array of minimal symbols for all
 179      global symbols that are defined within the file.  The array is terminated
 180      by a "null symbol", one that has a NULL pointer for the name and a zero
 181      value for the address.  This makes it easy to walk through the array
 182      when passed a pointer to somewhere in the middle of it.  There is also
 183      a count of the number of symbols, which does include the terminating
 184      null symbol.  The array itself, as well as all the data that it points
 185      to, should be allocated on the symbol_obstack for this file. */
 186
 187   struct minimal_symbol *msymbols;
 188   int minimal_symbol_count;
 189
 190   /* For object file formats which don't specify fundamental types, gdb
 191      can create such types.  For now, it maintains a vector of pointers
 192      to these internally created fundamental types on a per objfile basis,
 193      however it really should ultimately keep them on a per-compilation-unit
 194      basis, to account for linkage-units that consist of a number of
 195      compilation units that may have different fundamental types, such as
 196      linking C modules with ADA modules, or linking C modules that are
 197      compiled with 32-bit ints with C modules that are compiled with 64-bit
 198      ints (not inherently evil with a smarter linker). */
 199
 200   struct type **fundamental_types;
 201
 202   /* The mmalloc() malloc-descriptor for this objfile if we are using
 203      the memory mapped malloc() package to manage storage for this objfile's
 204      data.  NULL if we are not. */
 205
 206   PTR md;
 207
 208   /* Structure which keeps track of functions that manipulate objfile's
 209      of the same type as this objfile.  I.E. the function to read partial
 210      symbols for example.  Note that this structure is in statically
 211      allocated memory, and is shared by all objfiles that use the
 212      object module reader of this type. */
 213
 214   struct sym_fns *sf;
 215
 216   /* The per-objfile information about the entry point, the scope (file/func)
 217      containing the entry point, and the scope of the user's main() func. */
 218
 219   struct entry_info ei;
 220
 221   /* Hook for information which is shared by sym_init and sym_read for
 222      this objfile.  It is typically a pointer to malloc'd memory.  */
 223
 224   PTR sym_private;
 225
 226 };
 227
 228 /* Defines for the objfile flag word. */
 229
 230 /* Gdb can arrange to allocate storage for all objects related to a
 231    particular objfile in a designated section of it's address space,
 232    managed at a low level by mmap() and using a special version of
 233    malloc that handles malloc/free/realloc on top of the mmap() interface.
 234    This allows the "internal gdb state" for a particular objfile to be
 235    dumped to a gdb state file and subsequently reloaded at a later time. */
 236
 237 #define OBJF_MAPPED     (1 << 0)        /* Objfile data is mmap'd */
 238
 239 /* The object file that the main symbol table was loaded from (e.g. the
 240    argument to the "symbol-file" or "file" command).  */
 241
 242 extern struct objfile *symfile_objfile;
 243
 244 /* When we need to allocate a new type, we need to know which type_obstack
 245    to allocate the type on, since there is one for each objfile.  The places
 246    where types are allocated are deeply buried in function call hierarchies
 247    which know nothing about objfiles, so rather than trying to pass a
 248    particular objfile down to them, we just do an end run around them and
 249    set current_objfile to be whatever objfile we expect to be using at the
 250    time types are being allocated.  For instance, when we start reading
 251    symbols for a particular objfile, we set current_objfile to point to that
 252    objfile, and when we are done, we set it back to NULL, to ensure that we
 253    never put a type someplace other than where we are expecting to put it.
 254    FIXME:  Maybe we should review the entire type handling system and
 255    see if there is a better way to avoid this problem. */
 256
 257 extern struct objfile *current_objfile;
 258
 259 /* All known objfiles are kept in a linked list.  This points to the
 260    root of this list. */
 261
 262 extern struct objfile *object_files;
 263
 264 /* Declarations for functions defined in objfiles.c */
 265
 266 extern struct objfile *
 267 allocate_objfile PARAMS ((bfd *, int));
 268
 269 extern void
 270 free_objfile PARAMS ((struct objfile *));
 271
 272 extern void
 273 free_all_objfiles PARAMS ((void));
 274
 275 extern int
 276 have_partial_symbols PARAMS ((void));
 277
 278 extern int
 279 have_full_symbols PARAMS ((void));
 280
 281 /* Functions for dealing with the minimal symbol table, really a misc
 282    address<->symbol mapping for things we don't have debug symbols for.  */
 283
 284 extern int
 285 have_minimal_symbols PARAMS ((void));
 286
 287 extern PTR
 288 iterate_over_objfiles PARAMS ((PTR (*func) (struct objfile *,
 289                                             PTR arg1, PTR arg2, PTR arg3),
 290                                PTR arg1, PTR arg2, PTR arg3));
 291
 292 extern PTR
 293 iterate_over_symtabs PARAMS ((PTR (*func) (struct objfile *, struct symtab *,
 294                                            PTR arg1, PTR arg2, PTR arg3),
 295                               PTR arg1, PTR arg2, PTR arg3));
 296
 297 extern PTR
 298 iterate_over_psymtabs PARAMS ((PTR (*func) (struct objfile *,
 299                                             struct partial_symtab *,
 300                                             PTR arg1, PTR arg2, PTR arg3),
 301                                PTR arg1, PTR arg2, PTR arg3));
 302
 303
 304 /* Traverse all object files.  ALL_OBJFILES_SAFE works even if you delete
 305    the objfile during the traversal.  */
 306
 307 #define ALL_OBJFILES(obj) \
 308   for ((obj)=object_files; (obj)!=NULL; (obj)=(obj)->next)
 309
 310 #define ALL_OBJFILES_SAFE(obj,nxt) \
 311   for ((obj)=object_files; (obj)!=NULL?((nxt)=(obj)->next,1):0; (obj)=(nxt))
 312
 313 #endif  /* !defined (OBJFILES_H) */