1 \input texinfo @c -*- texinfo -*-
2 @setfilename gdbint.info
4 @dircategory Programming & development tools.
6 * Gdb-Internals: (gdbint). The GNU debugger's internals.
10 This file documents the internals of the GNU debugger @value{GDBN}.
11 Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001
12 Free Software Foundation, Inc.
13 Contributed by Cygnus Solutions. Written by John Gilmore.
14 Second Edition by Stan Shebs.
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.1 or
18 any later version published by the Free Software Foundation; with the
19 Invariant Sections being ``Algorithms'' and ``Porting GDB'', with the
20 Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover
21 Texts as in (a) below.
23 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
24 this GNU Manual, like GNU software. Copies published by the Free
25 Software Foundation raise funds for GNU development.''
28 @setchapternewpage off
29 @settitle @value{GDBN} Internals
35 @title @value{GDBN} Internals
36 @subtitle{A guide to the internals of the GNU debugger}
38 @author Cygnus Solutions
39 @author Second Edition:
41 @author Cygnus Solutions
44 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
45 \xdef\manvers{\$Revision$} % For use in headers, footers too
47 \hfill Cygnus Solutions\par
49 \hfill \TeX{}info \texinfoversion\par
53 @vskip 0pt plus 1filll
54 Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001
55 Free Software Foundation, Inc.
57 Permission is granted to copy, distribute and/or modify this document
58 under the terms of the GNU Free Documentation License, Version 1.1 or
59 any later version published by the Free Software Foundation; with the
60 Invariant Sections being ``Algorithms'' and ``Porting GDB'', with the
61 Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover
62 Texts as in (a) below.
64 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
65 this GNU Manual, like GNU software. Copies published by the Free
66 Software Foundation raise funds for GNU development.''
69 @c TeX can handle the contents at the start but makeinfo 3.12 can not
75 @c Perhaps this should be the title of the document (but only for info,
76 @c not for TeX). Existing GNU manuals seem inconsistent on this point.
77 @top Scope of this Document
79 This document documents the internals of the GNU debugger, @value{GDBN}. It
80 includes description of @value{GDBN}'s key algorithms and operations, as well
81 as the mechanisms that adapt @value{GDBN} to specific hosts and targets.
92 * Target Architecture Definition::
93 * Target Vector Definition::
105 @chapter Requirements
106 @cindex requirements for @value{GDBN}
108 Before diving into the internals, you should understand the formal
109 requirements and other expectations for @value{GDBN}. Although some
110 of these may seem obvious, there have been proposals for @value{GDBN}
111 that have run counter to these requirements.
113 First of all, @value{GDBN} is a debugger. It's not designed to be a
114 front panel for embedded systems. It's not a text editor. It's not a
115 shell. It's not a programming environment.
117 @value{GDBN} is an interactive tool. Although a batch mode is
118 available, @value{GDBN}'s primary role is to interact with a human
121 @value{GDBN} should be responsive to the user. A programmer hot on
122 the trail of a nasty bug, and operating under a looming deadline, is
123 going to be very impatient of everything, including the response time
124 to debugger commands.
126 @value{GDBN} should be relatively permissive, such as for expressions.
127 While the compiler should be picky (or have the option to be made
128 picky), since source code lives for a long time usually, the
129 programmer doing debugging shouldn't be spending time figuring out to
130 mollify the debugger.
132 @value{GDBN} will be called upon to deal with really large programs.
133 Executable sizes of 50 to 100 megabytes occur regularly, and we've
134 heard reports of programs approaching 1 gigabyte in size.
136 @value{GDBN} should be able to run everywhere. No other debugger is
137 available for even half as many configurations as @value{GDBN}
141 @node Overall Structure
143 @chapter Overall Structure
145 @value{GDBN} consists of three major subsystems: user interface,
146 symbol handling (the @dfn{symbol side}), and target system handling (the
149 The user interface consists of several actual interfaces, plus
152 The symbol side consists of object file readers, debugging info
153 interpreters, symbol table management, source language expression
154 parsing, type and value printing.
156 The target side consists of execution control, stack frame analysis, and
157 physical target manipulation.
159 The target side/symbol side division is not formal, and there are a
160 number of exceptions. For instance, core file support involves symbolic
161 elements (the basic core file reader is in BFD) and target elements (it
162 supplies the contents of memory and the values of registers). Instead,
163 this division is useful for understanding how the minor subsystems
166 @section The Symbol Side
168 The symbolic side of @value{GDBN} can be thought of as ``everything
169 you can do in @value{GDBN} without having a live program running''.
170 For instance, you can look at the types of variables, and evaluate
171 many kinds of expressions.
173 @section The Target Side
175 The target side of @value{GDBN} is the ``bits and bytes manipulator''.
176 Although it may make reference to symbolic info here and there, most
177 of the target side will run with only a stripped executable
178 available---or even no executable at all, in remote debugging cases.
180 Operations such as disassembly, stack frame crawls, and register
181 display, are able to work with no symbolic info at all. In some cases,
182 such as disassembly, @value{GDBN} will use symbolic info to present addresses
183 relative to symbols rather than as raw numbers, but it will work either
186 @section Configurations
190 @dfn{Host} refers to attributes of the system where @value{GDBN} runs.
191 @dfn{Target} refers to the system where the program being debugged
192 executes. In most cases they are the same machine, in which case a
193 third type of @dfn{Native} attributes come into play.
195 Defines and include files needed to build on the host are host support.
196 Examples are tty support, system defined types, host byte order, host
199 Defines and information needed to handle the target format are target
200 dependent. Examples are the stack frame format, instruction set,
201 breakpoint instruction, registers, and how to set up and tear down the stack
204 Information that is only needed when the host and target are the same,
205 is native dependent. One example is Unix child process support; if the
206 host and target are not the same, doing a fork to start the target
207 process is a bad idea. The various macros needed for finding the
208 registers in the @code{upage}, running @code{ptrace}, and such are all
209 in the native-dependent files.
211 Another example of native-dependent code is support for features that
212 are really part of the target environment, but which require
213 @code{#include} files that are only available on the host system. Core
214 file handling and @code{setjmp} handling are two common cases.
216 When you want to make @value{GDBN} work ``native'' on a particular machine, you
217 have to include all three kinds of information.
225 @value{GDBN} uses a number of debugging-specific algorithms. They are
226 often not very complicated, but get lost in the thicket of special
227 cases and real-world issues. This chapter describes the basic
228 algorithms and mentions some of the specific target definitions that
234 @cindex call stack frame
235 A frame is a construct that @value{GDBN} uses to keep track of calling
236 and called functions.
238 @findex create_new_frame
240 @code{FRAME_FP} in the machine description has no meaning to the
241 machine-independent part of @value{GDBN}, except that it is used when
242 setting up a new frame from scratch, as follows:
245 create_new_frame (read_register (FP_REGNUM), read_pc ()));
248 @cindex frame pointer register
249 Other than that, all the meaning imparted to @code{FP_REGNUM} is
250 imparted by the machine-dependent code. So, @code{FP_REGNUM} can have
251 any value that is convenient for the code that creates new frames.
252 (@code{create_new_frame} calls @code{INIT_EXTRA_FRAME_INFO} if it is
253 defined; that is where you should use the @code{FP_REGNUM} value, if
254 your frames are nonstandard.)
257 Given a @value{GDBN} frame, define @code{FRAME_CHAIN} to determine the
258 address of the calling function's frame. This will be used to create
259 a new @value{GDBN} frame struct, and then @code{INIT_EXTRA_FRAME_INFO}
260 and @code{INIT_FRAME_PC} will be called for the new frame.
262 @section Breakpoint Handling
265 In general, a breakpoint is a user-designated location in the program
266 where the user wants to regain control if program execution ever reaches
269 There are two main ways to implement breakpoints; either as ``hardware''
270 breakpoints or as ``software'' breakpoints.
272 @cindex hardware breakpoints
273 @cindex program counter
274 Hardware breakpoints are sometimes available as a builtin debugging
275 features with some chips. Typically these work by having dedicated
276 register into which the breakpoint address may be stored. If the PC
277 (shorthand for @dfn{program counter})
278 ever matches a value in a breakpoint registers, the CPU raises an
279 exception and reports it to @value{GDBN}.
281 Another possibility is when an emulator is in use; many emulators
282 include circuitry that watches the address lines coming out from the
283 processor, and force it to stop if the address matches a breakpoint's
286 A third possibility is that the target already has the ability to do
287 breakpoints somehow; for instance, a ROM monitor may do its own
288 software breakpoints. So although these are not literally ``hardware
289 breakpoints'', from @value{GDBN}'s point of view they work the same;
290 @value{GDBN} need not do nothing more than set the breakpoint and wait
291 for something to happen.
293 Since they depend on hardware resources, hardware breakpoints may be
294 limited in number; when the user asks for more, @value{GDBN} will
295 start trying to set software breakpoints. (On some architectures,
296 notably the 32-bit x86 platforms, @value{GDBN} cannot alsways know
297 whether there's enough hardware resources to insert all the hardware
298 breakpoints and watchpoints. On those platforms, @value{GDBN} prints
299 an error message only when the program being debugged is continued.)
301 @cindex software breakpoints
302 Software breakpoints require @value{GDBN} to do somewhat more work.
303 The basic theory is that @value{GDBN} will replace a program
304 instruction with a trap, illegal divide, or some other instruction
305 that will cause an exception, and then when it's encountered,
306 @value{GDBN} will take the exception and stop the program. When the
307 user says to continue, @value{GDBN} will restore the original
308 instruction, single-step, re-insert the trap, and continue on.
310 Since it literally overwrites the program being tested, the program area
311 must be writable, so this technique won't work on programs in ROM. It
312 can also distort the behavior of programs that examine themselves,
313 although such a situation would be highly unusual.
315 Also, the software breakpoint instruction should be the smallest size of
316 instruction, so it doesn't overwrite an instruction that might be a jump
317 target, and cause disaster when the program jumps into the middle of the
318 breakpoint instruction. (Strictly speaking, the breakpoint must be no
319 larger than the smallest interval between instructions that may be jump
320 targets; perhaps there is an architecture where only even-numbered
321 instructions may jumped to.) Note that it's possible for an instruction
322 set not to have any instructions usable for a software breakpoint,
323 although in practice only the ARC has failed to define such an
327 The basic definition of the software breakpoint is the macro
330 Basic breakpoint object handling is in @file{breakpoint.c}. However,
331 much of the interesting breakpoint action is in @file{infrun.c}.
333 @section Single Stepping
335 @section Signal Handling
337 @section Thread Handling
339 @section Inferior Function Calls
341 @section Longjmp Support
343 @cindex @code{longjmp} debugging
344 @value{GDBN} has support for figuring out that the target is doing a
345 @code{longjmp} and for stopping at the target of the jump, if we are
346 stepping. This is done with a few specialized internal breakpoints,
347 which are visible in the output of the @samp{maint info breakpoint}
350 @findex GET_LONGJMP_TARGET
351 To make this work, you need to define a macro called
352 @code{GET_LONGJMP_TARGET}, which will examine the @code{jmp_buf}
353 structure and extract the longjmp target address. Since @code{jmp_buf}
354 is target specific, you will need to define it in the appropriate
355 @file{tm-@var{target}.h} file. Look in @file{tm-sun4os4.h} and
356 @file{sparc-tdep.c} for examples of how to do this.
361 Watchpoints are a special kind of breakpoints (@pxref{Algorithms,
362 breakpoints}) which break when data is accessed rather than when some
363 instruction is executed. When you have data which changes without
364 your knowing what code does that, watchpoints are the silver bullet to
365 hunt down and kill such bugs.
367 @cindex hardware watchpoints
368 @cindex software watchpoints
369 Watchpoints can be either hardware-assisted or not; the latter type is
370 known as ``software watchpoints.'' @value{GDBN} always uses
371 hardware-assisted watchpoints if they are available, and falls back on
372 software watchpoints otherwise. Typical situations where @value{GDBN}
373 will use software watchpoints are:
377 The watched memory region is too large for the underlying hardware
378 watchpoint support. For example, each x86 debug register can watch up
379 to 4 bytes of memory, so trying to watch data structures whose size is
380 more than 16 bytes will cause @value{GDBN} to use software
384 The value of the expression to be watched depends on data held in
385 registers (as opposed to memory).
388 Too many different watchpoints requested. (On some architectures,
389 this situation is impossible to detect until the debugged program is
390 resumed.) Note that x86 debug registers are used both for hardware
391 breakpoints and for watchpoints, so setting too many hardware
392 breakpoints might cause watchpoint insertion to fail.
395 No hardware-assisted watchpoints provided by the target
399 Software watchpoints are very slow, since @value{GDBN} needs to
400 single-step the program being debugged and test the value of the
401 watched expression(s) after each instruction. The rest of this
402 section is mostly irrelevant for software watchpoints.
404 @value{GDBN} uses several macros and primitives to support hardware
408 @findex TARGET_HAS_HARDWARE_WATCHPOINTS
409 @item TARGET_HAS_HARDWARE_WATCHPOINTS
410 If defined, the target supports hardware watchpoints.
412 @findex TARGET_CAN_USE_HARDWARE_WATCHPOINT
413 @item TARGET_CAN_USE_HARDWARE_WATCHPOINT (@var{type}, @var{count}, @var{other})
414 Return the number of hardware watchpoints of type @var{type} that are
415 possible to be set. The value is positive if @var{count} watchpoints
416 of this type can be set, zero if setting watchpoints of this type is
417 not supported, and negative if @var{count} is more than the maximum
418 number of watchpoints of type @var{type} that can be set. @var{other}
419 is non-zero if other types of watchpoints are currently enabled (there
420 are architectures which cannot set watchpoints of different types at
423 @findex TARGET_REGION_OK_FOR_HW_WATCHPOINT
424 @item TARGET_REGION_OK_FOR_HW_WATCHPOINT (@var{addr}, @var{len})
425 Return non-zero if hardware watchpoints can be used to watch a region
426 whose address is @var{addr} and whose length in bytes is @var{len}.
428 @findex TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT
429 @item TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT (@var{size})
430 Return non-zero if hardware watchpoints can be used to watch a region
431 whose size is @var{size}. @value{GDBN} only uses this macro as a
432 fall-back, in case @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is not
435 @findex TARGET_DISABLE_HW_WATCHPOINTS
436 @item TARGET_DISABLE_HW_WATCHPOINTS (@var{pid})
437 Disables watchpoints in the process identified by @var{pid}. This is
438 used, e.g., on HP-UX which provides operations to disable and enable
439 the page-level memory protection that implements hardware watchpoints
442 @findex TARGET_ENABLE_HW_WATCHPOINTS
443 @item TARGET_ENABLE_HW_WATCHPOINTS (@var{pid})
444 Enables watchpoints in the process identified by @var{pid}. This is
445 used, e.g., on HP-UX which provides operations to disable and enable
446 the page-level memory protection that implements hardware watchpoints
449 @findex target_insert_watchpoint
450 @findex target_remove_watchpoint
451 @item target_insert_watchpoint (@var{addr}, @var{len}, @var{type})
452 @itemx target_remove_watchpoint (@var{addr}, @var{len}, @var{type})
453 Insert or remove a hardware watchpoint starting at @var{addr}, for
454 @var{len} bytes. @var{type} is the watchpoint type, one of the
455 possible values of the enumerated data type @code{target_hw_bp_type},
456 defined by @file{breakpoint.h} as follows:
459 enum target_hw_bp_type
461 hw_write = 0, /* Common (write) HW watchpoint */
462 hw_read = 1, /* Read HW watchpoint */
463 hw_access = 2, /* Access (read or write) HW watchpoint */
464 hw_execute = 3 /* Execute HW breakpoint */
469 These two macros should return 0 for success, non-zero for failure.
471 @cindex insert or remove hardware breakpoint
472 @findex target_remove_hw_breakpoint
473 @findex target_insert_hw_breakpoint
474 @item target_remove_hw_breakpoint (@var{addr}, @var{shadow})
475 @itemx target_insert_hw_breakpoint (@var{addr}, @var{shadow})
476 Insert or remove a hardware-assisted breakpoint at address @var{addr}.
477 Returns zero for success, non-zero for failure. @var{shadow} is the
478 real contents of the byte where the breakpoint has been inserted; it
479 is generally not valid when hardware breakpoints are used, but since
480 no other code touches these values, the implementations of the above
481 two macros can use them for their internal purposes.
483 @findex target_stopped_data_address
484 @item target_stopped_data_address ()
485 If the inferior has some watchpoint that triggered, return the address
486 associated with that watchpoint. Otherwise, return zero.
488 @findex DECR_PC_AFTER_HW_BREAK
489 @item DECR_PC_AFTER_HW_BREAK
490 If defined, @value{GDBN} decrements the program counter by the value
491 of @code{DECR_PC_AFTER_HW_BREAK} after a hardware break-point. This
492 overrides the value of @code{DECR_PC_AFTER_BREAK} when a breakpoint
493 that breaks is a hardware-assisted breakpoint.
495 @findex HAVE_STEPPABLE_WATCHPOINT
496 @item HAVE_STEPPABLE_WATCHPOINT
497 If defined to a non-zero value, it is not necessary to disable a
498 watchpoint to step over it.
500 @findex HAVE_NONSTEPPABLE_WATCHPOINT
501 @item HAVE_NONSTEPPABLE_WATCHPOINT
502 If defined to a non-zero value, @value{GDBN} should disable a
503 watchpoint to step the inferior over it.
505 @findex HAVE_CONTINUABLE_WATCHPOINT
506 @item HAVE_CONTINUABLE_WATCHPOINT
507 If defined to a non-zero value, it is possible to continue the
508 inferior after a watchpoint has been hit.
510 @findex CANNOT_STEP_HW_WATCHPOINTS
511 @item CANNOT_STEP_HW_WATCHPOINTS
512 If this is defined to a non-zero value, @value{GDBN} will remove all
513 watchpoints before stepping the inferior.
515 @findex STOPPED_BY_WATCHPOINT
516 @item STOPPED_BY_WATCHPOINT (@var{wait_status})
517 Return non-zero if stopped by a watchpoint. @var{wait_status} is of
518 the type @code{struct target_waitstatus}, defined by @file{target.h}.
521 @subsection x86 Watchpoints
522 @cindex x86 debug registers
523 @cindex watchpoints, on x86
525 The 32-bit Intel x86 (a.k.a.@: ia32) processors feature special debug
526 registers designed to facilitate debugging. @value{GDBN} provides a
527 generic library of functions that x86-based ports can use to implement
528 support for watchpoints and hardware-assisted breakpoints. This
529 subsection documents the x86 watchpoint facilities in @value{GDBN}.
531 To use the generic x86 watchpoint support, a port should do the
535 @findex I386_USE_GENERIC_WATCHPOINTS
537 Define the macro @code{I386_USE_GENERIC_WATCHPOINTS} somewhere in the
538 target-dependent headers.
541 Include the @file{config/i386/nm-i386.h} header file @emph{after}
542 defining @code{I386_USE_GENERIC_WATCHPOINTS}.
545 Add @file{i386-nat.o} to the value of the Make variable
546 @code{NATDEPFILES} (@pxref{Native Debugging, NATDEPFILES}) or
547 @code{TDEPFILES} (@pxref{Target Architecture Definition, TDEPFILES}).
550 Provide implementations for the @code{I386_DR_LOW_*} macros described
551 below. Typically, each macro should call a target-specific function
552 which does the real work.
555 The x86 watchpoint support works by maintaining mirror images of the
556 debug registers. Values are copied between the mirror images and the
557 real debug registers via a set of macros which each target needs to
561 @findex I386_DR_LOW_SET_CONTROL
562 @item I386_DR_LOW_SET_CONTROL (@var{val})
563 Set the Debug Control (DR7) register to the value @var{val}.
565 @findex I386_DR_LOW_SET_ADDR
566 @item I386_DR_LOW_SET_ADDR (@var{idx}, @var{addr})
567 Put the address @var{addr} into the debug register number @var{idx}.
569 @findex I386_DR_LOW_RESET_ADDR
570 @item I386_DR_LOW_RESET_ADDR (@var{idx})
571 Reset (i.e.@: zero out) the address stored in the debug register
574 @findex I386_DR_LOW_GET_STATUS
575 @item I386_DR_LOW_GET_STATUS
576 Return the value of the Debug Status (DR6) register. This value is
577 used immediately after it is returned by
578 @code{I386_DR_LOW_GET_STATUS}, so as to support per-thread status
582 For each one of the 4 debug registers (whose indices are from 0 to 3)
583 that store addresses, a reference count is maintained by @value{GDBN},
584 to allow sharing of debug registers by several watchpoints. This
585 allows users to define several watchpoints that watch the same
586 expression, but with different conditions and/or commands, without
587 wasting debug registers which are in short supply. @value{GDBN}
588 maintains the reference counts internally, targets don't have to do
589 anything to use this feature.
591 The x86 debug registers can each watch a region that is 1, 2, or 4
592 bytes long. The ia32 architecture requires that each watched region
593 be appropriately aligned: 2-byte region on 2-byte boundary, 4-byte
594 region on 4-byte boundary. However, the x86 watchpoint support in
595 @value{GDBN} can watch unaligned regions and regions larger than 4
596 bytes (up to 16 bytes) by allocating several debug registers to watch
597 a single region. This allocation of several registers per a watched
598 region is also done automatically without target code intervention.
600 The generic x86 watchpoint support provides the following API for the
601 @value{GDBN}'s application code:
604 @findex i386_region_ok_for_watchpoint
605 @item i386_region_ok_for_watchpoint (@var{addr}, @var{len})
606 The macro @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is set to call
607 this function. It counts the number of debug registers required to
608 watch a given region, and returns a non-zero value if that number is
609 less than 4, the number of debug registers available to x86
612 @findex i386_stopped_data_address
613 @item i386_stopped_data_address (void)
614 The macros @code{STOPPED_BY_WATCHPOINT} and
615 @code{target_stopped_data_address} are set to call this function. The
616 argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored. This
617 function examines the breakpoint condition bits in the DR6 Debug
618 Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}
619 macro, and returns the address associated with the first bit that is
622 @findex i386_insert_watchpoint
623 @findex i386_remove_watchpoint
624 @item i386_insert_watchpoint (@var{addr}, @var{len}, @var{type})
625 @itemx i386_remove_watchpoint (@var{addr}, @var{len}, @var{type})
626 Insert or remove a watchpoint. The macros
627 @code{target_insert_watchpoint} and @code{target_remove_watchpoint}
628 are set to call these functions. @code{i386_insert_watchpoint} first
629 looks for a debug register which is already set to watch the same
630 region for the same access types; if found, it just increments the
631 reference count of that debug register, thus implementing debug
632 register sharing between watchpoints. If no such register is found,
633 the function looks for a vacant debug register, sets its mirrorred
634 value to @var{addr}, sets the mirrorred value of DR7 Debug Control
635 register as appropriate for the @var{len} and @var{type} parameters,
636 and then passes the new values of the debug register and DR7 to the
637 inferior by calling @code{I386_DR_LOW_SET_ADDR} and
638 @code{I386_DR_LOW_SET_CONTROL}. If more than one debug register is
639 required to cover the given region, the above process is repeated for
642 @code{i386_remove_watchpoint} does the opposite: it resets the address
643 in the mirrorred value of the debug register and its read/write and
644 length bits in the mirrorred value of DR7, then passes these new
645 values to the inferior via @code{I386_DR_LOW_RESET_ADDR} and
646 @code{I386_DR_LOW_SET_CONTROL}. If a register is shared by several
647 watchpoints, each time a @code{i386_remove_watchpoint} is called, it
648 decrements the reference count, and only calls
649 @code{I386_DR_LOW_RESET_ADDR} and @code{I386_DR_LOW_SET_CONTROL} when
650 the count goes to zero.
652 @findex i386_insert_hw_breakpoint
653 @findex i386_remove_hw_breakpoint
654 @item i386_insert_hw_breakpoint (@var{addr}, @var{shadow}
655 @itemx i386_remove_hw_breakpoint (@var{addr}, @var{shadow})
656 These functions insert and remove hardware-assisted breakpoints. The
657 macros @code{target_insert_hw_breakpoint} and
658 @code{target_remove_hw_breakpoint} are set to call these functions.
659 These functions work like @code{i386_insert_watchpoint} and
660 @code{i386_remove_watchpoint}, respectively, except that they set up
661 the debug registers to watch instruction execution, and each
662 hardware-assisted breakpoint always requires exactly one debug
665 @findex i386_stopped_by_hwbp
666 @item i386_stopped_by_hwbp (void)
667 This function returns non-zero if the inferior has some watchpoint or
668 hardware breakpoint that triggered. It works like
669 @code{i386_stopped_data_address}, except that it doesn't return the
670 address whose watchpoint triggered.
672 @findex i386_cleanup_dregs
673 @item i386_cleanup_dregs (void)
674 This function clears all the reference counts, addresses, and control
675 bits in the mirror images of the debug registers. It doesn't affect
676 the actual debug registers in the inferior process.
683 x86 processors support setting watchpoints on I/O reads or writes.
684 However, since no target supports this (as of March 2001), and since
685 @code{enum target_hw_bp_type} doesn't even have an enumeration for I/O
686 watchpoints, this feature is not yet available to @value{GDBN} running
690 x86 processors can enable watchpoints locally, for the current task
691 only, or globally, for all the tasks. For each debug register,
692 there's a bit in the DR7 Debug Control register that determines
693 whether the associated address is watched locally or globally. The
694 current implementation of x86 watchpoint support in @value{GDBN}
695 always sets watchpoints to be locally enabled, since global
696 watchpoints might interfere with the underlying OS and are probably
697 unavailable in many platforms.
702 @chapter User Interface
704 @value{GDBN} has several user interfaces. Although the command-line interface
705 is the most common and most familiar, there are others.
707 @section Command Interpreter
709 @cindex command interpreter
711 The command interpreter in @value{GDBN} is fairly simple. It is designed to
712 allow for the set of commands to be augmented dynamically, and also
713 has a recursive subcommand capability, where the first argument to
714 a command may itself direct a lookup on a different command list.
716 For instance, the @samp{set} command just starts a lookup on the
717 @code{setlist} command list, while @samp{set thread} recurses
718 to the @code{set_thread_cmd_list}.
722 To add commands in general, use @code{add_cmd}. @code{add_com} adds to
723 the main command list, and should be used for those commands. The usual
724 place to add commands is in the @code{_initialize_@var{xyz}} routines at
725 the ends of most source files.
727 @cindex deprecating commands
728 @findex deprecate_cmd
729 Before removing commands from the command set it is a good idea to
730 deprecate them for some time. Use @code{deprecate_cmd} on commands or
731 aliases to set the deprecated flag. @code{deprecate_cmd} takes a
732 @code{struct cmd_list_element} as it's first argument. You can use the
733 return value from @code{add_com} or @code{add_cmd} to deprecate the
734 command immediately after it is created.
736 The first time a command is used the user will be warned and offered a
737 replacement (if one exists). Note that the replacement string passed to
738 @code{deprecate_cmd} should be the full name of the command, i.e. the
739 entire string the user should type at the command line.
741 @section UI-Independent Output---the @code{ui_out} Functions
742 @c This section is based on the documentation written by Fernando
743 @c Nasser <fnasser@redhat.com>.
745 @cindex @code{ui_out} functions
746 The @code{ui_out} functions present an abstraction level for the
747 @value{GDBN} output code. They hide the specifics of different user
748 interfaces supported by @value{GDBN}, and thus free the programmer
749 from the need to write several versions of the same code, one each for
750 every UI, to produce output.
752 @subsection Overview and Terminology
754 In general, execution of each @value{GDBN} command produces some sort
755 of output, and can even generate an input request.
757 Output can be generated for the following purposes:
761 to display a @emph{result} of an operation;
764 to convey @emph{info} or produce side-effects of a requested
768 to provide a @emph{notification} of an asynchronous event (including
769 progress indication of a prolonged asynchronous operation);
772 to display @emph{error messages} (including warnings);
775 to show @emph{debug data};
778 to @emph{query} or prompt a user for input (a special case).
782 This section mainly concentrates on how to build result output,
783 although some of it also applies to other kinds of output.
785 Generation of output that displays the results of an operation
786 involves one or more of the following:
790 output of the actual data
793 formatting the output as appropriate for console output, to make it
794 easily readable by humans
797 machine oriented formatting--a more terse formatting to allow for easy
798 parsing by programs which read @value{GDBN}'s output
801 annotation, whose purpose is to help legacy GUIs to identify interesting
805 The @code{ui_out} routines take care of the first three aspects.
806 Annotations are provided by separate annotation routines. Note that use
807 of annotations for an interface between a GUI and @value{GDBN} is
810 Output can be in the form of a single item, which we call a @dfn{field};
811 a @dfn{list} consisting of identical fields; a @dfn{tuple} consisting of
812 non-identical fields; or a @dfn{table}, which is a tuple consisting of a
813 header and a body. In a BNF-like form:
816 @item <table> @expansion{}
817 @code{<header> <body>}
818 @item <header> @expansion{}
819 @code{@{ <column> @}}
820 @item <column> @expansion{}
821 @code{<width> <alignment> <title>}
822 @item <body> @expansion{}
827 @subsection General Conventions
829 Most @code{ui_out} routines are of type @code{void}, the exceptions are
830 @code{ui_out_stream_new} (which returns a pointer to the newly created
831 object) and the @code{make_cleanup} routines.
833 The first parameter is always the @code{ui_out} vector object, a pointer
834 to a @code{struct ui_out}.
836 The @var{format} parameter is like in @code{printf} family of functions.
837 When it is present, there must also be a variable list of arguments
838 sufficient used to satisfy the @code{%} specifiers in the supplied
841 When a character string argument is not used in a @code{ui_out} function
842 call, a @code{NULL} pointer has to be supplied instead.
845 @subsection Table, Tuple and List Functions
847 @cindex list output functions
848 @cindex table output functions
849 @cindex tuple output functions
850 This section introduces @code{ui_out} routines for building lists,
851 tuples and tables. The routines to output the actual data items
852 (fields) are presented in the next section.
854 To recap: A @dfn{tuple} is a sequence of @dfn{fields}, each field
855 containing information about an object; a @dfn{list} is a sequence of
856 fields where each field describes an identical object.
858 Use the @dfn{table} functions when your output consists of a list of
859 rows (tuples) and the console output should include a heading. Use this
860 even when you are listing just one object but you still want the header.
862 @cindex nesting level in @code{ui_out} functions
863 Tables can not be nested. Tuples and lists can be nested up to a
864 maximum of five levels.
866 The overall structure of the table output code is something like this:
881 Here is the description of table-, tuple- and list-related @code{ui_out}
884 @deftypefun void ui_out_table_begin (struct ui_out *@var{uiout}, int @var{nbrofcols}, int @var{nr_rows}, const char *@var{tblid})
885 The function @code{ui_out_table_begin} marks the beginning of the output
886 of a table. It should always be called before any other @code{ui_out}
887 function for a given table. @var{nbrofcols} is the number of columns in
888 the table. @var{nr_rows} is the number of rows in the table.
889 @var{tblid} is an optional string identifying the table. The string
890 pointed to by @var{tblid} is copied by the implementation of
891 @code{ui_out_table_begin}, so the application can free the string if it
894 The companion function @code{ui_out_table_end}, described below, marks
895 the end of the table's output.
898 @deftypefun void ui_out_table_header (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{colhdr})
899 @code{ui_out_table_header} provides the header information for a single
900 table column. You call this function several times, one each for every
901 column of the table, after @code{ui_out_table_begin}, but before
902 @code{ui_out_table_body}.
904 The value of @var{width} gives the column width in characters. The
905 value of @var{alignment} is one of @code{left}, @code{center}, and
906 @code{right}, and it specifies how to align the header: left-justify,
907 center, or right-justify it. @var{colhdr} points to a string that
908 specifies the column header; the implementation copies that string, so
909 column header strings in @code{malloc}ed storage can be freed after the
913 @deftypefun void ui_out_table_body (struct ui_out *@var{uiout})
914 This function delimits the table header from the table body.
917 @deftypefun void ui_out_table_end (struct ui_out *@var{uiout})
918 This function signals the end of a table's output. It should be called
919 after the table body has been produced by the list and field output
922 There should be exactly one call to @code{ui_out_table_end} for each
923 call to @code{ui_out_table_begin}, otherwise the @code{ui_out} functions
924 will signal an internal error.
927 The output of the tuples that represent the table rows must follow the
928 call to @code{ui_out_table_body} and precede the call to
929 @code{ui_out_table_end}. You build a tuple by calling
930 @code{ui_out_tuple_begin} and @code{ui_out_tuple_end}, with suitable
931 calls to functions which actually output fields between them.
933 @deftypefun void ui_out_tuple_begin (struct ui_out *@var{uiout}, const char *@var{id})
934 This function marks the beginning of a tuple output. @var{id} points
935 to an optional string that identifies the tuple; it is copied by the
936 implementation, and so strings in @code{malloc}ed storage can be freed
940 @deftypefun void ui_out_tuple_end (struct ui_out *@var{uiout})
941 This function signals an end of a tuple output. There should be exactly
942 one call to @code{ui_out_tuple_end} for each call to
943 @code{ui_out_tuple_begin}, otherwise an internal @value{GDBN} error will
947 @deftypefun struct cleanup *make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
948 This function first opens the tuple and then establishes a cleanup
949 (@pxref{Coding, Cleanups}) to close the tuple. It provides a convenient
950 and correct implementation of the non-portable@footnote{The function
951 cast is not portable ISO-C.} code sequence:
953 struct cleanup *old_cleanup;
954 ui_out_tuple_begin (uiout, "...");
955 old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end,
960 @deftypefun void ui_out_list_begin (struct ui_out *@var{uiout}, const char *@var{id})
961 This function marks the beginning of a list output. @var{id} points to
962 an optional string that identifies the list; it is copied by the
963 implementation, and so strings in @code{malloc}ed storage can be freed
967 @deftypefun void ui_out_list_end (struct ui_out *@var{uiout})
968 This function signals an end of a list output. There should be exactly
969 one call to @code{ui_out_list_end} for each call to
970 @code{ui_out_list_begin}, otherwise an internal @value{GDBN} error will
974 @deftypefun struct cleanup *make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
975 Similar to @code{make_cleanup_ui_out_tuple_begin_end}, this function
976 opens a list and then establishes cleanup (@pxref{Coding, Cleanups})
977 that will close the list.list.
980 @subsection Item Output Functions
982 @cindex item output functions
983 @cindex field output functions
985 The functions described below produce output for the actual data
986 items, or fields, which contain information about the object.
988 Choose the appropriate function accordingly to your particular needs.
990 @deftypefun void ui_out_field_fmt (struct ui_out *@var{uiout}, char *@var{fldname}, char *@var{format}, ...)
991 This is the most general output function. It produces the
992 representation of the data in the variable-length argument list
993 according to formatting specifications in @var{format}, a
994 @code{printf}-like format string. The optional argument @var{fldname}
995 supplies the name of the field. The data items themselves are
996 supplied as additional arguments after @var{format}.
998 This generic function should be used only when it is not possible to
999 use one of the specialized versions (see below).
1002 @deftypefun void ui_out_field_int (struct ui_out *@var{uiout}, const char *@var{fldname}, int @var{value})
1003 This function outputs a value of an @code{int} variable. It uses the
1004 @code{"%d"} output conversion specification. @var{fldname} specifies
1005 the name of the field.
1008 @deftypefun void ui_out_field_core_addr (struct ui_out *@var{uiout}, const char *@var{fldname}, CORE_ADDR @var{address})
1009 This function outputs an address.
1012 @deftypefun void ui_out_field_string (struct ui_out *@var{uiout}, const char *@var{fldname}, const char *@var{string})
1013 This function outputs a string using the @code{"%s"} conversion
1017 Sometimes, there's a need to compose your output piece by piece using
1018 functions that operate on a stream, such as @code{value_print} or
1019 @code{fprintf_symbol_filtered}. These functions accept an argument of
1020 the type @code{struct ui_file *}, a pointer to a @code{ui_file} object
1021 used to store the data stream used for the output. When you use one
1022 of these functions, you need a way to pass their results stored in a
1023 @code{ui_file} object to the @code{ui_out} functions. To this end,
1024 you first create a @code{ui_stream} object by calling
1025 @code{ui_out_stream_new}, pass the @code{stream} member of that
1026 @code{ui_stream} object to @code{value_print} and similar functions,
1027 and finally call @code{ui_out_field_stream} to output the field you
1028 constructed. When the @code{ui_stream} object is no longer needed,
1029 you should destroy it and free its memory by calling
1030 @code{ui_out_stream_delete}.
1032 @deftypefun struct ui_stream *ui_out_stream_new (struct ui_out *@var{uiout})
1033 This function creates a new @code{ui_stream} object which uses the
1034 same output methods as the @code{ui_out} object whose pointer is
1035 passed in @var{uiout}. It returns a pointer to the newly created
1036 @code{ui_stream} object.
1039 @deftypefun void ui_out_stream_delete (struct ui_stream *@var{streambuf})
1040 This functions destroys a @code{ui_stream} object specified by
1044 @deftypefun void ui_out_field_stream (struct ui_out *@var{uiout}, const char *@var{fieldname}, struct ui_stream *@var{streambuf})
1045 This function consumes all the data accumulated in
1046 @code{streambuf->stream} and outputs it like
1047 @code{ui_out_field_string} does. After a call to
1048 @code{ui_out_field_stream}, the accumulated data no longer exists, but
1049 the stream is still valid and may be used for producing more fields.
1052 @strong{Important:} If there is any chance that your code could bail
1053 out before completing output generation and reaching the point where
1054 @code{ui_out_stream_delete} is called, it is necessary to set up a
1055 cleanup, to avoid leaking memory and other resources. Here's a
1056 skeleton code to do that:
1059 struct ui_stream *mybuf = ui_out_stream_new (uiout);
1060 struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf);
1065 If the function already has the old cleanup chain set (for other kinds
1066 of cleanups), you just have to add your cleanup to it:
1069 mybuf = ui_out_stream_new (uiout);
1070 make_cleanup (ui_out_stream_delete, mybuf);
1073 Note that with cleanups in place, you should not call
1074 @code{ui_out_stream_delete} directly, or you would attempt to free the
1077 @subsection Utility Output Functions
1079 @deftypefun void ui_out_field_skip (struct ui_out *@var{uiout}, const char *@var{fldname})
1080 This function skips a field in a table. Use it if you have to leave
1081 an empty field without disrupting the table alignment. The argument
1082 @var{fldname} specifies a name for the (missing) filed.
1085 @deftypefun void ui_out_text (struct ui_out *@var{uiout}, const char *@var{string})
1086 This function outputs the text in @var{string} in a way that makes it
1087 easy to be read by humans. For example, the console implementation of
1088 this method filters the text through a built-in pager, to prevent it
1089 from scrolling off the visible portion of the screen.
1091 Use this function for printing relatively long chunks of text around
1092 the actual field data: the text it produces is not aligned according
1093 to the table's format. Use @code{ui_out_field_string} to output a
1094 string field, and use @code{ui_out_message}, described below, to
1095 output short messages.
1098 @deftypefun void ui_out_spaces (struct ui_out *@var{uiout}, int @var{nspaces})
1099 This function outputs @var{nspaces} spaces. It is handy to align the
1100 text produced by @code{ui_out_text} with the rest of the table or
1104 @deftypefun void ui_out_message (struct ui_out *@var{uiout}, int @var{verbosity}, const char *@var{format}, ...)
1105 This function produces a formatted message, provided that the current
1106 verbosity level is at least as large as given by @var{verbosity}. The
1107 current verbosity level is specified by the user with the @samp{set
1108 verbositylevel} command.@footnote{As of this writing (April 2001),
1109 setting verbosity level is not yet implemented, and is always returned
1110 as zero. So calling @code{ui_out_message} with a @var{verbosity}
1111 argument more than zero will cause the message to never be printed.}
1114 @deftypefun void ui_out_wrap_hint (struct ui_out *@var{uiout}, char *@var{indent})
1115 This function gives the console output filter (a paging filter) a hint
1116 of where to break lines which are too long. Ignored for all other
1117 output consumers. @var{indent}, if non-@code{NULL}, is the string to
1118 be printed to indent the wrapped text on the next line; it must remain
1119 accessible until the next call to @code{ui_out_wrap_hint}, or until an
1120 explicit newline is produced by one of the other functions. If
1121 @var{indent} is @code{NULL}, the wrapped text will not be indented.
1124 @deftypefun void ui_out_flush (struct ui_out *@var{uiout})
1125 This function flushes whatever output has been accumulated so far, if
1126 the UI buffers output.
1130 @subsection Examples of Use of @code{ui_out} functions
1132 @cindex using @code{ui_out} functions
1133 @cindex @code{ui_out} functions, usage examples
1134 This section gives some practical examples of using the @code{ui_out}
1135 functions to generalize the old console-oriented code in
1136 @value{GDBN}. The examples all come from functions defined on the
1137 @file{breakpoints.c} file.
1139 This example, from the @code{breakpoint_1} function, shows how to
1142 The original code was:
1145 if (!found_a_breakpoint++)
1147 annotate_breakpoints_headers ();
1150 printf_filtered ("Num ");
1152 printf_filtered ("Type ");
1154 printf_filtered ("Disp ");
1156 printf_filtered ("Enb ");
1160 printf_filtered ("Address ");
1163 printf_filtered ("What\n");
1165 annotate_breakpoints_table ();
1169 Here's the new version:
1172 nr_printable_breakpoints = @dots{};
1175 ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable");
1177 ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable");
1179 if (nr_printable_breakpoints > 0)
1180 annotate_breakpoints_headers ();
1181 if (nr_printable_breakpoints > 0)
1183 ui_out_table_header (uiout, 3, ui_left, "number", "Num"); /* 1 */
1184 if (nr_printable_breakpoints > 0)
1186 ui_out_table_header (uiout, 14, ui_left, "type", "Type"); /* 2 */
1187 if (nr_printable_breakpoints > 0)
1189 ui_out_table_header (uiout, 4, ui_left, "disp", "Disp"); /* 3 */
1190 if (nr_printable_breakpoints > 0)
1192 ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb"); /* 4 */
1195 if (nr_printable_breakpoints > 0)
1197 if (TARGET_ADDR_BIT <= 32)
1198 ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */
1200 ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */
1202 if (nr_printable_breakpoints > 0)
1204 ui_out_table_header (uiout, 40, ui_noalign, "what", "What"); /* 6 */
1205 ui_out_table_body (uiout);
1206 if (nr_printable_breakpoints > 0)
1207 annotate_breakpoints_table ();
1210 This example, from the @code{print_one_breakpoint} function, shows how
1211 to produce the actual data for the table whose structure was defined
1212 in the above example. The original code was:
1217 printf_filtered ("%-3d ", b->number);
1219 if ((int)b->type > (sizeof(bptypes)/sizeof(bptypes[0]))
1220 || ((int) b->type != bptypes[(int) b->type].type))
1221 internal_error ("bptypes table does not describe type #%d.",
1223 printf_filtered ("%-14s ", bptypes[(int)b->type].description);
1225 printf_filtered ("%-4s ", bpdisps[(int)b->disposition]);
1227 printf_filtered ("%-3c ", bpenables[(int)b->enable]);
1231 This is the new version:
1235 ui_out_tuple_begin (uiout, "bkpt");
1237 ui_out_field_int (uiout, "number", b->number);
1239 if (((int) b->type > (sizeof (bptypes) / sizeof (bptypes[0])))
1240 || ((int) b->type != bptypes[(int) b->type].type))
1241 internal_error ("bptypes table does not describe type #%d.",
1243 ui_out_field_string (uiout, "type", bptypes[(int)b->type].description);
1245 ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]);
1247 ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);
1251 This example, also from @code{print_one_breakpoint}, shows how to
1252 produce a complicated output field using the @code{print_expression}
1253 functions which requires a stream to be passed. It also shows how to
1254 automate stream destruction with cleanups. The original code was:
1258 print_expression (b->exp, gdb_stdout);
1264 struct ui_stream *stb = ui_out_stream_new (uiout);
1265 struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb);
1268 print_expression (b->exp, stb->stream);
1269 ui_out_field_stream (uiout, "what", local_stream);
1272 This example, also from @code{print_one_breakpoint}, shows how to use
1273 @code{ui_out_text} and @code{ui_out_field_string}. The original code
1278 if (b->dll_pathname == NULL)
1279 printf_filtered ("<any library> ");
1281 printf_filtered ("library \"%s\" ", b->dll_pathname);
1288 if (b->dll_pathname == NULL)
1290 ui_out_field_string (uiout, "what", "<any library>");
1291 ui_out_spaces (uiout, 1);
1295 ui_out_text (uiout, "library \"");
1296 ui_out_field_string (uiout, "what", b->dll_pathname);
1297 ui_out_text (uiout, "\" ");
1301 The following example from @code{print_one_breakpoint} shows how to
1302 use @code{ui_out_field_int} and @code{ui_out_spaces}. The original
1307 if (b->forked_inferior_pid != 0)
1308 printf_filtered ("process %d ", b->forked_inferior_pid);
1315 if (b->forked_inferior_pid != 0)
1317 ui_out_text (uiout, "process ");
1318 ui_out_field_int (uiout, "what", b->forked_inferior_pid);
1319 ui_out_spaces (uiout, 1);
1323 Here's an example of using @code{ui_out_field_string}. The original
1328 if (b->exec_pathname != NULL)
1329 printf_filtered ("program \"%s\" ", b->exec_pathname);
1336 if (b->exec_pathname != NULL)
1338 ui_out_text (uiout, "program \"");
1339 ui_out_field_string (uiout, "what", b->exec_pathname);
1340 ui_out_text (uiout, "\" ");
1344 Finally, here's an example of printing an address. The original code:
1348 printf_filtered ("%s ",
1349 local_hex_string_custom ((unsigned long) b->address, "08l"));
1356 ui_out_field_core_addr (uiout, "Address", b->address);
1360 @section Console Printing
1369 @cindex @code{libgdb}
1370 @code{libgdb} 1.0 was an abortive project of years ago. The theory was
1371 to provide an API to @value{GDBN}'s functionality.
1374 @cindex @code{libgdb}
1375 @code{libgdb} 2.0 is an ongoing effort to update @value{GDBN} so that is
1376 better able to support graphical and other environments.
1378 Since @code{libgdb} development is on-going, its architecture is still
1379 evolving. The following components have so far been identified:
1383 Observer - @file{gdb-events.h}.
1385 Builder - @file{ui-out.h}
1387 Event Loop - @file{event-loop.h}
1389 Library - @file{gdb.h}
1392 The model that ties these components together is described below.
1394 @section The @code{libgdb} Model
1396 A client of @code{libgdb} interacts with the library in two ways.
1400 As an observer (using @file{gdb-events}) receiving notifications from
1401 @code{libgdb} of any internal state changes (break point changes, run
1404 As a client querying @code{libgdb} (using the @file{ui-out} builder) to
1405 obtain various status values from @value{GDBN}.
1408 Since @code{libgdb} could have multiple clients (e.g. a GUI supporting
1409 the existing @value{GDBN} CLI), those clients must co-operate when
1410 controlling @code{libgdb}. In particular, a client must ensure that
1411 @code{libgdb} is idle (i.e. no other client is using @code{libgdb})
1412 before responding to a @file{gdb-event} by making a query.
1414 @section CLI support
1416 At present @value{GDBN}'s CLI is very much entangled in with the core of
1417 @code{libgdb}. Consequently, a client wishing to include the CLI in
1418 their interface needs to carefully co-ordinate its own and the CLI's
1421 It is suggested that the client set @code{libgdb} up to be bi-modal
1422 (alternate between CLI and client query modes). The notes below sketch
1427 The client registers itself as an observer of @code{libgdb}.
1429 The client create and install @code{cli-out} builder using its own
1430 versions of the @code{ui-file} @code{gdb_stderr}, @code{gdb_stdtarg} and
1431 @code{gdb_stdout} streams.
1433 The client creates a separate custom @code{ui-out} builder that is only
1434 used while making direct queries to @code{libgdb}.
1437 When the client receives input intended for the CLI, it simply passes it
1438 along. Since the @code{cli-out} builder is installed by default, all
1439 the CLI output in response to that command is routed (pronounced rooted)
1440 through to the client controlled @code{gdb_stdout} et.@: al.@: streams.
1441 At the same time, the client is kept abreast of internal changes by
1442 virtue of being a @code{libgdb} observer.
1444 The only restriction on the client is that it must wait until
1445 @code{libgdb} becomes idle before initiating any queries (using the
1446 client's custom builder).
1448 @section @code{libgdb} components
1450 @subheading Observer - @file{gdb-events.h}
1451 @file{gdb-events} provides the client with a very raw mechanism that can
1452 be used to implement an observer. At present it only allows for one
1453 observer and that observer must, internally, handle the need to delay
1454 the processing of any event notifications until after @code{libgdb} has
1455 finished the current command.
1457 @subheading Builder - @file{ui-out.h}
1458 @file{ui-out} provides the infrastructure necessary for a client to
1459 create a builder. That builder is then passed down to @code{libgdb}
1460 when doing any queries.
1462 @subheading Event Loop - @file{event-loop.h}
1463 @c There could be an entire section on the event-loop
1464 @file{event-loop}, currently non-re-entrant, provides a simple event
1465 loop. A client would need to either plug its self into this loop or,
1466 implement a new event-loop that GDB would use.
1468 The event-loop will eventually be made re-entrant. This is so that
1469 @value{GDB} can better handle the problem of some commands blocking
1470 instead of returning.
1472 @subheading Library - @file{gdb.h}
1473 @file{libgdb} is the most obvious component of this system. It provides
1474 the query interface. Each function is parameterized by a @code{ui-out}
1475 builder. The result of the query is constructed using that builder
1476 before the query function returns.
1478 @node Symbol Handling
1480 @chapter Symbol Handling
1482 Symbols are a key part of @value{GDBN}'s operation. Symbols include variables,
1483 functions, and types.
1485 @section Symbol Reading
1487 @cindex symbol reading
1488 @cindex reading of symbols
1489 @cindex symbol files
1490 @value{GDBN} reads symbols from @dfn{symbol files}. The usual symbol
1491 file is the file containing the program which @value{GDBN} is
1492 debugging. @value{GDBN} can be directed to use a different file for
1493 symbols (with the @samp{symbol-file} command), and it can also read
1494 more symbols via the @samp{add-file} and @samp{load} commands, or while
1495 reading symbols from shared libraries.
1497 @findex find_sym_fns
1498 Symbol files are initially opened by code in @file{symfile.c} using
1499 the BFD library (@pxref{Support Libraries}). BFD identifies the type
1500 of the file by examining its header. @code{find_sym_fns} then uses
1501 this identification to locate a set of symbol-reading functions.
1503 @findex add_symtab_fns
1504 @cindex @code{sym_fns} structure
1505 @cindex adding a symbol-reading module
1506 Symbol-reading modules identify themselves to @value{GDBN} by calling
1507 @code{add_symtab_fns} during their module initialization. The argument
1508 to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the
1509 name (or name prefix) of the symbol format, the length of the prefix,
1510 and pointers to four functions. These functions are called at various
1511 times to process symbol files whose identification matches the specified
1514 The functions supplied by each module are:
1517 @item @var{xyz}_symfile_init(struct sym_fns *sf)
1519 @cindex secondary symbol file
1520 Called from @code{symbol_file_add} when we are about to read a new
1521 symbol file. This function should clean up any internal state (possibly
1522 resulting from half-read previous files, for example) and prepare to
1523 read a new symbol file. Note that the symbol file which we are reading
1524 might be a new ``main'' symbol file, or might be a secondary symbol file
1525 whose symbols are being added to the existing symbol table.
1527 The argument to @code{@var{xyz}_symfile_init} is a newly allocated
1528 @code{struct sym_fns} whose @code{bfd} field contains the BFD for the
1529 new symbol file being read. Its @code{private} field has been zeroed,
1530 and can be modified as desired. Typically, a struct of private
1531 information will be @code{malloc}'d, and a pointer to it will be placed
1532 in the @code{private} field.
1534 There is no result from @code{@var{xyz}_symfile_init}, but it can call
1535 @code{error} if it detects an unavoidable problem.
1537 @item @var{xyz}_new_init()
1539 Called from @code{symbol_file_add} when discarding existing symbols.
1540 This function needs only handle the symbol-reading module's internal
1541 state; the symbol table data structures visible to the rest of
1542 @value{GDBN} will be discarded by @code{symbol_file_add}. It has no
1543 arguments and no result. It may be called after
1544 @code{@var{xyz}_symfile_init}, if a new symbol table is being read, or
1545 may be called alone if all symbols are simply being discarded.
1547 @item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)
1549 Called from @code{symbol_file_add} to actually read the symbols from a
1550 symbol-file into a set of psymtabs or symtabs.
1552 @code{sf} points to the @code{struct sym_fns} originally passed to
1553 @code{@var{xyz}_sym_init} for possible initialization. @code{addr} is
1554 the offset between the file's specified start address and its true
1555 address in memory. @code{mainline} is 1 if this is the main symbol
1556 table being read, and 0 if a secondary symbol file (e.g. shared library
1557 or dynamically loaded file) is being read.@refill
1560 In addition, if a symbol-reading module creates psymtabs when
1561 @var{xyz}_symfile_read is called, these psymtabs will contain a pointer
1562 to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called
1563 from any point in the @value{GDBN} symbol-handling code.
1566 @item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst)
1568 Called from @code{psymtab_to_symtab} (or the @code{PSYMTAB_TO_SYMTAB} macro) if
1569 the psymtab has not already been read in and had its @code{pst->symtab}
1570 pointer set. The argument is the psymtab to be fleshed-out into a
1571 symtab. Upon return, @code{pst->readin} should have been set to 1, and
1572 @code{pst->symtab} should contain a pointer to the new corresponding symtab, or
1573 zero if there were no symbols in that part of the symbol file.
1576 @section Partial Symbol Tables
1578 @value{GDBN} has three types of symbol tables:
1581 @cindex full symbol table
1584 Full symbol tables (@dfn{symtabs}). These contain the main
1585 information about symbols and addresses.
1589 Partial symbol tables (@dfn{psymtabs}). These contain enough
1590 information to know when to read the corresponding part of the full
1593 @cindex minimal symbol table
1596 Minimal symbol tables (@dfn{msymtabs}). These contain information
1597 gleaned from non-debugging symbols.
1600 @cindex partial symbol table
1601 This section describes partial symbol tables.
1603 A psymtab is constructed by doing a very quick pass over an executable
1604 file's debugging information. Small amounts of information are
1605 extracted---enough to identify which parts of the symbol table will
1606 need to be re-read and fully digested later, when the user needs the
1607 information. The speed of this pass causes @value{GDBN} to start up very
1608 quickly. Later, as the detailed rereading occurs, it occurs in small
1609 pieces, at various times, and the delay therefrom is mostly invisible to
1611 @c (@xref{Symbol Reading}.)
1613 The symbols that show up in a file's psymtab should be, roughly, those
1614 visible to the debugger's user when the program is not running code from
1615 that file. These include external symbols and types, static symbols and
1616 types, and @code{enum} values declared at file scope.
1618 The psymtab also contains the range of instruction addresses that the
1619 full symbol table would represent.
1621 @cindex finding a symbol
1622 @cindex symbol lookup
1623 The idea is that there are only two ways for the user (or much of the
1624 code in the debugger) to reference a symbol:
1627 @findex find_pc_function
1628 @findex find_pc_line
1630 By its address (e.g. execution stops at some address which is inside a
1631 function in this file). The address will be noticed to be in the
1632 range of this psymtab, and the full symtab will be read in.
1633 @code{find_pc_function}, @code{find_pc_line}, and other
1634 @code{find_pc_@dots{}} functions handle this.
1636 @cindex lookup_symbol
1639 (e.g. the user asks to print a variable, or set a breakpoint on a
1640 function). Global names and file-scope names will be found in the
1641 psymtab, which will cause the symtab to be pulled in. Local names will
1642 have to be qualified by a global name, or a file-scope name, in which
1643 case we will have already read in the symtab as we evaluated the
1644 qualifier. Or, a local symbol can be referenced when we are ``in'' a
1645 local scope, in which case the first case applies. @code{lookup_symbol}
1646 does most of the work here.
1649 The only reason that psymtabs exist is to cause a symtab to be read in
1650 at the right moment. Any symbol that can be elided from a psymtab,
1651 while still causing that to happen, should not appear in it. Since
1652 psymtabs don't have the idea of scope, you can't put local symbols in
1653 them anyway. Psymtabs don't have the idea of the type of a symbol,
1654 either, so types need not appear, unless they will be referenced by
1657 It is a bug for @value{GDBN} to behave one way when only a psymtab has
1658 been read, and another way if the corresponding symtab has been read
1659 in. Such bugs are typically caused by a psymtab that does not contain
1660 all the visible symbols, or which has the wrong instruction address
1663 The psymtab for a particular section of a symbol file (objfile) could be
1664 thrown away after the symtab has been read in. The symtab should always
1665 be searched before the psymtab, so the psymtab will never be used (in a
1666 bug-free environment). Currently, psymtabs are allocated on an obstack,
1667 and all the psymbols themselves are allocated in a pair of large arrays
1668 on an obstack, so there is little to be gained by trying to free them
1669 unless you want to do a lot more work.
1673 @unnumberedsubsec Fundamental Types (e.g., @code{FT_VOID}, @code{FT_BOOLEAN}).
1675 @cindex fundamental types
1676 These are the fundamental types that @value{GDBN} uses internally. Fundamental
1677 types from the various debugging formats (stabs, ELF, etc) are mapped
1678 into one of these. They are basically a union of all fundamental types
1679 that @value{GDBN} knows about for all the languages that @value{GDBN}
1682 @unnumberedsubsec Type Codes (e.g., @code{TYPE_CODE_PTR}, @code{TYPE_CODE_ARRAY}).
1685 Each time @value{GDBN} builds an internal type, it marks it with one
1686 of these types. The type may be a fundamental type, such as
1687 @code{TYPE_CODE_INT}, or a derived type, such as @code{TYPE_CODE_PTR}
1688 which is a pointer to another type. Typically, several @code{FT_*}
1689 types map to one @code{TYPE_CODE_*} type, and are distinguished by
1690 other members of the type struct, such as whether the type is signed
1691 or unsigned, and how many bits it uses.
1693 @unnumberedsubsec Builtin Types (e.g., @code{builtin_type_void}, @code{builtin_type_char}).
1695 These are instances of type structs that roughly correspond to
1696 fundamental types and are created as global types for @value{GDBN} to
1697 use for various ugly historical reasons. We eventually want to
1698 eliminate these. Note for example that @code{builtin_type_int}
1699 initialized in @file{gdbtypes.c} is basically the same as a
1700 @code{TYPE_CODE_INT} type that is initialized in @file{c-lang.c} for
1701 an @code{FT_INTEGER} fundamental type. The difference is that the
1702 @code{builtin_type} is not associated with any particular objfile, and
1703 only one instance exists, while @file{c-lang.c} builds as many
1704 @code{TYPE_CODE_INT} types as needed, with each one associated with
1705 some particular objfile.
1707 @section Object File Formats
1708 @cindex object file formats
1712 @cindex @code{a.out} format
1713 The @code{a.out} format is the original file format for Unix. It
1714 consists of three sections: @code{text}, @code{data}, and @code{bss},
1715 which are for program code, initialized data, and uninitialized data,
1718 The @code{a.out} format is so simple that it doesn't have any reserved
1719 place for debugging information. (Hey, the original Unix hackers used
1720 @samp{adb}, which is a machine-language debugger!) The only debugging
1721 format for @code{a.out} is stabs, which is encoded as a set of normal
1722 symbols with distinctive attributes.
1724 The basic @code{a.out} reader is in @file{dbxread.c}.
1729 The COFF format was introduced with System V Release 3 (SVR3) Unix.
1730 COFF files may have multiple sections, each prefixed by a header. The
1731 number of sections is limited.
1733 The COFF specification includes support for debugging. Although this
1734 was a step forward, the debugging information was woefully limited. For
1735 instance, it was not possible to represent code that came from an
1738 The COFF reader is in @file{coffread.c}.
1742 @cindex ECOFF format
1743 ECOFF is an extended COFF originally introduced for Mips and Alpha
1746 The basic ECOFF reader is in @file{mipsread.c}.
1750 @cindex XCOFF format
1751 The IBM RS/6000 running AIX uses an object file format called XCOFF.
1752 The COFF sections, symbols, and line numbers are used, but debugging
1753 symbols are @code{dbx}-style stabs whose strings are located in the
1754 @code{.debug} section (rather than the string table). For more
1755 information, see @ref{Top,,,stabs,The Stabs Debugging Format}.
1757 The shared library scheme has a clean interface for figuring out what
1758 shared libraries are in use, but the catch is that everything which
1759 refers to addresses (symbol tables and breakpoints at least) needs to be
1760 relocated for both shared libraries and the main executable. At least
1761 using the standard mechanism this can only be done once the program has
1762 been run (or the core file has been read).
1766 @cindex PE-COFF format
1767 Windows 95 and NT use the PE (@dfn{Portable Executable}) format for their
1768 executables. PE is basically COFF with additional headers.
1770 While BFD includes special PE support, @value{GDBN} needs only the basic
1776 The ELF format came with System V Release 4 (SVR4) Unix. ELF is similar
1777 to COFF in being organized into a number of sections, but it removes
1778 many of COFF's limitations.
1780 The basic ELF reader is in @file{elfread.c}.
1785 SOM is HP's object file and debug format (not to be confused with IBM's
1786 SOM, which is a cross-language ABI).
1788 The SOM reader is in @file{hpread.c}.
1790 @subsection Other File Formats
1792 @cindex Netware Loadable Module format
1793 Other file formats that have been supported by @value{GDBN} include Netware
1794 Loadable Modules (@file{nlmread.c}).
1796 @section Debugging File Formats
1798 This section describes characteristics of debugging information that
1799 are independent of the object file format.
1803 @cindex stabs debugging info
1804 @code{stabs} started out as special symbols within the @code{a.out}
1805 format. Since then, it has been encapsulated into other file
1806 formats, such as COFF and ELF.
1808 While @file{dbxread.c} does some of the basic stab processing,
1809 including for encapsulated versions, @file{stabsread.c} does
1814 @cindex COFF debugging info
1815 The basic COFF definition includes debugging information. The level
1816 of support is minimal and non-extensible, and is not often used.
1818 @subsection Mips debug (Third Eye)
1820 @cindex ECOFF debugging info
1821 ECOFF includes a definition of a special debug format.
1823 The file @file{mdebugread.c} implements reading for this format.
1827 @cindex DWARF 1 debugging info
1828 DWARF 1 is a debugging format that was originally designed to be
1829 used with ELF in SVR4 systems.
1835 @c If defined, these are the producer strings in a DWARF 1 file. All of
1836 @c these have reasonable defaults already.
1838 The DWARF 1 reader is in @file{dwarfread.c}.
1842 @cindex DWARF 2 debugging info
1843 DWARF 2 is an improved but incompatible version of DWARF 1.
1845 The DWARF 2 reader is in @file{dwarf2read.c}.
1849 @cindex SOM debugging info
1850 Like COFF, the SOM definition includes debugging information.
1852 @section Adding a New Symbol Reader to @value{GDBN}
1854 @cindex adding debugging info reader
1855 If you are using an existing object file format (@code{a.out}, COFF, ELF, etc),
1856 there is probably little to be done.
1858 If you need to add a new object file format, you must first add it to
1859 BFD. This is beyond the scope of this document.
1861 You must then arrange for the BFD code to provide access to the
1862 debugging symbols. Generally @value{GDBN} will have to call swapping routines
1863 from BFD and a few other BFD internal routines to locate the debugging
1864 information. As much as possible, @value{GDBN} should not depend on the BFD
1865 internal data structures.
1867 For some targets (e.g., COFF), there is a special transfer vector used
1868 to call swapping routines, since the external data structures on various
1869 platforms have different sizes and layouts. Specialized routines that
1870 will only ever be implemented by one object file format may be called
1871 directly. This interface should be described in a file
1872 @file{bfd/lib@var{xyz}.h}, which is included by @value{GDBN}.
1875 @node Language Support
1877 @chapter Language Support
1879 @cindex language support
1880 @value{GDBN}'s language support is mainly driven by the symbol reader,
1881 although it is possible for the user to set the source language
1884 @value{GDBN} chooses the source language by looking at the extension
1885 of the file recorded in the debug info; @file{.c} means C, @file{.f}
1886 means Fortran, etc. It may also use a special-purpose language
1887 identifier if the debug format supports it, like with DWARF.
1889 @section Adding a Source Language to @value{GDBN}
1891 @cindex adding source language
1892 To add other languages to @value{GDBN}'s expression parser, follow the
1896 @item Create the expression parser.
1898 @cindex expression parser
1899 This should reside in a file @file{@var{lang}-exp.y}. Routines for
1900 building parsed expressions into a @code{union exp_element} list are in
1903 @cindex language parser
1904 Since we can't depend upon everyone having Bison, and YACC produces
1905 parsers that define a bunch of global names, the following lines
1906 @strong{must} be included at the top of the YACC parser, to prevent the
1907 various parsers from defining the same global names:
1910 #define yyparse @var{lang}_parse
1911 #define yylex @var{lang}_lex
1912 #define yyerror @var{lang}_error
1913 #define yylval @var{lang}_lval
1914 #define yychar @var{lang}_char
1915 #define yydebug @var{lang}_debug
1916 #define yypact @var{lang}_pact
1917 #define yyr1 @var{lang}_r1
1918 #define yyr2 @var{lang}_r2
1919 #define yydef @var{lang}_def
1920 #define yychk @var{lang}_chk
1921 #define yypgo @var{lang}_pgo
1922 #define yyact @var{lang}_act
1923 #define yyexca @var{lang}_exca
1924 #define yyerrflag @var{lang}_errflag
1925 #define yynerrs @var{lang}_nerrs
1928 At the bottom of your parser, define a @code{struct language_defn} and
1929 initialize it with the right values for your language. Define an
1930 @code{initialize_@var{lang}} routine and have it call
1931 @samp{add_language(@var{lang}_language_defn)} to tell the rest of @value{GDBN}
1932 that your language exists. You'll need some other supporting variables
1933 and functions, which will be used via pointers from your
1934 @code{@var{lang}_language_defn}. See the declaration of @code{struct
1935 language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
1936 for more information.
1938 @item Add any evaluation routines, if necessary
1940 @cindex expression evaluation routines
1941 @findex evaluate_subexp
1942 @findex prefixify_subexp
1943 @findex length_of_subexp
1944 If you need new opcodes (that represent the operations of the language),
1945 add them to the enumerated type in @file{expression.h}. Add support
1946 code for these operations in the @code{evaluate_subexp} function
1947 defined in the file @file{eval.c}. Add cases
1948 for new opcodes in two functions from @file{parse.c}:
1949 @code{prefixify_subexp} and @code{length_of_subexp}. These compute
1950 the number of @code{exp_element}s that a given operation takes up.
1952 @item Update some existing code
1954 Add an enumerated identifier for your language to the enumerated type
1955 @code{enum language} in @file{defs.h}.
1957 Update the routines in @file{language.c} so your language is included.
1958 These routines include type predicates and such, which (in some cases)
1959 are language dependent. If your language does not appear in the switch
1960 statement, an error is reported.
1962 @vindex current_language
1963 Also included in @file{language.c} is the code that updates the variable
1964 @code{current_language}, and the routines that translate the
1965 @code{language_@var{lang}} enumerated identifier into a printable
1968 @findex _initialize_language
1969 Update the function @code{_initialize_language} to include your
1970 language. This function picks the default language upon startup, so is
1971 dependent upon which languages that @value{GDBN} is built for.
1973 @findex allocate_symtab
1974 Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
1975 code so that the language of each symtab (source file) is set properly.
1976 This is used to determine the language to use at each stack frame level.
1977 Currently, the language is set based upon the extension of the source
1978 file. If the language can be better inferred from the symbol
1979 information, please set the language of the symtab in the symbol-reading
1982 @findex print_subexp
1983 @findex op_print_tab
1984 Add helper code to @code{print_subexp} (in @file{expprint.c}) to handle any new
1985 expression opcodes you have added to @file{expression.h}. Also, add the
1986 printed representations of your operators to @code{op_print_tab}.
1988 @item Add a place of call
1991 Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
1992 @code{parse_exp_1} (defined in @file{parse.c}).
1994 @item Use macros to trim code
1996 @cindex trimming language-dependent code
1997 The user has the option of building @value{GDBN} for some or all of the
1998 languages. If the user decides to build @value{GDBN} for the language
1999 @var{lang}, then every file dependent on @file{language.h} will have the
2000 macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to
2001 leave out large routines that the user won't need if he or she is not
2002 using your language.
2004 Note that you do not need to do this in your YACC parser, since if @value{GDBN}
2005 is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
2006 compiled form of your parser) is not linked into @value{GDBN} at all.
2008 See the file @file{configure.in} for how @value{GDBN} is configured
2009 for different languages.
2011 @item Edit @file{Makefile.in}
2013 Add dependencies in @file{Makefile.in}. Make sure you update the macro
2014 variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
2015 not get linked in, or, worse yet, it may not get @code{tar}red into the
2020 @node Host Definition
2022 @chapter Host Definition
2024 @emph{Maintainer's note: In theory, new targets no longer need to use
2025 the host framework described below. Instead it should be possible to
2026 handle everything using autoconf. Patches eliminating this framework
2029 With the advent of Autoconf, it's rarely necessary to have host
2030 definition machinery anymore.
2032 @section Adding a New Host
2034 @cindex adding a new host
2035 @cindex host, adding
2036 Most of @value{GDBN}'s host configuration support happens via
2037 Autoconf. New host-specific definitions should be rarely needed.
2038 @value{GDBN} still uses the host-specific definitions and files listed
2039 below, but these mostly exist for historical reasons, and should
2040 eventually disappear.
2042 Several files control @value{GDBN}'s configuration for host systems:
2046 @item gdb/config/@var{arch}/@var{xyz}.mh
2047 Specifies Makefile fragments needed when hosting on machine @var{xyz}.
2048 In particular, this lists the required machine-dependent object files,
2049 by defining @samp{XDEPFILES=@dots{}}. Also specifies the header file
2050 which describes host @var{xyz}, by defining @code{XM_FILE=
2051 xm-@var{xyz}.h}. You can also define @code{CC}, @code{SYSV_DEFINE},
2052 @code{XM_CFLAGS}, @code{XM_ADD_FILES}, @code{XM_CLIBS}, @code{XM_CDEPS},
2053 etc.; see @file{Makefile.in}.
2055 @item gdb/config/@var{arch}/xm-@var{xyz}.h
2056 (@file{xm.h} is a link to this file, created by @code{configure}). Contains C
2057 macro definitions describing the host system environment, such as byte
2058 order, host C compiler and library.
2060 @item gdb/@var{xyz}-xdep.c
2061 Contains any miscellaneous C code required for this machine as a host.
2062 On most machines it doesn't exist at all. If it does exist, put
2063 @file{@var{xyz}-xdep.o} into the @code{XDEPFILES} line in
2064 @file{gdb/config/@var{arch}/@var{xyz}.mh}.
2067 @subheading Generic Host Support Files
2069 @cindex generic host support
2070 There are some ``generic'' versions of routines that can be used by
2071 various systems. These can be customized in various ways by macros
2072 defined in your @file{xm-@var{xyz}.h} file. If these routines work for
2073 the @var{xyz} host, you can just include the generic file's name (with
2074 @samp{.o}, not @samp{.c}) in @code{XDEPFILES}.
2076 Otherwise, if your machine needs custom support routines, you will need
2077 to write routines that perform the same functions as the generic file.
2078 Put them into @code{@var{xyz}-xdep.c}, and put @code{@var{xyz}-xdep.o}
2079 into @code{XDEPFILES}.
2082 @cindex remote debugging support
2083 @cindex serial line support
2085 This contains serial line support for Unix systems. This is always
2086 included, via the makefile variable @code{SER_HARDWIRE}; override this
2087 variable in the @file{.mh} file to avoid it.
2090 This contains serial line support for 32-bit programs running under DOS,
2091 using the DJGPP (a.k.a.@: GO32) execution environment.
2093 @cindex TCP remote support
2095 This contains generic TCP support using sockets.
2098 @section Host Conditionals
2100 When @value{GDBN} is configured and compiled, various macros are
2101 defined or left undefined, to control compilation based on the
2102 attributes of the host system. These macros and their meanings (or if
2103 the meaning is not documented here, then one of the source files where
2104 they are used is indicated) are:
2107 @item @value{GDBN}INIT_FILENAME
2108 The default name of @value{GDBN}'s initialization file (normally
2112 This macro is deprecated.
2115 Define this if your system does not have a @code{<sys/file.h>}.
2117 @item SIGWINCH_HANDLER
2118 If your host defines @code{SIGWINCH}, you can define this to be the name
2119 of a function to be called if @code{SIGWINCH} is received.
2121 @item SIGWINCH_HANDLER_BODY
2122 Define this to expand into code that will define the function named by
2123 the expansion of @code{SIGWINCH_HANDLER}.
2125 @item ALIGN_STACK_ON_STARTUP
2126 @cindex stack alignment
2127 Define this if your system is of a sort that will crash in
2128 @code{tgetent} if the stack happens not to be longword-aligned when
2129 @code{main} is called. This is a rare situation, but is known to occur
2130 on several different types of systems.
2132 @item CRLF_SOURCE_FILES
2133 @cindex DOS text files
2134 Define this if host files use @code{\r\n} rather than @code{\n} as a
2135 line terminator. This will cause source file listings to omit @code{\r}
2136 characters when printing and it will allow @code{\r\n} line endings of files
2137 which are ``sourced'' by gdb. It must be possible to open files in binary
2138 mode using @code{O_BINARY} or, for fopen, @code{"rb"}.
2140 @item DEFAULT_PROMPT
2142 The default value of the prompt string (normally @code{"(gdb) "}).
2145 @cindex terminal device
2146 The name of the generic TTY device, defaults to @code{"/dev/tty"}.
2148 @item FCLOSE_PROVIDED
2149 Define this if the system declares @code{fclose} in the headers included
2150 in @code{defs.h}. This isn't needed unless your compiler is unusually
2154 Define this if binary files are opened the same way as text files.
2156 @item GETENV_PROVIDED
2157 Define this if the system declares @code{getenv} in its headers included
2158 in @code{defs.h}. This isn't needed unless your compiler is unusually
2163 In some cases, use the system call @code{mmap} for reading symbol
2164 tables. For some machines this allows for sharing and quick updates.
2167 Define this if the host system has @code{termio.h}.
2174 Values for host-side constants.
2177 Substitute for isatty, if not available.
2180 This is the longest integer type available on the host. If not defined,
2181 it will default to @code{long long} or @code{long}, depending on
2182 @code{CC_HAS_LONG_LONG}.
2184 @item CC_HAS_LONG_LONG
2185 @cindex @code{long long} data type
2186 Define this if the host C compiler supports @code{long long}. This is set
2187 by the @code{configure} script.
2189 @item PRINTF_HAS_LONG_LONG
2190 Define this if the host can handle printing of long long integers via
2191 the printf format conversion specifier @code{ll}. This is set by the
2192 @code{configure} script.
2194 @item HAVE_LONG_DOUBLE
2195 Define this if the host C compiler supports @code{long double}. This is
2196 set by the @code{configure} script.
2198 @item PRINTF_HAS_LONG_DOUBLE
2199 Define this if the host can handle printing of long double float-point
2200 numbers via the printf format conversion specifier @code{Lg}. This is
2201 set by the @code{configure} script.
2203 @item SCANF_HAS_LONG_DOUBLE
2204 Define this if the host can handle the parsing of long double
2205 float-point numbers via the scanf format conversion specifier
2206 @code{Lg}. This is set by the @code{configure} script.
2208 @item LSEEK_NOT_LINEAR
2209 Define this if @code{lseek (n)} does not necessarily move to byte number
2210 @code{n} in the file. This is only used when reading source files. It
2211 is normally faster to define @code{CRLF_SOURCE_FILES} when possible.
2214 This macro is used as the argument to @code{lseek} (or, most commonly,
2215 @code{bfd_seek}). FIXME, should be replaced by SEEK_SET instead,
2216 which is the POSIX equivalent.
2218 @item MALLOC_INCOMPATIBLE
2219 Define this if the system's prototype for @code{malloc} differs from the
2220 @sc{ansi} definition.
2222 @item MMAP_BASE_ADDRESS
2223 When using HAVE_MMAP, the first mapping should go at this address.
2225 @item MMAP_INCREMENT
2226 when using HAVE_MMAP, this is the increment between mappings.
2229 If defined, this should be one or more tokens, such as @code{volatile},
2230 that can be used in both the declaration and definition of functions to
2231 indicate that they never return. The default is already set correctly
2232 if compiling with GCC. This will almost never need to be defined.
2235 If defined, this should be one or more tokens, such as
2236 @code{__attribute__ ((noreturn))}, that can be used in the declarations
2237 of functions to indicate that they never return. The default is already
2238 set correctly if compiling with GCC. This will almost never need to be
2241 @item USE_GENERIC_DUMMY_FRAMES
2242 @cindex generic dummy frames
2243 Define this to 1 if the target is using the generic inferior function
2244 call code. See @code{blockframe.c} for more information.
2248 @value{GDBN} will use the @code{mmalloc} library for memory allocation
2249 for symbol reading if this symbol is defined. Be careful defining it
2250 since there are systems on which @code{mmalloc} does not work for some
2251 reason. One example is the DECstation, where its RPC library can't
2252 cope with our redefinition of @code{malloc} to call @code{mmalloc}.
2253 When defining @code{USE_MMALLOC}, you will also have to set
2254 @code{MMALLOC} in the Makefile, to point to the @code{mmalloc} library. This
2255 define is set when you configure with @samp{--with-mmalloc}.
2259 Define this if you are using @code{mmalloc}, but don't want the overhead
2260 of checking the heap with @code{mmcheck}. Note that on some systems,
2261 the C runtime makes calls to @code{malloc} prior to calling @code{main}, and if
2262 @code{free} is ever called with these pointers after calling
2263 @code{mmcheck} to enable checking, a memory corruption abort is certain
2264 to occur. These systems can still use @code{mmalloc}, but must define
2268 Define this to 1 if the C runtime allocates memory prior to
2269 @code{mmcheck} being called, but that memory is never freed so we don't
2270 have to worry about it triggering a memory corruption abort. The
2271 default is 0, which means that @code{mmcheck} will only install the heap
2272 checking functions if there has not yet been any memory allocation
2273 calls, and if it fails to install the functions, @value{GDBN} will issue a
2274 warning. This is currently defined if you configure using
2275 @samp{--with-mmalloc}.
2277 @item NO_SIGINTERRUPT
2278 @findex siginterrupt
2279 Define this to indicate that @code{siginterrupt} is not available.
2283 Define these to appropriate value for the system @code{lseek}, if not already
2287 This is the signal for stopping @value{GDBN}. Defaults to
2288 @code{SIGTSTP}. (Only redefined for the Convex.)
2291 Define this if the interior's tty should be opened with the @code{O_NOCTTY}
2292 flag. (FIXME: This should be a native-only flag, but @file{inflow.c} is
2296 Means that System V (prior to SVR4) include files are in use. (FIXME:
2297 This symbol is abused in @file{infrun.c}, @file{regex.c},
2298 @file{remote-nindy.c}, and @file{utils.c} for other things, at the
2302 Define this to help placate @code{lint} in some situations.
2305 Define this to override the defaults of @code{__volatile__} or
2310 @node Target Architecture Definition
2312 @chapter Target Architecture Definition
2314 @cindex target architecture definition
2315 @value{GDBN}'s target architecture defines what sort of
2316 machine-language programs @value{GDBN} can work with, and how it works
2319 The target architecture object is implemented as the C structure
2320 @code{struct gdbarch *}. The structure, and its methods, are generated
2321 using the Bourne shell script @file{gdbarch.sh}.
2323 @section Registers and Memory
2325 @value{GDBN}'s model of the target machine is rather simple.
2326 @value{GDBN} assumes the machine includes a bank of registers and a
2327 block of memory. Each register may have a different size.
2329 @value{GDBN} does not have a magical way to match up with the
2330 compiler's idea of which registers are which; however, it is critical
2331 that they do match up accurately. The only way to make this work is
2332 to get accurate information about the order that the compiler uses,
2333 and to reflect that in the @code{REGISTER_NAME} and related macros.
2335 @value{GDBN} can handle big-endian, little-endian, and bi-endian architectures.
2337 @section Pointers Are Not Always Addresses
2338 @cindex pointer representation
2339 @cindex address representation
2340 @cindex word-addressed machines
2341 @cindex separate data and code address spaces
2342 @cindex spaces, separate data and code address
2343 @cindex address spaces, separate data and code
2344 @cindex code pointers, word-addressed
2345 @cindex converting between pointers and addresses
2346 @cindex D10V addresses
2348 On almost all 32-bit architectures, the representation of a pointer is
2349 indistinguishable from the representation of some fixed-length number
2350 whose value is the byte address of the object pointed to. On such
2351 machines, the words ``pointer'' and ``address'' can be used interchangeably.
2352 However, architectures with smaller word sizes are often cramped for
2353 address space, so they may choose a pointer representation that breaks this
2354 identity, and allows a larger code address space.
2356 For example, the Mitsubishi D10V is a 16-bit VLIW processor whose
2357 instructions are 32 bits long@footnote{Some D10V instructions are
2358 actually pairs of 16-bit sub-instructions. However, since you can't
2359 jump into the middle of such a pair, code addresses can only refer to
2360 full 32 bit instructions, which is what matters in this explanation.}.
2361 If the D10V used ordinary byte addresses to refer to code locations,
2362 then the processor would only be able to address 64kb of instructions.
2363 However, since instructions must be aligned on four-byte boundaries, the
2364 low two bits of any valid instruction's byte address are always
2365 zero---byte addresses waste two bits. So instead of byte addresses,
2366 the D10V uses word addresses---byte addresses shifted right two bits---to
2367 refer to code. Thus, the D10V can use 16-bit words to address 256kb of
2370 However, this means that code pointers and data pointers have different
2371 forms on the D10V. The 16-bit word @code{0xC020} refers to byte address
2372 @code{0xC020} when used as a data address, but refers to byte address
2373 @code{0x30080} when used as a code address.
2375 (The D10V also uses separate code and data address spaces, which also
2376 affects the correspondence between pointers and addresses, but we're
2377 going to ignore that here; this example is already too long.)
2379 To cope with architectures like this---the D10V is not the only
2380 one!---@value{GDBN} tries to distinguish between @dfn{addresses}, which are
2381 byte numbers, and @dfn{pointers}, which are the target's representation
2382 of an address of a particular type of data. In the example above,
2383 @code{0xC020} is the pointer, which refers to one of the addresses
2384 @code{0xC020} or @code{0x30080}, depending on the type imposed upon it.
2385 @value{GDBN} provides functions for turning a pointer into an address
2386 and vice versa, in the appropriate way for the current architecture.
2388 Unfortunately, since addresses and pointers are identical on almost all
2389 processors, this distinction tends to bit-rot pretty quickly. Thus,
2390 each time you port @value{GDBN} to an architecture which does
2391 distinguish between pointers and addresses, you'll probably need to
2392 clean up some architecture-independent code.
2394 Here are functions which convert between pointers and addresses:
2396 @deftypefun CORE_ADDR extract_typed_address (void *@var{buf}, struct type *@var{type})
2397 Treat the bytes at @var{buf} as a pointer or reference of type
2398 @var{type}, and return the address it represents, in a manner
2399 appropriate for the current architecture. This yields an address
2400 @value{GDBN} can use to read target memory, disassemble, etc. Note that
2401 @var{buf} refers to a buffer in @value{GDBN}'s memory, not the
2404 For example, if the current architecture is the Intel x86, this function
2405 extracts a little-endian integer of the appropriate length from
2406 @var{buf} and returns it. However, if the current architecture is the
2407 D10V, this function will return a 16-bit integer extracted from
2408 @var{buf}, multiplied by four if @var{type} is a pointer to a function.
2410 If @var{type} is not a pointer or reference type, then this function
2411 will signal an internal error.
2414 @deftypefun CORE_ADDR store_typed_address (void *@var{buf}, struct type *@var{type}, CORE_ADDR @var{addr})
2415 Store the address @var{addr} in @var{buf}, in the proper format for a
2416 pointer of type @var{type} in the current architecture. Note that
2417 @var{buf} refers to a buffer in @value{GDBN}'s memory, not the
2420 For example, if the current architecture is the Intel x86, this function
2421 stores @var{addr} unmodified as a little-endian integer of the
2422 appropriate length in @var{buf}. However, if the current architecture
2423 is the D10V, this function divides @var{addr} by four if @var{type} is
2424 a pointer to a function, and then stores it in @var{buf}.
2426 If @var{type} is not a pointer or reference type, then this function
2427 will signal an internal error.
2430 @deftypefun CORE_ADDR value_as_address (value_ptr @var{val})
2431 Assuming that @var{val} is a pointer, return the address it represents,
2432 as appropriate for the current architecture.
2434 This function actually works on integral values, as well as pointers.
2435 For pointers, it performs architecture-specific conversions as
2436 described above for @code{extract_typed_address}.
2439 @deftypefun CORE_ADDR value_from_pointer (struct type *@var{type}, CORE_ADDR @var{addr})
2440 Create and return a value representing a pointer of type @var{type} to
2441 the address @var{addr}, as appropriate for the current architecture.
2442 This function performs architecture-specific conversions as described
2443 above for @code{store_typed_address}.
2447 @value{GDBN} also provides functions that do the same tasks, but assume
2448 that pointers are simply byte addresses; they aren't sensitive to the
2449 current architecture, beyond knowing the appropriate endianness.
2451 @deftypefun CORE_ADDR extract_address (void *@var{addr}, int len)
2452 Extract a @var{len}-byte number from @var{addr} in the appropriate
2453 endianness for the current architecture, and return it. Note that
2454 @var{addr} refers to @value{GDBN}'s memory, not the inferior's.
2456 This function should only be used in architecture-specific code; it
2457 doesn't have enough information to turn bits into a true address in the
2458 appropriate way for the current architecture. If you can, use
2459 @code{extract_typed_address} instead.
2462 @deftypefun void store_address (void *@var{addr}, int @var{len}, LONGEST @var{val})
2463 Store @var{val} at @var{addr} as a @var{len}-byte integer, in the
2464 appropriate endianness for the current architecture. Note that
2465 @var{addr} refers to a buffer in @value{GDBN}'s memory, not the
2468 This function should only be used in architecture-specific code; it
2469 doesn't have enough information to turn a true address into bits in the
2470 appropriate way for the current architecture. If you can, use
2471 @code{store_typed_address} instead.
2475 Here are some macros which architectures can define to indicate the
2476 relationship between pointers and addresses. These have default
2477 definitions, appropriate for architectures on which all pointers are
2478 simple unsigned byte addresses.
2480 @deftypefn {Target Macro} CORE_ADDR POINTER_TO_ADDRESS (struct type *@var{type}, char *@var{buf})
2481 Assume that @var{buf} holds a pointer of type @var{type}, in the
2482 appropriate format for the current architecture. Return the byte
2483 address the pointer refers to.
2485 This function may safely assume that @var{type} is either a pointer or a
2486 C@t{++} reference type.
2489 @deftypefn {Target Macro} void ADDRESS_TO_POINTER (struct type *@var{type}, char *@var{buf}, CORE_ADDR @var{addr})
2490 Store in @var{buf} a pointer of type @var{type} representing the address
2491 @var{addr}, in the appropriate format for the current architecture.
2493 This function may safely assume that @var{type} is either a pointer or a
2494 C@t{++} reference type.
2498 @section Using Different Register and Memory Data Representations
2499 @cindex raw representation
2500 @cindex virtual representation
2501 @cindex representations, raw and virtual
2502 @cindex register data formats, converting
2503 @cindex @code{struct value}, converting register contents to
2505 @emph{Maintainer's note: The way GDB manipulates registers is undergoing
2506 significant change. Many of the macros and functions refered to in the
2507 sections below are likely to be made obsolete. See the file @file{TODO}
2508 for more up-to-date information.}
2510 Some architectures use one representation for a value when it lives in a
2511 register, but use a different representation when it lives in memory.
2512 In @value{GDBN}'s terminology, the @dfn{raw} representation is the one used in
2513 the target registers, and the @dfn{virtual} representation is the one
2514 used in memory, and within @value{GDBN} @code{struct value} objects.
2516 For almost all data types on almost all architectures, the virtual and
2517 raw representations are identical, and no special handling is needed.
2518 However, they do occasionally differ. For example:
2522 The x86 architecture supports an 80-bit @code{long double} type. However, when
2523 we store those values in memory, they occupy twelve bytes: the
2524 floating-point number occupies the first ten, and the final two bytes
2525 are unused. This keeps the values aligned on four-byte boundaries,
2526 allowing more efficient access. Thus, the x86 80-bit floating-point
2527 type is the raw representation, and the twelve-byte loosely-packed
2528 arrangement is the virtual representation.
2531 Some 64-bit MIPS targets present 32-bit registers to @value{GDBN} as 64-bit
2532 registers, with garbage in their upper bits. @value{GDBN} ignores the top 32
2533 bits. Thus, the 64-bit form, with garbage in the upper 32 bits, is the
2534 raw representation, and the trimmed 32-bit representation is the
2535 virtual representation.
2538 In general, the raw representation is determined by the architecture, or
2539 @value{GDBN}'s interface to the architecture, while the virtual representation
2540 can be chosen for @value{GDBN}'s convenience. @value{GDBN}'s register file,
2541 @code{registers}, holds the register contents in raw format, and the
2542 @value{GDBN} remote protocol transmits register values in raw format.
2544 Your architecture may define the following macros to request
2545 conversions between the raw and virtual format:
2547 @deftypefn {Target Macro} int REGISTER_CONVERTIBLE (int @var{reg})
2548 Return non-zero if register number @var{reg}'s value needs different raw
2549 and virtual formats.
2551 You should not use @code{REGISTER_CONVERT_TO_VIRTUAL} for a register
2552 unless this macro returns a non-zero value for that register.
2555 @deftypefn {Target Macro} int REGISTER_RAW_SIZE (int @var{reg})
2556 The size of register number @var{reg}'s raw value. This is the number
2557 of bytes the register will occupy in @code{registers}, or in a @value{GDBN}
2558 remote protocol packet.
2561 @deftypefn {Target Macro} int REGISTER_VIRTUAL_SIZE (int @var{reg})
2562 The size of register number @var{reg}'s value, in its virtual format.
2563 This is the size a @code{struct value}'s buffer will have, holding that
2567 @deftypefn {Target Macro} struct type *REGISTER_VIRTUAL_TYPE (int @var{reg})
2568 This is the type of the virtual representation of register number
2569 @var{reg}. Note that there is no need for a macro giving a type for the
2570 register's raw form; once the register's value has been obtained, @value{GDBN}
2571 always uses the virtual form.
2574 @deftypefn {Target Macro} void REGISTER_CONVERT_TO_VIRTUAL (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to})
2575 Convert the value of register number @var{reg} to @var{type}, which
2576 should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
2577 at @var{from} holds the register's value in raw format; the macro should
2578 convert the value to virtual format, and place it at @var{to}.
2580 Note that @code{REGISTER_CONVERT_TO_VIRTUAL} and
2581 @code{REGISTER_CONVERT_TO_RAW} take their @var{reg} and @var{type}
2582 arguments in different orders.
2584 You should only use @code{REGISTER_CONVERT_TO_VIRTUAL} with registers
2585 for which the @code{REGISTER_CONVERTIBLE} macro returns a non-zero
2589 @deftypefn {Target Macro} void REGISTER_CONVERT_TO_RAW (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to})
2590 Convert the value of register number @var{reg} to @var{type}, which
2591 should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer
2592 at @var{from} holds the register's value in raw format; the macro should
2593 convert the value to virtual format, and place it at @var{to}.
2595 Note that REGISTER_CONVERT_TO_VIRTUAL and REGISTER_CONVERT_TO_RAW take
2596 their @var{reg} and @var{type} arguments in different orders.
2600 @section Frame Interpretation
2602 @section Inferior Call Setup
2604 @section Compiler Characteristics
2606 @section Target Conditionals
2608 This section describes the macros that you can use to define the target
2613 @item ADDITIONAL_OPTIONS
2614 @itemx ADDITIONAL_OPTION_CASES
2615 @itemx ADDITIONAL_OPTION_HANDLER
2616 @itemx ADDITIONAL_OPTION_HELP
2617 @findex ADDITIONAL_OPTION_HELP
2618 @findex ADDITIONAL_OPTION_HANDLER
2619 @findex ADDITIONAL_OPTION_CASES
2620 @findex ADDITIONAL_OPTIONS
2621 These are a set of macros that allow the addition of additional command
2622 line options to @value{GDBN}. They are currently used only for the unsupported
2623 i960 Nindy target, and should not be used in any other configuration.
2625 @item ADDR_BITS_REMOVE (addr)
2626 @findex ADDR_BITS_REMOVE
2627 If a raw machine instruction address includes any bits that are not
2628 really part of the address, then define this macro to expand into an
2629 expression that zeroes those bits in @var{addr}. This is only used for
2630 addresses of instructions, and even then not in all contexts.
2632 For example, the two low-order bits of the PC on the Hewlett-Packard PA
2633 2.0 architecture contain the privilege level of the corresponding
2634 instruction. Since instructions must always be aligned on four-byte
2635 boundaries, the processor masks out these bits to generate the actual
2636 address of the instruction. ADDR_BITS_REMOVE should filter out these
2637 bits with an expression such as @code{((addr) & ~3)}.
2639 @item ADDRESS_TO_POINTER (@var{type}, @var{buf}, @var{addr})
2640 @findex ADDRESS_TO_POINTER
2641 Store in @var{buf} a pointer of type @var{type} representing the address
2642 @var{addr}, in the appropriate format for the current architecture.
2643 This macro may safely assume that @var{type} is either a pointer or a
2644 C@t{++} reference type.
2645 @xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
2647 @item BEFORE_MAIN_LOOP_HOOK
2648 @findex BEFORE_MAIN_LOOP_HOOK
2649 Define this to expand into any code that you want to execute before the
2650 main loop starts. Although this is not, strictly speaking, a target
2651 conditional, that is how it is currently being used. Note that if a
2652 configuration were to define it one way for a host and a different way
2653 for the target, @value{GDBN} will probably not compile, let alone run
2654 correctly. This macro is currently used only for the unsupported i960 Nindy
2655 target, and should not be used in any other configuration.
2657 @item BELIEVE_PCC_PROMOTION
2658 @findex BELIEVE_PCC_PROMOTION
2659 Define if the compiler promotes a @code{short} or @code{char}
2660 parameter to an @code{int}, but still reports the parameter as its
2661 original type, rather than the promoted type.
2663 @item BELIEVE_PCC_PROMOTION_TYPE
2664 @findex BELIEVE_PCC_PROMOTION_TYPE
2665 Define this if @value{GDBN} should believe the type of a @code{short}
2666 argument when compiled by @code{pcc}, but look within a full int space to get
2667 its value. Only defined for Sun-3 at present.
2669 @item BITS_BIG_ENDIAN
2670 @findex BITS_BIG_ENDIAN
2671 Define this if the numbering of bits in the targets does @strong{not} match the
2672 endianness of the target byte order. A value of 1 means that the bits
2673 are numbered in a big-endian bit order, 0 means little-endian.
2677 This is the character array initializer for the bit pattern to put into
2678 memory where a breakpoint is set. Although it's common to use a trap
2679 instruction for a breakpoint, it's not required; for instance, the bit
2680 pattern could be an invalid instruction. The breakpoint must be no
2681 longer than the shortest instruction of the architecture.
2683 @code{BREAKPOINT} has been deprecated in favor of
2684 @code{BREAKPOINT_FROM_PC}.
2686 @item BIG_BREAKPOINT
2687 @itemx LITTLE_BREAKPOINT
2688 @findex LITTLE_BREAKPOINT
2689 @findex BIG_BREAKPOINT
2690 Similar to BREAKPOINT, but used for bi-endian targets.
2692 @code{BIG_BREAKPOINT} and @code{LITTLE_BREAKPOINT} have been deprecated in
2693 favor of @code{BREAKPOINT_FROM_PC}.
2695 @item REMOTE_BREAKPOINT
2696 @itemx LITTLE_REMOTE_BREAKPOINT
2697 @itemx BIG_REMOTE_BREAKPOINT
2698 @findex BIG_REMOTE_BREAKPOINT
2699 @findex LITTLE_REMOTE_BREAKPOINT
2700 @findex REMOTE_BREAKPOINT
2701 Similar to BREAKPOINT, but used for remote targets.
2703 @code{BIG_REMOTE_BREAKPOINT} and @code{LITTLE_REMOTE_BREAKPOINT} have been
2704 deprecated in favor of @code{BREAKPOINT_FROM_PC}.
2706 @item BREAKPOINT_FROM_PC (@var{pcptr}, @var{lenptr})
2707 @findex BREAKPOINT_FROM_PC
2708 Use the program counter to determine the contents and size of a
2709 breakpoint instruction. It returns a pointer to a string of bytes
2710 that encode a breakpoint instruction, stores the length of the string
2711 to *@var{lenptr}, and adjusts pc (if necessary) to point to the actual
2712 memory location where the breakpoint should be inserted.
2714 Although it is common to use a trap instruction for a breakpoint, it's
2715 not required; for instance, the bit pattern could be an invalid
2716 instruction. The breakpoint must be no longer than the shortest
2717 instruction of the architecture.
2719 Replaces all the other @var{BREAKPOINT} macros.
2721 @item MEMORY_INSERT_BREAKPOINT (@var{addr}, @var{contents_cache})
2722 @itemx MEMORY_REMOVE_BREAKPOINT (@var{addr}, @var{contents_cache})
2723 @findex MEMORY_REMOVE_BREAKPOINT
2724 @findex MEMORY_INSERT_BREAKPOINT
2725 Insert or remove memory based breakpoints. Reasonable defaults
2726 (@code{default_memory_insert_breakpoint} and
2727 @code{default_memory_remove_breakpoint} respectively) have been
2728 provided so that it is not necessary to define these for most
2729 architectures. Architectures which may want to define
2730 @code{MEMORY_INSERT_BREAKPOINT} and @code{MEMORY_REMOVE_BREAKPOINT} will
2731 likely have instructions that are oddly sized or are not stored in a
2732 conventional manner.
2734 It may also be desirable (from an efficiency standpoint) to define
2735 custom breakpoint insertion and removal routines if
2736 @code{BREAKPOINT_FROM_PC} needs to read the target's memory for some
2740 @findex CALL_DUMMY_P
2741 A C expresson that is non-zero when the target suports inferior function
2744 @item CALL_DUMMY_WORDS
2745 @findex CALL_DUMMY_WORDS
2746 Pointer to an array of @code{LONGEST} words of data containing
2747 host-byte-ordered @code{REGISTER_BYTES} sized values that partially
2748 specify the sequence of instructions needed for an inferior function
2751 Should be deprecated in favor of a macro that uses target-byte-ordered
2754 @item SIZEOF_CALL_DUMMY_WORDS
2755 @findex SIZEOF_CALL_DUMMY_WORDS
2756 The size of @code{CALL_DUMMY_WORDS}. When @code{CALL_DUMMY_P} this must
2757 return a positive value. See also @code{CALL_DUMMY_LENGTH}.
2761 A static initializer for @code{CALL_DUMMY_WORDS}. Deprecated.
2763 @item CALL_DUMMY_LOCATION
2764 @findex CALL_DUMMY_LOCATION
2765 See the file @file{inferior.h}.
2767 @item CALL_DUMMY_STACK_ADJUST
2768 @findex CALL_DUMMY_STACK_ADJUST
2769 Stack adjustment needed when performing an inferior function call.
2771 Should be deprecated in favor of something like @code{STACK_ALIGN}.
2773 @item CALL_DUMMY_STACK_ADJUST_P
2774 @findex CALL_DUMMY_STACK_ADJUST_P
2775 Predicate for use of @code{CALL_DUMMY_STACK_ADJUST}.
2777 Should be deprecated in favor of something like @code{STACK_ALIGN}.
2779 @item CANNOT_FETCH_REGISTER (@var{regno})
2780 @findex CANNOT_FETCH_REGISTER
2781 A C expression that should be nonzero if @var{regno} cannot be fetched
2782 from an inferior process. This is only relevant if
2783 @code{FETCH_INFERIOR_REGISTERS} is not defined.
2785 @item CANNOT_STORE_REGISTER (@var{regno})
2786 @findex CANNOT_STORE_REGISTER
2787 A C expression that should be nonzero if @var{regno} should not be
2788 written to the target. This is often the case for program counters,
2789 status words, and other special registers. If this is not defined,
2790 @value{GDBN} will assume that all registers may be written.
2792 @item DO_DEFERRED_STORES
2793 @itemx CLEAR_DEFERRED_STORES
2794 @findex CLEAR_DEFERRED_STORES
2795 @findex DO_DEFERRED_STORES
2796 Define this to execute any deferred stores of registers into the inferior,
2797 and to cancel any deferred stores.
2799 Currently only implemented correctly for native Sparc configurations?
2801 @item COERCE_FLOAT_TO_DOUBLE (@var{formal}, @var{actual})
2802 @findex COERCE_FLOAT_TO_DOUBLE
2803 @cindex promotion to @code{double}
2804 @cindex @code{float} arguments
2805 @cindex prototyped functions, passing arguments to
2806 @cindex passing arguments to prototyped functions
2807 Return non-zero if GDB should promote @code{float} values to
2808 @code{double} when calling a non-prototyped function. The argument
2809 @var{actual} is the type of the value we want to pass to the function.
2810 The argument @var{formal} is the type of this argument, as it appears in
2811 the function's definition. Note that @var{formal} may be zero if we
2812 have no debugging information for the function, or if we're passing more
2813 arguments than are officially declared (for example, varargs). This
2814 macro is never invoked if the function definitely has a prototype.
2816 How you should pass arguments to a function depends on whether it was
2817 defined in K&R style or prototype style. If you define a function using
2818 the K&R syntax that takes a @code{float} argument, then callers must
2819 pass that argument as a @code{double}. If you define the function using
2820 the prototype syntax, then you must pass the argument as a @code{float},
2823 Unfortunately, on certain older platforms, the debug info doesn't
2824 indicate reliably how each function was defined. A function type's
2825 @code{TYPE_FLAG_PROTOTYPED} flag may be unset, even if the function was
2826 defined in prototype style. When calling a function whose
2827 @code{TYPE_FLAG_PROTOTYPED} flag is unset, GDB consults the
2828 @code{COERCE_FLOAT_TO_DOUBLE} macro to decide what to do.
2830 @findex standard_coerce_float_to_double
2831 For modern targets, it is proper to assume that, if the prototype flag
2832 is unset, that can be trusted: @code{float} arguments should be promoted
2833 to @code{double}. You should use the function
2834 @code{standard_coerce_float_to_double} to get this behavior.
2836 @findex default_coerce_float_to_double
2837 For some older targets, if the prototype flag is unset, that doesn't
2838 tell us anything. So we guess that, if we don't have a type for the
2839 formal parameter (@i{i.e.}, the first argument to
2840 @code{COERCE_FLOAT_TO_DOUBLE} is null), then we should promote it;
2841 otherwise, we should leave it alone. The function
2842 @code{default_coerce_float_to_double} provides this behavior; it is the
2843 default value, for compatibility with older configurations.
2846 @findex CPLUS_MARKERz
2847 Define this to expand into the character that G@t{++} uses to distinguish
2848 compiler-generated identifiers from programmer-specified identifiers.
2849 By default, this expands into @code{'$'}. Most System V targets should
2850 define this to @code{'.'}.
2852 @item DBX_PARM_SYMBOL_CLASS
2853 @findex DBX_PARM_SYMBOL_CLASS
2854 Hook for the @code{SYMBOL_CLASS} of a parameter when decoding DBX symbol
2855 information. In the i960, parameters can be stored as locals or as
2856 args, depending on the type of the debug record.
2858 @item DECR_PC_AFTER_BREAK
2859 @findex DECR_PC_AFTER_BREAK
2860 Define this to be the amount by which to decrement the PC after the
2861 program encounters a breakpoint. This is often the number of bytes in
2862 @code{BREAKPOINT}, though not always. For most targets this value will be 0.
2864 @item DECR_PC_AFTER_HW_BREAK
2865 @findex DECR_PC_AFTER_HW_BREAK
2866 Similarly, for hardware breakpoints.
2868 @item DISABLE_UNSETTABLE_BREAK (@var{addr})
2869 @findex DISABLE_UNSETTABLE_BREAK
2870 If defined, this should evaluate to 1 if @var{addr} is in a shared
2871 library in which breakpoints cannot be set and so should be disabled.
2873 @item DO_REGISTERS_INFO
2874 @findex DO_REGISTERS_INFO
2875 If defined, use this to print the value of a register or all registers.
2877 @item DWARF_REG_TO_REGNUM
2878 @findex DWARF_REG_TO_REGNUM
2879 Convert DWARF register number into @value{GDBN} regnum. If not defined,
2880 no conversion will be performed.
2882 @item DWARF2_REG_TO_REGNUM
2883 @findex DWARF2_REG_TO_REGNUM
2884 Convert DWARF2 register number into @value{GDBN} regnum. If not
2885 defined, no conversion will be performed.
2887 @item ECOFF_REG_TO_REGNUM
2888 @findex ECOFF_REG_TO_REGNUM
2889 Convert ECOFF register number into @value{GDBN} regnum. If not defined,
2890 no conversion will be performed.
2892 @item END_OF_TEXT_DEFAULT
2893 @findex END_OF_TEXT_DEFAULT
2894 This is an expression that should designate the end of the text section.
2897 @item EXTRACT_RETURN_VALUE(@var{type}, @var{regbuf}, @var{valbuf})
2898 @findex EXTRACT_RETURN_VALUE
2899 Define this to extract a function's return value of type @var{type} from
2900 the raw register state @var{regbuf} and copy that, in virtual format,
2903 @item EXTRACT_STRUCT_VALUE_ADDRESS(@var{regbuf})
2904 @findex EXTRACT_STRUCT_VALUE_ADDRESS
2905 When defined, extract from the array @var{regbuf} (containing the raw
2906 register state) the @code{CORE_ADDR} at which a function should return
2907 its structure value.
2909 If not defined, @code{EXTRACT_RETURN_VALUE} is used.
2911 @item EXTRACT_STRUCT_VALUE_ADDRESS_P()
2912 @findex EXTRACT_STRUCT_VALUE_ADDRESS_P
2913 Predicate for @code{EXTRACT_STRUCT_VALUE_ADDRESS}.
2917 If defined, then the @samp{info float} command will print information about
2918 the processor's floating point unit.
2922 If the virtual frame pointer is kept in a register, then define this
2923 macro to be the number (greater than or equal to zero) of that register.
2925 This should only need to be defined if @code{TARGET_READ_FP} and
2926 @code{TARGET_WRITE_FP} are not defined.
2928 @item FRAMELESS_FUNCTION_INVOCATION(@var{fi})
2929 @findex FRAMELESS_FUNCTION_INVOCATION
2930 Define this to an expression that returns 1 if the function invocation
2931 represented by @var{fi} does not have a stack frame associated with it.
2934 @item FRAME_ARGS_ADDRESS_CORRECT
2935 @findex FRAME_ARGS_ADDRESS_CORRECT
2938 @item FRAME_CHAIN(@var{frame})
2940 Given @var{frame}, return a pointer to the calling frame.
2942 @item FRAME_CHAIN_COMBINE(@var{chain}, @var{frame})
2943 @findex FRAME_CHAIN_COMBINE
2944 Define this to take the frame chain pointer and the frame's nominal
2945 address and produce the nominal address of the caller's frame.
2946 Presently only defined for HP PA.
2948 @item FRAME_CHAIN_VALID(@var{chain}, @var{thisframe})
2949 @findex FRAME_CHAIN_VALID
2950 Define this to be an expression that returns zero if the given frame is
2951 an outermost frame, with no caller, and nonzero otherwise. Several
2952 common definitions are available:
2956 @code{file_frame_chain_valid} is nonzero if the chain pointer is nonzero
2957 and given frame's PC is not inside the startup file (such as
2961 @code{func_frame_chain_valid} is nonzero if the chain
2962 pointer is nonzero and the given frame's PC is not in @code{main} or a
2963 known entry point function (such as @code{_start}).
2966 @code{generic_file_frame_chain_valid} and
2967 @code{generic_func_frame_chain_valid} are equivalent implementations for
2968 targets using generic dummy frames.
2971 @item FRAME_INIT_SAVED_REGS(@var{frame})
2972 @findex FRAME_INIT_SAVED_REGS
2973 See @file{frame.h}. Determines the address of all registers in the
2974 current stack frame storing each in @code{frame->saved_regs}. Space for
2975 @code{frame->saved_regs} shall be allocated by
2976 @code{FRAME_INIT_SAVED_REGS} using either
2977 @code{frame_saved_regs_zalloc} or @code{frame_obstack_alloc}.
2979 @code{FRAME_FIND_SAVED_REGS} and @code{EXTRA_FRAME_INFO} are deprecated.
2981 @item FRAME_NUM_ARGS (@var{fi})
2982 @findex FRAME_NUM_ARGS
2983 For the frame described by @var{fi} return the number of arguments that
2984 are being passed. If the number of arguments is not known, return
2987 @item FRAME_SAVED_PC(@var{frame})
2988 @findex FRAME_SAVED_PC
2989 Given @var{frame}, return the pc saved there. This is the return
2992 @item FUNCTION_EPILOGUE_SIZE
2993 @findex FUNCTION_EPILOGUE_SIZE
2994 For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the
2995 function end symbol is 0. For such targets, you must define
2996 @code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a
2997 function's epilogue.
2999 @item FUNCTION_START_OFFSET
3000 @findex FUNCTION_START_OFFSET
3001 An integer, giving the offset in bytes from a function's address (as
3002 used in the values of symbols, function pointers, etc.), and the
3003 function's first genuine instruction.
3005 This is zero on almost all machines: the function's address is usually
3006 the address of its first instruction. However, on the VAX, for example,
3007 each function starts with two bytes containing a bitmask indicating
3008 which registers to save upon entry to the function. The VAX @code{call}
3009 instructions check this value, and save the appropriate registers
3010 automatically. Thus, since the offset from the function's address to
3011 its first instruction is two bytes, @code{FUNCTION_START_OFFSET} would
3014 @item GCC_COMPILED_FLAG_SYMBOL
3015 @itemx GCC2_COMPILED_FLAG_SYMBOL
3016 @findex GCC2_COMPILED_FLAG_SYMBOL
3017 @findex GCC_COMPILED_FLAG_SYMBOL
3018 If defined, these are the names of the symbols that @value{GDBN} will
3019 look for to detect that GCC compiled the file. The default symbols
3020 are @code{gcc_compiled.} and @code{gcc2_compiled.},
3021 respectively. (Currently only defined for the Delta 68.)
3023 @item @value{GDBN}_MULTI_ARCH
3024 @findex @value{GDBN}_MULTI_ARCH
3025 If defined and non-zero, enables suport for multiple architectures
3026 within @value{GDBN}.
3028 This support can be enabled at two levels. At level one, only
3029 definitions for previously undefined macros are provided; at level two,
3030 a multi-arch definition of all architecture dependant macros will be
3033 @item @value{GDBN}_TARGET_IS_HPPA
3034 @findex @value{GDBN}_TARGET_IS_HPPA
3035 This determines whether horrible kludge code in @file{dbxread.c} and
3036 @file{partial-stab.h} is used to mangle multiple-symbol-table files from
3037 HPPA's. This should all be ripped out, and a scheme like @file{elfread.c}
3040 @item GET_LONGJMP_TARGET
3041 @findex GET_LONGJMP_TARGET
3042 For most machines, this is a target-dependent parameter. On the
3043 DECstation and the Iris, this is a native-dependent parameter, since
3044 trhe header file @file{setjmp.h} is needed to define it.
3046 This macro determines the target PC address that @code{longjmp} will jump to,
3047 assuming that we have just stopped at a @code{longjmp} breakpoint. It takes a
3048 @code{CORE_ADDR *} as argument, and stores the target PC value through this
3049 pointer. It examines the current state of the machine as needed.
3051 @item GET_SAVED_REGISTER
3052 @findex GET_SAVED_REGISTER
3053 @findex get_saved_register
3054 Define this if you need to supply your own definition for the function
3055 @code{get_saved_register}.
3057 @item HAVE_REGISTER_WINDOWS
3058 @findex HAVE_REGISTER_WINDOWS
3059 Define this if the target has register windows.
3061 @item REGISTER_IN_WINDOW_P (@var{regnum})
3062 @findex REGISTER_IN_WINDOW_P
3063 Define this to be an expression that is 1 if the given register is in
3066 @item IBM6000_TARGET
3067 @findex IBM6000_TARGET
3068 Shows that we are configured for an IBM RS/6000 target. This
3069 conditional should be eliminated (FIXME) and replaced by
3070 feature-specific macros. It was introduced in a haste and we are
3071 repenting at leisure.
3073 @item I386_USE_GENERIC_WATCHPOINTS
3074 An x86-based target can define this to use the generic x86 watchpoint
3075 support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}.
3077 @item SYMBOLS_CAN_START_WITH_DOLLAR
3078 @findex SYMBOLS_CAN_START_WITH_DOLLAR
3079 Some systems have routines whose names start with @samp{$}. Giving this
3080 macro a non-zero value tells @value{GDBN}'s expression parser to check for such
3081 routines when parsing tokens that begin with @samp{$}.
3083 On HP-UX, certain system routines (millicode) have names beginning with
3084 @samp{$} or @samp{$$}. For example, @code{$$dyncall} is a millicode
3085 routine that handles inter-space procedure calls on PA-RISC.
3089 Define this if the target system uses IEEE-format floating point numbers.
3091 @item INIT_EXTRA_FRAME_INFO (@var{fromleaf}, @var{frame})
3092 @findex INIT_EXTRA_FRAME_INFO
3093 If additional information about the frame is required this should be
3094 stored in @code{frame->extra_info}. Space for @code{frame->extra_info}
3095 is allocated using @code{frame_obstack_alloc}.
3097 @item INIT_FRAME_PC (@var{fromleaf}, @var{prev})
3098 @findex INIT_FRAME_PC
3099 This is a C statement that sets the pc of the frame pointed to by
3100 @var{prev}. [By default...]
3102 @item INNER_THAN (@var{lhs}, @var{rhs})
3104 Returns non-zero if stack address @var{lhs} is inner than (nearer to the
3105 stack top) stack address @var{rhs}. Define this as @code{lhs < rhs} if
3106 the target's stack grows downward in memory, or @code{lhs > rsh} if the
3109 @item gdbarch_in_function_epilogue_p (@var{gdbarch}, @var{pc})
3110 @findex gdbarch_in_function_epilogue_p
3111 Returns non-zero if the given @var{pc} is in the epilogue of a function.
3112 The epilogue of a function is defined as the part of a function where
3113 the stack frame of the function already has been destroyed up to the
3114 final `return from function call' instruction.
3116 @item IN_SIGTRAMP (@var{pc}, @var{name})
3118 Define this to return non-zero if the given @var{pc} and/or @var{name}
3119 indicates that the current function is a @code{sigtramp}.
3121 @item SIGTRAMP_START (@var{pc})
3122 @findex SIGTRAMP_START
3123 @itemx SIGTRAMP_END (@var{pc})
3124 @findex SIGTRAMP_END
3125 Define these to be the start and end address of the @code{sigtramp} for the
3126 given @var{pc}. On machines where the address is just a compile time
3127 constant, the macro expansion will typically just ignore the supplied
3130 @item IN_SOLIB_CALL_TRAMPOLINE (@var{pc}, @var{name})
3131 @findex IN_SOLIB_CALL_TRAMPOLINE
3132 Define this to evaluate to nonzero if the program is stopped in the
3133 trampoline that connects to a shared library.
3135 @item IN_SOLIB_RETURN_TRAMPOLINE (@var{pc}, @var{name})
3136 @findex IN_SOLIB_RETURN_TRAMPOLINE
3137 Define this to evaluate to nonzero if the program is stopped in the
3138 trampoline that returns from a shared library.
3140 @item IN_SOLIB_DYNSYM_RESOLVE_CODE (@var{pc})
3141 @findex IN_SOLIB_DYNSYM_RESOLVE_CODE
3142 Define this to evaluate to nonzero if the program is stopped in the
3145 @item SKIP_SOLIB_RESOLVER (@var{pc})
3146 @findex SKIP_SOLIB_RESOLVER
3147 Define this to evaluate to the (nonzero) address at which execution
3148 should continue to get past the dynamic linker's symbol resolution
3149 function. A zero value indicates that it is not important or necessary
3150 to set a breakpoint to get through the dynamic linker and that single
3151 stepping will suffice.
3153 @item INTEGER_TO_ADDRESS (@var{type}, @var{buf})
3154 @findex INTEGER_TO_ADDRESS
3155 @cindex converting integers to addresses
3156 Define this when the architecture needs to handle non-pointer to address
3157 conversions specially. Converts that value to an address according to
3158 the current architectures conventions.
3160 @emph{Pragmatics: When the user copies a well defined expression from
3161 their source code and passes it, as a parameter, to @value{GDBN}'s
3162 @code{print} command, they should get the same value as would have been
3163 computed by the target program. Any deviation from this rule can cause
3164 major confusion and annoyance, and needs to be justified carefully. In
3165 other words, @value{GDBN} doesn't really have the freedom to do these
3166 conversions in clever and useful ways. It has, however, been pointed
3167 out that users aren't complaining about how @value{GDBN} casts integers
3168 to pointers; they are complaining that they can't take an address from a
3169 disassembly listing and give it to @code{x/i}. Adding an architecture
3170 method like @code{INTEGER_TO_ADDRESS} certainly makes it possible for
3171 @value{GDBN} to ``get it right'' in all circumstances.}
3173 @xref{Target Architecture Definition, , Pointers Are Not Always
3176 @item IS_TRAPPED_INTERNALVAR (@var{name})
3177 @findex IS_TRAPPED_INTERNALVAR
3178 This is an ugly hook to allow the specification of special actions that
3179 should occur as a side-effect of setting the value of a variable
3180 internal to @value{GDBN}. Currently only used by the h8500. Note that this
3181 could be either a host or target conditional.
3183 @item NEED_TEXT_START_END
3184 @findex NEED_TEXT_START_END
3185 Define this if @value{GDBN} should determine the start and end addresses of the
3186 text section. (Seems dubious.)
3188 @item NO_HIF_SUPPORT
3189 @findex NO_HIF_SUPPORT
3190 (Specific to the a29k.)
3192 @item POINTER_TO_ADDRESS (@var{type}, @var{buf})
3193 @findex POINTER_TO_ADDRESS
3194 Assume that @var{buf} holds a pointer of type @var{type}, in the
3195 appropriate format for the current architecture. Return the byte
3196 address the pointer refers to.
3197 @xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.
3199 @item REGISTER_CONVERTIBLE (@var{reg})
3200 @findex REGISTER_CONVERTIBLE
3201 Return non-zero if @var{reg} uses different raw and virtual formats.
3202 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
3204 @item REGISTER_RAW_SIZE (@var{reg})
3205 @findex REGISTER_RAW_SIZE
3206 Return the raw size of @var{reg}.
3207 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
3209 @item REGISTER_VIRTUAL_SIZE (@var{reg})
3210 @findex REGISTER_VIRTUAL_SIZE
3211 Return the virtual size of @var{reg}.
3212 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
3214 @item REGISTER_VIRTUAL_TYPE (@var{reg})
3215 @findex REGISTER_VIRTUAL_TYPE
3216 Return the virtual type of @var{reg}.
3217 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
3219 @item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to})
3220 @findex REGISTER_CONVERT_TO_VIRTUAL
3221 Convert the value of register @var{reg} from its raw form to its virtual
3223 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
3225 @item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to})
3226 @findex REGISTER_CONVERT_TO_RAW
3227 Convert the value of register @var{reg} from its virtual form to its raw
3229 @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
3231 @item RETURN_VALUE_ON_STACK(@var{type})
3232 @findex RETURN_VALUE_ON_STACK
3233 @cindex returning structures by value
3234 @cindex structures, returning by value
3236 Return non-zero if values of type TYPE are returned on the stack, using
3237 the ``struct convention'' (i.e., the caller provides a pointer to a
3238 buffer in which the callee should store the return value). This
3239 controls how the @samp{finish} command finds a function's return value,
3240 and whether an inferior function call reserves space on the stack for
3243 The full logic @value{GDBN} uses here is kind of odd.
3247 If the type being returned by value is not a structure, union, or array,
3248 and @code{RETURN_VALUE_ON_STACK} returns zero, then @value{GDBN}
3249 concludes the value is not returned using the struct convention.
3252 Otherwise, @value{GDBN} calls @code{USE_STRUCT_CONVENTION} (see below).
3253 If that returns non-zero, @value{GDBN} assumes the struct convention is
3257 In other words, to indicate that a given type is returned by value using
3258 the struct convention, that type must be either a struct, union, array,
3259 or something @code{RETURN_VALUE_ON_STACK} likes, @emph{and} something
3260 that @code{USE_STRUCT_CONVENTION} likes.
3262 Note that, in C and C@t{++}, arrays are never returned by value. In those
3263 languages, these predicates will always see a pointer type, never an
3264 array type. All the references above to arrays being returned by value
3265 apply only to other languages.
3267 @item SOFTWARE_SINGLE_STEP_P()
3268 @findex SOFTWARE_SINGLE_STEP_P
3269 Define this as 1 if the target does not have a hardware single-step
3270 mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined.
3272 @item SOFTWARE_SINGLE_STEP(@var{signal}, @var{insert_breapoints_p})
3273 @findex SOFTWARE_SINGLE_STEP
3274 A function that inserts or removes (depending on
3275 @var{insert_breapoints_p}) breakpoints at each possible destinations of
3276 the next instruction. See @file{sparc-tdep.c} and @file{rs6000-tdep.c}
3279 @item SOFUN_ADDRESS_MAYBE_MISSING
3280 @findex SOFUN_ADDRESS_MAYBE_MISSING
3281 Somebody clever observed that, the more actual addresses you have in the
3282 debug information, the more time the linker has to spend relocating
3283 them. So whenever there's some other way the debugger could find the
3284 address it needs, you should omit it from the debug info, to make
3287 @code{SOFUN_ADDRESS_MAYBE_MISSING} indicates that a particular set of
3288 hacks of this sort are in use, affecting @code{N_SO} and @code{N_FUN}
3289 entries in stabs-format debugging information. @code{N_SO} stabs mark
3290 the beginning and ending addresses of compilation units in the text
3291 segment. @code{N_FUN} stabs mark the starts and ends of functions.
3293 @code{SOFUN_ADDRESS_MAYBE_MISSING} means two things:
3297 @code{N_FUN} stabs have an address of zero. Instead, you should find the
3298 addresses where the function starts by taking the function name from
3299 the stab, and then looking that up in the minsyms (the
3300 linker/assembler symbol table). In other words, the stab has the
3301 name, and the linker/assembler symbol table is the only place that carries
3305 @code{N_SO} stabs have an address of zero, too. You just look at the
3306 @code{N_FUN} stabs that appear before and after the @code{N_SO} stab,
3307 and guess the starting and ending addresses of the compilation unit from
3311 @item PCC_SOL_BROKEN
3312 @findex PCC_SOL_BROKEN
3313 (Used only in the Convex target.)
3315 @item PC_IN_CALL_DUMMY
3316 @findex PC_IN_CALL_DUMMY
3317 See @file{inferior.h}.
3319 @item PC_LOAD_SEGMENT
3320 @findex PC_LOAD_SEGMENT
3321 If defined, print information about the load segment for the program
3322 counter. (Defined only for the RS/6000.)
3326 If the program counter is kept in a register, then define this macro to
3327 be the number (greater than or equal to zero) of that register.
3329 This should only need to be defined if @code{TARGET_READ_PC} and
3330 @code{TARGET_WRITE_PC} are not defined.
3334 The number of the ``next program counter'' register, if defined.
3338 The number of the ``next next program counter'' register, if defined.
3339 Currently, this is only defined for the Motorola 88K.
3342 @findex PARM_BOUNDARY
3343 If non-zero, round arguments to a boundary of this many bits before
3344 pushing them on the stack.
3346 @item PRINT_REGISTER_HOOK (@var{regno})
3347 @findex PRINT_REGISTER_HOOK
3348 If defined, this must be a function that prints the contents of the
3349 given register to standard output.
3351 @item PRINT_TYPELESS_INTEGER
3352 @findex PRINT_TYPELESS_INTEGER
3353 This is an obscure substitute for @code{print_longest} that seems to
3354 have been defined for the Convex target.
3356 @item PROCESS_LINENUMBER_HOOK
3357 @findex PROCESS_LINENUMBER_HOOK
3358 A hook defined for XCOFF reading.
3360 @item PROLOGUE_FIRSTLINE_OVERLAP
3361 @findex PROLOGUE_FIRSTLINE_OVERLAP
3362 (Only used in unsupported Convex configuration.)
3366 If defined, this is the number of the processor status register. (This
3367 definition is only used in generic code when parsing "$ps".)
3371 @findex call_function_by_hand
3372 @findex return_command
3373 Used in @samp{call_function_by_hand} to remove an artificial stack
3374 frame and in @samp{return_command} to remove a real stack frame.
3376 @item PUSH_ARGUMENTS (@var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr})
3377 @findex PUSH_ARGUMENTS
3378 Define this to push arguments onto the stack for inferior function
3379 call. Returns the updated stack pointer value.
3381 @item PUSH_DUMMY_FRAME
3382 @findex PUSH_DUMMY_FRAME
3383 Used in @samp{call_function_by_hand} to create an artificial stack frame.
3385 @item REGISTER_BYTES
3386 @findex REGISTER_BYTES
3387 The total amount of space needed to store @value{GDBN}'s copy of the machine's
3390 @item REGISTER_NAME(@var{i})
3391 @findex REGISTER_NAME
3392 Return the name of register @var{i} as a string. May return @code{NULL}
3393 or @code{NUL} to indicate that register @var{i} is not valid.
3395 @item REGISTER_NAMES
3396 @findex REGISTER_NAMES
3397 Deprecated in favor of @code{REGISTER_NAME}.
3399 @item REG_STRUCT_HAS_ADDR (@var{gcc_p}, @var{type})
3400 @findex REG_STRUCT_HAS_ADDR
3401 Define this to return 1 if the given type will be passed by pointer
3402 rather than directly.
3404 @item SAVE_DUMMY_FRAME_TOS (@var{sp})
3405 @findex SAVE_DUMMY_FRAME_TOS
3406 Used in @samp{call_function_by_hand} to notify the target dependent code
3407 of the top-of-stack value that will be passed to the the inferior code.
3408 This is the value of the @code{SP} after both the dummy frame and space
3409 for parameters/results have been allocated on the stack.
3411 @item SDB_REG_TO_REGNUM
3412 @findex SDB_REG_TO_REGNUM
3413 Define this to convert sdb register numbers into @value{GDBN} regnums. If not
3414 defined, no conversion will be done.
3416 @item SHIFT_INST_REGS
3417 @findex SHIFT_INST_REGS
3418 (Only used for m88k targets.)
3420 @item SKIP_PERMANENT_BREAKPOINT
3421 @findex SKIP_PERMANENT_BREAKPOINT
3422 Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally
3423 steps over a breakpoint by removing it, stepping one instruction, and
3424 re-inserting the breakpoint. However, permanent breakpoints are
3425 hardwired into the inferior, and can't be removed, so this strategy
3426 doesn't work. Calling @code{SKIP_PERMANENT_BREAKPOINT} adjusts the processor's
3427 state so that execution will resume just after the breakpoint. This
3428 macro does the right thing even when the breakpoint is in the delay slot
3429 of a branch or jump.
3431 @item SKIP_PROLOGUE (@var{pc})
3432 @findex SKIP_PROLOGUE
3433 A C expression that returns the address of the ``real'' code beyond the
3434 function entry prologue found at @var{pc}.
3436 @item SKIP_PROLOGUE_FRAMELESS_P
3437 @findex SKIP_PROLOGUE_FRAMELESS_P
3438 A C expression that should behave similarly, but that can stop as soon
3439 as the function is known to have a frame. If not defined,
3440 @code{SKIP_PROLOGUE} will be used instead.
3442 @item SKIP_TRAMPOLINE_CODE (@var{pc})
3443 @findex SKIP_TRAMPOLINE_CODE
3444 If the target machine has trampoline code that sits between callers and
3445 the functions being called, then define this macro to return a new PC
3446 that is at the start of the real function.
3450 If the stack-pointer is kept in a register, then define this macro to be
3451 the number (greater than or equal to zero) of that register.
3453 This should only need to be defined if @code{TARGET_WRITE_SP} and
3454 @code{TARGET_WRITE_SP} are not defined.
3456 @item STAB_REG_TO_REGNUM
3457 @findex STAB_REG_TO_REGNUM
3458 Define this to convert stab register numbers (as gotten from `r'
3459 declarations) into @value{GDBN} regnums. If not defined, no conversion will be
3462 @item STACK_ALIGN (@var{addr})
3464 Define this to adjust the address to the alignment required for the
3467 @item STEP_SKIPS_DELAY (@var{addr})
3468 @findex STEP_SKIPS_DELAY
3469 Define this to return true if the address is of an instruction with a
3470 delay slot. If a breakpoint has been placed in the instruction's delay
3471 slot, @value{GDBN} will single-step over that instruction before resuming
3472 normally. Currently only defined for the Mips.
3474 @item STORE_RETURN_VALUE (@var{type}, @var{valbuf})
3475 @findex STORE_RETURN_VALUE
3476 A C expression that stores a function return value of type @var{type},
3477 where @var{valbuf} is the address of the value to be stored.
3479 @item SUN_FIXED_LBRAC_BUG
3480 @findex SUN_FIXED_LBRAC_BUG
3481 (Used only for Sun-3 and Sun-4 targets.)
3483 @item SYMBOL_RELOADING_DEFAULT
3484 @findex SYMBOL_RELOADING_DEFAULT
3485 The default value of the ``symbol-reloading'' variable. (Never defined in
3488 @item TARGET_BYTE_ORDER_DEFAULT
3489 @findex TARGET_BYTE_ORDER_DEFAULT
3490 The ordering of bytes in the target. This must be either
3491 @code{BIG_ENDIAN} or @code{BFD_ENDIAN_LITTLE}. This macro replaces
3492 @code{TARGET_BYTE_ORDER} which is deprecated.
3494 @item TARGET_BYTE_ORDER_SELECTABLE_P
3495 @findex TARGET_BYTE_ORDER_SELECTABLE_P
3496 Non-zero if the target has both @code{BIG_ENDIAN} and
3497 @code{BFD_ENDIAN_LITTLE} variants. This macro replaces
3498 @code{TARGET_BYTE_ORDER_SELECTABLE} which is deprecated.
3500 @item TARGET_CHAR_BIT
3501 @findex TARGET_CHAR_BIT
3502 Number of bits in a char; defaults to 8.
3504 @item TARGET_COMPLEX_BIT
3505 @findex TARGET_COMPLEX_BIT
3506 Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}.
3508 At present this macro is not used.
3510 @item TARGET_DOUBLE_BIT
3511 @findex TARGET_DOUBLE_BIT
3512 Number of bits in a double float; defaults to @code{8 * TARGET_CHAR_BIT}.
3514 @item TARGET_DOUBLE_COMPLEX_BIT
3515 @findex TARGET_DOUBLE_COMPLEX_BIT
3516 Number of bits in a double complex; defaults to @code{2 * TARGET_DOUBLE_BIT}.
3518 At present this macro is not used.
3520 @item TARGET_FLOAT_BIT
3521 @findex TARGET_FLOAT_BIT
3522 Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}.
3524 @item TARGET_INT_BIT
3525 @findex TARGET_INT_BIT
3526 Number of bits in an integer; defaults to @code{4 * TARGET_CHAR_BIT}.
3528 @item TARGET_LONG_BIT
3529 @findex TARGET_LONG_BIT
3530 Number of bits in a long integer; defaults to @code{4 * TARGET_CHAR_BIT}.
3532 @item TARGET_LONG_DOUBLE_BIT
3533 @findex TARGET_LONG_DOUBLE_BIT
3534 Number of bits in a long double float;
3535 defaults to @code{2 * TARGET_DOUBLE_BIT}.
3537 @item TARGET_LONG_LONG_BIT
3538 @findex TARGET_LONG_LONG_BIT
3539 Number of bits in a long long integer; defaults to @code{2 * TARGET_LONG_BIT}.
3541 @item TARGET_PTR_BIT
3542 @findex TARGET_PTR_BIT
3543 Number of bits in a pointer; defaults to @code{TARGET_INT_BIT}.
3545 @item TARGET_SHORT_BIT
3546 @findex TARGET_SHORT_BIT
3547 Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}.
3549 @item TARGET_READ_PC
3550 @findex TARGET_READ_PC
3551 @itemx TARGET_WRITE_PC (@var{val}, @var{pid})
3552 @findex TARGET_WRITE_PC
3553 @itemx TARGET_READ_SP
3554 @findex TARGET_READ_SP
3555 @itemx TARGET_WRITE_SP
3556 @findex TARGET_WRITE_SP
3557 @itemx TARGET_READ_FP
3558 @findex TARGET_READ_FP
3559 @itemx TARGET_WRITE_FP
3560 @findex TARGET_WRITE_FP
3567 These change the behavior of @code{read_pc}, @code{write_pc},
3568 @code{read_sp}, @code{write_sp}, @code{read_fp} and @code{write_fp}.
3569 For most targets, these may be left undefined. @value{GDBN} will call the read
3570 and write register functions with the relevant @code{_REGNUM} argument.
3572 These macros are useful when a target keeps one of these registers in a
3573 hard to get at place; for example, part in a segment register and part
3574 in an ordinary register.
3576 @item TARGET_VIRTUAL_FRAME_POINTER(@var{pc}, @var{regp}, @var{offsetp})
3577 @findex TARGET_VIRTUAL_FRAME_POINTER
3578 Returns a @code{(register, offset)} pair representing the virtual
3579 frame pointer in use at the code address @var{pc}. If virtual
3580 frame pointers are not used, a default definition simply returns
3581 @code{FP_REGNUM}, with an offset of zero.
3583 @item TARGET_HAS_HARDWARE_WATCHPOINTS
3584 If non-zero, the target has support for hardware-assisted
3585 watchpoints. @xref{Algorithms, watchpoints}, for more details and
3586 other related macros.
3588 @item TARGET_PRINT_INSN (@var{addr}, @var{info})
3589 @findex TARGET_PRINT_INSN
3590 This is the function used by @value{GDBN} to print an assembly
3591 instruction. It prints the instruction at address @var{addr} in
3592 debugged memory and returns the length of the instruction, in bytes. If
3593 a target doesn't define its own printing routine, it defaults to an
3594 accessor function for the global pointer @code{tm_print_insn}. This
3595 usually points to a function in the @code{opcodes} library (@pxref{Support
3596 Libraries, ,Opcodes}). @var{info} is a structure (of type
3597 @code{disassemble_info}) defined in @file{include/dis-asm.h} used to
3598 pass information to the instruction decoding routine.
3600 @item USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type})
3601 @findex USE_STRUCT_CONVENTION
3602 If defined, this must be an expression that is nonzero if a value of the
3603 given @var{type} being returned from a function must have space
3604 allocated for it on the stack. @var{gcc_p} is true if the function
3605 being considered is known to have been compiled by GCC; this is helpful
3606 for systems where GCC is known to use different calling convention than
3609 @item VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p})
3610 @findex VARIABLES_INSIDE_BLOCK
3611 For dbx-style debugging information, if the compiler puts variable
3612 declarations inside LBRAC/RBRAC blocks, this should be defined to be
3613 nonzero. @var{desc} is the value of @code{n_desc} from the
3614 @code{N_RBRAC} symbol, and @var{gcc_p} is true if @value{GDBN} has noticed the
3615 presence of either the @code{GCC_COMPILED_SYMBOL} or the
3616 @code{GCC2_COMPILED_SYMBOL}. By default, this is 0.
3618 @item OS9K_VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p})
3619 @findex OS9K_VARIABLES_INSIDE_BLOCK
3620 Similarly, for OS/9000. Defaults to 1.
3623 Motorola M68K target conditionals.
3627 Define this to be the 4-bit location of the breakpoint trap vector. If
3628 not defined, it will default to @code{0xf}.
3630 @item REMOTE_BPT_VECTOR
3631 Defaults to @code{1}.
3634 @section Adding a New Target
3636 @cindex adding a target
3637 The following files add a target to @value{GDBN}:
3641 @item gdb/config/@var{arch}/@var{ttt}.mt
3642 Contains a Makefile fragment specific to this target. Specifies what
3643 object files are needed for target @var{ttt}, by defining
3644 @samp{TDEPFILES=@dots{}} and @samp{TDEPLIBS=@dots{}}. Also specifies
3645 the header file which describes @var{ttt}, by defining @samp{TM_FILE=
3648 You can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, @samp{TM_CDEPS},
3649 but these are now deprecated, replaced by autoconf, and may go away in
3650 future versions of @value{GDBN}.
3652 @item gdb/@var{ttt}-tdep.c
3653 Contains any miscellaneous code required for this target machine. On
3654 some machines it doesn't exist at all. Sometimes the macros in
3655 @file{tm-@var{ttt}.h} become very complicated, so they are implemented
3656 as functions here instead, and the macro is simply defined to call the
3657 function. This is vastly preferable, since it is easier to understand
3660 @item gdb/@var{arch}-tdep.c
3661 @itemx gdb/@var{arch}-tdep.h
3662 This often exists to describe the basic layout of the target machine's
3663 processor chip (registers, stack, etc.). If used, it is included by
3664 @file{@var{ttt}-tdep.h}. It can be shared among many targets that use
3667 @item gdb/config/@var{arch}/tm-@var{ttt}.h
3668 (@file{tm.h} is a link to this file, created by @code{configure}). Contains
3669 macro definitions about the target machine's registers, stack frame
3670 format and instructions.
3672 New targets do not need this file and should not create it.
3674 @item gdb/config/@var{arch}/tm-@var{arch}.h
3675 This often exists to describe the basic layout of the target machine's
3676 processor chip (registers, stack, etc.). If used, it is included by
3677 @file{tm-@var{ttt}.h}. It can be shared among many targets that use the
3680 New targets do not need this file and should not create it.
3684 If you are adding a new operating system for an existing CPU chip, add a
3685 @file{config/tm-@var{os}.h} file that describes the operating system
3686 facilities that are unusual (extra symbol table info; the breakpoint
3687 instruction needed; etc.). Then write a @file{@var{arch}/tm-@var{os}.h}
3688 that just @code{#include}s @file{tm-@var{arch}.h} and
3689 @file{config/tm-@var{os}.h}.
3692 @node Target Vector Definition
3694 @chapter Target Vector Definition
3695 @cindex target vector
3697 The target vector defines the interface between @value{GDBN}'s
3698 abstract handling of target systems, and the nitty-gritty code that
3699 actually exercises control over a process or a serial port.
3700 @value{GDBN} includes some 30-40 different target vectors; however,
3701 each configuration of @value{GDBN} includes only a few of them.
3703 @section File Targets
3705 Both executables and core files have target vectors.
3707 @section Standard Protocol and Remote Stubs
3709 @value{GDBN}'s file @file{remote.c} talks a serial protocol to code
3710 that runs in the target system. @value{GDBN} provides several sample
3711 @dfn{stubs} that can be integrated into target programs or operating
3712 systems for this purpose; they are named @file{*-stub.c}.
3714 The @value{GDBN} user's manual describes how to put such a stub into
3715 your target code. What follows is a discussion of integrating the
3716 SPARC stub into a complicated operating system (rather than a simple
3717 program), by Stu Grossman, the author of this stub.
3719 The trap handling code in the stub assumes the following upon entry to
3724 %l1 and %l2 contain pc and npc respectively at the time of the trap;
3730 you are in the correct trap window.
3733 As long as your trap handler can guarantee those conditions, then there
3734 is no reason why you shouldn't be able to ``share'' traps with the stub.
3735 The stub has no requirement that it be jumped to directly from the
3736 hardware trap vector. That is why it calls @code{exceptionHandler()},
3737 which is provided by the external environment. For instance, this could
3738 set up the hardware traps to actually execute code which calls the stub
3739 first, and then transfers to its own trap handler.
3741 For the most point, there probably won't be much of an issue with
3742 ``sharing'' traps, as the traps we use are usually not used by the kernel,
3743 and often indicate unrecoverable error conditions. Anyway, this is all
3744 controlled by a table, and is trivial to modify. The most important
3745 trap for us is for @code{ta 1}. Without that, we can't single step or
3746 do breakpoints. Everything else is unnecessary for the proper operation
3747 of the debugger/stub.
3749 From reading the stub, it's probably not obvious how breakpoints work.
3750 They are simply done by deposit/examine operations from @value{GDBN}.
3752 @section ROM Monitor Interface
3754 @section Custom Protocols
3756 @section Transport Layer
3758 @section Builtin Simulator
3761 @node Native Debugging
3763 @chapter Native Debugging
3764 @cindex native debugging
3766 Several files control @value{GDBN}'s configuration for native support:
3770 @item gdb/config/@var{arch}/@var{xyz}.mh
3771 Specifies Makefile fragments needed when hosting @emph{or native} on
3772 machine @var{xyz}. In particular, this lists the required
3773 native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}.
3774 Also specifies the header file which describes native support on
3775 @var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}. You can also
3776 define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS},
3777 @samp{NAT_CDEPS}, etc.; see @file{Makefile.in}.
3779 @item gdb/config/@var{arch}/nm-@var{xyz}.h
3780 (@file{nm.h} is a link to this file, created by @code{configure}). Contains C
3781 macro definitions describing the native system environment, such as
3782 child process control and core file support.
3784 @item gdb/@var{xyz}-nat.c
3785 Contains any miscellaneous C code required for this native support of
3786 this machine. On some machines it doesn't exist at all.
3789 There are some ``generic'' versions of routines that can be used by
3790 various systems. These can be customized in various ways by macros
3791 defined in your @file{nm-@var{xyz}.h} file. If these routines work for
3792 the @var{xyz} host, you can just include the generic file's name (with
3793 @samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.
3795 Otherwise, if your machine needs custom support routines, you will need
3796 to write routines that perform the same functions as the generic file.
3797 Put them into @file{@var{xyz}-nat.c}, and put @file{@var{xyz}-nat.o}
3798 into @code{NATDEPFILES}.
3802 This contains the @emph{target_ops vector} that supports Unix child
3803 processes on systems which use ptrace and wait to control the child.
3806 This contains the @emph{target_ops vector} that supports Unix child
3807 processes on systems which use /proc to control the child.
3810 This does the low-level grunge that uses Unix system calls to do a ``fork
3811 and exec'' to start up a child process.
3814 This is the low level interface to inferior processes for systems using
3815 the Unix @code{ptrace} call in a vanilla way.
3818 @section Native core file Support
3819 @cindex native core files
3822 @findex fetch_core_registers
3823 @item core-aout.c::fetch_core_registers()
3824 Support for reading registers out of a core file. This routine calls
3825 @code{register_addr()}, see below. Now that BFD is used to read core
3826 files, virtually all machines should use @code{core-aout.c}, and should
3827 just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or
3828 @code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}).
3830 @item core-aout.c::register_addr()
3831 If your @code{nm-@var{xyz}.h} file defines the macro
3832 @code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
3833 set @code{addr} to the offset within the @samp{user} struct of @value{GDBN}
3834 register number @code{regno}. @code{blockend} is the offset within the
3835 ``upage'' of @code{u.u_ar0}. If @code{REGISTER_U_ADDR} is defined,
3836 @file{core-aout.c} will define the @code{register_addr()} function and
3837 use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but
3838 you are using the standard @code{fetch_core_registers()}, you will need
3839 to define your own version of @code{register_addr()}, put it into your
3840 @code{@var{xyz}-nat.c} file, and be sure @code{@var{xyz}-nat.o} is in
3841 the @code{NATDEPFILES} list. If you have your own
3842 @code{fetch_core_registers()}, you may not need a separate
3843 @code{register_addr()}. Many custom @code{fetch_core_registers()}
3844 implementations simply locate the registers themselves.@refill
3847 When making @value{GDBN} run native on a new operating system, to make it
3848 possible to debug core files, you will need to either write specific
3849 code for parsing your OS's core files, or customize
3850 @file{bfd/trad-core.c}. First, use whatever @code{#include} files your
3851 machine uses to define the struct of registers that is accessible
3852 (possibly in the u-area) in a core file (rather than
3853 @file{machine/reg.h}), and an include file that defines whatever header
3854 exists on a core file (e.g. the u-area or a @code{struct core}). Then
3855 modify @code{trad_unix_core_file_p} to use these values to set up the
3856 section information for the data segment, stack segment, any other
3857 segments in the core file (perhaps shared library contents or control
3858 information), ``registers'' segment, and if there are two discontiguous
3859 sets of registers (e.g. integer and float), the ``reg2'' segment. This
3860 section information basically delimits areas in the core file in a
3861 standard way, which the section-reading routines in BFD know how to seek
3864 Then back in @value{GDBN}, you need a matching routine called
3865 @code{fetch_core_registers}. If you can use the generic one, it's in
3866 @file{core-aout.c}; if not, it's in your @file{@var{xyz}-nat.c} file.
3867 It will be passed a char pointer to the entire ``registers'' segment,
3868 its length, and a zero; or a char pointer to the entire ``regs2''
3869 segment, its length, and a 2. The routine should suck out the supplied
3870 register values and install them into @value{GDBN}'s ``registers'' array.
3872 If your system uses @file{/proc} to control processes, and uses ELF
3873 format core files, then you may be able to use the same routines for
3874 reading the registers out of processes and out of core files.
3882 @section shared libraries
3884 @section Native Conditionals
3885 @cindex native conditionals
3887 When @value{GDBN} is configured and compiled, various macros are
3888 defined or left undefined, to control compilation when the host and
3889 target systems are the same. These macros should be defined (or left
3890 undefined) in @file{nm-@var{system}.h}.
3894 @findex ATTACH_DETACH
3895 If defined, then @value{GDBN} will include support for the @code{attach} and
3896 @code{detach} commands.
3898 @item CHILD_PREPARE_TO_STORE
3899 @findex CHILD_PREPARE_TO_STORE
3900 If the machine stores all registers at once in the child process, then
3901 define this to ensure that all values are correct. This usually entails
3902 a read from the child.
3904 [Note that this is incorrectly defined in @file{xm-@var{system}.h} files
3907 @item FETCH_INFERIOR_REGISTERS
3908 @findex FETCH_INFERIOR_REGISTERS
3909 Define this if the native-dependent code will provide its own routines
3910 @code{fetch_inferior_registers} and @code{store_inferior_registers} in
3911 @file{@var{host}-nat.c}. If this symbol is @emph{not} defined, and
3912 @file{infptrace.c} is included in this configuration, the default
3913 routines in @file{infptrace.c} are used for these functions.
3915 @item FILES_INFO_HOOK
3916 @findex FILES_INFO_HOOK
3917 (Only defined for Convex.)
3921 This macro is normally defined to be the number of the first floating
3922 point register, if the machine has such registers. As such, it would
3923 appear only in target-specific code. However, @file{/proc} support uses this
3924 to decide whether floats are in use on this target.
3926 @item GET_LONGJMP_TARGET
3927 @findex GET_LONGJMP_TARGET
3928 For most machines, this is a target-dependent parameter. On the
3929 DECstation and the Iris, this is a native-dependent parameter, since
3930 @file{setjmp.h} is needed to define it.
3932 This macro determines the target PC address that @code{longjmp} will jump to,
3933 assuming that we have just stopped at a longjmp breakpoint. It takes a
3934 @code{CORE_ADDR *} as argument, and stores the target PC value through this
3935 pointer. It examines the current state of the machine as needed.
3937 @item I386_USE_GENERIC_WATCHPOINTS
3938 An x86-based machine can define this to use the generic x86 watchpoint
3939 support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}.
3942 @findex KERNEL_U_ADDR
3943 Define this to the address of the @code{u} structure (the ``user
3944 struct'', also known as the ``u-page'') in kernel virtual memory. @value{GDBN}
3945 needs to know this so that it can subtract this address from absolute
3946 addresses in the upage, that are obtained via ptrace or from core files.
3947 On systems that don't need this value, set it to zero.
3949 @item KERNEL_U_ADDR_BSD
3950 @findex KERNEL_U_ADDR_BSD
3951 Define this to cause @value{GDBN} to determine the address of @code{u} at
3952 runtime, by using Berkeley-style @code{nlist} on the kernel's image in
3955 @item KERNEL_U_ADDR_HPUX
3956 @findex KERNEL_U_ADDR_HPUX
3957 Define this to cause @value{GDBN} to determine the address of @code{u} at
3958 runtime, by using HP-style @code{nlist} on the kernel's image in the
3961 @item ONE_PROCESS_WRITETEXT
3962 @findex ONE_PROCESS_WRITETEXT
3963 Define this to be able to, when a breakpoint insertion fails, warn the
3964 user that another process may be running with the same executable.
3966 @item PREPARE_TO_PROCEED (@var{select_it})
3967 @findex PREPARE_TO_PROCEED
3968 This (ugly) macro allows a native configuration to customize the way the
3969 @code{proceed} function in @file{infrun.c} deals with switching between
3972 In a multi-threaded task we may select another thread and then continue
3973 or step. But if the old thread was stopped at a breakpoint, it will
3974 immediately cause another breakpoint stop without any execution (i.e. it
3975 will report a breakpoint hit incorrectly). So @value{GDBN} must step over it
3978 If defined, @code{PREPARE_TO_PROCEED} should check the current thread
3979 against the thread that reported the most recent event. If a step-over
3980 is required, it returns TRUE. If @var{select_it} is non-zero, it should
3981 reselect the old thread.
3984 @findex PROC_NAME_FMT
3985 Defines the format for the name of a @file{/proc} device. Should be
3986 defined in @file{nm.h} @emph{only} in order to override the default
3987 definition in @file{procfs.c}.
3990 @findex PTRACE_FP_BUG
3991 See @file{mach386-xdep.c}.
3993 @item PTRACE_ARG3_TYPE
3994 @findex PTRACE_ARG3_TYPE
3995 The type of the third argument to the @code{ptrace} system call, if it
3996 exists and is different from @code{int}.
3998 @item REGISTER_U_ADDR
3999 @findex REGISTER_U_ADDR
4000 Defines the offset of the registers in the ``u area''.
4002 @item SHELL_COMMAND_CONCAT
4003 @findex SHELL_COMMAND_CONCAT
4004 If defined, is a string to prefix on the shell command used to start the
4009 If defined, this is the name of the shell to use to run the inferior.
4010 Defaults to @code{"/bin/sh"}.
4012 @item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ}, @var{readsyms})
4014 Define this to expand into an expression that will cause the symbols in
4015 @var{filename} to be added to @value{GDBN}'s symbol table. If
4016 @var{readsyms} is zero symbols are not read but any necessary low level
4017 processing for @var{filename} is still done.
4019 @item SOLIB_CREATE_INFERIOR_HOOK
4020 @findex SOLIB_CREATE_INFERIOR_HOOK
4021 Define this to expand into any shared-library-relocation code that you
4022 want to be run just after the child process has been forked.
4024 @item START_INFERIOR_TRAPS_EXPECTED
4025 @findex START_INFERIOR_TRAPS_EXPECTED
4026 When starting an inferior, @value{GDBN} normally expects to trap
4028 the shell execs, and once when the program itself execs. If the actual
4029 number of traps is something other than 2, then define this macro to
4030 expand into the number expected.
4032 @item SVR4_SHARED_LIBS
4033 @findex SVR4_SHARED_LIBS
4034 Define this to indicate that SVR4-style shared libraries are in use.
4038 This determines whether small routines in @file{*-tdep.c}, which
4039 translate register values between @value{GDBN}'s internal
4040 representation and the @file{/proc} representation, are compiled.
4043 @findex U_REGS_OFFSET
4044 This is the offset of the registers in the upage. It need only be
4045 defined if the generic ptrace register access routines in
4046 @file{infptrace.c} are being used (that is, @file{infptrace.c} is
4047 configured in, and @code{FETCH_INFERIOR_REGISTERS} is not defined). If
4048 the default value from @file{infptrace.c} is good enough, leave it
4051 The default value means that u.u_ar0 @emph{points to} the location of
4052 the registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means
4053 that @code{u.u_ar0} @emph{is} the location of the registers.
4057 See @file{objfiles.c}.
4060 @findex DEBUG_PTRACE
4061 Define this to debug @code{ptrace} calls.
4065 @node Support Libraries
4067 @chapter Support Libraries
4072 BFD provides support for @value{GDBN} in several ways:
4075 @item identifying executable and core files
4076 BFD will identify a variety of file types, including a.out, coff, and
4077 several variants thereof, as well as several kinds of core files.
4079 @item access to sections of files
4080 BFD parses the file headers to determine the names, virtual addresses,
4081 sizes, and file locations of all the various named sections in files
4082 (such as the text section or the data section). @value{GDBN} simply
4083 calls BFD to read or write section @var{x} at byte offset @var{y} for
4086 @item specialized core file support
4087 BFD provides routines to determine the failing command name stored in a
4088 core file, the signal with which the program failed, and whether a core
4089 file matches (i.e.@: could be a core dump of) a particular executable
4092 @item locating the symbol information
4093 @value{GDBN} uses an internal interface of BFD to determine where to find the
4094 symbol information in an executable file or symbol-file. @value{GDBN} itself
4095 handles the reading of symbols, since BFD does not ``understand'' debug
4096 symbols, but @value{GDBN} uses BFD's cached information to find the symbols,
4101 @cindex opcodes library
4103 The opcodes library provides @value{GDBN}'s disassembler. (It's a separate
4104 library because it's also used in binutils, for @file{objdump}).
4113 @cindex regular expressions library
4124 @item SIGN_EXTEND_CHAR
4126 @item SWITCH_ENUM_BUG
4141 This chapter covers topics that are lower-level than the major
4142 algorithms of @value{GDBN}.
4147 Cleanups are a structured way to deal with things that need to be done
4148 later. When your code does something (like @code{malloc} some memory,
4149 or open a file) that needs to be undone later (e.g., free the memory or
4150 close the file), it can make a cleanup. The cleanup will be done at
4151 some future point: when the command is finished, when an error occurs,
4152 or when your code decides it's time to do cleanups.
4154 You can also discard cleanups, that is, throw them away without doing
4155 what they say. This is only done if you ask that it be done.
4160 @item struct cleanup *@var{old_chain};
4161 Declare a variable which will hold a cleanup chain handle.
4163 @findex make_cleanup
4164 @item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
4165 Make a cleanup which will cause @var{function} to be called with
4166 @var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a
4167 handle that can be passed to @code{do_cleanups} or
4168 @code{discard_cleanups} later. Unless you are going to call
4169 @code{do_cleanups} or @code{discard_cleanups} yourself, you can ignore
4170 the result from @code{make_cleanup}.
4173 @item do_cleanups (@var{old_chain});
4174 Perform all cleanups done since @code{make_cleanup} returned
4175 @var{old_chain}. E.g.:
4178 make_cleanup (a, 0);
4179 old = make_cleanup (b, 0);
4184 will call @code{b()} but will not call @code{a()}. The cleanup that
4185 calls @code{a()} will remain in the cleanup chain, and will be done
4186 later unless otherwise discarded.@refill
4188 @findex discard_cleanups
4189 @item discard_cleanups (@var{old_chain});
4190 Same as @code{do_cleanups} except that it just removes the cleanups from
4191 the chain and does not call the specified functions.
4194 Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify
4195 that they ``should not be called when cleanups are not in place''. This
4196 means that any actions you need to reverse in the case of an error or
4197 interruption must be on the cleanup chain before you call these
4198 functions, since they might never return to your code (they
4199 @samp{longjmp} instead).
4201 @section Wrapping Output Lines
4202 @cindex line wrap in output
4205 Output that goes through @code{printf_filtered} or @code{fputs_filtered}
4206 or @code{fputs_demangled} needs only to have calls to @code{wrap_here}
4207 added in places that would be good breaking points. The utility
4208 routines will take care of actually wrapping if the line width is
4211 The argument to @code{wrap_here} is an indentation string which is
4212 printed @emph{only} if the line breaks there. This argument is saved
4213 away and used later. It must remain valid until the next call to
4214 @code{wrap_here} or until a newline has been printed through the
4215 @code{*_filtered} functions. Don't pass in a local variable and then
4218 It is usually best to call @code{wrap_here} after printing a comma or
4219 space. If you call it before printing a space, make sure that your
4220 indentation properly accounts for the leading space that will print if
4221 the line wraps there.
4223 Any function or set of functions that produce filtered output must
4224 finish by printing a newline, to flush the wrap buffer, before switching
4225 to unfiltered (@code{printf}) output. Symbol reading routines that
4226 print warnings are a good example.
4228 @section @value{GDBN} Coding Standards
4229 @cindex coding standards
4231 @value{GDBN} follows the GNU coding standards, as described in
4232 @file{etc/standards.texi}. This file is also available for anonymous
4233 FTP from GNU archive sites. @value{GDBN} takes a strict interpretation
4234 of the standard; in general, when the GNU standard recommends a practice
4235 but does not require it, @value{GDBN} requires it.
4237 @value{GDBN} follows an additional set of coding standards specific to
4238 @value{GDBN}, as described in the following sections.
4243 @value{GDBN} assumes an ISO-C compliant compiler.
4245 @value{GDBN} does not assume an ISO-C or POSIX compliant C library.
4248 @subsection Memory Management
4250 @value{GDBN} does not use the functions @code{malloc}, @code{realloc},
4251 @code{calloc}, @code{free} and @code{asprintf}.
4253 @value{GDBN} uses the functions @code{xmalloc}, @code{xrealloc} and
4254 @code{xcalloc} when allocating memory. Unlike @code{malloc} et.al.@:
4255 these functions do not return when the memory pool is empty. Instead,
4256 they unwind the stack using cleanups. These functions return
4257 @code{NULL} when requested to allocate a chunk of memory of size zero.
4259 @emph{Pragmatics: By using these functions, the need to check every
4260 memory allocation is removed. These functions provide portable
4263 @value{GDBN} does not use the function @code{free}.
4265 @value{GDBN} uses the function @code{xfree} to return memory to the
4266 memory pool. Consistent with ISO-C, this function ignores a request to
4267 free a @code{NULL} pointer.
4269 @emph{Pragmatics: On some systems @code{free} fails when passed a
4270 @code{NULL} pointer.}
4272 @value{GDBN} can use the non-portable function @code{alloca} for the
4273 allocation of small temporary values (such as strings).
4275 @emph{Pragmatics: This function is very non-portable. Some systems
4276 restrict the memory being allocated to no more than a few kilobytes.}
4278 @value{GDBN} uses the string function @code{xstrdup} and the print
4279 function @code{xasprintf}.
4281 @emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print
4282 functions such as @code{sprintf} are very prone to buffer overflow
4286 @subsection Compiler Warnings
4287 @cindex compiler warnings
4289 With few exceptions, developers should include the configuration option
4290 @samp{--enable-gdb-build-warnings=,-Werror} when building @value{GDBN}.
4291 The exceptions are listed in the file @file{gdb/MAINTAINERS}.
4293 This option causes @value{GDBN} (when built using GCC) to be compiled
4294 with a carefully selected list of compiler warning flags. Any warnings
4295 from those flags being treated as errors.
4297 The current list of warning flags includes:
4301 Since @value{GDBN} coding standard requires all functions to be declared
4302 using a prototype, the flag has the side effect of ensuring that
4303 prototyped functions are always visible with out resorting to
4304 @samp{-Wstrict-prototypes}.
4307 Such code often appears to work except on instruction set architectures
4308 that use register windows.
4315 Since @value{GDBN} uses the @code{format printf} attribute on all
4316 @code{printf} like functions this checks not just @code{printf} calls
4317 but also calls to functions such as @code{fprintf_unfiltered}.
4320 This warning includes uses of the assignment operator within an
4321 @code{if} statement.
4323 @item -Wpointer-arith
4325 @item -Wuninitialized
4328 @emph{Pragmatics: Due to the way that @value{GDBN} is implemented most
4329 functions have unused parameters. Consequently the warning
4330 @samp{-Wunused-parameter} is precluded from the list. The macro
4331 @code{ATTRIBUTE_UNUSED} is not used as it leads to false negatives ---
4332 it is not an error to have @code{ATTRIBUTE_UNUSED} on a parameter that
4333 is being used. The options @samp{-Wall} and @samp{-Wunused} are also
4334 precluded because they both include @samp{-Wunused-parameter}.}
4336 @emph{Pragmatics: @value{GDBN} has not simply accepted the warnings
4337 enabled by @samp{-Wall -Werror -W...}. Instead it is selecting warnings
4338 when and where their benefits can be demonstrated.}
4340 @subsection Formatting
4342 @cindex source code formatting
4343 The standard GNU recommendations for formatting must be followed
4346 A function declaration should not have its name in column zero. A
4347 function definition should have its name in column zero.
4351 static void foo (void);
4359 @emph{Pragmatics: This simplifies scripting. Function definitions can
4360 be found using @samp{^function-name}.}
4362 There must be a space between a function or macro name and the opening
4363 parenthesis of its argument list (except for macro definitions, as
4364 required by C). There must not be a space after an open paren/bracket
4365 or before a close paren/bracket.
4367 While additional whitespace is generally helpful for reading, do not use
4368 more than one blank line to separate blocks, and avoid adding whitespace
4369 after the end of a program line (as of 1/99, some 600 lines had
4370 whitespace after the semicolon). Excess whitespace causes difficulties
4371 for @code{diff} and @code{patch} utilities.
4373 Pointers are declared using the traditional K&R C style:
4387 @subsection Comments
4389 @cindex comment formatting
4390 The standard GNU requirements on comments must be followed strictly.
4392 Block comments must appear in the following form, with no @code{/*}- or
4393 @code{*/}-only lines, and no leading @code{*}:
4396 /* Wait for control to return from inferior to debugger. If inferior
4397 gets a signal, we may decide to start it up again instead of
4398 returning. That is why there is a loop in this function. When
4399 this function actually returns it means the inferior should be left
4400 stopped and @value{GDBN} should read more commands. */
4403 (Note that this format is encouraged by Emacs; tabbing for a multi-line
4404 comment works correctly, and @kbd{M-q} fills the block consistently.)
4406 Put a blank line between the block comments preceding function or
4407 variable definitions, and the definition itself.
4409 In general, put function-body comments on lines by themselves, rather
4410 than trying to fit them into the 20 characters left at the end of a
4411 line, since either the comment or the code will inevitably get longer
4412 than will fit, and then somebody will have to move it anyhow.
4416 @cindex C data types
4417 Code must not depend on the sizes of C data types, the format of the
4418 host's floating point numbers, the alignment of anything, or the order
4419 of evaluation of expressions.
4421 @cindex function usage
4422 Use functions freely. There are only a handful of compute-bound areas
4423 in @value{GDBN} that might be affected by the overhead of a function
4424 call, mainly in symbol reading. Most of @value{GDBN}'s performance is
4425 limited by the target interface (whether serial line or system call).
4427 However, use functions with moderation. A thousand one-line functions
4428 are just as hard to understand as a single thousand-line function.
4430 @emph{Macros are bad, M'kay.}
4431 (But if you have to use a macro, make sure that the macro arguments are
4432 protected with parentheses.)
4436 Declarations like @samp{struct foo *} should be used in preference to
4437 declarations like @samp{typedef struct foo @{ @dots{} @} *foo_ptr}.
4440 @subsection Function Prototypes
4441 @cindex function prototypes
4443 Prototypes must be used when both @emph{declaring} and @emph{defining}
4444 a function. Prototypes for @value{GDBN} functions must include both the
4445 argument type and name, with the name matching that used in the actual
4446 function definition.
4448 All external functions should have a declaration in a header file that
4449 callers include, except for @code{_initialize_*} functions, which must
4450 be external so that @file{init.c} construction works, but shouldn't be
4451 visible to random source files.
4453 Where a source file needs a forward declaration of a static function,
4454 that declaration must appear in a block near the top of the source file.
4457 @subsection Internal Error Recovery
4459 During its execution, @value{GDBN} can encounter two types of errors.
4460 User errors and internal errors. User errors include not only a user
4461 entering an incorrect command but also problems arising from corrupt
4462 object files and system errors when interacting with the target.
4463 Internal errors include situtations where @value{GDBN} has detected, at
4464 run time, a corrupt or erroneous situtation.
4466 When reporting an internal error, @value{GDBN} uses
4467 @code{internal_error} and @code{gdb_assert}.
4469 @value{GDBN} must not call @code{abort} or @code{assert}.
4471 @emph{Pragmatics: There is no @code{internal_warning} function. Either
4472 the code detected a user error, recovered from it and issued a
4473 @code{warning} or the code failed to correctly recover from the user
4474 error and issued an @code{internal_error}.}
4476 @subsection File Names
4478 Any file used when building the core of @value{GDBN} must be in lower
4479 case. Any file used when building the core of @value{GDBN} must be 8.3
4480 unique. These requirements apply to both source and generated files.
4482 @emph{Pragmatics: The core of @value{GDBN} must be buildable on many
4483 platforms including DJGPP and MacOS/HFS. Every time an unfriendly file
4484 is introduced to the build process both @file{Makefile.in} and
4485 @file{configure.in} need to be modified accordingly. Compare the
4486 convoluted conversion process needed to transform @file{COPYING} into
4487 @file{copying.c} with the conversion needed to transform
4488 @file{version.in} into @file{version.c}.}
4490 Any file non 8.3 compliant file (that is not used when building the core
4491 of @value{GDBN}) must be added to @file{gdb/config/djgpp/fnchange.lst}.
4493 @emph{Pragmatics: This is clearly a compromise.}
4495 When @value{GDBN} has a local version of a system header file (ex
4496 @file{string.h}) the file name based on the POSIX header prefixed with
4497 @file{gdb_} (@file{gdb_string.h}).
4499 For other files @samp{-} is used as the separator.
4502 @subsection Include Files
4504 All @file{.c} files should include @file{defs.h} first.
4506 All @file{.c} files should explicitly include the headers for any
4507 declarations they refer to. They should not rely on files being
4508 included indirectly.
4510 With the exception of the global definitions supplied by @file{defs.h},
4511 a header file should explictily include the header declaring any
4512 @code{typedefs} et.al.@: it refers to.
4514 @code{extern} declarations should never appear in @code{.c} files.
4516 All include files should be wrapped in:
4519 #ifndef INCLUDE_FILE_NAME_H
4520 #define INCLUDE_FILE_NAME_H
4526 @subsection Clean Design and Portable Implementation
4529 In addition to getting the syntax right, there's the little question of
4530 semantics. Some things are done in certain ways in @value{GDBN} because long
4531 experience has shown that the more obvious ways caused various kinds of
4534 @cindex assumptions about targets
4535 You can't assume the byte order of anything that comes from a target
4536 (including @var{value}s, object files, and instructions). Such things
4537 must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in
4538 @value{GDBN}, or one of the swap routines defined in @file{bfd.h},
4539 such as @code{bfd_get_32}.
4541 You can't assume that you know what interface is being used to talk to
4542 the target system. All references to the target must go through the
4543 current @code{target_ops} vector.
4545 You can't assume that the host and target machines are the same machine
4546 (except in the ``native'' support modules). In particular, you can't
4547 assume that the target machine's header files will be available on the
4548 host machine. Target code must bring along its own header files --
4549 written from scratch or explicitly donated by their owner, to avoid
4553 Insertion of new @code{#ifdef}'s will be frowned upon. It's much better
4554 to write the code portably than to conditionalize it for various
4557 @cindex system dependencies
4558 New @code{#ifdef}'s which test for specific compilers or manufacturers
4559 or operating systems are unacceptable. All @code{#ifdef}'s should test
4560 for features. The information about which configurations contain which
4561 features should be segregated into the configuration files. Experience
4562 has proven far too often that a feature unique to one particular system
4563 often creeps into other systems; and that a conditional based on some
4564 predefined macro for your current system will become worthless over
4565 time, as new versions of your system come out that behave differently
4566 with regard to this feature.
4568 Adding code that handles specific architectures, operating systems,
4569 target interfaces, or hosts, is not acceptable in generic code.
4571 @cindex portable file name handling
4572 @cindex file names, portability
4573 One particularly notorious area where system dependencies tend to
4574 creep in is handling of file names. The mainline @value{GDBN} code
4575 assumes Posix semantics of file names: absolute file names begin with
4576 a forward slash @file{/}, slashes are used to separate leading
4577 directories, case-sensitive file names. These assumptions are not
4578 necessarily true on non-Posix systems such as MS-Windows. To avoid
4579 system-dependent code where you need to take apart or construct a file
4580 name, use the following portable macros:
4583 @findex HAVE_DOS_BASED_FILE_SYSTEM
4584 @item HAVE_DOS_BASED_FILE_SYSTEM
4585 This preprocessing symbol is defined to a non-zero value on hosts
4586 whose filesystems belong to the MS-DOS/MS-Windows family. Use this
4587 symbol to write conditional code which should only be compiled for
4590 @findex IS_DIR_SEPARATOR
4591 @item IS_DIR_SEPARATOR (@var{c}
4592 Evaluates to a non-zero value if @var{c} is a directory separator
4593 character. On Unix and GNU/Linux systems, only a slash @file{/} is
4594 such a character, but on Windows, both @file{/} and @file{\} will
4597 @findex IS_ABSOLUTE_PATH
4598 @item IS_ABSOLUTE_PATH (@var{file})
4599 Evaluates to a non-zero value if @var{file} is an absolute file name.
4600 For Unix and GNU/Linux hosts, a name which begins with a slash
4601 @file{/} is absolute. On DOS and Windows, @file{d:/foo} and
4602 @file{x:\bar} are also absolute file names.
4604 @findex FILENAME_CMP
4605 @item FILENAME_CMP (@var{f1}, @var{f2})
4606 Calls a function which compares file names @var{f1} and @var{f2} as
4607 appropriate for the underlying host filesystem. For Posix systems,
4608 this simply calls @code{strcmp}; on case-insensitive filesystems it
4609 will call @code{strcasecmp} instead.
4611 @findex DIRNAME_SEPARATOR
4612 @item DIRNAME_SEPARATOR
4613 Evaluates to a character which separates directories in
4614 @code{PATH}-style lists, typically held in environment variables.
4615 This character is @samp{:} on Unix, @samp{;} on DOS and Windows.
4617 @findex SLASH_STRING
4619 This evaluates to a constant string you should use to produce an
4620 absolute filename from leading directories and the file's basename.
4621 @code{SLASH_STRING} is @code{"/"} on most systems, but might be
4622 @code{"\\"} for some Windows-based ports.
4625 In addition to using these macros, be sure to use portable library
4626 functions whenever possible. For example, to extract a directory or a
4627 basename part from a file name, use the @code{dirname} and
4628 @code{basename} library functions (available in @code{libiberty} for
4629 platforms which don't provide them), instead of searching for a slash
4630 with @code{strrchr}.
4632 Another way to generalize @value{GDBN} along a particular interface is with an
4633 attribute struct. For example, @value{GDBN} has been generalized to handle
4634 multiple kinds of remote interfaces---not by @code{#ifdef}s everywhere, but
4635 by defining the @code{target_ops} structure and having a current target (as
4636 well as a stack of targets below it, for memory references). Whenever
4637 something needs to be done that depends on which remote interface we are
4638 using, a flag in the current target_ops structure is tested (e.g.,
4639 @code{target_has_stack}), or a function is called through a pointer in the
4640 current target_ops structure. In this way, when a new remote interface
4641 is added, only one module needs to be touched---the one that actually
4642 implements the new remote interface. Other examples of
4643 attribute-structs are BFD access to multiple kinds of object file
4644 formats, or @value{GDBN}'s access to multiple source languages.
4646 Please avoid duplicating code. For example, in @value{GDBN} 3.x all
4647 the code interfacing between @code{ptrace} and the rest of
4648 @value{GDBN} was duplicated in @file{*-dep.c}, and so changing
4649 something was very painful. In @value{GDBN} 4.x, these have all been
4650 consolidated into @file{infptrace.c}. @file{infptrace.c} can deal
4651 with variations between systems the same way any system-independent
4652 file would (hooks, @code{#if defined}, etc.), and machines which are
4653 radically different don't need to use @file{infptrace.c} at all.
4655 All debugging code must be controllable using the @samp{set debug
4656 @var{module}} command. Do not use @code{printf} to print trace
4657 messages. Use @code{fprintf_unfiltered(gdb_stdlog, ...}. Do not use
4658 @code{#ifdef DEBUG}.
4663 @chapter Porting @value{GDBN}
4664 @cindex porting to new machines
4666 Most of the work in making @value{GDBN} compile on a new machine is in
4667 specifying the configuration of the machine. This is done in a
4668 dizzying variety of header files and configuration scripts, which we
4669 hope to make more sensible soon. Let's say your new host is called an
4670 @var{xyz} (e.g., @samp{sun4}), and its full three-part configuration
4671 name is @code{@var{arch}-@var{xvend}-@var{xos}} (e.g.,
4672 @samp{sparc-sun-sunos4}). In particular:
4676 In the top level directory, edit @file{config.sub} and add @var{arch},
4677 @var{xvend}, and @var{xos} to the lists of supported architectures,
4678 vendors, and operating systems near the bottom of the file. Also, add
4679 @var{xyz} as an alias that maps to
4680 @code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by
4684 ./config.sub @var{xyz}
4691 ./config.sub @code{@var{arch}-@var{xvend}-@var{xos}}
4695 which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}}
4696 and no error messages.
4699 You need to port BFD, if that hasn't been done already. Porting BFD is
4700 beyond the scope of this manual.
4703 To configure @value{GDBN} itself, edit @file{gdb/configure.host} to recognize
4704 your system and set @code{gdb_host} to @var{xyz}, and (unless your
4705 desired target is already available) also edit @file{gdb/configure.tgt},
4706 setting @code{gdb_target} to something appropriate (for instance,
4710 Finally, you'll need to specify and define @value{GDBN}'s host-, native-, and
4711 target-dependent @file{.h} and @file{.c} files used for your
4715 @section Configuring @value{GDBN} for Release
4717 @cindex preparing a release
4718 @cindex making a distribution tarball
4719 From the top level directory (containing @file{gdb}, @file{bfd},
4720 @file{libiberty}, and so on):
4723 make -f Makefile.in gdb.tar.gz
4727 This will properly configure, clean, rebuild any files that are
4728 distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}),
4729 and will then make a tarfile. (If the top level directory has already
4730 been configured, you can just do @code{make gdb.tar.gz} instead.)
4732 This procedure requires:
4740 @code{makeinfo} (texinfo2 level);
4749 @code{yacc} or @code{bison}.
4753 @dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.).
4755 @subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
4757 @file{gdb.texinfo} is currently marked up using the texinfo-2 macros,
4758 which are not yet a default for anything (but we have to start using
4761 For making paper, the only thing this implies is the right generation of
4762 @file{texinfo.tex} needs to be included in the distribution.
4764 For making info files, however, rather than duplicating the texinfo2
4765 distribution, generate @file{gdb-all.texinfo} locally, and include the
4766 files @file{gdb.info*} in the distribution. Note the plural;
4767 @code{makeinfo} will split the document into one overall file and five
4768 or so included files.
4775 The testsuite is an important component of the @value{GDBN} package.
4776 While it is always worthwhile to encourage user testing, in practice
4777 this is rarely sufficient; users typically use only a small subset of
4778 the available commands, and it has proven all too common for a change
4779 to cause a significant regression that went unnoticed for some time.
4781 The @value{GDBN} testsuite uses the DejaGNU testing framework.
4782 DejaGNU is built using @code{Tcl} and @code{expect}. The tests
4783 themselves are calls to various @code{Tcl} procs; the framework runs all the
4784 procs and summarizes the passes and fails.
4786 @section Using the Testsuite
4788 @cindex running the test suite
4789 To run the testsuite, simply go to the @value{GDBN} object directory (or to the
4790 testsuite's objdir) and type @code{make check}. This just sets up some
4791 environment variables and invokes DejaGNU's @code{runtest} script. While
4792 the testsuite is running, you'll get mentions of which test file is in use,
4793 and a mention of any unexpected passes or fails. When the testsuite is
4794 finished, you'll get a summary that looks like this:
4799 # of expected passes 6016
4800 # of unexpected failures 58
4801 # of unexpected successes 5
4802 # of expected failures 183
4803 # of unresolved testcases 3
4804 # of untested testcases 5
4807 The ideal test run consists of expected passes only; however, reality
4808 conspires to keep us from this ideal. Unexpected failures indicate
4809 real problems, whether in @value{GDBN} or in the testsuite. Expected
4810 failures are still failures, but ones which have been decided are too
4811 hard to deal with at the time; for instance, a test case might work
4812 everywhere except on AIX, and there is no prospect of the AIX case
4813 being fixed in the near future. Expected failures should not be added
4814 lightly, since you may be masking serious bugs in @value{GDBN}.
4815 Unexpected successes are expected fails that are passing for some
4816 reason, while unresolved and untested cases often indicate some minor
4817 catastrophe, such as the compiler being unable to deal with a test
4820 When making any significant change to @value{GDBN}, you should run the
4821 testsuite before and after the change, to confirm that there are no
4822 regressions. Note that truly complete testing would require that you
4823 run the testsuite with all supported configurations and a variety of
4824 compilers; however this is more than really necessary. In many cases
4825 testing with a single configuration is sufficient. Other useful
4826 options are to test one big-endian (Sparc) and one little-endian (x86)
4827 host, a cross config with a builtin simulator (powerpc-eabi,
4828 mips-elf), or a 64-bit host (Alpha).
4830 If you add new functionality to @value{GDBN}, please consider adding
4831 tests for it as well; this way future @value{GDBN} hackers can detect
4832 and fix their changes that break the functionality you added.
4833 Similarly, if you fix a bug that was not previously reported as a test
4834 failure, please add a test case for it. Some cases are extremely
4835 difficult to test, such as code that handles host OS failures or bugs
4836 in particular versions of compilers, and it's OK not to try to write
4837 tests for all of those.
4839 @section Testsuite Organization
4841 @cindex test suite organization
4842 The testsuite is entirely contained in @file{gdb/testsuite}. While the
4843 testsuite includes some makefiles and configury, these are very minimal,
4844 and used for little besides cleaning up, since the tests themselves
4845 handle the compilation of the programs that @value{GDBN} will run. The file
4846 @file{testsuite/lib/gdb.exp} contains common utility procs useful for
4847 all @value{GDBN} tests, while the directory @file{testsuite/config} contains
4848 configuration-specific files, typically used for special-purpose
4849 definitions of procs like @code{gdb_load} and @code{gdb_start}.
4851 The tests themselves are to be found in @file{testsuite/gdb.*} and
4852 subdirectories of those. The names of the test files must always end
4853 with @file{.exp}. DejaGNU collects the test files by wildcarding
4854 in the test directories, so both subdirectories and individual files
4855 get chosen and run in alphabetical order.
4857 The following table lists the main types of subdirectories and what they
4858 are for. Since DejaGNU finds test files no matter where they are
4859 located, and since each test file sets up its own compilation and
4860 execution environment, this organization is simply for convenience and
4865 This is the base testsuite. The tests in it should apply to all
4866 configurations of @value{GDBN} (but generic native-only tests may live here).
4867 The test programs should be in the subset of C that is valid K&R,
4868 ANSI/ISO, and C++ (@code{#ifdef}s are allowed if necessary, for instance
4871 @item gdb.@var{lang}
4872 Language-specific tests for any language @var{lang} besides C. Examples are
4873 @file{gdb.c++} and @file{gdb.java}.
4875 @item gdb.@var{platform}
4876 Non-portable tests. The tests are specific to a specific configuration
4877 (host or target), such as HP-UX or eCos. Example is @file{gdb.hp}, for
4880 @item gdb.@var{compiler}
4881 Tests specific to a particular compiler. As of this writing (June
4882 1999), there aren't currently any groups of tests in this category that
4883 couldn't just as sensibly be made platform-specific, but one could
4884 imagine a @file{gdb.gcc}, for tests of @value{GDBN}'s handling of GCC
4887 @item gdb.@var{subsystem}
4888 Tests that exercise a specific @value{GDBN} subsystem in more depth. For
4889 instance, @file{gdb.disasm} exercises various disassemblers, while
4890 @file{gdb.stabs} tests pathways through the stabs symbol reader.
4893 @section Writing Tests
4894 @cindex writing tests
4896 In many areas, the @value{GDBN} tests are already quite comprehensive; you
4897 should be able to copy existing tests to handle new cases.
4899 You should try to use @code{gdb_test} whenever possible, since it
4900 includes cases to handle all the unexpected errors that might happen.
4901 However, it doesn't cost anything to add new test procedures; for
4902 instance, @file{gdb.base/exprs.exp} defines a @code{test_expr} that
4903 calls @code{gdb_test} multiple times.
4905 Only use @code{send_gdb} and @code{gdb_expect} when absolutely
4906 necessary, such as when @value{GDBN} has several valid responses to a command.
4908 The source language programs do @emph{not} need to be in a consistent
4909 style. Since @value{GDBN} is used to debug programs written in many different
4910 styles, it's worth having a mix of styles in the testsuite; for
4911 instance, some @value{GDBN} bugs involving the display of source lines would
4912 never manifest themselves if the programs used GNU coding style
4919 Check the @file{README} file, it often has useful information that does not
4920 appear anywhere else in the directory.
4923 * Getting Started:: Getting started working on @value{GDBN}
4924 * Debugging GDB:: Debugging @value{GDBN} with itself
4927 @node Getting Started,,, Hints
4929 @section Getting Started
4931 @value{GDBN} is a large and complicated program, and if you first starting to
4932 work on it, it can be hard to know where to start. Fortunately, if you
4933 know how to go about it, there are ways to figure out what is going on.
4935 This manual, the @value{GDBN} Internals manual, has information which applies
4936 generally to many parts of @value{GDBN}.
4938 Information about particular functions or data structures are located in
4939 comments with those functions or data structures. If you run across a
4940 function or a global variable which does not have a comment correctly
4941 explaining what is does, this can be thought of as a bug in @value{GDBN}; feel
4942 free to submit a bug report, with a suggested comment if you can figure
4943 out what the comment should say. If you find a comment which is
4944 actually wrong, be especially sure to report that.
4946 Comments explaining the function of macros defined in host, target, or
4947 native dependent files can be in several places. Sometimes they are
4948 repeated every place the macro is defined. Sometimes they are where the
4949 macro is used. Sometimes there is a header file which supplies a
4950 default definition of the macro, and the comment is there. This manual
4951 also documents all the available macros.
4952 @c (@pxref{Host Conditionals}, @pxref{Target
4953 @c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete
4956 Start with the header files. Once you have some idea of how
4957 @value{GDBN}'s internal symbol tables are stored (see @file{symtab.h},
4958 @file{gdbtypes.h}), you will find it much easier to understand the
4959 code which uses and creates those symbol tables.
4961 You may wish to process the information you are getting somehow, to
4962 enhance your understanding of it. Summarize it, translate it to another
4963 language, add some (perhaps trivial or non-useful) feature to @value{GDBN}, use
4964 the code to predict what a test case would do and write the test case
4965 and verify your prediction, etc. If you are reading code and your eyes
4966 are starting to glaze over, this is a sign you need to use a more active
4969 Once you have a part of @value{GDBN} to start with, you can find more
4970 specifically the part you are looking for by stepping through each
4971 function with the @code{next} command. Do not use @code{step} or you
4972 will quickly get distracted; when the function you are stepping through
4973 calls another function try only to get a big-picture understanding
4974 (perhaps using the comment at the beginning of the function being
4975 called) of what it does. This way you can identify which of the
4976 functions being called by the function you are stepping through is the
4977 one which you are interested in. You may need to examine the data
4978 structures generated at each stage, with reference to the comments in
4979 the header files explaining what the data structures are supposed to
4982 Of course, this same technique can be used if you are just reading the
4983 code, rather than actually stepping through it. The same general
4984 principle applies---when the code you are looking at calls something
4985 else, just try to understand generally what the code being called does,
4986 rather than worrying about all its details.
4988 @cindex command implementation
4989 A good place to start when tracking down some particular area is with
4990 a command which invokes that feature. Suppose you want to know how
4991 single-stepping works. As a @value{GDBN} user, you know that the
4992 @code{step} command invokes single-stepping. The command is invoked
4993 via command tables (see @file{command.h}); by convention the function
4994 which actually performs the command is formed by taking the name of
4995 the command and adding @samp{_command}, or in the case of an
4996 @code{info} subcommand, @samp{_info}. For example, the @code{step}
4997 command invokes the @code{step_command} function and the @code{info
4998 display} command invokes @code{display_info}. When this convention is
4999 not followed, you might have to use @code{grep} or @kbd{M-x
5000 tags-search} in emacs, or run @value{GDBN} on itself and set a
5001 breakpoint in @code{execute_command}.
5003 @cindex @code{bug-gdb} mailing list
5004 If all of the above fail, it may be appropriate to ask for information
5005 on @code{bug-gdb}. But @emph{never} post a generic question like ``I was
5006 wondering if anyone could give me some tips about understanding
5007 @value{GDBN}''---if we had some magic secret we would put it in this manual.
5008 Suggestions for improving the manual are always welcome, of course.
5010 @node Debugging GDB,,,Hints
5012 @section Debugging @value{GDBN} with itself
5013 @cindex debugging @value{GDBN}
5015 If @value{GDBN} is limping on your machine, this is the preferred way to get it
5016 fully functional. Be warned that in some ancient Unix systems, like
5017 Ultrix 4.2, a program can't be running in one process while it is being
5018 debugged in another. Rather than typing the command @kbd{@w{./gdb
5019 ./gdb}}, which works on Suns and such, you can copy @file{gdb} to
5020 @file{gdb2} and then type @kbd{@w{./gdb ./gdb2}}.
5022 When you run @value{GDBN} in the @value{GDBN} source directory, it will read a
5023 @file{.gdbinit} file that sets up some simple things to make debugging
5024 gdb easier. The @code{info} command, when executed without a subcommand
5025 in a @value{GDBN} being debugged by gdb, will pop you back up to the top level
5026 gdb. See @file{.gdbinit} for details.
5028 If you use emacs, you will probably want to do a @code{make TAGS} after
5029 you configure your distribution; this will put the machine dependent
5030 routines for your local machine where they will be accessed first by
5033 Also, make sure that you've either compiled @value{GDBN} with your local cc, or
5034 have run @code{fixincludes} if you are compiling with gcc.
5036 @section Submitting Patches
5038 @cindex submitting patches
5039 Thanks for thinking of offering your changes back to the community of
5040 @value{GDBN} users. In general we like to get well designed enhancements.
5041 Thanks also for checking in advance about the best way to transfer the
5044 The @value{GDBN} maintainers will only install ``cleanly designed'' patches.
5045 This manual summarizes what we believe to be clean design for @value{GDBN}.
5047 If the maintainers don't have time to put the patch in when it arrives,
5048 or if there is any question about a patch, it goes into a large queue
5049 with everyone else's patches and bug reports.
5051 @cindex legal papers for code contributions
5052 The legal issue is that to incorporate substantial changes requires a
5053 copyright assignment from you and/or your employer, granting ownership
5054 of the changes to the Free Software Foundation. You can get the
5055 standard documents for doing this by sending mail to @code{gnu@@gnu.org}
5056 and asking for it. We recommend that people write in "All programs
5057 owned by the Free Software Foundation" as "NAME OF PROGRAM", so that
5058 changes in many programs (not just @value{GDBN}, but GAS, Emacs, GCC,
5060 contributed with only one piece of legalese pushed through the
5061 bureaucracy and filed with the FSF. We can't start merging changes until
5062 this paperwork is received by the FSF (their rules, which we follow
5063 since we maintain it for them).
5065 Technically, the easiest way to receive changes is to receive each
5066 feature as a small context diff or unidiff, suitable for @code{patch}.
5067 Each message sent to me should include the changes to C code and
5068 header files for a single feature, plus @file{ChangeLog} entries for
5069 each directory where files were modified, and diffs for any changes
5070 needed to the manuals (@file{gdb/doc/gdb.texinfo} or
5071 @file{gdb/doc/gdbint.texinfo}). If there are a lot of changes for a
5072 single feature, they can be split down into multiple messages.
5074 In this way, if we read and like the feature, we can add it to the
5075 sources with a single patch command, do some testing, and check it in.
5076 If you leave out the @file{ChangeLog}, we have to write one. If you leave
5077 out the doc, we have to puzzle out what needs documenting. Etc., etc.
5079 The reason to send each change in a separate message is that we will not
5080 install some of the changes. They'll be returned to you with questions
5081 or comments. If we're doing our job correctly, the message back to you
5082 will say what you have to fix in order to make the change acceptable.
5083 The reason to have separate messages for separate features is so that
5084 the acceptable changes can be installed while one or more changes are
5085 being reworked. If multiple features are sent in a single message, we
5086 tend to not put in the effort to sort out the acceptable changes from
5087 the unacceptable, so none of the features get installed until all are
5090 If this sounds painful or authoritarian, well, it is. But we get a lot
5091 of bug reports and a lot of patches, and many of them don't get
5092 installed because we don't have the time to finish the job that the bug
5093 reporter or the contributor could have done. Patches that arrive
5094 complete, working, and well designed, tend to get installed on the day
5095 they arrive. The others go into a queue and get installed as time
5096 permits, which, since the maintainers have many demands to meet, may not
5097 be for quite some time.
5099 Please send patches directly to
5100 @email{gdb-patches@@sourceware.cygnus.com, the @value{GDBN} maintainers}.
5102 @section Obsolete Conditionals
5103 @cindex obsolete code
5105 Fragments of old code in @value{GDBN} sometimes reference or set the following
5106 configuration macros. They should not be used by new code, and old uses
5107 should be removed as those parts of the debugger are otherwise touched.
5110 @item STACK_END_ADDR
5111 This macro used to define where the end of the stack appeared, for use
5112 in interpreting core file formats that don't record this address in the
5113 core file itself. This information is now configured in BFD, and @value{GDBN}
5114 gets the info portably from there. The values in @value{GDBN}'s configuration
5115 files should be moved into BFD configuration files (if needed there),
5116 and deleted from all of @value{GDBN}'s config files.
5118 Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
5119 is so old that it has never been converted to use BFD. Now that's old!
5121 @item PYRAMID_CONTROL_FRAME_DEBUGGING
5125 @item PYRAMID_PTRACE
5128 @item REG_STACK_SEGMENT
5138 @c TeX can handle the contents at the start but makeinfo 3.12 can not