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
42 @title @value{GDBN} Internals
43 @subtitle{A guide to the internals of the GNU debugger}
45 @author Cygnus Solutions
46 @author Second Edition:
48 @author Cygnus Solutions
51 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
52 \xdef\manvers{\$Revision$} % For use in headers, footers too
54 \hfill Cygnus Solutions\par
56 \hfill \TeX{}info \texinfoversion\par
60 @vskip 0pt plus 1filll
61 Copyright @copyright{} 1990-1999 Free Software Foundation, Inc.
63 Permission is granted to make and distribute verbatim copies of
64 this manual provided the copyright notice and this permission notice
65 are preserved on all copies.
69 @c TeX can handle the contents at the start but makeinfo 3.12 can not
75 @c Perhaps this should be the title of the document (but only for info,
76 @c not for TeX). Existing GNU manuals seem inconsistent on this point.
77 @top Scope of this Document
79 This document documents the internals of the GNU debugger, @value{GDBN}. It
80 includes description of @value{GDBN}'s key algorithms and operations, as well
81 as the mechanisms that adapt @value{GDBN} to specific hosts and targets.
91 * Target Architecture Definition::
92 * Target Vector Definition::
104 @chapter Requirements
105 @cindex requirements for @value{GDBN}
107 Before diving into the internals, you should understand the formal
108 requirements and other expectations for @value{GDBN}. Although some
109 of these may seem obvious, there have been proposals for @value{GDBN}
110 that have run counter to these requirements.
112 First of all, @value{GDBN} is a debugger. It's not designed to be a
113 front panel for embedded systems. It's not a text editor. It's not a
114 shell. It's not a programming environment.
116 @value{GDBN} is an interactive tool. Although a batch mode is
117 available, @value{GDBN}'s primary role is to interact with a human
120 @value{GDBN} should be responsive to the user. A programmer hot on
121 the trail of a nasty bug, and operating under a looming deadline, is
122 going to be very impatient of everything, including the response time
123 to debugger commands.
125 @value{GDBN} should be relatively permissive, such as for expressions.
126 While the compiler should be picky (or have the option to be made
127 picky), since source code lives for a long time usuazlly, the
128 programmer doing debugging shouldn't be spending time figuring out to
129 mollify the debugger.
131 @value{GDBN} will be called upon to deal with really large programs.
132 Executable sizes of 50 to 100 megabytes occur regularly, and we've
133 heard reports of programs approaching 1 gigabyte in size.
135 @value{GDBN} should be able to run everywhere. No other debugger is
136 available for even half as many configurations as @value{GDBN}
140 @node Overall Structure
142 @chapter Overall Structure
144 @value{GDBN} consists of three major subsystems: user interface,
145 symbol handling (the @dfn{symbol side}), and target system handling (the
148 The user interface consists of several actual interfaces, plus
151 The symbol side consists of object file readers, debugging info
152 interpreters, symbol table management, source language expression
153 parsing, type and value printing.
155 The target side consists of execution control, stack frame analysis, and
156 physical target manipulation.
158 The target side/symbol side division is not formal, and there are a
159 number of exceptions. For instance, core file support involves symbolic
160 elements (the basic core file reader is in BFD) and target elements (it
161 supplies the contents of memory and the values of registers). Instead,
162 this division is useful for understanding how the minor subsystems
165 @section The Symbol Side
167 The symbolic side of @value{GDBN} can be thought of as ``everything
168 you can do in @value{GDBN} without having a live program running''.
169 For instance, you can look at the types of variables, and evaluate
170 many kinds of expressions.
172 @section The Target Side
174 The target side of @value{GDBN} is the ``bits and bytes manipulator''.
175 Although it may make reference to symbolic info here and there, most
176 of the target side will run with only a stripped executable
177 available---or even no executable at all, in remote debugging cases.
179 Operations such as disassembly, stack frame crawls, and register
180 display, are able to work with no symbolic info at all. In some cases,
181 such as disassembly, @value{GDBN} will use symbolic info to present addresses
182 relative to symbols rather than as raw numbers, but it will work either
185 @section Configurations
189 @dfn{Host} refers to attributes of the system where @value{GDBN} runs.
190 @dfn{Target} refers to the system where the program being debugged
191 executes. In most cases they are the same machine, in which case a
192 third type of @dfn{Native} attributes come into play.
194 Defines and include files needed to build on the host are host support.
195 Examples are tty support, system defined types, host byte order, host
198 Defines and information needed to handle the target format are target
199 dependent. Examples are the stack frame format, instruction set,
200 breakpoint instruction, registers, and how to set up and tear down the stack
203 Information that is only needed when the host and target are the same,
204 is native dependent. One example is Unix child process support; if the
205 host and target are not the same, doing a fork to start the target
206 process is a bad idea. The various macros needed for finding the
207 registers in the @code{upage}, running @code{ptrace}, and such are all
208 in the native-dependent files.
210 Another example of native-dependent code is support for features that
211 are really part of the target environment, but which require
212 @code{#include} files that are only available on the host system. Core
213 file handling and @code{setjmp} handling are two common cases.
215 When you want to make @value{GDBN} work ``native'' on a particular machine, you
216 have to include all three kinds of information.
224 @value{GDBN} uses a number of debugging-specific algorithms. They are
225 often not very complicated, but get lost in the thicket of special
226 cases and real-world issues. This chapter describes the basic
227 algorithms and mentions some of the specific target definitions that
233 @cindex call stack frame
234 A frame is a construct that @value{GDBN} uses to keep track of calling
235 and called functions.
237 @findex create_new_frame
239 @code{FRAME_FP} in the machine description has no meaning to the
240 machine-independent part of @value{GDBN}, except that it is used when
241 setting up a new frame from scratch, as follows:
244 create_new_frame (read_register (FP_REGNUM), read_pc ()));
247 @cindex frame pointer register
248 Other than that, all the meaning imparted to @code{FP_REGNUM} is
249 imparted by the machine-dependent code. So, @code{FP_REGNUM} can have
250 any value that is convenient for the code that creates new frames.
251 (@code{create_new_frame} calls @code{INIT_EXTRA_FRAME_INFO} if it is
252 defined; that is where you should use the @code{FP_REGNUM} value, if
253 your frames are nonstandard.)
256 Given a @value{GDBN} frame, define @code{FRAME_CHAIN} to determine the
257 address of the calling function's frame. This will be used to create
258 a new @value{GDBN} frame struct, and then @code{INIT_EXTRA_FRAME_INFO}
259 and @code{INIT_FRAME_PC} will be called for the new frame.
261 @section Breakpoint Handling
264 In general, a breakpoint is a user-designated location in the program
265 where the user wants to regain control if program execution ever reaches
268 There are two main ways to implement breakpoints; either as ``hardware''
269 breakpoints or as ``software'' breakpoints.
271 @cindex hardware breakpoints
272 @cindex program counter
273 Hardware breakpoints are sometimes available as a builtin debugging
274 features with some chips. Typically these work by having dedicated
275 register into which the breakpoint address may be stored. If the PC
276 (shorthand for @dfn{program counter})
277 ever matches a value in a breakpoint registers, the CPU raises an
278 exception and reports it to @value{GDBN}.
280 Another possibility is when an emulator is in use; many emulators
281 include circuitry that watches the address lines coming out from the
282 processor, and force it to stop if the address matches a breakpoint's
285 A third possibility is that the target already has the ability to do
286 breakpoints somehow; for instance, a ROM monitor may do its own
287 software breakpoints. So although these are not literally ``hardware
288 breakpoints'', from @value{GDBN}'s point of view they work the same;
289 @value{GDBN} need not do nothing more than set the breakpoint and wait
290 for something to happen.
292 Since they depend on hardware resources, hardware breakpoints may be
293 limited in number; when the user asks for more, @value{GDBN} will
294 start trying to set software breakpoints.
296 @cindex software breakpoints
297 Software breakpoints require @value{GDBN} to do somewhat more work.
298 The basic theory is that @value{GDBN} will replace a program
299 instruction with a trap, illegal divide, or some other instruction
300 that will cause an exception, and then when it's encountered,
301 @value{GDBN} will take the exception and stop the program. When the
302 user says to continue, @value{GDBN} will restore the original
303 instruction, single-step, re-insert the trap, and continue on.
305 Since it literally overwrites the program being tested, the program area
306 must be writeable, so this technique won't work on programs in ROM. It
307 can also distort the behavior of programs that examine themselves,
308 although such a situation would be highly unusual.
310 Also, the software breakpoint instruction should be the smallest size of
311 instruction, so it doesn't overwrite an instruction that might be a jump
312 target, and cause disaster when the program jumps into the middle of the
313 breakpoint instruction. (Strictly speaking, the breakpoint must be no
314 larger than the smallest interval between instructions that may be jump
315 targets; perhaps there is an architecture where only even-numbered
316 instructions may jumped to.) Note that it's possible for an instruction
317 set not to have any instructions usable for a software breakpoint,
318 although in practice only the ARC has failed to define such an
322 The basic definition of the software breakpoint is the macro
325 Basic breakpoint object handling is in @file{breakpoint.c}. However,
326 much of the interesting breakpoint action is in @file{infrun.c}.
328 @section Single Stepping
330 @section Signal Handling
332 @section Thread Handling
334 @section Inferior Function Calls
336 @section Longjmp Support
338 @cindex @code{longjmp} debugging
339 @value{GDBN} has support for figuring out that the target is doing a
340 @code{longjmp} and for stopping at the target of the jump, if we are
341 stepping. This is done with a few specialized internal breakpoints,
342 which are visible in the output of the @samp{maint info breakpoint}
345 @findex GET_LONGJMP_TARGET
346 To make this work, you need to define a macro called
347 @code{GET_LONGJMP_TARGET}, which will examine the @code{jmp_buf}
348 structure and extract the longjmp target address. Since @code{jmp_buf}
349 is target specific, you will need to define it in the appropriate
350 @file{tm-@var{target}.h} file. Look in @file{tm-sun4os4.h} and
351 @file{sparc-tdep.c} for examples of how to do this.
355 @chapter User Interface
357 @value{GDBN} has several user interfaces. Although the command-line interface
358 is the most common and most familiar, there are others.
360 @section Command Interpreter
362 @cindex command interpreter
363 The command interpreter in @value{GDBN} is fairly simple. It is designed to
364 allow for the set of commands to be augmented dynamically, and also
365 has a recursive subcommand capability, where the first argument to
366 a command may itself direct a lookup on a different command list.
368 For instance, the @samp{set} command just starts a lookup on the
369 @code{setlist} command list, while @samp{set thread} recurses
370 to the @code{set_thread_cmd_list}.
374 To add commands in general, use @code{add_cmd}. @code{add_com} adds to
375 the main command list, and should be used for those commands. The usual
376 place to add commands is in the @code{_initialize_@var{xyz}} routines at
377 the ends of most source files.
379 @cindex deprecating commands
380 @findex deprecate_cmd
381 Before removing commands from the command set it is a good idea to
382 deprecate them for some time. Use @code{deprecate_cmd} on commands or
383 aliases to set the deprecated flag. @code{deprecate_cmd} takes a
384 @code{struct cmd_list_element} as it's first argument. You can use the
385 return value from @code{add_com} or @code{add_cmd} to deprecate the
386 command immediately after it is created.
388 The first time a comamnd is used the user will be warned and offered a
389 replacement (if one exists). Note that the replacement string passed to
390 @code{deprecate_cmd} should be the full name of the command, i.e. the
391 entire string the user should type at the command line.
393 @section Console Printing
399 @cindex @code{libgdb}
400 @code{libgdb} was an abortive project of years ago. The theory was to
401 provide an API to @value{GDBN}'s functionality.
403 @node Symbol Handling
405 @chapter Symbol Handling
407 Symbols are a key part of @value{GDBN}'s operation. Symbols include variables,
408 functions, and types.
410 @section Symbol Reading
412 @cindex symbol reading
413 @cindex reading of symbols
415 @value{GDBN} reads symbols from @dfn{symbol files}. The usual symbol
416 file is the file containing the program which @value{GDBN} is
417 debugging. @value{GDBN} can be directed to use a different file for
418 symbols (with the @samp{symbol-file} command), and it can also read
419 more symbols via the @samp{add-file} and @samp{load} commands, or while
420 reading symbols from shared libraries.
423 Symbol files are initially opened by code in @file{symfile.c} using
424 the BFD library (@pxref{Support Libraries}). BFD identifies the type
425 of the file by examining its header. @code{find_sym_fns} then uses
426 this identification to locate a set of symbol-reading functions.
428 @findex add_symtab_fns
429 @cindex @code{sym_fns} structure
430 @cindex adding a symbol-reading module
431 Symbol-reading modules identify themselves to @value{GDBN} by calling
432 @code{add_symtab_fns} during their module initialization. The argument
433 to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the
434 name (or name prefix) of the symbol format, the length of the prefix,
435 and pointers to four functions. These functions are called at various
436 times to process symbol files whose identification matches the specified
439 The functions supplied by each module are:
442 @item @var{xyz}_symfile_init(struct sym_fns *sf)
444 @cindex secondary symbol file
445 Called from @code{symbol_file_add} when we are about to read a new
446 symbol file. This function should clean up any internal state (possibly
447 resulting from half-read previous files, for example) and prepare to
448 read a new symbol file. Note that the symbol file which we are reading
449 might be a new ``main'' symbol file, or might be a secondary symbol file
450 whose symbols are being added to the existing symbol table.
452 The argument to @code{@var{xyz}_symfile_init} is a newly allocated
453 @code{struct sym_fns} whose @code{bfd} field contains the BFD for the
454 new symbol file being read. Its @code{private} field has been zeroed,
455 and can be modified as desired. Typically, a struct of private
456 information will be @code{malloc}'d, and a pointer to it will be placed
457 in the @code{private} field.
459 There is no result from @code{@var{xyz}_symfile_init}, but it can call
460 @code{error} if it detects an unavoidable problem.
462 @item @var{xyz}_new_init()
464 Called from @code{symbol_file_add} when discarding existing symbols.
465 This function needs only handle the symbol-reading module's internal
466 state; the symbol table data structures visible to the rest of
467 @value{GDBN} will be discarded by @code{symbol_file_add}. It has no
468 arguments and no result. It may be called after
469 @code{@var{xyz}_symfile_init}, if a new symbol table is being read, or
470 may be called alone if all symbols are simply being discarded.
472 @item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)
474 Called from @code{symbol_file_add} to actually read the symbols from a
475 symbol-file into a set of psymtabs or symtabs.
477 @code{sf} points to the @code{struct sym_fns} originally passed to
478 @code{@var{xyz}_sym_init} for possible initialization. @code{addr} is
479 the offset between the file's specified start address and its true
480 address in memory. @code{mainline} is 1 if this is the main symbol
481 table being read, and 0 if a secondary symbol file (e.g. shared library
482 or dynamically loaded file) is being read.@refill
485 In addition, if a symbol-reading module creates psymtabs when
486 @var{xyz}_symfile_read is called, these psymtabs will contain a pointer
487 to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called
488 from any point in the @value{GDBN} symbol-handling code.
491 @item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst)
493 Called from @code{psymtab_to_symtab} (or the @code{PSYMTAB_TO_SYMTAB} macro) if
494 the psymtab has not already been read in and had its @code{pst->symtab}
495 pointer set. The argument is the psymtab to be fleshed-out into a
496 symtab. Upon return, @code{pst->readin} should have been set to 1, and
497 @code{pst->symtab} should contain a pointer to the new corresponding symtab, or
498 zero if there were no symbols in that part of the symbol file.
501 @section Partial Symbol Tables
503 @value{GDBN} has three types of symbol tables:
506 @cindex full symbol table
509 Full symbol tables (@dfn{symtabs}). These contain the main
510 information about symbols and addresses.
514 Partial symbol tables (@dfn{psymtabs}). These contain enough
515 information to know when to read the corresponding part of the full
518 @cindex minimal symbol table
521 Minimal symbol tables (@dfn{msymtabs}). These contain information
522 gleaned from non-debugging symbols.
525 @cindex partial symbol table
526 This section describes partial symbol tables.
528 A psymtab is constructed by doing a very quick pass over an executable
529 file's debugging information. Small amounts of information are
530 extracted---enough to identify which parts of the symbol table will
531 need to be re-read and fully digested later, when the user needs the
532 information. The speed of this pass causes @value{GDBN} to start up very
533 quickly. Later, as the detailed rereading occurs, it occurs in small
534 pieces, at various times, and the delay therefrom is mostly invisible to
536 @c (@xref{Symbol Reading}.)
538 The symbols that show up in a file's psymtab should be, roughly, those
539 visible to the debugger's user when the program is not running code from
540 that file. These include external symbols and types, static symbols and
541 types, and @code{enum} values declared at file scope.
543 The psymtab also contains the range of instruction addresses that the
544 full symbol table would represent.
546 @cindex finding a symbol
547 @cindex symbol lookup
548 The idea is that there are only two ways for the user (or much of the
549 code in the debugger) to reference a symbol:
552 @findex find_pc_function
555 By its address (e.g. execution stops at some address which is inside a
556 function in this file). The address will be noticed to be in the
557 range of this psymtab, and the full symtab will be read in.
558 @code{find_pc_function}, @code{find_pc_line}, and other
559 @code{find_pc_@dots{}} functions handle this.
561 @cindex lookup_symbol
564 (e.g. the user asks to print a variable, or set a breakpoint on a
565 function). Global names and file-scope names will be found in the
566 psymtab, which will cause the symtab to be pulled in. Local names will
567 have to be qualified by a global name, or a file-scope name, in which
568 case we will have already read in the symtab as we evaluated the
569 qualifier. Or, a local symbol can be referenced when we are ``in'' a
570 local scope, in which case the first case applies. @code{lookup_symbol}
571 does most of the work here.
574 The only reason that psymtabs exist is to cause a symtab to be read in
575 at the right moment. Any symbol that can be elided from a psymtab,
576 while still causing that to happen, should not appear in it. Since
577 psymtabs don't have the idea of scope, you can't put local symbols in
578 them anyway. Psymtabs don't have the idea of the type of a symbol,
579 either, so types need not appear, unless they will be referenced by
582 It is a bug for @value{GDBN} to behave one way when only a psymtab has
583 been read, and another way if the corresponding symtab has been read
584 in. Such bugs are typically caused by a psymtab that does not contain
585 all the visible symbols, or which has the wrong instruction address
588 The psymtab for a particular section of a symbol file (objfile) could be
589 thrown away after the symtab has been read in. The symtab should always
590 be searched before the psymtab, so the psymtab will never be used (in a
591 bug-free environment). Currently, psymtabs are allocated on an obstack,
592 and all the psymbols themselves are allocated in a pair of large arrays
593 on an obstack, so there is little to be gained by trying to free them
594 unless you want to do a lot more work.
598 @unnumberedsubsec Fundamental Types (e.g., @code{FT_VOID}, @code{FT_BOOLEAN}).
600 @cindex fundamental types
601 These are the fundamental types that @value{GDBN} uses internally. Fundamental
602 types from the various debugging formats (stabs, ELF, etc) are mapped
603 into one of these. They are basically a union of all fundamental types
604 that @value{GDBN} knows about for all the languages that @value{GDBN}
607 @unnumberedsubsec Type Codes (e.g., @code{TYPE_CODE_PTR}, @code{TYPE_CODE_ARRAY}).
610 Each time @value{GDBN} builds an internal type, it marks it with one
611 of these types. The type may be a fundamental type, such as
612 @code{TYPE_CODE_INT}, or a derived type, such as @code{TYPE_CODE_PTR}
613 which is a pointer to another type. Typically, several @code{FT_*}
614 types map to one @code{TYPE_CODE_*} type, and are distinguished by
615 other members of the type struct, such as whether the type is signed
616 or unsigned, and how many bits it uses.
618 @unnumberedsubsec Builtin Types (e.g., @code{builtin_type_void}, @code{builtin_type_char}).
620 These are instances of type structs that roughly correspond to
621 fundamental types and are created as global types for @value{GDBN} to
622 use for various ugly historical reasons. We eventually want to
623 eliminate these. Note for example that @code{builtin_type_int}
624 initialized in @file{gdbtypes.c} is basically the same as a
625 @code{TYPE_CODE_INT} type that is initialized in @file{c-lang.c} for
626 an @code{FT_INTEGER} fundamental type. The difference is that the
627 @code{builtin_type} is not associated with any particular objfile, and
628 only one instance exists, while @file{c-lang.c} builds as many
629 @code{TYPE_CODE_INT} types as needed, with each one associated with
630 some particular objfile.
632 @section Object File Formats
633 @cindex object file formats
637 @cindex @code{a.out} format
638 The @code{a.out} format is the original file format for Unix. It
639 consists of three sections: @code{text}, @code{data}, and @code{bss},
640 which are for program code, initialized data, and uninitialized data,
643 The @code{a.out} format is so simple that it doesn't have any reserved
644 place for debugging information. (Hey, the original Unix hackers used
645 @samp{adb}, which is a machine-language debugger!) The only debugging
646 format for @code{a.out} is stabs, which is encoded as a set of normal
647 symbols with distinctive attributes.
649 The basic @code{a.out} reader is in @file{dbxread.c}.
654 The COFF format was introduced with System V Release 3 (SVR3) Unix.
655 COFF files may have multiple sections, each prefixed by a header. The
656 number of sections is limited.
658 The COFF specification includes support for debugging. Although this
659 was a step forward, the debugging information was woefully limited. For
660 instance, it was not possible to represent code that came from an
663 The COFF reader is in @file{coffread.c}.
668 ECOFF is an extended COFF originally introduced for Mips and Alpha
671 The basic ECOFF reader is in @file{mipsread.c}.
676 The IBM RS/6000 running AIX uses an object file format called XCOFF.
677 The COFF sections, symbols, and line numbers are used, but debugging
678 symbols are @code{dbx}-style stabs whose strings are located in the
679 @code{.debug} section (rather than the string table). For more
680 information, see @ref{Top,,,stabs,The Stabs Debugging Format}.
682 The shared library scheme has a clean interface for figuring out what
683 shared libraries are in use, but the catch is that everything which
684 refers to addresses (symbol tables and breakpoints at least) needs to be
685 relocated for both shared libraries and the main executable. At least
686 using the standard mechanism this can only be done once the program has
687 been run (or the core file has been read).
691 @cindex PE-COFF format
692 Windows 95 and NT use the PE (@dfn{Portable Executable}) format for their
693 executables. PE is basically COFF with additional headers.
695 While BFD includes special PE support, @value{GDBN} needs only the basic
701 The ELF format came with System V Release 4 (SVR4) Unix. ELF is similar
702 to COFF in being organized into a number of sections, but it removes
703 many of COFF's limitations.
705 The basic ELF reader is in @file{elfread.c}.
710 SOM is HP's object file and debug format (not to be confused with IBM's
711 SOM, which is a cross-language ABI).
713 The SOM reader is in @file{hpread.c}.
715 @subsection Other File Formats
717 @cindex Netware Loadable Module format
718 Other file formats that have been supported by @value{GDBN} include Netware
719 Loadable Modules (@file{nlmread.c}.
721 @section Debugging File Formats
723 This section describes characteristics of debugging information that
724 are independent of the object file format.
728 @cindex stabs debugging info
729 @code{stabs} started out as special symbols within the @code{a.out}
730 format. Since then, it has been encapsulated into other file
731 formats, such as COFF and ELF.
733 While @file{dbxread.c} does some of the basic stab processing,
734 including for encapsulated versions, @file{stabsread.c} does
739 @cindex COFF debugging info
740 The basic COFF definition includes debugging information. The level
741 of support is minimal and non-extensible, and is not often used.
743 @subsection Mips debug (Third Eye)
745 @cindex ECOFF debugging info
746 ECOFF includes a definition of a special debug format.
748 The file @file{mdebugread.c} implements reading for this format.
752 @cindex DWARF 1 debugging info
753 DWARF 1 is a debugging format that was originally designed to be
754 used with ELF in SVR4 systems.
760 @c If defined, these are the producer strings in a DWARF 1 file. All of
761 @c these have reasonable defaults already.
763 The DWARF 1 reader is in @file{dwarfread.c}.
767 @cindex DWARF 2 debugging info
768 DWARF 2 is an improved but incompatible version of DWARF 1.
770 The DWARF 2 reader is in @file{dwarf2read.c}.
774 @cindex SOM debugging info
775 Like COFF, the SOM definition includes debugging information.
777 @section Adding a New Symbol Reader to @value{GDBN}
779 @cindex adding debugging info reader
780 If you are using an existing object file format (@code{a.out}, COFF, ELF, etc),
781 there is probably little to be done.
783 If you need to add a new object file format, you must first add it to
784 BFD. This is beyond the scope of this document.
786 You must then arrange for the BFD code to provide access to the
787 debugging symbols. Generally @value{GDBN} will have to call swapping routines
788 from BFD and a few other BFD internal routines to locate the debugging
789 information. As much as possible, @value{GDBN} should not depend on the BFD
790 internal data structures.
792 For some targets (e.g., COFF), there is a special transfer vector used
793 to call swapping routines, since the external data structures on various
794 platforms have different sizes and layouts. Specialized routines that
795 will only ever be implemented by one object file format may be called
796 directly. This interface should be described in a file
797 @file{bfd/lib@var{xyz}.h}, which is included by @value{GDBN}.
800 @node Language Support
802 @chapter Language Support
804 @cindex language support
805 @value{GDBN}'s language support is mainly driven by the symbol reader,
806 although it is possible for the user to set the source language
809 @value{GDBN} chooses the source language by looking at the extension
810 of the file recorded in the debug info; @file{.c} means C, @file{.f}
811 means Fortran, etc. It may also use a special-purpose language
812 identifier if the debug format supports it, like with DWARF.
814 @section Adding a Source Language to @value{GDBN}
816 @cindex adding source language
817 To add other languages to @value{GDBN}'s expression parser, follow the
821 @item Create the expression parser.
823 @cindex expression parser
824 This should reside in a file @file{@var{lang}-exp.y}. Routines for
825 building parsed expressions into a @code{union exp_element} list are in
828 @cindex language parser
829 Since we can't depend upon everyone having Bison, and YACC produces
830 parsers that define a bunch of global names, the following lines
831 @strong{must} be included at the top of the YACC parser, to prevent the
832 various parsers from defining the same global names:
835 #define yyparse @var{lang}_parse
836 #define yylex @var{lang}_lex
837 #define yyerror @var{lang}_error
838 #define yylval @var{lang}_lval
839 #define yychar @var{lang}_char
840 #define yydebug @var{lang}_debug
841 #define yypact @var{lang}_pact
842 #define yyr1 @var{lang}_r1
843 #define yyr2 @var{lang}_r2
844 #define yydef @var{lang}_def
845 #define yychk @var{lang}_chk
846 #define yypgo @var{lang}_pgo
847 #define yyact @var{lang}_act
848 #define yyexca @var{lang}_exca
849 #define yyerrflag @var{lang}_errflag
850 #define yynerrs @var{lang}_nerrs
853 At the bottom of your parser, define a @code{struct language_defn} and
854 initialize it with the right values for your language. Define an
855 @code{initialize_@var{lang}} routine and have it call
856 @samp{add_language(@var{lang}_language_defn)} to tell the rest of @value{GDBN}
857 that your language exists. You'll need some other supporting variables
858 and functions, which will be used via pointers from your
859 @code{@var{lang}_language_defn}. See the declaration of @code{struct
860 language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
861 for more information.
863 @item Add any evaluation routines, if necessary
865 @cindex expression evaluation routines
866 @findex evaluate_subexp
867 @findex prefixify_subexp
868 @findex length_of_subexp
869 If you need new opcodes (that represent the operations of the language),
870 add them to the enumerated type in @file{expression.h}. Add support
871 code for these operations in the @code{evaluate_subexp} function
872 defined in the file @file{eval.c}. Add cases
873 for new opcodes in two functions from @file{parse.c}:
874 @code{prefixify_subexp} and @code{length_of_subexp}. These compute
875 the number of @code{exp_element}s that a given operation takes up.
877 @item Update some existing code
879 Add an enumerated identifier for your language to the enumerated type
880 @code{enum language} in @file{defs.h}.
882 Update the routines in @file{language.c} so your language is included.
883 These routines include type predicates and such, which (in some cases)
884 are language dependent. If your language does not appear in the switch
885 statement, an error is reported.
887 @vindex current_language
888 Also included in @file{language.c} is the code that updates the variable
889 @code{current_language}, and the routines that translate the
890 @code{language_@var{lang}} enumerated identifier into a printable
893 @findex _initialize_language
894 Update the function @code{_initialize_language} to include your
895 language. This function picks the default language upon startup, so is
896 dependent upon which languages that @value{GDBN} is built for.
898 @findex allocate_symtab
899 Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
900 code so that the language of each symtab (source file) is set properly.
901 This is used to determine the language to use at each stack frame level.
902 Currently, the language is set based upon the extension of the source
903 file. If the language can be better inferred from the symbol
904 information, please set the language of the symtab in the symbol-reading
909 Add helper code to @code{print_subexp} (in @file{expprint.c}) to handle any new
910 expression opcodes you have added to @file{expression.h}. Also, add the
911 printed representations of your operators to @code{op_print_tab}.
913 @item Add a place of call
916 Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
917 @code{parse_exp_1} (defined in @file{parse.c}).
919 @item Use macros to trim code
921 @cindex trimming language-dependent code
922 The user has the option of building @value{GDBN} for some or all of the
923 languages. If the user decides to build @value{GDBN} for the language
924 @var{lang}, then every file dependent on @file{language.h} will have the
925 macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to
926 leave out large routines that the user won't need if he or she is not
929 Note that you do not need to do this in your YACC parser, since if @value{GDBN}
930 is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
931 compiled form of your parser) is not linked into @value{GDBN} at all.
933 See the file @file{configure.in} for how @value{GDBN} is configured
934 for different languages.
936 @item Edit @file{Makefile.in}
938 Add dependencies in @file{Makefile.in}. Make sure you update the macro
939 variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
940 not get linked in, or, worse yet, it may not get @code{tar}red into the
945 @node Host Definition
947 @chapter Host Definition
949 With the advent of Autoconf, it's rarely necessary to have host
950 definition machinery anymore.
952 @section Adding a New Host
954 @cindex adding a new host
956 Most of @value{GDBN}'s host configuration support happens via
957 Autoconf. New host-specific definitions should be rarely needed.
958 @value{GDBN} still uses the host-specific definitions and files listed
959 below, but these mostly exist for historical reasons, and should
960 eventually disappear.
962 Several files control @value{GDBN}'s configuration for host systems:
966 @item gdb/config/@var{arch}/@var{xyz}.mh
967 Specifies Makefile fragments needed when hosting on machine @var{xyz}.
968 In particular, this lists the required machine-dependent object files,
969 by defining @samp{XDEPFILES=@dots{}}. Also specifies the header file
970 which describes host @var{xyz}, by defining @code{XM_FILE=
971 xm-@var{xyz}.h}. You can also define @code{CC}, @code{SYSV_DEFINE},
972 @code{XM_CFLAGS}, @code{XM_ADD_FILES}, @code{XM_CLIBS}, @code{XM_CDEPS},
973 etc.; see @file{Makefile.in}.
975 @item gdb/config/@var{arch}/xm-@var{xyz}.h
976 (@file{xm.h} is a link to this file, created by @code{configure}). Contains C
977 macro definitions describing the host system environment, such as byte
978 order, host C compiler and library.
980 @item gdb/@var{xyz}-xdep.c
981 Contains any miscellaneous C code required for this machine as a host.
982 On most machines it doesn't exist at all. If it does exist, put
983 @file{@var{xyz}-xdep.o} into the @code{XDEPFILES} line in
984 @file{gdb/config/@var{arch}/@var{xyz}.mh}.
987 @subheading Generic Host Support Files
989 @cindex generic host support
990 There are some ``generic'' versions of routines that can be used by
991 various systems. These can be customized in various ways by macros
992 defined in your @file{xm-@var{xyz}.h} file. If these routines work for
993 the @var{xyz} host, you can just include the generic file's name (with
994 @samp{.o}, not @samp{.c}) in @code{XDEPFILES}.
996 Otherwise, if your machine needs custom support routines, you will need
997 to write routines that perform the same functions as the generic file.
998 Put them into @code{@var{xyz}-xdep.c}, and put @code{@var{xyz}-xdep.o}
999 into @code{XDEPFILES}.
1002 @cindex remote debugging support
1003 @cindex serial line support
1005 This contains serial line support for Unix systems. This is always
1006 included, via the makefile variable @code{SER_HARDWIRE}; override this
1007 variable in the @file{.mh} file to avoid it.
1010 This contains serial line support for 32-bit programs running under DOS,
1011 using the DJGPP (a.k.a.@: GO32) execution environment.
1013 @cindex TCP remote support
1015 This contains generic TCP support using sockets.
1018 @section Host Conditionals
1020 When @value{GDBN} is configured and compiled, various macros are
1021 defined or left undefined, to control compilation based on the
1022 attributes of the host system. These macros and their meanings (or if
1023 the meaning is not documented here, then one of the source files where
1024 they are used is indicated) are:
1027 @item @value{GDBN}INIT_FILENAME
1028 The default name of @value{GDBN}'s initialization file (normally
1031 @item MEM_FNS_DECLARED
1032 Your host config file defines this if it includes declarations of
1033 @code{memcpy} and @code{memset}. Define this to avoid conflicts between
1034 the native include files and the declarations in @file{defs.h}.
1037 This macro is deprecated.
1040 Define this if your system does not have a @code{<sys/file.h>}.
1042 @item SIGWINCH_HANDLER
1043 If your host defines @code{SIGWINCH}, you can define this to be the name
1044 of a function to be called if @code{SIGWINCH} is received.
1046 @item SIGWINCH_HANDLER_BODY
1047 Define this to expand into code that will define the function named by
1048 the expansion of @code{SIGWINCH_HANDLER}.
1050 @item ALIGN_STACK_ON_STARTUP
1051 @cindex stack alignment
1052 Define this if your system is of a sort that will crash in
1053 @code{tgetent} if the stack happens not to be longword-aligned when
1054 @code{main} is called. This is a rare situation, but is known to occur
1055 on several different types of systems.
1057 @item CRLF_SOURCE_FILES
1058 @cindex DOS text files
1059 Define this if host files use @code{\r\n} rather than @code{\n} as a
1060 line terminator. This will cause source file listings to omit @code{\r}
1061 characters when printing and it will allow @code{\r\n} line endings of files
1062 which are ``sourced'' by gdb. It must be possible to open files in binary
1063 mode using @code{O_BINARY} or, for fopen, @code{"rb"}.
1065 @item DEFAULT_PROMPT
1067 The default value of the prompt string (normally @code{"(gdb) "}).
1070 @cindex terminal device
1071 The name of the generic TTY device, defaults to @code{"/dev/tty"}.
1073 @item FCLOSE_PROVIDED
1074 Define this if the system declares @code{fclose} in the headers included
1075 in @code{defs.h}. This isn't needed unless your compiler is unusually
1079 Define this if binary files are opened the same way as text files.
1081 @item GETENV_PROVIDED
1082 Define this if the system declares @code{getenv} in its headers included
1083 in @code{defs.h}. This isn't needed unless your compiler is unusually
1088 In some cases, use the system call @code{mmap} for reading symbol
1089 tables. For some machines this allows for sharing and quick updates.
1091 @item HAVE_SIGSETMASK
1093 Define this if the host system has job control, but does not define
1094 @code{sigsetmask}. Currently, this is only true of the RS/6000.
1097 Define this if the host system has @code{termio.h}.
1099 @item HOST_BYTE_ORDER
1101 The ordering of bytes in the host. This must be defined to be either
1102 @code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}.
1109 Values for host-side constants.
1112 Substitute for isatty, if not available.
1115 This is the longest integer type available on the host. If not defined,
1116 it will default to @code{long long} or @code{long}, depending on
1117 @code{CC_HAS_LONG_LONG}.
1119 @item CC_HAS_LONG_LONG
1120 @cindex @code{long long} data type
1121 Define this if the host C compiler supports @code{long long}. This is set
1122 by the @code{configure} script.
1124 @item PRINTF_HAS_LONG_LONG
1125 Define this if the host can handle printing of long long integers via
1126 the printf format conversion specifier @code{ll}. This is set by the
1127 @code{configure} script.
1129 @item HAVE_LONG_DOUBLE
1130 Define this if the host C compiler supports @code{long double}. This is
1131 set by the @code{configure} script.
1133 @item PRINTF_HAS_LONG_DOUBLE
1134 Define this if the host can handle printing of long double float-point
1135 numbers via the printf format conversion specifier @code{Lg}. This is
1136 set by the @code{configure} script.
1138 @item SCANF_HAS_LONG_DOUBLE
1139 Define this if the host can handle the parsing of long double
1140 float-point numbers via the scanf format conversion specifier
1141 @code{Lg}. This is set by the @code{configure} script.
1143 @item LSEEK_NOT_LINEAR
1144 Define this if @code{lseek (n)} does not necessarily move to byte number
1145 @code{n} in the file. This is only used when reading source files. It
1146 is normally faster to define @code{CRLF_SOURCE_FILES} when possible.
1149 This macro is used as the argument to @code{lseek} (or, most commonly,
1150 @code{bfd_seek}). FIXME, should be replaced by SEEK_SET instead,
1151 which is the POSIX equivalent.
1153 @item MALLOC_INCOMPATIBLE
1154 Define this if the system's prototype for @code{malloc} differs from the
1155 @sc{ansi} definition.
1157 @item MMAP_BASE_ADDRESS
1158 When using HAVE_MMAP, the first mapping should go at this address.
1160 @item MMAP_INCREMENT
1161 when using HAVE_MMAP, this is the increment between mappings.
1163 @item NEED_POSIX_SETPGID
1165 Define this to use the POSIX version of @code{setpgid} to determine
1166 whether job control is available.
1169 If defined, this should be one or more tokens, such as @code{volatile},
1170 that can be used in both the declaration and definition of functions to
1171 indicate that they never return. The default is already set correctly
1172 if compiling with GCC. This will almost never need to be defined.
1175 If defined, this should be one or more tokens, such as
1176 @code{__attribute__ ((noreturn))}, that can be used in the declarations
1177 of functions to indicate that they never return. The default is already
1178 set correctly if compiling with GCC. This will almost never need to be
1181 @item USE_GENERIC_DUMMY_FRAMES
1182 @cindex generic dummy frames
1183 Define this to 1 if the target is using the generic inferior function
1184 call code. See @code{blockframe.c} for more information.
1188 @value{GDBN} will use the @code{mmalloc} library for memory allocation
1189 for symbol reading if this symbol is defined. Be careful defining it
1190 since there are systems on which @code{mmalloc} does not work for some
1191 reason. One example is the DECstation, where its RPC library can't
1192 cope with our redefinition of @code{malloc} to call @code{mmalloc}.
1193 When defining @code{USE_MMALLOC}, you will also have to set
1194 @code{MMALLOC} in the Makefile, to point to the @code{mmalloc} library. This
1195 define is set when you configure with @samp{--with-mmalloc}.
1199 Define this if you are using @code{mmalloc}, but don't want the overhead
1200 of checking the heap with @code{mmcheck}. Note that on some systems,
1201 the C runtime makes calls to @code{malloc} prior to calling @code{main}, and if
1202 @code{free} is ever called with these pointers after calling
1203 @code{mmcheck} to enable checking, a memory corruption abort is certain
1204 to occur. These systems can still use @code{mmalloc}, but must define
1208 Define this to 1 if the C runtime allocates memory prior to
1209 @code{mmcheck} being called, but that memory is never freed so we don't
1210 have to worry about it triggering a memory corruption abort. The
1211 default is 0, which means that @code{mmcheck} will only install the heap
1212 checking functions if there has not yet been any memory allocation
1213 calls, and if it fails to install the functions, @value{GDBN} will issue a
1214 warning. This is currently defined if you configure using
1215 @samp{--with-mmalloc}.
1217 @item NO_SIGINTERRUPT
1218 @findex siginterrupt
1219 Define this to indicate that @code{siginterrupt} is not available.
1222 Define if this is not in a system header file (typically, @file{unistd.h}).
1226 Define these to appropriate value for the system @code{lseek}, if not already
1230 This is the signal for stopping @value{GDBN}. Defaults to
1231 @code{SIGTSTP}. (Only redefined for the Convex.)
1234 Define this if the interior's tty should be opened with the @code{O_NOCTTY}
1235 flag. (FIXME: This should be a native-only flag, but @file{inflow.c} is
1239 Means that System V (prior to SVR4) include files are in use. (FIXME:
1240 This symbol is abused in @file{infrun.c}, @file{regex.c},
1241 @file{remote-nindy.c}, and @file{utils.c} for other things, at the
1245 Define this to help placate @code{lint} in some situations.
1248 Define this to override the defaults of @code{__volatile__} or
1253 @node Target Architecture Definition
1255 @chapter Target Architecture Definition
1257 @cindex target architecture definition
1258 @value{GDBN}'s target architecture defines what sort of
1259 machine-language programs @value{GDBN} can work with, and how it works
1262 At present, the target architecture definition consists of a number of C
1265 @section Registers and Memory
1267 @value{GDBN}'s model of the target machine is rather simple.
1268 @value{GDBN} assumes the machine includes a bank of registers and a
1269 block of memory. Each register may have a different size.
1271 @value{GDBN} does not have a magical way to match up with the
1272 compiler's idea of which registers are which; however, it is critical
1273 that they do match up accurately. The only way to make this work is
1274 to get accurate information about the order that the compiler uses,
1275 and to reflect that in the @code{REGISTER_NAME} and related macros.
1277 @value{GDBN} can handle big-endian, little-endian, and bi-endian architectures.
1279 @section Pointers Are Not Always Addresses
1280 @cindex pointer representation
1281 @cindex address representation
1282 @cindex word-addressed machines
1283 @cindex separate data and code address spaces
1284 @cindex spaces, separate data and code address
1285 @cindex address spaces, separate data and code
1286 @cindex code pointers, word-addressed
1287 @cindex converting between pointers and addresses
1288 @cindex D10V addresses
1290 On almost all 32-bit architectures, the representation of a pointer is
1291 indistinguishable from the representation of some fixed-length number
1292 whose value is the byte address of the object pointed to. On such
1293 machines, the words ``pointer'' and ``address'' can be used interchangeably.
1294 However, architectures with smaller word sizes are often cramped for
1295 address space, so they may choose a pointer representation that breaks this
1296 identity, and allows a larger code address space.
1298 For example, the Mitsubishi D10V is a 16-bit VLIW processor whose
1299 instructions are 32 bits long@footnote{Some D10V instructions are
1300 actually pairs of 16-bit sub-instructions. However, since you can't
1301 jump into the middle of such a pair, code addresses can only refer to
1302 full 32 bit instructions, which is what matters in this explanation.}.
1303 If the D10V used ordinary byte addresses to refer to code locations,
1304 then the processor would only be able to address 64kb of instructions.
1305 However, since instructions must be aligned on four-byte boundaries, the
1306 low two bits of any valid instruction's byte address are always
1307 zero---byte addresses waste two bits. So instead of byte addresses,
1308 the D10V uses word addresses---byte addresses shifted right two bits---to
1309 refer to code. Thus, the D10V can use 16-bit words to address 256kb of
1312 However, this means that code pointers and data pointers have different
1313 forms on the D10V. The 16-bit word @code{0xC020} refers to byte address
1314 @code{0xC020} when used as a data address, but refers to byte address
1315 @code{0x30080} when used as a code address.
1317 (The D10V also uses separate code and data address spaces, which also
1318 affects the correspondence between pointers and addresses, but we're
1319 going to ignore that here; this example is already too long.)
1321 To cope with architectures like this---the D10V is not the only
1322 one!---@value{GDBN} tries to distinguish between @dfn{addresses}, which are
1323 byte numbers, and @dfn{pointers}, which are the target's representation
1324 of an address of a particular type of data. In the example above,
1325 @code{0xC020} is the pointer, which refers to one of the addresses
1326 @code{0xC020} or @code{0x30080}, depending on the type imposed upon it.
1327 @value{GDBN} provides functions for turning a pointer into an address
1328 and vice versa, in the appropriate way for the current architecture.
1330 Unfortunately, since addresses and pointers are identical on almost all
1331 processors, this distinction tends to bit-rot pretty quickly. Thus,
1332 each time you port @value{GDBN} to an architecture which does
1333 distinguish between pointers and addresses, you'll probably need to
1334 clean up some architecture-independent code.
1336 Here are functions which convert between pointers and addresses:
1338 @deftypefun CORE_ADDR extract_typed_address (void *@var{buf}, struct type *@var{type})
1339 Treat the bytes at @var{buf} as a pointer or reference of type
1340 @var{type}, and return the address it represents, in a manner
1341 appropriate for the current architecture. This yields an address
1342 @value{GDBN} can use to read target memory, disassemble, etc. Note that
1343 @var{buf} refers to a buffer in @value{GDBN}'s memory, not the
1346 For example, if the current architecture is the Intel x86, this function
1347 extracts a little-endian integer of the appropriate length from
1348 @var{buf} and returns it. However, if the current architecture is the
1349 D10V, this function will return a 16-bit integer extracted from
1350 @var{buf}, multiplied by four if @var{type} is a pointer to a function.
1352 If @var{type} is not a pointer or reference type, then this function
1353 will signal an internal error.
1356 @deftypefun CORE_ADDR store_typed_address (void *@var{buf}, struct type *@var{type}, CORE_ADDR @var{addr})
1357 Store the address @var{addr} in @var{buf}, in the proper format for a
1358 pointer of type @var{type} in the current architecture. Note that
1359 @var{buf} refers to a buffer in @value{GDBN}'s memory, not the
1362 For example, if the current architecture is the Intel x86, this function
1363 stores @var{addr} unmodified as a little-endian integer of the
1364 appropriate length in @var{buf}. However, if the current architecture
1365 is the D10V, this function divides @var{addr} by four if @var{type} is
1366 a pointer to a function, and then stores it in @var{buf}.
1368 If @var{type} is not a pointer or reference type, then this function
1369 will signal an internal error.
1372 @deftypefun CORE_ADDR value_as_pointer (value_ptr @var{val})
1373 Assuming that @var{val} is a pointer, return the address it represents,
1374 as appropriate for the current architecture.
1376 This function actually works on integral values, as well as pointers.
1377 For pointers, it performs architecture-specific conversions as
1378 described above for @code{extract_typed_address}.
1381 @deftypefun CORE_ADDR value_from_pointer (struct type *@var{type}, CORE_ADDR @var{addr})
1382 Create and return a value representing a pointer of type @var{type} to
1383 the address @var{addr}, as appropriate for the current architecture.
1384 This function performs architecture-specific conversions as described
1385 above for @code{store_typed_address}.
1389 @value{GDBN} also provides functions that do the same tasks, but assume
1390 that pointers are simply byte addresses; they aren't sensitive to the
1391 current architecture, beyond knowing the appropriate endianness.
1393 @deftypefun CORE_ADDR extract_address (void *@var{addr}, int len)
1394 Extract a @var{len}-byte number from @var{addr} in the appropriate
1395 endianness for the current architecture, and return it. Note that
1396 @var{addr} refers to @value{GDBN}'s memory, not the inferior's.
1398 This function should only be used in architecture-specific code; it
1399 doesn't have enough information to turn bits into a true address in the
1400 appropriate way for the current architecture. If you can, use
1401 @code{extract_typed_address} instead.
1404 @deftypefun void store_address (void *@var{addr}, int @var{len}, LONGEST @var{val})
1405 Store @var{val} at @var{addr} as a @var{len}-byte integer, in the
1406 appropriate endianness for the current architecture. Note that
1407 @var{addr} refers to a buffer in @value{GDBN}'s memory, not the
1410 This function should only be used in architecture-specific code; it
1411 doesn't have enough information to turn a true address into bits in the
1412 appropriate way for the current architecture. If you can, use
1413 @code{store_typed_address} instead.
1417 Here are some macros which architectures can define to indicate the
1418 relationship between pointers and addresses. These have default
1419 definitions, appropriate for architectures on which all pointers are
1420 simple byte addresses.
1422 @deftypefn {Target Macro} CORE_ADDR POINTER_TO_ADDRESS (struct type *@var{type}, char *@var{buf})
1423 Assume that @var{buf} holds a pointer of type @var{type}, in the
1424 appropriate format for the current architecture. Return the byte
1425 address the pointer refers to.
1427 This function may safely assume that @var{type} is either a pointer or a
1428 C@t{++} reference type.
1431 @deftypefn {Target Macro} void ADDRESS_TO_POINTER (struct type *@var{type}, char *@var{buf}, CORE_ADDR @var{addr})
1432 Store in @var{buf} a pointer of type @var{type} representing the address
1433 @var{addr}, in the appropriate format for the current architecture.
1435 This function may safely assume that @var{type} is either a pointer or a
1436 C@t{++} reference type.
1440 @section Using Different Register and Memory Data Representations
1441 @cindex raw representation
1442 @cindex virtual representation
1443 @cindex representations, raw and virtual
1444 @cindex register data formats, converting
1445 @cindex @code{struct value}, converting register contents to
1447 Some architectures use one representation for a value when it lives in a
1448 register, but use a different representation when it lives in memory.
1449 In @value{GDBN}'s terminology, the @dfn{raw} representation is the one used in
1450 the target registers, and the @dfn{virtual} representation is the one
1451 used in memory, and within @value{GDBN} @code{struct value} objects.
1453 For almost all data types on almost all architectures, the virtual and
1454 raw representations are identical, and no special handling is needed.
1455 However, they do occasionally differ. For example:
1459 The x86 architecture supports an 80-bit @code{long double} type. However, when
1460 we store those values in memory, they occupy twelve bytes: the
1461 floating-point number occupies the first ten, and the final two bytes
1462 are unused. This keeps the values aligned on four-byte boundaries,
1463 allowing more efficient access. Thus, the x86 80-bit floating-point
1464 type is the raw representation, and the twelve-byte loosely-packed
1465 arrangement is the virtual representation.
1468 Some 64-bit MIPS targets present 32-bit registers to @value{GDBN} as 64-bit
1469 registers, with garbage in their upper bits. @value{GDBN} ignores the top 32
1470 bits. Thus, the 64-bit form, with garbage in the upper 32 bits, is the
1471 raw representation, and the trimmed 32-bit representation is the
1472 virtual representation.
1475 In general, the raw representation is determined by the architecture, or
1476 @value{GDBN}'s interface to the architecture, while the virtual representation
1477 can be chosen for @value{GDBN}'s convenience. @value{GDBN}'s register file,
1478 @code{registers}, holds the register contents in raw format, and the
1479 @value{GDBN} remote protocol transmits register values in raw format.
1481 Your architecture may define the following macros to request
1482 conversions between the raw and virtual format:
1484 @deftypefn {Target Macro} int REGISTER_CONVERTIBLE (int @var{reg})
1485 Return non-zero if register number @var{reg}'s value needs different raw
1486 and virtual formats.
1488 You should not use @code{REGISTER_CONVERT_TO_VIRTUAL} for a register
1489 unless this macro returns a non-zero value for that register.
1492 @deftypefn {Target Macro} int REGISTER_RAW_SIZE (int @var{reg})
1493 The size of register number @var{reg}'s raw value. This is the number
1494 of bytes the register will occupy in @code{registers}, or in a @value{GDBN}
1495 remote protocol packet.
1498 @deftypefn {Target Macro} int REGISTER_VIRTUAL_SIZE (int @var{reg})
1499 The size of register number @var{reg}'s value, in its virtual format.
1500 This is the size a @code{struct value}'s buffer will have, holding that
1504 @deftypefn {Target Macro} struct type *REGISTER_VIRTUAL_TYPE (int @var{reg})
1505 This is the type of the virtual representation of register number
1506 @var{reg}. Note that there is no need for a macro giving a type for the
1507 register's raw form; once the register's value has been obtained, @value{GDBN}
1508 always uses the virtual form.
1511 @deftypefn {Target Macro} void REGISTER_CONVERT_TO_VIRTUAL (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to})
1512 Convert the value of register number @var{reg} to @var{type}, which
1513 should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
1514 at @var{from} holds the register's value in raw format; the macro should
1515 convert the value to virtual format, and place it at @var{to}.
1517 Note that @code{REGISTER_CONVERT_TO_VIRTUAL} and
1518 @code{REGISTER_CONVERT_TO_RAW} take their @var{reg} and @var{type}
1519 arguments in different orders.
1521 You should only use @code{REGISTER_CONVERT_TO_VIRTUAL} with registers
1522 for which the @code{REGISTER_CONVERTIBLE} macro returns a non-zero
1526 @deftypefn {Target Macro} void REGISTER_CONVERT_TO_RAW (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to})
1527 Convert the value of register number @var{reg} to @var{type}, which
1528 should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
1529 at @var{from} holds the register's value in raw format; the macro should
1530 convert the value to virtual format, and place it at @var{to}.
1532 Note that REGISTER_CONVERT_TO_VIRTUAL and REGISTER_CONVERT_TO_RAW take
1533 their @var{reg} and @var{type} arguments in different orders.
1537 @section Frame Interpretation
1539 @section Inferior Call Setup
1541 @section Compiler Characteristics
1543 @section Target Conditionals
1545 This section describes the macros that you can use to define the target
1550 @item ADDITIONAL_OPTIONS
1551 @itemx ADDITIONAL_OPTION_CASES
1552 @itemx ADDITIONAL_OPTION_HANDLER
1553 @itemx ADDITIONAL_OPTION_HELP
1554 @findex ADDITIONAL_OPTION_HELP
1555 @findex ADDITIONAL_OPTION_HANDLER
1556 @findex ADDITIONAL_OPTION_CASES
1557 @findex ADDITIONAL_OPTIONS
1558 These are a set of macros that allow the addition of additional command
1559 line options to @value{GDBN}. They are currently used only for the unsupported
1560 i960 Nindy target, and should not be used in any other configuration.
1562 @item ADDR_BITS_REMOVE (addr)
1563 @findex ADDR_BITS_REMOVE
1564 If a raw machine instruction address includes any bits that are not
1565 really part of the address, then define this macro to expand into an
1566 expression that zeroes those bits in @var{addr}. This is only used for
1567 addresses of instructions, and even then not in all contexts.
1569 For example, the two low-order bits of the PC on the Hewlett-Packard PA
1570 2.0 architecture contain the privilege level of the corresponding
1571 instruction. Since instructions must always be aligned on four-byte
1572 boundaries, the processor masks out these bits to generate the actual
1573 address of the instruction. ADDR_BITS_REMOVE should filter out these
1574 bits with an expression such as @code{((addr) & ~3)}.
1576 @item ADDRESS_TO_POINTER (@var{type}, @var{buf}, @var{addr})
1577 @findex ADDRESS_TO_POINTER
1578 Store in @var{buf} a pointer of type @var{type} representing the address
1579 @var{addr}, in the appropriate format for the current architecture.
1580 This macro may safely assume that @var{type} is either a pointer or a
1581 C@t{++} reference type.
1582 @xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
1584 @item BEFORE_MAIN_LOOP_HOOK
1585 @findex BEFORE_MAIN_LOOP_HOOK
1586 Define this to expand into any code that you want to execute before the
1587 main loop starts. Although this is not, strictly speaking, a target
1588 conditional, that is how it is currently being used. Note that if a
1589 configuration were to define it one way for a host and a different way
1590 for the target, @value{GDBN} will probably not compile, let alone run
1591 correctly. This macro is currently used only for the unsupported i960 Nindy
1592 target, and should not be used in any other configuration.
1594 @item BELIEVE_PCC_PROMOTION
1595 @findex BELIEVE_PCC_PROMOTION
1596 Define if the compiler promotes a @code{short} or @code{char}
1597 parameter to an @code{int}, but still reports the parameter as its
1598 original type, rather than the promoted type.
1600 @item BELIEVE_PCC_PROMOTION_TYPE
1601 @findex BELIEVE_PCC_PROMOTION_TYPE
1602 Define this if @value{GDBN} should believe the type of a @code{short}
1603 argument when compiled by @code{pcc}, but look within a full int space to get
1604 its value. Only defined for Sun-3 at present.
1606 @item BITS_BIG_ENDIAN
1607 @findex BITS_BIG_ENDIAN
1608 Define this if the numbering of bits in the targets does @strong{not} match the
1609 endianness of the target byte order. A value of 1 means that the bits
1610 are numbered in a big-endian bit order, 0 means little-endian.
1614 This is the character array initializer for the bit pattern to put into
1615 memory where a breakpoint is set. Although it's common to use a trap
1616 instruction for a breakpoint, it's not required; for instance, the bit
1617 pattern could be an invalid instruction. The breakpoint must be no
1618 longer than the shortest instruction of the architecture.
1620 @code{BREAKPOINT} has been deprecated in favor of
1621 @code{BREAKPOINT_FROM_PC}.
1623 @item BIG_BREAKPOINT
1624 @itemx LITTLE_BREAKPOINT
1625 @findex LITTLE_BREAKPOINT
1626 @findex BIG_BREAKPOINT
1627 Similar to BREAKPOINT, but used for bi-endian targets.
1629 @code{BIG_BREAKPOINT} and @code{LITTLE_BREAKPOINT} have been deprecated in
1630 favor of @code{BREAKPOINT_FROM_PC}.
1632 @item REMOTE_BREAKPOINT
1633 @itemx LITTLE_REMOTE_BREAKPOINT
1634 @itemx BIG_REMOTE_BREAKPOINT
1635 @findex BIG_REMOTE_BREAKPOINT
1636 @findex LITTLE_REMOTE_BREAKPOINT
1637 @findex REMOTE_BREAKPOINT
1638 Similar to BREAKPOINT, but used for remote targets.
1640 @code{BIG_REMOTE_BREAKPOINT} and @code{LITTLE_REMOTE_BREAKPOINT} have been
1641 deprecated in favor of @code{BREAKPOINT_FROM_PC}.
1643 @item BREAKPOINT_FROM_PC (@var{pcptr}, @var{lenptr})
1644 @findex BREAKPOINT_FROM_PC
1645 Use the program counter to determine the contents and size of a
1646 breakpoint instruction. It returns a pointer to a string of bytes
1647 that encode a breakpoint instruction, stores the length of the string
1648 to *@var{lenptr}, and adjusts pc (if necessary) to point to the actual
1649 memory location where the breakpoint should be inserted.
1651 Although it is common to use a trap instruction for a breakpoint, it's
1652 not required; for instance, the bit pattern could be an invalid
1653 instruction. The breakpoint must be no longer than the shortest
1654 instruction of the architecture.
1656 Replaces all the other @var{BREAKPOINT} macros.
1658 @item MEMORY_INSERT_BREAKPOINT (@var{addr}, @var{contents_cache})
1659 @itemx MEMORY_REMOVE_BREAKPOINT (@var{addr}, @var{contents_cache})
1660 @findex MEMORY_REMOVE_BREAKPOINT
1661 @findex MEMORY_INSERT_BREAKPOINT
1662 Insert or remove memory based breakpoints. Reasonable defaults
1663 (@code{default_memory_insert_breakpoint} and
1664 @code{default_memory_remove_breakpoint} respectively) have been
1665 provided so that it is not necessary to define these for most
1666 architectures. Architectures which may want to define
1667 @code{MEMORY_INSERT_BREAKPOINT} and @code{MEMORY_REMOVE_BREAKPOINT} will
1668 likely have instructions that are oddly sized or are not stored in a
1669 conventional manner.
1671 It may also be desirable (from an efficiency standpoint) to define
1672 custom breakpoint insertion and removal routines if
1673 @code{BREAKPOINT_FROM_PC} needs to read the target's memory for some
1677 @findex CALL_DUMMY_P
1678 A C expresson that is non-zero when the target suports inferior function
1681 @item CALL_DUMMY_WORDS
1682 @findex CALL_DUMMY_WORDS
1683 Pointer to an array of @code{LONGEST} words of data containing
1684 host-byte-ordered @code{REGISTER_BYTES} sized values that partially
1685 specify the sequence of instructions needed for an inferior function
1688 Should be deprecated in favor of a macro that uses target-byte-ordered
1691 @item SIZEOF_CALL_DUMMY_WORDS
1692 @findex SIZEOF_CALL_DUMMY_WORDS
1693 The size of @code{CALL_DUMMY_WORDS}. When @code{CALL_DUMMY_P} this must
1694 return a positive value. See also @code{CALL_DUMMY_LENGTH}.
1698 A static initializer for @code{CALL_DUMMY_WORDS}. Deprecated.
1700 @item CALL_DUMMY_LOCATION
1701 @findex CALL_DUMMY_LOCATION
1702 See the file @file{inferior.h}.
1704 @item CALL_DUMMY_STACK_ADJUST
1705 @findex CALL_DUMMY_STACK_ADJUST
1706 Stack adjustment needed when performing an inferior function call.
1708 Should be deprecated in favor of something like @code{STACK_ALIGN}.
1710 @item CALL_DUMMY_STACK_ADJUST_P
1711 @findex CALL_DUMMY_STACK_ADJUST_P
1712 Predicate for use of @code{CALL_DUMMY_STACK_ADJUST}.
1714 Should be deprecated in favor of something like @code{STACK_ALIGN}.
1716 @item CANNOT_FETCH_REGISTER (@var{regno})
1717 @findex CANNOT_FETCH_REGISTER
1718 A C expression that should be nonzero if @var{regno} cannot be fetched
1719 from an inferior process. This is only relevant if
1720 @code{FETCH_INFERIOR_REGISTERS} is not defined.
1722 @item CANNOT_STORE_REGISTER (@var{regno})
1723 @findex CANNOT_STORE_REGISTER
1724 A C expression that should be nonzero if @var{regno} should not be
1725 written to the target. This is often the case for program counters,
1726 status words, and other special registers. If this is not defined,
1727 @value{GDBN} will assume that all registers may be written.
1729 @item DO_DEFERRED_STORES
1730 @itemx CLEAR_DEFERRED_STORES@item
1731 @findex CLEAR_DEFERRED_STORES
1732 @findex DO_DEFERRED_STORES
1733 Define this to execute any deferred stores of registers into the inferior,
1734 and to cancel any deferred stores.
1736 Currently only implemented correctly for native Sparc configurations?
1738 @item COERCE_FLOAT_TO_DOUBLE (@var{formal}, @var{actual})
1739 @findex COERCE_FLOAT_TO_DOUBLE
1740 @cindex promotion to @code{double}
1741 If we are calling a function by hand, and the function was declared
1742 (according to the debug info) without a prototype, should we
1743 automatically promote @code{float}s to @code{double}s? This macro
1744 must evaluate to non-zero if we should, or zero if we should leave the
1747 The argument @var{actual} is the type of the value we want to pass to
1748 the function. The argument @var{formal} is the type of this argument,
1749 as it appears in the function's definition. Note that @var{formal} may
1750 be zero if we have no debugging information for the function, or if
1751 we're passing more arguments than are officially declared (for example,
1752 varargs). This macro is never invoked if the function definitely has a
1755 @findex set_gdbarch_coerce_float_to_double
1756 @findex standard_coerce_float_to_double
1757 The default behavior is to promote only when we have no type information
1758 for the formal parameter. This is different from the obvious behavior,
1759 which would be to promote whenever we have no prototype, just as the
1760 compiler does. It's annoying, but some older targets rely on this. If
1761 you want @value{GDBN} to follow the typical compiler behavior---to always
1762 promote when there is no prototype in scope---your gdbarch @code{init}
1763 function can call @code{set_gdbarch_coerce_float_to_double} and select
1764 the @code{standard_coerce_float_to_double} function.
1767 @findex CPLUS_MARKERz
1768 Define this to expand into the character that G@t{++} uses to distinguish
1769 compiler-generated identifiers from programmer-specified identifiers.
1770 By default, this expands into @code{'$'}. Most System V targets should
1771 define this to @code{'.'}.
1773 @item DBX_PARM_SYMBOL_CLASS
1774 @findex DBX_PARM_SYMBOL_CLASS
1775 Hook for the @code{SYMBOL_CLASS} of a parameter when decoding DBX symbol
1776 information. In the i960, parameters can be stored as locals or as
1777 args, depending on the type of the debug record.
1779 @item DECR_PC_AFTER_BREAK
1780 @findex DECR_PC_AFTER_BREAK
1781 Define this to be the amount by which to decrement the PC after the
1782 program encounters a breakpoint. This is often the number of bytes in
1783 @code{BREAKPOINT}, though not always. For most targets this value will be 0.
1785 @item DECR_PC_AFTER_HW_BREAK
1786 @findex DECR_PC_AFTER_HW_BREAK
1787 Similarly, for hardware breakpoints.
1789 @item DISABLE_UNSETTABLE_BREAK (@var{addr})
1790 @findex DISABLE_UNSETTABLE_BREAK
1791 If defined, this should evaluate to 1 if @var{addr} is in a shared
1792 library in which breakpoints cannot be set and so should be disabled.
1794 @item DO_REGISTERS_INFO
1795 @findex DO_REGISTERS_INFO
1796 If defined, use this to print the value of a register or all registers.
1798 @item DWARF_REG_TO_REGNUM
1799 @findex DWARF_REG_TO_REGNUM
1800 Convert DWARF register number into @value{GDBN} regnum. If not defined,
1801 no conversion will be performed.
1803 @item DWARF2_REG_TO_REGNUM
1804 @findex DWARF2_REG_TO_REGNUM
1805 Convert DWARF2 register number into @value{GDBN} regnum. If not
1806 defined, no conversion will be performed.
1808 @item ECOFF_REG_TO_REGNUM
1809 @findex ECOFF_REG_TO_REGNUM
1810 Convert ECOFF register number into @value{GDBN} regnum. If not defined,
1811 no conversion will be performed.
1813 @item END_OF_TEXT_DEFAULT
1814 @findex END_OF_TEXT_DEFAULT
1815 This is an expression that should designate the end of the text section.
1818 @item EXTRACT_RETURN_VALUE(@var{type}, @var{regbuf}, @var{valbuf})
1819 @findex EXTRACT_RETURN_VALUE
1820 Define this to extract a function's return value of type @var{type} from
1821 the raw register state @var{regbuf} and copy that, in virtual format,
1824 @item EXTRACT_STRUCT_VALUE_ADDRESS(@var{regbuf})
1825 @findex EXTRACT_STRUCT_VALUE_ADDRESS
1826 When @code{EXTRACT_STRUCT_VALUE_ADDRESS_P} is non-zero, this is used to extract
1827 from an array @var{regbuf} (containing the raw register state) the
1828 address in which a function should return its structure value, as a
1829 @code{CORE_ADDR} (or an expression that can be used as one).
1831 @item EXTRACT_STRUCT_VALUE_ADDRESS_P
1832 @findex EXTRACT_STRUCT_VALUE_ADDRESS_P
1833 Predicate for @code{EXTRACT_STRUCT_VALUE_ADDRESS}.
1837 If defined, then the @samp{info float} command will print information about
1838 the processor's floating point unit.
1842 If the virtual frame pointer is kept in a register, then define this
1843 macro to be the number (greater than or equal to zero) of that register.
1845 This should only need to be defined if @code{TARGET_READ_FP} and
1846 @code{TARGET_WRITE_FP} are not defined.
1848 @item FRAMELESS_FUNCTION_INVOCATION(@var{fi})
1849 @findex FRAMELESS_FUNCTION_INVOCATION
1850 Define this to an expression that returns 1 if the function invocation
1851 represented by @var{fi} does not have a stack frame associated with it.
1854 @item FRAME_ARGS_ADDRESS_CORRECT@item
1855 @findex FRAME_ARGS_ADDRESS_CORRECT
1858 @item FRAME_CHAIN(@var{frame})
1860 Given @var{frame}, return a pointer to the calling frame.
1862 @item FRAME_CHAIN_COMBINE(@var{chain}, @var{frame})
1863 @findex FRAME_CHAIN_COMBINE
1864 Define this to take the frame chain pointer and the frame's nominal
1865 address and produce the nominal address of the caller's frame.
1866 Presently only defined for HP PA.
1868 @item FRAME_CHAIN_VALID(@var{chain}, @var{thisframe})
1869 @findex FRAME_CHAIN_VALID
1870 Define this to be an expression that returns zero if the given frame is
1871 an outermost frame, with no caller, and nonzero otherwise. Several
1872 common definitions are available:
1876 @code{file_frame_chain_valid} is nonzero if the chain pointer is nonzero
1877 and given frame's PC is not inside the startup file (such as
1881 @code{func_frame_chain_valid} is nonzero if the chain
1882 pointer is nonzero and the given frame's PC is not in @code{main} or a
1883 known entry point function (such as @code{_start}).
1886 @code{generic_file_frame_chain_valid} and
1887 @code{generic_func_frame_chain_valid} are equivalent implementations for
1888 targets using generic dummy frames.
1891 @item FRAME_INIT_SAVED_REGS(@var{frame})
1892 @findex FRAME_INIT_SAVED_REGS
1893 See @file{frame.h}. Determines the address of all registers in the
1894 current stack frame storing each in @code{frame->saved_regs}. Space for
1895 @code{frame->saved_regs} shall be allocated by
1896 @code{FRAME_INIT_SAVED_REGS} using either
1897 @code{frame_saved_regs_zalloc} or @code{frame_obstack_alloc}.
1899 @code{FRAME_FIND_SAVED_REGS} and @code{EXTRA_FRAME_INFO} are deprecated.
1901 @item FRAME_NUM_ARGS (@var{fi})
1902 @findex FRAME_NUM_ARGS
1903 For the frame described by @var{fi} return the number of arguments that
1904 are being passed. If the number of arguments is not known, return
1907 @item FRAME_SAVED_PC(@var{frame})
1908 @findex FRAME_SAVED_PC
1909 Given @var{frame}, return the pc saved there. This is the return
1912 @item FUNCTION_EPILOGUE_SIZE
1913 @findex FUNCTION_EPILOGUE_SIZE
1914 For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the
1915 function end symbol is 0. For such targets, you must define
1916 @code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a
1917 function's epilogue.
1919 @item FUNCTION_START_OFFSET
1920 @findex FUNCTION_START_OFFSET
1921 An integer, giving the offset in bytes from a function's address (as
1922 used in the values of symbols, function pointers, etc.), and the
1923 function's first genuine instruction.
1925 This is zero on almost all machines: the function's address is usually
1926 the address of its first instruction. However, on the VAX, for example,
1927 each function starts with two bytes containing a bitmask indicating
1928 which registers to save upon entry to the function. The VAX @code{call}
1929 instructions check this value, and save the appropriate registers
1930 automatically. Thus, since the offset from the function's address to
1931 its first instruction is two bytes, @code{FUNCTION_START_OFFSET} would
1934 @item GCC_COMPILED_FLAG_SYMBOL
1935 @itemx GCC2_COMPILED_FLAG_SYMBOL
1936 @findex GCC2_COMPILED_FLAG_SYMBOL
1937 @findex GCC_COMPILED_FLAG_SYMBOL
1938 If defined, these are the names of the symbols that @value{GDBN} will
1939 look for to detect that GCC compiled the file. The default symbols
1940 are @code{gcc_compiled.} and @code{gcc2_compiled.},
1941 respectively. (Currently only defined for the Delta 68.)
1943 @item @value{GDBN}_MULTI_ARCH
1944 @findex @value{GDBN}_MULTI_ARCH
1945 If defined and non-zero, enables suport for multiple architectures
1946 within @value{GDBN}.
1948 This support can be enabled at two levels. At level one, only
1949 definitions for previously undefined macros are provided; at level two,
1950 a multi-arch definition of all architecture dependant macros will be
1953 @item @value{GDBN}_TARGET_IS_HPPA
1954 @findex @value{GDBN}_TARGET_IS_HPPA
1955 This determines whether horrible kludge code in @file{dbxread.c} and
1956 @file{partial-stab.h} is used to mangle multiple-symbol-table files from
1957 HPPA's. This should all be ripped out, and a scheme like @file{elfread.c}
1960 @item GET_LONGJMP_TARGET
1961 @findex GET_LONGJMP_TARGET
1962 For most machines, this is a target-dependent parameter. On the
1963 DECstation and the Iris, this is a native-dependent parameter, since
1964 trhe header file @file{setjmp.h} is needed to define it.
1966 This macro determines the target PC address that @code{longjmp} will jump to,
1967 assuming that we have just stopped at a @code{longjmp} breakpoint. It takes a
1968 @code{CORE_ADDR *} as argument, and stores the target PC value through this
1969 pointer. It examines the current state of the machine as needed.
1971 @item GET_SAVED_REGISTER
1972 @findex GET_SAVED_REGISTER
1973 @findex get_saved_register
1974 Define this if you need to supply your own definition for the function
1975 @code{get_saved_register}.
1977 @item HAVE_REGISTER_WINDOWS
1978 @findex HAVE_REGISTER_WINDOWS
1979 Define this if the target has register windows.
1981 @item REGISTER_IN_WINDOW_P (@var{regnum})
1982 @findex REGISTER_IN_WINDOW_P
1983 Define this to be an expression that is 1 if the given register is in
1986 @item IBM6000_TARGET
1987 @findex IBM6000_TARGET
1988 Shows that we are configured for an IBM RS/6000 target. This
1989 conditional should be eliminated (FIXME) and replaced by
1990 feature-specific macros. It was introduced in a haste and we are
1991 repenting at leisure.
1993 @item SYMBOLS_CAN_START_WITH_DOLLAR
1994 @findex SYMBOLS_CAN_START_WITH_DOLLAR
1995 Some systems have routines whose names start with @samp{$}. Giving this
1996 macro a non-zero value tells @value{GDBN}'s expression parser to check for such
1997 routines when parsing tokens that begin with @samp{$}.
1999 On HP-UX, certain system routines (millicode) have names beginning with
2000 @samp{$} or @samp{$$}. For example, @code{$$dyncall} is a millicode
2001 routine that handles inter-space procedure calls on PA-RISC.
2005 Define this if the target system uses IEEE-format floating point numbers.
2007 @item INIT_EXTRA_FRAME_INFO (@var{fromleaf}, @var{frame})
2008 @findex INIT_EXTRA_FRAME_INFO
2009 If additional information about the frame is required this should be
2010 stored in @code{frame->extra_info}. Space for @code{frame->extra_info}
2011 is allocated using @code{frame_obstack_alloc}.
2013 @item INIT_FRAME_PC (@var{fromleaf}, @var{prev})
2014 @findex INIT_FRAME_PC
2015 This is a C statement that sets the pc of the frame pointed to by
2016 @var{prev}. [By default...]
2018 @item INNER_THAN (@var{lhs}, @var{rhs})
2020 Returns non-zero if stack address @var{lhs} is inner than (nearer to the
2021 stack top) stack address @var{rhs}. Define this as @code{lhs < rhs} if
2022 the target's stack grows downward in memory, or @code{lhs > rsh} if the
2025 @item IN_SIGTRAMP (@var{pc}, @var{name})
2027 Define this to return non-zero if the given @var{pc} and/or @var{name}
2028 indicates that the current function is a @code{sigtramp}.
2030 @item SIGTRAMP_START (@var{pc})
2031 @findex SIGTRAMP_START
2032 @itemx SIGTRAMP_END (@var{pc})
2033 @findex SIGTRAMP_END
2034 Define these to be the start and end address of the @code{sigtramp} for the
2035 given @var{pc}. On machines where the address is just a compile time
2036 constant, the macro expansion will typically just ignore the supplied
2039 @item IN_SOLIB_CALL_TRAMPOLINE (@var{pc}, @var{name})
2040 @findex IN_SOLIB_CALL_TRAMPOLINE
2041 Define this to evaluate to nonzero if the program is stopped in the
2042 trampoline that connects to a shared library.
2044 @item IN_SOLIB_RETURN_TRAMPOLINE (@var{pc}, @var{name})
2045 @findex IN_SOLIB_RETURN_TRAMPOLINE
2046 Define this to evaluate to nonzero if the program is stopped in the
2047 trampoline that returns from a shared library.
2049 @item IN_SOLIB_DYNSYM_RESOLVE_CODE (@var{pc})
2050 @findex IN_SOLIB_DYNSYM_RESOLVE_CODE
2051 Define this to evaluate to nonzero if the program is stopped in the
2054 @item SKIP_SOLIB_RESOLVER (@var{pc})
2055 @findex SKIP_SOLIB_RESOLVER
2056 Define this to evaluate to the (nonzero) address at which execution
2057 should continue to get past the dynamic linker's symbol resolution
2058 function. A zero value indicates that it is not important or necessary
2059 to set a breakpoint to get through the dynamic linker and that single
2060 stepping will suffice.
2062 @item IS_TRAPPED_INTERNALVAR (@var{name})
2063 @findex IS_TRAPPED_INTERNALVAR
2064 This is an ugly hook to allow the specification of special actions that
2065 should occur as a side-effect of setting the value of a variable
2066 internal to @value{GDBN}. Currently only used by the h8500. Note that this
2067 could be either a host or target conditional.
2069 @item NEED_TEXT_START_END
2070 @findex NEED_TEXT_START_END
2071 Define this if @value{GDBN} should determine the start and end addresses of the
2072 text section. (Seems dubious.)
2074 @item NO_HIF_SUPPORT
2075 @findex NO_HIF_SUPPORT
2076 (Specific to the a29k.)
2078 @item POINTER_TO_ADDRESS (@var{type}, @var{buf})
2079 @findex POINTER_TO_ADDRESS
2080 Assume that @var{buf} holds a pointer of type @var{type}, in the
2081 appropriate format for the current architecture. Return the byte
2082 address the pointer refers to.
2083 @xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
2085 @item REGISTER_CONVERTIBLE (@var{reg})
2086 @findex REGISTER_CONVERTIBLE
2087 Return non-zero if @var{reg} uses different raw and virtual formats.
2088 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
2090 @item REGISTER_RAW_SIZE (@var{reg})
2091 @findex REGISTER_RAW_SIZE
2092 Return the raw size of @var{reg}.
2093 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
2095 @item REGISTER_VIRTUAL_SIZE (@var{reg})
2096 @findex REGISTER_VIRTUAL_SIZE
2097 Return the virtual size of @var{reg}.
2098 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
2100 @item REGISTER_VIRTUAL_TYPE (@var{reg})
2101 @findex REGISTER_VIRTUAL_TYPE
2102 Return the virtual type of @var{reg}.
2103 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
2105 @item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to})
2106 @findex REGISTER_CONVERT_TO_VIRTUAL
2107 Convert the value of register @var{reg} from its raw form to its virtual
2109 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
2111 @item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to})
2112 @findex REGISTER_CONVERT_TO_RAW
2113 Convert the value of register @var{reg} from its virtual form to its raw
2115 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
2117 @item RETURN_VALUE_ON_STACK(@var{type})
2118 @findex RETURN_VALUE_ON_STACK
2119 @cindex returning structures by value
2120 @cindex structures, returning by value
2122 Return non-zero if values of type TYPE are returned on the stack, using
2123 the ``struct convention'' (i.e., the caller provides a pointer to a
2124 buffer in which the callee should store the return value). This
2125 controls how the @samp{finish} command finds a function's return value,
2126 and whether an inferior function call reserves space on the stack for
2129 The full logic @value{GDBN} uses here is kind of odd.
2133 If the type being returned by value is not a structure, union, or array,
2134 and @code{RETURN_VALUE_ON_STACK} returns zero, then @value{GDBN}
2135 concludes the value is not returned using the struct convention.
2138 Otherwise, @value{GDBN} calls @code{USE_STRUCT_CONVENTION} (see below).
2139 If that returns non-zero, @value{GDBN} assumes the struct convention is
2143 In other words, to indicate that a given type is returned by value using
2144 the struct convention, that type must be either a struct, union, array,
2145 or something @code{RETURN_VALUE_ON_STACK} likes, @emph{and} something
2146 that @code{USE_STRUCT_CONVENTION} likes.
2148 Note that, in C and C@t{++}, arrays are never returned by value. In those
2149 languages, these predicates will always see a pointer type, never an
2150 array type. All the references above to arrays being returned by value
2151 apply only to other languages.
2153 @item SOFTWARE_SINGLE_STEP_P
2154 @findex SOFTWARE_SINGLE_STEP_P
2155 Define this as 1 if the target does not have a hardware single-step
2156 mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined.
2158 @item SOFTWARE_SINGLE_STEP(@var{signal}, @var{insert_breapoints_p})
2159 @findex SOFTWARE_SINGLE_STEP
2160 A function that inserts or removes (depending on
2161 @var{insert_breapoints_p}) breakpoints at each possible destinations of
2162 the next instruction. See @file{sparc-tdep.c} and @file{rs6000-tdep.c}
2165 @item SOFUN_ADDRESS_MAYBE_MISSING
2166 @findex SOFUN_ADDRESS_MAYBE_MISSING
2167 Somebody clever observed that, the more actual addresses you have in the
2168 debug information, the more time the linker has to spend relocating
2169 them. So whenever there's some other way the debugger could find the
2170 address it needs, you should omit it from the debug info, to make
2173 @code{SOFUN_ADDRESS_MAYBE_MISSING} indicates that a particular set of
2174 hacks of this sort are in use, affecting @code{N_SO} and @code{N_FUN}
2175 entries in stabs-format debugging information. @code{N_SO} stabs mark
2176 the beginning and ending addresses of compilation units in the text
2177 segment. @code{N_FUN} stabs mark the starts and ends of functions.
2179 @code{SOFUN_ADDRESS_MAYBE_MISSING} means two things:
2183 @code{N_FUN} stabs have an address of zero. Instead, you should find the
2184 addresses where the function starts by taking the function name from
2185 the stab, and then looking that up in the minsyms (the
2186 linker/assembler symbol table). In other words, the stab has the
2187 name, and the linker/assembler symbol table is the only place that carries
2191 @code{N_SO} stabs have an address of zero, too. You just look at the
2192 @code{N_FUN} stabs that appear before and after the @code{N_SO} stab,
2193 and guess the starting and ending addresses of the compilation unit from
2197 @item PCC_SOL_BROKEN
2198 @findex PCC_SOL_BROKEN
2199 (Used only in the Convex target.)
2201 @item PC_IN_CALL_DUMMY
2202 @findex PC_IN_CALL_DUMMY
2203 See @file{inferior.h}.
2205 @item PC_LOAD_SEGMENT
2206 @findex PC_LOAD_SEGMENT
2207 If defined, print information about the load segment for the program
2208 counter. (Defined only for the RS/6000.)
2212 If the program counter is kept in a register, then define this macro to
2213 be the number (greater than or equal to zero) of that register.
2215 This should only need to be defined if @code{TARGET_READ_PC} and
2216 @code{TARGET_WRITE_PC} are not defined.
2220 The number of the ``next program counter'' register, if defined.
2224 The number of the ``next next program counter'' register, if defined.
2225 Currently, this is only defined for the Motorola 88K.
2228 @findex PARM_BOUNDARY
2229 If non-zero, round arguments to a boundary of this many bits before
2230 pushing them on the stack.
2232 @item PRINT_REGISTER_HOOK (@var{regno})
2233 @findex PRINT_REGISTER_HOOK
2234 If defined, this must be a function that prints the contents of the
2235 given register to standard output.
2237 @item PRINT_TYPELESS_INTEGER
2238 @findex PRINT_TYPELESS_INTEGER
2239 This is an obscure substitute for @code{print_longest} that seems to
2240 have been defined for the Convex target.
2242 @item PROCESS_LINENUMBER_HOOK
2243 @findex PROCESS_LINENUMBER_HOOK
2244 A hook defined for XCOFF reading.
2246 @item PROLOGUE_FIRSTLINE_OVERLAP
2247 @findex PROLOGUE_FIRSTLINE_OVERLAP
2248 (Only used in unsupported Convex configuration.)
2252 If defined, this is the number of the processor status register. (This
2253 definition is only used in generic code when parsing "$ps".)
2257 @findex call_function_by_hand
2258 @findex return_command
2259 Used in @samp{call_function_by_hand} to remove an artificial stack
2260 frame and in @samp{return_command} to remove a real stack frame.
2262 @item PUSH_ARGUMENTS (@var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr})
2263 @findex PUSH_ARGUMENTS
2264 Define this to push arguments onto the stack for inferior function
2265 call. Returns the updated stack pointer value.
2267 @item PUSH_DUMMY_FRAME
2268 @findex PUSH_DUMMY_FRAME
2269 Used in @samp{call_function_by_hand} to create an artificial stack frame.
2271 @item REGISTER_BYTES
2272 @findex REGISTER_BYTES
2273 The total amount of space needed to store @value{GDBN}'s copy of the machine's
2276 @item REGISTER_NAME(@var{i})
2277 @findex REGISTER_NAME
2278 Return the name of register @var{i} as a string. May return @code{NULL}
2279 or @code{NUL} to indicate that register @var{i} is not valid.
2281 @item REGISTER_NAMES
2282 @findex REGISTER_NAMES
2283 Deprecated in favor of @code{REGISTER_NAME}.
2285 @item REG_STRUCT_HAS_ADDR (@var{gcc_p}, @var{type})
2286 @findex REG_STRUCT_HAS_ADDR
2287 Define this to return 1 if the given type will be passed by pointer
2288 rather than directly.
2290 @item SAVE_DUMMY_FRAME_TOS (@var{sp})
2291 @findex SAVE_DUMMY_FRAME_TOS
2292 Used in @samp{call_function_by_hand} to notify the target dependent code
2293 of the top-of-stack value that will be passed to the the inferior code.
2294 This is the value of the @code{SP} after both the dummy frame and space
2295 for parameters/results have been allocated on the stack.
2297 @item SDB_REG_TO_REGNUM
2298 @findex SDB_REG_TO_REGNUM
2299 Define this to convert sdb register numbers into @value{GDBN} regnums. If not
2300 defined, no conversion will be done.
2302 @item SHIFT_INST_REGS
2303 @findex SHIFT_INST_REGS
2304 (Only used for m88k targets.)
2306 @item SKIP_PERMANENT_BREAKPOINT
2307 @findex SKIP_PERMANENT_BREAKPOINT
2308 Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally
2309 steps over a breakpoint by removing it, stepping one instruction, and
2310 re-inserting the breakpoint. However, permanent breakpoints are
2311 hardwired into the inferior, and can't be removed, so this strategy
2312 doesn't work. Calling @code{SKIP_PERMANENT_BREAKPOINT} adjusts the processor's
2313 state so that execution will resume just after the breakpoint. This
2314 macro does the right thing even when the breakpoint is in the delay slot
2315 of a branch or jump.
2317 @item SKIP_PROLOGUE (@var{pc})
2318 @findex SKIP_PROLOGUE
2319 A C expression that returns the address of the ``real'' code beyond the
2320 function entry prologue found at @var{pc}.
2322 @item SKIP_PROLOGUE_FRAMELESS_P
2323 @findex SKIP_PROLOGUE_FRAMELESS_P
2324 A C expression that should behave similarly, but that can stop as soon
2325 as the function is known to have a frame. If not defined,
2326 @code{SKIP_PROLOGUE} will be used instead.
2328 @item SKIP_TRAMPOLINE_CODE (@var{pc})
2329 @findex SKIP_TRAMPOLINE_CODE
2330 If the target machine has trampoline code that sits between callers and
2331 the functions being called, then define this macro to return a new PC
2332 that is at the start of the real function.
2336 If the stack-pointer is kept in a register, then define this macro to be
2337 the number (greater than or equal to zero) of that register.
2339 This should only need to be defined if @code{TARGET_WRITE_SP} and
2340 @code{TARGET_WRITE_SP} are not defined.
2342 @item STAB_REG_TO_REGNUM
2343 @findex STAB_REG_TO_REGNUM
2344 Define this to convert stab register numbers (as gotten from `r'
2345 declarations) into @value{GDBN} regnums. If not defined, no conversion will be
2348 @item STACK_ALIGN (@var{addr})
2350 Define this to adjust the address to the alignment required for the
2353 @item STEP_SKIPS_DELAY (@var{addr})
2354 @findex STEP_SKIPS_DELAY
2355 Define this to return true if the address is of an instruction with a
2356 delay slot. If a breakpoint has been placed in the instruction's delay
2357 slot, @value{GDBN} will single-step over that instruction before resuming
2358 normally. Currently only defined for the Mips.
2360 @item STORE_RETURN_VALUE (@var{type}, @var{valbuf})
2361 @findex STORE_RETURN_VALUE
2362 A C expression that stores a function return value of type @var{type},
2363 where @var{valbuf} is the address of the value to be stored.
2365 @item SUN_FIXED_LBRAC_BUG
2366 @findex SUN_FIXED_LBRAC_BUG
2367 (Used only for Sun-3 and Sun-4 targets.)
2369 @item SYMBOL_RELOADING_DEFAULT
2370 @findex SYMBOL_RELOADING_DEFAULT
2371 The default value of the ``symbol-reloading'' variable. (Never defined in
2374 @item TARGET_BYTE_ORDER_DEFAULT
2375 @findex TARGET_BYTE_ORDER_DEFAULT
2376 The ordering of bytes in the target. This must be either
2377 @code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. This macro replaces
2378 @code{TARGET_BYTE_ORDER} which is deprecated.
2380 @item TARGET_BYTE_ORDER_SELECTABLE_P
2381 @findex TARGET_BYTE_ORDER_SELECTABLE_P
2382 Non-zero if the target has both @code{BIG_ENDIAN} and
2383 @code{LITTLE_ENDIAN} variants. This macro replaces
2384 @code{TARGET_BYTE_ORDER_SELECTABLE} which is deprecated.
2386 @item TARGET_CHAR_BIT
2387 @findex TARGET_CHAR_BIT
2388 Number of bits in a char; defaults to 8.
2390 @item TARGET_COMPLEX_BIT
2391 @findex TARGET_COMPLEX_BIT
2392 Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}.
2394 At present this macro is not used.
2396 @item TARGET_DOUBLE_BIT
2397 @findex TARGET_DOUBLE_BIT
2398 Number of bits in a double float; defaults to @code{8 * TARGET_CHAR_BIT}.
2400 @item TARGET_DOUBLE_COMPLEX_BIT
2401 @findex TARGET_DOUBLE_COMPLEX_BIT
2402 Number of bits in a double complex; defaults to @code{2 * TARGET_DOUBLE_BIT}.
2404 At present this macro is not used.
2406 @item TARGET_FLOAT_BIT
2407 @findex TARGET_FLOAT_BIT
2408 Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}.
2410 @item TARGET_INT_BIT
2411 @findex TARGET_INT_BIT
2412 Number of bits in an integer; defaults to @code{4 * TARGET_CHAR_BIT}.
2414 @item TARGET_LONG_BIT
2415 @findex TARGET_LONG_BIT
2416 Number of bits in a long integer; defaults to @code{4 * TARGET_CHAR_BIT}.
2418 @item TARGET_LONG_DOUBLE_BIT
2419 @findex TARGET_LONG_DOUBLE_BIT
2420 Number of bits in a long double float;
2421 defaults to @code{2 * TARGET_DOUBLE_BIT}.
2423 @item TARGET_LONG_LONG_BIT
2424 @findex TARGET_LONG_LONG_BIT
2425 Number of bits in a long long integer; defaults to @code{2 * TARGET_LONG_BIT}.
2427 @item TARGET_PTR_BIT
2428 @findex TARGET_PTR_BIT
2429 Number of bits in a pointer; defaults to @code{TARGET_INT_BIT}.
2431 @item TARGET_SHORT_BIT
2432 @findex TARGET_SHORT_BIT
2433 Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}.
2435 @item TARGET_READ_PC
2436 @findex TARGET_READ_PC
2437 @itemx TARGET_WRITE_PC (@var{val}, @var{pid})
2438 @findex TARGET_WRITE_PC
2439 @itemx TARGET_READ_SP
2440 @findex TARGET_READ_SP
2441 @itemx TARGET_WRITE_SP
2442 @findex TARGET_WRITE_SP
2443 @itemx TARGET_READ_FP
2444 @findex TARGET_READ_FP
2445 @itemx TARGET_WRITE_FP
2446 @findex TARGET_WRITE_FP
2453 These change the behavior of @code{read_pc}, @code{write_pc},
2454 @code{read_sp}, @code{write_sp}, @code{read_fp} and @code{write_fp}.
2455 For most targets, these may be left undefined. @value{GDBN} will call the read
2456 and write register functions with the relevant @code{_REGNUM} argument.
2458 These macros are useful when a target keeps one of these registers in a
2459 hard to get at place; for example, part in a segment register and part
2460 in an ordinary register.
2462 @item TARGET_VIRTUAL_FRAME_POINTER(@var{pc}, @var{regp}, @var{offsetp})
2463 @findex TARGET_VIRTUAL_FRAME_POINTER
2464 Returns a @code{(register, offset)} pair representing the virtual
2465 frame pointer in use at the code address @var{pc}. If virtual
2466 frame pointers are not used, a default definition simply returns
2467 @code{FP_REGNUM}, with an offset of zero.
2469 @item USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type})
2470 @findex USE_STRUCT_CONVENTION
2471 If defined, this must be an expression that is nonzero if a value of the
2472 given @var{type} being returned from a function must have space
2473 allocated for it on the stack. @var{gcc_p} is true if the function
2474 being considered is known to have been compiled by GCC; this is helpful
2475 for systems where GCC is known to use different calling convention than
2478 @item VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p})
2479 @findex VARIABLES_INSIDE_BLOCK
2480 For dbx-style debugging information, if the compiler puts variable
2481 declarations inside LBRAC/RBRAC blocks, this should be defined to be
2482 nonzero. @var{desc} is the value of @code{n_desc} from the
2483 @code{N_RBRAC} symbol, and @var{gcc_p} is true if @value{GDBN} has noticed the
2484 presence of either the @code{GCC_COMPILED_SYMBOL} or the
2485 @code{GCC2_COMPILED_SYMBOL}. By default, this is 0.
2487 @item OS9K_VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p})
2488 @findex OS9K_VARIABLES_INSIDE_BLOCK
2489 Similarly, for OS/9000. Defaults to 1.
2492 Motorola M68K target conditionals.
2496 Define this to be the 4-bit location of the breakpoint trap vector. If
2497 not defined, it will default to @code{0xf}.
2499 @item REMOTE_BPT_VECTOR
2500 Defaults to @code{1}.
2503 @section Adding a New Target
2505 @cindex adding a target
2506 The following files define a target to @value{GDBN}:
2510 @item gdb/config/@var{arch}/@var{ttt}.mt
2511 Contains a Makefile fragment specific to this target. Specifies what
2512 object files are needed for target @var{ttt}, by defining
2513 @samp{TDEPFILES=@dots{}} and @samp{TDEPLIBS=@dots{}}. Also specifies
2514 the header file which describes @var{ttt}, by defining @samp{TM_FILE=
2517 You can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, @samp{TM_CDEPS},
2518 but these are now deprecated, replaced by autoconf, and may go away in
2519 future versions of @value{GDBN}.
2521 @item gdb/config/@var{arch}/tm-@var{ttt}.h
2522 (@file{tm.h} is a link to this file, created by @code{configure}). Contains
2523 macro definitions about the target machine's registers, stack frame
2524 format and instructions.
2526 @item gdb/@var{ttt}-tdep.c
2527 Contains any miscellaneous code required for this target machine. On
2528 some machines it doesn't exist at all. Sometimes the macros in
2529 @file{tm-@var{ttt}.h} become very complicated, so they are implemented
2530 as functions here instead, and the macro is simply defined to call the
2531 function. This is vastly preferable, since it is easier to understand
2534 @item gdb/config/@var{arch}/tm-@var{arch}.h
2535 This often exists to describe the basic layout of the target machine's
2536 processor chip (registers, stack, etc.). If used, it is included by
2537 @file{tm-@var{ttt}.h}. It can be shared among many targets that use the
2540 @item gdb/@var{arch}-tdep.c
2541 Similarly, there are often common subroutines that are shared by all
2542 target machines that use this particular architecture.
2545 If you are adding a new operating system for an existing CPU chip, add a
2546 @file{config/tm-@var{os}.h} file that describes the operating system
2547 facilities that are unusual (extra symbol table info; the breakpoint
2548 instruction needed; etc.). Then write a @file{@var{arch}/tm-@var{os}.h}
2549 that just @code{#include}s @file{tm-@var{arch}.h} and
2550 @file{config/tm-@var{os}.h}.
2553 @node Target Vector Definition
2555 @chapter Target Vector Definition
2556 @cindex target vector
2558 The target vector defines the interface between @value{GDBN}'s
2559 abstract handling of target systems, and the nitty-gritty code that
2560 actually exercises control over a process or a serial port.
2561 @value{GDBN} includes some 30-40 different target vectors; however,
2562 each configuration of @value{GDBN} includes only a few of them.
2564 @section File Targets
2566 Both executables and core files have target vectors.
2568 @section Standard Protocol and Remote Stubs
2570 @value{GDBN}'s file @file{remote.c} talks a serial protocol to code
2571 that runs in the target system. @value{GDBN} provides several sample
2572 @dfn{stubs} that can be integrated into target programs or operating
2573 systems for this purpose; they are named @file{*-stub.c}.
2575 The @value{GDBN} user's manual describes how to put such a stub into
2576 your target code. What follows is a discussion of integrating the
2577 SPARC stub into a complicated operating system (rather than a simple
2578 program), by Stu Grossman, the author of this stub.
2580 The trap handling code in the stub assumes the following upon entry to
2585 %l1 and %l2 contain pc and npc respectively at the time of the trap;
2591 you are in the correct trap window.
2594 As long as your trap handler can guarantee those conditions, then there
2595 is no reason why you shouldn't be able to ``share'' traps with the stub.
2596 The stub has no requirement that it be jumped to directly from the
2597 hardware trap vector. That is why it calls @code{exceptionHandler()},
2598 which is provided by the external environment. For instance, this could
2599 set up the hardware traps to actually execute code which calls the stub
2600 first, and then transfers to its own trap handler.
2602 For the most point, there probably won't be much of an issue with
2603 ``sharing'' traps, as the traps we use are usually not used by the kernel,
2604 and often indicate unrecoverable error conditions. Anyway, this is all
2605 controlled by a table, and is trivial to modify. The most important
2606 trap for us is for @code{ta 1}. Without that, we can't single step or
2607 do breakpoints. Everything else is unnecessary for the proper operation
2608 of the debugger/stub.
2610 From reading the stub, it's probably not obvious how breakpoints work.
2611 They are simply done by deposit/examine operations from @value{GDBN}.
2613 @section ROM Monitor Interface
2615 @section Custom Protocols
2617 @section Transport Layer
2619 @section Builtin Simulator
2622 @node Native Debugging
2624 @chapter Native Debugging
2625 @cindex native debugging
2627 Several files control @value{GDBN}'s configuration for native support:
2631 @item gdb/config/@var{arch}/@var{xyz}.mh
2632 Specifies Makefile fragments needed when hosting @emph{or native} on
2633 machine @var{xyz}. In particular, this lists the required
2634 native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}.
2635 Also specifies the header file which describes native support on
2636 @var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}. You can also
2637 define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS},
2638 @samp{NAT_CDEPS}, etc.; see @file{Makefile.in}.
2640 @item gdb/config/@var{arch}/nm-@var{xyz}.h
2641 (@file{nm.h} is a link to this file, created by @code{configure}). Contains C
2642 macro definitions describing the native system environment, such as
2643 child process control and core file support.
2645 @item gdb/@var{xyz}-nat.c
2646 Contains any miscellaneous C code required for this native support of
2647 this machine. On some machines it doesn't exist at all.
2650 There are some ``generic'' versions of routines that can be used by
2651 various systems. These can be customized in various ways by macros
2652 defined in your @file{nm-@var{xyz}.h} file. If these routines work for
2653 the @var{xyz} host, you can just include the generic file's name (with
2654 @samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.
2656 Otherwise, if your machine needs custom support routines, you will need
2657 to write routines that perform the same functions as the generic file.
2658 Put them into @file{@var{xyz}-nat.c}, and put @file{@var{xyz}-nat.o}
2659 into @code{NATDEPFILES}.
2663 This contains the @emph{target_ops vector} that supports Unix child
2664 processes on systems which use ptrace and wait to control the child.
2667 This contains the @emph{target_ops vector} that supports Unix child
2668 processes on systems which use /proc to control the child.
2671 This does the low-level grunge that uses Unix system calls to do a ``fork
2672 and exec'' to start up a child process.
2675 This is the low level interface to inferior processes for systems using
2676 the Unix @code{ptrace} call in a vanilla way.
2679 @section Native core file Support
2680 @cindex native core files
2683 @findex fetch_core_registers
2684 @item core-aout.c::fetch_core_registers()
2685 Support for reading registers out of a core file. This routine calls
2686 @code{register_addr()}, see below. Now that BFD is used to read core
2687 files, virtually all machines should use @code{core-aout.c}, and should
2688 just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or
2689 @code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}).
2691 @item core-aout.c::register_addr()
2692 If your @code{nm-@var{xyz}.h} file defines the macro
2693 @code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
2694 set @code{addr} to the offset within the @samp{user} struct of @value{GDBN}
2695 register number @code{regno}. @code{blockend} is the offset within the
2696 ``upage'' of @code{u.u_ar0}. If @code{REGISTER_U_ADDR} is defined,
2697 @file{core-aout.c} will define the @code{register_addr()} function and
2698 use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but
2699 you are using the standard @code{fetch_core_registers()}, you will need
2700 to define your own version of @code{register_addr()}, put it into your
2701 @code{@var{xyz}-nat.c} file, and be sure @code{@var{xyz}-nat.o} is in
2702 the @code{NATDEPFILES} list. If you have your own
2703 @code{fetch_core_registers()}, you may not need a separate
2704 @code{register_addr()}. Many custom @code{fetch_core_registers()}
2705 implementations simply locate the registers themselves.@refill
2708 When making @value{GDBN} run native on a new operating system, to make it
2709 possible to debug core files, you will need to either write specific
2710 code for parsing your OS's core files, or customize
2711 @file{bfd/trad-core.c}. First, use whatever @code{#include} files your
2712 machine uses to define the struct of registers that is accessible
2713 (possibly in the u-area) in a core file (rather than
2714 @file{machine/reg.h}), and an include file that defines whatever header
2715 exists on a core file (e.g. the u-area or a @code{struct core}). Then
2716 modify @code{trad_unix_core_file_p} to use these values to set up the
2717 section information for the data segment, stack segment, any other
2718 segments in the core file (perhaps shared library contents or control
2719 information), ``registers'' segment, and if there are two discontiguous
2720 sets of registers (e.g. integer and float), the ``reg2'' segment. This
2721 section information basically delimits areas in the core file in a
2722 standard way, which the section-reading routines in BFD know how to seek
2725 Then back in @value{GDBN}, you need a matching routine called
2726 @code{fetch_core_registers}. If you can use the generic one, it's in
2727 @file{core-aout.c}; if not, it's in your @file{@var{xyz}-nat.c} file.
2728 It will be passed a char pointer to the entire ``registers'' segment,
2729 its length, and a zero; or a char pointer to the entire ``regs2''
2730 segment, its length, and a 2. The routine should suck out the supplied
2731 register values and install them into @value{GDBN}'s ``registers'' array.
2733 If your system uses @file{/proc} to control processes, and uses ELF
2734 format core files, then you may be able to use the same routines for
2735 reading the registers out of processes and out of core files.
2743 @section shared libraries
2745 @section Native Conditionals
2746 @cindex native conditionals
2748 When @value{GDBN} is configured and compiled, various macros are
2749 defined or left undefined, to control compilation when the host and
2750 target systems are the same. These macros should be defined (or left
2751 undefined) in @file{nm-@var{system}.h}.
2755 @findex ATTACH_DETACH
2756 If defined, then @value{GDBN} will include support for the @code{attach} and
2757 @code{detach} commands.
2759 @item CHILD_PREPARE_TO_STORE
2760 @findex CHILD_PREPARE_TO_STORE
2761 If the machine stores all registers at once in the child process, then
2762 define this to ensure that all values are correct. This usually entails
2763 a read from the child.
2765 [Note that this is incorrectly defined in @file{xm-@var{system}.h} files
2768 @item FETCH_INFERIOR_REGISTERS
2769 @findex FETCH_INFERIOR_REGISTERS
2770 Define this if the native-dependent code will provide its own routines
2771 @code{fetch_inferior_registers} and @code{store_inferior_registers} in
2772 @file{@var{host}-nat.c}. If this symbol is @emph{not} defined, and
2773 @file{infptrace.c} is included in this configuration, the default
2774 routines in @file{infptrace.c} are used for these functions.
2776 @item FILES_INFO_HOOK
2777 @findex FILES_INFO_HOOK
2778 (Only defined for Convex.)
2782 This macro is normally defined to be the number of the first floating
2783 point register, if the machine has such registers. As such, it would
2784 appear only in target-specific code. However, @file{/proc} support uses this
2785 to decide whether floats are in use on this target.
2787 @item GET_LONGJMP_TARGET
2788 @findex GET_LONGJMP_TARGET
2789 For most machines, this is a target-dependent parameter. On the
2790 DECstation and the Iris, this is a native-dependent parameter, since
2791 @file{setjmp.h} is needed to define it.
2793 This macro determines the target PC address that @code{longjmp} will jump to,
2794 assuming that we have just stopped at a longjmp breakpoint. It takes a
2795 @code{CORE_ADDR *} as argument, and stores the target PC value through this
2796 pointer. It examines the current state of the machine as needed.
2799 @findex KERNEL_U_ADDR
2800 Define this to the address of the @code{u} structure (the ``user
2801 struct'', also known as the ``u-page'') in kernel virtual memory. @value{GDBN}
2802 needs to know this so that it can subtract this address from absolute
2803 addresses in the upage, that are obtained via ptrace or from core files.
2804 On systems that don't need this value, set it to zero.
2806 @item KERNEL_U_ADDR_BSD
2807 @findex KERNEL_U_ADDR_BSD
2808 Define this to cause @value{GDBN} to determine the address of @code{u} at
2809 runtime, by using Berkeley-style @code{nlist} on the kernel's image in
2812 @item KERNEL_U_ADDR_HPUX
2813 @findex KERNEL_U_ADDR_HPUX
2814 Define this to cause @value{GDBN} to determine the address of @code{u} at
2815 runtime, by using HP-style @code{nlist} on the kernel's image in the
2818 @item ONE_PROCESS_WRITETEXT
2819 @findex ONE_PROCESS_WRITETEXT
2820 Define this to be able to, when a breakpoint insertion fails, warn the
2821 user that another process may be running with the same executable.
2823 @item PREPARE_TO_PROCEED (@var{select_it})
2824 @findex PREPARE_TO_PROCEED
2825 This (ugly) macro allows a native configuration to customize the way the
2826 @code{proceed} function in @file{infrun.c} deals with switching between
2829 In a multi-threaded task we may select another thread and then continue
2830 or step. But if the old thread was stopped at a breakpoint, it will
2831 immediately cause another breakpoint stop without any execution (i.e. it
2832 will report a breakpoint hit incorrectly). So @value{GDBN} must step over it
2835 If defined, @code{PREPARE_TO_PROCEED} should check the current thread
2836 against the thread that reported the most recent event. If a step-over
2837 is required, it returns TRUE. If @var{select_it} is non-zero, it should
2838 reselect the old thread.
2841 @findex PROC_NAME_FMT
2842 Defines the format for the name of a @file{/proc} device. Should be
2843 defined in @file{nm.h} @emph{only} in order to override the default
2844 definition in @file{procfs.c}.
2847 @findex PTRACE_FP_BUG
2848 See @file{mach386-xdep.c}.
2850 @item PTRACE_ARG3_TYPE
2851 @findex PTRACE_ARG3_TYPE
2852 The type of the third argument to the @code{ptrace} system call, if it
2853 exists and is different from @code{int}.
2855 @item REGISTER_U_ADDR
2856 @findex REGISTER_U_ADDR
2857 Defines the offset of the registers in the ``u area''.
2859 @item SHELL_COMMAND_CONCAT
2860 @findex SHELL_COMMAND_CONCAT
2861 If defined, is a string to prefix on the shell command used to start the
2866 If defined, this is the name of the shell to use to run the inferior.
2867 Defaults to @code{"/bin/sh"}.
2869 @item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ})
2871 Define this to expand into an expression that will cause the symbols in
2872 @var{filename} to be added to @value{GDBN}'s symbol table.
2874 @item SOLIB_CREATE_INFERIOR_HOOK
2875 @findex SOLIB_CREATE_INFERIOR_HOOK
2876 Define this to expand into any shared-library-relocation code that you
2877 want to be run just after the child process has been forked.
2879 @item START_INFERIOR_TRAPS_EXPECTED
2880 @findex START_INFERIOR_TRAPS_EXPECTED
2881 When starting an inferior, @value{GDBN} normally expects to trap
2883 the shell execs, and once when the program itself execs. If the actual
2884 number of traps is something other than 2, then define this macro to
2885 expand into the number expected.
2887 @item SVR4_SHARED_LIBS
2888 @findex SVR4_SHARED_LIBS
2889 Define this to indicate that SVR4-style shared libraries are in use.
2893 This determines whether small routines in @file{*-tdep.c}, which
2894 translate register values between @value{GDBN}'s internal
2895 representation and the @file{/proc} representation, are compiled.
2898 @findex U_REGS_OFFSET
2899 This is the offset of the registers in the upage. It need only be
2900 defined if the generic ptrace register access routines in
2901 @file{infptrace.c} are being used (that is, @file{infptrace.c} is
2902 configured in, and @code{FETCH_INFERIOR_REGISTERS} is not defined). If
2903 the default value from @file{infptrace.c} is good enough, leave it
2906 The default value means that u.u_ar0 @emph{points to} the location of
2907 the registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means
2908 that @code{u.u_ar0} @emph{is} the location of the registers.
2912 See @file{objfiles.c}.
2915 @findex DEBUG_PTRACE
2916 Define this to debug @code{ptrace} calls.
2920 @node Support Libraries
2922 @chapter Support Libraries
2927 BFD provides support for @value{GDBN} in several ways:
2930 @item identifying executable and core files
2931 BFD will identify a variety of file types, including a.out, coff, and
2932 several variants thereof, as well as several kinds of core files.
2934 @item access to sections of files
2935 BFD parses the file headers to determine the names, virtual addresses,
2936 sizes, and file locations of all the various named sections in files
2937 (such as the text section or the data section). @value{GDBN} simply
2938 calls BFD to read or write section @var{x} at byte offset @var{y} for
2941 @item specialized core file support
2942 BFD provides routines to determine the failing command name stored in a
2943 core file, the signal with which the program failed, and whether a core
2944 file matches (i.e.@: could be a core dump of) a particular executable
2947 @item locating the symbol information
2948 @value{GDBN} uses an internal interface of BFD to determine where to find the
2949 symbol information in an executable file or symbol-file. @value{GDBN} itself
2950 handles the reading of symbols, since BFD does not ``understand'' debug
2951 symbols, but @value{GDBN} uses BFD's cached information to find the symbols,
2956 @cindex opcodes library
2958 The opcodes library provides @value{GDBN}'s disassembler. (It's a separate
2959 library because it's also used in binutils, for @file{objdump}).
2968 @cindex regular expressions library
2979 @item SIGN_EXTEND_CHAR
2981 @item SWITCH_ENUM_BUG
2996 This chapter covers topics that are lower-level than the major
2997 algorithms of @value{GDBN}.
3002 Cleanups are a structured way to deal with things that need to be done
3003 later. When your code does something (like @code{malloc} some memory,
3004 or open a file) that needs to be undone later (e.g., free the memory or
3005 close the file), it can make a cleanup. The cleanup will be done at
3006 some future point: when the command is finished, when an error occurs,
3007 or when your code decides it's time to do cleanups.
3009 You can also discard cleanups, that is, throw them away without doing
3010 what they say. This is only done if you ask that it be done.
3015 @item struct cleanup *@var{old_chain};
3016 Declare a variable which will hold a cleanup chain handle.
3018 @findex make_cleanup
3019 @item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
3020 Make a cleanup which will cause @var{function} to be called with
3021 @var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a
3022 handle that can be passed to @code{do_cleanups} or
3023 @code{discard_cleanups} later. Unless you are going to call
3024 @code{do_cleanups} or @code{discard_cleanups} yourself, you can ignore
3025 the result from @code{make_cleanup}.
3028 @item do_cleanups (@var{old_chain});
3029 Perform all cleanups done since @code{make_cleanup} returned
3030 @var{old_chain}. E.g.:
3033 make_cleanup (a, 0);
3034 old = make_cleanup (b, 0);
3039 will call @code{b()} but will not call @code{a()}. The cleanup that
3040 calls @code{a()} will remain in the cleanup chain, and will be done
3041 later unless otherwise discarded.@refill
3043 @findex discard_cleanups
3044 @item discard_cleanups (@var{old_chain});
3045 Same as @code{do_cleanups} except that it just removes the cleanups from
3046 the chain and does not call the specified functions.
3049 Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify
3050 that they ``should not be called when cleanups are not in place''. This
3051 means that any actions you need to reverse in the case of an error or
3052 interruption must be on the cleanup chain before you call these
3053 functions, since they might never return to your code (they
3054 @samp{longjmp} instead).
3056 @section Wrapping Output Lines
3057 @cindex line wrap in output
3060 Output that goes through @code{printf_filtered} or @code{fputs_filtered}
3061 or @code{fputs_demangled} needs only to have calls to @code{wrap_here}
3062 added in places that would be good breaking points. The utility
3063 routines will take care of actually wrapping if the line width is
3066 The argument to @code{wrap_here} is an indentation string which is
3067 printed @emph{only} if the line breaks there. This argument is saved
3068 away and used later. It must remain valid until the next call to
3069 @code{wrap_here} or until a newline has been printed through the
3070 @code{*_filtered} functions. Don't pass in a local variable and then
3073 It is usually best to call @code{wrap_here} after printing a comma or
3074 space. If you call it before printing a space, make sure that your
3075 indentation properly accounts for the leading space that will print if
3076 the line wraps there.
3078 Any function or set of functions that produce filtered output must
3079 finish by printing a newline, to flush the wrap buffer, before switching
3080 to unfiltered (@code{printf}) output. Symbol reading routines that
3081 print warnings are a good example.
3083 @section @value{GDBN} Coding Standards
3084 @cindex coding standards
3086 @value{GDBN} follows the GNU coding standards, as described in
3087 @file{etc/standards.texi}. This file is also available for anonymous
3088 FTP from GNU archive sites. @value{GDBN} takes a strict interpretation of the
3089 standard; in general, when the GNU standard recommends a practice but
3090 does not require it, @value{GDBN} requires it.
3092 @value{GDBN} follows an additional set of coding standards specific to
3093 @value{GDBN}, as described in the following sections.
3095 @cindex compiler warnings
3096 You can configure with @samp{--enable-build-warnings} or
3097 @samp{--enable-gdb-build-warnings} to get GCC to check on a number of
3098 these rules. @value{GDBN} sources ought not to engender any complaints,
3099 unless they are caused by bogus host systems. (The exact set of enabled
3100 warnings is currently @samp{-Wimplicit -Wreturn-type -Wcomment
3101 -Wtrigraphs -Wformat -Wparentheses -Wpointer-arith -Wuninitialized}.
3103 @subsection Formatting
3105 @cindex source code formatting
3106 The standard GNU recommendations for formatting must be followed
3109 Note that while in a definition, the function's name must be in column
3110 zero; in a function declaration, the name must be on the same line as
3113 In addition, there must be a space between a function or macro name and
3114 the opening parenthesis of its argument list (except for macro
3115 definitions, as required by C). There must not be a space after an open
3116 paren/bracket or before a close paren/bracket.
3118 While additional whitespace is generally helpful for reading, do not use
3119 more than one blank line to separate blocks, and avoid adding whitespace
3120 after the end of a program line (as of 1/99, some 600 lines had whitespace
3121 after the semicolon). Excess whitespace causes difficulties for
3122 @code{diff} and @code{patch} utilities.
3124 @subsection Comments
3126 @cindex comment formatting
3127 The standard GNU requirements on comments must be followed strictly.
3129 Block comments must appear in the following form, with no @samp{/*}- or
3130 @samp{*/}-only lines, and no leading @samp{*}:
3133 /* Wait for control to return from inferior to debugger. If inferior
3134 gets a signal, we may decide to start it up again instead of
3135 returning. That is why there is a loop in this function. When
3136 this function actually returns it means the inferior should be left
3137 stopped and @value{GDBN} should read more commands. */
3140 (Note that this format is encouraged by Emacs; tabbing for a multi-line
3141 comment works correctly, and @kbd{M-q} fills the block consistently.)
3143 Put a blank line between the block comments preceding function or
3144 variable definitions, and the definition itself.
3146 In general, put function-body comments on lines by themselves, rather
3147 than trying to fit them into the 20 characters left at the end of a
3148 line, since either the comment or the code will inevitably get longer
3149 than will fit, and then somebody will have to move it anyhow.
3153 @cindex C data types
3154 Code must not depend on the sizes of C data types, the format of the
3155 host's floating point numbers, the alignment of anything, or the order
3156 of evaluation of expressions.
3158 @cindex function usage
3159 Use functions freely. There are only a handful of compute-bound areas
3160 in @value{GDBN} that might be affected by the overhead of a function
3161 call, mainly in symbol reading. Most of @value{GDBN}'s performance is
3162 limited by the target interface (whether serial line or system call).
3164 However, use functions with moderation. A thousand one-line functions
3165 are just as hard to understand as a single thousand-line function.
3167 @subsection Function Prototypes
3169 @cindex function prototypes
3170 Prototypes must be used to @emph{declare} functions, and may be used
3171 to @emph{define} them. Prototypes for @value{GDBN} functions must
3172 include both the argument type and name, with the name matching that
3173 used in the actual function definition.
3175 All external functions should have a declaration in a header file that
3176 callers include, except for @code{_initialize_*} functions, which must
3177 be external so that @file{init.c} construction works, but shouldn't be
3178 visible to random source files.
3180 All static functions must be declared in a block near the top of the
3183 @subsection Clean Design
3186 In addition to getting the syntax right, there's the little question of
3187 semantics. Some things are done in certain ways in @value{GDBN} because long
3188 experience has shown that the more obvious ways caused various kinds of
3191 @cindex assumptions about targets
3192 You can't assume the byte order of anything that comes from a target
3193 (including @var{value}s, object files, and instructions). Such things
3194 must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in
3195 @value{GDBN}, or one of the swap routines defined in @file{bfd.h},
3196 such as @code{bfd_get_32}.
3198 You can't assume that you know what interface is being used to talk to
3199 the target system. All references to the target must go through the
3200 current @code{target_ops} vector.
3202 You can't assume that the host and target machines are the same machine
3203 (except in the ``native'' support modules). In particular, you can't
3204 assume that the target machine's header files will be available on the
3205 host machine. Target code must bring along its own header files --
3206 written from scratch or explicitly donated by their owner, to avoid
3210 Insertion of new @code{#ifdef}'s will be frowned upon. It's much better
3211 to write the code portably than to conditionalize it for various
3214 @cindex system dependencies
3215 New @code{#ifdef}'s which test for specific compilers or manufacturers
3216 or operating systems are unacceptable. All @code{#ifdef}'s should test
3217 for features. The information about which configurations contain which
3218 features should be segregated into the configuration files. Experience
3219 has proven far too often that a feature unique to one particular system
3220 often creeps into other systems; and that a conditional based on some
3221 predefined macro for your current system will become worthless over
3222 time, as new versions of your system come out that behave differently
3223 with regard to this feature.
3225 Adding code that handles specific architectures, operating systems,
3226 target interfaces, or hosts, is not acceptable in generic code. If a
3227 hook is needed at that point, invent a generic hook and define it for
3228 your configuration, with something like:
3231 #ifdef WRANGLE_SIGNALS
3232 WRANGLE_SIGNALS (signo);
3236 In your host, target, or native configuration file, as appropriate,
3237 define @code{WRANGLE_SIGNALS} to do the machine-dependent thing. Take a
3238 bit of care in defining the hook, so that it can be used by other ports
3239 in the future, if they need a hook in the same place.
3241 If the hook is not defined, the code should do whatever ``most'' machines
3242 want. Using @code{#ifdef}, as above, is the preferred way to do this,
3243 but sometimes that gets convoluted, in which case use
3246 #ifndef SPECIAL_FOO_HANDLING
3247 #define SPECIAL_FOO_HANDLING(pc, sp) (0)
3252 where the macro is used or in an appropriate header file.
3254 Whether to include a @dfn{small} hook, a hook around the exact pieces of
3255 code which are system-dependent, or whether to replace a whole function
3256 with a hook, depends on the case. A good example of this dilemma can be
3257 found in @code{get_saved_register}. All machines that @value{GDBN} 2.8 ran on
3258 just needed the @code{FRAME_FIND_SAVED_REGS} hook to find the saved
3259 registers. Then the SPARC and Pyramid came along, and
3260 @code{HAVE_REGISTER_WINDOWS} and @code{REGISTER_IN_WINDOW_P} were
3261 introduced. Then the 29k and 88k required the @code{GET_SAVED_REGISTER}
3262 hook. The first three are examples of small hooks; the latter replaces
3263 a whole function. In this specific case, it is useful to have both
3264 kinds; it would be a bad idea to replace all the uses of the small hooks
3265 with @code{GET_SAVED_REGISTER}, since that would result in much
3266 duplicated code. Other times, duplicating a few lines of code here or
3267 there is much cleaner than introducing a large number of small hooks.
3269 Another way to generalize @value{GDBN} along a particular interface is with an
3270 attribute struct. For example, @value{GDBN} has been generalized to handle
3271 multiple kinds of remote interfaces---not by @code{#ifdef}s everywhere, but
3272 by defining the @code{target_ops} structure and having a current target (as
3273 well as a stack of targets below it, for memory references). Whenever
3274 something needs to be done that depends on which remote interface we are
3275 using, a flag in the current target_ops structure is tested (e.g.,
3276 @code{target_has_stack}), or a function is called through a pointer in the
3277 current target_ops structure. In this way, when a new remote interface
3278 is added, only one module needs to be touched---the one that actually
3279 implements the new remote interface. Other examples of
3280 attribute-structs are BFD access to multiple kinds of object file
3281 formats, or @value{GDBN}'s access to multiple source languages.
3283 Please avoid duplicating code. For example, in @value{GDBN} 3.x all
3284 the code interfacing between @code{ptrace} and the rest of
3285 @value{GDBN} was duplicated in @file{*-dep.c}, and so changing
3286 something was very painful. In @value{GDBN} 4.x, these have all been
3287 consolidated into @file{infptrace.c}. @file{infptrace.c} can deal
3288 with variations between systems the same way any system-independent
3289 file would (hooks, @code{#if defined}, etc.), and machines which are
3290 radically different don't need to use @file{infptrace.c} at all.
3292 Don't put debugging @code{printf}s in the code.
3296 @chapter Porting @value{GDBN}
3297 @cindex porting to new machines
3299 Most of the work in making @value{GDBN} compile on a new machine is in
3300 specifying the configuration of the machine. This is done in a
3301 dizzying variety of header files and configuration scripts, which we
3302 hope to make more sensible soon. Let's say your new host is called an
3303 @var{xyz} (e.g., @samp{sun4}), and its full three-part configuration
3304 name is @code{@var{arch}-@var{xvend}-@var{xos}} (e.g.,
3305 @samp{sparc-sun-sunos4}). In particular:
3309 In the top level directory, edit @file{config.sub} and add @var{arch},
3310 @var{xvend}, and @var{xos} to the lists of supported architectures,
3311 vendors, and operating systems near the bottom of the file. Also, add
3312 @var{xyz} as an alias that maps to
3313 @code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by
3317 ./config.sub @var{xyz}
3324 ./config.sub @code{@var{arch}-@var{xvend}-@var{xos}}
3328 which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}}
3329 and no error messages.
3332 You need to port BFD, if that hasn't been done already. Porting BFD is
3333 beyond the scope of this manual.
3336 To configure @value{GDBN} itself, edit @file{gdb/configure.host} to recognize
3337 your system and set @code{gdb_host} to @var{xyz}, and (unless your
3338 desired target is already available) also edit @file{gdb/configure.tgt},
3339 setting @code{gdb_target} to something appropriate (for instance,
3343 Finally, you'll need to specify and define @value{GDBN}'s host-, native-, and
3344 target-dependent @file{.h} and @file{.c} files used for your
3348 @section Configuring @value{GDBN} for Release
3350 @cindex preparing a release
3351 @cindex making a distribution tarball
3352 From the top level directory (containing @file{gdb}, @file{bfd},
3353 @file{libiberty}, and so on):
3356 make -f Makefile.in gdb.tar.gz
3360 This will properly configure, clean, rebuild any files that are
3361 distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}),
3362 and will then make a tarfile. (If the top level directory has already
3363 been configured, you can just do @code{make gdb.tar.gz} instead.)
3365 This procedure requires:
3373 @code{makeinfo} (texinfo2 level);
3382 @code{yacc} or @code{bison}.
3386 @dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.).
3388 @subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
3390 @file{gdb.texinfo} is currently marked up using the texinfo-2 macros,
3391 which are not yet a default for anything (but we have to start using
3394 For making paper, the only thing this implies is the right generation of
3395 @file{texinfo.tex} needs to be included in the distribution.
3397 For making info files, however, rather than duplicating the texinfo2
3398 distribution, generate @file{gdb-all.texinfo} locally, and include the
3399 files @file{gdb.info*} in the distribution. Note the plural;
3400 @code{makeinfo} will split the document into one overall file and five
3401 or so included files.
3408 The testsuite is an important component of the @value{GDBN} package.
3409 While it is always worthwhile to encourage user testing, in practice
3410 this is rarely sufficient; users typically use only a small subset of
3411 the available commands, and it has proven all too common for a change
3412 to cause a significant regression that went unnoticed for some time.
3414 The @value{GDBN} testsuite uses the DejaGNU testing framework.
3415 DejaGNU is built using @code{Tcl} and @code{expect}. The tests
3416 themselves are calls to various @code{Tcl} procs; the framework runs all the
3417 procs and summarizes the passes and fails.
3419 @section Using the Testsuite
3421 @cindex running the test suite
3422 To run the testsuite, simply go to the @value{GDBN} object directory (or to the
3423 testsuite's objdir) and type @code{make check}. This just sets up some
3424 environment variables and invokes DejaGNU's @code{runtest} script. While
3425 the testsuite is running, you'll get mentions of which test file is in use,
3426 and a mention of any unexpected passes or fails. When the testsuite is
3427 finished, you'll get a summary that looks like this:
3432 # of expected passes 6016
3433 # of unexpected failures 58
3434 # of unexpected successes 5
3435 # of expected failures 183
3436 # of unresolved testcases 3
3437 # of untested testcases 5
3440 The ideal test run consists of expected passes only; however, reality
3441 conspires to keep us from this ideal. Unexpected failures indicate
3442 real problems, whether in @value{GDBN} or in the testsuite. Expected
3443 failures are still failures, but ones which have been decided are too
3444 hard to deal with at the time; for instance, a test case might work
3445 everywhere except on AIX, and there is no prospect of the AIX case
3446 being fixed in the near future. Expected failures should not be added
3447 lightly, since you may be masking serious bugs in @value{GDBN}.
3448 Unexpected successes are expected fails that are passing for some
3449 reason, while unresolved and untested cases often indicate some minor
3450 catastrophe, such as the compiler being unable to deal with a test
3453 When making any significant change to @value{GDBN}, you should run the
3454 testsuite before and after the change, to confirm that there are no
3455 regressions. Note that truly complete testing would require that you
3456 run the testsuite with all supported configurations and a variety of
3457 compilers; however this is more than really necessary. In many cases
3458 testing with a single configuration is sufficient. Other useful
3459 options are to test one big-endian (Sparc) and one little-endian (x86)
3460 host, a cross config with a builtin simulator (powerpc-eabi,
3461 mips-elf), or a 64-bit host (Alpha).
3463 If you add new functionality to @value{GDBN}, please consider adding
3464 tests for it as well; this way future @value{GDBN} hackers can detect
3465 and fix their changes that break the functionality you added.
3466 Similarly, if you fix a bug that was not previously reported as a test
3467 failure, please add a test case for it. Some cases are extremely
3468 difficult to test, such as code that handles host OS failures or bugs
3469 in particular versions of compilers, and it's OK not to try to write
3470 tests for all of those.
3472 @section Testsuite Organization
3474 @cindex test suite organization
3475 The testsuite is entirely contained in @file{gdb/testsuite}. While the
3476 testsuite includes some makefiles and configury, these are very minimal,
3477 and used for little besides cleaning up, since the tests themselves
3478 handle the compilation of the programs that @value{GDBN} will run. The file
3479 @file{testsuite/lib/gdb.exp} contains common utility procs useful for
3480 all @value{GDBN} tests, while the directory @file{testsuite/config} contains
3481 configuration-specific files, typically used for special-purpose
3482 definitions of procs like @code{gdb_load} and @code{gdb_start}.
3484 The tests themselves are to be found in @file{testsuite/gdb.*} and
3485 subdirectories of those. The names of the test files must always end
3486 with @file{.exp}. DejaGNU collects the test files by wildcarding
3487 in the test directories, so both subdirectories and individual files
3488 get chosen and run in alphabetical order.
3490 The following table lists the main types of subdirectories and what they
3491 are for. Since DejaGNU finds test files no matter where they are
3492 located, and since each test file sets up its own compilation and
3493 execution environment, this organization is simply for convenience and
3498 This is the base testsuite. The tests in it should apply to all
3499 configurations of @value{GDBN} (but generic native-only tests may live here).
3500 The test programs should be in the subset of C that is valid K&R,
3501 ANSI/ISO, and C++ (@code{#ifdef}s are allowed if necessary, for instance
3504 @item gdb.@var{lang}
3505 Language-specific tests for any language @var{lang} besides C. Examples are
3506 @file{gdb.c++} and @file{gdb.java}.
3508 @item gdb.@var{platform}
3509 Non-portable tests. The tests are specific to a specific configuration
3510 (host or target), such as HP-UX or eCos. Example is @file{gdb.hp}, for
3513 @item gdb.@var{compiler}
3514 Tests specific to a particular compiler. As of this writing (June
3515 1999), there aren't currently any groups of tests in this category that
3516 couldn't just as sensibly be made platform-specific, but one could
3517 imagine a @file{gdb.gcc}, for tests of @value{GDBN}'s handling of GCC
3520 @item gdb.@var{subsystem}
3521 Tests that exercise a specific @value{GDBN} subsystem in more depth. For
3522 instance, @file{gdb.disasm} exercises various disassemblers, while
3523 @file{gdb.stabs} tests pathways through the stabs symbol reader.
3526 @section Writing Tests
3527 @cindex writing tests
3529 In many areas, the @value{GDBN} tests are already quite comprehensive; you
3530 should be able to copy existing tests to handle new cases.
3532 You should try to use @code{gdb_test} whenever possible, since it
3533 includes cases to handle all the unexpected errors that might happen.
3534 However, it doesn't cost anything to add new test procedures; for
3535 instance, @file{gdb.base/exprs.exp} defines a @code{test_expr} that
3536 calls @code{gdb_test} multiple times.
3538 Only use @code{send_gdb} and @code{gdb_expect} when absolutely
3539 necessary, such as when @value{GDBN} has several valid responses to a command.
3541 The source language programs do @emph{not} need to be in a consistent
3542 style. Since @value{GDBN} is used to debug programs written in many different
3543 styles, it's worth having a mix of styles in the testsuite; for
3544 instance, some @value{GDBN} bugs involving the display of source lines would
3545 never manifest themselves if the programs used GNU coding style
3552 Check the @file{README} file, it often has useful information that does not
3553 appear anywhere else in the directory.
3556 * Getting Started:: Getting started working on @value{GDBN}
3557 * Debugging GDB:: Debugging @value{GDBN} with itself
3560 @node Getting Started,,, Hints
3562 @section Getting Started
3564 @value{GDBN} is a large and complicated program, and if you first starting to
3565 work on it, it can be hard to know where to start. Fortunately, if you
3566 know how to go about it, there are ways to figure out what is going on.
3568 This manual, the @value{GDBN} Internals manual, has information which applies
3569 generally to many parts of @value{GDBN}.
3571 Information about particular functions or data structures are located in
3572 comments with those functions or data structures. If you run across a
3573 function or a global variable which does not have a comment correctly
3574 explaining what is does, this can be thought of as a bug in @value{GDBN}; feel
3575 free to submit a bug report, with a suggested comment if you can figure
3576 out what the comment should say. If you find a comment which is
3577 actually wrong, be especially sure to report that.
3579 Comments explaining the function of macros defined in host, target, or
3580 native dependent files can be in several places. Sometimes they are
3581 repeated every place the macro is defined. Sometimes they are where the
3582 macro is used. Sometimes there is a header file which supplies a
3583 default definition of the macro, and the comment is there. This manual
3584 also documents all the available macros.
3585 @c (@pxref{Host Conditionals}, @pxref{Target
3586 @c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete
3589 Start with the header files. Once you have some idea of how
3590 @value{GDBN}'s internal symbol tables are stored (see @file{symtab.h},
3591 @file{gdbtypes.h}), you will find it much easier to understand the
3592 code which uses and creates those symbol tables.
3594 You may wish to process the information you are getting somehow, to
3595 enhance your understanding of it. Summarize it, translate it to another
3596 language, add some (perhaps trivial or non-useful) feature to @value{GDBN}, use
3597 the code to predict what a test case would do and write the test case
3598 and verify your prediction, etc. If you are reading code and your eyes
3599 are starting to glaze over, this is a sign you need to use a more active
3602 Once you have a part of @value{GDBN} to start with, you can find more
3603 specifically the part you are looking for by stepping through each
3604 function with the @code{next} command. Do not use @code{step} or you
3605 will quickly get distracted; when the function you are stepping through
3606 calls another function try only to get a big-picture understanding
3607 (perhaps using the comment at the beginning of the function being
3608 called) of what it does. This way you can identify which of the
3609 functions being called by the function you are stepping through is the
3610 one which you are interested in. You may need to examine the data
3611 structures generated at each stage, with reference to the comments in
3612 the header files explaining what the data structures are supposed to
3615 Of course, this same technique can be used if you are just reading the
3616 code, rather than actually stepping through it. The same general
3617 principle applies---when the code you are looking at calls something
3618 else, just try to understand generally what the code being called does,
3619 rather than worrying about all its details.
3621 @cindex command implementation
3622 A good place to start when tracking down some particular area is with
3623 a command which invokes that feature. Suppose you want to know how
3624 single-stepping works. As a @value{GDBN} user, you know that the
3625 @code{step} command invokes single-stepping. The command is invoked
3626 via command tables (see @file{command.h}); by convention the function
3627 which actually performs the command is formed by taking the name of
3628 the command and adding @samp{_command}, or in the case of an
3629 @code{info} subcommand, @samp{_info}. For example, the @code{step}
3630 command invokes the @code{step_command} function and the @code{info
3631 display} command invokes @code{display_info}. When this convention is
3632 not followed, you might have to use @code{grep} or @kbd{M-x
3633 tags-search} in emacs, or run @value{GDBN} on itself and set a
3634 breakpoint in @code{execute_command}.
3636 @cindex @code{bug-gdb} mailing list
3637 If all of the above fail, it may be appropriate to ask for information
3638 on @code{bug-gdb}. But @emph{never} post a generic question like ``I was
3639 wondering if anyone could give me some tips about understanding
3640 @value{GDBN}''---if we had some magic secret we would put it in this manual.
3641 Suggestions for improving the manual are always welcome, of course.
3643 @node Debugging GDB,,,Hints
3645 @section Debugging @value{GDBN} with itself
3646 @cindex debugging @value{GDBN}
3648 If @value{GDBN} is limping on your machine, this is the preferred way to get it
3649 fully functional. Be warned that in some ancient Unix systems, like
3650 Ultrix 4.2, a program can't be running in one process while it is being
3651 debugged in another. Rather than typing the command @kbd{@w{./gdb
3652 ./gdb}}, which works on Suns and such, you can copy @file{gdb} to
3653 @file{gdb2} and then type @kbd{@w{./gdb ./gdb2}}.
3655 When you run @value{GDBN} in the @value{GDBN} source directory, it will read a
3656 @file{.gdbinit} file that sets up some simple things to make debugging
3657 gdb easier. The @code{info} command, when executed without a subcommand
3658 in a @value{GDBN} being debugged by gdb, will pop you back up to the top level
3659 gdb. See @file{.gdbinit} for details.
3661 If you use emacs, you will probably want to do a @code{make TAGS} after
3662 you configure your distribution; this will put the machine dependent
3663 routines for your local machine where they will be accessed first by
3666 Also, make sure that you've either compiled @value{GDBN} with your local cc, or
3667 have run @code{fixincludes} if you are compiling with gcc.
3669 @section Submitting Patches
3671 @cindex submitting patches
3672 Thanks for thinking of offering your changes back to the community of
3673 @value{GDBN} users. In general we like to get well designed enhancements.
3674 Thanks also for checking in advance about the best way to transfer the
3677 The @value{GDBN} maintainers will only install ``cleanly designed'' patches.
3678 This manual summarizes what we believe to be clean design for @value{GDBN}.
3680 If the maintainers don't have time to put the patch in when it arrives,
3681 or if there is any question about a patch, it goes into a large queue
3682 with everyone else's patches and bug reports.
3684 @cindex legal papers for code contributions
3685 The legal issue is that to incorporate substantial changes requires a
3686 copyright assignment from you and/or your employer, granting ownership
3687 of the changes to the Free Software Foundation. You can get the
3688 standard documents for doing this by sending mail to @code{gnu@@gnu.org}
3689 and asking for it. We recommend that people write in "All programs
3690 owned by the Free Software Foundation" as "NAME OF PROGRAM", so that
3691 changes in many programs (not just @value{GDBN}, but GAS, Emacs, GCC,
3693 contributed with only one piece of legalese pushed through the
3694 bureacracy and filed with the FSF. We can't start merging changes until
3695 this paperwork is received by the FSF (their rules, which we follow
3696 since we maintain it for them).
3698 Technically, the easiest way to receive changes is to receive each
3699 feature as a small context diff or unidiff, suitable for @code{patch}.
3700 Each message sent to me should include the changes to C code and
3701 header files for a single feature, plus @file{ChangeLog} entries for
3702 each directory where files were modified, and diffs for any changes
3703 needed to the manuals (@file{gdb/doc/gdb.texinfo} or
3704 @file{gdb/doc/gdbint.texinfo}). If there are a lot of changes for a
3705 single feature, they can be split down into multiple messages.
3707 In this way, if we read and like the feature, we can add it to the
3708 sources with a single patch command, do some testing, and check it in.
3709 If you leave out the @file{ChangeLog}, we have to write one. If you leave
3710 out the doc, we have to puzzle out what needs documenting. Etc., etc.
3712 The reason to send each change in a separate message is that we will not
3713 install some of the changes. They'll be returned to you with questions
3714 or comments. If we're doing our job correctly, the message back to you
3715 will say what you have to fix in order to make the change acceptable.
3716 The reason to have separate messages for separate features is so that
3717 the acceptable changes can be installed while one or more changes are
3718 being reworked. If multiple features are sent in a single message, we
3719 tend to not put in the effort to sort out the acceptable changes from
3720 the unacceptable, so none of the features get installed until all are
3723 If this sounds painful or authoritarian, well, it is. But we get a lot
3724 of bug reports and a lot of patches, and many of them don't get
3725 installed because we don't have the time to finish the job that the bug
3726 reporter or the contributor could have done. Patches that arrive
3727 complete, working, and well designed, tend to get installed on the day
3728 they arrive. The others go into a queue and get installed as time
3729 permits, which, since the maintainers have many demands to meet, may not
3730 be for quite some time.
3732 Please send patches directly to
3733 @email{gdb-patches@@sourceware.cygnus.com, the @value{GDBN} maintainers}.
3735 @section Obsolete Conditionals
3736 @cindex obsolete code
3738 Fragments of old code in @value{GDBN} sometimes reference or set the following
3739 configuration macros. They should not be used by new code, and old uses
3740 should be removed as those parts of the debugger are otherwise touched.
3743 @item STACK_END_ADDR
3744 This macro used to define where the end of the stack appeared, for use
3745 in interpreting core file formats that don't record this address in the
3746 core file itself. This information is now configured in BFD, and @value{GDBN}
3747 gets the info portably from there. The values in @value{GDBN}'s configuration
3748 files should be moved into BFD configuration files (if needed there),
3749 and deleted from all of @value{GDBN}'s config files.
3751 Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
3752 is so old that it has never been converted to use BFD. Now that's old!
3754 @item PYRAMID_CONTROL_FRAME_DEBUGGING
3758 @item PYRAMID_PTRACE
3761 @item REG_STACK_SEGMENT
3771 @c TeX can handle the contents at the start but makeinfo 3.12 can not