2003-06-09 Andrew Cagney <cagney@redhat.com>
[platform/upstream/binutils.git] / gdb / objfiles.h
1 /* Definitions for symbol file management in GDB.
2
3    Copyright 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
4    2001, 2002, 2003 Free Software Foundation, Inc.
5
6    This file is part of GDB.
7
8    This program is free software; you can redistribute it and/or modify
9    it under the terms of the GNU General Public License as published by
10    the Free Software Foundation; either version 2 of the License, or
11    (at your option) any later version.
12
13    This program is distributed in the hope that it will be useful,
14    but WITHOUT ANY WARRANTY; without even the implied warranty of
15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16    GNU General Public License for more details.
17
18    You should have received a copy of the GNU General Public License
19    along with this program; if not, write to the Free Software
20    Foundation, Inc., 59 Temple Place - Suite 330,
21    Boston, MA 02111-1307, USA.  */
22
23 #if !defined (OBJFILES_H)
24 #define OBJFILES_H
25
26 #include "gdb_obstack.h"        /* For obstack internals.  */
27 #include "symfile.h"            /* For struct psymbol_allocation_list */
28
29 struct bcache;
30 struct htab;
31
32 /* This structure maintains information on a per-objfile basis about the
33    "entry point" of the objfile, and the scope within which the entry point
34    exists.  It is possible that gdb will see more than one objfile that is
35    executable, each with its own entry point.
36
37    For example, for dynamically linked executables in SVR4, the dynamic linker
38    code is contained within the shared C library, which is actually executable
39    and is run by the kernel first when an exec is done of a user executable
40    that is dynamically linked.  The dynamic linker within the shared C library
41    then maps in the various program segments in the user executable and jumps
42    to the user executable's recorded entry point, as if the call had been made
43    directly by the kernel.
44
45    The traditional gdb method of using this info is to use the recorded entry
46    point to set the variables entry_file_lowpc and entry_file_highpc from
47    the debugging information, where these values are the starting address
48    (inclusive) and ending address (exclusive) of the instruction space in the
49    executable which correspond to the "startup file", I.E. crt0.o in most
50    cases.  This file is assumed to be a startup file and frames with pc's
51    inside it are treated as nonexistent.  Setting these variables is necessary
52    so that backtraces do not fly off the bottom of the stack.
53
54    Gdb also supports an alternate method to avoid running off the bottom
55    of the stack.
56
57    There are two frames that are "special", the frame for the function
58    containing the process entry point, since it has no predecessor frame,
59    and the frame for the function containing the user code entry point
60    (the main() function), since all the predecessor frames are for the
61    process startup code.  Since we have no guarantee that the linked
62    in startup modules have any debugging information that gdb can use,
63    we need to avoid following frame pointers back into frames that might
64    have been built in the startup code, as we might get hopelessly 
65    confused.  However, we almost always have debugging information
66    available for main().
67
68    These variables are used to save the range of PC values which are
69    valid within the main() function and within the function containing
70    the process entry point.  If we always consider the frame for
71    main() as the outermost frame when debugging user code, and the
72    frame for the process entry point function as the outermost frame
73    when debugging startup code, then all we have to do is have
74    DEPRECATED_FRAME_CHAIN_VALID return false whenever a frame's
75    current PC is within the range specified by these variables.  In
76    essence, we set "ceilings" in the frame chain beyond which we will
77    not proceed when following the frame chain back up the stack.
78
79    A nice side effect is that we can still debug startup code without
80    running off the end of the frame chain, assuming that we have usable
81    debugging information in the startup modules, and if we choose to not
82    use the block at main, or can't find it for some reason, everything
83    still works as before.  And if we have no startup code debugging
84    information but we do have usable information for main(), backtraces
85    from user code don't go wandering off into the startup code.
86
87    To use this method, define your DEPRECATED_FRAME_CHAIN_VALID macro
88    like:
89
90    #define DEPRECATED_FRAME_CHAIN_VALID(chain, thisframe)     \
91    (chain != 0                                   \
92    && !(inside_main_func ((thisframe)->pc))     \
93    && !(inside_entry_func ((thisframe)->pc)))
94
95    and add initializations of the four scope controlling variables inside
96    the object file / debugging information processing modules.  */
97
98 struct entry_info
99   {
100
101     /* The value we should use for this objects entry point.
102        The illegal/unknown value needs to be something other than 0, ~0
103        for instance, which is much less likely than 0. */
104
105     CORE_ADDR entry_point;
106
107 #define INVALID_ENTRY_POINT (~0)        /* ~0 will not be in any file, we hope.  */
108
109     /* Start (inclusive) and end (exclusive) of function containing the
110        entry point. */
111
112     CORE_ADDR entry_func_lowpc;
113     CORE_ADDR entry_func_highpc;
114
115     /* Start (inclusive) and end (exclusive) of object file containing the
116        entry point. */
117
118     CORE_ADDR entry_file_lowpc;
119     CORE_ADDR entry_file_highpc;
120
121     /* Start (inclusive) and end (exclusive) of the user code main() function. */
122
123     CORE_ADDR main_func_lowpc;
124     CORE_ADDR main_func_highpc;
125
126 /* Use these values when any of the above ranges is invalid.  */
127
128 /* We use these values because it guarantees that there is no number that is
129    both >= LOWPC && < HIGHPC.  It is also highly unlikely that 3 is a valid
130    module or function start address (as opposed to 0).  */
131
132 #define INVALID_ENTRY_LOWPC (3)
133 #define INVALID_ENTRY_HIGHPC (1)
134
135   };
136
137 /* Sections in an objfile.
138
139    It is strange that we have both this notion of "sections"
140    and the one used by section_offsets.  Section as used
141    here, (currently at least) means a BFD section, and the sections
142    are set up from the BFD sections in allocate_objfile.
143
144    The sections in section_offsets have their meaning determined by
145    the symbol format, and they are set up by the sym_offsets function
146    for that symbol file format.
147
148    I'm not sure this could or should be changed, however.  */
149
150 struct obj_section
151   {
152     CORE_ADDR addr;             /* lowest address in section */
153     CORE_ADDR endaddr;          /* 1+highest address in section */
154
155     /* This field is being used for nefarious purposes by syms_from_objfile.
156        It is said to be redundant with section_offsets; it's not really being
157        used that way, however, it's some sort of hack I don't understand
158        and am not going to try to eliminate (yet, anyway).  FIXME.
159
160        It was documented as "offset between (end)addr and actual memory
161        addresses", but that's not true; addr & endaddr are actual memory
162        addresses.  */
163     CORE_ADDR offset;
164
165     sec_ptr the_bfd_section;    /* BFD section pointer */
166
167     /* Objfile this section is part of.  */
168     struct objfile *objfile;
169
170     /* True if this "overlay section" is mapped into an "overlay region". */
171     int ovly_mapped;
172   };
173
174 /* An import entry contains information about a symbol that
175    is used in this objfile but not defined in it, and so needs
176    to be imported from some other objfile */
177 /* Currently we just store the name; no attributes. 1997-08-05 */
178 typedef char *ImportEntry;
179
180
181 /* An export entry contains information about a symbol that
182    is defined in this objfile and available for use in other
183    objfiles */
184 typedef struct
185   {
186     char *name;                 /* name of exported symbol */
187     int address;                /* offset subject to relocation */
188     /* Currently no other attributes 1997-08-05 */
189   }
190 ExportEntry;
191
192
193 /* The "objstats" structure provides a place for gdb to record some
194    interesting information about its internal state at runtime, on a
195    per objfile basis, such as information about the number of symbols
196    read, size of string table (if any), etc. */
197
198 struct objstats
199   {
200     int n_minsyms;              /* Number of minimal symbols read */
201     int n_psyms;                /* Number of partial symbols read */
202     int n_syms;                 /* Number of full symbols read */
203     int n_stabs;                /* Number of ".stabs" read (if applicable) */
204     int n_types;                /* Number of types */
205     int sz_strtab;              /* Size of stringtable, (if applicable) */
206   };
207
208 #define OBJSTAT(objfile, expr) (objfile -> stats.expr)
209 #define OBJSTATS struct objstats stats
210 extern void print_objfile_statistics (void);
211 extern void print_symbol_bcache_statistics (void);
212
213 /* Number of entries in the minimal symbol hash table.  */
214 #define MINIMAL_SYMBOL_HASH_SIZE 2039
215
216 /* Master structure for keeping track of each file from which
217    gdb reads symbols.  There are several ways these get allocated: 1.
218    The main symbol file, symfile_objfile, set by the symbol-file command,
219    2.  Additional symbol files added by the add-symbol-file command,
220    3.  Shared library objfiles, added by ADD_SOLIB,  4.  symbol files
221    for modules that were loaded when GDB attached to a remote system
222    (see remote-vx.c).  */
223
224 struct objfile
225   {
226
227     /* All struct objfile's are chained together by their next pointers.
228        The global variable "object_files" points to the first link in this
229        chain.
230
231        FIXME:  There is a problem here if the objfile is reusable, and if
232        multiple users are to be supported.  The problem is that the objfile
233        list is linked through a member of the objfile struct itself, which
234        is only valid for one gdb process.  The list implementation needs to
235        be changed to something like:
236
237        struct list {struct list *next; struct objfile *objfile};
238
239        where the list structure is completely maintained separately within
240        each gdb process. */
241
242     struct objfile *next;
243
244     /* The object file's name, tilde-expanded and absolute.
245        Malloc'd; free it if you free this struct.  */
246
247     char *name;
248
249     /* Some flag bits for this objfile. */
250
251     unsigned short flags;
252
253     /* Each objfile points to a linked list of symtabs derived from this file,
254        one symtab structure for each compilation unit (source file).  Each link
255        in the symtab list contains a backpointer to this objfile. */
256
257     struct symtab *symtabs;
258
259     /* Each objfile points to a linked list of partial symtabs derived from
260        this file, one partial symtab structure for each compilation unit
261        (source file). */
262
263     struct partial_symtab *psymtabs;
264
265     /* List of freed partial symtabs, available for re-use */
266
267     struct partial_symtab *free_psymtabs;
268
269     /* The object file's BFD.  Can be null if the objfile contains only
270        minimal symbols, e.g. the run time common symbols for SunOS4.  */
271
272     bfd *obfd;
273
274     /* The modification timestamp of the object file, as of the last time
275        we read its symbols.  */
276
277     long mtime;
278
279     /* Obstacks to hold objects that should be freed when we load a new symbol
280        table from this object file. */
281
282     struct obstack psymbol_obstack;     /* Partial symbols */
283     struct obstack symbol_obstack;      /* Full symbols */
284     struct obstack type_obstack;        /* Types */
285
286     /* A byte cache where we can stash arbitrary "chunks" of bytes that
287        will not change. */
288
289     struct bcache *psymbol_cache;       /* Byte cache for partial syms */
290     struct bcache *macro_cache;          /* Byte cache for macros */
291
292     /* Hash table for mapping symbol names to demangled names.  Each
293        entry in the hash table is actually two consecutive strings,
294        both null-terminated; the first one is a mangled or linkage
295        name, and the second is the demangled name or just a zero byte
296        if the name doesn't demangle.  */
297     struct htab *demangled_names_hash;
298
299     /* Vectors of all partial symbols read in from file.  The actual data
300        is stored in the psymbol_obstack. */
301
302     struct psymbol_allocation_list global_psymbols;
303     struct psymbol_allocation_list static_psymbols;
304
305     /* Each file contains a pointer to an array of minimal symbols for all
306        global symbols that are defined within the file.  The array is terminated
307        by a "null symbol", one that has a NULL pointer for the name and a zero
308        value for the address.  This makes it easy to walk through the array
309        when passed a pointer to somewhere in the middle of it.  There is also
310        a count of the number of symbols, which does not include the terminating
311        null symbol.  The array itself, as well as all the data that it points
312        to, should be allocated on the symbol_obstack for this file. */
313
314     struct minimal_symbol *msymbols;
315     int minimal_symbol_count;
316
317     /* This is a hash table used to index the minimal symbols by name.  */
318
319     struct minimal_symbol *msymbol_hash[MINIMAL_SYMBOL_HASH_SIZE];
320
321     /* This hash table is used to index the minimal symbols by their
322        demangled names.  */
323
324     struct minimal_symbol *msymbol_demangled_hash[MINIMAL_SYMBOL_HASH_SIZE];
325
326     /* For object file formats which don't specify fundamental types, gdb
327        can create such types.  For now, it maintains a vector of pointers
328        to these internally created fundamental types on a per objfile basis,
329        however it really should ultimately keep them on a per-compilation-unit
330        basis, to account for linkage-units that consist of a number of
331        compilation units that may have different fundamental types, such as
332        linking C modules with ADA modules, or linking C modules that are
333        compiled with 32-bit ints with C modules that are compiled with 64-bit
334        ints (not inherently evil with a smarter linker). */
335
336     struct type **fundamental_types;
337
338     /* The mmalloc() malloc-descriptor for this objfile if we are using
339        the memory mapped malloc() package to manage storage for this objfile's
340        data.  NULL if we are not. */
341
342     void *md;
343
344     /* The file descriptor that was used to obtain the mmalloc descriptor
345        for this objfile.  If we call mmalloc_detach with the malloc descriptor
346        we should then close this file descriptor. */
347
348     int mmfd;
349
350     /* Structure which keeps track of functions that manipulate objfile's
351        of the same type as this objfile.  I.E. the function to read partial
352        symbols for example.  Note that this structure is in statically
353        allocated memory, and is shared by all objfiles that use the
354        object module reader of this type. */
355
356     struct sym_fns *sf;
357
358     /* The per-objfile information about the entry point, the scope (file/func)
359        containing the entry point, and the scope of the user's main() func. */
360
361     struct entry_info ei;
362
363     /* Information about stabs.  Will be filled in with a dbx_symfile_info
364        struct by those readers that need it. */
365
366     struct dbx_symfile_info *sym_stab_info;
367
368     /* Hook for information for use by the symbol reader (currently used
369        for information shared by sym_init and sym_read).  It is
370        typically a pointer to malloc'd memory.  The symbol reader's finish
371        function is responsible for freeing the memory thusly allocated.  */
372
373     void *sym_private;
374
375     /* Hook for target-architecture-specific information.  This must
376        point to memory allocated on one of the obstacks in this objfile,
377        so that it gets freed automatically when reading a new object
378        file. */
379
380     void *obj_private;
381
382     /* Set of relocation offsets to apply to each section.
383        Currently on the psymbol_obstack (which makes no sense, but I'm
384        not sure it's harming anything).
385
386        These offsets indicate that all symbols (including partial and
387        minimal symbols) which have been read have been relocated by this
388        much.  Symbols which are yet to be read need to be relocated by
389        it.  */
390
391     struct section_offsets *section_offsets;
392     int num_sections;
393
394     /* Indexes in the section_offsets array. These are initialized by the
395        *_symfile_offsets() family of functions (som_symfile_offsets,
396        xcoff_symfile_offsets, default_symfile_offsets). In theory they
397        should correspond to the section indexes used by bfd for the
398        current objfile. The exception to this for the time being is the
399        SOM version. */
400
401     int sect_index_text;
402     int sect_index_data;
403     int sect_index_bss;
404     int sect_index_rodata;
405
406     /* These pointers are used to locate the section table, which
407        among other things, is used to map pc addresses into sections.
408        SECTIONS points to the first entry in the table, and
409        SECTIONS_END points to the first location past the last entry
410        in the table.  Currently the table is stored on the
411        psymbol_obstack (which makes no sense, but I'm not sure it's
412        harming anything).  */
413
414     struct obj_section
415      *sections, *sections_end;
416
417     /* two auxiliary fields, used to hold the fp of separate symbol files */
418     FILE *auxf1, *auxf2;
419
420     /* Imported symbols */
421     ImportEntry *import_list;
422     int import_list_size;
423
424     /* Exported symbols */
425     ExportEntry *export_list;
426     int export_list_size;
427
428     /* Link to objfile that contains the debug symbols for this one.
429        One is loaded if this file has an debug link to an existing
430        debug file with the right checksum */
431     struct objfile *separate_debug_objfile;
432
433     /* If this is a separate debug object, this is used as a link to the
434        actual executable objfile. */
435     struct objfile *separate_debug_objfile_backlink;
436     
437     /* Place to stash various statistics about this objfile */
438       OBJSTATS;
439   };
440
441 /* Defines for the objfile flag word. */
442
443 /* Gdb can arrange to allocate storage for all objects related to a
444    particular objfile in a designated section of its address space,
445    managed at a low level by mmap() and using a special version of
446    malloc that handles malloc/free/realloc on top of the mmap() interface.
447    This allows the "internal gdb state" for a particular objfile to be
448    dumped to a gdb state file and subsequently reloaded at a later time. */
449
450 #define OBJF_MAPPED     (1 << 0)        /* Objfile data is mmap'd */
451
452 /* When using mapped/remapped predigested gdb symbol information, we need
453    a flag that indicates that we have previously done an initial symbol
454    table read from this particular objfile.  We can't just look for the
455    absence of any of the three symbol tables (msymbols, psymtab, symtab)
456    because if the file has no symbols for example, none of these will
457    exist. */
458
459 #define OBJF_SYMS       (1 << 1)        /* Have tried to read symbols */
460
461 /* When an object file has its functions reordered (currently Irix-5.2
462    shared libraries exhibit this behaviour), we will need an expensive
463    algorithm to locate a partial symtab or symtab via an address.
464    To avoid this penalty for normal object files, we use this flag,
465    whose setting is determined upon symbol table read in.  */
466
467 #define OBJF_REORDERED  (1 << 2)        /* Functions are reordered */
468
469 /* Distinguish between an objfile for a shared library and a "vanilla"
470    objfile. (If not set, the objfile may still actually be a solib.
471    This can happen if the user created the objfile by using the
472    add-symbol-file command.  GDB doesn't in that situation actually
473    check whether the file is a solib.  Rather, the target's
474    implementation of the solib interface is responsible for setting
475    this flag when noticing solibs used by an inferior.)  */
476
477 #define OBJF_SHARED     (1 << 3)        /* From a shared library */
478
479 /* User requested that this objfile be read in it's entirety. */
480
481 #define OBJF_READNOW    (1 << 4)        /* Immediate full read */
482
483 /* This objfile was created because the user explicitly caused it
484    (e.g., used the add-symbol-file command).  This bit offers a way
485    for run_command to remove old objfile entries which are no longer
486    valid (i.e., are associated with an old inferior), but to preserve
487    ones that the user explicitly loaded via the add-symbol-file
488    command. */
489
490 #define OBJF_USERLOADED (1 << 5)        /* User loaded */
491
492 /* The object file that the main symbol table was loaded from (e.g. the
493    argument to the "symbol-file" or "file" command).  */
494
495 extern struct objfile *symfile_objfile;
496
497 /* The object file that contains the runtime common minimal symbols
498    for SunOS4. Note that this objfile has no associated BFD.  */
499
500 extern struct objfile *rt_common_objfile;
501
502 /* When we need to allocate a new type, we need to know which type_obstack
503    to allocate the type on, since there is one for each objfile.  The places
504    where types are allocated are deeply buried in function call hierarchies
505    which know nothing about objfiles, so rather than trying to pass a
506    particular objfile down to them, we just do an end run around them and
507    set current_objfile to be whatever objfile we expect to be using at the
508    time types are being allocated.  For instance, when we start reading
509    symbols for a particular objfile, we set current_objfile to point to that
510    objfile, and when we are done, we set it back to NULL, to ensure that we
511    never put a type someplace other than where we are expecting to put it.
512    FIXME:  Maybe we should review the entire type handling system and
513    see if there is a better way to avoid this problem. */
514
515 extern struct objfile *current_objfile;
516
517 /* All known objfiles are kept in a linked list.  This points to the
518    root of this list. */
519
520 extern struct objfile *object_files;
521
522 /* Declarations for functions defined in objfiles.c */
523
524 extern struct objfile *allocate_objfile (bfd *, int);
525
526 extern int build_objfile_section_table (struct objfile *);
527
528 extern void terminate_minimal_symbol_table (struct objfile *objfile);
529
530 extern void put_objfile_before (struct objfile *, struct objfile *);
531
532 extern void objfile_to_front (struct objfile *);
533
534 extern void unlink_objfile (struct objfile *);
535
536 extern void free_objfile (struct objfile *);
537
538 extern struct cleanup *make_cleanup_free_objfile (struct objfile *);
539
540 extern void free_all_objfiles (void);
541
542 extern void objfile_relocate (struct objfile *, struct section_offsets *);
543
544 extern int have_partial_symbols (void);
545
546 extern int have_full_symbols (void);
547
548 /* This operation deletes all objfile entries that represent solibs that
549    weren't explicitly loaded by the user, via e.g., the add-symbol-file
550    command.
551  */
552 extern void objfile_purge_solibs (void);
553
554 /* Functions for dealing with the minimal symbol table, really a misc
555    address<->symbol mapping for things we don't have debug symbols for.  */
556
557 extern int have_minimal_symbols (void);
558
559 extern struct obj_section *find_pc_section (CORE_ADDR pc);
560
561 extern struct obj_section *find_pc_sect_section (CORE_ADDR pc,
562                                                  asection * section);
563
564 extern int in_plt_section (CORE_ADDR, char *);
565
566 extern int is_in_import_list (char *, struct objfile *);
567
568 /* Traverse all object files.  ALL_OBJFILES_SAFE works even if you delete
569    the objfile during the traversal.  */
570
571 #define ALL_OBJFILES(obj) \
572   for ((obj) = object_files; (obj) != NULL; (obj) = (obj)->next)
573
574 #define ALL_OBJFILES_SAFE(obj,nxt) \
575   for ((obj) = object_files;       \
576        (obj) != NULL? ((nxt)=(obj)->next,1) :0; \
577        (obj) = (nxt))
578
579 /* Traverse all symtabs in one objfile.  */
580
581 #define ALL_OBJFILE_SYMTABS(objfile, s) \
582     for ((s) = (objfile) -> symtabs; (s) != NULL; (s) = (s) -> next)
583
584 /* Traverse all psymtabs in one objfile.  */
585
586 #define ALL_OBJFILE_PSYMTABS(objfile, p) \
587     for ((p) = (objfile) -> psymtabs; (p) != NULL; (p) = (p) -> next)
588
589 /* Traverse all minimal symbols in one objfile.  */
590
591 #define ALL_OBJFILE_MSYMBOLS(objfile, m) \
592     for ((m) = (objfile) -> msymbols; DEPRECATED_SYMBOL_NAME(m) != NULL; (m)++)
593
594 /* Traverse all symtabs in all objfiles.  */
595
596 #define ALL_SYMTABS(objfile, s) \
597   ALL_OBJFILES (objfile)         \
598     ALL_OBJFILE_SYMTABS (objfile, s)
599
600 /* Traverse all psymtabs in all objfiles.  */
601
602 #define ALL_PSYMTABS(objfile, p) \
603   ALL_OBJFILES (objfile)         \
604     ALL_OBJFILE_PSYMTABS (objfile, p)
605
606 /* Traverse all minimal symbols in all objfiles.  */
607
608 #define ALL_MSYMBOLS(objfile, m) \
609   ALL_OBJFILES (objfile)         \
610     ALL_OBJFILE_MSYMBOLS (objfile, m)
611
612 #define ALL_OBJFILE_OSECTIONS(objfile, osect)   \
613   for (osect = objfile->sections; osect < objfile->sections_end; osect++)
614
615 #define ALL_OBJSECTIONS(objfile, osect)         \
616   ALL_OBJFILES (objfile)                        \
617     ALL_OBJFILE_OSECTIONS (objfile, osect)
618
619 #define SECT_OFF_DATA(objfile) \
620      ((objfile->sect_index_data == -1) \
621       ? (internal_error (__FILE__, __LINE__, "sect_index_data not initialized"), -1) \
622       : objfile->sect_index_data)
623
624 #define SECT_OFF_RODATA(objfile) \
625      ((objfile->sect_index_rodata == -1) \
626       ? (internal_error (__FILE__, __LINE__, "sect_index_rodata not initialized"), -1) \
627       : objfile->sect_index_rodata)
628
629 #define SECT_OFF_TEXT(objfile) \
630      ((objfile->sect_index_text == -1) \
631       ? (internal_error (__FILE__, __LINE__, "sect_index_text not initialized"), -1) \
632       : objfile->sect_index_text)
633
634 /* Sometimes the .bss section is missing from the objfile, so we don't
635    want to die here. Let the users of SECT_OFF_BSS deal with an
636    uninitialized section index. */
637 #define SECT_OFF_BSS(objfile) (objfile)->sect_index_bss
638
639 #endif /* !defined (OBJFILES_H) */