2 @setfilename gdbint.info
7 * Gdb-Internals: (gdbint). The GNU debugger's internals.
13 This file documents the internals of the GNU debugger GDB.
15 Copyright 1990-1999 Free Software Foundation, Inc.
16 Contributed by Cygnus Solutions. Written by John Gilmore.
17 Second Edition by Stan Shebs.
19 Permission is granted to make and distribute verbatim copies of this
20 manual provided the copyright notice and this permission notice are
21 preserved on all copies.
24 Permission is granted to process this file through Tex and print the
25 results, provided the printed document carries copying permission notice
26 identical to this one except for the removal of this paragraph (this
27 paragraph not being relevant to the printed manual).
30 Permission is granted to copy or distribute modified versions of this
31 manual under the terms of the GPL (for which purpose this text may be
32 regarded as a program in the language TeX).
35 @setchapternewpage off
36 @settitle GDB Internals
40 @subtitle{A guide to the internals of the GNU debugger}
42 @author Cygnus Solutions
43 @author Second Edition:
45 @author Cygnus Solutions
48 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
49 \xdef\manvers{\$Revision$} % For use in headers, footers too
51 \hfill Cygnus Solutions\par
53 \hfill \TeX{}info \texinfoversion\par
57 @vskip 0pt plus 1filll
58 Copyright @copyright{} 1990-1999 Free Software Foundation, Inc.
60 Permission is granted to make and distribute verbatim copies of
61 this manual provided the copyright notice and this permission notice
62 are preserved on all copies.
67 @c Perhaps this should be the title of the document (but only for info,
68 @c not for TeX). Existing GNU manuals seem inconsistent on this point.
69 @top Scope of this Document
71 This document documents the internals of the GNU debugger, GDB. It
72 includes description of GDB's key algorithms and operations, as well
73 as the mechanisms that adapt GDB to specific hosts and targets.
83 * Target Architecture Definition::
84 * Target Vector Definition::
97 Before diving into the internals, you should understand the formal
98 requirements and other expectations for GDB. Although some of these may
99 seem obvious, there have been proposals for GDB that have run counter to
102 First of all, GDB is a debugger. It's not designed to be a front panel
103 for embedded systems. It's not a text editor. It's not a shell. It's
104 not a programming environment.
106 GDB is an interactive tool. Although a batch mode is available, GDB's
107 primary role is to interact with a human programmer.
109 GDB should be responsive to the user. A programmer hot on the trail of
110 a nasty bug, and operating under a looming deadline, is going to be very
111 impatient of everything, including the response time to debugger
114 GDB should be relatively permissive, such as for expressions. While the
115 compiler should be picky (or have the option to be made picky), since
116 source code lives for a long time usually, the programmer doing
117 debugging shouldn't be spending time figuring out to mollify the
120 GDB will be called upon to deal with really large programs. Executable
121 sizes of 50 to 100 megabytes occur regularly, and we've heard reports of
122 programs approaching 1 gigabyte in size.
124 GDB should be able to run everywhere. No other debugger is available
125 for even half as many configurations as GDB supports.
128 @node Overall Structure
130 @chapter Overall Structure
132 GDB consists of three major subsystems: user interface, symbol handling
133 (the ``symbol side''), and target system handling (the ``target side'').
135 Ther user interface consists of several actual interfaces, plus
138 The symbol side consists of object file readers, debugging info
139 interpreters, symbol table management, source language expression
140 parsing, type and value printing.
142 The target side consists of execution control, stack frame analysis, and
143 physical target manipulation.
145 The target side/symbol side division is not formal, and there are a
146 number of exceptions. For instance, core file support involves symbolic
147 elements (the basic core file reader is in BFD) and target elements (it
148 supplies the contents of memory and the values of registers). Instead,
149 this division is useful for understanding how the minor subsystems
152 @section The Symbol Side
154 The symbolic side of GDB can be thought of as ``everything you can do in
155 GDB without having a live program running''. For instance, you can look
156 at the types of variables, and evaluate many kinds of expressions.
158 @section The Target Side
160 The target side of GDB is the ``bits and bytes manipulator''. Although
161 it may make reference to symbolic info here and there, most of the
162 target side will run with only a stripped executable available -- or
163 even no executable at all, in remote debugging cases.
165 Operations such as disassembly, stack frame crawls, and register
166 display, are able to work with no symbolic info at all. In some cases,
167 such as disassembly, GDB will use symbolic info to present addresses
168 relative to symbols rather than as raw numbers, but it will work either
171 @section Configurations
173 @dfn{Host} refers to attributes of the system where GDB runs.
174 @dfn{Target} refers to the system where the program being debugged
175 executes. In most cases they are the same machine, in which case a
176 third type of @dfn{Native} attributes come into play.
178 Defines and include files needed to build on the host are host support.
179 Examples are tty support, system defined types, host byte order, host
182 Defines and information needed to handle the target format are target
183 dependent. Examples are the stack frame format, instruction set,
184 breakpoint instruction, registers, and how to set up and tear down the stack
187 Information that is only needed when the host and target are the same,
188 is native dependent. One example is Unix child process support; if the
189 host and target are not the same, doing a fork to start the target
190 process is a bad idea. The various macros needed for finding the
191 registers in the @code{upage}, running @code{ptrace}, and such are all
192 in the native-dependent files.
194 Another example of native-dependent code is support for features that
195 are really part of the target environment, but which require
196 @code{#include} files that are only available on the host system. Core
197 file handling and @code{setjmp} handling are two common cases.
199 When you want to make GDB work ``native'' on a particular machine, you
200 have to include all three kinds of information.
207 GDB uses a number of debugging-specific algorithms. They are often not
208 very complicated, but get lost in the thicket of special cases and
209 real-world issues. This chapter describes the basic algorithms and
210 mentions some of the specific target definitions that they use.
214 A frame is a construct that GDB uses to keep track of calling and called
217 @code{FRAME_FP} in the machine description has no meaning to the
218 machine-independent part of GDB, except that it is used when setting up
219 a new frame from scratch, as follows:
222 create_new_frame (read_register (FP_REGNUM), read_pc ()));
225 Other than that, all the meaning imparted to @code{FP_REGNUM} is
226 imparted by the machine-dependent code. So, @code{FP_REGNUM} can have
227 any value that is convenient for the code that creates new frames.
228 (@code{create_new_frame} calls @code{INIT_EXTRA_FRAME_INFO} if it is
229 defined; that is where you should use the @code{FP_REGNUM} value, if
230 your frames are nonstandard.)
232 Given a GDB frame, define @code{FRAME_CHAIN} to determine the address of
233 the calling function's frame. This will be used to create a new GDB
234 frame struct, and then @code{INIT_EXTRA_FRAME_INFO} and
235 @code{INIT_FRAME_PC} will be called for the new frame.
237 @section Breakpoint Handling
239 In general, a breakpoint is a user-designated location in the program
240 where the user wants to regain control if program execution ever reaches
243 There are two main ways to implement breakpoints; either as ``hardware''
244 breakpoints or as ``software'' breakpoints.
246 Hardware breakpoints are sometimes available as a builtin debugging
247 features with some chips. Typically these work by having dedicated
248 register into which the breakpoint address may be stored. If the PC
249 ever matches a value in a breakpoint registers, the CPU raises an
250 exception and reports it to GDB. Another possibility is when an
251 emulator is in use; many emulators include circuitry that watches the
252 address lines coming out from the processor, and force it to stop if the
253 address matches a breakpoint's address. A third possibility is that the
254 target already has the ability to do breakpoints somehow; for instance,
255 a ROM monitor may do its own software breakpoints. So although these
256 are not literally ``hardware breakpoints'', from GDB's point of view
257 they work the same; GDB need not do nothing more than set the breakpoint
258 and wait for something to happen.
260 Since they depend on hardware resources, hardware breakpoints may be
261 limited in number; when the user asks for more, GDB will start trying to
262 set software breakpoints.
264 Software breakpoints require GDB to do somewhat more work. The basic
265 theory is that GDB will replace a program instruction with a trap,
266 illegal divide, or some other instruction that will cause an exception,
267 and then when it's encountered, GDB will take the exception and stop the
268 program. When the user says to continue, GDB will restore the original
269 instruction, single-step, re-insert the trap, and continue on.
271 Since it literally overwrites the program being tested, the program area
272 must be writeable, so this technique won't work on programs in ROM. It
273 can also distort the behavior of programs that examine themselves,
274 although the situation would be highly unusual.
276 Also, the software breakpoint instruction should be the smallest size of
277 instruction, so it doesn't overwrite an instruction that might be a jump
278 target, and cause disaster when the program jumps into the middle of the
279 breakpoint instruction. (Strictly speaking, the breakpoint must be no
280 larger than the smallest interval between instructions that may be jump
281 targets; perhaps there is an architecture where only even-numbered
282 instructions may jumped to.) Note that it's possible for an instruction
283 set not to have any instructions usable for a software breakpoint,
284 although in practice only the ARC has failed to define such an
287 The basic definition of the software breakpoint is the macro
290 Basic breakpoint object handling is in @file{breakpoint.c}. However,
291 much of the interesting breakpoint action is in @file{infrun.c}.
293 @section Single Stepping
295 @section Signal Handling
297 @section Thread Handling
299 @section Inferior Function Calls
301 @section Longjmp Support
303 GDB has support for figuring out that the target is doing a
304 @code{longjmp} and for stopping at the target of the jump, if we are
305 stepping. This is done with a few specialized internal breakpoints,
306 which are visible in the @code{maint info breakpoint} command.
308 To make this work, you need to define a macro called
309 @code{GET_LONGJMP_TARGET}, which will examine the @code{jmp_buf}
310 structure and extract the longjmp target address. Since @code{jmp_buf}
311 is target specific, you will need to define it in the appropriate
312 @file{tm-@var{xyz}.h} file. Look in @file{tm-sun4os4.h} and
313 @file{sparc-tdep.c} for examples of how to do this.
317 @chapter User Interface
319 GDB has several user interfaces. Although the command-line interface
320 is the most common and most familiar, there are others.
322 @section Command Interpreter
324 The command interpreter in GDB is fairly simple. It is designed to
325 allow for the set of commands to be augmented dynamically, and also
326 has a recursive subcommand capability, where the first argument to
327 a command may itself direct a lookup on a different command list.
329 For instance, the @code{set} command just starts a lookup on the
330 @code{setlist} command list, while @code{set thread} recurses
331 to the @code{set_thread_cmd_list}.
333 To add commands in general, use @code{add_cmd}. @code{add_com} adds to
334 the main command list, and should be used for those commands. The usual
335 place to add commands is in the @code{_initialize_@var{xyz}} routines at the
336 ends of most source files.
338 @section Console Printing
344 @code{libgdb} was an abortive project of years ago. The theory was to
345 provide an API to GDB's functionality.
347 @node Symbol Handling
349 @chapter Symbol Handling
351 Symbols are a key part of GDB's operation. Symbols include variables,
352 functions, and types.
354 @section Symbol Reading
356 GDB reads symbols from ``symbol files''. The usual symbol file is the
357 file containing the program which GDB is debugging. GDB can be directed
358 to use a different file for symbols (with the @code{symbol-file}
359 command), and it can also read more symbols via the ``add-file'' and
360 ``load'' commands, or while reading symbols from shared libraries.
362 Symbol files are initially opened by code in @file{symfile.c} using the
363 BFD library. BFD identifies the type of the file by examining its
364 header. @code{find_sym_fns} then uses this identification to locate a
365 set of symbol-reading functions.
367 Symbol reading modules identify themselves to GDB by calling
368 @code{add_symtab_fns} during their module initialization. The argument
369 to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the
370 name (or name prefix) of the symbol format, the length of the prefix,
371 and pointers to four functions. These functions are called at various
372 times to process symbol-files whose identification matches the specified
375 The functions supplied by each module are:
378 @item @var{xyz}_symfile_init(struct sym_fns *sf)
380 Called from @code{symbol_file_add} when we are about to read a new
381 symbol file. This function should clean up any internal state (possibly
382 resulting from half-read previous files, for example) and prepare to
383 read a new symbol file. Note that the symbol file which we are reading
384 might be a new "main" symbol file, or might be a secondary symbol file
385 whose symbols are being added to the existing symbol table.
387 The argument to @code{@var{xyz}_symfile_init} is a newly allocated
388 @code{struct sym_fns} whose @code{bfd} field contains the BFD for the
389 new symbol file being read. Its @code{private} field has been zeroed,
390 and can be modified as desired. Typically, a struct of private
391 information will be @code{malloc}'d, and a pointer to it will be placed
392 in the @code{private} field.
394 There is no result from @code{@var{xyz}_symfile_init}, but it can call
395 @code{error} if it detects an unavoidable problem.
397 @item @var{xyz}_new_init()
399 Called from @code{symbol_file_add} when discarding existing symbols.
400 This function need only handle the symbol-reading module's internal
401 state; the symbol table data structures visible to the rest of GDB will
402 be discarded by @code{symbol_file_add}. It has no arguments and no
403 result. It may be called after @code{@var{xyz}_symfile_init}, if a new
404 symbol table is being read, or may be called alone if all symbols are
405 simply being discarded.
407 @item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)
409 Called from @code{symbol_file_add} to actually read the symbols from a
410 symbol-file into a set of psymtabs or symtabs.
412 @code{sf} points to the struct sym_fns originally passed to
413 @code{@var{xyz}_sym_init} for possible initialization. @code{addr} is
414 the offset between the file's specified start address and its true
415 address in memory. @code{mainline} is 1 if this is the main symbol
416 table being read, and 0 if a secondary symbol file (e.g. shared library
417 or dynamically loaded file) is being read.@refill
420 In addition, if a symbol-reading module creates psymtabs when
421 @var{xyz}_symfile_read is called, these psymtabs will contain a pointer
422 to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called
423 from any point in the GDB symbol-handling code.
426 @item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst)
428 Called from @code{psymtab_to_symtab} (or the PSYMTAB_TO_SYMTAB macro) if
429 the psymtab has not already been read in and had its @code{pst->symtab}
430 pointer set. The argument is the psymtab to be fleshed-out into a
431 symtab. Upon return, pst->readin should have been set to 1, and
432 pst->symtab should contain a pointer to the new corresponding symtab, or
433 zero if there were no symbols in that part of the symbol file.
436 @section Partial Symbol Tables
438 GDB has three types of symbol tables.
442 @item full symbol tables (symtabs). These contain the main information
443 about symbols and addresses.
445 @item partial symbol tables (psymtabs). These contain enough
446 information to know when to read the corresponding part of the full
449 @item minimal symbol tables (msymtabs). These contain information
450 gleaned from non-debugging symbols.
454 This section describes partial symbol tables.
456 A psymtab is constructed by doing a very quick pass over an executable
457 file's debugging information. Small amounts of information are
458 extracted -- enough to identify which parts of the symbol table will
459 need to be re-read and fully digested later, when the user needs the
460 information. The speed of this pass causes GDB to start up very
461 quickly. Later, as the detailed rereading occurs, it occurs in small
462 pieces, at various times, and the delay therefrom is mostly invisible to
464 @c (@xref{Symbol Reading}.)
466 The symbols that show up in a file's psymtab should be, roughly, those
467 visible to the debugger's user when the program is not running code from
468 that file. These include external symbols and types, static symbols and
469 types, and enum values declared at file scope.
471 The psymtab also contains the range of instruction addresses that the
472 full symbol table would represent.
474 The idea is that there are only two ways for the user (or much of the
475 code in the debugger) to reference a symbol:
480 (e.g. execution stops at some address which is inside a function in this
481 file). The address will be noticed to be in the range of this psymtab,
482 and the full symtab will be read in. @code{find_pc_function},
483 @code{find_pc_line}, and other @code{find_pc_@dots{}} functions handle
487 (e.g. the user asks to print a variable, or set a breakpoint on a
488 function). Global names and file-scope names will be found in the
489 psymtab, which will cause the symtab to be pulled in. Local names will
490 have to be qualified by a global name, or a file-scope name, in which
491 case we will have already read in the symtab as we evaluated the
492 qualifier. Or, a local symbol can be referenced when we are "in" a
493 local scope, in which case the first case applies. @code{lookup_symbol}
494 does most of the work here.
498 The only reason that psymtabs exist is to cause a symtab to be read in
499 at the right moment. Any symbol that can be elided from a psymtab,
500 while still causing that to happen, should not appear in it. Since
501 psymtabs don't have the idea of scope, you can't put local symbols in
502 them anyway. Psymtabs don't have the idea of the type of a symbol,
503 either, so types need not appear, unless they will be referenced by
506 It is a bug for GDB to behave one way when only a psymtab has been read,
507 and another way if the corresponding symtab has been read in. Such bugs
508 are typically caused by a psymtab that does not contain all the visible
509 symbols, or which has the wrong instruction address ranges.
511 The psymtab for a particular section of a symbol-file (objfile) could be
512 thrown away after the symtab has been read in. The symtab should always
513 be searched before the psymtab, so the psymtab will never be used (in a
514 bug-free environment). Currently, psymtabs are allocated on an obstack,
515 and all the psymbols themselves are allocated in a pair of large arrays
516 on an obstack, so there is little to be gained by trying to free them
517 unless you want to do a lot more work.
521 Fundamental Types (e.g., FT_VOID, FT_BOOLEAN).
523 These are the fundamental types that GDB uses internally. Fundamental
524 types from the various debugging formats (stabs, ELF, etc) are mapped
525 into one of these. They are basically a union of all fundamental types
526 that gdb knows about for all the languages that GDB knows about.
528 Type Codes (e.g., TYPE_CODE_PTR, TYPE_CODE_ARRAY).
530 Each time GDB builds an internal type, it marks it with one of these
531 types. The type may be a fundamental type, such as TYPE_CODE_INT, or a
532 derived type, such as TYPE_CODE_PTR which is a pointer to another type.
533 Typically, several FT_* types map to one TYPE_CODE_* type, and are
534 distinguished by other members of the type struct, such as whether the
535 type is signed or unsigned, and how many bits it uses.
537 Builtin Types (e.g., builtin_type_void, builtin_type_char).
539 These are instances of type structs that roughly correspond to
540 fundamental types and are created as global types for GDB to use for
541 various ugly historical reasons. We eventually want to eliminate these.
542 Note for example that builtin_type_int initialized in gdbtypes.c is
543 basically the same as a TYPE_CODE_INT type that is initialized in
544 c-lang.c for an FT_INTEGER fundamental type. The difference is that the
545 builtin_type is not associated with any particular objfile, and only one
546 instance exists, while c-lang.c builds as many TYPE_CODE_INT types as
547 needed, with each one associated with some particular objfile.
549 @section Object File Formats
553 The @file{a.out} format is the original file format for Unix. It
554 consists of three sections: text, data, and bss, which are for program
555 code, initialized data, and uninitialized data, respectively.
557 The @file{a.out} format is so simple that it doesn't have any reserved
558 place for debugging information. (Hey, the original Unix hackers used
559 @file{adb}, which is a machine-language debugger.) The only debugging
560 format for @file{a.out} is stabs, which is encoded as a set of normal
561 symbols with distinctive attributes.
563 The basic @file{a.out} reader is in @file{dbxread.c}.
567 The COFF format was introduced with System V Release 3 (SVR3) Unix.
568 COFF files may have multiple sections, each prefixed by a header. The
569 number of sections is limited.
571 The COFF specification includes support for debugging. Although this
572 was a step forward, the debugging information was woefully limited. For
573 instance, it was not possible to represent code that came from an
576 The COFF reader is in @file{coffread.c}.
580 ECOFF is an extended COFF originally introduced for Mips and Alpha
583 The basic ECOFF reader is in @file{mipsread.c}.
587 The IBM RS/6000 running AIX uses an object file format called XCOFF.
588 The COFF sections, symbols, and line numbers are used, but debugging
589 symbols are dbx-style stabs whose strings are located in the
590 @samp{.debug} section (rather than the string table). For more
591 information, see @xref{Top,,,stabs,The Stabs Debugging Format}.
593 The shared library scheme has a clean interface for figuring out what
594 shared libraries are in use, but the catch is that everything which
595 refers to addresses (symbol tables and breakpoints at least) needs to be
596 relocated for both shared libraries and the main executable. At least
597 using the standard mechanism this can only be done once the program has
598 been run (or the core file has been read).
602 Windows 95 and NT use the PE (Portable Executable) format for their
603 executables. PE is basically COFF with additional headers.
605 While BFD includes special PE support, GDB needs only the basic
610 The ELF format came with System V Release 4 (SVR4) Unix. ELF is similar
611 to COFF in being organized into a number of sections, but it removes
612 many of COFF's limitations.
614 The basic ELF reader is in @file{elfread.c}.
618 SOM is HP's object file and debug format (not to be confused with IBM's
619 SOM, which is a cross-language ABI).
621 The SOM reader is in @file{hpread.c}.
623 @subsection Other File Formats
625 Other file formats that have been supported by GDB include Netware
626 Loadable Modules (@file{nlmread.c}.
628 @section Debugging File Formats
630 This section describes characteristics of debugging information that
631 are independent of the object file format.
635 @code{stabs} started out as special symbols within the @code{a.out}
636 format. Since then, it has been encapsulated into other file
637 formats, such as COFF and ELF.
639 While @file{dbxread.c} does some of the basic stab processing,
640 including for encapsulated versions, @file{stabsread.c} does
645 The basic COFF definition includes debugging information. The level
646 of support is minimal and non-extensible, and is not often used.
648 @subsection Mips debug (Third Eye)
650 ECOFF includes a definition of a special debug format.
652 The file @file{mdebugread.c} implements reading for this format.
656 DWARF 1 is a debugging format that was originally designed to be
657 used with ELF in SVR4 systems.
663 @c If defined, these are the producer strings in a DWARF 1 file. All of
664 @c these have reasonable defaults already.
666 The DWARF 1 reader is in @file{dwarfread.c}.
670 DWARF 2 is an improved but incompatible version of DWARF 1.
672 The DWARF 2 reader is in @file{dwarf2read.c}.
676 Like COFF, the SOM definition includes debugging information.
678 @section Adding a New Symbol Reader to GDB
680 If you are using an existing object file format (a.out, COFF, ELF, etc),
681 there is probably little to be done.
683 If you need to add a new object file format, you must first add it to
684 BFD. This is beyond the scope of this document.
686 You must then arrange for the BFD code to provide access to the
687 debugging symbols. Generally GDB will have to call swapping routines
688 from BFD and a few other BFD internal routines to locate the debugging
689 information. As much as possible, GDB should not depend on the BFD
690 internal data structures.
692 For some targets (e.g., COFF), there is a special transfer vector used
693 to call swapping routines, since the external data structures on various
694 platforms have different sizes and layouts. Specialized routines that
695 will only ever be implemented by one object file format may be called
696 directly. This interface should be described in a file
697 @file{bfd/libxyz.h}, which is included by GDB.
700 @node Language Support
702 @chapter Language Support
704 GDB's language support is mainly driven by the symbol reader, although
705 it is possible for the user to set the source language manually.
707 GDB chooses the source language by looking at the extension of the file
708 recorded in the debug info; @code{.c} means C, @code{.f} means Fortran,
709 etc. It may also use a special-purpose language identifier if the debug
710 format supports it, such as DWARF.
712 @section Adding a Source Language to GDB
714 To add other languages to GDB's expression parser, follow the following
718 @item Create the expression parser.
720 This should reside in a file @file{@var{lang}-exp.y}. Routines for
721 building parsed expressions into a @samp{union exp_element} list are in
724 Since we can't depend upon everyone having Bison, and YACC produces
725 parsers that define a bunch of global names, the following lines
726 @emph{must} be included at the top of the YACC parser, to prevent the
727 various parsers from defining the same global names:
730 #define yyparse @var{lang}_parse
731 #define yylex @var{lang}_lex
732 #define yyerror @var{lang}_error
733 #define yylval @var{lang}_lval
734 #define yychar @var{lang}_char
735 #define yydebug @var{lang}_debug
736 #define yypact @var{lang}_pact
737 #define yyr1 @var{lang}_r1
738 #define yyr2 @var{lang}_r2
739 #define yydef @var{lang}_def
740 #define yychk @var{lang}_chk
741 #define yypgo @var{lang}_pgo
742 #define yyact @var{lang}_act
743 #define yyexca @var{lang}_exca
744 #define yyerrflag @var{lang}_errflag
745 #define yynerrs @var{lang}_nerrs
748 At the bottom of your parser, define a @code{struct language_defn} and
749 initialize it with the right values for your language. Define an
750 @code{initialize_@var{lang}} routine and have it call
751 @samp{add_language(@var{lang}_language_defn)} to tell the rest of GDB
752 that your language exists. You'll need some other supporting variables
753 and functions, which will be used via pointers from your
754 @code{@var{lang}_language_defn}. See the declaration of @code{struct
755 language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
756 for more information.
758 @item Add any evaluation routines, if necessary
760 If you need new opcodes (that represent the operations of the language),
761 add them to the enumerated type in @file{expression.h}. Add support
762 code for these operations in @code{eval.c:evaluate_subexp()}. Add cases
763 for new opcodes in two functions from @file{parse.c}:
764 @code{prefixify_subexp()} and @code{length_of_subexp()}. These compute
765 the number of @code{exp_element}s that a given operation takes up.
767 @item Update some existing code
769 Add an enumerated identifier for your language to the enumerated type
770 @code{enum language} in @file{defs.h}.
772 Update the routines in @file{language.c} so your language is included.
773 These routines include type predicates and such, which (in some cases)
774 are language dependent. If your language does not appear in the switch
775 statement, an error is reported.
777 Also included in @file{language.c} is the code that updates the variable
778 @code{current_language}, and the routines that translate the
779 @code{language_@var{lang}} enumerated identifier into a printable
782 Update the function @code{_initialize_language} to include your
783 language. This function picks the default language upon startup, so is
784 dependent upon which languages that GDB is built for.
786 Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
787 code so that the language of each symtab (source file) is set properly.
788 This is used to determine the language to use at each stack frame level.
789 Currently, the language is set based upon the extension of the source
790 file. If the language can be better inferred from the symbol
791 information, please set the language of the symtab in the symbol-reading
794 Add helper code to @code{expprint.c:print_subexp()} to handle any new
795 expression opcodes you have added to @file{expression.h}. Also, add the
796 printed representations of your operators to @code{op_print_tab}.
798 @item Add a place of call
800 Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
801 @code{parse.c:parse_exp_1()}.
803 @item Use macros to trim code
805 The user has the option of building GDB for some or all of the
806 languages. If the user decides to build GDB for the language
807 @var{lang}, then every file dependent on @file{language.h} will have the
808 macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to
809 leave out large routines that the user won't need if he or she is not
812 Note that you do not need to do this in your YACC parser, since if GDB
813 is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
814 compiled form of your parser) is not linked into GDB at all.
816 See the file @file{configure.in} for how GDB is configured for different
819 @item Edit @file{Makefile.in}
821 Add dependencies in @file{Makefile.in}. Make sure you update the macro
822 variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
823 not get linked in, or, worse yet, it may not get @code{tar}red into the
829 @node Host Definition
831 @chapter Host Definition
833 With the advent of autoconf, it's rarely necessary to have host
834 definition machinery anymore.
836 @section Adding a New Host
838 Most of GDB's host configuration support happens via autoconf. It
839 should be rare to need new host-specific definitions. GDB still uses
840 the host-specific definitions and files listed below, but these mostly
841 exist for historical reasons, and should eventually disappear.
843 Several files control GDB's configuration for host systems:
847 @item gdb/config/@var{arch}/@var{xyz}.mh
848 Specifies Makefile fragments needed when hosting on machine @var{xyz}.
849 In particular, this lists the required machine-dependent object files,
850 by defining @samp{XDEPFILES=@dots{}}. Also specifies the header file
851 which describes host @var{xyz}, by defining @code{XM_FILE=
852 xm-@var{xyz}.h}. You can also define @code{CC}, @code{SYSV_DEFINE},
853 @code{XM_CFLAGS}, @code{XM_ADD_FILES}, @code{XM_CLIBS}, @code{XM_CDEPS},
854 etc.; see @file{Makefile.in}.
856 @item gdb/config/@var{arch}/xm-@var{xyz}.h
857 (@file{xm.h} is a link to this file, created by configure). Contains C
858 macro definitions describing the host system environment, such as byte
859 order, host C compiler and library.
861 @item gdb/@var{xyz}-xdep.c
862 Contains any miscellaneous C code required for this machine as a host.
863 On most machines it doesn't exist at all. If it does exist, put
864 @file{@var{xyz}-xdep.o} into the @code{XDEPFILES} line in
865 @file{gdb/config/@var{arch}/@var{xyz}.mh}.
869 @subheading Generic Host Support Files
871 There are some ``generic'' versions of routines that can be used by
872 various systems. These can be customized in various ways by macros
873 defined in your @file{xm-@var{xyz}.h} file. If these routines work for
874 the @var{xyz} host, you can just include the generic file's name (with
875 @samp{.o}, not @samp{.c}) in @code{XDEPFILES}.
877 Otherwise, if your machine needs custom support routines, you will need
878 to write routines that perform the same functions as the generic file.
879 Put them into @code{@var{xyz}-xdep.c}, and put @code{@var{xyz}-xdep.o}
880 into @code{XDEPFILES}.
885 This contains serial line support for Unix systems. This is always
886 included, via the makefile variable @code{SER_HARDWIRE}; override this
887 variable in the @file{.mh} file to avoid it.
890 This contains serial line support for 32-bit programs running under DOS,
891 using the GO32 execution environment.
894 This contains generic TCP support using sockets.
898 @section Host Conditionals
900 When GDB is configured and compiled, various macros are defined or left
901 undefined, to control compilation based on the attributes of the host
902 system. These macros and their meanings (or if the meaning is not
903 documented here, then one of the source files where they are used is
908 @item GDBINIT_FILENAME
909 The default name of GDB's initialization file (normally @file{.gdbinit}).
911 @item MEM_FNS_DECLARED
912 Your host config file defines this if it includes declarations of
913 @code{memcpy} and @code{memset}. Define this to avoid conflicts between
914 the native include files and the declarations in @file{defs.h}.
917 This macro is deprecated.
920 Define this if your system does not have a @code{<sys/file.h>}.
922 @item SIGWINCH_HANDLER
923 If your host defines @code{SIGWINCH}, you can define this to be the name
924 of a function to be called if @code{SIGWINCH} is received.
926 @item SIGWINCH_HANDLER_BODY
927 Define this to expand into code that will define the function named by
928 the expansion of @code{SIGWINCH_HANDLER}.
930 @item ALIGN_STACK_ON_STARTUP
931 Define this if your system is of a sort that will crash in
932 @code{tgetent} if the stack happens not to be longword-aligned when
933 @code{main} is called. This is a rare situation, but is known to occur
934 on several different types of systems.
936 @item CRLF_SOURCE_FILES
937 Define this if host files use @code{\r\n} rather than @code{\n} as a
938 line terminator. This will cause source file listings to omit @code{\r}
939 characters when printing and it will allow \r\n line endings of files
940 which are "sourced" by gdb. It must be possible to open files in binary
941 mode using @code{O_BINARY} or, for fopen, @code{"rb"}.
944 The default value of the prompt string (normally @code{"(gdb) "}).
947 The name of the generic TTY device, defaults to @code{"/dev/tty"}.
949 @item FCLOSE_PROVIDED
950 Define this if the system declares @code{fclose} in the headers included
951 in @code{defs.h}. This isn't needed unless your compiler is unusually
955 Define this if binary files are opened the same way as text files.
957 @item GETENV_PROVIDED
958 Define this if the system declares @code{getenv} in its headers included
959 in @code{defs.h}. This isn't needed unless your compiler is unusually
963 In some cases, use the system call @code{mmap} for reading symbol
964 tables. For some machines this allows for sharing and quick updates.
966 @item HAVE_SIGSETMASK
967 Define this if the host system has job control, but does not define
968 @code{sigsetmask()}. Currently, this is only true of the RS/6000.
971 Define this if the host system has @code{termio.h}.
973 @item HOST_BYTE_ORDER
974 The ordering of bytes in the host. This must be defined to be either
975 @code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}.
982 Values for host-side constants.
985 Substitute for isatty, if not available.
988 This is the longest integer type available on the host. If not defined,
989 it will default to @code{long long} or @code{long}, depending on
990 @code{CC_HAS_LONG_LONG}.
992 @item CC_HAS_LONG_LONG
993 Define this if the host C compiler supports ``long long''. This is set
994 by the configure script.
996 @item PRINTF_HAS_LONG_LONG
997 Define this if the host can handle printing of long long integers via
998 the printf format directive ``ll''. This is set by the configure script.
1000 @item HAVE_LONG_DOUBLE
1001 Define this if the host C compiler supports ``long double''. This is
1002 set by the configure script.
1004 @item PRINTF_HAS_LONG_DOUBLE
1005 Define this if the host can handle printing of long double float-point
1006 numbers via the printf format directive ``Lg''. This is set by the
1009 @item SCANF_HAS_LONG_DOUBLE
1010 Define this if the host can handle the parsing of long double
1011 float-point numbers via the scanf format directive directive
1012 ``Lg''. This is set by the configure script.
1014 @item LSEEK_NOT_LINEAR
1015 Define this if @code{lseek (n)} does not necessarily move to byte number
1016 @code{n} in the file. This is only used when reading source files. It
1017 is normally faster to define @code{CRLF_SOURCE_FILES} when possible.
1020 This macro is used as the argument to lseek (or, most commonly,
1021 bfd_seek). FIXME, should be replaced by SEEK_SET instead, which is the
1024 @item MALLOC_INCOMPATIBLE
1025 Define this if the system's prototype for @code{malloc} differs from the
1026 @sc{ANSI} definition.
1028 @item MMAP_BASE_ADDRESS
1029 When using HAVE_MMAP, the first mapping should go at this address.
1031 @item MMAP_INCREMENT
1032 when using HAVE_MMAP, this is the increment between mappings.
1034 @item NEED_POSIX_SETPGID
1035 Define this to use the POSIX version of @code{setpgid} to determine
1036 whether job control is available.
1039 If defined, this should be one or more tokens, such as @code{volatile},
1040 that can be used in both the declaration and definition of functions to
1041 indicate that they never return. The default is already set correctly
1042 if compiling with GCC. This will almost never need to be defined.
1045 If defined, this should be one or more tokens, such as
1046 @code{__attribute__ ((noreturn))}, that can be used in the declarations
1047 of functions to indicate that they never return. The default is already
1048 set correctly if compiling with GCC. This will almost never need to be
1051 @item USE_GENERIC_DUMMY_FRAMES
1052 Define this to 1 if the target is using the generic inferior function
1053 call code. See @code{blockframe.c} for more information.
1056 GDB will use the @code{mmalloc} library for memory allocation for symbol
1057 reading if this symbol is defined. Be careful defining it since there
1058 are systems on which @code{mmalloc} does not work for some reason. One
1059 example is the DECstation, where its RPC library can't cope with our
1060 redefinition of @code{malloc} to call @code{mmalloc}. When defining
1061 @code{USE_MMALLOC}, you will also have to set @code{MMALLOC} in the
1062 Makefile, to point to the mmalloc library. This define is set when you
1063 configure with --with-mmalloc.
1066 Define this if you are using @code{mmalloc}, but don't want the overhead
1067 of checking the heap with @code{mmcheck}. Note that on some systems,
1068 the C runtime makes calls to malloc prior to calling @code{main}, and if
1069 @code{free} is ever called with these pointers after calling
1070 @code{mmcheck} to enable checking, a memory corruption abort is certain
1071 to occur. These systems can still use mmalloc, but must define
1075 Define this to 1 if the C runtime allocates memory prior to
1076 @code{mmcheck} being called, but that memory is never freed so we don't
1077 have to worry about it triggering a memory corruption abort. The
1078 default is 0, which means that @code{mmcheck} will only install the heap
1079 checking functions if there has not yet been any memory allocation
1080 calls, and if it fails to install the functions, gdb will issue a
1081 warning. This is currently defined if you configure using
1084 @item NO_SIGINTERRUPT
1085 Define this to indicate that siginterrupt() is not available.
1088 Define if this is not in a system .h file.
1092 Define these to appropriate value for the system lseek(), if not already
1096 This is the signal for stopping GDB. Defaults to SIGTSTP. (Only
1097 redefined for the Convex.)
1100 Define this if the interior's tty should be opened with the O_NOCTTY
1101 flag. (FIXME: This should be a native-only flag, but @file{inflow.c} is
1105 Means that System V (prior to SVR4) include files are in use. (FIXME:
1106 This symbol is abused in @file{infrun.c}, @file{regex.c},
1107 @file{remote-nindy.c}, and @file{utils.c} for other things, at the
1111 Define this to help placate lint in some situations.
1114 Define this to override the defaults of @code{__volatile__} or
1120 @node Target Architecture Definition
1122 @chapter Target Architecture Definition
1124 GDB's target architecture defines what sort of machine-language programs
1125 GDB can work with, and how it works with them.
1127 At present, the target architecture definition consists of a number of C
1130 @section Registers and Memory
1132 GDB's model of the target machine is rather simple. GDB assumes the
1133 machine includes a bank of registers and a block of memory. Each
1134 register may have a different size.
1136 GDB does not have a magical way to match up with the compiler's idea of
1137 which registers are which; however, it is critical that they do match up
1138 accurately. The only way to make this work is to get accurate
1139 information about the order that the compiler uses, and to reflect that
1140 in the @code{REGISTER_NAME} and related macros.
1142 GDB can handle big-endian, little-endian, and bi-endian architectures.
1144 @section Frame Interpretation
1146 @section Inferior Call Setup
1148 @section Compiler Characteristics
1150 @section Target Conditionals
1152 This section describes the macros that you can use to define the target
1157 @item ADDITIONAL_OPTIONS
1158 @item ADDITIONAL_OPTION_CASES
1159 @item ADDITIONAL_OPTION_HANDLER
1160 @item ADDITIONAL_OPTION_HELP
1161 These are a set of macros that allow the addition of additional command
1162 line options to GDB. They are currently used only for the unsupported
1163 i960 Nindy target, and should not be used in any other configuration.
1165 @item ADDR_BITS_REMOVE (addr)
1166 If a raw machine instruction address includes any bits that are not
1167 really part of the address, then define this macro to expand into an
1168 expression that zeros those bits in @var{addr}. This is only used for
1169 addresses of instructions, and even then not in all contexts.
1171 For example, the two low-order bits of the PC on the Hewlett-Packard PA
1172 2.0 architecture contain the privilege level of the corresponding
1173 instruction. Since instructions must always be aligned on four-byte
1174 boundaries, the processor masks out these bits to generate the actual
1175 address of the instruction. ADDR_BITS_REMOVE should filter out these
1176 bits with an expression such as @code{((addr) & ~3)}.
1178 @item BEFORE_MAIN_LOOP_HOOK
1179 Define this to expand into any code that you want to execute before the
1180 main loop starts. Although this is not, strictly speaking, a target
1181 conditional, that is how it is currently being used. Note that if a
1182 configuration were to define it one way for a host and a different way
1183 for the target, GDB will probably not compile, let alone run correctly.
1184 This is currently used only for the unsupported i960 Nindy target, and
1185 should not be used in any other configuration.
1187 @item BELIEVE_PCC_PROMOTION
1188 Define if the compiler promotes a short or char parameter to an int, but
1189 still reports the parameter as its original type, rather than the
1192 @item BELIEVE_PCC_PROMOTION_TYPE
1193 Define this if GDB should believe the type of a short argument when
1194 compiled by pcc, but look within a full int space to get its value.
1195 Only defined for Sun-3 at present.
1197 @item BITS_BIG_ENDIAN
1198 Define this if the numbering of bits in the targets does *not* match the
1199 endianness of the target byte order. A value of 1 means that the bits
1200 are numbered in a big-endian order, 0 means little-endian.
1203 This is the character array initializer for the bit pattern to put into
1204 memory where a breakpoint is set. Although it's common to use a trap
1205 instruction for a breakpoint, it's not required; for instance, the bit
1206 pattern could be an invalid instruction. The breakpoint must be no
1207 longer than the shortest instruction of the architecture.
1209 @var{BREAKPOINT} has been deprecated in favour of
1210 @var{BREAKPOINT_FROM_PC}.
1212 @item BIG_BREAKPOINT
1213 @item LITTLE_BREAKPOINT
1214 Similar to BREAKPOINT, but used for bi-endian targets.
1216 @var{BIG_BREAKPOINT} and @var{LITTLE_BREAKPOINT} have been deprecated in
1217 favour of @var{BREAKPOINT_FROM_PC}.
1219 @item REMOTE_BREAKPOINT
1220 @item LITTLE_REMOTE_BREAKPOINT
1221 @item BIG_REMOTE_BREAKPOINT
1222 Similar to BREAKPOINT, but used for remote targets.
1224 @var{BIG_REMOTE_BREAKPOINT} and @var{LITTLE_REMOTE_BREAKPOINT} have been
1225 deprecated in favour of @var{BREAKPOINT_FROM_PC}.
1227 @item BREAKPOINT_FROM_PC (pcptr, lenptr)
1229 Use the program counter to determine the contents and size of a
1230 breakpoint instruction. It returns a pointer to a string of bytes that
1231 encode a breakpoint instruction, stores the length of the string to
1232 *lenptr, and adjusts pc (if necessary) to point to the actual memory
1233 location where the breakpoint should be inserted.
1235 Although it is common to use a trap instruction for a breakpoint, it's
1236 not required; for instance, the bit pattern could be an invalid
1237 instruction. The breakpoint must be no longer than the shortest
1238 instruction of the architecture.
1240 Replaces all the other @var{BREAKPOINT} macros.
1243 A C expresson that is non-zero when the target suports inferior function
1246 @item CALL_DUMMY_WORDS
1247 Pointer to an array of @var{LONGEST} words of data containing
1248 host-byte-ordered @var{REGISTER_BYTES} sized values that partially
1249 specify the sequence of instructions needed for an inferior function
1252 Should be deprecated in favour of a macro that uses target-byte-ordered
1255 @item SIZEOF_CALL_DUMMY_WORDS
1256 The size of @var{CALL_DUMMY_WORDS}. When @var{CALL_DUMMY_P} this must
1257 return a positive value. See also @var{CALL_DUMMY_LENGTH}.
1260 A static initializer for @var{CALL_DUMMY_WORDS}. Deprecated.
1262 @item CALL_DUMMY_LOCATION
1265 @item CALL_DUMMY_STACK_ADJUST
1266 Stack adjustment needed when performing an inferior function call.
1268 Should be deprecated in favor of something like @var{STACK_ALIGN}.
1270 @item CALL_DUMMY_STACK_ADJUST_P
1271 Predicate for use of @var{CALL_DUMMY_STACK_ADJUST}.
1273 Should be deprecated in favor of something like @var{STACK_ALIGN}.
1275 @item CANNOT_FETCH_REGISTER (regno)
1276 A C expression that should be nonzero if @var{regno} cannot be fetched
1277 from an inferior process. This is only relevant if
1278 @code{FETCH_INFERIOR_REGISTERS} is not defined.
1280 @item CANNOT_STORE_REGISTER (regno)
1281 A C expression that should be nonzero if @var{regno} should not be
1282 written to the target. This is often the case for program counters,
1283 status words, and other special registers. If this is not defined, GDB
1284 will assume that all registers may be written.
1286 @item DO_DEFERRED_STORES
1287 @item CLEAR_DEFERRED_STORES
1288 Define this to execute any deferred stores of registers into the inferior,
1289 and to cancel any deferred stores.
1291 Currently only implemented correctly for native Sparc configurations?
1294 Define this to expand into the character that G++ uses to distinguish
1295 compiler-generated identifiers from programmer-specified identifiers.
1296 By default, this expands into @code{'$'}. Most System V targets should
1297 define this to @code{'.'}.
1299 @item DBX_PARM_SYMBOL_CLASS
1300 Hook for the @code{SYMBOL_CLASS} of a parameter when decoding DBX symbol
1301 information. In the i960, parameters can be stored as locals or as
1302 args, depending on the type of the debug record.
1304 @item DECR_PC_AFTER_BREAK
1305 Define this to be the amount by which to decrement the PC after the
1306 program encounters a breakpoint. This is often the number of bytes in
1307 BREAKPOINT, though not always. For most targets this value will be 0.
1309 @item DECR_PC_AFTER_HW_BREAK
1310 Similarly, for hardware breakpoints.
1312 @item DISABLE_UNSETTABLE_BREAK addr
1313 If defined, this should evaluate to 1 if @var{addr} is in a shared
1314 library in which breakpoints cannot be set and so should be disabled.
1316 @item DO_REGISTERS_INFO
1317 If defined, use this to print the value of a register or all registers.
1319 @item END_OF_TEXT_DEFAULT
1320 This is an expression that should designate the end of the text section
1323 @item EXTRACT_RETURN_VALUE(type,regbuf,valbuf)
1324 Define this to extract a function's return value of type @var{type} from
1325 the raw register state @var{regbuf} and copy that, in virtual format,
1328 @item EXTRACT_STRUCT_VALUE_ADDRESS(regbuf)
1329 When @var{EXTRACT_STRUCT_VALUE_ADDRESS_P} this is used to to extract
1330 from an array @var{regbuf} (containing the raw register state) the
1331 address in which a function should return its structure value, as a
1332 CORE_ADDR (or an expression that can be used as one).
1334 @item EXTRACT_STRUCT_VALUE_ADDRESS_P
1335 Predicate for @var{EXTRACT_STRUCT_VALUE_ADDRESS}.
1338 If defined, then the `info float' command will print information about
1339 the processor's floating point unit.
1342 If the virtual frame pointer is kept in a register, then define this
1343 macro to be the number (greater than or equal to zero) of that register.
1345 This should only need to be defined if @code{TARGET_READ_FP} and
1346 @code{TARGET_WRITE_FP} are not defined.
1348 @item FRAMELESS_FUNCTION_INVOCATION(fi)
1349 Define this to an expression that returns 1 if the function invocation
1350 represented by @var{fi} does not have a stack frame associated with it.
1353 @item FRAME_ARGS_ADDRESS_CORRECT
1356 @item FRAME_CHAIN(frame)
1357 Given @var{frame}, return a pointer to the calling frame.
1359 @item FRAME_CHAIN_COMBINE(chain,frame)
1360 Define this to take the frame chain pointer and the frame's nominal
1361 address and produce the nominal address of the caller's frame.
1362 Presently only defined for HP PA.
1364 @item FRAME_CHAIN_VALID(chain,thisframe)
1366 Define this to be an expression that returns zero if the given frame is
1367 an outermost frame, with no caller, and nonzero otherwise. Three common
1368 definitions are available. @code{default_frame_chain_valid} (the
1369 default) is nonzero if the chain pointer is nonzero and given frame's PC
1370 is not inside the startup file (such as @file{crt0.o}).
1371 @code{alternate_frame_chain_valid} is nonzero if the chain pointer is
1372 nonzero and the given frame's PC is not in @code{main()} or a known
1373 entry point function (such as @code{_start()}).
1375 @item FRAME_INIT_SAVED_REGS(frame)
1376 See @file{frame.h}. Determines the address of all registers in the
1377 current stack frame storing each in @code{frame->saved_regs}. Space for
1378 @code{frame->saved_regs} shall be allocated by
1379 @code{FRAME_INIT_SAVED_REGS} using either
1380 @code{frame_saved_regs_zalloc} or @code{frame_obstack_alloc}.
1382 @var{FRAME_FIND_SAVED_REGS} and @var{EXTRA_FRAME_INFO} are deprecated.
1384 @item FRAME_NUM_ARGS (fi)
1385 For the frame described by @var{fi} return the number of arguments that
1386 are being passed. If the number of arguments is not known, return
1389 @item FRAME_SAVED_PC(frame)
1390 Given @var{frame}, return the pc saved there. That is, the return
1393 @item FUNCTION_EPILOGUE_SIZE
1394 For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the
1395 function end symbol is 0. For such targets, you must define
1396 @code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a
1397 function's epilogue.
1399 @item GCC_COMPILED_FLAG_SYMBOL
1400 @item GCC2_COMPILED_FLAG_SYMBOL
1401 If defined, these are the names of the symbols that GDB will look for to
1402 detect that GCC compiled the file. The default symbols are
1403 @code{gcc_compiled.} and @code{gcc2_compiled.}, respectively. (Currently
1404 only defined for the Delta 68.)
1406 @item GDB_MULTI_ARCH
1407 If defined and non-zero, enables suport for multiple architectures
1410 The support can be enabled at two levels. At level one, only
1411 definitions for previously undefined macros are provided; at level two,
1412 a multi-arch definition of all architecture dependant macros will be
1415 @item GDB_TARGET_IS_HPPA
1416 This determines whether horrible kludge code in dbxread.c and
1417 partial-stab.h is used to mangle multiple-symbol-table files from
1418 HPPA's. This should all be ripped out, and a scheme like elfread.c
1421 @item GET_LONGJMP_TARGET
1422 For most machines, this is a target-dependent parameter. On the
1423 DECstation and the Iris, this is a native-dependent parameter, since
1424 <setjmp.h> is needed to define it.
1426 This macro determines the target PC address that longjmp() will jump to,
1427 assuming that we have just stopped at a longjmp breakpoint. It takes a
1428 CORE_ADDR * as argument, and stores the target PC value through this
1429 pointer. It examines the current state of the machine as needed.
1431 @item GET_SAVED_REGISTER
1432 Define this if you need to supply your own definition for the function
1433 @code{get_saved_register}.
1435 @item HAVE_REGISTER_WINDOWS
1436 Define this if the target has register windows.
1437 @item REGISTER_IN_WINDOW_P (regnum)
1438 Define this to be an expression that is 1 if the given register is in
1441 @item IBM6000_TARGET
1442 Shows that we are configured for an IBM RS/6000 target. This
1443 conditional should be eliminated (FIXME) and replaced by
1444 feature-specific macros. It was introduced in haste and we are
1445 repenting at leisure.
1447 @item SYMBOLS_CAN_START_WITH_DOLLAR
1448 Some systems have routines whose names start with @samp{$}. Giving this
1449 macro a non-zero value tells GDB's expression parser to check for such
1450 routines when parsing tokens that begin with @samp{$}.
1452 On HP-UX, certain system routines (millicode) have names beginning with
1453 @samp{$} or @samp{$$}. For example, @code{$$dyncall} is a millicode
1454 routine that handles inter-space procedure calls on PA-RISC.
1457 Define this if the target system uses IEEE-format floating point numbers.
1459 @item INIT_EXTRA_FRAME_INFO (fromleaf, frame)
1460 If additional information about the frame is required this should be
1461 stored in @code{frame->extra_info}. Space for @code{frame->extra_info}
1462 is allocated using @code{frame_obstack_alloc}.
1464 @item INIT_FRAME_PC (fromleaf, prev)
1465 This is a C statement that sets the pc of the frame pointed to by
1466 @var{prev}. [By default...]
1468 @item INNER_THAN (lhs,rhs)
1469 Returns non-zero if stack address @var{lhs} is inner than (nearer to the
1470 stack top) stack address @var{rhs}. Define this as @code{lhs < rhs} if
1471 the target's stack grows downward in memory, or @code{lhs > rsh} if the
1474 @item IN_SIGTRAMP (pc, name)
1475 Define this to return true if the given @var{pc} and/or @var{name}
1476 indicates that the current function is a sigtramp.
1478 @item SIGTRAMP_START (pc)
1479 @item SIGTRAMP_END (pc)
1480 Define these to be the start and end address of the sigtramp for the
1481 given @var{pc}. On machines where the address is just a compile time
1482 constant, the macro expansion will typically just ignore the supplied
1485 @item IN_SOLIB_CALL_TRAMPOLINE pc name
1486 Define this to evaluate to nonzero if the program is stopped in the
1487 trampoline that connects to a shared library.
1489 @item IN_SOLIB_RETURN_TRAMPOLINE pc name
1490 Define this to evaluate to nonzero if the program is stopped in the
1491 trampoline that returns from a shared library.
1493 @item IN_SOLIB_DYNSYM_RESOLVE_CODE pc
1494 Define this to evaluate to nonzero if the program is stopped in the
1497 @item SKIP_SOLIB_RESOLVER pc
1498 Define this to evaluate to the (nonzero) address at which execution
1499 should continue to get past the dynamic linker's symbol resolution
1500 function. A zero value indicates that it is not important or necessary
1501 to set a breakpoint to get through the dynamic linker and that single
1502 stepping will suffice.
1504 @item IS_TRAPPED_INTERNALVAR (name)
1505 This is an ugly hook to allow the specification of special actions that
1506 should occur as a side-effect of setting the value of a variable
1507 internal to GDB. Currently only used by the h8500. Note that this
1508 could be either a host or target conditional.
1510 @item NEED_TEXT_START_END
1511 Define this if GDB should determine the start and end addresses of the
1512 text section. (Seems dubious.)
1514 @item NO_HIF_SUPPORT
1515 (Specific to the a29k.)
1517 @item SOFTWARE_SINGLE_STEP_P
1518 Define this as 1 if the target does not have a hardware single-step
1519 mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined.
1521 @item SOFTWARE_SINGLE_STEP(signal,insert_breapoints_p)
1522 A function that inserts or removes (dependant on
1523 @var{insert_breapoints_p}) breakpoints at each possible destinations of
1524 the next instruction. See @code{sparc-tdep.c} and @code{rs6000-tdep.c}
1527 @item PCC_SOL_BROKEN
1528 (Used only in the Convex target.)
1530 @item PC_IN_CALL_DUMMY
1533 @item PC_LOAD_SEGMENT
1534 If defined, print information about the load segment for the program
1535 counter. (Defined only for the RS/6000.)
1538 If the program counter is kept in a register, then define this macro to
1539 be the number (greater than or equal to zero) of that register.
1541 This should only need to be defined if @code{TARGET_READ_PC} and
1542 @code{TARGET_WRITE_PC} are not defined.
1545 The number of the ``next program counter'' register, if defined.
1548 The number of the ``next next program counter'' register, if defined.
1549 Currently, this is only defined for the Motorola 88K.
1552 If non-zero, round arguments to a boundary of this many bits before
1553 pushing them on the stack.
1555 @item PRINT_REGISTER_HOOK (regno)
1556 If defined, this must be a function that prints the contents of the
1557 given register to standard output.
1559 @item PRINT_TYPELESS_INTEGER
1560 This is an obscure substitute for @code{print_longest} that seems to
1561 have been defined for the Convex target.
1563 @item PROCESS_LINENUMBER_HOOK
1564 A hook defined for XCOFF reading.
1566 @item PROLOGUE_FIRSTLINE_OVERLAP
1567 (Only used in unsupported Convex configuration.)
1570 If defined, this is the number of the processor status register. (This
1571 definition is only used in generic code when parsing "$ps".)
1574 Used in @samp{call_function_by_hand} to remove an artificial stack
1577 @item PUSH_ARGUMENTS (nargs, args, sp, struct_return, struct_addr)
1578 Define this to push arguments onto the stack for inferior function
1579 call. Return the updated stack pointer value.
1581 @item PUSH_DUMMY_FRAME
1582 Used in @samp{call_function_by_hand} to create an artificial stack frame.
1584 @item REGISTER_BYTES
1585 The total amount of space needed to store GDB's copy of the machine's
1588 @item REGISTER_NAME(i)
1589 Return the name of register @var{i} as a string. May return @var{NULL}
1590 or @var{NUL} to indicate that register @var{i} is not valid.
1592 @item REGISTER_NAMES
1593 Deprecated in favor of @var{REGISTER_NAME}.
1595 @item REG_STRUCT_HAS_ADDR (gcc_p, type)
1596 Define this to return 1 if the given type will be passed by pointer
1597 rather than directly.
1599 @item SAVE_DUMMY_FRAME_TOS (sp)
1600 Used in @samp{call_function_by_hand} to notify the target dependent code
1601 of the top-of-stack value that will be passed to the the inferior code.
1602 This is the value of the @var{SP} after both the dummy frame and space
1603 for parameters/results have been allocated on the stack.
1605 @item SDB_REG_TO_REGNUM
1606 Define this to convert sdb register numbers into GDB regnums. If not
1607 defined, no conversion will be done.
1609 @item SHIFT_INST_REGS
1610 (Only used for m88k targets.)
1612 @item SKIP_PERMANENT_BREAKPOINT
1613 Advance the inferior's PC past a permanent breakpoint. GDB normally
1614 steps over a breakpoint by removing it, stepping one instruction, and
1615 re-inserting the breakpoint. However, permanent breakpoints are
1616 hardwired into the inferior, and can't be removed, so this strategy
1617 doesn't work. Calling SKIP_PERMANENT_BREAKPOINT adjusts the processor's
1618 state so that execution will resume just after the breakpoint. This
1619 macro does the right thing even when the breakpoint is in the delay slot
1620 of a branch or jump.
1622 @item SKIP_PROLOGUE (pc)
1623 A C expression that returns the address of the ``real'' code beyond the
1624 function entry prologue found at @var{pc}.
1626 @item SKIP_PROLOGUE_FRAMELESS_P
1627 A C expression that should behave similarly, but that can stop as soon
1628 as the function is known to have a frame. If not defined,
1629 @code{SKIP_PROLOGUE} will be used instead.
1631 @item SKIP_TRAMPOLINE_CODE (pc)
1632 If the target machine has trampoline code that sits between callers and
1633 the functions being called, then define this macro to return a new PC
1634 that is at the start of the real function.
1637 If the stack-pointer is kept in a register, then define this macro to be
1638 the number (greater than or equal to zero) of that register.
1640 This should only need to be defined if @code{TARGET_WRITE_SP} and
1641 @code{TARGET_WRITE_SP} are not defined.
1643 @item STAB_REG_TO_REGNUM
1644 Define this to convert stab register numbers (as gotten from `r'
1645 declarations) into GDB regnums. If not defined, no conversion will be
1648 @item STACK_ALIGN (addr)
1649 Define this to adjust the address to the alignment required for the
1652 @item STEP_SKIPS_DELAY (addr)
1653 Define this to return true if the address is of an instruction with a
1654 delay slot. If a breakpoint has been placed in the instruction's delay
1655 slot, GDB will single-step over that instruction before resuming
1656 normally. Currently only defined for the Mips.
1658 @item STORE_RETURN_VALUE (type, valbuf)
1659 A C expression that stores a function return value of type @var{type},
1660 where @var{valbuf} is the address of the value to be stored.
1662 @item SUN_FIXED_LBRAC_BUG
1663 (Used only for Sun-3 and Sun-4 targets.)
1665 @item SYMBOL_RELOADING_DEFAULT
1666 The default value of the `symbol-reloading' variable. (Never defined in
1669 @item TARGET_BYTE_ORDER_DEFAULT
1670 The ordering of bytes in the target. This must be either
1671 @code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. This macro replaces
1672 @var{TARGET_BYTE_ORDER} which is deprecated.
1674 @item TARGET_BYTE_ORDER_SELECTABLE_P
1675 Non-zero if the target has both @code{BIG_ENDIAN} and
1676 @code{LITTLE_ENDIAN} variants. This macro replaces
1677 @var{TARGET_BYTE_ORDER_SELECTABLE} which is deprecated.
1679 @item TARGET_CHAR_BIT
1680 Number of bits in a char; defaults to 8.
1682 @item TARGET_COMPLEX_BIT
1683 Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}.
1685 At present this macro is not used.
1687 @item TARGET_DOUBLE_BIT
1688 Number of bits in a double float; defaults to @code{8 * TARGET_CHAR_BIT}.
1690 @item TARGET_DOUBLE_COMPLEX_BIT
1691 Number of bits in a double complex; defaults to @code{2 * TARGET_DOUBLE_BIT}.
1693 At present this macro is not used.
1695 @item TARGET_FLOAT_BIT
1696 Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}.
1698 @item TARGET_INT_BIT
1699 Number of bits in an integer; defaults to @code{4 * TARGET_CHAR_BIT}.
1701 @item TARGET_LONG_BIT
1702 Number of bits in a long integer; defaults to @code{4 * TARGET_CHAR_BIT}.
1704 @item TARGET_LONG_DOUBLE_BIT
1705 Number of bits in a long double float;
1706 defaults to @code{2 * TARGET_DOUBLE_BIT}.
1708 @item TARGET_LONG_LONG_BIT
1709 Number of bits in a long long integer; defaults to @code{2 * TARGET_LONG_BIT}.
1711 @item TARGET_PTR_BIT
1712 Number of bits in a pointer; defaults to @code{TARGET_INT_BIT}.
1714 @item TARGET_SHORT_BIT
1715 Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}.
1717 @item TARGET_READ_PC
1718 @item TARGET_WRITE_PC (val, pid)
1719 @item TARGET_READ_SP
1720 @item TARGET_WRITE_SP
1721 @item TARGET_READ_FP
1722 @item TARGET_WRITE_FP
1723 These change the behavior of @code{read_pc}, @code{write_pc},
1724 @code{read_sp}, @code{write_sp}, @code{read_fp} and @code{write_fp}.
1725 For most targets, these may be left undefined. GDB will call the read
1726 and write register functions with the relevant @code{_REGNUM} argument.
1728 These macros are useful when a target keeps one of these registers in a
1729 hard to get at place; for example, part in a segment register and part
1730 in an ordinary register.
1732 @item TARGET_VIRTUAL_FRAME_POINTER(pc,regp,offsetp)
1733 Returns a @code{(register, offset)} pair representing the virtual
1734 frame pointer in use at the code address @code{"pc"}. If virtual
1735 frame pointers are not used, a default definition simply returns
1736 @code{FP_REGNUM}, with an offset of zero.
1738 @item USE_STRUCT_CONVENTION (gcc_p, type)
1739 If defined, this must be an expression that is nonzero if a value of the
1740 given @var{type} being returned from a function must have space
1741 allocated for it on the stack. @var{gcc_p} is true if the function
1742 being considered is known to have been compiled by GCC; this is helpful
1743 for systems where GCC is known to use different calling convention than
1746 @item VARIABLES_INSIDE_BLOCK (desc, gcc_p)
1747 For dbx-style debugging information, if the compiler puts variable
1748 declarations inside LBRAC/RBRAC blocks, this should be defined to be
1749 nonzero. @var{desc} is the value of @code{n_desc} from the
1750 @code{N_RBRAC} symbol, and @var{gcc_p} is true if GDB has noticed the
1751 presence of either the @code{GCC_COMPILED_SYMBOL} or the
1752 @code{GCC2_COMPILED_SYMBOL}. By default, this is 0.
1754 @item OS9K_VARIABLES_INSIDE_BLOCK (desc, gcc_p)
1755 Similarly, for OS/9000. Defaults to 1.
1759 Motorola M68K target conditionals.
1764 Define this to be the 4-bit location of the breakpoint trap vector. If
1765 not defined, it will default to @code{0xf}.
1767 @item REMOTE_BPT_VECTOR
1768 Defaults to @code{1}.
1772 @section Adding a New Target
1774 The following files define a target to GDB:
1778 @item gdb/config/@var{arch}/@var{ttt}.mt
1779 Contains a Makefile fragment specific to this target. Specifies what
1780 object files are needed for target @var{ttt}, by defining
1781 @samp{TDEPFILES=@dots{}} and @samp{TDEPLIBS=@dots{}}. Also specifies
1782 the header file which describes @var{ttt}, by defining @samp{TM_FILE=
1785 You can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, @samp{TM_CDEPS},
1786 but these are now deprecated, replaced by autoconf, and may go away in
1787 future versions of GDB.
1789 @item gdb/config/@var{arch}/tm-@var{ttt}.h
1790 (@file{tm.h} is a link to this file, created by configure). Contains
1791 macro definitions about the target machine's registers, stack frame
1792 format and instructions.
1794 @item gdb/@var{ttt}-tdep.c
1795 Contains any miscellaneous code required for this target machine. On
1796 some machines it doesn't exist at all. Sometimes the macros in
1797 @file{tm-@var{ttt}.h} become very complicated, so they are implemented
1798 as functions here instead, and the macro is simply defined to call the
1799 function. This is vastly preferable, since it is easier to understand
1802 @item gdb/config/@var{arch}/tm-@var{arch}.h
1803 This often exists to describe the basic layout of the target machine's
1804 processor chip (registers, stack, etc). If used, it is included by
1805 @file{tm-@var{ttt}.h}. It can be shared among many targets that use the
1808 @item gdb/@var{arch}-tdep.c
1809 Similarly, there are often common subroutines that are shared by all
1810 target machines that use this particular architecture.
1814 If you are adding a new operating system for an existing CPU chip, add a
1815 @file{config/tm-@var{os}.h} file that describes the operating system
1816 facilities that are unusual (extra symbol table info; the breakpoint
1817 instruction needed; etc). Then write a @file{@var{arch}/tm-@var{os}.h}
1818 that just @code{#include}s @file{tm-@var{arch}.h} and
1819 @file{config/tm-@var{os}.h}.
1822 @node Target Vector Definition
1824 @chapter Target Vector Definition
1826 The target vector defines the interface between GDB's abstract handling
1827 of target systems, and the nitty-gritty code that actually exercises
1828 control over a process or a serial port. GDB includes some 30-40
1829 different target vectors; however, each configuration of GDB includes
1832 @section File Targets
1834 Both executables and core files have target vectors.
1836 @section Standard Protocol and Remote Stubs
1838 GDB's file @file{remote.c} talks a serial protocol to code that runs in
1839 the target system. GDB provides several sample ``stubs'' that can be
1840 integrated into target programs or operating systems for this purpose;
1841 they are named @file{*-stub.c}.
1843 The GDB user's manual describes how to put such a stub into your target
1844 code. What follows is a discussion of integrating the SPARC stub into a
1845 complicated operating system (rather than a simple program), by Stu
1846 Grossman, the author of this stub.
1848 The trap handling code in the stub assumes the following upon entry to
1853 @item %l1 and %l2 contain pc and npc respectively at the time of the trap
1855 @item traps are disabled
1857 @item you are in the correct trap window
1861 As long as your trap handler can guarantee those conditions, then there
1862 is no reason why you shouldn't be able to `share' traps with the stub.
1863 The stub has no requirement that it be jumped to directly from the
1864 hardware trap vector. That is why it calls @code{exceptionHandler()},
1865 which is provided by the external environment. For instance, this could
1866 setup the hardware traps to actually execute code which calls the stub
1867 first, and then transfers to its own trap handler.
1869 For the most point, there probably won't be much of an issue with
1870 `sharing' traps, as the traps we use are usually not used by the kernel,
1871 and often indicate unrecoverable error conditions. Anyway, this is all
1872 controlled by a table, and is trivial to modify. The most important
1873 trap for us is for @code{ta 1}. Without that, we can't single step or
1874 do breakpoints. Everything else is unnecessary for the proper operation
1875 of the debugger/stub.
1877 From reading the stub, it's probably not obvious how breakpoints work.
1878 They are simply done by deposit/examine operations from GDB.
1880 @section ROM Monitor Interface
1882 @section Custom Protocols
1884 @section Transport Layer
1886 @section Builtin Simulator
1889 @node Native Debugging
1891 @chapter Native Debugging
1893 Several files control GDB's configuration for native support:
1897 @item gdb/config/@var{arch}/@var{xyz}.mh
1898 Specifies Makefile fragments needed when hosting @emph{or native} on
1899 machine @var{xyz}. In particular, this lists the required
1900 native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}.
1901 Also specifies the header file which describes native support on
1902 @var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}. You can also
1903 define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS},
1904 @samp{NAT_CDEPS}, etc.; see @file{Makefile.in}.
1906 @item gdb/config/@var{arch}/nm-@var{xyz}.h
1907 (@file{nm.h} is a link to this file, created by configure). Contains C
1908 macro definitions describing the native system environment, such as
1909 child process control and core file support.
1911 @item gdb/@var{xyz}-nat.c
1912 Contains any miscellaneous C code required for this native support of
1913 this machine. On some machines it doesn't exist at all.
1917 There are some ``generic'' versions of routines that can be used by
1918 various systems. These can be customized in various ways by macros
1919 defined in your @file{nm-@var{xyz}.h} file. If these routines work for
1920 the @var{xyz} host, you can just include the generic file's name (with
1921 @samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.
1923 Otherwise, if your machine needs custom support routines, you will need
1924 to write routines that perform the same functions as the generic file.
1925 Put them into @code{@var{xyz}-nat.c}, and put @code{@var{xyz}-nat.o}
1926 into @code{NATDEPFILES}.
1931 This contains the @emph{target_ops vector} that supports Unix child
1932 processes on systems which use ptrace and wait to control the child.
1935 This contains the @emph{target_ops vector} that supports Unix child
1936 processes on systems which use /proc to control the child.
1939 This does the low-level grunge that uses Unix system calls to do a "fork
1940 and exec" to start up a child process.
1943 This is the low level interface to inferior processes for systems using
1944 the Unix @code{ptrace} call in a vanilla way.
1948 @section Native core file Support
1952 @item core-aout.c::fetch_core_registers()
1953 Support for reading registers out of a core file. This routine calls
1954 @code{register_addr()}, see below. Now that BFD is used to read core
1955 files, virtually all machines should use @code{core-aout.c}, and should
1956 just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or
1957 @code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}).
1959 @item core-aout.c::register_addr()
1960 If your @code{nm-@var{xyz}.h} file defines the macro
1961 @code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
1962 set @code{addr} to the offset within the @samp{user} struct of GDB
1963 register number @code{regno}. @code{blockend} is the offset within the
1964 ``upage'' of @code{u.u_ar0}. If @code{REGISTER_U_ADDR} is defined,
1965 @file{core-aout.c} will define the @code{register_addr()} function and
1966 use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but
1967 you are using the standard @code{fetch_core_registers()}, you will need
1968 to define your own version of @code{register_addr()}, put it into your
1969 @code{@var{xyz}-nat.c} file, and be sure @code{@var{xyz}-nat.o} is in
1970 the @code{NATDEPFILES} list. If you have your own
1971 @code{fetch_core_registers()}, you may not need a separate
1972 @code{register_addr()}. Many custom @code{fetch_core_registers()}
1973 implementations simply locate the registers themselves.@refill
1977 When making GDB run native on a new operating system, to make it
1978 possible to debug core files, you will need to either write specific
1979 code for parsing your OS's core files, or customize
1980 @file{bfd/trad-core.c}. First, use whatever @code{#include} files your
1981 machine uses to define the struct of registers that is accessible
1982 (possibly in the u-area) in a core file (rather than
1983 @file{machine/reg.h}), and an include file that defines whatever header
1984 exists on a core file (e.g. the u-area or a @samp{struct core}). Then
1985 modify @code{trad_unix_core_file_p()} to use these values to set up the
1986 section information for the data segment, stack segment, any other
1987 segments in the core file (perhaps shared library contents or control
1988 information), ``registers'' segment, and if there are two discontiguous
1989 sets of registers (e.g. integer and float), the ``reg2'' segment. This
1990 section information basically delimits areas in the core file in a
1991 standard way, which the section-reading routines in BFD know how to seek
1994 Then back in GDB, you need a matching routine called
1995 @code{fetch_core_registers()}. If you can use the generic one, it's in
1996 @file{core-aout.c}; if not, it's in your @file{@var{xyz}-nat.c} file.
1997 It will be passed a char pointer to the entire ``registers'' segment,
1998 its length, and a zero; or a char pointer to the entire ``regs2''
1999 segment, its length, and a 2. The routine should suck out the supplied
2000 register values and install them into GDB's ``registers'' array.
2002 If your system uses @file{/proc} to control processes, and uses ELF
2003 format core files, then you may be able to use the same routines for
2004 reading the registers out of processes and out of core files.
2012 @section shared libraries
2014 @section Native Conditionals
2016 When GDB is configured and compiled, various macros are defined or left
2017 undefined, to control compilation when the host and target systems are
2018 the same. These macros should be defined (or left undefined) in
2019 @file{nm-@var{system}.h}.
2024 If defined, then GDB will include support for the @code{attach} and
2025 @code{detach} commands.
2027 @item CHILD_PREPARE_TO_STORE
2028 If the machine stores all registers at once in the child process, then
2029 define this to ensure that all values are correct. This usually entails
2030 a read from the child.
2032 [Note that this is incorrectly defined in @file{xm-@var{system}.h} files
2035 @item FETCH_INFERIOR_REGISTERS
2036 Define this if the native-dependent code will provide its own routines
2037 @code{fetch_inferior_registers} and @code{store_inferior_registers} in
2038 @file{@var{HOST}-nat.c}. If this symbol is @emph{not} defined, and
2039 @file{infptrace.c} is included in this configuration, the default
2040 routines in @file{infptrace.c} are used for these functions.
2042 @item FILES_INFO_HOOK
2043 (Only defined for Convex.)
2046 This macro is normally defined to be the number of the first floating
2047 point register, if the machine has such registers. As such, it would
2048 appear only in target-specific code. However, /proc support uses this
2049 to decide whether floats are in use on this target.
2051 @item GET_LONGJMP_TARGET
2052 For most machines, this is a target-dependent parameter. On the
2053 DECstation and the Iris, this is a native-dependent parameter, since
2054 <setjmp.h> is needed to define it.
2056 This macro determines the target PC address that longjmp() will jump to,
2057 assuming that we have just stopped at a longjmp breakpoint. It takes a
2058 CORE_ADDR * as argument, and stores the target PC value through this
2059 pointer. It examines the current state of the machine as needed.
2062 Define this to the address of the @code{u} structure (the ``user
2063 struct'', also known as the ``u-page'') in kernel virtual memory. GDB
2064 needs to know this so that it can subtract this address from absolute
2065 addresses in the upage, that are obtained via ptrace or from core files.
2066 On systems that don't need this value, set it to zero.
2068 @item KERNEL_U_ADDR_BSD
2069 Define this to cause GDB to determine the address of @code{u} at
2070 runtime, by using Berkeley-style @code{nlist} on the kernel's image in
2073 @item KERNEL_U_ADDR_HPUX
2074 Define this to cause GDB to determine the address of @code{u} at
2075 runtime, by using HP-style @code{nlist} on the kernel's image in the
2078 @item ONE_PROCESS_WRITETEXT
2079 Define this to be able to, when a breakpoint insertion fails, warn the
2080 user that another process may be running with the same executable.
2082 @item PREPARE_TO_PROCEED @var{select_it}
2083 This (ugly) macro allows a native configuration to customize the way the
2084 @code{proceed} function in @file{infrun.c} deals with switching between
2087 In a multi-threaded task we may select another thread and then continue
2088 or step. But if the old thread was stopped at a breakpoint, it will
2089 immediately cause another breakpoint stop without any execution (i.e. it
2090 will report a breakpoint hit incorrectly). So GDB must step over it
2093 If defined, @code{PREPARE_TO_PROCEED} should check the current thread
2094 against the thread that reported the most recent event. If a step-over
2095 is required, it returns TRUE. If @var{select_it} is non-zero, it should
2096 reselect the old thread.
2099 Defines the format for the name of a @file{/proc} device. Should be
2100 defined in @file{nm.h} @emph{only} in order to override the default
2101 definition in @file{procfs.c}.
2106 @item PTRACE_ARG3_TYPE
2107 The type of the third argument to the @code{ptrace} system call, if it
2108 exists and is different from @code{int}.
2110 @item REGISTER_U_ADDR
2111 Defines the offset of the registers in the ``u area''.
2113 @item SHELL_COMMAND_CONCAT
2114 If defined, is a string to prefix on the shell command used to start the
2118 If defined, this is the name of the shell to use to run the inferior.
2119 Defaults to @code{"/bin/sh"}.
2121 @item SOLIB_ADD (filename, from_tty, targ)
2122 Define this to expand into an expression that will cause the symbols in
2123 @var{filename} to be added to GDB's symbol table.
2125 @item SOLIB_CREATE_INFERIOR_HOOK
2126 Define this to expand into any shared-library-relocation code that you
2127 want to be run just after the child process has been forked.
2129 @item START_INFERIOR_TRAPS_EXPECTED
2130 When starting an inferior, GDB normally expects to trap twice; once when
2131 the shell execs, and once when the program itself execs. If the actual
2132 number of traps is something other than 2, then define this macro to
2133 expand into the number expected.
2135 @item SVR4_SHARED_LIBS
2136 Define this to indicate that SVR4-style shared libraries are in use.
2139 This determines whether small routines in @file{*-tdep.c}, which
2140 translate register values between GDB's internal representation and the
2141 /proc representation, are compiled.
2144 This is the offset of the registers in the upage. It need only be
2145 defined if the generic ptrace register access routines in
2146 @file{infptrace.c} are being used (that is, @file{infptrace.c} is
2147 configured in, and @code{FETCH_INFERIOR_REGISTERS} is not defined). If
2148 the default value from @file{infptrace.c} is good enough, leave it
2151 The default value means that u.u_ar0 @emph{points to} the location of
2152 the registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means
2153 that u.u_ar0 @emph{is} the location of the registers.
2159 Define this to debug ptrace calls.
2164 @node Support Libraries
2166 @chapter Support Libraries
2170 BFD provides support for GDB in several ways:
2174 @item identifying executable and core files
2175 BFD will identify a variety of file types, including a.out, coff, and
2176 several variants thereof, as well as several kinds of core files.
2178 @item access to sections of files
2179 BFD parses the file headers to determine the names, virtual addresses,
2180 sizes, and file locations of all the various named sections in files
2181 (such as the text section or the data section). GDB simply calls BFD to
2182 read or write section X at byte offset Y for length Z.
2184 @item specialized core file support
2185 BFD provides routines to determine the failing command name stored in a
2186 core file, the signal with which the program failed, and whether a core
2187 file matches (i.e. could be a core dump of) a particular executable
2190 @item locating the symbol information
2191 GDB uses an internal interface of BFD to determine where to find the
2192 symbol information in an executable file or symbol-file. GDB itself
2193 handles the reading of symbols, since BFD does not ``understand'' debug
2194 symbols, but GDB uses BFD's cached information to find the symbols,
2201 The opcodes library provides GDB's disassembler. (It's a separate
2202 library because it's also used in binutils, for @file{objdump}).
2222 @item SIGN_EXTEND_CHAR
2224 @item SWITCH_ENUM_BUG
2240 This chapter covers topics that are lower-level than the major
2245 Cleanups are a structured way to deal with things that need to be done
2246 later. When your code does something (like @code{malloc} some memory,
2247 or open a file) that needs to be undone later (e.g. free the memory or
2248 close the file), it can make a cleanup. The cleanup will be done at
2249 some future point: when the command is finished, when an error occurs,
2250 or when your code decides it's time to do cleanups.
2252 You can also discard cleanups, that is, throw them away without doing
2253 what they say. This is only done if you ask that it be done.
2259 @item struct cleanup *@var{old_chain};
2260 Declare a variable which will hold a cleanup chain handle.
2262 @item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
2263 Make a cleanup which will cause @var{function} to be called with
2264 @var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a
2265 handle that can be passed to @code{do_cleanups} or
2266 @code{discard_cleanups} later. Unless you are going to call
2267 @code{do_cleanups} or @code{discard_cleanups} yourself, you can ignore
2268 the result from @code{make_cleanup}.
2270 @item do_cleanups (@var{old_chain});
2271 Perform all cleanups done since @code{make_cleanup} returned
2272 @var{old_chain}. E.g.:
2274 make_cleanup (a, 0);
2275 old = make_cleanup (b, 0);
2279 will call @code{b()} but will not call @code{a()}. The cleanup that
2280 calls @code{a()} will remain in the cleanup chain, and will be done
2281 later unless otherwise discarded.@refill
2283 @item discard_cleanups (@var{old_chain});
2284 Same as @code{do_cleanups} except that it just removes the cleanups from
2285 the chain and does not call the specified functions.
2289 Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify
2290 that they ``should not be called when cleanups are not in place''. This
2291 means that any actions you need to reverse in the case of an error or
2292 interruption must be on the cleanup chain before you call these
2293 functions, since they might never return to your code (they
2294 @samp{longjmp} instead).
2296 @section Wrapping Output Lines
2298 Output that goes through @code{printf_filtered} or @code{fputs_filtered}
2299 or @code{fputs_demangled} needs only to have calls to @code{wrap_here}
2300 added in places that would be good breaking points. The utility
2301 routines will take care of actually wrapping if the line width is
2304 The argument to @code{wrap_here} is an indentation string which is
2305 printed @emph{only} if the line breaks there. This argument is saved
2306 away and used later. It must remain valid until the next call to
2307 @code{wrap_here} or until a newline has been printed through the
2308 @code{*_filtered} functions. Don't pass in a local variable and then
2311 It is usually best to call @code{wrap_here()} after printing a comma or
2312 space. If you call it before printing a space, make sure that your
2313 indentation properly accounts for the leading space that will print if
2314 the line wraps there.
2316 Any function or set of functions that produce filtered output must
2317 finish by printing a newline, to flush the wrap buffer, before switching
2318 to unfiltered (``@code{printf}'') output. Symbol reading routines that
2319 print warnings are a good example.
2321 @section GDB Coding Standards
2323 GDB follows the GNU coding standards, as described in
2324 @file{etc/standards.texi}. This file is also available for anonymous
2325 FTP from GNU archive sites. GDB takes a strict interpretation of the
2326 standard; in general, when the GNU standard recommends a practice but
2327 does not require it, GDB requires it.
2329 GDB follows an additional set of coding standards specific to GDB,
2330 as described in the following sections.
2332 You can configure with @samp{--enable-build-warnings} to get GCC to
2333 check on a number of these rules. GDB sources ought not to engender any
2334 complaints, unless they are caused by bogus host systems. (The exact
2335 set of enabled warnings is currently @samp{-Wall -Wpointer-arith
2336 -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations}.
2338 @subsection Formatting
2340 The standard GNU recommendations for formatting must be followed
2343 Note that while in a definition, the function's name must be in column
2344 zero; in a function declaration, the name must be on the same line as
2347 In addition, there must be a space between a function or macro name and
2348 the opening parenthesis of its argument list (except for macro
2349 definitions, as required by C). There must not be a space after an open
2350 paren/bracket or before a close paren/bracket.
2352 While additional whitespace is generally helpful for reading, do not use
2353 more than one blank line to separate blocks, and avoid adding whitespace
2354 after the end of a program line (as of 1/99, some 600 lines had whitespace
2355 after the semicolon). Excess whitespace causes difficulties for diff and
2358 @subsection Comments
2360 The standard GNU requirements on comments must be followed strictly.
2362 Block comments must appear in the following form, with no `/*'- or
2363 '*/'-only lines, and no leading `*':
2366 /* Wait for control to return from inferior to debugger. If inferior
2367 gets a signal, we may decide to start it up again instead of
2368 returning. That is why there is a loop in this function. When
2369 this function actually returns it means the inferior should be left
2370 stopped and GDB should read more commands. */
2373 (Note that this format is encouraged by Emacs; tabbing for a multi-line
2374 comment works correctly, and M-Q fills the block consistently.)
2376 Put a blank line between the block comments preceding function or
2377 variable definitions, and the definition itself.
2379 In general, put function-body comments on lines by themselves, rather
2380 than trying to fit them into the 20 characters left at the end of a
2381 line, since either the comment or the code will inevitably get longer
2382 than will fit, and then somebody will have to move it anyhow.
2386 Code must not depend on the sizes of C data types, the format of the
2387 host's floating point numbers, the alignment of anything, or the order
2388 of evaluation of expressions.
2390 Use functions freely. There are only a handful of compute-bound areas
2391 in GDB that might be affected by the overhead of a function call, mainly
2392 in symbol reading. Most of GDB's performance is limited by the target
2393 interface (whether serial line or system call).
2395 However, use functions with moderation. A thousand one-line functions
2396 are just as hard to understand as a single thousand-line function.
2398 @subsection Function Prototypes
2400 Prototypes must be used to @emph{declare} functions, and may be used to
2401 @emph{define} them. Prototypes for GDB functions must include both the
2402 argument type and name, with the name matching that used in the actual
2403 function definition.
2405 All external functions should have a declaration in a header file that
2406 callers include, except for @code{_initialize_*} functions, which must
2407 be external so that @file{init.c} construction works, but shouldn't be
2408 visible to random source files.
2410 All static functions must be declared in a block near the top of the
2413 @subsection Clean Design
2415 In addition to getting the syntax right, there's the little question of
2416 semantics. Some things are done in certain ways in GDB because long
2417 experience has shown that the more obvious ways caused various kinds of
2420 You can't assume the byte order of anything that comes from a target
2421 (including @var{value}s, object files, and instructions). Such things
2422 must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in GDB, or one of
2423 the swap routines defined in @file{bfd.h}, such as @code{bfd_get_32}.
2425 You can't assume that you know what interface is being used to talk to
2426 the target system. All references to the target must go through the
2427 current @code{target_ops} vector.
2429 You can't assume that the host and target machines are the same machine
2430 (except in the ``native'' support modules). In particular, you can't
2431 assume that the target machine's header files will be available on the
2432 host machine. Target code must bring along its own header files --
2433 written from scratch or explicitly donated by their owner, to avoid
2436 Insertion of new @code{#ifdef}'s will be frowned upon. It's much better
2437 to write the code portably than to conditionalize it for various
2440 New @code{#ifdef}'s which test for specific compilers or manufacturers
2441 or operating systems are unacceptable. All @code{#ifdef}'s should test
2442 for features. The information about which configurations contain which
2443 features should be segregated into the configuration files. Experience
2444 has proven far too often that a feature unique to one particular system
2445 often creeps into other systems; and that a conditional based on some
2446 predefined macro for your current system will become worthless over
2447 time, as new versions of your system come out that behave differently
2448 with regard to this feature.
2450 Adding code that handles specific architectures, operating systems,
2451 target interfaces, or hosts, is not acceptable in generic code. If a
2452 hook is needed at that point, invent a generic hook and define it for
2453 your configuration, with something like:
2456 #ifdef WRANGLE_SIGNALS
2457 WRANGLE_SIGNALS (signo);
2461 In your host, target, or native configuration file, as appropriate,
2462 define @code{WRANGLE_SIGNALS} to do the machine-dependent thing. Take a
2463 bit of care in defining the hook, so that it can be used by other ports
2464 in the future, if they need a hook in the same place.
2466 If the hook is not defined, the code should do whatever "most" machines
2467 want. Using @code{#ifdef}, as above, is the preferred way to do this,
2468 but sometimes that gets convoluted, in which case use
2471 #ifndef SPECIAL_FOO_HANDLING
2472 #define SPECIAL_FOO_HANDLING(pc, sp) (0)
2476 where the macro is used or in an appropriate header file.
2478 Whether to include a @dfn{small} hook, a hook around the exact pieces of
2479 code which are system-dependent, or whether to replace a whole function
2480 with a hook depends on the case. A good example of this dilemma can be
2481 found in @code{get_saved_register}. All machines that GDB 2.8 ran on
2482 just needed the @code{FRAME_FIND_SAVED_REGS} hook to find the saved
2483 registers. Then the SPARC and Pyramid came along, and
2484 @code{HAVE_REGISTER_WINDOWS} and @code{REGISTER_IN_WINDOW_P} were
2485 introduced. Then the 29k and 88k required the @code{GET_SAVED_REGISTER}
2486 hook. The first three are examples of small hooks; the latter replaces
2487 a whole function. In this specific case, it is useful to have both
2488 kinds; it would be a bad idea to replace all the uses of the small hooks
2489 with @code{GET_SAVED_REGISTER}, since that would result in much
2490 duplicated code. Other times, duplicating a few lines of code here or
2491 there is much cleaner than introducing a large number of small hooks.
2493 Another way to generalize GDB along a particular interface is with an
2494 attribute struct. For example, GDB has been generalized to handle
2495 multiple kinds of remote interfaces -- not by #ifdef's everywhere, but
2496 by defining the "target_ops" structure and having a current target (as
2497 well as a stack of targets below it, for memory references). Whenever
2498 something needs to be done that depends on which remote interface we are
2499 using, a flag in the current target_ops structure is tested (e.g.
2500 `target_has_stack'), or a function is called through a pointer in the
2501 current target_ops structure. In this way, when a new remote interface
2502 is added, only one module needs to be touched -- the one that actually
2503 implements the new remote interface. Other examples of
2504 attribute-structs are BFD access to multiple kinds of object file
2505 formats, or GDB's access to multiple source languages.
2507 Please avoid duplicating code. For example, in GDB 3.x all the code
2508 interfacing between @code{ptrace} and the rest of GDB was duplicated in
2509 @file{*-dep.c}, and so changing something was very painful. In GDB 4.x,
2510 these have all been consolidated into @file{infptrace.c}.
2511 @file{infptrace.c} can deal with variations between systems the same way
2512 any system-independent file would (hooks, #if defined, etc.), and
2513 machines which are radically different don't need to use infptrace.c at
2516 Don't put debugging printfs in the code.
2520 @chapter Porting GDB
2522 Most of the work in making GDB compile on a new machine is in specifying
2523 the configuration of the machine. This is done in a dizzying variety of
2524 header files and configuration scripts, which we hope to make more
2525 sensible soon. Let's say your new host is called an @var{xyz} (e.g.
2526 @samp{sun4}), and its full three-part configuration name is
2527 @code{@var{arch}-@var{xvend}-@var{xos}} (e.g. @samp{sparc-sun-sunos4}).
2530 In the top level directory, edit @file{config.sub} and add @var{arch},
2531 @var{xvend}, and @var{xos} to the lists of supported architectures,
2532 vendors, and operating systems near the bottom of the file. Also, add
2533 @var{xyz} as an alias that maps to
2534 @code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by
2538 ./config.sub @var{xyz}
2543 ./config.sub @code{@var{arch}-@var{xvend}-@var{xos}}
2546 which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}}
2547 and no error messages.
2549 You need to port BFD, if that hasn't been done already. Porting BFD is
2550 beyond the scope of this manual.
2552 To configure GDB itself, edit @file{gdb/configure.host} to recognize
2553 your system and set @code{gdb_host} to @var{xyz}, and (unless your
2554 desired target is already available) also edit @file{gdb/configure.tgt},
2555 setting @code{gdb_target} to something appropriate (for instance,
2558 Finally, you'll need to specify and define GDB's host-, native-, and
2559 target-dependent @file{.h} and @file{.c} files used for your
2562 @section Configuring GDB for Release
2564 From the top level directory (containing @file{gdb}, @file{bfd},
2565 @file{libiberty}, and so on):
2567 make -f Makefile.in gdb.tar.gz
2570 This will properly configure, clean, rebuild any files that are
2571 distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}),
2572 and will then make a tarfile. (If the top level directory has already
2573 been configured, you can just do @code{make gdb.tar.gz} instead.)
2575 This procedure requires:
2577 @item symbolic links
2578 @item @code{makeinfo} (texinfo2 level)
2581 @item @code{yacc} or @code{bison}
2584 @dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.).
2586 @subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
2588 @file{gdb.texinfo} is currently marked up using the texinfo-2 macros,
2589 which are not yet a default for anything (but we have to start using
2592 For making paper, the only thing this implies is the right generation of
2593 @file{texinfo.tex} needs to be included in the distribution.
2595 For making info files, however, rather than duplicating the texinfo2
2596 distribution, generate @file{gdb-all.texinfo} locally, and include the
2597 files @file{gdb.info*} in the distribution. Note the plural;
2598 @code{makeinfo} will split the document into one overall file and five
2599 or so included files.
2605 The testsuite is an important component of the GDB package. While it is
2606 always worthwhile to encourage user testing, in practice this is rarely
2607 sufficient; users typically use only a small subset of the available
2608 commands, and it has proven all too common for a change to cause a
2609 significant regression that went unnoticed for some time.
2611 The GDB testsuite uses the DejaGNU testing framework. DejaGNU is built
2612 using tcl and expect. The tests themselves are calls to various tcl
2613 procs; the framework runs all the procs and summarizes the passes and
2616 @section Using the Testsuite
2618 To run the testsuite, simply go to the GDB object directory (or to the
2619 testsuite's objdir) and type @code{make check}. This just sets up some
2620 environment variables and invokes DejaGNU's @code{runtest} script. While
2621 the testsuite is running, you'll get mentions of which test file is in use,
2622 and a mention of any unexpected passes or fails. When the testsuite is
2623 finished, you'll get a summary that looks like this:
2627 # of expected passes 6016
2628 # of unexpected failures 58
2629 # of unexpected successes 5
2630 # of expected failures 183
2631 # of unresolved testcases 3
2632 # of untested testcases 5
2634 The ideal test run consists of expected passes only; however, reality
2635 conspires to keep us from this ideal. Unexpected failures indicate
2636 real problems, whether in GDB or in the testsuite. Expected failures
2637 are still failures, but ones which have been decided are too hard to
2638 deal with at the time; for instance, a test case might work everywhere
2639 except on AIX, and there is no prospect of the AIX case being fixed in
2640 the near future. Expected failures should not be added lightly, since
2641 you may be masking serious bugs in GDB. Unexpected successes are expected
2642 fails that are passing for some reason, while unresolved and untested
2643 cases often indicate some minor catastrophe, such as the compiler being
2644 unable to deal with a test program.
2646 When making any significant change to GDB, you should run the testsuite
2647 before and after the change, to confirm that there are no regressions.
2648 Note that truly complete testing would require that you run the
2649 testsuite with all supported configurations and a variety of compilers;
2650 however this is more than really necessary. In many cases testing with
2651 a single configuration is sufficient. Other useful options are to test
2652 one big-endian (Sparc) and one little-endian (x86) host, a cross config
2653 with a builtin simulator (powerpc-eabi, mips-elf), or a 64-bit host
2656 If you add new functionality to GDB, please consider adding tests for it
2657 as well; this way future GDB hackers can detect and fix their changes
2658 that break the functionality you added. Similarly, if you fix a bug
2659 that was not previously reported as a test failure, please add a test
2660 case for it. Some cases are extremely difficult to test, such as code
2661 that handles host OS failures or bugs in particular versions of
2662 compilers, and it's OK not to try to write tests for all of those.
2664 @section Testsuite Organization
2666 The testsuite is entirely contained in @file{gdb/testsuite}. While the
2667 testsuite includes some makefiles and configury, these are very minimal,
2668 and used for little besides cleaning up, since the tests themselves
2669 handle the compilation of the programs that GDB will run. The file
2670 @file{testsuite/lib/gdb.exp} contains common utility procs useful for
2671 all GDB tests, while the directory @file{testsuite/config} contains
2672 configuration-specific files, typically used for special-purpose
2673 definitions of procs like @code{gdb_load} and @code{gdb_start}.
2675 The tests themselves are to be found in @file{testsuite/gdb.*} and
2676 subdirectories of those. The names of the test files must always end
2677 with @file{.exp}. DejaGNU collects the test files by wildcarding
2678 in the test directories, so both subdirectories and individual files
2679 get chosen and run in alphabetical order.
2681 The following table lists the main types of subdirectories and what they
2682 are for. Since DejaGNU finds test files no matter where they are
2683 located, and since each test file sets up its own compilation and
2684 execution environment, this organization is simply for convenience and
2691 This is the base testsuite. The tests in it should apply to all
2692 configurations of GDB (but generic native-only tests may live here).
2693 The test programs should be in the subset of C that is valid K&R,
2694 ANSI/ISO, and C++ (ifdefs are allowed if necessary, for instance
2697 @item gdb.@var{lang}
2699 Language-specific tests for all languages besides C. Examples are
2700 @file{gdb.c++} and @file{gdb.java}.
2702 @item gdb.@var{platform}
2704 Non-portable tests. The tests are specific to a specific configuration
2705 (host or target), such as HP-UX or eCos. Example is @file{gdb.hp}, for
2708 @item gdb.@var{compiler}
2710 Tests specific to a particular compiler. As of this writing (June
2711 1999), there aren't currently any groups of tests in this category that
2712 couldn't just as sensibly be made platform-specific, but one could
2713 imagine a gdb.gcc, for tests of GDB's handling of GCC extensions.
2715 @item gdb.@var{subsystem}
2717 Tests that exercise a specific GDB subsystem in more depth. For
2718 instance, @file{gdb.disasm} exercises various disassemblers, while
2719 @file{gdb.stabs} tests pathways through the stabs symbol reader.
2723 @section Writing Tests
2725 In many areas, the GDB tests are already quite comprehensive; you
2726 should be able to copy existing tests to handle new cases.
2728 You should try to use @code{gdb_test} whenever possible, since it
2729 includes cases to handle all the unexpected errors that might happen.
2730 However, it doesn't cost anything to add new test procedures; for
2731 instance, @file{gdb.base/exprs.exp} defines a @code{test_expr} that
2732 calls @code{gdb_test} multiple times.
2734 Only use @code{send_gdb} and @code{gdb_expect} when absolutely
2735 necessary, such as when GDB has several valid responses to a command.
2737 The source language programs do @emph{not} need to be in a consistent
2738 style. Since GDB is used to debug programs written in many different
2739 styles, it's worth having a mix of styles in the testsuite; for
2740 instance, some GDB bugs involving the display of source lines would
2741 never manifest themselves if the programs used GNU coding style
2748 Check the @file{README} file, it often has useful information that does not
2749 appear anywhere else in the directory.
2752 * Getting Started:: Getting started working on GDB
2753 * Debugging GDB:: Debugging GDB with itself
2756 @node Getting Started,,, Hints
2758 @section Getting Started
2760 GDB is a large and complicated program, and if you first starting to
2761 work on it, it can be hard to know where to start. Fortunately, if you
2762 know how to go about it, there are ways to figure out what is going on.
2764 This manual, the GDB Internals manual, has information which applies
2765 generally to many parts of GDB.
2767 Information about particular functions or data structures are located in
2768 comments with those functions or data structures. If you run across a
2769 function or a global variable which does not have a comment correctly
2770 explaining what is does, this can be thought of as a bug in GDB; feel
2771 free to submit a bug report, with a suggested comment if you can figure
2772 out what the comment should say. If you find a comment which is
2773 actually wrong, be especially sure to report that.
2775 Comments explaining the function of macros defined in host, target, or
2776 native dependent files can be in several places. Sometimes they are
2777 repeated every place the macro is defined. Sometimes they are where the
2778 macro is used. Sometimes there is a header file which supplies a
2779 default definition of the macro, and the comment is there. This manual
2780 also documents all the available macros.
2781 @c (@pxref{Host Conditionals}, @pxref{Target
2782 @c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete
2785 Start with the header files. Once you have some idea of how GDB's internal
2786 symbol tables are stored (see @file{symtab.h}, @file{gdbtypes.h}), you
2787 will find it much easier to understand the code which uses and creates
2788 those symbol tables.
2790 You may wish to process the information you are getting somehow, to
2791 enhance your understanding of it. Summarize it, translate it to another
2792 language, add some (perhaps trivial or non-useful) feature to GDB, use
2793 the code to predict what a test case would do and write the test case
2794 and verify your prediction, etc. If you are reading code and your eyes
2795 are starting to glaze over, this is a sign you need to use a more active
2798 Once you have a part of GDB to start with, you can find more
2799 specifically the part you are looking for by stepping through each
2800 function with the @code{next} command. Do not use @code{step} or you
2801 will quickly get distracted; when the function you are stepping through
2802 calls another function try only to get a big-picture understanding
2803 (perhaps using the comment at the beginning of the function being
2804 called) of what it does. This way you can identify which of the
2805 functions being called by the function you are stepping through is the
2806 one which you are interested in. You may need to examine the data
2807 structures generated at each stage, with reference to the comments in
2808 the header files explaining what the data structures are supposed to
2811 Of course, this same technique can be used if you are just reading the
2812 code, rather than actually stepping through it. The same general
2813 principle applies---when the code you are looking at calls something
2814 else, just try to understand generally what the code being called does,
2815 rather than worrying about all its details.
2817 A good place to start when tracking down some particular area is with a
2818 command which invokes that feature. Suppose you want to know how
2819 single-stepping works. As a GDB user, you know that the @code{step}
2820 command invokes single-stepping. The command is invoked via command
2821 tables (see @file{command.h}); by convention the function which actually
2822 performs the command is formed by taking the name of the command and
2823 adding @samp{_command}, or in the case of an @code{info} subcommand,
2824 @samp{_info}. For example, the @code{step} command invokes the
2825 @code{step_command} function and the @code{info display} command invokes
2826 @code{display_info}. When this convention is not followed, you might
2827 have to use @code{grep} or @kbd{M-x tags-search} in emacs, or run GDB on
2828 itself and set a breakpoint in @code{execute_command}.
2830 If all of the above fail, it may be appropriate to ask for information
2831 on @code{bug-gdb}. But @emph{never} post a generic question like ``I was
2832 wondering if anyone could give me some tips about understanding
2833 GDB''---if we had some magic secret we would put it in this manual.
2834 Suggestions for improving the manual are always welcome, of course.
2836 @node Debugging GDB,,,Hints
2838 @section Debugging GDB with itself
2840 If GDB is limping on your machine, this is the preferred way to get it
2841 fully functional. Be warned that in some ancient Unix systems, like
2842 Ultrix 4.2, a program can't be running in one process while it is being
2843 debugged in another. Rather than typing the command @code{@w{./gdb
2844 ./gdb}}, which works on Suns and such, you can copy @file{gdb} to
2845 @file{gdb2} and then type @code{@w{./gdb ./gdb2}}.
2847 When you run GDB in the GDB source directory, it will read a
2848 @file{.gdbinit} file that sets up some simple things to make debugging
2849 gdb easier. The @code{info} command, when executed without a subcommand
2850 in a GDB being debugged by gdb, will pop you back up to the top level
2851 gdb. See @file{.gdbinit} for details.
2853 If you use emacs, you will probably want to do a @code{make TAGS} after
2854 you configure your distribution; this will put the machine dependent
2855 routines for your local machine where they will be accessed first by
2858 Also, make sure that you've either compiled GDB with your local cc, or
2859 have run @code{fixincludes} if you are compiling with gcc.
2861 @section Submitting Patches
2863 Thanks for thinking of offering your changes back to the community of
2864 GDB users. In general we like to get well designed enhancements.
2865 Thanks also for checking in advance about the best way to transfer the
2868 The GDB maintainers will only install ``cleanly designed'' patches.
2869 This manual summarizes what we believe to be clean design for GDB.
2871 If the maintainers don't have time to put the patch in when it arrives,
2872 or if there is any question about a patch, it goes into a large queue
2873 with everyone else's patches and bug reports.
2875 The legal issue is that to incorporate substantial changes requires a
2876 copyright assignment from you and/or your employer, granting ownership
2877 of the changes to the Free Software Foundation. You can get the
2878 standard documents for doing this by sending mail to @code{gnu@@gnu.org}
2879 and asking for it. We recommend that people write in "All programs
2880 owned by the Free Software Foundation" as "NAME OF PROGRAM", so that
2881 changes in many programs (not just GDB, but GAS, Emacs, GCC, etc) can be
2882 contributed with only one piece of legalese pushed through the
2883 bureacracy and filed with the FSF. We can't start merging changes until
2884 this paperwork is received by the FSF (their rules, which we follow
2885 since we maintain it for them).
2887 Technically, the easiest way to receive changes is to receive each
2888 feature as a small context diff or unidiff, suitable for "patch". Each
2889 message sent to me should include the changes to C code and header files
2890 for a single feature, plus ChangeLog entries for each directory where
2891 files were modified, and diffs for any changes needed to the manuals
2892 (gdb/doc/gdb.texinfo or gdb/doc/gdbint.texinfo). If there are a lot of
2893 changes for a single feature, they can be split down into multiple
2896 In this way, if we read and like the feature, we can add it to the
2897 sources with a single patch command, do some testing, and check it in.
2898 If you leave out the ChangeLog, we have to write one. If you leave
2899 out the doc, we have to puzzle out what needs documenting. Etc.
2901 The reason to send each change in a separate message is that we will not
2902 install some of the changes. They'll be returned to you with questions
2903 or comments. If we're doing our job correctly, the message back to you
2904 will say what you have to fix in order to make the change acceptable.
2905 The reason to have separate messages for separate features is so that
2906 the acceptable changes can be installed while one or more changes are
2907 being reworked. If multiple features are sent in a single message, we
2908 tend to not put in the effort to sort out the acceptable changes from
2909 the unacceptable, so none of the features get installed until all are
2912 If this sounds painful or authoritarian, well, it is. But we get a lot
2913 of bug reports and a lot of patches, and many of them don't get
2914 installed because we don't have the time to finish the job that the bug
2915 reporter or the contributor could have done. Patches that arrive
2916 complete, working, and well designed, tend to get installed on the day
2917 they arrive. The others go into a queue and get installed as time
2918 permits, which, since the maintainers have many demands to meet, may not
2919 be for quite some time.
2921 Please send patches directly to the GDB maintainers at
2922 @code{gdb-patches@@sourceware.cygnus.com}.
2924 @section Obsolete Conditionals
2926 Fragments of old code in GDB sometimes reference or set the following
2927 configuration macros. They should not be used by new code, and old uses
2928 should be removed as those parts of the debugger are otherwise touched.
2932 @item STACK_END_ADDR
2933 This macro used to define where the end of the stack appeared, for use
2934 in interpreting core file formats that don't record this address in the
2935 core file itself. This information is now configured in BFD, and GDB
2936 gets the info portably from there. The values in GDB's configuration
2937 files should be moved into BFD configuration files (if needed there),
2938 and deleted from all of GDB's config files.
2940 Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
2941 is so old that it has never been converted to use BFD. Now that's old!
2943 @item PYRAMID_CONTROL_FRAME_DEBUGGING
2947 @item PYRAMID_PTRACE
2950 @item REG_STACK_SEGMENT