\input texinfo
@setfilename gdb-internals
+@c $Id$
@ifinfo
This file documents the internals of the GNU debugger GDB.
* Releases:: Configuring GDB for release
* README:: The README file
* New Architectures:: Defining a new host or target architecture
+* BFD support for GDB:: How BFD and GDB interface
* Host versus Target:: What features are in which files
* Symbol Reading:: Defining new symbol readers
-
@end menu
@node Cleanups, Wrapping, Top, Top
Syntax:
@table @code
-@item old_chain = make_cleanup (function, arg);
-This makes a cleanup which will cause FUNCTION to be called with ARG
-(a char *) later. The result, OLD_CHAIN, is a handle that can be
-passed to do_cleanups or discard_cleanups later. Unless you are
-going to call do_cleanups or discard_cleanups yourself,
-you can ignore the result from make_cleanup.
-
-
-@item do_cleanups (old_chain);
-Performs all cleanups done since make_cleanup returned OLD_CHAIN.
-E.g.: make_cleanup (a, 0); old = make_cleanup (b, 0); do_cleanups (old);
-will call b() but will not call a(). The cleanup that calls a() will remain
-in the cleanup chain, and will be done later unless otherwise discarded.
-
-@item discard_cleanups (old_chain);
-Same as do_cleanups except that it just removes the cleanups from the
+@item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
+Make a cleanup which will cause @var{function} to be called with @var{arg}
+(a @code{char *}) later. The result, @var{old_chain}, is a handle that can be
+passed to @code{do_cleanups} or @code{discard_cleanups} later. Unless you are
+going to call @code{do_cleanups} or @code{discard_cleanups} yourself,
+you can ignore the result from @code{make_cleanup}.
+
+
+@item do_cleanups (@var{old_chain});
+Perform all cleanups done since @code{make_cleanup} returned @var{old_chain}.
+E.g.:
+@example
+make_cleanup (a, 0);
+old = make_cleanup (b, 0);
+do_cleanups (old);
+@end example
+@noindent
+will call @code{b()} but will not call @code{a()}. The cleanup that calls @code{a()} will remain
+in the cleanup chain, and will be done later unless otherwise discarded.@refill
+
+@item discard_cleanups (@var{old_chain});
+Same as @code{do_cleanups} except that it just removes the cleanups from the
chain and does not call the specified functions.
@end table
-@node New Architectures, Host versus Target, README, Top
+@node New Architectures, BFD support for GDB, README, Top
@chapter Defining a new host or target architecture
Object files needed when the host system is an @var{ARCH} are listed in
the file @file{xconfig/@var{ARCH}}, in the Makefile macro @samp{XDEPFILES
-= }@dots{}. You can also define XXXXXX in there.
+= }@dots{}. The header file that defines the host system should be
+called xm-@var{ARCH}.h, and should be specified as the value of @samp{XM_FILE=}
+in @file{xconfig/@var{ARCH}}.
+You can also define @samp{CC}, @samp{REGEX} and @samp{REGEX1},
+@samp{SYSV_DEFINE}, @samp{XM_CFLAGS}, etc in there; see @file{Makefile.in}.
There are some ``generic'' versions of routines that can be used by
various host systems. If these routines work for the @var{ARCH} host,
@code{register_addr(}), see below.
@item register_addr()
-If your @code{xm-@var{ARCH}.h} file defines the macro @code{REGISTER_U_ADDR(reg)} to be the
-offset within the @samp{user} struct of a register (represented as a GDB
-register number), @file{coredep.c} will define the @code{register_addr()} function
-and use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but
-you are using the standard @code{fetch_core_registers}, you
-will need to define your own version of @code{register_addr}, put it into
-your @code{@var{ARCH}-xdep.c} file, and be sure @code{@var{ARCH}-xdep.o} is in the @code{XDEPFILES} list.
-If you have your own @code{fetch_core_registers}, you only need to define
-@code{register_addr} if your @code{fetch_core_registers} calls it. Many custom
-@code{fetch_core_registers} implementations simply locate the registers
-themselves.
+If your @code{xm-@var{ARCH}.h} file defines the macro
+@code{REGISTER_U_ADDR(reg)} to be the offset within the @samp{user}
+struct of a register (represented as a GDB register number),
+@file{coredep.c} will define the @code{register_addr()} function and use
+the macro in it. If you do not define @code{REGISTER_U_ADDR}, but you
+are using the standard @code{fetch_core_registers}, you will need to
+define your own version of @code{register_addr}, put it into your
+@code{@var{ARCH}-xdep.c} file, and be sure @code{@var{ARCH}-xdep.o} is
+in the @code{XDEPFILES} list. If you have your own
+@code{fetch_core_registers}, you only need to define
+@code{register_addr} if your @code{fetch_core_registers} calls it. Many
+custom @code{fetch_core_registers} implementations simply locate the
+registers themselves.@refill
@end table
-Files needed when the target system is an @var{ARCH} are listed in the file
-@file{tconfig/@var{ARCH}}, in the @code{Makefile} macro @samp{TDEPFILES = }@dots{}. You can also
-define XXXXXX in there.
+Object files needed when the target system is an @var{ARCH} are listed in
+the file @file{tconfig/@var{ARCH}}, in the Makefile macro @samp{TDEPFILES
+= }@dots{}. The header file that defines the target system should be
+called tm-@var{ARCH}.h, and should be specified as the value of @samp{TM_FILE}
+in @file{tconfig/@var{ARCH}}.
+You can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, and @samp{TM_CDEPS}
+in there; see @file{Makefile.in}.
Similar generic support files for target systems are:
etc. Now that executable files are handled with BFD, every architecture
should be able to use the generic exec.c rather than its own custom code.
-@node Host versus Target, Symbol Reading, New Architectures, Top
+@node BFD support for GDB, Host versus Target, New Architectures, Top
+@chapter Binary File Descriptor library support for GDB
+
+BFD provides support for GDB in several ways:
+
+@table @emph
+@item identifying executable and core files
+BFD will identify a variety of file types, including a.out, coff, and
+several variants thereof, as well as several kinds of core files.
+
+@item access to sections of files
+BFD parses the file headers to determine the names, virtual addresses,
+sizes, and file locations of all the various named sections in files
+(such as the text section or the data section). GDB simply calls
+BFD to read or write section X at byte offset Y for length Z.
+
+@item specialized core file support
+BFD provides routines to determine the failing command name stored
+in a core file, the signal with which the program failed, and whether
+a core file matches (i.e. could be a core dump of) a particular executable
+file.
+
+@item locating the symbol information
+GDB uses an internal interface of BFD to determine where to find the
+symbol information in an executable file or symbol-file. GDB itself
+handles the reading of symbols, since BFD does not ``understand'' debug
+symbols, but GDB uses BFD's cached information to find the symbols,
+string table, etc.
+@end table
+
+When porting GDB to a new operating system, you will need to either
+write specific code for parsing your OS's core files, or customize
+bfd/trad-core.c. First, use whatever #include files your machine uses
+to define the struct of registers that is accessible (possibly in the
+upage) in a core file (rather than <machine/reg.h>), and an include
+file that defines whatever header exists on a core file (e.g. the
+u-area or a "struct core"). Then modify @samp{trad_unix_core_file_p}
+to use these values to set up the section information for the data
+segment, stack segment, any other segments in the core file (perhaps
+shared library contents or control information), "registers" segment,
+and if there are two discontiguous sets of registers (e.g. integer and
+float), the "reg2" segment. This section information basically
+delimits areas in the core file in a standard way, which the
+section-reading routines in BFD know how to seek around in.
+
+Then back in GDB, you need a matching routine called fetch_core_registers.
+If you can use the generic one, it's in core-dep.c; if not, it's in
+your xm-foobar.c file. It will be passed a char pointer
+to the entire "registers" segment, its length, and a zero; or a char
+pointer to the entire "regs2" segment, its length, and a 2. The
+routine should suck out the supplied register values and install them into
+gdb's "registers" array. (@xref{New Architectures}
+for more info about this.)
+
+The interface for symbol reading is described in @xref{Symbol Reading}.
+
+@node Host versus Target, Symbol Reading, BFD support for GDB, Top
@chapter What is considered ``host-dependent'' versus ``target-dependent''?
The xconfig/*, xm-*.h and *-xdep.c files are for host support. The
actually, partly as a result of BFD and partly by removing duplicated
code.
+@menu
+* New Host:: Adding a New Host
+* New Target:: Adding a New Target
+* New Config:: Extending @code{configure}
+@end menu
-@node Symbol Reading, , Host Versus Target, Top
+@node New Host, New Target, Host versus Target, Host versus Target
+@section Adding a New Host
+
+@node New Target, New Config, New Host, Host versus Target
+@section Adding a New Target
+
+@node New Config, , New Target, Host versus Target
+@section Extending @code{configure}
+Once you have added a new host, target, or both, you'll also need to
+extend the @code{configure} script to recognize the new configuration
+possibilities.
+
+You shouldn't edit the @code{configure} script itself to add hosts or
+targets; instead, edit the script fragments in the file
+@code{configure.in}. To handle new hosts, modify the segment after the
+comment @samp{# per-host}; to handle new targets, modify after @samp{#
+per-target}.
+@c Would it be simpler to just use different per-host and per-target
+@c *scripts*, and call them from {configure} ?
+
+Then fold your changes into the @code{configure} script by using the
+@code{+template} option, and specifying @code{configure} itself as the
+template:
+@example
+configure +template=configure
+@end example
+@c If "configure" is the only workable option value for +template, it's
+@c kind of silly to insist that it be provided. If it isn't, somebody
+@c please fill in here what are others... (then delete this comment!)
+
+@node Symbol Reading, , Host versus Target, Top
@chapter Symbol Reading
GDB reads symbols from "symbol files". The usual symbol file is the
Called from @code{symbol_file_add} to actually read the symbols from a
symbol-file into a set of psymtabs or symtabs.
-@code{sf} points to the struct sym_fns originally passed to @code{XXX_sym_init} for possible initialization.
-@code{addr} is the offset between the file's specified start address and
-its true address in memory. @code{mainline} is 1 if this is the
-main symbol table being read, and 0 if a secondary
-symbol file (e.g. shared library or dynamically loaded file)
-is being read.
-
+@code{sf} points to the struct sym_fns originally passed to
+@code{XXX_sym_init} for possible initialization. @code{addr} is the
+offset between the file's specified start address and its true address
+in memory. @code{mainline} is 1 if this is the main symbol table being
+read, and 0 if a secondary symbol file (e.g. shared library or
+dynamically loaded file) is being read.@refill
@end table
In addition, if a symbol-reading module creates psymtabs when
projects / binutils-gdb.git / commitdiff