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 @c IMHO much information should go into *comments* as you discover it
65 @c or design changes to GDB. It's more likely to get noticed and
66 @c easier to maintain there. -kingdon
67 This documents the internals of the GNU debugger, GDB. It is a
68 collection of miscellaneous information with little form at this point.
69 Mostly, it is a repository into which you can put information about
70 GDB as you discover it (or as you design changes to GDB).
73 * README:: The README File
74 * Getting Started:: Getting started working on GDB
75 * Debugging GDB:: Debugging GDB with itself
76 * New Architectures:: Defining a New Host or Target Architecture
77 * Config:: Adding a New Configuration
78 * Host:: Adding a New Host
79 * Native:: Adding a New Native Configuration
80 * Target:: Adding a New Target
81 * Languages:: Defining New Source Languages
82 * Releases:: Configuring GDB for Release
83 * Partial Symbol Tables:: How GDB reads symbols quickly at startup
84 * Types:: How GDB keeps track of types
85 * BFD support for GDB:: How BFD and GDB interface
86 * Symbol Reading:: Defining New Symbol Readers
88 * Wrapping:: Wrapping Output Lines
89 * Frames:: Keeping track of function calls
90 * Remote Stubs:: Code that runs in targets and talks to GDB
91 * Longjmp Support:: Stepping through longjmp's in the target
92 * Coding Style:: Strunk and White for GDB maintainers
93 * Clean Design:: Frank Lloyd Wright for GDB maintainers
94 * Submitting Patches:: How to get your changes into GDB releases
95 * Host Conditionals:: What features exist in the host
96 * Target Conditionals:: What features exist in the target
97 * Native Conditionals:: Conditionals for when host and target are same
98 * Obsolete Conditionals:: Conditionals that don't exist any more
99 * XCOFF:: The Object file format used on IBM's RS/6000
103 @chapter The @file{README} File
105 Check the @file{README} file, it often has useful information that does not
106 appear anywhere else in the directory.
108 @node Getting Started
109 @chapter Getting Started Working on GDB
111 GDB is a large and complicated program, and if you first starting to
112 work on it, it can be hard to know where to start. Fortunately, if you
113 know how to go about it, there are ways to figure out what is going on:
117 This manual, the GDB Internals manual, has information which applies
118 generally to many parts of GDB.
121 Information about particular functions or data structures are located in
122 comments with those functions or data structures. If you run across a
123 function or a global variable which does not have a comment correctly
124 explaining what is does, this can be thought of as a bug in GDB; feel
125 free to submit a bug report, with a suggested comment if you can figure
126 out what the comment should say (@pxref{Submitting Patches}). If you
127 find a comment which is actually wrong, be especially sure to report that.
129 Comments explaining the function of macros defined in host, target, or
130 native dependent files can be in several places. Sometimes they are
131 repeated every place the macro is defined. Sometimes they are where the
132 macro is used. Sometimes there is a header file which supplies a
133 default definition of the macro, and the comment is there. This manual
134 also has a list of macros (@pxref{Host Conditionals}, @pxref{Target
135 Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete
136 Conditionals}) with some documentation.
139 Start with the header files. Once you some idea of how GDB's internal
140 symbol tables are stored (see @file{symtab.h}, @file{gdbtypes.h}), you
141 will find it much easier to understand the code which uses and creates
145 You may wish to process the information you are getting somehow, to
146 enhance your understanding of it. Summarize it, translate it to another
147 language, add some (perhaps trivial or non-useful) feature to GDB, use
148 the code to predict what a test case would do and write the test case
149 and verify your prediction, etc. If you are reading code and your eyes
150 are starting to glaze over, this is a sign you need to use a more active
154 Once you have a part of GDB to start with, you can find more
155 specifically the part you are looking for by stepping through each
156 function with the @code{next} command. Do not use @code{step} or you
157 will quickly get distracted; when the function you are stepping through
158 calls another function try only to get a big-picture understanding
159 (perhaps using the comment at the beginning of the function being
160 called) of what it does. This way you can identify which of the
161 functions being called by the function you are stepping through is the
162 one which you are interested in. You may need to examine the data
163 structures generated at each stage, with reference to the comments in
164 the header files explaining what the data structures are supposed to
167 Of course, this same technique can be used if you are just reading the
168 code, rather than actually stepping through it. The same general
169 principle applies---when the code you are looking at calls something
170 else, just try to understand generally what the code being called does,
171 rather than worrying about all its details.
174 A good place to start when tracking down some particular area is with a
175 command which invokes that feature. Suppose you want to know how
176 single-stepping works. As a GDB user, you know that the @code{step}
177 command invokes single-stepping. The command is invoked via command
178 tables (see @file{command.h}); by convention the function which actually
179 performs the command is formed by taking the name of the command and
180 adding @samp{_command}, or in the case of an @code{info} subcommand,
181 @samp{_info}. For example, the @code{step} command invokes the
182 @code{step_command} function and the @code{info display} command invokes
183 @code{display_info}. When this convention is not followed, you might
184 have to use @code{grep} or @kbd{M-x tags-search} in emacs, or run GDB on
185 itself and set a breakpoint in @code{execute_command}.
188 If all of the above fail, it may be appropriate to ask for information
189 on @code{bug-gdb}. But @emph{never} post a generic question like ``I was
190 wondering if anyone could give me some tips about understanding
191 GDB''---if we had some magic secret we would put it in this manual.
192 Suggestions for improving the manual are always welcome, of course.
198 @chapter Debugging GDB with itself
199 If gdb is limping on your machine, this is the preferred way to get it
200 fully functional. Be warned that in some ancient Unix systems, like
201 Ultrix 4.0, a program can't be running in one process while it is being
202 debugged in another. Rather than typing the command @code{@w{./gdb
203 ./gdb}}, which works on Suns and such, you can copy @file{gdb} to
204 @file{gdb2} and then type @code{@w{./gdb ./gdb2}}.
206 When you run gdb in the gdb source directory, it will read a
207 @file{.gdbinit} file that sets up some simple things to make debugging
208 gdb easier. The @code{info} command, when executed without a subcommand
209 in a gdb being debugged by gdb, will pop you back up to the top level
210 gdb. See @file{.gdbinit} for details.
212 If you use emacs, you will probably want to do a @code{make TAGS} after
213 you configure your distribution; this will put the machine dependent
214 routines for your local machine where they will be accessed first by
217 Also, make sure that you've either compiled gdb with your local cc, or
218 have run @code{fixincludes} if you are compiling with gcc.
220 @node New Architectures
221 @chapter Defining a New Host or Target Architecture
223 When building support for a new host and/or target, much of the work you
224 need to do is handled by specifying configuration files;
225 @pxref{Config,,Adding a New Configuration}. Further work can be
226 divided into ``host-dependent'' (@pxref{Host,,Adding a New Host}) and
227 ``target-dependent'' (@pxref{Target,,Adding a New Target}). The
228 following discussion is meant to explain the difference between hosts
231 @heading What is considered ``host-dependent'' versus ``target-dependent''?
233 @dfn{Host} refers to attributes of the system where GDB runs.
234 @dfn{Target} refers to the system where the program being debugged
235 executes. In most cases they are the same machine, in which case
236 a third type of @dfn{Native} attributes come into play.
238 Defines and include files needed to build on the host are host support.
239 Examples are tty support, system defined types, host byte order, host
242 Defines and information needed to handle the target format are target
243 dependent. Examples are the stack frame format, instruction set,
244 breakpoint instruction, registers, and how to set up and tear down the stack
247 Information that is only needed when the host and target are the same,
248 is native dependent. One example is Unix child process support; if the
249 host and target are not the same, doing a fork to start the target
250 process is a bad idea. The various macros needed for finding the
251 registers in the @code{upage}, running @code{ptrace}, and such are all in the
252 native-dependent files.
254 Another example of native-dependent code is support for features
255 that are really part of the target environment, but which require
256 @code{#include} files that are only available on the host system.
257 Core file handling and @code{setjmp} handling are two common cases.
259 When you want to make GDB work ``native'' on a particular
260 machine, you have to include all three kinds of information.
262 The dependent information in GDB is organized into files by naming
268 Sets Makefile parameters
269 @item config/*/xm-*.h
270 Global #include's and #define's and definitions
272 Global variables and functions
275 Native-Dependent Files
278 Sets Makefile parameters (for @emph{both} host and native)
279 @item config/*/nm-*.h
280 #include's and #define's and definitions. This file
281 is only included by the small number of modules that need it,
282 so beware of doing feature-test #define's from its macros.
284 global variables and functions
287 Target-Dependent Files
290 Sets Makefile parameters
291 @item config/*/tm-*.h
292 Global #include's and #define's and definitions
294 Global variables and functions
297 At this writing, most supported hosts have had their host and native
298 dependencies sorted out properly. There are a few stragglers, which
299 can be recognized by the absence of NATDEPFILES lines in their
300 @file{config/*/*.mh}.
303 @chapter Adding a New Configuration
305 Most of the work in making GDB compile on a new machine is in specifying
306 the configuration of the machine. This is done in a dizzying variety of
307 header files and configuration scripts, which we hope to make more
308 sensible soon. Let's say your new host is called an @var{xxx} (e.g.
309 @samp{sun4}), and its full three-part configuration name is
310 @code{@var{xarch}-@var{xvend}-@var{xos}} (e.g. @samp{sparc-sun-sunos4}). In
313 In the top level directory, edit @file{config.sub} and add @var{xarch},
314 @var{xvend}, and @var{xos} to the lists of supported architectures,
315 vendors, and operating systems near the bottom of the file. Also, add
316 @var{xxx} as an alias that maps to
317 @code{@var{xarch}-@var{xvend}-@var{xos}}. You can test your changes by
321 ./config.sub @var{xxx}
326 ./config.sub @code{@var{xarch}-@var{xvend}-@var{xos}}
329 which should both respond with @code{@var{xarch}-@var{xvend}-@var{xos}}
330 and no error messages.
332 Now, go to the @file{bfd} directory and
333 create a new file @file{bfd/hosts/h-@var{xxx}.h}. Examine the
334 other @file{h-*.h} files as templates, and create one that brings in the
335 right include files for your system, and defines any host-specific
336 macros needed by BFD, the Binutils, GNU LD, or the Opcodes directories.
337 (They all share the bfd @file{hosts} directory and the @file{configure.host}
340 Then edit @file{bfd/configure.host}. Add a line to recognize your
341 @code{@var{xarch}-@var{xvend}-@var{xos}} configuration, and set
342 @code{my_host} to @var{xxx} when you recognize it. This will cause your
343 file @file{h-@var{xxx}.h} to be linked to @file{sysdep.h} at configuration
344 time. When creating the line that recognizes your configuration,
345 only match the fields that you really need to match; e.g. don't match
346 match the architecture or manufacturer if the OS is sufficient
347 to distinguish the configuration that your @file{h-@var{xxx}.h} file supports.
348 Don't match the manufacturer name unless you really need to.
349 This should make future ports easier.
351 Also, if this host requires any changes to the Makefile, create a file
352 @file{bfd/config/@var{xxx}.mh}, which includes the required lines.
354 It's possible that the @file{libiberty} and @file{readline} directories
355 won't need any changes for your configuration, but if they do, you can
356 change the @file{configure.in} file there to recognize your system and
357 map to an @file{mh-@var{xxx}} file. Then add @file{mh-@var{xxx}}
358 to the @file{config/} subdirectory, to set any makefile variables you
359 need. The only current options in there are things like @samp{-DSYSV}.
360 (This @file{mh-@var{xxx}} naming convention differs from elsewhere
361 in GDB, by historical accident. It should be cleaned up so that all
362 such files are called @file{@var{xxx}.mh}.)
364 Aha! Now to configure GDB itself! Edit
365 @file{gdb/configure.in} to recognize your system and set @code{gdb_host}
366 to @var{xxx}, and (unless your desired target is already available) also
367 set @code{gdb_target} to something appropriate (for instance,
368 @var{xxx}). To handle new hosts, modify the segment after the comment
369 @samp{# per-host}; to handle new targets, modify after @samp{#
371 @c Would it be simpler to just use different per-host and per-target
372 @c *scripts*, and call them from {configure} ?
374 Finally, you'll need to specify and define GDB's host-, native-, and
375 target-dependent @file{.h} and @file{.c} files used for your
376 configuration; the next two chapters discuss those.
380 @chapter Adding a New Host
382 Once you have specified a new configuration for your host
383 (@pxref{Config,,Adding a New Configuration}), there are three remaining
384 pieces to making GDB work on a new machine. First, you have to make it
385 host on the new machine (compile there, handle that machine's terminals
386 properly, etc). If you will be cross-debugging to some other kind of
387 system that's already supported, you are done.
389 If you want to use GDB to debug programs that run on the new machine,
390 you have to get it to understand the machine's object files, symbol
391 files, and interfaces to processes; @pxref{Target,,Adding a New Target}
392 and @pxref{Native,,Adding a New Native Configuration}
394 Several files control GDB's configuration for host systems:
397 @item gdb/config/@var{arch}/@var{xxx}.mh
398 Specifies Makefile fragments needed when hosting on machine @var{xxx}.
399 In particular, this lists the required machine-dependent object files,
400 by defining @samp{XDEPFILES=@dots{}}. Also
401 specifies the header file which describes host @var{xxx}, by defining
402 @samp{XM_FILE= xm-@var{xxx}.h}. You can also define @samp{CC},
403 @samp{REGEX} and @samp{REGEX1}, @samp{SYSV_DEFINE}, @samp{XM_CFLAGS},
404 @samp{XM_ADD_FILES}, @samp{XM_CLIBS}, @samp{XM_CDEPS},
405 etc.; see @file{Makefile.in}.
407 @item gdb/config/@var{arch}/xm-@var{xxx}.h
408 (@file{xm.h} is a link to this file, created by configure).
409 Contains C macro definitions describing the host system environment,
410 such as byte order, host C compiler and library, ptrace support,
411 and core file structure. Crib from existing @file{xm-*.h} files
414 @item gdb/@var{xxx}-xdep.c
415 Contains any miscellaneous C code required for this machine
416 as a host. On many machines it doesn't exist at all. If it does
417 exist, put @file{@var{xxx}-xdep.o} into the @code{XDEPFILES} line
418 in @file{gdb/config/mh-@var{xxx}}.
421 @subheading Generic Host Support Files
423 There are some ``generic'' versions of routines that can be used by
424 various systems. These can be customized in various ways by macros
425 defined in your @file{xm-@var{xxx}.h} file. If these routines work for
426 the @var{xxx} host, you can just include the generic file's name (with
427 @samp{.o}, not @samp{.c}) in @code{XDEPFILES}.
429 Otherwise, if your machine needs custom support routines, you will need
430 to write routines that perform the same functions as the generic file.
431 Put them into @code{@var{xxx}-xdep.c}, and put @code{@var{xxx}-xdep.o}
432 into @code{XDEPFILES}.
436 This contains serial line support for Berkeley-derived Unix systems.
439 This contains serial line support for 32-bit programs running under DOS
440 using the GO32 execution environment.
443 This contains serial line support for System V-derived Unix systems.
446 Now, you are now ready to try configuring GDB to compile using your system
447 as its host. From the top level (above @file{bfd}, @file{gdb}, etc), do:
450 ./configure @var{xxx} +target=vxworks960
453 This will configure your system to cross-compile for VxWorks on
454 the Intel 960, which is probably not what you really want, but it's
455 a test case that works at this stage. (You haven't set up to be
456 able to debug programs that run @emph{on} @var{xxx} yet.)
458 If this succeeds, you can try building it all with:
464 Repeat until the program configures, compiles, links, and runs.
465 When run, it won't be able to do much (unless you have a VxWorks/960
466 board on your network) but you will know that the host support is
469 Good luck! Comments and suggestions about this section are particularly
470 welcome; send them to @samp{bug-gdb@@prep.ai.mit.edu}.
473 @chapter Adding a New Native Configuration
475 If you are making GDB run native on the @var{xxx} machine, you have
476 plenty more work to do. Several files control GDB's configuration for
480 @item gdb/config/@var{xarch}/@var{xxx}.mh
481 Specifies Makefile fragments needed when hosting @emph{or native}
482 on machine @var{xxx}.
483 In particular, this lists the required native-dependent object files,
484 by defining @samp{NATDEPFILES=@dots{}}. Also
485 specifies the header file which describes native support on @var{xxx},
486 by defining @samp{NAT_FILE= nm-@var{xxx}.h}.
487 You can also define @samp{NAT_CFLAGS},
488 @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS}, @samp{NAT_CDEPS},
489 etc.; see @file{Makefile.in}.
491 @item gdb/config/@var{arch}/nm-@var{xxx}.h
492 (@file{nm.h} is a link to this file, created by configure).
493 Contains C macro definitions describing the native system environment,
494 such as child process control and core file support.
495 Crib from existing @file{nm-*.h} files to create a new one.
497 @item gdb/@var{xxx}-nat.c
498 Contains any miscellaneous C code required for this native support
499 of this machine. On some machines it doesn't exist at all.
502 @subheading Generic Native Support Files
504 There are some ``generic'' versions of routines that can be used by
505 various systems. These can be customized in various ways by macros
506 defined in your @file{nm-@var{xxx}.h} file. If these routines work for
507 the @var{xxx} host, you can just include the generic file's name (with
508 @samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.
510 Otherwise, if your machine needs custom support routines, you will need
511 to write routines that perform the same functions as the generic file.
512 Put them into @code{@var{xxx}-nat.c}, and put @code{@var{xxx}-nat.o}
513 into @code{NATDEPFILES}.
518 This contains the @emph{target_ops vector} that supports Unix child
519 processes on systems which use ptrace and wait to control the child.
522 This contains the @emph{target_ops vector} that supports Unix child
523 processes on systems which use /proc to control the child.
526 This does the low-level grunge that uses Unix system calls
527 to do a "fork and exec" to start up a child process.
530 This is the low level interface to inferior processes for systems
531 using the Unix @code{ptrace} call in a vanilla way.
533 @item coredep.c::fetch_core_registers()
534 Support for reading registers out of a core file. This routine calls
535 @code{register_addr()}, see below.
536 Now that BFD is used to read core files, virtually all machines should
537 use @code{coredep.c}, and should just provide @code{fetch_core_registers} in
538 @code{@var{xxx}-nat.c} (or @code{REGISTER_U_ADDR} in @code{nm-@var{xxx}.h}).
540 @item coredep.c::register_addr()
541 If your @code{nm-@var{xxx}.h} file defines the macro
542 @code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
543 set @code{addr} to the offset within the @samp{user}
544 struct of GDB register number @code{regno}. @code{blockend} is the
545 offset within the ``upage'' of @code{u.u_ar0}.
546 If @code{REGISTER_U_ADDR} is defined,
547 @file{coredep.c} will define the @code{register_addr()} function and use
548 the macro in it. If you do not define @code{REGISTER_U_ADDR}, but you
549 are using the standard @code{fetch_core_registers()}, you will need to
550 define your own version of @code{register_addr()}, put it into your
551 @code{@var{xxx}-nat.c} file, and be sure @code{@var{xxx}-nat.o} is in
552 the @code{NATDEPFILES} list. If you have your own
553 @code{fetch_core_registers()}, you may not need a separate
554 @code{register_addr()}. Many custom @code{fetch_core_registers()}
555 implementations simply locate the registers themselves.@refill
558 When making GDB run native on a new operating system,
559 to make it possible to debug
560 core files, you will need to either write specific code for parsing your
561 OS's core files, or customize @file{bfd/trad-core.c}. First, use
562 whatever @code{#include} files your machine uses to define the struct of
563 registers that is accessible (possibly in the u-area) in a core file
564 (rather than @file{machine/reg.h}), and an include file that defines whatever
565 header exists on a core file (e.g. the u-area or a @samp{struct core}). Then
566 modify @code{trad_unix_core_file_p()} to use these values to set up the
567 section information for the data segment, stack segment, any other
568 segments in the core file (perhaps shared library contents or control
569 information), ``registers'' segment, and if there are two discontiguous
570 sets of registers (e.g. integer and float), the ``reg2'' segment. This
571 section information basically delimits areas in the core file in a
572 standard way, which the section-reading routines in BFD know how to seek
575 Then back in GDB, you need a matching routine called
576 @code{fetch_core_registers()}. If you can use the generic one, it's in
577 @file{coredep.c}; if not, it's in your @file{@var{xxx}-nat.c} file.
578 It will be passed a char pointer to the entire ``registers'' segment,
579 its length, and a zero; or a char pointer to the entire ``regs2''
580 segment, its length, and a 2. The routine should suck out the supplied
581 register values and install them into GDB's ``registers'' array.
582 (@xref{New Architectures,,Defining a New Host or Target Architecture},
583 for more info about this.)
585 If your system uses @file{/proc} to control processes, and uses ELF
586 format core files, then you may be able to use the same routines
587 for reading the registers out of processes and out of core files.
590 @chapter Adding a New Target
592 For a new target called @var{ttt}, first specify the configuration as
593 described in @ref{Config,,Adding a New Configuration}. If your new
594 target is the same as your new host, you've probably already done that.
596 A variety of files specify attributes of the GDB target environment:
599 @item gdb/config/@var{arch}/@var{ttt}.mt
600 Contains a Makefile fragment specific to this target.
601 Specifies what object files are needed for target @var{ttt}, by
602 defining @samp{TDEPFILES=@dots{}}.
603 Also specifies the header file which describes @var{ttt}, by defining
604 @samp{TM_FILE= tm-@var{ttt}.h}. You can also define @samp{TM_CFLAGS},
605 @samp{TM_CLIBS}, @samp{TM_CDEPS},
606 and other Makefile variables here; see @file{Makefile.in}.
608 @item gdb/config/@var{arch}/tm-@var{ttt}.h
609 (@file{tm.h} is a link to this file, created by configure).
610 Contains macro definitions about the target machine's
611 registers, stack frame format and instructions.
612 Crib from existing @file{tm-*.h} files when building a new one.
614 @item gdb/@var{ttt}-tdep.c
615 Contains any miscellaneous code required for this target machine.
616 On some machines it doesn't exist at all. Sometimes the macros
617 in @file{tm-@var{ttt}.h} become very complicated, so they are
618 implemented as functions here instead, and the macro is simply
619 defined to call the function.
622 Defines functions for accessing files that are
623 executable on the target system. These functions open and examine an
624 exec file, extract data from one, write data to one, print information
625 about one, etc. Now that executable files are handled with BFD, every
626 target should be able to use the generic exec.c rather than its
629 @item gdb/@var{arch}-pinsn.c
630 Prints (disassembles) the target machine's instructions.
631 This file is usually shared with other target machines which use the
632 same processor, which is why it is @file{@var{arch}-pinsn.c} rather
633 than @file{@var{ttt}-pinsn.c}.
635 @item gdb/@var{arch}-opcode.h
636 Contains some large initialized
637 data structures describing the target machine's instructions.
638 This is a bit strange for a @file{.h} file, but it's OK since
639 it is only included in one place. @file{@var{arch}-opcode.h} is shared
640 between the debugger and the assembler, if the GNU assembler has been
641 ported to the target machine.
643 @item gdb/config/@var{arch}/tm-@var{arch}.h
644 This often exists to describe the basic layout of the target machine's
645 processor chip (registers, stack, etc).
646 If used, it is included by @file{tm-@var{xxx}.h}. It can
647 be shared among many targets that use the same processor.
649 @item gdb/@var{arch}-tdep.c
650 Similarly, there are often common subroutines that are shared by all
651 target machines that use this particular architecture.
654 When adding support for a new target machine, there are various areas
655 of support that might need change, or might be OK.
657 If you are using an existing object file format (a.out or COFF),
658 there is probably little to be done. See @file{bfd/doc/bfd.texinfo}
659 for more information on writing new a.out or COFF versions.
661 If you need to add a new object file format, you must first add it to
662 BFD. This is beyond the scope of this document right now. Basically
663 you must build a transfer vector (of type @code{bfd_target}), which will
664 mean writing all the required routines, and add it to the list in
665 @file{bfd/targets.c}.
667 You must then arrange for the BFD code to provide access to the
668 debugging symbols. Generally GDB will have to call swapping routines
669 from BFD and a few other BFD internal routines to locate the debugging
670 information. As much as possible, GDB should not depend on the BFD
671 internal data structures.
673 For some targets (e.g., COFF), there is a special transfer vector used
674 to call swapping routines, since the external data structures on various
675 platforms have different sizes and layouts. Specialized routines that
676 will only ever be implemented by one object file format may be called
677 directly. This interface should be described in a file
678 @file{bfd/libxxx.h}, which is included by GDB.
680 If you are adding a new operating system for an existing CPU chip, add a
681 @file{tm-@var{xos}.h} file that describes the operating system
682 facilities that are unusual (extra symbol table info; the breakpoint
683 instruction needed; etc). Then write a
684 @file{tm-@var{xarch}-@var{xos}.h} that just @code{#include}s
685 @file{tm-@var{xarch}.h} and @file{tm-@var{xos}.h}. (Now that we have
686 three-part configuration names, this will probably get revised to
687 separate the @var{xos} configuration from the @var{xarch}
692 @chapter Adding a Source Language to GDB
694 To add other languages to GDB's expression parser, follow the following steps:
697 @item Create the expression parser.
699 This should reside in a file @file{@var{lang}-exp.y}. Routines for building
700 parsed expressions into a @samp{union exp_element} list are in @file{parse.c}.
702 Since we can't depend upon everyone having Bison, and YACC produces
703 parsers that define a bunch of global names, the following lines
704 @emph{must} be included at the top of the YACC parser, to prevent
705 the various parsers from defining the same global names:
708 #define yyparse @var{lang}_parse
709 #define yylex @var{lang}_lex
710 #define yyerror @var{lang}_error
711 #define yylval @var{lang}_lval
712 #define yychar @var{lang}_char
713 #define yydebug @var{lang}_debug
714 #define yypact @var{lang}_pact
715 #define yyr1 @var{lang}_r1
716 #define yyr2 @var{lang}_r2
717 #define yydef @var{lang}_def
718 #define yychk @var{lang}_chk
719 #define yypgo @var{lang}_pgo
720 #define yyact @var{lang}_act
721 #define yyexca @var{lang}_exca
722 #define yyerrflag @var{lang}_errflag
723 #define yynerrs @var{lang}_nerrs
726 At the bottom of your parser, define a @code{struct language_defn} and
727 initialize it with the right values for your language. Define an
728 @code{initialize_@var{lang}} routine and have it call
729 @samp{add_language(@var{lang}_language_defn)} to tell the rest of GDB
730 that your language exists. You'll need some other supporting variables
731 and functions, which will be used via pointers from your
732 @code{@var{lang}_language_defn}. See the declaration of @code{struct
733 language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
734 for more information.
736 @item Add any evaluation routines, if necessary
738 If you need new opcodes (that represent the operations of the language),
739 add them to the enumerated type in @file{expression.h}. Add support
740 code for these operations in @code{eval.c:evaluate_subexp()}. Add cases
741 for new opcodes in two functions from @file{parse.c}:
742 @code{prefixify_subexp()} and @code{length_of_subexp()}. These compute
743 the number of @code{exp_element}s that a given operation takes up.
745 @item Update some existing code
747 Add an enumerated identifier for your language to the enumerated type
748 @code{enum language} in @file{defs.h}.
750 Update the routines in @file{language.c} so your language is included. These
751 routines include type predicates and such, which (in some cases) are
752 language dependent. If your language does not appear in the switch
753 statement, an error is reported.
755 Also included in @file{language.c} is the code that updates the variable
756 @code{current_language}, and the routines that translate the
757 @code{language_@var{lang}} enumerated identifier into a printable
760 Update the function @code{_initialize_language} to include your language. This
761 function picks the default language upon startup, so is dependent upon
762 which languages that GDB is built for.
764 Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
765 code so that the language of each symtab (source file) is set properly.
766 This is used to determine the language to use at each stack frame level.
767 Currently, the language is set based upon the extension of the source
768 file. If the language can be better inferred from the symbol
769 information, please set the language of the symtab in the symbol-reading
772 Add helper code to @code{expprint.c:print_subexp()} to handle any new
773 expression opcodes you have added to @file{expression.h}. Also, add the
774 printed representations of your operators to @code{op_print_tab}.
776 @item Add a place of call
778 Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
779 @code{parse.c:parse_exp_1()}.
781 @item Use macros to trim code
783 The user has the option of building GDB for some or all of the
784 languages. If the user decides to build GDB for the language
785 @var{lang}, then every file dependent on @file{language.h} will have the
786 macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to
787 leave out large routines that the user won't need if he or she is not
790 Note that you do not need to do this in your YACC parser, since if GDB
791 is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
792 compiled form of your parser) is not linked into GDB at all.
794 See the file @file{configure.in} for how GDB is configured for different
797 @item Edit @file{Makefile.in}
799 Add dependencies in @file{Makefile.in}. Make sure you update the macro
800 variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
801 not get linked in, or, worse yet, it may not get @code{tar}red into the
807 @chapter Configuring GDB for Release
809 From the top level directory (containing @file{gdb}, @file{bfd},
810 @file{libiberty}, and so on):
812 make -f Makefile.in gdb.tar.Z
815 This will properly configure, clean, rebuild any files that are
816 distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}),
817 and will then make a tarfile. (If the top level directory has already
818 beenn configured, you can just do @code{make gdb.tar.Z} instead.)
820 This procedure requires:
823 @item @code{makeinfo} (texinfo2 level)
826 @item @code{yacc} or @code{bison}
829 @dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.).
831 @subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
833 @file{gdb.texinfo} is currently marked up using the texinfo-2 macros,
834 which are not yet a default for anything (but we have to start using
837 For making paper, the only thing this implies is the right generation of
838 @file{texinfo.tex} needs to be included in the distribution.
840 For making info files, however, rather than duplicating the texinfo2
841 distribution, generate @file{gdb-all.texinfo} locally, and include the files
842 @file{gdb.info*} in the distribution. Note the plural; @code{makeinfo} will
843 split the document into one overall file and five or so included files.
846 @node Partial Symbol Tables
847 @chapter Partial Symbol Tables
849 GDB has three types of symbol tables.
852 @item full symbol tables (symtabs). These contain the main
853 information about symbols and addresses.
854 @item partial symbol tables (psymtabs). These contain enough
855 information to know when to read the corresponding
856 part of the full symbol table.
857 @item minimal symbol tables (msymtabs). These contain information
858 gleaned from non-debugging symbols.
861 This section describes partial symbol tables.
863 A psymtab is constructed by doing a very quick pass over an executable
864 file's debugging information. Small amounts of information are
865 extracted -- enough to identify which parts of the symbol table will
866 need to be re-read and fully digested later, when the user needs the
867 information. The speed of this pass causes GDB to start up very
868 quickly. Later, as the detailed rereading occurs, it occurs in small
869 pieces, at various times, and the delay therefrom is mostly invisible to
870 the user. (@xref{Symbol Reading}.)
872 The symbols that show up in a file's psymtab should be, roughly, those
873 visible to the debugger's user when the program is not running code from
874 that file. These include external symbols and types, static
875 symbols and types, and enum values declared at file scope.
877 The psymtab also contains the range of instruction addresses that the
878 full symbol table would represent.
880 The idea is that there are only two ways for the user (or much of
881 the code in the debugger) to reference a symbol:
886 (e.g. execution stops at some address which is inside a function
887 in this file). The address will be noticed to be in the
888 range of this psymtab, and the full symtab will be read in.
889 @code{find_pc_function}, @code{find_pc_line}, and other @code{find_pc_@dots{}}
890 functions handle this.
893 (e.g. the user asks to print a variable, or set a breakpoint on a
894 function). Global names and file-scope names will be found in the
895 psymtab, which will cause the symtab to be pulled in. Local names will
896 have to be qualified by a global name, or a file-scope name, in which
897 case we will have already read in the symtab as we evaluated the
898 qualifier. Or, a local symbol can be referenced when
899 we are "in" a local scope, in which case the first case applies.
900 @code{lookup_symbol} does most of the work here.
904 The only reason that psymtabs exist is to cause a symtab to be read in
905 at the right moment. Any symbol that can be elided from a psymtab,
906 while still causing that to happen, should not appear in it. Since
907 psymtabs don't have the idea of scope, you can't put local symbols in
908 them anyway. Psymtabs don't have the idea of the type of a symbol,
909 either, so types need not appear, unless they will be referenced by
912 It is a bug for GDB to behave one way when only a psymtab has been read,
913 and another way if the corresponding symtab has been read in. Such
914 bugs are typically caused by a psymtab that does not contain all the
915 visible symbols, or which has the wrong instruction address ranges.
917 The psymtab for a particular section of a symbol-file (objfile)
918 could be thrown away after the symtab has been read in. The symtab
919 should always be searched before the psymtab, so the psymtab will
920 never be used (in a bug-free environment). Currently,
921 psymtabs are allocated on an obstack, and all the psymbols themselves
922 are allocated in a pair of large arrays on an obstack, so there is
923 little to be gained by trying to free them unless you want to do a lot
929 Fundamental Types (e.g., FT_VOID, FT_BOOLEAN).
931 These are the fundamental types that gdb uses internally. Fundamental
932 types from the various debugging formats (stabs, ELF, etc) are mapped into
933 one of these. They are basically a union of all fundamental types that
934 gdb knows about for all the languages that gdb knows about.
936 Type Codes (e.g., TYPE_CODE_PTR, TYPE_CODE_ARRAY).
938 Each time gdb builds an internal type, it marks it with one of these
939 types. The type may be a fundamental type, such as TYPE_CODE_INT, or
940 a derived type, such as TYPE_CODE_PTR which is a pointer to another
941 type. Typically, several FT_* types map to one TYPE_CODE_* type, and
942 are distinguished by other members of the type struct, such as whether
943 the type is signed or unsigned, and how many bits it uses.
945 Builtin Types (e.g., builtin_type_void, builtin_type_char).
947 These are instances of type structs that roughly correspond to fundamental
948 types and are created as global types for gdb to use for various ugly
949 historical reasons. We eventually want to eliminate these. Note for
950 example that builtin_type_int initialized in gdbtypes.c is basically the
951 same as a TYPE_CODE_INT type that is initialized in c-lang.c for an
952 FT_INTEGER fundamental type. The difference is that the builtin_type is
953 not associated with any particular objfile, and only one instance exists,
954 while c-lang.c builds as many TYPE_CODE_INT types as needed, with each
955 one associated with some particular objfile.
957 @node BFD support for GDB
958 @chapter Binary File Descriptor Library Support for GDB
960 BFD provides support for GDB in several ways:
963 @item identifying executable and core files
964 BFD will identify a variety of file types, including a.out, coff, and
965 several variants thereof, as well as several kinds of core files.
967 @item access to sections of files
968 BFD parses the file headers to determine the names, virtual addresses,
969 sizes, and file locations of all the various named sections in files
970 (such as the text section or the data section). GDB simply calls
971 BFD to read or write section X at byte offset Y for length Z.
973 @item specialized core file support
974 BFD provides routines to determine the failing command name stored
975 in a core file, the signal with which the program failed, and whether
976 a core file matches (i.e. could be a core dump of) a particular executable
979 @item locating the symbol information
980 GDB uses an internal interface of BFD to determine where to find the
981 symbol information in an executable file or symbol-file. GDB itself
982 handles the reading of symbols, since BFD does not ``understand'' debug
983 symbols, but GDB uses BFD's cached information to find the symbols,
987 @c The interface for symbol reading is described in @ref{Symbol
988 @c Reading,,Symbol Reading}.
992 @chapter Symbol Reading
994 GDB reads symbols from "symbol files". The usual symbol file is the
995 file containing the program which gdb is debugging. GDB can be directed
996 to use a different file for symbols (with the ``symbol-file''
997 command), and it can also read more symbols via the ``add-file'' and ``load''
998 commands, or while reading symbols from shared libraries.
1000 Symbol files are initially opened by @file{symfile.c} using the BFD
1001 library. BFD identifies the type of the file by examining its header.
1002 @code{symfile_init} then uses this identification to locate a
1003 set of symbol-reading functions.
1005 Symbol reading modules identify themselves to GDB by calling
1006 @code{add_symtab_fns} during their module initialization. The argument
1007 to @code{add_symtab_fns} is a @code{struct sym_fns} which contains
1008 the name (or name prefix) of the symbol format, the length of the prefix,
1009 and pointers to four functions. These functions are called at various
1010 times to process symbol-files whose identification matches the specified
1013 The functions supplied by each module are:
1016 @item @var{xxx}_symfile_init(struct sym_fns *sf)
1018 Called from @code{symbol_file_add} when we are about to read a new
1019 symbol file. This function should clean up any internal state
1020 (possibly resulting from half-read previous files, for example)
1021 and prepare to read a new symbol file. Note that the symbol file
1022 which we are reading might be a new "main" symbol file, or might
1023 be a secondary symbol file whose symbols are being added to the
1024 existing symbol table.
1026 The argument to @code{@var{xxx}_symfile_init} is a newly allocated
1027 @code{struct sym_fns} whose @code{bfd} field contains the BFD
1028 for the new symbol file being read. Its @code{private} field
1029 has been zeroed, and can be modified as desired. Typically,
1030 a struct of private information will be @code{malloc}'d, and
1031 a pointer to it will be placed in the @code{private} field.
1033 There is no result from @code{@var{xxx}_symfile_init}, but it can call
1034 @code{error} if it detects an unavoidable problem.
1036 @item @var{xxx}_new_init()
1038 Called from @code{symbol_file_add} when discarding existing symbols.
1039 This function need only handle
1040 the symbol-reading module's internal state; the symbol table data
1041 structures visible to the rest of GDB will be discarded by
1042 @code{symbol_file_add}. It has no arguments and no result.
1043 It may be called after @code{@var{xxx}_symfile_init}, if a new symbol
1044 table is being read, or may be called alone if all symbols are
1045 simply being discarded.
1047 @item @var{xxx}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)
1049 Called from @code{symbol_file_add} to actually read the symbols from a
1050 symbol-file into a set of psymtabs or symtabs.
1052 @code{sf} points to the struct sym_fns originally passed to
1053 @code{@var{xxx}_sym_init} for possible initialization. @code{addr} is the
1054 offset between the file's specified start address and its true address
1055 in memory. @code{mainline} is 1 if this is the main symbol table being
1056 read, and 0 if a secondary symbol file (e.g. shared library or
1057 dynamically loaded file) is being read.@refill
1060 In addition, if a symbol-reading module creates psymtabs when
1061 @var{xxx}_symfile_read is called, these psymtabs will contain a pointer to
1062 a function @code{@var{xxx}_psymtab_to_symtab}, which can be called from
1063 any point in the GDB symbol-handling code.
1066 @item @var{xxx}_psymtab_to_symtab (struct partial_symtab *pst)
1068 Called from @code{psymtab_to_symtab} (or the PSYMTAB_TO_SYMTAB
1069 macro) if the psymtab has not already been read in and had its
1070 @code{pst->symtab} pointer set. The argument is the psymtab
1071 to be fleshed-out into a symtab. Upon return, pst->readin
1072 should have been set to 1, and pst->symtab should contain a
1073 pointer to the new corresponding symtab, or zero if there
1074 were no symbols in that part of the symbol file.
1081 Cleanups are a structured way to deal with things that need to be done
1082 later. When your code does something (like @code{malloc} some memory, or open
1083 a file) that needs to be undone later (e.g. free the memory or close
1084 the file), it can make a cleanup. The cleanup will be done at some
1085 future point: when the command is finished, when an error occurs, or
1086 when your code decides it's time to do cleanups.
1088 You can also discard cleanups, that is, throw them away without doing
1089 what they say. This is only done if you ask that it be done.
1094 @item struct cleanup *@var{old_chain};
1095 Declare a variable which will hold a cleanup chain handle.
1097 @item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
1098 Make a cleanup which will cause @var{function} to be called with @var{arg}
1099 (a @code{char *}) later. The result, @var{old_chain}, is a handle that can be
1100 passed to @code{do_cleanups} or @code{discard_cleanups} later. Unless you are
1101 going to call @code{do_cleanups} or @code{discard_cleanups} yourself,
1102 you can ignore the result from @code{make_cleanup}.
1105 @item do_cleanups (@var{old_chain});
1106 Perform all cleanups done since @code{make_cleanup} returned @var{old_chain}.
1109 make_cleanup (a, 0);
1110 old = make_cleanup (b, 0);
1114 will call @code{b()} but will not call @code{a()}. The cleanup that calls @code{a()} will remain
1115 in the cleanup chain, and will be done later unless otherwise discarded.@refill
1117 @item discard_cleanups (@var{old_chain});
1118 Same as @code{do_cleanups} except that it just removes the cleanups from the
1119 chain and does not call the specified functions.
1123 Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify that they
1124 ``should not be called when cleanups are not in place''. This means
1125 that any actions you need to reverse in the case of an error or
1126 interruption must be on the cleanup chain before you call these functions,
1127 since they might never return to your code (they @samp{longjmp} instead).
1131 @chapter Wrapping Output Lines
1133 Output that goes through @code{printf_filtered} or @code{fputs_filtered} or
1134 @code{fputs_demangled} needs only to have calls to @code{wrap_here} added
1135 in places that would be good breaking points. The utility routines
1136 will take care of actually wrapping if the line width is exceeded.
1138 The argument to @code{wrap_here} is an indentation string which is printed
1139 @emph{only} if the line breaks there. This argument is saved away and used
1140 later. It must remain valid until the next call to @code{wrap_here} or
1141 until a newline has been printed through the @code{*_filtered} functions.
1142 Don't pass in a local variable and then return!
1144 It is usually best to call @code{wrap_here()} after printing a comma or space.
1145 If you call it before printing a space, make sure that your indentation
1146 properly accounts for the leading space that will print if the line wraps
1149 Any function or set of functions that produce filtered output must finish
1150 by printing a newline, to flush the wrap buffer, before switching to
1151 unfiltered (``@code{printf}'') output. Symbol reading routines that print
1152 warnings are a good example.
1158 A frame is a construct that GDB uses to keep track of calling and called
1163 in the machine description has no meaning to the machine-independent
1164 part of GDB, except that it is used when setting up a new frame from
1165 scratch, as follows:
1168 create_new_frame (read_register (FP_REGNUM), read_pc ()));
1171 Other than that, all the meaning imparted to @code{FP_REGNUM} is imparted by
1172 the machine-dependent code. So, @code{FP_REGNUM} can have any value that
1173 is convenient for the code that creates new frames. (@code{create_new_frame}
1174 calls @code{INIT_EXTRA_FRAME_INFO} if it is defined; that is where you should
1175 use the @code{FP_REGNUM} value, if your frames are nonstandard.)
1178 Given a GDB frame, determine the address of the calling function's
1179 frame. This will be used to create a new GDB frame struct, and then
1180 @code{INIT_EXTRA_FRAME_INFO} and @code{INIT_FRAME_PC} will be called for
1185 @chapter Remote Stubs
1187 GDB's file @file{remote.c} talks a serial protocol to code that runs
1188 in the target system. GDB provides several sample ``stubs'' that can
1189 be integrated into target programs or operating systems for this purpose;
1190 they are named @file{*-stub.c}.
1192 The GDB user's manual describes how to put such a stub into your target
1193 code. What follows is a discussion of integrating the SPARC stub
1194 into a complicated operating system (rather than a simple program),
1195 by Stu Grossman, the author of this stub.
1197 The trap handling code in the stub assumes the following upon entry to
1201 @item %l1 and %l2 contain pc and npc respectively at the time of the trap
1202 @item traps are disabled
1203 @item you are in the correct trap window
1206 As long as your trap handler can guarantee those conditions, then there is no
1207 reason why you shouldn't be able to `share' traps with the stub. The stub has
1208 no requirement that it be jumped to directly from the hardware trap vector.
1209 That is why it calls @code{exceptionHandler()}, which is provided by the external
1210 environment. For instance, this could setup the hardware traps to actually
1211 execute code which calls the stub first, and then transfers to its own trap
1214 For the most point, there probably won't be much of an issue with `sharing'
1215 traps, as the traps we use are usually not used by the kernel, and often
1216 indicate unrecoverable error conditions. Anyway, this is all controlled by a
1217 table, and is trivial to modify.
1218 The most important trap for us is for @code{ta 1}. Without that, we
1219 can't single step or do breakpoints. Everything else is unnecessary
1220 for the proper operation of the debugger/stub.
1222 From reading the stub, it's probably not obvious how breakpoints work. They
1223 are simply done by deposit/examine operations from GDB.
1225 @node Longjmp Support
1226 @chapter Longjmp Support
1228 GDB has support for figuring out that the target is doing a
1229 @code{longjmp} and for stopping at the target of the jump, if we are
1230 stepping. This is done with a few specialized internal breakpoints,
1231 which are visible in the @code{maint info breakpoint} command.
1233 To make this work, you need to define a macro called
1234 @code{GET_LONGJMP_TARGET}, which will examine the @code{jmp_buf}
1235 structure and extract the longjmp target address. Since @code{jmp_buf}
1236 is target specific, you will need to define it in the appropriate
1237 @file{tm-xxx.h} file. Look in @file{tm-sun4os4.h} and
1238 @file{sparc-tdep.c} for examples of how to do this.
1241 @chapter Coding Style
1243 GDB is generally written using the GNU coding standards, as described in
1244 @file{standards.texi}, which is available for anonymous FTP from GNU
1245 archive sites. There are some additional considerations for GDB
1246 maintainers that reflect the unique environment and style of GDB
1247 maintenance. If you follow these guidelines, GDB will be more
1248 consistent and easier to maintain.
1250 GDB's policy on the use of prototypes is that prototypes are used
1251 to @emph{declare} functions but never to @emph{define} them. Simple
1252 macros are used in the declarations, so that a non-ANSI compiler can
1253 compile GDB without trouble. The simple macro calls are used like
1258 memory_remove_breakpoint PARAMS ((CORE_ADDR, char *));
1261 Note the double parentheses around the parameter types. This allows
1262 an arbitrary number of parameters to be described, without freaking
1263 out the C preprocessor. When the function has no parameters, it
1264 should be described like:
1268 noprocess PARAMS ((void));
1271 The @code{PARAMS} macro expands to its argument in ANSI C, or to a simple
1272 @code{()} in traditional C.
1274 All external functions should have a @code{PARAMS} declaration in a
1275 header file that callers include. All static functions should have such
1276 a declaration near the top of their source file.
1278 We don't have a gcc option that will properly check that these rules
1279 have been followed, but it's GDB policy, and we periodically check it
1280 using the tools available (plus manual labor), and clean up any remnants.
1283 @chapter Clean Design
1285 In addition to getting the syntax right, there's the little question of
1286 semantics. Some things are done in certain ways in GDB because long
1287 experience has shown that the more obvious ways caused various kinds of
1288 trouble. In particular:
1292 You can't assume the byte order of anything that comes from a
1293 target (including @var{value}s, object files, and instructions). Such
1294 things must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in GDB,
1295 or one of the swap routines defined in @file{bfd.h}, such as @code{bfd_get_32}.
1298 You can't assume that you know what interface is being used to talk to
1299 the target system. All references to the target must go through the
1300 current @code{target_ops} vector.
1303 You can't assume that the host and target machines are the same machine
1304 (except in the ``native'' support modules).
1305 In particular, you can't assume that the target machine's header files
1306 will be available on the host machine. Target code must bring along its
1307 own header files -- written from scratch or explicitly donated by their
1308 owner, to avoid copyright problems.
1311 Insertion of new @code{#ifdef}'s will be frowned upon. It's much better
1312 to write the code portably than to conditionalize it for various systems.
1315 New @code{#ifdef}'s which test for specific compilers or manufacturers
1316 or operating systems are unacceptable. All @code{#ifdef}'s should test
1317 for features. The information about which configurations contain which
1318 features should be segregated into the configuration files. Experience
1319 has proven far too often that a feature unique to one particular system
1320 often creeps into other systems; and that a conditional based on
1321 some predefined macro for your current system will become worthless
1322 over time, as new versions of your system come out that behave differently
1323 with regard to this feature.
1326 Adding code that handles specific architectures, operating systems, target
1327 interfaces, or hosts, is not acceptable in generic code. If a hook
1328 is needed at that point, invent a generic hook and define it for your
1329 configuration, with something like:
1332 #ifdef WRANGLE_SIGNALS
1333 WRANGLE_SIGNALS (signo);
1337 In your host, target, or native configuration file, as appropriate,
1338 define @code{WRANGLE_SIGNALS} to do the machine-dependent thing. Take
1339 a bit of care in defining the hook, so that it can be used by other
1340 ports in the future, if they need a hook in the same place.
1342 If the hook is not defined, the code should do whatever "most" machines
1343 want. Using @code{#ifdef}, as above, is the preferred way to do this,
1344 but sometimes that gets convoluted, in which case use
1347 #ifndef SPECIAL_FOO_HANDLING
1348 #define SPECIAL_FOO_HANDLING(pc, sp) (0)
1352 where the macro is used or in an appropriate header file.
1354 Whether to include a @dfn{small} hook, a hook around the exact pieces of
1355 code which are system-dependent, or whether to replace a whole function
1356 with a hook depends on the case. A good example of this dilemma can be
1357 found in @code{get_saved_register}. All machines that GDB 2.8 ran on
1358 just needed the @code{FRAME_FIND_SAVED_REGS} hook to find the saved
1359 registers. Then the SPARC and Pyramid came along, and
1360 @code{HAVE_REGISTER_WINDOWS} and @code{REGISTER_IN_WINDOW_P} were
1361 introduced. Then the 29k and 88k required the @code{GET_SAVED_REGISTER}
1362 hook. The first three are examples of small hooks; the latter replaces
1363 a whole function. In this specific case, it is useful to have both
1364 kinds; it would be a bad idea to replace all the uses of the small hooks
1365 with @code{GET_SAVED_REGISTER}, since that would result in much
1366 duplicated code. Other times, duplicating a few lines of code here or
1367 there is much cleaner than introducing a large number of small hooks.
1369 Another way to generalize GDB along a particular interface is with an
1370 attribute struct. For example, GDB has been generalized to handle
1371 multiple kinds of remote interfaces -- not by #ifdef's everywhere, but
1372 by defining the "target_ops" structure and having a current target (as
1373 well as a stack of targets below it, for memory references). Whenever
1374 something needs to be done that depends on which remote interface we are
1375 using, a flag in the current target_ops structure is tested (e.g.
1376 `target_has_stack'), or a function is called through a pointer in the
1377 current target_ops structure. In this way, when a new remote interface
1378 is added, only one module needs to be touched -- the one that actually
1379 implements the new remote interface. Other examples of
1380 attribute-structs are BFD access to multiple kinds of object file
1381 formats, or GDB's access to multiple source languages.
1383 Please avoid duplicating code. For example, in GDB 3.x all the code
1384 interfacing between @code{ptrace} and the rest of GDB was duplicated in
1385 @file{*-dep.c}, and so changing something was very painful. In GDB 4.x,
1386 these have all been consolidated into @file{infptrace.c}.
1387 @file{infptrace.c} can deal with variations between systems the same way
1388 any system-independent file would (hooks, #if defined, etc.), and
1389 machines which are radically different don't need to use infptrace.c at
1393 @emph{Do} write code that doesn't depend on the sizes of C data types,
1394 the format of the host's floating point numbers, the alignment of anything,
1395 or the order of evaluation of expressions. In short, follow good
1396 programming practices for writing portable C code.
1400 @node Submitting Patches
1401 @chapter Submitting Patches
1403 Thanks for thinking of offering your changes back to the community of
1404 GDB users. In general we like to get well designed enhancements.
1405 Thanks also for checking in advance about the best way to transfer the
1408 The two main problems with getting your patches in are,
1412 The GDB maintainers will only install ``cleanly designed'' patches.
1413 You may not always agree on what is clean design.
1414 @pxref{Coding Style}, @pxref{Clean Design}.
1417 If the maintainers don't have time to put the patch in when it
1418 arrives, or if there is any question about a patch, it
1419 goes into a large queue with everyone else's patches and
1423 I don't know how to get past these problems except by continuing to try.
1425 There are two issues here -- technical and legal.
1427 The legal issue is that to incorporate substantial changes requires a
1428 copyright assignment from you and/or your employer, granting ownership
1429 of the changes to the Free Software Foundation. You can get the
1430 standard document for doing this by sending mail to
1431 @code{gnu@@prep.ai.mit.edu} and asking for it. I recommend that people
1432 write in "All programs owned by the Free Software Foundation" as "NAME
1433 OF PROGRAM", so that changes in many programs (not just GDB, but GAS,
1434 Emacs, GCC, etc) can be contributed with only one piece of legalese
1435 pushed through the bureacracy and filed with the FSF. I can't start
1436 merging changes until this paperwork is received by the FSF (their
1437 rules, which I follow since I maintain it for them).
1439 Technically, the easiest way to receive changes is to receive each
1440 feature as a small context diff or unidiff, suitable for "patch".
1441 Each message sent to me should include the changes to C code and
1442 header files for a single feature, plus ChangeLog entries for each
1443 directory where files were modified, and diffs for any changes needed
1444 to the manuals (gdb/doc/gdb.texi or gdb/doc/gdbint.texi). If there
1445 are a lot of changes for a single feature, they can be split down
1446 into multiple messages.
1448 In this way, if I read and like the feature, I can add it to the
1449 sources with a single patch command, do some testing, and check it in.
1450 If you leave out the ChangeLog, I have to write one. If you leave
1451 out the doc, I have to puzzle out what needs documenting. Etc.
1453 The reason to send each change in a separate message is that I will
1454 not install some of the changes. They'll be returned to you with
1455 questions or comments. If I'm doing my job, my message back to you
1456 will say what you have to fix in order to make the change acceptable.
1457 The reason to have separate messages for separate features is so
1458 that other changes (which I @emph{am} willing to accept) can be installed
1459 while one or more changes are being reworked. If multiple features
1460 are sent in a single message, I tend to not put in the effort to sort
1461 out the acceptable changes from the unacceptable, so none of the
1462 features get installed until all are acceptable.
1464 If this sounds painful or authoritarian, well, it is. But I get a lot
1465 of bug reports and a lot of patches, and most of them don't get
1466 installed because I don't have the time to finish the job that the bug
1467 reporter or the contributor could have done. Patches that arrive
1468 complete, working, and well designed, tend to get installed on the day
1469 they arrive. The others go into a queue and get installed if and when
1470 I scan back over the queue -- which can literally take months
1471 sometimes. It's in both our interests to make patch installation easy
1472 -- you get your changes installed, and I make some forward progress on
1473 GDB in a normal 12-hour day (instead of them having to wait until I
1474 have a 14-hour or 16-hour day to spend cleaning up patches before I
1477 Please send patches to @code{bug-gdb@@prep.ai.mit.edu}, if they are less
1478 than about 25,000 characters. If longer than that, either make them
1479 available somehow (e.g. anonymous FTP), and announce it on
1480 @code{bug-gdb}, or send them directly to the GDB maintainers at
1481 @code{gdb-patches@@cygnus.com}.
1483 @node Host Conditionals
1484 @chapter Host Conditionals
1486 When GDB is configured and compiled, various macros are defined or left
1487 undefined, to control compilation based on the attributes of the host
1488 system. These macros and their meanings are:
1490 @emph{NOTE: For now, both host and target conditionals are here.
1491 Eliminate target conditionals from this list as they are identified.}
1496 @item BLOCK_ADDRESS_FUNCTION_RELATIVE
1498 @item GDBINIT_FILENAME
1502 @item MEM_FNS_DECLARED
1503 Your host config file defines this if it includes
1504 declarations of @code{memcpy} and @code{memset}. Define this
1505 to avoid conflicts between the native include
1506 files and the declarations in @file{defs.h}.
1509 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1511 @item SIGWINCH_HANDLER_BODY
1529 @item ADDITIONAL_OPTIONS
1531 @item ADDITIONAL_OPTION_CASES
1533 @item ADDITIONAL_OPTION_HANDLER
1535 @item ADDITIONAL_OPTION_HELP
1537 @item ADDR_BITS_REMOVE
1539 @item AIX_BUGGY_PTRACE_CONTINUE
1541 @item ALIGN_STACK_ON_STARTUP
1553 @item BEFORE_MAIN_LOOP_HOOK
1555 @item BELIEVE_PCC_PROMOTION
1557 @item BELIEVE_PCC_PROMOTION_TYPE
1561 @item BITS_BIG_ENDIAN
1565 @item BLOCK_ADDRESS_ABSOLUTE
1571 @item BREAKPOINT_DEBUG
1573 @item BROKEN_LARGE_ALLOCA
1574 Avoid large @code{alloca}'s. For example, on sun's, Large alloca's fail
1575 because the attempt to increase the stack limit in main() fails because
1576 shared libraries are allocated just below the initial stack limit. The
1577 SunOS kernel will not allow the stack to grow into the area occupied by
1578 the shared libraries.
1583 @item CALL_DUMMY_LOCATION
1585 @item CALL_DUMMY_STACK_ADJUST
1587 @item CANNOT_FETCH_REGISTER
1589 @item CANNOT_STORE_REGISTER
1591 @item CFRONT_PRODUCER
1593 @item CHILD_PREPARE_TO_STORE
1595 @item CLEAR_DEFERRED_STORES
1599 @item COFF_ENCAPSULATE
1603 @item CORE_NEEDS_RELOCATION
1607 @item CREATE_INFERIOR_HOOK
1615 @item DBX_PARM_SYMBOL_CLASS
1623 @item DECR_PC_AFTER_BREAK
1625 @item DEFAULT_PROMPT
1633 @item DISABLE_UNSETTABLE_BREAK
1635 @item DONT_USE_REMOTE
1637 @item DO_DEFERRED_STORES
1639 @item DO_REGISTERS_INFO
1641 @item END_OF_TEXT_DEFAULT
1645 @item EXTRACT_RETURN_VALUE
1647 @item EXTRACT_STRUCT_VALUE_ADDRESS
1649 @item EXTRA_FRAME_INFO
1651 @item EXTRA_SYMTAB_INFO
1653 @item FILES_INFO_HOOK
1667 @item FRAMELESS_FUNCTION_INVOCATION
1669 @item FRAME_ARGS_ADDRESS_CORRECT
1671 @item FRAME_CHAIN_COMBINE
1673 @item FRAME_CHAIN_VALID
1675 @item FRAME_CHAIN_VALID_ALTERNATE
1677 @item FRAME_FIND_SAVED_REGS
1679 @item FRAME_GET_BASEREG_VALUE
1681 @item FRAME_NUM_ARGS
1683 @item FRAME_SPECIFICATION_DYADIC
1685 @item FUNCTION_EPILOGUE_SIZE
1689 @item GCC2_COMPILED_FLAG_SYMBOL
1691 @item GCC_COMPILED_FLAG_SYMBOL
1693 @item GCC_MANGLE_BUG
1697 @item GET_SAVED_REGISTER
1699 @item GPLUS_PRODUCER
1710 In some cases, use the system call @code{mmap} for reading symbol
1711 tables. For some machines this allows for sharing and quick updates.
1712 @item HAVE_REGISTER_WINDOWS
1714 @item HAVE_SIGSETMASK
1718 @item HEADER_SEEK_FD
1722 @item HOST_BYTE_ORDER
1726 @item HPUX_VERSION_5
1738 @item INIT_EXTRA_FRAME_INFO
1740 @item INIT_EXTRA_SYMTAB_INFO
1754 @item IN_SOLIB_TRAMPOLINE
1758 @item IS_TRAPPED_INTERNALVAR
1762 @item KERNEL_DEBUGGING
1765 Define this to the address of the @code{u} structure (the ``user struct'',
1766 also known as the ``u-page'') in kernel virtual memory. GDB needs to know
1767 this so that it can subtract this address from absolute addresses in
1768 the upage, that are obtained via ptrace or from core files. On systems
1769 that don't need this value, set it to zero.
1770 @item KERNEL_U_ADDR_BSD
1771 Define this to cause GDB to determine the address of @code{u} at runtime,
1772 by using Berkeley-style @code{nlist} on the kernel's image in the root
1774 @item KERNEL_U_ADDR_HPUX
1775 Define this to cause GDB to determine the address of @code{u} at runtime,
1776 by using HP-style @code{nlist} on the kernel's image in the root
1792 @item LSEEK_NOT_LINEAR
1797 This macro is used as the argument to lseek (or, most commonly, bfd_seek).
1798 FIXME, it should be replaced by SEEK_SET instead, which is the POSIX equivalent.
1799 @item MACHKERNELDEBUG
1805 @item MAINTENANCE_CMDS
1807 @item MAINTENANCE_CMDS
1809 @item MALLOC_INCOMPATIBLE
1810 Define this if the system's prototype for @code{malloc} differs from the
1811 @sc{ANSI} definition.
1814 @item MMAP_BASE_ADDRESS
1815 When using HAVE_MMAP, the first mapping should go at this address.
1816 @item MMAP_INCREMENT
1817 when using HAVE_MMAP, this is the increment between mappings.
1824 @item NEED_POSIX_SETPGID
1826 @item NEED_TEXT_START_END
1840 @item NOTICE_SIGNAL_HANDLING_CHANGE
1842 @item NO_HIF_SUPPORT
1844 @item NO_JOB_CONTROL
1847 GDB will use the @code{mmalloc} library for memory allocation for symbol
1848 reading, unless this symbol is defined. Define it on systems
1849 on which @code{mmalloc} does not
1850 work for some reason. One example is the DECstation, where its RPC
1851 library can't cope with our redefinition of @code{malloc} to call
1852 @code{mmalloc}. When defining @code{NO_MMALLOC}, you will also have
1853 to override the setting of @code{MMALLOC_LIB} to empty, in the Makefile.
1854 Therefore, this define is usually set on the command line by overriding
1855 @code{MMALLOC_DISABLE} in @file{config/*/*.mh}, rather than by defining
1856 it in @file{xm-*.h}.
1857 @item NO_MMALLOC_CHECK
1858 Define this if you are using @code{mmalloc}, but don't want the overhead
1859 of checking the heap with @code{mmcheck}.
1860 @item NO_SIGINTERRUPT
1862 @item NO_SINGLE_STEP
1866 @item NS32K_SVC_IMMED_OPERANDS
1868 @item NUMERIC_REG_NAMES
1876 @item ONE_PROCESS_WRITETEXT
1884 @item PCC_SOL_BROKEN
1886 @item PC_IN_CALL_DUMMY
1888 @item PC_LOAD_SEGMENT
1892 @item PRINT_RANDOM_SIGNAL
1894 @item PRINT_REGISTER_HOOK
1896 @item PRINT_TYPELESS_INTEGER
1898 @item PROCESS_LINENUMBER_HOOK
1900 @item PROLOGUE_FIRSTLINE_OVERLAP
1902 @item PSIGNAL_IN_SIGNAL_H
1906 @item PUSH_ARGUMENTS
1908 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1912 @item PYRAMID_PTRACE
1914 @item REGISTER_BYTES
1916 @item REGISTER_NAMES
1918 @item REG_STACK_SEGMENT
1920 @item REG_STRUCT_HAS_ADDR
1928 @item SDB_REG_TO_REGNUM
1936 @item SET_STACK_LIMIT_HUGE
1937 When defined, stack limits will be raised to their maximum. Use this
1938 if your host supports @code{setrlimit} and you have trouble with
1939 @code{stringtab} in @file{dbxread.c}.
1941 Also used in @file{fork-child.c} to return stack limits before child
1942 processes are forked.
1943 @item SHELL_COMMAND_CONCAT
1947 @item SHIFT_INST_REGS
1949 @item SIGN_EXTEND_CHAR
1951 @item SIGTRAP_STOP_AFTER_LOAD
1955 @item SKIP_PROLOGUE_FRAMELESS_P
1957 @item SKIP_TRAMPOLINE_CODE
1961 @item SOLIB_CREATE_INFERIOR_HOOK
1965 @item STAB_REG_TO_REGNUM
1969 @item STACK_DIRECTION
1971 @item START_INFERIOR_TRAPS_EXPECTED
1975 @item STORE_RETURN_VALUE
1977 @item SUN4_COMPILER_FEATURE
1979 @item SUN_FIXED_LBRAC_BUG
1981 @item SVR4_SHARED_LIBS
1983 @item SWITCH_ENUM_BUG
1987 @item SYMBOL_RELOADING_DEFAULT
2007 @item TM_FILE_OVERRIDE
2023 @item USE_STRUCT_CONVENTION
2026 Means that System V (prior to SVR4) include files are in use.
2027 (FIXME: This symbol is abused in @file{infrun.c}, @file{regex.c},
2028 @file{remote-nindy.c}, and @file{utils.c} for other things, at the moment.)
2033 @item VARIABLES_INSIDE_BLOCK
2045 @item __HAVE_68881__
2049 @item __INT_VARARGS_H
2051 @item __not_on_pyr_yet
2067 @item longest_to_int
2097 @node Target Conditionals
2098 @chapter Target Conditionals
2100 When GDB is configured and compiled, various macros are defined or left
2101 undefined, to control compilation based on the attributes of the target
2102 system. These macros and their meanings are:
2104 @emph{NOTE: For now, both host and target conditionals are here.
2105 Eliminate host conditionals from this list as they are identified.}
2108 @item PUSH_DUMMY_FRAME
2109 Used in @samp{call_function_by_hand} to create an artificial stack frame.
2111 Used in @samp{call_function_by_hand} to remove an artificial stack frame.
2114 @item BLOCK_ADDRESS_FUNCTION_RELATIVE
2116 @item GDBINIT_FILENAME
2122 @item PYRAMID_CONTROL_FRAME_DEBUGGING
2124 @item SIGWINCH_HANDLER_BODY
2126 @item ADDITIONAL_OPTIONS
2128 @item ADDITIONAL_OPTION_CASES
2130 @item ADDITIONAL_OPTION_HANDLER
2132 @item ADDITIONAL_OPTION_HELP
2134 @item ADDR_BITS_REMOVE
2136 @item ALIGN_STACK_ON_STARTUP
2148 @item BEFORE_MAIN_LOOP_HOOK
2150 @item BELIEVE_PCC_PROMOTION
2152 @item BELIEVE_PCC_PROMOTION_TYPE
2156 @item BITS_BIG_ENDIAN
2160 @item BLOCK_ADDRESS_ABSOLUTE
2166 @item BREAKPOINT_DEBUG
2172 @item CALL_DUMMY_LOCATION
2174 @item CALL_DUMMY_STACK_ADJUST
2176 @item CANNOT_FETCH_REGISTER
2178 @item CANNOT_STORE_REGISTER
2180 @item CFRONT_PRODUCER
2182 @item CHILD_PREPARE_TO_STORE
2184 @item CLEAR_DEFERRED_STORES
2188 @item COFF_ENCAPSULATE
2192 @item CORE_NEEDS_RELOCATION
2196 @item CREATE_INFERIOR_HOOK
2204 @item DBX_PARM_SYMBOL_CLASS
2212 @item DECR_PC_AFTER_BREAK
2214 @item DEFAULT_PROMPT
2222 @item DISABLE_UNSETTABLE_BREAK
2224 @item DONT_USE_REMOTE
2226 @item DO_DEFERRED_STORES
2228 @item DO_REGISTERS_INFO
2230 @item END_OF_TEXT_DEFAULT
2234 @item EXTRACT_RETURN_VALUE
2236 @item EXTRACT_STRUCT_VALUE_ADDRESS
2238 @item EXTRA_FRAME_INFO
2240 @item EXTRA_SYMTAB_INFO
2242 @item FILES_INFO_HOOK
2257 Unused? 6-oct-92 rich@@cygnus.com. FIXME.
2258 @item FRAMELESS_FUNCTION_INVOCATION
2260 @item FRAME_ARGS_ADDRESS_CORRECT
2263 Given FRAME, return a pointer to the calling frame.
2264 @item FRAME_CHAIN_COMBINE
2266 @item FRAME_CHAIN_VALID
2268 @item FRAME_CHAIN_VALID_ALTERNATE
2270 @item FRAME_FIND_SAVED_REGS
2272 @item FRAME_GET_BASEREG_VALUE
2274 @item FRAME_NUM_ARGS
2276 @item FRAME_SPECIFICATION_DYADIC
2278 @item FRAME_SAVED_PC
2279 Given FRAME, return the pc saved there. That is, the return address.
2280 @item FUNCTION_EPILOGUE_SIZE
2284 @item GCC2_COMPILED_FLAG_SYMBOL
2286 @item GCC_COMPILED_FLAG_SYMBOL
2288 @item GCC_MANGLE_BUG
2292 @item GDB_TARGET_IS_HPPA
2293 This determines whether horrible kludge code in dbxread.c and partial-stab.h
2294 is used to mangle multiple-symbol-table files from HPPA's. This should all
2295 be ripped out, and a scheme like elfread.c used.
2296 @item GDB_TARGET_IS_MACH386
2298 @item GDB_TARGET_IS_SUN3
2300 @item GDB_TARGET_IS_SUN386
2302 @item GET_LONGJMP_TARGET
2303 For most machines, this is a target-dependent parameter. On the DECstation
2304 and the Iris, this is a native-dependent parameter, since <setjmp.h> is
2305 needed to define it.
2307 This macro determines the target PC address that longjmp() will jump
2308 to, assuming that we have just stopped at a longjmp breakpoint. It
2309 takes a CORE_ADDR * as argument, and stores the target PC value through
2310 this pointer. It examines the current state of the machine as needed.
2311 @item GET_SAVED_REGISTER
2313 @item GPLUS_PRODUCER
2323 @item HAVE_REGISTER_WINDOWS
2325 @item HAVE_SIGSETMASK
2329 @item HEADER_SEEK_FD
2333 @item HOST_BYTE_ORDER
2337 @item HPUX_VERSION_5
2343 @item IBM6000_TARGET
2344 Shows that we are configured for an IBM RS/6000 target. This conditional
2345 should be eliminated (FIXME) and replaced by feature-specific macros.
2346 It was introduced in haste and we are repenting at leisure.
2353 @item INIT_EXTRA_FRAME_INFO
2355 @item INIT_EXTRA_SYMTAB_INFO
2369 @item IN_SOLIB_TRAMPOLINE
2373 @item IS_TRAPPED_INTERNALVAR
2377 @item KERNEL_DEBUGGING
2395 @item MACHKERNELDEBUG
2401 @item MAINTENANCE_CMDS
2403 @item MAINTENANCE_CMDS
2411 @item NEED_POSIX_SETPGID
2413 @item NEED_TEXT_START_END
2427 @item NOTICE_SIGNAL_HANDLING_CHANGE
2429 @item NO_HIF_SUPPORT
2431 @item NO_SIGINTERRUPT
2433 @item NO_SINGLE_STEP
2436 xcoffread.c--This causes types not to be read, to save memory and speed
2440 @item NS32K_SVC_IMMED_OPERANDS
2442 @item NUMERIC_REG_NAMES
2450 @item ONE_PROCESS_WRITETEXT
2454 @item PCC_SOL_BROKEN
2456 @item PC_IN_CALL_DUMMY
2458 @item PC_LOAD_SEGMENT
2462 @item PRINT_RANDOM_SIGNAL
2464 @item PRINT_REGISTER_HOOK
2466 @item PRINT_TYPELESS_INTEGER
2468 @item PROCESS_LINENUMBER_HOOK
2470 @item PROLOGUE_FIRSTLINE_OVERLAP
2472 @item PSIGNAL_IN_SIGNAL_H
2476 @item PUSH_ARGUMENTS
2478 @item REGISTER_BYTES
2480 @item REGISTER_NAMES
2482 @item REG_STACK_SEGMENT
2484 @item REG_STRUCT_HAS_ADDR
2492 @item SDB_REG_TO_REGNUM
2500 @item SHELL_COMMAND_CONCAT
2504 @item SHIFT_INST_REGS
2506 @item SIGN_EXTEND_CHAR
2508 @item SIGTRAP_STOP_AFTER_LOAD
2512 @item SKIP_PROLOGUE_FRAMELESS_P
2514 @item SKIP_TRAMPOLINE_CODE
2518 @item SOLIB_CREATE_INFERIOR_HOOK
2522 @item STAB_REG_TO_REGNUM
2526 @item STACK_DIRECTION
2528 @item START_INFERIOR_TRAPS_EXPECTED
2532 @item STORE_RETURN_VALUE
2534 @item SUN4_COMPILER_FEATURE
2536 @item SUN_FIXED_LBRAC_BUG
2538 @item SVR4_SHARED_LIBS
2540 @item SWITCH_ENUM_BUG
2544 @item SYMBOL_RELOADING_DEFAULT
2550 @item TARGET_BYTE_ORDER
2552 @item TARGET_CHAR_BIT
2554 @item TARGET_COMPLEX_BIT
2556 @item TARGET_DOUBLE_BIT
2558 @item TARGET_DOUBLE_COMPLEX_BIT
2560 @item TARGET_FLOAT_BIT
2562 @item TARGET_INT_BIT
2564 @item TARGET_LONG_BIT
2566 @item TARGET_LONG_DOUBLE_BIT
2568 @item TARGET_LONG_LONG_BIT
2570 @item TARGET_PTR_BIT
2572 @item TARGET_SHORT_BIT
2576 @item TM_FILE_OVERRIDE
2588 @item USE_STRUCT_CONVENTION
2594 @item VARIABLES_INSIDE_BLOCK
2604 @item __HAVE_68881__
2608 @item __INT_VARARGS_H
2610 @item __not_on_pyr_yet
2620 @item longest_to_int
2644 @node Native Conditionals
2645 @chapter Native Conditionals
2647 When GDB is configured and compiled, various macros are defined or left
2648 undefined, to control compilation when the host and target systems
2649 are the same. These macros should be defined (or left undefined)
2650 in @file{nm-@var{system}.h}.
2654 If defined, then gdb will include support for the @code{attach} and
2655 @code{detach} commands.
2656 @item FETCH_INFERIOR_REGISTERS
2657 Define this if the native-dependent code will provide its
2659 @code{fetch_inferior_registers} and @code{store_inferior_registers} in
2660 @file{@var{HOST}-nat.c}.
2661 If this symbol is @emph{not} defined, and @file{infptrace.c}
2662 is included in this configuration, the default routines in
2663 @file{infptrace.c} are used for these functions.
2664 @item GET_LONGJMP_TARGET
2665 For most machines, this is a target-dependent parameter. On the DECstation
2666 and the Iris, this is a native-dependent parameter, since <setjmp.h> is
2667 needed to define it.
2669 This macro determines the target PC address that longjmp() will jump
2670 to, assuming that we have just stopped at a longjmp breakpoint. It
2671 takes a CORE_ADDR * as argument, and stores the target PC value through
2672 this pointer. It examines the current state of the machine as needed.
2674 Defines the format for the name of a @file{/proc} device. Should be
2675 defined in @file{nm.h} @emph{only} in order to override the default
2676 definition in @file{procfs.c}.
2679 @item PTRACE_ARG3_TYPE
2680 The type of the third argument to the @code{ptrace} system call, if it exists
2681 and is different from @code{int}.
2682 @item REGISTER_U_ADDR
2683 Defines the offset of the registers in the ``u area''; @pxref{Host}.
2685 This determines whether small routines in @file{*-tdep.c}, which
2686 translate register values
2687 between GDB's internal representation and the /proc representation,
2690 This is the offset of the registers in the upage. It need only be
2691 defined if the generic ptrace register access routines in
2692 @file{infptrace.c} are being used (that is,
2693 @file{infptrace.c} is configured in, and
2694 @code{FETCH_INFERIOR_REGISTERS} is not defined). If the default value
2695 from @file{infptrace.c} is good enough, leave it undefined.
2697 The default value means that u.u_ar0 @emph{points to} the location of the
2698 registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means that
2699 u.u_ar0 @emph{is} the location of the registers.
2702 @node Obsolete Conditionals
2703 @chapter Obsolete Conditionals
2705 Fragments of old code in GDB sometimes reference or set the following
2706 configuration macros. They should not be used by new code, and
2707 old uses should be removed as those parts of the debugger are
2711 @item STACK_END_ADDR
2712 This macro used to define where the end of the stack appeared, for use
2713 in interpreting core file formats that don't record this address in the
2714 core file itself. This information is now configured in BFD, and GDB
2715 gets the info portably from there. The values in GDB's configuration
2716 files should be moved into BFD configuration files (if needed there),
2717 and deleted from all of GDB's config files.
2719 Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
2720 is so old that it has never been converted to use BFD. Now that's old!
2724 @chapter The XCOFF Object File Format
2726 The IBM RS/6000 running AIX uses an object file format called xcoff.
2727 The COFF sections, symbols, and line numbers are used, but debugging
2728 symbols are dbx-style stabs whose strings are located in the
2729 @samp{.debug} section (rather than the string table). Files are
2730 indicated with a @samp{C_FILE} symbol (.file) which is analogous to
2731 @samp{N_SO}; include files are delimited with @samp{C_BINCL} (.bi) and
2732 @samp{C_EINCL} (.ei) which correspond to @samp{N_SOL} rather than Sun's
2733 @samp{N_BINCL} (that is, they don't nest and there is no equivalent to
2734 N_EXCL). The values of the @samp{C_BINCL} and @samp{C_EINCL} symbols
2735 are offsets into the executable file which point to the beginning and
2736 the end of the portion of the linetable which correspond to this include
2737 file (warning: C_EINCL is inclusive not exclusive like most end of
2738 something pointers). Other differences from standard stabs include the
2739 use of negative type numbers for builtin types.
2741 The shared library scheme has a nice clean interface for figuring out
2742 what shared libraries are in use, but the catch is that everything which
2743 refers to addresses (symbol tables and breakpoints at least) needs to be
2744 relocated for both shared libraries and the main executable. At least
2745 using the standard mechanism this can only be done once the program has
2746 been run (or the core file has been read).