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, 1993 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, 1993 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 * Types:: How GDB keeps track of types
80 * BFD support for GDB:: How BFD and GDB interface
81 * Symbol Reading:: Defining New Symbol Readers
83 * Wrapping:: Wrapping Output Lines
84 * Frames:: Keeping track of function calls
85 * Remote Stubs:: Code that runs in targets and talks to GDB
86 * Longjmp Support:: Stepping through longjmp's in the target
87 * Coding Style:: Strunk and White for GDB maintainers
88 * Clean Design:: Frank Lloyd Wright for GDB maintainers
89 * Submitting Patches:: How to get your changes into GDB releases
90 * Host Conditionals:: What features exist in the host
91 * Target Conditionals:: What features exist in the target
92 * Native Conditionals:: Conditionals for when host and target are same
93 * Obsolete Conditionals:: Conditionals that don't exist any more
94 * XCOFF:: The Object file format used on IBM's RS/6000
98 @chapter The @file{README} File
100 Check the @file{README} file, it often has useful information that does not
101 appear anywhere else in the directory.
104 @node New Architectures
105 @chapter Defining a New Host or Target Architecture
107 When building support for a new host and/or target, much of the work you
108 need to do is handled by specifying configuration files;
109 @pxref{Config,,Adding a New Configuration}. Further work can be
110 divided into ``host-dependent'' (@pxref{Host,,Adding a New Host}) and
111 ``target-dependent'' (@pxref{Target,,Adding a New Target}). The
112 following discussion is meant to explain the difference between hosts
115 @heading What is considered ``host-dependent'' versus ``target-dependent''?
117 @dfn{Host} refers to attributes of the system where GDB runs.
118 @dfn{Target} refers to the system where the program being debugged
119 executes. In most cases they are the same machine, in which case
120 a third type of @dfn{Native} attributes come into play.
122 Defines and include files needed to build on the host are host support.
123 Examples are tty support, system defined types, host byte order, host
126 Defines and information needed to handle the target format are target
127 dependent. Examples are the stack frame format, instruction set,
128 breakpoint instruction, registers, and how to set up and tear down the stack
131 Information that is only needed when the host and target are the same,
132 is native dependent. One example is Unix child process support; if the
133 host and target are not the same, doing a fork to start the target
134 process is a bad idea. The various macros needed for finding the
135 registers in the @code{upage}, running @code{ptrace}, and such are all in the
136 native-dependent files.
138 Another example of native-dependent code is support for features
139 that are really part of the target environment, but which require
140 @code{#include} files that are only available on the host system.
141 Core file handling and @code{setjmp} handling are two common cases.
143 When you want to make GDB work ``native'' on a particular
144 machine, you have to include all three kinds of information.
146 The dependent information in GDB is organized into files by naming
152 Sets Makefile parameters
153 @item config/*/xm-*.h
154 Global #include's and #define's and definitions
156 Global variables and functions
159 Native-Dependent Files
162 Sets Makefile parameters (for @emph{both} host and native)
163 @item config/*/nm-*.h
164 #include's and #define's and definitions. This file
165 is only included by the small number of modules that need it,
166 so beware of doing feature-test #define's from its macros.
168 global variables and functions
171 Target-Dependent Files
174 Sets Makefile parameters
175 @item config/*/tm-*.h
176 Global #include's and #define's and definitions
178 Global variables and functions
181 At this writing, most supported hosts have had their host and native
182 dependencies sorted out properly. There are a few stragglers, which
183 can be recognized by the absence of NATDEPFILES lines in their
184 @file{config/*/*.mh}.
187 @chapter Adding a New Configuration
189 Most of the work in making GDB compile on a new machine is in specifying
190 the configuration of the machine. This is done in a dizzying variety of
191 header files and configuration scripts, which we hope to make more
192 sensible soon. Let's say your new host is called an @var{xxx} (e.g.
193 @samp{sun4}), and its full three-part configuration name is
194 @code{@var{xarch}-@var{xvend}-@var{xos}} (e.g. @samp{sparc-sun-sunos4}). In
197 In the top level directory, edit @file{config.sub} and add @var{xarch},
198 @var{xvend}, and @var{xos} to the lists of supported architectures,
199 vendors, and operating systems near the bottom of the file. Also, add
200 @var{xxx} as an alias that maps to
201 @code{@var{xarch}-@var{xvend}-@var{xos}}. You can test your changes by
205 ./config.sub @var{xxx}
210 ./config.sub @code{@var{xarch}-@var{xvend}-@var{xos}}
213 which should both respond with @code{@var{xarch}-@var{xvend}-@var{xos}}
214 and no error messages.
216 Now, go to the @file{bfd} directory and
217 create a new file @file{bfd/hosts/h-@var{xxx}.h}. Examine the
218 other @file{h-*.h} files as templates, and create one that brings in the
219 right include files for your system, and defines any host-specific
220 macros needed by BFD, the Binutils, GNU LD, or the Opcodes directories.
221 (They all share the bfd @file{hosts} directory and the @file{configure.host}
224 Then edit @file{bfd/configure.host}. Add a line to recognize your
225 @code{@var{xarch}-@var{xvend}-@var{xos}} configuration, and set
226 @code{my_host} to @var{xxx} when you recognize it. This will cause your
227 file @file{h-@var{xxx}.h} to be linked to @file{sysdep.h} at configuration
228 time. When creating the line that recognizes your configuration,
229 only match the fields that you really need to match; e.g. don't match
230 match the architecture or manufacturer if the OS is sufficient
231 to distinguish the configuration that your @file{h-@var{xxx}.h} file supports.
232 Don't match the manufacturer name unless you really need to.
233 This should make future ports easier.
235 Also, if this host requires any changes to the Makefile, create a file
236 @file{bfd/config/@var{xxx}.mh}, which includes the required lines.
238 It's possible that the @file{libiberty} and @file{readline} directories
239 won't need any changes for your configuration, but if they do, you can
240 change the @file{configure.in} file there to recognize your system and
241 map to an @file{mh-@var{xxx}} file. Then add @file{mh-@var{xxx}}
242 to the @file{config/} subdirectory, to set any makefile variables you
243 need. The only current options in there are things like @samp{-DSYSV}.
244 (This @file{mh-@var{xxx}} naming convention differs from elsewhere
245 in GDB, by historical accident. It should be cleaned up so that all
246 such files are called @file{@var{xxx}.mh}.)
248 Aha! Now to configure GDB itself! Edit
249 @file{gdb/configure.in} to recognize your system and set @code{gdb_host}
250 to @var{xxx}, and (unless your desired target is already available) also
251 set @code{gdb_target} to something appropriate (for instance,
252 @var{xxx}). To handle new hosts, modify the segment after the comment
253 @samp{# per-host}; to handle new targets, modify after @samp{#
255 @c Would it be simpler to just use different per-host and per-target
256 @c *scripts*, and call them from {configure} ?
258 Finally, you'll need to specify and define GDB's host-, native-, and
259 target-dependent @file{.h} and @file{.c} files used for your
260 configuration; the next two chapters discuss those.
264 @chapter Adding a New Host
266 Once you have specified a new configuration for your host
267 (@pxref{Config,,Adding a New Configuration}), there are three remaining
268 pieces to making GDB work on a new machine. First, you have to make it
269 host on the new machine (compile there, handle that machine's terminals
270 properly, etc). If you will be cross-debugging to some other kind of
271 system that's already supported, you are done.
273 If you want to use GDB to debug programs that run on the new machine,
274 you have to get it to understand the machine's object files, symbol
275 files, and interfaces to processes; @pxref{Target,,Adding a New Target}
276 and @pxref{Native,,Adding a New Native Configuration}
278 Several files control GDB's configuration for host systems:
281 @item gdb/config/@var{arch}/@var{xxx}.mh
282 Specifies Makefile fragments needed when hosting on machine @var{xxx}.
283 In particular, this lists the required machine-dependent object files,
284 by defining @samp{XDEPFILES=@dots{}}. Also
285 specifies the header file which describes host @var{xxx}, by defining
286 @samp{XM_FILE= xm-@var{xxx}.h}. You can also define @samp{CC},
287 @samp{REGEX} and @samp{REGEX1}, @samp{SYSV_DEFINE}, @samp{XM_CFLAGS},
288 @samp{XM_ADD_FILES}, @samp{XM_CLIBS}, @samp{XM_CDEPS},
289 etc.; see @file{Makefile.in}.
291 @item gdb/config/@var{arch}/xm-@var{xxx}.h
292 (@file{xm.h} is a link to this file, created by configure).
293 Contains C macro definitions describing the host system environment,
294 such as byte order, host C compiler and library, ptrace support,
295 and core file structure. Crib from existing @file{xm-*.h} files
298 @item gdb/@var{xxx}-xdep.c
299 Contains any miscellaneous C code required for this machine
300 as a host. On many machines it doesn't exist at all. If it does
301 exist, put @file{@var{xxx}-xdep.o} into the @code{XDEPFILES} line
302 in @file{gdb/config/mh-@var{xxx}}.
305 @subheading Generic Host Support Files
307 There are some ``generic'' versions of routines that can be used by
308 various systems. These can be customized in various ways by macros
309 defined in your @file{xm-@var{xxx}.h} file. If these routines work for
310 the @var{xxx} host, you can just include the generic file's name (with
311 @samp{.o}, not @samp{.c}) in @code{XDEPFILES}.
313 Otherwise, if your machine needs custom support routines, you will need
314 to write routines that perform the same functions as the generic file.
315 Put them into @code{@var{xxx}-xdep.c}, and put @code{@var{xxx}-xdep.o}
316 into @code{XDEPFILES}.
320 This contains serial line support for Berkeley-derived Unix systems.
323 This contains serial line support for 32-bit programs running under DOS
324 using the GO32 execution environment.
327 This contains serial line support for System V-derived Unix systems.
330 Now, you are now ready to try configuring GDB to compile using your system
331 as its host. From the top level (above @file{bfd}, @file{gdb}, etc), do:
334 ./configure @var{xxx} +target=vxworks960
337 This will configure your system to cross-compile for VxWorks on
338 the Intel 960, which is probably not what you really want, but it's
339 a test case that works at this stage. (You haven't set up to be
340 able to debug programs that run @emph{on} @var{xxx} yet.)
342 If this succeeds, you can try building it all with:
348 Repeat until the program configures, compiles, links, and runs.
349 When run, it won't be able to do much (unless you have a VxWorks/960
350 board on your network) but you will know that the host support is
353 Good luck! Comments and suggestions about this section are particularly
354 welcome; send them to @samp{bug-gdb@@prep.ai.mit.edu}.
357 @chapter Adding a New Native Configuration
359 If you are making GDB run native on the @var{xxx} machine, you have
360 plenty more work to do. Several files control GDB's configuration for
364 @item gdb/config/@var{xarch}/@var{xxx}.mh
365 Specifies Makefile fragments needed when hosting @emph{or native}
366 on machine @var{xxx}.
367 In particular, this lists the required native-dependent object files,
368 by defining @samp{NATDEPFILES=@dots{}}. Also
369 specifies the header file which describes native support on @var{xxx},
370 by defining @samp{NAT_FILE= nm-@var{xxx}.h}.
371 You can also define @samp{NAT_CFLAGS},
372 @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS}, @samp{NAT_CDEPS},
373 etc.; see @file{Makefile.in}.
375 @item gdb/config/@var{arch}/nm-@var{xxx}.h
376 (@file{nm.h} is a link to this file, created by configure).
377 Contains C macro definitions describing the native system environment,
378 such as child process control and core file support.
379 Crib from existing @file{nm-*.h} files to create a new one.
381 @item gdb/@var{xxx}-nat.c
382 Contains any miscellaneous C code required for this native support
383 of this machine. On some machines it doesn't exist at all.
386 @subheading Generic Native Support Files
388 There are some ``generic'' versions of routines that can be used by
389 various systems. These can be customized in various ways by macros
390 defined in your @file{nm-@var{xxx}.h} file. If these routines work for
391 the @var{xxx} host, you can just include the generic file's name (with
392 @samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.
394 Otherwise, if your machine needs custom support routines, you will need
395 to write routines that perform the same functions as the generic file.
396 Put them into @code{@var{xxx}-nat.c}, and put @code{@var{xxx}-nat.o}
397 into @code{NATDEPFILES}.
402 This contains the @emph{target_ops vector} that supports Unix child
403 processes on systems which use ptrace and wait to control the child.
406 This contains the @emph{target_ops vector} that supports Unix child
407 processes on systems which use /proc to control the child.
410 This does the low-level grunge that uses Unix system calls
411 to do a "fork and exec" to start up a child process.
414 This is the low level interface to inferior processes for systems
415 using the Unix @code{ptrace} call in a vanilla way.
417 @item coredep.c::fetch_core_registers()
418 Support for reading registers out of a core file. This routine calls
419 @code{register_addr()}, see below.
420 Now that BFD is used to read core files, virtually all machines should
421 use @code{coredep.c}, and should just provide @code{fetch_core_registers} in
422 @code{@var{xxx}-nat.c} (or @code{REGISTER_U_ADDR} in @code{nm-@var{xxx}.h}).
424 @item coredep.c::register_addr()
425 If your @code{nm-@var{xxx}.h} file defines the macro
426 @code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
427 set @code{addr} to the offset within the @samp{user}
428 struct of GDB register number @code{regno}. @code{blockend} is the
429 offset within the ``upage'' of @code{u.u_ar0}.
430 If @code{REGISTER_U_ADDR} is defined,
431 @file{coredep.c} will define the @code{register_addr()} function and use
432 the macro in it. If you do not define @code{REGISTER_U_ADDR}, but you
433 are using the standard @code{fetch_core_registers()}, you will need to
434 define your own version of @code{register_addr()}, put it into your
435 @code{@var{xxx}-nat.c} file, and be sure @code{@var{xxx}-nat.o} is in
436 the @code{NATDEPFILES} list. If you have your own
437 @code{fetch_core_registers()}, you may not need a separate
438 @code{register_addr()}. Many custom @code{fetch_core_registers()}
439 implementations simply locate the registers themselves.@refill
442 When making GDB run native on a new operating system,
443 to make it possible to debug
444 core files, you will need to either write specific code for parsing your
445 OS's core files, or customize @file{bfd/trad-core.c}. First, use
446 whatever @code{#include} files your machine uses to define the struct of
447 registers that is accessible (possibly in the u-area) in a core file
448 (rather than @file{machine/reg.h}), and an include file that defines whatever
449 header exists on a core file (e.g. the u-area or a @samp{struct core}). Then
450 modify @code{trad_unix_core_file_p()} to use these values to set up the
451 section information for the data segment, stack segment, any other
452 segments in the core file (perhaps shared library contents or control
453 information), ``registers'' segment, and if there are two discontiguous
454 sets of registers (e.g. integer and float), the ``reg2'' segment. This
455 section information basically delimits areas in the core file in a
456 standard way, which the section-reading routines in BFD know how to seek
459 Then back in GDB, you need a matching routine called
460 @code{fetch_core_registers()}. If you can use the generic one, it's in
461 @file{coredep.c}; if not, it's in your @file{@var{xxx}-nat.c} file.
462 It will be passed a char pointer to the entire ``registers'' segment,
463 its length, and a zero; or a char pointer to the entire ``regs2''
464 segment, its length, and a 2. The routine should suck out the supplied
465 register values and install them into GDB's ``registers'' array.
466 (@xref{New Architectures,,Defining a New Host or Target Architecture},
467 for more info about this.)
469 If your system uses @file{/proc} to control processes, and uses ELF
470 format core files, then you may be able to use the same routines
471 for reading the registers out of processes and out of core files.
474 @chapter Adding a New Target
476 For a new target called @var{ttt}, first specify the configuration as
477 described in @ref{Config,,Adding a New Configuration}. If your new
478 target is the same as your new host, you've probably already done that.
480 A variety of files specify attributes of the GDB target environment:
483 @item gdb/config/@var{arch}/@var{ttt}.mt
484 Contains a Makefile fragment specific to this target.
485 Specifies what object files are needed for target @var{ttt}, by
486 defining @samp{TDEPFILES=@dots{}}.
487 Also specifies the header file which describes @var{ttt}, by defining
488 @samp{TM_FILE= tm-@var{ttt}.h}. You can also define @samp{TM_CFLAGS},
489 @samp{TM_CLIBS}, @samp{TM_CDEPS},
490 and other Makefile variables here; see @file{Makefile.in}.
492 @item gdb/config/@var{arch}/tm-@var{ttt}.h
493 (@file{tm.h} is a link to this file, created by configure).
494 Contains macro definitions about the target machine's
495 registers, stack frame format and instructions.
496 Crib from existing @file{tm-*.h} files when building a new one.
498 @item gdb/@var{ttt}-tdep.c
499 Contains any miscellaneous code required for this target machine.
500 On some machines it doesn't exist at all. Sometimes the macros
501 in @file{tm-@var{ttt}.h} become very complicated, so they are
502 implemented as functions here instead, and the macro is simply
503 defined to call the function.
506 Defines functions for accessing files that are
507 executable on the target system. These functions open and examine an
508 exec file, extract data from one, write data to one, print information
509 about one, etc. Now that executable files are handled with BFD, every
510 target should be able to use the generic exec.c rather than its
513 @item gdb/@var{arch}-pinsn.c
514 Prints (disassembles) the target machine's instructions.
515 This file is usually shared with other target machines which use the
516 same processor, which is why it is @file{@var{arch}-pinsn.c} rather
517 than @file{@var{ttt}-pinsn.c}.
519 @item gdb/@var{arch}-opcode.h
520 Contains some large initialized
521 data structures describing the target machine's instructions.
522 This is a bit strange for a @file{.h} file, but it's OK since
523 it is only included in one place. @file{@var{arch}-opcode.h} is shared
524 between the debugger and the assembler, if the GNU assembler has been
525 ported to the target machine.
527 @item gdb/config/@var{arch}/tm-@var{arch}.h
528 This often exists to describe the basic layout of the target machine's
529 processor chip (registers, stack, etc).
530 If used, it is included by @file{tm-@var{xxx}.h}. It can
531 be shared among many targets that use the same processor.
533 @item gdb/@var{arch}-tdep.c
534 Similarly, there are often common subroutines that are shared by all
535 target machines that use this particular architecture.
538 When adding support for a new target machine, there are various areas
539 of support that might need change, or might be OK.
541 If you are using an existing object file format (a.out or COFF),
542 there is probably little to be done. See @file{bfd/doc/bfd.texinfo}
543 for more information on writing new a.out or COFF versions.
545 If you need to add a new object file format, you must first add it to
546 BFD. This is beyond the scope of this document right now. Basically
547 you must build a transfer vector (of type @code{bfd_target}), which will
548 mean writing all the required routines, and add it to the list in
549 @file{bfd/targets.c}.
551 You must then arrange for the BFD code to provide access to the
552 debugging symbols. Generally GDB will have to call swapping routines
553 from BFD and a few other BFD internal routines to locate the debugging
554 information. As much as possible, GDB should not depend on the BFD
555 internal data structures.
557 For some targets (e.g., COFF), there is a special transfer vector used
558 to call swapping routines, since the external data structures on various
559 platforms have different sizes and layouts. Specialized routines that
560 will only ever be implemented by one object file format may be called
561 directly. This interface should be described in a file
562 @file{bfd/libxxx.h}, which is included by GDB.
564 If you are adding a new operating system for an existing CPU chip, add a
565 @file{tm-@var{xos}.h} file that describes the operating system
566 facilities that are unusual (extra symbol table info; the breakpoint
567 instruction needed; etc). Then write a
568 @file{tm-@var{xarch}-@var{xos}.h} that just @code{#include}s
569 @file{tm-@var{xarch}.h} and @file{tm-@var{xos}.h}. (Now that we have
570 three-part configuration names, this will probably get revised to
571 separate the @var{xos} configuration from the @var{xarch}
576 @chapter Adding a Source Language to GDB
578 To add other languages to GDB's expression parser, follow the following steps:
581 @item Create the expression parser.
583 This should reside in a file @file{@var{lang}-exp.y}. Routines for building
584 parsed expressions into a @samp{union exp_element} list are in @file{parse.c}.
586 Since we can't depend upon everyone having Bison, and YACC produces
587 parsers that define a bunch of global names, the following lines
588 @emph{must} be included at the top of the YACC parser, to prevent
589 the various parsers from defining the same global names:
592 #define yyparse @var{lang}_parse
593 #define yylex @var{lang}_lex
594 #define yyerror @var{lang}_error
595 #define yylval @var{lang}_lval
596 #define yychar @var{lang}_char
597 #define yydebug @var{lang}_debug
598 #define yypact @var{lang}_pact
599 #define yyr1 @var{lang}_r1
600 #define yyr2 @var{lang}_r2
601 #define yydef @var{lang}_def
602 #define yychk @var{lang}_chk
603 #define yypgo @var{lang}_pgo
604 #define yyact @var{lang}_act
605 #define yyexca @var{lang}_exca
606 #define yyerrflag @var{lang}_errflag
607 #define yynerrs @var{lang}_nerrs
610 At the bottom of your parser, define a @code{struct language_defn} and
611 initialize it with the right values for your language. Define an
612 @code{initialize_@var{lang}} routine and have it call
613 @samp{add_language(@var{lang}_language_defn)} to tell the rest of GDB
614 that your language exists. You'll need some other supporting variables
615 and functions, which will be used via pointers from your
616 @code{@var{lang}_language_defn}. See the declaration of @code{struct
617 language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
618 for more information.
620 @item Add any evaluation routines, if necessary
622 If you need new opcodes (that represent the operations of the language),
623 add them to the enumerated type in @file{expression.h}. Add support
624 code for these operations in @code{eval.c:evaluate_subexp()}. Add cases
625 for new opcodes in two functions from @file{parse.c}:
626 @code{prefixify_subexp()} and @code{length_of_subexp()}. These compute
627 the number of @code{exp_element}s that a given operation takes up.
629 @item Update some existing code
631 Add an enumerated identifier for your language to the enumerated type
632 @code{enum language} in @file{defs.h}.
634 Update the routines in @file{language.c} so your language is included. These
635 routines include type predicates and such, which (in some cases) are
636 language dependent. If your language does not appear in the switch
637 statement, an error is reported.
639 Also included in @file{language.c} is the code that updates the variable
640 @code{current_language}, and the routines that translate the
641 @code{language_@var{lang}} enumerated identifier into a printable
644 Update the function @code{_initialize_language} to include your language. This
645 function picks the default language upon startup, so is dependent upon
646 which languages that GDB is built for.
648 Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
649 code so that the language of each symtab (source file) is set properly.
650 This is used to determine the language to use at each stack frame level.
651 Currently, the language is set based upon the extension of the source
652 file. If the language can be better inferred from the symbol
653 information, please set the language of the symtab in the symbol-reading
656 Add helper code to @code{expprint.c:print_subexp()} to handle any new
657 expression opcodes you have added to @file{expression.h}. Also, add the
658 printed representations of your operators to @code{op_print_tab}.
660 @item Add a place of call
662 Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
663 @code{parse.c:parse_exp_1()}.
665 @item Use macros to trim code
667 The user has the option of building GDB for some or all of the
668 languages. If the user decides to build GDB for the language
669 @var{lang}, then every file dependent on @file{language.h} will have the
670 macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to
671 leave out large routines that the user won't need if he or she is not
674 Note that you do not need to do this in your YACC parser, since if GDB
675 is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
676 compiled form of your parser) is not linked into GDB at all.
678 See the file @file{configure.in} for how GDB is configured for different
681 @item Edit @file{Makefile.in}
683 Add dependencies in @file{Makefile.in}. Make sure you update the macro
684 variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
685 not get linked in, or, worse yet, it may not get @code{tar}red into the
691 @chapter Configuring GDB for Release
693 From the top level directory (containing @file{gdb}, @file{bfd},
694 @file{libiberty}, and so on):
696 make -f Makefile.in gdb.tar.Z
699 This will properly configure, clean, rebuild any files that are
700 distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}),
701 and will then make a tarfile. (If the top level directory has already
702 beenn configured, you can just do @code{make gdb.tar.Z} instead.)
704 This procedure requires:
707 @item @code{makeinfo} (texinfo2 level)
710 @item @code{yacc} or @code{bison}
713 @dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.).
715 @subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
717 @file{gdb.texinfo} is currently marked up using the texinfo-2 macros,
718 which are not yet a default for anything (but we have to start using
721 For making paper, the only thing this implies is the right generation of
722 @file{texinfo.tex} needs to be included in the distribution.
724 For making info files, however, rather than duplicating the texinfo2
725 distribution, generate @file{gdb-all.texinfo} locally, and include the files
726 @file{gdb.info*} in the distribution. Note the plural; @code{makeinfo} will
727 split the document into one overall file and five or so included files.
730 @node Partial Symbol Tables
731 @chapter Partial Symbol Tables
733 GDB has three types of symbol tables.
736 @item full symbol tables (symtabs). These contain the main
737 information about symbols and addresses.
738 @item partial symbol tables (psymtabs). These contain enough
739 information to know when to read the corresponding
740 part of the full symbol table.
741 @item minimal symbol tables (msymtabs). These contain information
742 gleaned from non-debugging symbols.
745 This section describes partial symbol tables.
747 A psymtab is constructed by doing a very quick pass over an executable
748 file's debugging information. Small amounts of information are
749 extracted -- enough to identify which parts of the symbol table will
750 need to be re-read and fully digested later, when the user needs the
751 information. The speed of this pass causes GDB to start up very
752 quickly. Later, as the detailed rereading occurs, it occurs in small
753 pieces, at various times, and the delay therefrom is mostly invisible to
754 the user. (@xref{Symbol Reading}.)
756 The symbols that show up in a file's psymtab should be, roughly, those
757 visible to the debugger's user when the program is not running code from
758 that file. These include external symbols and types, static
759 symbols and types, and enum values declared at file scope.
761 The psymtab also contains the range of instruction addresses that the
762 full symbol table would represent.
764 The idea is that there are only two ways for the user (or much of
765 the code in the debugger) to reference a symbol:
770 (e.g. execution stops at some address which is inside a function
771 in this file). The address will be noticed to be in the
772 range of this psymtab, and the full symtab will be read in.
773 @code{find_pc_function}, @code{find_pc_line}, and other @code{find_pc_@dots{}}
774 functions handle this.
777 (e.g. the user asks to print a variable, or set a breakpoint on a
778 function). Global names and file-scope names will be found in the
779 psymtab, which will cause the symtab to be pulled in. Local names will
780 have to be qualified by a global name, or a file-scope name, in which
781 case we will have already read in the symtab as we evaluated the
782 qualifier. Or, a local symbol can be referenced when
783 we are "in" a local scope, in which case the first case applies.
784 @code{lookup_symbol} does most of the work here.
788 The only reason that psymtabs exist is to cause a symtab to be read in
789 at the right moment. Any symbol that can be elided from a psymtab,
790 while still causing that to happen, should not appear in it. Since
791 psymtabs don't have the idea of scope, you can't put local symbols in
792 them anyway. Psymtabs don't have the idea of the type of a symbol,
793 either, so types need not appear, unless they will be referenced by
796 It is a bug for GDB to behave one way when only a psymtab has been read,
797 and another way if the corresponding symtab has been read in. Such
798 bugs are typically caused by a psymtab that does not contain all the
799 visible symbols, or which has the wrong instruction address ranges.
801 The psymtab for a particular section of a symbol-file (objfile)
802 could be thrown away after the symtab has been read in. The symtab
803 should always be searched before the psymtab, so the psymtab will
804 never be used (in a bug-free environment). Currently,
805 psymtabs are allocated on an obstack, and all the psymbols themselves
806 are allocated in a pair of large arrays on an obstack, so there is
807 little to be gained by trying to free them unless you want to do a lot
813 Fundamental Types (e.g., FT_VOID, FT_BOOLEAN).
815 These are the fundamental types that gdb uses internally. Fundamental
816 types from the various debugging formats (stabs, ELF, etc) are mapped into
817 one of these. They are basically a union of all fundamental types that
818 gdb knows about for all the languages that gdb knows about.
820 Type Codes (e.g., TYPE_CODE_PTR, TYPE_CODE_ARRAY).
822 Each time gdb builds an internal type, it marks it with one of these
823 types. The type may be a fundamental type, such as TYPE_CODE_INT, or
824 a derived type, such as TYPE_CODE_PTR which is a pointer to another
825 type. Typically, several FT_* types map to one TYPE_CODE_* type, and
826 are distinguished by other members of the type struct, such as whether
827 the type is signed or unsigned, and how many bits it uses.
829 Builtin Types (e.g., builtin_type_void, builtin_type_char).
831 These are instances of type structs that roughly correspond to fundamental
832 types and are created as global types for gdb to use for various ugly
833 historical reasons. We eventually want to eliminate these. Note for
834 example that builtin_type_int initialized in gdbtypes.c is basically the
835 same as a TYPE_CODE_INT type that is initialized in c-lang.c for an
836 FT_INTEGER fundamental type. The difference is that the builtin_type is
837 not associated with any particular objfile, and only one instance exists,
838 while c-lang.c builds as many TYPE_CODE_INT types as needed, with each
839 one associated with some particular objfile.
841 @node BFD support for GDB
842 @chapter Binary File Descriptor Library Support for GDB
844 BFD provides support for GDB in several ways:
847 @item identifying executable and core files
848 BFD will identify a variety of file types, including a.out, coff, and
849 several variants thereof, as well as several kinds of core files.
851 @item access to sections of files
852 BFD parses the file headers to determine the names, virtual addresses,
853 sizes, and file locations of all the various named sections in files
854 (such as the text section or the data section). GDB simply calls
855 BFD to read or write section X at byte offset Y for length Z.
857 @item specialized core file support
858 BFD provides routines to determine the failing command name stored
859 in a core file, the signal with which the program failed, and whether
860 a core file matches (i.e. could be a core dump of) a particular executable
863 @item locating the symbol information
864 GDB uses an internal interface of BFD to determine where to find the
865 symbol information in an executable file or symbol-file. GDB itself
866 handles the reading of symbols, since BFD does not ``understand'' debug
867 symbols, but GDB uses BFD's cached information to find the symbols,
871 @c The interface for symbol reading is described in @ref{Symbol
872 @c Reading,,Symbol Reading}.
876 @chapter Symbol Reading
878 GDB reads symbols from "symbol files". The usual symbol file is the
879 file containing the program which gdb is debugging. GDB can be directed
880 to use a different file for symbols (with the ``symbol-file''
881 command), and it can also read more symbols via the ``add-file'' and ``load''
882 commands, or while reading symbols from shared libraries.
884 Symbol files are initially opened by @file{symfile.c} using the BFD
885 library. BFD identifies the type of the file by examining its header.
886 @code{symfile_init} then uses this identification to locate a
887 set of symbol-reading functions.
889 Symbol reading modules identify themselves to GDB by calling
890 @code{add_symtab_fns} during their module initialization. The argument
891 to @code{add_symtab_fns} is a @code{struct sym_fns} which contains
892 the name (or name prefix) of the symbol format, the length of the prefix,
893 and pointers to four functions. These functions are called at various
894 times to process symbol-files whose identification matches the specified
897 The functions supplied by each module are:
900 @item @var{xxx}_symfile_init(struct sym_fns *sf)
902 Called from @code{symbol_file_add} when we are about to read a new
903 symbol file. This function should clean up any internal state
904 (possibly resulting from half-read previous files, for example)
905 and prepare to read a new symbol file. Note that the symbol file
906 which we are reading might be a new "main" symbol file, or might
907 be a secondary symbol file whose symbols are being added to the
908 existing symbol table.
910 The argument to @code{@var{xxx}_symfile_init} is a newly allocated
911 @code{struct sym_fns} whose @code{bfd} field contains the BFD
912 for the new symbol file being read. Its @code{private} field
913 has been zeroed, and can be modified as desired. Typically,
914 a struct of private information will be @code{malloc}'d, and
915 a pointer to it will be placed in the @code{private} field.
917 There is no result from @code{@var{xxx}_symfile_init}, but it can call
918 @code{error} if it detects an unavoidable problem.
920 @item @var{xxx}_new_init()
922 Called from @code{symbol_file_add} when discarding existing symbols.
923 This function need only handle
924 the symbol-reading module's internal state; the symbol table data
925 structures visible to the rest of GDB will be discarded by
926 @code{symbol_file_add}. It has no arguments and no result.
927 It may be called after @code{@var{xxx}_symfile_init}, if a new symbol
928 table is being read, or may be called alone if all symbols are
929 simply being discarded.
931 @item @var{xxx}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)
933 Called from @code{symbol_file_add} to actually read the symbols from a
934 symbol-file into a set of psymtabs or symtabs.
936 @code{sf} points to the struct sym_fns originally passed to
937 @code{@var{xxx}_sym_init} for possible initialization. @code{addr} is the
938 offset between the file's specified start address and its true address
939 in memory. @code{mainline} is 1 if this is the main symbol table being
940 read, and 0 if a secondary symbol file (e.g. shared library or
941 dynamically loaded file) is being read.@refill
944 In addition, if a symbol-reading module creates psymtabs when
945 @var{xxx}_symfile_read is called, these psymtabs will contain a pointer to
946 a function @code{@var{xxx}_psymtab_to_symtab}, which can be called from
947 any point in the GDB symbol-handling code.
950 @item @var{xxx}_psymtab_to_symtab (struct partial_symtab *pst)
952 Called from @code{psymtab_to_symtab} (or the PSYMTAB_TO_SYMTAB
953 macro) if the psymtab has not already been read in and had its
954 @code{pst->symtab} pointer set. The argument is the psymtab
955 to be fleshed-out into a symtab. Upon return, pst->readin
956 should have been set to 1, and pst->symtab should contain a
957 pointer to the new corresponding symtab, or zero if there
958 were no symbols in that part of the symbol file.
965 Cleanups are a structured way to deal with things that need to be done
966 later. When your code does something (like @code{malloc} some memory, or open
967 a file) that needs to be undone later (e.g. free the memory or close
968 the file), it can make a cleanup. The cleanup will be done at some
969 future point: when the command is finished, when an error occurs, or
970 when your code decides it's time to do cleanups.
972 You can also discard cleanups, that is, throw them away without doing
973 what they say. This is only done if you ask that it be done.
978 @item struct cleanup *@var{old_chain};
979 Declare a variable which will hold a cleanup chain handle.
981 @item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
982 Make a cleanup which will cause @var{function} to be called with @var{arg}
983 (a @code{char *}) later. The result, @var{old_chain}, is a handle that can be
984 passed to @code{do_cleanups} or @code{discard_cleanups} later. Unless you are
985 going to call @code{do_cleanups} or @code{discard_cleanups} yourself,
986 you can ignore the result from @code{make_cleanup}.
989 @item do_cleanups (@var{old_chain});
990 Perform all cleanups done since @code{make_cleanup} returned @var{old_chain}.
994 old = make_cleanup (b, 0);
998 will call @code{b()} but will not call @code{a()}. The cleanup that calls @code{a()} will remain
999 in the cleanup chain, and will be done later unless otherwise discarded.@refill
1001 @item discard_cleanups (@var{old_chain});
1002 Same as @code{do_cleanups} except that it just removes the cleanups from the
1003 chain and does not call the specified functions.
1007 Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify that they
1008 ``should not be called when cleanups are not in place''. This means
1009 that any actions you need to reverse in the case of an error or
1010 interruption must be on the cleanup chain before you call these functions,
1011 since they might never return to your code (they @samp{longjmp} instead).
1015 @chapter Wrapping Output Lines
1017 Output that goes through @code{printf_filtered} or @code{fputs_filtered} or
1018 @code{fputs_demangled} needs only to have calls to @code{wrap_here} added
1019 in places that would be good breaking points. The utility routines
1020 will take care of actually wrapping if the line width is exceeded.
1022 The argument to @code{wrap_here} is an indentation string which is printed
1023 @emph{only} if the line breaks there. This argument is saved away and used
1024 later. It must remain valid until the next call to @code{wrap_here} or
1025 until a newline has been printed through the @code{*_filtered} functions.
1026 Don't pass in a local variable and then return!
1028 It is usually best to call @code{wrap_here()} after printing a comma or space.
1029 If you call it before printing a space, make sure that your indentation
1030 properly accounts for the leading space that will print if the line wraps
1033 Any function or set of functions that produce filtered output must finish
1034 by printing a newline, to flush the wrap buffer, before switching to
1035 unfiltered (``@code{printf}'') output. Symbol reading routines that print
1036 warnings are a good example.
1042 A frame is a construct that GDB uses to keep track of calling and called
1047 in the machine description has no meaning to the machine-independent
1048 part of GDB, except that it is used when setting up a new frame from
1049 scratch, as follows:
1052 create_new_frame (read_register (FP_REGNUM), read_pc ()));
1055 Other than that, all the meaning imparted to @code{FP_REGNUM} is imparted by
1056 the machine-dependent code. So, @code{FP_REGNUM} can have any value that
1057 is convenient for the code that creates new frames. (@code{create_new_frame}
1058 calls @code{INIT_EXTRA_FRAME_INFO} if it is defined; that is where you should
1059 use the @code{FP_REGNUM} value, if your frames are nonstandard.)
1062 Given a GDB frame, determine the address of the calling function's
1063 frame. This will be used to create a new GDB frame struct, and then
1064 @code{INIT_EXTRA_FRAME_INFO} and @code{INIT_FRAME_PC} will be called for
1069 @chapter Remote Stubs
1071 GDB's file @file{remote.c} talks a serial protocol to code that runs
1072 in the target system. GDB provides several sample ``stubs'' that can
1073 be integrated into target programs or operating systems for this purpose;
1074 they are named @file{*-stub.c}.
1076 The GDB user's manual describes how to put such a stub into your target
1077 code. What follows is a discussion of integrating the SPARC stub
1078 into a complicated operating system (rather than a simple program),
1079 by Stu Grossman, the author of this stub.
1081 The trap handling code in the stub assumes the following upon entry to
1085 @item %l1 and %l2 contain pc and npc respectively at the time of the trap
1086 @item traps are disabled
1087 @item you are in the correct trap window
1090 As long as your trap handler can guarantee those conditions, then there is no
1091 reason why you shouldn't be able to `share' traps with the stub. The stub has
1092 no requirement that it be jumped to directly from the hardware trap vector.
1093 That is why it calls @code{exceptionHandler()}, which is provided by the external
1094 environment. For instance, this could setup the hardware traps to actually
1095 execute code which calls the stub first, and then transfers to its own trap
1098 For the most point, there probably won't be much of an issue with `sharing'
1099 traps, as the traps we use are usually not used by the kernel, and often
1100 indicate unrecoverable error conditions. Anyway, this is all controlled by a
1101 table, and is trivial to modify.
1102 The most important trap for us is for @code{ta 1}. Without that, we
1103 can't single step or do breakpoints. Everything else is unnecessary
1104 for the proper operation of the debugger/stub.
1106 From reading the stub, it's probably not obvious how breakpoints work. They
1107 are simply done by deposit/examine operations from GDB.
1109 @node Longjmp Support
1110 @chapter Longjmp Support
1112 GDB has support for figuring out that the target is doing a
1113 @code{longjmp} and for stopping at the target of the jump, if we are
1114 stepping. This is done with a few specialized internal breakpoints,
1115 which are visible in the @code{maint info breakpoint} command.
1117 To make this work, you need to define a macro called
1118 @code{GET_LONGJMP_TARGET}, which will examine the @code{jmp_buf}
1119 structure and extract the longjmp target address. Since @code{jmp_buf}
1120 is target specific, you will need to define it in the appropriate
1121 @file{tm-xxx.h} file. Look in @file{tm-sun4os4.h} and
1122 @file{sparc-tdep.c} for examples of how to do this.
1125 @chapter Coding Style
1127 GDB is generally written using the GNU coding standards, as described in
1128 @file{standards.texi}, which you can get from the Free Software
1129 Foundation. There are some additional considerations for GDB maintainers
1130 that reflect the unique environment and style of GDB maintenance.
1131 If you follow these guidelines, GDB will be more consistent and easier
1134 GDB's policy on the use of prototypes is that prototypes are used
1135 to @emph{declare} functions but never to @emph{define} them. Simple
1136 macros are used in the declarations, so that a non-ANSI compiler can
1137 compile GDB without trouble. The simple macro calls are used like
1142 memory_remove_breakpoint PARAMS ((CORE_ADDR, char *));
1145 Note the double parentheses around the parameter types. This allows
1146 an arbitrary number of parameters to be described, without freaking
1147 out the C preprocessor. When the function has no parameters, it
1148 should be described like:
1152 noprocess PARAMS ((void));
1155 The @code{PARAMS} macro expands to its argument in ANSI C, or to a simple
1156 @code{()} in traditional C.
1158 All external functions should have a @code{PARAMS} declaration in a
1159 header file that callers include. All static functions should have such
1160 a declaration near the top of their source file.
1162 We don't have a gcc option that will properly check that these rules
1163 have been followed, but it's GDB policy, and we periodically check it
1164 using the tools available (plus manual labor), and clean up any remnants.
1167 @chapter Clean Design
1169 In addition to getting the syntax right, there's the little question of
1170 semantics. Some things are done in certain ways in GDB because long
1171 experience has shown that the more obvious ways caused various kinds of
1172 trouble. In particular:
1176 You can't assume the byte order of anything that comes from a
1177 target (including @var{value}s, object files, and instructions). Such
1178 things must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in GDB,
1179 or one of the swap routines defined in @file{bfd.h}, such as @code{bfd_get_32}.
1182 You can't assume that you know what interface is being used to talk to
1183 the target system. All references to the target must go through the
1184 current @code{target_ops} vector.
1187 You can't assume that the host and target machines are the same machine
1188 (except in the ``native'' support modules).
1189 In particular, you can't assume that the target machine's header files
1190 will be available on the host machine. Target code must bring along its
1191 own header files -- written from scratch or explicitly donated by their
1192 owner, to avoid copyright problems.
1195 Insertion of new @code{#ifdef}'s will be frowned upon. It's much better
1196 to write the code portably than to conditionalize it for various systems.
1199 New @code{#ifdef}'s which test for specific compilers or manufacturers
1200 or operating systems are unacceptable. All @code{#ifdef}'s should test
1201 for features. The information about which configurations contain which
1202 features should be segregated into the configuration files. Experience
1203 has proven far too often that a feature unique to one particular system
1204 often creeps into other systems; and that a conditional based on
1205 some predefined macro for your current system will become worthless
1206 over time, as new versions of your system come out that behave differently
1207 with regard to this feature.
1210 Adding code that handles specific architectures, operating systems, target
1211 interfaces, or hosts, is not acceptable in generic code. If a hook
1212 is needed at that point, invent a generic hook and define it for your
1213 configuration, with something like:
1216 #ifdef WRANGLE_SIGNALS
1217 WRANGLE_SIGNALS (signo);
1221 In your host, target, or native configuration file, as appropriate,
1222 define @code{WRANGLE_SIGNALS} to do the machine-dependent thing. Take
1223 a bit of care in defining the hook, so that it can be used by other
1224 ports in the future, if they need a hook in the same place.
1227 @emph{Do} write code that doesn't depend on the sizes of C data types,
1228 the format of the host's floating point numbers, the alignment of anything,
1229 or the order of evaluation of expressions. In short, follow good
1230 programming practices for writing portable C code.
1234 @node Submitting Patches
1235 @chapter Submitting Patches
1237 Thanks for thinking of offering your changes back to the community of
1238 GDB users. In general we like to get well designed enhancements.
1239 Thanks also for checking in advance about the best way to transfer the
1242 The two main problems with getting your patches in are,
1246 The GDB maintainers will only install "cleanly designed" patches.
1247 You may not always agree on what is clean design.
1248 @pxref{Coding Style}, @pxref{Clean Design}.
1251 If the maintainers don't have time to put the patch in when it
1252 arrives, or if there is any question about a patch, it
1253 goes into a large queue with everyone else's patches and
1257 I don't know how to get past these problems except by continuing to try.
1259 There are two issues here -- technical and legal.
1261 The legal issue is that to incorporate substantial changes requires a
1262 copyright assignment from you and/or your employer, granting ownership of the changes to
1263 the Free Software Foundation. You can get the standard document for
1264 doing this by sending mail to @code{gnu@@prep.ai.mit.edu} and asking for it.
1265 I recommend that people write in "All programs owned by the
1266 Free Software Foundation" as "NAME OF PROGRAM", so that changes in
1267 many programs (not just GDB, but GAS, Emacs, GCC, etc) can be
1268 contributed with only one piece of legalese pushed through the
1269 bureacracy and filed with the FSF. I can't start merging changes until
1270 this paperwork is received by the FSF (their rules, which I follow since
1271 I maintain it for them).
1273 Technically, the easiest way to receive changes is to receive each
1274 feature as a small context diff or unidiff, suitable for "patch".
1275 Each message sent to me should include the changes to C code and
1276 header files for a single feature, plus ChangeLog entries for each
1277 directory where files were modified, and diffs for any changes needed
1278 to the manuals (gdb/doc/gdb.texi or gdb/doc/gdbint.texi). If there
1279 are a lot of changes for a single feature, they can be split down
1280 into multiple messages.
1282 In this way, if I read and like the feature, I can add it to the
1283 sources with a single patch command, do some testing, and check it in.
1284 If you leave out the ChangeLog, I have to write one. If you leave
1285 out the doc, I have to puzzle out what needs documenting. Etc.
1287 The reason to send each change in a separate message is that I will
1288 not install some of the changes. They'll be returned to you with
1289 questions or comments. If I'm doing my job, my message back to you
1290 will say what you have to fix in order to make the change acceptable.
1291 The reason to have separate messages for separate features is so
1292 that other changes (which I @emph{am} willing to accept) can be installed
1293 while one or more changes are being reworked. If multiple features
1294 are sent in a single message, I tend to not put in the effort to sort
1295 out the acceptable changes from the unacceptable, so none of the
1296 features get installed until all are acceptable.
1298 If this sounds painful or authoritarian, well, it is. But I get a lot
1299 of bug reports and a lot of patches, and most of them don't get
1300 installed because I don't have the time to finish the job that the bug
1301 reporter or the contributor could have done. Patches that arrive
1302 complete, working, and well designed, tend to get installed on the day
1303 they arrive. The others go into a queue and get installed if and when
1304 I scan back over the queue -- which can literally take months
1305 sometimes. It's in both our interests to make patch installation easy
1306 -- you get your changes installed, and I make some forward progress on
1307 GDB in a normal 12-hour day (instead of them having to wait until I
1308 have a 14-hour or 16-hour day to spend cleaning up patches before I
1311 @node Host Conditionals
1312 @chapter Host Conditionals
1314 When GDB is configured and compiled, various macros are defined or left
1315 undefined, to control compilation based on the attributes of the host
1316 system. These macros and their meanings are:
1318 @emph{NOTE: For now, both host and target conditionals are here.
1319 Eliminate target conditionals from this list as they are identified.}
1324 @item BLOCK_ADDRESS_FUNCTION_RELATIVE
1326 @item GDBINIT_FILENAME
1330 @item MEM_FNS_DECLARED
1331 Your host config file defines this if it includes
1332 declarations of @code{memcpy} and @code{memset}. Define this
1333 to avoid conflicts between the native include
1334 files and the declarations in @file{defs.h}.
1337 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1339 @item SIGWINCH_HANDLER_BODY
1357 @item ADDITIONAL_OPTIONS
1359 @item ADDITIONAL_OPTION_CASES
1361 @item ADDITIONAL_OPTION_HANDLER
1363 @item ADDITIONAL_OPTION_HELP
1365 @item ADDR_BITS_REMOVE
1367 @item AIX_BUGGY_PTRACE_CONTINUE
1369 @item ALIGN_STACK_ON_STARTUP
1381 @item BEFORE_MAIN_LOOP_HOOK
1383 @item BELIEVE_PCC_PROMOTION
1385 @item BELIEVE_PCC_PROMOTION_TYPE
1389 @item BITS_BIG_ENDIAN
1393 @item BLOCK_ADDRESS_ABSOLUTE
1399 @item BREAKPOINT_DEBUG
1401 @item BROKEN_LARGE_ALLOCA
1402 Avoid large @code{alloca}'s. For example, on sun's, Large alloca's fail
1403 because the attempt to increase the stack limit in main() fails because
1404 shared libraries are allocated just below the initial stack limit. The
1405 SunOS kernel will not allow the stack to grow into the area occupied by
1406 the shared libraries.
1411 @item CALL_DUMMY_LOCATION
1413 @item CALL_DUMMY_STACK_ADJUST
1415 @item CANNOT_FETCH_REGISTER
1417 @item CANNOT_STORE_REGISTER
1419 @item CFRONT_PRODUCER
1421 @item CHILD_PREPARE_TO_STORE
1423 @item CLEAR_DEFERRED_STORES
1427 @item COFF_ENCAPSULATE
1431 @item CORE_NEEDS_RELOCATION
1435 @item CREATE_INFERIOR_HOOK
1443 @item DBX_PARM_SYMBOL_CLASS
1451 @item DECR_PC_AFTER_BREAK
1453 @item DEFAULT_PROMPT
1461 @item DISABLE_UNSETTABLE_BREAK
1463 @item DONT_USE_REMOTE
1465 @item DO_DEFERRED_STORES
1467 @item DO_REGISTERS_INFO
1469 @item END_OF_TEXT_DEFAULT
1473 @item EXTRACT_RETURN_VALUE
1475 @item EXTRACT_STRUCT_VALUE_ADDRESS
1477 @item EXTRA_FRAME_INFO
1479 @item EXTRA_SYMTAB_INFO
1481 @item FILES_INFO_HOOK
1495 @item FRAMELESS_FUNCTION_INVOCATION
1497 @item FRAME_ARGS_ADDRESS_CORRECT
1499 @item FRAME_CHAIN_COMBINE
1501 @item FRAME_CHAIN_VALID
1503 @item FRAME_CHAIN_VALID_ALTERNATE
1505 @item FRAME_FIND_SAVED_REGS
1507 @item FRAME_GET_BASEREG_VALUE
1509 @item FRAME_NUM_ARGS
1511 @item FRAME_SPECIFICATION_DYADIC
1513 @item FUNCTION_EPILOGUE_SIZE
1517 @item GCC2_COMPILED_FLAG_SYMBOL
1519 @item GCC_COMPILED_FLAG_SYMBOL
1521 @item GCC_MANGLE_BUG
1525 @item GET_SAVED_REGISTER
1527 @item GPLUS_PRODUCER
1538 In some cases, use the system call @code{mmap} for reading symbol
1539 tables. For some machines this allows for sharing and quick updates.
1540 @item HAVE_REGISTER_WINDOWS
1542 @item HAVE_SIGSETMASK
1546 @item HEADER_SEEK_FD
1550 @item HOST_BYTE_ORDER
1554 @item HPUX_VERSION_5
1566 @item INIT_EXTRA_FRAME_INFO
1568 @item INIT_EXTRA_SYMTAB_INFO
1582 @item IN_SOLIB_TRAMPOLINE
1586 @item IS_TRAPPED_INTERNALVAR
1590 @item KERNEL_DEBUGGING
1593 Define this to the address of the @code{u} structure (the ``user struct'',
1594 also known as the ``u-page'') in kernel virtual memory. GDB needs to know
1595 this so that it can subtract this address from absolute addresses in
1596 the upage, that are obtained via ptrace or from core files. On systems
1597 that don't need this value, set it to zero.
1598 @item KERNEL_U_ADDR_BSD
1599 Define this to cause GDB to determine the address of @code{u} at runtime,
1600 by using Berkeley-style @code{nlist} on the kernel's image in the root
1602 @item KERNEL_U_ADDR_HPUX
1603 Define this to cause GDB to determine the address of @code{u} at runtime,
1604 by using HP-style @code{nlist} on the kernel's image in the root
1620 @item LSEEK_NOT_LINEAR
1625 This macro is used as the argument to lseek (or, most commonly, bfd_seek).
1626 FIXME, it should be replaced by SEEK_SET instead, which is the POSIX equivalent.
1627 @item MACHKERNELDEBUG
1633 @item MAINTENANCE_CMDS
1635 @item MAINTENANCE_CMDS
1637 @item MALLOC_INCOMPATIBLE
1638 Define this if the system's prototype for @code{malloc} differs from the
1639 @sc{ANSI} definition.
1642 @item MMAP_BASE_ADDRESS
1643 When using HAVE_MMAP, the first mapping should go at this address.
1644 @item MMAP_INCREMENT
1645 when using HAVE_MMAP, this is the increment between mappings.
1652 @item NEED_POSIX_SETPGID
1654 @item NEED_TEXT_START_END
1668 @item NOTICE_SIGNAL_HANDLING_CHANGE
1670 @item NO_HIF_SUPPORT
1672 @item NO_JOB_CONTROL
1675 GDB will use the @code{mmalloc} library for memory allocation for symbol
1676 reading, unless this symbol is defined. Define it on systems
1677 on which @code{mmalloc} does not
1678 work for some reason. One example is the DECstation, where its RPC
1679 library can't cope with our redefinition of @code{malloc} to call
1680 @code{mmalloc}. When defining @code{NO_MMALLOC}, you will also have
1681 to override the setting of @code{MMALLOC_LIB} to empty, in the Makefile.
1682 Therefore, this define is usually set on the command line by overriding
1683 @code{MMALLOC_DISABLE} in @file{config/*/*.mh}, rather than by defining
1684 it in @file{xm-*.h}.
1685 @item NO_MMALLOC_CHECK
1686 Define this if you are using @code{mmalloc}, but don't want the overhead
1687 of checking the heap with @code{mmcheck}.
1688 @item NO_SIGINTERRUPT
1690 @item NO_SINGLE_STEP
1694 @item NS32K_SVC_IMMED_OPERANDS
1696 @item NUMERIC_REG_NAMES
1704 @item ONE_PROCESS_WRITETEXT
1712 @item PCC_SOL_BROKEN
1714 @item PC_IN_CALL_DUMMY
1716 @item PC_LOAD_SEGMENT
1720 @item PRINT_RANDOM_SIGNAL
1722 @item PRINT_REGISTER_HOOK
1724 @item PRINT_TYPELESS_INTEGER
1726 @item PROCESS_LINENUMBER_HOOK
1728 @item PROLOGUE_FIRSTLINE_OVERLAP
1730 @item PSIGNAL_IN_SIGNAL_H
1734 @item PUSH_ARGUMENTS
1736 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1740 @item PYRAMID_PTRACE
1742 @item REGISTER_BYTES
1744 @item REGISTER_NAMES
1746 @item REG_STACK_SEGMENT
1748 @item REG_STRUCT_HAS_ADDR
1756 @item SDB_REG_TO_REGNUM
1764 @item SET_STACK_LIMIT_HUGE
1765 When defined, stack limits will be raised to their maximum. Use this
1766 if your host supports @code{setrlimit} and you have trouble with
1767 @code{stringtab} in @file{dbxread.c}.
1769 Also used in @file{fork-child.c} to return stack limits before child
1770 processes are forked.
1771 @item SHELL_COMMAND_CONCAT
1775 @item SHIFT_INST_REGS
1777 @item SIGN_EXTEND_CHAR
1779 @item SIGTRAP_STOP_AFTER_LOAD
1783 @item SKIP_PROLOGUE_FRAMELESS_P
1785 @item SKIP_TRAMPOLINE_CODE
1789 @item SOLIB_CREATE_INFERIOR_HOOK
1793 @item STAB_REG_TO_REGNUM
1797 @item STACK_DIRECTION
1799 @item START_INFERIOR_TRAPS_EXPECTED
1803 @item STORE_RETURN_VALUE
1805 @item SUN4_COMPILER_FEATURE
1807 @item SUN_FIXED_LBRAC_BUG
1809 @item SVR4_SHARED_LIBS
1811 @item SWITCH_ENUM_BUG
1815 @item SYMBOL_RELOADING_DEFAULT
1835 @item TM_FILE_OVERRIDE
1851 @item USE_STRUCT_CONVENTION
1854 Means that System V (prior to SVR4) include files are in use.
1855 (FIXME: This symbol is abused in @file{infrun.c}, @file{regex.c},
1856 @file{remote-nindy.c}, and @file{utils.c} for other things, at the moment.)
1861 @item VARIABLES_INSIDE_BLOCK
1873 @item __HAVE_68881__
1877 @item __INT_VARARGS_H
1879 @item __not_on_pyr_yet
1895 @item longest_to_int
1925 @node Target Conditionals
1926 @chapter Target Conditionals
1928 When GDB is configured and compiled, various macros are defined or left
1929 undefined, to control compilation based on the attributes of the target
1930 system. These macros and their meanings are:
1932 @emph{NOTE: For now, both host and target conditionals are here.
1933 Eliminate host conditionals from this list as they are identified.}
1936 @item PUSH_DUMMY_FRAME
1937 Used in @samp{call_function_by_hand} to create an artificial stack frame.
1939 Used in @samp{call_function_by_hand} to remove an artificial stack frame.
1942 @item BLOCK_ADDRESS_FUNCTION_RELATIVE
1944 @item GDBINIT_FILENAME
1950 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1952 @item SIGWINCH_HANDLER_BODY
1954 @item ADDITIONAL_OPTIONS
1956 @item ADDITIONAL_OPTION_CASES
1958 @item ADDITIONAL_OPTION_HANDLER
1960 @item ADDITIONAL_OPTION_HELP
1962 @item ADDR_BITS_REMOVE
1964 @item ALIGN_STACK_ON_STARTUP
1976 @item BEFORE_MAIN_LOOP_HOOK
1978 @item BELIEVE_PCC_PROMOTION
1980 @item BELIEVE_PCC_PROMOTION_TYPE
1984 @item BITS_BIG_ENDIAN
1988 @item BLOCK_ADDRESS_ABSOLUTE
1994 @item BREAKPOINT_DEBUG
2000 @item CALL_DUMMY_LOCATION
2002 @item CALL_DUMMY_STACK_ADJUST
2004 @item CANNOT_FETCH_REGISTER
2006 @item CANNOT_STORE_REGISTER
2008 @item CFRONT_PRODUCER
2010 @item CHILD_PREPARE_TO_STORE
2012 @item CLEAR_DEFERRED_STORES
2016 @item COFF_ENCAPSULATE
2020 @item CORE_NEEDS_RELOCATION
2024 @item CREATE_INFERIOR_HOOK
2032 @item DBX_PARM_SYMBOL_CLASS
2040 @item DECR_PC_AFTER_BREAK
2042 @item DEFAULT_PROMPT
2050 @item DISABLE_UNSETTABLE_BREAK
2052 @item DONT_USE_REMOTE
2054 @item DO_DEFERRED_STORES
2056 @item DO_REGISTERS_INFO
2058 @item END_OF_TEXT_DEFAULT
2062 @item EXTRACT_RETURN_VALUE
2064 @item EXTRACT_STRUCT_VALUE_ADDRESS
2066 @item EXTRA_FRAME_INFO
2068 @item EXTRA_SYMTAB_INFO
2070 @item FILES_INFO_HOOK
2085 Unused? 6-oct-92 rich@@cygnus.com. FIXME.
2086 @item FRAMELESS_FUNCTION_INVOCATION
2088 @item FRAME_ARGS_ADDRESS_CORRECT
2090 @item FRAME_CHAIN_COMBINE
2092 @item FRAME_CHAIN_VALID
2094 @item FRAME_CHAIN_VALID_ALTERNATE
2096 @item FRAME_FIND_SAVED_REGS
2098 @item FRAME_GET_BASEREG_VALUE
2100 @item FRAME_NUM_ARGS
2102 @item FRAME_SPECIFICATION_DYADIC
2104 @item FUNCTION_EPILOGUE_SIZE
2108 @item GCC2_COMPILED_FLAG_SYMBOL
2110 @item GCC_COMPILED_FLAG_SYMBOL
2112 @item GCC_MANGLE_BUG
2116 @item GDB_TARGET_IS_HPPA
2117 This determines whether horrible kludge code in dbxread.c and partial-stab.h
2118 is used to mangle multiple-symbol-table files from HPPA's. This should all
2119 be ripped out, and a scheme like elfread.c used.
2120 @item GDB_TARGET_IS_MACH386
2122 @item GDB_TARGET_IS_SUN3
2124 @item GDB_TARGET_IS_SUN386
2126 @item GET_LONGJMP_TARGET
2127 For most machines, this is a target-dependent parameter. On the DECstation
2128 and the Iris, this is a native-dependent parameter, since <setjmp.h> is
2129 needed to define it.
2131 This macro determines the target PC address that longjmp() will jump
2132 to, assuming that we have just stopped at a longjmp breakpoint. It
2133 takes a CORE_ADDR * as argument, and stores the target PC value through
2134 this pointer. It examines the current state of the machine as needed.
2135 @item GET_SAVED_REGISTER
2137 @item GPLUS_PRODUCER
2147 @item HAVE_REGISTER_WINDOWS
2149 @item HAVE_SIGSETMASK
2153 @item HEADER_SEEK_FD
2157 @item HOST_BYTE_ORDER
2161 @item HPUX_VERSION_5
2167 @item IBM6000_TARGET
2168 Shows that we are configured for an IBM RS/6000 target. This conditional
2169 should be eliminated (FIXME) and replaced by feature-specific macros.
2170 It was introduced in haste and we are repenting at leisure.
2177 @item INIT_EXTRA_FRAME_INFO
2179 @item INIT_EXTRA_SYMTAB_INFO
2193 @item IN_SOLIB_TRAMPOLINE
2197 @item IS_TRAPPED_INTERNALVAR
2201 @item KERNEL_DEBUGGING
2219 @item MACHKERNELDEBUG
2225 @item MAINTENANCE_CMDS
2227 @item MAINTENANCE_CMDS
2235 @item NEED_POSIX_SETPGID
2237 @item NEED_TEXT_START_END
2251 @item NOTICE_SIGNAL_HANDLING_CHANGE
2253 @item NO_HIF_SUPPORT
2255 @item NO_SIGINTERRUPT
2257 @item NO_SINGLE_STEP
2260 xcoffread.c--This causes types not to be read, to save memory and speed
2264 @item NS32K_SVC_IMMED_OPERANDS
2266 @item NUMERIC_REG_NAMES
2274 @item ONE_PROCESS_WRITETEXT
2278 @item PCC_SOL_BROKEN
2280 @item PC_IN_CALL_DUMMY
2282 @item PC_LOAD_SEGMENT
2286 @item PRINT_RANDOM_SIGNAL
2288 @item PRINT_REGISTER_HOOK
2290 @item PRINT_TYPELESS_INTEGER
2292 @item PROCESS_LINENUMBER_HOOK
2294 @item PROLOGUE_FIRSTLINE_OVERLAP
2296 @item PSIGNAL_IN_SIGNAL_H
2300 @item PUSH_ARGUMENTS
2302 @item REGISTER_BYTES
2304 @item REGISTER_NAMES
2306 @item REG_STACK_SEGMENT
2308 @item REG_STRUCT_HAS_ADDR
2316 @item SDB_REG_TO_REGNUM
2324 @item SHELL_COMMAND_CONCAT
2328 @item SHIFT_INST_REGS
2330 @item SIGN_EXTEND_CHAR
2332 @item SIGTRAP_STOP_AFTER_LOAD
2336 @item SKIP_PROLOGUE_FRAMELESS_P
2338 @item SKIP_TRAMPOLINE_CODE
2342 @item SOLIB_CREATE_INFERIOR_HOOK
2346 @item STAB_REG_TO_REGNUM
2350 @item STACK_DIRECTION
2352 @item START_INFERIOR_TRAPS_EXPECTED
2356 @item STORE_RETURN_VALUE
2358 @item SUN4_COMPILER_FEATURE
2360 @item SUN_FIXED_LBRAC_BUG
2362 @item SVR4_SHARED_LIBS
2364 @item SWITCH_ENUM_BUG
2368 @item SYMBOL_RELOADING_DEFAULT
2374 @item TARGET_BYTE_ORDER
2376 @item TARGET_CHAR_BIT
2378 @item TARGET_COMPLEX_BIT
2380 @item TARGET_DOUBLE_BIT
2382 @item TARGET_DOUBLE_COMPLEX_BIT
2384 @item TARGET_FLOAT_BIT
2386 @item TARGET_INT_BIT
2388 @item TARGET_LONG_BIT
2390 @item TARGET_LONG_DOUBLE_BIT
2392 @item TARGET_LONG_LONG_BIT
2394 @item TARGET_PTR_BIT
2396 @item TARGET_SHORT_BIT
2400 @item TM_FILE_OVERRIDE
2412 @item USE_STRUCT_CONVENTION
2418 @item VARIABLES_INSIDE_BLOCK
2428 @item __HAVE_68881__
2432 @item __INT_VARARGS_H
2434 @item __not_on_pyr_yet
2444 @item longest_to_int
2468 @node Native Conditionals
2469 @chapter Native Conditionals
2471 When GDB is configured and compiled, various macros are defined or left
2472 undefined, to control compilation when the host and target systems
2473 are the same. These macros should be defined (or left undefined)
2474 in @file{nm-@var{system}.h}.
2478 If defined, then gdb will include support for the @code{attach} and
2479 @code{detach} commands.
2480 @item FETCH_INFERIOR_REGISTERS
2481 Define this if the native-dependent code will provide its
2483 @code{fetch_inferior_registers} and @code{store_inferior_registers} in
2484 @file{@var{HOST}-nat.c}.
2485 If this symbol is @emph{not} defined, and @file{infptrace.c}
2486 is included in this configuration, the default routines in
2487 @file{infptrace.c} are used for these functions.
2488 @item GET_LONGJMP_TARGET
2489 For most machines, this is a target-dependent parameter. On the DECstation
2490 and the Iris, this is a native-dependent parameter, since <setjmp.h> is
2491 needed to define it.
2493 This macro determines the target PC address that longjmp() will jump
2494 to, assuming that we have just stopped at a longjmp breakpoint. It
2495 takes a CORE_ADDR * as argument, and stores the target PC value through
2496 this pointer. It examines the current state of the machine as needed.
2498 Defines the format for the name of a @file{/proc} device. Should be
2499 defined in @file{nm.h} @emph{only} in order to override the default
2500 definition in @file{procfs.c}.
2503 @item PTRACE_ARG3_TYPE
2504 The type of the third argument to the @code{ptrace} system call, if it exists
2505 and is different from @code{int}.
2506 @item REGISTER_U_ADDR
2507 Defines the offset of the registers in the ``u area''; @pxref{Host}.
2509 This determines whether small routines in @file{*-tdep.c}, which
2510 translate register values
2511 between GDB's internal representation and the /proc representation,
2514 This is the offset of the registers in the upage. It need only be
2515 defined if the generic ptrace register access routines in
2516 @file{infptrace.c} are being used (that is,
2517 @file{infptrace.c} is configured in, and
2518 @code{FETCH_INFERIOR_REGISTERS} is not defined). If the default value
2519 from @file{infptrace.c} is good enough, leave it undefined.
2521 The default value means that u.u_ar0 @emph{points to} the location of the
2522 registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means that
2523 u.u_ar0 @emph{is} the location of the registers.
2526 @node Obsolete Conditionals
2527 @chapter Obsolete Conditionals
2529 Fragments of old code in GDB sometimes reference or set the following
2530 configuration macros. They should not be used by new code, and
2531 old uses should be removed as those parts of the debugger are
2535 @item STACK_END_ADDR
2536 This macro used to define where the end of the stack appeared, for use
2537 in interpreting core file formats that don't record this address in the
2538 core file itself. This information is now configured in BFD, and GDB
2539 gets the info portably from there. The values in GDB's configuration
2540 files should be moved into BFD configuration files (if needed there),
2541 and deleted from all of GDB's config files.
2543 Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
2544 is so old that it has never been converted to use BFD. Now that's old!
2548 @chapter The XCOFF Object File Format
2550 The IBM RS/6000 running AIX uses an object file format called xcoff.
2551 The COFF sections, symbols, and line numbers are used, but debugging
2552 symbols are dbx-style stabs whose strings are located in the
2553 @samp{.debug} section (rather than the string table). Files are
2554 indicated with a @samp{C_FILE} symbol (.file) which is analogous to
2555 @samp{N_SO}; include files are delimited with @samp{C_BINCL} (.bi) and
2556 @samp{C_EINCL} (.ei) which correspond to @samp{N_SOL} rather than Sun's
2557 @samp{N_BINCL} (that is, they don't nest and there is no equivalent to
2558 N_EXCL). The values of the @samp{C_BINCL} and @samp{C_EINCL} symbols
2559 are offsets into the executable file which point to the beginning and
2560 the end of the portion of the linetable which correspond to this include
2561 file (warning: C_EINCL is inclusive not exclusive like most end of
2562 something pointers). Other differences from standard stabs include the
2563 use of negative type numbers for builtin types.
2565 The shared library scheme has a nice clean interface for figuring out
2566 what shared libraries are in use, but the catch is that everything which
2567 refers to addresses (symbol tables and breakpoints at least) needs to be
2568 relocated for both shared libraries and the main executable. At least
2569 using the standard mechanism this can only be done once the program has
2570 been run (or the core file has been read).