2 @setfilename gdbint.info
8 * Gdb-Internals: (gdbint). The GNU debugger's internals.
14 This file documents the internals of the GNU debugger GDB.
16 Copyright 1990, 1991, 1992 Free Software Foundation, Inc.
17 Contributed by Cygnus Support. Written by John Gilmore.
19 Permission is granted to make and distribute verbatim copies of
20 this manual provided the copyright notice and this permission notice
21 are 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
26 notice identical to this one except for the removal of this paragraph
27 (this paragraph not being relevant to the printed manual).
30 Permission is granted to copy or distribute modified versions of this
31 manual under the terms of the GPL (for which purpose this text may be
32 regarded as a program in the language TeX).
35 @setchapternewpage off
36 @settitle GDB Internals
38 @title{Working in GDB}
39 @subtitle{A guide to the internals of the GNU debugger}
41 @author Cygnus Support
44 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
45 \xdef\manvers{\$Revision$} % For use in headers, footers too
47 \hfill Cygnus Support\par
49 \hfill \TeX{}info \texinfoversion\par
53 @vskip 0pt plus 1filll
54 Copyright @copyright{} 1990, 1991, 1992 Free Software Foundation, Inc.
56 Permission is granted to make and distribute verbatim copies of
57 this manual provided the copyright notice and this permission notice
58 are preserved on all copies.
64 This documents the internals of the GNU debugger, GDB. It is a
65 collection of miscellaneous information with little form at this point.
66 Mostly, it is a repository into which you can put information about
67 GDB as you discover it (or as you design changes to GDB).
70 * README:: The README File
71 * New Architectures:: Defining a New Host or Target Architecture
72 * Config:: Adding a New Configuration
73 * Host:: Adding a New Host
74 * Native:: Adding a New Native Configuration
75 * Target:: Adding a New Target
76 * Languages:: Defining New Source Languages
77 * Releases:: Configuring GDB for Release
78 * Partial Symbol Tables:: How GDB reads symbols quickly at startup
79 * BFD support for GDB:: How BFD and GDB interface
80 * Symbol Reading:: Defining New Symbol Readers
82 * Wrapping:: Wrapping Output Lines
83 * Frames:: Keeping track of function calls
84 * Coding Style:: Strunk and White for GDB maintainers
85 * Clean Design:: Frank Lloyd Wright for GDB maintainers
86 * Submitting Patches:: How to get your changes into GDB releases
87 * Host Conditionals:: What features exist in the host
88 * Target Conditionals:: What features exist in the target
89 * Native Conditionals:: Conditionals for when host and target are same
90 * Obsolete Conditionals:: Conditionals that don't exist any more
95 @chapter The @file{README} File
97 Check the @file{README} file, it often has useful information that does not
98 appear anywhere else in the directory.
101 @node New Architectures
102 @chapter Defining a New Host or Target Architecture
104 When building support for a new host and/or target, much of the work you
105 need to do is handled by specifying configuration files;
106 @pxref{Config,,Adding a New Configuration}. Further work can be
107 divided into ``host-dependent'' (@pxref{Host,,Adding a New Host}) and
108 ``target-dependent'' (@pxref{Target,,Adding a New Target}). The
109 following discussion is meant to explain the difference between hosts
112 @heading What is considered ``host-dependent'' versus ``target-dependent''?
114 @dfn{Host} refers to attributes of the system where GDB runs.
115 @dfn{Target} refers to the system where the program being debugged
116 executes. In most cases they are the same machine, in which case
117 a third type of @dfn{Native} attributes come into play.
119 Defines and include files needed to build on the host are host support.
120 Examples are tty support, system defined types, host byte order, host
123 Defines and information needed to handle the target format are target
124 dependent. Examples are the stack frame format, instruction set,
125 breakpoint instruction, registers, and how to set up and tear down the stack
128 Information that is only needed when the host and target are the same,
129 is native dependent. One example is Unix child process support; if the
130 host and target are not the same, doing a fork to start the target
131 process is a bad idea. The various macros needed for finding the
132 registers in the @code{upage}, running @code{ptrace}, and such are all in the
133 native-dependent files.
135 Another example of native-dependent code is support for features
136 that are really part of the target environment, but which require
137 @code{#include} files that are only available on the host system.
138 Core file handling and @code{setjmp} handling are two common cases.
140 When you want to make GDB work ``native'' on a particular
141 machine, you have to include all three kinds of information.
143 The dependent information in GDB is organized into files by naming
149 Sets Makefile parameters
151 Global #include's and #define's and definitions
153 Global variables and functions
156 Native-Dependent Files
159 Sets Makefile parameters (for @emph{both} host and native)
161 #include's and #define's and definitions. This file
162 is only included by the small number of modules that need it,
163 so beware of doing feature-test #define's from its macros.
165 global variables and functions
168 Target-Dependent Files
171 Sets Makefile parameters
173 Global #include's and #define's and definitions
175 Global variables and functions
178 At this writing, most supported hosts have had their host and native
179 dependencies sorted out properly. There are a few stragglers, which
180 can be recognized by the absence of NATDEPFILES lines in their
184 @chapter Adding a New Configuration
186 Most of the work in making GDB compile on a new machine is in specifying
187 the configuration of the machine. This is done in a dizzying variety of
188 header files and configuration scripts, which we hope to make more
189 sensible soon. Let's say your new host is called an @var{xxx} (e.g.
190 @samp{sun4}), and its full three-part configuration name is
191 @code{@var{xarch}-@var{xvend}-@var{xos}} (e.g. @samp{sparc-sun-sunos4}). In
194 In the top level directory, edit @file{config.sub} and add @var{xarch},
195 @var{xvend}, and @var{xos} to the lists of supported architectures,
196 vendors, and operating systems near the bottom of the file. Also, add
197 @var{xxx} as an alias that maps to
198 @code{@var{xarch}-@var{xvend}-@var{xos}}. You can test your changes by
202 ./config.sub @var{xxx}
207 ./config.sub @code{@var{xarch}-@var{xvend}-@var{xos}}
210 which should both respond with @code{@var{xarch}-@var{xvend}-@var{xos}}
211 and no error messages.
213 Now, go to the @file{bfd} directory and
214 create a new file @file{bfd/hosts/h-@var{xxx}.h}. Examine the
215 other @file{h-*.h} files as templates, and create one that brings in the
216 right include files for your system, and defines any host-specific
217 macros needed by BFD, the Binutils, GNU LD, or the Opcodes directories.
218 (They all share the bfd @file{hosts} directory and the @file{configure.host}
221 Then edit @file{bfd/configure.host}. Add a line to recognize your
222 @code{@var{xarch}-@var{xvend}-@var{xos}} configuration, and set
223 @code{my_host} to @var{xxx} when you recognize it. This will cause your
224 file @file{h-@var{xxx}.h} to be linked to @file{sysdep.h} at configuration
225 time. When creating the line that recognizes your configuration,
226 only match the fields that you really need to match; e.g. don't match
227 match the architecture or manufacturer if the OS is sufficient
228 to distinguish the configuration that your @file{h-@var{xxx}.h} file supports.
229 Don't match the manufacturer name unless you really need to.
230 This should make future ports easier.
232 Also, if this host requires any changes to the Makefile, create a file
233 @file{bfd/config/@var{xxx}.mh}, which includes the required lines.
235 It's possible that the @file{libiberty} and @file{readline} directories
236 won't need any changes for your configuration, but if they do, you can
237 change the @file{configure.in} file there to recognize your system and
238 map to an @file{mh-@var{xxx}} file. Then add @file{mh-@var{xxx}}
239 to the @file{config/} subdirectory, to set any makefile variables you
240 need. The only current options in there are things like @samp{-DSYSV}.
241 (This @file{mh-@var{xxx}} naming convention differs from elsewhere
242 in GDB, by historical accident. It should be cleaned up so that all
243 such files are called @file{@var{xxx}.mh}.)
245 Aha! Now to configure GDB itself! Edit
246 @file{gdb/configure.in} to recognize your system and set @code{gdb_host}
247 to @var{xxx}, and (unless your desired target is already available) also
248 set @code{gdb_target} to something appropriate (for instance,
249 @var{xxx}). To handle new hosts, modify the segment after the comment
250 @samp{# per-host}; to handle new targets, modify after @samp{#
252 @c Would it be simpler to just use different per-host and per-target
253 @c *scripts*, and call them from {configure} ?
255 Finally, you'll need to specify and define GDB's host-, native-, and
256 target-dependent @file{.h} and @file{.c} files used for your
257 configuration; the next two chapters discuss those.
261 @chapter Adding a New Host
263 Once you have specified a new configuration for your host
264 (@pxref{Config,,Adding a New Configuration}), there are three remaining
265 pieces to making GDB work on a new machine. First, you have to make it
266 host on the new machine (compile there, handle that machine's terminals
267 properly, etc). If you will be cross-debugging to some other kind of
268 system that's already supported, you are done.
270 If you want to use GDB to debug programs that run on the new machine,
271 you have to get it to understand the machine's object files, symbol
272 files, and interfaces to processes; @pxref{Target,,Adding a New Target}
273 and @pxref{Native,,Adding a New Native Configuration}
275 Several files control GDB's configuration for host systems:
278 @item gdb/config/mh-@var{xxx}
279 Specifies Makefile fragments needed when hosting on machine @var{xxx}.
280 In particular, this lists the required machine-dependent object files,
281 by defining @samp{XDEPFILES=@dots{}}. Also
282 specifies the header file which describes host @var{xxx}, by defining
283 @samp{XM_FILE= xm-@var{xxx}.h}. You can also define @samp{CC},
284 @samp{REGEX} and @samp{REGEX1}, @samp{SYSV_DEFINE}, @samp{XM_CFLAGS},
285 @samp{XM_ADD_FILES}, @samp{XM_CLIBS}, @samp{XM_CDEPS},
286 etc.; see @file{Makefile.in}.
288 @item gdb/xm-@var{xxx}.h
289 (@file{xm.h} is a link to this file, created by configure).
290 Contains C macro definitions describing the host system environment,
291 such as byte order, host C compiler and library, ptrace support,
292 and core file structure. Crib from existing @file{xm-*.h} files
295 @item gdb/@var{xxx}-xdep.c
296 Contains any miscellaneous C code required for this machine
297 as a host. On many machines it doesn't exist at all. If it does
298 exist, put @file{@var{xxx}-xdep.o} into the @code{XDEPFILES} line
299 in @file{gdb/config/mh-@var{xxx}}.
302 @subheading Generic Host Support Files
304 There are some ``generic'' versions of routines that can be used by
305 various systems. These can be customized in various ways by macros
306 defined in your @file{xm-@var{xxx}.h} file. If these routines work for
307 the @var{xxx} host, you can just include the generic file's name (with
308 @samp{.o}, not @samp{.c}) in @code{XDEPFILES}.
310 Otherwise, if your machine needs custom support routines, you will need
311 to write routines that perform the same functions as the generic file.
312 Put them into @code{@var{xxx}-xdep.c}, and put @code{@var{xxx}-xdep.o}
313 into @code{XDEPFILES}.
317 This contains serial line support for Berkeley-derived Unix systems.
320 This contains serial line support for 32-bit programs running under DOS
321 using the GO32 execution environment.
324 This contains serial line support for System V-derived Unix systems.
327 Now, you are now ready to try configuring GDB to compile using your system
328 as its host. From the top level (above @file{bfd}, @file{gdb}, etc), do:
331 ./configure @var{xxx} +target=vxworks960
334 This will configure your system to cross-compile for VxWorks on
335 the Intel 960, which is probably not what you really want, but it's
336 a test case that works at this stage. (You haven't set up to be
337 able to debug programs that run @emph{on} @var{xxx} yet.)
339 If this succeeds, you can try building it all with:
345 Repeat until the program configures, compiles, links, and runs.
346 When run, it won't be able to do much (unless you have a VxWorks/960
347 board on your network) but you will know that the host support is
350 Good luck! Comments and suggestions about this section are particularly
351 welcome; send them to @samp{bug-gdb@@prep.ai.mit.edu}.
354 @chapter Adding a New Native Configuration
356 If you are making GDB run native on the @var{xxx} machine, you have
357 plenty more work to do. Several files control GDB's configuration for
361 @item gdb/config/@var{xxx}.mh
362 Specifies Makefile fragments needed when hosting @emph{or native}
363 on machine @var{xxx}.
364 In particular, this lists the required native-dependent object files,
365 by defining @samp{NATDEPFILES=@dots{}}. Also
366 specifies the header file which describes native support on @var{xxx},
367 by defining @samp{NM_FILE= nm-@var{xxx}.h}.
368 You can also define @samp{NAT_CFLAGS},
369 @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS}, @samp{NAT_CDEPS},
370 etc.; see @file{Makefile.in}.
372 @item gdb/nm-@var{xxx}.h
373 (@file{nm.h} is a link to this file, created by configure).
374 Contains C macro definitions describing the native system environment,
375 such as child process control and core file support.
376 Crib from existing @file{nm-*.h} files to create a new one.
378 @item gdb/@var{xxx}-nat.c
379 Contains any miscellaneous C code required for this native support
380 of this machine. On some machines it doesn't exist at all.
383 @subheading Generic Native Support Files
385 There are some ``generic'' versions of routines that can be used by
386 various systems. These can be customized in various ways by macros
387 defined in your @file{nm-@var{xxx}.h} file. If these routines work for
388 the @var{xxx} host, you can just include the generic file's name (with
389 @samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.
391 Otherwise, if your machine needs custom support routines, you will need
392 to write routines that perform the same functions as the generic file.
393 Put them into @code{@var{xxx}-nat.c}, and put @code{@var{xxx}-nat.o}
394 into @code{NATDEPFILES}.
399 This contains the @emph{target_ops vector} that supports Unix child
400 processes on systems which use ptrace and wait to control the child.
403 This contains the @emph{target_ops vector} that supports Unix child
404 processes on systems which use /proc to control the child.
407 This does the low-level grunge that uses Unix system calls
408 to do a "fork and exec" to start up a child process.
411 This is the low level interface to inferior processes for systems
412 using the Unix @code{ptrace} call in a vanilla way.
414 @item coredep.c::fetch_core_registers()
415 Support for reading registers out of a core file. This routine calls
416 @code{register_addr()}, see below.
417 Now that BFD is used to read core files, virtually all machines should
418 use @code{coredep.c}, and should just provide @code{fetch_core_registers} in
419 @code{@var{xxx}-nat.c} (or @code{REGISTER_U_ADDR} in @code{nm-@var{xxx}.h}).
421 @item coredep.c::register_addr()
422 If your @code{nm-@var{xxx}.h} file defines the macro
423 @code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
424 set @code{addr} to the offset within the @samp{user}
425 struct of GDB register number @code{regno}. @code{blockend} is the
426 offset within the ``upage'' of @code{u.u_ar0}.
427 If @code{REGISTER_U_ADDR} is defined,
428 @file{coredep.c} will define the @code{register_addr()} function and use
429 the macro in it. If you do not define @code{REGISTER_U_ADDR}, but you
430 are using the standard @code{fetch_core_registers()}, you will need to
431 define your own version of @code{register_addr()}, put it into your
432 @code{@var{xxx}-nat.c} file, and be sure @code{@var{xxx}-nat.o} is in
433 the @code{NATDEPFILES} list. If you have your own
434 @code{fetch_core_registers()}, you may not need a separate
435 @code{register_addr()}. Many custom @code{fetch_core_registers()}
436 implementations simply locate the registers themselves.@refill
439 When making GDB run native on a new operating system,
440 to make it possible to debug
441 core files, you will need to either write specific code for parsing your
442 OS's core files, or customize @file{bfd/trad-core.c}. First, use
443 whatever @code{#include} files your machine uses to define the struct of
444 registers that is accessible (possibly in the u-area) in a core file
445 (rather than @file{machine/reg.h}), and an include file that defines whatever
446 header exists on a core file (e.g. the u-area or a @samp{struct core}). Then
447 modify @code{trad_unix_core_file_p()} to use these values to set up the
448 section information for the data segment, stack segment, any other
449 segments in the core file (perhaps shared library contents or control
450 information), ``registers'' segment, and if there are two discontiguous
451 sets of registers (e.g. integer and float), the ``reg2'' segment. This
452 section information basically delimits areas in the core file in a
453 standard way, which the section-reading routines in BFD know how to seek
456 Then back in GDB, you need a matching routine called
457 @code{fetch_core_registers()}. If you can use the generic one, it's in
458 @file{coredep.c}; if not, it's in your @file{@var{xxx}-nat.c} file.
459 It will be passed a char pointer to the entire ``registers'' segment,
460 its length, and a zero; or a char pointer to the entire ``regs2''
461 segment, its length, and a 2. The routine should suck out the supplied
462 register values and install them into GDB's ``registers'' array.
463 (@xref{New Architectures,,Defining a New Host or Target Architecture},
464 for more info about this.)
466 If your system uses @file{/proc} to control processes, and uses ELF
467 format core files, then you may be able to use the same routines
468 for reading the registers out of processes and out of core files.
471 @chapter Adding a New Target
473 For a new target called @var{ttt}, first specify the configuration as
474 described in @ref{Config,,Adding a New Configuration}. If your new
475 target is the same as your new host, you've probably already done that.
477 A variety of files specify attributes of the GDB target environment:
480 @item gdb/config/@var{ttt}.mt
481 Contains a Makefile fragment specific to this target.
482 Specifies what object files are needed for target @var{ttt}, by
483 defining @samp{TDEPFILES=@dots{}}.
484 Also specifies the header file which describes @var{ttt}, by defining
485 @samp{TM_FILE= tm-@var{ttt}.h}. You can also define @samp{TM_CFLAGS},
486 @samp{TM_CLIBS}, @samp{TM_CDEPS},
487 and other Makefile variables here; see @file{Makefile.in}.
489 @item gdb/tm-@var{ttt}.h
490 (@file{tm.h} is a link to this file, created by configure).
491 Contains macro definitions about the target machine's
492 registers, stack frame format and instructions.
493 Crib from existing @file{tm-*.h} files when building a new one.
495 @item gdb/@var{ttt}-tdep.c
496 Contains any miscellaneous code required for this target machine.
497 On some machines it doesn't exist at all. Sometimes the macros
498 in @file{tm-@var{ttt}.h} become very complicated, so they are
499 implemented as functions here instead, and the macro is simply
500 defined to call the function.
503 Defines functions for accessing files that are
504 executable on the target system. These functions open and examine an
505 exec file, extract data from one, write data to one, print information
506 about one, etc. Now that executable files are handled with BFD, every
507 target should be able to use the generic exec.c rather than its
510 @item gdb/@var{arch}-pinsn.c
511 Prints (disassembles) the target machine's instructions.
512 This file is usually shared with other target machines which use the
513 same processor, which is why it is @file{@var{arch}-pinsn.c} rather
514 than @file{@var{ttt}-pinsn.c}.
516 @item gdb/@var{arch}-opcode.h
517 Contains some large initialized
518 data structures describing the target machine's instructions.
519 This is a bit strange for a @file{.h} file, but it's OK since
520 it is only included in one place. @file{@var{arch}-opcode.h} is shared
521 between the debugger and the assembler, if the GNU assembler has been
522 ported to the target machine.
524 @item gdb/tm-@var{arch}.h
525 This often exists to describe the basic layout of the target machine's
526 processor chip (registers, stack, etc).
527 If used, it is included by @file{tm-@var{xxx}.h}. It can
528 be shared among many targets that use the same processor.
530 @item gdb/@var{arch}-tdep.c
531 Similarly, there are often common subroutines that are shared by all
532 target machines that use this particular architecture.
535 When adding support for a new target machine, there are various areas
536 of support that might need change, or might be OK.
538 If you are using an existing object file format (a.out or COFF),
539 there is probably little to be done. See @file{bfd/doc/bfd.texinfo}
540 for more information on writing new a.out or COFF versions.
542 If you need to add a new object file format, you are beyond the scope
543 of this document right now. Look at the structure of the a.out
544 and COFF support, build a transfer vector (@code{xvec}) for your new format,
545 and start populating it with routines. Add it to the list in
546 @file{bfd/targets.c}.
548 If you are adding a new operating system for an existing CPU chip, add a
549 @file{tm-@var{xos}.h} file that describes the operating system
550 facilities that are unusual (extra symbol table info; the breakpoint
551 instruction needed; etc). Then write a
552 @file{tm-@var{xarch}-@var{xos}.h} that just @code{#include}s
553 @file{tm-@var{xarch}.h} and @file{tm-@var{xos}.h}. (Now that we have
554 three-part configuration names, this will probably get revised to
555 separate the @var{xos} configuration from the @var{xarch}
560 @chapter Adding a Source Language to GDB
562 To add other languages to GDB's expression parser, follow the following steps:
565 @item Create the expression parser.
567 This should reside in a file @file{@var{lang}-exp.y}. Routines for building
568 parsed expressions into a @samp{union exp_element} list are in @file{parse.c}.
570 Since we can't depend upon everyone having Bison, and YACC produces
571 parsers that define a bunch of global names, the following lines
572 @emph{must} be included at the top of the YACC parser, to prevent
573 the various parsers from defining the same global names:
576 #define yyparse @var{lang}_parse
577 #define yylex @var{lang}_lex
578 #define yyerror @var{lang}_error
579 #define yylval @var{lang}_lval
580 #define yychar @var{lang}_char
581 #define yydebug @var{lang}_debug
582 #define yypact @var{lang}_pact
583 #define yyr1 @var{lang}_r1
584 #define yyr2 @var{lang}_r2
585 #define yydef @var{lang}_def
586 #define yychk @var{lang}_chk
587 #define yypgo @var{lang}_pgo
588 #define yyact @var{lang}_act
589 #define yyexca @var{lang}_exca
590 #define yyerrflag @var{lang}_errflag
591 #define yynerrs @var{lang}_nerrs
594 At the bottom of your parser, define a @code{struct language_defn} and
595 initialize it with the right values for your language. Define an
596 @code{initialize_@var{lang}} routine and have it call
597 @samp{add_language(@var{lang}_language_defn)} to tell the rest of GDB
598 that your language exists. You'll need some other supporting variables
599 and functions, which will be used via pointers from your
600 @code{@var{lang}_language_defn}. See the declaration of @code{struct
601 language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
602 for more information.
604 @item Add any evaluation routines, if necessary
606 If you need new opcodes (that represent the operations of the language),
607 add them to the enumerated type in @file{expression.h}. Add support
608 code for these operations in @code{eval.c:evaluate_subexp()}. Add cases
609 for new opcodes in two functions from @file{parse.c}:
610 @code{prefixify_subexp()} and @code{length_of_subexp()}. These compute
611 the number of @code{exp_element}s that a given operation takes up.
613 @item Update some existing code
615 Add an enumerated identifier for your language to the enumerated type
616 @code{enum language} in @file{defs.h}.
618 Update the routines in @file{language.c} so your language is included. These
619 routines include type predicates and such, which (in some cases) are
620 language dependent. If your language does not appear in the switch
621 statement, an error is reported.
623 Also included in @file{language.c} is the code that updates the variable
624 @code{current_language}, and the routines that translate the
625 @code{language_@var{lang}} enumerated identifier into a printable
628 Update the function @code{_initialize_language} to include your language. This
629 function picks the default language upon startup, so is dependent upon
630 which languages that GDB is built for.
632 Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
633 code so that the language of each symtab (source file) is set properly.
634 This is used to determine the language to use at each stack frame level.
635 Currently, the language is set based upon the extension of the source
636 file. If the language can be better inferred from the symbol
637 information, please set the language of the symtab in the symbol-reading
640 Add helper code to @code{expprint.c:print_subexp()} to handle any new
641 expression opcodes you have added to @file{expression.h}. Also, add the
642 printed representations of your operators to @code{op_print_tab}.
644 @item Add a place of call
646 Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
647 @code{parse.c:parse_exp_1()}.
649 @item Use macros to trim code
651 The user has the option of building GDB for some or all of the
652 languages. If the user decides to build GDB for the language
653 @var{lang}, then every file dependent on @file{language.h} will have the
654 macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to
655 leave out large routines that the user won't need if he or she is not
658 Note that you do not need to do this in your YACC parser, since if GDB
659 is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
660 compiled form of your parser) is not linked into GDB at all.
662 See the file @file{configure.in} for how GDB is configured for different
665 @item Edit @file{Makefile.in}
667 Add dependencies in @file{Makefile.in}. Make sure you update the macro
668 variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
669 not get linked in, or, worse yet, it may not get @code{tar}red into the
675 @chapter Configuring GDB for Release
677 From the top level directory (containing @file{gdb}, @file{bfd},
678 @file{libiberty}, and so on):
680 make -f Makefile.in gdb.tar.Z
683 This will properly configure, clean, rebuild any files that are
684 distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}),
685 and will then make a tarfile. (If the top level directory has already
686 beenn configured, you can just do @code{make gdb.tar.Z} instead.)
688 This procedure requires:
691 @item @code{makeinfo} (texinfo2 level)
694 @item @code{yacc} or @code{bison}
697 @dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.).
699 @subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
701 @file{gdb.texinfo} is currently marked up using the texinfo-2 macros,
702 which are not yet a default for anything (but we have to start using
705 For making paper, the only thing this implies is the right generation of
706 @file{texinfo.tex} needs to be included in the distribution.
708 For making info files, however, rather than duplicating the texinfo2
709 distribution, generate @file{gdb-all.texinfo} locally, and include the files
710 @file{gdb.info*} in the distribution. Note the plural; @code{makeinfo} will
711 split the document into one overall file and five or so included files.
714 @node Partial Symbol Tables
715 @chapter Partial Symbol Tables
717 GDB has three types of symbol tables.
720 @item full symbol tables (symtabs). These contain the main
721 information about symbols and addresses.
722 @item partial symbol tables (psymtabs). These contain enough
723 information to know when to read the corresponding
724 part of the full symbol table.
725 @item minimal symbol tables (msymtabs). These contain information
726 gleaned from non-debugging symbols.
729 This section describes partial symbol tables.
731 A psymtab is constructed by doing a very quick pass over an executable
732 file's debugging information. Small amounts of information are
733 extracted -- enough to identify which parts of the symbol table will
734 need to be re-read and fully digested later, when the user needs the
735 information. The speed of this pass causes GDB to start up very
736 quickly. Later, as the detailed rereading occurs, it occurs in small
737 pieces, at various times, and the delay therefrom is mostly invisible to
738 the user. (@xref{Symbol Reading}.)
740 The symbols that show up in a file's psymtab should be, roughly, those
741 visible to the debugger's user when the program is not running code from
742 that file. These include external symbols and types, static
743 symbols and types, and enum values declared at file scope.
745 The psymtab also contains the range of instruction addresses that the
746 full symbol table would represent.
748 The idea is that there are only two ways for the user (or much of
749 the code in the debugger) to reference a symbol:
754 (e.g. execution stops at some address which is inside a function
755 in this file). The address will be noticed to be in the
756 range of this psymtab, and the full symtab will be read in.
757 @code{find_pc_function}, @code{find_pc_line}, and other @code{find_pc_@dots{}}
758 functions handle this.
761 (e.g. the user asks to print a variable, or set a breakpoint on a
762 function). Global names and file-scope names will be found in the
763 psymtab, which will cause the symtab to be pulled in. Local names will
764 have to be qualified by a global name, or a file-scope name, in which
765 case we will have already read in the symtab as we evaluated the
766 qualifier. Or, a local symbol can be referenced when
767 we are "in" a local scope, in which case the first case applies.
768 @code{lookup_symbol} does most of the work here.
772 The only reason that psymtabs exist is to cause a symtab to be read in
773 at the right moment. Any symbol that can be elided from a psymtab,
774 while still causing that to happen, should not appear in it. Since
775 psymtabs don't have the idea of scope, you can't put local symbols in
776 them anyway. Psymtabs don't have the idea of the type of a symbol,
777 either, so types need not appear, unless they will be referenced by
780 It is a bug for GDB to behave one way when only a psymtab has been read,
781 and another way if the corresponding symtab has been read in. Such
782 bugs are typically caused by a psymtab that does not contain all the
783 visible symbols, or which has the wrong instruction address ranges.
785 The psymtab for a particular section of a symbol-file (objfile)
786 could be thrown away after the symtab has been read in. The symtab
787 should always be searched before the psymtab, so the psymtab will
788 never be used (in a bug-free environment). Currently,
789 psymtabs are allocated on an obstack, and all the psymbols themselves
790 are allocated in a pair of large arrays on an obstack, so there is
791 little to be gained by trying to free them unless you want to do a lot
794 @node BFD support for GDB
795 @chapter Binary File Descriptor Library Support for GDB
797 BFD provides support for GDB in several ways:
800 @item identifying executable and core files
801 BFD will identify a variety of file types, including a.out, coff, and
802 several variants thereof, as well as several kinds of core files.
804 @item access to sections of files
805 BFD parses the file headers to determine the names, virtual addresses,
806 sizes, and file locations of all the various named sections in files
807 (such as the text section or the data section). GDB simply calls
808 BFD to read or write section X at byte offset Y for length Z.
810 @item specialized core file support
811 BFD provides routines to determine the failing command name stored
812 in a core file, the signal with which the program failed, and whether
813 a core file matches (i.e. could be a core dump of) a particular executable
816 @item locating the symbol information
817 GDB uses an internal interface of BFD to determine where to find the
818 symbol information in an executable file or symbol-file. GDB itself
819 handles the reading of symbols, since BFD does not ``understand'' debug
820 symbols, but GDB uses BFD's cached information to find the symbols,
824 @c The interface for symbol reading is described in @ref{Symbol
825 @c Reading,,Symbol Reading}.
829 @chapter Symbol Reading
831 GDB reads symbols from "symbol files". The usual symbol file is the
832 file containing the program which gdb is debugging. GDB can be directed
833 to use a different file for symbols (with the ``symbol-file''
834 command), and it can also read more symbols via the ``add-file'' and ``load''
835 commands, or while reading symbols from shared libraries.
837 Symbol files are initially opened by @file{symfile.c} using the BFD
838 library. BFD identifies the type of the file by examining its header.
839 @code{symfile_init} then uses this identification to locate a
840 set of symbol-reading functions.
842 Symbol reading modules identify themselves to GDB by calling
843 @code{add_symtab_fns} during their module initialization. The argument
844 to @code{add_symtab_fns} is a @code{struct sym_fns} which contains
845 the name (or name prefix) of the symbol format, the length of the prefix,
846 and pointers to four functions. These functions are called at various
847 times to process symbol-files whose identification matches the specified
850 The functions supplied by each module are:
853 @item @var{xxx}_symfile_init(struct sym_fns *sf)
855 Called from @code{symbol_file_add} when we are about to read a new
856 symbol file. This function should clean up any internal state
857 (possibly resulting from half-read previous files, for example)
858 and prepare to read a new symbol file. Note that the symbol file
859 which we are reading might be a new "main" symbol file, or might
860 be a secondary symbol file whose symbols are being added to the
861 existing symbol table.
863 The argument to @code{@var{xxx}_symfile_init} is a newly allocated
864 @code{struct sym_fns} whose @code{bfd} field contains the BFD
865 for the new symbol file being read. Its @code{private} field
866 has been zeroed, and can be modified as desired. Typically,
867 a struct of private information will be @code{malloc}'d, and
868 a pointer to it will be placed in the @code{private} field.
870 There is no result from @code{@var{xxx}_symfile_init}, but it can call
871 @code{error} if it detects an unavoidable problem.
873 @item @var{xxx}_new_init()
875 Called from @code{symbol_file_add} when discarding existing symbols.
876 This function need only handle
877 the symbol-reading module's internal state; the symbol table data
878 structures visible to the rest of GDB will be discarded by
879 @code{symbol_file_add}. It has no arguments and no result.
880 It may be called after @code{@var{xxx}_symfile_init}, if a new symbol
881 table is being read, or may be called alone if all symbols are
882 simply being discarded.
884 @item @var{xxx}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)
886 Called from @code{symbol_file_add} to actually read the symbols from a
887 symbol-file into a set of psymtabs or symtabs.
889 @code{sf} points to the struct sym_fns originally passed to
890 @code{@var{xxx}_sym_init} for possible initialization. @code{addr} is the
891 offset between the file's specified start address and its true address
892 in memory. @code{mainline} is 1 if this is the main symbol table being
893 read, and 0 if a secondary symbol file (e.g. shared library or
894 dynamically loaded file) is being read.@refill
897 In addition, if a symbol-reading module creates psymtabs when
898 @var{xxx}_symfile_read is called, these psymtabs will contain a pointer to
899 a function @code{@var{xxx}_psymtab_to_symtab}, which can be called from
900 any point in the GDB symbol-handling code.
903 @item @var{xxx}_psymtab_to_symtab (struct partial_symtab *pst)
905 Called from @code{psymtab_to_symtab} (or the PSYMTAB_TO_SYMTAB
906 macro) if the psymtab has not already been read in and had its
907 @code{pst->symtab} pointer set. The argument is the psymtab
908 to be fleshed-out into a symtab. Upon return, pst->readin
909 should have been set to 1, and pst->symtab should contain a
910 pointer to the new corresponding symtab, or zero if there
911 were no symbols in that part of the symbol file.
918 Cleanups are a structured way to deal with things that need to be done
919 later. When your code does something (like @code{malloc} some memory, or open
920 a file) that needs to be undone later (e.g. free the memory or close
921 the file), it can make a cleanup. The cleanup will be done at some
922 future point: when the command is finished, when an error occurs, or
923 when your code decides it's time to do cleanups.
925 You can also discard cleanups, that is, throw them away without doing
926 what they say. This is only done if you ask that it be done.
931 @item struct cleanup *@var{old_chain};
932 Declare a variable which will hold a cleanup chain handle.
934 @item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
935 Make a cleanup which will cause @var{function} to be called with @var{arg}
936 (a @code{char *}) later. The result, @var{old_chain}, is a handle that can be
937 passed to @code{do_cleanups} or @code{discard_cleanups} later. Unless you are
938 going to call @code{do_cleanups} or @code{discard_cleanups} yourself,
939 you can ignore the result from @code{make_cleanup}.
942 @item do_cleanups (@var{old_chain});
943 Perform all cleanups done since @code{make_cleanup} returned @var{old_chain}.
947 old = make_cleanup (b, 0);
951 will call @code{b()} but will not call @code{a()}. The cleanup that calls @code{a()} will remain
952 in the cleanup chain, and will be done later unless otherwise discarded.@refill
954 @item discard_cleanups (@var{old_chain});
955 Same as @code{do_cleanups} except that it just removes the cleanups from the
956 chain and does not call the specified functions.
960 Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify that they
961 ``should not be called when cleanups are not in place''. This means
962 that any actions you need to reverse in the case of an error or
963 interruption must be on the cleanup chain before you call these functions,
964 since they might never return to your code (they @samp{longjmp} instead).
968 @chapter Wrapping Output Lines
970 Output that goes through @code{printf_filtered} or @code{fputs_filtered} or
971 @code{fputs_demangled} needs only to have calls to @code{wrap_here} added
972 in places that would be good breaking points. The utility routines
973 will take care of actually wrapping if the line width is exceeded.
975 The argument to @code{wrap_here} is an indentation string which is printed
976 @emph{only} if the line breaks there. This argument is saved away and used
977 later. It must remain valid until the next call to @code{wrap_here} or
978 until a newline has been printed through the @code{*_filtered} functions.
979 Don't pass in a local variable and then return!
981 It is usually best to call @code{wrap_here()} after printing a comma or space.
982 If you call it before printing a space, make sure that your indentation
983 properly accounts for the leading space that will print if the line wraps
986 Any function or set of functions that produce filtered output must finish
987 by printing a newline, to flush the wrap buffer, before switching to
988 unfiltered (``@code{printf}'') output. Symbol reading routines that print
989 warnings are a good example.
995 A frame is a construct that GDB uses to keep track of calling and called
1000 in the machine description has no meaning to the machine-independent
1001 part of GDB, except that it is used when setting up a new frame from
1002 scratch, as follows:
1005 create_new_frame (read_register (FP_REGNUM), read_pc ()));
1008 Other than that, all the meaning imparted to @code{FP_REGNUM} is imparted by
1009 the machine-dependent code. So, @code{FP_REGNUM} can have any value that
1010 is convenient for the code that creates new frames. (@code{create_new_frame}
1011 calls @code{INIT_EXTRA_FRAME_INFO} if it is defined; that is where you should
1012 use the @code{FP_REGNUM} value, if your frames are nonstandard.)
1015 Given a GDB frame, determine the address of the calling function's
1016 frame. This will be used to create a new GDB frame struct, and then
1017 @code{INIT_EXTRA_FRAME_INFO} and @code{INIT_FRAME_PC} will be called for
1022 @chapter Coding Style
1024 GDB is generally written using the GNU coding standards, as described in
1025 @file{standards.texi}, which you can get from the Free Software
1026 Foundation. There are some additional considerations for GDB maintainers
1027 that reflect the unique environment and style of GDB maintenance.
1028 If you follow these guidelines, GDB will be more consistent and easier
1031 GDB's policy on the use of prototypes is that prototypes are used
1032 to @emph{declare} functions but never to @emph{define} them. Simple
1033 macros are used in the declarations, so that a non-ANSI compiler can
1034 compile GDB without trouble. The simple macro calls are used like
1039 memory_remove_breakpoint PARAMS ((CORE_ADDR, char *));
1042 Note the double parentheses around the parameter types. This allows
1043 an arbitrary number of parameters to be described, without freaking
1044 out the C preprocessor. When the function has no parameters, it
1045 should be described like:
1049 noprocess PARAMS ((void));
1052 The @code{PARAMS} macro expands to its argument in ANSI C, or to a simple
1053 @code{()} in traditional C.
1055 All external functions should have a @code{PARAMS} declaration in a
1056 header file that callers include. All static functions should have such
1057 a declaration near the top of their source file.
1059 We don't have a gcc option that will properly check that these rules
1060 have been followed, but it's GDB policy, and we periodically check it
1061 using the tools available (plus manual labor), and clean up any remnants.
1064 @chapter Clean Design
1066 In addition to getting the syntax right, there's the little question of
1067 semantics. Some things are done in certain ways in GDB because long
1068 experience has shown that the more obvious ways caused various kinds of
1069 trouble. In particular:
1073 You can't assume the byte order of anything that comes from a
1074 target (including @var{value}s, object files, and instructions). Such
1075 things must be byte-swapped using @code{SWAP_HOST_AND_TARGET} in GDB,
1076 or one of the swap routines defined in @file{bfd.h}, such as @code{bfd_get_32}.
1079 You can't assume that you know what interface is being used to talk to
1080 the target system. All references to the target must go through the
1081 current @code{target_ops} vector.
1084 You can't assume that the host and target machines are the same machine
1085 (except in the ``native'' support modules).
1086 In particular, you can't assume that the target machine's header files
1087 will be available on the host machine. Target code must bring along its
1088 own header files -- written from scratch or explicitly donated by their
1089 owner, to avoid copyright problems.
1092 Insertion of new @code{#ifdef}'s will be frowned upon.
1095 New @code{#ifdef}'s which test for specific compilers or manufacturers
1096 or operating systems are unacceptable. All @code{#ifdef}'s should test
1097 for features. The information about which configurations contain which
1098 features should be segregated into the configuration files. Experience
1099 has proven far too often that a feature unique to one particular system
1100 often creeps into other systems; and that a conditional based on
1101 some predefined macro for your current system will become worthless
1102 over time, as new versions of your system come out that behave differently
1103 with regard to this feature.
1106 Adding code that handles specific architectures, operating systems, target
1107 interfaces, or hosts, is not acceptable in generic code. If a hook
1108 is needed at that point, invent a generic hook and define it for your
1109 configuration, with something like:
1112 #ifdef WRANGLE_SIGNALS
1113 WRANGLE_SIGNALS (signo);
1117 In your host, target, or native configuration file, as appropriate,
1118 define @code{WRANGLE_SIGNALS} to do the machine-dependent thing. Take
1119 a bit of care in defining the hook, so that it can be used by other
1120 ports in the future, if they need a hook in the same place.
1123 @emph{Do} write code that doesn't depend on the sizes of C data types,
1124 the format of the host's floating point numbers, the alignment of anything,
1125 or the order of evaluation of expressions. In short, follow good
1126 programming practices for writing portable C code.
1130 @node Submitting Patches
1131 @chapter Submitting Patches
1133 Thanks for thinking of offering your changes back to the community of
1134 GDB users. In general we like to get well designed enhancements.
1135 Thanks also for checking in advance about the best way to transfer the
1138 The two main problems with getting your patches in are,
1142 The GDB maintainers will only install "cleanly designed" patches.
1143 You may not always agree on what is clean design.
1144 @pxref{Coding Style}, @pxref{Clean Design}.
1147 If the maintainers don't have time to put the patch in when it
1148 arrives, or if there is any question about a patch, it
1149 goes into a large queue with everyone else's patches and
1153 I don't know how to get past these problems except by continuing to try.
1155 There are two issues here -- technical and legal.
1157 The legal issue is that to incorporate substantial changes requires a
1158 copyright assignment from you and/or your employer, granting ownership of the changes to
1159 the Free Software Foundation. You can get the standard document for
1160 doing this by sending mail to @code{gnu@prep.ai.mit.edu} and asking for it.
1161 I recommend that people write in "All programs owned by the
1162 Free Software Foundation" as "NAME OF PROGRAM", so that changes in
1163 many programs (not just GDB, but GAS, Emacs, GCC, etc) can be
1164 contributed with only one piece of legalese pushed through the
1165 bureacracy and filed with the FSF. I can't start merging changes until
1166 this paperwork is received by the FSF (their rules, which I follow since
1167 I maintain it for them).
1169 Technically, the easiest way to receive changes is to receive each
1170 feature as a small context diff or unidiff, suitable for "patch".
1171 Each message sent to me should include the changes to C code and
1172 header files for a single feature, plus ChangeLog entries for each
1173 directory where files were modified, and diffs for any changes needed
1174 to the manuals (gdb/doc/gdb.texi or gdb/doc/gdbint.texi). If there
1175 are a lot of changes for a single feature, they can be split down
1176 into multiple messages.
1178 In this way, if I read and like the feature, I can add it to the
1179 sources with a single patch command, do some testing, and check it in.
1180 If you leave out the ChangeLog, I have to write one. If you leave
1181 out the doc, I have to puzzle out what needs documenting. Etc.
1183 The reason to send each change in a separate message is that I will
1184 not install some of the changes. They'll be returned to you with
1185 questions or comments. If I'm doing my job, my message back to you
1186 will say what you have to fix in order to make the change acceptable.
1187 The reason to have separate messages for separate features is so
1188 that other changes (which I @emph{am} willing to accept) can be installed
1189 while one or more changes are being reworked. If multiple features
1190 are sent in a single message, I tend to not put in the effort to sort
1191 out the acceptable changes from the unacceptable, so none of the
1192 features get installed until all are acceptable.
1194 If this sounds painful or authoritarian, well, it is. But I get a lot
1195 of bug reports and a lot of patches, and most of them don't get
1196 installed because I don't have the time to finish the job that the bug
1197 reporter or the contributor could have done. Patches that arrive
1198 complete, working, and well designed, tend to get installed on the day
1199 they arrive. The others go into a queue and get installed if and when
1200 I scan back over the queue -- which can literally take months
1201 sometimes. It's in both our interests to make patch installation easy
1202 -- you get your changes installed, and I make some forward progress on
1203 GDB in a normal 12-hour day (instead of them having to wait until I
1204 have a 14-hour or 16-hour day to spend cleaning up patches before I
1207 @node Host Conditionals
1208 @chapter Host Conditionals
1210 When GDB is configured and compiled, various macros are defined or left
1211 undefined, to control compilation based on the attributes of the host
1212 system. These macros and their meanings are:
1214 @emph{NOTE: For now, both host and target conditionals are here.
1215 Eliminate target conditionals from this list as they are identified.}
1220 @item BLOCK_ADDRESS_FUNCTION_RELATIVE
1222 @item GDBINIT_FILENAME
1226 @item MEM_FNS_DECLARED
1230 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1232 @item SIGWINCH_HANDLER_BODY
1250 @item ADDITIONAL_OPTIONS
1252 @item ADDITIONAL_OPTION_CASES
1254 @item ADDITIONAL_OPTION_HANDLER
1256 @item ADDITIONAL_OPTION_HELP
1258 @item ADDR_BITS_REMOVE
1260 @item AIX_BUGGY_PTRACE_CONTINUE
1262 @item ALIGN_STACK_ON_STARTUP
1274 @item BEFORE_MAIN_LOOP_HOOK
1276 @item BELIEVE_PCC_PROMOTION
1278 @item BELIEVE_PCC_PROMOTION_TYPE
1282 @item BITS_BIG_ENDIAN
1286 @item BLOCK_ADDRESS_ABSOLUTE
1292 @item BREAKPOINT_DEBUG
1294 @item BROKEN_LARGE_ALLOCA
1295 Avoid large @code{alloca}'s. For example, on sun's, Large alloca's fail
1296 because the attempt to increase the stack limit in main() fails because
1297 shared libraries are allocated just below the initial stack limit. The
1298 SunOS kernel will not allow the stack to grow into the area occupied by
1299 the shared libraries.
1304 @item CALL_DUMMY_LOCATION
1306 @item CALL_DUMMY_STACK_ADJUST
1308 @item CANNOT_FETCH_REGISTER
1310 @item CANNOT_STORE_REGISTER
1312 @item CFRONT_PRODUCER
1314 @item CHILD_PREPARE_TO_STORE
1316 @item CLEAR_DEFERRED_STORES
1320 @item COFF_ENCAPSULATE
1324 @item COFF_NO_LONG_FILE_NAMES
1326 @item CORE_NEEDS_RELOCATION
1330 @item CREATE_INFERIOR_HOOK
1340 @item DBX_PARM_SYMBOL_CLASS
1348 @item DECR_PC_AFTER_BREAK
1350 @item DEFAULT_PROMPT
1358 @item DISABLE_UNSETTABLE_BREAK
1360 @item DONT_USE_REMOTE
1362 @item DO_DEFERRED_STORES
1364 @item DO_REGISTERS_INFO
1366 @item END_OF_TEXT_DEFAULT
1370 @item EXTRACT_RETURN_VALUE
1372 @item EXTRACT_STRUCT_VALUE_ADDRESS
1374 @item EXTRA_FRAME_INFO
1376 @item EXTRA_SYMTAB_INFO
1378 @item FILES_INFO_HOOK
1392 @item FRAMELESS_FUNCTION_INVOCATION
1394 @item FRAME_ARGS_ADDRESS_CORRECT
1396 @item FRAME_CHAIN_COMBINE
1398 @item FRAME_CHAIN_VALID
1400 @item FRAME_CHAIN_VALID_ALTERNATE
1402 @item FRAME_FIND_SAVED_REGS
1404 @item FRAME_GET_BASEREG_VALUE
1406 @item FRAME_NUM_ARGS
1408 @item FRAME_SPECIFICATION_DYADIC
1410 @item FUNCTION_EPILOGUE_SIZE
1414 @item GCC2_COMPILED_FLAG_SYMBOL
1416 @item GCC_COMPILED_FLAG_SYMBOL
1418 @item GCC_MANGLE_BUG
1422 @item GET_SAVED_REGISTER
1424 @item GPLUS_PRODUCER
1435 In some cases, use the system call @code{mmap} for reading symbol
1436 tables. For some machines this allows for sharing and quick updates.
1437 @item HAVE_REGISTER_WINDOWS
1439 @item HAVE_SIGSETMASK
1443 @item HEADER_SEEK_FD
1447 @item HOST_BYTE_ORDER
1451 @item HPUX_VERSION_5
1459 @item IBM6000_TARGET
1467 @item INIT_EXTRA_FRAME_INFO
1469 @item INIT_EXTRA_SYMTAB_INFO
1483 @item IN_SOLIB_TRAMPOLINE
1487 @item IS_TRAPPED_INTERNALVAR
1491 @item KERNEL_DEBUGGING
1494 Define this to the address of the @code{u} structure (the ``user struct'',
1495 also known as the ``u-page'') in kernel virtual memory. GDB needs to know
1496 this so that it can subtract this address from absolute addresses in
1497 the upage, that are obtained via ptrace or from core files. On systems
1498 that don't need this value, set it to zero.
1499 @item KERNEL_U_ADDR_BSD
1500 Define this to cause GDB to determine the address of @code{u} at runtime,
1501 by using Berkeley-style @code{nlist} on the kernel's image in the root
1503 @item KERNEL_U_ADDR_HPUX
1504 Define this to cause GDB to determine the address of @code{u} at runtime,
1505 by using HP-style @code{nlist} on the kernel's image in the root
1521 @item LSEEK_NOT_LINEAR
1526 This macro is used as the argument to lseek (or, most commonly, bfd_seek).
1527 FIXME, it should be replaced by SEEK_SET instead, which is the POSIX equivalent.
1528 @item MACHKERNELDEBUG
1534 @item MAINTENANCE_CMDS
1536 @item MAINTENANCE_CMDS
1538 @item MALLOC_INCOMPATIBLE
1539 Define this if the system's prototype for @code{malloc} differs from the
1540 @sc{ANSI} definition.
1543 @item MMAP_BASE_ADDRESS
1544 When using HAVE_MMAP, the first mapping should go at this address.
1545 @item MMAP_INCREMENT
1546 when using HAVE_MMAP, this is the increment between mappings.
1551 @item NAMES_HAVE_UNDERSCORE
1555 @item NEED_POSIX_SETPGID
1557 @item NEED_TEXT_START_END
1571 @item NOTICE_SIGNAL_HANDLING_CHANGE
1573 @item NO_DEFINE_SYMBOL
1575 @item NO_HIF_SUPPORT
1577 @item NO_JOB_CONTROL
1579 @item NO_MALLOC_CHECK
1587 @item NO_SIGINTERRUPT
1589 @item NO_SINGLE_STEP
1597 @item NS32K_SVC_IMMED_OPERANDS
1599 @item NUMERIC_REG_NAMES
1607 @item ONE_PROCESS_WRITETEXT
1615 @item PCC_SOL_BROKEN
1617 @item PC_IN_CALL_DUMMY
1619 @item PC_LOAD_SEGMENT
1623 @item PRINT_RANDOM_SIGNAL
1625 @item PRINT_REGISTER_HOOK
1627 @item PRINT_TYPELESS_INTEGER
1629 @item PROCESS_LINENUMBER_HOOK
1631 @item PROLOGUE_FIRSTLINE_OVERLAP
1633 @item PSIGNAL_IN_SIGNAL_H
1637 @item PTRACE_ARG3_TYPE
1647 @item PUSH_ARGUMENTS
1649 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1653 @item PYRAMID_PTRACE
1655 @item REGISTER_BYTES
1657 @item REGISTER_NAMES
1659 @item REG_STACK_SEGMENT
1661 @item REG_STRUCT_HAS_ADDR
1669 @item SDB_REG_TO_REGNUM
1677 @item SET_STACK_LIMIT_HUGE
1678 When defined, stack limits will be raised to their maximum. Use this
1679 if your host supports @code{setrlimit} and you have trouble with
1680 @code{stringtab} in @file{dbxread.c}.
1682 Also used in @file{fork-child.c} to return stack limits before child
1683 processes are forked.
1684 @item SHELL_COMMAND_CONCAT
1688 @item SHIFT_INST_REGS
1690 @item SIGN_EXTEND_CHAR
1692 @item SIGTRAP_STOP_AFTER_LOAD
1696 @item SKIP_PROLOGUE_FRAMELESS_P
1698 @item SKIP_TRAMPOLINE_CODE
1702 @item SOLIB_CREATE_INFERIOR_HOOK
1704 @item SOME_NAMES_HAVE_DOT
1708 @item STAB_REG_TO_REGNUM
1712 @item STACK_DIRECTION
1714 @item START_INFERIOR_TRAPS_EXPECTED
1718 @item STORE_RETURN_VALUE
1720 @item SUN4_COMPILER_FEATURE
1722 @item SUN_FIXED_LBRAC_BUG
1724 @item SVR4_SHARED_LIBS
1726 @item SWITCH_ENUM_BUG
1730 @item SYMBOL_RELOADING_DEFAULT
1750 @item TM_FILE_OVERRIDE
1766 @item USE_STRUCT_CONVENTION
1769 Means that System V (prior to SVR4) include files are in use.
1770 (FIXME: This symbol is abused in @file{infrun.c}, @file{regex.c},
1771 @file{remote-nindy.c}, and @file{utils.c} for other things, at the moment.)
1776 @item VARIABLES_INSIDE_BLOCK
1788 @item __HAVE_68881__
1792 @item __INT_VARARGS_H
1794 @item __not_on_pyr_yet
1810 @item longest_to_int
1840 @node Target Conditionals
1841 @chapter Target Conditionals
1843 When GDB is configured and compiled, various macros are defined or left
1844 undefined, to control compilation based on the attributes of the target
1845 system. These macros and their meanings are:
1847 @emph{NOTE: For now, both host and target conditionals are here.
1848 Eliminate host conditionals from this list as they are identified.}
1851 @item PUSH_DUMMY_FRAME
1852 Used in @samp{call_function_by_hand} to create an artificial stack frame.
1854 Used in @samp{call_function_by_hand} to remove an artificial stack frame.
1857 @item BLOCK_ADDRESS_FUNCTION_RELATIVE
1859 @item GDBINIT_FILENAME
1863 @item MEM_FNS_DECLARED
1867 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1869 @item SIGWINCH_HANDLER_BODY
1871 @item ADDITIONAL_OPTIONS
1873 @item ADDITIONAL_OPTION_CASES
1875 @item ADDITIONAL_OPTION_HANDLER
1877 @item ADDITIONAL_OPTION_HELP
1879 @item ADDR_BITS_REMOVE
1881 @item ALIGN_STACK_ON_STARTUP
1893 @item BEFORE_MAIN_LOOP_HOOK
1895 @item BELIEVE_PCC_PROMOTION
1897 @item BELIEVE_PCC_PROMOTION_TYPE
1901 @item BITS_BIG_ENDIAN
1905 @item BLOCK_ADDRESS_ABSOLUTE
1911 @item BREAKPOINT_DEBUG
1917 @item CALL_DUMMY_LOCATION
1919 @item CALL_DUMMY_STACK_ADJUST
1921 @item CANNOT_FETCH_REGISTER
1923 @item CANNOT_STORE_REGISTER
1925 @item CFRONT_PRODUCER
1927 @item CHILD_PREPARE_TO_STORE
1929 @item CLEAR_DEFERRED_STORES
1933 @item COFF_ENCAPSULATE
1937 @item COFF_NO_LONG_FILE_NAMES
1939 @item CORE_NEEDS_RELOCATION
1943 @item CREATE_INFERIOR_HOOK
1953 @item DBX_PARM_SYMBOL_CLASS
1961 @item DECR_PC_AFTER_BREAK
1963 @item DEFAULT_PROMPT
1971 @item DISABLE_UNSETTABLE_BREAK
1973 @item DONT_USE_REMOTE
1975 @item DO_DEFERRED_STORES
1977 @item DO_REGISTERS_INFO
1979 @item END_OF_TEXT_DEFAULT
1983 @item EXTRACT_RETURN_VALUE
1985 @item EXTRACT_STRUCT_VALUE_ADDRESS
1987 @item EXTRA_FRAME_INFO
1989 @item EXTRA_SYMTAB_INFO
1991 @item FILES_INFO_HOOK
2006 Unused? 6-oct-92 rich@@cygnus.com. FIXME.
2007 @item FRAMELESS_FUNCTION_INVOCATION
2009 @item FRAME_ARGS_ADDRESS_CORRECT
2011 @item FRAME_CHAIN_COMBINE
2013 @item FRAME_CHAIN_VALID
2015 @item FRAME_CHAIN_VALID_ALTERNATE
2017 @item FRAME_FIND_SAVED_REGS
2019 @item FRAME_GET_BASEREG_VALUE
2021 @item FRAME_NUM_ARGS
2023 @item FRAME_SPECIFICATION_DYADIC
2025 @item FUNCTION_EPILOGUE_SIZE
2029 @item GCC2_COMPILED_FLAG_SYMBOL
2031 @item GCC_COMPILED_FLAG_SYMBOL
2033 @item GCC_MANGLE_BUG
2037 @item GDB_TARGET_IS_HPPA
2038 This determines whether horrible kludge code in dbxread.c and partial-stab.h
2039 is used to mangle multiple-symbol-table files from HPPA's. This should all
2040 be ripped out, and a scheme like elfread.c used.
2041 @item GDB_TARGET_IS_MACH386
2043 @item GDB_TARGET_IS_SUN3
2045 @item GDB_TARGET_IS_SUN386
2047 @item GET_LONGJMP_TARGET
2048 For most machines, this is a target-dependent parameter. On the DECstation
2049 and the Iris, this is a native-dependent parameter, since <setjmp.h> is
2050 needed to define it.
2052 This macro determines the target PC address that longjmp() will jump
2053 to, assuming that we have just stopped at a longjmp breakpoint. It
2054 takes a CORE_ADDR * as argument, and stores the target PC value through
2055 this pointer. It examines the current state of the machine as needed.
2056 @item GET_SAVED_REGISTER
2058 @item GPLUS_PRODUCER
2068 @item HAVE_REGISTER_WINDOWS
2070 @item HAVE_SIGSETMASK
2074 @item HEADER_SEEK_FD
2078 @item HOST_BYTE_ORDER
2082 @item HPUX_VERSION_5
2090 @item IBM6000_TARGET
2098 @item INIT_EXTRA_FRAME_INFO
2100 @item INIT_EXTRA_SYMTAB_INFO
2114 @item IN_SOLIB_TRAMPOLINE
2118 @item IS_TRAPPED_INTERNALVAR
2122 @item KERNEL_DEBUGGING
2140 @item MACHKERNELDEBUG
2146 @item MAINTENANCE_CMDS
2148 @item MAINTENANCE_CMDS
2154 @item NAMES_HAVE_UNDERSCORE
2158 @item NEED_POSIX_SETPGID
2160 @item NEED_TEXT_START_END
2174 @item NOTICE_SIGNAL_HANDLING_CHANGE
2176 @item NO_DEFINE_SYMBOL
2178 @item NO_HIF_SUPPORT
2180 @item NO_JOB_CONTROL
2182 @item NO_MALLOC_CHECK
2190 @item NO_SIGINTERRUPT
2192 @item NO_SINGLE_STEP
2200 @item NS32K_SVC_IMMED_OPERANDS
2202 @item NUMERIC_REG_NAMES
2210 @item ONE_PROCESS_WRITETEXT
2214 @item PCC_SOL_BROKEN
2216 @item PC_IN_CALL_DUMMY
2218 @item PC_LOAD_SEGMENT
2222 @item PRINT_RANDOM_SIGNAL
2224 @item PRINT_REGISTER_HOOK
2226 @item PRINT_TYPELESS_INTEGER
2228 @item PROCESS_LINENUMBER_HOOK
2230 @item PROLOGUE_FIRSTLINE_OVERLAP
2232 @item PSIGNAL_IN_SIGNAL_H
2236 @item PTRACE_ARG3_TYPE
2240 @item PUSH_ARGUMENTS
2242 @item REGISTER_BYTES
2244 @item REGISTER_NAMES
2246 @item REG_STACK_SEGMENT
2248 @item REG_STRUCT_HAS_ADDR
2256 @item SDB_REG_TO_REGNUM
2264 @item SET_STACK_LIMIT_HUGE
2266 @item SHELL_COMMAND_CONCAT
2270 @item SHIFT_INST_REGS
2272 @item SIGN_EXTEND_CHAR
2274 @item SIGTRAP_STOP_AFTER_LOAD
2278 @item SKIP_PROLOGUE_FRAMELESS_P
2280 @item SKIP_TRAMPOLINE_CODE
2284 @item SOLIB_CREATE_INFERIOR_HOOK
2286 @item SOME_NAMES_HAVE_DOT
2290 @item STAB_REG_TO_REGNUM
2294 @item STACK_DIRECTION
2296 @item START_INFERIOR_TRAPS_EXPECTED
2300 @item STORE_RETURN_VALUE
2302 @item SUN4_COMPILER_FEATURE
2304 @item SUN_FIXED_LBRAC_BUG
2306 @item SVR4_SHARED_LIBS
2308 @item SWITCH_ENUM_BUG
2312 @item SYMBOL_RELOADING_DEFAULT
2318 @item TARGET_BYTE_ORDER
2320 @item TARGET_CHAR_BIT
2322 @item TARGET_COMPLEX_BIT
2324 @item TARGET_DOUBLE_BIT
2326 @item TARGET_DOUBLE_COMPLEX_BIT
2328 @item TARGET_FLOAT_BIT
2330 @item TARGET_INT_BIT
2332 @item TARGET_LONG_BIT
2334 @item TARGET_LONG_DOUBLE_BIT
2336 @item TARGET_LONG_LONG_BIT
2338 @item TARGET_PTR_BIT
2340 @item TARGET_SHORT_BIT
2344 @item TM_FILE_OVERRIDE
2356 @item USE_STRUCT_CONVENTION
2362 @item VARIABLES_INSIDE_BLOCK
2372 @item __HAVE_68881__
2376 @item __INT_VARARGS_H
2378 @item __not_on_pyr_yet
2388 @item longest_to_int
2412 @node Native Conditionals
2413 @chapter Native Conditionals
2415 When GDB is configured and compiled, various macros are defined or left
2416 undefined, to control compilation when the host and target systems
2417 are the same. These macros should be defined (or left undefined)
2418 in @file{nm-@var{system}.h}.
2422 If defined, then gdb will include support for the @code{attach} and
2423 @code{detach} commands.
2424 @item FETCH_INFERIOR_REGISTERS
2425 Define this if the native-dependent code will provide its
2427 @code{fetch_inferior_registers} and @code{store_inferior_registers} in
2428 @file{@var{HOST}-nat.c}.
2429 If this symbol is @emph{not} defined, and @file{infptrace.c}
2430 is included in this configuration, the default routines in
2431 @file{infptrace.c} are used for these functions.
2432 @item GET_LONGJMP_TARGET
2433 For most machines, this is a target-dependent parameter. On the DECstation
2434 and the Iris, this is a native-dependent parameter, since <setjmp.h> is
2435 needed to define it.
2437 This macro determines the target PC address that longjmp() will jump
2438 to, assuming that we have just stopped at a longjmp breakpoint. It
2439 takes a CORE_ADDR * as argument, and stores the target PC value through
2440 this pointer. It examines the current state of the machine as needed.
2442 Defines the format for the name of a @file{/proc} device. Should be
2443 defined in @file{nm.h} @emph{only} in order to override the default
2444 definition in @file{procfs.c}.
2445 @item REGISTER_U_ADDR
2446 Defines the offset of the registers in the ``u area''; @pxref{Host}.
2448 This determines whether small routines in @file{*-tdep.c}, which
2449 translate register values
2450 between GDB's internal representation and the /proc representation,
2453 This is the offset of the registers in the upage. It need only be
2454 defined if the generic ptrace register access routines in
2455 @file{infptrace.c} are being used (that is,
2456 @file{infptrace.c} is configured in, and
2457 @code{FETCH_INFERIOR_REGISTERS} is not defined). If the default value
2458 from @file{infptrace.c} is good enough, leave it undefined.
2460 The default value means that u.u_ar0 @emph{points to} the location of the
2461 registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means that
2462 u.u_ar0 @emph{is} the location of the registers.
2465 @node Obsolete Conditionals
2466 @chapter Obsolete Conditionals
2468 Fragments of old code in GDB sometimes reference or set the following
2469 configuration macros. They should not be used by new code, and
2470 old uses should be removed as those parts of the debugger are
2474 @item STACK_END_ADDR
2475 This macro used to define where the end of the stack appeared, for use
2476 in interpreting core file formats that don't record this address in the
2477 core file itself. This information is now configured in BFD, and GDB
2478 gets the info portably from there. The values in GDB's configuration
2479 files should be moved into BFD configuration files (if needed there),
2480 and deleted from all of GDB's config files.
2482 Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
2483 is so old that it has never been converted to use BFD. Now that's old!