1 This is gdbint.info, produced by makeinfo version 4.8 from
2 /home/jingyu/projects/gcc/android-toolchainsrc/build/../gdb/gdb-6.6/gdb/doc/gdbint.texinfo.
4 INFO-DIR-SECTION Software development
6 * Gdb-Internals: (gdbint). The GNU debugger's internals.
9 This file documents the internals of the GNU debugger GDB.
10 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999, 2000,
11 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
12 Contributed by Cygnus Solutions. Written by John Gilmore. Second
13 Edition by Stan Shebs.
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the GNU Free Documentation License, Version 1.1 or
17 any later version published by the Free Software Foundation; with no
18 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
19 Texts. A copy of the license is included in the section entitled "GNU
20 Free Documentation License".
23 File: gdbint.info, Node: Top, Next: Requirements, Up: (dir)
25 Scope of this Document
26 **********************
28 This document documents the internals of the GNU debugger, GDB. It
29 includes description of GDB's key algorithms and operations, as well as
30 the mechanisms that adapt GDB to specific hosts and targets.
42 * Target Architecture Definition::
43 * Target Vector Definition::
48 * Versions and Branches::
49 * Start of New Year Procedure::
54 * GDB Observers:: GDB Currently available observers
55 * GNU Free Documentation License:: The license for this documentation
59 File: gdbint.info, Node: Requirements, Next: Overall Structure, Prev: Top, Up: Top
64 Before diving into the internals, you should understand the formal
65 requirements and other expectations for GDB. Although some of these
66 may seem obvious, there have been proposals for GDB that have run
67 counter to these requirements.
69 First of all, GDB is a debugger. It's not designed to be a front
70 panel for embedded systems. It's not a text editor. It's not a shell.
71 It's not a programming environment.
73 GDB is an interactive tool. Although a batch mode is available,
74 GDB's primary role is to interact with a human programmer.
76 GDB should be responsive to the user. A programmer hot on the trail
77 of a nasty bug, and operating under a looming deadline, is going to be
78 very impatient of everything, including the response time to debugger
81 GDB should be relatively permissive, such as for expressions. While
82 the compiler should be picky (or have the option to be made picky),
83 since source code lives for a long time usually, the programmer doing
84 debugging shouldn't be spending time figuring out to mollify the
87 GDB will be called upon to deal with really large programs.
88 Executable sizes of 50 to 100 megabytes occur regularly, and we've
89 heard reports of programs approaching 1 gigabyte in size.
91 GDB should be able to run everywhere. No other debugger is
92 available for even half as many configurations as GDB supports.
95 File: gdbint.info, Node: Overall Structure, Next: Algorithms, Prev: Requirements, Up: Top
100 GDB consists of three major subsystems: user interface, symbol handling
101 (the "symbol side"), and target system handling (the "target side").
103 The user interface consists of several actual interfaces, plus
106 The symbol side consists of object file readers, debugging info
107 interpreters, symbol table management, source language expression
108 parsing, type and value printing.
110 The target side consists of execution control, stack frame analysis,
111 and physical target manipulation.
113 The target side/symbol side division is not formal, and there are a
114 number of exceptions. For instance, core file support involves symbolic
115 elements (the basic core file reader is in BFD) and target elements (it
116 supplies the contents of memory and the values of registers). Instead,
117 this division is useful for understanding how the minor subsystems
123 The symbolic side of GDB can be thought of as "everything you can do in
124 GDB without having a live program running". For instance, you can look
125 at the types of variables, and evaluate many kinds of expressions.
130 The target side of GDB is the "bits and bytes manipulator". Although
131 it may make reference to symbolic info here and there, most of the
132 target side will run with only a stripped executable available--or even
133 no executable at all, in remote debugging cases.
135 Operations such as disassembly, stack frame crawls, and register
136 display, are able to work with no symbolic info at all. In some cases,
137 such as disassembly, GDB will use symbolic info to present addresses
138 relative to symbols rather than as raw numbers, but it will work either
144 "Host" refers to attributes of the system where GDB runs. "Target"
145 refers to the system where the program being debugged executes. In
146 most cases they are the same machine, in which case a third type of
147 "Native" attributes come into play.
149 Defines and include files needed to build on the host are host
150 support. Examples are tty support, system defined types, host byte
151 order, host float format.
153 Defines and information needed to handle the target format are target
154 dependent. Examples are the stack frame format, instruction set,
155 breakpoint instruction, registers, and how to set up and tear down the
156 stack to call a function.
158 Information that is only needed when the host and target are the
159 same, is native dependent. One example is Unix child process support;
160 if the host and target are not the same, doing a fork to start the
161 target process is a bad idea. The various macros needed for finding the
162 registers in the `upage', running `ptrace', and such are all in the
163 native-dependent files.
165 Another example of native-dependent code is support for features that
166 are really part of the target environment, but which require `#include'
167 files that are only available on the host system. Core file handling
168 and `setjmp' handling are two common cases.
170 When you want to make GDB work "native" on a particular machine, you
171 have to include all three kinds of information.
173 2.4 Source Tree Structure
174 =========================
176 The GDB source directory has a mostly flat structure--there are only a
177 few subdirectories. A file's name usually gives a hint as to what it
178 does; for example, `stabsread.c' reads stabs, `dwarfread.c' reads
181 Files that are related to some common task have names that share
182 common substrings. For example, `*-thread.c' files deal with debugging
183 threads on various platforms; `*read.c' files deal with reading various
184 kinds of symbol and object files; `inf*.c' files deal with direct
185 control of the "inferior program" (GDB parlance for the program being
188 There are several dozens of files in the `*-tdep.c' family. `tdep'
189 stands for "target-dependent code"--each of these files implements
190 debug support for a specific target architecture (sparc, mips, etc).
191 Usually, only one of these will be used in a specific GDB configuration
192 (sometimes two, closely related).
194 Similarly, there are many `*-nat.c' files, each one for native
195 debugging on a specific system (e.g., `sparc-linux-nat.c' is for native
196 debugging of Sparc machines running the Linux kernel).
198 The few subdirectories of the source tree are:
201 Code that implements "CLI", the GDB Command-Line Interpreter.
202 *Note Command Interpreter: User Interface.
205 Code for the GDB remote server.
208 Code for Insight, the GDB TK-based GUI front-end.
211 The "GDB/MI", the GDB Machine Interface interpreter.
214 Target signal translation code.
217 Code for "TUI", the GDB Text-mode full-screen User Interface.
218 *Note TUI: User Interface.
221 File: gdbint.info, Node: Algorithms, Next: User Interface, Prev: Overall Structure, Up: Top
226 GDB uses a number of debugging-specific algorithms. They are often not
227 very complicated, but get lost in the thicket of special cases and
228 real-world issues. This chapter describes the basic algorithms and
229 mentions some of the specific target definitions that they use.
234 A frame is a construct that GDB uses to keep track of calling and
237 GDB's frame model, a fresh design, was implemented with the need to
238 support DWARF's Call Frame Information in mind. In fact, the term
239 "unwind" is taken directly from that specification. Developers wishing
240 to learn more about unwinders, are encouraged to read the the DWARF
243 GDB's model is that you find a frame's registers by "unwinding" them
244 from the next younger frame. That is, `get_frame_register' which
245 returns the value of a register in frame #1 (the next-to-youngest
246 frame), is implemented by calling frame #0's `frame_register_unwind'
247 (the youngest frame). But then the obvious question is: how do you
248 access the registers of the youngest frame itself?
250 To answer this question, GDB has the "sentinel" frame, the "-1st"
251 frame. Unwinding registers from the sentinel frame gives you the
252 current values of the youngest real frame's registers. If F is a
253 sentinel frame, then `get_frame_type (F) == SENTINEL_FRAME'.
255 3.2 Prologue Analysis
256 =====================
258 To produce a backtrace and allow the user to manipulate older frames'
259 variables and arguments, GDB needs to find the base addresses of older
260 frames, and discover where those frames' registers have been saved.
261 Since a frame's "callee-saves" registers get saved by younger frames if
262 and when they're reused, a frame's registers may be scattered
263 unpredictably across younger frames. This means that changing the
264 value of a register-allocated variable in an older frame may actually
265 entail writing to a save slot in some younger frame.
267 Modern versions of GCC emit Dwarf call frame information ("CFI"),
268 which describes how to find frame base addresses and saved registers.
269 But CFI is not always available, so as a fallback GDB uses a technique
270 called "prologue analysis" to find frame sizes and saved registers. A
271 prologue analyzer disassembles the function's machine code starting
272 from its entry point, and looks for instructions that allocate frame
273 space, save the stack pointer in a frame pointer register, save
274 registers, and so on. Obviously, this can't be done accurately in
275 general, but it's tractable to do well enough to be very helpful.
276 Prologue analysis predates the GNU toolchain's support for CFI; at one
277 time, prologue analysis was the only mechanism GDB used for stack
278 unwinding at all, when the function calling conventions didn't specify
279 a fixed frame layout.
281 In the olden days, function prologues were generated by hand-written,
282 target-specific code in GCC, and treated as opaque and untouchable by
283 optimizers. Looking at this code, it was usually straightforward to
284 write a prologue analyzer for GDB that would accurately understand all
285 the prologues GCC would generate. However, over time GCC became more
286 aggressive about instruction scheduling, and began to understand more
287 about the semantics of the prologue instructions themselves; in
288 response, GDB's analyzers became more complex and fragile. Keeping the
289 prologue analyzers working as GCC (and the instruction sets themselves)
290 evolved became a substantial task.
292 To try to address this problem, the code in `prologue-value.h' and
293 `prologue-value.c' provides a general framework for writing prologue
294 analyzers that are simpler and more robust than ad-hoc analyzers. When
295 we analyze a prologue using the prologue-value framework, we're really
296 doing "abstract interpretation" or "pseudo-evaluation": running the
297 function's code in simulation, but using conservative approximations of
298 the values registers and memory would hold when the code actually runs.
299 For example, if our function starts with the instruction:
301 addi r1, 42 # add 42 to r1
302 we don't know exactly what value will be in `r1' after executing
303 this instruction, but we do know it'll be 42 greater than its original
306 If we then see an instruction like:
308 addi r1, 22 # add 22 to r1
309 we still don't know what `r1's' value is, but again, we can say it
310 is now 64 greater than its original value.
312 If the next instruction were:
314 mov r2, r1 # set r2 to r1's value
315 then we can say that `r2's' value is now the original value of `r1'
318 It's common for prologues to save registers on the stack, so we'll
319 need to track the values of stack frame slots, as well as the
320 registers. So after an instruction like this:
323 then we'd know that the stack slot four bytes above the frame pointer
324 holds the original value of `r1' plus 64.
328 Of course, this can only go so far before it gets unreasonable. If
329 we wanted to be able to say anything about the value of `r1' after the
332 xor r1, r3 # exclusive-or r1 and r3, place result in r1
333 then things would get pretty complex. But remember, we're just doing
334 a conservative approximation; if exclusive-or instructions aren't
335 relevant to prologues, we can just say `r1''s value is now "unknown".
336 We can ignore things that are too complex, if that loss of information
337 is acceptable for our application.
339 So when we say "conservative approximation" here, what we mean is an
340 approximation that is either accurate, or marked "unknown", but never
343 Using this framework, a prologue analyzer is simply an interpreter
344 for machine code, but one that uses conservative approximations for the
345 contents of registers and memory instead of actual values. Starting
346 from the function's entry point, you simulate instructions up to the
347 current PC, or an instruction that you don't know how to simulate. Now
348 you can examine the state of the registers and stack slots you've kept
351 * To see how large your stack frame is, just check the value of the
352 stack pointer register; if it's the original value of the SP minus
353 a constant, then that constant is the stack frame's size. If the
354 SP's value has been marked as "unknown", then that means the
355 prologue has done something too complex for us to track, and we
356 don't know the frame size.
358 * To see where we've saved the previous frame's registers, we just
359 search the values we've tracked -- stack slots, usually, but
360 registers, too, if you want -- for something equal to the
361 register's original value. If the calling conventions suggest a
362 standard place to save a given register, then we can check there
363 first, but really, anything that will get us back the original
364 value will probably work.
366 This does take some work. But prologue analyzers aren't
367 quick-and-simple pattern patching to recognize a few fixed prologue
368 forms any more; they're big, hairy functions. Along with inferior
369 function calls, prologue analysis accounts for a substantial portion of
370 the time needed to stabilize a GDB port. So it's worthwhile to look
371 for an approach that will be easier to understand and maintain. In the
372 approach described above:
374 * It's easier to see that the analyzer is correct: you just see
375 whether the analyzer properly (albeit conservatively) simulates
376 the effect of each instruction.
378 * It's easier to extend the analyzer: you can add support for new
379 instructions, and know that you haven't broken anything that
380 wasn't already broken before.
382 * It's orthogonal: to gather new information, you don't need to
383 complicate the code for each instruction. As long as your domain
384 of conservative values is already detailed enough to tell you what
385 you need, then all the existing instruction simulations are
386 already gathering the right data for you.
389 The file `prologue-value.h' contains detailed comments explaining
390 the framework and how to use it.
392 3.3 Breakpoint Handling
393 =======================
395 In general, a breakpoint is a user-designated location in the program
396 where the user wants to regain control if program execution ever reaches
399 There are two main ways to implement breakpoints; either as
400 "hardware" breakpoints or as "software" breakpoints.
402 Hardware breakpoints are sometimes available as a builtin debugging
403 features with some chips. Typically these work by having dedicated
404 register into which the breakpoint address may be stored. If the PC
405 (shorthand for "program counter") ever matches a value in a breakpoint
406 registers, the CPU raises an exception and reports it to GDB.
408 Another possibility is when an emulator is in use; many emulators
409 include circuitry that watches the address lines coming out from the
410 processor, and force it to stop if the address matches a breakpoint's
413 A third possibility is that the target already has the ability to do
414 breakpoints somehow; for instance, a ROM monitor may do its own
415 software breakpoints. So although these are not literally "hardware
416 breakpoints", from GDB's point of view they work the same; GDB need not
417 do anything more than set the breakpoint and wait for something to
420 Since they depend on hardware resources, hardware breakpoints may be
421 limited in number; when the user asks for more, GDB will start trying
422 to set software breakpoints. (On some architectures, notably the
423 32-bit x86 platforms, GDB cannot always know whether there's enough
424 hardware resources to insert all the hardware breakpoints and
425 watchpoints. On those platforms, GDB prints an error message only when
426 the program being debugged is continued.)
428 Software breakpoints require GDB to do somewhat more work. The
429 basic theory is that GDB will replace a program instruction with a
430 trap, illegal divide, or some other instruction that will cause an
431 exception, and then when it's encountered, GDB will take the exception
432 and stop the program. When the user says to continue, GDB will restore
433 the original instruction, single-step, re-insert the trap, and continue
436 Since it literally overwrites the program being tested, the program
437 area must be writable, so this technique won't work on programs in ROM.
438 It can also distort the behavior of programs that examine themselves,
439 although such a situation would be highly unusual.
441 Also, the software breakpoint instruction should be the smallest
442 size of instruction, so it doesn't overwrite an instruction that might
443 be a jump target, and cause disaster when the program jumps into the
444 middle of the breakpoint instruction. (Strictly speaking, the
445 breakpoint must be no larger than the smallest interval between
446 instructions that may be jump targets; perhaps there is an architecture
447 where only even-numbered instructions may jumped to.) Note that it's
448 possible for an instruction set not to have any instructions usable for
449 a software breakpoint, although in practice only the ARC has failed to
450 define such an instruction.
452 The basic definition of the software breakpoint is the macro
455 Basic breakpoint object handling is in `breakpoint.c'. However,
456 much of the interesting breakpoint action is in `infrun.c'.
458 `target_remove_breakpoint (BP_TGT)'
459 `target_insert_breakpoint (BP_TGT)'
460 Insert or remove a software breakpoint at address
461 `BP_TGT->placed_address'. Returns zero for success, non-zero for
462 failure. On input, BP_TGT contains the address of the breakpoint,
463 and is otherwise initialized to zero. The fields of the `struct
464 bp_target_info' pointed to by BP_TGT are updated to contain other
465 information about the breakpoint on output. The field
466 `placed_address' may be updated if the breakpoint was placed at a
467 related address; the field `shadow_contents' contains the real
468 contents of the bytes where the breakpoint has been inserted, if
469 reading memory would return the breakpoint instead of the
470 underlying memory; the field `shadow_len' is the length of memory
471 cached in `shadow_contents', if any; and the field `placed_size'
472 is optionally set and used by the target, if it could differ from
475 For example, the remote target `Z0' packet does not require
476 shadowing memory, so `shadow_len' is left at zero. However, the
477 length reported by `BREAKPOINT_FROM_PC' is cached in
478 `placed_size', so that a matching `z0' packet can be used to
479 remove the breakpoint.
481 `target_remove_hw_breakpoint (BP_TGT)'
482 `target_insert_hw_breakpoint (BP_TGT)'
483 Insert or remove a hardware-assisted breakpoint at address
484 `BP_TGT->placed_address'. Returns zero for success, non-zero for
485 failure. See `target_insert_breakpoint' for a description of the
486 `struct bp_target_info' pointed to by BP_TGT; the
487 `shadow_contents' and `shadow_len' members are not used for
488 hardware breakpoints, but `placed_size' may be.
499 3.7 Inferior Function Calls
500 ===========================
505 GDB has support for figuring out that the target is doing a `longjmp'
506 and for stopping at the target of the jump, if we are stepping. This
507 is done with a few specialized internal breakpoints, which are visible
508 in the output of the `maint info breakpoint' command.
510 To make this work, you need to define a macro called
511 `GET_LONGJMP_TARGET', which will examine the `jmp_buf' structure and
512 extract the longjmp target address. Since `jmp_buf' is target
513 specific, you will need to define it in the appropriate `tm-TARGET.h'
514 file. Look in `tm-sun4os4.h' and `sparc-tdep.c' for examples of how to
520 Watchpoints are a special kind of breakpoints (*note breakpoints:
521 Algorithms.) which break when data is accessed rather than when some
522 instruction is executed. When you have data which changes without your
523 knowing what code does that, watchpoints are the silver bullet to hunt
524 down and kill such bugs.
526 Watchpoints can be either hardware-assisted or not; the latter type
527 is known as "software watchpoints." GDB always uses hardware-assisted
528 watchpoints if they are available, and falls back on software
529 watchpoints otherwise. Typical situations where GDB will use software
532 * The watched memory region is too large for the underlying hardware
533 watchpoint support. For example, each x86 debug register can
534 watch up to 4 bytes of memory, so trying to watch data structures
535 whose size is more than 16 bytes will cause GDB to use software
538 * The value of the expression to be watched depends on data held in
539 registers (as opposed to memory).
541 * Too many different watchpoints requested. (On some architectures,
542 this situation is impossible to detect until the debugged program
543 is resumed.) Note that x86 debug registers are used both for
544 hardware breakpoints and for watchpoints, so setting too many
545 hardware breakpoints might cause watchpoint insertion to fail.
547 * No hardware-assisted watchpoints provided by the target
550 Software watchpoints are very slow, since GDB needs to single-step
551 the program being debugged and test the value of the watched
552 expression(s) after each instruction. The rest of this section is
553 mostly irrelevant for software watchpoints.
555 When the inferior stops, GDB tries to establish, among other
556 possible reasons, whether it stopped due to a watchpoint being hit.
557 For a data-write watchpoint, it does so by evaluating, for each
558 watchpoint, the expression whose value is being watched, and testing
559 whether the watched value has changed. For data-read and data-access
560 watchpoints, GDB needs the target to supply a primitive that returns
561 the address of the data that was accessed or read (see the description
562 of `target_stopped_data_address' below): if this primitive returns a
563 valid address, GDB infers that a watchpoint triggered if it watches an
564 expression whose evaluation uses that address.
566 GDB uses several macros and primitives to support hardware
569 `TARGET_HAS_HARDWARE_WATCHPOINTS'
570 If defined, the target supports hardware watchpoints.
572 `TARGET_CAN_USE_HARDWARE_WATCHPOINT (TYPE, COUNT, OTHER)'
573 Return the number of hardware watchpoints of type TYPE that are
574 possible to be set. The value is positive if COUNT watchpoints of
575 this type can be set, zero if setting watchpoints of this type is
576 not supported, and negative if COUNT is more than the maximum
577 number of watchpoints of type TYPE that can be set. OTHER is
578 non-zero if other types of watchpoints are currently enabled (there
579 are architectures which cannot set watchpoints of different types
582 `TARGET_REGION_OK_FOR_HW_WATCHPOINT (ADDR, LEN)'
583 Return non-zero if hardware watchpoints can be used to watch a
584 region whose address is ADDR and whose length in bytes is LEN.
586 `target_insert_watchpoint (ADDR, LEN, TYPE)'
587 `target_remove_watchpoint (ADDR, LEN, TYPE)'
588 Insert or remove a hardware watchpoint starting at ADDR, for LEN
589 bytes. TYPE is the watchpoint type, one of the possible values of
590 the enumerated data type `target_hw_bp_type', defined by
591 `breakpoint.h' as follows:
593 enum target_hw_bp_type
595 hw_write = 0, /* Common (write) HW watchpoint */
596 hw_read = 1, /* Read HW watchpoint */
597 hw_access = 2, /* Access (read or write) HW watchpoint */
598 hw_execute = 3 /* Execute HW breakpoint */
601 These two macros should return 0 for success, non-zero for failure.
603 `target_stopped_data_address (ADDR_P)'
604 If the inferior has some watchpoint that triggered, place the
605 address associated with the watchpoint at the location pointed to
606 by ADDR_P and return non-zero. Otherwise, return zero. Note that
607 this primitive is used by GDB only on targets that support
608 data-read or data-access type watchpoints, so targets that have
609 support only for data-write watchpoints need not implement these
612 `HAVE_STEPPABLE_WATCHPOINT'
613 If defined to a non-zero value, it is not necessary to disable a
614 watchpoint to step over it.
616 `HAVE_NONSTEPPABLE_WATCHPOINT'
617 If defined to a non-zero value, GDB should disable a watchpoint to
618 step the inferior over it.
620 `HAVE_CONTINUABLE_WATCHPOINT'
621 If defined to a non-zero value, it is possible to continue the
622 inferior after a watchpoint has been hit.
624 `CANNOT_STEP_HW_WATCHPOINTS'
625 If this is defined to a non-zero value, GDB will remove all
626 watchpoints before stepping the inferior.
628 `STOPPED_BY_WATCHPOINT (WAIT_STATUS)'
629 Return non-zero if stopped by a watchpoint. WAIT_STATUS is of the
630 type `struct target_waitstatus', defined by `target.h'. Normally,
631 this macro is defined to invoke the function pointed to by the
632 `to_stopped_by_watchpoint' member of the structure (of the type
633 `target_ops', defined on `target.h') that describes the
634 target-specific operations; `to_stopped_by_watchpoint' ignores the
635 WAIT_STATUS argument.
637 GDB does not require the non-zero value returned by
638 `STOPPED_BY_WATCHPOINT' to be 100% correct, so if a target cannot
639 determine for sure whether the inferior stopped due to a
640 watchpoint, it could return non-zero "just in case".
642 3.9.1 x86 Watchpoints
643 ---------------------
645 The 32-bit Intel x86 (a.k.a. ia32) processors feature special debug
646 registers designed to facilitate debugging. GDB provides a generic
647 library of functions that x86-based ports can use to implement support
648 for watchpoints and hardware-assisted breakpoints. This subsection
649 documents the x86 watchpoint facilities in GDB.
651 To use the generic x86 watchpoint support, a port should do the
654 * Define the macro `I386_USE_GENERIC_WATCHPOINTS' somewhere in the
655 target-dependent headers.
657 * Include the `config/i386/nm-i386.h' header file _after_ defining
658 `I386_USE_GENERIC_WATCHPOINTS'.
660 * Add `i386-nat.o' to the value of the Make variable `NATDEPFILES'
661 (*note NATDEPFILES: Native Debugging.) or `TDEPFILES' (*note
662 TDEPFILES: Target Architecture Definition.).
664 * Provide implementations for the `I386_DR_LOW_*' macros described
665 below. Typically, each macro should call a target-specific
666 function which does the real work.
668 The x86 watchpoint support works by maintaining mirror images of the
669 debug registers. Values are copied between the mirror images and the
670 real debug registers via a set of macros which each target needs to
673 `I386_DR_LOW_SET_CONTROL (VAL)'
674 Set the Debug Control (DR7) register to the value VAL.
676 `I386_DR_LOW_SET_ADDR (IDX, ADDR)'
677 Put the address ADDR into the debug register number IDX.
679 `I386_DR_LOW_RESET_ADDR (IDX)'
680 Reset (i.e. zero out) the address stored in the debug register
683 `I386_DR_LOW_GET_STATUS'
684 Return the value of the Debug Status (DR6) register. This value is
685 used immediately after it is returned by `I386_DR_LOW_GET_STATUS',
686 so as to support per-thread status register values.
688 For each one of the 4 debug registers (whose indices are from 0 to 3)
689 that store addresses, a reference count is maintained by GDB, to allow
690 sharing of debug registers by several watchpoints. This allows users
691 to define several watchpoints that watch the same expression, but with
692 different conditions and/or commands, without wasting debug registers
693 which are in short supply. GDB maintains the reference counts
694 internally, targets don't have to do anything to use this feature.
696 The x86 debug registers can each watch a region that is 1, 2, or 4
697 bytes long. The ia32 architecture requires that each watched region be
698 appropriately aligned: 2-byte region on 2-byte boundary, 4-byte region
699 on 4-byte boundary. However, the x86 watchpoint support in GDB can
700 watch unaligned regions and regions larger than 4 bytes (up to 16
701 bytes) by allocating several debug registers to watch a single region.
702 This allocation of several registers per a watched region is also done
703 automatically without target code intervention.
705 The generic x86 watchpoint support provides the following API for the
706 GDB's application code:
708 `i386_region_ok_for_watchpoint (ADDR, LEN)'
709 The macro `TARGET_REGION_OK_FOR_HW_WATCHPOINT' is set to call this
710 function. It counts the number of debug registers required to
711 watch a given region, and returns a non-zero value if that number
712 is less than 4, the number of debug registers available to x86
715 `i386_stopped_data_address (ADDR_P)'
716 The target function `target_stopped_data_address' is set to call
717 this function. This function examines the breakpoint condition
718 bits in the DR6 Debug Status register, as returned by the
719 `I386_DR_LOW_GET_STATUS' macro, and returns the address associated
720 with the first bit that is set in DR6.
722 `i386_stopped_by_watchpoint (void)'
723 The macro `STOPPED_BY_WATCHPOINT' is set to call this function.
724 The argument passed to `STOPPED_BY_WATCHPOINT' is ignored. This
725 function examines the breakpoint condition bits in the DR6 Debug
726 Status register, as returned by the `I386_DR_LOW_GET_STATUS'
727 macro, and returns true if any bit is set. Otherwise, false is
730 `i386_insert_watchpoint (ADDR, LEN, TYPE)'
731 `i386_remove_watchpoint (ADDR, LEN, TYPE)'
732 Insert or remove a watchpoint. The macros
733 `target_insert_watchpoint' and `target_remove_watchpoint' are set
734 to call these functions. `i386_insert_watchpoint' first looks for
735 a debug register which is already set to watch the same region for
736 the same access types; if found, it just increments the reference
737 count of that debug register, thus implementing debug register
738 sharing between watchpoints. If no such register is found, the
739 function looks for a vacant debug register, sets its mirrored
740 value to ADDR, sets the mirrored value of DR7 Debug Control
741 register as appropriate for the LEN and TYPE parameters, and then
742 passes the new values of the debug register and DR7 to the
743 inferior by calling `I386_DR_LOW_SET_ADDR' and
744 `I386_DR_LOW_SET_CONTROL'. If more than one debug register is
745 required to cover the given region, the above process is repeated
746 for each debug register.
748 `i386_remove_watchpoint' does the opposite: it resets the address
749 in the mirrored value of the debug register and its read/write and
750 length bits in the mirrored value of DR7, then passes these new
751 values to the inferior via `I386_DR_LOW_RESET_ADDR' and
752 `I386_DR_LOW_SET_CONTROL'. If a register is shared by several
753 watchpoints, each time a `i386_remove_watchpoint' is called, it
754 decrements the reference count, and only calls
755 `I386_DR_LOW_RESET_ADDR' and `I386_DR_LOW_SET_CONTROL' when the
758 `i386_insert_hw_breakpoint (BP_TGT)'
759 `i386_remove_hw_breakpoint (BP_TGT)'
760 These functions insert and remove hardware-assisted breakpoints.
761 The macros `target_insert_hw_breakpoint' and
762 `target_remove_hw_breakpoint' are set to call these functions.
763 The argument is a `struct bp_target_info *', as described in the
764 documentation for `target_insert_breakpoint'. These functions
765 work like `i386_insert_watchpoint' and `i386_remove_watchpoint',
766 respectively, except that they set up the debug registers to watch
767 instruction execution, and each hardware-assisted breakpoint
768 always requires exactly one debug register.
770 `i386_stopped_by_hwbp (void)'
771 This function returns non-zero if the inferior has some watchpoint
772 or hardware breakpoint that triggered. It works like
773 `i386_stopped_data_address', except that it doesn't record the
774 address whose watchpoint triggered.
776 `i386_cleanup_dregs (void)'
777 This function clears all the reference counts, addresses, and
778 control bits in the mirror images of the debug registers. It
779 doesn't affect the actual debug registers in the inferior process.
782 1. x86 processors support setting watchpoints on I/O reads or writes.
783 However, since no target supports this (as of March 2001), and
784 since `enum target_hw_bp_type' doesn't even have an enumeration
785 for I/O watchpoints, this feature is not yet available to GDB
788 2. x86 processors can enable watchpoints locally, for the current task
789 only, or globally, for all the tasks. For each debug register,
790 there's a bit in the DR7 Debug Control register that determines
791 whether the associated address is watched locally or globally. The
792 current implementation of x86 watchpoint support in GDB always
793 sets watchpoints to be locally enabled, since global watchpoints
794 might interfere with the underlying OS and are probably
795 unavailable in many platforms.
800 In the abstract, a checkpoint is a point in the execution history of
801 the program, which the user may wish to return to at some later time.
803 Internally, a checkpoint is a saved copy of the program state,
804 including whatever information is required in order to restore the
805 program to that state at a later time. This can be expected to include
806 the state of registers and memory, and may include external state such
807 as the state of open files and devices.
809 There are a number of ways in which checkpoints may be implemented
810 in gdb, e.g. as corefiles, as forked processes, and as some opaque
811 method implemented on the target side.
813 A corefile can be used to save an image of target memory and register
814 state, which can in principle be restored later -- but corefiles do not
815 typically include information about external entities such as open
816 files. Currently this method is not implemented in gdb.
818 A forked process can save the state of user memory and registers, as
819 well as some subset of external (kernel) state. This method is used to
820 implement checkpoints on Linux, and in principle might be used on other
823 Some targets, e.g. simulators, might have their own built-in method
824 for saving checkpoints, and gdb might be able to take advantage of that
825 capability without necessarily knowing any details of how it is done.
827 3.11 Observing changes in GDB internals
828 =======================================
830 In order to function properly, several modules need to be notified when
831 some changes occur in the GDB internals. Traditionally, these modules
832 have relied on several paradigms, the most common ones being hooks and
833 gdb-events. Unfortunately, none of these paradigms was versatile
834 enough to become the standard notification mechanism in GDB. The fact
835 that they only supported one "client" was also a strong limitation.
837 A new paradigm, based on the Observer pattern of the `Design
838 Patterns' book, has therefore been implemented. The goal was to provide
839 a new interface overcoming the issues with the notification mechanisms
840 previously available. This new interface needed to be strongly typed,
841 easy to extend, and versatile enough to be used as the standard
842 interface when adding new notifications.
844 See *Note GDB Observers:: for a brief description of the observers
845 currently implemented in GDB. The rationale for the current
846 implementation is also briefly discussed.
849 File: gdbint.info, Node: User Interface, Next: libgdb, Prev: Algorithms, Up: Top
854 GDB has several user interfaces. Although the command-line interface
855 is the most common and most familiar, there are others.
857 4.1 Command Interpreter
858 =======================
860 The command interpreter in GDB is fairly simple. It is designed to
861 allow for the set of commands to be augmented dynamically, and also has
862 a recursive subcommand capability, where the first argument to a
863 command may itself direct a lookup on a different command list.
865 For instance, the `set' command just starts a lookup on the
866 `setlist' command list, while `set thread' recurses to the
867 `set_thread_cmd_list'.
869 To add commands in general, use `add_cmd'. `add_com' adds to the
870 main command list, and should be used for those commands. The usual
871 place to add commands is in the `_initialize_XYZ' routines at the ends
872 of most source files.
874 To add paired `set' and `show' commands, use `add_setshow_cmd' or
875 `add_setshow_cmd_full'. The former is a slightly simpler interface
876 which is useful when you don't need to further modify the new command
877 structures, while the latter returns the new command structures for
880 Before removing commands from the command set it is a good idea to
881 deprecate them for some time. Use `deprecate_cmd' on commands or
882 aliases to set the deprecated flag. `deprecate_cmd' takes a `struct
883 cmd_list_element' as it's first argument. You can use the return value
884 from `add_com' or `add_cmd' to deprecate the command immediately after
887 The first time a command is used the user will be warned and offered
888 a replacement (if one exists). Note that the replacement string passed
889 to `deprecate_cmd' should be the full name of the command, i.e. the
890 entire string the user should type at the command line.
892 4.2 UI-Independent Output--the `ui_out' Functions
893 =================================================
895 The `ui_out' functions present an abstraction level for the GDB output
896 code. They hide the specifics of different user interfaces supported
897 by GDB, and thus free the programmer from the need to write several
898 versions of the same code, one each for every UI, to produce output.
900 4.2.1 Overview and Terminology
901 ------------------------------
903 In general, execution of each GDB command produces some sort of output,
904 and can even generate an input request.
906 Output can be generated for the following purposes:
908 * to display a _result_ of an operation;
910 * to convey _info_ or produce side-effects of a requested operation;
912 * to provide a _notification_ of an asynchronous event (including
913 progress indication of a prolonged asynchronous operation);
915 * to display _error messages_ (including warnings);
917 * to show _debug data_;
919 * to _query_ or prompt a user for input (a special case).
921 This section mainly concentrates on how to build result output,
922 although some of it also applies to other kinds of output.
924 Generation of output that displays the results of an operation
925 involves one or more of the following:
927 * output of the actual data
929 * formatting the output as appropriate for console output, to make it
930 easily readable by humans
932 * machine oriented formatting-a more terse formatting to allow for
933 easy parsing by programs which read GDB's output
935 * annotation, whose purpose is to help legacy GUIs to identify
936 interesting parts in the output
938 The `ui_out' routines take care of the first three aspects.
939 Annotations are provided by separate annotation routines. Note that use
940 of annotations for an interface between a GUI and GDB is deprecated.
942 Output can be in the form of a single item, which we call a "field";
943 a "list" consisting of identical fields; a "tuple" consisting of
944 non-identical fields; or a "table", which is a tuple consisting of a
945 header and a body. In a BNF-like form:
954 `<width> <alignment> <title>'
959 4.2.2 General Conventions
960 -------------------------
962 Most `ui_out' routines are of type `void', the exceptions are
963 `ui_out_stream_new' (which returns a pointer to the newly created
964 object) and the `make_cleanup' routines.
966 The first parameter is always the `ui_out' vector object, a pointer
967 to a `struct ui_out'.
969 The FORMAT parameter is like in `printf' family of functions. When
970 it is present, there must also be a variable list of arguments
971 sufficient used to satisfy the `%' specifiers in the supplied format.
973 When a character string argument is not used in a `ui_out' function
974 call, a `NULL' pointer has to be supplied instead.
976 4.2.3 Table, Tuple and List Functions
977 -------------------------------------
979 This section introduces `ui_out' routines for building lists, tuples
980 and tables. The routines to output the actual data items (fields) are
981 presented in the next section.
983 To recap: A "tuple" is a sequence of "fields", each field containing
984 information about an object; a "list" is a sequence of fields where
985 each field describes an identical object.
987 Use the "table" functions when your output consists of a list of
988 rows (tuples) and the console output should include a heading. Use this
989 even when you are listing just one object but you still want the header.
991 Tables can not be nested. Tuples and lists can be nested up to a
992 maximum of five levels.
994 The overall structure of the table output code is something like
1008 Here is the description of table-, tuple- and list-related `ui_out'
1011 -- Function: void ui_out_table_begin (struct ui_out *UIOUT, int
1012 NBROFCOLS, int NR_ROWS, const char *TBLID)
1013 The function `ui_out_table_begin' marks the beginning of the output
1014 of a table. It should always be called before any other `ui_out'
1015 function for a given table. NBROFCOLS is the number of columns in
1016 the table. NR_ROWS is the number of rows in the table. TBLID is
1017 an optional string identifying the table. The string pointed to
1018 by TBLID is copied by the implementation of `ui_out_table_begin',
1019 so the application can free the string if it was `malloc'ed.
1021 The companion function `ui_out_table_end', described below, marks
1022 the end of the table's output.
1024 -- Function: void ui_out_table_header (struct ui_out *UIOUT, int
1025 WIDTH, enum ui_align ALIGNMENT, const char *COLHDR)
1026 `ui_out_table_header' provides the header information for a single
1027 table column. You call this function several times, one each for
1028 every column of the table, after `ui_out_table_begin', but before
1029 `ui_out_table_body'.
1031 The value of WIDTH gives the column width in characters. The
1032 value of ALIGNMENT is one of `left', `center', and `right', and it
1033 specifies how to align the header: left-justify, center, or
1034 right-justify it. COLHDR points to a string that specifies the
1035 column header; the implementation copies that string, so column
1036 header strings in `malloc'ed storage can be freed after the call.
1038 -- Function: void ui_out_table_body (struct ui_out *UIOUT)
1039 This function delimits the table header from the table body.
1041 -- Function: void ui_out_table_end (struct ui_out *UIOUT)
1042 This function signals the end of a table's output. It should be
1043 called after the table body has been produced by the list and
1044 field output functions.
1046 There should be exactly one call to `ui_out_table_end' for each
1047 call to `ui_out_table_begin', otherwise the `ui_out' functions
1048 will signal an internal error.
1050 The output of the tuples that represent the table rows must follow
1051 the call to `ui_out_table_body' and precede the call to
1052 `ui_out_table_end'. You build a tuple by calling `ui_out_tuple_begin'
1053 and `ui_out_tuple_end', with suitable calls to functions which actually
1054 output fields between them.
1056 -- Function: void ui_out_tuple_begin (struct ui_out *UIOUT, const char
1058 This function marks the beginning of a tuple output. ID points to
1059 an optional string that identifies the tuple; it is copied by the
1060 implementation, and so strings in `malloc'ed storage can be freed
1063 -- Function: void ui_out_tuple_end (struct ui_out *UIOUT)
1064 This function signals an end of a tuple output. There should be
1065 exactly one call to `ui_out_tuple_end' for each call to
1066 `ui_out_tuple_begin', otherwise an internal GDB error will be
1069 -- Function: struct cleanup *make_cleanup_ui_out_tuple_begin_end
1070 (struct ui_out *UIOUT, const char *ID)
1071 This function first opens the tuple and then establishes a cleanup
1072 (*note Cleanups: Coding.) to close the tuple. It provides a
1073 convenient and correct implementation of the non-portable(1) code
1075 struct cleanup *old_cleanup;
1076 ui_out_tuple_begin (uiout, "...");
1077 old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end,
1080 -- Function: void ui_out_list_begin (struct ui_out *UIOUT, const char
1082 This function marks the beginning of a list output. ID points to
1083 an optional string that identifies the list; it is copied by the
1084 implementation, and so strings in `malloc'ed storage can be freed
1087 -- Function: void ui_out_list_end (struct ui_out *UIOUT)
1088 This function signals an end of a list output. There should be
1089 exactly one call to `ui_out_list_end' for each call to
1090 `ui_out_list_begin', otherwise an internal GDB error will be
1093 -- Function: struct cleanup *make_cleanup_ui_out_list_begin_end
1094 (struct ui_out *UIOUT, const char *ID)
1095 Similar to `make_cleanup_ui_out_tuple_begin_end', this function
1096 opens a list and then establishes cleanup (*note Cleanups: Coding.)
1097 that will close the list.list.
1099 4.2.4 Item Output Functions
1100 ---------------------------
1102 The functions described below produce output for the actual data items,
1103 or fields, which contain information about the object.
1105 Choose the appropriate function accordingly to your particular needs.
1107 -- Function: void ui_out_field_fmt (struct ui_out *UIOUT, char
1108 *FLDNAME, char *FORMAT, ...)
1109 This is the most general output function. It produces the
1110 representation of the data in the variable-length argument list
1111 according to formatting specifications in FORMAT, a `printf'-like
1112 format string. The optional argument FLDNAME supplies the name of
1113 the field. The data items themselves are supplied as additional
1114 arguments after FORMAT.
1116 This generic function should be used only when it is not possible
1117 to use one of the specialized versions (see below).
1119 -- Function: void ui_out_field_int (struct ui_out *UIOUT, const char
1120 *FLDNAME, int VALUE)
1121 This function outputs a value of an `int' variable. It uses the
1122 `"%d"' output conversion specification. FLDNAME specifies the
1125 -- Function: void ui_out_field_fmt_int (struct ui_out *UIOUT, int
1126 WIDTH, enum ui_align ALIGNMENT, const char *FLDNAME, int
1128 This function outputs a value of an `int' variable. It differs
1129 from `ui_out_field_int' in that the caller specifies the desired
1130 WIDTH and ALIGNMENT of the output. FLDNAME specifies the name of
1133 -- Function: void ui_out_field_core_addr (struct ui_out *UIOUT, const
1134 char *FLDNAME, CORE_ADDR ADDRESS)
1135 This function outputs an address.
1137 -- Function: void ui_out_field_string (struct ui_out *UIOUT, const
1138 char *FLDNAME, const char *STRING)
1139 This function outputs a string using the `"%s"' conversion
1142 Sometimes, there's a need to compose your output piece by piece using
1143 functions that operate on a stream, such as `value_print' or
1144 `fprintf_symbol_filtered'. These functions accept an argument of the
1145 type `struct ui_file *', a pointer to a `ui_file' object used to store
1146 the data stream used for the output. When you use one of these
1147 functions, you need a way to pass their results stored in a `ui_file'
1148 object to the `ui_out' functions. To this end, you first create a
1149 `ui_stream' object by calling `ui_out_stream_new', pass the `stream'
1150 member of that `ui_stream' object to `value_print' and similar
1151 functions, and finally call `ui_out_field_stream' to output the field
1152 you constructed. When the `ui_stream' object is no longer needed, you
1153 should destroy it and free its memory by calling `ui_out_stream_delete'.
1155 -- Function: struct ui_stream *ui_out_stream_new (struct ui_out *UIOUT)
1156 This function creates a new `ui_stream' object which uses the same
1157 output methods as the `ui_out' object whose pointer is passed in
1158 UIOUT. It returns a pointer to the newly created `ui_stream'
1161 -- Function: void ui_out_stream_delete (struct ui_stream *STREAMBUF)
1162 This functions destroys a `ui_stream' object specified by
1165 -- Function: void ui_out_field_stream (struct ui_out *UIOUT, const
1166 char *FIELDNAME, struct ui_stream *STREAMBUF)
1167 This function consumes all the data accumulated in
1168 `streambuf->stream' and outputs it like `ui_out_field_string'
1169 does. After a call to `ui_out_field_stream', the accumulated data
1170 no longer exists, but the stream is still valid and may be used
1171 for producing more fields.
1173 *Important:* If there is any chance that your code could bail out
1174 before completing output generation and reaching the point where
1175 `ui_out_stream_delete' is called, it is necessary to set up a cleanup,
1176 to avoid leaking memory and other resources. Here's a skeleton code to
1179 struct ui_stream *mybuf = ui_out_stream_new (uiout);
1180 struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf);
1184 If the function already has the old cleanup chain set (for other
1185 kinds of cleanups), you just have to add your cleanup to it:
1187 mybuf = ui_out_stream_new (uiout);
1188 make_cleanup (ui_out_stream_delete, mybuf);
1190 Note that with cleanups in place, you should not call
1191 `ui_out_stream_delete' directly, or you would attempt to free the same
1194 4.2.5 Utility Output Functions
1195 ------------------------------
1197 -- Function: void ui_out_field_skip (struct ui_out *UIOUT, const char
1199 This function skips a field in a table. Use it if you have to
1200 leave an empty field without disrupting the table alignment. The
1201 argument FLDNAME specifies a name for the (missing) filed.
1203 -- Function: void ui_out_text (struct ui_out *UIOUT, const char
1205 This function outputs the text in STRING in a way that makes it
1206 easy to be read by humans. For example, the console
1207 implementation of this method filters the text through a built-in
1208 pager, to prevent it from scrolling off the visible portion of the
1211 Use this function for printing relatively long chunks of text
1212 around the actual field data: the text it produces is not aligned
1213 according to the table's format. Use `ui_out_field_string' to
1214 output a string field, and use `ui_out_message', described below,
1215 to output short messages.
1217 -- Function: void ui_out_spaces (struct ui_out *UIOUT, int NSPACES)
1218 This function outputs NSPACES spaces. It is handy to align the
1219 text produced by `ui_out_text' with the rest of the table or list.
1221 -- Function: void ui_out_message (struct ui_out *UIOUT, int VERBOSITY,
1222 const char *FORMAT, ...)
1223 This function produces a formatted message, provided that the
1224 current verbosity level is at least as large as given by
1225 VERBOSITY. The current verbosity level is specified by the user
1226 with the `set verbositylevel' command.(2)
1228 -- Function: void ui_out_wrap_hint (struct ui_out *UIOUT, char *INDENT)
1229 This function gives the console output filter (a paging filter) a
1230 hint of where to break lines which are too long. Ignored for all
1231 other output consumers. INDENT, if non-`NULL', is the string to
1232 be printed to indent the wrapped text on the next line; it must
1233 remain accessible until the next call to `ui_out_wrap_hint', or
1234 until an explicit newline is produced by one of the other
1235 functions. If INDENT is `NULL', the wrapped text will not be
1238 -- Function: void ui_out_flush (struct ui_out *UIOUT)
1239 This function flushes whatever output has been accumulated so far,
1240 if the UI buffers output.
1242 4.2.6 Examples of Use of `ui_out' functions
1243 -------------------------------------------
1245 This section gives some practical examples of using the `ui_out'
1246 functions to generalize the old console-oriented code in GDB. The
1247 examples all come from functions defined on the `breakpoints.c' file.
1249 This example, from the `breakpoint_1' function, shows how to produce
1252 The original code was:
1254 if (!found_a_breakpoint++)
1256 annotate_breakpoints_headers ();
1259 printf_filtered ("Num ");
1261 printf_filtered ("Type ");
1263 printf_filtered ("Disp ");
1265 printf_filtered ("Enb ");
1269 printf_filtered ("Address ");
1272 printf_filtered ("What\n");
1274 annotate_breakpoints_table ();
1277 Here's the new version:
1279 nr_printable_breakpoints = ...;
1282 ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable");
1284 ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable");
1286 if (nr_printable_breakpoints > 0)
1287 annotate_breakpoints_headers ();
1288 if (nr_printable_breakpoints > 0)
1290 ui_out_table_header (uiout, 3, ui_left, "number", "Num"); /* 1 */
1291 if (nr_printable_breakpoints > 0)
1293 ui_out_table_header (uiout, 14, ui_left, "type", "Type"); /* 2 */
1294 if (nr_printable_breakpoints > 0)
1296 ui_out_table_header (uiout, 4, ui_left, "disp", "Disp"); /* 3 */
1297 if (nr_printable_breakpoints > 0)
1299 ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb"); /* 4 */
1302 if (nr_printable_breakpoints > 0)
1304 if (TARGET_ADDR_BIT <= 32)
1305 ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */
1307 ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */
1309 if (nr_printable_breakpoints > 0)
1311 ui_out_table_header (uiout, 40, ui_noalign, "what", "What"); /* 6 */
1312 ui_out_table_body (uiout);
1313 if (nr_printable_breakpoints > 0)
1314 annotate_breakpoints_table ();
1316 This example, from the `print_one_breakpoint' function, shows how to
1317 produce the actual data for the table whose structure was defined in
1318 the above example. The original code was:
1322 printf_filtered ("%-3d ", b->number);
1324 if ((int)b->type > (sizeof(bptypes)/sizeof(bptypes[0]))
1325 || ((int) b->type != bptypes[(int) b->type].type))
1326 internal_error ("bptypes table does not describe type #%d.",
1328 printf_filtered ("%-14s ", bptypes[(int)b->type].description);
1330 printf_filtered ("%-4s ", bpdisps[(int)b->disposition]);
1332 printf_filtered ("%-3c ", bpenables[(int)b->enable]);
1335 This is the new version:
1338 ui_out_tuple_begin (uiout, "bkpt");
1340 ui_out_field_int (uiout, "number", b->number);
1342 if (((int) b->type > (sizeof (bptypes) / sizeof (bptypes[0])))
1343 || ((int) b->type != bptypes[(int) b->type].type))
1344 internal_error ("bptypes table does not describe type #%d.",
1346 ui_out_field_string (uiout, "type", bptypes[(int)b->type].description);
1348 ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]);
1350 ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);
1353 This example, also from `print_one_breakpoint', shows how to produce
1354 a complicated output field using the `print_expression' functions which
1355 requires a stream to be passed. It also shows how to automate stream
1356 destruction with cleanups. The original code was:
1359 print_expression (b->exp, gdb_stdout);
1363 struct ui_stream *stb = ui_out_stream_new (uiout);
1364 struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb);
1367 print_expression (b->exp, stb->stream);
1368 ui_out_field_stream (uiout, "what", local_stream);
1370 This example, also from `print_one_breakpoint', shows how to use
1371 `ui_out_text' and `ui_out_field_string'. The original code was:
1374 if (b->dll_pathname == NULL)
1375 printf_filtered ("<any library> ");
1377 printf_filtered ("library \"%s\" ", b->dll_pathname);
1382 if (b->dll_pathname == NULL)
1384 ui_out_field_string (uiout, "what", "<any library>");
1385 ui_out_spaces (uiout, 1);
1389 ui_out_text (uiout, "library \"");
1390 ui_out_field_string (uiout, "what", b->dll_pathname);
1391 ui_out_text (uiout, "\" ");
1394 The following example from `print_one_breakpoint' shows how to use
1395 `ui_out_field_int' and `ui_out_spaces'. The original code was:
1398 if (b->forked_inferior_pid != 0)
1399 printf_filtered ("process %d ", b->forked_inferior_pid);
1404 if (b->forked_inferior_pid != 0)
1406 ui_out_text (uiout, "process ");
1407 ui_out_field_int (uiout, "what", b->forked_inferior_pid);
1408 ui_out_spaces (uiout, 1);
1411 Here's an example of using `ui_out_field_string'. The original code
1415 if (b->exec_pathname != NULL)
1416 printf_filtered ("program \"%s\" ", b->exec_pathname);
1421 if (b->exec_pathname != NULL)
1423 ui_out_text (uiout, "program \"");
1424 ui_out_field_string (uiout, "what", b->exec_pathname);
1425 ui_out_text (uiout, "\" ");
1428 Finally, here's an example of printing an address. The original
1432 printf_filtered ("%s ",
1433 hex_string_custom ((unsigned long) b->address, 8));
1438 ui_out_field_core_addr (uiout, "Address", b->address);
1440 4.3 Console Printing
1441 ====================
1446 ---------- Footnotes ----------
1448 (1) The function cast is not portable ISO C.
1450 (2) As of this writing (April 2001), setting verbosity level is not
1451 yet implemented, and is always returned as zero. So calling
1452 `ui_out_message' with a VERBOSITY argument more than zero will cause
1453 the message to never be printed.
1456 File: gdbint.info, Node: libgdb, Next: Symbol Handling, Prev: User Interface, Up: Top
1464 `libgdb' 1.0 was an abortive project of years ago. The theory was to
1465 provide an API to GDB's functionality.
1470 `libgdb' 2.0 is an ongoing effort to update GDB so that is better able
1471 to support graphical and other environments.
1473 Since `libgdb' development is on-going, its architecture is still
1474 evolving. The following components have so far been identified:
1476 * Observer - `gdb-events.h'.
1478 * Builder - `ui-out.h'
1480 * Event Loop - `event-loop.h'
1484 The model that ties these components together is described below.
1486 5.3 The `libgdb' Model
1487 ======================
1489 A client of `libgdb' interacts with the library in two ways.
1491 * As an observer (using `gdb-events') receiving notifications from
1492 `libgdb' of any internal state changes (break point changes, run
1495 * As a client querying `libgdb' (using the `ui-out' builder) to
1496 obtain various status values from GDB.
1498 Since `libgdb' could have multiple clients (e.g., a GUI supporting
1499 the existing GDB CLI), those clients must co-operate when controlling
1500 `libgdb'. In particular, a client must ensure that `libgdb' is idle
1501 (i.e. no other client is using `libgdb') before responding to a
1502 `gdb-event' by making a query.
1507 At present GDB's CLI is very much entangled in with the core of
1508 `libgdb'. Consequently, a client wishing to include the CLI in their
1509 interface needs to carefully co-ordinate its own and the CLI's
1512 It is suggested that the client set `libgdb' up to be bi-modal
1513 (alternate between CLI and client query modes). The notes below sketch
1516 * The client registers itself as an observer of `libgdb'.
1518 * The client create and install `cli-out' builder using its own
1519 versions of the `ui-file' `gdb_stderr', `gdb_stdtarg' and
1520 `gdb_stdout' streams.
1522 * The client creates a separate custom `ui-out' builder that is only
1523 used while making direct queries to `libgdb'.
1525 When the client receives input intended for the CLI, it simply
1526 passes it along. Since the `cli-out' builder is installed by default,
1527 all the CLI output in response to that command is routed (pronounced
1528 rooted) through to the client controlled `gdb_stdout' et. al. streams.
1529 At the same time, the client is kept abreast of internal changes by
1530 virtue of being a `libgdb' observer.
1532 The only restriction on the client is that it must wait until
1533 `libgdb' becomes idle before initiating any queries (using the client's
1536 5.5 `libgdb' components
1537 =======================
1539 Observer - `gdb-events.h'
1540 -------------------------
1542 `gdb-events' provides the client with a very raw mechanism that can be
1543 used to implement an observer. At present it only allows for one
1544 observer and that observer must, internally, handle the need to delay
1545 the processing of any event notifications until after `libgdb' has
1546 finished the current command.
1548 Builder - `ui-out.h'
1549 --------------------
1551 `ui-out' provides the infrastructure necessary for a client to create a
1552 builder. That builder is then passed down to `libgdb' when doing any
1555 Event Loop - `event-loop.h'
1556 ---------------------------
1558 `event-loop', currently non-re-entrant, provides a simple event loop.
1559 A client would need to either plug its self into this loop or,
1560 implement a new event-loop that GDB would use.
1562 The event-loop will eventually be made re-entrant. This is so that
1563 GDB can better handle the problem of some commands blocking instead of
1569 `libgdb' is the most obvious component of this system. It provides the
1570 query interface. Each function is parameterized by a `ui-out' builder.
1571 The result of the query is constructed using that builder before the
1572 query function returns.
1575 File: gdbint.info, Node: Symbol Handling, Next: Language Support, Prev: libgdb, Up: Top
1580 Symbols are a key part of GDB's operation. Symbols include variables,
1581 functions, and types.
1586 GDB reads symbols from "symbol files". The usual symbol file is the
1587 file containing the program which GDB is debugging. GDB can be
1588 directed to use a different file for symbols (with the `symbol-file'
1589 command), and it can also read more symbols via the `add-file' and
1590 `load' commands, or while reading symbols from shared libraries.
1592 Symbol files are initially opened by code in `symfile.c' using the
1593 BFD library (*note Support Libraries::). BFD identifies the type of
1594 the file by examining its header. `find_sym_fns' then uses this
1595 identification to locate a set of symbol-reading functions.
1597 Symbol-reading modules identify themselves to GDB by calling
1598 `add_symtab_fns' during their module initialization. The argument to
1599 `add_symtab_fns' is a `struct sym_fns' which contains the name (or name
1600 prefix) of the symbol format, the length of the prefix, and pointers to
1601 four functions. These functions are called at various times to process
1602 symbol files whose identification matches the specified prefix.
1604 The functions supplied by each module are:
1606 `XYZ_symfile_init(struct sym_fns *sf)'
1607 Called from `symbol_file_add' when we are about to read a new
1608 symbol file. This function should clean up any internal state
1609 (possibly resulting from half-read previous files, for example)
1610 and prepare to read a new symbol file. Note that the symbol file
1611 which we are reading might be a new "main" symbol file, or might
1612 be a secondary symbol file whose symbols are being added to the
1613 existing symbol table.
1615 The argument to `XYZ_symfile_init' is a newly allocated `struct
1616 sym_fns' whose `bfd' field contains the BFD for the new symbol
1617 file being read. Its `private' field has been zeroed, and can be
1618 modified as desired. Typically, a struct of private information
1619 will be `malloc''d, and a pointer to it will be placed in the
1622 There is no result from `XYZ_symfile_init', but it can call
1623 `error' if it detects an unavoidable problem.
1626 Called from `symbol_file_add' when discarding existing symbols.
1627 This function needs only handle the symbol-reading module's
1628 internal state; the symbol table data structures visible to the
1629 rest of GDB will be discarded by `symbol_file_add'. It has no
1630 arguments and no result. It may be called after
1631 `XYZ_symfile_init', if a new symbol table is being read, or may be
1632 called alone if all symbols are simply being discarded.
1634 `XYZ_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)'
1635 Called from `symbol_file_add' to actually read the symbols from a
1636 symbol-file into a set of psymtabs or symtabs.
1638 `sf' points to the `struct sym_fns' originally passed to
1639 `XYZ_sym_init' for possible initialization. `addr' is the offset
1640 between the file's specified start address and its true address in
1641 memory. `mainline' is 1 if this is the main symbol table being
1642 read, and 0 if a secondary symbol file (e.g., shared library or
1643 dynamically loaded file) is being read.
1645 In addition, if a symbol-reading module creates psymtabs when
1646 XYZ_symfile_read is called, these psymtabs will contain a pointer to a
1647 function `XYZ_psymtab_to_symtab', which can be called from any point in
1648 the GDB symbol-handling code.
1650 `XYZ_psymtab_to_symtab (struct partial_symtab *pst)'
1651 Called from `psymtab_to_symtab' (or the `PSYMTAB_TO_SYMTAB' macro)
1652 if the psymtab has not already been read in and had its
1653 `pst->symtab' pointer set. The argument is the psymtab to be
1654 fleshed-out into a symtab. Upon return, `pst->readin' should have
1655 been set to 1, and `pst->symtab' should contain a pointer to the
1656 new corresponding symtab, or zero if there were no symbols in that
1657 part of the symbol file.
1659 6.2 Partial Symbol Tables
1660 =========================
1662 GDB has three types of symbol tables:
1664 * Full symbol tables ("symtabs"). These contain the main
1665 information about symbols and addresses.
1667 * Partial symbol tables ("psymtabs"). These contain enough
1668 information to know when to read the corresponding part of the full
1671 * Minimal symbol tables ("msymtabs"). These contain information
1672 gleaned from non-debugging symbols.
1674 This section describes partial symbol tables.
1676 A psymtab is constructed by doing a very quick pass over an
1677 executable file's debugging information. Small amounts of information
1678 are extracted--enough to identify which parts of the symbol table will
1679 need to be re-read and fully digested later, when the user needs the
1680 information. The speed of this pass causes GDB to start up very
1681 quickly. Later, as the detailed rereading occurs, it occurs in small
1682 pieces, at various times, and the delay therefrom is mostly invisible to
1685 The symbols that show up in a file's psymtab should be, roughly,
1686 those visible to the debugger's user when the program is not running
1687 code from that file. These include external symbols and types, static
1688 symbols and types, and `enum' values declared at file scope.
1690 The psymtab also contains the range of instruction addresses that the
1691 full symbol table would represent.
1693 The idea is that there are only two ways for the user (or much of the
1694 code in the debugger) to reference a symbol:
1696 * By its address (e.g., execution stops at some address which is
1697 inside a function in this file). The address will be noticed to
1698 be in the range of this psymtab, and the full symtab will be read
1699 in. `find_pc_function', `find_pc_line', and other `find_pc_...'
1700 functions handle this.
1702 * By its name (e.g., the user asks to print a variable, or set a
1703 breakpoint on a function). Global names and file-scope names will
1704 be found in the psymtab, which will cause the symtab to be pulled
1705 in. Local names will have to be qualified by a global name, or a
1706 file-scope name, in which case we will have already read in the
1707 symtab as we evaluated the qualifier. Or, a local symbol can be
1708 referenced when we are "in" a local scope, in which case the first
1709 case applies. `lookup_symbol' does most of the work here.
1711 The only reason that psymtabs exist is to cause a symtab to be read
1712 in at the right moment. Any symbol that can be elided from a psymtab,
1713 while still causing that to happen, should not appear in it. Since
1714 psymtabs don't have the idea of scope, you can't put local symbols in
1715 them anyway. Psymtabs don't have the idea of the type of a symbol,
1716 either, so types need not appear, unless they will be referenced by
1719 It is a bug for GDB to behave one way when only a psymtab has been
1720 read, and another way if the corresponding symtab has been read in.
1721 Such bugs are typically caused by a psymtab that does not contain all
1722 the visible symbols, or which has the wrong instruction address ranges.
1724 The psymtab for a particular section of a symbol file (objfile)
1725 could be thrown away after the symtab has been read in. The symtab
1726 should always be searched before the psymtab, so the psymtab will never
1727 be used (in a bug-free environment). Currently, psymtabs are allocated
1728 on an obstack, and all the psymbols themselves are allocated in a pair
1729 of large arrays on an obstack, so there is little to be gained by
1730 trying to free them unless you want to do a lot more work.
1735 Fundamental Types (e.g., `FT_VOID', `FT_BOOLEAN').
1736 --------------------------------------------------
1738 These are the fundamental types that GDB uses internally. Fundamental
1739 types from the various debugging formats (stabs, ELF, etc) are mapped
1740 into one of these. They are basically a union of all fundamental types
1741 that GDB knows about for all the languages that GDB knows about.
1743 Type Codes (e.g., `TYPE_CODE_PTR', `TYPE_CODE_ARRAY').
1744 ------------------------------------------------------
1746 Each time GDB builds an internal type, it marks it with one of these
1747 types. The type may be a fundamental type, such as `TYPE_CODE_INT', or
1748 a derived type, such as `TYPE_CODE_PTR' which is a pointer to another
1749 type. Typically, several `FT_*' types map to one `TYPE_CODE_*' type,
1750 and are distinguished by other members of the type struct, such as
1751 whether the type is signed or unsigned, and how many bits it uses.
1753 Builtin Types (e.g., `builtin_type_void', `builtin_type_char').
1754 ---------------------------------------------------------------
1756 These are instances of type structs that roughly correspond to
1757 fundamental types and are created as global types for GDB to use for
1758 various ugly historical reasons. We eventually want to eliminate
1759 these. Note for example that `builtin_type_int' initialized in
1760 `gdbtypes.c' is basically the same as a `TYPE_CODE_INT' type that is
1761 initialized in `c-lang.c' for an `FT_INTEGER' fundamental type. The
1762 difference is that the `builtin_type' is not associated with any
1763 particular objfile, and only one instance exists, while `c-lang.c'
1764 builds as many `TYPE_CODE_INT' types as needed, with each one
1765 associated with some particular objfile.
1767 6.4 Object File Formats
1768 =======================
1773 The `a.out' format is the original file format for Unix. It consists
1774 of three sections: `text', `data', and `bss', which are for program
1775 code, initialized data, and uninitialized data, respectively.
1777 The `a.out' format is so simple that it doesn't have any reserved
1778 place for debugging information. (Hey, the original Unix hackers used
1779 `adb', which is a machine-language debugger!) The only debugging
1780 format for `a.out' is stabs, which is encoded as a set of normal
1781 symbols with distinctive attributes.
1783 The basic `a.out' reader is in `dbxread.c'.
1788 The COFF format was introduced with System V Release 3 (SVR3) Unix.
1789 COFF files may have multiple sections, each prefixed by a header. The
1790 number of sections is limited.
1792 The COFF specification includes support for debugging. Although this
1793 was a step forward, the debugging information was woefully limited. For
1794 instance, it was not possible to represent code that came from an
1797 The COFF reader is in `coffread.c'.
1802 ECOFF is an extended COFF originally introduced for Mips and Alpha
1805 The basic ECOFF reader is in `mipsread.c'.
1810 The IBM RS/6000 running AIX uses an object file format called XCOFF.
1811 The COFF sections, symbols, and line numbers are used, but debugging
1812 symbols are `dbx'-style stabs whose strings are located in the `.debug'
1813 section (rather than the string table). For more information, see
1814 *Note Top: (stabs)Top.
1816 The shared library scheme has a clean interface for figuring out what
1817 shared libraries are in use, but the catch is that everything which
1818 refers to addresses (symbol tables and breakpoints at least) needs to be
1819 relocated for both shared libraries and the main executable. At least
1820 using the standard mechanism this can only be done once the program has
1821 been run (or the core file has been read).
1826 Windows 95 and NT use the PE ("Portable Executable") format for their
1827 executables. PE is basically COFF with additional headers.
1829 While BFD includes special PE support, GDB needs only the basic COFF
1835 The ELF format came with System V Release 4 (SVR4) Unix. ELF is similar
1836 to COFF in being organized into a number of sections, but it removes
1837 many of COFF's limitations.
1839 The basic ELF reader is in `elfread.c'.
1844 SOM is HP's object file and debug format (not to be confused with IBM's
1845 SOM, which is a cross-language ABI).
1847 The SOM reader is in `hpread.c'.
1849 6.4.8 Other File Formats
1850 ------------------------
1852 Other file formats that have been supported by GDB include Netware
1853 Loadable Modules (`nlmread.c').
1855 6.5 Debugging File Formats
1856 ==========================
1858 This section describes characteristics of debugging information that
1859 are independent of the object file format.
1864 `stabs' started out as special symbols within the `a.out' format.
1865 Since then, it has been encapsulated into other file formats, such as
1868 While `dbxread.c' does some of the basic stab processing, including
1869 for encapsulated versions, `stabsread.c' does the real work.
1874 The basic COFF definition includes debugging information. The level of
1875 support is minimal and non-extensible, and is not often used.
1877 6.5.3 Mips debug (Third Eye)
1878 ----------------------------
1880 ECOFF includes a definition of a special debug format.
1882 The file `mdebugread.c' implements reading for this format.
1887 DWARF 1 is a debugging format that was originally designed to be used
1888 with ELF in SVR4 systems.
1890 The DWARF 1 reader is in `dwarfread.c'.
1895 DWARF 2 is an improved but incompatible version of DWARF 1.
1897 The DWARF 2 reader is in `dwarf2read.c'.
1902 Like COFF, the SOM definition includes debugging information.
1904 6.6 Adding a New Symbol Reader to GDB
1905 =====================================
1907 If you are using an existing object file format (`a.out', COFF, ELF,
1908 etc), there is probably little to be done.
1910 If you need to add a new object file format, you must first add it to
1911 BFD. This is beyond the scope of this document.
1913 You must then arrange for the BFD code to provide access to the
1914 debugging symbols. Generally GDB will have to call swapping routines
1915 from BFD and a few other BFD internal routines to locate the debugging
1916 information. As much as possible, GDB should not depend on the BFD
1917 internal data structures.
1919 For some targets (e.g., COFF), there is a special transfer vector
1920 used to call swapping routines, since the external data structures on
1921 various platforms have different sizes and layouts. Specialized
1922 routines that will only ever be implemented by one object file format
1923 may be called directly. This interface should be described in a file
1924 `bfd/libXYZ.h', which is included by GDB.
1926 6.7 Memory Management for Symbol Files
1927 ======================================
1929 Most memory associated with a loaded symbol file is stored on its
1930 `objfile_obstack'. This includes symbols, types, namespace data, and
1931 other information produced by the symbol readers.
1933 Because this data lives on the objfile's obstack, it is automatically
1934 released when the objfile is unloaded or reloaded. Therefore one
1935 objfile must not reference symbol or type data from another objfile;
1936 they could be unloaded at different times.
1938 User convenience variables, et cetera, have associated types.
1939 Normally these types live in the associated objfile. However, when the
1940 objfile is unloaded, those types are deep copied to global memory, so
1941 that the values of the user variables and history items are not lost.
1944 File: gdbint.info, Node: Language Support, Next: Host Definition, Prev: Symbol Handling, Up: Top
1949 GDB's language support is mainly driven by the symbol reader, although
1950 it is possible for the user to set the source language manually.
1952 GDB chooses the source language by looking at the extension of the
1953 file recorded in the debug info; `.c' means C, `.f' means Fortran, etc.
1954 It may also use a special-purpose language identifier if the debug
1955 format supports it, like with DWARF.
1957 7.1 Adding a Source Language to GDB
1958 ===================================
1960 To add other languages to GDB's expression parser, follow the following
1963 _Create the expression parser._
1964 This should reside in a file `LANG-exp.y'. Routines for building
1965 parsed expressions into a `union exp_element' list are in
1968 Since we can't depend upon everyone having Bison, and YACC produces
1969 parsers that define a bunch of global names, the following lines
1970 *must* be included at the top of the YACC parser, to prevent the
1971 various parsers from defining the same global names:
1973 #define yyparse LANG_parse
1974 #define yylex LANG_lex
1975 #define yyerror LANG_error
1976 #define yylval LANG_lval
1977 #define yychar LANG_char
1978 #define yydebug LANG_debug
1979 #define yypact LANG_pact
1980 #define yyr1 LANG_r1
1981 #define yyr2 LANG_r2
1982 #define yydef LANG_def
1983 #define yychk LANG_chk
1984 #define yypgo LANG_pgo
1985 #define yyact LANG_act
1986 #define yyexca LANG_exca
1987 #define yyerrflag LANG_errflag
1988 #define yynerrs LANG_nerrs
1990 At the bottom of your parser, define a `struct language_defn' and
1991 initialize it with the right values for your language. Define an
1992 `initialize_LANG' routine and have it call
1993 `add_language(LANG_language_defn)' to tell the rest of GDB that
1994 your language exists. You'll need some other supporting variables
1995 and functions, which will be used via pointers from your
1996 `LANG_language_defn'. See the declaration of `struct
1997 language_defn' in `language.h', and the other `*-exp.y' files, for
2000 _Add any evaluation routines, if necessary_
2001 If you need new opcodes (that represent the operations of the
2002 language), add them to the enumerated type in `expression.h'. Add
2003 support code for these operations in the `evaluate_subexp' function
2004 defined in the file `eval.c'. Add cases for new opcodes in two
2005 functions from `parse.c': `prefixify_subexp' and
2006 `length_of_subexp'. These compute the number of `exp_element's
2007 that a given operation takes up.
2009 _Update some existing code_
2010 Add an enumerated identifier for your language to the enumerated
2011 type `enum language' in `defs.h'.
2013 Update the routines in `language.c' so your language is included.
2014 These routines include type predicates and such, which (in some
2015 cases) are language dependent. If your language does not appear
2016 in the switch statement, an error is reported.
2018 Also included in `language.c' is the code that updates the variable
2019 `current_language', and the routines that translate the
2020 `language_LANG' enumerated identifier into a printable string.
2022 Update the function `_initialize_language' to include your
2023 language. This function picks the default language upon startup,
2024 so is dependent upon which languages that GDB is built for.
2026 Update `allocate_symtab' in `symfile.c' and/or symbol-reading code
2027 so that the language of each symtab (source file) is set properly.
2028 This is used to determine the language to use at each stack frame
2029 level. Currently, the language is set based upon the extension of
2030 the source file. If the language can be better inferred from the
2031 symbol information, please set the language of the symtab in the
2032 symbol-reading code.
2034 Add helper code to `print_subexp' (in `expprint.c') to handle any
2035 new expression opcodes you have added to `expression.h'. Also,
2036 add the printed representations of your operators to
2039 _Add a place of call_
2040 Add a call to `LANG_parse()' and `LANG_error' in `parse_exp_1'
2041 (defined in `parse.c').
2043 _Use macros to trim code_
2044 The user has the option of building GDB for some or all of the
2045 languages. If the user decides to build GDB for the language
2046 LANG, then every file dependent on `language.h' will have the
2047 macro `_LANG_LANG' defined in it. Use `#ifdef's to leave out
2048 large routines that the user won't need if he or she is not using
2051 Note that you do not need to do this in your YACC parser, since if
2052 GDB is not build for LANG, then `LANG-exp.tab.o' (the compiled
2053 form of your parser) is not linked into GDB at all.
2055 See the file `configure.in' for how GDB is configured for
2056 different languages.
2058 _Edit `Makefile.in'_
2059 Add dependencies in `Makefile.in'. Make sure you update the macro
2060 variables such as `HFILES' and `OBJS', otherwise your code may not
2061 get linked in, or, worse yet, it may not get `tar'red into the
2065 File: gdbint.info, Node: Host Definition, Next: Target Architecture Definition, Prev: Language Support, Up: Top
2070 With the advent of Autoconf, it's rarely necessary to have host
2071 definition machinery anymore. The following information is provided,
2072 mainly, as an historical reference.
2074 8.1 Adding a New Host
2075 =====================
2077 GDB's host configuration support normally happens via Autoconf. New
2078 host-specific definitions should not be needed. Older hosts GDB still
2079 use the host-specific definitions and files listed below, but these
2080 mostly exist for historical reasons, and will eventually disappear.
2082 `gdb/config/ARCH/XYZ.mh'
2083 This file once contained both host and native configuration
2084 information (*note Native Debugging::) for the machine XYZ. The
2085 host configuration information is now handed by Autoconf.
2087 Host configuration information included a definition of
2088 `XM_FILE=xm-XYZ.h' and possibly definitions for `CC',
2089 `SYSV_DEFINE', `XM_CFLAGS', `XM_ADD_FILES', `XM_CLIBS',
2090 `XM_CDEPS', etc.; see `Makefile.in'.
2092 New host only configurations do not need this file.
2094 `gdb/config/ARCH/xm-XYZ.h'
2095 This file once contained definitions and includes required when
2096 hosting gdb on machine XYZ. Those definitions and includes are now
2097 handled by Autoconf.
2099 New host and native configurations do not need this file.
2101 _Maintainer's note: Some hosts continue to use the `xm-xyz.h' file
2102 to define the macros HOST_FLOAT_FORMAT, HOST_DOUBLE_FORMAT and
2103 HOST_LONG_DOUBLE_FORMAT. That code also needs to be replaced with
2104 either an Autoconf or run-time test._
2107 Generic Host Support Files
2108 --------------------------
2110 There are some "generic" versions of routines that can be used by
2111 various systems. These can be customized in various ways by macros
2112 defined in your `xm-XYZ.h' file. If these routines work for the XYZ
2113 host, you can just include the generic file's name (with `.o', not
2114 `.c') in `XDEPFILES'.
2116 Otherwise, if your machine needs custom support routines, you will
2117 need to write routines that perform the same functions as the generic
2118 file. Put them into `XYZ-xdep.c', and put `XYZ-xdep.o' into
2122 This contains serial line support for Unix systems. This is always
2123 included, via the makefile variable `SER_HARDWIRE'; override this
2124 variable in the `.mh' file to avoid it.
2127 This contains serial line support for 32-bit programs running
2128 under DOS, using the DJGPP (a.k.a. GO32) execution environment.
2131 This contains generic TCP support using sockets.
2133 8.2 Host Conditionals
2134 =====================
2136 When GDB is configured and compiled, various macros are defined or left
2137 undefined, to control compilation based on the attributes of the host
2138 system. These macros and their meanings (or if the meaning is not
2139 documented here, then one of the source files where they are used is
2143 The default name of GDB's initialization file (normally
2147 This macro is deprecated.
2150 If your host defines `SIGWINCH', you can define this to be the name
2151 of a function to be called if `SIGWINCH' is received.
2153 `SIGWINCH_HANDLER_BODY'
2154 Define this to expand into code that will define the function
2155 named by the expansion of `SIGWINCH_HANDLER'.
2157 `ALIGN_STACK_ON_STARTUP'
2158 Define this if your system is of a sort that will crash in
2159 `tgetent' if the stack happens not to be longword-aligned when
2160 `main' is called. This is a rare situation, but is known to occur
2161 on several different types of systems.
2164 Define this if host files use `\r\n' rather than `\n' as a line
2165 terminator. This will cause source file listings to omit `\r'
2166 characters when printing and it will allow `\r\n' line endings of
2167 files which are "sourced" by gdb. It must be possible to open
2168 files in binary mode using `O_BINARY' or, for fopen, `"rb"'.
2171 The default value of the prompt string (normally `"(gdb) "').
2174 The name of the generic TTY device, defaults to `"/dev/tty"'.
2177 Define this if binary files are opened the same way as text files.
2180 In some cases, use the system call `mmap' for reading symbol
2181 tables. For some machines this allows for sharing and quick
2185 Define this if the host system has `termio.h'.
2192 Values for host-side constants.
2195 Substitute for isatty, if not available.
2198 This is the longest integer type available on the host. If not
2199 defined, it will default to `long long' or `long', depending on
2203 Define this if the host C compiler supports `long long'. This is
2204 set by the `configure' script.
2206 `PRINTF_HAS_LONG_LONG'
2207 Define this if the host can handle printing of long long integers
2208 via the printf format conversion specifier `ll'. This is set by
2209 the `configure' script.
2212 Define this if the host C compiler supports `long double'. This is
2213 set by the `configure' script.
2215 `PRINTF_HAS_LONG_DOUBLE'
2216 Define this if the host can handle printing of long double
2217 float-point numbers via the printf format conversion specifier
2218 `Lg'. This is set by the `configure' script.
2220 `SCANF_HAS_LONG_DOUBLE'
2221 Define this if the host can handle the parsing of long double
2222 float-point numbers via the scanf format conversion specifier
2223 `Lg'. This is set by the `configure' script.
2226 Define this if `lseek (n)' does not necessarily move to byte number
2227 `n' in the file. This is only used when reading source files. It
2228 is normally faster to define `CRLF_SOURCE_FILES' when possible.
2231 This macro is used as the argument to `lseek' (or, most commonly,
2232 `bfd_seek'). FIXME, should be replaced by SEEK_SET instead, which
2233 is the POSIX equivalent.
2236 If defined, this should be one or more tokens, such as `volatile',
2237 that can be used in both the declaration and definition of
2238 functions to indicate that they never return. The default is
2239 already set correctly if compiling with GCC. This will almost
2240 never need to be defined.
2243 If defined, this should be one or more tokens, such as
2244 `__attribute__ ((noreturn))', that can be used in the declarations
2245 of functions to indicate that they never return. The default is
2246 already set correctly if compiling with GCC. This will almost
2247 never need to be defined.
2251 Define these to appropriate value for the system `lseek', if not
2255 This is the signal for stopping GDB. Defaults to `SIGTSTP'.
2256 (Only redefined for the Convex.)
2259 Means that System V (prior to SVR4) include files are in use.
2260 (FIXME: This symbol is abused in `infrun.c', `regex.c', and
2261 `utils.c' for other things, at the moment.)
2264 Define this to help placate `lint' in some situations.
2267 Define this to override the defaults of `__volatile__' or `/**/'.
2270 File: gdbint.info, Node: Target Architecture Definition, Next: Target Vector Definition, Prev: Host Definition, Up: Top
2272 9 Target Architecture Definition
2273 ********************************
2275 GDB's target architecture defines what sort of machine-language
2276 programs GDB can work with, and how it works with them.
2278 The target architecture object is implemented as the C structure
2279 `struct gdbarch *'. The structure, and its methods, are generated
2280 using the Bourne shell script `gdbarch.sh'.
2282 9.1 Operating System ABI Variant Handling
2283 =========================================
2285 GDB provides a mechanism for handling variations in OS ABIs. An OS ABI
2286 variant may have influence over any number of variables in the target
2287 architecture definition. There are two major components in the OS ABI
2288 mechanism: sniffers and handlers.
2290 A "sniffer" examines a file matching a BFD architecture/flavour pair
2291 (the architecture may be wildcarded) in an attempt to determine the OS
2292 ABI of that file. Sniffers with a wildcarded architecture are
2293 considered to be "generic", while sniffers for a specific architecture
2294 are considered to be "specific". A match from a specific sniffer
2295 overrides a match from a generic sniffer. Multiple sniffers for an
2296 architecture/flavour may exist, in order to differentiate between two
2297 different operating systems which use the same basic file format. The
2298 OS ABI framework provides a generic sniffer for ELF-format files which
2299 examines the `EI_OSABI' field of the ELF header, as well as note
2300 sections known to be used by several operating systems.
2302 A "handler" is used to fine-tune the `gdbarch' structure for the
2303 selected OS ABI. There may be only one handler for a given OS ABI for
2304 each BFD architecture.
2306 The following OS ABI variants are defined in `osabi.h':
2309 The ABI of the inferior is unknown. The default `gdbarch'
2310 settings for the architecture will be used.
2313 UNIX System V Release 4
2316 GNU using the Hurd kernel
2322 OSF/1, including Digital UNIX and Compaq Tru64 UNIX
2325 GNU using the Linux kernel
2327 `GDB_OSABI_FREEBSD_AOUT'
2328 FreeBSD using the a.out executable format
2330 `GDB_OSABI_FREEBSD_ELF'
2331 FreeBSD using the ELF executable format
2333 `GDB_OSABI_NETBSD_AOUT'
2334 NetBSD using the a.out executable format
2336 `GDB_OSABI_NETBSD_ELF'
2337 NetBSD using the ELF executable format
2348 `GDB_OSABI_ARM_EABI_V1'
2349 ARM Embedded ABI version 1
2351 `GDB_OSABI_ARM_EABI_V2'
2352 ARM Embedded ABI version 2
2354 `GDB_OSABI_ARM_APCS'
2355 Generic ARM Procedure Call Standard
2358 Here are the functions that make up the OS ABI framework:
2360 -- Function: const char *gdbarch_osabi_name (enum gdb_osabi OSABI)
2361 Return the name of the OS ABI corresponding to OSABI.
2363 -- Function: void gdbarch_register_osabi (enum bfd_architecture ARCH,
2364 unsigned long MACHINE, enum gdb_osabi OSABI, void
2365 (*INIT_OSABI)(struct gdbarch_info INFO, struct gdbarch
2367 Register the OS ABI handler specified by INIT_OSABI for the
2368 architecture, machine type and OS ABI specified by ARCH, MACHINE
2369 and OSABI. In most cases, a value of zero for the machine type,
2370 which implies the architecture's default machine type, will
2373 -- Function: void gdbarch_register_osabi_sniffer (enum
2374 bfd_architecture ARCH, enum bfd_flavour FLAVOUR, enum
2375 gdb_osabi (*SNIFFER)(bfd *ABFD))
2376 Register the OS ABI file sniffer specified by SNIFFER for the BFD
2377 architecture/flavour pair specified by ARCH and FLAVOUR. If ARCH
2378 is `bfd_arch_unknown', the sniffer is considered to be generic,
2379 and is allowed to examine FLAVOUR-flavoured files for any
2382 -- Function: enum gdb_osabi gdbarch_lookup_osabi (bfd *ABFD)
2383 Examine the file described by ABFD to determine its OS ABI. The
2384 value `GDB_OSABI_UNKNOWN' is returned if the OS ABI cannot be
2387 -- Function: void gdbarch_init_osabi (struct gdbarch info INFO, struct
2388 gdbarch *GDBARCH, enum gdb_osabi OSABI)
2389 Invoke the OS ABI handler corresponding to OSABI to fine-tune the
2390 `gdbarch' structure specified by GDBARCH. If a handler
2391 corresponding to OSABI has not been registered for GDBARCH's
2392 architecture, a warning will be issued and the debugging session
2393 will continue with the defaults already established for GDBARCH.
2395 9.2 Initializing a New Architecture
2396 ===================================
2398 Each `gdbarch' is associated with a single BFD architecture, via a
2399 `bfd_arch_ARCH' constant. The `gdbarch' is registered by a call to
2400 `register_gdbarch_init', usually from the file's `_initialize_FILENAME'
2401 routine, which will be automatically called during GDB startup. The
2402 arguments are a BFD architecture constant and an initialization
2405 The initialization function has this type:
2407 static struct gdbarch *
2408 ARCH_gdbarch_init (struct gdbarch_info INFO,
2409 struct gdbarch_list *ARCHES)
2411 The INFO argument contains parameters used to select the correct
2412 architecture, and ARCHES is a list of architectures which have already
2413 been created with the same `bfd_arch_ARCH' value.
2415 The initialization function should first make sure that INFO is
2416 acceptable, and return `NULL' if it is not. Then, it should search
2417 through ARCHES for an exact match to INFO, and return one if found.
2418 Lastly, if no exact match was found, it should create a new
2419 architecture based on INFO and return it.
2421 Only information in INFO should be used to choose the new
2422 architecture. Historically, INFO could be sparse, and defaults would
2423 be collected from the first element on ARCHES. However, GDB now fills
2424 in INFO more thoroughly, so new `gdbarch' initialization functions
2425 should not take defaults from ARCHES.
2427 9.3 Registers and Memory
2428 ========================
2430 GDB's model of the target machine is rather simple. GDB assumes the
2431 machine includes a bank of registers and a block of memory. Each
2432 register may have a different size.
2434 GDB does not have a magical way to match up with the compiler's idea
2435 of which registers are which; however, it is critical that they do
2436 match up accurately. The only way to make this work is to get accurate
2437 information about the order that the compiler uses, and to reflect that
2438 in the `REGISTER_NAME' and related macros.
2440 GDB can handle big-endian, little-endian, and bi-endian
2443 9.4 Pointers Are Not Always Addresses
2444 =====================================
2446 On almost all 32-bit architectures, the representation of a pointer is
2447 indistinguishable from the representation of some fixed-length number
2448 whose value is the byte address of the object pointed to. On such
2449 machines, the words "pointer" and "address" can be used interchangeably.
2450 However, architectures with smaller word sizes are often cramped for
2451 address space, so they may choose a pointer representation that breaks
2452 this identity, and allows a larger code address space.
2454 For example, the Renesas D10V is a 16-bit VLIW processor whose
2455 instructions are 32 bits long(1). If the D10V used ordinary byte
2456 addresses to refer to code locations, then the processor would only be
2457 able to address 64kb of instructions. However, since instructions must
2458 be aligned on four-byte boundaries, the low two bits of any valid
2459 instruction's byte address are always zero--byte addresses waste two
2460 bits. So instead of byte addresses, the D10V uses word addresses--byte
2461 addresses shifted right two bits--to refer to code. Thus, the D10V can
2462 use 16-bit words to address 256kb of code space.
2464 However, this means that code pointers and data pointers have
2465 different forms on the D10V. The 16-bit word `0xC020' refers to byte
2466 address `0xC020' when used as a data address, but refers to byte address
2467 `0x30080' when used as a code address.
2469 (The D10V also uses separate code and data address spaces, which also
2470 affects the correspondence between pointers and addresses, but we're
2471 going to ignore that here; this example is already too long.)
2473 To cope with architectures like this--the D10V is not the only
2474 one!--GDB tries to distinguish between "addresses", which are byte
2475 numbers, and "pointers", which are the target's representation of an
2476 address of a particular type of data. In the example above, `0xC020'
2477 is the pointer, which refers to one of the addresses `0xC020' or
2478 `0x30080', depending on the type imposed upon it. GDB provides
2479 functions for turning a pointer into an address and vice versa, in the
2480 appropriate way for the current architecture.
2482 Unfortunately, since addresses and pointers are identical on almost
2483 all processors, this distinction tends to bit-rot pretty quickly. Thus,
2484 each time you port GDB to an architecture which does distinguish
2485 between pointers and addresses, you'll probably need to clean up some
2486 architecture-independent code.
2488 Here are functions which convert between pointers and addresses:
2490 -- Function: CORE_ADDR extract_typed_address (void *BUF, struct type
2492 Treat the bytes at BUF as a pointer or reference of type TYPE, and
2493 return the address it represents, in a manner appropriate for the
2494 current architecture. This yields an address GDB can use to read
2495 target memory, disassemble, etc. Note that BUF refers to a buffer
2496 in GDB's memory, not the inferior's.
2498 For example, if the current architecture is the Intel x86, this
2499 function extracts a little-endian integer of the appropriate
2500 length from BUF and returns it. However, if the current
2501 architecture is the D10V, this function will return a 16-bit
2502 integer extracted from BUF, multiplied by four if TYPE is a
2503 pointer to a function.
2505 If TYPE is not a pointer or reference type, then this function
2506 will signal an internal error.
2508 -- Function: CORE_ADDR store_typed_address (void *BUF, struct type
2509 *TYPE, CORE_ADDR ADDR)
2510 Store the address ADDR in BUF, in the proper format for a pointer
2511 of type TYPE in the current architecture. Note that BUF refers to
2512 a buffer in GDB's memory, not the inferior's.
2514 For example, if the current architecture is the Intel x86, this
2515 function stores ADDR unmodified as a little-endian integer of the
2516 appropriate length in BUF. However, if the current architecture
2517 is the D10V, this function divides ADDR by four if TYPE is a
2518 pointer to a function, and then stores it in BUF.
2520 If TYPE is not a pointer or reference type, then this function
2521 will signal an internal error.
2523 -- Function: CORE_ADDR value_as_address (struct value *VAL)
2524 Assuming that VAL is a pointer, return the address it represents,
2525 as appropriate for the current architecture.
2527 This function actually works on integral values, as well as
2528 pointers. For pointers, it performs architecture-specific
2529 conversions as described above for `extract_typed_address'.
2531 -- Function: CORE_ADDR value_from_pointer (struct type *TYPE,
2533 Create and return a value representing a pointer of type TYPE to
2534 the address ADDR, as appropriate for the current architecture.
2535 This function performs architecture-specific conversions as
2536 described above for `store_typed_address'.
2538 Here are some macros which architectures can define to indicate the
2539 relationship between pointers and addresses. These have default
2540 definitions, appropriate for architectures on which all pointers are
2541 simple unsigned byte addresses.
2543 -- Target Macro: CORE_ADDR POINTER_TO_ADDRESS (struct type *TYPE, char
2545 Assume that BUF holds a pointer of type TYPE, in the appropriate
2546 format for the current architecture. Return the byte address the
2549 This function may safely assume that TYPE is either a pointer or a
2552 -- Target Macro: void ADDRESS_TO_POINTER (struct type *TYPE, char
2553 *BUF, CORE_ADDR ADDR)
2554 Store in BUF a pointer of type TYPE representing the address ADDR,
2555 in the appropriate format for the current architecture.
2557 This function may safely assume that TYPE is either a pointer or a
2563 Sometimes information about different kinds of addresses is available
2564 via the debug information. For example, some programming environments
2565 define addresses of several different sizes. If the debug information
2566 distinguishes these kinds of address classes through either the size
2567 info (e.g, `DW_AT_byte_size' in DWARF 2) or through an explicit address
2568 class attribute (e.g, `DW_AT_address_class' in DWARF 2), the following
2569 macros should be defined in order to disambiguate these types within
2570 GDB as well as provide the added information to a GDB user when
2571 printing type expressions.
2573 -- Target Macro: int ADDRESS_CLASS_TYPE_FLAGS (int BYTE_SIZE, int
2575 Returns the type flags needed to construct a pointer type whose
2576 size is BYTE_SIZE and whose address class is DWARF2_ADDR_CLASS.
2577 This function is normally called from within a symbol reader. See
2580 -- Target Macro: char *ADDRESS_CLASS_TYPE_FLAGS_TO_NAME (int
2582 Given the type flags representing an address class qualifier,
2585 -- Target Macro: int ADDRESS_CLASS_NAME_to_TYPE_FLAGS (int NAME, int
2587 Given an address qualifier name, set the `int' refererenced by
2588 TYPE_FLAGS_PTR to the type flags for that address class qualifier.
2590 Since the need for address classes is rather rare, none of the
2591 address class macros defined by default. Predicate macros are provided
2592 to detect when they are defined.
2594 Consider a hypothetical architecture in which addresses are normally
2595 32-bits wide, but 16-bit addresses are also supported. Furthermore,
2596 suppose that the DWARF 2 information for this architecture simply uses
2597 a `DW_AT_byte_size' value of 2 to indicate the use of one of these
2598 "short" pointers. The following functions could be defined to
2599 implement the address class macros:
2601 somearch_address_class_type_flags (int byte_size,
2602 int dwarf2_addr_class)
2605 return TYPE_FLAG_ADDRESS_CLASS_1;
2611 somearch_address_class_type_flags_to_name (int type_flags)
2613 if (type_flags & TYPE_FLAG_ADDRESS_CLASS_1)
2620 somearch_address_class_name_to_type_flags (char *name,
2621 int *type_flags_ptr)
2623 if (strcmp (name, "short") == 0)
2625 *type_flags_ptr = TYPE_FLAG_ADDRESS_CLASS_1;
2632 The qualifier `@short' is used in GDB's type expressions to indicate
2633 the presence of one of these "short" pointers. E.g, if the debug
2634 information indicates that `short_ptr_var' is one of these short
2635 pointers, GDB might show the following behavior:
2637 (gdb) ptype short_ptr_var
2640 9.6 Raw and Virtual Register Representations
2641 ============================================
2643 _Maintainer note: This section is pretty much obsolete. The
2644 functionality described here has largely been replaced by
2645 pseudo-registers and the mechanisms described in *Note Using Different
2646 Register and Memory Data Representations: Target Architecture
2647 Definition. See also Bug Tracking Database
2648 (http://www.gnu.org/software/gdb/bugs/) and ARI Index
2649 (http://sources.redhat.com/gdb/current/ari/) for more up-to-date
2652 Some architectures use one representation for a value when it lives
2653 in a register, but use a different representation when it lives in
2654 memory. In GDB's terminology, the "raw" representation is the one used
2655 in the target registers, and the "virtual" representation is the one
2656 used in memory, and within GDB `struct value' objects.
2658 _Maintainer note: Notice that the same mechanism is being used to
2659 both convert a register to a `struct value' and alternative register
2662 For almost all data types on almost all architectures, the virtual
2663 and raw representations are identical, and no special handling is
2664 needed. However, they do occasionally differ. For example:
2666 * The x86 architecture supports an 80-bit `long double' type.
2667 However, when we store those values in memory, they occupy twelve
2668 bytes: the floating-point number occupies the first ten, and the
2669 final two bytes are unused. This keeps the values aligned on
2670 four-byte boundaries, allowing more efficient access. Thus, the
2671 x86 80-bit floating-point type is the raw representation, and the
2672 twelve-byte loosely-packed arrangement is the virtual
2675 * Some 64-bit MIPS targets present 32-bit registers to GDB as 64-bit
2676 registers, with garbage in their upper bits. GDB ignores the top
2677 32 bits. Thus, the 64-bit form, with garbage in the upper 32
2678 bits, is the raw representation, and the trimmed 32-bit
2679 representation is the virtual representation.
2681 In general, the raw representation is determined by the
2682 architecture, or GDB's interface to the architecture, while the virtual
2683 representation can be chosen for GDB's convenience. GDB's register
2684 file, `registers', holds the register contents in raw format, and the
2685 GDB remote protocol transmits register values in raw format.
2687 Your architecture may define the following macros to request
2688 conversions between the raw and virtual format:
2690 -- Target Macro: int REGISTER_CONVERTIBLE (int REG)
2691 Return non-zero if register number REG's value needs different raw
2692 and virtual formats.
2694 You should not use `REGISTER_CONVERT_TO_VIRTUAL' for a register
2695 unless this macro returns a non-zero value for that register.
2697 -- Target Macro: int DEPRECATED_REGISTER_RAW_SIZE (int REG)
2698 The size of register number REG's raw value. This is the number
2699 of bytes the register will occupy in `registers', or in a GDB
2700 remote protocol packet.
2702 -- Target Macro: int DEPRECATED_REGISTER_VIRTUAL_SIZE (int REG)
2703 The size of register number REG's value, in its virtual format.
2704 This is the size a `struct value''s buffer will have, holding that
2707 -- Target Macro: struct type *DEPRECATED_REGISTER_VIRTUAL_TYPE (int
2709 This is the type of the virtual representation of register number
2710 REG. Note that there is no need for a macro giving a type for the
2711 register's raw form; once the register's value has been obtained,
2712 GDB always uses the virtual form.
2714 -- Target Macro: void REGISTER_CONVERT_TO_VIRTUAL (int REG, struct
2715 type *TYPE, char *FROM, char *TO)
2716 Convert the value of register number REG to TYPE, which should
2717 always be `DEPRECATED_REGISTER_VIRTUAL_TYPE (REG)'. The buffer at
2718 FROM holds the register's value in raw format; the macro should
2719 convert the value to virtual format, and place it at TO.
2721 Note that `REGISTER_CONVERT_TO_VIRTUAL' and
2722 `REGISTER_CONVERT_TO_RAW' take their REG and TYPE arguments in
2725 You should only use `REGISTER_CONVERT_TO_VIRTUAL' with registers
2726 for which the `REGISTER_CONVERTIBLE' macro returns a non-zero
2729 -- Target Macro: void REGISTER_CONVERT_TO_RAW (struct type *TYPE, int
2730 REG, char *FROM, char *TO)
2731 Convert the value of register number REG to TYPE, which should
2732 always be `DEPRECATED_REGISTER_VIRTUAL_TYPE (REG)'. The buffer at
2733 FROM holds the register's value in raw format; the macro should
2734 convert the value to virtual format, and place it at TO.
2736 Note that REGISTER_CONVERT_TO_VIRTUAL and REGISTER_CONVERT_TO_RAW
2737 take their REG and TYPE arguments in different orders.
2739 9.7 Using Different Register and Memory Data Representations
2740 ============================================================
2742 _Maintainer's note: The way GDB manipulates registers is undergoing
2743 significant change. Many of the macros and functions refered to in this
2744 section are likely to be subject to further revision. See A.R. Index
2745 (http://sources.redhat.com/gdb/current/ari/) and Bug Tracking Database
2746 (http://www.gnu.org/software/gdb/bugs) for further information.
2749 Some architectures can represent a data object in a register using a
2750 form that is different to the objects more normal memory representation.
2753 * The Alpha architecture can represent 32 bit integer values in
2754 floating-point registers.
2756 * The x86 architecture supports 80-bit floating-point registers. The
2757 `long double' data type occupies 96 bits in memory but only 80 bits
2758 when stored in a register.
2761 In general, the register representation of a data type is determined
2762 by the architecture, or GDB's interface to the architecture, while the
2763 memory representation is determined by the Application Binary Interface.
2765 For almost all data types on almost all architectures, the two
2766 representations are identical, and no special handling is needed.
2767 However, they do occasionally differ. Your architecture may define the
2768 following macros to request conversions between the register and memory
2769 representations of a data type:
2771 -- Target Macro: int CONVERT_REGISTER_P (int REG)
2772 Return non-zero if the representation of a data value stored in
2773 this register may be different to the representation of that same
2774 data value when stored in memory.
2776 When non-zero, the macros `REGISTER_TO_VALUE' and
2777 `VALUE_TO_REGISTER' are used to perform any necessary conversion.
2779 -- Target Macro: void REGISTER_TO_VALUE (int REG, struct type *TYPE,
2780 char *FROM, char *TO)
2781 Convert the value of register number REG to a data object of type
2782 TYPE. The buffer at FROM holds the register's value in raw
2783 format; the converted value should be placed in the buffer at TO.
2785 Note that `REGISTER_TO_VALUE' and `VALUE_TO_REGISTER' take their
2786 REG and TYPE arguments in different orders.
2788 You should only use `REGISTER_TO_VALUE' with registers for which
2789 the `CONVERT_REGISTER_P' macro returns a non-zero value.
2791 -- Target Macro: void VALUE_TO_REGISTER (struct type *TYPE, int REG,
2792 char *FROM, char *TO)
2793 Convert a data value of type TYPE to register number REG' raw
2796 Note that `REGISTER_TO_VALUE' and `VALUE_TO_REGISTER' take their
2797 REG and TYPE arguments in different orders.
2799 You should only use `VALUE_TO_REGISTER' with registers for which
2800 the `CONVERT_REGISTER_P' macro returns a non-zero value.
2802 -- Target Macro: void REGISTER_CONVERT_TO_TYPE (int REGNUM, struct
2803 type *TYPE, char *BUF)
2804 See `mips-tdep.c'. It does not do what you want.
2806 9.8 Frame Interpretation
2807 ========================
2809 9.9 Inferior Call Setup
2810 =======================
2812 9.10 Compiler Characteristics
2813 =============================
2815 9.11 Target Conditionals
2816 ========================
2818 This section describes the macros that you can use to define the target
2821 `ADDR_BITS_REMOVE (addr)'
2822 If a raw machine instruction address includes any bits that are not
2823 really part of the address, then define this macro to expand into
2824 an expression that zeroes those bits in ADDR. This is only used
2825 for addresses of instructions, and even then not in all contexts.
2827 For example, the two low-order bits of the PC on the
2828 Hewlett-Packard PA 2.0 architecture contain the privilege level of
2829 the corresponding instruction. Since instructions must always be
2830 aligned on four-byte boundaries, the processor masks out these
2831 bits to generate the actual address of the instruction.
2832 ADDR_BITS_REMOVE should filter out these bits with an expression
2833 such as `((addr) & ~3)'.
2835 `ADDRESS_CLASS_NAME_TO_TYPE_FLAGS (NAME, TYPE_FLAGS_PTR)'
2836 If NAME is a valid address class qualifier name, set the `int'
2837 referenced by TYPE_FLAGS_PTR to the mask representing the qualifier
2838 and return 1. If NAME is not a valid address class qualifier name,
2841 The value for TYPE_FLAGS_PTR should be one of
2842 `TYPE_FLAG_ADDRESS_CLASS_1', `TYPE_FLAG_ADDRESS_CLASS_2', or
2843 possibly some combination of these values or'd together. *Note
2844 Address Classes: Target Architecture Definition.
2846 `ADDRESS_CLASS_NAME_TO_TYPE_FLAGS_P ()'
2847 Predicate which indicates whether
2848 `ADDRESS_CLASS_NAME_TO_TYPE_FLAGS' has been defined.
2850 `ADDRESS_CLASS_TYPE_FLAGS (BYTE_SIZE, DWARF2_ADDR_CLASS)'
2851 Given a pointers byte size (as described by the debug information)
2852 and the possible `DW_AT_address_class' value, return the type flags
2853 used by GDB to represent this address class. The value returned
2854 should be one of `TYPE_FLAG_ADDRESS_CLASS_1',
2855 `TYPE_FLAG_ADDRESS_CLASS_2', or possibly some combination of these
2856 values or'd together. *Note Address Classes: Target Architecture
2859 `ADDRESS_CLASS_TYPE_FLAGS_P ()'
2860 Predicate which indicates whether `ADDRESS_CLASS_TYPE_FLAGS' has
2863 `ADDRESS_CLASS_TYPE_FLAGS_TO_NAME (TYPE_FLAGS)'
2864 Return the name of the address class qualifier associated with the
2865 type flags given by TYPE_FLAGS.
2867 `ADDRESS_CLASS_TYPE_FLAGS_TO_NAME_P ()'
2868 Predicate which indicates whether
2869 `ADDRESS_CLASS_TYPE_FLAGS_TO_NAME' has been defined. *Note
2870 Address Classes: Target Architecture Definition.
2872 `ADDRESS_TO_POINTER (TYPE, BUF, ADDR)'
2873 Store in BUF a pointer of type TYPE representing the address ADDR,
2874 in the appropriate format for the current architecture. This
2875 macro may safely assume that TYPE is either a pointer or a C++
2876 reference type. *Note Pointers Are Not Always Addresses: Target
2877 Architecture Definition.
2879 `BELIEVE_PCC_PROMOTION'
2880 Define if the compiler promotes a `short' or `char' parameter to
2881 an `int', but still reports the parameter as its original type,
2882 rather than the promoted type.
2885 Define this if the numbering of bits in the targets does *not*
2886 match the endianness of the target byte order. A value of 1 means
2887 that the bits are numbered in a big-endian bit order, 0 means
2891 This is the character array initializer for the bit pattern to put
2892 into memory where a breakpoint is set. Although it's common to
2893 use a trap instruction for a breakpoint, it's not required; for
2894 instance, the bit pattern could be an invalid instruction. The
2895 breakpoint must be no longer than the shortest instruction of the
2898 `BREAKPOINT' has been deprecated in favor of `BREAKPOINT_FROM_PC'.
2902 Similar to BREAKPOINT, but used for bi-endian targets.
2904 `BIG_BREAKPOINT' and `LITTLE_BREAKPOINT' have been deprecated in
2905 favor of `BREAKPOINT_FROM_PC'.
2907 `DEPRECATED_REMOTE_BREAKPOINT'
2908 `DEPRECATED_LITTLE_REMOTE_BREAKPOINT'
2909 `DEPRECATED_BIG_REMOTE_BREAKPOINT'
2910 Specify the breakpoint instruction sequence for a remote target.
2911 `DEPRECATED_REMOTE_BREAKPOINT', `DEPRECATED_BIG_REMOTE_BREAKPOINT'
2912 and `DEPRECATED_LITTLE_REMOTE_BREAKPOINT' have been deprecated in
2913 favor of `BREAKPOINT_FROM_PC' (*note BREAKPOINT_FROM_PC::).
2915 `BREAKPOINT_FROM_PC (PCPTR, LENPTR)'
2916 Use the program counter to determine the contents and size of a
2917 breakpoint instruction. It returns a pointer to a string of bytes
2918 that encode a breakpoint instruction, stores the length of the
2919 string to `*LENPTR', and adjusts the program counter (if
2920 necessary) to point to the actual memory location where the
2921 breakpoint should be inserted.
2923 Although it is common to use a trap instruction for a breakpoint,
2924 it's not required; for instance, the bit pattern could be an
2925 invalid instruction. The breakpoint must be no longer than the
2926 shortest instruction of the architecture.
2928 Replaces all the other BREAKPOINT macros.
2930 `MEMORY_INSERT_BREAKPOINT (BP_TGT)'
2931 `MEMORY_REMOVE_BREAKPOINT (BP_TGT)'
2932 Insert or remove memory based breakpoints. Reasonable defaults
2933 (`default_memory_insert_breakpoint' and
2934 `default_memory_remove_breakpoint' respectively) have been
2935 provided so that it is not necessary to define these for most
2936 architectures. Architectures which may want to define
2937 `MEMORY_INSERT_BREAKPOINT' and `MEMORY_REMOVE_BREAKPOINT' will
2938 likely have instructions that are oddly sized or are not stored in
2939 a conventional manner.
2941 It may also be desirable (from an efficiency standpoint) to define
2942 custom breakpoint insertion and removal routines if
2943 `BREAKPOINT_FROM_PC' needs to read the target's memory for some
2946 `ADJUST_BREAKPOINT_ADDRESS (ADDRESS)'
2947 Given an address at which a breakpoint is desired, return a
2948 breakpoint address adjusted to account for architectural
2949 constraints on breakpoint placement. This method is not needed by
2952 The FR-V target (see `frv-tdep.c') requires this method. The FR-V
2953 is a VLIW architecture in which a number of RISC-like instructions
2954 are grouped (packed) together into an aggregate instruction or
2955 instruction bundle. When the processor executes one of these
2956 bundles, the component instructions are executed in parallel.
2958 In the course of optimization, the compiler may group instructions
2959 from distinct source statements into the same bundle. The line
2960 number information associated with one of the latter statements
2961 will likely refer to some instruction other than the first one in
2962 the bundle. So, if the user attempts to place a breakpoint on one
2963 of these latter statements, GDB must be careful to _not_ place the
2964 break instruction on any instruction other than the first one in
2965 the bundle. (Remember though that the instructions within a
2966 bundle execute in parallel, so the _first_ instruction is the
2967 instruction at the lowest address and has nothing to do with
2970 The FR-V's `ADJUST_BREAKPOINT_ADDRESS' method will adjust a
2971 breakpoint's address by scanning backwards for the beginning of
2972 the bundle, returning the address of the bundle.
2974 Since the adjustment of a breakpoint may significantly alter a
2975 user's expectation, GDB prints a warning when an adjusted
2976 breakpoint is initially set and each time that that breakpoint is
2979 `CALL_DUMMY_LOCATION'
2980 See the file `inferior.h'.
2982 This method has been replaced by `push_dummy_code' (*note
2985 `CANNOT_FETCH_REGISTER (REGNO)'
2986 A C expression that should be nonzero if REGNO cannot be fetched
2987 from an inferior process. This is only relevant if
2988 `FETCH_INFERIOR_REGISTERS' is not defined.
2990 `CANNOT_STORE_REGISTER (REGNO)'
2991 A C expression that should be nonzero if REGNO should not be
2992 written to the target. This is often the case for program
2993 counters, status words, and other special registers. If this is
2994 not defined, GDB will assume that all registers may be written.
2996 `int CONVERT_REGISTER_P(REGNUM)'
2997 Return non-zero if register REGNUM can represent data values in a
2998 non-standard form. *Note Using Different Register and Memory Data
2999 Representations: Target Architecture Definition.
3001 `DECR_PC_AFTER_BREAK'
3002 Define this to be the amount by which to decrement the PC after the
3003 program encounters a breakpoint. This is often the number of
3004 bytes in `BREAKPOINT', though not always. For most targets this
3007 `DISABLE_UNSETTABLE_BREAK (ADDR)'
3008 If defined, this should evaluate to 1 if ADDR is in a shared
3009 library in which breakpoints cannot be set and so should be
3012 `PRINT_FLOAT_INFO()'
3013 If defined, then the `info float' command will print information
3014 about the processor's floating point unit.
3016 `print_registers_info (GDBARCH, FRAME, REGNUM, ALL)'
3017 If defined, pretty print the value of the register REGNUM for the
3018 specified FRAME. If the value of REGNUM is -1, pretty print
3019 either all registers (ALL is non zero) or a select subset of
3020 registers (ALL is zero).
3022 The default method prints one register per line, and if ALL is
3023 zero omits floating-point registers.
3025 `PRINT_VECTOR_INFO()'
3026 If defined, then the `info vector' command will call this function
3027 to print information about the processor's vector unit.
3029 By default, the `info vector' command will print all vector
3030 registers (the register's type having the vector attribute).
3032 `DWARF_REG_TO_REGNUM'
3033 Convert DWARF register number into GDB regnum. If not defined, no
3034 conversion will be performed.
3036 `DWARF2_REG_TO_REGNUM'
3037 Convert DWARF2 register number into GDB regnum. If not defined,
3038 no conversion will be performed.
3040 `ECOFF_REG_TO_REGNUM'
3041 Convert ECOFF register number into GDB regnum. If not defined, no
3042 conversion will be performed.
3044 `END_OF_TEXT_DEFAULT'
3045 This is an expression that should designate the end of the text
3048 `EXTRACT_RETURN_VALUE(TYPE, REGBUF, VALBUF)'
3049 Define this to extract a function's return value of type TYPE from
3050 the raw register state REGBUF and copy that, in virtual format,
3053 This method has been deprecated in favour of `gdbarch_return_value'
3054 (*note gdbarch_return_value::).
3056 `DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS(REGBUF)'
3057 When defined, extract from the array REGBUF (containing the raw
3058 register state) the `CORE_ADDR' at which a function should return
3059 its structure value.
3061 *Note gdbarch_return_value::.
3063 `DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS_P()'
3064 Predicate for `DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS'.
3066 `DEPRECATED_FP_REGNUM'
3067 If the virtual frame pointer is kept in a register, then define
3068 this macro to be the number (greater than or equal to zero) of
3071 This should only need to be defined if `DEPRECATED_TARGET_READ_FP'
3074 `DEPRECATED_FRAMELESS_FUNCTION_INVOCATION(FI)'
3075 Define this to an expression that returns 1 if the function
3076 invocation represented by FI does not have a stack frame
3077 associated with it. Otherwise return 0.
3079 `frame_align (ADDRESS)'
3080 Define this to adjust ADDRESS so that it meets the alignment
3081 requirements for the start of a new stack frame. A stack frame's
3082 alignment requirements are typically stronger than a target
3083 processors stack alignment requirements (*note
3084 DEPRECATED_STACK_ALIGN::).
3086 This function is used to ensure that, when creating a dummy frame,
3087 both the initial stack pointer and (if needed) the address of the
3088 return value are correctly aligned.
3090 Unlike `DEPRECATED_STACK_ALIGN', this function always adjusts the
3091 address in the direction of stack growth.
3093 By default, no frame based stack alignment is performed.
3095 `int frame_red_zone_size'
3096 The number of bytes, beyond the innermost-stack-address, reserved
3097 by the ABI. A function is permitted to use this scratch area
3098 (instead of allocating extra stack space).
3100 When performing an inferior function call, to ensure that it does
3101 not modify this area, GDB adjusts the innermost-stack-address by
3102 FRAME_RED_ZONE_SIZE bytes before pushing parameters onto the stack.
3104 By default, zero bytes are allocated. The value must be aligned
3105 (*note frame_align::).
3107 The AMD64 (nee x86-64) ABI documentation refers to the _red zone_
3108 when describing this scratch area.
3110 `DEPRECATED_FRAME_CHAIN(FRAME)'
3111 Given FRAME, return a pointer to the calling frame.
3113 `DEPRECATED_FRAME_CHAIN_VALID(CHAIN, THISFRAME)'
3114 Define this to be an expression that returns zero if the given
3115 frame is an outermost frame, with no caller, and nonzero
3116 otherwise. Most normal situations can be handled without defining
3117 this macro, including `NULL' chain pointers, dummy frames, and
3118 frames whose PC values are inside the startup file (e.g.
3119 `crt0.o'), inside `main', or inside `_start'.
3121 `DEPRECATED_FRAME_INIT_SAVED_REGS(FRAME)'
3122 See `frame.h'. Determines the address of all registers in the
3123 current stack frame storing each in `frame->saved_regs'. Space for
3124 `frame->saved_regs' shall be allocated by
3125 `DEPRECATED_FRAME_INIT_SAVED_REGS' using `frame_saved_regs_zalloc'.
3127 `FRAME_FIND_SAVED_REGS' is deprecated.
3129 `FRAME_NUM_ARGS (FI)'
3130 For the frame described by FI return the number of arguments that
3131 are being passed. If the number of arguments is not known, return
3134 `DEPRECATED_FRAME_SAVED_PC(FRAME)'
3135 Given FRAME, return the pc saved there. This is the return
3138 This method is deprecated. *Note unwind_pc::.
3140 `CORE_ADDR unwind_pc (struct frame_info *THIS_FRAME)'
3141 Return the instruction address, in THIS_FRAME's caller, at which
3142 execution will resume after THIS_FRAME returns. This is commonly
3143 refered to as the return address.
3145 The implementation, which must be frame agnostic (work with any
3146 frame), is typically no more than:
3149 frame_unwind_unsigned_register (this_frame, D10V_PC_REGNUM, &pc);
3150 return d10v_make_iaddr (pc);
3152 *Note DEPRECATED_FRAME_SAVED_PC::, which this method replaces.
3154 `CORE_ADDR unwind_sp (struct frame_info *THIS_FRAME)'
3155 Return the frame's inner most stack address. This is commonly
3156 refered to as the frame's "stack pointer".
3158 The implementation, which must be frame agnostic (work with any
3159 frame), is typically no more than:
3162 frame_unwind_unsigned_register (this_frame, D10V_SP_REGNUM, &sp);
3163 return d10v_make_daddr (sp);
3165 *Note TARGET_READ_SP::, which this method replaces.
3167 `FUNCTION_EPILOGUE_SIZE'
3168 For some COFF targets, the `x_sym.x_misc.x_fsize' field of the
3169 function end symbol is 0. For such targets, you must define
3170 `FUNCTION_EPILOGUE_SIZE' to expand into the standard size of a
3171 function's epilogue.
3173 `DEPRECATED_FUNCTION_START_OFFSET'
3174 An integer, giving the offset in bytes from a function's address
3175 (as used in the values of symbols, function pointers, etc.), and
3176 the function's first genuine instruction.
3178 This is zero on almost all machines: the function's address is
3179 usually the address of its first instruction. However, on the
3180 VAX, for example, each function starts with two bytes containing a
3181 bitmask indicating which registers to save upon entry to the
3182 function. The VAX `call' instructions check this value, and save
3183 the appropriate registers automatically. Thus, since the offset
3184 from the function's address to its first instruction is two bytes,
3185 `DEPRECATED_FUNCTION_START_OFFSET' would be 2 on the VAX.
3187 `GCC_COMPILED_FLAG_SYMBOL'
3188 `GCC2_COMPILED_FLAG_SYMBOL'
3189 If defined, these are the names of the symbols that GDB will look
3190 for to detect that GCC compiled the file. The default symbols are
3191 `gcc_compiled.' and `gcc2_compiled.', respectively. (Currently
3192 only defined for the Delta 68.)
3195 If defined and non-zero, enables support for multiple architectures
3198 This support can be enabled at two levels. At level one, only
3199 definitions for previously undefined macros are provided; at level
3200 two, a multi-arch definition of all architecture dependent macros
3203 `GDB_TARGET_IS_HPPA'
3204 This determines whether horrible kludge code in `dbxread.c' and
3205 `partial-stab.h' is used to mangle multiple-symbol-table files from
3206 HPPA's. This should all be ripped out, and a scheme like
3207 `elfread.c' used instead.
3209 `GET_LONGJMP_TARGET'
3210 For most machines, this is a target-dependent parameter. On the
3211 DECstation and the Iris, this is a native-dependent parameter,
3212 since the header file `setjmp.h' is needed to define it.
3214 This macro determines the target PC address that `longjmp' will
3215 jump to, assuming that we have just stopped at a `longjmp'
3216 breakpoint. It takes a `CORE_ADDR *' as argument, and stores the
3217 target PC value through this pointer. It examines the current
3218 state of the machine as needed.
3220 `DEPRECATED_GET_SAVED_REGISTER'
3221 Define this if you need to supply your own definition for the
3222 function `DEPRECATED_GET_SAVED_REGISTER'.
3224 `DEPRECATED_IBM6000_TARGET'
3225 Shows that we are configured for an IBM RS/6000 system. This
3226 conditional should be eliminated (FIXME) and replaced by
3227 feature-specific macros. It was introduced in a haste and we are
3228 repenting at leisure.
3230 `I386_USE_GENERIC_WATCHPOINTS'
3231 An x86-based target can define this to use the generic x86
3232 watchpoint support; see *Note I386_USE_GENERIC_WATCHPOINTS:
3235 `SYMBOLS_CAN_START_WITH_DOLLAR'
3236 Some systems have routines whose names start with `$'. Giving this
3237 macro a non-zero value tells GDB's expression parser to check for
3238 such routines when parsing tokens that begin with `$'.
3240 On HP-UX, certain system routines (millicode) have names beginning
3241 with `$' or `$$'. For example, `$$dyncall' is a millicode routine
3242 that handles inter-space procedure calls on PA-RISC.
3244 `DEPRECATED_INIT_EXTRA_FRAME_INFO (FROMLEAF, FRAME)'
3245 If additional information about the frame is required this should
3246 be stored in `frame->extra_info'. Space for `frame->extra_info'
3247 is allocated using `frame_extra_info_zalloc'.
3249 `DEPRECATED_INIT_FRAME_PC (FROMLEAF, PREV)'
3250 This is a C statement that sets the pc of the frame pointed to by
3251 PREV. [By default...]
3253 `INNER_THAN (LHS, RHS)'
3254 Returns non-zero if stack address LHS is inner than (nearer to the
3255 stack top) stack address RHS. Define this as `lhs < rhs' if the
3256 target's stack grows downward in memory, or `lhs > rsh' if the
3259 `gdbarch_in_function_epilogue_p (GDBARCH, PC)'
3260 Returns non-zero if the given PC is in the epilogue of a function.
3261 The epilogue of a function is defined as the part of a function
3262 where the stack frame of the function already has been destroyed
3263 up to the final `return from function call' instruction.
3265 `DEPRECATED_SIGTRAMP_START (PC)'
3266 `DEPRECATED_SIGTRAMP_END (PC)'
3267 Define these to be the start and end address of the `sigtramp' for
3268 the given PC. On machines where the address is just a compile time
3269 constant, the macro expansion will typically just ignore the
3272 `IN_SOLIB_CALL_TRAMPOLINE (PC, NAME)'
3273 Define this to evaluate to nonzero if the program is stopped in the
3274 trampoline that connects to a shared library.
3276 `IN_SOLIB_RETURN_TRAMPOLINE (PC, NAME)'
3277 Define this to evaluate to nonzero if the program is stopped in the
3278 trampoline that returns from a shared library.
3280 `IN_SOLIB_DYNSYM_RESOLVE_CODE (PC)'
3281 Define this to evaluate to nonzero if the program is stopped in the
3284 `SKIP_SOLIB_RESOLVER (PC)'
3285 Define this to evaluate to the (nonzero) address at which execution
3286 should continue to get past the dynamic linker's symbol resolution
3287 function. A zero value indicates that it is not important or
3288 necessary to set a breakpoint to get through the dynamic linker
3289 and that single stepping will suffice.
3291 `INTEGER_TO_ADDRESS (TYPE, BUF)'
3292 Define this when the architecture needs to handle non-pointer to
3293 address conversions specially. Converts that value to an address
3294 according to the current architectures conventions.
3296 _Pragmatics: When the user copies a well defined expression from
3297 their source code and passes it, as a parameter, to GDB's `print'
3298 command, they should get the same value as would have been
3299 computed by the target program. Any deviation from this rule can
3300 cause major confusion and annoyance, and needs to be justified
3301 carefully. In other words, GDB doesn't really have the freedom to
3302 do these conversions in clever and useful ways. It has, however,
3303 been pointed out that users aren't complaining about how GDB casts
3304 integers to pointers; they are complaining that they can't take an
3305 address from a disassembly listing and give it to `x/i'. Adding
3306 an architecture method like `INTEGER_TO_ADDRESS' certainly makes
3307 it possible for GDB to "get it right" in all circumstances._
3309 *Note Pointers Are Not Always Addresses: Target Architecture
3313 (Specific to the a29k.)
3315 `POINTER_TO_ADDRESS (TYPE, BUF)'
3316 Assume that BUF holds a pointer of type TYPE, in the appropriate
3317 format for the current architecture. Return the byte address the
3318 pointer refers to. *Note Pointers Are Not Always Addresses:
3319 Target Architecture Definition.
3321 `REGISTER_CONVERTIBLE (REG)'
3322 Return non-zero if REG uses different raw and virtual formats.
3323 *Note Raw and Virtual Register Representations: Target
3324 Architecture Definition.
3326 `REGISTER_TO_VALUE(REGNUM, TYPE, FROM, TO)'
3327 Convert the raw contents of register REGNUM into a value of type
3328 TYPE. *Note Using Different Register and Memory Data
3329 Representations: Target Architecture Definition.
3331 `DEPRECATED_REGISTER_RAW_SIZE (REG)'
3332 Return the raw size of REG; defaults to the size of the register's
3333 virtual type. *Note Raw and Virtual Register Representations:
3334 Target Architecture Definition.
3336 `register_reggroup_p (GDBARCH, REGNUM, REGGROUP)'
3337 Return non-zero if register REGNUM is a member of the register
3340 By default, registers are grouped as follows:
3343 Any register with a valid name and a floating-point type.
3346 Any register with a valid name and a vector type.
3349 Any register with a valid name and a type other than vector or
3350 floating-point. `float_reggroup'.
3355 Any register with a valid name.
3357 `DEPRECATED_REGISTER_VIRTUAL_SIZE (REG)'
3358 Return the virtual size of REG; defaults to the size of the
3359 register's virtual type. Return the virtual size of REG. *Note
3360 Raw and Virtual Register Representations: Target Architecture
3363 `DEPRECATED_REGISTER_VIRTUAL_TYPE (REG)'
3364 Return the virtual type of REG. *Note Raw and Virtual Register
3365 Representations: Target Architecture Definition.
3367 `struct type *register_type (GDBARCH, REG)'
3368 If defined, return the type of register REG. This function
3369 superseeds `DEPRECATED_REGISTER_VIRTUAL_TYPE'. *Note Raw and
3370 Virtual Register Representations: Target Architecture Definition.
3372 `REGISTER_CONVERT_TO_VIRTUAL(REG, TYPE, FROM, TO)'
3373 Convert the value of register REG from its raw form to its virtual
3374 form. *Note Raw and Virtual Register Representations: Target
3375 Architecture Definition.
3377 `REGISTER_CONVERT_TO_RAW(TYPE, REG, FROM, TO)'
3378 Convert the value of register REG from its virtual form to its raw
3379 form. *Note Raw and Virtual Register Representations: Target
3380 Architecture Definition.
3382 `const struct regset *regset_from_core_section (struct gdbarch * GDBARCH, const char * SECT_NAME, size_t SECT_SIZE)'
3383 Return the appropriate register set for a core file section with
3384 name SECT_NAME and size SECT_SIZE.
3386 `SOFTWARE_SINGLE_STEP_P()'
3387 Define this as 1 if the target does not have a hardware single-step
3388 mechanism. The macro `SOFTWARE_SINGLE_STEP' must also be defined.
3390 `SOFTWARE_SINGLE_STEP(SIGNAL, INSERT_BREAPOINTS_P)'
3391 A function that inserts or removes (depending on
3392 INSERT_BREAPOINTS_P) breakpoints at each possible destinations of
3393 the next instruction. See `sparc-tdep.c' and `rs6000-tdep.c' for
3396 `SOFUN_ADDRESS_MAYBE_MISSING'
3397 Somebody clever observed that, the more actual addresses you have
3398 in the debug information, the more time the linker has to spend
3399 relocating them. So whenever there's some other way the debugger
3400 could find the address it needs, you should omit it from the debug
3401 info, to make linking faster.
3403 `SOFUN_ADDRESS_MAYBE_MISSING' indicates that a particular set of
3404 hacks of this sort are in use, affecting `N_SO' and `N_FUN'
3405 entries in stabs-format debugging information. `N_SO' stabs mark
3406 the beginning and ending addresses of compilation units in the text
3407 segment. `N_FUN' stabs mark the starts and ends of functions.
3409 `SOFUN_ADDRESS_MAYBE_MISSING' means two things:
3411 * `N_FUN' stabs have an address of zero. Instead, you should
3412 find the addresses where the function starts by taking the
3413 function name from the stab, and then looking that up in the
3414 minsyms (the linker/assembler symbol table). In other words,
3415 the stab has the name, and the linker/assembler symbol table
3416 is the only place that carries the address.
3418 * `N_SO' stabs have an address of zero, too. You just look at
3419 the `N_FUN' stabs that appear before and after the `N_SO'
3420 stab, and guess the starting and ending addresses of the
3421 compilation unit from them.
3424 If defined, print information about the load segment for the
3425 program counter. (Defined only for the RS/6000.)
3428 If the program counter is kept in a register, then define this
3429 macro to be the number (greater than or equal to zero) of that
3432 This should only need to be defined if `TARGET_READ_PC' and
3433 `TARGET_WRITE_PC' are not defined.
3436 If non-zero, round arguments to a boundary of this many bits before
3437 pushing them on the stack.
3439 `stabs_argument_has_addr (GDBARCH, TYPE)'
3440 Define this to return nonzero if a function argument of type TYPE
3441 is passed by reference instead of value.
3443 This method replaces `DEPRECATED_REG_STRUCT_HAS_ADDR' (*note
3444 DEPRECATED_REG_STRUCT_HAS_ADDR::).
3446 `PROCESS_LINENUMBER_HOOK'
3447 A hook defined for XCOFF reading.
3449 `PROLOGUE_FIRSTLINE_OVERLAP'
3450 (Only used in unsupported Convex configuration.)
3453 If defined, this is the number of the processor status register.
3454 (This definition is only used in generic code when parsing "$ps".)
3456 `DEPRECATED_POP_FRAME'
3457 If defined, used by `frame_pop' to remove a stack frame. This
3458 method has been superseeded by generic code.
3460 `push_dummy_call (GDBARCH, FUNCTION, REGCACHE, PC_ADDR, NARGS, ARGS, SP, STRUCT_RETURN, STRUCT_ADDR)'
3461 Define this to push the dummy frame's call to the inferior
3462 function onto the stack. In addition to pushing NARGS, the code
3463 should push STRUCT_ADDR (when STRUCT_RETURN), and the return
3466 FUNCTION is a pointer to a `struct value'; on architectures that
3467 use function descriptors, this contains the function descriptor
3470 Returns the updated top-of-stack pointer.
3472 This method replaces `DEPRECATED_PUSH_ARGUMENTS'.
3474 `CORE_ADDR push_dummy_code (GDBARCH, SP, FUNADDR, USING_GCC, ARGS, NARGS, VALUE_TYPE, REAL_PC, BP_ADDR)'
3475 Given a stack based call dummy, push the instruction sequence
3476 (including space for a breakpoint) to which the called function
3479 Set BP_ADDR to the address at which the breakpoint instruction
3480 should be inserted, REAL_PC to the resume address when starting
3481 the call sequence, and return the updated inner-most stack address.
3483 By default, the stack is grown sufficient to hold a frame-aligned
3484 (*note frame_align::) breakpoint, BP_ADDR is set to the address
3485 reserved for that breakpoint, and REAL_PC set to FUNADDR.
3487 This method replaces `CALL_DUMMY_LOCATION',
3488 `DEPRECATED_REGISTER_SIZE'.
3491 Return the name of register I as a string. May return `NULL' or
3492 `NUL' to indicate that register I is not valid.
3494 `DEPRECATED_REG_STRUCT_HAS_ADDR (GCC_P, TYPE)'
3495 Define this to return 1 if the given type will be passed by
3496 pointer rather than directly.
3498 This method has been replaced by `stabs_argument_has_addr' (*note
3499 stabs_argument_has_addr::).
3501 `SAVE_DUMMY_FRAME_TOS (SP)'
3502 Used in `call_function_by_hand' to notify the target dependent
3503 code of the top-of-stack value that will be passed to the the
3504 inferior code. This is the value of the `SP' after both the dummy
3505 frame and space for parameters/results have been allocated on the
3506 stack. *Note unwind_dummy_id::.
3509 Define this to convert sdb register numbers into GDB regnums. If
3510 not defined, no conversion will be done.
3512 `enum return_value_convention gdbarch_return_value (struct gdbarch *GDBARCH, struct type *VALTYPE, struct regcache *REGCACHE, void *READBUF, const void *WRITEBUF)'
3513 Given a function with a return-value of type RETTYPE, return which
3514 return-value convention that function would use.
3516 GDB currently recognizes two function return-value conventions:
3517 `RETURN_VALUE_REGISTER_CONVENTION' where the return value is found
3518 in registers; and `RETURN_VALUE_STRUCT_CONVENTION' where the return
3519 value is found in memory and the address of that memory location is
3520 passed in as the function's first parameter.
3522 If the register convention is being used, and WRITEBUF is
3523 non-`NULL', also copy the return-value in WRITEBUF into REGCACHE.
3525 If the register convention is being used, and READBUF is
3526 non-`NULL', also copy the return value from REGCACHE into READBUF
3527 (REGCACHE contains a copy of the registers from the just returned
3530 *Note DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS::, for a description
3531 of how return-values that use the struct convention are handled.
3533 _Maintainer note: This method replaces separate predicate, extract,
3534 store methods. By having only one method, the logic needed to
3535 determine the return-value convention need only be implemented in
3536 one place. If GDB were written in an OO language, this method
3537 would instead return an object that knew how to perform the
3538 register return-value extract and store._
3540 _Maintainer note: This method does not take a GCC_P parameter, and
3541 such a parameter should not be added. If an architecture that
3542 requires per-compiler or per-function information be identified,
3543 then the replacement of RETTYPE with `struct value' FUNCTION
3546 _Maintainer note: The REGCACHE parameter limits this methods to
3547 the inner most frame. While replacing REGCACHE with a `struct
3548 frame_info' FRAME parameter would remove that limitation there has
3549 yet to be a demonstrated need for such a change._
3551 `SKIP_PERMANENT_BREAKPOINT'
3552 Advance the inferior's PC past a permanent breakpoint. GDB
3553 normally steps over a breakpoint by removing it, stepping one
3554 instruction, and re-inserting the breakpoint. However, permanent
3555 breakpoints are hardwired into the inferior, and can't be removed,
3556 so this strategy doesn't work. Calling
3557 `SKIP_PERMANENT_BREAKPOINT' adjusts the processor's state so that
3558 execution will resume just after the breakpoint. This macro does
3559 the right thing even when the breakpoint is in the delay slot of a
3562 `SKIP_PROLOGUE (PC)'
3563 A C expression that returns the address of the "real" code beyond
3564 the function entry prologue found at PC.
3566 `SKIP_TRAMPOLINE_CODE (PC)'
3567 If the target machine has trampoline code that sits between
3568 callers and the functions being called, then define this macro to
3569 return a new PC that is at the start of the real function.
3572 If the stack-pointer is kept in a register, then define this macro
3573 to be the number (greater than or equal to zero) of that register,
3574 or -1 if there is no such register.
3576 `STAB_REG_TO_REGNUM'
3577 Define this to convert stab register numbers (as gotten from `r'
3578 declarations) into GDB regnums. If not defined, no conversion
3581 `DEPRECATED_STACK_ALIGN (ADDR)'
3582 Define this to increase ADDR so that it meets the alignment
3583 requirements for the processor's stack.
3585 Unlike *Note frame_align::, this function always adjusts ADDR
3588 By default, no stack alignment is performed.
3590 `STEP_SKIPS_DELAY (ADDR)'
3591 Define this to return true if the address is of an instruction
3592 with a delay slot. If a breakpoint has been placed in the
3593 instruction's delay slot, GDB will single-step over that
3594 instruction before resuming normally. Currently only defined for
3597 `STORE_RETURN_VALUE (TYPE, REGCACHE, VALBUF)'
3598 A C expression that writes the function return value, found in
3599 VALBUF, into the REGCACHE. TYPE is the type of the value that is
3602 This method has been deprecated in favour of `gdbarch_return_value'
3603 (*note gdbarch_return_value::).
3605 `SYMBOL_RELOADING_DEFAULT'
3606 The default value of the "symbol-reloading" variable. (Never
3607 defined in current sources.)
3610 Number of bits in a char; defaults to 8.
3612 `TARGET_CHAR_SIGNED'
3613 Non-zero if `char' is normally signed on this architecture; zero if
3614 it should be unsigned.
3616 The ISO C standard requires the compiler to treat `char' as
3617 equivalent to either `signed char' or `unsigned char'; any
3618 character in the standard execution set is supposed to be positive.
3619 Most compilers treat `char' as signed, but `char' is unsigned on
3620 the IBM S/390, RS6000, and PowerPC targets.
3622 `TARGET_COMPLEX_BIT'
3623 Number of bits in a complex number; defaults to `2 *
3626 At present this macro is not used.
3629 Number of bits in a double float; defaults to `8 *
3632 `TARGET_DOUBLE_COMPLEX_BIT'
3633 Number of bits in a double complex; defaults to `2 *
3636 At present this macro is not used.
3639 Number of bits in a float; defaults to `4 * TARGET_CHAR_BIT'.
3642 Number of bits in an integer; defaults to `4 * TARGET_CHAR_BIT'.
3645 Number of bits in a long integer; defaults to `4 *
3648 `TARGET_LONG_DOUBLE_BIT'
3649 Number of bits in a long double float; defaults to `2 *
3652 `TARGET_LONG_LONG_BIT'
3653 Number of bits in a long long integer; defaults to `2 *
3657 Number of bits in a pointer; defaults to `TARGET_INT_BIT'.
3660 Number of bits in a short integer; defaults to `2 *
3664 `TARGET_WRITE_PC (VAL, PID)'
3667 These change the behavior of `read_pc', `write_pc', and `read_sp'.
3668 For most targets, these may be left undefined. GDB will call the
3669 read and write register functions with the relevant `_REGNUM'
3672 These macros are useful when a target keeps one of these registers
3673 in a hard to get at place; for example, part in a segment register
3674 and part in an ordinary register.
3676 *Note unwind_sp::, which replaces `TARGET_READ_SP'.
3678 `TARGET_VIRTUAL_FRAME_POINTER(PC, REGP, OFFSETP)'
3679 Returns a `(register, offset)' pair representing the virtual frame
3680 pointer in use at the code address PC. If virtual frame pointers
3681 are not used, a default definition simply returns
3682 `DEPRECATED_FP_REGNUM', with an offset of zero.
3684 `TARGET_HAS_HARDWARE_WATCHPOINTS'
3685 If non-zero, the target has support for hardware-assisted
3686 watchpoints. *Note watchpoints: Algorithms, for more details and
3687 other related macros.
3689 `TARGET_PRINT_INSN (ADDR, INFO)'
3690 This is the function used by GDB to print an assembly instruction.
3691 It prints the instruction at address ADDR in debugged memory and
3692 returns the length of the instruction, in bytes. If a target
3693 doesn't define its own printing routine, it defaults to an
3694 accessor function for the global pointer
3695 `deprecated_tm_print_insn'. This usually points to a function in
3696 the `opcodes' library (*note Opcodes: Support Libraries.). INFO
3697 is a structure (of type `disassemble_info') defined in
3698 `include/dis-asm.h' used to pass information to the instruction
3701 `struct frame_id unwind_dummy_id (struct frame_info *FRAME)'
3702 Given FRAME return a `struct frame_id' that uniquely identifies an
3703 inferior function call's dummy frame. The value returned must
3704 match the dummy frame stack value previously saved using
3705 `SAVE_DUMMY_FRAME_TOS'. *Note SAVE_DUMMY_FRAME_TOS::.
3707 `DEPRECATED_USE_STRUCT_CONVENTION (GCC_P, TYPE)'
3708 If defined, this must be an expression that is nonzero if a value
3709 of the given TYPE being returned from a function must have space
3710 allocated for it on the stack. GCC_P is true if the function
3711 being considered is known to have been compiled by GCC; this is
3712 helpful for systems where GCC is known to use different calling
3713 convention than other compilers.
3715 This method has been deprecated in favour of `gdbarch_return_value'
3716 (*note gdbarch_return_value::).
3718 `VALUE_TO_REGISTER(TYPE, REGNUM, FROM, TO)'
3719 Convert a value of type TYPE into the raw contents of register
3720 REGNUM's. *Note Using Different Register and Memory Data
3721 Representations: Target Architecture Definition.
3723 `VARIABLES_INSIDE_BLOCK (DESC, GCC_P)'
3724 For dbx-style debugging information, if the compiler puts variable
3725 declarations inside LBRAC/RBRAC blocks, this should be defined to
3726 be nonzero. DESC is the value of `n_desc' from the `N_RBRAC'
3727 symbol, and GCC_P is true if GDB has noticed the presence of
3728 either the `GCC_COMPILED_SYMBOL' or the `GCC2_COMPILED_SYMBOL'.
3729 By default, this is 0.
3731 `OS9K_VARIABLES_INSIDE_BLOCK (DESC, GCC_P)'
3732 Similarly, for OS/9000. Defaults to 1.
3734 Motorola M68K target conditionals.
3737 Define this to be the 4-bit location of the breakpoint trap
3738 vector. If not defined, it will default to `0xf'.
3744 A string containing the name of the function to call in order to
3745 allocate some memory in the inferior. The default value is
3749 9.12 Adding a New Target
3750 ========================
3752 The following files add a target to GDB:
3754 `gdb/config/ARCH/TTT.mt'
3755 Contains a Makefile fragment specific to this target. Specifies
3756 what object files are needed for target TTT, by defining
3757 `TDEPFILES=...' and `TDEPLIBS=...'. Also specifies the header
3758 file which describes TTT, by defining `TM_FILE= tm-TTT.h'.
3760 You can also define `TM_CFLAGS', `TM_CLIBS', `TM_CDEPS', but these
3761 are now deprecated, replaced by autoconf, and may go away in
3762 future versions of GDB.
3765 Contains any miscellaneous code required for this target machine.
3766 On some machines it doesn't exist at all. Sometimes the macros in
3767 `tm-TTT.h' become very complicated, so they are implemented as
3768 functions here instead, and the macro is simply defined to call the
3769 function. This is vastly preferable, since it is easier to
3770 understand and debug.
3774 This often exists to describe the basic layout of the target
3775 machine's processor chip (registers, stack, etc.). If used, it is
3776 included by `TTT-tdep.h'. It can be shared among many targets
3777 that use the same processor.
3779 `gdb/config/ARCH/tm-TTT.h'
3780 (`tm.h' is a link to this file, created by `configure'). Contains
3781 macro definitions about the target machine's registers, stack frame
3782 format and instructions.
3784 New targets do not need this file and should not create it.
3786 `gdb/config/ARCH/tm-ARCH.h'
3787 This often exists to describe the basic layout of the target
3788 machine's processor chip (registers, stack, etc.). If used, it is
3789 included by `tm-TTT.h'. It can be shared among many targets that
3790 use the same processor.
3792 New targets do not need this file and should not create it.
3795 If you are adding a new operating system for an existing CPU chip,
3796 add a `config/tm-OS.h' file that describes the operating system
3797 facilities that are unusual (extra symbol table info; the breakpoint
3798 instruction needed; etc.). Then write a `ARCH/tm-OS.h' that just
3799 `#include's `tm-ARCH.h' and `config/tm-OS.h'.
3801 9.13 Converting an existing Target Architecture to Multi-arch
3802 =============================================================
3804 This section describes the current accepted best practice for converting
3805 an existing target architecture to the multi-arch framework.
3807 The process consists of generating, testing, posting and committing a
3808 sequence of patches. Each patch must contain a single change, for
3811 * Directly convert a group of functions into macros (the conversion
3812 does not change the behavior of any of the functions).
3814 * Replace a non-multi-arch with a multi-arch mechanism (e.g.,
3817 * Enable multi-arch level one.
3819 * Delete one or more files.
3822 There isn't a size limit on a patch, however, a developer is strongly
3823 encouraged to keep the patch size down.
3825 Since each patch is well defined, and since each change has been
3826 tested and shows no regressions, the patches are considered _fairly_
3827 obvious. Such patches, when submitted by developers listed in the
3828 `MAINTAINERS' file, do not need approval. Occasional steps in the
3829 process may be more complicated and less clear. The developer is
3830 expected to use their judgment and is encouraged to seek advice as
3836 The first step is to establish control. Build (with `-Werror' enabled)
3837 and test the target so that there is a baseline against which the
3838 debugger can be compared.
3840 At no stage can the test results regress or GDB stop compiling with
3843 9.13.2 Add the multi-arch initialization code
3844 ---------------------------------------------
3846 The objective of this step is to establish the basic multi-arch
3847 framework. It involves
3849 * The addition of a `ARCH_gdbarch_init' function(2) that creates the
3851 static struct gdbarch *
3852 d10v_gdbarch_init (info, arches)
3853 struct gdbarch_info info;
3854 struct gdbarch_list *arches;
3856 struct gdbarch *gdbarch;
3857 /* there is only one d10v architecture */
3859 return arches->gdbarch;
3860 gdbarch = gdbarch_alloc (&info, NULL);
3865 * A per-architecture dump function to print any architecture specific
3868 mips_dump_tdep (struct gdbarch *current_gdbarch,
3869 struct ui_file *file)
3871 ... code to print architecture specific info ...
3874 * A change to `_initialize_ARCH_tdep' to register this new
3877 _initialize_mips_tdep (void)
3879 gdbarch_register (bfd_arch_mips, mips_gdbarch_init,
3882 * Add the macro `GDB_MULTI_ARCH', defined as 0 (zero), to the file
3883 `config/ARCH/tm-ARCH.h'.
3886 9.13.3 Update multi-arch incompatible mechanisms
3887 ------------------------------------------------
3889 Some mechanisms do not work with multi-arch. They include:
3891 `FRAME_FIND_SAVED_REGS'
3892 Replaced with `DEPRECATED_FRAME_INIT_SAVED_REGS'
3894 At this stage you could also consider converting the macros into
3897 9.13.4 Prepare for multi-arch level to one
3898 ------------------------------------------
3900 Temporally set `GDB_MULTI_ARCH' to `GDB_MULTI_ARCH_PARTIAL' and then
3901 build and start GDB (the change should not be committed). GDB may not
3902 build, and once built, it may die with an internal error listing the
3903 architecture methods that must be provided.
3905 Fix any build problems (patch(es)).
3907 Convert all the architecture methods listed, which are only macros,
3908 into functions (patch(es)).
3910 Update `ARCH_gdbarch_init' to set all the missing architecture
3911 methods and wrap the corresponding macros in `#if !GDB_MULTI_ARCH'
3914 9.13.5 Set multi-arch level one
3915 -------------------------------
3917 Change the value of `GDB_MULTI_ARCH' to GDB_MULTI_ARCH_PARTIAL (a
3920 Any problems with throwing "the switch" should have been fixed
3923 9.13.6 Convert remaining macros
3924 -------------------------------
3926 Suggest converting macros into functions (and setting the corresponding
3927 architecture method) in small batches.
3929 9.13.7 Set multi-arch level to two
3930 ----------------------------------
3932 This should go smoothly.
3934 9.13.8 Delete the TM file
3935 -------------------------
3937 The `tm-ARCH.h' can be deleted. `ARCH.mt' and `configure.in' updated.
3939 ---------- Footnotes ----------
3941 (1) Some D10V instructions are actually pairs of 16-bit
3942 sub-instructions. However, since you can't jump into the middle of
3943 such a pair, code addresses can only refer to full 32 bit instructions,
3944 which is what matters in this explanation.
3946 (2) The above is from the original example and uses K&R C. GDB has
3947 since converted to ISO C but lets ignore that.
3950 File: gdbint.info, Node: Target Vector Definition, Next: Native Debugging, Prev: Target Architecture Definition, Up: Top
3952 10 Target Vector Definition
3953 ***************************
3955 The target vector defines the interface between GDB's abstract handling
3956 of target systems, and the nitty-gritty code that actually exercises
3957 control over a process or a serial port. GDB includes some 30-40
3958 different target vectors; however, each configuration of GDB includes
3963 * Managing Execution State::
3964 * Existing Targets::
3967 File: gdbint.info, Node: Managing Execution State, Next: Existing Targets, Up: Target Vector Definition
3969 10.1 Managing Execution State
3970 =============================
3972 A target vector can be completely inactive (not pushed on the target
3973 stack), active but not running (pushed, but not connected to a fully
3974 manifested inferior), or completely active (pushed, with an accessible
3975 inferior). Most targets are only completely inactive or completely
3976 active, but some support persistant connections to a target even when
3977 the target has exited or not yet started.
3979 For example, connecting to the simulator using `target sim' does not
3980 create a running program. Neither registers nor memory are accessible
3981 until `run'. Similarly, after `kill', the program can not continue
3982 executing. But in both cases GDB remains connected to the simulator,
3983 and target-specific commands are directed to the simulator.
3985 A target which only supports complete activation should push itself
3986 onto the stack in its `to_open' routine (by calling `push_target'), and
3987 unpush itself from the stack in its `to_mourn_inferior' routine (by
3988 calling `unpush_target').
3990 A target which supports both partial and complete activation should
3991 still call `push_target' in `to_open', but not call `unpush_target' in
3992 `to_mourn_inferior'. Instead, it should call either
3993 `target_mark_running' or `target_mark_exited' in its `to_open',
3994 depending on whether the target is fully active after connection. It
3995 should also call `target_mark_running' any time the inferior becomes
3996 fully active (e.g. in `to_create_inferior' and `to_attach'), and
3997 `target_mark_exited' when the inferior becomes inactive (in
3998 `to_mourn_inferior'). The target should also make sure to call
3999 `target_mourn_inferior' from its `to_kill', to return the target to
4003 File: gdbint.info, Node: Existing Targets, Prev: Managing Execution State, Up: Target Vector Definition
4005 10.2 Existing Targets
4006 =====================
4011 Both executables and core files have target vectors.
4013 10.2.2 Standard Protocol and Remote Stubs
4014 -----------------------------------------
4016 GDB's file `remote.c' talks a serial protocol to code that runs in the
4017 target system. GDB provides several sample "stubs" that can be
4018 integrated into target programs or operating systems for this purpose;
4019 they are named `*-stub.c'.
4021 The GDB user's manual describes how to put such a stub into your
4022 target code. What follows is a discussion of integrating the SPARC
4023 stub into a complicated operating system (rather than a simple
4024 program), by Stu Grossman, the author of this stub.
4026 The trap handling code in the stub assumes the following upon entry
4029 1. %l1 and %l2 contain pc and npc respectively at the time of the
4032 2. traps are disabled;
4034 3. you are in the correct trap window.
4036 As long as your trap handler can guarantee those conditions, then
4037 there is no reason why you shouldn't be able to "share" traps with the
4038 stub. The stub has no requirement that it be jumped to directly from
4039 the hardware trap vector. That is why it calls `exceptionHandler()',
4040 which is provided by the external environment. For instance, this could
4041 set up the hardware traps to actually execute code which calls the stub
4042 first, and then transfers to its own trap handler.
4044 For the most point, there probably won't be much of an issue with
4045 "sharing" traps, as the traps we use are usually not used by the kernel,
4046 and often indicate unrecoverable error conditions. Anyway, this is all
4047 controlled by a table, and is trivial to modify. The most important
4048 trap for us is for `ta 1'. Without that, we can't single step or do
4049 breakpoints. Everything else is unnecessary for the proper operation
4050 of the debugger/stub.
4052 From reading the stub, it's probably not obvious how breakpoints
4053 work. They are simply done by deposit/examine operations from GDB.
4055 10.2.3 ROM Monitor Interface
4056 ----------------------------
4058 10.2.4 Custom Protocols
4059 -----------------------
4061 10.2.5 Transport Layer
4062 ----------------------
4064 10.2.6 Builtin Simulator
4065 ------------------------
4068 File: gdbint.info, Node: Native Debugging, Next: Support Libraries, Prev: Target Vector Definition, Up: Top
4073 Several files control GDB's configuration for native support:
4075 `gdb/config/ARCH/XYZ.mh'
4076 Specifies Makefile fragments needed by a _native_ configuration on
4077 machine XYZ. In particular, this lists the required
4078 native-dependent object files, by defining `NATDEPFILES=...'.
4079 Also specifies the header file which describes native support on
4080 XYZ, by defining `NAT_FILE= nm-XYZ.h'. You can also define
4081 `NAT_CFLAGS', `NAT_ADD_FILES', `NAT_CLIBS', `NAT_CDEPS', etc.; see
4084 _Maintainer's note: The `.mh' suffix is because this file
4085 originally contained `Makefile' fragments for hosting GDB on
4086 machine XYZ. While the file is no longer used for this purpose,
4087 the `.mh' suffix remains. Perhaps someone will eventually rename
4088 these fragments so that they have a `.mn' suffix._
4090 `gdb/config/ARCH/nm-XYZ.h'
4091 (`nm.h' is a link to this file, created by `configure'). Contains
4092 C macro definitions describing the native system environment, such
4093 as child process control and core file support.
4096 Contains any miscellaneous C code required for this native support
4097 of this machine. On some machines it doesn't exist at all.
4099 There are some "generic" versions of routines that can be used by
4100 various systems. These can be customized in various ways by macros
4101 defined in your `nm-XYZ.h' file. If these routines work for the XYZ
4102 host, you can just include the generic file's name (with `.o', not
4103 `.c') in `NATDEPFILES'.
4105 Otherwise, if your machine needs custom support routines, you will
4106 need to write routines that perform the same functions as the generic
4107 file. Put them into `XYZ-nat.c', and put `XYZ-nat.o' into
4111 This contains the _target_ops vector_ that supports Unix child
4112 processes on systems which use ptrace and wait to control the
4116 This contains the _target_ops vector_ that supports Unix child
4117 processes on systems which use /proc to control the child.
4120 This does the low-level grunge that uses Unix system calls to do a
4121 "fork and exec" to start up a child process.
4124 This is the low level interface to inferior processes for systems
4125 using the Unix `ptrace' call in a vanilla way.
4127 11.1 Native core file Support
4128 =============================
4130 `core-aout.c::fetch_core_registers()'
4131 Support for reading registers out of a core file. This routine
4132 calls `register_addr()', see below. Now that BFD is used to read
4133 core files, virtually all machines should use `core-aout.c', and
4134 should just provide `fetch_core_registers' in `XYZ-nat.c' (or
4135 `REGISTER_U_ADDR' in `nm-XYZ.h').
4137 `core-aout.c::register_addr()'
4138 If your `nm-XYZ.h' file defines the macro `REGISTER_U_ADDR(addr,
4139 blockend, regno)', it should be defined to set `addr' to the
4140 offset within the `user' struct of GDB register number `regno'.
4141 `blockend' is the offset within the "upage" of `u.u_ar0'. If
4142 `REGISTER_U_ADDR' is defined, `core-aout.c' will define the
4143 `register_addr()' function and use the macro in it. If you do not
4144 define `REGISTER_U_ADDR', but you are using the standard
4145 `fetch_core_registers()', you will need to define your own version
4146 of `register_addr()', put it into your `XYZ-nat.c' file, and be
4147 sure `XYZ-nat.o' is in the `NATDEPFILES' list. If you have your
4148 own `fetch_core_registers()', you may not need a separate
4149 `register_addr()'. Many custom `fetch_core_registers()'
4150 implementations simply locate the registers themselves.
4152 When making GDB run native on a new operating system, to make it
4153 possible to debug core files, you will need to either write specific
4154 code for parsing your OS's core files, or customize `bfd/trad-core.c'.
4155 First, use whatever `#include' files your machine uses to define the
4156 struct of registers that is accessible (possibly in the u-area) in a
4157 core file (rather than `machine/reg.h'), and an include file that
4158 defines whatever header exists on a core file (e.g., the u-area or a
4159 `struct core'). Then modify `trad_unix_core_file_p' to use these
4160 values to set up the section information for the data segment, stack
4161 segment, any other segments in the core file (perhaps shared library
4162 contents or control information), "registers" segment, and if there are
4163 two discontiguous sets of registers (e.g., integer and float), the
4164 "reg2" segment. This section information basically delimits areas in
4165 the core file in a standard way, which the section-reading routines in
4166 BFD know how to seek around in.
4168 Then back in GDB, you need a matching routine called
4169 `fetch_core_registers'. If you can use the generic one, it's in
4170 `core-aout.c'; if not, it's in your `XYZ-nat.c' file. It will be
4171 passed a char pointer to the entire "registers" segment, its length,
4172 and a zero; or a char pointer to the entire "regs2" segment, its
4173 length, and a 2. The routine should suck out the supplied register
4174 values and install them into GDB's "registers" array.
4176 If your system uses `/proc' to control processes, and uses ELF
4177 format core files, then you may be able to use the same routines for
4178 reading the registers out of processes and out of core files.
4189 11.5 shared libraries
4190 =====================
4192 11.6 Native Conditionals
4193 ========================
4195 When GDB is configured and compiled, various macros are defined or left
4196 undefined, to control compilation when the host and target systems are
4197 the same. These macros should be defined (or left undefined) in
4200 `CHILD_PREPARE_TO_STORE'
4201 If the machine stores all registers at once in the child process,
4202 then define this to ensure that all values are correct. This
4203 usually entails a read from the child.
4205 [Note that this is incorrectly defined in `xm-SYSTEM.h' files
4208 `FETCH_INFERIOR_REGISTERS'
4209 Define this if the native-dependent code will provide its own
4210 routines `fetch_inferior_registers' and `store_inferior_registers'
4211 in `HOST-nat.c'. If this symbol is _not_ defined, and
4212 `infptrace.c' is included in this configuration, the default
4213 routines in `infptrace.c' are used for these functions.
4216 This macro is normally defined to be the number of the first
4217 floating point register, if the machine has such registers. As
4218 such, it would appear only in target-specific code. However,
4219 `/proc' support uses this to decide whether floats are in use on
4222 `GET_LONGJMP_TARGET'
4223 For most machines, this is a target-dependent parameter. On the
4224 DECstation and the Iris, this is a native-dependent parameter,
4225 since `setjmp.h' is needed to define it.
4227 This macro determines the target PC address that `longjmp' will
4228 jump to, assuming that we have just stopped at a longjmp
4229 breakpoint. It takes a `CORE_ADDR *' as argument, and stores the
4230 target PC value through this pointer. It examines the current
4231 state of the machine as needed.
4233 `I386_USE_GENERIC_WATCHPOINTS'
4234 An x86-based machine can define this to use the generic x86
4235 watchpoint support; see *Note I386_USE_GENERIC_WATCHPOINTS:
4239 Define this to the address of the `u' structure (the "user
4240 struct", also known as the "u-page") in kernel virtual memory.
4241 GDB needs to know this so that it can subtract this address from
4242 absolute addresses in the upage, that are obtained via ptrace or
4243 from core files. On systems that don't need this value, set it to
4246 `KERNEL_U_ADDR_HPUX'
4247 Define this to cause GDB to determine the address of `u' at
4248 runtime, by using HP-style `nlist' on the kernel's image in the
4251 `ONE_PROCESS_WRITETEXT'
4252 Define this to be able to, when a breakpoint insertion fails, warn
4253 the user that another process may be running with the same
4257 Defines the format for the name of a `/proc' device. Should be
4258 defined in `nm.h' _only_ in order to override the default
4259 definition in `procfs.c'.
4262 The type of the third argument to the `ptrace' system call, if it
4263 exists and is different from `int'.
4266 Defines the offset of the registers in the "u area".
4268 `SHELL_COMMAND_CONCAT'
4269 If defined, is a string to prefix on the shell command used to
4273 If defined, this is the name of the shell to use to run the
4274 inferior. Defaults to `"/bin/sh"'.
4276 `SOLIB_ADD (FILENAME, FROM_TTY, TARG, READSYMS)'
4277 Define this to expand into an expression that will cause the
4278 symbols in FILENAME to be added to GDB's symbol table. If READSYMS
4279 is zero symbols are not read but any necessary low level
4280 processing for FILENAME is still done.
4282 `SOLIB_CREATE_INFERIOR_HOOK'
4283 Define this to expand into any shared-library-relocation code that
4284 you want to be run just after the child process has been forked.
4286 `START_INFERIOR_TRAPS_EXPECTED'
4287 When starting an inferior, GDB normally expects to trap twice;
4288 once when the shell execs, and once when the program itself execs.
4289 If the actual number of traps is something other than 2, then
4290 define this macro to expand into the number expected.
4293 This determines whether small routines in `*-tdep.c', which
4294 translate register values between GDB's internal representation
4295 and the `/proc' representation, are compiled.
4298 This is the offset of the registers in the upage. It need only be
4299 defined if the generic ptrace register access routines in
4300 `infptrace.c' are being used (that is, `infptrace.c' is configured
4301 in, and `FETCH_INFERIOR_REGISTERS' is not defined). If the
4302 default value from `infptrace.c' is good enough, leave it
4305 The default value means that u.u_ar0 _points to_ the location of
4306 the registers. I'm guessing that `#define U_REGS_OFFSET 0' means
4307 that `u.u_ar0' _is_ the location of the registers.
4313 Define this to debug `ptrace' calls.
4316 File: gdbint.info, Node: Support Libraries, Next: Coding, Prev: Native Debugging, Up: Top
4318 12 Support Libraries
4319 ********************
4324 BFD provides support for GDB in several ways:
4326 _identifying executable and core files_
4327 BFD will identify a variety of file types, including a.out, coff,
4328 and several variants thereof, as well as several kinds of core
4331 _access to sections of files_
4332 BFD parses the file headers to determine the names, virtual
4333 addresses, sizes, and file locations of all the various named
4334 sections in files (such as the text section or the data section).
4335 GDB simply calls BFD to read or write section X at byte offset Y
4338 _specialized core file support_
4339 BFD provides routines to determine the failing command name stored
4340 in a core file, the signal with which the program failed, and
4341 whether a core file matches (i.e. could be a core dump of) a
4342 particular executable file.
4344 _locating the symbol information_
4345 GDB uses an internal interface of BFD to determine where to find
4346 the symbol information in an executable file or symbol-file. GDB
4347 itself handles the reading of symbols, since BFD does not
4348 "understand" debug symbols, but GDB uses BFD's cached information
4349 to find the symbols, string table, etc.
4354 The opcodes library provides GDB's disassembler. (It's a separate
4355 library because it's also used in binutils, for `objdump').
4366 The `libiberty' library provides a set of functions and features that
4367 integrate and improve on functionality found in modern operating
4368 systems. Broadly speaking, such features can be divided into three
4369 groups: supplemental functions (functions that may be missing in some
4370 environments and operating systems), replacement functions (providing a
4371 uniform and easier to use interface for commonly used standard
4372 functions), and extensions (which provide additional functionality
4373 beyond standard functions).
4375 GDB uses various features provided by the `libiberty' library, for
4376 instance the C++ demangler, the IEEE floating format support functions,
4377 the input options parser `getopt', the `obstack' extension, and other
4380 12.5.1 `obstacks' in GDB
4381 ------------------------
4383 The obstack mechanism provides a convenient way to allocate and free
4384 chunks of memory. Each obstack is a pool of memory that is managed
4385 like a stack. Objects (of any nature, size and alignment) are
4386 allocated and freed in a LIFO fashion on an obstack (see `libiberty''s
4387 documenatation for a more detailed explanation of `obstacks').
4389 The most noticeable use of the `obstacks' in GDB is in object files.
4390 There is an obstack associated with each internal representation of an
4391 object file. Lots of things get allocated on these `obstacks':
4392 dictionary entries, blocks, blockvectors, symbols, minimal symbols,
4393 types, vectors of fundamental types, class fields of types, object
4394 files section lists, object files section offets lists, line tables,
4395 symbol tables, partial symbol tables, string tables, symbol table
4396 private data, macros tables, debug information sections and entries,
4397 import and export lists (som), unwind information (hppa), dwarf2
4398 location expressions data. Plus various strings such as directory
4399 names strings, debug format strings, names of types.
4401 An essential and convenient property of all data on `obstacks' is
4402 that memory for it gets allocated (with `obstack_alloc') at various
4403 times during a debugging sesssion, but it is released all at once using
4404 the `obstack_free' function. The `obstack_free' function takes a
4405 pointer to where in the stack it must start the deletion from (much
4406 like the cleanup chains have a pointer to where to start the cleanups).
4407 Because of the stack like structure of the `obstacks', this allows to
4408 free only a top portion of the obstack. There are a few instances in
4409 GDB where such thing happens. Calls to `obstack_free' are done after
4410 some local data is allocated to the obstack. Only the local data is
4411 deleted from the obstack. Of course this assumes that nothing between
4412 the `obstack_alloc' and the `obstack_free' allocates anything else on
4413 the same obstack. For this reason it is best and safest to use
4414 temporary `obstacks'.
4416 Releasing the whole obstack is also not safe per se. It is safe only
4417 under the condition that we know the `obstacks' memory is no longer
4418 needed. In GDB we get rid of the `obstacks' only when we get rid of
4419 the whole objfile(s), for instance upon reading a new symbol file.
4442 12.7 Array Containers
4443 =====================
4445 Often it is necessary to manipulate a dynamic array of a set of
4446 objects. C forces some bookkeeping on this, which can get cumbersome
4447 and repetative. The `vec.h' file contains macros for defining and
4448 using a typesafe vector type. The functions defined will be inlined
4449 when compiling, and so the abstraction cost should be zero. Domain
4450 checks are added to detect programming errors.
4452 An example use would be an array of symbols or section information.
4453 The array can be grown as symbols are read in (or preallocated), and
4454 the accessor macros provided keep care of all the necessary
4455 bookkeeping. Because the arrays are type safe, there is no danger of
4456 accidentally mixing up the contents. Think of these as C++ templates,
4457 but implemented in C.
4459 Because of the different behavior of structure objects, scalar
4460 objects and of pointers, there are three flavors of vector, one for
4461 each of these variants. Both the structure object and pointer variants
4462 pass pointers to objects around -- in the former case the pointers are
4463 stored into the vector and in the latter case the pointers are
4464 dereferenced and the objects copied into the vector. The scalar object
4465 variant is suitable for `int'-like objects, and the vector elements are
4468 There are both `index' and `iterate' accessors. The iterator
4469 returns a boolean iteration condition and updates the iteration
4470 variable passed by reference. Because the iterator will be inlined,
4471 the address-of can be optimized away.
4473 The vectors are implemented using the trailing array idiom, thus they
4474 are not resizeable without changing the address of the vector object
4475 itself. This means you cannot have variables or fields of vector type
4476 -- always use a pointer to a vector. The one exception is the final
4477 field of a structure, which could be a vector type. You will have to
4478 use the `embedded_size' & `embedded_init' calls to create such objects,
4479 and they will probably not be resizeable (so don't use the "safe"
4480 allocation variants). The trailing array idiom is used (rather than a
4481 pointer to an array of data), because, if we allow `NULL' to also
4482 represent an empty vector, empty vectors occupy minimal space in the
4483 structure containing them.
4485 Each operation that increases the number of active elements is
4486 available in "quick" and "safe" variants. The former presumes that
4487 there is sufficient allocated space for the operation to succeed (it
4488 dies if there is not). The latter will reallocate the vector, if
4489 needed. Reallocation causes an exponential increase in vector size.
4490 If you know you will be adding N elements, it would be more efficient
4491 to use the reserve operation before adding the elements with the
4492 "quick" operation. This will ensure there are at least as many
4493 elements as you ask for, it will exponentially increase if there are
4494 too few spare slots. If you want reserve a specific number of slots,
4495 but do not want the exponential increase (for instance, you know this
4496 is the last allocation), use a negative number for reservation. You
4497 can also create a vector of a specific size from the get go.
4499 You should prefer the push and pop operations, as they append and
4500 remove from the end of the vector. If you need to remove several items
4501 in one go, use the truncate operation. The insert and remove
4502 operations allow you to change elements in the middle of the vector.
4503 There are two remove operations, one which preserves the element
4504 ordering `ordered_remove', and one which does not `unordered_remove'.
4505 The latter function copies the end element into the removed slot,
4506 rather than invoke a memmove operation. The `lower_bound' function
4507 will determine where to place an item in the array using insert that
4508 will maintain sorted order.
4510 If you need to directly manipulate a vector, then the `address'
4511 accessor will return the address of the start of the vector. Also the
4512 `space' predicate will tell you whether there is spare capacity in the
4513 vector. You will not normally need to use these two functions.
4515 Vector types are defined using a `DEF_VEC_{O,P,I}(TYPENAME)' macro.
4516 Variables of vector type are declared using a `VEC(TYPENAME)' macro.
4517 The characters `O', `P' and `I' indicate whether TYPENAME is an object
4518 (`O'), pointer (`P') or integral (`I') type. Be careful to pick the
4519 correct one, as you'll get an awkward and inefficient API if you use
4520 the wrong one. There is a check, which results in a compile-time
4521 warning, for the `P' and `I' versions, but there is no check for the
4522 `O' versions, as that is not possible in plain C.
4524 An example of their use would be,
4526 DEF_VEC_P(tree); // non-managed tree vector.
4529 VEC(tree) *v; // A (pointer to) a vector of tree pointers.
4532 struct my_struct *s;
4534 if (VEC_length(tree, s->v)) { we have some contents }
4535 VEC_safe_push(tree, s->v, decl); // append some decl onto the end
4536 for (ix = 0; VEC_iterate(tree, s->v, ix, elt); ix++)
4537 { do something with elt }
4539 The `vec.h' file provides details on how to invoke the various
4540 accessors provided. They are enumerated here:
4543 Return the number of items in the array,
4546 Return true if the array has no elements.
4550 Return the last or arbitrary item in the array.
4553 Access an array element and indicate whether the array has been
4558 Create and destroy an array.
4562 Helpers for embedding an array as the final element of another
4569 Return the amount of free space in an array.
4572 Ensure a certain amount of free space.
4576 Append to an array, either assuming the space is available, or
4577 making sure that it is.
4580 Remove the last item from an array.
4583 Remove several items from the end of an array.
4586 Add several items to the end of an array.
4589 Overwrite an item in the array.
4593 Insert an item into the middle of the array. Either the space must
4594 already exist, or the space is created.
4596 `VEC_ordered_remove'
4597 `VEC_unordered_remove'
4598 Remove an item from the array, preserving order or not.
4601 Remove a set of items from the array.
4604 Provide the address of the first element.
4607 Binary search the array.
4614 File: gdbint.info, Node: Coding, Next: Porting GDB, Prev: Support Libraries, Up: Top
4619 This chapter covers topics that are lower-level than the major
4625 Cleanups are a structured way to deal with things that need to be done
4628 When your code does something (e.g., `xmalloc' some memory, or
4629 `open' a file) that needs to be undone later (e.g., `xfree' the memory
4630 or `close' the file), it can make a cleanup. The cleanup will be done
4631 at some future point: when the command is finished and control returns
4632 to the top level; when an error occurs and the stack is unwound; or
4633 when your code decides it's time to explicitly perform cleanups.
4634 Alternatively you can elect to discard the cleanups you created.
4638 `struct cleanup *OLD_CHAIN;'
4639 Declare a variable which will hold a cleanup chain handle.
4641 `OLD_CHAIN = make_cleanup (FUNCTION, ARG);'
4642 Make a cleanup which will cause FUNCTION to be called with ARG (a
4643 `char *') later. The result, OLD_CHAIN, is a handle that can
4644 later be passed to `do_cleanups' or `discard_cleanups'. Unless
4645 you are going to call `do_cleanups' or `discard_cleanups', you can
4646 ignore the result from `make_cleanup'.
4648 `do_cleanups (OLD_CHAIN);'
4649 Do all cleanups added to the chain since the corresponding
4650 `make_cleanup' call was made.
4652 `discard_cleanups (OLD_CHAIN);'
4653 Same as `do_cleanups' except that it just removes the cleanups from
4654 the chain and does not call the specified functions.
4656 Cleanups are implemented as a chain. The handle returned by
4657 `make_cleanups' includes the cleanup passed to the call and any later
4658 cleanups appended to the chain (but not yet discarded or performed).
4661 make_cleanup (a, 0);
4663 struct cleanup *old = make_cleanup (b, 0);
4669 will call `c()' and `b()' but will not call `a()'. The cleanup that
4670 calls `a()' will remain in the cleanup chain, and will be done later
4671 unless otherwise discarded.
4673 Your function should explicitly do or discard the cleanups it
4674 creates. Failing to do this leads to non-deterministic behavior since
4675 the caller will arbitrarily do or discard your functions cleanups.
4676 This need leads to two common cleanup styles.
4678 The first style is try/finally. Before it exits, your code-block
4679 calls `do_cleanups' with the old cleanup chain and thus ensures that
4680 your code-block's cleanups are always performed. For instance, the
4681 following code-segment avoids a memory leak problem (even when `error'
4682 is called and a forced stack unwind occurs) by ensuring that the
4683 `xfree' will always be called:
4685 struct cleanup *old = make_cleanup (null_cleanup, 0);
4686 data = xmalloc (sizeof blah);
4687 make_cleanup (xfree, data);
4691 The second style is try/except. Before it exits, your code-block
4692 calls `discard_cleanups' with the old cleanup chain and thus ensures
4693 that any created cleanups are not performed. For instance, the
4694 following code segment, ensures that the file will be closed but only
4695 if there is an error:
4697 FILE *file = fopen ("afile", "r");
4698 struct cleanup *old = make_cleanup (close_file, file);
4700 discard_cleanups (old);
4703 Some functions, e.g., `fputs_filtered()' or `error()', specify that
4704 they "should not be called when cleanups are not in place". This means
4705 that any actions you need to reverse in the case of an error or
4706 interruption must be on the cleanup chain before you call these
4707 functions, since they might never return to your code (they `longjmp'
4710 13.2 Per-architecture module data
4711 =================================
4713 The multi-arch framework includes a mechanism for adding module
4714 specific per-architecture data-pointers to the `struct gdbarch'
4715 architecture object.
4717 A module registers one or more per-architecture data-pointers using:
4719 -- Function: struct gdbarch_data *gdbarch_data_register_pre_init
4720 (gdbarch_data_pre_init_ftype *PRE_INIT)
4721 PRE_INIT is used to, on-demand, allocate an initial value for a
4722 per-architecture data-pointer using the architecture's obstack
4723 (passed in as a parameter). Since PRE_INIT can be called during
4724 architecture creation, it is not parameterized with the
4725 architecture. and must not call modules that use per-architecture
4728 -- Function: struct gdbarch_data *gdbarch_data_register_post_init
4729 (gdbarch_data_post_init_ftype *POST_INIT)
4730 POST_INIT is used to obtain an initial value for a
4731 per-architecture data-pointer _after_. Since POST_INIT is always
4732 called after architecture creation, it both receives the fully
4733 initialized architecture and is free to call modules that use
4734 per-architecture data (care needs to be taken to ensure that those
4735 other modules do not try to call back to this module as that will
4736 create in cycles in the initialization call graph).
4738 These functions return a `struct gdbarch_data' that is used to
4739 identify the per-architecture data-pointer added for that module.
4741 The per-architecture data-pointer is accessed using the function:
4743 -- Function: void *gdbarch_data (struct gdbarch *GDBARCH, struct
4744 gdbarch_data *DATA_HANDLE)
4745 Given the architecture ARCH and module data handle DATA_HANDLE
4746 (returned by `gdbarch_data_register_pre_init' or
4747 `gdbarch_data_register_post_init'), this function returns the
4748 current value of the per-architecture data-pointer. If the data
4749 pointer is `NULL', it is first initialized by calling the
4750 corresponding PRE_INIT or POST_INIT method.
4752 The examples below assume the following definitions:
4754 struct nozel { int total; };
4755 static struct gdbarch_data *nozel_handle;
4757 A module can extend the architecture vector, adding additional
4758 per-architecture data, using the PRE_INIT method. The module's
4759 per-architecture data is then initialized during architecture creation.
4761 In the below, the module's per-architecture _nozel_ is added. An
4762 architecture can specify its nozel by calling `set_gdbarch_nozel' from
4766 nozel_pre_init (struct obstack *obstack)
4768 struct nozel *data = OBSTACK_ZALLOC (obstack, struct nozel);
4773 set_gdbarch_nozel (struct gdbarch *gdbarch, int total)
4775 struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
4776 data->total = nozel;
4779 A module can on-demand create architecture dependant data structures
4782 In the below, the nozel's total is computed on-demand by
4783 `nozel_post_init' using information obtained from the architecture.
4786 nozel_post_init (struct gdbarch *gdbarch)
4788 struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel);
4789 nozel->total = gdbarch... (gdbarch);
4794 nozel_total (struct gdbarch *gdbarch)
4796 struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
4800 13.3 Wrapping Output Lines
4801 ==========================
4803 Output that goes through `printf_filtered' or `fputs_filtered' or
4804 `fputs_demangled' needs only to have calls to `wrap_here' added in
4805 places that would be good breaking points. The utility routines will
4806 take care of actually wrapping if the line width is exceeded.
4808 The argument to `wrap_here' is an indentation string which is
4809 printed _only_ if the line breaks there. This argument is saved away
4810 and used later. It must remain valid until the next call to
4811 `wrap_here' or until a newline has been printed through the
4812 `*_filtered' functions. Don't pass in a local variable and then return!
4814 It is usually best to call `wrap_here' after printing a comma or
4815 space. If you call it before printing a space, make sure that your
4816 indentation properly accounts for the leading space that will print if
4817 the line wraps there.
4819 Any function or set of functions that produce filtered output must
4820 finish by printing a newline, to flush the wrap buffer, before switching
4821 to unfiltered (`printf') output. Symbol reading routines that print
4822 warnings are a good example.
4824 13.4 GDB Coding Standards
4825 =========================
4827 GDB follows the GNU coding standards, as described in
4828 `etc/standards.texi'. This file is also available for anonymous FTP
4829 from GNU archive sites. GDB takes a strict interpretation of the
4830 standard; in general, when the GNU standard recommends a practice but
4831 does not require it, GDB requires it.
4833 GDB follows an additional set of coding standards specific to GDB,
4834 as described in the following sections.
4839 GDB assumes an ISO/IEC 9899:1990 (a.k.a. ISO C90) compliant compiler.
4841 GDB does not assume an ISO C or POSIX compliant C library.
4843 13.4.2 Memory Management
4844 ------------------------
4846 GDB does not use the functions `malloc', `realloc', `calloc', `free'
4849 GDB uses the functions `xmalloc', `xrealloc' and `xcalloc' when
4850 allocating memory. Unlike `malloc' et.al. these functions do not
4851 return when the memory pool is empty. Instead, they unwind the stack
4852 using cleanups. These functions return `NULL' when requested to
4853 allocate a chunk of memory of size zero.
4855 _Pragmatics: By using these functions, the need to check every
4856 memory allocation is removed. These functions provide portable
4859 GDB does not use the function `free'.
4861 GDB uses the function `xfree' to return memory to the memory pool.
4862 Consistent with ISO-C, this function ignores a request to free a `NULL'
4865 _Pragmatics: On some systems `free' fails when passed a `NULL'
4868 GDB can use the non-portable function `alloca' for the allocation of
4869 small temporary values (such as strings).
4871 _Pragmatics: This function is very non-portable. Some systems
4872 restrict the memory being allocated to no more than a few kilobytes._
4874 GDB uses the string function `xstrdup' and the print function
4877 _Pragmatics: `asprintf' and `strdup' can fail. Print functions such
4878 as `sprintf' are very prone to buffer overflow errors._
4880 13.4.3 Compiler Warnings
4881 ------------------------
4883 With few exceptions, developers should include the configuration option
4884 `--enable-gdb-build-warnings=,-Werror' when building GDB. The
4885 exceptions are listed in the file `gdb/MAINTAINERS'.
4887 This option causes GDB (when built using GCC) to be compiled with a
4888 carefully selected list of compiler warning flags. Any warnings from
4889 those flags being treated as errors.
4891 The current list of warning flags includes:
4894 Since GDB coding standard requires all functions to be declared
4895 using a prototype, the flag has the side effect of ensuring that
4896 prototyped functions are always visible with out resorting to
4897 `-Wstrict-prototypes'.
4900 Such code often appears to work except on instruction set
4901 architectures that use register windows.
4908 `-Wformat-nonliteral'
4909 Since GDB uses the `format printf' attribute on all `printf' like
4910 functions these check not just `printf' calls but also calls to
4911 functions such as `fprintf_unfiltered'.
4914 This warning includes uses of the assignment operator within an
4922 This warning has the additional benefit of detecting the absence
4923 of the `case' reserved word in a switch statement:
4924 enum { FD_SCHEDULED, NOTHING_SCHEDULED } sched;
4939 In version 4.0, GCC began warning about pointer argument passing or
4940 assignment even when the source and destination differed only in
4941 signedness. However, most GDB code doesn't distinguish carefully
4942 between `char' and `unsigned char'. In early 2006 the GDB
4943 developers decided correcting these warnings wasn't worth the time
4947 _Pragmatics: Due to the way that GDB is implemented most functions
4948 have unused parameters. Consequently the warning `-Wunused-parameter'
4949 is precluded from the list. The macro `ATTRIBUTE_UNUSED' is not used
4950 as it leads to false negatives -- it is not an error to have
4951 `ATTRIBUTE_UNUSED' on a parameter that is being used. The options
4952 `-Wall' and `-Wunused' are also precluded because they both include
4953 `-Wunused-parameter'._
4955 _Pragmatics: GDB has not simply accepted the warnings enabled by
4956 `-Wall -Werror -W...'. Instead it is selecting warnings when and where
4957 their benefits can be demonstrated._
4962 The standard GNU recommendations for formatting must be followed
4965 A function declaration should not have its name in column zero. A
4966 function definition should have its name in column zero.
4969 static void foo (void);
4976 _Pragmatics: This simplifies scripting. Function definitions can be
4977 found using `^function-name'._
4979 There must be a space between a function or macro name and the
4980 opening parenthesis of its argument list (except for macro definitions,
4981 as required by C). There must not be a space after an open
4982 paren/bracket or before a close paren/bracket.
4984 While additional whitespace is generally helpful for reading, do not
4985 use more than one blank line to separate blocks, and avoid adding
4986 whitespace after the end of a program line (as of 1/99, some 600 lines
4987 had whitespace after the semicolon). Excess whitespace causes
4988 difficulties for `diff' and `patch' utilities.
4990 Pointers are declared using the traditional K&R C style:
5002 The standard GNU requirements on comments must be followed strictly.
5004 Block comments must appear in the following form, with no `/*'- or
5005 `*/'-only lines, and no leading `*':
5007 /* Wait for control to return from inferior to debugger. If inferior
5008 gets a signal, we may decide to start it up again instead of
5009 returning. That is why there is a loop in this function. When
5010 this function actually returns it means the inferior should be left
5011 stopped and GDB should read more commands. */
5013 (Note that this format is encouraged by Emacs; tabbing for a
5014 multi-line comment works correctly, and `M-q' fills the block
5017 Put a blank line between the block comments preceding function or
5018 variable definitions, and the definition itself.
5020 In general, put function-body comments on lines by themselves, rather
5021 than trying to fit them into the 20 characters left at the end of a
5022 line, since either the comment or the code will inevitably get longer
5023 than will fit, and then somebody will have to move it anyhow.
5028 Code must not depend on the sizes of C data types, the format of the
5029 host's floating point numbers, the alignment of anything, or the order
5030 of evaluation of expressions.
5032 Use functions freely. There are only a handful of compute-bound
5033 areas in GDB that might be affected by the overhead of a function call,
5034 mainly in symbol reading. Most of GDB's performance is limited by the
5035 target interface (whether serial line or system call).
5037 However, use functions with moderation. A thousand one-line
5038 functions are just as hard to understand as a single thousand-line
5041 _Macros are bad, M'kay._ (But if you have to use a macro, make sure
5042 that the macro arguments are protected with parentheses.)
5044 Declarations like `struct foo *' should be used in preference to
5045 declarations like `typedef struct foo { ... } *foo_ptr'.
5047 13.4.7 Function Prototypes
5048 --------------------------
5050 Prototypes must be used when both _declaring_ and _defining_ a
5051 function. Prototypes for GDB functions must include both the argument
5052 type and name, with the name matching that used in the actual function
5055 All external functions should have a declaration in a header file
5056 that callers include, except for `_initialize_*' functions, which must
5057 be external so that `init.c' construction works, but shouldn't be
5058 visible to random source files.
5060 Where a source file needs a forward declaration of a static function,
5061 that declaration must appear in a block near the top of the source file.
5063 13.4.8 Internal Error Recovery
5064 ------------------------------
5066 During its execution, GDB can encounter two types of errors. User
5067 errors and internal errors. User errors include not only a user
5068 entering an incorrect command but also problems arising from corrupt
5069 object files and system errors when interacting with the target.
5070 Internal errors include situations where GDB has detected, at run time,
5071 a corrupt or erroneous situation.
5073 When reporting an internal error, GDB uses `internal_error' and
5076 GDB must not call `abort' or `assert'.
5078 _Pragmatics: There is no `internal_warning' function. Either the
5079 code detected a user error, recovered from it and issued a `warning' or
5080 the code failed to correctly recover from the user error and issued an
5086 Any file used when building the core of GDB must be in lower case. Any
5087 file used when building the core of GDB must be 8.3 unique. These
5088 requirements apply to both source and generated files.
5090 _Pragmatics: The core of GDB must be buildable on many platforms
5091 including DJGPP and MacOS/HFS. Every time an unfriendly file is
5092 introduced to the build process both `Makefile.in' and `configure.in'
5093 need to be modified accordingly. Compare the convoluted conversion
5094 process needed to transform `COPYING' into `copying.c' with the
5095 conversion needed to transform `version.in' into `version.c'._
5097 Any file non 8.3 compliant file (that is not used when building the
5098 core of GDB) must be added to `gdb/config/djgpp/fnchange.lst'.
5100 _Pragmatics: This is clearly a compromise._
5102 When GDB has a local version of a system header file (ex `string.h')
5103 the file name based on the POSIX header prefixed with `gdb_'
5104 (`gdb_string.h'). These headers should be relatively independent: they
5105 should use only macros defined by `configure', the compiler, or the
5106 host; they should include only system headers; they should refer only
5107 to system types. They may be shared between multiple programs, e.g.
5110 For other files `-' is used as the separator.
5112 13.4.10 Include Files
5113 ---------------------
5115 A `.c' file should include `defs.h' first.
5117 A `.c' file should directly include the `.h' file of every
5118 declaration and/or definition it directly refers to. It cannot rely on
5121 A `.h' file should directly include the `.h' file of every
5122 declaration and/or definition it directly refers to. It cannot rely on
5123 indirect inclusion. Exception: The file `defs.h' does not need to be
5126 An external declaration should only appear in one include file.
5128 An external declaration should never appear in a `.c' file.
5129 Exception: a declaration for the `_initialize' function that pacifies
5130 `-Wmissing-declaration'.
5132 A `typedef' definition should only appear in one include file.
5134 An opaque `struct' declaration can appear in multiple `.h' files.
5135 Where possible, a `.h' file should use an opaque `struct' declaration
5136 instead of an include.
5138 All `.h' files should be wrapped in:
5140 #ifndef INCLUDE_FILE_NAME_H
5141 #define INCLUDE_FILE_NAME_H
5145 13.4.11 Clean Design and Portable Implementation
5146 ------------------------------------------------
5148 In addition to getting the syntax right, there's the little question of
5149 semantics. Some things are done in certain ways in GDB because long
5150 experience has shown that the more obvious ways caused various kinds of
5153 You can't assume the byte order of anything that comes from a target
5154 (including VALUEs, object files, and instructions). Such things must
5155 be byte-swapped using `SWAP_TARGET_AND_HOST' in GDB, or one of the swap
5156 routines defined in `bfd.h', such as `bfd_get_32'.
5158 You can't assume that you know what interface is being used to talk
5159 to the target system. All references to the target must go through the
5160 current `target_ops' vector.
5162 You can't assume that the host and target machines are the same
5163 machine (except in the "native" support modules). In particular, you
5164 can't assume that the target machine's header files will be available
5165 on the host machine. Target code must bring along its own header files
5166 - written from scratch or explicitly donated by their owner, to avoid
5169 Insertion of new `#ifdef''s will be frowned upon. It's much better
5170 to write the code portably than to conditionalize it for various
5173 New `#ifdef''s which test for specific compilers or manufacturers or
5174 operating systems are unacceptable. All `#ifdef''s should test for
5175 features. The information about which configurations contain which
5176 features should be segregated into the configuration files. Experience
5177 has proven far too often that a feature unique to one particular system
5178 often creeps into other systems; and that a conditional based on some
5179 predefined macro for your current system will become worthless over
5180 time, as new versions of your system come out that behave differently
5181 with regard to this feature.
5183 Adding code that handles specific architectures, operating systems,
5184 target interfaces, or hosts, is not acceptable in generic code.
5186 One particularly notorious area where system dependencies tend to
5187 creep in is handling of file names. The mainline GDB code assumes
5188 Posix semantics of file names: absolute file names begin with a forward
5189 slash `/', slashes are used to separate leading directories,
5190 case-sensitive file names. These assumptions are not necessarily true
5191 on non-Posix systems such as MS-Windows. To avoid system-dependent
5192 code where you need to take apart or construct a file name, use the
5193 following portable macros:
5195 `HAVE_DOS_BASED_FILE_SYSTEM'
5196 This preprocessing symbol is defined to a non-zero value on hosts
5197 whose filesystems belong to the MS-DOS/MS-Windows family. Use this
5198 symbol to write conditional code which should only be compiled for
5201 `IS_DIR_SEPARATOR (C)'
5202 Evaluates to a non-zero value if C is a directory separator
5203 character. On Unix and GNU/Linux systems, only a slash `/' is
5204 such a character, but on Windows, both `/' and `\' will pass.
5206 `IS_ABSOLUTE_PATH (FILE)'
5207 Evaluates to a non-zero value if FILE is an absolute file name.
5208 For Unix and GNU/Linux hosts, a name which begins with a slash `/'
5209 is absolute. On DOS and Windows, `d:/foo' and `x:\bar' are also
5210 absolute file names.
5212 `FILENAME_CMP (F1, F2)'
5213 Calls a function which compares file names F1 and F2 as
5214 appropriate for the underlying host filesystem. For Posix systems,
5215 this simply calls `strcmp'; on case-insensitive filesystems it
5216 will call `strcasecmp' instead.
5219 Evaluates to a character which separates directories in
5220 `PATH'-style lists, typically held in environment variables. This
5221 character is `:' on Unix, `;' on DOS and Windows.
5224 This evaluates to a constant string you should use to produce an
5225 absolute filename from leading directories and the file's basename.
5226 `SLASH_STRING' is `"/"' on most systems, but might be `"\\"' for
5227 some Windows-based ports.
5229 In addition to using these macros, be sure to use portable library
5230 functions whenever possible. For example, to extract a directory or a
5231 basename part from a file name, use the `dirname' and `basename'
5232 library functions (available in `libiberty' for platforms which don't
5233 provide them), instead of searching for a slash with `strrchr'.
5235 Another way to generalize GDB along a particular interface is with an
5236 attribute struct. For example, GDB has been generalized to handle
5237 multiple kinds of remote interfaces--not by `#ifdef's everywhere, but
5238 by defining the `target_ops' structure and having a current target (as
5239 well as a stack of targets below it, for memory references). Whenever
5240 something needs to be done that depends on which remote interface we are
5241 using, a flag in the current target_ops structure is tested (e.g.,
5242 `target_has_stack'), or a function is called through a pointer in the
5243 current target_ops structure. In this way, when a new remote interface
5244 is added, only one module needs to be touched--the one that actually
5245 implements the new remote interface. Other examples of
5246 attribute-structs are BFD access to multiple kinds of object file
5247 formats, or GDB's access to multiple source languages.
5249 Please avoid duplicating code. For example, in GDB 3.x all the code
5250 interfacing between `ptrace' and the rest of GDB was duplicated in
5251 `*-dep.c', and so changing something was very painful. In GDB 4.x,
5252 these have all been consolidated into `infptrace.c'. `infptrace.c' can
5253 deal with variations between systems the same way any system-independent
5254 file would (hooks, `#if defined', etc.), and machines which are
5255 radically different don't need to use `infptrace.c' at all.
5257 All debugging code must be controllable using the `set debug MODULE'
5258 command. Do not use `printf' to print trace messages. Use
5259 `fprintf_unfiltered(gdb_stdlog, ...'. Do not use `#ifdef DEBUG'.
5262 File: gdbint.info, Node: Porting GDB, Next: Versions and Branches, Prev: Coding, Up: Top
5267 Most of the work in making GDB compile on a new machine is in
5268 specifying the configuration of the machine. This is done in a
5269 dizzying variety of header files and configuration scripts, which we
5270 hope to make more sensible soon. Let's say your new host is called an
5271 XYZ (e.g., `sun4'), and its full three-part configuration name is
5272 `ARCH-XVEND-XOS' (e.g., `sparc-sun-sunos4'). In particular:
5274 * In the top level directory, edit `config.sub' and add ARCH, XVEND,
5275 and XOS to the lists of supported architectures, vendors, and
5276 operating systems near the bottom of the file. Also, add XYZ as
5277 an alias that maps to `ARCH-XVEND-XOS'. You can test your changes
5284 ./config.sub `ARCH-XVEND-XOS'
5286 which should both respond with `ARCH-XVEND-XOS' and no error
5289 You need to port BFD, if that hasn't been done already. Porting
5290 BFD is beyond the scope of this manual.
5292 * To configure GDB itself, edit `gdb/configure.host' to recognize
5293 your system and set `gdb_host' to XYZ, and (unless your desired
5294 target is already available) also edit `gdb/configure.tgt',
5295 setting `gdb_target' to something appropriate (for instance, XYZ).
5297 _Maintainer's note: Work in progress. The file
5298 `gdb/configure.host' originally needed to be modified when either a
5299 new native target or a new host machine was being added to GDB.
5300 Recent changes have removed this requirement. The file now only
5301 needs to be modified when adding a new native configuration. This
5302 will likely changed again in the future._
5304 * Finally, you'll need to specify and define GDB's host-, native-,
5305 and target-dependent `.h' and `.c' files used for your
5309 File: gdbint.info, Node: Versions and Branches, Next: Start of New Year Procedure, Prev: Porting GDB, Up: Top
5311 15 Versions and Branches
5312 ************************
5317 GDB's version is determined by the file `gdb/version.in' and takes one
5318 of the following forms:
5321 MAJOR.MINOR.PATCHLEVEL
5322 an official release (e.g., 6.2 or 6.2.1)
5324 MAJOR.MINOR.PATCHLEVEL.YYYYMMDD
5325 a snapshot taken at YYYY-MM-DD-gmt (e.g., 6.1.50.20020302,
5326 6.1.90.20020304, or 6.1.0.20020308)
5328 MAJOR.MINOR.PATCHLEVEL.YYYYMMDD-cvs
5329 a CVS check out drawn on YYYY-MM-DD (e.g., 6.1.50.20020302-cvs,
5330 6.1.90.20020304-cvs, or 6.1.0.20020308-cvs)
5332 MAJOR.MINOR.PATCHLEVEL.YYYYMMDD (VENDOR)
5333 a vendor specific release of GDB, that while based on
5334 MAJOR.MINOR.PATCHLEVEL.YYYYMMDD, may include additional changes
5336 GDB's mainline uses the MAJOR and MINOR version numbers from the
5337 most recent release branch, with a PATCHLEVEL of 50. At the time each
5338 new release branch is created, the mainline's MAJOR and MINOR version
5339 numbers are updated.
5341 GDB's release branch is similar. When the branch is cut, the
5342 PATCHLEVEL is changed from 50 to 90. As draft releases are drawn from
5343 the branch, the PATCHLEVEL is incremented. Once the first release
5344 (MAJOR.MINOR) has been made, the PATCHLEVEL is set to 0 and updates
5345 have an incremented PATCHLEVEL.
5347 For snapshots, and CVS check outs, it is also possible to identify
5350 MAJOR.MINOR.50.YYYYMMDD
5351 drawn from the HEAD of mainline CVS (e.g., 6.1.50.20020302)
5353 MAJOR.MINOR.90.YYYYMMDD
5354 MAJOR.MINOR.91.YYYYMMDD ...
5355 drawn from a release branch prior to the release (e.g.,
5358 MAJOR.MINOR.0.YYYYMMDD
5359 MAJOR.MINOR.1.YYYYMMDD ...
5360 drawn from a release branch after the release (e.g.,
5363 If the previous GDB version is 6.1 and the current version is 6.2,
5364 then, substituting 6 for MAJOR and 1 or 2 for MINOR, here's an
5365 illustration of a typical sequence:
5371 +--------------------------.
5374 6.2.50.20020303-cvs 6.1.90 (draft #1)
5376 6.2.50.20020304-cvs 6.1.90.20020304-cvs
5378 6.2.50.20020305-cvs 6.1.91 (draft #2)
5380 6.2.50.20020306-cvs 6.1.91.20020306-cvs
5382 6.2.50.20020307-cvs 6.2 (release)
5384 6.2.50.20020308-cvs 6.2.0.20020308-cvs
5386 6.2.50.20020309-cvs 6.2.1 (update)
5388 6.2.50.20020310-cvs <branch closed>
5392 +--------------------------.
5395 6.3.50.20020312-cvs 6.2.90 (draft #1)
5398 15.2 Release Branches
5399 =====================
5401 GDB draws a release series (6.2, 6.2.1, ...) from a single release
5402 branch, and identifies that branch using the CVS branch tags:
5404 gdb_MAJOR_MINOR-YYYYMMDD-branchpoint
5405 gdb_MAJOR_MINOR-branch
5406 gdb_MAJOR_MINOR-YYYYMMDD-release
5408 _Pragmatics: To help identify the date at which a branch or release
5409 is made, both the branchpoint and release tags include the date that
5410 they are cut (YYYYMMDD) in the tag. The branch tag, denoting the head
5411 of the branch, does not need this._
5413 15.3 Vendor Branches
5414 ====================
5416 To avoid version conflicts, vendors are expected to modify the file
5417 `gdb/version.in' to include a vendor unique alphabetic identifier (an
5418 official GDB release never uses alphabetic characters in its version
5419 identifer). E.g., `6.2widgit2', or `6.2 (Widgit Inc Patch 2)'.
5421 15.4 Experimental Branches
5422 ==========================
5427 GDB permits the creation of branches, cut from the CVS repository, for
5428 experimental development. Branches make it possible for developers to
5429 share preliminary work, and maintainers to examine significant new
5432 The following are a set of guidelines for creating such branches:
5434 _a branch has an owner_
5435 The owner can set further policy for a branch, but may not change
5436 the ground rules. In particular, they can set a policy for
5437 commits (be it adding more reviewers or deciding who can commit).
5439 _all commits are posted_
5440 All changes committed to a branch shall also be posted to the GDB
5441 patches mailing list <gdb-patches@sources.redhat.com>. While
5442 commentary on such changes are encouraged, people should remember
5443 that the changes only apply to a branch.
5445 _all commits are covered by an assignment_
5446 This ensures that all changes belong to the Free Software
5447 Foundation, and avoids the possibility that the branch may become
5450 _a branch is focused_
5451 A focused branch has a single objective or goal, and does not
5452 contain unnecessary or irrelevant changes. Cleanups, where
5453 identified, being be pushed into the mainline as soon as possible.
5455 _a branch tracks mainline_
5456 This keeps the level of divergence under control. It also keeps
5457 the pressure on developers to push cleanups and other stuff into
5460 _a branch shall contain the entire GDB module_
5461 The GDB module `gdb' should be specified when creating a branch
5462 (branches of individual files should be avoided). *Note Tags::.
5464 _a branch shall be branded using `version.in'_
5465 The file `gdb/version.in' shall be modified so that it identifies
5466 the branch OWNER and branch NAME, e.g.,
5467 `6.2.50.20030303_owner_name' or `6.2 (Owner Name)'.
5473 To simplify the identification of GDB branches, the following branch
5474 tagging convention is strongly recommended:
5476 `OWNER_NAME-YYYYMMDD-branchpoint'
5477 `OWNER_NAME-YYYYMMDD-branch'
5478 The branch point and corresponding branch tag. YYYYMMDD is the
5479 date that the branch was created. A branch is created using the
5481 cvs rtag OWNER_NAME-YYYYMMDD-branchpoint gdb
5482 cvs rtag -b -r OWNER_NAME-YYYYMMDD-branchpoint \
5483 OWNER_NAME-YYYYMMDD-branch gdb
5485 `OWNER_NAME-YYYYMMDD-mergepoint'
5486 The tagged point, on the mainline, that was used when merging the
5487 branch on YYYYMMDD. To merge in all changes since the branch was
5488 cut, use a command sequence like:
5489 cvs rtag OWNER_NAME-YYYYMMDD-mergepoint gdb
5491 -jOWNER_NAME-YYYYMMDD-branchpoint
5492 -jOWNER_NAME-YYYYMMDD-mergepoint
5493 Similar sequences can be used to just merge in changes since the
5497 For further information on CVS, see Concurrent Versions System
5498 (http://www.gnu.org/software/cvs/).
5501 File: gdbint.info, Node: Start of New Year Procedure, Next: Releasing GDB, Prev: Versions and Branches, Up: Top
5503 16 Start of New Year Procedure
5504 ******************************
5506 At the start of each new year, the following actions should be
5509 * Rotate the ChangeLog file
5511 The current `ChangeLog' file should be renamed into
5512 `ChangeLog-YYYY' where YYYY is the year that has just passed. A
5513 new `ChangeLog' file should be created, and its contents should
5514 contain a reference to the previous ChangeLog. The following
5515 should also be preserved at the end of the new ChangeLog, in order
5516 to provide the appropriate settings when editing this file with
5522 version-control: never
5525 * Update the copyright year in the startup message
5527 Update the copyright year in file `top.c', function
5528 `print_gdb_version'.
5531 File: gdbint.info, Node: Releasing GDB, Next: Testsuite, Prev: Start of New Year Procedure, Up: Top
5536 17.1 Branch Commit Policy
5537 =========================
5539 The branch commit policy is pretty slack. GDB releases 5.0, 5.1 and
5540 5.2 all used the below:
5542 * The `gdb/MAINTAINERS' file still holds.
5544 * Don't fix something on the branch unless/until it is also fixed in
5545 the trunk. If this isn't possible, mentioning it in the
5546 `gdb/PROBLEMS' file is better than committing a hack.
5548 * When considering a patch for the branch, suggested criteria
5549 include: Does it fix a build? Does it fix the sequence `break
5550 main; run' when debugging a static binary?
5552 * The further a change is from the core of GDB, the less likely the
5553 change will worry anyone (e.g., target specific code).
5555 * Only post a proposal to change the core of GDB after you've sent
5556 individual bribes to all the people listed in the `MAINTAINERS'
5559 _Pragmatics: Provided updates are restricted to non-core
5560 functionality there is little chance that a broken change will be fatal.
5561 This means that changes such as adding a new architectures or (within
5562 reason) support for a new host are considered acceptable._
5564 17.2 Obsoleting code
5565 ====================
5567 Before anything else, poke the other developers (and around the source
5568 code) to see if there is anything that can be removed from GDB (an old
5569 target, an unused file).
5571 Obsolete code is identified by adding an `OBSOLETE' prefix to every
5572 line. Doing this means that it is easy to identify something that has
5573 been obsoleted when greping through the sources.
5575 The process is done in stages -- this is mainly to ensure that the
5576 wider GDB community has a reasonable opportunity to respond. Remember,
5577 everything on the Internet takes a week.
5579 1. Post the proposal on the GDB mailing list <gdb@sources.redhat.com>
5580 Creating a bug report to track the task's state, is also highly
5583 2. Wait a week or so.
5585 3. Post the proposal on the GDB Announcement mailing list
5586 <gdb-announce@sources.redhat.com>.
5588 4. Wait a week or so.
5590 5. Go through and edit all relevant files and lines so that they are
5591 prefixed with the word `OBSOLETE'.
5593 6. Wait until the next GDB version, containing this obsolete code,
5596 7. Remove the obsolete code.
5598 _Maintainer note: While removing old code is regrettable it is
5599 hopefully better for GDB's long term development. Firstly it helps the
5600 developers by removing code that is either no longer relevant or simply
5601 wrong. Secondly since it removes any history associated with the file
5602 (effectively clearing the slate) the developer has a much freer hand
5603 when it comes to fixing broken files._
5605 17.3 Before the Branch
5606 ======================
5608 The most important objective at this stage is to find and fix simple
5609 changes that become a pain to track once the branch is created. For
5610 instance, configuration problems that stop GDB from even building. If
5611 you can't get the problem fixed, document it in the `gdb/PROBLEMS' file.
5613 Prompt for `gdb/NEWS'
5614 ---------------------
5616 People always forget. Send a post reminding them but also if you know
5617 something interesting happened add it yourself. The `schedule' script
5618 will mention this in its e-mail.
5623 Grab one of the nightly snapshots and then walk through the
5624 `gdb/README' looking for anything that can be improved. The `schedule'
5625 script will mention this in its e-mail.
5627 Refresh any imported files.
5628 ---------------------------
5630 A number of files are taken from external repositories. They include:
5632 * `texinfo/texinfo.tex'
5634 * `config.guess' et. al. (see the top-level `MAINTAINERS' file)
5636 * `etc/standards.texi', `etc/make-stds.texi'
5641 A.R.I. is an `awk' script (Awk Regression Index ;-) that checks for a
5642 number of errors and coding conventions. The checks include things
5643 like using `malloc' instead of `xmalloc' and file naming problems.
5644 There shouldn't be any regressions.
5646 17.3.1 Review the bug data base
5647 -------------------------------
5649 Close anything obviously fixed.
5651 17.3.2 Check all cross targets build
5652 ------------------------------------
5654 The targets are listed in `gdb/MAINTAINERS'.
5664 $ V=`echo $v | sed 's/\./_/g'`
5665 $ D=`date -u +%Y-%m-%d`
5668 $ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
5669 -D $D-gmt gdb_$V-$D-branchpoint insight
5670 cvs -f -d :ext:sources.redhat.com:/cvs/src rtag
5671 -D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight
5674 $ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
5675 -b -r gdb_$V-$D-branchpoint gdb_$V-branch insight
5676 cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
5677 -b -r gdb_5_2-2002-03-03-branchpoint gdb_5_2-branch insight
5682 * By using `-D YYYY-MM-DD-gmt', the branch is forced to an exact
5685 * The trunk is first tagged so that the branch point can easily be
5688 * Insight, which includes GDB, is tagged at the same time.
5690 * `version.in' gets bumped to avoid version number conflicts.
5692 * The reading of `.cvsrc' is disabled using `-f'.
5699 $ V=`echo $v | sed 's/\./_/g'`
5703 $ echo cvs -f -d :ext:sources.redhat.com:/cvs/src co \
5704 -r gdb_$V-branch src/gdb/version.in
5705 cvs -f -d :ext:sources.redhat.com:/cvs/src co
5706 -r gdb_5_2-branch src/gdb/version.in
5708 U src/gdb/version.in
5710 $ echo $u.90-0000-00-00-cvs > version.in
5712 5.1.90-0000-00-00-cvs
5713 $ cvs -f commit version.in
5715 * `0000-00-00' is used as a date to pump prime the version.in update
5718 * `.90' and the previous branch version are used as fairly arbitrary
5719 initial branch version number.
5721 Update the web and news pages
5722 -----------------------------
5726 Tweak cron to track the new branch
5727 ----------------------------------
5729 The file `gdbadmin/cron/crontab' contains gdbadmin's cron table. This
5730 file needs to be updated so that:
5732 * A daily timestamp is added to the file `version.in'.
5734 * The new branch is included in the snapshot process.
5736 See the file `gdbadmin/cron/README' for how to install the updated cron
5739 The file `gdbadmin/ss/README' should also be reviewed to reflect any
5740 changes. That file is copied to both the branch/ and current/ snapshot
5743 Update the NEWS and README files
5744 --------------------------------
5746 The `NEWS' file needs to be updated so that on the branch it refers to
5747 _changes in the current release_ while on the trunk it also refers to
5748 _changes since the current release_.
5750 The `README' file needs to be updated so that it refers to the
5753 Post the branch info
5754 --------------------
5756 Send an announcement to the mailing lists:
5758 * GDB Announcement mailing list <gdb-announce@sources.redhat.com>
5760 * GDB Discsussion mailing list <gdb@sources.redhat.com> and GDB
5761 Discsussion mailing list <gdb-testers@sources.redhat.com>
5763 _Pragmatics: The branch creation is sent to the announce list to
5764 ensure that people people not subscribed to the higher volume discussion
5767 The announcement should include:
5771 * How to check out the branch using CVS.
5773 * The date/number of weeks until the release.
5775 * The branch commit policy still holds.
5777 17.5 Stabilize the branch
5778 =========================
5780 Something goes here.
5782 17.6 Create a Release
5783 =====================
5785 The process of creating and then making available a release is broken
5786 down into a number of stages. The first part addresses the technical
5787 process of creating a releasable tar ball. The later stages address the
5788 process of releasing that tar ball.
5790 When making a release candidate just the first section is needed.
5792 17.6.1 Create a release candidate
5793 ---------------------------------
5795 The objective at this stage is to create a set of tar balls that can be
5796 made available as a formal release (or as a less formal release
5802 Send out an e-mail notifying everyone that the branch is frozen to
5803 <gdb-patches@sources.redhat.com>.
5805 Establish a few defaults.
5806 .........................
5810 $ t=/sourceware/snapshot-tmp/gdbadmin-tmp
5812 /sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
5816 /sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
5818 /home/gdbadmin/bin/autoconf
5823 * Check the `autoconf' version carefully. You want to be using the
5824 version taken from the `binutils' snapshot directory, which can be
5825 found at `ftp://sources.redhat.com/pub/binutils/'. It is very
5826 unlikely that a system installed version of `autoconf' (e.g.,
5827 `/usr/bin/autoconf') is correct.
5829 Check out the relevant modules:
5830 ...............................
5832 $ for m in gdb insight
5834 ( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m )
5840 * The reading of `.cvsrc' is disabled (`-f') so that there isn't any
5841 confusion between what is written here and what your local `cvs'
5844 Update relevant files.
5845 ......................
5848 Major releases get their comments added as part of the mainline.
5849 Minor releases should probably mention any significant bugs that
5852 Don't forget to include the `ChangeLog' entry.
5854 $ emacs gdb/src/gdb/NEWS
5859 $ cp gdb/src/gdb/NEWS insight/src/gdb/NEWS
5860 $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
5863 You'll need to update:
5871 $ emacs gdb/src/gdb/README
5876 $ cp gdb/src/gdb/README insight/src/gdb/README
5877 $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
5879 _Maintainer note: Hopefully the `README' file was reviewed before
5880 the initial branch was cut so just a simple substitute is needed
5883 _Maintainer note: Other projects generate `README' and `INSTALL'
5884 from the core documentation. This might be worth pursuing._
5887 $ echo $v > gdb/src/gdb/version.in
5888 $ cat gdb/src/gdb/version.in
5890 $ emacs gdb/src/gdb/version.in
5893 ... Bump to version ...
5895 $ cp gdb/src/gdb/version.in insight/src/gdb/version.in
5896 $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
5902 This is identical to the process used to create the daily snapshot.
5904 $ for m in gdb insight
5906 ( cd $m/src && gmake -f src-release $m.tar )
5909 If the top level source directory does not have `src-release' (GDB
5910 version 5.3.1 or earlier), try these commands instead:
5912 $ for m in gdb insight
5914 ( cd $m/src && gmake -f Makefile.in $m.tar )
5917 Check the source files
5918 ......................
5920 You're looking for files that have mysteriously disappeared.
5921 `distclean' has the habit of deleting files it shouldn't. Watch out
5922 for the `version.in' update `cronjob'.
5924 $ ( cd gdb/src && cvs -f -q -n update )
5928 ... lots of generated files ...
5933 ... lots of generated files ...
5936 _Don't worry about the `gdb.info-??' or `gdb/p-exp.tab.c'. They were
5937 generated (and yes `gdb.info-1' was also generated only something
5938 strange with CVS means that they didn't get supressed). Fixing it
5939 would be nice though._
5941 Create compressed versions of the release
5942 .........................................
5947 gdb/ gdb-5.2.tar insight/ insight-5.2.tar
5948 $ for m in gdb insight
5950 bzip2 -v -9 -c $m-$v.tar > $m-$v.tar.bz2
5951 gzip -v -9 -c $m-$v.tar > $m-$v.tar.gz
5957 * A pipe such as `bunzip2 < xxx.bz2 | gzip -9 > xxx.gz' is not since,
5958 in that mode, `gzip' does not know the name of the file and, hence,
5959 can not include it in the compressed file. This is also why the
5960 release process runs `tar' and `bzip2' as separate passes.
5962 17.6.2 Sanity check the tar ball
5963 --------------------------------
5965 Pick a popular machine (Solaris/PPC?) and try the build on that.
5967 $ bunzip2 < gdb-5.2.tar.bz2 | tar xpf -
5972 $ ./gdb/gdb ./gdb/gdb
5976 Breakpoint 1 at 0x80732bc: file main.c, line 734.
5978 Starting program: /tmp/gdb-5.2/gdb/gdb
5980 Breakpoint 1, main (argc=1, argv=0xbffff8b4) at main.c:734
5981 734 catch_errors (captured_main, &args, "", RETURN_MASK_ALL);
5983 $1 = {argc = 136426532, argv = 0x821b7f0}
5986 17.6.3 Make a release candidate available
5987 -----------------------------------------
5989 If this is a release candidate then the only remaining steps are:
5991 1. Commit `version.in' and `ChangeLog'
5993 2. Tweak `version.in' (and `ChangeLog' to read L.M.N-0000-00-00-cvs
5994 so that the version update process can restart.
5996 3. Make the release candidate available in
5997 `ftp://sources.redhat.com/pub/gdb/snapshots/branch'
5999 4. Notify the relevant mailing lists ( <gdb@sources.redhat.com> and
6000 <gdb-testers@sources.redhat.com> that the candidate is available.
6002 17.6.4 Make a formal release available
6003 --------------------------------------
6005 (And you thought all that was required was to post an e-mail.)
6010 Copy the new files to both the release and the old release directory:
6012 $ cp *.bz2 *.gz ~ftp/pub/gdb/old-releases/
6013 $ cp *.bz2 *.gz ~ftp/pub/gdb/releases
6015 Clean up the releases directory so that only the most recent releases
6016 are available (e.g. keep 5.2 and 5.2.1 but remove 5.1):
6018 $ cd ~ftp/pub/gdb/releases
6021 Update the file `README' and `.message' in the releases directory:
6026 $ ln README .message
6028 Update the web pages.
6029 .....................
6031 `htdocs/download/ANNOUNCEMENT'
6032 This file, which is posted as the official announcement, includes:
6033 * General announcement.
6035 * News. If making an M.N.1 release, retain the news from
6036 earlier M.N release.
6041 `htdocs/news/index.html'
6042 `htdocs/download/index.html'
6043 These files include:
6044 * Announcement of the most recent release.
6046 * News entry (remember to update both the top level and the
6048 These pages also need to be regenerate using `index.sh'.
6050 `download/onlinedocs/'
6051 You need to find the magic command that is used to generate the
6052 online docs from the `.tar.bz2'. The best way is to look in the
6053 output from one of the nightly `cron' jobs and then just edit
6054 accordingly. Something like:
6056 $ ~/ss/update-web-docs \
6057 ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
6059 /www/sourceware/htdocs/gdb/download/onlinedocs \
6063 Just like the online documentation. Something like:
6065 $ /bin/sh ~/ss/update-web-ari \
6066 ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
6068 /www/sourceware/htdocs/gdb/download/ari \
6072 Shadow the pages onto gnu
6073 .........................
6075 Something goes here.
6077 Install the GDB tar ball on GNU
6078 ...............................
6080 At the time of writing, the GNU machine was `gnudist.gnu.org' in
6083 Make the `ANNOUNCEMENT'
6084 .......................
6086 Post the `ANNOUNCEMENT' file you created above to:
6088 * GDB Announcement mailing list <gdb-announce@sources.redhat.com>
6090 * General GNU Announcement list <info-gnu@gnu.org> (but delay it a
6091 day or so to let things get out)
6093 * GDB Bug Report mailing list <bug-gdb@gnu.org>
6098 The release is out but you're still not finished.
6100 Commit outstanding changes
6101 ..........................
6103 In particular you'll need to commit any changes to:
6118 $ d=`date -u +%Y-%m-%d`
6121 $ ( cd insight/src/gdb && cvs -f -q update )
6122 $ ( cd insight/src && cvs -f -q tag gdb_5_2-$d-release )
6124 Insight is used since that contains more of the release than GDB.
6126 Mention the release on the trunk
6127 ................................
6129 Just put something in the `ChangeLog' so that the trunk also indicates
6130 when the release was made.
6132 Restart `gdb/version.in'
6133 ........................
6135 If `gdb/version.in' does not contain an ISO date such as `2002-01-24'
6136 then the daily `cronjob' won't update it. Having committed all the
6137 release changes it can be set to `5.2.0_0000-00-00-cvs' which will
6138 restart things (yes the `_' is important - it affects the snapshot
6141 Don't forget the `ChangeLog'.
6146 The files committed to the branch may also need changes merged into the
6149 Revise the release schedule
6150 ...........................
6152 Post a revised release schedule to GDB Discussion List
6153 <gdb@sources.redhat.com> with an updated announcement. The schedule
6154 can be generated by running:
6156 $ ~/ss/schedule `date +%s` schedule
6158 The first parameter is approximate date/time in seconds (from the epoch)
6159 of the most recent release.
6161 Also update the schedule `cronjob'.
6166 Remove any `OBSOLETE' code.
6169 File: gdbint.info, Node: Testsuite, Next: Hints, Prev: Releasing GDB, Up: Top
6174 The testsuite is an important component of the GDB package. While it
6175 is always worthwhile to encourage user testing, in practice this is
6176 rarely sufficient; users typically use only a small subset of the
6177 available commands, and it has proven all too common for a change to
6178 cause a significant regression that went unnoticed for some time.
6180 The GDB testsuite uses the DejaGNU testing framework. The tests
6181 themselves are calls to various `Tcl' procs; the framework runs all the
6182 procs and summarizes the passes and fails.
6184 18.1 Using the Testsuite
6185 ========================
6187 To run the testsuite, simply go to the GDB object directory (or to the
6188 testsuite's objdir) and type `make check'. This just sets up some
6189 environment variables and invokes DejaGNU's `runtest' script. While
6190 the testsuite is running, you'll get mentions of which test file is in
6191 use, and a mention of any unexpected passes or fails. When the
6192 testsuite is finished, you'll get a summary that looks like this:
6196 # of expected passes 6016
6197 # of unexpected failures 58
6198 # of unexpected successes 5
6199 # of expected failures 183
6200 # of unresolved testcases 3
6201 # of untested testcases 5
6203 To run a specific test script, type:
6204 make check RUNTESTFLAGS='TESTS'
6205 where TESTS is a list of test script file names, separated by spaces.
6207 The ideal test run consists of expected passes only; however, reality
6208 conspires to keep us from this ideal. Unexpected failures indicate
6209 real problems, whether in GDB or in the testsuite. Expected failures
6210 are still failures, but ones which have been decided are too hard to
6211 deal with at the time; for instance, a test case might work everywhere
6212 except on AIX, and there is no prospect of the AIX case being fixed in
6213 the near future. Expected failures should not be added lightly, since
6214 you may be masking serious bugs in GDB. Unexpected successes are
6215 expected fails that are passing for some reason, while unresolved and
6216 untested cases often indicate some minor catastrophe, such as the
6217 compiler being unable to deal with a test program.
6219 When making any significant change to GDB, you should run the
6220 testsuite before and after the change, to confirm that there are no
6221 regressions. Note that truly complete testing would require that you
6222 run the testsuite with all supported configurations and a variety of
6223 compilers; however this is more than really necessary. In many cases
6224 testing with a single configuration is sufficient. Other useful
6225 options are to test one big-endian (Sparc) and one little-endian (x86)
6226 host, a cross config with a builtin simulator (powerpc-eabi, mips-elf),
6227 or a 64-bit host (Alpha).
6229 If you add new functionality to GDB, please consider adding tests
6230 for it as well; this way future GDB hackers can detect and fix their
6231 changes that break the functionality you added. Similarly, if you fix
6232 a bug that was not previously reported as a test failure, please add a
6233 test case for it. Some cases are extremely difficult to test, such as
6234 code that handles host OS failures or bugs in particular versions of
6235 compilers, and it's OK not to try to write tests for all of those.
6237 DejaGNU supports separate build, host, and target machines. However,
6238 some GDB test scripts do not work if the build machine and the host
6239 machine are not the same. In such an environment, these scripts will
6240 give a result of "UNRESOLVED", like this:
6242 UNRESOLVED: gdb.base/example.exp: This test script does not work on a remote host.
6244 18.2 Testsuite Organization
6245 ===========================
6247 The testsuite is entirely contained in `gdb/testsuite'. While the
6248 testsuite includes some makefiles and configury, these are very minimal,
6249 and used for little besides cleaning up, since the tests themselves
6250 handle the compilation of the programs that GDB will run. The file
6251 `testsuite/lib/gdb.exp' contains common utility procs useful for all
6252 GDB tests, while the directory `testsuite/config' contains
6253 configuration-specific files, typically used for special-purpose
6254 definitions of procs like `gdb_load' and `gdb_start'.
6256 The tests themselves are to be found in `testsuite/gdb.*' and
6257 subdirectories of those. The names of the test files must always end
6258 with `.exp'. DejaGNU collects the test files by wildcarding in the
6259 test directories, so both subdirectories and individual files get
6260 chosen and run in alphabetical order.
6262 The following table lists the main types of subdirectories and what
6263 they are for. Since DejaGNU finds test files no matter where they are
6264 located, and since each test file sets up its own compilation and
6265 execution environment, this organization is simply for convenience and
6269 This is the base testsuite. The tests in it should apply to all
6270 configurations of GDB (but generic native-only tests may live
6271 here). The test programs should be in the subset of C that is
6272 valid K&R, ANSI/ISO, and C++ (`#ifdef's are allowed if necessary,
6273 for instance for prototypes).
6276 Language-specific tests for any language LANG besides C. Examples
6277 are `gdb.cp' and `gdb.java'.
6280 Non-portable tests. The tests are specific to a specific
6281 configuration (host or target), such as HP-UX or eCos. Example is
6282 `gdb.hp', for HP-UX.
6285 Tests specific to a particular compiler. As of this writing (June
6286 1999), there aren't currently any groups of tests in this category
6287 that couldn't just as sensibly be made platform-specific, but one
6288 could imagine a `gdb.gcc', for tests of GDB's handling of GCC
6292 Tests that exercise a specific GDB subsystem in more depth. For
6293 instance, `gdb.disasm' exercises various disassemblers, while
6294 `gdb.stabs' tests pathways through the stabs symbol reader.
6299 In many areas, the GDB tests are already quite comprehensive; you
6300 should be able to copy existing tests to handle new cases.
6302 You should try to use `gdb_test' whenever possible, since it
6303 includes cases to handle all the unexpected errors that might happen.
6304 However, it doesn't cost anything to add new test procedures; for
6305 instance, `gdb.base/exprs.exp' defines a `test_expr' that calls
6306 `gdb_test' multiple times.
6308 Only use `send_gdb' and `gdb_expect' when absolutely necessary, such
6309 as when GDB has several valid responses to a command.
6311 The source language programs do _not_ need to be in a consistent
6312 style. Since GDB is used to debug programs written in many different
6313 styles, it's worth having a mix of styles in the testsuite; for
6314 instance, some GDB bugs involving the display of source lines would
6315 never manifest themselves if the programs used GNU coding style
6319 File: gdbint.info, Node: Hints, Next: GDB Observers, Prev: Testsuite, Up: Top
6324 Check the `README' file, it often has useful information that does not
6325 appear anywhere else in the directory.
6329 * Getting Started:: Getting started working on GDB
6330 * Debugging GDB:: Debugging GDB with itself
6333 File: gdbint.info, Node: Getting Started, Up: Hints
6335 19.1 Getting Started
6336 ====================
6338 GDB is a large and complicated program, and if you first starting to
6339 work on it, it can be hard to know where to start. Fortunately, if you
6340 know how to go about it, there are ways to figure out what is going on.
6342 This manual, the GDB Internals manual, has information which applies
6343 generally to many parts of GDB.
6345 Information about particular functions or data structures are
6346 located in comments with those functions or data structures. If you
6347 run across a function or a global variable which does not have a
6348 comment correctly explaining what is does, this can be thought of as a
6349 bug in GDB; feel free to submit a bug report, with a suggested comment
6350 if you can figure out what the comment should say. If you find a
6351 comment which is actually wrong, be especially sure to report that.
6353 Comments explaining the function of macros defined in host, target,
6354 or native dependent files can be in several places. Sometimes they are
6355 repeated every place the macro is defined. Sometimes they are where the
6356 macro is used. Sometimes there is a header file which supplies a
6357 default definition of the macro, and the comment is there. This manual
6358 also documents all the available macros.
6360 Start with the header files. Once you have some idea of how GDB's
6361 internal symbol tables are stored (see `symtab.h', `gdbtypes.h'), you
6362 will find it much easier to understand the code which uses and creates
6363 those symbol tables.
6365 You may wish to process the information you are getting somehow, to
6366 enhance your understanding of it. Summarize it, translate it to another
6367 language, add some (perhaps trivial or non-useful) feature to GDB, use
6368 the code to predict what a test case would do and write the test case
6369 and verify your prediction, etc. If you are reading code and your eyes
6370 are starting to glaze over, this is a sign you need to use a more active
6373 Once you have a part of GDB to start with, you can find more
6374 specifically the part you are looking for by stepping through each
6375 function with the `next' command. Do not use `step' or you will
6376 quickly get distracted; when the function you are stepping through
6377 calls another function try only to get a big-picture understanding
6378 (perhaps using the comment at the beginning of the function being
6379 called) of what it does. This way you can identify which of the
6380 functions being called by the function you are stepping through is the
6381 one which you are interested in. You may need to examine the data
6382 structures generated at each stage, with reference to the comments in
6383 the header files explaining what the data structures are supposed to
6386 Of course, this same technique can be used if you are just reading
6387 the code, rather than actually stepping through it. The same general
6388 principle applies--when the code you are looking at calls something
6389 else, just try to understand generally what the code being called does,
6390 rather than worrying about all its details.
6392 A good place to start when tracking down some particular area is with
6393 a command which invokes that feature. Suppose you want to know how
6394 single-stepping works. As a GDB user, you know that the `step' command
6395 invokes single-stepping. The command is invoked via command tables
6396 (see `command.h'); by convention the function which actually performs
6397 the command is formed by taking the name of the command and adding
6398 `_command', or in the case of an `info' subcommand, `_info'. For
6399 example, the `step' command invokes the `step_command' function and the
6400 `info display' command invokes `display_info'. When this convention is
6401 not followed, you might have to use `grep' or `M-x tags-search' in
6402 emacs, or run GDB on itself and set a breakpoint in `execute_command'.
6404 If all of the above fail, it may be appropriate to ask for
6405 information on `bug-gdb'. But _never_ post a generic question like "I
6406 was wondering if anyone could give me some tips about understanding
6407 GDB"--if we had some magic secret we would put it in this manual.
6408 Suggestions for improving the manual are always welcome, of course.
6411 File: gdbint.info, Node: Debugging GDB, Up: Hints
6413 19.2 Debugging GDB with itself
6414 ==============================
6416 If GDB is limping on your machine, this is the preferred way to get it
6417 fully functional. Be warned that in some ancient Unix systems, like
6418 Ultrix 4.2, a program can't be running in one process while it is being
6419 debugged in another. Rather than typing the command `./gdb ./gdb',
6420 which works on Suns and such, you can copy `gdb' to `gdb2' and then
6421 type `./gdb ./gdb2'.
6423 When you run GDB in the GDB source directory, it will read a
6424 `.gdbinit' file that sets up some simple things to make debugging gdb
6425 easier. The `info' command, when executed without a subcommand in a
6426 GDB being debugged by gdb, will pop you back up to the top level gdb.
6427 See `.gdbinit' for details.
6429 If you use emacs, you will probably want to do a `make TAGS' after
6430 you configure your distribution; this will put the machine dependent
6431 routines for your local machine where they will be accessed first by
6434 Also, make sure that you've either compiled GDB with your local cc,
6435 or have run `fixincludes' if you are compiling with gcc.
6437 19.3 Submitting Patches
6438 =======================
6440 Thanks for thinking of offering your changes back to the community of
6441 GDB users. In general we like to get well designed enhancements.
6442 Thanks also for checking in advance about the best way to transfer the
6445 The GDB maintainers will only install "cleanly designed" patches.
6446 This manual summarizes what we believe to be clean design for GDB.
6448 If the maintainers don't have time to put the patch in when it
6449 arrives, or if there is any question about a patch, it goes into a
6450 large queue with everyone else's patches and bug reports.
6452 The legal issue is that to incorporate substantial changes requires a
6453 copyright assignment from you and/or your employer, granting ownership
6454 of the changes to the Free Software Foundation. You can get the
6455 standard documents for doing this by sending mail to `gnu@gnu.org' and
6456 asking for it. We recommend that people write in "All programs owned
6457 by the Free Software Foundation" as "NAME OF PROGRAM", so that changes
6458 in many programs (not just GDB, but GAS, Emacs, GCC, etc) can be
6459 contributed with only one piece of legalese pushed through the
6460 bureaucracy and filed with the FSF. We can't start merging changes
6461 until this paperwork is received by the FSF (their rules, which we
6462 follow since we maintain it for them).
6464 Technically, the easiest way to receive changes is to receive each
6465 feature as a small context diff or unidiff, suitable for `patch'. Each
6466 message sent to me should include the changes to C code and header
6467 files for a single feature, plus `ChangeLog' entries for each directory
6468 where files were modified, and diffs for any changes needed to the
6469 manuals (`gdb/doc/gdb.texinfo' or `gdb/doc/gdbint.texinfo'). If there
6470 are a lot of changes for a single feature, they can be split down into
6473 In this way, if we read and like the feature, we can add it to the
6474 sources with a single patch command, do some testing, and check it in.
6475 If you leave out the `ChangeLog', we have to write one. If you leave
6476 out the doc, we have to puzzle out what needs documenting. Etc., etc.
6478 The reason to send each change in a separate message is that we will
6479 not install some of the changes. They'll be returned to you with
6480 questions or comments. If we're doing our job correctly, the message
6481 back to you will say what you have to fix in order to make the change
6482 acceptable. The reason to have separate messages for separate features
6483 is so that the acceptable changes can be installed while one or more
6484 changes are being reworked. If multiple features are sent in a single
6485 message, we tend to not put in the effort to sort out the acceptable
6486 changes from the unacceptable, so none of the features get installed
6487 until all are acceptable.
6489 If this sounds painful or authoritarian, well, it is. But we get a
6490 lot of bug reports and a lot of patches, and many of them don't get
6491 installed because we don't have the time to finish the job that the bug
6492 reporter or the contributor could have done. Patches that arrive
6493 complete, working, and well designed, tend to get installed on the day
6494 they arrive. The others go into a queue and get installed as time
6495 permits, which, since the maintainers have many demands to meet, may not
6496 be for quite some time.
6498 Please send patches directly to the GDB maintainers
6499 <gdb-patches@sources.redhat.com>.
6501 19.4 Obsolete Conditionals
6502 ==========================
6504 Fragments of old code in GDB sometimes reference or set the following
6505 configuration macros. They should not be used by new code, and old uses
6506 should be removed as those parts of the debugger are otherwise touched.
6509 This macro used to define where the end of the stack appeared, for
6510 use in interpreting core file formats that don't record this
6511 address in the core file itself. This information is now
6512 configured in BFD, and GDB gets the info portably from there. The
6513 values in GDB's configuration files should be moved into BFD
6514 configuration files (if needed there), and deleted from all of
6517 Any `FOO-xdep.c' file that references STACK_END_ADDR is so old
6518 that it has never been converted to use BFD. Now that's old!
6522 File: gdbint.info, Node: GDB Observers, Next: GNU Free Documentation License, Prev: Hints, Up: Top
6524 Appendix A GDB Currently available observers
6525 ********************************************
6527 A.1 Implementation rationale
6528 ============================
6530 An "observer" is an entity which is interested in being notified when
6531 GDB reaches certain states, or certain events occur in GDB. The entity
6532 being observed is called the "subject". To receive notifications, the
6533 observer attaches a callback to the subject. One subject can have
6536 `observer.c' implements an internal generic low-level event
6537 notification mechanism. This generic event notification mechanism is
6538 then re-used to implement the exported high-level notification
6539 management routines for all possible notifications.
6541 The current implementation of the generic observer provides support
6542 for contextual data. This contextual data is given to the subject when
6543 attaching the callback. In return, the subject will provide this
6544 contextual data back to the observer as a parameter of the callback.
6546 Note that the current support for the contextual data is only
6547 partial, as it lacks a mechanism that would deallocate this data when
6548 the callback is detached. This is not a problem so far, as this
6549 contextual data is only used internally to hold a function pointer.
6550 Later on, if a certain observer needs to provide support for user-level
6551 contextual data, then the generic notification mechanism will need to be
6552 enhanced to allow the observer to provide a routine to deallocate the
6553 data when attaching the callback.
6555 The observer implementation is also currently not reentrant. In
6556 particular, it is therefore not possible to call the attach or detach
6557 routines during a notification.
6562 Observer notifications can be traced using the command `set debug
6563 observer 1' (*note Optional messages about internal happenings:
6564 (gdb)Debugging Output.).
6566 A.3 `normal_stop' Notifications
6567 ===============================
6569 GDB notifies all `normal_stop' observers when the inferior execution
6570 has just stopped, the associated messages and annotations have been
6571 printed, and the control is about to be returned to the user.
6573 Note that the `normal_stop' notification is not emitted when the
6574 execution stops due to a breakpoint, and this breakpoint has a
6575 condition that is not met. If the breakpoint has any associated
6576 commands list, the commands are executed after the notification is
6579 The following interfaces are available to manage observers:
6581 -- Function: extern struct observer *observer_attach_EVENT
6582 (observer_EVENT_ftype *F)
6583 Using the function F, create an observer that is notified when
6584 ever EVENT occures, return the observer.
6586 -- Function: extern void observer_detach_EVENT (struct observer
6588 Remove OBSERVER from the list of observers to be notified when
6591 -- Function: extern void observer_notify_EVENT (void);
6592 Send a notification to all EVENT observers.
6594 The following observable events are defined:
6596 -- Function: void normal_stop (struct bpstats *BS)
6597 The inferior has stopped for real.
6599 -- Function: void target_changed (struct target_ops *TARGET)
6600 The target's register contents have changed.
6602 -- Function: void executable_changed (void *UNUSED_ARGS)
6603 The executable being debugged by GDB has changed: The user decided
6604 to debug a different program, or the program he was debugging has
6605 been modified since being loaded by the debugger (by being
6606 recompiled, for instance).
6608 -- Function: void inferior_created (struct target_ops *OBJFILE, int
6610 GDB has just connected to an inferior. For `run', GDB calls this
6611 observer while the inferior is still stopped at the entry-point
6612 instruction. For `attach' and `core', GDB calls this observer
6613 immediately after connecting to the inferior, and before any
6614 information on the inferior has been printed.
6616 -- Function: void solib_loaded (struct so_list *SOLIB)
6617 The shared library specified by SOLIB has been loaded. Note that
6618 when GDB calls this observer, the library's symbols probably
6619 haven't been loaded yet.
6621 -- Function: void solib_unloaded (struct so_list *SOLIB)
6622 The shared library specified by SOLIB has been unloaded.
6625 File: gdbint.info, Node: GNU Free Documentation License, Next: Index, Prev: GDB Observers, Up: Top
6627 Appendix B GNU Free Documentation License
6628 *****************************************
6630 Version 1.2, November 2002
6632 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
6633 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
6635 Everyone is permitted to copy and distribute verbatim copies
6636 of this license document, but changing it is not allowed.
6640 The purpose of this License is to make a manual, textbook, or other
6641 functional and useful document "free" in the sense of freedom: to
6642 assure everyone the effective freedom to copy and redistribute it,
6643 with or without modifying it, either commercially or
6644 noncommercially. Secondarily, this License preserves for the
6645 author and publisher a way to get credit for their work, while not
6646 being considered responsible for modifications made by others.
6648 This License is a kind of "copyleft", which means that derivative
6649 works of the document must themselves be free in the same sense.
6650 It complements the GNU General Public License, which is a copyleft
6651 license designed for free software.
6653 We have designed this License in order to use it for manuals for
6654 free software, because free software needs free documentation: a
6655 free program should come with manuals providing the same freedoms
6656 that the software does. But this License is not limited to
6657 software manuals; it can be used for any textual work, regardless
6658 of subject matter or whether it is published as a printed book.
6659 We recommend this License principally for works whose purpose is
6660 instruction or reference.
6662 1. APPLICABILITY AND DEFINITIONS
6664 This License applies to any manual or other work, in any medium,
6665 that contains a notice placed by the copyright holder saying it
6666 can be distributed under the terms of this License. Such a notice
6667 grants a world-wide, royalty-free license, unlimited in duration,
6668 to use that work under the conditions stated herein. The
6669 "Document", below, refers to any such manual or work. Any member
6670 of the public is a licensee, and is addressed as "you". You
6671 accept the license if you copy, modify or distribute the work in a
6672 way requiring permission under copyright law.
6674 A "Modified Version" of the Document means any work containing the
6675 Document or a portion of it, either copied verbatim, or with
6676 modifications and/or translated into another language.
6678 A "Secondary Section" is a named appendix or a front-matter section
6679 of the Document that deals exclusively with the relationship of the
6680 publishers or authors of the Document to the Document's overall
6681 subject (or to related matters) and contains nothing that could
6682 fall directly within that overall subject. (Thus, if the Document
6683 is in part a textbook of mathematics, a Secondary Section may not
6684 explain any mathematics.) The relationship could be a matter of
6685 historical connection with the subject or with related matters, or
6686 of legal, commercial, philosophical, ethical or political position
6689 The "Invariant Sections" are certain Secondary Sections whose
6690 titles are designated, as being those of Invariant Sections, in
6691 the notice that says that the Document is released under this
6692 License. If a section does not fit the above definition of
6693 Secondary then it is not allowed to be designated as Invariant.
6694 The Document may contain zero Invariant Sections. If the Document
6695 does not identify any Invariant Sections then there are none.
6697 The "Cover Texts" are certain short passages of text that are
6698 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
6699 that says that the Document is released under this License. A
6700 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
6701 be at most 25 words.
6703 A "Transparent" copy of the Document means a machine-readable copy,
6704 represented in a format whose specification is available to the
6705 general public, that is suitable for revising the document
6706 straightforwardly with generic text editors or (for images
6707 composed of pixels) generic paint programs or (for drawings) some
6708 widely available drawing editor, and that is suitable for input to
6709 text formatters or for automatic translation to a variety of
6710 formats suitable for input to text formatters. A copy made in an
6711 otherwise Transparent file format whose markup, or absence of
6712 markup, has been arranged to thwart or discourage subsequent
6713 modification by readers is not Transparent. An image format is
6714 not Transparent if used for any substantial amount of text. A
6715 copy that is not "Transparent" is called "Opaque".
6717 Examples of suitable formats for Transparent copies include plain
6718 ASCII without markup, Texinfo input format, LaTeX input format,
6719 SGML or XML using a publicly available DTD, and
6720 standard-conforming simple HTML, PostScript or PDF designed for
6721 human modification. Examples of transparent image formats include
6722 PNG, XCF and JPG. Opaque formats include proprietary formats that
6723 can be read and edited only by proprietary word processors, SGML or
6724 XML for which the DTD and/or processing tools are not generally
6725 available, and the machine-generated HTML, PostScript or PDF
6726 produced by some word processors for output purposes only.
6728 The "Title Page" means, for a printed book, the title page itself,
6729 plus such following pages as are needed to hold, legibly, the
6730 material this License requires to appear in the title page. For
6731 works in formats which do not have any title page as such, "Title
6732 Page" means the text near the most prominent appearance of the
6733 work's title, preceding the beginning of the body of the text.
6735 A section "Entitled XYZ" means a named subunit of the Document
6736 whose title either is precisely XYZ or contains XYZ in parentheses
6737 following text that translates XYZ in another language. (Here XYZ
6738 stands for a specific section name mentioned below, such as
6739 "Acknowledgements", "Dedications", "Endorsements", or "History".)
6740 To "Preserve the Title" of such a section when you modify the
6741 Document means that it remains a section "Entitled XYZ" according
6744 The Document may include Warranty Disclaimers next to the notice
6745 which states that this License applies to the Document. These
6746 Warranty Disclaimers are considered to be included by reference in
6747 this License, but only as regards disclaiming warranties: any other
6748 implication that these Warranty Disclaimers may have is void and
6749 has no effect on the meaning of this License.
6753 You may copy and distribute the Document in any medium, either
6754 commercially or noncommercially, provided that this License, the
6755 copyright notices, and the license notice saying this License
6756 applies to the Document are reproduced in all copies, and that you
6757 add no other conditions whatsoever to those of this License. You
6758 may not use technical measures to obstruct or control the reading
6759 or further copying of the copies you make or distribute. However,
6760 you may accept compensation in exchange for copies. If you
6761 distribute a large enough number of copies you must also follow
6762 the conditions in section 3.
6764 You may also lend copies, under the same conditions stated above,
6765 and you may publicly display copies.
6767 3. COPYING IN QUANTITY
6769 If you publish printed copies (or copies in media that commonly
6770 have printed covers) of the Document, numbering more than 100, and
6771 the Document's license notice requires Cover Texts, you must
6772 enclose the copies in covers that carry, clearly and legibly, all
6773 these Cover Texts: Front-Cover Texts on the front cover, and
6774 Back-Cover Texts on the back cover. Both covers must also clearly
6775 and legibly identify you as the publisher of these copies. The
6776 front cover must present the full title with all words of the
6777 title equally prominent and visible. You may add other material
6778 on the covers in addition. Copying with changes limited to the
6779 covers, as long as they preserve the title of the Document and
6780 satisfy these conditions, can be treated as verbatim copying in
6783 If the required texts for either cover are too voluminous to fit
6784 legibly, you should put the first ones listed (as many as fit
6785 reasonably) on the actual cover, and continue the rest onto
6788 If you publish or distribute Opaque copies of the Document
6789 numbering more than 100, you must either include a
6790 machine-readable Transparent copy along with each Opaque copy, or
6791 state in or with each Opaque copy a computer-network location from
6792 which the general network-using public has access to download
6793 using public-standard network protocols a complete Transparent
6794 copy of the Document, free of added material. If you use the
6795 latter option, you must take reasonably prudent steps, when you
6796 begin distribution of Opaque copies in quantity, to ensure that
6797 this Transparent copy will remain thus accessible at the stated
6798 location until at least one year after the last time you
6799 distribute an Opaque copy (directly or through your agents or
6800 retailers) of that edition to the public.
6802 It is requested, but not required, that you contact the authors of
6803 the Document well before redistributing any large number of
6804 copies, to give them a chance to provide you with an updated
6805 version of the Document.
6809 You may copy and distribute a Modified Version of the Document
6810 under the conditions of sections 2 and 3 above, provided that you
6811 release the Modified Version under precisely this License, with
6812 the Modified Version filling the role of the Document, thus
6813 licensing distribution and modification of the Modified Version to
6814 whoever possesses a copy of it. In addition, you must do these
6815 things in the Modified Version:
6817 A. Use in the Title Page (and on the covers, if any) a title
6818 distinct from that of the Document, and from those of
6819 previous versions (which should, if there were any, be listed
6820 in the History section of the Document). You may use the
6821 same title as a previous version if the original publisher of
6822 that version gives permission.
6824 B. List on the Title Page, as authors, one or more persons or
6825 entities responsible for authorship of the modifications in
6826 the Modified Version, together with at least five of the
6827 principal authors of the Document (all of its principal
6828 authors, if it has fewer than five), unless they release you
6829 from this requirement.
6831 C. State on the Title page the name of the publisher of the
6832 Modified Version, as the publisher.
6834 D. Preserve all the copyright notices of the Document.
6836 E. Add an appropriate copyright notice for your modifications
6837 adjacent to the other copyright notices.
6839 F. Include, immediately after the copyright notices, a license
6840 notice giving the public permission to use the Modified
6841 Version under the terms of this License, in the form shown in
6844 G. Preserve in that license notice the full lists of Invariant
6845 Sections and required Cover Texts given in the Document's
6848 H. Include an unaltered copy of this License.
6850 I. Preserve the section Entitled "History", Preserve its Title,
6851 and add to it an item stating at least the title, year, new
6852 authors, and publisher of the Modified Version as given on
6853 the Title Page. If there is no section Entitled "History" in
6854 the Document, create one stating the title, year, authors,
6855 and publisher of the Document as given on its Title Page,
6856 then add an item describing the Modified Version as stated in
6857 the previous sentence.
6859 J. Preserve the network location, if any, given in the Document
6860 for public access to a Transparent copy of the Document, and
6861 likewise the network locations given in the Document for
6862 previous versions it was based on. These may be placed in
6863 the "History" section. You may omit a network location for a
6864 work that was published at least four years before the
6865 Document itself, or if the original publisher of the version
6866 it refers to gives permission.
6868 K. For any section Entitled "Acknowledgements" or "Dedications",
6869 Preserve the Title of the section, and preserve in the
6870 section all the substance and tone of each of the contributor
6871 acknowledgements and/or dedications given therein.
6873 L. Preserve all the Invariant Sections of the Document,
6874 unaltered in their text and in their titles. Section numbers
6875 or the equivalent are not considered part of the section
6878 M. Delete any section Entitled "Endorsements". Such a section
6879 may not be included in the Modified Version.
6881 N. Do not retitle any existing section to be Entitled
6882 "Endorsements" or to conflict in title with any Invariant
6885 O. Preserve any Warranty Disclaimers.
6887 If the Modified Version includes new front-matter sections or
6888 appendices that qualify as Secondary Sections and contain no
6889 material copied from the Document, you may at your option
6890 designate some or all of these sections as invariant. To do this,
6891 add their titles to the list of Invariant Sections in the Modified
6892 Version's license notice. These titles must be distinct from any
6893 other section titles.
6895 You may add a section Entitled "Endorsements", provided it contains
6896 nothing but endorsements of your Modified Version by various
6897 parties--for example, statements of peer review or that the text
6898 has been approved by an organization as the authoritative
6899 definition of a standard.
6901 You may add a passage of up to five words as a Front-Cover Text,
6902 and a passage of up to 25 words as a Back-Cover Text, to the end
6903 of the list of Cover Texts in the Modified Version. Only one
6904 passage of Front-Cover Text and one of Back-Cover Text may be
6905 added by (or through arrangements made by) any one entity. If the
6906 Document already includes a cover text for the same cover,
6907 previously added by you or by arrangement made by the same entity
6908 you are acting on behalf of, you may not add another; but you may
6909 replace the old one, on explicit permission from the previous
6910 publisher that added the old one.
6912 The author(s) and publisher(s) of the Document do not by this
6913 License give permission to use their names for publicity for or to
6914 assert or imply endorsement of any Modified Version.
6916 5. COMBINING DOCUMENTS
6918 You may combine the Document with other documents released under
6919 this License, under the terms defined in section 4 above for
6920 modified versions, provided that you include in the combination
6921 all of the Invariant Sections of all of the original documents,
6922 unmodified, and list them all as Invariant Sections of your
6923 combined work in its license notice, and that you preserve all
6924 their Warranty Disclaimers.
6926 The combined work need only contain one copy of this License, and
6927 multiple identical Invariant Sections may be replaced with a single
6928 copy. If there are multiple Invariant Sections with the same name
6929 but different contents, make the title of each such section unique
6930 by adding at the end of it, in parentheses, the name of the
6931 original author or publisher of that section if known, or else a
6932 unique number. Make the same adjustment to the section titles in
6933 the list of Invariant Sections in the license notice of the
6936 In the combination, you must combine any sections Entitled
6937 "History" in the various original documents, forming one section
6938 Entitled "History"; likewise combine any sections Entitled
6939 "Acknowledgements", and any sections Entitled "Dedications". You
6940 must delete all sections Entitled "Endorsements."
6942 6. COLLECTIONS OF DOCUMENTS
6944 You may make a collection consisting of the Document and other
6945 documents released under this License, and replace the individual
6946 copies of this License in the various documents with a single copy
6947 that is included in the collection, provided that you follow the
6948 rules of this License for verbatim copying of each of the
6949 documents in all other respects.
6951 You may extract a single document from such a collection, and
6952 distribute it individually under this License, provided you insert
6953 a copy of this License into the extracted document, and follow
6954 this License in all other respects regarding verbatim copying of
6957 7. AGGREGATION WITH INDEPENDENT WORKS
6959 A compilation of the Document or its derivatives with other
6960 separate and independent documents or works, in or on a volume of
6961 a storage or distribution medium, is called an "aggregate" if the
6962 copyright resulting from the compilation is not used to limit the
6963 legal rights of the compilation's users beyond what the individual
6964 works permit. When the Document is included in an aggregate, this
6965 License does not apply to the other works in the aggregate which
6966 are not themselves derivative works of the Document.
6968 If the Cover Text requirement of section 3 is applicable to these
6969 copies of the Document, then if the Document is less than one half
6970 of the entire aggregate, the Document's Cover Texts may be placed
6971 on covers that bracket the Document within the aggregate, or the
6972 electronic equivalent of covers if the Document is in electronic
6973 form. Otherwise they must appear on printed covers that bracket
6974 the whole aggregate.
6978 Translation is considered a kind of modification, so you may
6979 distribute translations of the Document under the terms of section
6980 4. Replacing Invariant Sections with translations requires special
6981 permission from their copyright holders, but you may include
6982 translations of some or all Invariant Sections in addition to the
6983 original versions of these Invariant Sections. You may include a
6984 translation of this License, and all the license notices in the
6985 Document, and any Warranty Disclaimers, provided that you also
6986 include the original English version of this License and the
6987 original versions of those notices and disclaimers. In case of a
6988 disagreement between the translation and the original version of
6989 this License or a notice or disclaimer, the original version will
6992 If a section in the Document is Entitled "Acknowledgements",
6993 "Dedications", or "History", the requirement (section 4) to
6994 Preserve its Title (section 1) will typically require changing the
6999 You may not copy, modify, sublicense, or distribute the Document
7000 except as expressly provided for under this License. Any other
7001 attempt to copy, modify, sublicense or distribute the Document is
7002 void, and will automatically terminate your rights under this
7003 License. However, parties who have received copies, or rights,
7004 from you under this License will not have their licenses
7005 terminated so long as such parties remain in full compliance.
7007 10. FUTURE REVISIONS OF THIS LICENSE
7009 The Free Software Foundation may publish new, revised versions of
7010 the GNU Free Documentation License from time to time. Such new
7011 versions will be similar in spirit to the present version, but may
7012 differ in detail to address new problems or concerns. See
7013 `http://www.gnu.org/copyleft/'.
7015 Each version of the License is given a distinguishing version
7016 number. If the Document specifies that a particular numbered
7017 version of this License "or any later version" applies to it, you
7018 have the option of following the terms and conditions either of
7019 that specified version or of any later version that has been
7020 published (not as a draft) by the Free Software Foundation. If
7021 the Document does not specify a version number of this License,
7022 you may choose any version ever published (not as a draft) by the
7023 Free Software Foundation.
7025 B.1 ADDENDUM: How to use this License for your documents
7026 ========================================================
7028 To use this License in a document you have written, include a copy of
7029 the License in the document and put the following copyright and license
7030 notices just after the title page:
7032 Copyright (C) YEAR YOUR NAME.
7033 Permission is granted to copy, distribute and/or modify this document
7034 under the terms of the GNU Free Documentation License, Version 1.2
7035 or any later version published by the Free Software Foundation;
7036 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
7037 Texts. A copy of the license is included in the section entitled ``GNU
7038 Free Documentation License''.
7040 If you have Invariant Sections, Front-Cover Texts and Back-Cover
7041 Texts, replace the "with...Texts." line with this:
7043 with the Invariant Sections being LIST THEIR TITLES, with
7044 the Front-Cover Texts being LIST, and with the Back-Cover Texts
7047 If you have Invariant Sections without Cover Texts, or some other
7048 combination of the three, merge those two alternatives to suit the
7051 If your document contains nontrivial examples of program code, we
7052 recommend releasing these examples in parallel under your choice of
7053 free software license, such as the GNU General Public License, to
7054 permit their use in free software.
7057 File: gdbint.info, Node: Index, Prev: GNU Free Documentation License, Up: Top
7065 * *ADDRESS_CLASS_TYPE_FLAGS_TO_NAME: Target Architecture Definition.
7067 * *gdbarch_data: Coding. (line 132)
7068 * _initialize_language: Language Support. (line 79)
7069 * a.out format: Symbol Handling. (line 199)
7070 * abstract interpretation of function prologues: Algorithms. (line 72)
7071 * add_cmd: User Interface. (line 21)
7072 * add_com: User Interface. (line 21)
7073 * add_setshow_cmd: User Interface. (line 26)
7074 * add_setshow_cmd_full: User Interface. (line 26)
7075 * add_symtab_fns: Symbol Handling. (line 23)
7076 * adding a new host: Host Definition. (line 13)
7077 * adding a symbol-reading module: Symbol Handling. (line 23)
7078 * adding a target: Target Architecture Definition.
7080 * adding debugging info reader: Symbol Handling. (line 333)
7081 * adding source language: Language Support. (line 17)
7082 * ADDR_BITS_REMOVE: Target Architecture Definition.
7084 * address classes: Target Architecture Definition.
7086 * address representation: Target Architecture Definition.
7088 * address spaces, separate data and code: Target Architecture Definition.
7090 * ADDRESS_CLASS_NAME_TO_TYPE_FLAGS: Target Architecture Definition.
7092 * ADDRESS_CLASS_NAME_to_TYPE_FLAGS: Target Architecture Definition.
7094 * ADDRESS_CLASS_NAME_TO_TYPE_FLAGS_P: Target Architecture Definition.
7096 * ADDRESS_CLASS_TYPE_FLAGS: Target Architecture Definition.
7098 * ADDRESS_CLASS_TYPE_FLAGS (BYTE_SIZE, DWARF2_ADDR_CLASS): Target Architecture Definition.
7100 * ADDRESS_CLASS_TYPE_FLAGS_P: Target Architecture Definition.
7102 * ADDRESS_CLASS_TYPE_FLAGS_TO_NAME: Target Architecture Definition.
7104 * ADDRESS_CLASS_TYPE_FLAGS_TO_NAME_P: Target Architecture Definition.
7106 * ADDRESS_TO_POINTER: Target Architecture Definition.
7108 * ADJUST_BREAKPOINT_ADDRESS: Target Architecture Definition.
7110 * algorithms: Algorithms. (line 6)
7111 * ALIGN_STACK_ON_STARTUP: Host Definition. (line 93)
7112 * allocate_symtab: Language Support. (line 83)
7113 * Array Containers: Support Libraries. (line 130)
7114 * assumptions about targets: Coding. (line 540)
7115 * ATTR_NORETURN: Host Definition. (line 178)
7116 * BELIEVE_PCC_PROMOTION: Target Architecture Definition.
7118 * BFD library: Support Libraries. (line 9)
7119 * BIG_BREAKPOINT: Target Architecture Definition.
7121 * BITS_BIG_ENDIAN: Target Architecture Definition.
7123 * BPT_VECTOR: Target Architecture Definition.
7125 * BREAKPOINT <1>: Target Architecture Definition.
7127 * BREAKPOINT: Algorithms. (line 232)
7128 * breakpoint address adjusted: Target Architecture Definition.
7130 * BREAKPOINT_FROM_PC: Target Architecture Definition.
7132 * breakpoints: Algorithms. (line 175)
7133 * bug-gdb mailing list: Getting Started. (line 72)
7134 * C data types: Coding. (line 415)
7135 * call frame information: Algorithms. (line 38)
7136 * call stack frame: Algorithms. (line 14)
7137 * CALL_DUMMY_LOCATION: Target Architecture Definition.
7139 * CANNOT_FETCH_REGISTER: Target Architecture Definition.
7141 * CANNOT_STEP_HW_WATCHPOINTS: Algorithms. (line 404)
7142 * CANNOT_STORE_REGISTER: Target Architecture Definition.
7144 * CC_HAS_LONG_LONG: Host Definition. (line 138)
7145 * CFI (call frame information): Algorithms. (line 38)
7146 * char: Target Architecture Definition.
7148 * checkpoints: Algorithms. (line 580)
7149 * CHILD_PREPARE_TO_STORE: Native Debugging. (line 134)
7150 * cleanup: User Interface. (line 223)
7151 * cleanups: Coding. (line 12)
7152 * CLEAR_SOLIB: Native Debugging. (line 243)
7153 * CLI: User Interface. (line 12)
7154 * code pointers, word-addressed: Target Architecture Definition.
7156 * coding standards: Coding. (line 214)
7157 * COFF debugging info: Symbol Handling. (line 300)
7158 * COFF format: Symbol Handling. (line 214)
7159 * command implementation: Getting Started. (line 60)
7160 * command interpreter: User Interface. (line 12)
7161 * comment formatting: Coding. (line 389)
7162 * compiler warnings: Coding. (line 270)
7163 * CONVERT_REGISTER_P: Target Architecture Definition.
7165 * converting between pointers and addresses: Target Architecture Definition.
7167 * converting integers to addresses: Target Architecture Definition.
7169 * converting targets to multi-arch: Target Architecture Definition.
7171 * CRLF_SOURCE_FILES: Host Definition. (line 99)
7172 * current_language: Language Support. (line 75)
7173 * D10V addresses: Target Architecture Definition.
7175 * data output: User Interface. (line 254)
7176 * data-pointer, per-architecture/per-module: Coding. (line 100)
7177 * DEBUG_PTRACE: Native Debugging. (line 246)
7178 * debugging GDB: Debugging GDB. (line 6)
7179 * DECR_PC_AFTER_BREAK: Target Architecture Definition.
7181 * DEFAULT_PROMPT: Host Definition. (line 106)
7182 * deprecate_cmd: User Interface. (line 32)
7183 * DEPRECATED_BIG_REMOTE_BREAKPOINT: Target Architecture Definition.
7185 * DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS: Target Architecture Definition.
7187 * DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS_P: Target Architecture Definition.
7189 * DEPRECATED_FP_REGNUM: Target Architecture Definition.
7191 * DEPRECATED_FRAME_CHAIN: Target Architecture Definition.
7193 * DEPRECATED_FRAME_CHAIN_VALID: Target Architecture Definition.
7195 * DEPRECATED_FRAME_INIT_SAVED_REGS: Target Architecture Definition.
7197 * DEPRECATED_FRAME_SAVED_PC: Target Architecture Definition.
7199 * DEPRECATED_FRAMELESS_FUNCTION_INVOCATION: Target Architecture Definition.
7201 * DEPRECATED_FUNCTION_START_OFFSET: Target Architecture Definition.
7203 * DEPRECATED_GET_SAVED_REGISTER: Target Architecture Definition.
7205 * DEPRECATED_IBM6000_TARGET: Target Architecture Definition.
7207 * DEPRECATED_INIT_EXTRA_FRAME_INFO: Target Architecture Definition.
7209 * DEPRECATED_INIT_FRAME_PC: Target Architecture Definition.
7211 * DEPRECATED_LITTLE_REMOTE_BREAKPOINT: Target Architecture Definition.
7213 * DEPRECATED_POP_FRAME: Target Architecture Definition.
7215 * DEPRECATED_PUSH_ARGUMENTS.: Target Architecture Definition.
7217 * DEPRECATED_REG_STRUCT_HAS_ADDR: Target Architecture Definition.
7219 * DEPRECATED_REGISTER_RAW_SIZE: Target Architecture Definition.
7221 * DEPRECATED_REGISTER_VIRTUAL_SIZE: Target Architecture Definition.
7223 * DEPRECATED_REMOTE_BREAKPOINT: Target Architecture Definition.
7225 * DEPRECATED_SIGTRAMP_END: Target Architecture Definition.
7227 * DEPRECATED_SIGTRAMP_START: Target Architecture Definition.
7229 * DEPRECATED_STACK_ALIGN: Target Architecture Definition.
7231 * DEPRECATED_USE_STRUCT_CONVENTION: Target Architecture Definition.
7233 * deprecating commands: User Interface. (line 32)
7234 * design: Coding. (line 535)
7235 * DEV_TTY: Host Definition. (line 109)
7236 * DIRNAME_SEPARATOR: Coding. (line 605)
7237 * DISABLE_UNSETTABLE_BREAK: Target Architecture Definition.
7239 * discard_cleanups: Coding. (line 39)
7240 * do_cleanups: Coding. (line 35)
7241 * DOS text files: Host Definition. (line 100)
7242 * DW_AT_address_class: Target Architecture Definition.
7244 * DW_AT_byte_size: Target Architecture Definition.
7246 * DWARF 1 debugging info: Symbol Handling. (line 313)
7247 * DWARF 2 debugging info: Symbol Handling. (line 321)
7248 * DWARF2_REG_TO_REGNUM: Target Architecture Definition.
7250 * DWARF_REG_TO_REGNUM: Target Architecture Definition.
7252 * ECOFF debugging info: Symbol Handling. (line 306)
7253 * ECOFF format: Symbol Handling. (line 228)
7254 * ECOFF_REG_TO_REGNUM: Target Architecture Definition.
7256 * ELF format: Symbol Handling. (line 261)
7257 * END_OF_TEXT_DEFAULT: Target Architecture Definition.
7259 * evaluate_subexp: Language Support. (line 58)
7260 * executable_changed: GDB Observers. (line 82)
7261 * execution state: Managing Execution State.
7263 * experimental branches: Versions and Branches.
7265 * expression evaluation routines: Language Support. (line 58)
7266 * expression parser: Language Support. (line 21)
7267 * EXTRACT_RETURN_VALUE: Target Architecture Definition.
7269 * extract_typed_address: Target Architecture Definition.
7271 * FDL, GNU Free Documentation License: GNU Free Documentation License.
7273 * fetch_core_registers: Native Debugging. (line 63)
7274 * FETCH_INFERIOR_REGISTERS: Native Debugging. (line 142)
7275 * field output functions: User Interface. (line 254)
7276 * file names, portability: Coding. (line 573)
7277 * FILENAME_CMP: Coding. (line 599)
7278 * find_pc_function: Symbol Handling. (line 122)
7279 * find_pc_line: Symbol Handling. (line 122)
7280 * find_sym_fns: Symbol Handling. (line 18)
7281 * finding a symbol: Symbol Handling. (line 119)
7282 * fine-tuning gdbarch structure: Target Architecture Definition.
7284 * FOPEN_RB: Host Definition. (line 112)
7285 * FP0_REGNUM: Native Debugging. (line 149)
7286 * frame: Algorithms. (line 14)
7287 * frame, unwind: Algorithms. (line 17)
7288 * frame_align: Target Architecture Definition.
7290 * FRAME_NUM_ARGS: Target Architecture Definition.
7292 * frame_pop: Target Architecture Definition.
7294 * frame_register_unwind: Algorithms. (line 23)
7295 * full symbol table: Symbol Handling. (line 90)
7296 * function prototypes: Coding. (line 437)
7297 * function usage: Coding. (line 419)
7298 * FUNCTION_EPILOGUE_SIZE: Target Architecture Definition.
7300 * fundamental types: Symbol Handling. (line 164)
7301 * GCC2_COMPILED_FLAG_SYMBOL: Target Architecture Definition.
7303 * GCC_COMPILED_FLAG_SYMBOL: Target Architecture Definition.
7305 * GDB source tree structure: Overall Structure. (line 82)
7306 * GDB_MULTI_ARCH: Target Architecture Definition.
7308 * gdb_osabi: Target Architecture Definition.
7310 * GDB_OSABI_ARM_APCS: Target Architecture Definition.
7312 * GDB_OSABI_ARM_EABI_V1: Target Architecture Definition.
7314 * GDB_OSABI_ARM_EABI_V2: Target Architecture Definition.
7316 * GDB_OSABI_FREEBSD_AOUT: Target Architecture Definition.
7318 * GDB_OSABI_FREEBSD_ELF: Target Architecture Definition.
7320 * GDB_OSABI_GO32: Target Architecture Definition.
7322 * GDB_OSABI_HURD: Target Architecture Definition.
7324 * GDB_OSABI_LINUX: Target Architecture Definition.
7326 * GDB_OSABI_NETBSD_AOUT: Target Architecture Definition.
7328 * GDB_OSABI_NETBSD_ELF: Target Architecture Definition.
7330 * GDB_OSABI_NETWARE: Target Architecture Definition.
7332 * GDB_OSABI_OSF1: Target Architecture Definition.
7334 * GDB_OSABI_SOLARIS: Target Architecture Definition.
7336 * GDB_OSABI_SVR4: Target Architecture Definition.
7338 * GDB_OSABI_UNKNOWN: Target Architecture Definition.
7340 * GDB_OSABI_WINCE: Target Architecture Definition.
7342 * GDB_TARGET_IS_HPPA: Target Architecture Definition.
7344 * gdbarch_data: Coding. (line 108)
7345 * gdbarch_in_function_epilogue_p: Target Architecture Definition.
7347 * gdbarch_init_osabi: Target Architecture Definition.
7349 * gdbarch_register_osabi: Target Architecture Definition.
7351 * gdbarch_register_osabi_sniffer: Target Architecture Definition.
7353 * gdbarch_return_value: Target Architecture Definition.
7355 * GDBINIT_FILENAME: Host Definition. (line 78)
7356 * generic host support: Host Definition. (line 46)
7357 * get_frame_register: Algorithms. (line 23)
7358 * get_frame_type: Algorithms. (line 30)
7359 * GET_LONGJMP_TARGET <1>: Native Debugging. (line 156)
7360 * GET_LONGJMP_TARGET <2>: Target Architecture Definition.
7362 * GET_LONGJMP_TARGET: Algorithms. (line 290)
7363 * hardware breakpoints: Algorithms. (line 182)
7364 * hardware watchpoints: Algorithms. (line 306)
7365 * HAVE_CONTINUABLE_WATCHPOINT: Algorithms. (line 400)
7366 * HAVE_DOS_BASED_FILE_SYSTEM: Coding. (line 582)
7367 * HAVE_LONG_DOUBLE: Host Definition. (line 147)
7368 * HAVE_MMAP: Host Definition. (line 115)
7369 * HAVE_NONSTEPPABLE_WATCHPOINT: Algorithms. (line 396)
7370 * HAVE_STEPPABLE_WATCHPOINT: Algorithms. (line 392)
7371 * HAVE_TERMIO: Host Definition. (line 120)
7372 * host: Overall Structure. (line 50)
7373 * host, adding: Host Definition. (line 13)
7374 * i386_cleanup_dregs: Algorithms. (line 556)
7375 * I386_DR_LOW_GET_STATUS: Algorithms. (line 463)
7376 * I386_DR_LOW_RESET_ADDR: Algorithms. (line 459)
7377 * I386_DR_LOW_SET_ADDR: Algorithms. (line 456)
7378 * I386_DR_LOW_SET_CONTROL: Algorithms. (line 453)
7379 * i386_insert_hw_breakpoint: Algorithms. (line 538)
7380 * i386_insert_watchpoint: Algorithms. (line 510)
7381 * i386_region_ok_for_watchpoint: Algorithms. (line 488)
7382 * i386_remove_hw_breakpoint: Algorithms. (line 538)
7383 * i386_remove_watchpoint: Algorithms. (line 510)
7384 * i386_stopped_by_hwbp: Algorithms. (line 550)
7385 * i386_stopped_by_watchpoint: Algorithms. (line 502)
7386 * i386_stopped_data_address: Algorithms. (line 495)
7387 * I386_USE_GENERIC_WATCHPOINTS: Algorithms. (line 434)
7388 * IN_SOLIB_CALL_TRAMPOLINE: Target Architecture Definition.
7390 * IN_SOLIB_DYNSYM_RESOLVE_CODE: Target Architecture Definition.
7392 * IN_SOLIB_RETURN_TRAMPOLINE: Target Architecture Definition.
7394 * inferior_created: GDB Observers. (line 89)
7395 * INNER_THAN: Target Architecture Definition.
7397 * insert or remove hardware breakpoint: Algorithms. (line 261)
7398 * insert or remove hardware watchpoint: Algorithms. (line 366)
7399 * insert or remove software breakpoint: Algorithms. (line 238)
7400 * INT_MAX: Host Definition. (line 123)
7401 * INT_MIN: Host Definition. (line 124)
7402 * INTEGER_TO_ADDRESS: Target Architecture Definition.
7404 * IS_ABSOLUTE_PATH: Coding. (line 593)
7405 * IS_DIR_SEPARATOR: Coding. (line 588)
7406 * ISATTY: Host Definition. (line 130)
7407 * item output functions: User Interface. (line 254)
7408 * KERNEL_U_ADDR: Native Debugging. (line 172)
7409 * KERNEL_U_ADDR_HPUX: Native Debugging. (line 180)
7410 * L_SET: Host Definition. (line 166)
7411 * language parser: Language Support. (line 25)
7412 * language support: Language Support. (line 6)
7413 * legal papers for code contributions: Debugging GDB. (line 42)
7414 * length_of_subexp: Language Support. (line 58)
7415 * libgdb: libgdb. (line 9)
7416 * libiberty library: Support Libraries. (line 51)
7417 * line wrap in output: Coding. (line 190)
7418 * lint: Host Definition. (line 199)
7419 * list output functions: User Interface. (line 131)
7420 * LITTLE_BREAKPOINT: Target Architecture Definition.
7422 * long long data type: Host Definition. (line 139)
7423 * LONG_MAX: Host Definition. (line 125)
7424 * LONGEST: Host Definition. (line 133)
7425 * longjmp debugging: Algorithms. (line 285)
7426 * lookup_symbol: Symbol Handling. (line 128)
7427 * LSEEK_NOT_LINEAR: Host Definition. (line 161)
7428 * make_cleanup: Coding. (line 28)
7429 * making a new release of gdb: Releasing GDB. (line 6)
7430 * memory representation: Target Architecture Definition.
7432 * MEMORY_INSERT_BREAKPOINT: Target Architecture Definition.
7434 * MEMORY_REMOVE_BREAKPOINT: Target Architecture Definition.
7436 * minimal symbol table: Symbol Handling. (line 97)
7437 * minsymtabs: Symbol Handling. (line 97)
7438 * mmap: Host Definition. (line 116)
7439 * multi-arch data: Coding. (line 100)
7440 * NAME_OF_MALLOC: Target Architecture Definition.
7442 * NATDEPFILES: Native Debugging. (line 8)
7443 * native conditionals: Native Debugging. (line 128)
7444 * native core files: Native Debugging. (line 63)
7445 * native debugging: Native Debugging. (line 6)
7446 * nesting level in ui_out functions: User Interface. (line 143)
7447 * Netware Loadable Module format: Symbol Handling. (line 278)
7448 * new year procedure: Start of New Year Procedure.
7450 * NO_HIF_SUPPORT: Target Architecture Definition.
7452 * NO_STD_REGS: Host Definition. (line 82)
7453 * NORETURN: Host Definition. (line 171)
7454 * normal_stop: GDB Observers. (line 76)
7455 * normal_stop observer: GDB Observers. (line 48)
7456 * notification about inferior execution stop: GDB Observers. (line 48)
7457 * notifications about changes in internals: Algorithms. (line 610)
7458 * object file formats: Symbol Handling. (line 196)
7459 * observer pattern interface: Algorithms. (line 610)
7460 * observers implementation rationale: GDB Observers. (line 9)
7461 * obsolete code: Debugging GDB. (line 94)
7462 * obstacks: Support Libraries. (line 68)
7463 * ONE_PROCESS_WRITETEXT: Native Debugging. (line 185)
7464 * op_print_tab: Language Support. (line 91)
7465 * opcodes library: Support Libraries. (line 39)
7466 * OS ABI variants: Target Architecture Definition.
7468 * OS9K_VARIABLES_INSIDE_BLOCK: Target Architecture Definition.
7470 * PARM_BOUNDARY: Target Architecture Definition.
7472 * parse_exp_1: Language Support. (line 97)
7473 * partial symbol table: Symbol Handling. (line 100)
7474 * PC_LOAD_SEGMENT: Target Architecture Definition.
7476 * PC_REGNUM: Target Architecture Definition.
7478 * PE-COFF format: Symbol Handling. (line 252)
7479 * per-architecture module data: Coding. (line 100)
7480 * pointer representation: Target Architecture Definition.
7482 * POINTER_TO_ADDRESS: Target Architecture Definition.
7484 * portability: Coding. (line 556)
7485 * portable file name handling: Coding. (line 573)
7486 * porting to new machines: Porting GDB. (line 6)
7487 * prefixify_subexp: Language Support. (line 58)
7488 * PRINT_FLOAT_INFO: Target Architecture Definition.
7490 * print_registers_info: Target Architecture Definition.
7492 * print_subexp: Language Support. (line 91)
7493 * PRINT_VECTOR_INFO: Target Architecture Definition.
7495 * PRINTF_HAS_LONG_DOUBLE: Host Definition. (line 151)
7496 * PRINTF_HAS_LONG_LONG: Host Definition. (line 142)
7497 * PROC_NAME_FMT: Native Debugging. (line 190)
7498 * PROCESS_LINENUMBER_HOOK: Target Architecture Definition.
7500 * program counter: Algorithms. (line 182)
7501 * prologue analysis: Algorithms. (line 38)
7502 * prologue-value.c: Algorithms. (line 72)
7503 * PROLOGUE_FIRSTLINE_OVERLAP: Target Architecture Definition.
7505 * prompt: Host Definition. (line 107)
7506 * PS_REGNUM: Target Architecture Definition.
7508 * pseudo-evaluation of function prologues: Algorithms. (line 72)
7509 * psymtabs: Symbol Handling. (line 93)
7510 * PTRACE_ARG3_TYPE: Native Debugging. (line 195)
7511 * push_dummy_call: Target Architecture Definition.
7513 * push_dummy_code: Target Architecture Definition.
7515 * raw register representation: Target Architecture Definition.
7517 * read_fp: Target Architecture Definition.
7519 * read_pc: Target Architecture Definition.
7521 * read_sp: Target Architecture Definition.
7523 * reading of symbols: Symbol Handling. (line 12)
7524 * red zone: Target Architecture Definition.
7526 * register data formats, converting: Target Architecture Definition.
7528 * register groups: Target Architecture Definition.
7530 * register representation: Target Architecture Definition.
7532 * REGISTER_CONVERT_TO_RAW: Target Architecture Definition.
7534 * REGISTER_CONVERT_TO_TYPE: Target Architecture Definition.
7536 * REGISTER_CONVERT_TO_VIRTUAL: Target Architecture Definition.
7538 * REGISTER_CONVERTIBLE: Target Architecture Definition.
7540 * REGISTER_NAME: Target Architecture Definition.
7542 * register_reggroup_p: Target Architecture Definition.
7544 * REGISTER_TO_VALUE: Target Architecture Definition.
7546 * register_type: Target Architecture Definition.
7548 * REGISTER_U_ADDR: Native Debugging. (line 199)
7549 * REGISTER_VIRTUAL_TYPE: Target Architecture Definition.
7551 * regset_from_core_section: Target Architecture Definition.
7553 * regular expressions library: Support Libraries. (line 109)
7554 * Release Branches: Versions and Branches.
7556 * remote debugging support: Host Definition. (line 57)
7557 * REMOTE_BPT_VECTOR: Target Architecture Definition.
7559 * representations, raw and virtual registers: Target Architecture Definition.
7561 * representations, register and memory: Target Architecture Definition.
7563 * requirements for GDB: Requirements. (line 6)
7564 * restart: Algorithms. (line 580)
7565 * running the test suite: Testsuite. (line 19)
7566 * SAVE_DUMMY_FRAME_TOS: Target Architecture Definition.
7568 * SCANF_HAS_LONG_DOUBLE: Host Definition. (line 156)
7569 * SDB_REG_TO_REGNUM: Target Architecture Definition.
7571 * secondary symbol file: Symbol Handling. (line 33)
7572 * SEEK_CUR: Host Definition. (line 185)
7573 * SEEK_SET: Host Definition. (line 186)
7574 * sentinel frame: Algorithms. (line 30)
7575 * SENTINEL_FRAME: Algorithms. (line 30)
7576 * separate data and code address spaces: Target Architecture Definition.
7578 * serial line support: Host Definition. (line 57)
7579 * SHELL_COMMAND_CONCAT: Native Debugging. (line 202)
7580 * SHELL_FILE: Native Debugging. (line 206)
7581 * SIGWINCH_HANDLER: Host Definition. (line 85)
7582 * SIGWINCH_HANDLER_BODY: Host Definition. (line 89)
7583 * SKIP_PERMANENT_BREAKPOINT: Target Architecture Definition.
7585 * SKIP_PROLOGUE: Target Architecture Definition.
7587 * SKIP_SOLIB_RESOLVER: Target Architecture Definition.
7589 * SKIP_TRAMPOLINE_CODE: Target Architecture Definition.
7591 * SLASH_STRING: Coding. (line 610)
7592 * software breakpoints: Algorithms. (line 208)
7593 * software watchpoints: Algorithms. (line 306)
7594 * SOFTWARE_SINGLE_STEP: Target Architecture Definition.
7596 * SOFTWARE_SINGLE_STEP_P: Target Architecture Definition.
7598 * SOFUN_ADDRESS_MAYBE_MISSING: Target Architecture Definition.
7600 * SOLIB_ADD: Native Debugging. (line 210)
7601 * SOLIB_CREATE_INFERIOR_HOOK: Native Debugging. (line 216)
7602 * solib_loaded: GDB Observers. (line 96)
7603 * solib_unloaded: GDB Observers. (line 101)
7604 * SOM debugging info: Symbol Handling. (line 328)
7605 * SOM format: Symbol Handling. (line 270)
7606 * source code formatting: Coding. (line 349)
7607 * SP_REGNUM: Target Architecture Definition.
7609 * spaces, separate data and code address: Target Architecture Definition.
7611 * STAB_REG_TO_REGNUM: Target Architecture Definition.
7613 * stabs debugging info: Symbol Handling. (line 290)
7614 * stabs_argument_has_addr: Target Architecture Definition.
7616 * stack alignment: Host Definition. (line 94)
7617 * START_INFERIOR_TRAPS_EXPECTED: Native Debugging. (line 220)
7618 * STEP_SKIPS_DELAY: Target Architecture Definition.
7620 * STOP_SIGNAL: Host Definition. (line 190)
7621 * STOPPED_BY_WATCHPOINT: Algorithms. (line 408)
7622 * STORE_RETURN_VALUE: Target Architecture Definition.
7624 * store_typed_address: Target Architecture Definition.
7626 * struct: GDB Observers. (line 62)
7627 * struct value, converting register contents to: Target Architecture Definition.
7629 * submitting patches: Debugging GDB. (line 30)
7630 * sym_fns structure: Symbol Handling. (line 23)
7631 * symbol files: Symbol Handling. (line 12)
7632 * symbol lookup: Symbol Handling. (line 119)
7633 * symbol reading: Symbol Handling. (line 12)
7634 * SYMBOL_RELOADING_DEFAULT: Target Architecture Definition.
7636 * SYMBOLS_CAN_START_WITH_DOLLAR: Target Architecture Definition.
7638 * symtabs: Symbol Handling. (line 90)
7639 * system dependencies: Coding. (line 560)
7640 * table output functions: User Interface. (line 131)
7641 * target: Overall Structure. (line 50)
7642 * target architecture definition: Target Architecture Definition.
7644 * target vector: Target Vector Definition.
7646 * TARGET_CAN_USE_HARDWARE_WATCHPOINT: Algorithms. (line 352)
7647 * target_changed: GDB Observers. (line 79)
7648 * TARGET_CHAR_BIT: Target Architecture Definition.
7650 * TARGET_CHAR_SIGNED: Target Architecture Definition.
7652 * TARGET_COMPLEX_BIT: Target Architecture Definition.
7654 * TARGET_DOUBLE_BIT: Target Architecture Definition.
7656 * TARGET_DOUBLE_COMPLEX_BIT: Target Architecture Definition.
7658 * TARGET_FLOAT_BIT: Target Architecture Definition.
7660 * TARGET_HAS_HARDWARE_WATCHPOINTS: Algorithms. (line 349)
7661 * target_insert_breakpoint: Algorithms. (line 238)
7662 * target_insert_hw_breakpoint: Algorithms. (line 261)
7663 * target_insert_watchpoint: Algorithms. (line 366)
7664 * TARGET_INT_BIT: Target Architecture Definition.
7666 * TARGET_LONG_BIT: Target Architecture Definition.
7668 * TARGET_LONG_DOUBLE_BIT: Target Architecture Definition.
7670 * TARGET_LONG_LONG_BIT: Target Architecture Definition.
7672 * TARGET_PRINT_INSN: Target Architecture Definition.
7674 * TARGET_PTR_BIT: Target Architecture Definition.
7676 * TARGET_READ_FP: Target Architecture Definition.
7678 * TARGET_READ_PC: Target Architecture Definition.
7680 * TARGET_READ_SP: Target Architecture Definition.
7682 * TARGET_REGION_OK_FOR_HW_WATCHPOINT: Algorithms. (line 362)
7683 * target_remove_breakpoint: Algorithms. (line 238)
7684 * target_remove_hw_breakpoint: Algorithms. (line 261)
7685 * target_remove_watchpoint: Algorithms. (line 366)
7686 * TARGET_SHORT_BIT: Target Architecture Definition.
7688 * target_stopped_data_address: Algorithms. (line 383)
7689 * TARGET_VIRTUAL_FRAME_POINTER: Target Architecture Definition.
7691 * TARGET_WRITE_PC: Target Architecture Definition.
7693 * targets: Existing Targets. (line 6)
7694 * TCP remote support: Host Definition. (line 66)
7695 * TDEPFILES: Target Architecture Definition.
7697 * terminal device: Host Definition. (line 110)
7698 * test suite: Testsuite. (line 6)
7699 * test suite organization: Testsuite. (line 79)
7700 * trimming language-dependent code: Language Support. (line 101)
7701 * tuple output functions: User Interface. (line 131)
7702 * type: Target Architecture Definition.
7704 * type codes: Symbol Handling. (line 172)
7705 * types: Coding. (line 431)
7706 * U_REGS_OFFSET: Native Debugging. (line 231)
7707 * ui_out functions: User Interface. (line 47)
7708 * ui_out functions, usage examples: User Interface. (line 397)
7709 * ui_out_field_core_addr: User Interface. (line 287)
7710 * ui_out_field_fmt: User Interface. (line 261)
7711 * ui_out_field_fmt_int: User Interface. (line 280)
7712 * ui_out_field_int: User Interface. (line 273)
7713 * ui_out_field_skip: User Interface. (line 351)
7714 * ui_out_field_stream: User Interface. (line 319)
7715 * ui_out_field_string: User Interface. (line 291)
7716 * ui_out_flush: User Interface. (line 391)
7717 * ui_out_list_begin: User Interface. (line 234)
7718 * ui_out_list_end: User Interface. (line 240)
7719 * ui_out_message: User Interface. (line 375)
7720 * ui_out_spaces: User Interface. (line 370)
7721 * ui_out_stream_delete: User Interface. (line 314)
7722 * ui_out_table_begin: User Interface. (line 165)
7723 * ui_out_table_body: User Interface. (line 191)
7724 * ui_out_table_end: User Interface. (line 194)
7725 * ui_out_table_header: User Interface. (line 178)
7726 * ui_out_text: User Interface. (line 357)
7727 * ui_out_tuple_begin: User Interface. (line 210)
7728 * ui_out_tuple_end: User Interface. (line 216)
7729 * ui_out_wrap_hint: User Interface. (line 381)
7730 * ui_stream: User Interface. (line 308)
7731 * UINT_MAX: Host Definition. (line 126)
7732 * ULONG_MAX: Host Definition. (line 127)
7733 * unwind_dummy_id: Target Architecture Definition.
7735 * unwind_pc: Target Architecture Definition.
7737 * unwind_sp: Target Architecture Definition.
7739 * USE_PROC_FS: Native Debugging. (line 226)
7740 * USG: Host Definition. (line 194)
7741 * using ui_out functions: User Interface. (line 397)
7742 * value_as_address: Target Architecture Definition.
7744 * value_from_pointer: Target Architecture Definition.
7746 * VALUE_TO_REGISTER: Target Architecture Definition.
7748 * VARIABLES_INSIDE_BLOCK: Target Architecture Definition.
7750 * VEC: Support Libraries. (line 130)
7751 * vendor branches: Versions and Branches.
7753 * virtual register representation: Target Architecture Definition.
7755 * void: GDB Observers. (line 67)
7756 * volatile: Host Definition. (line 202)
7757 * watchpoints: Algorithms. (line 300)
7758 * watchpoints, on x86: Algorithms. (line 425)
7759 * word-addressed machines: Target Architecture Definition.
7761 * wrap_here: Coding. (line 190)
7762 * write_pc: Target Architecture Definition.
7764 * writing tests: Testsuite. (line 131)
7765 * x86 debug registers: Algorithms. (line 425)
7766 * XCOFF format: Symbol Handling. (line 236)
7772 Node: Requirements
\7f1803
7773 Node: Overall Structure
\7f3291
7774 Node: Algorithms
\7f8224
7775 Node: User Interface
\7f37932
7776 Ref: User Interface-Footnote-1
\7f61709
7777 Ref: User Interface-Footnote-2
\7f61758
7778 Node: libgdb
\7f61993
7779 Node: Symbol Handling
\7f65953
7780 Node: Language Support
\7f81053
7781 Node: Host Definition
\7f86454
7782 Node: Target Architecture Definition
\7f93811
7783 Ref: BREAKPOINT_FROM_PC
\7f121433
7784 Ref: DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS
\7f127601
7785 Ref: frame_align
\7f128433
7786 Ref: DEPRECATED_FRAME_SAVED_PC
\7f130812
7787 Ref: unwind_pc
\7f130998
7788 Ref: unwind_sp
\7f131551
7789 Ref: stabs_argument_has_addr
\7f144014
7790 Ref: push_dummy_call
\7f144788
7791 Ref: push_dummy_code
\7f145374
7792 Ref: DEPRECATED_REG_STRUCT_HAS_ADDR
\7f146219
7793 Ref: SAVE_DUMMY_FRAME_TOS
\7f146453
7794 Ref: gdbarch_return_value
\7f147072
7795 Ref: DEPRECATED_STACK_ALIGN
\7f150357
7796 Ref: TARGET_WRITE_PC
\7f152984
7797 Ref: TARGET_READ_SP
\7f153018
7798 Ref: unwind_dummy_id
\7f154691
7799 Ref: Target Architecture Definition-Footnote-1
\7f163244
7800 Ref: Target Architecture Definition-Footnote-2
\7f163487
7801 Node: Target Vector Definition
\7f163606
7802 Node: Managing Execution State
\7f164149
7803 Node: Existing Targets
\7f165962
7804 Node: Native Debugging
\7f168283
7805 Node: Support Libraries
\7f178722
7806 Node: Coding
\7f190128
7807 Node: Porting GDB
\7f215847
7808 Node: Versions and Branches
\7f217756
7810 Ref: experimental branch tags
\7f224046
7811 Node: Start of New Year Procedure
\7f224778
7812 Node: Releasing GDB
\7f225776
7813 Node: Testsuite
\7f244120
7814 Node: Hints
\7f251073
7815 Node: Getting Started
\7f251395
7816 Node: Debugging GDB
\7f255538
7817 Node: GDB Observers
\7f260900
7818 Node: GNU Free Documentation License
\7f265265
7819 Node: Index
\7f287709