1 \input texinfo @c -*- texinfo -*-
2 @setfilename gdbint.info
4 @dircategory Programming & development tools.
7 * Gdb-Internals: (gdbint). The GNU debugger's internals.
12 This file documents the internals of the GNU debugger @value{GDBN}.
13 Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001
14 Free Software Foundation, Inc.
15 Contributed by Cygnus Solutions. Written by John Gilmore.
16 Second Edition by Stan Shebs.
18 Permission is granted to copy, distribute and/or modify this document
19 under the terms of the GNU Free Documentation License, Version 1.1 or
20 any later version published by the Free Software Foundation; with the
21 Invariant Sections being ``Algorithms'' and ``Porting GDB'', with the
22 Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover
23 Texts as in (a) below.
25 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
26 this GNU Manual, like GNU software. Copies published by the Free
27 Software Foundation raise funds for GNU development.''
30 @setchapternewpage off
31 @settitle @value{GDBN} Internals
37 @title @value{GDBN} Internals
38 @subtitle{A guide to the internals of the GNU debugger}
40 @author Cygnus Solutions
41 @author Second Edition:
43 @author Cygnus Solutions
46 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
47 \xdef\manvers{\$Revision$} % For use in headers, footers too
49 \hfill Cygnus Solutions\par
51 \hfill \TeX{}info \texinfoversion\par
55 @vskip 0pt plus 1filll
56 Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001
57 Free Software Foundation, Inc.
59 Permission is granted to copy, distribute and/or modify this document
60 under the terms of the GNU Free Documentation License, Version 1.1 or
61 any later version published by the Free Software Foundation; with the
62 Invariant Sections being ``Algorithms'' and ``Porting GDB'', with the
63 Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover
64 Texts as in (a) below.
66 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
67 this GNU Manual, like GNU software. Copies published by the Free
68 Software Foundation raise funds for GNU development.''
71 @c TeX can handle the contents at the start but makeinfo 3.12 can not
77 @c Perhaps this should be the title of the document (but only for info,
78 @c not for TeX). Existing GNU manuals seem inconsistent on this point.
79 @top Scope of this Document
81 This document documents the internals of the GNU debugger, @value{GDBN}. It
82 includes description of @value{GDBN}'s key algorithms and operations, as well
83 as the mechanisms that adapt @value{GDBN} to specific hosts and targets.
93 * Target Architecture Definition::
94 * Target Vector Definition::
106 @chapter Requirements
107 @cindex requirements for @value{GDBN}
109 Before diving into the internals, you should understand the formal
110 requirements and other expectations for @value{GDBN}. Although some
111 of these may seem obvious, there have been proposals for @value{GDBN}
112 that have run counter to these requirements.
114 First of all, @value{GDBN} is a debugger. It's not designed to be a
115 front panel for embedded systems. It's not a text editor. It's not a
116 shell. It's not a programming environment.
118 @value{GDBN} is an interactive tool. Although a batch mode is
119 available, @value{GDBN}'s primary role is to interact with a human
122 @value{GDBN} should be responsive to the user. A programmer hot on
123 the trail of a nasty bug, and operating under a looming deadline, is
124 going to be very impatient of everything, including the response time
125 to debugger commands.
127 @value{GDBN} should be relatively permissive, such as for expressions.
128 While the compiler should be picky (or have the option to be made
129 picky), since source code lives for a long time usuazlly, the
130 programmer doing debugging shouldn't be spending time figuring out to
131 mollify the debugger.
133 @value{GDBN} will be called upon to deal with really large programs.
134 Executable sizes of 50 to 100 megabytes occur regularly, and we've
135 heard reports of programs approaching 1 gigabyte in size.
137 @value{GDBN} should be able to run everywhere. No other debugger is
138 available for even half as many configurations as @value{GDBN}
142 @node Overall Structure
144 @chapter Overall Structure
146 @value{GDBN} consists of three major subsystems: user interface,
147 symbol handling (the @dfn{symbol side}), and target system handling (the
150 The user interface consists of several actual interfaces, plus
153 The symbol side consists of object file readers, debugging info
154 interpreters, symbol table management, source language expression
155 parsing, type and value printing.
157 The target side consists of execution control, stack frame analysis, and
158 physical target manipulation.
160 The target side/symbol side division is not formal, and there are a
161 number of exceptions. For instance, core file support involves symbolic
162 elements (the basic core file reader is in BFD) and target elements (it
163 supplies the contents of memory and the values of registers). Instead,
164 this division is useful for understanding how the minor subsystems
167 @section The Symbol Side
169 The symbolic side of @value{GDBN} can be thought of as ``everything
170 you can do in @value{GDBN} without having a live program running''.
171 For instance, you can look at the types of variables, and evaluate
172 many kinds of expressions.
174 @section The Target Side
176 The target side of @value{GDBN} is the ``bits and bytes manipulator''.
177 Although it may make reference to symbolic info here and there, most
178 of the target side will run with only a stripped executable
179 available---or even no executable at all, in remote debugging cases.
181 Operations such as disassembly, stack frame crawls, and register
182 display, are able to work with no symbolic info at all. In some cases,
183 such as disassembly, @value{GDBN} will use symbolic info to present addresses
184 relative to symbols rather than as raw numbers, but it will work either
187 @section Configurations
191 @dfn{Host} refers to attributes of the system where @value{GDBN} runs.
192 @dfn{Target} refers to the system where the program being debugged
193 executes. In most cases they are the same machine, in which case a
194 third type of @dfn{Native} attributes come into play.
196 Defines and include files needed to build on the host are host support.
197 Examples are tty support, system defined types, host byte order, host
200 Defines and information needed to handle the target format are target
201 dependent. Examples are the stack frame format, instruction set,
202 breakpoint instruction, registers, and how to set up and tear down the stack
205 Information that is only needed when the host and target are the same,
206 is native dependent. One example is Unix child process support; if the
207 host and target are not the same, doing a fork to start the target
208 process is a bad idea. The various macros needed for finding the
209 registers in the @code{upage}, running @code{ptrace}, and such are all
210 in the native-dependent files.
212 Another example of native-dependent code is support for features that
213 are really part of the target environment, but which require
214 @code{#include} files that are only available on the host system. Core
215 file handling and @code{setjmp} handling are two common cases.
217 When you want to make @value{GDBN} work ``native'' on a particular machine, you
218 have to include all three kinds of information.
226 @value{GDBN} uses a number of debugging-specific algorithms. They are
227 often not very complicated, but get lost in the thicket of special
228 cases and real-world issues. This chapter describes the basic
229 algorithms and mentions some of the specific target definitions that
235 @cindex call stack frame
236 A frame is a construct that @value{GDBN} uses to keep track of calling
237 and called functions.
239 @findex create_new_frame
241 @code{FRAME_FP} in the machine description has no meaning to the
242 machine-independent part of @value{GDBN}, except that it is used when
243 setting up a new frame from scratch, as follows:
246 create_new_frame (read_register (FP_REGNUM), read_pc ()));
249 @cindex frame pointer register
250 Other than that, all the meaning imparted to @code{FP_REGNUM} is
251 imparted by the machine-dependent code. So, @code{FP_REGNUM} can have
252 any value that is convenient for the code that creates new frames.
253 (@code{create_new_frame} calls @code{INIT_EXTRA_FRAME_INFO} if it is
254 defined; that is where you should use the @code{FP_REGNUM} value, if
255 your frames are nonstandard.)
258 Given a @value{GDBN} frame, define @code{FRAME_CHAIN} to determine the
259 address of the calling function's frame. This will be used to create
260 a new @value{GDBN} frame struct, and then @code{INIT_EXTRA_FRAME_INFO}
261 and @code{INIT_FRAME_PC} will be called for the new frame.
263 @section Breakpoint Handling
266 In general, a breakpoint is a user-designated location in the program
267 where the user wants to regain control if program execution ever reaches
270 There are two main ways to implement breakpoints; either as ``hardware''
271 breakpoints or as ``software'' breakpoints.
273 @cindex hardware breakpoints
274 @cindex program counter
275 Hardware breakpoints are sometimes available as a builtin debugging
276 features with some chips. Typically these work by having dedicated
277 register into which the breakpoint address may be stored. If the PC
278 (shorthand for @dfn{program counter})
279 ever matches a value in a breakpoint registers, the CPU raises an
280 exception and reports it to @value{GDBN}.
282 Another possibility is when an emulator is in use; many emulators
283 include circuitry that watches the address lines coming out from the
284 processor, and force it to stop if the address matches a breakpoint's
287 A third possibility is that the target already has the ability to do
288 breakpoints somehow; for instance, a ROM monitor may do its own
289 software breakpoints. So although these are not literally ``hardware
290 breakpoints'', from @value{GDBN}'s point of view they work the same;
291 @value{GDBN} need not do nothing more than set the breakpoint and wait
292 for something to happen.
294 Since they depend on hardware resources, hardware breakpoints may be
295 limited in number; when the user asks for more, @value{GDBN} will
296 start trying to set software breakpoints. (On some architectures,
297 notably the 32-bit x86 platforms, @value{GDBN} cannot alsways know
298 whether there's enough hardware resources to insert all the hardware
299 breakpoints and watchpoints. On those platforms, @value{GDBN} prints
300 an error message only when the program being debugged is continued.)
302 @cindex software breakpoints
303 Software breakpoints require @value{GDBN} to do somewhat more work.
304 The basic theory is that @value{GDBN} will replace a program
305 instruction with a trap, illegal divide, or some other instruction
306 that will cause an exception, and then when it's encountered,
307 @value{GDBN} will take the exception and stop the program. When the
308 user says to continue, @value{GDBN} will restore the original
309 instruction, single-step, re-insert the trap, and continue on.
311 Since it literally overwrites the program being tested, the program area
312 must be writeable, so this technique won't work on programs in ROM. It
313 can also distort the behavior of programs that examine themselves,
314 although such a situation would be highly unusual.
316 Also, the software breakpoint instruction should be the smallest size of
317 instruction, so it doesn't overwrite an instruction that might be a jump
318 target, and cause disaster when the program jumps into the middle of the
319 breakpoint instruction. (Strictly speaking, the breakpoint must be no
320 larger than the smallest interval between instructions that may be jump
321 targets; perhaps there is an architecture where only even-numbered
322 instructions may jumped to.) Note that it's possible for an instruction
323 set not to have any instructions usable for a software breakpoint,
324 although in practice only the ARC has failed to define such an
328 The basic definition of the software breakpoint is the macro
331 Basic breakpoint object handling is in @file{breakpoint.c}. However,
332 much of the interesting breakpoint action is in @file{infrun.c}.
334 @section Single Stepping
336 @section Signal Handling
338 @section Thread Handling
340 @section Inferior Function Calls
342 @section Longjmp Support
344 @cindex @code{longjmp} debugging
345 @value{GDBN} has support for figuring out that the target is doing a
346 @code{longjmp} and for stopping at the target of the jump, if we are
347 stepping. This is done with a few specialized internal breakpoints,
348 which are visible in the output of the @samp{maint info breakpoint}
351 @findex GET_LONGJMP_TARGET
352 To make this work, you need to define a macro called
353 @code{GET_LONGJMP_TARGET}, which will examine the @code{jmp_buf}
354 structure and extract the longjmp target address. Since @code{jmp_buf}
355 is target specific, you will need to define it in the appropriate
356 @file{tm-@var{target}.h} file. Look in @file{tm-sun4os4.h} and
357 @file{sparc-tdep.c} for examples of how to do this.
362 Watchpoints are a special kind of breakpoints (@pxref{Algorithms,
363 breakpoints}) which break when data is accessed rather than when some
364 instruction is executed. When you have data which changes without
365 your knowing what code does that, watchpoints are the silver bullet to
366 hunt down and kill such bugs.
368 @cindex hardware watchpoints
369 @cindex software watchpoints
370 Watchpoints can be either hardware-assisted or not; the latter type is
371 known as ``software watchpoints.'' @value{GDBN} always uses
372 hardware-assisted watchpoints if they are available, and falls back on
373 software watchpoints otherwise. Typical situations where @value{GDBN}
374 will use software watchpoints are:
378 The watched memory region is too large for the underlying hardware
379 watchpoint support. For example, each x86 debug register can watch up
380 to 4 bytes of memory, so trying to watch data structures whose size is
381 more than 16 bytes will cause @value{GDBN} to use software
385 The value of the expression to be watched depends on data held in
386 registers (as opposed to memory).
389 Too many different watchpoints requested. (On some architectures,
390 this situation is impossible to detect until the debugged program is
391 resumed.) Note that x86 debug registers are used both for hardware
392 breakpoints and for watchpoints, so setting too many hardware
393 breakpoints might cause watchpoint insertion to fail.
396 No hardware-assisted watchpoints provided by the target
400 Software watchpoints are very slow, since @value{GDBN} needs to
401 single-step the program being debugged and test the value of the
402 watched expression(s) after each instruction. The rest of this
403 section is mostly irrelevant for software watchpoints.
405 @value{GDBN} uses several macros and primitives to support hardware
409 @findex TARGET_HAS_HARDWARE_WATCHPOINTS
410 @item TARGET_HAS_HARDWARE_WATCHPOINTS
411 If defined, the target supports hardware watchpoints.
413 @findex TARGET_CAN_USE_HARDWARE_WATCHPOINT
414 @item TARGET_CAN_USE_HARDWARE_WATCHPOINT (@var{type}, @var{count}, @var{other})
415 Return the number of hardware watchpoints of type @var{type} that are
416 possible to be set. The value is positive if @var{count} watchpoints
417 of this type can be set, zero if setting watchpoints of this type is
418 not supported, and negative if @var{count} is more than the maximum
419 number of watchpoints of type @var{type} that can be set. @var{other}
420 is non-zero if other types of watchpoints are currently enabled (there
421 are architectures which cannot set watchpoints of different types at
424 @findex TARGET_REGION_OK_FOR_HW_WATCHPOINT
425 @item TARGET_REGION_OK_FOR_HW_WATCHPOINT (@var{addr}, @var{len})
426 Return non-zero if hardware watchpoints can be used to watch a region
427 whose address is @var{addr} and whose length in bytes is @var{len}.
429 @findex TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT
430 @item TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT (@var{size})
431 Return non-zero if hardware watchpoints can be used to watch a region
432 whose size is @var{size}. @value{GDBN} only uses this macro as a
433 fall-back, in case @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is not
436 @findex TARGET_DISABLE_HW_WATCHPOINTS
437 @item TARGET_DISABLE_HW_WATCHPOINTS (@var{pid})
438 Disables watchpoints in the process identified by @var{pid}. This is
439 used, e.g., on HP-UX which provides operations to disable and enable
440 the page-level memory protection that implements hardware watchpoints
443 @findex TARGET_ENABLE_HW_WATCHPOINTS
444 @item TARGET_ENABLE_HW_WATCHPOINTS (@var{pid})
445 Enables watchpoints in the process identified by @var{pid}. This is
446 used, e.g., on HP-UX which provides operations to disable and enable
447 the page-level memory protection that implements hardware watchpoints
450 @findex TARGET_RANGE_PROFITABLE_FOR_HW_WATCHPOINT
451 @item TARGET_RANGE_PROFITABLE_FOR_HW_WATCHPOINT (@var{pid},@var{start},@var{len})
452 Some addresses may not be profitable to use hardware to watch, or may
453 be difficult to understand when the addressed object is out of scope,
454 and hence should not be watched with hardware watchpoints. On some
455 targets, this may have severe performance penalties, such that we
456 might as well use regular watchpoints, and save (possibly precious)
457 hardware watchpoints for other locations.
459 @findex target_insert_watchpoint
460 @findex target_remove_watchpoint
461 @item target_insert_watchpoint (@var{addr}, @var{len}, @var{type})
462 @itemx target_remove_watchpoint (@var{addr}, @var{len}, @var{type})
463 Insert or remove a hardware watchpoint starting at @var{addr}, for
464 @var{len} bytes. @var{type} is the watchpoint type, one of the
465 possible values of the enumerated data type @code{target_hw_bp_type},
466 defined by @file{breakpoint.h} as follows:
469 enum target_hw_bp_type
471 hw_write = 0, /* Common (write) HW watchpoint */
472 hw_read = 1, /* Read HW watchpoint */
473 hw_access = 2, /* Access (read or write) HW watchpoint */
474 hw_execute = 3 /* Execute HW breakpoint */
479 These two macros should return 0 for success, non-zero for failure.
481 @cindex insert or remove hardware breakpoint
482 @findex target_remove_hw_breakpoint
483 @findex target_insert_hw_breakpoint
484 @item target_remove_hw_breakpoint (@var{addr}, @var{shadow})
485 @itemx target_insert_hw_breakpoint (@var{addr}, @var{shadow})
486 Insert or remove a hardware-assisted breakpoint at address @var{addr}.
487 Returns zero for success, non-zero for failure. @var{shadow} is the
488 real contents of the byte where the breakpoint has been inserted; it
489 is generally not valid when hardware breakpoints are used, but since
490 no other code touches these values, the implementations of the above
491 two macros can use them for their internal purposes.
493 @findex target_stopped_data_address
494 @item target_stopped_data_address ()
495 If the inferior has some watchpoint that triggered, return the address
496 associated with that watchpoint. Otherwise, return zero.
498 @findex DECR_PC_AFTER_HW_BREAK
499 @item DECR_PC_AFTER_HW_BREAK
500 If defined, @value{GDBN} decrements the program counter by the value
501 of @code{DECR_PC_AFTER_HW_BREAK} after a hardware break-point. This
502 overrides the value of @code{DECR_PC_AFTER_BREAK} when a breakpoint
503 that breaks is a hardware-assisted breakpoint.
505 @findex HAVE_STEPPABLE_WATCHPOINT
506 @item HAVE_STEPPABLE_WATCHPOINT
507 If defined to a non-zero value, it is not necessary to disable a
508 watchpoint to step over it.
510 @findex HAVE_NONSTEPPABLE_WATCHPOINT
511 @item HAVE_NONSTEPPABLE_WATCHPOINT
512 If defined to a non-zero value, @value{GDBN} should disable a
513 watchpoint to step the inferior over it.
515 @findex HAVE_CONTINUABLE_WATCHPOINT
516 @item HAVE_CONTINUABLE_WATCHPOINT
517 If defined to a non-zero value, it is possible to continue the
518 inferior after a watchpoint has been hit.
520 @findex CANNOT_STEP_HW_WATCHPOINTS
521 @item CANNOT_STEP_HW_WATCHPOINTS
522 If this is defined to a non-zero value, @value{GDBN} will remove all
523 watchpoints before stepping the inferior.
525 @findex STOPPED_BY_WATCHPOINT
526 @item STOPPED_BY_WATCHPOINT (@var{wait_status})
527 Return non-zero if stopped by a watchpoint. @var{wait_status} is of
528 the type @code{struct target_waitstatus}, defined by @file{target.h}.
531 @subsection x86 Watchpoints
532 @cindex x86 debug registers
533 @cindex watchpoints, on x86
535 The 32-bit Intel x86 (a.k.a.@: ia32) processors feature special debug
536 registers designed to facilitate debugging. @value{GDBN} provides a
537 generic library of functions that x86-based ports can use to implement
538 support for watchpoints and hardware-assisted breakpoints. This
539 subsection documents the x86 watchpoint facilities in @value{GDBN}.
541 To use the generic x86 watchpoint support, a port should do the
545 @findex I386_USE_GENERIC_WATCHPOINTS
547 Define the macro @code{I386_USE_GENERIC_WATCHPOINTS} somewhere in the
548 target-dependent headers.
551 Include the @file{config/i386/nm-i386.h} header file @emph{after}
552 defining @code{I386_USE_GENERIC_WATCHPOINTS}.
555 Add @file{i386-nat.o} to the value of the Make variable
556 @code{NATDEPFILES} (@pxref{Native Debugging, NATDEPFILES}) or
557 @code{TDEPFILES} (@pxref{Target Architecture Definition, TDEPFILES}).
560 Provide implementations for the @code{I386_DR_LOW_*} macros described
561 below. Typically, each macro should call a target-specific function
562 which does the real work.
565 The x86 watchpoint support works by maintaining mirror images of the
566 debug registers. Values are copied between the mirror images and the
567 real debug registers via a set of macros which each target needs to
571 @findex I386_DR_LOW_SET_CONTROL
572 @item I386_DR_LOW_SET_CONTROL (@var{val})
573 Set the Debug Control (DR7) register to the value @var{val}.
575 @findex I386_DR_LOW_SET_ADDR
576 @item I386_DR_LOW_SET_ADDR (@var{idx}, @var{addr})
577 Put the address @var{addr} into the debug register number @var{idx}.
579 @findex I386_DR_LOW_RESET_ADDR
580 @item I386_DR_LOW_RESET_ADDR (@var{idx})
581 Reset (i.e.@: zero out) the address stored in the debug register
584 @findex I386_DR_LOW_GET_STATUS
585 @item I386_DR_LOW_GET_STATUS
586 Return the value of the Debug Status (DR6) register. This value is
587 used immediately after it is returned by
588 @code{I386_DR_LOW_GET_STATUS}, so as to support per-thread status
592 For each one of the 4 debug registers (whose indices are from 0 to 3)
593 that store addresses, a reference count is maintained by @value{GDBN},
594 to allow sharing of debug registers by several watchpoints. This
595 allows users to define several watchpoints that watch the same
596 expression, but with different conditions and/or commands, without
597 wasting debug registers which are in short supply. @value{GDBN}
598 maintains the reference counts internally, targets don't have to do
599 anything to use this feature.
601 The x86 debug registers can each watch a region that is 1, 2, or 4
602 bytes long. The ia32 architecture requires that each watched region
603 be appropriately aligned: 2-byte region on 2-byte boundary, 4-byte
604 region on 4-byte boundary. However, the x86 watchpoint support in
605 @value{GDBN} can watch unaligned regions and regions larger than 4
606 bytes (up to 16 bytes) by allocating several debug registers to watch
607 a single region. This allocation of several registers per a watched
608 region is also done automatically without target code intervention.
610 The generic x86 watchpoint support provides the following API for the
611 @value{GDBN}'s application code:
614 @findex i386_region_ok_for_watchpoint
615 @item i386_region_ok_for_watchpoint (@var{addr}, @var{len})
616 The macro @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is set to call
617 this function. It counts the number of debug registers required to
618 watch a given region, and returns a non-zero value if that number is
619 less than 4, the number of debug registers available to x86
622 @findex i386_stopped_data_address
623 @item i386_stopped_data_address (void)
624 The macros @code{STOPPED_BY_WATCHPOINT} and
625 @code{target_stopped_data_address} are set to call this function. The
626 argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored. This
627 function examines the breakpoint condition bits in the DR6 Debug
628 Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}
629 macro, and returns the address associated with the first bit that is
632 @findex i386_insert_watchpoint
633 @findex i386_remove_watchpoint
634 @item i386_insert_watchpoint (@var{addr}, @var{len}, @var{type})
635 @itemx i386_remove_watchpoint (@var{addr}, @var{len}, @var{type})
636 Insert or remove a watchpoint. The macros
637 @code{target_insert_watchpoint} and @code{target_remove_watchpoint}
638 are set to call these functions. @code{i386_insert_watchpoint} first
639 looks for a debug register which is already set to watch the same
640 region for the same access types; if found, it just increments the
641 reference count of that debug register, thus implementing debug
642 register sharing between watchpoints. If no such register is found,
643 the function looks for a vacant debug register, sets its mirrorred
644 value to @var{addr}, sets the mirrorred value of DR7 Debug Control
645 register as appropriate for the @var{len} and @var{type} parameters,
646 and then passes the new values of the debug register and DR7 to the
647 inferior by calling @code{I386_DR_LOW_SET_ADDR} and
648 @code{I386_DR_LOW_SET_CONTROL}. If more than one debug register is
649 required to cover the given region, the above process is repeated for
652 @code{i386_remove_watchpoint} does the opposite: it resets the address
653 in the mirrorred value of the debug register and its read/write and
654 length bits in the mirrorred value of DR7, then passes these new
655 values to the inferior via @code{I386_DR_LOW_RESET_ADDR} and
656 @code{I386_DR_LOW_SET_CONTROL}. If a register is shared by several
657 watchpoints, each time a @code{i386_remove_watchpoint} is called, it
658 decrements the reference count, and only calls
659 @code{I386_DR_LOW_RESET_ADDR} and @code{I386_DR_LOW_SET_CONTROL} when
660 the count goes to zero.
662 @findex i386_insert_hw_breakpoint
663 @findex i386_remove_hw_breakpoint
664 @item i386_insert_hw_breakpoint (@var{addr}, @var{shadow}
665 @itemx i386_remove_hw_breakpoint (@var{addr}, @var{shadow})
666 These functions insert and remove hardware-assisted breakpoints. The
667 macros @code{target_insert_hw_breakpoint} and
668 @code{target_remove_hw_breakpoint} are set to call these functions.
669 These functions work like @code{i386_insert_watchpoint} and
670 @code{i386_remove_watchpoint}, respectively, except that they set up
671 the debug registers to watch instruction execution, and each
672 hardware-assisted breakpoint always requires exactly one debug
675 @findex i386_stopped_by_hwbp
676 @item i386_stopped_by_hwbp (void)
677 This function returns non-zero if the inferior has some watchpoint or
678 hardware breakpoint that triggered. It works like
679 @code{i386_stopped_data_address}, except that it doesn't return the
680 address whose watchpoint triggered.
682 @findex i386_cleanup_dregs
683 @item i386_cleanup_dregs (void)
684 This function clears all the reference counts, addresses, and control
685 bits in the mirror images of the debug registers. It doesn't affect
686 the actual debug registers in the inferior process.
693 x86 processors support setting watchpoints on I/O reads or writes.
694 However, since no target supports this (as of March 2001), and since
695 @code{enum target_hw_bp_type} doesn't even have an enumeration for I/O
696 watchpoints, this feature is not yet available to @value{GDBN} running
700 x86 processors can enable watchpoints locally, for the current task
701 only, or globally, for all the tasks. For each debug register,
702 there's a bit in the DR7 Debug Control register that determines
703 whether the associated address is watched locally or globally. The
704 current implementation of x86 watchpoint support in @value{GDBN}
705 always sets watchpoints to be locally enabled, since global
706 watchpoints might interfere with the underlying OS and are probably
707 unavailable in many platforms.
712 @chapter User Interface
714 @value{GDBN} has several user interfaces. Although the command-line interface
715 is the most common and most familiar, there are others.
717 @section Command Interpreter
719 @cindex command interpreter
721 The command interpreter in @value{GDBN} is fairly simple. It is designed to
722 allow for the set of commands to be augmented dynamically, and also
723 has a recursive subcommand capability, where the first argument to
724 a command may itself direct a lookup on a different command list.
726 For instance, the @samp{set} command just starts a lookup on the
727 @code{setlist} command list, while @samp{set thread} recurses
728 to the @code{set_thread_cmd_list}.
732 To add commands in general, use @code{add_cmd}. @code{add_com} adds to
733 the main command list, and should be used for those commands. The usual
734 place to add commands is in the @code{_initialize_@var{xyz}} routines at
735 the ends of most source files.
737 @cindex deprecating commands
738 @findex deprecate_cmd
739 Before removing commands from the command set it is a good idea to
740 deprecate them for some time. Use @code{deprecate_cmd} on commands or
741 aliases to set the deprecated flag. @code{deprecate_cmd} takes a
742 @code{struct cmd_list_element} as it's first argument. You can use the
743 return value from @code{add_com} or @code{add_cmd} to deprecate the
744 command immediately after it is created.
746 The first time a command is used the user will be warned and offered a
747 replacement (if one exists). Note that the replacement string passed to
748 @code{deprecate_cmd} should be the full name of the command, i.e. the
749 entire string the user should type at the command line.
751 @section UI-Independent Output---the @code{ui_out} Functions
752 @c This section is based on the documentation written by Fernando
753 @c Nasser <fnasser@redhat.com>.
755 @cindex @code{ui_out} functions
756 The @code{ui_out} functions present an abstraction level for the
757 @value{GDBN} output code. They hide the specifics of different user
758 interfaces supported by @value{GDBN}, and thus free the programmer
759 from the need to write several versions of the same code, one each for
760 every UI, to produce output.
762 @subsection Overview and Terminology
764 In general, execution of each @value{GDBN} command produces some sort
765 of output, and can even generate an input request.
767 Output can be generated for the following purposes:
771 to display a @emph{result} of an operation;
774 to convey @emph{info} or produce side-effects of a requested
778 to provide a @emph{notification} of an asynchronous event (including
779 progress indication of a prolonged asynchronous operation);
782 to display @emph{error messages} (including warnings);
785 to show @emph{debug data};
788 to @emph{query} or prompt a user for input (a special case).
792 This section mainly concentrates on how to build result output,
793 although some of it also applies to other kinds of output.
795 Generation of output that displays the results of an operation
796 involves one or more of the following:
800 output of the actual data
803 formatting the output as appropriate for console output, to make it
804 easily readable by humans
807 machine oriented formatting--a more terse formatting to allow for easy
808 parsing by programs which read @value{GDBN}'s output
811 annotation, whose purpose is to help legacy GUIs to identify interesting
815 The @code{ui_out} routines take care of the first three aspects.
816 Annotations are provided by separate annotation routines. Note that use
817 of annotations for an interface between a GUI and @value{GDBN} is
820 Output can be in the form of a single item, which we call a @dfn{field};
821 a @dfn{list} consisting of identical fields; a @dfn{tuple} consisting of
822 non-identical fields; or a @dfn{table}, which is a tuple consisting of a
823 header and a body. In a BNF-like form:
826 @item <table> @expansion{}
827 @code{<header> <body>}
828 @item <header> @expansion{}
829 @code{@{ <column> @}}
830 @item <column> @expansion{}
831 @code{<width> <alignment> <title>}
832 @item <body> @expansion{}
837 @subsection General Conventions
839 Most @code{ui_out} routines are of type @code{void}, the exceptions are
840 @code{ui_out_stream_new} (which returns a pointer to the newly created
841 object) and the @code{make_cleanup} routines.
843 The first parameter is always the @code{ui_out} vector object, a pointer
844 to a @code{struct ui_out}.
846 The @var{format} parameter is like in @code{printf} family of functions.
847 When it is present, there must also be a variable list of arguments
848 sufficient used to satisfy the @code{%} specifiers in the supplied
851 When a character string argument is not used in a @code{ui_out} function
852 call, a @code{NULL} pointer has to be supplied instead.
855 @subsection Table, Tuple and List Functions
857 @cindex list output functions
858 @cindex table output functions
859 @cindex tuple output functions
860 This section introduces @code{ui_out} routines for building lists,
861 tuples and tables. The routines to output the actual data items
862 (fields) are presented in the next section.
864 To recap: A @dfn{tuple} is a sequence of @dfn{fields}, each field
865 containing information about an object; a @dfn{list} is a sequence of
866 fields where each field describes an identical object.
868 Use the @dfn{table} functions when your output consists of a list of
869 rows (tuples) and the console output should include a heading. Use this
870 even when you are listing just one object but you still want the header.
872 @cindex nesting level in @code{ui_out} functions
873 Tables can not be nested. Tuples and lists can be nested up to a
874 maximum of five levels.
876 The overall structure of the table output code is something like this:
891 Here is the description of table-, tuple- and list-related @code{ui_out}
894 @deftypefun void ui_out_table_begin (struct ui_out *@var{uiout}, int @var{nbrofcols}, int @var{nr_rows}, const char *@var{tblid})
895 The function @code{ui_out_table_begin} marks the beginning of the output
896 of a table. It should always be called before any other @code{ui_out}
897 function for a given table. @var{nbrofcols} is the number of columns in
898 the table. @var{nr_rows} is the number of rows in the table.
899 @var{tblid} is an optional string identifying the table. The string
900 pointed to by @var{tblid} is copied by the implementation of
901 @code{ui_out_table_begin}, so the application can free the string if it
904 The companion function @code{ui_out_table_end}, described below, marks
905 the end of the table's output.
908 @deftypefun void ui_out_table_header (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{colhdr})
909 @code{ui_out_table_header} provides the header information for a single
910 table column. You call this function several times, one each for every
911 column of the table, after @code{ui_out_table_begin}, but before
912 @code{ui_out_table_body}.
914 The value of @var{width} gives the column width in characters. The
915 value of @var{alignment} is one of @code{left}, @code{center}, and
916 @code{right}, and it specifies how to align the header: left-justify,
917 center, or right-justify it. @var{colhdr} points to a string that
918 specifies the column header; the implementation copies that string, so
919 column header strings in @code{malloc}ed storage can be freed after the
923 @deftypefun void ui_out_table_body (struct ui_out *@var{uiout})
924 This function delimits the table header from the table body.
927 @deftypefun void ui_out_table_end (struct ui_out *@var{uiout})
928 This function signals the end of a table's output. It should be called
929 after the table body has been produced by the list and field output
932 There should be exactly one call to @code{ui_out_table_end} for each
933 call to @code{ui_out_table_begin}, otherwise the @code{ui_out} functions
934 will signal an internal error.
937 The output of the tuples that represent the table rows must follow the
938 call to @code{ui_out_table_body} and precede the call to
939 @code{ui_out_table_end}. You build a tuple by calling
940 @code{ui_out_tuple_begin} and @code{ui_out_tuple_end}, with suitable
941 calls to functions which actually output fields between them.
943 @deftypefun void ui_out_tuple_begin (struct ui_out *@var{uiout}, const char *@var{id})
944 This function marks the beginning of a tuple output. @var{id} points
945 to an optional string that identifies the tuple; it is copied by the
946 implementation, and so strings in @code{malloc}ed storage can be freed
950 @deftypefun void ui_out_tuple_end (struct ui_out *@var{uiout})
951 This function signals an end of a tuple output. There should be exactly
952 one call to @code{ui_out_tuple_end} for each call to
953 @code{ui_out_tuple_begin}, otherwise an internal @value{GDBN} error will
957 @deftypefun struct cleanup *make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
958 This function first opens the tuple and then establishes a cleanup
959 (@pxref{Coding, Cleanups}) to close the tuple. It provides a convenient
960 and correct implementation of the non-portable@footnote{The function
961 cast is not portable ISO-C.} code sequence:
963 struct cleanup *old_cleanup;
964 ui_out_tuple_begin (uiout, "...");
965 old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end,
970 @deftypefun void ui_out_list_begin (struct ui_out *@var{uiout}, const char *@var{id})
971 This function marks the beginning of a list output. @var{id} points to
972 an optional string that identifies the list; it is copied by the
973 implementation, and so strings in @code{malloc}ed storage can be freed
977 @deftypefun void ui_out_list_end (struct ui_out *@var{uiout})
978 This function signals an end of a list output. There should be exactly
979 one call to @code{ui_out_list_end} for each call to
980 @code{ui_out_list_begin}, otherwise an internal @value{GDBN} error will
984 @deftypefun struct cleanup *make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
985 Similar to @code{make_cleanup_ui_out_tuple_begin_end}, this function
986 opens a list and then establishes cleanup (@pxref{Coding, Cleanups})
987 that will close the list.list.
990 @subsection Item Output Functions
992 @cindex item output functions
993 @cindex field output functions
995 The functions described below produce output for the actual data
996 items, or fields, which contain information about the object.
998 Choose the appropriate function accordingly to your particular needs.
1000 @deftypefun void ui_out_field_fmt (struct ui_out *@var{uiout}, char *@var{fldname}, char *@var{format}, ...)
1001 This is the most general output function. It produces the
1002 representation of the data in the variable-length argument list
1003 according to formatting specifications in @var{format}, a
1004 @code{printf}-like format string. The optional argument @var{fldname}
1005 supplies the name of the field. The data items themselves are
1006 supplied as additional arguments after @var{format}.
1008 This generic function should be used only when it is not possible to
1009 use one of the specialized versions (see below).
1012 @deftypefun void ui_out_field_int (struct ui_out *@var{uiout}, const char *@var{fldname}, int @var{value})
1013 This function outputs a value of an @code{int} variable. It uses the
1014 @code{"%d"} output conversion specification. @var{fldname} specifies
1015 the name of the field.
1018 @deftypefun void ui_out_field_core_addr (struct ui_out *@var{uiout}, const char *@var{fldname}, CORE_ADDR @var{address})
1019 This function outputs an address.
1022 @deftypefun void ui_out_field_string (struct ui_out *@var{uiout}, const char *@var{fldname}, const char *@var{string})
1023 This function outputs a string using the @code{"%s"} conversion
1027 Sometimes, there's a need to compose your output piece by piece using
1028 functions that operate on a stream, such as @code{value_print} or
1029 @code{fprintf_symbol_filtered}. These functions accept an argument of
1030 the type @code{struct ui_file *}, a pointer to a @code{ui_file} object
1031 used to store the data stream used for the output. When you use one
1032 of these functions, you need a way to pass their results stored in a
1033 @code{ui_file} object to the @code{ui_out} functions. To this end,
1034 you first create a @code{ui_stream} object by calling
1035 @code{ui_out_stream_new}, pass the @code{stream} member of that
1036 @code{ui_stream} object to @code{value_print} and similar functions,
1037 and finally call @code{ui_out_field_stream} to output the field you
1038 constructed. When the @code{ui_stream} object is no longer needed,
1039 you should destroy it and free its memory by calling
1040 @code{ui_out_stream_delete}.
1042 @deftypefun struct ui_stream *ui_out_stream_new (struct ui_out *@var{uiout})
1043 This function creates a new @code{ui_stream} object which uses the
1044 same output methods as the @code{ui_out} object whose pointer is
1045 passed in @var{uiout}. It returns a pointer to the newly created
1046 @code{ui_stream} object.
1049 @deftypefun void ui_out_stream_delete (struct ui_stream *@var{streambuf})
1050 This functions destroys a @code{ui_stream} object specified by
1054 @deftypefun void ui_out_field_stream (struct ui_out *@var{uiout}, const char *@var{fieldname}, struct ui_stream *@var{streambuf})
1055 This function consumes all the data accumulated in
1056 @code{streambuf->stream} and outputs it like
1057 @code{ui_out_field_string} does. After a call to
1058 @code{ui_out_field_stream}, the accumulated data no longer exists, but
1059 the stream is still valid and may be used for producing more fields.
1062 @strong{Important:} If there is any chance that your code could bail
1063 out before completing output generation and reaching the point where
1064 @code{ui_out_stream_delete} is called, it is necessary to set up a
1065 cleanup, to avoid leaking memory and other resources. Here's a
1066 skeleton code to do that:
1069 struct ui_stream *mybuf = ui_out_stream_new (uiout);
1070 struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf);
1075 If the function already has the old cleanup chain set (for other kinds
1076 of cleanups), you just have to add your cleanup to it:
1079 mybuf = ui_out_stream_new (uiout);
1080 make_cleanup (ui_out_stream_delete, mybuf);
1083 Note that with cleanups in place, you should not call
1084 @code{ui_out_stream_delete} directly, or you would attempt to free the
1087 @subsection Utility Output Functions
1089 @deftypefun void ui_out_field_skip (struct ui_out *@var{uiout}, const char *@var{fldname})
1090 This function skips a field in a table. Use it if you have to leave
1091 an empty field without disrupting the table alignment. The argument
1092 @var{fldname} specifies a name for the (missing) filed.
1095 @deftypefun void ui_out_text (struct ui_out *@var{uiout}, const char *@var{string})
1096 This function outputs the text in @var{string} in a way that makes it
1097 easy to be read by humans. For example, the console implementation of
1098 this method filters the text through a built-in pager, to prevent it
1099 from scrolling off the visible portion of the screen.
1101 Use this function for printing relatively long chunks of text around
1102 the actual field data: the text it produces is not aligned according
1103 to the table's format. Use @code{ui_out_field_string} to output a
1104 string field, and use @code{ui_out_message}, described below, to
1105 output short messages.
1108 @deftypefun void ui_out_spaces (struct ui_out *@var{uiout}, int @var{nspaces})
1109 This function outputs @var{nspaces} spaces. It is handy to align the
1110 text produced by @code{ui_out_text} with the rest of the table or
1114 @deftypefun void ui_out_message (struct ui_out *@var{uiout}, int @var{verbosity}, const char *@var{format}, ...)
1115 This function produces a formatted message, provided that the current
1116 verbosity level is at least as large as given by @var{verbosity}. The
1117 current verbosity level is specified by the user with the @samp{set
1118 verbositylevel} command.@footnote{As of this writing (April 2001),
1119 setting verbosity level is not yet implemented, and is always returned
1120 as zero. So calling @code{ui_out_message} with a @var{verbosity}
1121 argument more than zero will cause the message to never be printed.}
1124 @deftypefun void ui_out_wrap_hint (struct ui_out *@var{uiout}, char *@var{indent})
1125 This function gives the console output filter (a paging filter) a hint
1126 of where to break lines which are too long. Ignored for all other
1127 output consumers. @var{indent}, if non-@code{NULL}, is the string to
1128 be printed to indent the wrapped text on the next line; it must remain
1129 accessible until the next call to @code{ui_out_wrap_hint}, or until an
1130 explicit newline is produced by one of the other functions. If
1131 @var{indent} is @code{NULL}, the wrapped text will not be indented.
1134 @deftypefun void ui_out_flush (struct ui_out *@var{uiout})
1135 This function flushes whatever output has been accumulated so far, if
1136 the UI buffers output.
1140 @subsection Examples of Use of @code{ui_out} functions
1142 @cindex using @code{ui_out} functions
1143 @cindex @code{ui_out} functions, usage examples
1144 This section gives some practical examples of using the @code{ui_out}
1145 functions to generalize the old console-oriented code in
1146 @value{GDBN}. The examples all come from functions defined on the
1147 @file{breakpoints.c} file.
1149 This example, from the @code{breakpoint_1} function, shows how to
1152 The original code was:
1155 if (!found_a_breakpoint++)
1157 annotate_breakpoints_headers ();
1160 printf_filtered ("Num ");
1162 printf_filtered ("Type ");
1164 printf_filtered ("Disp ");
1166 printf_filtered ("Enb ");
1170 printf_filtered ("Address ");
1173 printf_filtered ("What\n");
1175 annotate_breakpoints_table ();
1179 Here's the new version:
1182 nr_printable_breakpoints = @dots{};
1185 ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable");
1187 ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable");
1189 if (nr_printable_breakpoints > 0)
1190 annotate_breakpoints_headers ();
1191 if (nr_printable_breakpoints > 0)
1193 ui_out_table_header (uiout, 3, ui_left, "number", "Num"); /* 1 */
1194 if (nr_printable_breakpoints > 0)
1196 ui_out_table_header (uiout, 14, ui_left, "type", "Type"); /* 2 */
1197 if (nr_printable_breakpoints > 0)
1199 ui_out_table_header (uiout, 4, ui_left, "disp", "Disp"); /* 3 */
1200 if (nr_printable_breakpoints > 0)
1202 ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb"); /* 4 */
1205 if (nr_printable_breakpoints > 0)
1207 if (TARGET_ADDR_BIT <= 32)
1208 ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */
1210 ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */
1212 if (nr_printable_breakpoints > 0)
1214 ui_out_table_header (uiout, 40, ui_noalign, "what", "What"); /* 6 */
1215 ui_out_table_body (uiout);
1216 if (nr_printable_breakpoints > 0)
1217 annotate_breakpoints_table ();
1220 This example, from the @code{print_one_breakpoint} function, shows how
1221 to produce the actual data for the table whose structure was defined
1222 in the above example. The original code was:
1227 printf_filtered ("%-3d ", b->number);
1229 if ((int)b->type > (sizeof(bptypes)/sizeof(bptypes[0]))
1230 || ((int) b->type != bptypes[(int) b->type].type))
1231 internal_error ("bptypes table does not describe type #%d.",
1233 printf_filtered ("%-14s ", bptypes[(int)b->type].description);
1235 printf_filtered ("%-4s ", bpdisps[(int)b->disposition]);
1237 printf_filtered ("%-3c ", bpenables[(int)b->enable]);
1241 This is the new version:
1245 ui_out_tuple_begin (uiout, "bkpt");
1247 ui_out_field_int (uiout, "number", b->number);
1249 if (((int) b->type > (sizeof (bptypes) / sizeof (bptypes[0])))
1250 || ((int) b->type != bptypes[(int) b->type].type))
1251 internal_error ("bptypes table does not describe type #%d.",
1253 ui_out_field_string (uiout, "type", bptypes[(int)b->type].description);
1255 ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]);
1257 ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);
1261 This example, also from @code{print_one_breakpoint}, shows how to
1262 produce a complicated output field using the @code{print_expression}
1263 functions which requires a stream to be passed. It also shows how to
1264 automate stream destruction with cleanups. The original code was:
1268 print_expression (b->exp, gdb_stdout);
1274 struct ui_stream *stb = ui_out_stream_new (uiout);
1275 struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb);
1278 print_expression (b->exp, stb->stream);
1279 ui_out_field_stream (uiout, "what", local_stream);
1282 This example, also from @code{print_one_breakpoint}, shows how to use
1283 @code{ui_out_text} and @code{ui_out_field_string}. The original code
1288 if (b->dll_pathname == NULL)
1289 printf_filtered ("<any library> ");
1291 printf_filtered ("library \"%s\" ", b->dll_pathname);
1298 if (b->dll_pathname == NULL)
1300 ui_out_field_string (uiout, "what", "<any library>");
1301 ui_out_spaces (uiout, 1);
1305 ui_out_text (uiout, "library \"");
1306 ui_out_field_string (uiout, "what", b->dll_pathname);
1307 ui_out_text (uiout, "\" ");
1311 The following example from @code{print_one_breakpoint} shows how to
1312 use @code{ui_out_field_int} and @code{ui_out_spaces}. The original
1317 if (b->forked_inferior_pid != 0)
1318 printf_filtered ("process %d ", b->forked_inferior_pid);
1325 if (b->forked_inferior_pid != 0)
1327 ui_out_text (uiout, "process ");
1328 ui_out_field_int (uiout, "what", b->forked_inferior_pid);
1329 ui_out_spaces (uiout, 1);
1333 Here's an example of using @code{ui_out_field_string}. The original
1338 if (b->exec_pathname != NULL)
1339 printf_filtered ("program \"%s\" ", b->exec_pathname);
1346 if (b->exec_pathname != NULL)
1348 ui_out_text (uiout, "program \"");
1349 ui_out_field_string (uiout, "what", b->exec_pathname);
1350 ui_out_text (uiout, "\" ");
1354 Finally, here's an example of printing an address. The original code:
1358 printf_filtered ("%s ",
1359 local_hex_string_custom ((unsigned long) b->address, "08l"));
1366 ui_out_field_core_addr (uiout, "Address", b->address);
1370 @section Console Printing
1376 @cindex @code{libgdb}
1377 @code{libgdb} was an abortive project of years ago. The theory was to
1378 provide an API to @value{GDBN}'s functionality.
1380 @node Symbol Handling
1382 @chapter Symbol Handling
1384 Symbols are a key part of @value{GDBN}'s operation. Symbols include variables,
1385 functions, and types.
1387 @section Symbol Reading
1389 @cindex symbol reading
1390 @cindex reading of symbols
1391 @cindex symbol files
1392 @value{GDBN} reads symbols from @dfn{symbol files}. The usual symbol
1393 file is the file containing the program which @value{GDBN} is
1394 debugging. @value{GDBN} can be directed to use a different file for
1395 symbols (with the @samp{symbol-file} command), and it can also read
1396 more symbols via the @samp{add-file} and @samp{load} commands, or while
1397 reading symbols from shared libraries.
1399 @findex find_sym_fns
1400 Symbol files are initially opened by code in @file{symfile.c} using
1401 the BFD library (@pxref{Support Libraries}). BFD identifies the type
1402 of the file by examining its header. @code{find_sym_fns} then uses
1403 this identification to locate a set of symbol-reading functions.
1405 @findex add_symtab_fns
1406 @cindex @code{sym_fns} structure
1407 @cindex adding a symbol-reading module
1408 Symbol-reading modules identify themselves to @value{GDBN} by calling
1409 @code{add_symtab_fns} during their module initialization. The argument
1410 to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the
1411 name (or name prefix) of the symbol format, the length of the prefix,
1412 and pointers to four functions. These functions are called at various
1413 times to process symbol files whose identification matches the specified
1416 The functions supplied by each module are:
1419 @item @var{xyz}_symfile_init(struct sym_fns *sf)
1421 @cindex secondary symbol file
1422 Called from @code{symbol_file_add} when we are about to read a new
1423 symbol file. This function should clean up any internal state (possibly
1424 resulting from half-read previous files, for example) and prepare to
1425 read a new symbol file. Note that the symbol file which we are reading
1426 might be a new ``main'' symbol file, or might be a secondary symbol file
1427 whose symbols are being added to the existing symbol table.
1429 The argument to @code{@var{xyz}_symfile_init} is a newly allocated
1430 @code{struct sym_fns} whose @code{bfd} field contains the BFD for the
1431 new symbol file being read. Its @code{private} field has been zeroed,
1432 and can be modified as desired. Typically, a struct of private
1433 information will be @code{malloc}'d, and a pointer to it will be placed
1434 in the @code{private} field.
1436 There is no result from @code{@var{xyz}_symfile_init}, but it can call
1437 @code{error} if it detects an unavoidable problem.
1439 @item @var{xyz}_new_init()
1441 Called from @code{symbol_file_add} when discarding existing symbols.
1442 This function needs only handle the symbol-reading module's internal
1443 state; the symbol table data structures visible to the rest of
1444 @value{GDBN} will be discarded by @code{symbol_file_add}. It has no
1445 arguments and no result. It may be called after
1446 @code{@var{xyz}_symfile_init}, if a new symbol table is being read, or
1447 may be called alone if all symbols are simply being discarded.
1449 @item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)
1451 Called from @code{symbol_file_add} to actually read the symbols from a
1452 symbol-file into a set of psymtabs or symtabs.
1454 @code{sf} points to the @code{struct sym_fns} originally passed to
1455 @code{@var{xyz}_sym_init} for possible initialization. @code{addr} is
1456 the offset between the file's specified start address and its true
1457 address in memory. @code{mainline} is 1 if this is the main symbol
1458 table being read, and 0 if a secondary symbol file (e.g. shared library
1459 or dynamically loaded file) is being read.@refill
1462 In addition, if a symbol-reading module creates psymtabs when
1463 @var{xyz}_symfile_read is called, these psymtabs will contain a pointer
1464 to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called
1465 from any point in the @value{GDBN} symbol-handling code.
1468 @item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst)
1470 Called from @code{psymtab_to_symtab} (or the @code{PSYMTAB_TO_SYMTAB} macro) if
1471 the psymtab has not already been read in and had its @code{pst->symtab}
1472 pointer set. The argument is the psymtab to be fleshed-out into a
1473 symtab. Upon return, @code{pst->readin} should have been set to 1, and
1474 @code{pst->symtab} should contain a pointer to the new corresponding symtab, or
1475 zero if there were no symbols in that part of the symbol file.
1478 @section Partial Symbol Tables
1480 @value{GDBN} has three types of symbol tables:
1483 @cindex full symbol table
1486 Full symbol tables (@dfn{symtabs}). These contain the main
1487 information about symbols and addresses.
1491 Partial symbol tables (@dfn{psymtabs}). These contain enough
1492 information to know when to read the corresponding part of the full
1495 @cindex minimal symbol table
1498 Minimal symbol tables (@dfn{msymtabs}). These contain information
1499 gleaned from non-debugging symbols.
1502 @cindex partial symbol table
1503 This section describes partial symbol tables.
1505 A psymtab is constructed by doing a very quick pass over an executable
1506 file's debugging information. Small amounts of information are
1507 extracted---enough to identify which parts of the symbol table will
1508 need to be re-read and fully digested later, when the user needs the
1509 information. The speed of this pass causes @value{GDBN} to start up very
1510 quickly. Later, as the detailed rereading occurs, it occurs in small
1511 pieces, at various times, and the delay therefrom is mostly invisible to
1513 @c (@xref{Symbol Reading}.)
1515 The symbols that show up in a file's psymtab should be, roughly, those
1516 visible to the debugger's user when the program is not running code from
1517 that file. These include external symbols and types, static symbols and
1518 types, and @code{enum} values declared at file scope.
1520 The psymtab also contains the range of instruction addresses that the
1521 full symbol table would represent.
1523 @cindex finding a symbol
1524 @cindex symbol lookup
1525 The idea is that there are only two ways for the user (or much of the
1526 code in the debugger) to reference a symbol:
1529 @findex find_pc_function
1530 @findex find_pc_line
1532 By its address (e.g. execution stops at some address which is inside a
1533 function in this file). The address will be noticed to be in the
1534 range of this psymtab, and the full symtab will be read in.
1535 @code{find_pc_function}, @code{find_pc_line}, and other
1536 @code{find_pc_@dots{}} functions handle this.
1538 @cindex lookup_symbol
1541 (e.g. the user asks to print a variable, or set a breakpoint on a
1542 function). Global names and file-scope names will be found in the
1543 psymtab, which will cause the symtab to be pulled in. Local names will
1544 have to be qualified by a global name, or a file-scope name, in which
1545 case we will have already read in the symtab as we evaluated the
1546 qualifier. Or, a local symbol can be referenced when we are ``in'' a
1547 local scope, in which case the first case applies. @code{lookup_symbol}
1548 does most of the work here.
1551 The only reason that psymtabs exist is to cause a symtab to be read in
1552 at the right moment. Any symbol that can be elided from a psymtab,
1553 while still causing that to happen, should not appear in it. Since
1554 psymtabs don't have the idea of scope, you can't put local symbols in
1555 them anyway. Psymtabs don't have the idea of the type of a symbol,
1556 either, so types need not appear, unless they will be referenced by
1559 It is a bug for @value{GDBN} to behave one way when only a psymtab has
1560 been read, and another way if the corresponding symtab has been read
1561 in. Such bugs are typically caused by a psymtab that does not contain
1562 all the visible symbols, or which has the wrong instruction address
1565 The psymtab for a particular section of a symbol file (objfile) could be
1566 thrown away after the symtab has been read in. The symtab should always
1567 be searched before the psymtab, so the psymtab will never be used (in a
1568 bug-free environment). Currently, psymtabs are allocated on an obstack,
1569 and all the psymbols themselves are allocated in a pair of large arrays
1570 on an obstack, so there is little to be gained by trying to free them
1571 unless you want to do a lot more work.
1575 @unnumberedsubsec Fundamental Types (e.g., @code{FT_VOID}, @code{FT_BOOLEAN}).
1577 @cindex fundamental types
1578 These are the fundamental types that @value{GDBN} uses internally. Fundamental
1579 types from the various debugging formats (stabs, ELF, etc) are mapped
1580 into one of these. They are basically a union of all fundamental types
1581 that @value{GDBN} knows about for all the languages that @value{GDBN}
1584 @unnumberedsubsec Type Codes (e.g., @code{TYPE_CODE_PTR}, @code{TYPE_CODE_ARRAY}).
1587 Each time @value{GDBN} builds an internal type, it marks it with one
1588 of these types. The type may be a fundamental type, such as
1589 @code{TYPE_CODE_INT}, or a derived type, such as @code{TYPE_CODE_PTR}
1590 which is a pointer to another type. Typically, several @code{FT_*}
1591 types map to one @code{TYPE_CODE_*} type, and are distinguished by
1592 other members of the type struct, such as whether the type is signed
1593 or unsigned, and how many bits it uses.
1595 @unnumberedsubsec Builtin Types (e.g., @code{builtin_type_void}, @code{builtin_type_char}).
1597 These are instances of type structs that roughly correspond to
1598 fundamental types and are created as global types for @value{GDBN} to
1599 use for various ugly historical reasons. We eventually want to
1600 eliminate these. Note for example that @code{builtin_type_int}
1601 initialized in @file{gdbtypes.c} is basically the same as a
1602 @code{TYPE_CODE_INT} type that is initialized in @file{c-lang.c} for
1603 an @code{FT_INTEGER} fundamental type. The difference is that the
1604 @code{builtin_type} is not associated with any particular objfile, and
1605 only one instance exists, while @file{c-lang.c} builds as many
1606 @code{TYPE_CODE_INT} types as needed, with each one associated with
1607 some particular objfile.
1609 @section Object File Formats
1610 @cindex object file formats
1614 @cindex @code{a.out} format
1615 The @code{a.out} format is the original file format for Unix. It
1616 consists of three sections: @code{text}, @code{data}, and @code{bss},
1617 which are for program code, initialized data, and uninitialized data,
1620 The @code{a.out} format is so simple that it doesn't have any reserved
1621 place for debugging information. (Hey, the original Unix hackers used
1622 @samp{adb}, which is a machine-language debugger!) The only debugging
1623 format for @code{a.out} is stabs, which is encoded as a set of normal
1624 symbols with distinctive attributes.
1626 The basic @code{a.out} reader is in @file{dbxread.c}.
1631 The COFF format was introduced with System V Release 3 (SVR3) Unix.
1632 COFF files may have multiple sections, each prefixed by a header. The
1633 number of sections is limited.
1635 The COFF specification includes support for debugging. Although this
1636 was a step forward, the debugging information was woefully limited. For
1637 instance, it was not possible to represent code that came from an
1640 The COFF reader is in @file{coffread.c}.
1644 @cindex ECOFF format
1645 ECOFF is an extended COFF originally introduced for Mips and Alpha
1648 The basic ECOFF reader is in @file{mipsread.c}.
1652 @cindex XCOFF format
1653 The IBM RS/6000 running AIX uses an object file format called XCOFF.
1654 The COFF sections, symbols, and line numbers are used, but debugging
1655 symbols are @code{dbx}-style stabs whose strings are located in the
1656 @code{.debug} section (rather than the string table). For more
1657 information, see @ref{Top,,,stabs,The Stabs Debugging Format}.
1659 The shared library scheme has a clean interface for figuring out what
1660 shared libraries are in use, but the catch is that everything which
1661 refers to addresses (symbol tables and breakpoints at least) needs to be
1662 relocated for both shared libraries and the main executable. At least
1663 using the standard mechanism this can only be done once the program has
1664 been run (or the core file has been read).
1668 @cindex PE-COFF format
1669 Windows 95 and NT use the PE (@dfn{Portable Executable}) format for their
1670 executables. PE is basically COFF with additional headers.
1672 While BFD includes special PE support, @value{GDBN} needs only the basic
1678 The ELF format came with System V Release 4 (SVR4) Unix. ELF is similar
1679 to COFF in being organized into a number of sections, but it removes
1680 many of COFF's limitations.
1682 The basic ELF reader is in @file{elfread.c}.
1687 SOM is HP's object file and debug format (not to be confused with IBM's
1688 SOM, which is a cross-language ABI).
1690 The SOM reader is in @file{hpread.c}.
1692 @subsection Other File Formats
1694 @cindex Netware Loadable Module format
1695 Other file formats that have been supported by @value{GDBN} include Netware
1696 Loadable Modules (@file{nlmread.c}).
1698 @section Debugging File Formats
1700 This section describes characteristics of debugging information that
1701 are independent of the object file format.
1705 @cindex stabs debugging info
1706 @code{stabs} started out as special symbols within the @code{a.out}
1707 format. Since then, it has been encapsulated into other file
1708 formats, such as COFF and ELF.
1710 While @file{dbxread.c} does some of the basic stab processing,
1711 including for encapsulated versions, @file{stabsread.c} does
1716 @cindex COFF debugging info
1717 The basic COFF definition includes debugging information. The level
1718 of support is minimal and non-extensible, and is not often used.
1720 @subsection Mips debug (Third Eye)
1722 @cindex ECOFF debugging info
1723 ECOFF includes a definition of a special debug format.
1725 The file @file{mdebugread.c} implements reading for this format.
1729 @cindex DWARF 1 debugging info
1730 DWARF 1 is a debugging format that was originally designed to be
1731 used with ELF in SVR4 systems.
1737 @c If defined, these are the producer strings in a DWARF 1 file. All of
1738 @c these have reasonable defaults already.
1740 The DWARF 1 reader is in @file{dwarfread.c}.
1744 @cindex DWARF 2 debugging info
1745 DWARF 2 is an improved but incompatible version of DWARF 1.
1747 The DWARF 2 reader is in @file{dwarf2read.c}.
1751 @cindex SOM debugging info
1752 Like COFF, the SOM definition includes debugging information.
1754 @section Adding a New Symbol Reader to @value{GDBN}
1756 @cindex adding debugging info reader
1757 If you are using an existing object file format (@code{a.out}, COFF, ELF, etc),
1758 there is probably little to be done.
1760 If you need to add a new object file format, you must first add it to
1761 BFD. This is beyond the scope of this document.
1763 You must then arrange for the BFD code to provide access to the
1764 debugging symbols. Generally @value{GDBN} will have to call swapping routines
1765 from BFD and a few other BFD internal routines to locate the debugging
1766 information. As much as possible, @value{GDBN} should not depend on the BFD
1767 internal data structures.
1769 For some targets (e.g., COFF), there is a special transfer vector used
1770 to call swapping routines, since the external data structures on various
1771 platforms have different sizes and layouts. Specialized routines that
1772 will only ever be implemented by one object file format may be called
1773 directly. This interface should be described in a file
1774 @file{bfd/lib@var{xyz}.h}, which is included by @value{GDBN}.
1777 @node Language Support
1779 @chapter Language Support
1781 @cindex language support
1782 @value{GDBN}'s language support is mainly driven by the symbol reader,
1783 although it is possible for the user to set the source language
1786 @value{GDBN} chooses the source language by looking at the extension
1787 of the file recorded in the debug info; @file{.c} means C, @file{.f}
1788 means Fortran, etc. It may also use a special-purpose language
1789 identifier if the debug format supports it, like with DWARF.
1791 @section Adding a Source Language to @value{GDBN}
1793 @cindex adding source language
1794 To add other languages to @value{GDBN}'s expression parser, follow the
1798 @item Create the expression parser.
1800 @cindex expression parser
1801 This should reside in a file @file{@var{lang}-exp.y}. Routines for
1802 building parsed expressions into a @code{union exp_element} list are in
1805 @cindex language parser
1806 Since we can't depend upon everyone having Bison, and YACC produces
1807 parsers that define a bunch of global names, the following lines
1808 @strong{must} be included at the top of the YACC parser, to prevent the
1809 various parsers from defining the same global names:
1812 #define yyparse @var{lang}_parse
1813 #define yylex @var{lang}_lex
1814 #define yyerror @var{lang}_error
1815 #define yylval @var{lang}_lval
1816 #define yychar @var{lang}_char
1817 #define yydebug @var{lang}_debug
1818 #define yypact @var{lang}_pact
1819 #define yyr1 @var{lang}_r1
1820 #define yyr2 @var{lang}_r2
1821 #define yydef @var{lang}_def
1822 #define yychk @var{lang}_chk
1823 #define yypgo @var{lang}_pgo
1824 #define yyact @var{lang}_act
1825 #define yyexca @var{lang}_exca
1826 #define yyerrflag @var{lang}_errflag
1827 #define yynerrs @var{lang}_nerrs
1830 At the bottom of your parser, define a @code{struct language_defn} and
1831 initialize it with the right values for your language. Define an
1832 @code{initialize_@var{lang}} routine and have it call
1833 @samp{add_language(@var{lang}_language_defn)} to tell the rest of @value{GDBN}
1834 that your language exists. You'll need some other supporting variables
1835 and functions, which will be used via pointers from your
1836 @code{@var{lang}_language_defn}. See the declaration of @code{struct
1837 language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
1838 for more information.
1840 @item Add any evaluation routines, if necessary
1842 @cindex expression evaluation routines
1843 @findex evaluate_subexp
1844 @findex prefixify_subexp
1845 @findex length_of_subexp
1846 If you need new opcodes (that represent the operations of the language),
1847 add them to the enumerated type in @file{expression.h}. Add support
1848 code for these operations in the @code{evaluate_subexp} function
1849 defined in the file @file{eval.c}. Add cases
1850 for new opcodes in two functions from @file{parse.c}:
1851 @code{prefixify_subexp} and @code{length_of_subexp}. These compute
1852 the number of @code{exp_element}s that a given operation takes up.
1854 @item Update some existing code
1856 Add an enumerated identifier for your language to the enumerated type
1857 @code{enum language} in @file{defs.h}.
1859 Update the routines in @file{language.c} so your language is included.
1860 These routines include type predicates and such, which (in some cases)
1861 are language dependent. If your language does not appear in the switch
1862 statement, an error is reported.
1864 @vindex current_language
1865 Also included in @file{language.c} is the code that updates the variable
1866 @code{current_language}, and the routines that translate the
1867 @code{language_@var{lang}} enumerated identifier into a printable
1870 @findex _initialize_language
1871 Update the function @code{_initialize_language} to include your
1872 language. This function picks the default language upon startup, so is
1873 dependent upon which languages that @value{GDBN} is built for.
1875 @findex allocate_symtab
1876 Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
1877 code so that the language of each symtab (source file) is set properly.
1878 This is used to determine the language to use at each stack frame level.
1879 Currently, the language is set based upon the extension of the source
1880 file. If the language can be better inferred from the symbol
1881 information, please set the language of the symtab in the symbol-reading
1884 @findex print_subexp
1885 @findex op_print_tab
1886 Add helper code to @code{print_subexp} (in @file{expprint.c}) to handle any new
1887 expression opcodes you have added to @file{expression.h}. Also, add the
1888 printed representations of your operators to @code{op_print_tab}.
1890 @item Add a place of call
1893 Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
1894 @code{parse_exp_1} (defined in @file{parse.c}).
1896 @item Use macros to trim code
1898 @cindex trimming language-dependent code
1899 The user has the option of building @value{GDBN} for some or all of the
1900 languages. If the user decides to build @value{GDBN} for the language
1901 @var{lang}, then every file dependent on @file{language.h} will have the
1902 macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to
1903 leave out large routines that the user won't need if he or she is not
1904 using your language.
1906 Note that you do not need to do this in your YACC parser, since if @value{GDBN}
1907 is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
1908 compiled form of your parser) is not linked into @value{GDBN} at all.
1910 See the file @file{configure.in} for how @value{GDBN} is configured
1911 for different languages.
1913 @item Edit @file{Makefile.in}
1915 Add dependencies in @file{Makefile.in}. Make sure you update the macro
1916 variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
1917 not get linked in, or, worse yet, it may not get @code{tar}red into the
1922 @node Host Definition
1924 @chapter Host Definition
1926 @emph{Maintainer's note: In theory, new targets no longer need to use
1927 the host framework described below. Instead it should be possible to
1928 handle everything using autoconf. Patches eliminating this framework
1931 With the advent of Autoconf, it's rarely necessary to have host
1932 definition machinery anymore.
1934 @section Adding a New Host
1936 @cindex adding a new host
1937 @cindex host, adding
1938 Most of @value{GDBN}'s host configuration support happens via
1939 Autoconf. New host-specific definitions should be rarely needed.
1940 @value{GDBN} still uses the host-specific definitions and files listed
1941 below, but these mostly exist for historical reasons, and should
1942 eventually disappear.
1944 Several files control @value{GDBN}'s configuration for host systems:
1948 @item gdb/config/@var{arch}/@var{xyz}.mh
1949 Specifies Makefile fragments needed when hosting on machine @var{xyz}.
1950 In particular, this lists the required machine-dependent object files,
1951 by defining @samp{XDEPFILES=@dots{}}. Also specifies the header file
1952 which describes host @var{xyz}, by defining @code{XM_FILE=
1953 xm-@var{xyz}.h}. You can also define @code{CC}, @code{SYSV_DEFINE},
1954 @code{XM_CFLAGS}, @code{XM_ADD_FILES}, @code{XM_CLIBS}, @code{XM_CDEPS},
1955 etc.; see @file{Makefile.in}.
1957 @item gdb/config/@var{arch}/xm-@var{xyz}.h
1958 (@file{xm.h} is a link to this file, created by @code{configure}). Contains C
1959 macro definitions describing the host system environment, such as byte
1960 order, host C compiler and library.
1962 @item gdb/@var{xyz}-xdep.c
1963 Contains any miscellaneous C code required for this machine as a host.
1964 On most machines it doesn't exist at all. If it does exist, put
1965 @file{@var{xyz}-xdep.o} into the @code{XDEPFILES} line in
1966 @file{gdb/config/@var{arch}/@var{xyz}.mh}.
1969 @subheading Generic Host Support Files
1971 @cindex generic host support
1972 There are some ``generic'' versions of routines that can be used by
1973 various systems. These can be customized in various ways by macros
1974 defined in your @file{xm-@var{xyz}.h} file. If these routines work for
1975 the @var{xyz} host, you can just include the generic file's name (with
1976 @samp{.o}, not @samp{.c}) in @code{XDEPFILES}.
1978 Otherwise, if your machine needs custom support routines, you will need
1979 to write routines that perform the same functions as the generic file.
1980 Put them into @code{@var{xyz}-xdep.c}, and put @code{@var{xyz}-xdep.o}
1981 into @code{XDEPFILES}.
1984 @cindex remote debugging support
1985 @cindex serial line support
1987 This contains serial line support for Unix systems. This is always
1988 included, via the makefile variable @code{SER_HARDWIRE}; override this
1989 variable in the @file{.mh} file to avoid it.
1992 This contains serial line support for 32-bit programs running under DOS,
1993 using the DJGPP (a.k.a.@: GO32) execution environment.
1995 @cindex TCP remote support
1997 This contains generic TCP support using sockets.
2000 @section Host Conditionals
2002 When @value{GDBN} is configured and compiled, various macros are
2003 defined or left undefined, to control compilation based on the
2004 attributes of the host system. These macros and their meanings (or if
2005 the meaning is not documented here, then one of the source files where
2006 they are used is indicated) are:
2009 @item @value{GDBN}INIT_FILENAME
2010 The default name of @value{GDBN}'s initialization file (normally
2013 @item MEM_FNS_DECLARED
2014 Your host config file defines this if it includes declarations of
2015 @code{memcpy} and @code{memset}. Define this to avoid conflicts between
2016 the native include files and the declarations in @file{defs.h}.
2019 This macro is deprecated.
2022 Define this if your system does not have a @code{<sys/file.h>}.
2024 @item SIGWINCH_HANDLER
2025 If your host defines @code{SIGWINCH}, you can define this to be the name
2026 of a function to be called if @code{SIGWINCH} is received.
2028 @item SIGWINCH_HANDLER_BODY
2029 Define this to expand into code that will define the function named by
2030 the expansion of @code{SIGWINCH_HANDLER}.
2032 @item ALIGN_STACK_ON_STARTUP
2033 @cindex stack alignment
2034 Define this if your system is of a sort that will crash in
2035 @code{tgetent} if the stack happens not to be longword-aligned when
2036 @code{main} is called. This is a rare situation, but is known to occur
2037 on several different types of systems.
2039 @item CRLF_SOURCE_FILES
2040 @cindex DOS text files
2041 Define this if host files use @code{\r\n} rather than @code{\n} as a
2042 line terminator. This will cause source file listings to omit @code{\r}
2043 characters when printing and it will allow @code{\r\n} line endings of files
2044 which are ``sourced'' by gdb. It must be possible to open files in binary
2045 mode using @code{O_BINARY} or, for fopen, @code{"rb"}.
2047 @item DEFAULT_PROMPT
2049 The default value of the prompt string (normally @code{"(gdb) "}).
2052 @cindex terminal device
2053 The name of the generic TTY device, defaults to @code{"/dev/tty"}.
2055 @item FCLOSE_PROVIDED
2056 Define this if the system declares @code{fclose} in the headers included
2057 in @code{defs.h}. This isn't needed unless your compiler is unusually
2061 Define this if binary files are opened the same way as text files.
2063 @item GETENV_PROVIDED
2064 Define this if the system declares @code{getenv} in its headers included
2065 in @code{defs.h}. This isn't needed unless your compiler is unusually
2070 In some cases, use the system call @code{mmap} for reading symbol
2071 tables. For some machines this allows for sharing and quick updates.
2073 @item HAVE_SIGSETMASK
2075 Define this if the host system has job control, but does not define
2076 @code{sigsetmask}. Currently, this is only true of the RS/6000.
2079 Define this if the host system has @code{termio.h}.
2081 @item HOST_BYTE_ORDER
2083 The ordering of bytes in the host. This must be defined to be either
2084 @code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}.
2091 Values for host-side constants.
2094 Substitute for isatty, if not available.
2097 This is the longest integer type available on the host. If not defined,
2098 it will default to @code{long long} or @code{long}, depending on
2099 @code{CC_HAS_LONG_LONG}.
2101 @item CC_HAS_LONG_LONG
2102 @cindex @code{long long} data type
2103 Define this if the host C compiler supports @code{long long}. This is set
2104 by the @code{configure} script.
2106 @item PRINTF_HAS_LONG_LONG
2107 Define this if the host can handle printing of long long integers via
2108 the printf format conversion specifier @code{ll}. This is set by the
2109 @code{configure} script.
2111 @item HAVE_LONG_DOUBLE
2112 Define this if the host C compiler supports @code{long double}. This is
2113 set by the @code{configure} script.
2115 @item PRINTF_HAS_LONG_DOUBLE
2116 Define this if the host can handle printing of long double float-point
2117 numbers via the printf format conversion specifier @code{Lg}. This is
2118 set by the @code{configure} script.
2120 @item SCANF_HAS_LONG_DOUBLE
2121 Define this if the host can handle the parsing of long double
2122 float-point numbers via the scanf format conversion specifier
2123 @code{Lg}. This is set by the @code{configure} script.
2125 @item LSEEK_NOT_LINEAR
2126 Define this if @code{lseek (n)} does not necessarily move to byte number
2127 @code{n} in the file. This is only used when reading source files. It
2128 is normally faster to define @code{CRLF_SOURCE_FILES} when possible.
2131 This macro is used as the argument to @code{lseek} (or, most commonly,
2132 @code{bfd_seek}). FIXME, should be replaced by SEEK_SET instead,
2133 which is the POSIX equivalent.
2135 @item MALLOC_INCOMPATIBLE
2136 Define this if the system's prototype for @code{malloc} differs from the
2137 @sc{ansi} definition.
2139 @item MMAP_BASE_ADDRESS
2140 When using HAVE_MMAP, the first mapping should go at this address.
2142 @item MMAP_INCREMENT
2143 when using HAVE_MMAP, this is the increment between mappings.
2145 @item NEED_POSIX_SETPGID
2147 Define this to use the POSIX version of @code{setpgid} to determine
2148 whether job control is available.
2151 If defined, this should be one or more tokens, such as @code{volatile},
2152 that can be used in both the declaration and definition of functions to
2153 indicate that they never return. The default is already set correctly
2154 if compiling with GCC. This will almost never need to be defined.
2157 If defined, this should be one or more tokens, such as
2158 @code{__attribute__ ((noreturn))}, that can be used in the declarations
2159 of functions to indicate that they never return. The default is already
2160 set correctly if compiling with GCC. This will almost never need to be
2163 @item USE_GENERIC_DUMMY_FRAMES
2164 @cindex generic dummy frames
2165 Define this to 1 if the target is using the generic inferior function
2166 call code. See @code{blockframe.c} for more information.
2170 @value{GDBN} will use the @code{mmalloc} library for memory allocation
2171 for symbol reading if this symbol is defined. Be careful defining it
2172 since there are systems on which @code{mmalloc} does not work for some
2173 reason. One example is the DECstation, where its RPC library can't
2174 cope with our redefinition of @code{malloc} to call @code{mmalloc}.
2175 When defining @code{USE_MMALLOC}, you will also have to set
2176 @code{MMALLOC} in the Makefile, to point to the @code{mmalloc} library. This
2177 define is set when you configure with @samp{--with-mmalloc}.
2181 Define this if you are using @code{mmalloc}, but don't want the overhead
2182 of checking the heap with @code{mmcheck}. Note that on some systems,
2183 the C runtime makes calls to @code{malloc} prior to calling @code{main}, and if
2184 @code{free} is ever called with these pointers after calling
2185 @code{mmcheck} to enable checking, a memory corruption abort is certain
2186 to occur. These systems can still use @code{mmalloc}, but must define
2190 Define this to 1 if the C runtime allocates memory prior to
2191 @code{mmcheck} being called, but that memory is never freed so we don't
2192 have to worry about it triggering a memory corruption abort. The
2193 default is 0, which means that @code{mmcheck} will only install the heap
2194 checking functions if there has not yet been any memory allocation
2195 calls, and if it fails to install the functions, @value{GDBN} will issue a
2196 warning. This is currently defined if you configure using
2197 @samp{--with-mmalloc}.
2199 @item NO_SIGINTERRUPT
2200 @findex siginterrupt
2201 Define this to indicate that @code{siginterrupt} is not available.
2204 Define if this is not in a system header file (typically, @file{unistd.h}).
2208 Define these to appropriate value for the system @code{lseek}, if not already
2212 This is the signal for stopping @value{GDBN}. Defaults to
2213 @code{SIGTSTP}. (Only redefined for the Convex.)
2216 Define this if the interior's tty should be opened with the @code{O_NOCTTY}
2217 flag. (FIXME: This should be a native-only flag, but @file{inflow.c} is
2221 Means that System V (prior to SVR4) include files are in use. (FIXME:
2222 This symbol is abused in @file{infrun.c}, @file{regex.c},
2223 @file{remote-nindy.c}, and @file{utils.c} for other things, at the
2227 Define this to help placate @code{lint} in some situations.
2230 Define this to override the defaults of @code{__volatile__} or
2235 @node Target Architecture Definition
2237 @chapter Target Architecture Definition
2239 @cindex target architecture definition
2240 @value{GDBN}'s target architecture defines what sort of
2241 machine-language programs @value{GDBN} can work with, and how it works
2244 The target architecture object is implemented as the C structure
2245 @code{struct gdbarch *}. The structure, and its methods, are generated
2246 using the Bourn shell script @file{gdbarch.sh}.
2248 @section Registers and Memory
2250 @value{GDBN}'s model of the target machine is rather simple.
2251 @value{GDBN} assumes the machine includes a bank of registers and a
2252 block of memory. Each register may have a different size.
2254 @value{GDBN} does not have a magical way to match up with the
2255 compiler's idea of which registers are which; however, it is critical
2256 that they do match up accurately. The only way to make this work is
2257 to get accurate information about the order that the compiler uses,
2258 and to reflect that in the @code{REGISTER_NAME} and related macros.
2260 @value{GDBN} can handle big-endian, little-endian, and bi-endian architectures.
2262 @section Pointers Are Not Always Addresses
2263 @cindex pointer representation
2264 @cindex address representation
2265 @cindex word-addressed machines
2266 @cindex separate data and code address spaces
2267 @cindex spaces, separate data and code address
2268 @cindex address spaces, separate data and code
2269 @cindex code pointers, word-addressed
2270 @cindex converting between pointers and addresses
2271 @cindex D10V addresses
2273 On almost all 32-bit architectures, the representation of a pointer is
2274 indistinguishable from the representation of some fixed-length number
2275 whose value is the byte address of the object pointed to. On such
2276 machines, the words ``pointer'' and ``address'' can be used interchangeably.
2277 However, architectures with smaller word sizes are often cramped for
2278 address space, so they may choose a pointer representation that breaks this
2279 identity, and allows a larger code address space.
2281 For example, the Mitsubishi D10V is a 16-bit VLIW processor whose
2282 instructions are 32 bits long@footnote{Some D10V instructions are
2283 actually pairs of 16-bit sub-instructions. However, since you can't
2284 jump into the middle of such a pair, code addresses can only refer to
2285 full 32 bit instructions, which is what matters in this explanation.}.
2286 If the D10V used ordinary byte addresses to refer to code locations,
2287 then the processor would only be able to address 64kb of instructions.
2288 However, since instructions must be aligned on four-byte boundaries, the
2289 low two bits of any valid instruction's byte address are always
2290 zero---byte addresses waste two bits. So instead of byte addresses,
2291 the D10V uses word addresses---byte addresses shifted right two bits---to
2292 refer to code. Thus, the D10V can use 16-bit words to address 256kb of
2295 However, this means that code pointers and data pointers have different
2296 forms on the D10V. The 16-bit word @code{0xC020} refers to byte address
2297 @code{0xC020} when used as a data address, but refers to byte address
2298 @code{0x30080} when used as a code address.
2300 (The D10V also uses separate code and data address spaces, which also
2301 affects the correspondence between pointers and addresses, but we're
2302 going to ignore that here; this example is already too long.)
2304 To cope with architectures like this---the D10V is not the only
2305 one!---@value{GDBN} tries to distinguish between @dfn{addresses}, which are
2306 byte numbers, and @dfn{pointers}, which are the target's representation
2307 of an address of a particular type of data. In the example above,
2308 @code{0xC020} is the pointer, which refers to one of the addresses
2309 @code{0xC020} or @code{0x30080}, depending on the type imposed upon it.
2310 @value{GDBN} provides functions for turning a pointer into an address
2311 and vice versa, in the appropriate way for the current architecture.
2313 Unfortunately, since addresses and pointers are identical on almost all
2314 processors, this distinction tends to bit-rot pretty quickly. Thus,
2315 each time you port @value{GDBN} to an architecture which does
2316 distinguish between pointers and addresses, you'll probably need to
2317 clean up some architecture-independent code.
2319 Here are functions which convert between pointers and addresses:
2321 @deftypefun CORE_ADDR extract_typed_address (void *@var{buf}, struct type *@var{type})
2322 Treat the bytes at @var{buf} as a pointer or reference of type
2323 @var{type}, and return the address it represents, in a manner
2324 appropriate for the current architecture. This yields an address
2325 @value{GDBN} can use to read target memory, disassemble, etc. Note that
2326 @var{buf} refers to a buffer in @value{GDBN}'s memory, not the
2329 For example, if the current architecture is the Intel x86, this function
2330 extracts a little-endian integer of the appropriate length from
2331 @var{buf} and returns it. However, if the current architecture is the
2332 D10V, this function will return a 16-bit integer extracted from
2333 @var{buf}, multiplied by four if @var{type} is a pointer to a function.
2335 If @var{type} is not a pointer or reference type, then this function
2336 will signal an internal error.
2339 @deftypefun CORE_ADDR store_typed_address (void *@var{buf}, struct type *@var{type}, CORE_ADDR @var{addr})
2340 Store the address @var{addr} in @var{buf}, in the proper format for a
2341 pointer of type @var{type} in the current architecture. Note that
2342 @var{buf} refers to a buffer in @value{GDBN}'s memory, not the
2345 For example, if the current architecture is the Intel x86, this function
2346 stores @var{addr} unmodified as a little-endian integer of the
2347 appropriate length in @var{buf}. However, if the current architecture
2348 is the D10V, this function divides @var{addr} by four if @var{type} is
2349 a pointer to a function, and then stores it in @var{buf}.
2351 If @var{type} is not a pointer or reference type, then this function
2352 will signal an internal error.
2355 @deftypefun CORE_ADDR value_as_pointer (value_ptr @var{val})
2356 Assuming that @var{val} is a pointer, return the address it represents,
2357 as appropriate for the current architecture.
2359 This function actually works on integral values, as well as pointers.
2360 For pointers, it performs architecture-specific conversions as
2361 described above for @code{extract_typed_address}.
2364 @deftypefun CORE_ADDR value_from_pointer (struct type *@var{type}, CORE_ADDR @var{addr})
2365 Create and return a value representing a pointer of type @var{type} to
2366 the address @var{addr}, as appropriate for the current architecture.
2367 This function performs architecture-specific conversions as described
2368 above for @code{store_typed_address}.
2372 @value{GDBN} also provides functions that do the same tasks, but assume
2373 that pointers are simply byte addresses; they aren't sensitive to the
2374 current architecture, beyond knowing the appropriate endianness.
2376 @deftypefun CORE_ADDR extract_address (void *@var{addr}, int len)
2377 Extract a @var{len}-byte number from @var{addr} in the appropriate
2378 endianness for the current architecture, and return it. Note that
2379 @var{addr} refers to @value{GDBN}'s memory, not the inferior's.
2381 This function should only be used in architecture-specific code; it
2382 doesn't have enough information to turn bits into a true address in the
2383 appropriate way for the current architecture. If you can, use
2384 @code{extract_typed_address} instead.
2387 @deftypefun void store_address (void *@var{addr}, int @var{len}, LONGEST @var{val})
2388 Store @var{val} at @var{addr} as a @var{len}-byte integer, in the
2389 appropriate endianness for the current architecture. Note that
2390 @var{addr} refers to a buffer in @value{GDBN}'s memory, not the
2393 This function should only be used in architecture-specific code; it
2394 doesn't have enough information to turn a true address into bits in the
2395 appropriate way for the current architecture. If you can, use
2396 @code{store_typed_address} instead.
2400 Here are some macros which architectures can define to indicate the
2401 relationship between pointers and addresses. These have default
2402 definitions, appropriate for architectures on which all pointers are
2403 simple byte addresses.
2405 @deftypefn {Target Macro} CORE_ADDR POINTER_TO_ADDRESS (struct type *@var{type}, char *@var{buf})
2406 Assume that @var{buf} holds a pointer of type @var{type}, in the
2407 appropriate format for the current architecture. Return the byte
2408 address the pointer refers to.
2410 This function may safely assume that @var{type} is either a pointer or a
2411 C@t{++} reference type.
2414 @deftypefn {Target Macro} void ADDRESS_TO_POINTER (struct type *@var{type}, char *@var{buf}, CORE_ADDR @var{addr})
2415 Store in @var{buf} a pointer of type @var{type} representing the address
2416 @var{addr}, in the appropriate format for the current architecture.
2418 This function may safely assume that @var{type} is either a pointer or a
2419 C@t{++} reference type.
2423 @section Using Different Register and Memory Data Representations
2424 @cindex raw representation
2425 @cindex virtual representation
2426 @cindex representations, raw and virtual
2427 @cindex register data formats, converting
2428 @cindex @code{struct value}, converting register contents to
2430 @emph{Maintainer's note: The way GDB manipulates registers is undergoing
2431 significant change. Many of the macros and functions refered to in the
2432 sections below are likely to be made obsolete. See the file @file{TODO}
2433 for more up-to-date information.}
2435 Some architectures use one representation for a value when it lives in a
2436 register, but use a different representation when it lives in memory.
2437 In @value{GDBN}'s terminology, the @dfn{raw} representation is the one used in
2438 the target registers, and the @dfn{virtual} representation is the one
2439 used in memory, and within @value{GDBN} @code{struct value} objects.
2441 For almost all data types on almost all architectures, the virtual and
2442 raw representations are identical, and no special handling is needed.
2443 However, they do occasionally differ. For example:
2447 The x86 architecture supports an 80-bit @code{long double} type. However, when
2448 we store those values in memory, they occupy twelve bytes: the
2449 floating-point number occupies the first ten, and the final two bytes
2450 are unused. This keeps the values aligned on four-byte boundaries,
2451 allowing more efficient access. Thus, the x86 80-bit floating-point
2452 type is the raw representation, and the twelve-byte loosely-packed
2453 arrangement is the virtual representation.
2456 Some 64-bit MIPS targets present 32-bit registers to @value{GDBN} as 64-bit
2457 registers, with garbage in their upper bits. @value{GDBN} ignores the top 32
2458 bits. Thus, the 64-bit form, with garbage in the upper 32 bits, is the
2459 raw representation, and the trimmed 32-bit representation is the
2460 virtual representation.
2463 In general, the raw representation is determined by the architecture, or
2464 @value{GDBN}'s interface to the architecture, while the virtual representation
2465 can be chosen for @value{GDBN}'s convenience. @value{GDBN}'s register file,
2466 @code{registers}, holds the register contents in raw format, and the
2467 @value{GDBN} remote protocol transmits register values in raw format.
2469 Your architecture may define the following macros to request
2470 conversions between the raw and virtual format:
2472 @deftypefn {Target Macro} int REGISTER_CONVERTIBLE (int @var{reg})
2473 Return non-zero if register number @var{reg}'s value needs different raw
2474 and virtual formats.
2476 You should not use @code{REGISTER_CONVERT_TO_VIRTUAL} for a register
2477 unless this macro returns a non-zero value for that register.
2480 @deftypefn {Target Macro} int REGISTER_RAW_SIZE (int @var{reg})
2481 The size of register number @var{reg}'s raw value. This is the number
2482 of bytes the register will occupy in @code{registers}, or in a @value{GDBN}
2483 remote protocol packet.
2486 @deftypefn {Target Macro} int REGISTER_VIRTUAL_SIZE (int @var{reg})
2487 The size of register number @var{reg}'s value, in its virtual format.
2488 This is the size a @code{struct value}'s buffer will have, holding that
2492 @deftypefn {Target Macro} struct type *REGISTER_VIRTUAL_TYPE (int @var{reg})
2493 This is the type of the virtual representation of register number
2494 @var{reg}. Note that there is no need for a macro giving a type for the
2495 register's raw form; once the register's value has been obtained, @value{GDBN}
2496 always uses the virtual form.
2499 @deftypefn {Target Macro} void REGISTER_CONVERT_TO_VIRTUAL (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to})
2500 Convert the value of register number @var{reg} to @var{type}, which
2501 should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
2502 at @var{from} holds the register's value in raw format; the macro should
2503 convert the value to virtual format, and place it at @var{to}.
2505 Note that @code{REGISTER_CONVERT_TO_VIRTUAL} and
2506 @code{REGISTER_CONVERT_TO_RAW} take their @var{reg} and @var{type}
2507 arguments in different orders.
2509 You should only use @code{REGISTER_CONVERT_TO_VIRTUAL} with registers
2510 for which the @code{REGISTER_CONVERTIBLE} macro returns a non-zero
2514 @deftypefn {Target Macro} void REGISTER_CONVERT_TO_RAW (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to})
2515 Convert the value of register number @var{reg} to @var{type}, which
2516 should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
2517 at @var{from} holds the register's value in raw format; the macro should
2518 convert the value to virtual format, and place it at @var{to}.
2520 Note that REGISTER_CONVERT_TO_VIRTUAL and REGISTER_CONVERT_TO_RAW take
2521 their @var{reg} and @var{type} arguments in different orders.
2525 @section Frame Interpretation
2527 @section Inferior Call Setup
2529 @section Compiler Characteristics
2531 @section Target Conditionals
2533 This section describes the macros that you can use to define the target
2538 @item ADDITIONAL_OPTIONS
2539 @itemx ADDITIONAL_OPTION_CASES
2540 @itemx ADDITIONAL_OPTION_HANDLER
2541 @itemx ADDITIONAL_OPTION_HELP
2542 @findex ADDITIONAL_OPTION_HELP
2543 @findex ADDITIONAL_OPTION_HANDLER
2544 @findex ADDITIONAL_OPTION_CASES
2545 @findex ADDITIONAL_OPTIONS
2546 These are a set of macros that allow the addition of additional command
2547 line options to @value{GDBN}. They are currently used only for the unsupported
2548 i960 Nindy target, and should not be used in any other configuration.
2550 @item ADDR_BITS_REMOVE (addr)
2551 @findex ADDR_BITS_REMOVE
2552 If a raw machine instruction address includes any bits that are not
2553 really part of the address, then define this macro to expand into an
2554 expression that zeroes those bits in @var{addr}. This is only used for
2555 addresses of instructions, and even then not in all contexts.
2557 For example, the two low-order bits of the PC on the Hewlett-Packard PA
2558 2.0 architecture contain the privilege level of the corresponding
2559 instruction. Since instructions must always be aligned on four-byte
2560 boundaries, the processor masks out these bits to generate the actual
2561 address of the instruction. ADDR_BITS_REMOVE should filter out these
2562 bits with an expression such as @code{((addr) & ~3)}.
2564 @item ADDRESS_TO_POINTER (@var{type}, @var{buf}, @var{addr})
2565 @findex ADDRESS_TO_POINTER
2566 Store in @var{buf} a pointer of type @var{type} representing the address
2567 @var{addr}, in the appropriate format for the current architecture.
2568 This macro may safely assume that @var{type} is either a pointer or a
2569 C@t{++} reference type.
2570 @xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
2572 @item BEFORE_MAIN_LOOP_HOOK
2573 @findex BEFORE_MAIN_LOOP_HOOK
2574 Define this to expand into any code that you want to execute before the
2575 main loop starts. Although this is not, strictly speaking, a target
2576 conditional, that is how it is currently being used. Note that if a
2577 configuration were to define it one way for a host and a different way
2578 for the target, @value{GDBN} will probably not compile, let alone run
2579 correctly. This macro is currently used only for the unsupported i960 Nindy
2580 target, and should not be used in any other configuration.
2582 @item BELIEVE_PCC_PROMOTION
2583 @findex BELIEVE_PCC_PROMOTION
2584 Define if the compiler promotes a @code{short} or @code{char}
2585 parameter to an @code{int}, but still reports the parameter as its
2586 original type, rather than the promoted type.
2588 @item BELIEVE_PCC_PROMOTION_TYPE
2589 @findex BELIEVE_PCC_PROMOTION_TYPE
2590 Define this if @value{GDBN} should believe the type of a @code{short}
2591 argument when compiled by @code{pcc}, but look within a full int space to get
2592 its value. Only defined for Sun-3 at present.
2594 @item BITS_BIG_ENDIAN
2595 @findex BITS_BIG_ENDIAN
2596 Define this if the numbering of bits in the targets does @strong{not} match the
2597 endianness of the target byte order. A value of 1 means that the bits
2598 are numbered in a big-endian bit order, 0 means little-endian.
2602 This is the character array initializer for the bit pattern to put into
2603 memory where a breakpoint is set. Although it's common to use a trap
2604 instruction for a breakpoint, it's not required; for instance, the bit
2605 pattern could be an invalid instruction. The breakpoint must be no
2606 longer than the shortest instruction of the architecture.
2608 @code{BREAKPOINT} has been deprecated in favor of
2609 @code{BREAKPOINT_FROM_PC}.
2611 @item BIG_BREAKPOINT
2612 @itemx LITTLE_BREAKPOINT
2613 @findex LITTLE_BREAKPOINT
2614 @findex BIG_BREAKPOINT
2615 Similar to BREAKPOINT, but used for bi-endian targets.
2617 @code{BIG_BREAKPOINT} and @code{LITTLE_BREAKPOINT} have been deprecated in
2618 favor of @code{BREAKPOINT_FROM_PC}.
2620 @item REMOTE_BREAKPOINT
2621 @itemx LITTLE_REMOTE_BREAKPOINT
2622 @itemx BIG_REMOTE_BREAKPOINT
2623 @findex BIG_REMOTE_BREAKPOINT
2624 @findex LITTLE_REMOTE_BREAKPOINT
2625 @findex REMOTE_BREAKPOINT
2626 Similar to BREAKPOINT, but used for remote targets.
2628 @code{BIG_REMOTE_BREAKPOINT} and @code{LITTLE_REMOTE_BREAKPOINT} have been
2629 deprecated in favor of @code{BREAKPOINT_FROM_PC}.
2631 @item BREAKPOINT_FROM_PC (@var{pcptr}, @var{lenptr})
2632 @findex BREAKPOINT_FROM_PC
2633 Use the program counter to determine the contents and size of a
2634 breakpoint instruction. It returns a pointer to a string of bytes
2635 that encode a breakpoint instruction, stores the length of the string
2636 to *@var{lenptr}, and adjusts pc (if necessary) to point to the actual
2637 memory location where the breakpoint should be inserted.
2639 Although it is common to use a trap instruction for a breakpoint, it's
2640 not required; for instance, the bit pattern could be an invalid
2641 instruction. The breakpoint must be no longer than the shortest
2642 instruction of the architecture.
2644 Replaces all the other @var{BREAKPOINT} macros.
2646 @item MEMORY_INSERT_BREAKPOINT (@var{addr}, @var{contents_cache})
2647 @itemx MEMORY_REMOVE_BREAKPOINT (@var{addr}, @var{contents_cache})
2648 @findex MEMORY_REMOVE_BREAKPOINT
2649 @findex MEMORY_INSERT_BREAKPOINT
2650 Insert or remove memory based breakpoints. Reasonable defaults
2651 (@code{default_memory_insert_breakpoint} and
2652 @code{default_memory_remove_breakpoint} respectively) have been
2653 provided so that it is not necessary to define these for most
2654 architectures. Architectures which may want to define
2655 @code{MEMORY_INSERT_BREAKPOINT} and @code{MEMORY_REMOVE_BREAKPOINT} will
2656 likely have instructions that are oddly sized or are not stored in a
2657 conventional manner.
2659 It may also be desirable (from an efficiency standpoint) to define
2660 custom breakpoint insertion and removal routines if
2661 @code{BREAKPOINT_FROM_PC} needs to read the target's memory for some
2665 @findex CALL_DUMMY_P
2666 A C expresson that is non-zero when the target suports inferior function
2669 @item CALL_DUMMY_WORDS
2670 @findex CALL_DUMMY_WORDS
2671 Pointer to an array of @code{LONGEST} words of data containing
2672 host-byte-ordered @code{REGISTER_BYTES} sized values that partially
2673 specify the sequence of instructions needed for an inferior function
2676 Should be deprecated in favor of a macro that uses target-byte-ordered
2679 @item SIZEOF_CALL_DUMMY_WORDS
2680 @findex SIZEOF_CALL_DUMMY_WORDS
2681 The size of @code{CALL_DUMMY_WORDS}. When @code{CALL_DUMMY_P} this must
2682 return a positive value. See also @code{CALL_DUMMY_LENGTH}.
2686 A static initializer for @code{CALL_DUMMY_WORDS}. Deprecated.
2688 @item CALL_DUMMY_LOCATION
2689 @findex CALL_DUMMY_LOCATION
2690 See the file @file{inferior.h}.
2692 @item CALL_DUMMY_STACK_ADJUST
2693 @findex CALL_DUMMY_STACK_ADJUST
2694 Stack adjustment needed when performing an inferior function call.
2696 Should be deprecated in favor of something like @code{STACK_ALIGN}.
2698 @item CALL_DUMMY_STACK_ADJUST_P
2699 @findex CALL_DUMMY_STACK_ADJUST_P
2700 Predicate for use of @code{CALL_DUMMY_STACK_ADJUST}.
2702 Should be deprecated in favor of something like @code{STACK_ALIGN}.
2704 @item CANNOT_FETCH_REGISTER (@var{regno})
2705 @findex CANNOT_FETCH_REGISTER
2706 A C expression that should be nonzero if @var{regno} cannot be fetched
2707 from an inferior process. This is only relevant if
2708 @code{FETCH_INFERIOR_REGISTERS} is not defined.
2710 @item CANNOT_STORE_REGISTER (@var{regno})
2711 @findex CANNOT_STORE_REGISTER
2712 A C expression that should be nonzero if @var{regno} should not be
2713 written to the target. This is often the case for program counters,
2714 status words, and other special registers. If this is not defined,
2715 @value{GDBN} will assume that all registers may be written.
2717 @item DO_DEFERRED_STORES
2718 @itemx CLEAR_DEFERRED_STORES
2719 @findex CLEAR_DEFERRED_STORES
2720 @findex DO_DEFERRED_STORES
2721 Define this to execute any deferred stores of registers into the inferior,
2722 and to cancel any deferred stores.
2724 Currently only implemented correctly for native Sparc configurations?
2726 @item COERCE_FLOAT_TO_DOUBLE (@var{formal}, @var{actual})
2727 @findex COERCE_FLOAT_TO_DOUBLE
2728 @cindex promotion to @code{double}
2729 If we are calling a function by hand, and the function was declared
2730 (according to the debug info) without a prototype, should we
2731 automatically promote @code{float}s to @code{double}s? This macro
2732 must evaluate to non-zero if we should, or zero if we should leave the
2735 The argument @var{actual} is the type of the value we want to pass to
2736 the function. The argument @var{formal} is the type of this argument,
2737 as it appears in the function's definition. Note that @var{formal} may
2738 be zero if we have no debugging information for the function, or if
2739 we're passing more arguments than are officially declared (for example,
2740 varargs). This macro is never invoked if the function definitely has a
2743 @findex set_gdbarch_coerce_float_to_double
2744 @findex standard_coerce_float_to_double
2745 The default behavior is to promote only when we have no type information
2746 for the formal parameter. This is different from the obvious behavior,
2747 which would be to promote whenever we have no prototype, just as the
2748 compiler does. It's annoying, but some older targets rely on this. If
2749 you want @value{GDBN} to follow the typical compiler behavior---to always
2750 promote when there is no prototype in scope---your gdbarch @code{init}
2751 function can call @code{set_gdbarch_coerce_float_to_double} and select
2752 the @code{standard_coerce_float_to_double} function.
2755 @findex CPLUS_MARKERz
2756 Define this to expand into the character that G@t{++} uses to distinguish
2757 compiler-generated identifiers from programmer-specified identifiers.
2758 By default, this expands into @code{'$'}. Most System V targets should
2759 define this to @code{'.'}.
2761 @item DBX_PARM_SYMBOL_CLASS
2762 @findex DBX_PARM_SYMBOL_CLASS
2763 Hook for the @code{SYMBOL_CLASS} of a parameter when decoding DBX symbol
2764 information. In the i960, parameters can be stored as locals or as
2765 args, depending on the type of the debug record.
2767 @item DECR_PC_AFTER_BREAK
2768 @findex DECR_PC_AFTER_BREAK
2769 Define this to be the amount by which to decrement the PC after the
2770 program encounters a breakpoint. This is often the number of bytes in
2771 @code{BREAKPOINT}, though not always. For most targets this value will be 0.
2773 @item DECR_PC_AFTER_HW_BREAK
2774 @findex DECR_PC_AFTER_HW_BREAK
2775 Similarly, for hardware breakpoints.
2777 @item DISABLE_UNSETTABLE_BREAK (@var{addr})
2778 @findex DISABLE_UNSETTABLE_BREAK
2779 If defined, this should evaluate to 1 if @var{addr} is in a shared
2780 library in which breakpoints cannot be set and so should be disabled.
2782 @item DO_REGISTERS_INFO
2783 @findex DO_REGISTERS_INFO
2784 If defined, use this to print the value of a register or all registers.
2786 @item DWARF_REG_TO_REGNUM
2787 @findex DWARF_REG_TO_REGNUM
2788 Convert DWARF register number into @value{GDBN} regnum. If not defined,
2789 no conversion will be performed.
2791 @item DWARF2_REG_TO_REGNUM
2792 @findex DWARF2_REG_TO_REGNUM
2793 Convert DWARF2 register number into @value{GDBN} regnum. If not
2794 defined, no conversion will be performed.
2796 @item ECOFF_REG_TO_REGNUM
2797 @findex ECOFF_REG_TO_REGNUM
2798 Convert ECOFF register number into @value{GDBN} regnum. If not defined,
2799 no conversion will be performed.
2801 @item END_OF_TEXT_DEFAULT
2802 @findex END_OF_TEXT_DEFAULT
2803 This is an expression that should designate the end of the text section.
2806 @item EXTRACT_RETURN_VALUE(@var{type}, @var{regbuf}, @var{valbuf})
2807 @findex EXTRACT_RETURN_VALUE
2808 Define this to extract a function's return value of type @var{type} from
2809 the raw register state @var{regbuf} and copy that, in virtual format,
2812 @item EXTRACT_STRUCT_VALUE_ADDRESS(@var{regbuf})
2813 @findex EXTRACT_STRUCT_VALUE_ADDRESS
2814 When defined, extract from the array @var{regbuf} (containing the raw
2815 register state) the @code{CORE_ADDR} at which a function should return
2816 its structure value.
2818 If not defined, @code{EXTRACT_RETURN_VALUE} is used.
2820 @item EXTRACT_STRUCT_VALUE_ADDRESS_P()
2821 @findex EXTRACT_STRUCT_VALUE_ADDRESS_P
2822 Predicate for @code{EXTRACT_STRUCT_VALUE_ADDRESS}.
2826 If defined, then the @samp{info float} command will print information about
2827 the processor's floating point unit.
2831 If the virtual frame pointer is kept in a register, then define this
2832 macro to be the number (greater than or equal to zero) of that register.
2834 This should only need to be defined if @code{TARGET_READ_FP} and
2835 @code{TARGET_WRITE_FP} are not defined.
2837 @item FRAMELESS_FUNCTION_INVOCATION(@var{fi})
2838 @findex FRAMELESS_FUNCTION_INVOCATION
2839 Define this to an expression that returns 1 if the function invocation
2840 represented by @var{fi} does not have a stack frame associated with it.
2843 @item FRAME_ARGS_ADDRESS_CORRECT
2844 @findex FRAME_ARGS_ADDRESS_CORRECT
2847 @item FRAME_CHAIN(@var{frame})
2849 Given @var{frame}, return a pointer to the calling frame.
2851 @item FRAME_CHAIN_COMBINE(@var{chain}, @var{frame})
2852 @findex FRAME_CHAIN_COMBINE
2853 Define this to take the frame chain pointer and the frame's nominal
2854 address and produce the nominal address of the caller's frame.
2855 Presently only defined for HP PA.
2857 @item FRAME_CHAIN_VALID(@var{chain}, @var{thisframe})
2858 @findex FRAME_CHAIN_VALID
2859 Define this to be an expression that returns zero if the given frame is
2860 an outermost frame, with no caller, and nonzero otherwise. Several
2861 common definitions are available:
2865 @code{file_frame_chain_valid} is nonzero if the chain pointer is nonzero
2866 and given frame's PC is not inside the startup file (such as
2870 @code{func_frame_chain_valid} is nonzero if the chain
2871 pointer is nonzero and the given frame's PC is not in @code{main} or a
2872 known entry point function (such as @code{_start}).
2875 @code{generic_file_frame_chain_valid} and
2876 @code{generic_func_frame_chain_valid} are equivalent implementations for
2877 targets using generic dummy frames.
2880 @item FRAME_INIT_SAVED_REGS(@var{frame})
2881 @findex FRAME_INIT_SAVED_REGS
2882 See @file{frame.h}. Determines the address of all registers in the
2883 current stack frame storing each in @code{frame->saved_regs}. Space for
2884 @code{frame->saved_regs} shall be allocated by
2885 @code{FRAME_INIT_SAVED_REGS} using either
2886 @code{frame_saved_regs_zalloc} or @code{frame_obstack_alloc}.
2888 @code{FRAME_FIND_SAVED_REGS} and @code{EXTRA_FRAME_INFO} are deprecated.
2890 @item FRAME_NUM_ARGS (@var{fi})
2891 @findex FRAME_NUM_ARGS
2892 For the frame described by @var{fi} return the number of arguments that
2893 are being passed. If the number of arguments is not known, return
2896 @item FRAME_SAVED_PC(@var{frame})
2897 @findex FRAME_SAVED_PC
2898 Given @var{frame}, return the pc saved there. This is the return
2901 @item FUNCTION_EPILOGUE_SIZE
2902 @findex FUNCTION_EPILOGUE_SIZE
2903 For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the
2904 function end symbol is 0. For such targets, you must define
2905 @code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a
2906 function's epilogue.
2908 @item FUNCTION_START_OFFSET
2909 @findex FUNCTION_START_OFFSET
2910 An integer, giving the offset in bytes from a function's address (as
2911 used in the values of symbols, function pointers, etc.), and the
2912 function's first genuine instruction.
2914 This is zero on almost all machines: the function's address is usually
2915 the address of its first instruction. However, on the VAX, for example,
2916 each function starts with two bytes containing a bitmask indicating
2917 which registers to save upon entry to the function. The VAX @code{call}
2918 instructions check this value, and save the appropriate registers
2919 automatically. Thus, since the offset from the function's address to
2920 its first instruction is two bytes, @code{FUNCTION_START_OFFSET} would
2923 @item GCC_COMPILED_FLAG_SYMBOL
2924 @itemx GCC2_COMPILED_FLAG_SYMBOL
2925 @findex GCC2_COMPILED_FLAG_SYMBOL
2926 @findex GCC_COMPILED_FLAG_SYMBOL
2927 If defined, these are the names of the symbols that @value{GDBN} will
2928 look for to detect that GCC compiled the file. The default symbols
2929 are @code{gcc_compiled.} and @code{gcc2_compiled.},
2930 respectively. (Currently only defined for the Delta 68.)
2932 @item @value{GDBN}_MULTI_ARCH
2933 @findex @value{GDBN}_MULTI_ARCH
2934 If defined and non-zero, enables suport for multiple architectures
2935 within @value{GDBN}.
2937 This support can be enabled at two levels. At level one, only
2938 definitions for previously undefined macros are provided; at level two,
2939 a multi-arch definition of all architecture dependant macros will be
2942 @item @value{GDBN}_TARGET_IS_HPPA
2943 @findex @value{GDBN}_TARGET_IS_HPPA
2944 This determines whether horrible kludge code in @file{dbxread.c} and
2945 @file{partial-stab.h} is used to mangle multiple-symbol-table files from
2946 HPPA's. This should all be ripped out, and a scheme like @file{elfread.c}
2949 @item GET_LONGJMP_TARGET
2950 @findex GET_LONGJMP_TARGET
2951 For most machines, this is a target-dependent parameter. On the
2952 DECstation and the Iris, this is a native-dependent parameter, since
2953 trhe header file @file{setjmp.h} is needed to define it.
2955 This macro determines the target PC address that @code{longjmp} will jump to,
2956 assuming that we have just stopped at a @code{longjmp} breakpoint. It takes a
2957 @code{CORE_ADDR *} as argument, and stores the target PC value through this
2958 pointer. It examines the current state of the machine as needed.
2960 @item GET_SAVED_REGISTER
2961 @findex GET_SAVED_REGISTER
2962 @findex get_saved_register
2963 Define this if you need to supply your own definition for the function
2964 @code{get_saved_register}.
2966 @item HAVE_REGISTER_WINDOWS
2967 @findex HAVE_REGISTER_WINDOWS
2968 Define this if the target has register windows.
2970 @item REGISTER_IN_WINDOW_P (@var{regnum})
2971 @findex REGISTER_IN_WINDOW_P
2972 Define this to be an expression that is 1 if the given register is in
2975 @item IBM6000_TARGET
2976 @findex IBM6000_TARGET
2977 Shows that we are configured for an IBM RS/6000 target. This
2978 conditional should be eliminated (FIXME) and replaced by
2979 feature-specific macros. It was introduced in a haste and we are
2980 repenting at leisure.
2982 @item I386_USE_GENERIC_WATCHPOINTS
2983 An x86-based target can define this to use the generic x86 watchpoint
2984 support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}.
2986 @item SYMBOLS_CAN_START_WITH_DOLLAR
2987 @findex SYMBOLS_CAN_START_WITH_DOLLAR
2988 Some systems have routines whose names start with @samp{$}. Giving this
2989 macro a non-zero value tells @value{GDBN}'s expression parser to check for such
2990 routines when parsing tokens that begin with @samp{$}.
2992 On HP-UX, certain system routines (millicode) have names beginning with
2993 @samp{$} or @samp{$$}. For example, @code{$$dyncall} is a millicode
2994 routine that handles inter-space procedure calls on PA-RISC.
2998 Define this if the target system uses IEEE-format floating point numbers.
3000 @item INIT_EXTRA_FRAME_INFO (@var{fromleaf}, @var{frame})
3001 @findex INIT_EXTRA_FRAME_INFO
3002 If additional information about the frame is required this should be
3003 stored in @code{frame->extra_info}. Space for @code{frame->extra_info}
3004 is allocated using @code{frame_obstack_alloc}.
3006 @item INIT_FRAME_PC (@var{fromleaf}, @var{prev})
3007 @findex INIT_FRAME_PC
3008 This is a C statement that sets the pc of the frame pointed to by
3009 @var{prev}. [By default...]
3011 @item INNER_THAN (@var{lhs}, @var{rhs})
3013 Returns non-zero if stack address @var{lhs} is inner than (nearer to the
3014 stack top) stack address @var{rhs}. Define this as @code{lhs < rhs} if
3015 the target's stack grows downward in memory, or @code{lhs > rsh} if the
3018 @item IN_SIGTRAMP (@var{pc}, @var{name})
3020 Define this to return non-zero if the given @var{pc} and/or @var{name}
3021 indicates that the current function is a @code{sigtramp}.
3023 @item SIGTRAMP_START (@var{pc})
3024 @findex SIGTRAMP_START
3025 @itemx SIGTRAMP_END (@var{pc})
3026 @findex SIGTRAMP_END
3027 Define these to be the start and end address of the @code{sigtramp} for the
3028 given @var{pc}. On machines where the address is just a compile time
3029 constant, the macro expansion will typically just ignore the supplied
3032 @item IN_SOLIB_CALL_TRAMPOLINE (@var{pc}, @var{name})
3033 @findex IN_SOLIB_CALL_TRAMPOLINE
3034 Define this to evaluate to nonzero if the program is stopped in the
3035 trampoline that connects to a shared library.
3037 @item IN_SOLIB_RETURN_TRAMPOLINE (@var{pc}, @var{name})
3038 @findex IN_SOLIB_RETURN_TRAMPOLINE
3039 Define this to evaluate to nonzero if the program is stopped in the
3040 trampoline that returns from a shared library.
3042 @item IN_SOLIB_DYNSYM_RESOLVE_CODE (@var{pc})
3043 @findex IN_SOLIB_DYNSYM_RESOLVE_CODE
3044 Define this to evaluate to nonzero if the program is stopped in the
3047 @item SKIP_SOLIB_RESOLVER (@var{pc})
3048 @findex SKIP_SOLIB_RESOLVER
3049 Define this to evaluate to the (nonzero) address at which execution
3050 should continue to get past the dynamic linker's symbol resolution
3051 function. A zero value indicates that it is not important or necessary
3052 to set a breakpoint to get through the dynamic linker and that single
3053 stepping will suffice.
3055 @item IS_TRAPPED_INTERNALVAR (@var{name})
3056 @findex IS_TRAPPED_INTERNALVAR
3057 This is an ugly hook to allow the specification of special actions that
3058 should occur as a side-effect of setting the value of a variable
3059 internal to @value{GDBN}. Currently only used by the h8500. Note that this
3060 could be either a host or target conditional.
3062 @item NEED_TEXT_START_END
3063 @findex NEED_TEXT_START_END
3064 Define this if @value{GDBN} should determine the start and end addresses of the
3065 text section. (Seems dubious.)
3067 @item NO_HIF_SUPPORT
3068 @findex NO_HIF_SUPPORT
3069 (Specific to the a29k.)
3071 @item POINTER_TO_ADDRESS (@var{type}, @var{buf})
3072 @findex POINTER_TO_ADDRESS
3073 Assume that @var{buf} holds a pointer of type @var{type}, in the
3074 appropriate format for the current architecture. Return the byte
3075 address the pointer refers to.
3076 @xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
3078 @item REGISTER_CONVERTIBLE (@var{reg})
3079 @findex REGISTER_CONVERTIBLE
3080 Return non-zero if @var{reg} uses different raw and virtual formats.
3081 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
3083 @item REGISTER_RAW_SIZE (@var{reg})
3084 @findex REGISTER_RAW_SIZE
3085 Return the raw size of @var{reg}.
3086 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
3088 @item REGISTER_VIRTUAL_SIZE (@var{reg})
3089 @findex REGISTER_VIRTUAL_SIZE
3090 Return the virtual size of @var{reg}.
3091 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
3093 @item REGISTER_VIRTUAL_TYPE (@var{reg})
3094 @findex REGISTER_VIRTUAL_TYPE
3095 Return the virtual type of @var{reg}.
3096 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
3098 @item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to})
3099 @findex REGISTER_CONVERT_TO_VIRTUAL
3100 Convert the value of register @var{reg} from its raw form to its virtual
3102 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
3104 @item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to})
3105 @findex REGISTER_CONVERT_TO_RAW
3106 Convert the value of register @var{reg} from its virtual form to its raw
3108 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
3110 @item RETURN_VALUE_ON_STACK(@var{type})
3111 @findex RETURN_VALUE_ON_STACK
3112 @cindex returning structures by value
3113 @cindex structures, returning by value
3115 Return non-zero if values of type TYPE are returned on the stack, using
3116 the ``struct convention'' (i.e., the caller provides a pointer to a
3117 buffer in which the callee should store the return value). This
3118 controls how the @samp{finish} command finds a function's return value,
3119 and whether an inferior function call reserves space on the stack for
3122 The full logic @value{GDBN} uses here is kind of odd.
3126 If the type being returned by value is not a structure, union, or array,
3127 and @code{RETURN_VALUE_ON_STACK} returns zero, then @value{GDBN}
3128 concludes the value is not returned using the struct convention.
3131 Otherwise, @value{GDBN} calls @code{USE_STRUCT_CONVENTION} (see below).
3132 If that returns non-zero, @value{GDBN} assumes the struct convention is
3136 In other words, to indicate that a given type is returned by value using
3137 the struct convention, that type must be either a struct, union, array,
3138 or something @code{RETURN_VALUE_ON_STACK} likes, @emph{and} something
3139 that @code{USE_STRUCT_CONVENTION} likes.
3141 Note that, in C and C@t{++}, arrays are never returned by value. In those
3142 languages, these predicates will always see a pointer type, never an
3143 array type. All the references above to arrays being returned by value
3144 apply only to other languages.
3146 @item SOFTWARE_SINGLE_STEP_P()
3147 @findex SOFTWARE_SINGLE_STEP_P
3148 Define this as 1 if the target does not have a hardware single-step
3149 mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined.
3151 @item SOFTWARE_SINGLE_STEP(@var{signal}, @var{insert_breapoints_p})
3152 @findex SOFTWARE_SINGLE_STEP
3153 A function that inserts or removes (depending on
3154 @var{insert_breapoints_p}) breakpoints at each possible destinations of
3155 the next instruction. See @file{sparc-tdep.c} and @file{rs6000-tdep.c}
3158 @item SOFUN_ADDRESS_MAYBE_MISSING
3159 @findex SOFUN_ADDRESS_MAYBE_MISSING
3160 Somebody clever observed that, the more actual addresses you have in the
3161 debug information, the more time the linker has to spend relocating
3162 them. So whenever there's some other way the debugger could find the
3163 address it needs, you should omit it from the debug info, to make
3166 @code{SOFUN_ADDRESS_MAYBE_MISSING} indicates that a particular set of
3167 hacks of this sort are in use, affecting @code{N_SO} and @code{N_FUN}
3168 entries in stabs-format debugging information. @code{N_SO} stabs mark
3169 the beginning and ending addresses of compilation units in the text
3170 segment. @code{N_FUN} stabs mark the starts and ends of functions.
3172 @code{SOFUN_ADDRESS_MAYBE_MISSING} means two things:
3176 @code{N_FUN} stabs have an address of zero. Instead, you should find the
3177 addresses where the function starts by taking the function name from
3178 the stab, and then looking that up in the minsyms (the
3179 linker/assembler symbol table). In other words, the stab has the
3180 name, and the linker/assembler symbol table is the only place that carries
3184 @code{N_SO} stabs have an address of zero, too. You just look at the
3185 @code{N_FUN} stabs that appear before and after the @code{N_SO} stab,
3186 and guess the starting and ending addresses of the compilation unit from
3190 @item PCC_SOL_BROKEN
3191 @findex PCC_SOL_BROKEN
3192 (Used only in the Convex target.)
3194 @item PC_IN_CALL_DUMMY
3195 @findex PC_IN_CALL_DUMMY
3196 See @file{inferior.h}.
3198 @item PC_LOAD_SEGMENT
3199 @findex PC_LOAD_SEGMENT
3200 If defined, print information about the load segment for the program
3201 counter. (Defined only for the RS/6000.)
3205 If the program counter is kept in a register, then define this macro to
3206 be the number (greater than or equal to zero) of that register.
3208 This should only need to be defined if @code{TARGET_READ_PC} and
3209 @code{TARGET_WRITE_PC} are not defined.
3213 The number of the ``next program counter'' register, if defined.
3217 The number of the ``next next program counter'' register, if defined.
3218 Currently, this is only defined for the Motorola 88K.
3221 @findex PARM_BOUNDARY
3222 If non-zero, round arguments to a boundary of this many bits before
3223 pushing them on the stack.
3225 @item PRINT_REGISTER_HOOK (@var{regno})
3226 @findex PRINT_REGISTER_HOOK
3227 If defined, this must be a function that prints the contents of the
3228 given register to standard output.
3230 @item PRINT_TYPELESS_INTEGER
3231 @findex PRINT_TYPELESS_INTEGER
3232 This is an obscure substitute for @code{print_longest} that seems to
3233 have been defined for the Convex target.
3235 @item PROCESS_LINENUMBER_HOOK
3236 @findex PROCESS_LINENUMBER_HOOK
3237 A hook defined for XCOFF reading.
3239 @item PROLOGUE_FIRSTLINE_OVERLAP
3240 @findex PROLOGUE_FIRSTLINE_OVERLAP
3241 (Only used in unsupported Convex configuration.)
3245 If defined, this is the number of the processor status register. (This
3246 definition is only used in generic code when parsing "$ps".)
3250 @findex call_function_by_hand
3251 @findex return_command
3252 Used in @samp{call_function_by_hand} to remove an artificial stack
3253 frame and in @samp{return_command} to remove a real stack frame.
3255 @item PUSH_ARGUMENTS (@var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr})
3256 @findex PUSH_ARGUMENTS
3257 Define this to push arguments onto the stack for inferior function
3258 call. Returns the updated stack pointer value.
3260 @item PUSH_DUMMY_FRAME
3261 @findex PUSH_DUMMY_FRAME
3262 Used in @samp{call_function_by_hand} to create an artificial stack frame.
3264 @item REGISTER_BYTES
3265 @findex REGISTER_BYTES
3266 The total amount of space needed to store @value{GDBN}'s copy of the machine's
3269 @item REGISTER_NAME(@var{i})
3270 @findex REGISTER_NAME
3271 Return the name of register @var{i} as a string. May return @code{NULL}
3272 or @code{NUL} to indicate that register @var{i} is not valid.
3274 @item REGISTER_NAMES
3275 @findex REGISTER_NAMES
3276 Deprecated in favor of @code{REGISTER_NAME}.
3278 @item REG_STRUCT_HAS_ADDR (@var{gcc_p}, @var{type})
3279 @findex REG_STRUCT_HAS_ADDR
3280 Define this to return 1 if the given type will be passed by pointer
3281 rather than directly.
3283 @item SAVE_DUMMY_FRAME_TOS (@var{sp})
3284 @findex SAVE_DUMMY_FRAME_TOS
3285 Used in @samp{call_function_by_hand} to notify the target dependent code
3286 of the top-of-stack value that will be passed to the the inferior code.
3287 This is the value of the @code{SP} after both the dummy frame and space
3288 for parameters/results have been allocated on the stack.
3290 @item SDB_REG_TO_REGNUM
3291 @findex SDB_REG_TO_REGNUM
3292 Define this to convert sdb register numbers into @value{GDBN} regnums. If not
3293 defined, no conversion will be done.
3295 @item SHIFT_INST_REGS
3296 @findex SHIFT_INST_REGS
3297 (Only used for m88k targets.)
3299 @item SKIP_PERMANENT_BREAKPOINT
3300 @findex SKIP_PERMANENT_BREAKPOINT
3301 Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally
3302 steps over a breakpoint by removing it, stepping one instruction, and
3303 re-inserting the breakpoint. However, permanent breakpoints are
3304 hardwired into the inferior, and can't be removed, so this strategy
3305 doesn't work. Calling @code{SKIP_PERMANENT_BREAKPOINT} adjusts the processor's
3306 state so that execution will resume just after the breakpoint. This
3307 macro does the right thing even when the breakpoint is in the delay slot
3308 of a branch or jump.
3310 @item SKIP_PROLOGUE (@var{pc})
3311 @findex SKIP_PROLOGUE
3312 A C expression that returns the address of the ``real'' code beyond the
3313 function entry prologue found at @var{pc}.
3315 @item SKIP_PROLOGUE_FRAMELESS_P
3316 @findex SKIP_PROLOGUE_FRAMELESS_P
3317 A C expression that should behave similarly, but that can stop as soon
3318 as the function is known to have a frame. If not defined,
3319 @code{SKIP_PROLOGUE} will be used instead.
3321 @item SKIP_TRAMPOLINE_CODE (@var{pc})
3322 @findex SKIP_TRAMPOLINE_CODE
3323 If the target machine has trampoline code that sits between callers and
3324 the functions being called, then define this macro to return a new PC
3325 that is at the start of the real function.
3329 If the stack-pointer is kept in a register, then define this macro to be
3330 the number (greater than or equal to zero) of that register.
3332 This should only need to be defined if @code{TARGET_WRITE_SP} and
3333 @code{TARGET_WRITE_SP} are not defined.
3335 @item STAB_REG_TO_REGNUM
3336 @findex STAB_REG_TO_REGNUM
3337 Define this to convert stab register numbers (as gotten from `r'
3338 declarations) into @value{GDBN} regnums. If not defined, no conversion will be
3341 @item STACK_ALIGN (@var{addr})
3343 Define this to adjust the address to the alignment required for the
3346 @item STEP_SKIPS_DELAY (@var{addr})
3347 @findex STEP_SKIPS_DELAY
3348 Define this to return true if the address is of an instruction with a
3349 delay slot. If a breakpoint has been placed in the instruction's delay
3350 slot, @value{GDBN} will single-step over that instruction before resuming
3351 normally. Currently only defined for the Mips.
3353 @item STORE_RETURN_VALUE (@var{type}, @var{valbuf})
3354 @findex STORE_RETURN_VALUE
3355 A C expression that stores a function return value of type @var{type},
3356 where @var{valbuf} is the address of the value to be stored.
3358 @item SUN_FIXED_LBRAC_BUG
3359 @findex SUN_FIXED_LBRAC_BUG
3360 (Used only for Sun-3 and Sun-4 targets.)
3362 @item SYMBOL_RELOADING_DEFAULT
3363 @findex SYMBOL_RELOADING_DEFAULT
3364 The default value of the ``symbol-reloading'' variable. (Never defined in
3367 @item TARGET_BYTE_ORDER_DEFAULT
3368 @findex TARGET_BYTE_ORDER_DEFAULT
3369 The ordering of bytes in the target. This must be either
3370 @code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. This macro replaces
3371 @code{TARGET_BYTE_ORDER} which is deprecated.
3373 @item TARGET_BYTE_ORDER_SELECTABLE_P
3374 @findex TARGET_BYTE_ORDER_SELECTABLE_P
3375 Non-zero if the target has both @code{BIG_ENDIAN} and
3376 @code{LITTLE_ENDIAN} variants. This macro replaces
3377 @code{TARGET_BYTE_ORDER_SELECTABLE} which is deprecated.
3379 @item TARGET_CHAR_BIT
3380 @findex TARGET_CHAR_BIT
3381 Number of bits in a char; defaults to 8.
3383 @item TARGET_COMPLEX_BIT
3384 @findex TARGET_COMPLEX_BIT
3385 Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}.
3387 At present this macro is not used.
3389 @item TARGET_DOUBLE_BIT
3390 @findex TARGET_DOUBLE_BIT
3391 Number of bits in a double float; defaults to @code{8 * TARGET_CHAR_BIT}.
3393 @item TARGET_DOUBLE_COMPLEX_BIT
3394 @findex TARGET_DOUBLE_COMPLEX_BIT
3395 Number of bits in a double complex; defaults to @code{2 * TARGET_DOUBLE_BIT}.
3397 At present this macro is not used.
3399 @item TARGET_FLOAT_BIT
3400 @findex TARGET_FLOAT_BIT
3401 Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}.
3403 @item TARGET_INT_BIT
3404 @findex TARGET_INT_BIT
3405 Number of bits in an integer; defaults to @code{4 * TARGET_CHAR_BIT}.
3407 @item TARGET_LONG_BIT
3408 @findex TARGET_LONG_BIT
3409 Number of bits in a long integer; defaults to @code{4 * TARGET_CHAR_BIT}.
3411 @item TARGET_LONG_DOUBLE_BIT
3412 @findex TARGET_LONG_DOUBLE_BIT
3413 Number of bits in a long double float;
3414 defaults to @code{2 * TARGET_DOUBLE_BIT}.
3416 @item TARGET_LONG_LONG_BIT
3417 @findex TARGET_LONG_LONG_BIT
3418 Number of bits in a long long integer; defaults to @code{2 * TARGET_LONG_BIT}.
3420 @item TARGET_PTR_BIT
3421 @findex TARGET_PTR_BIT
3422 Number of bits in a pointer; defaults to @code{TARGET_INT_BIT}.
3424 @item TARGET_SHORT_BIT
3425 @findex TARGET_SHORT_BIT
3426 Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}.
3428 @item TARGET_READ_PC
3429 @findex TARGET_READ_PC
3430 @itemx TARGET_WRITE_PC (@var{val}, @var{pid})
3431 @findex TARGET_WRITE_PC
3432 @itemx TARGET_READ_SP
3433 @findex TARGET_READ_SP
3434 @itemx TARGET_WRITE_SP
3435 @findex TARGET_WRITE_SP
3436 @itemx TARGET_READ_FP
3437 @findex TARGET_READ_FP
3438 @itemx TARGET_WRITE_FP
3439 @findex TARGET_WRITE_FP
3446 These change the behavior of @code{read_pc}, @code{write_pc},
3447 @code{read_sp}, @code{write_sp}, @code{read_fp} and @code{write_fp}.
3448 For most targets, these may be left undefined. @value{GDBN} will call the read
3449 and write register functions with the relevant @code{_REGNUM} argument.
3451 These macros are useful when a target keeps one of these registers in a
3452 hard to get at place; for example, part in a segment register and part
3453 in an ordinary register.
3455 @item TARGET_VIRTUAL_FRAME_POINTER(@var{pc}, @var{regp}, @var{offsetp})
3456 @findex TARGET_VIRTUAL_FRAME_POINTER
3457 Returns a @code{(register, offset)} pair representing the virtual
3458 frame pointer in use at the code address @var{pc}. If virtual
3459 frame pointers are not used, a default definition simply returns
3460 @code{FP_REGNUM}, with an offset of zero.
3462 @item TARGET_HAS_HARDWARE_WATCHPOINTS
3463 If non-zero, the target has support for hardware-assisted
3464 watchpoints. @xref{Algorithms, watchpoints}, for more details and
3465 other related macros.
3467 @item USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type})
3468 @findex USE_STRUCT_CONVENTION
3469 If defined, this must be an expression that is nonzero if a value of the
3470 given @var{type} being returned from a function must have space
3471 allocated for it on the stack. @var{gcc_p} is true if the function
3472 being considered is known to have been compiled by GCC; this is helpful
3473 for systems where GCC is known to use different calling convention than
3476 @item VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p})
3477 @findex VARIABLES_INSIDE_BLOCK
3478 For dbx-style debugging information, if the compiler puts variable
3479 declarations inside LBRAC/RBRAC blocks, this should be defined to be
3480 nonzero. @var{desc} is the value of @code{n_desc} from the
3481 @code{N_RBRAC} symbol, and @var{gcc_p} is true if @value{GDBN} has noticed the
3482 presence of either the @code{GCC_COMPILED_SYMBOL} or the
3483 @code{GCC2_COMPILED_SYMBOL}. By default, this is 0.
3485 @item OS9K_VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p})
3486 @findex OS9K_VARIABLES_INSIDE_BLOCK
3487 Similarly, for OS/9000. Defaults to 1.
3490 Motorola M68K target conditionals.
3494 Define this to be the 4-bit location of the breakpoint trap vector. If
3495 not defined, it will default to @code{0xf}.
3497 @item REMOTE_BPT_VECTOR
3498 Defaults to @code{1}.
3501 @section Adding a New Target
3503 @cindex adding a target
3504 The following files add a target to @value{GDBN}:
3508 @item gdb/config/@var{arch}/@var{ttt}.mt
3509 Contains a Makefile fragment specific to this target. Specifies what
3510 object files are needed for target @var{ttt}, by defining
3511 @samp{TDEPFILES=@dots{}} and @samp{TDEPLIBS=@dots{}}. Also specifies
3512 the header file which describes @var{ttt}, by defining @samp{TM_FILE=
3515 You can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, @samp{TM_CDEPS},
3516 but these are now deprecated, replaced by autoconf, and may go away in
3517 future versions of @value{GDBN}.
3519 @item gdb/@var{ttt}-tdep.c
3520 Contains any miscellaneous code required for this target machine. On
3521 some machines it doesn't exist at all. Sometimes the macros in
3522 @file{tm-@var{ttt}.h} become very complicated, so they are implemented
3523 as functions here instead, and the macro is simply defined to call the
3524 function. This is vastly preferable, since it is easier to understand
3527 @item gdb/@var{arch}-tdep.c
3528 @itemx gdb/@var{arch}-tdep.h
3529 This often exists to describe the basic layout of the target machine's
3530 processor chip (registers, stack, etc.). If used, it is included by
3531 @file{@var{ttt}-tdep.h}. It can be shared among many targets that use
3534 @item gdb/config/@var{arch}/tm-@var{ttt}.h
3535 (@file{tm.h} is a link to this file, created by @code{configure}). Contains
3536 macro definitions about the target machine's registers, stack frame
3537 format and instructions.
3539 New targets do not need this file and should not create it.
3541 @item gdb/config/@var{arch}/tm-@var{arch}.h
3542 This often exists to describe the basic layout of the target machine's
3543 processor chip (registers, stack, etc.). If used, it is included by
3544 @file{tm-@var{ttt}.h}. It can be shared among many targets that use the
3547 New targets do not need this file and should not create it.
3551 If you are adding a new operating system for an existing CPU chip, add a
3552 @file{config/tm-@var{os}.h} file that describes the operating system
3553 facilities that are unusual (extra symbol table info; the breakpoint
3554 instruction needed; etc.). Then write a @file{@var{arch}/tm-@var{os}.h}
3555 that just @code{#include}s @file{tm-@var{arch}.h} and
3556 @file{config/tm-@var{os}.h}.
3559 @node Target Vector Definition
3561 @chapter Target Vector Definition
3562 @cindex target vector
3564 The target vector defines the interface between @value{GDBN}'s
3565 abstract handling of target systems, and the nitty-gritty code that
3566 actually exercises control over a process or a serial port.
3567 @value{GDBN} includes some 30-40 different target vectors; however,
3568 each configuration of @value{GDBN} includes only a few of them.
3570 @section File Targets
3572 Both executables and core files have target vectors.
3574 @section Standard Protocol and Remote Stubs
3576 @value{GDBN}'s file @file{remote.c} talks a serial protocol to code
3577 that runs in the target system. @value{GDBN} provides several sample
3578 @dfn{stubs} that can be integrated into target programs or operating
3579 systems for this purpose; they are named @file{*-stub.c}.
3581 The @value{GDBN} user's manual describes how to put such a stub into
3582 your target code. What follows is a discussion of integrating the
3583 SPARC stub into a complicated operating system (rather than a simple
3584 program), by Stu Grossman, the author of this stub.
3586 The trap handling code in the stub assumes the following upon entry to
3591 %l1 and %l2 contain pc and npc respectively at the time of the trap;
3597 you are in the correct trap window.
3600 As long as your trap handler can guarantee those conditions, then there
3601 is no reason why you shouldn't be able to ``share'' traps with the stub.
3602 The stub has no requirement that it be jumped to directly from the
3603 hardware trap vector. That is why it calls @code{exceptionHandler()},
3604 which is provided by the external environment. For instance, this could
3605 set up the hardware traps to actually execute code which calls the stub
3606 first, and then transfers to its own trap handler.
3608 For the most point, there probably won't be much of an issue with
3609 ``sharing'' traps, as the traps we use are usually not used by the kernel,
3610 and often indicate unrecoverable error conditions. Anyway, this is all
3611 controlled by a table, and is trivial to modify. The most important
3612 trap for us is for @code{ta 1}. Without that, we can't single step or
3613 do breakpoints. Everything else is unnecessary for the proper operation
3614 of the debugger/stub.
3616 From reading the stub, it's probably not obvious how breakpoints work.
3617 They are simply done by deposit/examine operations from @value{GDBN}.
3619 @section ROM Monitor Interface
3621 @section Custom Protocols
3623 @section Transport Layer
3625 @section Builtin Simulator
3628 @node Native Debugging
3630 @chapter Native Debugging
3631 @cindex native debugging
3633 Several files control @value{GDBN}'s configuration for native support:
3637 @item gdb/config/@var{arch}/@var{xyz}.mh
3638 Specifies Makefile fragments needed when hosting @emph{or native} on
3639 machine @var{xyz}. In particular, this lists the required
3640 native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}.
3641 Also specifies the header file which describes native support on
3642 @var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}. You can also
3643 define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS},
3644 @samp{NAT_CDEPS}, etc.; see @file{Makefile.in}.
3646 @item gdb/config/@var{arch}/nm-@var{xyz}.h
3647 (@file{nm.h} is a link to this file, created by @code{configure}). Contains C
3648 macro definitions describing the native system environment, such as
3649 child process control and core file support.
3651 @item gdb/@var{xyz}-nat.c
3652 Contains any miscellaneous C code required for this native support of
3653 this machine. On some machines it doesn't exist at all.
3656 There are some ``generic'' versions of routines that can be used by
3657 various systems. These can be customized in various ways by macros
3658 defined in your @file{nm-@var{xyz}.h} file. If these routines work for
3659 the @var{xyz} host, you can just include the generic file's name (with
3660 @samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.
3662 Otherwise, if your machine needs custom support routines, you will need
3663 to write routines that perform the same functions as the generic file.
3664 Put them into @file{@var{xyz}-nat.c}, and put @file{@var{xyz}-nat.o}
3665 into @code{NATDEPFILES}.
3669 This contains the @emph{target_ops vector} that supports Unix child
3670 processes on systems which use ptrace and wait to control the child.
3673 This contains the @emph{target_ops vector} that supports Unix child
3674 processes on systems which use /proc to control the child.
3677 This does the low-level grunge that uses Unix system calls to do a ``fork
3678 and exec'' to start up a child process.
3681 This is the low level interface to inferior processes for systems using
3682 the Unix @code{ptrace} call in a vanilla way.
3685 @section Native core file Support
3686 @cindex native core files
3689 @findex fetch_core_registers
3690 @item core-aout.c::fetch_core_registers()
3691 Support for reading registers out of a core file. This routine calls
3692 @code{register_addr()}, see below. Now that BFD is used to read core
3693 files, virtually all machines should use @code{core-aout.c}, and should
3694 just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or
3695 @code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}).
3697 @item core-aout.c::register_addr()
3698 If your @code{nm-@var{xyz}.h} file defines the macro
3699 @code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
3700 set @code{addr} to the offset within the @samp{user} struct of @value{GDBN}
3701 register number @code{regno}. @code{blockend} is the offset within the
3702 ``upage'' of @code{u.u_ar0}. If @code{REGISTER_U_ADDR} is defined,
3703 @file{core-aout.c} will define the @code{register_addr()} function and
3704 use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but
3705 you are using the standard @code{fetch_core_registers()}, you will need
3706 to define your own version of @code{register_addr()}, put it into your
3707 @code{@var{xyz}-nat.c} file, and be sure @code{@var{xyz}-nat.o} is in
3708 the @code{NATDEPFILES} list. If you have your own
3709 @code{fetch_core_registers()}, you may not need a separate
3710 @code{register_addr()}. Many custom @code{fetch_core_registers()}
3711 implementations simply locate the registers themselves.@refill
3714 When making @value{GDBN} run native on a new operating system, to make it
3715 possible to debug core files, you will need to either write specific
3716 code for parsing your OS's core files, or customize
3717 @file{bfd/trad-core.c}. First, use whatever @code{#include} files your
3718 machine uses to define the struct of registers that is accessible
3719 (possibly in the u-area) in a core file (rather than
3720 @file{machine/reg.h}), and an include file that defines whatever header
3721 exists on a core file (e.g. the u-area or a @code{struct core}). Then
3722 modify @code{trad_unix_core_file_p} to use these values to set up the
3723 section information for the data segment, stack segment, any other
3724 segments in the core file (perhaps shared library contents or control
3725 information), ``registers'' segment, and if there are two discontiguous
3726 sets of registers (e.g. integer and float), the ``reg2'' segment. This
3727 section information basically delimits areas in the core file in a
3728 standard way, which the section-reading routines in BFD know how to seek
3731 Then back in @value{GDBN}, you need a matching routine called
3732 @code{fetch_core_registers}. If you can use the generic one, it's in
3733 @file{core-aout.c}; if not, it's in your @file{@var{xyz}-nat.c} file.
3734 It will be passed a char pointer to the entire ``registers'' segment,
3735 its length, and a zero; or a char pointer to the entire ``regs2''
3736 segment, its length, and a 2. The routine should suck out the supplied
3737 register values and install them into @value{GDBN}'s ``registers'' array.
3739 If your system uses @file{/proc} to control processes, and uses ELF
3740 format core files, then you may be able to use the same routines for
3741 reading the registers out of processes and out of core files.
3749 @section shared libraries
3751 @section Native Conditionals
3752 @cindex native conditionals
3754 When @value{GDBN} is configured and compiled, various macros are
3755 defined or left undefined, to control compilation when the host and
3756 target systems are the same. These macros should be defined (or left
3757 undefined) in @file{nm-@var{system}.h}.
3761 @findex ATTACH_DETACH
3762 If defined, then @value{GDBN} will include support for the @code{attach} and
3763 @code{detach} commands.
3765 @item CHILD_PREPARE_TO_STORE
3766 @findex CHILD_PREPARE_TO_STORE
3767 If the machine stores all registers at once in the child process, then
3768 define this to ensure that all values are correct. This usually entails
3769 a read from the child.
3771 [Note that this is incorrectly defined in @file{xm-@var{system}.h} files
3774 @item FETCH_INFERIOR_REGISTERS
3775 @findex FETCH_INFERIOR_REGISTERS
3776 Define this if the native-dependent code will provide its own routines
3777 @code{fetch_inferior_registers} and @code{store_inferior_registers} in
3778 @file{@var{host}-nat.c}. If this symbol is @emph{not} defined, and
3779 @file{infptrace.c} is included in this configuration, the default
3780 routines in @file{infptrace.c} are used for these functions.
3782 @item FILES_INFO_HOOK
3783 @findex FILES_INFO_HOOK
3784 (Only defined for Convex.)
3788 This macro is normally defined to be the number of the first floating
3789 point register, if the machine has such registers. As such, it would
3790 appear only in target-specific code. However, @file{/proc} support uses this
3791 to decide whether floats are in use on this target.
3793 @item GET_LONGJMP_TARGET
3794 @findex GET_LONGJMP_TARGET
3795 For most machines, this is a target-dependent parameter. On the
3796 DECstation and the Iris, this is a native-dependent parameter, since
3797 @file{setjmp.h} is needed to define it.
3799 This macro determines the target PC address that @code{longjmp} will jump to,
3800 assuming that we have just stopped at a longjmp breakpoint. It takes a
3801 @code{CORE_ADDR *} as argument, and stores the target PC value through this
3802 pointer. It examines the current state of the machine as needed.
3804 @item I386_USE_GENERIC_WATCHPOINTS
3805 An x86-based machine can define this to use the generic x86 watchpoint
3806 support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}.
3809 @findex KERNEL_U_ADDR
3810 Define this to the address of the @code{u} structure (the ``user
3811 struct'', also known as the ``u-page'') in kernel virtual memory. @value{GDBN}
3812 needs to know this so that it can subtract this address from absolute
3813 addresses in the upage, that are obtained via ptrace or from core files.
3814 On systems that don't need this value, set it to zero.
3816 @item KERNEL_U_ADDR_BSD
3817 @findex KERNEL_U_ADDR_BSD
3818 Define this to cause @value{GDBN} to determine the address of @code{u} at
3819 runtime, by using Berkeley-style @code{nlist} on the kernel's image in
3822 @item KERNEL_U_ADDR_HPUX
3823 @findex KERNEL_U_ADDR_HPUX
3824 Define this to cause @value{GDBN} to determine the address of @code{u} at
3825 runtime, by using HP-style @code{nlist} on the kernel's image in the
3828 @item ONE_PROCESS_WRITETEXT
3829 @findex ONE_PROCESS_WRITETEXT
3830 Define this to be able to, when a breakpoint insertion fails, warn the
3831 user that another process may be running with the same executable.
3833 @item PREPARE_TO_PROCEED (@var{select_it})
3834 @findex PREPARE_TO_PROCEED
3835 This (ugly) macro allows a native configuration to customize the way the
3836 @code{proceed} function in @file{infrun.c} deals with switching between
3839 In a multi-threaded task we may select another thread and then continue
3840 or step. But if the old thread was stopped at a breakpoint, it will
3841 immediately cause another breakpoint stop without any execution (i.e. it
3842 will report a breakpoint hit incorrectly). So @value{GDBN} must step over it
3845 If defined, @code{PREPARE_TO_PROCEED} should check the current thread
3846 against the thread that reported the most recent event. If a step-over
3847 is required, it returns TRUE. If @var{select_it} is non-zero, it should
3848 reselect the old thread.
3851 @findex PROC_NAME_FMT
3852 Defines the format for the name of a @file{/proc} device. Should be
3853 defined in @file{nm.h} @emph{only} in order to override the default
3854 definition in @file{procfs.c}.
3857 @findex PTRACE_FP_BUG
3858 See @file{mach386-xdep.c}.
3860 @item PTRACE_ARG3_TYPE
3861 @findex PTRACE_ARG3_TYPE
3862 The type of the third argument to the @code{ptrace} system call, if it
3863 exists and is different from @code{int}.
3865 @item REGISTER_U_ADDR
3866 @findex REGISTER_U_ADDR
3867 Defines the offset of the registers in the ``u area''.
3869 @item SHELL_COMMAND_CONCAT
3870 @findex SHELL_COMMAND_CONCAT
3871 If defined, is a string to prefix on the shell command used to start the
3876 If defined, this is the name of the shell to use to run the inferior.
3877 Defaults to @code{"/bin/sh"}.
3879 @item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ})
3881 Define this to expand into an expression that will cause the symbols in
3882 @var{filename} to be added to @value{GDBN}'s symbol table.
3884 @item SOLIB_CREATE_INFERIOR_HOOK
3885 @findex SOLIB_CREATE_INFERIOR_HOOK
3886 Define this to expand into any shared-library-relocation code that you
3887 want to be run just after the child process has been forked.
3889 @item START_INFERIOR_TRAPS_EXPECTED
3890 @findex START_INFERIOR_TRAPS_EXPECTED
3891 When starting an inferior, @value{GDBN} normally expects to trap
3893 the shell execs, and once when the program itself execs. If the actual
3894 number of traps is something other than 2, then define this macro to
3895 expand into the number expected.
3897 @item SVR4_SHARED_LIBS
3898 @findex SVR4_SHARED_LIBS
3899 Define this to indicate that SVR4-style shared libraries are in use.
3903 This determines whether small routines in @file{*-tdep.c}, which
3904 translate register values between @value{GDBN}'s internal
3905 representation and the @file{/proc} representation, are compiled.
3908 @findex U_REGS_OFFSET
3909 This is the offset of the registers in the upage. It need only be
3910 defined if the generic ptrace register access routines in
3911 @file{infptrace.c} are being used (that is, @file{infptrace.c} is
3912 configured in, and @code{FETCH_INFERIOR_REGISTERS} is not defined). If
3913 the default value from @file{infptrace.c} is good enough, leave it
3916 The default value means that u.u_ar0 @emph{points to} the location of
3917 the registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means
3918 that @code{u.u_ar0} @emph{is} the location of the registers.
3922 See @file{objfiles.c}.
3925 @findex DEBUG_PTRACE
3926 Define this to debug @code{ptrace} calls.
3930 @node Support Libraries
3932 @chapter Support Libraries
3937 BFD provides support for @value{GDBN} in several ways:
3940 @item identifying executable and core files
3941 BFD will identify a variety of file types, including a.out, coff, and
3942 several variants thereof, as well as several kinds of core files.
3944 @item access to sections of files
3945 BFD parses the file headers to determine the names, virtual addresses,
3946 sizes, and file locations of all the various named sections in files
3947 (such as the text section or the data section). @value{GDBN} simply
3948 calls BFD to read or write section @var{x} at byte offset @var{y} for
3951 @item specialized core file support
3952 BFD provides routines to determine the failing command name stored in a
3953 core file, the signal with which the program failed, and whether a core
3954 file matches (i.e.@: could be a core dump of) a particular executable
3957 @item locating the symbol information
3958 @value{GDBN} uses an internal interface of BFD to determine where to find the
3959 symbol information in an executable file or symbol-file. @value{GDBN} itself
3960 handles the reading of symbols, since BFD does not ``understand'' debug
3961 symbols, but @value{GDBN} uses BFD's cached information to find the symbols,
3966 @cindex opcodes library
3968 The opcodes library provides @value{GDBN}'s disassembler. (It's a separate
3969 library because it's also used in binutils, for @file{objdump}).
3978 @cindex regular expressions library
3989 @item SIGN_EXTEND_CHAR
3991 @item SWITCH_ENUM_BUG
4006 This chapter covers topics that are lower-level than the major
4007 algorithms of @value{GDBN}.
4012 Cleanups are a structured way to deal with things that need to be done
4013 later. When your code does something (like @code{malloc} some memory,
4014 or open a file) that needs to be undone later (e.g., free the memory or
4015 close the file), it can make a cleanup. The cleanup will be done at
4016 some future point: when the command is finished, when an error occurs,
4017 or when your code decides it's time to do cleanups.
4019 You can also discard cleanups, that is, throw them away without doing
4020 what they say. This is only done if you ask that it be done.
4025 @item struct cleanup *@var{old_chain};
4026 Declare a variable which will hold a cleanup chain handle.
4028 @findex make_cleanup
4029 @item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
4030 Make a cleanup which will cause @var{function} to be called with
4031 @var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a
4032 handle that can be passed to @code{do_cleanups} or
4033 @code{discard_cleanups} later. Unless you are going to call
4034 @code{do_cleanups} or @code{discard_cleanups} yourself, you can ignore
4035 the result from @code{make_cleanup}.
4038 @item do_cleanups (@var{old_chain});
4039 Perform all cleanups done since @code{make_cleanup} returned
4040 @var{old_chain}. E.g.:
4043 make_cleanup (a, 0);
4044 old = make_cleanup (b, 0);
4049 will call @code{b()} but will not call @code{a()}. The cleanup that
4050 calls @code{a()} will remain in the cleanup chain, and will be done
4051 later unless otherwise discarded.@refill
4053 @findex discard_cleanups
4054 @item discard_cleanups (@var{old_chain});
4055 Same as @code{do_cleanups} except that it just removes the cleanups from
4056 the chain and does not call the specified functions.
4059 Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify
4060 that they ``should not be called when cleanups are not in place''. This
4061 means that any actions you need to reverse in the case of an error or
4062 interruption must be on the cleanup chain before you call these
4063 functions, since they might never return to your code (they
4064 @samp{longjmp} instead).
4066 @section Wrapping Output Lines
4067 @cindex line wrap in output
4070 Output that goes through @code{printf_filtered} or @code{fputs_filtered}
4071 or @code{fputs_demangled} needs only to have calls to @code{wrap_here}
4072 added in places that would be good breaking points. The utility
4073 routines will take care of actually wrapping if the line width is
4076 The argument to @code{wrap_here} is an indentation string which is
4077 printed @emph{only} if the line breaks there. This argument is saved
4078 away and used later. It must remain valid until the next call to
4079 @code{wrap_here} or until a newline has been printed through the
4080 @code{*_filtered} functions. Don't pass in a local variable and then
4083 It is usually best to call @code{wrap_here} after printing a comma or
4084 space. If you call it before printing a space, make sure that your
4085 indentation properly accounts for the leading space that will print if
4086 the line wraps there.
4088 Any function or set of functions that produce filtered output must
4089 finish by printing a newline, to flush the wrap buffer, before switching
4090 to unfiltered (@code{printf}) output. Symbol reading routines that
4091 print warnings are a good example.
4093 @section @value{GDBN} Coding Standards
4094 @cindex coding standards
4096 @value{GDBN} follows the GNU coding standards, as described in
4097 @file{etc/standards.texi}. This file is also available for anonymous
4098 FTP from GNU archive sites. @value{GDBN} takes a strict interpretation
4099 of the standard; in general, when the GNU standard recommends a practice
4100 but does not require it, @value{GDBN} requires it.
4102 @value{GDBN} follows an additional set of coding standards specific to
4103 @value{GDBN}, as described in the following sections.
4108 @value{GDBN} assumes an ISO-C compliant compiler.
4110 @value{GDBN} does not assume an ISO-C or POSIX compliant C library.
4113 @subsection Memory Management
4115 @value{GDBN} does not use the functions @code{malloc}, @code{realloc},
4116 @code{calloc}, @code{free} and @code{asprintf}.
4118 @value{GDBN} uses the functions @code{xmalloc}, @code{xrealloc} and
4119 @code{xcalloc} when allocating memory. Unlike @code{malloc} et.al.@:
4120 these functions do not return when the memory pool is empty. Instead,
4121 they unwind the stack using cleanups. These functions return
4122 @code{NULL} when requested to allocate a chunk of memory of size zero.
4124 @emph{Pragmatics: By using these functions, the need to check every
4125 memory allocation is removed. These functions provide portable
4128 @value{GDBN} does not use the function @code{free}.
4130 @value{GDBN} uses the function @code{xfree} to return memory to the
4131 memory pool. Consistent with ISO-C, this function ignores a request to
4132 free a @code{NULL} pointer.
4134 @emph{Pragmatics: On some systems @code{free} fails when passed a
4135 @code{NULL} pointer.}
4137 @value{GDBN} can use the non-portable function @code{alloca} for the
4138 allocation of small temporary values (such as strings).
4140 @emph{Pragmatics: This function is very non-portable. Some systems
4141 restrict the memory being allocated to no more than a few kilobytes.}
4143 @value{GDBN} uses the string function @code{xstrdup} and the print
4144 function @code{xasprintf}.
4146 @emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print
4147 functions such as @code{sprintf} are very prone to buffer overflow
4151 @subsection Compiler Warnings
4152 @cindex compiler warnings
4154 With few exceptions, developers should include the configuration option
4155 @samp{--enable-gdb-build-warnings=,-Werror} when building @value{GDBN}.
4156 The exceptions are listed in the file @file{gdb/MAINTAINERS}.
4158 This option causes @value{GDBN} (when built using GCC) to be compiled
4159 with a carefully selected list of compiler warning flags. Any warnings
4160 from those flags being treated as errors.
4162 The current list of warning flags includes:
4166 Since @value{GDBN} coding standard requires all functions to be declared
4167 using a prototype, the flag has the side effect of ensuring that
4168 prototyped functions are always visible with out resorting to
4169 @samp{-Wstrict-prototypes}.
4172 Such code often appears to work except on instruction set architectures
4173 that use register windows.
4180 Since @value{GDBN} uses the @code{format printf} attribute on all
4181 @code{printf} like functions this checks not just @code{printf} calls
4182 but also calls to functions such as @code{fprintf_unfiltered}.
4185 This warning includes uses of the assignment operator within an
4186 @code{if} statement.
4188 @item -Wpointer-arith
4190 @item -Wuninitialized
4193 @emph{Pragmatics: Due to the way that @value{GDBN} is implemented most
4194 functions have unused parameters. Consequently the warning
4195 @samp{-Wunused-parameter} is precluded from the list. The macro
4196 @code{ATTRIBUTE_UNUSED} is not used as it leads to false negatives ---
4197 it is not an error to have @code{ATTRIBUTE_UNUSED} on a parameter that
4198 is being used. The options @samp{-Wall} and @samp{-Wunused} are also
4199 precluded because they both include @samp{-Wunused-parameter}.}
4201 @emph{Pragmatics: @value{GDBN} has not simply accepted the warnings
4202 enabled by @samp{-Wall -Werror -W...}. Instead it is selecting warnings
4203 when and where their benefits can be demonstrated.}
4205 @subsection Formatting
4207 @cindex source code formatting
4208 The standard GNU recommendations for formatting must be followed
4211 A function declaration should not have its name in column zero. A
4212 function definition should have its name in column zero.
4216 static void foo (void);
4224 @emph{Pragmatics: This simplifies scripting. Function definitions can
4225 be found using @samp{^function-name}.}
4227 There must be a space between a function or macro name and the opening
4228 parenthesis of its argument list (except for macro definitions, as
4229 required by C). There must not be a space after an open paren/bracket
4230 or before a close paren/bracket.
4232 While additional whitespace is generally helpful for reading, do not use
4233 more than one blank line to separate blocks, and avoid adding whitespace
4234 after the end of a program line (as of 1/99, some 600 lines had
4235 whitespace after the semicolon). Excess whitespace causes difficulties
4236 for @code{diff} and @code{patch} utilities.
4238 Pointers are declared using the traditional K&R C style:
4252 @subsection Comments
4254 @cindex comment formatting
4255 The standard GNU requirements on comments must be followed strictly.
4257 Block comments must appear in the following form, with no @code{/*}- or
4258 @code{*/}-only lines, and no leading @code{*}:
4261 /* Wait for control to return from inferior to debugger. If inferior
4262 gets a signal, we may decide to start it up again instead of
4263 returning. That is why there is a loop in this function. When
4264 this function actually returns it means the inferior should be left
4265 stopped and @value{GDBN} should read more commands. */
4268 (Note that this format is encouraged by Emacs; tabbing for a multi-line
4269 comment works correctly, and @kbd{M-q} fills the block consistently.)
4271 Put a blank line between the block comments preceding function or
4272 variable definitions, and the definition itself.
4274 In general, put function-body comments on lines by themselves, rather
4275 than trying to fit them into the 20 characters left at the end of a
4276 line, since either the comment or the code will inevitably get longer
4277 than will fit, and then somebody will have to move it anyhow.
4281 @cindex C data types
4282 Code must not depend on the sizes of C data types, the format of the
4283 host's floating point numbers, the alignment of anything, or the order
4284 of evaluation of expressions.
4286 @cindex function usage
4287 Use functions freely. There are only a handful of compute-bound areas
4288 in @value{GDBN} that might be affected by the overhead of a function
4289 call, mainly in symbol reading. Most of @value{GDBN}'s performance is
4290 limited by the target interface (whether serial line or system call).
4292 However, use functions with moderation. A thousand one-line functions
4293 are just as hard to understand as a single thousand-line function.
4295 @emph{Macros are bad, M'kay.}
4299 Declarations like @samp{struct foo *} should be used in preference to
4300 declarations like @samp{typedef struct foo @{ @dots{} @} *foo_ptr}.
4303 @subsection Function Prototypes
4304 @cindex function prototypes
4306 Prototypes must be used when both @emph{declaring} and @emph{defining}
4307 a function. Prototypes for @value{GDBN} functions must include both the
4308 argument type and name, with the name matching that used in the actual
4309 function definition.
4311 All external functions should have a declaration in a header file that
4312 callers include, except for @code{_initialize_*} functions, which must
4313 be external so that @file{init.c} construction works, but shouldn't be
4314 visible to random source files.
4316 Where a source file needs a forward declaration of a static function,
4317 that declaration must appear in a block near the top of the source file.
4320 @subsection Internal Error Recovery
4322 During its execution, @value{GDBN} can encounter two types of errors.
4323 User errors and internal errors. User errors include not only a user
4324 entering an incorrect command but also problems arising from corrupt
4325 object files and system errors when interacting with the target.
4326 Internal errors include situtations where @value{GDBN} has detected, at
4327 run time, a corrupt or erroneous situtation.
4329 When reporting an internal error, @value{GDBN} uses
4330 @code{internal_error} and @code{gdb_assert}.
4332 @value{GDBN} must not call @code{abort} or @code{assert}.
4334 @emph{Pragmatics: There is no @code{internal_warning} function. Either
4335 the code detected a user error, recovered from it and issued a
4336 @code{warning} or the code failed to correctly recover from the user
4337 error and issued an @code{internal_error}.}
4339 @subsection File Names
4341 Any file used when building the core of @value{GDBN} must be in lower
4342 case. Any file used when building the core of @value{GDBN} must be 8.3
4343 unique. These requirements apply to both source and generated files.
4345 @emph{Pragmatics: The core of @value{GDBN} must be buildable on many
4346 platforms including DJGPP and MacOS/HFS. Every time an unfriendly file
4347 is introduced to the build process both @file{Makefile.in} and
4348 @file{configure.in} need to be modified accordingly. Compare the
4349 convoluted conversion process needed to transform @file{COPYING} into
4350 @file{copying.c} with the conversion needed to transform
4351 @file{version.in} into @file{version.c}.}
4353 Any file non 8.3 compliant file (that is not used when building the core
4354 of @value{GDBN}) must be added to @file{gdb/config/djgpp/fnchange.lst}.
4356 @emph{Pragmatics: This is clearly a compromise.}
4358 When @value{GDBN} has a local version of a system header file (ex
4359 @file{string.h}) the file name based on the POSIX header prefixed with
4360 @file{gdb_} (@file{gdb_string.h}).
4362 For other files @samp{-} is used as the separator.
4365 @subsection Include Files
4367 All @file{.c} files should include @file{defs.h} first.
4369 All @file{.c} files should explicitly include the headers for any
4370 declarations they refer to. They should not rely on files being
4371 included indirectly.
4373 With the exception of the global definitions supplied by @file{defs.h},
4374 a header file should explictily include the header declaring any
4375 @code{typedefs} et.al.@: it refers to.
4377 @code{extern} declarations should never appear in @code{.c} files.
4379 All include files should be wrapped in:
4382 #ifndef INCLUDE_FILE_NAME_H
4383 #define INCLUDE_FILE_NAME_H
4389 @subsection Clean Design and Portable Implementation
4392 In addition to getting the syntax right, there's the little question of
4393 semantics. Some things are done in certain ways in @value{GDBN} because long
4394 experience has shown that the more obvious ways caused various kinds of
4397 @cindex assumptions about targets
4398 You can't assume the byte order of anything that comes from a target
4399 (including @var{value}s, object files, and instructions). Such things
4400 must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in
4401 @value{GDBN}, or one of the swap routines defined in @file{bfd.h},
4402 such as @code{bfd_get_32}.
4404 You can't assume that you know what interface is being used to talk to
4405 the target system. All references to the target must go through the
4406 current @code{target_ops} vector.
4408 You can't assume that the host and target machines are the same machine
4409 (except in the ``native'' support modules). In particular, you can't
4410 assume that the target machine's header files will be available on the
4411 host machine. Target code must bring along its own header files --
4412 written from scratch or explicitly donated by their owner, to avoid
4416 Insertion of new @code{#ifdef}'s will be frowned upon. It's much better
4417 to write the code portably than to conditionalize it for various
4420 @cindex system dependencies
4421 New @code{#ifdef}'s which test for specific compilers or manufacturers
4422 or operating systems are unacceptable. All @code{#ifdef}'s should test
4423 for features. The information about which configurations contain which
4424 features should be segregated into the configuration files. Experience
4425 has proven far too often that a feature unique to one particular system
4426 often creeps into other systems; and that a conditional based on some
4427 predefined macro for your current system will become worthless over
4428 time, as new versions of your system come out that behave differently
4429 with regard to this feature.
4431 Adding code that handles specific architectures, operating systems,
4432 target interfaces, or hosts, is not acceptable in generic code.
4434 @cindex portable file name handling
4435 @cindex file names, portability
4436 One particularly notorious area where system dependencies tend to
4437 creep in is handling of file names. The mainline @value{GDBN} code
4438 assumes Posix semantics of file names: absolute file names begin with
4439 a forward slash @file{/}, slashes are used to separate leading
4440 directories, case-sensitive file names. These assumptions are not
4441 necessarily true on non-Posix systems such as MS-Windows. To avoid
4442 system-dependent code where you need to take apart or construct a file
4443 name, use the following portable macros:
4446 @findex HAVE_DOS_BASED_FILE_SYSTEM
4447 @item HAVE_DOS_BASED_FILE_SYSTEM
4448 This preprocessing symbol is defined to a non-zero value on hosts
4449 whose filesystems belong to the MS-DOS/MS-Windows family. Use this
4450 symbol to write conditional code which should only be compiled for
4453 @findex IS_DIR_SEPARATOR
4454 @item IS_DIR_SEPARATOR (@var{c}
4455 Evaluates to a non-zero value if @var{c} is a directory separator
4456 character. On Unix and GNU/Linux systems, only a slash @file{/} is
4457 such a character, but on Windows, both @file{/} and @file{\} will
4460 @findex IS_ABSOLUTE_PATH
4461 @item IS_ABSOLUTE_PATH (@var{file})
4462 Evaluates to a non-zero value if @var{file} is an absolute file name.
4463 For Unix and GNU/Linux hosts, a name which begins with a slash
4464 @file{/} is absolute. On DOS and Windows, @file{d:/foo} and
4465 @file{x:\bar} are also absolute file names.
4467 @findex FILENAME_CMP
4468 @item FILENAME_CMP (@var{f1}, @var{f2})
4469 Calls a function which compares file names @var{f1} and @var{f2} as
4470 appropriate for the underlying host filesystem. For Posix systems,
4471 this simply calls @code{strcmp}; on case-insensitive filesystems it
4472 will call @code{strcasecmp} instead.
4474 @findex DIRNAME_SEPARATOR
4475 @item DIRNAME_SEPARATOR
4476 Evaluates to a character which separates directories in
4477 @code{PATH}-style lists, typically held in environment variables.
4478 This character is @samp{:} on Unix, @samp{;} on DOS and Windows.
4480 @findex SLASH_STRING
4482 This evaluates to a constant string you should use to produce an
4483 absolute filename from leading directories and the file's basename.
4484 @code{SLASH_STRING} is @code{"/"} on most systems, but might be
4485 @code{"\\"} for some Windows-based ports.
4488 In addition to using these macros, be sure to use portable library
4489 functions whenever possible. For example, to extract a directory or a
4490 basename part from a file name, use the @code{dirname} and
4491 @code{basename} library functions (available in @code{libiberty} for
4492 platforms which don't provide them), instead of searching for a slash
4493 with @code{strrchr}.
4495 Another way to generalize @value{GDBN} along a particular interface is with an
4496 attribute struct. For example, @value{GDBN} has been generalized to handle
4497 multiple kinds of remote interfaces---not by @code{#ifdef}s everywhere, but
4498 by defining the @code{target_ops} structure and having a current target (as
4499 well as a stack of targets below it, for memory references). Whenever
4500 something needs to be done that depends on which remote interface we are
4501 using, a flag in the current target_ops structure is tested (e.g.,
4502 @code{target_has_stack}), or a function is called through a pointer in the
4503 current target_ops structure. In this way, when a new remote interface
4504 is added, only one module needs to be touched---the one that actually
4505 implements the new remote interface. Other examples of
4506 attribute-structs are BFD access to multiple kinds of object file
4507 formats, or @value{GDBN}'s access to multiple source languages.
4509 Please avoid duplicating code. For example, in @value{GDBN} 3.x all
4510 the code interfacing between @code{ptrace} and the rest of
4511 @value{GDBN} was duplicated in @file{*-dep.c}, and so changing
4512 something was very painful. In @value{GDBN} 4.x, these have all been
4513 consolidated into @file{infptrace.c}. @file{infptrace.c} can deal
4514 with variations between systems the same way any system-independent
4515 file would (hooks, @code{#if defined}, etc.), and machines which are
4516 radically different don't need to use @file{infptrace.c} at all.
4518 All debugging code must be controllable using the @samp{set debug
4519 @var{module}} command. Do not use @code{printf} to print trace
4520 messages. Use @code{fprintf_unfiltered(gdb_stdlog, ...}. Do not use
4521 @code{#ifdef DEBUG}.
4526 @chapter Porting @value{GDBN}
4527 @cindex porting to new machines
4529 Most of the work in making @value{GDBN} compile on a new machine is in
4530 specifying the configuration of the machine. This is done in a
4531 dizzying variety of header files and configuration scripts, which we
4532 hope to make more sensible soon. Let's say your new host is called an
4533 @var{xyz} (e.g., @samp{sun4}), and its full three-part configuration
4534 name is @code{@var{arch}-@var{xvend}-@var{xos}} (e.g.,
4535 @samp{sparc-sun-sunos4}). In particular:
4539 In the top level directory, edit @file{config.sub} and add @var{arch},
4540 @var{xvend}, and @var{xos} to the lists of supported architectures,
4541 vendors, and operating systems near the bottom of the file. Also, add
4542 @var{xyz} as an alias that maps to
4543 @code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by
4547 ./config.sub @var{xyz}
4554 ./config.sub @code{@var{arch}-@var{xvend}-@var{xos}}
4558 which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}}
4559 and no error messages.
4562 You need to port BFD, if that hasn't been done already. Porting BFD is
4563 beyond the scope of this manual.
4566 To configure @value{GDBN} itself, edit @file{gdb/configure.host} to recognize
4567 your system and set @code{gdb_host} to @var{xyz}, and (unless your
4568 desired target is already available) also edit @file{gdb/configure.tgt},
4569 setting @code{gdb_target} to something appropriate (for instance,
4573 Finally, you'll need to specify and define @value{GDBN}'s host-, native-, and
4574 target-dependent @file{.h} and @file{.c} files used for your
4578 @section Configuring @value{GDBN} for Release
4580 @cindex preparing a release
4581 @cindex making a distribution tarball
4582 From the top level directory (containing @file{gdb}, @file{bfd},
4583 @file{libiberty}, and so on):
4586 make -f Makefile.in gdb.tar.gz
4590 This will properly configure, clean, rebuild any files that are
4591 distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}),
4592 and will then make a tarfile. (If the top level directory has already
4593 been configured, you can just do @code{make gdb.tar.gz} instead.)
4595 This procedure requires:
4603 @code{makeinfo} (texinfo2 level);
4612 @code{yacc} or @code{bison}.
4616 @dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.).
4618 @subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
4620 @file{gdb.texinfo} is currently marked up using the texinfo-2 macros,
4621 which are not yet a default for anything (but we have to start using
4624 For making paper, the only thing this implies is the right generation of
4625 @file{texinfo.tex} needs to be included in the distribution.
4627 For making info files, however, rather than duplicating the texinfo2
4628 distribution, generate @file{gdb-all.texinfo} locally, and include the
4629 files @file{gdb.info*} in the distribution. Note the plural;
4630 @code{makeinfo} will split the document into one overall file and five
4631 or so included files.
4638 The testsuite is an important component of the @value{GDBN} package.
4639 While it is always worthwhile to encourage user testing, in practice
4640 this is rarely sufficient; users typically use only a small subset of
4641 the available commands, and it has proven all too common for a change
4642 to cause a significant regression that went unnoticed for some time.
4644 The @value{GDBN} testsuite uses the DejaGNU testing framework.
4645 DejaGNU is built using @code{Tcl} and @code{expect}. The tests
4646 themselves are calls to various @code{Tcl} procs; the framework runs all the
4647 procs and summarizes the passes and fails.
4649 @section Using the Testsuite
4651 @cindex running the test suite
4652 To run the testsuite, simply go to the @value{GDBN} object directory (or to the
4653 testsuite's objdir) and type @code{make check}. This just sets up some
4654 environment variables and invokes DejaGNU's @code{runtest} script. While
4655 the testsuite is running, you'll get mentions of which test file is in use,
4656 and a mention of any unexpected passes or fails. When the testsuite is
4657 finished, you'll get a summary that looks like this:
4662 # of expected passes 6016
4663 # of unexpected failures 58
4664 # of unexpected successes 5
4665 # of expected failures 183
4666 # of unresolved testcases 3
4667 # of untested testcases 5
4670 The ideal test run consists of expected passes only; however, reality
4671 conspires to keep us from this ideal. Unexpected failures indicate
4672 real problems, whether in @value{GDBN} or in the testsuite. Expected
4673 failures are still failures, but ones which have been decided are too
4674 hard to deal with at the time; for instance, a test case might work
4675 everywhere except on AIX, and there is no prospect of the AIX case
4676 being fixed in the near future. Expected failures should not be added
4677 lightly, since you may be masking serious bugs in @value{GDBN}.
4678 Unexpected successes are expected fails that are passing for some
4679 reason, while unresolved and untested cases often indicate some minor
4680 catastrophe, such as the compiler being unable to deal with a test
4683 When making any significant change to @value{GDBN}, you should run the
4684 testsuite before and after the change, to confirm that there are no
4685 regressions. Note that truly complete testing would require that you
4686 run the testsuite with all supported configurations and a variety of
4687 compilers; however this is more than really necessary. In many cases
4688 testing with a single configuration is sufficient. Other useful
4689 options are to test one big-endian (Sparc) and one little-endian (x86)
4690 host, a cross config with a builtin simulator (powerpc-eabi,
4691 mips-elf), or a 64-bit host (Alpha).
4693 If you add new functionality to @value{GDBN}, please consider adding
4694 tests for it as well; this way future @value{GDBN} hackers can detect
4695 and fix their changes that break the functionality you added.
4696 Similarly, if you fix a bug that was not previously reported as a test
4697 failure, please add a test case for it. Some cases are extremely
4698 difficult to test, such as code that handles host OS failures or bugs
4699 in particular versions of compilers, and it's OK not to try to write
4700 tests for all of those.
4702 @section Testsuite Organization
4704 @cindex test suite organization
4705 The testsuite is entirely contained in @file{gdb/testsuite}. While the
4706 testsuite includes some makefiles and configury, these are very minimal,
4707 and used for little besides cleaning up, since the tests themselves
4708 handle the compilation of the programs that @value{GDBN} will run. The file
4709 @file{testsuite/lib/gdb.exp} contains common utility procs useful for
4710 all @value{GDBN} tests, while the directory @file{testsuite/config} contains
4711 configuration-specific files, typically used for special-purpose
4712 definitions of procs like @code{gdb_load} and @code{gdb_start}.
4714 The tests themselves are to be found in @file{testsuite/gdb.*} and
4715 subdirectories of those. The names of the test files must always end
4716 with @file{.exp}. DejaGNU collects the test files by wildcarding
4717 in the test directories, so both subdirectories and individual files
4718 get chosen and run in alphabetical order.
4720 The following table lists the main types of subdirectories and what they
4721 are for. Since DejaGNU finds test files no matter where they are
4722 located, and since each test file sets up its own compilation and
4723 execution environment, this organization is simply for convenience and
4728 This is the base testsuite. The tests in it should apply to all
4729 configurations of @value{GDBN} (but generic native-only tests may live here).
4730 The test programs should be in the subset of C that is valid K&R,
4731 ANSI/ISO, and C++ (@code{#ifdef}s are allowed if necessary, for instance
4734 @item gdb.@var{lang}
4735 Language-specific tests for any language @var{lang} besides C. Examples are
4736 @file{gdb.c++} and @file{gdb.java}.
4738 @item gdb.@var{platform}
4739 Non-portable tests. The tests are specific to a specific configuration
4740 (host or target), such as HP-UX or eCos. Example is @file{gdb.hp}, for
4743 @item gdb.@var{compiler}
4744 Tests specific to a particular compiler. As of this writing (June
4745 1999), there aren't currently any groups of tests in this category that
4746 couldn't just as sensibly be made platform-specific, but one could
4747 imagine a @file{gdb.gcc}, for tests of @value{GDBN}'s handling of GCC
4750 @item gdb.@var{subsystem}
4751 Tests that exercise a specific @value{GDBN} subsystem in more depth. For
4752 instance, @file{gdb.disasm} exercises various disassemblers, while
4753 @file{gdb.stabs} tests pathways through the stabs symbol reader.
4756 @section Writing Tests
4757 @cindex writing tests
4759 In many areas, the @value{GDBN} tests are already quite comprehensive; you
4760 should be able to copy existing tests to handle new cases.
4762 You should try to use @code{gdb_test} whenever possible, since it
4763 includes cases to handle all the unexpected errors that might happen.
4764 However, it doesn't cost anything to add new test procedures; for
4765 instance, @file{gdb.base/exprs.exp} defines a @code{test_expr} that
4766 calls @code{gdb_test} multiple times.
4768 Only use @code{send_gdb} and @code{gdb_expect} when absolutely
4769 necessary, such as when @value{GDBN} has several valid responses to a command.
4771 The source language programs do @emph{not} need to be in a consistent
4772 style. Since @value{GDBN} is used to debug programs written in many different
4773 styles, it's worth having a mix of styles in the testsuite; for
4774 instance, some @value{GDBN} bugs involving the display of source lines would
4775 never manifest themselves if the programs used GNU coding style
4782 Check the @file{README} file, it often has useful information that does not
4783 appear anywhere else in the directory.
4786 * Getting Started:: Getting started working on @value{GDBN}
4787 * Debugging GDB:: Debugging @value{GDBN} with itself
4790 @node Getting Started,,, Hints
4792 @section Getting Started
4794 @value{GDBN} is a large and complicated program, and if you first starting to
4795 work on it, it can be hard to know where to start. Fortunately, if you
4796 know how to go about it, there are ways to figure out what is going on.
4798 This manual, the @value{GDBN} Internals manual, has information which applies
4799 generally to many parts of @value{GDBN}.
4801 Information about particular functions or data structures are located in
4802 comments with those functions or data structures. If you run across a
4803 function or a global variable which does not have a comment correctly
4804 explaining what is does, this can be thought of as a bug in @value{GDBN}; feel
4805 free to submit a bug report, with a suggested comment if you can figure
4806 out what the comment should say. If you find a comment which is
4807 actually wrong, be especially sure to report that.
4809 Comments explaining the function of macros defined in host, target, or
4810 native dependent files can be in several places. Sometimes they are
4811 repeated every place the macro is defined. Sometimes they are where the
4812 macro is used. Sometimes there is a header file which supplies a
4813 default definition of the macro, and the comment is there. This manual
4814 also documents all the available macros.
4815 @c (@pxref{Host Conditionals}, @pxref{Target
4816 @c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete
4819 Start with the header files. Once you have some idea of how
4820 @value{GDBN}'s internal symbol tables are stored (see @file{symtab.h},
4821 @file{gdbtypes.h}), you will find it much easier to understand the
4822 code which uses and creates those symbol tables.
4824 You may wish to process the information you are getting somehow, to
4825 enhance your understanding of it. Summarize it, translate it to another
4826 language, add some (perhaps trivial or non-useful) feature to @value{GDBN}, use
4827 the code to predict what a test case would do and write the test case
4828 and verify your prediction, etc. If you are reading code and your eyes
4829 are starting to glaze over, this is a sign you need to use a more active
4832 Once you have a part of @value{GDBN} to start with, you can find more
4833 specifically the part you are looking for by stepping through each
4834 function with the @code{next} command. Do not use @code{step} or you
4835 will quickly get distracted; when the function you are stepping through
4836 calls another function try only to get a big-picture understanding
4837 (perhaps using the comment at the beginning of the function being
4838 called) of what it does. This way you can identify which of the
4839 functions being called by the function you are stepping through is the
4840 one which you are interested in. You may need to examine the data
4841 structures generated at each stage, with reference to the comments in
4842 the header files explaining what the data structures are supposed to
4845 Of course, this same technique can be used if you are just reading the
4846 code, rather than actually stepping through it. The same general
4847 principle applies---when the code you are looking at calls something
4848 else, just try to understand generally what the code being called does,
4849 rather than worrying about all its details.
4851 @cindex command implementation
4852 A good place to start when tracking down some particular area is with
4853 a command which invokes that feature. Suppose you want to know how
4854 single-stepping works. As a @value{GDBN} user, you know that the
4855 @code{step} command invokes single-stepping. The command is invoked
4856 via command tables (see @file{command.h}); by convention the function
4857 which actually performs the command is formed by taking the name of
4858 the command and adding @samp{_command}, or in the case of an
4859 @code{info} subcommand, @samp{_info}. For example, the @code{step}
4860 command invokes the @code{step_command} function and the @code{info
4861 display} command invokes @code{display_info}. When this convention is
4862 not followed, you might have to use @code{grep} or @kbd{M-x
4863 tags-search} in emacs, or run @value{GDBN} on itself and set a
4864 breakpoint in @code{execute_command}.
4866 @cindex @code{bug-gdb} mailing list
4867 If all of the above fail, it may be appropriate to ask for information
4868 on @code{bug-gdb}. But @emph{never} post a generic question like ``I was
4869 wondering if anyone could give me some tips about understanding
4870 @value{GDBN}''---if we had some magic secret we would put it in this manual.
4871 Suggestions for improving the manual are always welcome, of course.
4873 @node Debugging GDB,,,Hints
4875 @section Debugging @value{GDBN} with itself
4876 @cindex debugging @value{GDBN}
4878 If @value{GDBN} is limping on your machine, this is the preferred way to get it
4879 fully functional. Be warned that in some ancient Unix systems, like
4880 Ultrix 4.2, a program can't be running in one process while it is being
4881 debugged in another. Rather than typing the command @kbd{@w{./gdb
4882 ./gdb}}, which works on Suns and such, you can copy @file{gdb} to
4883 @file{gdb2} and then type @kbd{@w{./gdb ./gdb2}}.
4885 When you run @value{GDBN} in the @value{GDBN} source directory, it will read a
4886 @file{.gdbinit} file that sets up some simple things to make debugging
4887 gdb easier. The @code{info} command, when executed without a subcommand
4888 in a @value{GDBN} being debugged by gdb, will pop you back up to the top level
4889 gdb. See @file{.gdbinit} for details.
4891 If you use emacs, you will probably want to do a @code{make TAGS} after
4892 you configure your distribution; this will put the machine dependent
4893 routines for your local machine where they will be accessed first by
4896 Also, make sure that you've either compiled @value{GDBN} with your local cc, or
4897 have run @code{fixincludes} if you are compiling with gcc.
4899 @section Submitting Patches
4901 @cindex submitting patches
4902 Thanks for thinking of offering your changes back to the community of
4903 @value{GDBN} users. In general we like to get well designed enhancements.
4904 Thanks also for checking in advance about the best way to transfer the
4907 The @value{GDBN} maintainers will only install ``cleanly designed'' patches.
4908 This manual summarizes what we believe to be clean design for @value{GDBN}.
4910 If the maintainers don't have time to put the patch in when it arrives,
4911 or if there is any question about a patch, it goes into a large queue
4912 with everyone else's patches and bug reports.
4914 @cindex legal papers for code contributions
4915 The legal issue is that to incorporate substantial changes requires a
4916 copyright assignment from you and/or your employer, granting ownership
4917 of the changes to the Free Software Foundation. You can get the
4918 standard documents for doing this by sending mail to @code{gnu@@gnu.org}
4919 and asking for it. We recommend that people write in "All programs
4920 owned by the Free Software Foundation" as "NAME OF PROGRAM", so that
4921 changes in many programs (not just @value{GDBN}, but GAS, Emacs, GCC,
4923 contributed with only one piece of legalese pushed through the
4924 bureacracy and filed with the FSF. We can't start merging changes until
4925 this paperwork is received by the FSF (their rules, which we follow
4926 since we maintain it for them).
4928 Technically, the easiest way to receive changes is to receive each
4929 feature as a small context diff or unidiff, suitable for @code{patch}.
4930 Each message sent to me should include the changes to C code and
4931 header files for a single feature, plus @file{ChangeLog} entries for
4932 each directory where files were modified, and diffs for any changes
4933 needed to the manuals (@file{gdb/doc/gdb.texinfo} or
4934 @file{gdb/doc/gdbint.texinfo}). If there are a lot of changes for a
4935 single feature, they can be split down into multiple messages.
4937 In this way, if we read and like the feature, we can add it to the
4938 sources with a single patch command, do some testing, and check it in.
4939 If you leave out the @file{ChangeLog}, we have to write one. If you leave
4940 out the doc, we have to puzzle out what needs documenting. Etc., etc.
4942 The reason to send each change in a separate message is that we will not
4943 install some of the changes. They'll be returned to you with questions
4944 or comments. If we're doing our job correctly, the message back to you
4945 will say what you have to fix in order to make the change acceptable.
4946 The reason to have separate messages for separate features is so that
4947 the acceptable changes can be installed while one or more changes are
4948 being reworked. If multiple features are sent in a single message, we
4949 tend to not put in the effort to sort out the acceptable changes from
4950 the unacceptable, so none of the features get installed until all are
4953 If this sounds painful or authoritarian, well, it is. But we get a lot
4954 of bug reports and a lot of patches, and many of them don't get
4955 installed because we don't have the time to finish the job that the bug
4956 reporter or the contributor could have done. Patches that arrive
4957 complete, working, and well designed, tend to get installed on the day
4958 they arrive. The others go into a queue and get installed as time
4959 permits, which, since the maintainers have many demands to meet, may not
4960 be for quite some time.
4962 Please send patches directly to
4963 @email{gdb-patches@@sourceware.cygnus.com, the @value{GDBN} maintainers}.
4965 @section Obsolete Conditionals
4966 @cindex obsolete code
4968 Fragments of old code in @value{GDBN} sometimes reference or set the following
4969 configuration macros. They should not be used by new code, and old uses
4970 should be removed as those parts of the debugger are otherwise touched.
4973 @item STACK_END_ADDR
4974 This macro used to define where the end of the stack appeared, for use
4975 in interpreting core file formats that don't record this address in the
4976 core file itself. This information is now configured in BFD, and @value{GDBN}
4977 gets the info portably from there. The values in @value{GDBN}'s configuration
4978 files should be moved into BFD configuration files (if needed there),
4979 and deleted from all of @value{GDBN}'s config files.
4981 Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
4982 is so old that it has never been converted to use BFD. Now that's old!
4984 @item PYRAMID_CONTROL_FRAME_DEBUGGING
4988 @item PYRAMID_PTRACE
4991 @item REG_STACK_SEGMENT
5001 @c TeX can handle the contents at the start but makeinfo 3.12 can not