diff options
Diffstat (limited to 'gnu/usr.bin/gdb/doc/gdbint.texinfo')
| -rw-r--r-- | gnu/usr.bin/gdb/doc/gdbint.texinfo | 2658 |
1 files changed, 2658 insertions, 0 deletions
diff --git a/gnu/usr.bin/gdb/doc/gdbint.texinfo b/gnu/usr.bin/gdb/doc/gdbint.texinfo new file mode 100644 index 000000000000..d158bac8f81a --- /dev/null +++ b/gnu/usr.bin/gdb/doc/gdbint.texinfo @@ -0,0 +1,2658 @@ +\input texinfo +@setfilename gdbint.info +@c $Id: gdbint.texinfo,v 1.1 1994/06/10 13:34:28 paul Exp $ + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Gdb-Internals: (gdbint). The GNU debugger's internals. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@ifinfo +This file documents the internals of the GNU debugger GDB. + +Copyright 1990, 1991, 1992, 1993 Free Software Foundation, Inc. +Contributed by Cygnus Support. Written by John Gilmore. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy or distribute modified versions of this +manual under the terms of the GPL (for which purpose this text may be +regarded as a program in the language TeX). +@end ifinfo + +@setchapternewpage off +@settitle GDB Internals +@titlepage +@title{Working in GDB} +@subtitle{A guide to the internals of the GNU debugger} +@author John Gilmore +@author Cygnus Support +@page +@tex +\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ +\xdef\manvers{\$Revision: 1.1 $} % For use in headers, footers too +{\parskip=0pt +\hfill Cygnus Support\par +\hfill \manvers\par +\hfill \TeX{}info \texinfoversion\par +} +@end tex + +@vskip 0pt plus 1filll +Copyright @copyright{} 1990, 1991, 1992, 1993 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@end titlepage + +@node Top +@c Perhaps this should be the title of the document (but only for info, +@c not for TeX). Existing GNU manuals seem inconsistent on this point. +@top Scope of this Document + +This document documents the internals of the GNU debugger, GDB. It is +intended to document aspects of GDB which apply across many different +parts of GDB (for example, @pxref{Coding Style}), or which are global +aspects of design (for example, what are the major modules and which +files document them in detail?). Information which pertains to specific +data structures, functions, variables, etc., should be put in comments +in the source code, not here. It is more likely to get noticed and kept +up to date there. Some of the information in this document should +probably be moved into comments. + +@menu +* README:: The README File +* Getting Started:: Getting started working on GDB +* Debugging GDB:: Debugging GDB with itself +* New Architectures:: Defining a New Host or Target Architecture +* Config:: Adding a New Configuration +* Host:: Adding a New Host +* Native:: Adding a New Native Configuration +* Target:: Adding a New Target +* Languages:: Defining New Source Languages +* Releases:: Configuring GDB for Release +* Partial Symbol Tables:: How GDB reads symbols quickly at startup +* Types:: How GDB keeps track of types +* BFD support for GDB:: How BFD and GDB interface +* Symbol Reading:: Defining New Symbol Readers +* Cleanups:: Cleanups +* Wrapping:: Wrapping Output Lines +* Frames:: Keeping track of function calls +* Remote Stubs:: Code that runs in targets and talks to GDB +* Longjmp Support:: Stepping through longjmp's in the target +* Coding Style:: Strunk and White for GDB maintainers +* Clean Design:: Frank Lloyd Wright for GDB maintainers +* Submitting Patches:: How to get your changes into GDB releases +* Host Conditionals:: What features exist in the host +* Target Conditionals:: What features exist in the target +* Native Conditionals:: Conditionals for when host and target are same +* Obsolete Conditionals:: Conditionals that don't exist any more +* XCOFF:: The Object file format used on IBM's RS/6000 +@end menu + +@node README +@chapter The @file{README} File + +Check the @file{README} file, it often has useful information that does not +appear anywhere else in the directory. + +@node Getting Started +@chapter Getting Started Working on GDB + +GDB is a large and complicated program, and if you first starting to +work on it, it can be hard to know where to start. Fortunately, if you +know how to go about it, there are ways to figure out what is going on: + +@itemize @bullet +@item +This manual, the GDB Internals manual, has information which applies +generally to many parts of GDB. + +@item +Information about particular functions or data structures are located in +comments with those functions or data structures. If you run across a +function or a global variable which does not have a comment correctly +explaining what is does, this can be thought of as a bug in GDB; feel +free to submit a bug report, with a suggested comment if you can figure +out what the comment should say (@pxref{Submitting Patches}). If you +find a comment which is actually wrong, be especially sure to report that. + +Comments explaining the function of macros defined in host, target, or +native dependent files can be in several places. Sometimes they are +repeated every place the macro is defined. Sometimes they are where the +macro is used. Sometimes there is a header file which supplies a +default definition of the macro, and the comment is there. This manual +also has a list of macros (@pxref{Host Conditionals}, @pxref{Target +Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete +Conditionals}) with some documentation. + +@item +Start with the header files. Once you some idea of how GDB's internal +symbol tables are stored (see @file{symtab.h}, @file{gdbtypes.h}), you +will find it much easier to understand the code which uses and creates +those symbol tables. + +@item +You may wish to process the information you are getting somehow, to +enhance your understanding of it. Summarize it, translate it to another +language, add some (perhaps trivial or non-useful) feature to GDB, use +the code to predict what a test case would do and write the test case +and verify your prediction, etc. If you are reading code and your eyes +are starting to glaze over, this is a sign you need to use a more active +approach. + +@item +Once you have a part of GDB to start with, you can find more +specifically the part you are looking for by stepping through each +function with the @code{next} command. Do not use @code{step} or you +will quickly get distracted; when the function you are stepping through +calls another function try only to get a big-picture understanding +(perhaps using the comment at the beginning of the function being +called) of what it does. This way you can identify which of the +functions being called by the function you are stepping through is the +one which you are interested in. You may need to examine the data +structures generated at each stage, with reference to the comments in +the header files explaining what the data structures are supposed to +look like. + +Of course, this same technique can be used if you are just reading the +code, rather than actually stepping through it. The same general +principle applies---when the code you are looking at calls something +else, just try to understand generally what the code being called does, +rather than worrying about all its details. + +@item +A good place to start when tracking down some particular area is with a +command which invokes that feature. Suppose you want to know how +single-stepping works. As a GDB user, you know that the @code{step} +command invokes single-stepping. The command is invoked via command +tables (see @file{command.h}); by convention the function which actually +performs the command is formed by taking the name of the command and +adding @samp{_command}, or in the case of an @code{info} subcommand, +@samp{_info}. For example, the @code{step} command invokes the +@code{step_command} function and the @code{info display} command invokes +@code{display_info}. When this convention is not followed, you might +have to use @code{grep} or @kbd{M-x tags-search} in emacs, or run GDB on +itself and set a breakpoint in @code{execute_command}. + +@item +If all of the above fail, it may be appropriate to ask for information +on @code{bug-gdb}. But @emph{never} post a generic question like ``I was +wondering if anyone could give me some tips about understanding +GDB''---if we had some magic secret we would put it in this manual. +Suggestions for improving the manual are always welcome, of course. +@end itemize + +Good luck! + +@node Debugging GDB +@chapter Debugging GDB with itself +If gdb is limping on your machine, this is the preferred way to get it +fully functional. Be warned that in some ancient Unix systems, like +Ultrix 4.2, a program can't be running in one process while it is being +debugged in another. Rather than typing the command @code{@w{./gdb +./gdb}}, which works on Suns and such, you can copy @file{gdb} to +@file{gdb2} and then type @code{@w{./gdb ./gdb2}}. + +When you run gdb in the gdb source directory, it will read a +@file{.gdbinit} file that sets up some simple things to make debugging +gdb easier. The @code{info} command, when executed without a subcommand +in a gdb being debugged by gdb, will pop you back up to the top level +gdb. See @file{.gdbinit} for details. + +If you use emacs, you will probably want to do a @code{make TAGS} after +you configure your distribution; this will put the machine dependent +routines for your local machine where they will be accessed first by +@kbd{M-.} + +Also, make sure that you've either compiled gdb with your local cc, or +have run @code{fixincludes} if you are compiling with gcc. + +@node New Architectures +@chapter Defining a New Host or Target Architecture + +When building support for a new host and/or target, much of the work you +need to do is handled by specifying configuration files; +@pxref{Config,,Adding a New Configuration}. Further work can be +divided into ``host-dependent'' (@pxref{Host,,Adding a New Host}) and +``target-dependent'' (@pxref{Target,,Adding a New Target}). The +following discussion is meant to explain the difference between hosts +and targets. + +@heading What is considered ``host-dependent'' versus ``target-dependent''? + +@dfn{Host} refers to attributes of the system where GDB runs. +@dfn{Target} refers to the system where the program being debugged +executes. In most cases they are the same machine, in which case +a third type of @dfn{Native} attributes come into play. + +Defines and include files needed to build on the host are host support. +Examples are tty support, system defined types, host byte order, host +float format. + +Defines and information needed to handle the target format are target +dependent. Examples are the stack frame format, instruction set, +breakpoint instruction, registers, and how to set up and tear down the stack +to call a function. + +Information that is only needed when the host and target are the same, +is native dependent. One example is Unix child process support; if the +host and target are not the same, doing a fork to start the target +process is a bad idea. The various macros needed for finding the +registers in the @code{upage}, running @code{ptrace}, and such are all in the +native-dependent files. + +Another example of native-dependent code is support for features +that are really part of the target environment, but which require +@code{#include} files that are only available on the host system. +Core file handling and @code{setjmp} handling are two common cases. + +When you want to make GDB work ``native'' on a particular +machine, you have to include all three kinds of information. + +The dependent information in GDB is organized into files by naming +conventions. + +Host-Dependent Files +@table @file +@item config/*/*.mh +Sets Makefile parameters +@item config/*/xm-*.h +Global #include's and #define's and definitions +@item *-xdep.c +Global variables and functions +@end table + +Native-Dependent Files +@table @file +@item config/*/*.mh +Sets Makefile parameters (for @emph{both} host and native) +@item config/*/nm-*.h +#include's and #define's and definitions. This file +is only included by the small number of modules that need it, +so beware of doing feature-test #define's from its macros. +@item *-nat.c +global variables and functions +@end table + +Target-Dependent Files +@table @file +@item config/*/*.mt +Sets Makefile parameters +@item config/*/tm-*.h +Global #include's and #define's and definitions +@item *-tdep.c +Global variables and functions +@end table + +At this writing, most supported hosts have had their host and native +dependencies sorted out properly. There are a few stragglers, which +can be recognized by the absence of NATDEPFILES lines in their +@file{config/*/*.mh}. + +@node Config +@chapter Adding a New Configuration + +Most of the work in making GDB compile on a new machine is in specifying +the configuration of the machine. This is done in a dizzying variety of +header files and configuration scripts, which we hope to make more +sensible soon. Let's say your new host is called an @var{xxx} (e.g. +@samp{sun4}), and its full three-part configuration name is +@code{@var{xarch}-@var{xvend}-@var{xos}} (e.g. @samp{sparc-sun-sunos4}). In +particular: + +In the top level directory, edit @file{config.sub} and add @var{xarch}, +@var{xvend}, and @var{xos} to the lists of supported architectures, +vendors, and operating systems near the bottom of the file. Also, add +@var{xxx} as an alias that maps to +@code{@var{xarch}-@var{xvend}-@var{xos}}. You can test your changes by +running + +@example +./config.sub @var{xxx} +@end example +@noindent +and +@example +./config.sub @code{@var{xarch}-@var{xvend}-@var{xos}} +@end example +@noindent +which should both respond with @code{@var{xarch}-@var{xvend}-@var{xos}} +and no error messages. + +Now, go to the @file{bfd} directory and +create a new file @file{bfd/hosts/h-@var{xxx}.h}. Examine the +other @file{h-*.h} files as templates, and create one that brings in the +right include files for your system, and defines any host-specific +macros needed by BFD, the Binutils, GNU LD, or the Opcodes directories. +(They all share the bfd @file{hosts} directory and the @file{configure.host} +file.) + +Then edit @file{bfd/configure.host}. Add a line to recognize your +@code{@var{xarch}-@var{xvend}-@var{xos}} configuration, and set +@code{my_host} to @var{xxx} when you recognize it. This will cause your +file @file{h-@var{xxx}.h} to be linked to @file{sysdep.h} at configuration +time. When creating the line that recognizes your configuration, +only match the fields that you really need to match; e.g. don't match +match the architecture or manufacturer if the OS is sufficient +to distinguish the configuration that your @file{h-@var{xxx}.h} file supports. +Don't match the manufacturer name unless you really need to. +This should make future ports easier. + +Also, if this host requires any changes to the Makefile, create a file +@file{bfd/config/@var{xxx}.mh}, which includes the required lines. + +It's possible that the @file{libiberty} and @file{readline} directories +won't need any changes for your configuration, but if they do, you can +change the @file{configure.in} file there to recognize your system and +map to an @file{mh-@var{xxx}} file. Then add @file{mh-@var{xxx}} +to the @file{config/} subdirectory, to set any makefile variables you +need. The only current options in there are things like @samp{-DSYSV}. +(This @file{mh-@var{xxx}} naming convention differs from elsewhere +in GDB, by historical accident. It should be cleaned up so that all +such files are called @file{@var{xxx}.mh}.) + +Aha! Now to configure GDB itself! Edit +@file{gdb/configure.in} to recognize your system and set @code{gdb_host} +to @var{xxx}, and (unless your desired target is already available) also +set @code{gdb_target} to something appropriate (for instance, +@var{xxx}). 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} ? + +Finally, you'll need to specify and define GDB's host-, native-, and +target-dependent @file{.h} and @file{.c} files used for your +configuration; the next two chapters discuss those. + + +@node Host +@chapter Adding a New Host + +Once you have specified a new configuration for your host +(@pxref{Config,,Adding a New Configuration}), there are three remaining +pieces to making GDB work on a new machine. First, you have to make it +host on the new machine (compile there, handle that machine's terminals +properly, etc). If you will be cross-debugging to some other kind of +system that's already supported, you are done. + +If you want to use GDB to debug programs that run on the new machine, +you have to get it to understand the machine's object files, symbol +files, and interfaces to processes; @pxref{Target,,Adding a New Target} +and @pxref{Native,,Adding a New Native Configuration} + +Several files control GDB's configuration for host systems: + +@table @file +@item gdb/config/@var{arch}/@var{xxx}.mh +Specifies Makefile fragments needed when hosting on machine @var{xxx}. +In particular, this lists the required machine-dependent object files, +by defining @samp{XDEPFILES=@dots{}}. Also +specifies the header file which describes host @var{xxx}, by defining +@code{XM_FILE= xm-@var{xxx}.h}. You can also define @code{CC}, +@code{REGEX} and @code{REGEX1}, @code{SYSV_DEFINE}, @code{XM_CFLAGS}, +@code{XM_ADD_FILES}, @code{XM_CLIBS}, @code{XM_CDEPS}, +etc.; see @file{Makefile.in}. + +@item gdb/config/@var{arch}/xm-@var{xxx}.h +(@file{xm.h} is a link to this file, created by configure). +Contains C macro definitions describing the host system environment, +such as byte order, host C compiler and library, ptrace support, +and core file structure. Crib from existing @file{xm-*.h} files +to create a new one. + +@item gdb/@var{xxx}-xdep.c +Contains any miscellaneous C code required for this machine +as a host. On many machines it doesn't exist at all. If it does +exist, put @file{@var{xxx}-xdep.o} into the @code{XDEPFILES} line +in @file{gdb/config/mh-@var{xxx}}. +@end table + +@subheading Generic Host Support Files + +There are some ``generic'' versions of routines that can be used by +various systems. These can be customized in various ways by macros +defined in your @file{xm-@var{xxx}.h} file. If these routines work for +the @var{xxx} host, you can just include the generic file's name (with +@samp{.o}, not @samp{.c}) in @code{XDEPFILES}. + +Otherwise, if your machine needs custom support routines, you will need +to write routines that perform the same functions as the generic file. +Put them into @code{@var{xxx}-xdep.c}, and put @code{@var{xxx}-xdep.o} +into @code{XDEPFILES}. + +@table @file +@item ser-bsd.c +This contains serial line support for Berkeley-derived Unix systems. + +@item ser-go32.c +This contains serial line support for 32-bit programs running under DOS +using the GO32 execution environment. + +@item ser-termios.c +This contains serial line support for System V-derived Unix systems. +@end table + +Now, you are now ready to try configuring GDB to compile using your system +as its host. From the top level (above @file{bfd}, @file{gdb}, etc), do: + +@example +./configure @var{xxx} +target=vxworks960 +@end example + +This will configure your system to cross-compile for VxWorks on +the Intel 960, which is probably not what you really want, but it's +a test case that works at this stage. (You haven't set up to be +able to debug programs that run @emph{on} @var{xxx} yet.) + +If this succeeds, you can try building it all with: + +@example +make +@end example + +Repeat until the program configures, compiles, links, and runs. +When run, it won't be able to do much (unless you have a VxWorks/960 +board on your network) but you will know that the host support is +pretty well done. + +Good luck! Comments and suggestions about this section are particularly +welcome; send them to @samp{bug-gdb@@prep.ai.mit.edu}. + +@node Native +@chapter Adding a New Native Configuration + +If you are making GDB run native on the @var{xxx} machine, you have +plenty more work to do. Several files control GDB's configuration for +native support: + +@table @file +@item gdb/config/@var{xarch}/@var{xxx}.mh +Specifies Makefile fragments needed when hosting @emph{or native} +on machine @var{xxx}. +In particular, this lists the required native-dependent object files, +by defining @samp{NATDEPFILES=@dots{}}. Also +specifies the header file which describes native support on @var{xxx}, +by defining @samp{NAT_FILE= nm-@var{xxx}.h}. +You can also define @samp{NAT_CFLAGS}, +@samp{NAT_ADD_FILES}, @samp{NAT_CLIBS}, @samp{NAT_CDEPS}, +etc.; see @file{Makefile.in}. + +@item gdb/config/@var{arch}/nm-@var{xxx}.h +(@file{nm.h} is a link to this file, created by configure). +Contains C macro definitions describing the native system environment, +such as child process control and core file support. +Crib from existing @file{nm-*.h} files to create a new one. + +@item gdb/@var{xxx}-nat.c +Contains any miscellaneous C code required for this native support +of this machine. On some machines it doesn't exist at all. +@end table + +@subheading Generic Native Support Files + +There are some ``generic'' versions of routines that can be used by +various systems. These can be customized in various ways by macros +defined in your @file{nm-@var{xxx}.h} file. If these routines work for +the @var{xxx} host, you can just include the generic file's name (with +@samp{.o}, not @samp{.c}) in @code{NATDEPFILES}. + +Otherwise, if your machine needs custom support routines, you will need +to write routines that perform the same functions as the generic file. +Put them into @code{@var{xxx}-nat.c}, and put @code{@var{xxx}-nat.o} +into @code{NATDEPFILES}. + +@table @file + +@item inftarg.c +This contains the @emph{target_ops vector} that supports Unix child +processes on systems which use ptrace and wait to control the child. + +@item procfs.c +This contains the @emph{target_ops vector} that supports Unix child +processes on systems which use /proc to control the child. + +@item fork-child.c +This does the low-level grunge that uses Unix system calls +to do a "fork and exec" to start up a child process. + +@item infptrace.c +This is the low level interface to inferior processes for systems +using the Unix @code{ptrace} call in a vanilla way. + +@item coredep.c::fetch_core_registers() +Support for reading registers out of a core file. This routine calls +@code{register_addr()}, see below. +Now that BFD is used to read core files, virtually all machines should +use @code{coredep.c}, and should just provide @code{fetch_core_registers} in +@code{@var{xxx}-nat.c} (or @code{REGISTER_U_ADDR} in @code{nm-@var{xxx}.h}). + +@item coredep.c::register_addr() +If your @code{nm-@var{xxx}.h} file defines the macro +@code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to +set @code{addr} to the offset within the @samp{user} +struct of GDB register number @code{regno}. @code{blockend} is the +offset within the ``upage'' of @code{u.u_ar0}. +If @code{REGISTER_U_ADDR} is defined, +@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{xxx}-nat.c} file, and be sure @code{@var{xxx}-nat.o} is in +the @code{NATDEPFILES} list. If you have your own +@code{fetch_core_registers()}, you may not need a separate +@code{register_addr()}. Many custom @code{fetch_core_registers()} +implementations simply locate the registers themselves.@refill +@end table + +When making GDB run native on a new operating system, +to make it possible to debug +core files, you will need to either write specific code for parsing your +OS's core files, or customize @file{bfd/trad-core.c}. First, use +whatever @code{#include} files your machine uses to define the struct of +registers that is accessible (possibly in the u-area) in a core file +(rather than @file{machine/reg.h}), and an include file that defines whatever +header exists on a core file (e.g. the u-area or a @samp{struct core}). Then +modify @code{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 +@code{fetch_core_registers()}. If you can use the generic one, it's in +@file{coredep.c}; if not, it's in your @file{@var{xxx}-nat.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,,Defining a New Host or Target Architecture}, +for more info about this.) + +If your system uses @file{/proc} to control processes, and uses ELF +format core files, then you may be able to use the same routines +for reading the registers out of processes and out of core files. + +@node Target +@chapter Adding a New Target + +For a new target called @var{ttt}, first specify the configuration as +described in @ref{Config,,Adding a New Configuration}. If your new +target is the same as your new host, you've probably already done that. + +A variety of files specify attributes of the GDB target environment: + +@table @file +@item gdb/config/@var{arch}/@var{ttt}.mt +Contains a Makefile fragment specific to this target. +Specifies what object files are needed for target @var{ttt}, by +defining @samp{TDEPFILES=@dots{}}. +Also specifies the header file which describes @var{ttt}, by defining +@samp{TM_FILE= tm-@var{ttt}.h}. You can also define @samp{TM_CFLAGS}, +@samp{TM_CLIBS}, @samp{TM_CDEPS}, +and other Makefile variables here; see @file{Makefile.in}. + +@item gdb/config/@var{arch}/tm-@var{ttt}.h +(@file{tm.h} is a link to this file, created by configure). +Contains macro definitions about the target machine's +registers, stack frame format and instructions. +Crib from existing @file{tm-*.h} files when building a new one. + +@item gdb/@var{ttt}-tdep.c +Contains any miscellaneous code required for this target machine. +On some machines it doesn't exist at all. Sometimes the macros +in @file{tm-@var{ttt}.h} become very complicated, so they are +implemented as functions here instead, and the macro is simply +defined to call the function. + +@item gdb/exec.c +Defines functions for accessing files that are +executable on the target system. These functions open and examine an +exec file, extract data from one, write data to one, print information +about one, etc. Now that executable files are handled with BFD, every +target should be able to use the generic exec.c rather than its +own custom code. + +@item gdb/@var{arch}-pinsn.c +Prints (disassembles) the target machine's instructions. +This file is usually shared with other target machines which use the +same processor, which is why it is @file{@var{arch}-pinsn.c} rather +than @file{@var{ttt}-pinsn.c}. + +@item gdb/@var{arch}-opcode.h +Contains some large initialized +data structures describing the target machine's instructions. +This is a bit strange for a @file{.h} file, but it's OK since +it is only included in one place. @file{@var{arch}-opcode.h} is shared +between the debugger and the assembler, if the GNU assembler has been +ported to the target machine. + +@item gdb/config/@var{arch}/tm-@var{arch}.h +This often exists to describe the basic layout of the target machine's +processor chip (registers, stack, etc). +If used, it is included by @file{tm-@var{xxx}.h}. It can +be shared among many targets that use the same processor. + +@item gdb/@var{arch}-tdep.c +Similarly, there are often common subroutines that are shared by all +target machines that use this particular architecture. +@end table + +When adding support for a new target machine, there are various areas +of support that might need change, or might be OK. + +If you are using an existing object file format (a.out or COFF), +there is probably little to be done. See @file{bfd/doc/bfd.texinfo} +for more information on writing new a.out or COFF versions. + +If you need to add a new object file format, you must first add it to +BFD. This is beyond the scope of this document right now. Basically +you must build a transfer vector (of type @code{bfd_target}), which will +mean writing all the required routines, and add it to the list in +@file{bfd/targets.c}. + +You must then arrange for the BFD code to provide access to the +debugging symbols. Generally GDB will have to call swapping routines +from BFD and a few other BFD internal routines to locate the debugging +information. As much as possible, GDB should not depend on the BFD +internal data structures. + +For some targets (e.g., COFF), there is a special transfer vector used +to call swapping routines, since the external data structures on various +platforms have different sizes and layouts. Specialized routines that +will only ever be implemented by one object file format may be called +directly. This interface should be described in a file +@file{bfd/libxxx.h}, which is included by GDB. + +If you are adding a new operating system for an existing CPU chip, add a +@file{tm-@var{xos}.h} file that describes the operating system +facilities that are unusual (extra symbol table info; the breakpoint +instruction needed; etc). Then write a +@file{tm-@var{xarch}-@var{xos}.h} that just @code{#include}s +@file{tm-@var{xarch}.h} and @file{tm-@var{xos}.h}. (Now that we have +three-part configuration names, this will probably get revised to +separate the @var{xos} configuration from the @var{xarch} +configuration.) + + +@node Languages +@chapter Adding a Source Language to GDB + +To add other languages to GDB's expression parser, follow the following steps: + +@table @emph +@item Create the expression parser. + +This should reside in a file @file{@var{lang}-exp.y}. Routines for building +parsed expressions into a @samp{union exp_element} list are in @file{parse.c}. + +Since we can't depend upon everyone having Bison, and YACC produces +parsers that define a bunch of global names, the following lines +@emph{must} be included at the top of the YACC parser, to prevent +the various parsers from defining the same global names: + +@example +#define yyparse @var{lang}_parse +#define yylex @var{lang}_lex +#define yyerror @var{lang}_error +#define yylval @var{lang}_lval +#define yychar @var{lang}_char +#define yydebug @var{lang}_debug +#define yypact @var{lang}_pact +#define yyr1 @var{lang}_r1 +#define yyr2 @var{lang}_r2 +#define yydef @var{lang}_def +#define yychk @var{lang}_chk +#define yypgo @var{lang}_pgo +#define yyact @var{lang}_act +#define yyexca @var{lang}_exca +#define yyerrflag @var{lang}_errflag +#define yynerrs @var{lang}_nerrs +@end example + +At the bottom of your parser, define a @code{struct language_defn} and +initialize it with the right values for your language. Define an +@code{initialize_@var{lang}} routine and have it call +@samp{add_language(@var{lang}_language_defn)} to tell the rest of GDB +that your language exists. You'll need some other supporting variables +and functions, which will be used via pointers from your +@code{@var{lang}_language_defn}. See the declaration of @code{struct +language_defn} in @file{language.h}, and the other @file{*-exp.y} files, +for more information. + +@item Add any evaluation routines, if necessary + +If you need new opcodes (that represent the operations of the language), +add them to the enumerated type in @file{expression.h}. Add support +code for these operations in @code{eval.c:evaluate_subexp()}. Add cases +for new opcodes in two functions from @file{parse.c}: +@code{prefixify_subexp()} and @code{length_of_subexp()}. These compute +the number of @code{exp_element}s that a given operation takes up. + +@item Update some existing code + +Add an enumerated identifier for your language to the enumerated type +@code{enum language} in @file{defs.h}. + +Update the routines in @file{language.c} so your language is included. These +routines include type predicates and such, which (in some cases) are +language dependent. If your language does not appear in the switch +statement, an error is reported. + +Also included in @file{language.c} is the code that updates the variable +@code{current_language}, and the routines that translate the +@code{language_@var{lang}} enumerated identifier into a printable +string. + +Update the function @code{_initialize_language} to include your language. This +function picks the default language upon startup, so is dependent upon +which languages that GDB is built for. + +Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading +code so that the language of each symtab (source file) is set properly. +This is used to determine the language to use at each stack frame level. +Currently, the language is set based upon the extension of the source +file. If the language can be better inferred from the symbol +information, please set the language of the symtab in the symbol-reading +code. + +Add helper code to @code{expprint.c:print_subexp()} to handle any new +expression opcodes you have added to @file{expression.h}. Also, add the +printed representations of your operators to @code{op_print_tab}. + +@item Add a place of call + +Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in +@code{parse.c:parse_exp_1()}. + +@item Use macros to trim code + +The user has the option of building GDB for some or all of the +languages. If the user decides to build GDB for the language +@var{lang}, then every file dependent on @file{language.h} will have the +macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to +leave out large routines that the user won't need if he or she is not +using your language. + +Note that you do not need to do this in your YACC parser, since if GDB +is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the +compiled form of your parser) is not linked into GDB at all. + +See the file @file{configure.in} for how GDB is configured for different +languages. + +@item Edit @file{Makefile.in} + +Add dependencies in @file{Makefile.in}. Make sure you update the macro +variables such as @code{HFILES} and @code{OBJS}, otherwise your code may +not get linked in, or, worse yet, it may not get @code{tar}red into the +distribution! +@end table + + +@node Releases +@chapter Configuring GDB for Release + +From the top level directory (containing @file{gdb}, @file{bfd}, +@file{libiberty}, and so on): +@example +make -f Makefile.in gdb.tar.Z +@end example + +This will properly configure, clean, rebuild any files that are +distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}), +and will then make a tarfile. (If the top level directory has already +beenn configured, you can just do @code{make gdb.tar.Z} instead.) + +This procedure requires: +@itemize @bullet +@item symbolic links +@item @code{makeinfo} (texinfo2 level) +@item @TeX{} +@item @code{dvips} +@item @code{yacc} or @code{bison} +@end itemize +@noindent +@dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.). + +@subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION + +@file{gdb.texinfo} is currently marked up using the texinfo-2 macros, +which are not yet a default for anything (but we have to start using +them sometime). + +For making paper, the only thing this implies is the right generation of +@file{texinfo.tex} needs to be included in the distribution. + +For making info files, however, rather than duplicating the texinfo2 +distribution, generate @file{gdb-all.texinfo} locally, and include the files +@file{gdb.info*} in the distribution. Note the plural; @code{makeinfo} will +split the document into one overall file and five or so included files. + + +@node Partial Symbol Tables +@chapter Partial Symbol Tables + +GDB has three types of symbol tables. + +@itemize @bullet +@item full symbol tables (symtabs). These contain the main +information about symbols and addresses. +@item partial symbol tables (psymtabs). These contain enough +information to know when to read the corresponding +part of the full symbol table. +@item minimal symbol tables (msymtabs). These contain information +gleaned from non-debugging symbols. +@end itemize + +This section describes partial symbol tables. + +A psymtab is constructed by doing a very quick pass over an executable +file's debugging information. Small amounts of information are +extracted -- enough to identify which parts of the symbol table will +need to be re-read and fully digested later, when the user needs the +information. The speed of this pass causes GDB to start up very +quickly. Later, as the detailed rereading occurs, it occurs in small +pieces, at various times, and the delay therefrom is mostly invisible to +the user. (@xref{Symbol Reading}.) + +The symbols that show up in a file's psymtab should be, roughly, those +visible to the debugger's user when the program is not running code from +that file. These include external symbols and types, static +symbols and types, and enum values declared at file scope. + +The psymtab also contains the range of instruction addresses that the +full symbol table would represent. + +The idea is that there are only two ways for the user (or much of +the code in the debugger) to reference a symbol: + +@itemize @bullet + +@item by its address +(e.g. execution stops at some address which is inside a function +in this file). The address will be noticed to be in the +range of this psymtab, and the full symtab will be read in. +@code{find_pc_function}, @code{find_pc_line}, and other @code{find_pc_@dots{}} +functions handle this. + +@item by its name +(e.g. the user asks to print a variable, or set a breakpoint on a +function). Global names and file-scope names will be found in the +psymtab, which will cause the symtab to be pulled in. Local names will +have to be qualified by a global name, or a file-scope name, in which +case we will have already read in the symtab as we evaluated the +qualifier. Or, a local symbol can be referenced when +we are "in" a local scope, in which case the first case applies. +@code{lookup_symbol} does most of the work here. + +@end itemize + +The only reason that psymtabs exist is to cause a symtab to be read in +at the right moment. Any symbol that can be elided from a psymtab, +while still causing that to happen, should not appear in it. Since +psymtabs don't have the idea of scope, you can't put local symbols in +them anyway. Psymtabs don't have the idea of the type of a symbol, +either, so types need not appear, unless they will be referenced by +name. + +It is a bug for GDB to behave one way when only a psymtab has been read, +and another way if the corresponding symtab has been read in. Such +bugs are typically caused by a psymtab that does not contain all the +visible symbols, or which has the wrong instruction address ranges. + +The psymtab for a particular section of a symbol-file (objfile) +could be thrown away after the symtab has been read in. The symtab +should always be searched before the psymtab, so the psymtab will +never be used (in a bug-free environment). Currently, +psymtabs are allocated on an obstack, and all the psymbols themselves +are allocated in a pair of large arrays on an obstack, so there is +little to be gained by trying to free them unless you want to do a lot +more work. + +@node Types +@chapter Types + +Fundamental Types (e.g., FT_VOID, FT_BOOLEAN). + +These are the fundamental types that gdb uses internally. Fundamental +types from the various debugging formats (stabs, ELF, etc) are mapped into +one of these. They are basically a union of all fundamental types that +gdb knows about for all the languages that gdb knows about. + +Type Codes (e.g., TYPE_CODE_PTR, TYPE_CODE_ARRAY). + +Each time gdb builds an internal type, it marks it with one of these +types. The type may be a fundamental type, such as TYPE_CODE_INT, or +a derived type, such as TYPE_CODE_PTR which is a pointer to another +type. Typically, several FT_* types map to one TYPE_CODE_* type, and +are distinguished by other members of the type struct, such as whether +the type is signed or unsigned, and how many bits it uses. + +Builtin Types (e.g., builtin_type_void, builtin_type_char). + +These are instances of type structs that roughly correspond to fundamental +types and are created as global types for gdb to use for various ugly +historical reasons. We eventually want to eliminate these. Note for +example that builtin_type_int initialized in gdbtypes.c is basically the +same as a TYPE_CODE_INT type that is initialized in c-lang.c for an +FT_INTEGER fundamental type. The difference is that the builtin_type is +not associated with any particular objfile, and only one instance exists, +while c-lang.c builds as many TYPE_CODE_INT types as needed, with each +one associated with some particular objfile. + +@node BFD support for GDB +@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 + +@c The interface for symbol reading is described in @ref{Symbol +@c Reading,,Symbol Reading}. + + +@node Symbol Reading +@chapter Symbol Reading + +GDB reads symbols from "symbol files". The usual symbol file is the +file containing the program which gdb is debugging. GDB can be directed +to use a different file for symbols (with the ``symbol-file'' +command), and it can also read more symbols via the ``add-file'' and ``load'' +commands, or while reading symbols from shared libraries. + +Symbol files are initially opened by @file{symfile.c} using the BFD +library. BFD identifies the type of the file by examining its header. +@code{symfile_init} then uses this identification to locate a +set of symbol-reading functions. + +Symbol reading modules identify themselves to GDB by calling +@code{add_symtab_fns} during their module initialization. The argument +to @code{add_symtab_fns} is a @code{struct sym_fns} which contains +the name (or name prefix) of the symbol format, the length of the prefix, +and pointers to four functions. These functions are called at various +times to process symbol-files whose identification matches the specified +prefix. + +The functions supplied by each module are: + +@table @code +@item @var{xxx}_symfile_init(struct sym_fns *sf) + +Called from @code{symbol_file_add} when we are about to read a new +symbol file. This function should clean up any internal state +(possibly resulting from half-read previous files, for example) +and prepare to read a new symbol file. Note that the symbol file +which we are reading might be a new "main" symbol file, or might +be a secondary symbol file whose symbols are being added to the +existing symbol table. + +The argument to @code{@var{xxx}_symfile_init} is a newly allocated +@code{struct sym_fns} whose @code{bfd} field contains the BFD +for the new symbol file being read. Its @code{private} field +has been zeroed, and can be modified as desired. Typically, +a struct of private information will be @code{malloc}'d, and +a pointer to it will be placed in the @code{private} field. + +There is no result from @code{@var{xxx}_symfile_init}, but it can call +@code{error} if it detects an unavoidable problem. + +@item @var{xxx}_new_init() + +Called from @code{symbol_file_add} when discarding existing symbols. +This function need only handle +the symbol-reading module's internal state; the symbol table data +structures visible to the rest of GDB will be discarded by +@code{symbol_file_add}. It has no arguments and no result. +It may be called after @code{@var{xxx}_symfile_init}, if a new symbol +table is being read, or may be called alone if all symbols are +simply being discarded. + +@item @var{xxx}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline) + +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{@var{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 +@var{xxx}_symfile_read is called, these psymtabs will contain a pointer to +a function @code{@var{xxx}_psymtab_to_symtab}, which can be called from +any point in the GDB symbol-handling code. + +@table @code +@item @var{xxx}_psymtab_to_symtab (struct partial_symtab *pst) + +Called from @code{psymtab_to_symtab} (or the PSYMTAB_TO_SYMTAB +macro) if the psymtab has not already been read in and had its +@code{pst->symtab} pointer set. The argument is the psymtab +to be fleshed-out into a symtab. Upon return, pst->readin +should have been set to 1, and pst->symtab should contain a +pointer to the new corresponding symtab, or zero if there +were no symbols in that part of the symbol file. +@end table + + +@node Cleanups +@chapter Cleanups + +Cleanups are a structured way to deal with things that need to be done +later. When your code does something (like @code{malloc} some memory, or open +a file) that needs to be undone later (e.g. free the memory or close +the file), it can make a cleanup. The cleanup will be done at some +future point: when the command is finished, when an error occurs, or +when your code decides it's time to do cleanups. + +You can also discard cleanups, that is, throw them away without doing +what they say. This is only done if you ask that it be done. + +Syntax: + +@table @code +@item struct cleanup *@var{old_chain}; +Declare a variable which will hold a cleanup chain handle. + +@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 + +Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify that they +``should not be called when cleanups are not in place''. This means +that any actions you need to reverse in the case of an error or +interruption must be on the cleanup chain before you call these functions, +since they might never return to your code (they @samp{longjmp} instead). + + +@node Wrapping +@chapter Wrapping Output Lines + +Output that goes through @code{printf_filtered} or @code{fputs_filtered} or +@code{fputs_demangled} needs only to have calls to @code{wrap_here} added +in places that would be good breaking points. The utility routines +will take care of actually wrapping if the line width is exceeded. + +The argument to @code{wrap_here} is an indentation string which is printed +@emph{only} if the line breaks there. This argument is saved away and used +later. It must remain valid until the next call to @code{wrap_here} or +until a newline has been printed through the @code{*_filtered} functions. +Don't pass in a local variable and then return! + +It is usually best to call @code{wrap_here()} after printing a comma or space. +If you call it before printing a space, make sure that your indentation +properly accounts for the leading space that will print if the line wraps +there. + +Any function or set of functions that produce filtered output must finish +by printing a newline, to flush the wrap buffer, before switching to +unfiltered (``@code{printf}'') output. Symbol reading routines that print +warnings are a good example. + + +@node Frames +@chapter Frames + +A frame is a construct that GDB uses to keep track of calling and called +functions. + +@table @code +@item FRAME_FP +in the machine description has no meaning to the machine-independent +part of GDB, except that it is used when setting up a new frame from +scratch, as follows: + +@example + create_new_frame (read_register (FP_REGNUM), read_pc ())); +@end example + +Other than that, all the meaning imparted to @code{FP_REGNUM} is imparted by +the machine-dependent code. So, @code{FP_REGNUM} can have any value that +is convenient for the code that creates new frames. (@code{create_new_frame} +calls @code{INIT_EXTRA_FRAME_INFO} if it is defined; that is where you should +use the @code{FP_REGNUM} value, if your frames are nonstandard.) + +@item FRAME_CHAIN +Given a GDB frame, determine the address of the calling function's +frame. This will be used to create a new GDB frame struct, and then +@code{INIT_EXTRA_FRAME_INFO} and @code{INIT_FRAME_PC} will be called for +the new frame. +@end table + +@node Remote Stubs +@chapter Remote Stubs + +GDB's file @file{remote.c} talks a serial protocol to code that runs +in the target system. GDB provides several sample ``stubs'' that can +be integrated into target programs or operating systems for this purpose; +they are named @file{*-stub.c}. + +The GDB user's manual describes how to put such a stub into your target +code. What follows is a discussion of integrating the SPARC stub +into a complicated operating system (rather than a simple program), +by Stu Grossman, the author of this stub. + +The trap handling code in the stub assumes the following upon entry to +trap_low: + +@enumerate +@item %l1 and %l2 contain pc and npc respectively at the time of the trap +@item traps are disabled +@item you are in the correct trap window +@end enumerate + +As long as your trap handler can guarantee those conditions, then there is no +reason why you shouldn't be able to `share' traps with the stub. The stub has +no requirement that it be jumped to directly from the hardware trap vector. +That is why it calls @code{exceptionHandler()}, which is provided by the external +environment. For instance, this could setup the hardware traps to actually +execute code which calls the stub first, and then transfers to its own trap +handler. + +For the most point, there probably won't be much of an issue with `sharing' +traps, as the traps we use are usually not used by the kernel, and often +indicate unrecoverable error conditions. Anyway, this is all controlled by a +table, and is trivial to modify. +The most important trap for us is for @code{ta 1}. Without that, we +can't single step or do breakpoints. Everything else is unnecessary +for the proper operation of the debugger/stub. + +From reading the stub, it's probably not obvious how breakpoints work. They +are simply done by deposit/examine operations from GDB. + +@node Longjmp Support +@chapter Longjmp Support + +GDB has support for figuring out that the target is doing a +@code{longjmp} and for stopping at the target of the jump, if we are +stepping. This is done with a few specialized internal breakpoints, +which are visible in the @code{maint info breakpoint} command. + +To make this work, you need to define a macro called +@code{GET_LONGJMP_TARGET}, which will examine the @code{jmp_buf} +structure and extract the longjmp target address. Since @code{jmp_buf} +is target specific, you will need to define it in the appropriate +@file{tm-xxx.h} file. Look in @file{tm-sun4os4.h} and +@file{sparc-tdep.c} for examples of how to do this. + +@node Coding Style +@chapter Coding Style + +GDB is generally written using the GNU coding standards, as described in +@file{standards.texi}, which is available for anonymous FTP from GNU +archive sites. There are some additional considerations for GDB +maintainers that reflect the unique environment and style of GDB +maintenance. If you follow these guidelines, GDB will be more +consistent and easier to maintain. + +GDB's policy on the use of prototypes is that prototypes are used +to @emph{declare} functions but never to @emph{define} them. Simple +macros are used in the declarations, so that a non-ANSI compiler can +compile GDB without trouble. The simple macro calls are used like +this: + +@example @code +extern int +memory_remove_breakpoint PARAMS ((CORE_ADDR, char *)); +@end example + +Note the double parentheses around the parameter types. This allows +an arbitrary number of parameters to be described, without freaking +out the C preprocessor. When the function has no parameters, it +should be described like: + +@example @code +void +noprocess PARAMS ((void)); +@end example + +The @code{PARAMS} macro expands to its argument in ANSI C, or to a simple +@code{()} in traditional C. + +All external functions should have a @code{PARAMS} declaration in a +header file that callers include. All static functions should have such +a declaration near the top of their source file. + +We don't have a gcc option that will properly check that these rules +have been followed, but it's GDB policy, and we periodically check it +using the tools available (plus manual labor), and clean up any remnants. + +@node Clean Design +@chapter Clean Design + +In addition to getting the syntax right, there's the little question of +semantics. Some things are done in certain ways in GDB because long +experience has shown that the more obvious ways caused various kinds of +trouble. In particular: + +@table @bullet +@item +You can't assume the byte order of anything that comes from a +target (including @var{value}s, object files, and instructions). Such +things must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in GDB, +or one of the swap routines defined in @file{bfd.h}, such as @code{bfd_get_32}. + +@item +You can't assume that you know what interface is being used to talk to +the target system. All references to the target must go through the +current @code{target_ops} vector. + +@item +You can't assume that the host and target machines are the same machine +(except in the ``native'' support modules). +In particular, you can't assume that the target machine's header files +will be available on the host machine. Target code must bring along its +own header files -- written from scratch or explicitly donated by their +owner, to avoid copyright problems. + +@item +Insertion of new @code{#ifdef}'s will be frowned upon. It's much better +to write the code portably than to conditionalize it for various systems. + +@item +New @code{#ifdef}'s which test for specific compilers or manufacturers +or operating systems are unacceptable. All @code{#ifdef}'s should test +for features. The information about which configurations contain which +features should be segregated into the configuration files. Experience +has proven far too often that a feature unique to one particular system +often creeps into other systems; and that a conditional based on +some predefined macro for your current system will become worthless +over time, as new versions of your system come out that behave differently +with regard to this feature. + +@item +Adding code that handles specific architectures, operating systems, target +interfaces, or hosts, is not acceptable in generic code. If a hook +is needed at that point, invent a generic hook and define it for your +configuration, with something like: + +@example +#ifdef WRANGLE_SIGNALS + WRANGLE_SIGNALS (signo); +#endif +@end example + +In your host, target, or native configuration file, as appropriate, +define @code{WRANGLE_SIGNALS} to do the machine-dependent thing. Take +a bit of care in defining the hook, so that it can be used by other +ports in the future, if they need a hook in the same place. + +If the hook is not defined, the code should do whatever "most" machines +want. Using @code{#ifdef}, as above, is the preferred way to do this, +but sometimes that gets convoluted, in which case use + +@example +#ifndef SPECIAL_FOO_HANDLING +#define SPECIAL_FOO_HANDLING(pc, sp) (0) +#endif +@end example + +where the macro is used or in an appropriate header file. + +Whether to include a @dfn{small} hook, a hook around the exact pieces of +code which are system-dependent, or whether to replace a whole function +with a hook depends on the case. A good example of this dilemma can be +found in @code{get_saved_register}. All machines that GDB 2.8 ran on +just needed the @code{FRAME_FIND_SAVED_REGS} hook to find the saved +registers. Then the SPARC and Pyramid came along, and +@code{HAVE_REGISTER_WINDOWS} and @code{REGISTER_IN_WINDOW_P} were +introduced. Then the 29k and 88k required the @code{GET_SAVED_REGISTER} +hook. The first three are examples of small hooks; the latter replaces +a whole function. In this specific case, it is useful to have both +kinds; it would be a bad idea to replace all the uses of the small hooks +with @code{GET_SAVED_REGISTER}, since that would result in much +duplicated code. Other times, duplicating a few lines of code here or +there is much cleaner than introducing a large number of small hooks. + +Another way to generalize GDB along a particular interface is with an +attribute struct. For example, GDB has been generalized to handle +multiple kinds of remote interfaces -- not by #ifdef's everywhere, but +by defining the "target_ops" structure and having a current target (as +well as a stack of targets below it, for memory references). Whenever +something needs to be done that depends on which remote interface we are +using, a flag in the current target_ops structure is tested (e.g. +`target_has_stack'), or a function is called through a pointer in the +current target_ops structure. In this way, when a new remote interface +is added, only one module needs to be touched -- the one that actually +implements the new remote interface. Other examples of +attribute-structs are BFD access to multiple kinds of object file +formats, or GDB's access to multiple source languages. + +Please avoid duplicating code. For example, in GDB 3.x all the code +interfacing between @code{ptrace} and the rest of GDB was duplicated in +@file{*-dep.c}, and so changing something was very painful. In GDB 4.x, +these have all been consolidated into @file{infptrace.c}. +@file{infptrace.c} can deal with variations between systems the same way +any system-independent file would (hooks, #if defined, etc.), and +machines which are radically different don't need to use infptrace.c at +all. + +@item +@emph{Do} write code that doesn't depend on the sizes of C data types, +the format of the host's floating point numbers, the alignment of anything, +or the order of evaluation of expressions. In short, follow good +programming practices for writing portable C code. + +@end table + +@node Submitting Patches +@chapter Submitting Patches + +Thanks for thinking of offering your changes back to the community of +GDB users. In general we like to get well designed enhancements. +Thanks also for checking in advance about the best way to transfer the +changes. + +The two main problems with getting your patches in are, + +@table @bullet +@item +The GDB maintainers will only install ``cleanly designed'' patches. +You may not always agree on what is clean design. +@pxref{Coding Style}, @pxref{Clean Design}. + +@item +If the maintainers don't have time to put the patch in when it +arrives, or if there is any question about a patch, it +goes into a large queue with everyone else's patches and +bug reports. +@end table + +I don't know how to get past these problems except by continuing to try. + +There are two issues here -- technical and legal. + +The legal issue is that to incorporate substantial changes requires a +copyright assignment from you and/or your employer, granting ownership +of the changes to the Free Software Foundation. You can get the +standard document for doing this by sending mail to +@code{gnu@@prep.ai.mit.edu} and asking for it. I recommend that people +write in "All programs owned by the Free Software Foundation" as "NAME +OF PROGRAM", so that changes in many programs (not just GDB, but GAS, +Emacs, GCC, etc) can be contributed with only one piece of legalese +pushed through the bureacracy and filed with the FSF. I can't start +merging changes until this paperwork is received by the FSF (their +rules, which I follow since I maintain it for them). + +Technically, the easiest way to receive changes is to receive each +feature as a small context diff or unidiff, suitable for "patch". +Each message sent to me should include the changes to C code and +header files for a single feature, plus ChangeLog entries for each +directory where files were modified, and diffs for any changes needed +to the manuals (gdb/doc/gdb.texi or gdb/doc/gdbint.texi). If there +are a lot of changes for a single feature, they can be split down +into multiple messages. + +In this way, if I read and like the feature, I can add it to the +sources with a single patch command, do some testing, and check it in. +If you leave out the ChangeLog, I have to write one. If you leave +out the doc, I have to puzzle out what needs documenting. Etc. + +The reason to send each change in a separate message is that I will +not install some of the changes. They'll be returned to you with +questions or comments. If I'm doing my job, my message back to you +will say what you have to fix in order to make the change acceptable. +The reason to have separate messages for separate features is so +that other changes (which I @emph{am} willing to accept) can be installed +while one or more changes are being reworked. If multiple features +are sent in a single message, I tend to not put in the effort to sort +out the acceptable changes from the unacceptable, so none of the +features get installed until all are acceptable. + +If this sounds painful or authoritarian, well, it is. But I get a lot +of bug reports and a lot of patches, and most of them don't get +installed because I don't have the time to finish the job that the bug +reporter or the contributor could have done. Patches that arrive +complete, working, and well designed, tend to get installed on the day +they arrive. The others go into a queue and get installed if and when +I scan back over the queue -- which can literally take months +sometimes. It's in both our interests to make patch installation easy +-- you get your changes installed, and I make some forward progress on +GDB in a normal 12-hour day (instead of them having to wait until I +have a 14-hour or 16-hour day to spend cleaning up patches before I +can install them). + +Please send patches to @code{bug-gdb@@prep.ai.mit.edu}, if they are less +than about 25,000 characters. If longer than that, either make them +available somehow (e.g. anonymous FTP), and announce it on +@code{bug-gdb}, or send them directly to the GDB maintainers at +@code{gdb-patches@@cygnus.com}. + +@node Host Conditionals +@chapter Host Conditionals + +When GDB is configured and compiled, various macros are defined or left +undefined, to control compilation based on the attributes of the host +system. These macros and their meanings are: + +@emph{NOTE: For now, both host and target conditionals are here. +Eliminate target conditionals from this list as they are identified.} + +@table @code +@item BLOCK_ADDRESS_FUNCTION_RELATIVE +dbxread.c +@item GDBINIT_FILENAME +The default name of GDB's initialization file (normally @file{.gdbinit}). +@item KERNELDEBUG +tm-hppa.h +@item MEM_FNS_DECLARED +Your host config file defines this if it includes +declarations of @code{memcpy} and @code{memset}. Define this +to avoid conflicts between the native include +files and the declarations in @file{defs.h}. +@item NO_SYS_FILE +dbxread.c +@item PYRAMID_CONTROL_FRAME_DEBUGGING +pyr-xdep.c +@item SIGWINCH_HANDLER_BODY +utils.c +@item ADDITIONAL_OPTIONS +main.c +@item ADDITIONAL_OPTION_CASES +main.c +@item ADDITIONAL_OPTION_HANDLER +main.c +@item ADDITIONAL_OPTION_HELP +main.c +@item ADDR_BITS_REMOVE +defs.h +@item AIX_BUGGY_PTRACE_CONTINUE +infptrace.c +@item ALIGN_STACK_ON_STARTUP +main.c +@item ALTOS +altos-xdep.c +@item ALTOS_AS +xm-altos.h +@item ASCII_COFF +remote-adapt.c +@item BADMAG +coffread.c +@item BCS +tm-delta88.h +@item BEFORE_MAIN_LOOP_HOOK +main.c +@item BELIEVE_PCC_PROMOTION +coffread.c +@item BELIEVE_PCC_PROMOTION_TYPE +stabsread.c +@item BITS_BIG_ENDIAN +defs.h +@item BKPT_AT_MAIN +solib.c +@item BLOCK_ADDRESS_ABSOLUTE +dbxread.c +@item BPT_VECTOR +tm-m68k.h +@item BREAKPOINT +tm-m68k.h +@item BREAKPOINT_DEBUG +breakpoint.c +@item BROKEN_LARGE_ALLOCA +Avoid large @code{alloca}'s. For example, on sun's, Large alloca's fail +because the attempt to increase the stack limit in main() fails because +shared libraries are allocated just below the initial stack limit. The +SunOS kernel will not allow the stack to grow into the area occupied by +the shared libraries. +@item BSTRING +regex.c +@item CALL_DUMMY +valops.c +@item CALL_DUMMY_LOCATION +inferior.h +@item CALL_DUMMY_STACK_ADJUST +valops.c +@item CANNOT_FETCH_REGISTER +hppabsd-xdep.c +@item CANNOT_STORE_REGISTER +findvar.c +@item CFRONT_PRODUCER +dwarfread.c +@item CHILD_PREPARE_TO_STORE +inftarg.c +@item CLEAR_DEFERRED_STORES +inflow.c +@item CLEAR_SOLIB +objfiles.c +@item COFF_ENCAPSULATE +hppabsd-tdep.c +@item COFF_FORMAT +symm-tdep.c +@item CORE_NEEDS_RELOCATION +stack.c +@item CPLUS_MARKER +cplus-dem.c +@item CREATE_INFERIOR_HOOK +infrun.c +@item C_ALLOCA +regex.c +@item C_GLBLREG +coffread.c +@item DBXREAD_ONLY +partial-stab.h +@item DBX_PARM_SYMBOL_CLASS +stabsread.c +@item DEBUG +remote-adapt.c +@item DEBUG_INFO +partial-stab.h +@item DEBUG_PTRACE +hppabsd-xdep.c +@item DECR_PC_AFTER_BREAK +breakpoint.c +@item DEFAULT_PROMPT +The default value of the prompt string (normally @code{"(gdb) "}). +@item DELTA88 +m88k-xdep.c +@item DEV_TTY +symmisc.c +@item DGUX +m88k-xdep.c +@item DISABLE_UNSETTABLE_BREAK +breakpoint.c +@item DONT_USE_REMOTE +remote.c +@item DO_DEFERRED_STORES +infrun.c +@item DO_REGISTERS_INFO +infcmd.c +@item EXTRACT_RETURN_VALUE +tm-m68k.h +@item EXTRACT_STRUCT_VALUE_ADDRESS +values.c +@item EXTRA_FRAME_INFO +frame.h +@item EXTRA_SYMTAB_INFO +symtab.h +@item FILES_INFO_HOOK +target.c +@item FLOAT_INFO +infcmd.c +@item FOPEN_RB +defs.h +@item FRAMELESS_FUNCTION_INVOCATION +blockframe.c +@item FRAME_ARGS_ADDRESS_CORRECT +stack.c +@item FRAME_CHAIN_COMBINE +blockframe.c +@item FRAME_CHAIN_VALID +frame.h +@item FRAME_CHAIN_VALID_ALTERNATE +frame.h +@item FRAME_FIND_SAVED_REGS +stack.c +@item FRAME_GET_BASEREG_VALUE +frame.h +@item FRAME_NUM_ARGS +tm-m68k.h +@item FRAME_SPECIFICATION_DYADIC +stack.c +@item FUNCTION_EPILOGUE_SIZE +coffread.c +@item F_OK +xm-ultra3.h +@item GCC2_COMPILED_FLAG_SYMBOL +dbxread.c +@item GCC_COMPILED_FLAG_SYMBOL +dbxread.c +@item GCC_MANGLE_BUG +symtab.c +@item GCC_PRODUCER +dwarfread.c +@item GET_SAVED_REGISTER +findvar.c +@item GPLUS_PRODUCER +dwarfread.c +@item HANDLE_RBRAC +partial-stab.h +@item HAVE_MMAP +In some cases, use the system call @code{mmap} for reading symbol +tables. For some machines this allows for sharing and quick updates. +@item HAVE_REGISTER_WINDOWS +findvar.c +@item HAVE_SIGSETMASK +main.c +@item HAVE_TERMIO +inflow.c +@item HEADER_SEEK_FD +arm-tdep.c +@item HOSTING_ONLY +xm-rtbsd.h +@item HOST_BYTE_ORDER +ieee-float.c +@item HPUX_ASM +xm-hp300hpux.h +@item HPUX_VERSION_5 +hp300ux-xdep.c +@item HP_OS_BUG +infrun.c +@item I80960 +remote-vx.c +@item IEEE_DEBUG +ieee-float.c +@item IEEE_FLOAT +valprint.c +@item IGNORE_SYMBOL +dbxread.c +@item INIT_EXTRA_FRAME_INFO +blockframe.c +@item INIT_EXTRA_SYMTAB_INFO +symfile.c +@item INIT_FRAME_PC +blockframe.c +@item INNER_THAN +valops.c +@item INT_MAX +defs.h +@item INT_MIN +defs.h +@item IN_GDB +i960-pinsn.c +@item IN_SIGTRAMP +infrun.c +@item IN_SOLIB_TRAMPOLINE +infrun.c +@item ISATTY +main.c +@item IS_TRAPPED_INTERNALVAR +values.c +@item KERNELDEBUG +dbxread.c +@item KERNEL_DEBUGGING +tm-ultra3.h +@item KERNEL_U_ADDR +Define this to the address of the @code{u} structure (the ``user struct'', +also known as the ``u-page'') in kernel virtual memory. GDB needs to know +this so that it can subtract this address from absolute addresses in +the upage, that are obtained via ptrace or from core files. On systems +that don't need this value, set it to zero. +@item KERNEL_U_ADDR_BSD +Define this to cause GDB to determine the address of @code{u} at runtime, +by using Berkeley-style @code{nlist} on the kernel's image in the root +directory. +@item KERNEL_U_ADDR_HPUX +Define this to cause GDB to determine the address of @code{u} at runtime, +by using HP-style @code{nlist} on the kernel's image in the root +directory. +@item LCC_PRODUCER +dwarfread.c +@item LOG_FILE +remote-adapt.c +@item LONGERNAMES +cplus-dem.c +@item LONGEST +defs.h +@item CC_HAS_LONG_LONG +defs.h +@item PRINTF_HAS_LONG_LONG +defs.h +@item LONG_MAX +defs.h +@item LSEEK_NOT_LINEAR +source.c +@item L_LNNO32 +coffread.c +@item L_SET +This macro is used as the argument to lseek (or, most commonly, bfd_seek). +FIXME, it should be replaced by SEEK_SET instead, which is the POSIX equivalent. +@item MACHKERNELDEBUG +hppabsd-tdep.c +@item MAINTENANCE +dwarfread.c +@item MAINTENANCE_CMDS +If the value of this is 1, then a number of optional maintenance commands +are compiled in. +@item MALLOC_INCOMPATIBLE +Define this if the system's prototype for @code{malloc} differs from the +@sc{ANSI} definition. +@item MIPSEL +mips-tdep.c +@item MMAP_BASE_ADDRESS +When using HAVE_MMAP, the first mapping should go at this address. +@item MMAP_INCREMENT +when using HAVE_MMAP, this is the increment between mappings. +@item MONO +ser-go32.c +@item MOTOROLA +xm-altos.h +@item NBPG +altos-xdep.c +@item NEED_POSIX_SETPGID +infrun.c +@item NEED_TEXT_START_END +exec.c +@item NFAILURES +regex.c +@item NORETURN +(in defs.h - is this really useful to define/undefine?) +@item NOTDEF +regex.c +@item NOTDEF +remote-adapt.c +@item NOTDEF +remote-mm.c +@item NOTICE_SIGNAL_HANDLING_CHANGE +infrun.c +@item NO_HIF_SUPPORT +remote-mm.c +@item NO_JOB_CONTROL +signals.h +@item NO_MMALLOC +GDB will use the @code{mmalloc} library for memory allocation for symbol +reading, unless this symbol is defined. Define it on systems +on which @code{mmalloc} does not +work for some reason. One example is the DECstation, where its RPC +library can't cope with our redefinition of @code{malloc} to call +@code{mmalloc}. When defining @code{NO_MMALLOC}, you will also have +to override the setting of @code{MMALLOC_LIB} to empty, in the Makefile. +Therefore, this define is usually set on the command line by overriding +@code{MMALLOC_DISABLE} in @file{config/*/*.mh}, rather than by defining +it in @file{xm-*.h}. +@item NO_MMALLOC_CHECK +Define this if you are using @code{mmalloc}, but don't want the overhead +of checking the heap with @code{mmcheck}. +@item NO_SIGINTERRUPT +remote-adapt.c +@item NO_SINGLE_STEP +infptrace.c +@item NS32K_SVC_IMMED_OPERANDS +ns32k-opcode.h +@item NUMERIC_REG_NAMES +mips-tdep.c +@item N_SETV +dbxread.c +@item N_SET_MAGIC +hppabsd-tdep.c +@item NaN +tm-umax.h +@item ONE_PROCESS_WRITETEXT +breakpoint.c +@item O_BINARY +exec.c +@item O_RDONLY +xm-ultra3.h +@item PC +convx-opcode.h +@item PCC_SOL_BROKEN +dbxread.c +@item PC_IN_CALL_DUMMY +inferior.h +@item PC_LOAD_SEGMENT +stack.c +@item PRINT_RANDOM_SIGNAL +infcmd.c +@item PRINT_REGISTER_HOOK +infcmd.c +@item PRINT_TYPELESS_INTEGER +valprint.c +@item PROCESS_LINENUMBER_HOOK +buildsym.c +@item PROLOGUE_FIRSTLINE_OVERLAP +infrun.c +@item PSIGNAL_IN_SIGNAL_H +defs.h +@item PUSH_ARGUMENTS +valops.c +@item PYRAMID_CONTROL_FRAME_DEBUGGING +pyr-xdep.c +@item PYRAMID_CORE +pyr-xdep.c +@item PYRAMID_PTRACE +pyr-xdep.c +@item REGISTER_BYTES +remote.c +@item REGISTER_NAMES +tm-a29k.h +@item REG_STACK_SEGMENT +exec.c +@item REG_STRUCT_HAS_ADDR +findvar.c +@item RE_NREGS +regex.h +@item R_FP +dwarfread.c +@item R_OK +xm-altos.h +@item SEEK_END +state.c +@item SEEK_SET +state.c +@item SEM +coffread.c +@item SET_STACK_LIMIT_HUGE +When defined, stack limits will be raised to their maximum. Use this +if your host supports @code{setrlimit} and you have trouble with +@code{stringtab} in @file{dbxread.c}. + +Also used in @file{fork-child.c} to return stack limits before child +processes are forked. +@item SHELL_COMMAND_CONCAT +infrun.c +@item SHELL_FILE +infrun.c +@item SHIFT_INST_REGS +breakpoint.c +@item SIGN_EXTEND_CHAR +regex.c +@item SIGTRAP_STOP_AFTER_LOAD +infrun.c +@item SKIP_PROLOGUE +tm-m68k.h +@item SKIP_PROLOGUE_FRAMELESS_P +blockframe.c +@item SKIP_TRAMPOLINE_CODE +infrun.c +@item SOLIB_ADD +core.c +@item SOLIB_CREATE_INFERIOR_HOOK +infrun.c +@item STACK_ALIGN +valops.c +@item START_INFERIOR_TRAPS_EXPECTED +infrun.c +@item STOP_SIGNAL +main.c +@item STORE_RETURN_VALUE +tm-m68k.h +@item SUN4_COMPILER_FEATURE +infrun.c +@item SUN_FIXED_LBRAC_BUG +dbxread.c +@item SVR4_SHARED_LIBS +solib.c +@item SWITCH_ENUM_BUG +regex.c +@item SYM1 +tm-ultra3.h +@item SYMBOL_RELOADING_DEFAULT +symfile.c +@item SYNTAX_TABLE +regex.c +@item Sword +regex.c +@item TDESC +infrun.c +@item TIOCGETC +inflow.c +@item TIOCGLTC +inflow.c +@item TIOCGPGRP +inflow.c +@item TIOCLGET +inflow.c +@item TIOCLSET +inflow.c +@item TIOCNOTTY +inflow.c +@item T_ARG +coffread.c +@item T_VOID +coffread.c +@item UINT_MAX +defs.h +@item UPAGES +altos-xdep.c +@item USER +m88k-tdep.c +@item USE_GAS +xm-news.h +@item USE_O_NOCTTY +inflow.c +@item USE_STRUCT_CONVENTION +values.c +@item USG +Means that System V (prior to SVR4) include files are in use. +(FIXME: This symbol is abused in @file{infrun.c}, @file{regex.c}, +@file{remote-nindy.c}, and @file{utils.c} for other things, at the moment.) +@item USIZE +xm-m88k.h +@item U_FPSTATE +i386-xdep.c +@item VARIABLES_INSIDE_BLOCK +dbxread.c +@item WRS_ORIG +remote-vx.c +@item _LANG_c +language.c +@item _LANG_m2 +language.c +@item __GNUC__ +news-xdep.c +@item __GO32__ +inflow.c +@item __HPUX_ASM__ +xm-hp300hpux.h +@item __INT_VARARGS_H +printcmd.c +@item __not_on_pyr_yet +pyr-xdep.c +@item alloca +defs.h +@item const +defs.h +@item GOULD_PN +gould-pinsn.c +@item hp800 +xm-hppabsd.h +@item hpux +hppabsd-core.c +@item lint +valarith.c +@item longest_to_int +defs.h +@item mc68020 +m68k-stub.c +@item notdef +gould-pinsn.c +@item ns32k_opcodeT +ns32k-opcode.h +@item sgi +mips-tdep.c +@item sparc +regex.c +@item sun +m68k-tdep.c +@item sun386 +tm-sun386.h +@item test +regex.c +@item ultrix +xm-mips.h +@item volatile +defs.h +@end table + +@node Target Conditionals +@chapter Target Conditionals + +When GDB is configured and compiled, various macros are defined or left +undefined, to control compilation based on the attributes of the target +system. These macros and their meanings are: + +@emph{NOTE: For now, both host and target conditionals are here. +Eliminate host conditionals from this list as they are identified.} + +@table @code +@item PUSH_DUMMY_FRAME +Used in @samp{call_function_by_hand} to create an artificial stack frame. +@item POP_FRAME +Used in @samp{call_function_by_hand} to remove an artificial stack frame. +@item BLOCK_ADDRESS_FUNCTION_RELATIVE +dbxread.c +@item KERNELDEBUG +tm-hppa.h +@item NO_SYS_FILE +dbxread.c +@item PYRAMID_CONTROL_FRAME_DEBUGGING +pyr-xdep.c +@item SIGWINCH_HANDLER_BODY +utils.c +@item ADDITIONAL_OPTIONS +main.c +@item ADDITIONAL_OPTION_CASES +main.c +@item ADDITIONAL_OPTION_HANDLER +main.c +@item ADDITIONAL_OPTION_HELP +main.c +@item ADDR_BITS_REMOVE +defs.h +@item ALIGN_STACK_ON_STARTUP +main.c +@item ALTOS +altos-xdep.c +@item ALTOS_AS +xm-altos.h +@item ASCII_COFF +remote-adapt.c +@item BADMAG +coffread.c +@item BCS +tm-delta88.h +@item BEFORE_MAIN_LOOP_HOOK +main.c +@item BELIEVE_PCC_PROMOTION +coffread.c +@item BELIEVE_PCC_PROMOTION_TYPE +stabsread.c +@item BITS_BIG_ENDIAN +defs.h +@item BKPT_AT_MAIN +solib.c +@item BLOCK_ADDRESS_ABSOLUTE +dbxread.c +@item BPT_VECTOR +tm-m68k.h +@item BREAKPOINT +tm-m68k.h +@item BREAKPOINT_DEBUG +breakpoint.c +@item BSTRING +regex.c +@item CALL_DUMMY +valops.c +@item CALL_DUMMY_LOCATION +inferior.h +@item CALL_DUMMY_STACK_ADJUST +valops.c +@item CANNOT_FETCH_REGISTER +hppabsd-xdep.c +@item CANNOT_STORE_REGISTER +findvar.c +@item CFRONT_PRODUCER +dwarfread.c +@item CHILD_PREPARE_TO_STORE +inftarg.c +@item CLEAR_DEFERRED_STORES +inflow.c +@item CLEAR_SOLIB +objfiles.c +@item COFF_ENCAPSULATE +hppabsd-tdep.c +@item COFF_FORMAT +symm-tdep.c +@item CORE_NEEDS_RELOCATION +stack.c +@item CPLUS_MARKER +cplus-dem.c +@item CREATE_INFERIOR_HOOK +infrun.c +@item C_ALLOCA +regex.c +@item C_GLBLREG +coffread.c +@item DBXREAD_ONLY +partial-stab.h +@item DBX_PARM_SYMBOL_CLASS +stabsread.c +@item DEBUG +remote-adapt.c +@item DEBUG_INFO +partial-stab.h +@item DEBUG_PTRACE +hppabsd-xdep.c +@item DECR_PC_AFTER_BREAK +breakpoint.c +@item DELTA88 +m88k-xdep.c +@item DEV_TTY +symmisc.c +@item DGUX +m88k-xdep.c +@item DISABLE_UNSETTABLE_BREAK +breakpoint.c +@item DONT_USE_REMOTE +remote.c +@item DO_DEFERRED_STORES +infrun.c +@item DO_REGISTERS_INFO +infcmd.c +@item END_OF_TEXT_DEFAULT +This is an expression that should designate the end of the text section +(? FIXME ?) +@item EXTRACT_RETURN_VALUE +tm-m68k.h +@item EXTRACT_STRUCT_VALUE_ADDRESS +values.c +@item EXTRA_FRAME_INFO +frame.h +@item EXTRA_SYMTAB_INFO +symtab.h +@item FILES_INFO_HOOK +target.c +@item FLOAT_INFO +infcmd.c +@item FOPEN_RB +defs.h +@item FP0_REGNUM +a68v-xdep.c +@item FPC_REGNUM +mach386-xdep.c +@item FP_REGNUM +parse.c +@item FPU +Unused? 6-oct-92 rich@@cygnus.com. FIXME. +@item FRAMELESS_FUNCTION_INVOCATION +blockframe.c +@item FRAME_ARGS_ADDRESS_CORRECT +stack.c +@item FRAME_CHAIN +Given FRAME, return a pointer to the calling frame. +@item FRAME_CHAIN_COMBINE +blockframe.c +@item FRAME_CHAIN_VALID +frame.h +@item FRAME_CHAIN_VALID_ALTERNATE +frame.h +@item FRAME_FIND_SAVED_REGS +stack.c +@item FRAME_GET_BASEREG_VALUE +frame.h +@item FRAME_NUM_ARGS +tm-m68k.h +@item FRAME_SPECIFICATION_DYADIC +stack.c +@item FRAME_SAVED_PC +Given FRAME, return the pc saved there. That is, the return address. +@item FUNCTION_EPILOGUE_SIZE +coffread.c +@item F_OK +xm-ultra3.h +@item GCC2_COMPILED_FLAG_SYMBOL +dbxread.c +@item GCC_COMPILED_FLAG_SYMBOL +dbxread.c +@item GCC_MANGLE_BUG +symtab.c +@item GCC_PRODUCER +dwarfread.c +@item GDB_TARGET_IS_HPPA +This determines whether horrible kludge code in dbxread.c and partial-stab.h +is used to mangle multiple-symbol-table files from HPPA's. This should all +be ripped out, and a scheme like elfread.c used. +@item GDB_TARGET_IS_MACH386 +mach386-xdep.c +@item GDB_TARGET_IS_SUN3 +a68v-xdep.c +@item GDB_TARGET_IS_SUN386 +sun386-xdep.c +@item GET_LONGJMP_TARGET +For most machines, this is a target-dependent parameter. On the DECstation +and the Iris, this is a native-dependent parameter, since <setjmp.h> is +needed to define it. + +This macro determines the target PC address that longjmp() will jump +to, assuming that we have just stopped at a longjmp breakpoint. It +takes a CORE_ADDR * as argument, and stores the target PC value through +this pointer. It examines the current state of the machine as needed. +@item GET_SAVED_REGISTER +findvar.c +@item GPLUS_PRODUCER +dwarfread.c +@item GR64_REGNUM +remote-adapt.c +@item GR64_REGNUM +remote-mm.c +@item HANDLE_RBRAC +partial-stab.h +@item HAVE_68881 +m68k-tdep.c +@item HAVE_REGISTER_WINDOWS +findvar.c +@item HAVE_SIGSETMASK +main.c +@item HAVE_TERMIO +inflow.c +@item HEADER_SEEK_FD +arm-tdep.c +@item HOSTING_ONLY +xm-rtbsd.h +@item HOST_BYTE_ORDER +ieee-float.c +@item HPUX_ASM +xm-hp300hpux.h +@item HPUX_VERSION_5 +hp300ux-xdep.c +@item HP_OS_BUG +infrun.c +@item I80960 +remote-vx.c +@item IBM6000_TARGET +Shows that we are configured for an IBM RS/6000 target. This conditional +should be eliminated (FIXME) and replaced by feature-specific macros. +It was introduced in haste and we are repenting at leisure. +@item IEEE_DEBUG +ieee-float.c +@item IEEE_FLOAT +valprint.c +@item IGNORE_SYMBOL +dbxread.c +@item INIT_EXTRA_FRAME_INFO +blockframe.c +@item INIT_EXTRA_SYMTAB_INFO +symfile.c +@item INIT_FRAME_PC +blockframe.c +@item INNER_THAN +valops.c +@item INT_MAX +defs.h +@item INT_MIN +defs.h +@item IN_GDB +i960-pinsn.c +@item IN_SIGTRAMP +infrun.c +@item IN_SOLIB_TRAMPOLINE +infrun.c +@item ISATTY +main.c +@item IS_TRAPPED_INTERNALVAR +values.c +@item KERNELDEBUG +dbxread.c +@item KERNEL_DEBUGGING +tm-ultra3.h +@item LCC_PRODUCER +dwarfread.c +@item LOG_FILE +remote-adapt.c +@item LONGERNAMES +cplus-dem.c +@item LONGEST +defs.h +@item CC_HAS_LONG_LONG +defs.h +@item PRINTF_HAS_LONG_LONG +defs.h +@item LONG_MAX +defs.h +@item L_LNNO32 +coffread.c +@item MACHKERNELDEBUG +hppabsd-tdep.c +@item MAINTENANCE +dwarfread.c +@item MIPSEL +mips-tdep.c +@item MOTOROLA +xm-altos.h +@item NBPG +altos-xdep.c +@item NEED_POSIX_SETPGID +infrun.c +@item NEED_TEXT_START_END +exec.c +@item NFAILURES +regex.c +@item NNPC_REGNUM +infrun.c +@item NOTDEF +regex.c +@item NOTDEF +remote-adapt.c +@item NOTDEF +remote-mm.c +@item NOTICE_SIGNAL_HANDLING_CHANGE +infrun.c +@item NO_HIF_SUPPORT +remote-mm.c +@item NO_SIGINTERRUPT +remote-adapt.c +@item NO_SINGLE_STEP +infptrace.c +@item NPC_REGNUM +infcmd.c +@item NS32K_SVC_IMMED_OPERANDS +ns32k-opcode.h +@item NUMERIC_REG_NAMES +mips-tdep.c +@item N_SETV +dbxread.c +@item N_SET_MAGIC +hppabsd-tdep.c +@item NaN +tm-umax.h +@item ONE_PROCESS_WRITETEXT +breakpoint.c +@item PC +convx-opcode.h +@item PCC_SOL_BROKEN +dbxread.c +@item PC_IN_CALL_DUMMY +inferior.h +@item PC_LOAD_SEGMENT +stack.c +@item PC_REGNUM +parse.c +@item PRINT_RANDOM_SIGNAL +infcmd.c +@item PRINT_REGISTER_HOOK +infcmd.c +@item PRINT_TYPELESS_INTEGER +valprint.c +@item PROCESS_LINENUMBER_HOOK +buildsym.c +@item PROLOGUE_FIRSTLINE_OVERLAP +infrun.c +@item PSIGNAL_IN_SIGNAL_H +defs.h +@item PS_REGNUM +parse.c +@item PUSH_ARGUMENTS +valops.c +@item REGISTER_BYTES +remote.c +@item REGISTER_NAMES +tm-a29k.h +@item REG_STACK_SEGMENT +exec.c +@item REG_STRUCT_HAS_ADDR +findvar.c +@item RE_NREGS +regex.h +@item R_FP +dwarfread.c +@item R_OK +xm-altos.h +@item SDB_REG_TO_REGNUM +Define this to convert sdb register numbers +into gdb regnums. If not defined, no conversion will be done. +@item SEEK_END +state.c +@item SEEK_SET +state.c +@item SEM +coffread.c +@item SHELL_COMMAND_CONCAT +infrun.c +@item SHELL_FILE +infrun.c +@item SHIFT_INST_REGS +breakpoint.c +@item SIGN_EXTEND_CHAR +regex.c +@item SIGTRAP_STOP_AFTER_LOAD +infrun.c +@item SKIP_PROLOGUE +tm-m68k.h +@item SKIP_PROLOGUE_FRAMELESS_P +blockframe.c +@item SKIP_TRAMPOLINE_CODE +infrun.c +@item SOLIB_ADD +core.c +@item SOLIB_CREATE_INFERIOR_HOOK +infrun.c +@item SP_REGNUM +parse.c +@item STAB_REG_TO_REGNUM +Define this to convert stab register numbers (as gotten from `r' declarations) +into gdb regnums. If not defined, no conversion will be done. +@item STACK_ALIGN +valops.c +@item START_INFERIOR_TRAPS_EXPECTED +infrun.c +@item STOP_SIGNAL +main.c +@item STORE_RETURN_VALUE +tm-m68k.h +@item SUN4_COMPILER_FEATURE +infrun.c +@item SUN_FIXED_LBRAC_BUG +dbxread.c +@item SVR4_SHARED_LIBS +solib.c +@item SWITCH_ENUM_BUG +regex.c +@item SYM1 +tm-ultra3.h +@item SYMBOL_RELOADING_DEFAULT +symfile.c +@item SYNTAX_TABLE +regex.c +@item Sword +regex.c +@item TARGET_BYTE_ORDER +defs.h +@item TARGET_CHAR_BIT +defs.h +@item TARGET_COMPLEX_BIT +defs.h +@item TARGET_DOUBLE_BIT +defs.h +@item TARGET_DOUBLE_COMPLEX_BIT +defs.h +@item TARGET_FLOAT_BIT +defs.h +@item TARGET_INT_BIT +defs.h +@item TARGET_LONG_BIT +defs.h +@item TARGET_LONG_DOUBLE_BIT +defs.h +@item TARGET_LONG_LONG_BIT +defs.h +@item TARGET_PTR_BIT +defs.h +@item TARGET_READ_PC +@item TARGET_WRITE_PC +@item TARGET_READ_SP +@item TARGET_WRITE_SP +@item TARGET_READ_FP +@item TARGET_WRITE_FP +These change the behavior of @code{read_pc}, @code{write_pc}, +@code{read_sp}, @code{write_sp}, @code{read_fp} and @code{write_fp}. +For most targets, these may be left undefined. GDB will call the +read and write register functions with the relevant @code{_REGNUM} argument. + +These macros are useful when a target keeps one of these registers in a +hard to get at place; for example, part in a segment register and part +in an ordinary register. + +@item TARGET_SHORT_BIT +defs.h +@item TDESC +infrun.c +@item T_ARG +coffread.c +@item T_VOID +coffread.c +@item UINT_MAX +defs.h +@item USER +m88k-tdep.c +@item USE_GAS +xm-news.h +@item USE_STRUCT_CONVENTION +values.c +@item USIZE +xm-m88k.h +@item U_FPSTATE +i386-xdep.c +@item VARIABLES_INSIDE_BLOCK +dbxread.c +@item WRS_ORIG +remote-vx.c +@item _LANG_c +language.c +@item _LANG_m2 +language.c +@item __GO32__ +inflow.c +@item __HPUX_ASM__ +xm-hp300hpux.h +@item __INT_VARARGS_H +printcmd.c +@item __not_on_pyr_yet +pyr-xdep.c +@item GOULD_PN +gould-pinsn.c +@item hp800 +xm-hppabsd.h +@item hpux +hppabsd-core.c +@item longest_to_int +defs.h +@item mc68020 +m68k-stub.c +@item ns32k_opcodeT +ns32k-opcode.h +@item sgi +mips-tdep.c +@item sparc +regex.c +@item sun +m68k-tdep.c +@item sun386 +tm-sun386.h +@item test +(Define this to enable testing code in regex.c.) +@end table + +@node Native Conditionals +@chapter Native Conditionals + +When GDB is configured and compiled, various macros are defined or left +undefined, to control compilation when the host and target systems +are the same. These macros should be defined (or left undefined) +in @file{nm-@var{system}.h}. + +@table @code +@item ATTACH_DETACH +If defined, then gdb will include support for the @code{attach} and +@code{detach} commands. +@item FETCH_INFERIOR_REGISTERS +Define this if the native-dependent code will provide its +own routines +@code{fetch_inferior_registers} and @code{store_inferior_registers} in +@file{@var{HOST}-nat.c}. +If this symbol is @emph{not} defined, and @file{infptrace.c} +is included in this configuration, the default routines in +@file{infptrace.c} are used for these functions. +@item GET_LONGJMP_TARGET +For most machines, this is a target-dependent parameter. On the DECstation +and the Iris, this is a native-dependent parameter, since <setjmp.h> is +needed to define it. + +This macro determines the target PC address that longjmp() will jump +to, assuming that we have just stopped at a longjmp breakpoint. It +takes a CORE_ADDR * as argument, and stores the target PC value through +this pointer. It examines the current state of the machine as needed. +@item PROC_NAME_FMT +Defines the format for the name of a @file{/proc} device. Should be +defined in @file{nm.h} @emph{only} in order to override the default +definition in @file{procfs.c}. +@item PTRACE_FP_BUG +mach386-xdep.c +@item PTRACE_ARG3_TYPE +The type of the third argument to the @code{ptrace} system call, if it exists +and is different from @code{int}. +@item REGISTER_U_ADDR +Defines the offset of the registers in the ``u area''; @pxref{Host}. +@item USE_PROC_FS +This determines whether small routines in @file{*-tdep.c}, which +translate register values +between GDB's internal representation and the /proc representation, +are compiled. +@item U_REGS_OFFSET +This is the offset of the registers in the upage. It need only be +defined if the generic ptrace register access routines in +@file{infptrace.c} are being used (that is, +@file{infptrace.c} is configured in, and +@code{FETCH_INFERIOR_REGISTERS} is not defined). If the default value +from @file{infptrace.c} is good enough, leave it undefined. + +The default value means that u.u_ar0 @emph{points to} the location of the +registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means that +u.u_ar0 @emph{is} the location of the registers. +@end table + +@node Obsolete Conditionals +@chapter Obsolete Conditionals + +Fragments of old code in GDB sometimes reference or set the following +configuration macros. They should not be used by new code, and +old uses should be removed as those parts of the debugger are +otherwise touched. + +@table @code +@item STACK_END_ADDR +This macro used to define where the end of the stack appeared, for use +in interpreting core file formats that don't record this address in the +core file itself. This information is now configured in BFD, and GDB +gets the info portably from there. The values in GDB's configuration +files should be moved into BFD configuration files (if needed there), +and deleted from all of GDB's config files. + +Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR +is so old that it has never been converted to use BFD. Now that's old! +@end table + +@node XCOFF +@chapter The XCOFF Object File Format + +The IBM RS/6000 running AIX uses an object file format called xcoff. +The COFF sections, symbols, and line numbers are used, but debugging +symbols are dbx-style stabs whose strings are located in the +@samp{.debug} section (rather than the string table). For more +information, @xref{Top,,,stabs,The Stabs Debugging Format}, and search +for XCOFF. + +The shared library scheme has a nice clean interface for figuring out +what shared libraries are in use, but the catch is that everything which +refers to addresses (symbol tables and breakpoints at least) needs to be +relocated for both shared libraries and the main executable. At least +using the standard mechanism this can only be done once the program has +been run (or the core file has been read). + +@contents +@bye |