2 @setfilename gdbint.info
7 * Gdb-Internals: (gdbint). The GNU debugger's internals.
13 This file documents the internals of the GNU debugger @value{GDBN}.
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 @value{GDBN} Internals
39 @title @value{GDBN} 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.
66 @c TeX can handle the contents at the start but makeinfo 3.12 can not
72 @c Perhaps this should be the title of the document (but only for info,
73 @c not for TeX). Existing GNU manuals seem inconsistent on this point.
74 @top Scope of this Document
76 This document documents the internals of the GNU debugger, @value{GDBN}. It
77 includes description of @value{GDBN}'s key algorithms and operations, as well
78 as the mechanisms that adapt @value{GDBN} to specific hosts and targets.
88 * Target Architecture Definition::
89 * Target Vector Definition::
100 @chapter Requirements
102 Before diving into the internals, you should understand the formal
103 requirements and other expectations for @value{GDBN}. Although some of these may
104 seem obvious, there have been proposals for @value{GDBN} that have run counter to
107 First of all, @value{GDBN} is a debugger. It's not designed to be a front panel
108 for embedded systems. It's not a text editor. It's not a shell. It's
109 not a programming environment.
111 @value{GDBN} is an interactive tool. Although a batch mode is available, @value{GDBN}'s
112 primary role is to interact with a human programmer.
114 @value{GDBN} should be responsive to the user. A programmer hot on the trail of
115 a nasty bug, and operating under a looming deadline, is going to be very
116 impatient of everything, including the response time to debugger
119 @value{GDBN} should be relatively permissive, such as for expressions. While the
120 compiler should be picky (or have the option to be made picky), since
121 source code lives for a long time usually, the programmer doing
122 debugging shouldn't be spending time figuring out to mollify the
125 @value{GDBN} will be called upon to deal with really large programs. Executable
126 sizes of 50 to 100 megabytes occur regularly, and we've heard reports of
127 programs approaching 1 gigabyte in size.
129 @value{GDBN} should be able to run everywhere. No other debugger is available
130 for even half as many configurations as @value{GDBN} supports.
133 @node Overall Structure
135 @chapter Overall Structure
137 @value{GDBN} consists of three major subsystems: user interface, symbol handling
138 (the ``symbol side''), and target system handling (the ``target side'').
140 The user interface consists of several actual interfaces, plus
143 The symbol side consists of object file readers, debugging info
144 interpreters, symbol table management, source language expression
145 parsing, type and value printing.
147 The target side consists of execution control, stack frame analysis, and
148 physical target manipulation.
150 The target side/symbol side division is not formal, and there are a
151 number of exceptions. For instance, core file support involves symbolic
152 elements (the basic core file reader is in BFD) and target elements (it
153 supplies the contents of memory and the values of registers). Instead,
154 this division is useful for understanding how the minor subsystems
157 @section The Symbol Side
159 The symbolic side of @value{GDBN} can be thought of as ``everything you can do in
160 @value{GDBN} without having a live program running''. For instance, you can look
161 at the types of variables, and evaluate many kinds of expressions.
163 @section The Target Side
165 The target side of @value{GDBN} is the ``bits and bytes manipulator''. Although
166 it may make reference to symbolic info here and there, most of the
167 target side will run with only a stripped executable available -- or
168 even no executable at all, in remote debugging cases.
170 Operations such as disassembly, stack frame crawls, and register
171 display, are able to work with no symbolic info at all. In some cases,
172 such as disassembly, @value{GDBN} will use symbolic info to present addresses
173 relative to symbols rather than as raw numbers, but it will work either
176 @section Configurations
178 @dfn{Host} refers to attributes of the system where @value{GDBN} runs.
179 @dfn{Target} refers to the system where the program being debugged
180 executes. In most cases they are the same machine, in which case a
181 third type of @dfn{Native} attributes come into play.
183 Defines and include files needed to build on the host are host support.
184 Examples are tty support, system defined types, host byte order, host
187 Defines and information needed to handle the target format are target
188 dependent. Examples are the stack frame format, instruction set,
189 breakpoint instruction, registers, and how to set up and tear down the stack
192 Information that is only needed when the host and target are the same,
193 is native dependent. One example is Unix child process support; if the
194 host and target are not the same, doing a fork to start the target
195 process is a bad idea. The various macros needed for finding the
196 registers in the @code{upage}, running @code{ptrace}, and such are all
197 in the native-dependent files.
199 Another example of native-dependent code is support for features that
200 are really part of the target environment, but which require
201 @code{#include} files that are only available on the host system. Core
202 file handling and @code{setjmp} handling are two common cases.
204 When you want to make @value{GDBN} work ``native'' on a particular machine, you
205 have to include all three kinds of information.
212 @value{GDBN} uses a number of debugging-specific algorithms. They are often not
213 very complicated, but get lost in the thicket of special cases and
214 real-world issues. This chapter describes the basic algorithms and
215 mentions some of the specific target definitions that they use.
219 A frame is a construct that @value{GDBN} uses to keep track of calling and called
222 @code{FRAME_FP} in the machine description has no meaning to the
223 machine-independent part of @value{GDBN}, except that it is used when setting up
224 a new frame from scratch, as follows:
227 create_new_frame (read_register (FP_REGNUM), read_pc ()));
230 Other than that, all the meaning imparted to @code{FP_REGNUM} is
231 imparted by the machine-dependent code. So, @code{FP_REGNUM} can have
232 any value that is convenient for the code that creates new frames.
233 (@code{create_new_frame} calls @code{INIT_EXTRA_FRAME_INFO} if it is
234 defined; that is where you should use the @code{FP_REGNUM} value, if
235 your frames are nonstandard.)
237 Given a @value{GDBN} frame, define @code{FRAME_CHAIN} to determine the address of
238 the calling function's frame. This will be used to create a new @value{GDBN}
239 frame struct, and then @code{INIT_EXTRA_FRAME_INFO} and
240 @code{INIT_FRAME_PC} will be called for the new frame.
242 @section Breakpoint Handling
244 In general, a breakpoint is a user-designated location in the program
245 where the user wants to regain control if program execution ever reaches
248 There are two main ways to implement breakpoints; either as ``hardware''
249 breakpoints or as ``software'' breakpoints.
251 Hardware breakpoints are sometimes available as a builtin debugging
252 features with some chips. Typically these work by having dedicated
253 register into which the breakpoint address may be stored. If the PC
254 ever matches a value in a breakpoint registers, the CPU raises an
255 exception and reports it to @value{GDBN}. Another possibility is when an
256 emulator is in use; many emulators include circuitry that watches the
257 address lines coming out from the processor, and force it to stop if the
258 address matches a breakpoint's address. A third possibility is that the
259 target already has the ability to do breakpoints somehow; for instance,
260 a ROM monitor may do its own software breakpoints. So although these
261 are not literally ``hardware breakpoints'', from @value{GDBN}'s point of view
262 they work the same; @value{GDBN} need not do nothing more than set the breakpoint
263 and wait for something to happen.
265 Since they depend on hardware resources, hardware breakpoints may be
266 limited in number; when the user asks for more, @value{GDBN} will start trying to
267 set software breakpoints.
269 Software breakpoints require @value{GDBN} to do somewhat more work. The basic
270 theory is that @value{GDBN} will replace a program instruction with a trap,
271 illegal divide, or some other instruction that will cause an exception,
272 and then when it's encountered, @value{GDBN} will take the exception and stop the
273 program. When the user says to continue, @value{GDBN} will restore the original
274 instruction, single-step, re-insert the trap, and continue on.
276 Since it literally overwrites the program being tested, the program area
277 must be writeable, so this technique won't work on programs in ROM. It
278 can also distort the behavior of programs that examine themselves,
279 although the situation would be highly unusual.
281 Also, the software breakpoint instruction should be the smallest size of
282 instruction, so it doesn't overwrite an instruction that might be a jump
283 target, and cause disaster when the program jumps into the middle of the
284 breakpoint instruction. (Strictly speaking, the breakpoint must be no
285 larger than the smallest interval between instructions that may be jump
286 targets; perhaps there is an architecture where only even-numbered
287 instructions may jumped to.) Note that it's possible for an instruction
288 set not to have any instructions usable for a software breakpoint,
289 although in practice only the ARC has failed to define such an
292 The basic definition of the software breakpoint is the macro
295 Basic breakpoint object handling is in @file{breakpoint.c}. However,
296 much of the interesting breakpoint action is in @file{infrun.c}.
298 @section Single Stepping
300 @section Signal Handling
302 @section Thread Handling
304 @section Inferior Function Calls
306 @section Longjmp Support
308 @value{GDBN} has support for figuring out that the target is doing a
309 @code{longjmp} and for stopping at the target of the jump, if we are
310 stepping. This is done with a few specialized internal breakpoints,
311 which are visible in the @code{maint info breakpoint} command.
313 To make this work, you need to define a macro called
314 @code{GET_LONGJMP_TARGET}, which will examine the @code{jmp_buf}
315 structure and extract the longjmp target address. Since @code{jmp_buf}
316 is target specific, you will need to define it in the appropriate
317 @file{tm-@var{xyz}.h} file. Look in @file{tm-sun4os4.h} and
318 @file{sparc-tdep.c} for examples of how to do this.
322 @chapter User Interface
324 @value{GDBN} has several user interfaces. Although the command-line interface
325 is the most common and most familiar, there are others.
327 @section Command Interpreter
329 The command interpreter in @value{GDBN} is fairly simple. It is designed to
330 allow for the set of commands to be augmented dynamically, and also
331 has a recursive subcommand capability, where the first argument to
332 a command may itself direct a lookup on a different command list.
334 For instance, the @code{set} command just starts a lookup on the
335 @code{setlist} command list, while @code{set thread} recurses
336 to the @code{set_thread_cmd_list}.
338 To add commands in general, use @code{add_cmd}. @code{add_com} adds to
339 the main command list, and should be used for those commands. The usual
340 place to add commands is in the @code{_initialize_@var{xyz}} routines at
341 the ends of most source files.
343 Before removing commands from the command set it is a good idea to
344 deprecate them for some time. Use @code{deprecate_cmd} on commands or
345 aliases to set the deprecated flag. @code{deprecate_cmd} takes a
346 @code{struct cmd_list_element} as it's first argument. You can use the
347 return value from @code{add_com} or @code{add_cmd} to deprecate the
348 command immediately after it is created.
350 The first time a comamnd is used the user will be warned and offered a
351 replacement (if one exists). Note that the replacement string passed to
352 @code{deprecate_cmd} should be the full name of the command, i.e. the
353 entire string the user should type at the command line.
355 @section Console Printing
361 @code{libgdb} was an abortive project of years ago. The theory was to
362 provide an API to @value{GDBN}'s functionality.
364 @node Symbol Handling
366 @chapter Symbol Handling
368 Symbols are a key part of @value{GDBN}'s operation. Symbols include variables,
369 functions, and types.
371 @section Symbol Reading
373 @value{GDBN} reads symbols from ``symbol files''. The usual symbol file is the
374 file containing the program which @value{GDBN} is debugging. @value{GDBN} can be directed
375 to use a different file for symbols (with the @code{symbol-file}
376 command), and it can also read more symbols via the ``add-file'' and
377 ``load'' commands, or while reading symbols from shared libraries.
379 Symbol files are initially opened by code in @file{symfile.c} using the
380 BFD library. BFD identifies the type of the file by examining its
381 header. @code{find_sym_fns} then uses this identification to locate a
382 set of symbol-reading functions.
384 Symbol reading modules identify themselves to @value{GDBN} by calling
385 @code{add_symtab_fns} during their module initialization. The argument
386 to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the
387 name (or name prefix) of the symbol format, the length of the prefix,
388 and pointers to four functions. These functions are called at various
389 times to process symbol-files whose identification matches the specified
392 The functions supplied by each module are:
395 @item @var{xyz}_symfile_init(struct sym_fns *sf)
397 Called from @code{symbol_file_add} when we are about to read a new
398 symbol file. This function should clean up any internal state (possibly
399 resulting from half-read previous files, for example) and prepare to
400 read a new symbol file. Note that the symbol file which we are reading
401 might be a new "main" symbol file, or might be a secondary symbol file
402 whose symbols are being added to the existing symbol table.
404 The argument to @code{@var{xyz}_symfile_init} is a newly allocated
405 @code{struct sym_fns} whose @code{bfd} field contains the BFD for the
406 new symbol file being read. Its @code{private} field has been zeroed,
407 and can be modified as desired. Typically, a struct of private
408 information will be @code{malloc}'d, and a pointer to it will be placed
409 in the @code{private} field.
411 There is no result from @code{@var{xyz}_symfile_init}, but it can call
412 @code{error} if it detects an unavoidable problem.
414 @item @var{xyz}_new_init()
416 Called from @code{symbol_file_add} when discarding existing symbols.
417 This function need only handle the symbol-reading module's internal
418 state; the symbol table data structures visible to the rest of @value{GDBN} will
419 be discarded by @code{symbol_file_add}. It has no arguments and no
420 result. It may be called after @code{@var{xyz}_symfile_init}, if a new
421 symbol table is being read, or may be called alone if all symbols are
422 simply being discarded.
424 @item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)
426 Called from @code{symbol_file_add} to actually read the symbols from a
427 symbol-file into a set of psymtabs or symtabs.
429 @code{sf} points to the struct sym_fns originally passed to
430 @code{@var{xyz}_sym_init} for possible initialization. @code{addr} is
431 the offset between the file's specified start address and its true
432 address in memory. @code{mainline} is 1 if this is the main symbol
433 table being read, and 0 if a secondary symbol file (e.g. shared library
434 or dynamically loaded file) is being read.@refill
437 In addition, if a symbol-reading module creates psymtabs when
438 @var{xyz}_symfile_read is called, these psymtabs will contain a pointer
439 to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called
440 from any point in the @value{GDBN} symbol-handling code.
443 @item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst)
445 Called from @code{psymtab_to_symtab} (or the PSYMTAB_TO_SYMTAB macro) if
446 the psymtab has not already been read in and had its @code{pst->symtab}
447 pointer set. The argument is the psymtab to be fleshed-out into a
448 symtab. Upon return, pst->readin should have been set to 1, and
449 pst->symtab should contain a pointer to the new corresponding symtab, or
450 zero if there were no symbols in that part of the symbol file.
453 @section Partial Symbol Tables
455 @value{GDBN} has three types of symbol tables.
459 @item full symbol tables (symtabs). These contain the main information
460 about symbols and addresses.
462 @item partial symbol tables (psymtabs). These contain enough
463 information to know when to read the corresponding part of the full
466 @item minimal symbol tables (msymtabs). These contain information
467 gleaned from non-debugging symbols.
471 This section describes partial symbol tables.
473 A psymtab is constructed by doing a very quick pass over an executable
474 file's debugging information. Small amounts of information are
475 extracted -- enough to identify which parts of the symbol table will
476 need to be re-read and fully digested later, when the user needs the
477 information. The speed of this pass causes @value{GDBN} to start up very
478 quickly. Later, as the detailed rereading occurs, it occurs in small
479 pieces, at various times, and the delay therefrom is mostly invisible to
481 @c (@xref{Symbol Reading}.)
483 The symbols that show up in a file's psymtab should be, roughly, those
484 visible to the debugger's user when the program is not running code from
485 that file. These include external symbols and types, static symbols and
486 types, and enum values declared at file scope.
488 The psymtab also contains the range of instruction addresses that the
489 full symbol table would represent.
491 The idea is that there are only two ways for the user (or much of the
492 code in the debugger) to reference a symbol:
497 (e.g. execution stops at some address which is inside a function in this
498 file). The address will be noticed to be in the range of this psymtab,
499 and the full symtab will be read in. @code{find_pc_function},
500 @code{find_pc_line}, and other @code{find_pc_@dots{}} functions handle
504 (e.g. the user asks to print a variable, or set a breakpoint on a
505 function). Global names and file-scope names will be found in the
506 psymtab, which will cause the symtab to be pulled in. Local names will
507 have to be qualified by a global name, or a file-scope name, in which
508 case we will have already read in the symtab as we evaluated the
509 qualifier. Or, a local symbol can be referenced when we are "in" a
510 local scope, in which case the first case applies. @code{lookup_symbol}
511 does most of the work here.
515 The only reason that psymtabs exist is to cause a symtab to be read in
516 at the right moment. Any symbol that can be elided from a psymtab,
517 while still causing that to happen, should not appear in it. Since
518 psymtabs don't have the idea of scope, you can't put local symbols in
519 them anyway. Psymtabs don't have the idea of the type of a symbol,
520 either, so types need not appear, unless they will be referenced by
523 It is a bug for @value{GDBN} to behave one way when only a psymtab has been read,
524 and another way if the corresponding symtab has been read in. Such bugs
525 are typically caused by a psymtab that does not contain all the visible
526 symbols, or which has the wrong instruction address ranges.
528 The psymtab for a particular section of a symbol-file (objfile) could be
529 thrown away after the symtab has been read in. The symtab should always
530 be searched before the psymtab, so the psymtab will never be used (in a
531 bug-free environment). Currently, psymtabs are allocated on an obstack,
532 and all the psymbols themselves are allocated in a pair of large arrays
533 on an obstack, so there is little to be gained by trying to free them
534 unless you want to do a lot more work.
538 Fundamental Types (e.g., FT_VOID, FT_BOOLEAN).
540 These are the fundamental types that @value{GDBN} uses internally. Fundamental
541 types from the various debugging formats (stabs, ELF, etc) are mapped
542 into one of these. They are basically a union of all fundamental types
543 that gdb knows about for all the languages that @value{GDBN} knows about.
545 Type Codes (e.g., TYPE_CODE_PTR, TYPE_CODE_ARRAY).
547 Each time @value{GDBN} builds an internal type, it marks it with one of these
548 types. The type may be a fundamental type, such as TYPE_CODE_INT, or a
549 derived type, such as TYPE_CODE_PTR which is a pointer to another type.
550 Typically, several FT_* types map to one TYPE_CODE_* type, and are
551 distinguished by other members of the type struct, such as whether the
552 type is signed or unsigned, and how many bits it uses.
554 Builtin Types (e.g., builtin_type_void, builtin_type_char).
556 These are instances of type structs that roughly correspond to
557 fundamental types and are created as global types for @value{GDBN} to use for
558 various ugly historical reasons. We eventually want to eliminate these.
559 Note for example that builtin_type_int initialized in gdbtypes.c is
560 basically the same as a TYPE_CODE_INT type that is initialized in
561 c-lang.c for an FT_INTEGER fundamental type. The difference is that the
562 builtin_type is not associated with any particular objfile, and only one
563 instance exists, while c-lang.c builds as many TYPE_CODE_INT types as
564 needed, with each one associated with some particular objfile.
566 @section Object File Formats
570 The @file{a.out} format is the original file format for Unix. It
571 consists of three sections: text, data, and bss, which are for program
572 code, initialized data, and uninitialized data, respectively.
574 The @file{a.out} format is so simple that it doesn't have any reserved
575 place for debugging information. (Hey, the original Unix hackers used
576 @file{adb}, which is a machine-language debugger.) The only debugging
577 format for @file{a.out} is stabs, which is encoded as a set of normal
578 symbols with distinctive attributes.
580 The basic @file{a.out} reader is in @file{dbxread.c}.
584 The COFF format was introduced with System V Release 3 (SVR3) Unix.
585 COFF files may have multiple sections, each prefixed by a header. The
586 number of sections is limited.
588 The COFF specification includes support for debugging. Although this
589 was a step forward, the debugging information was woefully limited. For
590 instance, it was not possible to represent code that came from an
593 The COFF reader is in @file{coffread.c}.
597 ECOFF is an extended COFF originally introduced for Mips and Alpha
600 The basic ECOFF reader is in @file{mipsread.c}.
604 The IBM RS/6000 running AIX uses an object file format called XCOFF.
605 The COFF sections, symbols, and line numbers are used, but debugging
606 symbols are dbx-style stabs whose strings are located in the
607 @samp{.debug} section (rather than the string table). For more
608 information, see @xref{Top,,,stabs,The Stabs Debugging Format}.
610 The shared library scheme has a clean interface for figuring out what
611 shared libraries are in use, but the catch is that everything which
612 refers to addresses (symbol tables and breakpoints at least) needs to be
613 relocated for both shared libraries and the main executable. At least
614 using the standard mechanism this can only be done once the program has
615 been run (or the core file has been read).
619 Windows 95 and NT use the PE (Portable Executable) format for their
620 executables. PE is basically COFF with additional headers.
622 While BFD includes special PE support, @value{GDBN} needs only the basic
627 The ELF format came with System V Release 4 (SVR4) Unix. ELF is similar
628 to COFF in being organized into a number of sections, but it removes
629 many of COFF's limitations.
631 The basic ELF reader is in @file{elfread.c}.
635 SOM is HP's object file and debug format (not to be confused with IBM's
636 SOM, which is a cross-language ABI).
638 The SOM reader is in @file{hpread.c}.
640 @subsection Other File Formats
642 Other file formats that have been supported by @value{GDBN} include Netware
643 Loadable Modules (@file{nlmread.c}.
645 @section Debugging File Formats
647 This section describes characteristics of debugging information that
648 are independent of the object file format.
652 @code{stabs} started out as special symbols within the @code{a.out}
653 format. Since then, it has been encapsulated into other file
654 formats, such as COFF and ELF.
656 While @file{dbxread.c} does some of the basic stab processing,
657 including for encapsulated versions, @file{stabsread.c} does
662 The basic COFF definition includes debugging information. The level
663 of support is minimal and non-extensible, and is not often used.
665 @subsection Mips debug (Third Eye)
667 ECOFF includes a definition of a special debug format.
669 The file @file{mdebugread.c} implements reading for this format.
673 DWARF 1 is a debugging format that was originally designed to be
674 used with ELF in SVR4 systems.
680 @c If defined, these are the producer strings in a DWARF 1 file. All of
681 @c these have reasonable defaults already.
683 The DWARF 1 reader is in @file{dwarfread.c}.
687 DWARF 2 is an improved but incompatible version of DWARF 1.
689 The DWARF 2 reader is in @file{dwarf2read.c}.
693 Like COFF, the SOM definition includes debugging information.
695 @section Adding a New Symbol Reader to @value{GDBN}
697 If you are using an existing object file format (a.out, COFF, ELF, etc),
698 there is probably little to be done.
700 If you need to add a new object file format, you must first add it to
701 BFD. This is beyond the scope of this document.
703 You must then arrange for the BFD code to provide access to the
704 debugging symbols. Generally @value{GDBN} will have to call swapping routines
705 from BFD and a few other BFD internal routines to locate the debugging
706 information. As much as possible, @value{GDBN} should not depend on the BFD
707 internal data structures.
709 For some targets (e.g., COFF), there is a special transfer vector used
710 to call swapping routines, since the external data structures on various
711 platforms have different sizes and layouts. Specialized routines that
712 will only ever be implemented by one object file format may be called
713 directly. This interface should be described in a file
714 @file{bfd/libxyz.h}, which is included by @value{GDBN}.
717 @node Language Support
719 @chapter Language Support
721 @value{GDBN}'s language support is mainly driven by the symbol reader, although
722 it is possible for the user to set the source language manually.
724 @value{GDBN} chooses the source language by looking at the extension of the file
725 recorded in the debug info; @code{.c} means C, @code{.f} means Fortran,
726 etc. It may also use a special-purpose language identifier if the debug
727 format supports it, such as DWARF.
729 @section Adding a Source Language to @value{GDBN}
731 To add other languages to @value{GDBN}'s expression parser, follow the following
735 @item Create the expression parser.
737 This should reside in a file @file{@var{lang}-exp.y}. Routines for
738 building parsed expressions into a @samp{union exp_element} list are in
741 Since we can't depend upon everyone having Bison, and YACC produces
742 parsers that define a bunch of global names, the following lines
743 @emph{must} be included at the top of the YACC parser, to prevent the
744 various parsers from defining the same global names:
747 #define yyparse @var{lang}_parse
748 #define yylex @var{lang}_lex
749 #define yyerror @var{lang}_error
750 #define yylval @var{lang}_lval
751 #define yychar @var{lang}_char
752 #define yydebug @var{lang}_debug
753 #define yypact @var{lang}_pact
754 #define yyr1 @var{lang}_r1
755 #define yyr2 @var{lang}_r2
756 #define yydef @var{lang}_def
757 #define yychk @var{lang}_chk
758 #define yypgo @var{lang}_pgo
759 #define yyact @var{lang}_act
760 #define yyexca @var{lang}_exca
761 #define yyerrflag @var{lang}_errflag
762 #define yynerrs @var{lang}_nerrs
765 At the bottom of your parser, define a @code{struct language_defn} and
766 initialize it with the right values for your language. Define an
767 @code{initialize_@var{lang}} routine and have it call
768 @samp{add_language(@var{lang}_language_defn)} to tell the rest of @value{GDBN}
769 that your language exists. You'll need some other supporting variables
770 and functions, which will be used via pointers from your
771 @code{@var{lang}_language_defn}. See the declaration of @code{struct
772 language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
773 for more information.
775 @item Add any evaluation routines, if necessary
777 If you need new opcodes (that represent the operations of the language),
778 add them to the enumerated type in @file{expression.h}. Add support
779 code for these operations in @code{eval.c:evaluate_subexp()}. Add cases
780 for new opcodes in two functions from @file{parse.c}:
781 @code{prefixify_subexp()} and @code{length_of_subexp()}. These compute
782 the number of @code{exp_element}s that a given operation takes up.
784 @item Update some existing code
786 Add an enumerated identifier for your language to the enumerated type
787 @code{enum language} in @file{defs.h}.
789 Update the routines in @file{language.c} so your language is included.
790 These routines include type predicates and such, which (in some cases)
791 are language dependent. If your language does not appear in the switch
792 statement, an error is reported.
794 Also included in @file{language.c} is the code that updates the variable
795 @code{current_language}, and the routines that translate the
796 @code{language_@var{lang}} enumerated identifier into a printable
799 Update the function @code{_initialize_language} to include your
800 language. This function picks the default language upon startup, so is
801 dependent upon which languages that @value{GDBN} is built for.
803 Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
804 code so that the language of each symtab (source file) is set properly.
805 This is used to determine the language to use at each stack frame level.
806 Currently, the language is set based upon the extension of the source
807 file. If the language can be better inferred from the symbol
808 information, please set the language of the symtab in the symbol-reading
811 Add helper code to @code{expprint.c:print_subexp()} to handle any new
812 expression opcodes you have added to @file{expression.h}. Also, add the
813 printed representations of your operators to @code{op_print_tab}.
815 @item Add a place of call
817 Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
818 @code{parse.c:parse_exp_1()}.
820 @item Use macros to trim code
822 The user has the option of building @value{GDBN} for some or all of the
823 languages. If the user decides to build @value{GDBN} for the language
824 @var{lang}, then every file dependent on @file{language.h} will have the
825 macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to
826 leave out large routines that the user won't need if he or she is not
829 Note that you do not need to do this in your YACC parser, since if @value{GDBN}
830 is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
831 compiled form of your parser) is not linked into @value{GDBN} at all.
833 See the file @file{configure.in} for how @value{GDBN} is configured for different
836 @item Edit @file{Makefile.in}
838 Add dependencies in @file{Makefile.in}. Make sure you update the macro
839 variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
840 not get linked in, or, worse yet, it may not get @code{tar}red into the
846 @node Host Definition
848 @chapter Host Definition
850 With the advent of autoconf, it's rarely necessary to have host
851 definition machinery anymore.
853 @section Adding a New Host
855 Most of @value{GDBN}'s host configuration support happens via autoconf. It
856 should be rare to need new host-specific definitions. @value{GDBN} still uses
857 the host-specific definitions and files listed below, but these mostly
858 exist for historical reasons, and should eventually disappear.
860 Several files control @value{GDBN}'s configuration for host systems:
864 @item gdb/config/@var{arch}/@var{xyz}.mh
865 Specifies Makefile fragments needed when hosting on machine @var{xyz}.
866 In particular, this lists the required machine-dependent object files,
867 by defining @samp{XDEPFILES=@dots{}}. Also specifies the header file
868 which describes host @var{xyz}, by defining @code{XM_FILE=
869 xm-@var{xyz}.h}. You can also define @code{CC}, @code{SYSV_DEFINE},
870 @code{XM_CFLAGS}, @code{XM_ADD_FILES}, @code{XM_CLIBS}, @code{XM_CDEPS},
871 etc.; see @file{Makefile.in}.
873 @item gdb/config/@var{arch}/xm-@var{xyz}.h
874 (@file{xm.h} is a link to this file, created by configure). Contains C
875 macro definitions describing the host system environment, such as byte
876 order, host C compiler and library.
878 @item gdb/@var{xyz}-xdep.c
879 Contains any miscellaneous C code required for this machine as a host.
880 On most machines it doesn't exist at all. If it does exist, put
881 @file{@var{xyz}-xdep.o} into the @code{XDEPFILES} line in
882 @file{gdb/config/@var{arch}/@var{xyz}.mh}.
886 @subheading Generic Host Support Files
888 There are some ``generic'' versions of routines that can be used by
889 various systems. These can be customized in various ways by macros
890 defined in your @file{xm-@var{xyz}.h} file. If these routines work for
891 the @var{xyz} host, you can just include the generic file's name (with
892 @samp{.o}, not @samp{.c}) in @code{XDEPFILES}.
894 Otherwise, if your machine needs custom support routines, you will need
895 to write routines that perform the same functions as the generic file.
896 Put them into @code{@var{xyz}-xdep.c}, and put @code{@var{xyz}-xdep.o}
897 into @code{XDEPFILES}.
902 This contains serial line support for Unix systems. This is always
903 included, via the makefile variable @code{SER_HARDWIRE}; override this
904 variable in the @file{.mh} file to avoid it.
907 This contains serial line support for 32-bit programs running under DOS,
908 using the GO32 execution environment.
911 This contains generic TCP support using sockets.
915 @section Host Conditionals
917 When @value{GDBN} is configured and compiled, various macros are defined or left
918 undefined, to control compilation based on the attributes of the host
919 system. These macros and their meanings (or if the meaning is not
920 documented here, then one of the source files where they are used is
925 @item @value{GDBN}INIT_FILENAME
926 The default name of @value{GDBN}'s initialization file (normally @file{.gdbinit}).
928 @item MEM_FNS_DECLARED
929 Your host config file defines this if it includes declarations of
930 @code{memcpy} and @code{memset}. Define this to avoid conflicts between
931 the native include files and the declarations in @file{defs.h}.
934 This macro is deprecated.
937 Define this if your system does not have a @code{<sys/file.h>}.
939 @item SIGWINCH_HANDLER
940 If your host defines @code{SIGWINCH}, you can define this to be the name
941 of a function to be called if @code{SIGWINCH} is received.
943 @item SIGWINCH_HANDLER_BODY
944 Define this to expand into code that will define the function named by
945 the expansion of @code{SIGWINCH_HANDLER}.
947 @item ALIGN_STACK_ON_STARTUP
948 Define this if your system is of a sort that will crash in
949 @code{tgetent} if the stack happens not to be longword-aligned when
950 @code{main} is called. This is a rare situation, but is known to occur
951 on several different types of systems.
953 @item CRLF_SOURCE_FILES
954 Define this if host files use @code{\r\n} rather than @code{\n} as a
955 line terminator. This will cause source file listings to omit @code{\r}
956 characters when printing and it will allow \r\n line endings of files
957 which are "sourced" by gdb. It must be possible to open files in binary
958 mode using @code{O_BINARY} or, for fopen, @code{"rb"}.
961 The default value of the prompt string (normally @code{"(gdb) "}).
964 The name of the generic TTY device, defaults to @code{"/dev/tty"}.
966 @item FCLOSE_PROVIDED
967 Define this if the system declares @code{fclose} in the headers included
968 in @code{defs.h}. This isn't needed unless your compiler is unusually
972 Define this if binary files are opened the same way as text files.
974 @item GETENV_PROVIDED
975 Define this if the system declares @code{getenv} in its headers included
976 in @code{defs.h}. This isn't needed unless your compiler is unusually
980 In some cases, use the system call @code{mmap} for reading symbol
981 tables. For some machines this allows for sharing and quick updates.
983 @item HAVE_SIGSETMASK
984 Define this if the host system has job control, but does not define
985 @code{sigsetmask()}. Currently, this is only true of the RS/6000.
988 Define this if the host system has @code{termio.h}.
990 @item HOST_BYTE_ORDER
991 The ordering of bytes in the host. This must be defined to be either
992 @code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}.
999 Values for host-side constants.
1002 Substitute for isatty, if not available.
1005 This is the longest integer type available on the host. If not defined,
1006 it will default to @code{long long} or @code{long}, depending on
1007 @code{CC_HAS_LONG_LONG}.
1009 @item CC_HAS_LONG_LONG
1010 Define this if the host C compiler supports ``long long''. This is set
1011 by the configure script.
1013 @item PRINTF_HAS_LONG_LONG
1014 Define this if the host can handle printing of long long integers via
1015 the printf format directive ``ll''. This is set by the configure script.
1017 @item HAVE_LONG_DOUBLE
1018 Define this if the host C compiler supports ``long double''. This is
1019 set by the configure script.
1021 @item PRINTF_HAS_LONG_DOUBLE
1022 Define this if the host can handle printing of long double float-point
1023 numbers via the printf format directive ``Lg''. This is set by the
1026 @item SCANF_HAS_LONG_DOUBLE
1027 Define this if the host can handle the parsing of long double
1028 float-point numbers via the scanf format directive directive
1029 ``Lg''. This is set by the configure script.
1031 @item LSEEK_NOT_LINEAR
1032 Define this if @code{lseek (n)} does not necessarily move to byte number
1033 @code{n} in the file. This is only used when reading source files. It
1034 is normally faster to define @code{CRLF_SOURCE_FILES} when possible.
1037 This macro is used as the argument to lseek (or, most commonly,
1038 bfd_seek). FIXME, should be replaced by SEEK_SET instead, which is the
1041 @item MALLOC_INCOMPATIBLE
1042 Define this if the system's prototype for @code{malloc} differs from the
1043 @sc{ANSI} definition.
1045 @item MMAP_BASE_ADDRESS
1046 When using HAVE_MMAP, the first mapping should go at this address.
1048 @item MMAP_INCREMENT
1049 when using HAVE_MMAP, this is the increment between mappings.
1051 @item NEED_POSIX_SETPGID
1052 Define this to use the POSIX version of @code{setpgid} to determine
1053 whether job control is available.
1056 If defined, this should be one or more tokens, such as @code{volatile},
1057 that can be used in both the declaration and definition of functions to
1058 indicate that they never return. The default is already set correctly
1059 if compiling with GCC. This will almost never need to be defined.
1062 If defined, this should be one or more tokens, such as
1063 @code{__attribute__ ((noreturn))}, that can be used in the declarations
1064 of functions to indicate that they never return. The default is already
1065 set correctly if compiling with GCC. This will almost never need to be
1068 @item USE_GENERIC_DUMMY_FRAMES
1069 Define this to 1 if the target is using the generic inferior function
1070 call code. See @code{blockframe.c} for more information.
1073 @value{GDBN} will use the @code{mmalloc} library for memory allocation for symbol
1074 reading if this symbol is defined. Be careful defining it since there
1075 are systems on which @code{mmalloc} does not work for some reason. One
1076 example is the DECstation, where its RPC library can't cope with our
1077 redefinition of @code{malloc} to call @code{mmalloc}. When defining
1078 @code{USE_MMALLOC}, you will also have to set @code{MMALLOC} in the
1079 Makefile, to point to the mmalloc library. This define is set when you
1080 configure with --with-mmalloc.
1083 Define this if you are using @code{mmalloc}, but don't want the overhead
1084 of checking the heap with @code{mmcheck}. Note that on some systems,
1085 the C runtime makes calls to malloc prior to calling @code{main}, and if
1086 @code{free} is ever called with these pointers after calling
1087 @code{mmcheck} to enable checking, a memory corruption abort is certain
1088 to occur. These systems can still use mmalloc, but must define
1092 Define this to 1 if the C runtime allocates memory prior to
1093 @code{mmcheck} being called, but that memory is never freed so we don't
1094 have to worry about it triggering a memory corruption abort. The
1095 default is 0, which means that @code{mmcheck} will only install the heap
1096 checking functions if there has not yet been any memory allocation
1097 calls, and if it fails to install the functions, gdb will issue a
1098 warning. This is currently defined if you configure using
1101 @item NO_SIGINTERRUPT
1102 Define this to indicate that siginterrupt() is not available.
1105 Define if this is not in a system .h file.
1109 Define these to appropriate value for the system lseek(), if not already
1113 This is the signal for stopping @value{GDBN}. Defaults to SIGTSTP. (Only
1114 redefined for the Convex.)
1117 Define this if the interior's tty should be opened with the O_NOCTTY
1118 flag. (FIXME: This should be a native-only flag, but @file{inflow.c} is
1122 Means that System V (prior to SVR4) include files are in use. (FIXME:
1123 This symbol is abused in @file{infrun.c}, @file{regex.c},
1124 @file{remote-nindy.c}, and @file{utils.c} for other things, at the
1128 Define this to help placate lint in some situations.
1131 Define this to override the defaults of @code{__volatile__} or
1137 @node Target Architecture Definition
1139 @chapter Target Architecture Definition
1141 @value{GDBN}'s target architecture defines what sort of machine-language programs
1142 @value{GDBN} can work with, and how it works with them.
1144 At present, the target architecture definition consists of a number of C
1147 @section Registers and Memory
1149 @value{GDBN}'s model of the target machine is rather simple. @value{GDBN} assumes the
1150 machine includes a bank of registers and a block of memory. Each
1151 register may have a different size.
1153 @value{GDBN} does not have a magical way to match up with the compiler's idea of
1154 which registers are which; however, it is critical that they do match up
1155 accurately. The only way to make this work is to get accurate
1156 information about the order that the compiler uses, and to reflect that
1157 in the @code{REGISTER_NAME} and related macros.
1159 @value{GDBN} can handle big-endian, little-endian, and bi-endian architectures.
1161 @section Pointers Are Not Always Addresses
1162 @cindex pointer representation
1163 @cindex address representation
1164 @cindex word-addressed machines
1165 @cindex separate data and code address spaces
1166 @cindex spaces, separate data and code address
1167 @cindex address spaces, separate data and code
1168 @cindex code pointers, word-addressed
1169 @cindex converting between pointers and addresses
1170 @cindex D10V addresses
1172 On almost all 32-bit architectures, the representation of a pointer is
1173 indistinguishable from the representation of some fixed-length number
1174 whose value is the byte address of the object pointed to. On such
1175 machines, the words `pointer' and `address' can be used interchangeably.
1176 However, architectures with smaller word sizes are often cramped for
1177 address space, so they may choose a pointer representation that breaks this
1178 identity, and allows a larger code address space.
1180 For example, the Mitsubishi D10V is a 16-bit VLIW processor whose
1181 instructions are 32 bits long@footnote{Some D10V instructions are
1182 actually pairs of 16-bit sub-instructions. However, since you can't
1183 jump into the middle of such a pair, code addresses can only refer to
1184 full 32 bit instructions, which is what matters in this explanation.}.
1185 If the D10V used ordinary byte addresses to refer to code locations,
1186 then the processor would only be able to address 64kb of instructions.
1187 However, since instructions must be aligned on four-byte boundaries, the
1188 low two bits of any valid instruction's byte address are always zero ---
1189 byte addresses waste two bits. So instead of byte addresses, the D10V
1190 uses word addresses --- byte addresses shifted right two bits --- to
1191 refer to code. Thus, the D10V can use 16-bit words to address 256kb of
1194 However, this means that code pointers and data pointers have different
1195 forms on the D10V. The 16-bit word @code{0xC020} refers to byte address
1196 @code{0xC020} when used as a data address, but refers to byte address
1197 @code{0x30080} when used as a code address.
1199 (The D10V also uses separate code and data address spaces, which also
1200 affects the correspondence between pointers and addresses, but we're
1201 going to ignore that here; this example is already too long.)
1203 To cope with architectures like this --- the D10V is not the only one!
1204 --- @value{GDBN} tries to distinguish between @dfn{addresses}, which are
1205 byte numbers, and @dfn{pointers}, which are the target's representation
1206 of an address of a particular type of data. In the example above,
1207 @code{0xC020} is the pointer, which refers to one of the addresses
1208 @code{0xC020} or @code{0x30080}, depending on the type imposed upon it.
1209 @value{GDBN} provides functions for turning a pointer into an address
1210 and vice versa, in the appropriate way for the current architecture.
1212 Unfortunately, since addresses and pointers are identical on almost all
1213 processors, this distinction tends to bit-rot pretty quickly. Thus,
1214 each time you port @value{GDBN} to an architecture which does
1215 distinguish between pointers and addresses, you'll probably need to
1216 clean up some architecture-independent code.
1218 Here are functions which convert between pointers and addresses:
1220 @deftypefun CORE_ADDR extract_typed_address (void *@var{buf}, struct type *@var{type})
1221 Treat the bytes at @var{buf} as a pointer or reference of type
1222 @var{type}, and return the address it represents, in a manner
1223 appropriate for the current architecture. This yields an address
1224 @value{GDBN} can use to read target memory, disassemble, etc. Note that
1225 @var{buf} refers to a buffer in @value{GDBN}'s memory, not the
1228 For example, if the current architecture is the Intel x86, this function
1229 extracts a little-endian integer of the appropriate length from
1230 @var{buf} and returns it. However, if the current architecture is the
1231 D10V, this function will return a 16-bit integer extracted from
1232 @var{buf}, multiplied by four if @var{type} is a pointer to a function.
1234 If @var{type} is not a pointer or reference type, then this function
1235 will signal an internal error.
1238 @deftypefun CORE_ADDR store_typed_address (void *@var{buf}, struct type *@var{type}, CORE_ADDR @var{addr})
1239 Store the address @var{addr} in @var{buf}, in the proper format for a
1240 pointer of type @var{type} in the current architecture. Note that
1241 @var{buf} refers to a buffer in @value{GDBN}'s memory, not the
1244 For example, if the current architecture is the Intel x86, this function
1245 stores @var{addr} unmodified as a little-endian integer of the
1246 appropriate length in @var{buf}. However, if the current architecture
1247 is the D10V, this function divides @var{addr} by four if @var{type} is
1248 a pointer to a function, and then stores it in @var{buf}.
1250 If @var{type} is not a pointer or reference type, then this function
1251 will signal an internal error.
1254 @deftypefun CORE_ADDR value_as_pointer (value_ptr @var{val})
1255 Assuming that @var{val} is a pointer, return the address it represents,
1256 as appropriate for the current architecture.
1258 This function actually works on integral values, as well as pointers.
1259 For pointers, it performs architecture-specific conversions as
1260 described above for @code{extract_typed_address}.
1263 @deftypefun CORE_ADDR value_from_pointer (struct type *@var{type}, CORE_ADDR @var{addr})
1264 Create and return a value representing a pointer of type @var{type} to
1265 the address @var{addr}, as appropriate for the current architecture.
1266 This function performs architecture-specific conversions as described
1267 above for @code{store_typed_address}.
1271 @value{GDBN} also provides functions that do the same tasks, but assume
1272 that pointers are simply byte addresses; they aren't sensitive to the
1273 current architecture, beyond knowing the appropriate endianness.
1275 @deftypefun CORE_ADDR extract_address (void *@var{addr}, int len)
1276 Extract a @var{len}-byte number from @var{addr} in the appropriate
1277 endianness for the current architecture, and return it. Note that
1278 @var{addr} refers to @value{GDBN}'s memory, not the inferior's.
1280 This function should only be used in architecture-specific code; it
1281 doesn't have enough information to turn bits into a true address in the
1282 appropriate way for the current architecture. If you can, use
1283 @code{extract_typed_address} instead.
1286 @deftypefun void store_address (void *@var{addr}, int @var{len}, LONGEST @var{val})
1287 Store @var{val} at @var{addr} as a @var{len}-byte integer, in the
1288 appropriate endianness for the current architecture. Note that
1289 @var{addr} refers to a buffer in @value{GDBN}'s memory, not the
1292 This function should only be used in architecture-specific code; it
1293 doesn't have enough information to turn a true address into bits in the
1294 appropriate way for the current architecture. If you can, use
1295 @code{store_typed_address} instead.
1299 Here are some macros which architectures can define to indicate the
1300 relationship between pointers and addresses. These have default
1301 definitions, appropriate for architectures on which all pointers are
1302 simple byte addresses.
1304 @deftypefn {Target Macro} CORE_ADDR POINTER_TO_ADDRESS (struct type *@var{type}, char *@var{buf})
1305 Assume that @var{buf} holds a pointer of type @var{type}, in the
1306 appropriate format for the current architecture. Return the byte
1307 address the pointer refers to.
1309 This function may safely assume that @var{type} is either a pointer or a
1313 @deftypefn {Target Macro} void ADDRESS_TO_POINTER (struct type *@var{type}, char *@var{buf}, CORE_ADDR @var{addr})
1314 Store in @var{buf} a pointer of type @var{type} representing the address
1315 @var{addr}, in the appropriate format for the current architecture.
1317 This function may safely assume that @var{type} is either a pointer or a
1322 @section Using Different Register and Memory Data Representations
1323 @cindex raw representation
1324 @cindex virtual representation
1325 @cindex representations, raw and virtual
1326 @cindex register data formats, converting
1327 @cindex @code{struct value}, converting register contents to
1329 Some architectures use one representation for a value when it lives in a
1330 register, but use a different representation when it lives in memory.
1331 In @value{GDBN}'s terminology, the @dfn{raw} representation is the one used in
1332 the target registers, and the @dfn{virtual} representation is the one
1333 used in memory, and within @value{GDBN} @code{struct value} objects.
1335 For almost all data types on almost all architectures, the virtual and
1336 raw representations are identical, and no special handling is needed.
1337 However, they do occasionally differ. For example:
1342 The x86 architecture supports an 80-bit long double type. However, when
1343 we store those values in memory, they occupy twelve bytes: the
1344 floating-point number occupies the first ten, and the final two bytes
1345 are unused. This keeps the values aligned on four-byte boundaries,
1346 allowing more efficient access. Thus, the x86 80-bit floating-point
1347 type is the raw representation, and the twelve-byte loosely-packed
1348 arrangement is the virtual representation.
1351 Some 64-bit MIPS targets present 32-bit registers to @value{GDBN} as 64-bit
1352 registers, with garbage in their upper bits. @value{GDBN} ignores the top 32
1353 bits. Thus, the 64-bit form, with garbage in the upper 32 bits, is the
1354 raw representation, and the trimmed 32-bit representation is the
1355 virtual representation.
1359 In general, the raw representation is determined by the architecture, or
1360 @value{GDBN}'s interface to the architecture, while the virtual representation
1361 can be chosen for @value{GDBN}'s convenience. @value{GDBN}'s register file,
1362 @code{registers}, holds the register contents in raw format, and the @value{GDBN}
1363 remote protocol transmits register values in raw format.
1365 Your architecture may define the following macros to request raw /
1366 virtual conversions:
1368 @deftypefn {Target Macro} int REGISTER_CONVERTIBLE (int @var{reg})
1369 Return non-zero if register number @var{reg}'s value needs different raw
1370 and virtual formats.
1372 You should not use @code{REGISTER_CONVERT_TO_VIRTUAL} for a register
1373 unless this macro returns a non-zero value for that register.
1376 @deftypefn {Target Macro} int REGISTER_RAW_SIZE (int @var{reg})
1377 The size of register number @var{reg}'s raw value. This is the number
1378 of bytes the register will occupy in @code{registers}, or in a @value{GDBN}
1379 remote protocol packet.
1382 @deftypefn {Target Macro} int REGISTER_VIRTUAL_SIZE (int @var{reg})
1383 The size of register number @var{reg}'s value, in its virtual format.
1384 This is the size a @code{struct value}'s buffer will have, holding that
1388 @deftypefn {Target Macro} struct type *REGISTER_VIRTUAL_TYPE (int @var{reg})
1389 This is the type of the virtual representation of register number
1390 @var{reg}. Note that there is no need for a macro giving a type for the
1391 register's raw form; once the register's value has been obtained, @value{GDBN}
1392 always uses the virtual form.
1395 @deftypefn {Target Macro} void REGISTER_CONVERT_TO_VIRTUAL (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to})
1396 Convert the value of register number @var{reg} to @var{type}, which
1397 should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
1398 at @var{from} holds the register's value in raw format; the macro should
1399 convert the value to virtual format, and place it at @var{to}.
1401 Note that @code{REGISTER_CONVERT_TO_VIRTUAL} and
1402 @code{REGISTER_CONVERT_TO_RAW} take their @var{reg} and @var{type}
1403 arguments in different orders.
1405 You should only use @code{REGISTER_CONVERT_TO_VIRTUAL} with registers
1406 for which the @code{REGISTER_CONVERTIBLE} macro returns a non-zero
1410 @deftypefn {Target Macro} void REGISTER_CONVERT_TO_RAW (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to})
1411 Convert the value of register number @var{reg} to @var{type}, which
1412 should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
1413 at @var{from} holds the register's value in raw format; the macro should
1414 convert the value to virtual format, and place it at @var{to}.
1416 Note that REGISTER_CONVERT_TO_VIRTUAL and REGISTER_CONVERT_TO_RAW take
1417 their @var{reg} and @var{type} arguments in different orders.
1421 @section Frame Interpretation
1423 @section Inferior Call Setup
1425 @section Compiler Characteristics
1427 @section Target Conditionals
1429 This section describes the macros that you can use to define the target
1434 @item ADDITIONAL_OPTIONS
1435 @item ADDITIONAL_OPTION_CASES
1436 @item ADDITIONAL_OPTION_HANDLER
1437 @item ADDITIONAL_OPTION_HELP
1438 These are a set of macros that allow the addition of additional command
1439 line options to @value{GDBN}. They are currently used only for the unsupported
1440 i960 Nindy target, and should not be used in any other configuration.
1442 @item ADDR_BITS_REMOVE (addr)
1443 If a raw machine instruction address includes any bits that are not
1444 really part of the address, then define this macro to expand into an
1445 expression that zeros those bits in @var{addr}. This is only used for
1446 addresses of instructions, and even then not in all contexts.
1448 For example, the two low-order bits of the PC on the Hewlett-Packard PA
1449 2.0 architecture contain the privilege level of the corresponding
1450 instruction. Since instructions must always be aligned on four-byte
1451 boundaries, the processor masks out these bits to generate the actual
1452 address of the instruction. ADDR_BITS_REMOVE should filter out these
1453 bits with an expression such as @code{((addr) & ~3)}.
1455 @item ADDRESS_TO_POINTER (@var{type}, @var{buf}, @var{addr})
1456 Store in @var{buf} a pointer of type @var{type} representing the address
1457 @var{addr}, in the appropriate format for the current architecture.
1458 This macro may safely assume that @var{type} is either a pointer or a
1460 @xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
1462 @item BEFORE_MAIN_LOOP_HOOK
1463 Define this to expand into any code that you want to execute before the
1464 main loop starts. Although this is not, strictly speaking, a target
1465 conditional, that is how it is currently being used. Note that if a
1466 configuration were to define it one way for a host and a different way
1467 for the target, @value{GDBN} will probably not compile, let alone run correctly.
1468 This is currently used only for the unsupported i960 Nindy target, and
1469 should not be used in any other configuration.
1471 @item BELIEVE_PCC_PROMOTION
1472 Define if the compiler promotes a short or char parameter to an int, but
1473 still reports the parameter as its original type, rather than the
1476 @item BELIEVE_PCC_PROMOTION_TYPE
1477 Define this if @value{GDBN} should believe the type of a short argument when
1478 compiled by pcc, but look within a full int space to get its value.
1479 Only defined for Sun-3 at present.
1481 @item BITS_BIG_ENDIAN
1482 Define this if the numbering of bits in the targets does *not* match the
1483 endianness of the target byte order. A value of 1 means that the bits
1484 are numbered in a big-endian order, 0 means little-endian.
1487 This is the character array initializer for the bit pattern to put into
1488 memory where a breakpoint is set. Although it's common to use a trap
1489 instruction for a breakpoint, it's not required; for instance, the bit
1490 pattern could be an invalid instruction. The breakpoint must be no
1491 longer than the shortest instruction of the architecture.
1493 @var{BREAKPOINT} has been deprecated in favour of
1494 @var{BREAKPOINT_FROM_PC}.
1496 @item BIG_BREAKPOINT
1497 @item LITTLE_BREAKPOINT
1498 Similar to BREAKPOINT, but used for bi-endian targets.
1500 @var{BIG_BREAKPOINT} and @var{LITTLE_BREAKPOINT} have been deprecated in
1501 favour of @var{BREAKPOINT_FROM_PC}.
1503 @item REMOTE_BREAKPOINT
1504 @item LITTLE_REMOTE_BREAKPOINT
1505 @item BIG_REMOTE_BREAKPOINT
1506 Similar to BREAKPOINT, but used for remote targets.
1508 @var{BIG_REMOTE_BREAKPOINT} and @var{LITTLE_REMOTE_BREAKPOINT} have been
1509 deprecated in favour of @var{BREAKPOINT_FROM_PC}.
1511 @item BREAKPOINT_FROM_PC (pcptr, lenptr)
1513 Use the program counter to determine the contents and size of a
1514 breakpoint instruction. It returns a pointer to a string of bytes that
1515 encode a breakpoint instruction, stores the length of the string to
1516 *lenptr, and adjusts pc (if necessary) to point to the actual memory
1517 location where the breakpoint should be inserted.
1519 Although it is common to use a trap instruction for a breakpoint, it's
1520 not required; for instance, the bit pattern could be an invalid
1521 instruction. The breakpoint must be no longer than the shortest
1522 instruction of the architecture.
1524 Replaces all the other @var{BREAKPOINT} macros.
1526 @item MEMORY_INSERT_BREAKPOINT (addr, contents_cache)
1527 @item MEMORY_REMOVE_BREAKPOINT (addr, contents_cache)
1529 Insert or remove memory based breakpoints. Reasonable defaults
1530 (@code{default_memory_insert_breakpoint} and
1531 @code{default_memory_remove_breakpoint} respectively) have been
1532 provided so that it is not necessary to define these for most
1533 architectures. Architectures which may want to define
1534 @var{MEMORY_INSERT_BREAKPOINT} and @var{MEMORY_REMOVE_BREAKPOINT} will
1535 likely have instructions that are oddly sized or are not stored in a
1536 conventional manner.
1538 It may also be desirable (from an efficiency standpoint) to define
1539 custom breakpoint insertion and removal routines if
1540 @var{BREAKPOINT_FROM_PC} needs to read the target's memory for some
1544 A C expresson that is non-zero when the target suports inferior function
1547 @item CALL_DUMMY_WORDS
1548 Pointer to an array of @var{LONGEST} words of data containing
1549 host-byte-ordered @var{REGISTER_BYTES} sized values that partially
1550 specify the sequence of instructions needed for an inferior function
1553 Should be deprecated in favour of a macro that uses target-byte-ordered
1556 @item SIZEOF_CALL_DUMMY_WORDS
1557 The size of @var{CALL_DUMMY_WORDS}. When @var{CALL_DUMMY_P} this must
1558 return a positive value. See also @var{CALL_DUMMY_LENGTH}.
1561 A static initializer for @var{CALL_DUMMY_WORDS}. Deprecated.
1563 @item CALL_DUMMY_LOCATION
1566 @item CALL_DUMMY_STACK_ADJUST
1567 Stack adjustment needed when performing an inferior function call.
1569 Should be deprecated in favor of something like @var{STACK_ALIGN}.
1571 @item CALL_DUMMY_STACK_ADJUST_P
1572 Predicate for use of @var{CALL_DUMMY_STACK_ADJUST}.
1574 Should be deprecated in favor of something like @var{STACK_ALIGN}.
1576 @item CANNOT_FETCH_REGISTER (regno)
1577 A C expression that should be nonzero if @var{regno} cannot be fetched
1578 from an inferior process. This is only relevant if
1579 @code{FETCH_INFERIOR_REGISTERS} is not defined.
1581 @item CANNOT_STORE_REGISTER (regno)
1582 A C expression that should be nonzero if @var{regno} should not be
1583 written to the target. This is often the case for program counters,
1584 status words, and other special registers. If this is not defined, @value{GDBN}
1585 will assume that all registers may be written.
1587 @item DO_DEFERRED_STORES
1588 @item CLEAR_DEFERRED_STORES
1589 Define this to execute any deferred stores of registers into the inferior,
1590 and to cancel any deferred stores.
1592 Currently only implemented correctly for native Sparc configurations?
1594 @item COERCE_FLOAT_TO_DOUBLE (@var{formal}, @var{actual})
1595 If we are calling a function by hand, and the function was declared
1596 (according to the debug info) without a prototype, should we
1597 automatically promote floats to doubles? This macro must evaluate to
1598 non-zero if we should, or zero if we should leave the value alone.
1600 The argument @var{actual} is the type of the value we want to pass to
1601 the function. The argument @var{formal} is the type of this argument,
1602 as it appears in the function's definition. Note that @var{formal} may
1603 be zero if we have no debugging information for the function, or if
1604 we're passing more arguments than are officially declared (for example,
1605 varargs). This macro is never invoked if the function definitely has a
1608 The default behavior is to promote only when we have no type information
1609 for the formal parameter. This is different from the obvious behavior,
1610 which would be to promote whenever we have no prototype, just as the
1611 compiler does. It's annoying, but some older targets rely on this. If
1612 you want @value{GDBN} to follow the typical compiler behavior --- to always
1613 promote when there is no prototype in scope --- your gdbarch init
1614 function can call @code{set_gdbarch_coerce_float_to_double} and select
1615 the @code{standard_coerce_float_to_double} function.
1618 Define this to expand into the character that G++ uses to distinguish
1619 compiler-generated identifiers from programmer-specified identifiers.
1620 By default, this expands into @code{'$'}. Most System V targets should
1621 define this to @code{'.'}.
1623 @item DBX_PARM_SYMBOL_CLASS
1624 Hook for the @code{SYMBOL_CLASS} of a parameter when decoding DBX symbol
1625 information. In the i960, parameters can be stored as locals or as
1626 args, depending on the type of the debug record.
1628 @item DECR_PC_AFTER_BREAK
1629 Define this to be the amount by which to decrement the PC after the
1630 program encounters a breakpoint. This is often the number of bytes in
1631 BREAKPOINT, though not always. For most targets this value will be 0.
1633 @item DECR_PC_AFTER_HW_BREAK
1634 Similarly, for hardware breakpoints.
1636 @item DISABLE_UNSETTABLE_BREAK addr
1637 If defined, this should evaluate to 1 if @var{addr} is in a shared
1638 library in which breakpoints cannot be set and so should be disabled.
1640 @item DO_REGISTERS_INFO
1641 If defined, use this to print the value of a register or all registers.
1643 @item END_OF_TEXT_DEFAULT
1644 This is an expression that should designate the end of the text section
1647 @item EXTRACT_RETURN_VALUE(type,regbuf,valbuf)
1648 Define this to extract a function's return value of type @var{type} from
1649 the raw register state @var{regbuf} and copy that, in virtual format,
1652 @item EXTRACT_STRUCT_VALUE_ADDRESS(regbuf)
1653 When @var{EXTRACT_STRUCT_VALUE_ADDRESS_P} this is used to to extract
1654 from an array @var{regbuf} (containing the raw register state) the
1655 address in which a function should return its structure value, as a
1656 CORE_ADDR (or an expression that can be used as one).
1658 @item EXTRACT_STRUCT_VALUE_ADDRESS_P
1659 Predicate for @var{EXTRACT_STRUCT_VALUE_ADDRESS}.
1662 If defined, then the `info float' command will print information about
1663 the processor's floating point unit.
1666 If the virtual frame pointer is kept in a register, then define this
1667 macro to be the number (greater than or equal to zero) of that register.
1669 This should only need to be defined if @code{TARGET_READ_FP} and
1670 @code{TARGET_WRITE_FP} are not defined.
1672 @item FRAMELESS_FUNCTION_INVOCATION(fi)
1673 Define this to an expression that returns 1 if the function invocation
1674 represented by @var{fi} does not have a stack frame associated with it.
1677 @item FRAME_ARGS_ADDRESS_CORRECT
1680 @item FRAME_CHAIN(frame)
1681 Given @var{frame}, return a pointer to the calling frame.
1683 @item FRAME_CHAIN_COMBINE(chain,frame)
1684 Define this to take the frame chain pointer and the frame's nominal
1685 address and produce the nominal address of the caller's frame.
1686 Presently only defined for HP PA.
1688 @item FRAME_CHAIN_VALID(chain,thisframe)
1690 Define this to be an expression that returns zero if the given frame is
1691 an outermost frame, with no caller, and nonzero otherwise. Several
1692 common definitions are available.
1694 @code{file_frame_chain_valid} is nonzero if the chain pointer is nonzero
1695 and given frame's PC is not inside the startup file (such as
1696 @file{crt0.o}). @code{func_frame_chain_valid} is nonzero if the chain
1697 pointer is nonzero and the given frame's PC is not in @code{main()} or a
1698 known entry point function (such as @code{_start()}).
1699 @code{generic_file_frame_chain_valid} and
1700 @code{generic_func_frame_chain_valid} are equivalent implementations for
1701 targets using generic dummy frames.
1703 @item FRAME_INIT_SAVED_REGS(frame)
1704 See @file{frame.h}. Determines the address of all registers in the
1705 current stack frame storing each in @code{frame->saved_regs}. Space for
1706 @code{frame->saved_regs} shall be allocated by
1707 @code{FRAME_INIT_SAVED_REGS} using either
1708 @code{frame_saved_regs_zalloc} or @code{frame_obstack_alloc}.
1710 @var{FRAME_FIND_SAVED_REGS} and @var{EXTRA_FRAME_INFO} are deprecated.
1712 @item FRAME_NUM_ARGS (fi)
1713 For the frame described by @var{fi} return the number of arguments that
1714 are being passed. If the number of arguments is not known, return
1717 @item FRAME_SAVED_PC(frame)
1718 Given @var{frame}, return the pc saved there. That is, the return
1721 @item FUNCTION_EPILOGUE_SIZE
1722 For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the
1723 function end symbol is 0. For such targets, you must define
1724 @code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a
1725 function's epilogue.
1727 @item FUNCTION_START_OFFSET
1728 An integer, giving the offset in bytes from a function's address (as
1729 used in the values of symbols, function pointers, etc.), and the
1730 function's first genuine instruction.
1732 This is zero on almost all machines: the function's address is usually
1733 the address of its first instruction. However, on the VAX, for example,
1734 each function starts with two bytes containing a bitmask indicating
1735 which registers to save upon entry to the function. The VAX @code{call}
1736 instructions check this value, and save the appropriate registers
1737 automatically. Thus, since the offset from the function's address to
1738 its first instruction is two bytes, @code{FUNCTION_START_OFFSET} would
1741 @item GCC_COMPILED_FLAG_SYMBOL
1742 @item GCC2_COMPILED_FLAG_SYMBOL
1743 If defined, these are the names of the symbols that @value{GDBN} will look for to
1744 detect that GCC compiled the file. The default symbols are
1745 @code{gcc_compiled.} and @code{gcc2_compiled.}, respectively. (Currently
1746 only defined for the Delta 68.)
1748 @item @value{GDBN}_MULTI_ARCH
1749 If defined and non-zero, enables suport for multiple architectures
1750 within @value{GDBN}.
1752 The support can be enabled at two levels. At level one, only
1753 definitions for previously undefined macros are provided; at level two,
1754 a multi-arch definition of all architecture dependant macros will be
1757 @item @value{GDBN}_TARGET_IS_HPPA
1758 This determines whether horrible kludge code in dbxread.c and
1759 partial-stab.h is used to mangle multiple-symbol-table files from
1760 HPPA's. This should all be ripped out, and a scheme like elfread.c
1763 @item GET_LONGJMP_TARGET
1764 For most machines, this is a target-dependent parameter. On the
1765 DECstation and the Iris, this is a native-dependent parameter, since
1766 <setjmp.h> is needed to define it.
1768 This macro determines the target PC address that longjmp() will jump to,
1769 assuming that we have just stopped at a longjmp breakpoint. It takes a
1770 CORE_ADDR * as argument, and stores the target PC value through this
1771 pointer. It examines the current state of the machine as needed.
1773 @item GET_SAVED_REGISTER
1774 Define this if you need to supply your own definition for the function
1775 @code{get_saved_register}.
1777 @item HAVE_REGISTER_WINDOWS
1778 Define this if the target has register windows.
1779 @item REGISTER_IN_WINDOW_P (regnum)
1780 Define this to be an expression that is 1 if the given register is in
1783 @item IBM6000_TARGET
1784 Shows that we are configured for an IBM RS/6000 target. This
1785 conditional should be eliminated (FIXME) and replaced by
1786 feature-specific macros. It was introduced in haste and we are
1787 repenting at leisure.
1789 @item SYMBOLS_CAN_START_WITH_DOLLAR
1790 Some systems have routines whose names start with @samp{$}. Giving this
1791 macro a non-zero value tells @value{GDBN}'s expression parser to check for such
1792 routines when parsing tokens that begin with @samp{$}.
1794 On HP-UX, certain system routines (millicode) have names beginning with
1795 @samp{$} or @samp{$$}. For example, @code{$$dyncall} is a millicode
1796 routine that handles inter-space procedure calls on PA-RISC.
1799 Define this if the target system uses IEEE-format floating point numbers.
1801 @item INIT_EXTRA_FRAME_INFO (fromleaf, frame)
1802 If additional information about the frame is required this should be
1803 stored in @code{frame->extra_info}. Space for @code{frame->extra_info}
1804 is allocated using @code{frame_obstack_alloc}.
1806 @item INIT_FRAME_PC (fromleaf, prev)
1807 This is a C statement that sets the pc of the frame pointed to by
1808 @var{prev}. [By default...]
1810 @item INNER_THAN (lhs,rhs)
1811 Returns non-zero if stack address @var{lhs} is inner than (nearer to the
1812 stack top) stack address @var{rhs}. Define this as @code{lhs < rhs} if
1813 the target's stack grows downward in memory, or @code{lhs > rsh} if the
1816 @item IN_SIGTRAMP (pc, name)
1817 Define this to return true if the given @var{pc} and/or @var{name}
1818 indicates that the current function is a sigtramp.
1820 @item SIGTRAMP_START (pc)
1821 @item SIGTRAMP_END (pc)
1822 Define these to be the start and end address of the sigtramp for the
1823 given @var{pc}. On machines where the address is just a compile time
1824 constant, the macro expansion will typically just ignore the supplied
1827 @item IN_SOLIB_CALL_TRAMPOLINE pc name
1828 Define this to evaluate to nonzero if the program is stopped in the
1829 trampoline that connects to a shared library.
1831 @item IN_SOLIB_RETURN_TRAMPOLINE pc name
1832 Define this to evaluate to nonzero if the program is stopped in the
1833 trampoline that returns from a shared library.
1835 @item IN_SOLIB_DYNSYM_RESOLVE_CODE pc
1836 Define this to evaluate to nonzero if the program is stopped in the
1839 @item SKIP_SOLIB_RESOLVER pc
1840 Define this to evaluate to the (nonzero) address at which execution
1841 should continue to get past the dynamic linker's symbol resolution
1842 function. A zero value indicates that it is not important or necessary
1843 to set a breakpoint to get through the dynamic linker and that single
1844 stepping will suffice.
1846 @item IS_TRAPPED_INTERNALVAR (name)
1847 This is an ugly hook to allow the specification of special actions that
1848 should occur as a side-effect of setting the value of a variable
1849 internal to @value{GDBN}. Currently only used by the h8500. Note that this
1850 could be either a host or target conditional.
1852 @item NEED_TEXT_START_END
1853 Define this if @value{GDBN} should determine the start and end addresses of the
1854 text section. (Seems dubious.)
1856 @item NO_HIF_SUPPORT
1857 (Specific to the a29k.)
1859 @item POINTER_TO_ADDRESS (@var{type}, @var{buf})
1860 Assume that @var{buf} holds a pointer of type @var{type}, in the
1861 appropriate format for the current architecture. Return the byte
1862 address the pointer refers to.
1863 @xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
1865 @item REGISTER_CONVERTIBLE (@var{reg})
1866 Return non-zero if @var{reg} uses different raw and virtual formats.
1867 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
1869 @item REGISTER_RAW_SIZE (@var{reg})
1870 Return the raw size of @var{reg}.
1871 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
1873 @item REGISTER_VIRTUAL_SIZE (@var{reg})
1874 Return the virtual size of @var{reg}.
1875 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
1877 @item REGISTER_VIRTUAL_TYPE (@var{reg})
1878 Return the virtual type of @var{reg}.
1879 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
1881 @item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to})
1882 Convert the value of register @var{reg} from its raw form to its virtual
1884 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
1886 @item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to})
1887 Convert the value of register @var{reg} from its virtual form to its raw
1889 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
1891 @item RETURN_VALUE_ON_STACK(@var{type})
1892 @findex RETURN_VALUE_ON_STACK
1893 @cindex returning structures by value
1894 @cindex structures, returning by value
1896 Return non-zero if values of type TYPE are returned on the stack, using
1897 the ``struct convention'' (i.e., the caller provides a pointer to a
1898 buffer in which the callee should store the return value). This
1899 controls how the @samp{finish} command finds a function's return value,
1900 and whether an inferior function call reserves space on the stack for
1903 The full logic @value{GDBN} uses here is kind of odd.
1907 If the type being returned by value is not a structure, union, or array,
1908 and @code{RETURN_VALUE_ON_STACK} returns zero, then @value{GDBN}
1909 concludes the value is not returned using the struct convention.
1912 Otherwise, @value{GDBN} calls @code{USE_STRUCT_CONVENTION} (see below).
1913 If that returns non-zero, @value{GDBN} assumes the struct convention is
1918 In other words, to indicate that a given type is returned by value using
1919 the struct convention, that type must be either a struct, union, array,
1920 or something @code{RETURN_VALUE_ON_STACK} likes, @emph{and} something
1921 that @code{USE_STRUCT_CONVENTION} likes.
1923 Note that, in C and C++, arrays are never returned by value. In those
1924 languages, these predicates will always see a pointer type, never an
1925 array type. All the references above to arrays being returned by value
1926 apply only to other languages.
1928 @item SOFTWARE_SINGLE_STEP_P
1929 Define this as 1 if the target does not have a hardware single-step
1930 mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined.
1932 @item SOFTWARE_SINGLE_STEP(signal,insert_breapoints_p)
1933 A function that inserts or removes (dependant on
1934 @var{insert_breapoints_p}) breakpoints at each possible destinations of
1935 the next instruction. See @code{sparc-tdep.c} and @code{rs6000-tdep.c}
1938 @item SOFUN_ADDRESS_MAYBE_MISSING
1940 Somebody clever observed that, the more actual addresses you have in the
1941 debug information, the more time the linker has to spend relocating
1942 them. So whenever there's some other way the debugger could find the
1943 address it needs, you should omit it from the debug info, to make
1946 @code{SOFUN_ADDRESS_MAYBE_MISSING} indicates that a particular set of
1947 hacks of this sort are in use, affecting @code{N_SO} and @code{N_FUN}
1948 entries in stabs-format debugging information. @code{N_SO} stabs mark
1949 the beginning and ending addresses of compilation units in the text
1950 segment. @code{N_FUN} stabs mark the starts and ends of functions.
1952 @code{SOFUN_ADDRESS_MAYBE_MISSING} means two things:
1956 @code{N_FUN} stabs have an address of zero. Instead, you should find the
1957 addresses where the function starts by taking the function name from
1958 the stab, and then looking that up in the minsyms (the linker/
1959 assembler symbol table). In other words, the stab has the name, and
1960 the linker / assembler symbol table is the only place that carries
1964 @code{N_SO} stabs have an address of zero, too. You just look at the
1965 @code{N_FUN} stabs that appear before and after the @code{N_SO} stab,
1966 and guess the starting and ending addresses of the compilation unit from
1971 @item PCC_SOL_BROKEN
1972 (Used only in the Convex target.)
1974 @item PC_IN_CALL_DUMMY
1977 @item PC_LOAD_SEGMENT
1978 If defined, print information about the load segment for the program
1979 counter. (Defined only for the RS/6000.)
1982 If the program counter is kept in a register, then define this macro to
1983 be the number (greater than or equal to zero) of that register.
1985 This should only need to be defined if @code{TARGET_READ_PC} and
1986 @code{TARGET_WRITE_PC} are not defined.
1989 The number of the ``next program counter'' register, if defined.
1992 The number of the ``next next program counter'' register, if defined.
1993 Currently, this is only defined for the Motorola 88K.
1996 If non-zero, round arguments to a boundary of this many bits before
1997 pushing them on the stack.
1999 @item PRINT_REGISTER_HOOK (regno)
2000 If defined, this must be a function that prints the contents of the
2001 given register to standard output.
2003 @item PRINT_TYPELESS_INTEGER
2004 This is an obscure substitute for @code{print_longest} that seems to
2005 have been defined for the Convex target.
2007 @item PROCESS_LINENUMBER_HOOK
2008 A hook defined for XCOFF reading.
2010 @item PROLOGUE_FIRSTLINE_OVERLAP
2011 (Only used in unsupported Convex configuration.)
2014 If defined, this is the number of the processor status register. (This
2015 definition is only used in generic code when parsing "$ps".)
2018 Used in @samp{call_function_by_hand} to remove an artificial stack
2021 @item PUSH_ARGUMENTS (nargs, args, sp, struct_return, struct_addr)
2022 Define this to push arguments onto the stack for inferior function
2023 call. Return the updated stack pointer value.
2025 @item PUSH_DUMMY_FRAME
2026 Used in @samp{call_function_by_hand} to create an artificial stack frame.
2028 @item REGISTER_BYTES
2029 The total amount of space needed to store @value{GDBN}'s copy of the machine's
2032 @item REGISTER_NAME(i)
2033 Return the name of register @var{i} as a string. May return @var{NULL}
2034 or @var{NUL} to indicate that register @var{i} is not valid.
2036 @item REGISTER_NAMES
2037 Deprecated in favor of @var{REGISTER_NAME}.
2039 @item REG_STRUCT_HAS_ADDR (gcc_p, type)
2040 Define this to return 1 if the given type will be passed by pointer
2041 rather than directly.
2043 @item SAVE_DUMMY_FRAME_TOS (sp)
2044 Used in @samp{call_function_by_hand} to notify the target dependent code
2045 of the top-of-stack value that will be passed to the the inferior code.
2046 This is the value of the @var{SP} after both the dummy frame and space
2047 for parameters/results have been allocated on the stack.
2049 @item SDB_REG_TO_REGNUM
2050 Define this to convert sdb register numbers into @value{GDBN} regnums. If not
2051 defined, no conversion will be done.
2053 @item SHIFT_INST_REGS
2054 (Only used for m88k targets.)
2056 @item SKIP_PERMANENT_BREAKPOINT
2057 Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally
2058 steps over a breakpoint by removing it, stepping one instruction, and
2059 re-inserting the breakpoint. However, permanent breakpoints are
2060 hardwired into the inferior, and can't be removed, so this strategy
2061 doesn't work. Calling SKIP_PERMANENT_BREAKPOINT adjusts the processor's
2062 state so that execution will resume just after the breakpoint. This
2063 macro does the right thing even when the breakpoint is in the delay slot
2064 of a branch or jump.
2066 @item SKIP_PROLOGUE (pc)
2067 A C expression that returns the address of the ``real'' code beyond the
2068 function entry prologue found at @var{pc}.
2070 @item SKIP_PROLOGUE_FRAMELESS_P
2071 A C expression that should behave similarly, but that can stop as soon
2072 as the function is known to have a frame. If not defined,
2073 @code{SKIP_PROLOGUE} will be used instead.
2075 @item SKIP_TRAMPOLINE_CODE (pc)
2076 If the target machine has trampoline code that sits between callers and
2077 the functions being called, then define this macro to return a new PC
2078 that is at the start of the real function.
2081 If the stack-pointer is kept in a register, then define this macro to be
2082 the number (greater than or equal to zero) of that register.
2084 This should only need to be defined if @code{TARGET_WRITE_SP} and
2085 @code{TARGET_WRITE_SP} are not defined.
2087 @item STAB_REG_TO_REGNUM
2088 Define this to convert stab register numbers (as gotten from `r'
2089 declarations) into @value{GDBN} regnums. If not defined, no conversion will be
2092 @item STACK_ALIGN (addr)
2093 Define this to adjust the address to the alignment required for the
2096 @item STEP_SKIPS_DELAY (addr)
2097 Define this to return true if the address is of an instruction with a
2098 delay slot. If a breakpoint has been placed in the instruction's delay
2099 slot, @value{GDBN} will single-step over that instruction before resuming
2100 normally. Currently only defined for the Mips.
2102 @item STORE_RETURN_VALUE (type, valbuf)
2103 A C expression that stores a function return value of type @var{type},
2104 where @var{valbuf} is the address of the value to be stored.
2106 @item SUN_FIXED_LBRAC_BUG
2107 (Used only for Sun-3 and Sun-4 targets.)
2109 @item SYMBOL_RELOADING_DEFAULT
2110 The default value of the `symbol-reloading' variable. (Never defined in
2113 @item TARGET_BYTE_ORDER_DEFAULT
2114 The ordering of bytes in the target. This must be either
2115 @code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. This macro replaces
2116 @var{TARGET_BYTE_ORDER} which is deprecated.
2118 @item TARGET_BYTE_ORDER_SELECTABLE_P
2119 Non-zero if the target has both @code{BIG_ENDIAN} and
2120 @code{LITTLE_ENDIAN} variants. This macro replaces
2121 @var{TARGET_BYTE_ORDER_SELECTABLE} which is deprecated.
2123 @item TARGET_CHAR_BIT
2124 Number of bits in a char; defaults to 8.
2126 @item TARGET_COMPLEX_BIT
2127 Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}.
2129 At present this macro is not used.
2131 @item TARGET_DOUBLE_BIT
2132 Number of bits in a double float; defaults to @code{8 * TARGET_CHAR_BIT}.
2134 @item TARGET_DOUBLE_COMPLEX_BIT
2135 Number of bits in a double complex; defaults to @code{2 * TARGET_DOUBLE_BIT}.
2137 At present this macro is not used.
2139 @item TARGET_FLOAT_BIT
2140 Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}.
2142 @item TARGET_INT_BIT
2143 Number of bits in an integer; defaults to @code{4 * TARGET_CHAR_BIT}.
2145 @item TARGET_LONG_BIT
2146 Number of bits in a long integer; defaults to @code{4 * TARGET_CHAR_BIT}.
2148 @item TARGET_LONG_DOUBLE_BIT
2149 Number of bits in a long double float;
2150 defaults to @code{2 * TARGET_DOUBLE_BIT}.
2152 @item TARGET_LONG_LONG_BIT
2153 Number of bits in a long long integer; defaults to @code{2 * TARGET_LONG_BIT}.
2155 @item TARGET_PTR_BIT
2156 Number of bits in a pointer; defaults to @code{TARGET_INT_BIT}.
2158 @item TARGET_SHORT_BIT
2159 Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}.
2161 @item TARGET_READ_PC
2162 @item TARGET_WRITE_PC (val, pid)
2163 @item TARGET_READ_SP
2164 @item TARGET_WRITE_SP
2165 @item TARGET_READ_FP
2166 @item TARGET_WRITE_FP
2167 These change the behavior of @code{read_pc}, @code{write_pc},
2168 @code{read_sp}, @code{write_sp}, @code{read_fp} and @code{write_fp}.
2169 For most targets, these may be left undefined. @value{GDBN} will call the read
2170 and write register functions with the relevant @code{_REGNUM} argument.
2172 These macros are useful when a target keeps one of these registers in a
2173 hard to get at place; for example, part in a segment register and part
2174 in an ordinary register.
2176 @item TARGET_VIRTUAL_FRAME_POINTER(pc,regp,offsetp)
2177 Returns a @code{(register, offset)} pair representing the virtual
2178 frame pointer in use at the code address @code{"pc"}. If virtual
2179 frame pointers are not used, a default definition simply returns
2180 @code{FP_REGNUM}, with an offset of zero.
2182 @item USE_STRUCT_CONVENTION (gcc_p, type)
2183 If defined, this must be an expression that is nonzero if a value of the
2184 given @var{type} being returned from a function must have space
2185 allocated for it on the stack. @var{gcc_p} is true if the function
2186 being considered is known to have been compiled by GCC; this is helpful
2187 for systems where GCC is known to use different calling convention than
2190 @item VARIABLES_INSIDE_BLOCK (desc, gcc_p)
2191 For dbx-style debugging information, if the compiler puts variable
2192 declarations inside LBRAC/RBRAC blocks, this should be defined to be
2193 nonzero. @var{desc} is the value of @code{n_desc} from the
2194 @code{N_RBRAC} symbol, and @var{gcc_p} is true if @value{GDBN} has noticed the
2195 presence of either the @code{GCC_COMPILED_SYMBOL} or the
2196 @code{GCC2_COMPILED_SYMBOL}. By default, this is 0.
2198 @item OS9K_VARIABLES_INSIDE_BLOCK (desc, gcc_p)
2199 Similarly, for OS/9000. Defaults to 1.
2203 Motorola M68K target conditionals.
2208 Define this to be the 4-bit location of the breakpoint trap vector. If
2209 not defined, it will default to @code{0xf}.
2211 @item REMOTE_BPT_VECTOR
2212 Defaults to @code{1}.
2216 @section Adding a New Target
2218 The following files define a target to @value{GDBN}:
2222 @item gdb/config/@var{arch}/@var{ttt}.mt
2223 Contains a Makefile fragment specific to this target. Specifies what
2224 object files are needed for target @var{ttt}, by defining
2225 @samp{TDEPFILES=@dots{}} and @samp{TDEPLIBS=@dots{}}. Also specifies
2226 the header file which describes @var{ttt}, by defining @samp{TM_FILE=
2229 You can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, @samp{TM_CDEPS},
2230 but these are now deprecated, replaced by autoconf, and may go away in
2231 future versions of @value{GDBN}.
2233 @item gdb/config/@var{arch}/tm-@var{ttt}.h
2234 (@file{tm.h} is a link to this file, created by configure). Contains
2235 macro definitions about the target machine's registers, stack frame
2236 format and instructions.
2238 @item gdb/@var{ttt}-tdep.c
2239 Contains any miscellaneous code required for this target machine. On
2240 some machines it doesn't exist at all. Sometimes the macros in
2241 @file{tm-@var{ttt}.h} become very complicated, so they are implemented
2242 as functions here instead, and the macro is simply defined to call the
2243 function. This is vastly preferable, since it is easier to understand
2246 @item gdb/config/@var{arch}/tm-@var{arch}.h
2247 This often exists to describe the basic layout of the target machine's
2248 processor chip (registers, stack, etc). If used, it is included by
2249 @file{tm-@var{ttt}.h}. It can be shared among many targets that use the
2252 @item gdb/@var{arch}-tdep.c
2253 Similarly, there are often common subroutines that are shared by all
2254 target machines that use this particular architecture.
2258 If you are adding a new operating system for an existing CPU chip, add a
2259 @file{config/tm-@var{os}.h} file that describes the operating system
2260 facilities that are unusual (extra symbol table info; the breakpoint
2261 instruction needed; etc). Then write a @file{@var{arch}/tm-@var{os}.h}
2262 that just @code{#include}s @file{tm-@var{arch}.h} and
2263 @file{config/tm-@var{os}.h}.
2266 @node Target Vector Definition
2268 @chapter Target Vector Definition
2270 The target vector defines the interface between @value{GDBN}'s abstract handling
2271 of target systems, and the nitty-gritty code that actually exercises
2272 control over a process or a serial port. @value{GDBN} includes some 30-40
2273 different target vectors; however, each configuration of @value{GDBN} includes
2276 @section File Targets
2278 Both executables and core files have target vectors.
2280 @section Standard Protocol and Remote Stubs
2282 @value{GDBN}'s file @file{remote.c} talks a serial protocol to code that runs in
2283 the target system. @value{GDBN} provides several sample ``stubs'' that can be
2284 integrated into target programs or operating systems for this purpose;
2285 they are named @file{*-stub.c}.
2287 The @value{GDBN} user's manual describes how to put such a stub into your target
2288 code. What follows is a discussion of integrating the SPARC stub into a
2289 complicated operating system (rather than a simple program), by Stu
2290 Grossman, the author of this stub.
2292 The trap handling code in the stub assumes the following upon entry to
2297 @item %l1 and %l2 contain pc and npc respectively at the time of the trap
2299 @item traps are disabled
2301 @item you are in the correct trap window
2305 As long as your trap handler can guarantee those conditions, then there
2306 is no reason why you shouldn't be able to `share' traps with the stub.
2307 The stub has no requirement that it be jumped to directly from the
2308 hardware trap vector. That is why it calls @code{exceptionHandler()},
2309 which is provided by the external environment. For instance, this could
2310 setup the hardware traps to actually execute code which calls the stub
2311 first, and then transfers to its own trap handler.
2313 For the most point, there probably won't be much of an issue with
2314 `sharing' traps, as the traps we use are usually not used by the kernel,
2315 and often indicate unrecoverable error conditions. Anyway, this is all
2316 controlled by a table, and is trivial to modify. The most important
2317 trap for us is for @code{ta 1}. Without that, we can't single step or
2318 do breakpoints. Everything else is unnecessary for the proper operation
2319 of the debugger/stub.
2321 From reading the stub, it's probably not obvious how breakpoints work.
2322 They are simply done by deposit/examine operations from @value{GDBN}.
2324 @section ROM Monitor Interface
2326 @section Custom Protocols
2328 @section Transport Layer
2330 @section Builtin Simulator
2333 @node Native Debugging
2335 @chapter Native Debugging
2337 Several files control @value{GDBN}'s configuration for native support:
2341 @item gdb/config/@var{arch}/@var{xyz}.mh
2342 Specifies Makefile fragments needed when hosting @emph{or native} on
2343 machine @var{xyz}. In particular, this lists the required
2344 native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}.
2345 Also specifies the header file which describes native support on
2346 @var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}. You can also
2347 define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS},
2348 @samp{NAT_CDEPS}, etc.; see @file{Makefile.in}.
2350 @item gdb/config/@var{arch}/nm-@var{xyz}.h
2351 (@file{nm.h} is a link to this file, created by configure). Contains C
2352 macro definitions describing the native system environment, such as
2353 child process control and core file support.
2355 @item gdb/@var{xyz}-nat.c
2356 Contains any miscellaneous C code required for this native support of
2357 this machine. On some machines it doesn't exist at all.
2361 There are some ``generic'' versions of routines that can be used by
2362 various systems. These can be customized in various ways by macros
2363 defined in your @file{nm-@var{xyz}.h} file. If these routines work for
2364 the @var{xyz} host, you can just include the generic file's name (with
2365 @samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.
2367 Otherwise, if your machine needs custom support routines, you will need
2368 to write routines that perform the same functions as the generic file.
2369 Put them into @code{@var{xyz}-nat.c}, and put @code{@var{xyz}-nat.o}
2370 into @code{NATDEPFILES}.
2375 This contains the @emph{target_ops vector} that supports Unix child
2376 processes on systems which use ptrace and wait to control the child.
2379 This contains the @emph{target_ops vector} that supports Unix child
2380 processes on systems which use /proc to control the child.
2383 This does the low-level grunge that uses Unix system calls to do a "fork
2384 and exec" to start up a child process.
2387 This is the low level interface to inferior processes for systems using
2388 the Unix @code{ptrace} call in a vanilla way.
2392 @section Native core file Support
2396 @item core-aout.c::fetch_core_registers()
2397 Support for reading registers out of a core file. This routine calls
2398 @code{register_addr()}, see below. Now that BFD is used to read core
2399 files, virtually all machines should use @code{core-aout.c}, and should
2400 just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or
2401 @code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}).
2403 @item core-aout.c::register_addr()
2404 If your @code{nm-@var{xyz}.h} file defines the macro
2405 @code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
2406 set @code{addr} to the offset within the @samp{user} struct of @value{GDBN}
2407 register number @code{regno}. @code{blockend} is the offset within the
2408 ``upage'' of @code{u.u_ar0}. If @code{REGISTER_U_ADDR} is defined,
2409 @file{core-aout.c} will define the @code{register_addr()} function and
2410 use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but
2411 you are using the standard @code{fetch_core_registers()}, you will need
2412 to define your own version of @code{register_addr()}, put it into your
2413 @code{@var{xyz}-nat.c} file, and be sure @code{@var{xyz}-nat.o} is in
2414 the @code{NATDEPFILES} list. If you have your own
2415 @code{fetch_core_registers()}, you may not need a separate
2416 @code{register_addr()}. Many custom @code{fetch_core_registers()}
2417 implementations simply locate the registers themselves.@refill
2421 When making @value{GDBN} run native on a new operating system, to make it
2422 possible to debug core files, you will need to either write specific
2423 code for parsing your OS's core files, or customize
2424 @file{bfd/trad-core.c}. First, use whatever @code{#include} files your
2425 machine uses to define the struct of registers that is accessible
2426 (possibly in the u-area) in a core file (rather than
2427 @file{machine/reg.h}), and an include file that defines whatever header
2428 exists on a core file (e.g. the u-area or a @samp{struct core}). Then
2429 modify @code{trad_unix_core_file_p()} to use these values to set up the
2430 section information for the data segment, stack segment, any other
2431 segments in the core file (perhaps shared library contents or control
2432 information), ``registers'' segment, and if there are two discontiguous
2433 sets of registers (e.g. integer and float), the ``reg2'' segment. This
2434 section information basically delimits areas in the core file in a
2435 standard way, which the section-reading routines in BFD know how to seek
2438 Then back in @value{GDBN}, you need a matching routine called
2439 @code{fetch_core_registers()}. If you can use the generic one, it's in
2440 @file{core-aout.c}; if not, it's in your @file{@var{xyz}-nat.c} file.
2441 It will be passed a char pointer to the entire ``registers'' segment,
2442 its length, and a zero; or a char pointer to the entire ``regs2''
2443 segment, its length, and a 2. The routine should suck out the supplied
2444 register values and install them into @value{GDBN}'s ``registers'' array.
2446 If your system uses @file{/proc} to control processes, and uses ELF
2447 format core files, then you may be able to use the same routines for
2448 reading the registers out of processes and out of core files.
2456 @section shared libraries
2458 @section Native Conditionals
2460 When @value{GDBN} is configured and compiled, various macros are defined or left
2461 undefined, to control compilation when the host and target systems are
2462 the same. These macros should be defined (or left undefined) in
2463 @file{nm-@var{system}.h}.
2468 If defined, then @value{GDBN} will include support for the @code{attach} and
2469 @code{detach} commands.
2471 @item CHILD_PREPARE_TO_STORE
2472 If the machine stores all registers at once in the child process, then
2473 define this to ensure that all values are correct. This usually entails
2474 a read from the child.
2476 [Note that this is incorrectly defined in @file{xm-@var{system}.h} files
2479 @item FETCH_INFERIOR_REGISTERS
2480 Define this if the native-dependent code will provide its own routines
2481 @code{fetch_inferior_registers} and @code{store_inferior_registers} in
2482 @file{@var{HOST}-nat.c}. If this symbol is @emph{not} defined, and
2483 @file{infptrace.c} is included in this configuration, the default
2484 routines in @file{infptrace.c} are used for these functions.
2486 @item FILES_INFO_HOOK
2487 (Only defined for Convex.)
2490 This macro is normally defined to be the number of the first floating
2491 point register, if the machine has such registers. As such, it would
2492 appear only in target-specific code. However, /proc support uses this
2493 to decide whether floats are in use on this target.
2495 @item GET_LONGJMP_TARGET
2496 For most machines, this is a target-dependent parameter. On the
2497 DECstation and the Iris, this is a native-dependent parameter, since
2498 <setjmp.h> is needed to define it.
2500 This macro determines the target PC address that longjmp() will jump to,
2501 assuming that we have just stopped at a longjmp breakpoint. It takes a
2502 CORE_ADDR * as argument, and stores the target PC value through this
2503 pointer. It examines the current state of the machine as needed.
2506 Define this to the address of the @code{u} structure (the ``user
2507 struct'', also known as the ``u-page'') in kernel virtual memory. @value{GDBN}
2508 needs to know this so that it can subtract this address from absolute
2509 addresses in the upage, that are obtained via ptrace or from core files.
2510 On systems that don't need this value, set it to zero.
2512 @item KERNEL_U_ADDR_BSD
2513 Define this to cause @value{GDBN} to determine the address of @code{u} at
2514 runtime, by using Berkeley-style @code{nlist} on the kernel's image in
2517 @item KERNEL_U_ADDR_HPUX
2518 Define this to cause @value{GDBN} to determine the address of @code{u} at
2519 runtime, by using HP-style @code{nlist} on the kernel's image in the
2522 @item ONE_PROCESS_WRITETEXT
2523 Define this to be able to, when a breakpoint insertion fails, warn the
2524 user that another process may be running with the same executable.
2526 @item PREPARE_TO_PROCEED @var{select_it}
2527 This (ugly) macro allows a native configuration to customize the way the
2528 @code{proceed} function in @file{infrun.c} deals with switching between
2531 In a multi-threaded task we may select another thread and then continue
2532 or step. But if the old thread was stopped at a breakpoint, it will
2533 immediately cause another breakpoint stop without any execution (i.e. it
2534 will report a breakpoint hit incorrectly). So @value{GDBN} must step over it
2537 If defined, @code{PREPARE_TO_PROCEED} should check the current thread
2538 against the thread that reported the most recent event. If a step-over
2539 is required, it returns TRUE. If @var{select_it} is non-zero, it should
2540 reselect the old thread.
2543 Defines the format for the name of a @file{/proc} device. Should be
2544 defined in @file{nm.h} @emph{only} in order to override the default
2545 definition in @file{procfs.c}.
2550 @item PTRACE_ARG3_TYPE
2551 The type of the third argument to the @code{ptrace} system call, if it
2552 exists and is different from @code{int}.
2554 @item REGISTER_U_ADDR
2555 Defines the offset of the registers in the ``u area''.
2557 @item SHELL_COMMAND_CONCAT
2558 If defined, is a string to prefix on the shell command used to start the
2562 If defined, this is the name of the shell to use to run the inferior.
2563 Defaults to @code{"/bin/sh"}.
2565 @item SOLIB_ADD (filename, from_tty, targ)
2566 Define this to expand into an expression that will cause the symbols in
2567 @var{filename} to be added to @value{GDBN}'s symbol table.
2569 @item SOLIB_CREATE_INFERIOR_HOOK
2570 Define this to expand into any shared-library-relocation code that you
2571 want to be run just after the child process has been forked.
2573 @item START_INFERIOR_TRAPS_EXPECTED
2574 When starting an inferior, @value{GDBN} normally expects to trap twice; once when
2575 the shell execs, and once when the program itself execs. If the actual
2576 number of traps is something other than 2, then define this macro to
2577 expand into the number expected.
2579 @item SVR4_SHARED_LIBS
2580 Define this to indicate that SVR4-style shared libraries are in use.
2583 This determines whether small routines in @file{*-tdep.c}, which
2584 translate register values between @value{GDBN}'s internal representation and the
2585 /proc representation, are compiled.
2588 This is the offset of the registers in the upage. It need only be
2589 defined if the generic ptrace register access routines in
2590 @file{infptrace.c} are being used (that is, @file{infptrace.c} is
2591 configured in, and @code{FETCH_INFERIOR_REGISTERS} is not defined). If
2592 the default value from @file{infptrace.c} is good enough, leave it
2595 The default value means that u.u_ar0 @emph{points to} the location of
2596 the registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means
2597 that u.u_ar0 @emph{is} the location of the registers.
2603 Define this to debug ptrace calls.
2608 @node Support Libraries
2610 @chapter Support Libraries
2614 BFD provides support for @value{GDBN} in several ways:
2618 @item identifying executable and core files
2619 BFD will identify a variety of file types, including a.out, coff, and
2620 several variants thereof, as well as several kinds of core files.
2622 @item access to sections of files
2623 BFD parses the file headers to determine the names, virtual addresses,
2624 sizes, and file locations of all the various named sections in files
2625 (such as the text section or the data section). @value{GDBN} simply calls BFD to
2626 read or write section X at byte offset Y for length Z.
2628 @item specialized core file support
2629 BFD provides routines to determine the failing command name stored in a
2630 core file, the signal with which the program failed, and whether a core
2631 file matches (i.e. could be a core dump of) a particular executable
2634 @item locating the symbol information
2635 @value{GDBN} uses an internal interface of BFD to determine where to find the
2636 symbol information in an executable file or symbol-file. @value{GDBN} itself
2637 handles the reading of symbols, since BFD does not ``understand'' debug
2638 symbols, but @value{GDBN} uses BFD's cached information to find the symbols,
2645 The opcodes library provides @value{GDBN}'s disassembler. (It's a separate
2646 library because it's also used in binutils, for @file{objdump}).
2666 @item SIGN_EXTEND_CHAR
2668 @item SWITCH_ENUM_BUG
2684 This chapter covers topics that are lower-level than the major
2685 algorithms of @value{GDBN}.
2689 Cleanups are a structured way to deal with things that need to be done
2690 later. When your code does something (like @code{malloc} some memory,
2691 or open a file) that needs to be undone later (e.g. free the memory or
2692 close the file), it can make a cleanup. The cleanup will be done at
2693 some future point: when the command is finished, when an error occurs,
2694 or when your code decides it's time to do cleanups.
2696 You can also discard cleanups, that is, throw them away without doing
2697 what they say. This is only done if you ask that it be done.
2703 @item struct cleanup *@var{old_chain};
2704 Declare a variable which will hold a cleanup chain handle.
2706 @item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
2707 Make a cleanup which will cause @var{function} to be called with
2708 @var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a
2709 handle that can be passed to @code{do_cleanups} or
2710 @code{discard_cleanups} later. Unless you are going to call
2711 @code{do_cleanups} or @code{discard_cleanups} yourself, you can ignore
2712 the result from @code{make_cleanup}.
2714 @item do_cleanups (@var{old_chain});
2715 Perform all cleanups done since @code{make_cleanup} returned
2716 @var{old_chain}. E.g.:
2718 make_cleanup (a, 0);
2719 old = make_cleanup (b, 0);
2723 will call @code{b()} but will not call @code{a()}. The cleanup that
2724 calls @code{a()} will remain in the cleanup chain, and will be done
2725 later unless otherwise discarded.@refill
2727 @item discard_cleanups (@var{old_chain});
2728 Same as @code{do_cleanups} except that it just removes the cleanups from
2729 the chain and does not call the specified functions.
2733 Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify
2734 that they ``should not be called when cleanups are not in place''. This
2735 means that any actions you need to reverse in the case of an error or
2736 interruption must be on the cleanup chain before you call these
2737 functions, since they might never return to your code (they
2738 @samp{longjmp} instead).
2740 @section Wrapping Output Lines
2742 Output that goes through @code{printf_filtered} or @code{fputs_filtered}
2743 or @code{fputs_demangled} needs only to have calls to @code{wrap_here}
2744 added in places that would be good breaking points. The utility
2745 routines will take care of actually wrapping if the line width is
2748 The argument to @code{wrap_here} is an indentation string which is
2749 printed @emph{only} if the line breaks there. This argument is saved
2750 away and used later. It must remain valid until the next call to
2751 @code{wrap_here} or until a newline has been printed through the
2752 @code{*_filtered} functions. Don't pass in a local variable and then
2755 It is usually best to call @code{wrap_here()} after printing a comma or
2756 space. If you call it before printing a space, make sure that your
2757 indentation properly accounts for the leading space that will print if
2758 the line wraps there.
2760 Any function or set of functions that produce filtered output must
2761 finish by printing a newline, to flush the wrap buffer, before switching
2762 to unfiltered (``@code{printf}'') output. Symbol reading routines that
2763 print warnings are a good example.
2765 @section @value{GDBN} Coding Standards
2767 @value{GDBN} follows the GNU coding standards, as described in
2768 @file{etc/standards.texi}. This file is also available for anonymous
2769 FTP from GNU archive sites. @value{GDBN} takes a strict interpretation of the
2770 standard; in general, when the GNU standard recommends a practice but
2771 does not require it, @value{GDBN} requires it.
2773 @value{GDBN} follows an additional set of coding standards specific to @value{GDBN},
2774 as described in the following sections.
2776 You can configure with @samp{--enable-build-warnings} or
2777 @samp{--enable-gdb-build-warnings} to get GCC to check on a number of
2778 these rules. @value{GDBN} sources ought not to engender any complaints,
2779 unless they are caused by bogus host systems. (The exact set of enabled
2780 warnings is currently @samp{-Wimplicit -Wreturn-type -Wcomment
2781 -Wtrigraphs -Wformat -Wparentheses -Wpointer-arith -Wuninitialized}.
2783 @subsection Formatting
2785 The standard GNU recommendations for formatting must be followed
2788 Note that while in a definition, the function's name must be in column
2789 zero; in a function declaration, the name must be on the same line as
2792 In addition, there must be a space between a function or macro name and
2793 the opening parenthesis of its argument list (except for macro
2794 definitions, as required by C). There must not be a space after an open
2795 paren/bracket or before a close paren/bracket.
2797 While additional whitespace is generally helpful for reading, do not use
2798 more than one blank line to separate blocks, and avoid adding whitespace
2799 after the end of a program line (as of 1/99, some 600 lines had whitespace
2800 after the semicolon). Excess whitespace causes difficulties for diff and
2803 @subsection Comments
2805 The standard GNU requirements on comments must be followed strictly.
2807 Block comments must appear in the following form, with no `/*'- or
2808 '*/'-only lines, and no leading `*':
2811 /* Wait for control to return from inferior to debugger. If inferior
2812 gets a signal, we may decide to start it up again instead of
2813 returning. That is why there is a loop in this function. When
2814 this function actually returns it means the inferior should be left
2815 stopped and @value{GDBN} should read more commands. */
2818 (Note that this format is encouraged by Emacs; tabbing for a multi-line
2819 comment works correctly, and M-Q fills the block consistently.)
2821 Put a blank line between the block comments preceding function or
2822 variable definitions, and the definition itself.
2824 In general, put function-body comments on lines by themselves, rather
2825 than trying to fit them into the 20 characters left at the end of a
2826 line, since either the comment or the code will inevitably get longer
2827 than will fit, and then somebody will have to move it anyhow.
2831 Code must not depend on the sizes of C data types, the format of the
2832 host's floating point numbers, the alignment of anything, or the order
2833 of evaluation of expressions.
2835 Use functions freely. There are only a handful of compute-bound areas
2836 in @value{GDBN} that might be affected by the overhead of a function call, mainly
2837 in symbol reading. Most of @value{GDBN}'s performance is limited by the target
2838 interface (whether serial line or system call).
2840 However, use functions with moderation. A thousand one-line functions
2841 are just as hard to understand as a single thousand-line function.
2843 @subsection Function Prototypes
2845 Prototypes must be used to @emph{declare} functions, and may be used to
2846 @emph{define} them. Prototypes for @value{GDBN} functions must include both the
2847 argument type and name, with the name matching that used in the actual
2848 function definition.
2850 All external functions should have a declaration in a header file that
2851 callers include, except for @code{_initialize_*} functions, which must
2852 be external so that @file{init.c} construction works, but shouldn't be
2853 visible to random source files.
2855 All static functions must be declared in a block near the top of the
2858 @subsection Clean Design
2860 In addition to getting the syntax right, there's the little question of
2861 semantics. Some things are done in certain ways in @value{GDBN} because long
2862 experience has shown that the more obvious ways caused various kinds of
2865 You can't assume the byte order of anything that comes from a target
2866 (including @var{value}s, object files, and instructions). Such things
2867 must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in @value{GDBN}, or one of
2868 the swap routines defined in @file{bfd.h}, such as @code{bfd_get_32}.
2870 You can't assume that you know what interface is being used to talk to
2871 the target system. All references to the target must go through the
2872 current @code{target_ops} vector.
2874 You can't assume that the host and target machines are the same machine
2875 (except in the ``native'' support modules). In particular, you can't
2876 assume that the target machine's header files will be available on the
2877 host machine. Target code must bring along its own header files --
2878 written from scratch or explicitly donated by their owner, to avoid
2881 Insertion of new @code{#ifdef}'s will be frowned upon. It's much better
2882 to write the code portably than to conditionalize it for various
2885 New @code{#ifdef}'s which test for specific compilers or manufacturers
2886 or operating systems are unacceptable. All @code{#ifdef}'s should test
2887 for features. The information about which configurations contain which
2888 features should be segregated into the configuration files. Experience
2889 has proven far too often that a feature unique to one particular system
2890 often creeps into other systems; and that a conditional based on some
2891 predefined macro for your current system will become worthless over
2892 time, as new versions of your system come out that behave differently
2893 with regard to this feature.
2895 Adding code that handles specific architectures, operating systems,
2896 target interfaces, or hosts, is not acceptable in generic code. If a
2897 hook is needed at that point, invent a generic hook and define it for
2898 your configuration, with something like:
2901 #ifdef WRANGLE_SIGNALS
2902 WRANGLE_SIGNALS (signo);
2906 In your host, target, or native configuration file, as appropriate,
2907 define @code{WRANGLE_SIGNALS} to do the machine-dependent thing. Take a
2908 bit of care in defining the hook, so that it can be used by other ports
2909 in the future, if they need a hook in the same place.
2911 If the hook is not defined, the code should do whatever "most" machines
2912 want. Using @code{#ifdef}, as above, is the preferred way to do this,
2913 but sometimes that gets convoluted, in which case use
2916 #ifndef SPECIAL_FOO_HANDLING
2917 #define SPECIAL_FOO_HANDLING(pc, sp) (0)
2921 where the macro is used or in an appropriate header file.
2923 Whether to include a @dfn{small} hook, a hook around the exact pieces of
2924 code which are system-dependent, or whether to replace a whole function
2925 with a hook depends on the case. A good example of this dilemma can be
2926 found in @code{get_saved_register}. All machines that @value{GDBN} 2.8 ran on
2927 just needed the @code{FRAME_FIND_SAVED_REGS} hook to find the saved
2928 registers. Then the SPARC and Pyramid came along, and
2929 @code{HAVE_REGISTER_WINDOWS} and @code{REGISTER_IN_WINDOW_P} were
2930 introduced. Then the 29k and 88k required the @code{GET_SAVED_REGISTER}
2931 hook. The first three are examples of small hooks; the latter replaces
2932 a whole function. In this specific case, it is useful to have both
2933 kinds; it would be a bad idea to replace all the uses of the small hooks
2934 with @code{GET_SAVED_REGISTER}, since that would result in much
2935 duplicated code. Other times, duplicating a few lines of code here or
2936 there is much cleaner than introducing a large number of small hooks.
2938 Another way to generalize @value{GDBN} along a particular interface is with an
2939 attribute struct. For example, @value{GDBN} has been generalized to handle
2940 multiple kinds of remote interfaces -- not by #ifdef's everywhere, but
2941 by defining the "target_ops" structure and having a current target (as
2942 well as a stack of targets below it, for memory references). Whenever
2943 something needs to be done that depends on which remote interface we are
2944 using, a flag in the current target_ops structure is tested (e.g.
2945 `target_has_stack'), or a function is called through a pointer in the
2946 current target_ops structure. In this way, when a new remote interface
2947 is added, only one module needs to be touched -- the one that actually
2948 implements the new remote interface. Other examples of
2949 attribute-structs are BFD access to multiple kinds of object file
2950 formats, or @value{GDBN}'s access to multiple source languages.
2952 Please avoid duplicating code. For example, in @value{GDBN} 3.x all the code
2953 interfacing between @code{ptrace} and the rest of @value{GDBN} was duplicated in
2954 @file{*-dep.c}, and so changing something was very painful. In @value{GDBN} 4.x,
2955 these have all been consolidated into @file{infptrace.c}.
2956 @file{infptrace.c} can deal with variations between systems the same way
2957 any system-independent file would (hooks, #if defined, etc.), and
2958 machines which are radically different don't need to use infptrace.c at
2961 Don't put debugging printfs in the code.
2965 @chapter Porting @value{GDBN}
2967 Most of the work in making @value{GDBN} compile on a new machine is in specifying
2968 the configuration of the machine. This is done in a dizzying variety of
2969 header files and configuration scripts, which we hope to make more
2970 sensible soon. Let's say your new host is called an @var{xyz} (e.g.
2971 @samp{sun4}), and its full three-part configuration name is
2972 @code{@var{arch}-@var{xvend}-@var{xos}} (e.g. @samp{sparc-sun-sunos4}).
2975 In the top level directory, edit @file{config.sub} and add @var{arch},
2976 @var{xvend}, and @var{xos} to the lists of supported architectures,
2977 vendors, and operating systems near the bottom of the file. Also, add
2978 @var{xyz} as an alias that maps to
2979 @code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by
2983 ./config.sub @var{xyz}
2988 ./config.sub @code{@var{arch}-@var{xvend}-@var{xos}}
2991 which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}}
2992 and no error messages.
2994 You need to port BFD, if that hasn't been done already. Porting BFD is
2995 beyond the scope of this manual.
2997 To configure @value{GDBN} itself, edit @file{gdb/configure.host} to recognize
2998 your system and set @code{gdb_host} to @var{xyz}, and (unless your
2999 desired target is already available) also edit @file{gdb/configure.tgt},
3000 setting @code{gdb_target} to something appropriate (for instance,
3003 Finally, you'll need to specify and define @value{GDBN}'s host-, native-, and
3004 target-dependent @file{.h} and @file{.c} files used for your
3007 @section Configuring @value{GDBN} for Release
3009 From the top level directory (containing @file{gdb}, @file{bfd},
3010 @file{libiberty}, and so on):
3012 make -f Makefile.in gdb.tar.gz
3015 This will properly configure, clean, rebuild any files that are
3016 distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}),
3017 and will then make a tarfile. (If the top level directory has already
3018 been configured, you can just do @code{make gdb.tar.gz} instead.)
3020 This procedure requires:
3022 @item symbolic links
3023 @item @code{makeinfo} (texinfo2 level)
3026 @item @code{yacc} or @code{bison}
3029 @dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.).
3031 @subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
3033 @file{gdb.texinfo} is currently marked up using the texinfo-2 macros,
3034 which are not yet a default for anything (but we have to start using
3037 For making paper, the only thing this implies is the right generation of
3038 @file{texinfo.tex} needs to be included in the distribution.
3040 For making info files, however, rather than duplicating the texinfo2
3041 distribution, generate @file{gdb-all.texinfo} locally, and include the
3042 files @file{gdb.info*} in the distribution. Note the plural;
3043 @code{makeinfo} will split the document into one overall file and five
3044 or so included files.
3050 The testsuite is an important component of the @value{GDBN} package. While it is
3051 always worthwhile to encourage user testing, in practice this is rarely
3052 sufficient; users typically use only a small subset of the available
3053 commands, and it has proven all too common for a change to cause a
3054 significant regression that went unnoticed for some time.
3056 The @value{GDBN} testsuite uses the DejaGNU testing framework. DejaGNU is built
3057 using tcl and expect. The tests themselves are calls to various tcl
3058 procs; the framework runs all the procs and summarizes the passes and
3061 @section Using the Testsuite
3063 To run the testsuite, simply go to the @value{GDBN} object directory (or to the
3064 testsuite's objdir) and type @code{make check}. This just sets up some
3065 environment variables and invokes DejaGNU's @code{runtest} script. While
3066 the testsuite is running, you'll get mentions of which test file is in use,
3067 and a mention of any unexpected passes or fails. When the testsuite is
3068 finished, you'll get a summary that looks like this:
3072 # of expected passes 6016
3073 # of unexpected failures 58
3074 # of unexpected successes 5
3075 # of expected failures 183
3076 # of unresolved testcases 3
3077 # of untested testcases 5
3079 The ideal test run consists of expected passes only; however, reality
3080 conspires to keep us from this ideal. Unexpected failures indicate
3081 real problems, whether in @value{GDBN} or in the testsuite. Expected failures
3082 are still failures, but ones which have been decided are too hard to
3083 deal with at the time; for instance, a test case might work everywhere
3084 except on AIX, and there is no prospect of the AIX case being fixed in
3085 the near future. Expected failures should not be added lightly, since
3086 you may be masking serious bugs in @value{GDBN}. Unexpected successes are expected
3087 fails that are passing for some reason, while unresolved and untested
3088 cases often indicate some minor catastrophe, such as the compiler being
3089 unable to deal with a test program.
3091 When making any significant change to @value{GDBN}, you should run the testsuite
3092 before and after the change, to confirm that there are no regressions.
3093 Note that truly complete testing would require that you run the
3094 testsuite with all supported configurations and a variety of compilers;
3095 however this is more than really necessary. In many cases testing with
3096 a single configuration is sufficient. Other useful options are to test
3097 one big-endian (Sparc) and one little-endian (x86) host, a cross config
3098 with a builtin simulator (powerpc-eabi, mips-elf), or a 64-bit host
3101 If you add new functionality to @value{GDBN}, please consider adding tests for it
3102 as well; this way future @value{GDBN} hackers can detect and fix their changes
3103 that break the functionality you added. Similarly, if you fix a bug
3104 that was not previously reported as a test failure, please add a test
3105 case for it. Some cases are extremely difficult to test, such as code
3106 that handles host OS failures or bugs in particular versions of
3107 compilers, and it's OK not to try to write tests for all of those.
3109 @section Testsuite Organization
3111 The testsuite is entirely contained in @file{gdb/testsuite}. While the
3112 testsuite includes some makefiles and configury, these are very minimal,
3113 and used for little besides cleaning up, since the tests themselves
3114 handle the compilation of the programs that @value{GDBN} will run. The file
3115 @file{testsuite/lib/gdb.exp} contains common utility procs useful for
3116 all @value{GDBN} tests, while the directory @file{testsuite/config} contains
3117 configuration-specific files, typically used for special-purpose
3118 definitions of procs like @code{gdb_load} and @code{gdb_start}.
3120 The tests themselves are to be found in @file{testsuite/gdb.*} and
3121 subdirectories of those. The names of the test files must always end
3122 with @file{.exp}. DejaGNU collects the test files by wildcarding
3123 in the test directories, so both subdirectories and individual files
3124 get chosen and run in alphabetical order.
3126 The following table lists the main types of subdirectories and what they
3127 are for. Since DejaGNU finds test files no matter where they are
3128 located, and since each test file sets up its own compilation and
3129 execution environment, this organization is simply for convenience and
3136 This is the base testsuite. The tests in it should apply to all
3137 configurations of @value{GDBN} (but generic native-only tests may live here).
3138 The test programs should be in the subset of C that is valid K&R,
3139 ANSI/ISO, and C++ (ifdefs are allowed if necessary, for instance
3142 @item gdb.@var{lang}
3144 Language-specific tests for all languages besides C. Examples are
3145 @file{gdb.c++} and @file{gdb.java}.
3147 @item gdb.@var{platform}
3149 Non-portable tests. The tests are specific to a specific configuration
3150 (host or target), such as HP-UX or eCos. Example is @file{gdb.hp}, for
3153 @item gdb.@var{compiler}
3155 Tests specific to a particular compiler. As of this writing (June
3156 1999), there aren't currently any groups of tests in this category that
3157 couldn't just as sensibly be made platform-specific, but one could
3158 imagine a gdb.gcc, for tests of @value{GDBN}'s handling of GCC extensions.
3160 @item gdb.@var{subsystem}
3162 Tests that exercise a specific @value{GDBN} subsystem in more depth. For
3163 instance, @file{gdb.disasm} exercises various disassemblers, while
3164 @file{gdb.stabs} tests pathways through the stabs symbol reader.
3168 @section Writing Tests
3170 In many areas, the @value{GDBN} tests are already quite comprehensive; you
3171 should be able to copy existing tests to handle new cases.
3173 You should try to use @code{gdb_test} whenever possible, since it
3174 includes cases to handle all the unexpected errors that might happen.
3175 However, it doesn't cost anything to add new test procedures; for
3176 instance, @file{gdb.base/exprs.exp} defines a @code{test_expr} that
3177 calls @code{gdb_test} multiple times.
3179 Only use @code{send_gdb} and @code{gdb_expect} when absolutely
3180 necessary, such as when @value{GDBN} has several valid responses to a command.
3182 The source language programs do @emph{not} need to be in a consistent
3183 style. Since @value{GDBN} is used to debug programs written in many different
3184 styles, it's worth having a mix of styles in the testsuite; for
3185 instance, some @value{GDBN} bugs involving the display of source lines would
3186 never manifest themselves if the programs used GNU coding style
3193 Check the @file{README} file, it often has useful information that does not
3194 appear anywhere else in the directory.
3197 * Getting Started:: Getting started working on @value{GDBN}
3198 * Debugging GDB:: Debugging @value{GDBN} with itself
3201 @node Getting Started,,, Hints
3203 @section Getting Started
3205 @value{GDBN} is a large and complicated program, and if you first starting to
3206 work on it, it can be hard to know where to start. Fortunately, if you
3207 know how to go about it, there are ways to figure out what is going on.
3209 This manual, the @value{GDBN} Internals manual, has information which applies
3210 generally to many parts of @value{GDBN}.
3212 Information about particular functions or data structures are located in
3213 comments with those functions or data structures. If you run across a
3214 function or a global variable which does not have a comment correctly
3215 explaining what is does, this can be thought of as a bug in @value{GDBN}; feel
3216 free to submit a bug report, with a suggested comment if you can figure
3217 out what the comment should say. If you find a comment which is
3218 actually wrong, be especially sure to report that.
3220 Comments explaining the function of macros defined in host, target, or
3221 native dependent files can be in several places. Sometimes they are
3222 repeated every place the macro is defined. Sometimes they are where the
3223 macro is used. Sometimes there is a header file which supplies a
3224 default definition of the macro, and the comment is there. This manual
3225 also documents all the available macros.
3226 @c (@pxref{Host Conditionals}, @pxref{Target
3227 @c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete
3230 Start with the header files. Once you have some idea of how @value{GDBN}'s internal
3231 symbol tables are stored (see @file{symtab.h}, @file{gdbtypes.h}), you
3232 will find it much easier to understand the code which uses and creates
3233 those symbol tables.
3235 You may wish to process the information you are getting somehow, to
3236 enhance your understanding of it. Summarize it, translate it to another
3237 language, add some (perhaps trivial or non-useful) feature to @value{GDBN}, use
3238 the code to predict what a test case would do and write the test case
3239 and verify your prediction, etc. If you are reading code and your eyes
3240 are starting to glaze over, this is a sign you need to use a more active
3243 Once you have a part of @value{GDBN} to start with, you can find more
3244 specifically the part you are looking for by stepping through each
3245 function with the @code{next} command. Do not use @code{step} or you
3246 will quickly get distracted; when the function you are stepping through
3247 calls another function try only to get a big-picture understanding
3248 (perhaps using the comment at the beginning of the function being
3249 called) of what it does. This way you can identify which of the
3250 functions being called by the function you are stepping through is the
3251 one which you are interested in. You may need to examine the data
3252 structures generated at each stage, with reference to the comments in
3253 the header files explaining what the data structures are supposed to
3256 Of course, this same technique can be used if you are just reading the
3257 code, rather than actually stepping through it. The same general
3258 principle applies---when the code you are looking at calls something
3259 else, just try to understand generally what the code being called does,
3260 rather than worrying about all its details.
3262 A good place to start when tracking down some particular area is with a
3263 command which invokes that feature. Suppose you want to know how
3264 single-stepping works. As a @value{GDBN} user, you know that the @code{step}
3265 command invokes single-stepping. The command is invoked via command
3266 tables (see @file{command.h}); by convention the function which actually
3267 performs the command is formed by taking the name of the command and
3268 adding @samp{_command}, or in the case of an @code{info} subcommand,
3269 @samp{_info}. For example, the @code{step} command invokes the
3270 @code{step_command} function and the @code{info display} command invokes
3271 @code{display_info}. When this convention is not followed, you might
3272 have to use @code{grep} or @kbd{M-x tags-search} in emacs, or run @value{GDBN} on
3273 itself and set a breakpoint in @code{execute_command}.
3275 If all of the above fail, it may be appropriate to ask for information
3276 on @code{bug-gdb}. But @emph{never} post a generic question like ``I was
3277 wondering if anyone could give me some tips about understanding
3278 @value{GDBN}''---if we had some magic secret we would put it in this manual.
3279 Suggestions for improving the manual are always welcome, of course.
3281 @node Debugging GDB,,,Hints
3283 @section Debugging @value{GDBN} with itself
3285 If @value{GDBN} is limping on your machine, this is the preferred way to get it
3286 fully functional. Be warned that in some ancient Unix systems, like
3287 Ultrix 4.2, a program can't be running in one process while it is being
3288 debugged in another. Rather than typing the command @code{@w{./gdb
3289 ./gdb}}, which works on Suns and such, you can copy @file{gdb} to
3290 @file{gdb2} and then type @code{@w{./gdb ./gdb2}}.
3292 When you run @value{GDBN} in the @value{GDBN} source directory, it will read a
3293 @file{.gdbinit} file that sets up some simple things to make debugging
3294 gdb easier. The @code{info} command, when executed without a subcommand
3295 in a @value{GDBN} being debugged by gdb, will pop you back up to the top level
3296 gdb. See @file{.gdbinit} for details.
3298 If you use emacs, you will probably want to do a @code{make TAGS} after
3299 you configure your distribution; this will put the machine dependent
3300 routines for your local machine where they will be accessed first by
3303 Also, make sure that you've either compiled @value{GDBN} with your local cc, or
3304 have run @code{fixincludes} if you are compiling with gcc.
3306 @section Submitting Patches
3308 Thanks for thinking of offering your changes back to the community of
3309 @value{GDBN} users. In general we like to get well designed enhancements.
3310 Thanks also for checking in advance about the best way to transfer the
3313 The @value{GDBN} maintainers will only install ``cleanly designed'' patches.
3314 This manual summarizes what we believe to be clean design for @value{GDBN}.
3316 If the maintainers don't have time to put the patch in when it arrives,
3317 or if there is any question about a patch, it goes into a large queue
3318 with everyone else's patches and bug reports.
3320 The legal issue is that to incorporate substantial changes requires a
3321 copyright assignment from you and/or your employer, granting ownership
3322 of the changes to the Free Software Foundation. You can get the
3323 standard documents for doing this by sending mail to @code{gnu@@gnu.org}
3324 and asking for it. We recommend that people write in "All programs
3325 owned by the Free Software Foundation" as "NAME OF PROGRAM", so that
3326 changes in many programs (not just @value{GDBN}, but GAS, Emacs, GCC, etc) can be
3327 contributed with only one piece of legalese pushed through the
3328 bureacracy and filed with the FSF. We can't start merging changes until
3329 this paperwork is received by the FSF (their rules, which we follow
3330 since we maintain it for them).
3332 Technically, the easiest way to receive changes is to receive each
3333 feature as a small context diff or unidiff, suitable for "patch". Each
3334 message sent to me should include the changes to C code and header files
3335 for a single feature, plus ChangeLog entries for each directory where
3336 files were modified, and diffs for any changes needed to the manuals
3337 (gdb/doc/gdb.texinfo or gdb/doc/gdbint.texinfo). If there are a lot of
3338 changes for a single feature, they can be split down into multiple
3341 In this way, if we read and like the feature, we can add it to the
3342 sources with a single patch command, do some testing, and check it in.
3343 If you leave out the ChangeLog, we have to write one. If you leave
3344 out the doc, we have to puzzle out what needs documenting. Etc.
3346 The reason to send each change in a separate message is that we will not
3347 install some of the changes. They'll be returned to you with questions
3348 or comments. If we're doing our job correctly, the message back to you
3349 will say what you have to fix in order to make the change acceptable.
3350 The reason to have separate messages for separate features is so that
3351 the acceptable changes can be installed while one or more changes are
3352 being reworked. If multiple features are sent in a single message, we
3353 tend to not put in the effort to sort out the acceptable changes from
3354 the unacceptable, so none of the features get installed until all are
3357 If this sounds painful or authoritarian, well, it is. But we get a lot
3358 of bug reports and a lot of patches, and many of them don't get
3359 installed because we don't have the time to finish the job that the bug
3360 reporter or the contributor could have done. Patches that arrive
3361 complete, working, and well designed, tend to get installed on the day
3362 they arrive. The others go into a queue and get installed as time
3363 permits, which, since the maintainers have many demands to meet, may not
3364 be for quite some time.
3366 Please send patches directly to the @value{GDBN} maintainers at
3367 @code{gdb-patches@@sourceware.cygnus.com}.
3369 @section Obsolete Conditionals
3371 Fragments of old code in @value{GDBN} sometimes reference or set the following
3372 configuration macros. They should not be used by new code, and old uses
3373 should be removed as those parts of the debugger are otherwise touched.
3377 @item STACK_END_ADDR
3378 This macro used to define where the end of the stack appeared, for use
3379 in interpreting core file formats that don't record this address in the
3380 core file itself. This information is now configured in BFD, and @value{GDBN}
3381 gets the info portably from there. The values in @value{GDBN}'s configuration
3382 files should be moved into BFD configuration files (if needed there),
3383 and deleted from all of @value{GDBN}'s config files.
3385 Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
3386 is so old that it has never been converted to use BFD. Now that's old!
3388 @item PYRAMID_CONTROL_FRAME_DEBUGGING
3392 @item PYRAMID_PTRACE
3395 @item REG_STACK_SEGMENT
3400 @c TeX can handle the contents at the start but makeinfo 3.12 can not