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 * Remote Stubs:: Code that runs in targets and talks to GDB
85 * Coding Style:: Strunk and White for GDB maintainers
86 * Clean Design:: Frank Lloyd Wright for GDB maintainers
87 * Submitting Patches:: How to get your changes into GDB releases
88 * Host Conditionals:: What features exist in the host
89 * Target Conditionals:: What features exist in the target
90 * Native Conditionals:: Conditionals for when host and target are same
91 * Obsolete Conditionals:: Conditionals that don't exist any more
96 @chapter The @file{README} File
98 Check the @file{README} file, it often has useful information that does not
99 appear anywhere else in the directory.
102 @node New Architectures
103 @chapter Defining a New Host or Target Architecture
105 When building support for a new host and/or target, much of the work you
106 need to do is handled by specifying configuration files;
107 @pxref{Config,,Adding a New Configuration}. Further work can be
108 divided into ``host-dependent'' (@pxref{Host,,Adding a New Host}) and
109 ``target-dependent'' (@pxref{Target,,Adding a New Target}). The
110 following discussion is meant to explain the difference between hosts
113 @heading What is considered ``host-dependent'' versus ``target-dependent''?
115 @dfn{Host} refers to attributes of the system where GDB runs.
116 @dfn{Target} refers to the system where the program being debugged
117 executes. In most cases they are the same machine, in which case
118 a third type of @dfn{Native} attributes come into play.
120 Defines and include files needed to build on the host are host support.
121 Examples are tty support, system defined types, host byte order, host
124 Defines and information needed to handle the target format are target
125 dependent. Examples are the stack frame format, instruction set,
126 breakpoint instruction, registers, and how to set up and tear down the stack
129 Information that is only needed when the host and target are the same,
130 is native dependent. One example is Unix child process support; if the
131 host and target are not the same, doing a fork to start the target
132 process is a bad idea. The various macros needed for finding the
133 registers in the @code{upage}, running @code{ptrace}, and such are all in the
134 native-dependent files.
136 Another example of native-dependent code is support for features
137 that are really part of the target environment, but which require
138 @code{#include} files that are only available on the host system.
139 Core file handling and @code{setjmp} handling are two common cases.
141 When you want to make GDB work ``native'' on a particular
142 machine, you have to include all three kinds of information.
144 The dependent information in GDB is organized into files by naming
150 Sets Makefile parameters
152 Global #include's and #define's and definitions
154 Global variables and functions
157 Native-Dependent Files
160 Sets Makefile parameters (for @emph{both} host and native)
162 #include's and #define's and definitions. This file
163 is only included by the small number of modules that need it,
164 so beware of doing feature-test #define's from its macros.
166 global variables and functions
169 Target-Dependent Files
172 Sets Makefile parameters
174 Global #include's and #define's and definitions
176 Global variables and functions
179 At this writing, most supported hosts have had their host and native
180 dependencies sorted out properly. There are a few stragglers, which
181 can be recognized by the absence of NATDEPFILES lines in their
185 @chapter Adding a New Configuration
187 Most of the work in making GDB compile on a new machine is in specifying
188 the configuration of the machine. This is done in a dizzying variety of
189 header files and configuration scripts, which we hope to make more
190 sensible soon. Let's say your new host is called an @var{xxx} (e.g.
191 @samp{sun4}), and its full three-part configuration name is
192 @code{@var{xarch}-@var{xvend}-@var{xos}} (e.g. @samp{sparc-sun-sunos4}). In
195 In the top level directory, edit @file{config.sub} and add @var{xarch},
196 @var{xvend}, and @var{xos} to the lists of supported architectures,
197 vendors, and operating systems near the bottom of the file. Also, add
198 @var{xxx} as an alias that maps to
199 @code{@var{xarch}-@var{xvend}-@var{xos}}. You can test your changes by
203 ./config.sub @var{xxx}
208 ./config.sub @code{@var{xarch}-@var{xvend}-@var{xos}}
211 which should both respond with @code{@var{xarch}-@var{xvend}-@var{xos}}
212 and no error messages.
214 Now, go to the @file{bfd} directory and
215 create a new file @file{bfd/hosts/h-@var{xxx}.h}. Examine the
216 other @file{h-*.h} files as templates, and create one that brings in the
217 right include files for your system, and defines any host-specific
218 macros needed by BFD, the Binutils, GNU LD, or the Opcodes directories.
219 (They all share the bfd @file{hosts} directory and the @file{configure.host}
222 Then edit @file{bfd/configure.host}. Add a line to recognize your
223 @code{@var{xarch}-@var{xvend}-@var{xos}} configuration, and set
224 @code{my_host} to @var{xxx} when you recognize it. This will cause your
225 file @file{h-@var{xxx}.h} to be linked to @file{sysdep.h} at configuration
226 time. When creating the line that recognizes your configuration,
227 only match the fields that you really need to match; e.g. don't match
228 match the architecture or manufacturer if the OS is sufficient
229 to distinguish the configuration that your @file{h-@var{xxx}.h} file supports.
230 Don't match the manufacturer name unless you really need to.
231 This should make future ports easier.
233 Also, if this host requires any changes to the Makefile, create a file
234 @file{bfd/config/@var{xxx}.mh}, which includes the required lines.
236 It's possible that the @file{libiberty} and @file{readline} directories
237 won't need any changes for your configuration, but if they do, you can
238 change the @file{configure.in} file there to recognize your system and
239 map to an @file{mh-@var{xxx}} file. Then add @file{mh-@var{xxx}}
240 to the @file{config/} subdirectory, to set any makefile variables you
241 need. The only current options in there are things like @samp{-DSYSV}.
242 (This @file{mh-@var{xxx}} naming convention differs from elsewhere
243 in GDB, by historical accident. It should be cleaned up so that all
244 such files are called @file{@var{xxx}.mh}.)
246 Aha! Now to configure GDB itself! Edit
247 @file{gdb/configure.in} to recognize your system and set @code{gdb_host}
248 to @var{xxx}, and (unless your desired target is already available) also
249 set @code{gdb_target} to something appropriate (for instance,
250 @var{xxx}). To handle new hosts, modify the segment after the comment
251 @samp{# per-host}; to handle new targets, modify after @samp{#
253 @c Would it be simpler to just use different per-host and per-target
254 @c *scripts*, and call them from {configure} ?
256 Finally, you'll need to specify and define GDB's host-, native-, and
257 target-dependent @file{.h} and @file{.c} files used for your
258 configuration; the next two chapters discuss those.
262 @chapter Adding a New Host
264 Once you have specified a new configuration for your host
265 (@pxref{Config,,Adding a New Configuration}), there are three remaining
266 pieces to making GDB work on a new machine. First, you have to make it
267 host on the new machine (compile there, handle that machine's terminals
268 properly, etc). If you will be cross-debugging to some other kind of
269 system that's already supported, you are done.
271 If you want to use GDB to debug programs that run on the new machine,
272 you have to get it to understand the machine's object files, symbol
273 files, and interfaces to processes; @pxref{Target,,Adding a New Target}
274 and @pxref{Native,,Adding a New Native Configuration}
276 Several files control GDB's configuration for host systems:
279 @item gdb/config/mh-@var{xxx}
280 Specifies Makefile fragments needed when hosting on machine @var{xxx}.
281 In particular, this lists the required machine-dependent object files,
282 by defining @samp{XDEPFILES=@dots{}}. Also
283 specifies the header file which describes host @var{xxx}, by defining
284 @samp{XM_FILE= xm-@var{xxx}.h}. You can also define @samp{CC},
285 @samp{REGEX} and @samp{REGEX1}, @samp{SYSV_DEFINE}, @samp{XM_CFLAGS},
286 @samp{XM_ADD_FILES}, @samp{XM_CLIBS}, @samp{XM_CDEPS},
287 etc.; see @file{Makefile.in}.
289 @item gdb/xm-@var{xxx}.h
290 (@file{xm.h} is a link to this file, created by configure).
291 Contains C macro definitions describing the host system environment,
292 such as byte order, host C compiler and library, ptrace support,
293 and core file structure. Crib from existing @file{xm-*.h} files
296 @item gdb/@var{xxx}-xdep.c
297 Contains any miscellaneous C code required for this machine
298 as a host. On many machines it doesn't exist at all. If it does
299 exist, put @file{@var{xxx}-xdep.o} into the @code{XDEPFILES} line
300 in @file{gdb/config/mh-@var{xxx}}.
303 @subheading Generic Host Support Files
305 There are some ``generic'' versions of routines that can be used by
306 various systems. These can be customized in various ways by macros
307 defined in your @file{xm-@var{xxx}.h} file. If these routines work for
308 the @var{xxx} host, you can just include the generic file's name (with
309 @samp{.o}, not @samp{.c}) in @code{XDEPFILES}.
311 Otherwise, if your machine needs custom support routines, you will need
312 to write routines that perform the same functions as the generic file.
313 Put them into @code{@var{xxx}-xdep.c}, and put @code{@var{xxx}-xdep.o}
314 into @code{XDEPFILES}.
318 This contains serial line support for Berkeley-derived Unix systems.
321 This contains serial line support for 32-bit programs running under DOS
322 using the GO32 execution environment.
325 This contains serial line support for System V-derived Unix systems.
328 Now, you are now ready to try configuring GDB to compile using your system
329 as its host. From the top level (above @file{bfd}, @file{gdb}, etc), do:
332 ./configure @var{xxx} +target=vxworks960
335 This will configure your system to cross-compile for VxWorks on
336 the Intel 960, which is probably not what you really want, but it's
337 a test case that works at this stage. (You haven't set up to be
338 able to debug programs that run @emph{on} @var{xxx} yet.)
340 If this succeeds, you can try building it all with:
346 Repeat until the program configures, compiles, links, and runs.
347 When run, it won't be able to do much (unless you have a VxWorks/960
348 board on your network) but you will know that the host support is
351 Good luck! Comments and suggestions about this section are particularly
352 welcome; send them to @samp{bug-gdb@@prep.ai.mit.edu}.
355 @chapter Adding a New Native Configuration
357 If you are making GDB run native on the @var{xxx} machine, you have
358 plenty more work to do. Several files control GDB's configuration for
362 @item gdb/config/@var{xxx}.mh
363 Specifies Makefile fragments needed when hosting @emph{or native}
364 on machine @var{xxx}.
365 In particular, this lists the required native-dependent object files,
366 by defining @samp{NATDEPFILES=@dots{}}. Also
367 specifies the header file which describes native support on @var{xxx},
368 by defining @samp{NM_FILE= nm-@var{xxx}.h}.
369 You can also define @samp{NAT_CFLAGS},
370 @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS}, @samp{NAT_CDEPS},
371 etc.; see @file{Makefile.in}.
373 @item gdb/nm-@var{xxx}.h
374 (@file{nm.h} is a link to this file, created by configure).
375 Contains C macro definitions describing the native system environment,
376 such as child process control and core file support.
377 Crib from existing @file{nm-*.h} files to create a new one.
379 @item gdb/@var{xxx}-nat.c
380 Contains any miscellaneous C code required for this native support
381 of this machine. On some machines it doesn't exist at all.
384 @subheading Generic Native Support Files
386 There are some ``generic'' versions of routines that can be used by
387 various systems. These can be customized in various ways by macros
388 defined in your @file{nm-@var{xxx}.h} file. If these routines work for
389 the @var{xxx} host, you can just include the generic file's name (with
390 @samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.
392 Otherwise, if your machine needs custom support routines, you will need
393 to write routines that perform the same functions as the generic file.
394 Put them into @code{@var{xxx}-nat.c}, and put @code{@var{xxx}-nat.o}
395 into @code{NATDEPFILES}.
400 This contains the @emph{target_ops vector} that supports Unix child
401 processes on systems which use ptrace and wait to control the child.
404 This contains the @emph{target_ops vector} that supports Unix child
405 processes on systems which use /proc to control the child.
408 This does the low-level grunge that uses Unix system calls
409 to do a "fork and exec" to start up a child process.
412 This is the low level interface to inferior processes for systems
413 using the Unix @code{ptrace} call in a vanilla way.
415 @item coredep.c::fetch_core_registers()
416 Support for reading registers out of a core file. This routine calls
417 @code{register_addr()}, see below.
418 Now that BFD is used to read core files, virtually all machines should
419 use @code{coredep.c}, and should just provide @code{fetch_core_registers} in
420 @code{@var{xxx}-nat.c} (or @code{REGISTER_U_ADDR} in @code{nm-@var{xxx}.h}).
422 @item coredep.c::register_addr()
423 If your @code{nm-@var{xxx}.h} file defines the macro
424 @code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
425 set @code{addr} to the offset within the @samp{user}
426 struct of GDB register number @code{regno}. @code{blockend} is the
427 offset within the ``upage'' of @code{u.u_ar0}.
428 If @code{REGISTER_U_ADDR} is defined,
429 @file{coredep.c} will define the @code{register_addr()} function and use
430 the macro in it. If you do not define @code{REGISTER_U_ADDR}, but you
431 are using the standard @code{fetch_core_registers()}, you will need to
432 define your own version of @code{register_addr()}, put it into your
433 @code{@var{xxx}-nat.c} file, and be sure @code{@var{xxx}-nat.o} is in
434 the @code{NATDEPFILES} list. If you have your own
435 @code{fetch_core_registers()}, you may not need a separate
436 @code{register_addr()}. Many custom @code{fetch_core_registers()}
437 implementations simply locate the registers themselves.@refill
440 When making GDB run native on a new operating system,
441 to make it possible to debug
442 core files, you will need to either write specific code for parsing your
443 OS's core files, or customize @file{bfd/trad-core.c}. First, use
444 whatever @code{#include} files your machine uses to define the struct of
445 registers that is accessible (possibly in the u-area) in a core file
446 (rather than @file{machine/reg.h}), and an include file that defines whatever
447 header exists on a core file (e.g. the u-area or a @samp{struct core}). Then
448 modify @code{trad_unix_core_file_p()} to use these values to set up the
449 section information for the data segment, stack segment, any other
450 segments in the core file (perhaps shared library contents or control
451 information), ``registers'' segment, and if there are two discontiguous
452 sets of registers (e.g. integer and float), the ``reg2'' segment. This
453 section information basically delimits areas in the core file in a
454 standard way, which the section-reading routines in BFD know how to seek
457 Then back in GDB, you need a matching routine called
458 @code{fetch_core_registers()}. If you can use the generic one, it's in
459 @file{coredep.c}; if not, it's in your @file{@var{xxx}-nat.c} file.
460 It will be passed a char pointer to the entire ``registers'' segment,
461 its length, and a zero; or a char pointer to the entire ``regs2''
462 segment, its length, and a 2. The routine should suck out the supplied
463 register values and install them into GDB's ``registers'' array.
464 (@xref{New Architectures,,Defining a New Host or Target Architecture},
465 for more info about this.)
467 If your system uses @file{/proc} to control processes, and uses ELF
468 format core files, then you may be able to use the same routines
469 for reading the registers out of processes and out of core files.
472 @chapter Adding a New Target
474 For a new target called @var{ttt}, first specify the configuration as
475 described in @ref{Config,,Adding a New Configuration}. If your new
476 target is the same as your new host, you've probably already done that.
478 A variety of files specify attributes of the GDB target environment:
481 @item gdb/config/@var{ttt}.mt
482 Contains a Makefile fragment specific to this target.
483 Specifies what object files are needed for target @var{ttt}, by
484 defining @samp{TDEPFILES=@dots{}}.
485 Also specifies the header file which describes @var{ttt}, by defining
486 @samp{TM_FILE= tm-@var{ttt}.h}. You can also define @samp{TM_CFLAGS},
487 @samp{TM_CLIBS}, @samp{TM_CDEPS},
488 and other Makefile variables here; see @file{Makefile.in}.
490 @item gdb/tm-@var{ttt}.h
491 (@file{tm.h} is a link to this file, created by configure).
492 Contains macro definitions about the target machine's
493 registers, stack frame format and instructions.
494 Crib from existing @file{tm-*.h} files when building a new one.
496 @item gdb/@var{ttt}-tdep.c
497 Contains any miscellaneous code required for this target machine.
498 On some machines it doesn't exist at all. Sometimes the macros
499 in @file{tm-@var{ttt}.h} become very complicated, so they are
500 implemented as functions here instead, and the macro is simply
501 defined to call the function.
504 Defines functions for accessing files that are
505 executable on the target system. These functions open and examine an
506 exec file, extract data from one, write data to one, print information
507 about one, etc. Now that executable files are handled with BFD, every
508 target should be able to use the generic exec.c rather than its
511 @item gdb/@var{arch}-pinsn.c
512 Prints (disassembles) the target machine's instructions.
513 This file is usually shared with other target machines which use the
514 same processor, which is why it is @file{@var{arch}-pinsn.c} rather
515 than @file{@var{ttt}-pinsn.c}.
517 @item gdb/@var{arch}-opcode.h
518 Contains some large initialized
519 data structures describing the target machine's instructions.
520 This is a bit strange for a @file{.h} file, but it's OK since
521 it is only included in one place. @file{@var{arch}-opcode.h} is shared
522 between the debugger and the assembler, if the GNU assembler has been
523 ported to the target machine.
525 @item gdb/tm-@var{arch}.h
526 This often exists to describe the basic layout of the target machine's
527 processor chip (registers, stack, etc).
528 If used, it is included by @file{tm-@var{xxx}.h}. It can
529 be shared among many targets that use the same processor.
531 @item gdb/@var{arch}-tdep.c
532 Similarly, there are often common subroutines that are shared by all
533 target machines that use this particular architecture.
536 When adding support for a new target machine, there are various areas
537 of support that might need change, or might be OK.
539 If you are using an existing object file format (a.out or COFF),
540 there is probably little to be done. See @file{bfd/doc/bfd.texinfo}
541 for more information on writing new a.out or COFF versions.
543 If you need to add a new object file format, you must first add it to
544 BFD. This is beyond the scope of this document right now. Basically
545 you must build a transfer vector (of type @code{bfd_target}), which will
546 mean writing all the required routines, and add it to the list in
547 @file{bfd/targets.c}.
549 You must then arrange for the BFD code to provide access to the
550 debugging symbols. Generally GDB will have to call swapping routines
551 from BFD and a few other BFD internal routines to locate the debugging
552 information. As much as possible, GDB should not depend on the BFD
553 internal data structures.
555 For some targets (e.g., COFF), there is a special transfer vector used
556 to call swapping routines, since the external data structures on various
557 platforms have different sizes and layouts. Specialized routines that
558 will only ever be implemented by one object file format may be called
559 directly. This interface should be described in a file
560 @file{bfd/libxxx.h}, which is included by GDB.
562 If you are adding a new operating system for an existing CPU chip, add a
563 @file{tm-@var{xos}.h} file that describes the operating system
564 facilities that are unusual (extra symbol table info; the breakpoint
565 instruction needed; etc). Then write a
566 @file{tm-@var{xarch}-@var{xos}.h} that just @code{#include}s
567 @file{tm-@var{xarch}.h} and @file{tm-@var{xos}.h}. (Now that we have
568 three-part configuration names, this will probably get revised to
569 separate the @var{xos} configuration from the @var{xarch}
574 @chapter Adding a Source Language to GDB
576 To add other languages to GDB's expression parser, follow the following steps:
579 @item Create the expression parser.
581 This should reside in a file @file{@var{lang}-exp.y}. Routines for building
582 parsed expressions into a @samp{union exp_element} list are in @file{parse.c}.
584 Since we can't depend upon everyone having Bison, and YACC produces
585 parsers that define a bunch of global names, the following lines
586 @emph{must} be included at the top of the YACC parser, to prevent
587 the various parsers from defining the same global names:
590 #define yyparse @var{lang}_parse
591 #define yylex @var{lang}_lex
592 #define yyerror @var{lang}_error
593 #define yylval @var{lang}_lval
594 #define yychar @var{lang}_char
595 #define yydebug @var{lang}_debug
596 #define yypact @var{lang}_pact
597 #define yyr1 @var{lang}_r1
598 #define yyr2 @var{lang}_r2
599 #define yydef @var{lang}_def
600 #define yychk @var{lang}_chk
601 #define yypgo @var{lang}_pgo
602 #define yyact @var{lang}_act
603 #define yyexca @var{lang}_exca
604 #define yyerrflag @var{lang}_errflag
605 #define yynerrs @var{lang}_nerrs
608 At the bottom of your parser, define a @code{struct language_defn} and
609 initialize it with the right values for your language. Define an
610 @code{initialize_@var{lang}} routine and have it call
611 @samp{add_language(@var{lang}_language_defn)} to tell the rest of GDB
612 that your language exists. You'll need some other supporting variables
613 and functions, which will be used via pointers from your
614 @code{@var{lang}_language_defn}. See the declaration of @code{struct
615 language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
616 for more information.
618 @item Add any evaluation routines, if necessary
620 If you need new opcodes (that represent the operations of the language),
621 add them to the enumerated type in @file{expression.h}. Add support
622 code for these operations in @code{eval.c:evaluate_subexp()}. Add cases
623 for new opcodes in two functions from @file{parse.c}:
624 @code{prefixify_subexp()} and @code{length_of_subexp()}. These compute
625 the number of @code{exp_element}s that a given operation takes up.
627 @item Update some existing code
629 Add an enumerated identifier for your language to the enumerated type
630 @code{enum language} in @file{defs.h}.
632 Update the routines in @file{language.c} so your language is included. These
633 routines include type predicates and such, which (in some cases) are
634 language dependent. If your language does not appear in the switch
635 statement, an error is reported.
637 Also included in @file{language.c} is the code that updates the variable
638 @code{current_language}, and the routines that translate the
639 @code{language_@var{lang}} enumerated identifier into a printable
642 Update the function @code{_initialize_language} to include your language. This
643 function picks the default language upon startup, so is dependent upon
644 which languages that GDB is built for.
646 Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
647 code so that the language of each symtab (source file) is set properly.
648 This is used to determine the language to use at each stack frame level.
649 Currently, the language is set based upon the extension of the source
650 file. If the language can be better inferred from the symbol
651 information, please set the language of the symtab in the symbol-reading
654 Add helper code to @code{expprint.c:print_subexp()} to handle any new
655 expression opcodes you have added to @file{expression.h}. Also, add the
656 printed representations of your operators to @code{op_print_tab}.
658 @item Add a place of call
660 Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
661 @code{parse.c:parse_exp_1()}.
663 @item Use macros to trim code
665 The user has the option of building GDB for some or all of the
666 languages. If the user decides to build GDB for the language
667 @var{lang}, then every file dependent on @file{language.h} will have the
668 macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to
669 leave out large routines that the user won't need if he or she is not
672 Note that you do not need to do this in your YACC parser, since if GDB
673 is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
674 compiled form of your parser) is not linked into GDB at all.
676 See the file @file{configure.in} for how GDB is configured for different
679 @item Edit @file{Makefile.in}
681 Add dependencies in @file{Makefile.in}. Make sure you update the macro
682 variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
683 not get linked in, or, worse yet, it may not get @code{tar}red into the
689 @chapter Configuring GDB for Release
691 From the top level directory (containing @file{gdb}, @file{bfd},
692 @file{libiberty}, and so on):
694 make -f Makefile.in gdb.tar.Z
697 This will properly configure, clean, rebuild any files that are
698 distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}),
699 and will then make a tarfile. (If the top level directory has already
700 beenn configured, you can just do @code{make gdb.tar.Z} instead.)
702 This procedure requires:
705 @item @code{makeinfo} (texinfo2 level)
708 @item @code{yacc} or @code{bison}
711 @dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.).
713 @subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
715 @file{gdb.texinfo} is currently marked up using the texinfo-2 macros,
716 which are not yet a default for anything (but we have to start using
719 For making paper, the only thing this implies is the right generation of
720 @file{texinfo.tex} needs to be included in the distribution.
722 For making info files, however, rather than duplicating the texinfo2
723 distribution, generate @file{gdb-all.texinfo} locally, and include the files
724 @file{gdb.info*} in the distribution. Note the plural; @code{makeinfo} will
725 split the document into one overall file and five or so included files.
728 @node Partial Symbol Tables
729 @chapter Partial Symbol Tables
731 GDB has three types of symbol tables.
734 @item full symbol tables (symtabs). These contain the main
735 information about symbols and addresses.
736 @item partial symbol tables (psymtabs). These contain enough
737 information to know when to read the corresponding
738 part of the full symbol table.
739 @item minimal symbol tables (msymtabs). These contain information
740 gleaned from non-debugging symbols.
743 This section describes partial symbol tables.
745 A psymtab is constructed by doing a very quick pass over an executable
746 file's debugging information. Small amounts of information are
747 extracted -- enough to identify which parts of the symbol table will
748 need to be re-read and fully digested later, when the user needs the
749 information. The speed of this pass causes GDB to start up very
750 quickly. Later, as the detailed rereading occurs, it occurs in small
751 pieces, at various times, and the delay therefrom is mostly invisible to
752 the user. (@xref{Symbol Reading}.)
754 The symbols that show up in a file's psymtab should be, roughly, those
755 visible to the debugger's user when the program is not running code from
756 that file. These include external symbols and types, static
757 symbols and types, and enum values declared at file scope.
759 The psymtab also contains the range of instruction addresses that the
760 full symbol table would represent.
762 The idea is that there are only two ways for the user (or much of
763 the code in the debugger) to reference a symbol:
768 (e.g. execution stops at some address which is inside a function
769 in this file). The address will be noticed to be in the
770 range of this psymtab, and the full symtab will be read in.
771 @code{find_pc_function}, @code{find_pc_line}, and other @code{find_pc_@dots{}}
772 functions handle this.
775 (e.g. the user asks to print a variable, or set a breakpoint on a
776 function). Global names and file-scope names will be found in the
777 psymtab, which will cause the symtab to be pulled in. Local names will
778 have to be qualified by a global name, or a file-scope name, in which
779 case we will have already read in the symtab as we evaluated the
780 qualifier. Or, a local symbol can be referenced when
781 we are "in" a local scope, in which case the first case applies.
782 @code{lookup_symbol} does most of the work here.
786 The only reason that psymtabs exist is to cause a symtab to be read in
787 at the right moment. Any symbol that can be elided from a psymtab,
788 while still causing that to happen, should not appear in it. Since
789 psymtabs don't have the idea of scope, you can't put local symbols in
790 them anyway. Psymtabs don't have the idea of the type of a symbol,
791 either, so types need not appear, unless they will be referenced by
794 It is a bug for GDB to behave one way when only a psymtab has been read,
795 and another way if the corresponding symtab has been read in. Such
796 bugs are typically caused by a psymtab that does not contain all the
797 visible symbols, or which has the wrong instruction address ranges.
799 The psymtab for a particular section of a symbol-file (objfile)
800 could be thrown away after the symtab has been read in. The symtab
801 should always be searched before the psymtab, so the psymtab will
802 never be used (in a bug-free environment). Currently,
803 psymtabs are allocated on an obstack, and all the psymbols themselves
804 are allocated in a pair of large arrays on an obstack, so there is
805 little to be gained by trying to free them unless you want to do a lot
808 @node BFD support for GDB
809 @chapter Binary File Descriptor Library Support for GDB
811 BFD provides support for GDB in several ways:
814 @item identifying executable and core files
815 BFD will identify a variety of file types, including a.out, coff, and
816 several variants thereof, as well as several kinds of core files.
818 @item access to sections of files
819 BFD parses the file headers to determine the names, virtual addresses,
820 sizes, and file locations of all the various named sections in files
821 (such as the text section or the data section). GDB simply calls
822 BFD to read or write section X at byte offset Y for length Z.
824 @item specialized core file support
825 BFD provides routines to determine the failing command name stored
826 in a core file, the signal with which the program failed, and whether
827 a core file matches (i.e. could be a core dump of) a particular executable
830 @item locating the symbol information
831 GDB uses an internal interface of BFD to determine where to find the
832 symbol information in an executable file or symbol-file. GDB itself
833 handles the reading of symbols, since BFD does not ``understand'' debug
834 symbols, but GDB uses BFD's cached information to find the symbols,
838 @c The interface for symbol reading is described in @ref{Symbol
839 @c Reading,,Symbol Reading}.
843 @chapter Symbol Reading
845 GDB reads symbols from "symbol files". The usual symbol file is the
846 file containing the program which gdb is debugging. GDB can be directed
847 to use a different file for symbols (with the ``symbol-file''
848 command), and it can also read more symbols via the ``add-file'' and ``load''
849 commands, or while reading symbols from shared libraries.
851 Symbol files are initially opened by @file{symfile.c} using the BFD
852 library. BFD identifies the type of the file by examining its header.
853 @code{symfile_init} then uses this identification to locate a
854 set of symbol-reading functions.
856 Symbol reading modules identify themselves to GDB by calling
857 @code{add_symtab_fns} during their module initialization. The argument
858 to @code{add_symtab_fns} is a @code{struct sym_fns} which contains
859 the name (or name prefix) of the symbol format, the length of the prefix,
860 and pointers to four functions. These functions are called at various
861 times to process symbol-files whose identification matches the specified
864 The functions supplied by each module are:
867 @item @var{xxx}_symfile_init(struct sym_fns *sf)
869 Called from @code{symbol_file_add} when we are about to read a new
870 symbol file. This function should clean up any internal state
871 (possibly resulting from half-read previous files, for example)
872 and prepare to read a new symbol file. Note that the symbol file
873 which we are reading might be a new "main" symbol file, or might
874 be a secondary symbol file whose symbols are being added to the
875 existing symbol table.
877 The argument to @code{@var{xxx}_symfile_init} is a newly allocated
878 @code{struct sym_fns} whose @code{bfd} field contains the BFD
879 for the new symbol file being read. Its @code{private} field
880 has been zeroed, and can be modified as desired. Typically,
881 a struct of private information will be @code{malloc}'d, and
882 a pointer to it will be placed in the @code{private} field.
884 There is no result from @code{@var{xxx}_symfile_init}, but it can call
885 @code{error} if it detects an unavoidable problem.
887 @item @var{xxx}_new_init()
889 Called from @code{symbol_file_add} when discarding existing symbols.
890 This function need only handle
891 the symbol-reading module's internal state; the symbol table data
892 structures visible to the rest of GDB will be discarded by
893 @code{symbol_file_add}. It has no arguments and no result.
894 It may be called after @code{@var{xxx}_symfile_init}, if a new symbol
895 table is being read, or may be called alone if all symbols are
896 simply being discarded.
898 @item @var{xxx}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)
900 Called from @code{symbol_file_add} to actually read the symbols from a
901 symbol-file into a set of psymtabs or symtabs.
903 @code{sf} points to the struct sym_fns originally passed to
904 @code{@var{xxx}_sym_init} for possible initialization. @code{addr} is the
905 offset between the file's specified start address and its true address
906 in memory. @code{mainline} is 1 if this is the main symbol table being
907 read, and 0 if a secondary symbol file (e.g. shared library or
908 dynamically loaded file) is being read.@refill
911 In addition, if a symbol-reading module creates psymtabs when
912 @var{xxx}_symfile_read is called, these psymtabs will contain a pointer to
913 a function @code{@var{xxx}_psymtab_to_symtab}, which can be called from
914 any point in the GDB symbol-handling code.
917 @item @var{xxx}_psymtab_to_symtab (struct partial_symtab *pst)
919 Called from @code{psymtab_to_symtab} (or the PSYMTAB_TO_SYMTAB
920 macro) if the psymtab has not already been read in and had its
921 @code{pst->symtab} pointer set. The argument is the psymtab
922 to be fleshed-out into a symtab. Upon return, pst->readin
923 should have been set to 1, and pst->symtab should contain a
924 pointer to the new corresponding symtab, or zero if there
925 were no symbols in that part of the symbol file.
932 Cleanups are a structured way to deal with things that need to be done
933 later. When your code does something (like @code{malloc} some memory, or open
934 a file) that needs to be undone later (e.g. free the memory or close
935 the file), it can make a cleanup. The cleanup will be done at some
936 future point: when the command is finished, when an error occurs, or
937 when your code decides it's time to do cleanups.
939 You can also discard cleanups, that is, throw them away without doing
940 what they say. This is only done if you ask that it be done.
945 @item struct cleanup *@var{old_chain};
946 Declare a variable which will hold a cleanup chain handle.
948 @item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
949 Make a cleanup which will cause @var{function} to be called with @var{arg}
950 (a @code{char *}) later. The result, @var{old_chain}, is a handle that can be
951 passed to @code{do_cleanups} or @code{discard_cleanups} later. Unless you are
952 going to call @code{do_cleanups} or @code{discard_cleanups} yourself,
953 you can ignore the result from @code{make_cleanup}.
956 @item do_cleanups (@var{old_chain});
957 Perform all cleanups done since @code{make_cleanup} returned @var{old_chain}.
961 old = make_cleanup (b, 0);
965 will call @code{b()} but will not call @code{a()}. The cleanup that calls @code{a()} will remain
966 in the cleanup chain, and will be done later unless otherwise discarded.@refill
968 @item discard_cleanups (@var{old_chain});
969 Same as @code{do_cleanups} except that it just removes the cleanups from the
970 chain and does not call the specified functions.
974 Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify that they
975 ``should not be called when cleanups are not in place''. This means
976 that any actions you need to reverse in the case of an error or
977 interruption must be on the cleanup chain before you call these functions,
978 since they might never return to your code (they @samp{longjmp} instead).
982 @chapter Wrapping Output Lines
984 Output that goes through @code{printf_filtered} or @code{fputs_filtered} or
985 @code{fputs_demangled} needs only to have calls to @code{wrap_here} added
986 in places that would be good breaking points. The utility routines
987 will take care of actually wrapping if the line width is exceeded.
989 The argument to @code{wrap_here} is an indentation string which is printed
990 @emph{only} if the line breaks there. This argument is saved away and used
991 later. It must remain valid until the next call to @code{wrap_here} or
992 until a newline has been printed through the @code{*_filtered} functions.
993 Don't pass in a local variable and then return!
995 It is usually best to call @code{wrap_here()} after printing a comma or space.
996 If you call it before printing a space, make sure that your indentation
997 properly accounts for the leading space that will print if the line wraps
1000 Any function or set of functions that produce filtered output must finish
1001 by printing a newline, to flush the wrap buffer, before switching to
1002 unfiltered (``@code{printf}'') output. Symbol reading routines that print
1003 warnings are a good example.
1009 A frame is a construct that GDB uses to keep track of calling and called
1014 in the machine description has no meaning to the machine-independent
1015 part of GDB, except that it is used when setting up a new frame from
1016 scratch, as follows:
1019 create_new_frame (read_register (FP_REGNUM), read_pc ()));
1022 Other than that, all the meaning imparted to @code{FP_REGNUM} is imparted by
1023 the machine-dependent code. So, @code{FP_REGNUM} can have any value that
1024 is convenient for the code that creates new frames. (@code{create_new_frame}
1025 calls @code{INIT_EXTRA_FRAME_INFO} if it is defined; that is where you should
1026 use the @code{FP_REGNUM} value, if your frames are nonstandard.)
1029 Given a GDB frame, determine the address of the calling function's
1030 frame. This will be used to create a new GDB frame struct, and then
1031 @code{INIT_EXTRA_FRAME_INFO} and @code{INIT_FRAME_PC} will be called for
1036 @chapter Remote Stubs
1038 GDB's file @file{remote.c} talks a serial protocol to code that runs
1039 in the target system. GDB provides several sample ``stubs'' that can
1040 be integrated into target programs or operating systems for this purpose;
1041 they are named @file{*-stub.c}.
1043 The GDB user's manual describes how to put such a stub into your target
1044 code. What follows is a discussion of integrating the SPARC stub
1045 into a complicated operating system (rather than a simple program),
1046 by Stu Grossman, the author of this stub.
1048 The trap handling code in the stub assumes the following upon entry to
1052 @item %l1 and %l2 contain pc and npc respectively at the time of the trap
1053 @item traps are disabled
1054 @item you are in the correct trap window
1057 As long as your trap handler can guarantee those conditions, then there is no
1058 reason why you shouldn't be able to `share' traps with the stub. The stub has
1059 no requirement that it be jumped to directly from the hardware trap vector.
1060 That is why it calls @code{exceptionHandler()}, which is provided by the external
1061 environment. For instance, this could setup the hardware traps to actually
1062 execute code which calls the stub first, and then transfers to its own trap
1065 For the most point, there probably won't be much of an issue with `sharing'
1066 traps, as the traps we use are usually not used by the kernel, and often
1067 indicate unrecoverable error conditions. Anyway, this is all controlled by a
1068 table, and is trivial to modify.
1069 The most important trap for us is for @code{ta 1}. Without that, we
1070 can't single step or do breakpoints. Everything else is unnecessary
1071 for the proper operation of the debugger/stub.
1073 From reading the stub, it's probably not obvious how breakpoints work. They
1074 are simply done by deposit/examine operations from GDB.
1077 @chapter Coding Style
1079 GDB is generally written using the GNU coding standards, as described in
1080 @file{standards.texi}, which you can get from the Free Software
1081 Foundation. There are some additional considerations for GDB maintainers
1082 that reflect the unique environment and style of GDB maintenance.
1083 If you follow these guidelines, GDB will be more consistent and easier
1086 GDB's policy on the use of prototypes is that prototypes are used
1087 to @emph{declare} functions but never to @emph{define} them. Simple
1088 macros are used in the declarations, so that a non-ANSI compiler can
1089 compile GDB without trouble. The simple macro calls are used like
1094 memory_remove_breakpoint PARAMS ((CORE_ADDR, char *));
1097 Note the double parentheses around the parameter types. This allows
1098 an arbitrary number of parameters to be described, without freaking
1099 out the C preprocessor. When the function has no parameters, it
1100 should be described like:
1104 noprocess PARAMS ((void));
1107 The @code{PARAMS} macro expands to its argument in ANSI C, or to a simple
1108 @code{()} in traditional C.
1110 All external functions should have a @code{PARAMS} declaration in a
1111 header file that callers include. All static functions should have such
1112 a declaration near the top of their source file.
1114 We don't have a gcc option that will properly check that these rules
1115 have been followed, but it's GDB policy, and we periodically check it
1116 using the tools available (plus manual labor), and clean up any remnants.
1119 @chapter Clean Design
1121 In addition to getting the syntax right, there's the little question of
1122 semantics. Some things are done in certain ways in GDB because long
1123 experience has shown that the more obvious ways caused various kinds of
1124 trouble. In particular:
1128 You can't assume the byte order of anything that comes from a
1129 target (including @var{value}s, object files, and instructions). Such
1130 things must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in GDB,
1131 or one of the swap routines defined in @file{bfd.h}, such as @code{bfd_get_32}.
1134 You can't assume that you know what interface is being used to talk to
1135 the target system. All references to the target must go through the
1136 current @code{target_ops} vector.
1139 You can't assume that the host and target machines are the same machine
1140 (except in the ``native'' support modules).
1141 In particular, you can't assume that the target machine's header files
1142 will be available on the host machine. Target code must bring along its
1143 own header files -- written from scratch or explicitly donated by their
1144 owner, to avoid copyright problems.
1147 Insertion of new @code{#ifdef}'s will be frowned upon. It's much better
1148 to write the code portably than to conditionalize it for various systems.
1151 New @code{#ifdef}'s which test for specific compilers or manufacturers
1152 or operating systems are unacceptable. All @code{#ifdef}'s should test
1153 for features. The information about which configurations contain which
1154 features should be segregated into the configuration files. Experience
1155 has proven far too often that a feature unique to one particular system
1156 often creeps into other systems; and that a conditional based on
1157 some predefined macro for your current system will become worthless
1158 over time, as new versions of your system come out that behave differently
1159 with regard to this feature.
1162 Adding code that handles specific architectures, operating systems, target
1163 interfaces, or hosts, is not acceptable in generic code. If a hook
1164 is needed at that point, invent a generic hook and define it for your
1165 configuration, with something like:
1168 #ifdef WRANGLE_SIGNALS
1169 WRANGLE_SIGNALS (signo);
1173 In your host, target, or native configuration file, as appropriate,
1174 define @code{WRANGLE_SIGNALS} to do the machine-dependent thing. Take
1175 a bit of care in defining the hook, so that it can be used by other
1176 ports in the future, if they need a hook in the same place.
1179 @emph{Do} write code that doesn't depend on the sizes of C data types,
1180 the format of the host's floating point numbers, the alignment of anything,
1181 or the order of evaluation of expressions. In short, follow good
1182 programming practices for writing portable C code.
1186 @node Submitting Patches
1187 @chapter Submitting Patches
1189 Thanks for thinking of offering your changes back to the community of
1190 GDB users. In general we like to get well designed enhancements.
1191 Thanks also for checking in advance about the best way to transfer the
1194 The two main problems with getting your patches in are,
1198 The GDB maintainers will only install "cleanly designed" patches.
1199 You may not always agree on what is clean design.
1200 @pxref{Coding Style}, @pxref{Clean Design}.
1203 If the maintainers don't have time to put the patch in when it
1204 arrives, or if there is any question about a patch, it
1205 goes into a large queue with everyone else's patches and
1209 I don't know how to get past these problems except by continuing to try.
1211 There are two issues here -- technical and legal.
1213 The legal issue is that to incorporate substantial changes requires a
1214 copyright assignment from you and/or your employer, granting ownership of the changes to
1215 the Free Software Foundation. You can get the standard document for
1216 doing this by sending mail to @code{gnu@@prep.ai.mit.edu} and asking for it.
1217 I recommend that people write in "All programs owned by the
1218 Free Software Foundation" as "NAME OF PROGRAM", so that changes in
1219 many programs (not just GDB, but GAS, Emacs, GCC, etc) can be
1220 contributed with only one piece of legalese pushed through the
1221 bureacracy and filed with the FSF. I can't start merging changes until
1222 this paperwork is received by the FSF (their rules, which I follow since
1223 I maintain it for them).
1225 Technically, the easiest way to receive changes is to receive each
1226 feature as a small context diff or unidiff, suitable for "patch".
1227 Each message sent to me should include the changes to C code and
1228 header files for a single feature, plus ChangeLog entries for each
1229 directory where files were modified, and diffs for any changes needed
1230 to the manuals (gdb/doc/gdb.texi or gdb/doc/gdbint.texi). If there
1231 are a lot of changes for a single feature, they can be split down
1232 into multiple messages.
1234 In this way, if I read and like the feature, I can add it to the
1235 sources with a single patch command, do some testing, and check it in.
1236 If you leave out the ChangeLog, I have to write one. If you leave
1237 out the doc, I have to puzzle out what needs documenting. Etc.
1239 The reason to send each change in a separate message is that I will
1240 not install some of the changes. They'll be returned to you with
1241 questions or comments. If I'm doing my job, my message back to you
1242 will say what you have to fix in order to make the change acceptable.
1243 The reason to have separate messages for separate features is so
1244 that other changes (which I @emph{am} willing to accept) can be installed
1245 while one or more changes are being reworked. If multiple features
1246 are sent in a single message, I tend to not put in the effort to sort
1247 out the acceptable changes from the unacceptable, so none of the
1248 features get installed until all are acceptable.
1250 If this sounds painful or authoritarian, well, it is. But I get a lot
1251 of bug reports and a lot of patches, and most of them don't get
1252 installed because I don't have the time to finish the job that the bug
1253 reporter or the contributor could have done. Patches that arrive
1254 complete, working, and well designed, tend to get installed on the day
1255 they arrive. The others go into a queue and get installed if and when
1256 I scan back over the queue -- which can literally take months
1257 sometimes. It's in both our interests to make patch installation easy
1258 -- you get your changes installed, and I make some forward progress on
1259 GDB in a normal 12-hour day (instead of them having to wait until I
1260 have a 14-hour or 16-hour day to spend cleaning up patches before I
1263 @node Host Conditionals
1264 @chapter Host Conditionals
1266 When GDB is configured and compiled, various macros are defined or left
1267 undefined, to control compilation based on the attributes of the host
1268 system. These macros and their meanings are:
1270 @emph{NOTE: For now, both host and target conditionals are here.
1271 Eliminate target conditionals from this list as they are identified.}
1276 @item BLOCK_ADDRESS_FUNCTION_RELATIVE
1278 @item GDBINIT_FILENAME
1282 @item MEM_FNS_DECLARED
1283 Your host config file defines this if it includes
1284 declarations of @code{memcpy} and @code{memset}. Define this
1285 to avoid conflicts between the native include
1286 files and the declarations in @file{defs.h}.
1289 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1291 @item SIGWINCH_HANDLER_BODY
1309 @item ADDITIONAL_OPTIONS
1311 @item ADDITIONAL_OPTION_CASES
1313 @item ADDITIONAL_OPTION_HANDLER
1315 @item ADDITIONAL_OPTION_HELP
1317 @item ADDR_BITS_REMOVE
1319 @item AIX_BUGGY_PTRACE_CONTINUE
1321 @item ALIGN_STACK_ON_STARTUP
1333 @item BEFORE_MAIN_LOOP_HOOK
1335 @item BELIEVE_PCC_PROMOTION
1337 @item BELIEVE_PCC_PROMOTION_TYPE
1341 @item BITS_BIG_ENDIAN
1345 @item BLOCK_ADDRESS_ABSOLUTE
1351 @item BREAKPOINT_DEBUG
1353 @item BROKEN_LARGE_ALLOCA
1354 Avoid large @code{alloca}'s. For example, on sun's, Large alloca's fail
1355 because the attempt to increase the stack limit in main() fails because
1356 shared libraries are allocated just below the initial stack limit. The
1357 SunOS kernel will not allow the stack to grow into the area occupied by
1358 the shared libraries.
1363 @item CALL_DUMMY_LOCATION
1365 @item CALL_DUMMY_STACK_ADJUST
1367 @item CANNOT_FETCH_REGISTER
1369 @item CANNOT_STORE_REGISTER
1371 @item CFRONT_PRODUCER
1373 @item CHILD_PREPARE_TO_STORE
1375 @item CLEAR_DEFERRED_STORES
1379 @item COFF_ENCAPSULATE
1383 @item CORE_NEEDS_RELOCATION
1387 @item CREATE_INFERIOR_HOOK
1397 @item DBX_PARM_SYMBOL_CLASS
1405 @item DECR_PC_AFTER_BREAK
1407 @item DEFAULT_PROMPT
1415 @item DISABLE_UNSETTABLE_BREAK
1417 @item DONT_USE_REMOTE
1419 @item DO_DEFERRED_STORES
1421 @item DO_REGISTERS_INFO
1423 @item END_OF_TEXT_DEFAULT
1427 @item EXTRACT_RETURN_VALUE
1429 @item EXTRACT_STRUCT_VALUE_ADDRESS
1431 @item EXTRA_FRAME_INFO
1433 @item EXTRA_SYMTAB_INFO
1435 @item FILES_INFO_HOOK
1449 @item FRAMELESS_FUNCTION_INVOCATION
1451 @item FRAME_ARGS_ADDRESS_CORRECT
1453 @item FRAME_CHAIN_COMBINE
1455 @item FRAME_CHAIN_VALID
1457 @item FRAME_CHAIN_VALID_ALTERNATE
1459 @item FRAME_FIND_SAVED_REGS
1461 @item FRAME_GET_BASEREG_VALUE
1463 @item FRAME_NUM_ARGS
1465 @item FRAME_SPECIFICATION_DYADIC
1467 @item FUNCTION_EPILOGUE_SIZE
1471 @item GCC2_COMPILED_FLAG_SYMBOL
1473 @item GCC_COMPILED_FLAG_SYMBOL
1475 @item GCC_MANGLE_BUG
1479 @item GET_SAVED_REGISTER
1481 @item GPLUS_PRODUCER
1492 In some cases, use the system call @code{mmap} for reading symbol
1493 tables. For some machines this allows for sharing and quick updates.
1494 @item HAVE_REGISTER_WINDOWS
1496 @item HAVE_SIGSETMASK
1500 @item HEADER_SEEK_FD
1504 @item HOST_BYTE_ORDER
1508 @item HPUX_VERSION_5
1516 @item IBM6000_TARGET
1524 @item INIT_EXTRA_FRAME_INFO
1526 @item INIT_EXTRA_SYMTAB_INFO
1540 @item IN_SOLIB_TRAMPOLINE
1544 @item IS_TRAPPED_INTERNALVAR
1548 @item KERNEL_DEBUGGING
1551 Define this to the address of the @code{u} structure (the ``user struct'',
1552 also known as the ``u-page'') in kernel virtual memory. GDB needs to know
1553 this so that it can subtract this address from absolute addresses in
1554 the upage, that are obtained via ptrace or from core files. On systems
1555 that don't need this value, set it to zero.
1556 @item KERNEL_U_ADDR_BSD
1557 Define this to cause GDB to determine the address of @code{u} at runtime,
1558 by using Berkeley-style @code{nlist} on the kernel's image in the root
1560 @item KERNEL_U_ADDR_HPUX
1561 Define this to cause GDB to determine the address of @code{u} at runtime,
1562 by using HP-style @code{nlist} on the kernel's image in the root
1578 @item LSEEK_NOT_LINEAR
1583 This macro is used as the argument to lseek (or, most commonly, bfd_seek).
1584 FIXME, it should be replaced by SEEK_SET instead, which is the POSIX equivalent.
1585 @item MACHKERNELDEBUG
1591 @item MAINTENANCE_CMDS
1593 @item MAINTENANCE_CMDS
1595 @item MALLOC_INCOMPATIBLE
1596 Define this if the system's prototype for @code{malloc} differs from the
1597 @sc{ANSI} definition.
1600 @item MMAP_BASE_ADDRESS
1601 When using HAVE_MMAP, the first mapping should go at this address.
1602 @item MMAP_INCREMENT
1603 when using HAVE_MMAP, this is the increment between mappings.
1610 @item NEED_POSIX_SETPGID
1612 @item NEED_TEXT_START_END
1626 @item NOTICE_SIGNAL_HANDLING_CHANGE
1628 @item NO_DEFINE_SYMBOL
1630 @item NO_HIF_SUPPORT
1632 @item NO_JOB_CONTROL
1634 @item NO_MALLOC_CHECK
1642 @item NO_SIGINTERRUPT
1644 @item NO_SINGLE_STEP
1652 @item NS32K_SVC_IMMED_OPERANDS
1654 @item NUMERIC_REG_NAMES
1662 @item ONE_PROCESS_WRITETEXT
1670 @item PCC_SOL_BROKEN
1672 @item PC_IN_CALL_DUMMY
1674 @item PC_LOAD_SEGMENT
1678 @item PRINT_RANDOM_SIGNAL
1680 @item PRINT_REGISTER_HOOK
1682 @item PRINT_TYPELESS_INTEGER
1684 @item PROCESS_LINENUMBER_HOOK
1686 @item PROLOGUE_FIRSTLINE_OVERLAP
1688 @item PSIGNAL_IN_SIGNAL_H
1692 @item PTRACE_ARG3_TYPE
1702 @item PUSH_ARGUMENTS
1704 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1708 @item PYRAMID_PTRACE
1710 @item REGISTER_BYTES
1712 @item REGISTER_NAMES
1714 @item REG_STACK_SEGMENT
1716 @item REG_STRUCT_HAS_ADDR
1724 @item SDB_REG_TO_REGNUM
1732 @item SET_STACK_LIMIT_HUGE
1733 When defined, stack limits will be raised to their maximum. Use this
1734 if your host supports @code{setrlimit} and you have trouble with
1735 @code{stringtab} in @file{dbxread.c}.
1737 Also used in @file{fork-child.c} to return stack limits before child
1738 processes are forked.
1739 @item SHELL_COMMAND_CONCAT
1743 @item SHIFT_INST_REGS
1745 @item SIGN_EXTEND_CHAR
1747 @item SIGTRAP_STOP_AFTER_LOAD
1751 @item SKIP_PROLOGUE_FRAMELESS_P
1753 @item SKIP_TRAMPOLINE_CODE
1757 @item SOLIB_CREATE_INFERIOR_HOOK
1761 @item STAB_REG_TO_REGNUM
1765 @item STACK_DIRECTION
1767 @item START_INFERIOR_TRAPS_EXPECTED
1771 @item STORE_RETURN_VALUE
1773 @item SUN4_COMPILER_FEATURE
1775 @item SUN_FIXED_LBRAC_BUG
1777 @item SVR4_SHARED_LIBS
1779 @item SWITCH_ENUM_BUG
1783 @item SYMBOL_RELOADING_DEFAULT
1803 @item TM_FILE_OVERRIDE
1819 @item USE_STRUCT_CONVENTION
1822 Means that System V (prior to SVR4) include files are in use.
1823 (FIXME: This symbol is abused in @file{infrun.c}, @file{regex.c},
1824 @file{remote-nindy.c}, and @file{utils.c} for other things, at the moment.)
1829 @item VARIABLES_INSIDE_BLOCK
1841 @item __HAVE_68881__
1845 @item __INT_VARARGS_H
1847 @item __not_on_pyr_yet
1863 @item longest_to_int
1893 @node Target Conditionals
1894 @chapter Target Conditionals
1896 When GDB is configured and compiled, various macros are defined or left
1897 undefined, to control compilation based on the attributes of the target
1898 system. These macros and their meanings are:
1900 @emph{NOTE: For now, both host and target conditionals are here.
1901 Eliminate host conditionals from this list as they are identified.}
1904 @item PUSH_DUMMY_FRAME
1905 Used in @samp{call_function_by_hand} to create an artificial stack frame.
1907 Used in @samp{call_function_by_hand} to remove an artificial stack frame.
1910 @item BLOCK_ADDRESS_FUNCTION_RELATIVE
1912 @item GDBINIT_FILENAME
1918 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1920 @item SIGWINCH_HANDLER_BODY
1922 @item ADDITIONAL_OPTIONS
1924 @item ADDITIONAL_OPTION_CASES
1926 @item ADDITIONAL_OPTION_HANDLER
1928 @item ADDITIONAL_OPTION_HELP
1930 @item ADDR_BITS_REMOVE
1932 @item ALIGN_STACK_ON_STARTUP
1944 @item BEFORE_MAIN_LOOP_HOOK
1946 @item BELIEVE_PCC_PROMOTION
1948 @item BELIEVE_PCC_PROMOTION_TYPE
1952 @item BITS_BIG_ENDIAN
1956 @item BLOCK_ADDRESS_ABSOLUTE
1962 @item BREAKPOINT_DEBUG
1968 @item CALL_DUMMY_LOCATION
1970 @item CALL_DUMMY_STACK_ADJUST
1972 @item CANNOT_FETCH_REGISTER
1974 @item CANNOT_STORE_REGISTER
1976 @item CFRONT_PRODUCER
1978 @item CHILD_PREPARE_TO_STORE
1980 @item CLEAR_DEFERRED_STORES
1984 @item COFF_ENCAPSULATE
1988 @item CORE_NEEDS_RELOCATION
1992 @item CREATE_INFERIOR_HOOK
2002 @item DBX_PARM_SYMBOL_CLASS
2010 @item DECR_PC_AFTER_BREAK
2012 @item DEFAULT_PROMPT
2020 @item DISABLE_UNSETTABLE_BREAK
2022 @item DONT_USE_REMOTE
2024 @item DO_DEFERRED_STORES
2026 @item DO_REGISTERS_INFO
2028 @item END_OF_TEXT_DEFAULT
2032 @item EXTRACT_RETURN_VALUE
2034 @item EXTRACT_STRUCT_VALUE_ADDRESS
2036 @item EXTRA_FRAME_INFO
2038 @item EXTRA_SYMTAB_INFO
2040 @item FILES_INFO_HOOK
2055 Unused? 6-oct-92 rich@@cygnus.com. FIXME.
2056 @item FRAMELESS_FUNCTION_INVOCATION
2058 @item FRAME_ARGS_ADDRESS_CORRECT
2060 @item FRAME_CHAIN_COMBINE
2062 @item FRAME_CHAIN_VALID
2064 @item FRAME_CHAIN_VALID_ALTERNATE
2066 @item FRAME_FIND_SAVED_REGS
2068 @item FRAME_GET_BASEREG_VALUE
2070 @item FRAME_NUM_ARGS
2072 @item FRAME_SPECIFICATION_DYADIC
2074 @item FUNCTION_EPILOGUE_SIZE
2078 @item GCC2_COMPILED_FLAG_SYMBOL
2080 @item GCC_COMPILED_FLAG_SYMBOL
2082 @item GCC_MANGLE_BUG
2086 @item GDB_TARGET_IS_HPPA
2087 This determines whether horrible kludge code in dbxread.c and partial-stab.h
2088 is used to mangle multiple-symbol-table files from HPPA's. This should all
2089 be ripped out, and a scheme like elfread.c used.
2090 @item GDB_TARGET_IS_MACH386
2092 @item GDB_TARGET_IS_SUN3
2094 @item GDB_TARGET_IS_SUN386
2096 @item GET_LONGJMP_TARGET
2097 For most machines, this is a target-dependent parameter. On the DECstation
2098 and the Iris, this is a native-dependent parameter, since <setjmp.h> is
2099 needed to define it.
2101 This macro determines the target PC address that longjmp() will jump
2102 to, assuming that we have just stopped at a longjmp breakpoint. It
2103 takes a CORE_ADDR * as argument, and stores the target PC value through
2104 this pointer. It examines the current state of the machine as needed.
2105 @item GET_SAVED_REGISTER
2107 @item GPLUS_PRODUCER
2117 @item HAVE_REGISTER_WINDOWS
2119 @item HAVE_SIGSETMASK
2123 @item HEADER_SEEK_FD
2127 @item HOST_BYTE_ORDER
2131 @item HPUX_VERSION_5
2139 @item IBM6000_TARGET
2147 @item INIT_EXTRA_FRAME_INFO
2149 @item INIT_EXTRA_SYMTAB_INFO
2163 @item IN_SOLIB_TRAMPOLINE
2167 @item IS_TRAPPED_INTERNALVAR
2171 @item KERNEL_DEBUGGING
2189 @item MACHKERNELDEBUG
2195 @item MAINTENANCE_CMDS
2197 @item MAINTENANCE_CMDS
2205 @item NEED_POSIX_SETPGID
2207 @item NEED_TEXT_START_END
2221 @item NOTICE_SIGNAL_HANDLING_CHANGE
2223 @item NO_DEFINE_SYMBOL
2225 @item NO_HIF_SUPPORT
2227 @item NO_JOB_CONTROL
2229 @item NO_MALLOC_CHECK
2237 @item NO_SIGINTERRUPT
2239 @item NO_SINGLE_STEP
2247 @item NS32K_SVC_IMMED_OPERANDS
2249 @item NUMERIC_REG_NAMES
2257 @item ONE_PROCESS_WRITETEXT
2261 @item PCC_SOL_BROKEN
2263 @item PC_IN_CALL_DUMMY
2265 @item PC_LOAD_SEGMENT
2269 @item PRINT_RANDOM_SIGNAL
2271 @item PRINT_REGISTER_HOOK
2273 @item PRINT_TYPELESS_INTEGER
2275 @item PROCESS_LINENUMBER_HOOK
2277 @item PROLOGUE_FIRSTLINE_OVERLAP
2279 @item PSIGNAL_IN_SIGNAL_H
2283 @item PTRACE_ARG3_TYPE
2287 @item PUSH_ARGUMENTS
2289 @item REGISTER_BYTES
2291 @item REGISTER_NAMES
2293 @item REG_STACK_SEGMENT
2295 @item REG_STRUCT_HAS_ADDR
2303 @item SDB_REG_TO_REGNUM
2311 @item SET_STACK_LIMIT_HUGE
2313 @item SHELL_COMMAND_CONCAT
2317 @item SHIFT_INST_REGS
2319 @item SIGN_EXTEND_CHAR
2321 @item SIGTRAP_STOP_AFTER_LOAD
2325 @item SKIP_PROLOGUE_FRAMELESS_P
2327 @item SKIP_TRAMPOLINE_CODE
2331 @item SOLIB_CREATE_INFERIOR_HOOK
2335 @item STAB_REG_TO_REGNUM
2339 @item STACK_DIRECTION
2341 @item START_INFERIOR_TRAPS_EXPECTED
2345 @item STORE_RETURN_VALUE
2347 @item SUN4_COMPILER_FEATURE
2349 @item SUN_FIXED_LBRAC_BUG
2351 @item SVR4_SHARED_LIBS
2353 @item SWITCH_ENUM_BUG
2357 @item SYMBOL_RELOADING_DEFAULT
2363 @item TARGET_BYTE_ORDER
2365 @item TARGET_CHAR_BIT
2367 @item TARGET_COMPLEX_BIT
2369 @item TARGET_DOUBLE_BIT
2371 @item TARGET_DOUBLE_COMPLEX_BIT
2373 @item TARGET_FLOAT_BIT
2375 @item TARGET_INT_BIT
2377 @item TARGET_LONG_BIT
2379 @item TARGET_LONG_DOUBLE_BIT
2381 @item TARGET_LONG_LONG_BIT
2383 @item TARGET_PTR_BIT
2385 @item TARGET_SHORT_BIT
2389 @item TM_FILE_OVERRIDE
2401 @item USE_STRUCT_CONVENTION
2407 @item VARIABLES_INSIDE_BLOCK
2417 @item __HAVE_68881__
2421 @item __INT_VARARGS_H
2423 @item __not_on_pyr_yet
2433 @item longest_to_int
2457 @node Native Conditionals
2458 @chapter Native Conditionals
2460 When GDB is configured and compiled, various macros are defined or left
2461 undefined, to control compilation when the host and target systems
2462 are the same. These macros should be defined (or left undefined)
2463 in @file{nm-@var{system}.h}.
2467 If defined, then gdb will include support for the @code{attach} and
2468 @code{detach} commands.
2469 @item FETCH_INFERIOR_REGISTERS
2470 Define this if the native-dependent code will provide its
2472 @code{fetch_inferior_registers} and @code{store_inferior_registers} in
2473 @file{@var{HOST}-nat.c}.
2474 If this symbol is @emph{not} defined, and @file{infptrace.c}
2475 is included in this configuration, the default routines in
2476 @file{infptrace.c} are used for these functions.
2477 @item GET_LONGJMP_TARGET
2478 For most machines, this is a target-dependent parameter. On the DECstation
2479 and the Iris, this is a native-dependent parameter, since <setjmp.h> is
2480 needed to define it.
2482 This macro determines the target PC address that longjmp() will jump
2483 to, assuming that we have just stopped at a longjmp breakpoint. It
2484 takes a CORE_ADDR * as argument, and stores the target PC value through
2485 this pointer. It examines the current state of the machine as needed.
2487 Defines the format for the name of a @file{/proc} device. Should be
2488 defined in @file{nm.h} @emph{only} in order to override the default
2489 definition in @file{procfs.c}.
2490 @item REGISTER_U_ADDR
2491 Defines the offset of the registers in the ``u area''; @pxref{Host}.
2493 This determines whether small routines in @file{*-tdep.c}, which
2494 translate register values
2495 between GDB's internal representation and the /proc representation,
2498 This is the offset of the registers in the upage. It need only be
2499 defined if the generic ptrace register access routines in
2500 @file{infptrace.c} are being used (that is,
2501 @file{infptrace.c} is configured in, and
2502 @code{FETCH_INFERIOR_REGISTERS} is not defined). If the default value
2503 from @file{infptrace.c} is good enough, leave it undefined.
2505 The default value means that u.u_ar0 @emph{points to} the location of the
2506 registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means that
2507 u.u_ar0 @emph{is} the location of the registers.
2510 @node Obsolete Conditionals
2511 @chapter Obsolete Conditionals
2513 Fragments of old code in GDB sometimes reference or set the following
2514 configuration macros. They should not be used by new code, and
2515 old uses should be removed as those parts of the debugger are
2519 @item STACK_END_ADDR
2520 This macro used to define where the end of the stack appeared, for use
2521 in interpreting core file formats that don't record this address in the
2522 core file itself. This information is now configured in BFD, and GDB
2523 gets the info portably from there. The values in GDB's configuration
2524 files should be moved into BFD configuration files (if needed there),
2525 and deleted from all of GDB's config files.
2527 Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
2528 is so old that it has never been converted to use BFD. Now that's old!