diff options
Diffstat (limited to 'gdb/doc/gdbint.texinfo')
| -rw-r--r-- | gdb/doc/gdbint.texinfo | 2711 |
1 files changed, 2711 insertions, 0 deletions
diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo new file mode 100644 index 00000000000..99f081dcda4 --- /dev/null +++ b/gdb/doc/gdbint.texinfo @@ -0,0 +1,2711 @@ +\input texinfo +@setfilename gdbint.info + +@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-1999 Free Software Foundation, Inc. +Contributed by Cygnus Solutions. Written by John Gilmore. +Second Edition by Stan Shebs. + +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{GDB Internals} +@subtitle{A guide to the internals of the GNU debugger} +@author John Gilmore +@author Cygnus Solutions +@author Second Edition: +@author Stan Shebs +@author Cygnus Solutions +@page +@tex +\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ +\xdef\manvers{\$Revision$} % For use in headers, footers too +{\parskip=0pt +\hfill Cygnus Solutions\par +\hfill \manvers\par +\hfill \TeX{}info \texinfoversion\par +} +@end tex + +@vskip 0pt plus 1filll +Copyright @copyright{} 1990-1999 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 +includes description of GDB's key algorithms and operations, as well +as the mechanisms that adapt GDB to specific hosts and targets. + +@menu +* Requirements:: +* Overall Structure:: +* Algorithms:: +* User Interface:: +* Symbol Handling:: +* Language Support:: +* Host Definition:: +* Target Architecture Definition:: +* Target Vector Definition:: +* Native Debugging:: +* Support Libraries:: +* Coding:: +* Porting GDB:: +* Hints:: +@end menu + +@node Requirements + +@chapter Requirements + +Before diving into the internals, you should understand the formal +requirements and other expectations for GDB. Although some of these may +seem obvious, there have been proposals for GDB that have run counter to +these requirements. + +First of all, GDB is a debugger. It's not designed to be a front panel +for embedded systems. It's not a text editor. It's not a shell. It's +not a programming environment. + +GDB is an interactive tool. Although a batch mode is available, GDB's +primary role is to interact with a human programmer. + +GDB should be responsive to the user. A programmer hot on the trail of +a nasty bug, and operating under a looming deadline, is going to be very +impatient of everything, including the response time to debugger +commands. + +GDB should be relatively permissive, such as for expressions. While the +compiler should be picky (or have the option to be made picky), since +source code lives for a long time usually, the programmer doing +debugging shouldn't be spending time figuring out to mollify the +debugger. + +GDB will be called upon to deal with really large programs. Executable +sizes of 50 to 100 megabytes occur regularly, and we've heard reports of +programs approaching 1 gigabyte in size. + +GDB should be able to run everywhere. No other debugger is available +for even half as many configurations as GDB supports. + + +@node Overall Structure + +@chapter Overall Structure + +GDB consists of three major subsystems: user interface, symbol handling +(the ``symbol side''), and target system handling (the ``target side''). + +Ther user interface consists of several actual interfaces, plus +supporting code. + +The symbol side consists of object file readers, debugging info +interpreters, symbol table management, source language expression +parsing, type and value printing. + +The target side consists of execution control, stack frame analysis, and +physical target manipulation. + +The target side/symbol side division is not formal, and there are a +number of exceptions. For instance, core file support involves symbolic +elements (the basic core file reader is in BFD) and target elements (it +supplies the contents of memory and the values of registers). Instead, +this division is useful for understanding how the minor subsystems +should fit together. + +@section The Symbol Side + +The symbolic side of GDB can be thought of as ``everything you can do in +GDB without having a live program running''. For instance, you can look +at the types of variables, and evaluate many kinds of expressions. + +@section The Target Side + +The target side of GDB is the ``bits and bytes manipulator''. Although +it may make reference to symbolic info here and there, most of the +target side will run with only a stripped executable available -- or +even no executable at all, in remote debugging cases. + +Operations such as disassembly, stack frame crawls, and register +display, are able to work with no symbolic info at all. In some cases, +such as disassembly, GDB will use symbolic info to present addresses +relative to symbols rather than as raw numbers, but it will work either +way. + +@section Configurations + +@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. + + +@node Algorithms + +@chapter Algorithms + +GDB uses a number of debugging-specific algorithms. They are often not +very complicated, but get lost in the thicket of special cases and +real-world issues. This chapter describes the basic algorithms and +mentions some of the specific target definitions that they use. + +@section Frames + +A frame is a construct that GDB uses to keep track of calling and called +functions. + +@code{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.) + +Given a GDB frame, define @code{FRAME_CHAIN} to 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. + +@section Breakpoint Handling + +In general, a breakpoint is a user-designated location in the program +where the user wants to regain control if program execution ever reaches +that location. + +There are two main ways to implement breakpoints; either as ``hardware'' +breakpoints or as ``software'' breakpoints. + +Hardware breakpoints are sometimes available as a builtin debugging +features with some chips. Typically these work by having dedicated +register into which the breakpoint address may be stored. If the PC +ever matches a value in a breakpoint registers, the CPU raises an +exception and reports it to GDB. Another possibility is when an +emulator is in use; many emulators include circuitry that watches the +address lines coming out from the processor, and force it to stop if the +address matches a breakpoint's address. A third possibility is that the +target already has the ability to do breakpoints somehow; for instance, +a ROM monitor may do its own software breakpoints. So although these +are not literally ``hardware breakpoints'', from GDB's point of view +they work the same; GDB need not do nothing more than set the breakpoint +and wait for something to happen. + +Since they depend on hardware resources, hardware breakpoints may be +limited in number; when the user asks for more, GDB will start trying to +set software breakpoints. + +Software breakpoints require GDB to do somewhat more work. The basic +theory is that GDB will replace a program instruction a trap, illegal +divide, or some other instruction that will cause an exception, and then +when it's encountered, GDB will take the exception and stop the program. +When the user says to continue, GDB will restore the original +instruction, single-step, re-insert the trap, and continue on. + +Since it literally overwrites the program being tested, the program area +must be writeable, so this technique won't work on programs in ROM. It +can also distort the behavior of programs that examine themselves, +although the situation would be highly unusual. + +Also, the software breakpoint instruction should be the smallest size of +instruction, so it doesn't overwrite an instruction that might be a jump +target, and cause disaster when the program jumps into the middle of the +breakpoint instruction. (Strictly speaking, the breakpoint must be no +larger than the smallest interval between instructions that may be jump +targets; perhaps there is an architecture where only even-numbered +instructions may jumped to.) Note that it's possible for an instruction +set not to have any instructions usable for a software breakpoint, +although in practice only the ARC has failed to define such an +instruction. + +The basic definition of the software breakpoint is the macro +@code{BREAKPOINT}. + +Basic breakpoint object handling is in @file{breakpoint.c}. However, +much of the interesting breakpoint action is in @file{infrun.c}. + +@section Single Stepping + +@section Signal Handling + +@section Thread Handling + +@section Inferior Function Calls + +@section 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-@var{xyz}.h} file. Look in @file{tm-sun4os4.h} and +@file{sparc-tdep.c} for examples of how to do this. + +@node User Interface + +@chapter User Interface + +GDB has several user interfaces. Although the command-line interface +is the most common and most familiar, there are others. + +@section Command Interpreter + +The command interpreter in GDB is fairly simple. It is designed to +allow for the set of commands to be augmented dynamically, and also +has a recursive subcommand capability, where the first argument to +a command may itself direct a lookup on a different command list. + +For instance, the @code{set} command just starts a lookup on the +@code{setlist} command list, while @code{set thread} recurses +to the @code{set_thread_cmd_list}. + +To add commands in general, use @code{add_cmd}. @code{add_com} adds to +the main command list, and should be used for those commands. The usual +place to add commands is in the @code{_initialize_@var{xyz}} routines at the +ends of most source files. + +@section Console Printing + +@section TUI + +@section libgdb + +@code{libgdb} was an abortive project of years ago. The theory was to +provide an API to GDB's functionality. + +@node Symbol Handling + +@chapter Symbol Handling + +Symbols are a key part of GDB's operation. Symbols include variables, +functions, and types. + +@section 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 @code{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 code in @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{xyz}_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{xyz}_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{xyz}_symfile_init}, but it can call +@code{error} if it detects an unavoidable problem. + +@item @var{xyz}_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{xyz}_symfile_init}, if a new +symbol table is being read, or may be called alone if all symbols are +simply being discarded. + +@item @var{xyz}_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{xyz}_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{xyz}_symfile_read is called, these psymtabs will contain a pointer +to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called +from any point in the GDB symbol-handling code. + +@table @code +@item @var{xyz}_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 + +@section 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. +@c (@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. + +@section 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. + +@section Object File Formats + +@subsection a.out + +The @file{a.out} format is the original file format for Unix. It +consists of three sections: text, data, and bss, which are for program +code, initialized data, and uninitialized data, respectively. + +The @file{a.out} format is so simple that it doesn't have any reserved +place for debugging information. (Hey, the original Unix hackers used +@file{adb}, which is a machine-language debugger.) The only debugging +format for @file{a.out} is stabs, which is encoded as a set of normal +symbols with distinctive attributes. + +The basic @file{a.out} reader is in @file{dbxread.c}. + +@subsection COFF + +The COFF format was introduced with System V Release 3 (SVR3) Unix. +COFF files may have multiple sections, each prefixed by a header. The +number of sections is limited. + +The COFF specification includes support for debugging. Although this +was a step forward, the debugging information was woefully limited. For +instance, it was not possible to represent code that came from an +included file. + +The COFF reader is in @file{coffread.c}. + +@subsection ECOFF + +ECOFF is an extended COFF originally introduced for Mips and Alpha +workstations. + +The basic ECOFF reader is in @file{mipsread.c}. + +@subsection XCOFF + +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, see @xref{Top,,,stabs,The Stabs Debugging Format}. + +The shared library scheme has a 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). + +@subsection PE + +Windows 95 and NT use the PE (Portable Executable) format for their +executables. PE is basically COFF with additional headers. + +While BFD includes special PE support, GDB needs only the basic +COFF reader. + +@subsection ELF + +The ELF format came with System V Release 4 (SVR4) Unix. ELF is similar +to COFF in being organized into a number of sections, but it removes +many of COFF's limitations. + +The basic ELF reader is in @file{elfread.c}. + +@subsection SOM + +SOM is HP's object file and debug format (not to be confused with IBM's +SOM, which is a cross-language ABI). + +The SOM reader is in @file{hpread.c}. + +@subsection Other File Formats + +Other file formats that have been supported by GDB include Netware +Loadable Modules (@file{nlmread.c}. + +@section Debugging File Formats + +This section describes characteristics of debugging information that +are independent of the object file format. + +@subsection stabs + +@code{stabs} started out as special symbols within the @code{a.out} +format. Since then, it has been encapsulated into other file +formats, such as COFF and ELF. + +While @file{dbxread.c} does some of the basic stab processing, +including for encapsulated versions, @file{stabsread.c} does +the real work. + +@subsection COFF + +The basic COFF definition includes debugging information. The level +of support is minimal and non-extensible, and is not often used. + +@subsection Mips debug (Third Eye) + +ECOFF includes a definition of a special debug format. + +The file @file{mdebugread.c} implements reading for this format. + +@subsection DWARF 1 + +DWARF 1 is a debugging format that was originally designed to be +used with ELF in SVR4 systems. + +@c CHILL_PRODUCER +@c GCC_PRODUCER +@c GPLUS_PRODUCER +@c LCC_PRODUCER +@c If defined, these are the producer strings in a DWARF 1 file. All of +@c these have reasonable defaults already. + +The DWARF 1 reader is in @file{dwarfread.c}. + +@subsection DWARF 2 + +DWARF 2 is an improved but incompatible version of DWARF 1. + +The DWARF 2 reader is in @file{dwarf2read.c}. + +@subsection SOM + +Like COFF, the SOM definition includes debugging information. + +@section Adding a New Symbol Reader to GDB + +If you are using an existing object file format (a.out, COFF, ELF, etc), +there is probably little to be done. + +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. + +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/libxyz.h}, which is included by GDB. + + +@node Language Support + +@chapter Language Support + +GDB's language support is mainly driven by the symbol reader, although +it is possible for the user to set the source language manually. + +GDB chooses the source language by looking at the extension of the file +recorded in the debug info; @code{.c} means C, @code{.f} means Fortran, +etc. It may also use a special-purpose language identifier if the debug +format supports it, such as DWARF. + +@section 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 Host Definition + +@chapter Host Definition + +With the advent of autoconf, it's rarely necessary to have host +definition machinery anymore. + +@section Adding a New Host + +Most of GDB's host configuration support happens via autoconf. It +should be rare to need new host-specific definitions. GDB still uses +the host-specific definitions and files listed below, but these mostly +exist for historical reasons, and should eventually disappear. + +Several files control GDB's configuration for host systems: + +@table @file + +@item gdb/config/@var{arch}/@var{xyz}.mh +Specifies Makefile fragments needed when hosting on machine @var{xyz}. +In particular, this lists the required machine-dependent object files, +by defining @samp{XDEPFILES=@dots{}}. Also specifies the header file +which describes host @var{xyz}, by defining @code{XM_FILE= +xm-@var{xyz}.h}. You can also define @code{CC}, @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{xyz}.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. + +@item gdb/@var{xyz}-xdep.c +Contains any miscellaneous C code required for this machine as a host. +On most machines it doesn't exist at all. If it does exist, put +@file{@var{xyz}-xdep.o} into the @code{XDEPFILES} line in +@file{gdb/config/@var{arch}/@var{xyz}.mh}. + +@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{xyz}.h} file. If these routines work for +the @var{xyz} 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{xyz}-xdep.c}, and put @code{@var{xyz}-xdep.o} +into @code{XDEPFILES}. + +@table @file + +@item ser-unix.c +This contains serial line support for Unix systems. This is always +included, via the makefile variable @code{SER_HARDWIRE}; override this +variable in the @file{.mh} file to avoid it. + +@item ser-go32.c +This contains serial line support for 32-bit programs running under DOS, +using the GO32 execution environment. + +@item ser-tcp.c +This contains generic TCP support using sockets. + +@end table + +@section 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 (or if the meaning is not +documented here, then one of the source files where they are used is +indicated) are: + +@table @code + +@item GDBINIT_FILENAME +The default name of GDB's initialization file (normally @file{.gdbinit}). + +@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 +Define this if your system does not have a @code{<sys/file.h>}. + +@item SIGWINCH_HANDLER +If your host defines @code{SIGWINCH}, you can define this to be the name +of a function to be called if @code{SIGWINCH} is received. + +@item SIGWINCH_HANDLER_BODY +Define this to expand into code that will define the function named by +the expansion of @code{SIGWINCH_HANDLER}. + +@item ALIGN_STACK_ON_STARTUP +Define this if your system is of a sort that will crash in +@code{tgetent} if the stack happens not to be longword-aligned when +@code{main} is called. This is a rare situation, but is known to occur +on several different types of systems. + +@item CRLF_SOURCE_FILES +Define this if host files use @code{\r\n} rather than @code{\n} as a +line terminator. This will cause source file listings to omit @code{\r} +characters when printing and it will allow \r\n line endings of files +which are "sourced" by gdb. It must be possible to open files in binary +mode using @code{O_BINARY} or, for fopen, @code{"rb"}. + +@item DEFAULT_PROMPT +The default value of the prompt string (normally @code{"(gdb) "}). + +@item DEV_TTY +The name of the generic TTY device, defaults to @code{"/dev/tty"}. + +@item FCLOSE_PROVIDED +Define this if the system declares @code{fclose} in the headers included +in @code{defs.h}. This isn't needed unless your compiler is unusually +anal. + +@item FOPEN_RB +Define this if binary files are opened the same way as text files. + +@item GETENV_PROVIDED +Define this if the system declares @code{getenv} in its headers included +in @code{defs.h}. This isn't needed unless your compiler is unusually +anal. + +@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_SIGSETMASK +Define this if the host system has job control, but does not define +@code{sigsetmask()}. Currently, this is only true of the RS/6000. + +@item HAVE_TERMIO +Define this if the host system has @code{termio.h}. + +@item HOST_BYTE_ORDER +The ordering of bytes in the host. This must be defined to be either +@code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. + +@item INT_MAX +@item INT_MIN +@item LONG_MAX +@item UINT_MAX +@item ULONG_MAX +Values for host-side constants. + +@item ISATTY +Substitute for isatty, if not available. + +@item LONGEST +This is the longest integer type available on the host. If not defined, +it will default to @code{long long} or @code{long}, depending on +@code{CC_HAS_LONG_LONG}. + +@item CC_HAS_LONG_LONG +Define this if the host C compiler supports ``long long''. This is set +by the configure script. + +@item PRINTF_HAS_LONG_LONG +Define this if the host can handle printing of long long integers via +the printf format directive ``ll''. This is set by the configure script. + +@item HAVE_LONG_DOUBLE +Define this if the host C compiler supports ``long double''. This is +set by the configure script. + +@item PRINTF_HAS_LONG_DOUBLE +Define this if the host can handle printing of long double float-point +numbers via the printf format directive ``Lg''. This is set by the +configure script. + +@item SCANF_HAS_LONG_DOUBLE +Define this if the host can handle the parsing of long double +float-point numbers via the scanf format directive directive +``Lg''. This is set by the configure script. + +@item LSEEK_NOT_LINEAR +Define this if @code{lseek (n)} does not necessarily move to byte number +@code{n} in the file. This is only used when reading source files. It +is normally faster to define @code{CRLF_SOURCE_FILES} when possible. + +@item L_SET +This macro is used as the argument to lseek (or, most commonly, +bfd_seek). FIXME, should be replaced by SEEK_SET instead, which is the +POSIX equivalent. + +@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 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 NEED_POSIX_SETPGID +Define this to use the POSIX version of @code{setpgid} to determine +whether job control is available. + +@item NORETURN +If defined, this should be one or more tokens, such as @code{volatile}, +that can be used in both the declaration and definition of functions to +indicate that they never return. The default is already set correctly +if compiling with GCC. This will almost never need to be defined. + +@item ATTR_NORETURN +If defined, this should be one or more tokens, such as +@code{__attribute__ ((noreturn))}, that can be used in the declarations +of functions to indicate that they never return. The default is already +set correctly if compiling with GCC. This will almost never need to be +defined. + +@item USE_MMALLOC +GDB will use the @code{mmalloc} library for memory allocation for symbol +reading if this symbol is defined. Be careful defining it since there +are 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{USE_MMALLOC}, you will also have to set @code{MMALLOC} in the +Makefile, to point to the mmalloc library. This define is set when you +configure with --with-mmalloc. + +@item NO_MMCHECK +Define this if you are using @code{mmalloc}, but don't want the overhead +of checking the heap with @code{mmcheck}. Note that on some systems, +the C runtime makes calls to malloc prior to calling @code{main}, and if +@code{free} is ever called with these pointers after calling +@code{mmcheck} to enable checking, a memory corruption abort is certain +to occur. These systems can still use mmalloc, but must define +NO_MMCHECK. + +@item MMCHECK_FORCE +Define this to 1 if the C runtime allocates memory prior to +@code{mmcheck} being called, but that memory is never freed so we don't +have to worry about it triggering a memory corruption abort. The +default is 0, which means that @code{mmcheck} will only install the heap +checking functions if there has not yet been any memory allocation +calls, and if it fails to install the functions, gdb will issue a +warning. This is currently defined if you configure using +--with-mmalloc. + +@item NO_SIGINTERRUPT +Define this to indicate that siginterrupt() is not available. + +@item R_OK +Define if this is not in a system .h file. + +@item SEEK_CUR +@item SEEK_SET +Define these to appropriate value for the system lseek(), if not already +defined. + +@item STOP_SIGNAL +This is the signal for stopping GDB. Defaults to SIGTSTP. (Only +redefined for the Convex.) + +@item USE_O_NOCTTY +Define this if the interior's tty should be opened with the O_NOCTTY +flag. (FIXME: This should be a native-only flag, but @file{inflow.c} is +always linked in.) + +@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 lint +Define this to help placate lint in some situations. + +@item volatile +Define this to override the defaults of @code{__volatile__} or +@code{/**/}. + +@end table + + +@node Target Architecture Definition + +@chapter Target Architecture Definition + +GDB's target architecture defines what sort of machine-language programs +GDB can work with, and how it works with them. + +At present, the target architecture definition consists of a number of C +macros. + +@section Registers and Memory + +GDB's model of the target machine is rather simple. GDB assumes the +machine includes a bank of registers and a block of memory. Each +register may have a different size. + +GDB does not have a magical way to match up with the compiler's idea of +which registers are which; however, it is critical that they do match up +accurately. The only way to make this work is to get accurate +information about the order that the compiler uses, and to reflect that +in the @code{REGISTER_NAME} and related macros. + +GDB can handle big-endian, little-endian, and bi-endian architectures. + +@section Frame Interpretation + +@section Inferior Call Setup + +@section Compiler Characteristics + +@section Target Conditionals + +This section describes the macros that you can use to define the target +machine. + +@table @code + +@item ADDITIONAL_OPTIONS +@item ADDITIONAL_OPTION_CASES +@item ADDITIONAL_OPTION_HANDLER +@item ADDITIONAL_OPTION_HELP +These are a set of macros that allow the addition of additional command +line options to GDB. They are currently used only for the unsupported +i960 Nindy target, and should not be used in any other configuration. + +@item ADDR_BITS_REMOVE (addr) +If a raw machine address includes any bits that are not really part of +the address, then define this macro to expand into an expression that +zeros those bits in @var{addr}. For example, the two low-order bits of +a Motorola 88K address may be used by some kernels for their own +purposes, since addresses must always be 4-byte aligned, and so are of +no use for addressing. Those bits should be filtered out with an +expression such as @code{((addr) & ~3)}. + +@item BEFORE_MAIN_LOOP_HOOK +Define this to expand into any code that you want to execute before the +main loop starts. Although this is not, strictly speaking, a target +conditional, that is how it is currently being used. Note that if a +configuration were to define it one way for a host and a different way +for the target, GDB will probably not compile, let alone run correctly. +This is currently used only for the unsupported i960 Nindy target, and +should not be used in any other configuration. + +@item BELIEVE_PCC_PROMOTION +Define if the compiler promotes a short or char parameter to an int, but +still reports the parameter as its original type, rather than the +promoted type. + +@item BELIEVE_PCC_PROMOTION_TYPE +Define this if GDB should believe the type of a short argument when +compiled by pcc, but look within a full int space to get its value. +Only defined for Sun-3 at present. + +@item BITS_BIG_ENDIAN +Define this if the numbering of bits in the targets does *not* match the +endianness of the target byte order. A value of 1 means that the bits +are numbered in a big-endian order, 0 means little-endian. + +@item BREAKPOINT +This is the character array initializer for the bit pattern to put into +memory where a breakpoint is set. Although it's common to use a trap +instruction for a breakpoint, it's not required; for instance, the bit +pattern could be an invalid instruction. The breakpoint must be no +longer than the shortest instruction of the architecture. + +@item BIG_BREAKPOINT +@item LITTLE_BREAKPOINT +Similar to BREAKPOINT, but used for bi-endian targets. + +@item REMOTE_BREAKPOINT +@item LITTLE_REMOTE_BREAKPOINT +@item BIG_REMOTE_BREAKPOINT +Similar to BREAKPOINT, but used for remote targets. + +@item BREAKPOINT_FROM_PC (pcptr, lenptr) + +Use the program counter to determine the contents and size of a +breakpoint instruction. It returns a pointer to a string of bytes that +encode a breakpoint instruction, stores the length of the string to +*lenptr, and adjusts pc (if necessary) to point to the actual memory +location where the breakpoint should be inserted. + +Although it is common to use a trap instruction for a breakpoint, it's +not required; for instance, the bit pattern could be an invalid +instruction. The breakpoint must be no longer than the shortest +instruction of the architecture. + +Replaces all the other BREAKPOINTs. + +@item CALL_DUMMY +valops.c +@item CALL_DUMMY_LOCATION +inferior.h +@item CALL_DUMMY_STACK_ADJUST +valops.c + +@item CANNOT_FETCH_REGISTER (regno) +A C expression that should be nonzero if @var{regno} cannot be fetched +from an inferior process. This is only relevant if +@code{FETCH_INFERIOR_REGISTERS} is not defined. + +@item CANNOT_STORE_REGISTER (regno) +A C expression that should be nonzero if @var{regno} should not be +written to the target. This is often the case for program counters, +status words, and other special registers. If this is not defined, GDB +will assume that all registers may be written. + +@item DO_DEFERRED_STORES +@item CLEAR_DEFERRED_STORES +Define this to execute any deferred stores of registers into the inferior, +and to cancel any deferred stores. + +Currently only implemented correctly for native Sparc configurations? + +@item CPLUS_MARKER +Define this to expand into the character that G++ uses to distinguish +compiler-generated identifiers from programmer-specified identifiers. +By default, this expands into @code{'$'}. Most System V targets should +define this to @code{'.'}. + +@item DBX_PARM_SYMBOL_CLASS +Hook for the @code{SYMBOL_CLASS} of a parameter when decoding DBX symbol +information. In the i960, parameters can be stored as locals or as +args, depending on the type of the debug record. + +@item DECR_PC_AFTER_BREAK +Define this to be the amount by which to decrement the PC after the +program encounters a breakpoint. This is often the number of bytes in +BREAKPOINT, though not always. For most targets this value will be 0. + +@item DECR_PC_AFTER_HW_BREAK +Similarly, for hardware breakpoints. + +@item DISABLE_UNSETTABLE_BREAK addr +If defined, this should evaluate to 1 if @var{addr} is in a shared +library in which breakpoints cannot be set and so should be disabled. + +@item DO_REGISTERS_INFO +If defined, use this to print the value of a register or all registers. + +@item END_OF_TEXT_DEFAULT +This is an expression that should designate the end of the text section +(? FIXME ?) + +@item EXTRACT_RETURN_VALUE(type,regbuf,valbuf) +Define this to extract a function's return value of type @var{type} from +the raw register state @var{regbuf} and copy that, in virtual format, +into @var{valbuf}. + +@item EXTRACT_STRUCT_VALUE_ADDRESS(regbuf) +Define this to extract from an array @var{regbuf} containing the (raw) +register state, the address in which a function should return its +structure value, as a CORE_ADDR (or an expression that can be used as +one). + +@item FLOAT_INFO +If defined, then the `info float' command will print information about +the processor's floating point unit. + +@item FP_REGNUM +The number of the frame pointer register. + +@item FRAMELESS_FUNCTION_INVOCATION(fi, frameless) +Define this to set the variable @var{frameless} to 1 if the function +invocation represented by @var{fi} does not have a stack frame +associated with it. Otherwise set it to 0. + +@item FRAME_ARGS_ADDRESS_CORRECT +stack.c + +@item FRAME_CHAIN(frame) +Given @var{frame}, return a pointer to the calling frame. + +@item FRAME_CHAIN_COMBINE(chain,frame) +Define this to take the frame chain pointer and the frame's nominal +address and produce the nominal address of the caller's frame. +Presently only defined for HP PA. + +@item FRAME_CHAIN_VALID(chain,thisframe) + +Define this to be an expression that returns zero if the given frame is +an outermost frame, with no caller, and nonzero otherwise. Three common +definitions are available. @code{default_frame_chain_valid} (the +default) is nonzero if the chain pointer is nonzero and given frame's PC +is not inside the startup file (such as @file{crt0.o}). +@code{alternate_frame_chain_valid} is nonzero if the chain pointer is +nonzero and the given frame's PC is not in @code{main()} or a known +entry point function (such as @code{_start()}). + +@item FRAME_INIT_SAVED_REGS(frame) +See @file{frame.h}. Determines the address of all registers in the +current stack frame storing each in @code{frame->saved_regs}. Space for +@code{frame->saved_regs} shall be allocated by +@code{FRAME_INIT_SAVED_REGS} using either +@code{frame_saved_regs_zalloc} or @code{frame_obstack_alloc}. + +@var{FRAME_FIND_SAVED_REGS} and @var{EXTRA_FRAME_INFO} are deprecated. + +@item FRAME_NUM_ARGS (val, fi) +For the frame described by @var{fi}, set @var{val} to the number of arguments +that are being passed. + +@item FRAME_SAVED_PC(frame) +Given @var{frame}, return the pc saved there. That is, the return +address. + +@item FUNCTION_EPILOGUE_SIZE +For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the +function end symbol is 0. For such targets, you must define +@code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a +function's epilogue. + +@item GCC_COMPILED_FLAG_SYMBOL +@item GCC2_COMPILED_FLAG_SYMBOL +If defined, these are the names of the symbols that GDB will look for to +detect that GCC compiled the file. The default symbols are +@code{gcc_compiled.} and @code{gcc2_compiled.}, respectively. (Currently +only defined for the Delta 68.) + +@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 +@item GDB_TARGET_IS_SUN3 +@item GDB_TARGET_IS_SUN386 +Kludges that should go away. + +@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 +Define this if you need to supply your own definition for the function +@code{get_saved_register}. Currently this is only done for the a29k. + +@item HAVE_REGISTER_WINDOWS +Define this if the target has register windows. +@item REGISTER_IN_WINDOW_P (regnum) +Define this to be an expression that is 1 if the given register is in +the window. + +@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_FLOAT +Define this if the target system uses IEEE-format floating point numbers. + +@item INIT_EXTRA_FRAME_INFO (fromleaf, frame) +If additional information about the frame is required this should be +stored in @code{frame->extra_info}. Space for @code{frame->extra_info} +is allocated using @code{frame_obstack_alloc}. + +@item INIT_FRAME_PC (fromleaf, prev) +This is a C statement that sets the pc of the frame pointed to by +@var{prev}. [By default...] + +@item INNER_THAN (lhs,rhs) +Returns non-zero if stack address @var{lhs} is inner than (nearer to the +stack top) stack address @var{rhs}. Define this as @code{lhs < rhs} if +the target's stack grows downward in memory, or @code{lhs > rsh} if the +stack grows upward. + +@item IN_SIGTRAMP (pc, name) +Define this to return true if the given @var{pc} and/or @var{name} +indicates that the current function is a sigtramp. + +@item SIGTRAMP_START (pc) +@item SIGTRAMP_END (pc) +Define these to be the start and end address of the sigtramp for the +given @var{pc}. On machines where the address is just a compile time +constant, the macro expansion will typically just ignore the supplied +@var{pc}. + +@item IN_SOLIB_CALL_TRAMPOLINE pc name +Define this to evaluate to nonzero if the program is stopped in the +trampoline that connects to a shared library. + +@item IN_SOLIB_RETURN_TRAMPOLINE pc name +Define this to evaluate to nonzero if the program is stopped in the +trampoline that returns from a shared library. + +@item IS_TRAPPED_INTERNALVAR (name) +This is an ugly hook to allow the specification of special actions that +should occur as a side-effect of setting the value of a variable +internal to GDB. Currently only used by the h8500. Note that this +could be either a host or target conditional. + +@item NEED_TEXT_START_END +Define this if GDB should determine the start and end addresses of the +text section. (Seems dubious.) + +@item NO_HIF_SUPPORT +(Specific to the a29k.) + +@item SOFTWARE_SINGLE_STEP_P +Define this as 1 if the target does not have a hardware single-step +mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined. + +@item SOFTWARE_SINGLE_STEP(signal,insert_breapoints_p) +A function that inserts or removes (dependant on +@var{insert_breapoints_p}) breakpoints at each possible destinations of +the next instruction. See @code{sparc-tdep.c} and @code{rs6000-tdep.c} +for examples. + +@item PCC_SOL_BROKEN +(Used only in the Convex target.) + +@item PC_IN_CALL_DUMMY +inferior.h + +@item PC_LOAD_SEGMENT +If defined, print information about the load segment for the program +counter. (Defined only for the RS/6000.) + +@item PC_REGNUM +If the program counter is kept in a register, then define this macro to +be the number of that register. This need be defined only if +@code{TARGET_WRITE_PC} is not defined. + +@item NPC_REGNUM +The number of the ``next program counter'' register, if defined. + +@item NNPC_REGNUM +The number of the ``next next program counter'' register, if defined. +Currently, this is only defined for the Motorola 88K. + +@item PRINT_REGISTER_HOOK (regno) +If defined, this must be a function that prints the contents of the +given register to standard output. + +@item PRINT_TYPELESS_INTEGER +This is an obscure substitute for @code{print_longest} that seems to +have been defined for the Convex target. + +@item PROCESS_LINENUMBER_HOOK +A hook defined for XCOFF reading. + +@item PROLOGUE_FIRSTLINE_OVERLAP +(Only used in unsupported Convex configuration.) + +@item PS_REGNUM +If defined, this is the number of the processor status register. (This +definition is only used in generic code when parsing "$ps".) + +@item POP_FRAME +Used in @samp{call_function_by_hand} to remove an artificial stack +frame. + +@item PUSH_ARGUMENTS (nargs, args, sp, struct_return, struct_addr) +Define this to push arguments onto the stack for inferior function call. + +@item PUSH_DUMMY_FRAME +Used in @samp{call_function_by_hand} to create an artificial stack frame. + +@item REGISTER_BYTES +The total amount of space needed to store GDB's copy of the machine's +register state. + +@item REGISTER_NAME(i) +Return the name of register @var{i} as a string. May return @var{NULL} +or @var{NUL} to indicate that register @var{i} is not valid. + +@item REG_STRUCT_HAS_ADDR (gcc_p, type) +Define this to return 1 if the given type will be passed by pointer +rather than directly. + +@item SDB_REG_TO_REGNUM +Define this to convert sdb register numbers into GDB regnums. If not +defined, no conversion will be done. + +@item SHIFT_INST_REGS +(Only used for m88k targets.) + +@item SKIP_PROLOGUE (pc) +A C statement that advances the @var{pc} across any function entry +prologue instructions so as to reach ``real'' code. + +@item SKIP_PROLOGUE_FRAMELESS_P +A C statement that should behave similarly, but that can stop as soon as +the function is known to have a frame. If not defined, +@code{SKIP_PROLOGUE} will be used instead. + +@item SKIP_TRAMPOLINE_CODE (pc) +If the target machine has trampoline code that sits between callers and +the functions being called, then define this macro to return a new PC +that is at the start of the real function. + +@item SP_REGNUM +Define this to be the number of the register that serves as the stack +pointer. + +@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 (addr) +Define this to adjust the address to the alignment required for the +processor's stack. + +@item STEP_SKIPS_DELAY (addr) +Define this to return true if the address is of an instruction with a +delay slot. If a breakpoint has been placed in the instruction's delay +slot, GDB will single-step over that instruction before resuming +normally. Currently only defined for the Mips. + +@item STORE_RETURN_VALUE (type, valbuf) +A C expression that stores a function return value of type @var{type}, +where @var{valbuf} is the address of the value to be stored. + +@item SUN_FIXED_LBRAC_BUG +(Used only for Sun-3 and Sun-4 targets.) + +@item SYMBOL_RELOADING_DEFAULT +The default value of the `symbol-reloading' variable. (Never defined in +current sources.) + +@item TARGET_BYTE_ORDER_DEFAULT +The ordering of bytes in the target. This must be either +@code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. This macro replaces +@var{TARGET_BYTE_ORDER} which is deprecated. + +@item TARGET_BYTE_ORDER_SELECTABLE_P +Non-zero if the target has both @code{BIG_ENDIAN} and +@code{LITTLE_ENDIAN} variants. This macro replaces +@var{TARGET_BYTE_ORDER_SELECTABLE} which is deprecated. + +@item TARGET_CHAR_BIT +Number of bits in a char; defaults to 8. + +@item TARGET_COMPLEX_BIT +Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}. + +@item TARGET_DOUBLE_BIT +Number of bits in a double float; defaults to @code{8 * TARGET_CHAR_BIT}. + +@item TARGET_DOUBLE_COMPLEX_BIT +Number of bits in a double complex; defaults to @code{2 * TARGET_DOUBLE_BIT}. + +@item TARGET_FLOAT_BIT +Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}. + +@item TARGET_INT_BIT +Number of bits in an integer; defaults to @code{4 * TARGET_CHAR_BIT}. + +@item TARGET_LONG_BIT +Number of bits in a long integer; defaults to @code{4 * TARGET_CHAR_BIT}. + +@item TARGET_LONG_DOUBLE_BIT +Number of bits in a long double float; +defaults to @code{2 * TARGET_DOUBLE_BIT}. + +@item TARGET_LONG_LONG_BIT +Number of bits in a long long integer; defaults to @code{2 * TARGET_LONG_BIT}. + +@item TARGET_PTR_BIT +Number of bits in a pointer; defaults to @code{TARGET_INT_BIT}. + +@item TARGET_SHORT_BIT +Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}. + +@item TARGET_READ_PC +@item TARGET_WRITE_PC (val, pid) +@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_VIRTUAL_FRAME_POINTER(pc,regp,offsetp) +Returns a @code{(register, offset)} pair representing the virtual +frame pointer in use at the code address @code{"pc"}. If virtual +frame pointers are not used, a default definition simply returns +@code{FP_REGNUM}, with an offset of zero. + +@item USE_STRUCT_CONVENTION (gcc_p, type) +If defined, this must be an expression that is nonzero if a value of the +given @var{type} being returned from a function must have space +allocated for it on the stack. @var{gcc_p} is true if the function +being considered is known to have been compiled by GCC; this is helpful +for systems where GCC is known to use different calling convention than +other compilers. + +@item VARIABLES_INSIDE_BLOCK (desc, gcc_p) +For dbx-style debugging information, if the compiler puts variable +declarations inside LBRAC/RBRAC blocks, this should be defined to be +nonzero. @var{desc} is the value of @code{n_desc} from the +@code{N_RBRAC} symbol, and @var{gcc_p} is true if GDB has noticed the +presence of either the @code{GCC_COMPILED_SYMBOL} or the +@code{GCC2_COMPILED_SYMBOL}. By default, this is 0. + +@item OS9K_VARIABLES_INSIDE_BLOCK (desc, gcc_p) +Similarly, for OS/9000. Defaults to 1. + +@end table + +Motorola M68K target conditionals. + +@table @code + +@item BPT_VECTOR +Define this to be the 4-bit location of the breakpoint trap vector. If +not defined, it will default to @code{0xf}. + +@item REMOTE_BPT_VECTOR +Defaults to @code{1}. + +@end table + +@section Adding a New Target + +The following files define a target to GDB: + +@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}, but +these are now deprecated and may go away in future versions of GDB. + +@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. + +@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. This is vastly preferable, since it is easier to understand +and debug. + +@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{ttt}.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 + +If you are adding a new operating system for an existing CPU chip, add a +@file{config/tm-@var{os}.h} file that describes the operating system +facilities that are unusual (extra symbol table info; the breakpoint +instruction needed; etc). Then write a @file{@var{arch}/tm-@var{os}.h} +that just @code{#include}s @file{tm-@var{arch}.h} and +@file{config/tm-@var{os}.h}. + + +@node Target Vector Definition + +@chapter Target Vector Definition + +The target vector defines the interface between GDB's abstract handling +of target systems, and the nitty-gritty code that actually exercises +control over a process or a serial port. GDB includes some 30-40 +different target vectors; however, each configuration of GDB includes +only a few of them. + +@section File Targets + +Both executables and core files have target vectors. + +@section Standard Protocol and 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. + +@section ROM Monitor Interface + +@section Custom Protocols + +@section Transport Layer + +@section Builtin Simulator + + +@node Native Debugging + +@chapter Native Debugging + +Several files control GDB's configuration for native support: + +@table @file + +@item gdb/config/@var{arch}/@var{xyz}.mh +Specifies Makefile fragments needed when hosting @emph{or native} on +machine @var{xyz}. 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{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.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{xyz}.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. + +@item gdb/@var{xyz}-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 + +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{xyz}.h} file. If these routines work for +the @var{xyz} 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{xyz}-nat.c}, and put @code{@var{xyz}-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. + +@end table + +@section Native core file Support + +@table @file + +@item core-aout.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{core-aout.c}, and should +just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or +@code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}). + +@item core-aout.c::register_addr() +If your @code{nm-@var{xyz}.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{core-aout.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{xyz}-nat.c} file, and be sure @code{@var{xyz}-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{core-aout.c}; if not, it's in your @file{@var{xyz}-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. + +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. + +@section ptrace + +@section /proc + +@section win32 + +@section shared libraries + +@section 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 CHILD_PREPARE_TO_STORE +If the machine stores all registers at once in the child process, then +define this to ensure that all values are correct. This usually entails +a read from the child. + +[Note that this is incorrectly defined in @file{xm-@var{system}.h} files +currently.] + +@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 FILES_INFO_HOOK +(Only defined for Convex.) + +@item FP0_REGNUM +This macro is normally defined to be the number of the first floating +point register, if the machine has such registers. As such, it would +appear only in target-specific code. However, /proc support uses this +to decide whether floats are in use on this target. + +@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 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 ONE_PROCESS_WRITETEXT +Define this to be able to, when a breakpoint insertion fails, warn the +user that another process may be running with the same executable. + +@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''. + +@item SHELL_COMMAND_CONCAT +If defined, is a string to prefix on the shell command used to start the +inferior. + +@item SHELL_FILE +If defined, this is the name of the shell to use to run the inferior. +Defaults to @code{"/bin/sh"}. + +@item SOLIB_ADD (filename, from_tty, targ) +Define this to expand into an expression that will cause the symbols in +@var{filename} to be added to GDB's symbol table. + +@item SOLIB_CREATE_INFERIOR_HOOK +Define this to expand into any shared-library-relocation code that you +want to be run just after the child process has been forked. + +@item START_INFERIOR_TRAPS_EXPECTED +When starting an inferior, GDB normally expects to trap twice; once when +the shell execs, and once when the program itself execs. If the actual +number of traps is something other than 2, then define this macro to +expand into the number expected. + +@item SVR4_SHARED_LIBS +Define this to indicate that SVR4-style shared libraries are in use. + +@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. + +@item CLEAR_SOLIB +objfiles.c + +@item DEBUG_PTRACE +Define this to debug ptrace calls. + +@end table + + +@node Support Libraries + +@chapter Support Libraries + +@section BFD + +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 + +@section opcodes + +The opcodes library provides GDB's disassembler. (It's a separate +library because it's also used in binutils, for @file{objdump}). + +@section readline + +@section mmalloc + +@section libiberty + +@section gnu-regex + +Regex conditionals. + +@table @code + +@item C_ALLOCA + +@item NFAILURES + +@item RE_NREGS + +@item SIGN_EXTEND_CHAR + +@item SWITCH_ENUM_BUG + +@item SYNTAX_TABLE + +@item Sword + +@item sparc + +@end table + +@section include + +@node Coding + +@chapter Coding + +This chapter covers topics that are lower-level than the major +algorithms of GDB. + +@section 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). + +@section 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. + +@section GDB Coding Standards + +GDB follows the GNU coding standards, as described in +@file{etc/standards.texi}. This file is also available for anonymous +FTP from GNU archive sites. GDB takes a strict interpretation of the +standard; in general, when the GNU standard recommends a practice but +does not require it, GDB requires it. + +GDB follows an additional set of coding standards specific to GDB, +as described in the following sections. + +You can configure with @samp{--enable-build-warnings} to get GCC to +check on a number of these rules. GDB sources ought not to engender any +complaints, unless they are caused by bogus host systems. (The exact +set of enabled warnings is currently @samp{-Wall -Wpointer-arith +-Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations}. + +@subsection Formatting + +The standard GNU recommendations for formatting must be followed +strictly. + +Note that while in a definition, the function's name must be in column +zero; in a function declaration, the name must be on the same line as +the return type. + +In addition, there must be a space between a function or macro name and +the opening parenthesis of its argument list (except for macro +definitions, as required by C). There must not be a space after an open +paren/bracket or before a close paren/bracket. + +While additional whitespace is generally helpful for reading, do not use +more than one blank line to separate blocks, and avoid adding whitespace +after the end of a program line (as of 1/99, some 600 lines had whitespace +after the semicolon). Excess whitespace causes difficulties for diff and +patch. + +@subsection Comments + +The standard GNU requirements on comments must be followed strictly. + +Block comments must appear in the following form, with no `/*'- or +'*/'-only lines, and no leading `*': + +@example @code +/* Wait for control to return from inferior to debugger. If inferior + gets a signal, we may decide to start it up again instead of + returning. That is why there is a loop in this function. When + this function actually returns it means the inferior should be left + stopped and GDB should read more commands. */ +@end example + +(Note that this format is encouraged by Emacs; tabbing for a multi-line +comment works correctly, and M-Q fills the block consistently.) + +Put a blank line between the block comments preceding function or +variable definitions, and the definition itself. + +In general, put function-body comments on lines by themselves, rather +than trying to fit them into the 20 characters left at the end of a +line, since either the comment or the code will inevitably get longer +than will fit, and then somebody will have to move it anyhow. + +@subsection C Usage + +Code must not 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. + +Use functions freely. There are only a handful of compute-bound areas +in GDB that might be affected by the overhead of a function call, mainly +in symbol reading. Most of GDB's performance is limited by the target +interface (whether serial line or system call). + +However, use functions with moderation. A thousand one-line functions +are just as hard to understand as a single thousand-line function. + +@subsection Function Prototypes + +Prototypes must be used to @emph{declare} functions but never to +@emph{define} them. Prototypes for GDB functions must include both the +argument type and name, with the name matching that used in the actual +function definition. + +For the sake of compatibility with pre-ANSI compilers, define prototypes +with the @code{PARAMS} macro: + +@example @code +extern int memory_remove_breakpoint PARAMS ((CORE_ADDR addr, + char *contents_cache)); +@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 +extern 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, except for @code{_initialize_*} +functions, which must be external so that @file{init.c} construction +works, but shouldn't be visible to random source files. + +All static functions must be declared in a block near the top of the +source file. + +@subsection 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. + +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}. + +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. + +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. + +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. + +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. + +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. + + +@node Porting GDB + +@chapter Porting GDB + +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{xyz} (e.g. +@samp{sun4}), and its full three-part configuration name is +@code{@var{arch}-@var{xvend}-@var{xos}} (e.g. @samp{sparc-sun-sunos4}). +In particular: + +In the top level directory, edit @file{config.sub} and add @var{arch}, +@var{xvend}, and @var{xos} to the lists of supported architectures, +vendors, and operating systems near the bottom of the file. Also, add +@var{xyz} as an alias that maps to +@code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by +running + +@example +./config.sub @var{xyz} +@end example +@noindent +and +@example +./config.sub @code{@var{arch}-@var{xvend}-@var{xos}} +@end example +@noindent +which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}} +and no error messages. + +You need to port BFD, if that hasn't been done already. Porting BFD is +beyond the scope of this manual. + +To configure GDB itself, edit @file{gdb/configure.host} to recognize +your system and set @code{gdb_host} to @var{xyz}, and (unless your +desired target is already available) also edit @file{gdb/configure.tgt}, +setting @code{gdb_target} to something appropriate (for instance, +@var{xyz}). + +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. + +@section 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.gz +@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 +been configured, you can just do @code{make gdb.tar.gz} 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 Hints + +@chapter Hints + +Check the @file{README} file, it often has useful information that does not +appear anywhere else in the directory. + +@menu +* Getting Started:: Getting started working on GDB +* Debugging GDB:: Debugging GDB with itself +@end menu + +@node Getting Started,,, Hints + +@section Getting Started + +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. + +This manual, the GDB Internals manual, has information which applies +generally to many parts of GDB. + +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. 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 documents all the available macros. +@c (@pxref{Host Conditionals}, @pxref{Target +@c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete +@c Conditionals}) + +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. + +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. + +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. + +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}. + +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. + +@node Debugging GDB,,,Hints + +@section 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. + +@section 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 GDB maintainers will only install ``cleanly designed'' patches. You +may not always agree on what is clean design. +@c @pxref{Coding Style}, @pxref{Clean Design}. + +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. + +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 directly to the GDB maintainers at +@code{gdb-patches@@cygnus.com}. + +@section 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! + +@item PYRAMID_CONTROL_FRAME_DEBUGGING +pyr-xdep.c +@item PYRAMID_CORE +pyr-xdep.c +@item PYRAMID_PTRACE +pyr-xdep.c + +@item REG_STACK_SEGMENT +exec.c + +@end table + + +@contents +@bye |