1 This is Info file gdbint.info, produced by Makeinfo version 1.68 from
2 the input file ./gdbint.texinfo.
5 * Gdb-Internals: (gdbint). The GNU debugger's internals.
8 This file documents the internals of the GNU debugger GDB.
10 Copyright 1990-1999 Free Software Foundation, Inc. Contributed by
11 Cygnus Solutions. Written by John Gilmore. Second Edition by Stan
14 Permission is granted to make and distribute verbatim copies of this
15 manual provided the copyright notice and this permission notice are
16 preserved on all copies.
18 Permission is granted to copy or distribute modified versions of this
19 manual under the terms of the GPL (for which purpose this text may be
20 regarded as a program in the language TeX).
23 File: gdbint.info, Node: Target Architecture Definition, Next: Target Vector Definition, Prev: Host Definition, Up: Top
25 Target Architecture Definition
26 ******************************
28 GDB's target architecture defines what sort of machine-language
29 programs GDB can work with, and how it works with them.
31 At present, the target architecture definition consists of a number
37 GDB's model of the target machine is rather simple. GDB assumes the
38 machine includes a bank of registers and a block of memory. Each
39 register may have a different size.
41 GDB does not have a magical way to match up with the compiler's idea
42 of which registers are which; however, it is critical that they do
43 match up accurately. The only way to make this work is to get accurate
44 information about the order that the compiler uses, and to reflect that
45 in the `REGISTER_NAME' and related macros.
47 GDB can handle big-endian, little-endian, and bi-endian
56 Compiler Characteristics
57 ========================
62 This section describes the macros that you can use to define the
67 `ADDITIONAL_OPTION_CASES'
69 `ADDITIONAL_OPTION_HANDLER'
71 `ADDITIONAL_OPTION_HELP'
72 These are a set of macros that allow the addition of additional
73 command line options to GDB. They are currently used only for the
74 unsupported i960 Nindy target, and should not be used in any other
77 `ADDR_BITS_REMOVE (addr)'
78 If a raw machine address includes any bits that are not really
79 part of the address, then define this macro to expand into an
80 expression that zeros those bits in ADDR. For example, the two
81 low-order bits of a Motorola 88K address may be used by some
82 kernels for their own purposes, since addresses must always be
83 4-byte aligned, and so are of no use for addressing. Those bits
84 should be filtered out with an expression such as `((addr) & ~3)'.
86 `BEFORE_MAIN_LOOP_HOOK'
87 Define this to expand into any code that you want to execute
88 before the main loop starts. Although this is not, strictly
89 speaking, a target conditional, that is how it is currently being
90 used. Note that if a configuration were to define it one way for
91 a host and a different way for the target, GDB will probably not
92 compile, let alone run correctly. This is currently used only for
93 the unsupported i960 Nindy target, and should not be used in any
96 `BELIEVE_PCC_PROMOTION'
97 Define if the compiler promotes a short or char parameter to an
98 int, but still reports the parameter as its original type, rather
99 than the promoted type.
101 `BELIEVE_PCC_PROMOTION_TYPE'
102 Define this if GDB should believe the type of a short argument when
103 compiled by pcc, but look within a full int space to get its value.
104 Only defined for Sun-3 at present.
107 Define this if the numbering of bits in the targets does *not*
108 match the endianness of the target byte order. A value of 1 means
109 that the bits are numbered in a big-endian order, 0 means
113 This is the character array initializer for the bit pattern to put
114 into memory where a breakpoint is set. Although it's common to
115 use a trap instruction for a breakpoint, it's not required; for
116 instance, the bit pattern could be an invalid instruction. The
117 breakpoint must be no longer than the shortest instruction of the
123 Similar to BREAKPOINT, but used for bi-endian targets.
127 `LITTLE_REMOTE_BREAKPOINT'
129 `BIG_REMOTE_BREAKPOINT'
130 Similar to BREAKPOINT, but used for remote targets.
132 `BREAKPOINT_FROM_PC (pcptr, lenptr)'
133 Use the program counter to determine the contents and size of a
134 breakpoint instruction. It returns a pointer to a string of bytes
135 that encode a breakpoint instruction, stores the length of the
136 string to *lenptr, and adjusts pc (if necessary) to point to the
137 actual memory location where the breakpoint should be inserted.
139 Although it is common to use a trap instruction for a breakpoint,
140 it's not required; for instance, the bit pattern could be an
141 invalid instruction. The breakpoint must be no longer than the
142 shortest instruction of the architecture.
144 Replaces all the other BREAKPOINTs.
149 `CALL_DUMMY_LOCATION'
152 `CALL_DUMMY_STACK_ADJUST'
155 `CANNOT_FETCH_REGISTER (regno)'
156 A C expression that should be nonzero if REGNO cannot be fetched
157 from an inferior process. This is only relevant if
158 `FETCH_INFERIOR_REGISTERS' is not defined.
160 `CANNOT_STORE_REGISTER (regno)'
161 A C expression that should be nonzero if REGNO should not be
162 written to the target. This is often the case for program
163 counters, status words, and other special registers. If this is
164 not defined, GDB will assume that all registers may be written.
168 `CLEAR_DEFERRED_STORES'
169 Define this to execute any deferred stores of registers into the
170 inferior, and to cancel any deferred stores.
172 Currently only implemented correctly for native Sparc
176 Define this to expand into the character that G++ uses to
177 distinguish compiler-generated identifiers from
178 programmer-specified identifiers. By default, this expands into
179 `'$''. Most System V targets should define this to `'.''.
181 `DBX_PARM_SYMBOL_CLASS'
182 Hook for the `SYMBOL_CLASS' of a parameter when decoding DBX symbol
183 information. In the i960, parameters can be stored as locals or as
184 args, depending on the type of the debug record.
186 `DECR_PC_AFTER_BREAK'
187 Define this to be the amount by which to decrement the PC after the
188 program encounters a breakpoint. This is often the number of
189 bytes in BREAKPOINT, though not always. For most targets this
192 `DECR_PC_AFTER_HW_BREAK'
193 Similarly, for hardware breakpoints.
195 `DISABLE_UNSETTABLE_BREAK addr'
196 If defined, this should evaluate to 1 if ADDR is in a shared
197 library in which breakpoints cannot be set and so should be
201 If defined, use this to print the value of a register or all
204 `END_OF_TEXT_DEFAULT'
205 This is an expression that should designate the end of the text
208 `EXTRACT_RETURN_VALUE(type,regbuf,valbuf)'
209 Define this to extract a function's return value of type TYPE from
210 the raw register state REGBUF and copy that, in virtual format,
213 `EXTRACT_STRUCT_VALUE_ADDRESS(regbuf)'
214 Define this to extract from an array REGBUF containing the (raw)
215 register state, the address in which a function should return its
216 structure value, as a CORE_ADDR (or an expression that can be used
220 If defined, then the `info float' command will print information
221 about the processor's floating point unit.
224 The number of the frame pointer register.
226 `FRAMELESS_FUNCTION_INVOCATION(fi, frameless)'
227 Define this to set the variable FRAMELESS to 1 if the function
228 invocation represented by FI does not have a stack frame
229 associated with it. Otherwise set it to 0.
231 `FRAME_ARGS_ADDRESS_CORRECT'
235 Given FRAME, return a pointer to the calling frame.
237 `FRAME_CHAIN_COMBINE(chain,frame)'
238 Define this to take the frame chain pointer and the frame's nominal
239 address and produce the nominal address of the caller's frame.
240 Presently only defined for HP PA.
242 `FRAME_CHAIN_VALID(chain,thisframe)'
243 Define this to be an expression that returns zero if the given
244 frame is an outermost frame, with no caller, and nonzero
245 otherwise. Three common definitions are available.
246 `default_frame_chain_valid' (the default) is nonzero if the chain
247 pointer is nonzero and given frame's PC is not inside the startup
248 file (such as `crt0.o'). `alternate_frame_chain_valid' is nonzero
249 if the chain pointer is nonzero and the given frame's PC is not in
250 `main()' or a known entry point function (such as `_start()').
252 `FRAME_INIT_SAVED_REGS(frame)'
253 See `frame.h'. Determines the address of all registers in the
254 current stack frame storing each in `frame->saved_regs'. Space for
255 `frame->saved_regs' shall be allocated by `FRAME_INIT_SAVED_REGS'
256 using either `frame_saved_regs_zalloc' or `frame_obstack_alloc'.
258 FRAME_FIND_SAVED_REGS and EXTRA_FRAME_INFO are deprecated.
260 `FRAME_NUM_ARGS (val, fi)'
261 For the frame described by FI, set VAL to the number of arguments
262 that are being passed.
264 `FRAME_SAVED_PC(frame)'
265 Given FRAME, return the pc saved there. That is, the return
268 `FUNCTION_EPILOGUE_SIZE'
269 For some COFF targets, the `x_sym.x_misc.x_fsize' field of the
270 function end symbol is 0. For such targets, you must define
271 `FUNCTION_EPILOGUE_SIZE' to expand into the standard size of a
274 `GCC_COMPILED_FLAG_SYMBOL'
276 `GCC2_COMPILED_FLAG_SYMBOL'
277 If defined, these are the names of the symbols that GDB will look
278 for to detect that GCC compiled the file. The default symbols are
279 `gcc_compiled.' and `gcc2_compiled.', respectively. (Currently
280 only defined for the Delta 68.)
283 This determines whether horrible kludge code in dbxread.c and
284 partial-stab.h is used to mangle multiple-symbol-table files from
285 HPPA's. This should all be ripped out, and a scheme like elfread.c
288 `GDB_TARGET_IS_MACH386'
292 `GDB_TARGET_IS_SUN386'
293 Kludges that should go away.
296 For most machines, this is a target-dependent parameter. On the
297 DECstation and the Iris, this is a native-dependent parameter,
298 since <setjmp.h> is needed to define it.
300 This macro determines the target PC address that longjmp() will
301 jump to, assuming that we have just stopped at a longjmp
302 breakpoint. It takes a CORE_ADDR * as argument, and stores the
303 target PC value through this pointer. It examines the current
304 state of the machine as needed.
307 Define this if you need to supply your own definition for the
308 function `get_saved_register'. Currently this is only done for
311 `HAVE_REGISTER_WINDOWS'
312 Define this if the target has register windows.
314 `REGISTER_IN_WINDOW_P (regnum)'
315 Define this to be an expression that is 1 if the given register is
319 Shows that we are configured for an IBM RS/6000 target. This
320 conditional should be eliminated (FIXME) and replaced by
321 feature-specific macros. It was introduced in haste and we are
322 repenting at leisure.
325 Define this if the target system uses IEEE-format floating point
328 `INIT_EXTRA_FRAME_INFO (fromleaf, frame)'
329 If additional information about the frame is required this should
330 be stored in `frame->extra_info'. Space for `frame->extra_info'
331 is allocated using `frame_obstack_alloc'.
333 `INIT_FRAME_PC (fromleaf, prev)'
334 This is a C statement that sets the pc of the frame pointed to by
335 PREV. [By default...]
337 `INNER_THAN (lhs,rhs)'
338 Returns non-zero if stack address LHS is inner than (nearer to the
339 stack top) stack address RHS. Define this as `lhs < rhs' if the
340 target's stack grows downward in memory, or `lhs > rsh' if the
343 `IN_SIGTRAMP (pc, name)'
344 Define this to return true if the given PC and/or NAME indicates
345 that the current function is a sigtramp.
347 `SIGTRAMP_START (pc)'
350 Define these to be the start and end address of the sigtramp for
351 the given PC. On machines where the address is just a compile time
352 constant, the macro expansion will typically just ignore the
355 `IN_SOLIB_CALL_TRAMPOLINE pc name'
356 Define this to evaluate to nonzero if the program is stopped in the
357 trampoline that connects to a shared library.
359 `IN_SOLIB_RETURN_TRAMPOLINE pc name'
360 Define this to evaluate to nonzero if the program is stopped in the
361 trampoline that returns from a shared library.
363 `IS_TRAPPED_INTERNALVAR (name)'
364 This is an ugly hook to allow the specification of special actions
365 that should occur as a side-effect of setting the value of a
366 variable internal to GDB. Currently only used by the h8500. Note
367 that this could be either a host or target conditional.
369 `NEED_TEXT_START_END'
370 Define this if GDB should determine the start and end addresses of
371 the text section. (Seems dubious.)
374 (Specific to the a29k.)
376 `SOFTWARE_SINGLE_STEP_P'
377 Define this as 1 if the target does not have a hardware single-step
378 mechanism. The macro `SOFTWARE_SINGLE_STEP' must also be defined.
380 `SOFTWARE_SINGLE_STEP(signal,insert_breapoints_p)'
381 A function that inserts or removes (dependant on
382 INSERT_BREAPOINTS_P) breakpoints at each possible destinations of
383 the next instruction. See `sparc-tdep.c' and `rs6000-tdep.c' for
387 (Used only in the Convex target.)
393 If defined, print information about the load segment for the
394 program counter. (Defined only for the RS/6000.)
397 If the program counter is kept in a register, then define this
398 macro to be the number of that register. This need be defined
399 only if `TARGET_WRITE_PC' is not defined.
402 The number of the "next program counter" register, if defined.
405 The number of the "next next program counter" register, if defined.
406 Currently, this is only defined for the Motorola 88K.
408 `PRINT_REGISTER_HOOK (regno)'
409 If defined, this must be a function that prints the contents of the
410 given register to standard output.
412 `PRINT_TYPELESS_INTEGER'
413 This is an obscure substitute for `print_longest' that seems to
414 have been defined for the Convex target.
416 `PROCESS_LINENUMBER_HOOK'
417 A hook defined for XCOFF reading.
419 `PROLOGUE_FIRSTLINE_OVERLAP'
420 (Only used in unsupported Convex configuration.)
423 If defined, this is the number of the processor status register.
424 (This definition is only used in generic code when parsing "$ps".)
427 Used in `call_function_by_hand' to remove an artificial stack
430 `PUSH_ARGUMENTS (nargs, args, sp, struct_return, struct_addr)'
431 Define this to push arguments onto the stack for inferior function
435 Used in `call_function_by_hand' to create an artificial stack
439 The total amount of space needed to store GDB's copy of the
440 machine's register state.
443 Return the name of register I as a string. May return NULL or NUL
444 to indicate that register I is not valid.
446 `REG_STRUCT_HAS_ADDR (gcc_p, type)'
447 Define this to return 1 if the given type will be passed by pointer
448 rather than directly.
451 Define this to convert sdb register numbers into GDB regnums. If
452 not defined, no conversion will be done.
455 (Only used for m88k targets.)
458 A C statement that advances the PC across any function entry
459 prologue instructions so as to reach "real" code.
461 `SKIP_PROLOGUE_FRAMELESS_P'
462 A C statement that should behave similarly, but that can stop as
463 soon as the function is known to have a frame. If not defined,
464 `SKIP_PROLOGUE' will be used instead.
466 `SKIP_TRAMPOLINE_CODE (pc)'
467 If the target machine has trampoline code that sits between
468 callers and the functions being called, then define this macro to
469 return a new PC that is at the start of the real function.
472 Define this to be the number of the register that serves as the
476 Define this to convert stab register numbers (as gotten from `r'
477 declarations) into GDB regnums. If not defined, no conversion
481 Define this to adjust the address to the alignment required for the
484 `STEP_SKIPS_DELAY (addr)'
485 Define this to return true if the address is of an instruction
486 with a delay slot. If a breakpoint has been placed in the
487 instruction's delay slot, GDB will single-step over that
488 instruction before resuming normally. Currently only defined for
491 `STORE_RETURN_VALUE (type, valbuf)'
492 A C expression that stores a function return value of type TYPE,
493 where VALBUF is the address of the value to be stored.
495 `SUN_FIXED_LBRAC_BUG'
496 (Used only for Sun-3 and Sun-4 targets.)
498 `SYMBOL_RELOADING_DEFAULT'
499 The default value of the `symbol-reloading' variable. (Never
500 defined in current sources.)
502 `TARGET_BYTE_ORDER_DEFAULT'
503 The ordering of bytes in the target. This must be either
504 `BIG_ENDIAN' or `LITTLE_ENDIAN'. This macro replaces
505 TARGET_BYTE_ORDER which is deprecated.
507 `TARGET_BYTE_ORDER_SELECTABLE_P'
508 Non-zero if the target has both `BIG_ENDIAN' and `LITTLE_ENDIAN'
509 variants. This macro replaces TARGET_BYTE_ORDER_SELECTABLE which
513 Number of bits in a char; defaults to 8.
516 Number of bits in a complex number; defaults to `2 *
520 Number of bits in a double float; defaults to `8 *
523 `TARGET_DOUBLE_COMPLEX_BIT'
524 Number of bits in a double complex; defaults to `2 *
528 Number of bits in a float; defaults to `4 * TARGET_CHAR_BIT'.
531 Number of bits in an integer; defaults to `4 * TARGET_CHAR_BIT'.
534 Number of bits in a long integer; defaults to `4 *
537 `TARGET_LONG_DOUBLE_BIT'
538 Number of bits in a long double float; defaults to `2 *
541 `TARGET_LONG_LONG_BIT'
542 Number of bits in a long long integer; defaults to `2 *
546 Number of bits in a pointer; defaults to `TARGET_INT_BIT'.
549 Number of bits in a short integer; defaults to `2 *
554 `TARGET_WRITE_PC (val, pid)'
563 These change the behavior of `read_pc', `write_pc', `read_sp',
564 `write_sp', `read_fp' and `write_fp'. For most targets, these may
565 be left undefined. GDB will call the read and write register
566 functions with the relevant `_REGNUM' argument.
568 These macros are useful when a target keeps one of these registers
569 in a hard to get at place; for example, part in a segment register
570 and part in an ordinary register.
572 `TARGET_VIRTUAL_FRAME_POINTER(pc,regp,offsetp)'
573 Returns a `(register, offset)' pair representing the virtual frame
574 pointer in use at the code address `"pc"'. If virtual frame
575 pointers are not used, a default definition simply returns
576 `FP_REGNUM', with an offset of zero.
578 `USE_STRUCT_CONVENTION (gcc_p, type)'
579 If defined, this must be an expression that is nonzero if a value
580 of the given TYPE being returned from a function must have space
581 allocated for it on the stack. GCC_P is true if the function
582 being considered is known to have been compiled by GCC; this is
583 helpful for systems where GCC is known to use different calling
584 convention than other compilers.
586 `VARIABLES_INSIDE_BLOCK (desc, gcc_p)'
587 For dbx-style debugging information, if the compiler puts variable
588 declarations inside LBRAC/RBRAC blocks, this should be defined to
589 be nonzero. DESC is the value of `n_desc' from the `N_RBRAC'
590 symbol, and GCC_P is true if GDB has noticed the presence of
591 either the `GCC_COMPILED_SYMBOL' or the `GCC2_COMPILED_SYMBOL'.
592 By default, this is 0.
594 `OS9K_VARIABLES_INSIDE_BLOCK (desc, gcc_p)'
595 Similarly, for OS/9000. Defaults to 1.
597 Motorola M68K target conditionals.
600 Define this to be the 4-bit location of the breakpoint trap
601 vector. If not defined, it will default to `0xf'.
609 The following files define a target to GDB:
611 `gdb/config/ARCH/TTT.mt'
612 Contains a Makefile fragment specific to this target. Specifies
613 what object files are needed for target TTT, by defining
614 `TDEPFILES=...'. Also specifies the header file which describes
615 TTT, by defining `TM_FILE= tm-TTT.h'. You can also define
616 `TM_CFLAGS', `TM_CLIBS', `TM_CDEPS', but these are now deprecated
617 and may go away in future versions of GDB.
619 `gdb/config/ARCH/tm-TTT.h'
620 (`tm.h' is a link to this file, created by configure). Contains
621 macro definitions about the target machine's registers, stack frame
622 format and instructions.
625 Contains any miscellaneous code required for this target machine.
626 On some machines it doesn't exist at all. Sometimes the macros in
627 `tm-TTT.h' become very complicated, so they are implemented as
628 functions here instead, and the macro is simply defined to call the
629 function. This is vastly preferable, since it is easier to
630 understand and debug.
632 `gdb/config/ARCH/tm-ARCH.h'
633 This often exists to describe the basic layout of the target
634 machine's processor chip (registers, stack, etc). If used, it is
635 included by `tm-TTT.h'. It can be shared among many targets that
636 use the same processor.
639 Similarly, there are often common subroutines that are shared by
640 all target machines that use this particular architecture.
642 If you are adding a new operating system for an existing CPU chip,
643 add a `config/tm-OS.h' file that describes the operating system
644 facilities that are unusual (extra symbol table info; the breakpoint
645 instruction needed; etc). Then write a `ARCH/tm-OS.h' that just
646 `#include's `tm-ARCH.h' and `config/tm-OS.h'.
649 File: gdbint.info, Node: Target Vector Definition, Next: Native Debugging, Prev: Target Architecture Definition, Up: Top
651 Target Vector Definition
652 ************************
654 The target vector defines the interface between GDB's abstract
655 handling of target systems, and the nitty-gritty code that actually
656 exercises control over a process or a serial port. GDB includes some
657 30-40 different target vectors; however, each configuration of GDB
658 includes only a few of them.
663 Both executables and core files have target vectors.
665 Standard Protocol and Remote Stubs
666 ==================================
668 GDB's file `remote.c' talks a serial protocol to code that runs in
669 the target system. GDB provides several sample "stubs" that can be
670 integrated into target programs or operating systems for this purpose;
671 they are named `*-stub.c'.
673 The GDB user's manual describes how to put such a stub into your
674 target code. What follows is a discussion of integrating the SPARC
675 stub into a complicated operating system (rather than a simple
676 program), by Stu Grossman, the author of this stub.
678 The trap handling code in the stub assumes the following upon entry
681 1. %l1 and %l2 contain pc and npc respectively at the time of the trap
683 2. traps are disabled
685 3. you are in the correct trap window
688 As long as your trap handler can guarantee those conditions, then
689 there is no reason why you shouldn't be able to `share' traps with the
690 stub. The stub has no requirement that it be jumped to directly from
691 the hardware trap vector. That is why it calls `exceptionHandler()',
692 which is provided by the external environment. For instance, this could
693 setup the hardware traps to actually execute code which calls the stub
694 first, and then transfers to its own trap handler.
696 For the most point, there probably won't be much of an issue with
697 `sharing' traps, as the traps we use are usually not used by the kernel,
698 and often indicate unrecoverable error conditions. Anyway, this is all
699 controlled by a table, and is trivial to modify. The most important
700 trap for us is for `ta 1'. Without that, we can't single step or do
701 breakpoints. Everything else is unnecessary for the proper operation
702 of the debugger/stub.
704 From reading the stub, it's probably not obvious how breakpoints
705 work. They are simply done by deposit/examine operations from GDB.
707 ROM Monitor Interface
708 =====================
720 File: gdbint.info, Node: Native Debugging, Next: Support Libraries, Prev: Target Vector Definition, Up: Top
725 Several files control GDB's configuration for native support:
727 `gdb/config/ARCH/XYZ.mh'
728 Specifies Makefile fragments needed when hosting *or native* on
729 machine XYZ. In particular, this lists the required
730 native-dependent object files, by defining `NATDEPFILES=...'.
731 Also specifies the header file which describes native support on
732 XYZ, by defining `NAT_FILE= nm-XYZ.h'. You can also define
733 `NAT_CFLAGS', `NAT_ADD_FILES', `NAT_CLIBS', `NAT_CDEPS', etc.; see
736 `gdb/config/ARCH/nm-XYZ.h'
737 (`nm.h' is a link to this file, created by configure). Contains C
738 macro definitions describing the native system environment, such as
739 child process control and core file support.
742 Contains any miscellaneous C code required for this native support
743 of this machine. On some machines it doesn't exist at all.
745 There are some "generic" versions of routines that can be used by
746 various systems. These can be customized in various ways by macros
747 defined in your `nm-XYZ.h' file. If these routines work for the XYZ
748 host, you can just include the generic file's name (with `.o', not
749 `.c') in `NATDEPFILES'.
751 Otherwise, if your machine needs custom support routines, you will
752 need to write routines that perform the same functions as the generic
753 file. Put them into `XYZ-nat.c', and put `XYZ-nat.o' into
757 This contains the *target_ops vector* that supports Unix child
758 processes on systems which use ptrace and wait to control the
762 This contains the *target_ops vector* that supports Unix child
763 processes on systems which use /proc to control the child.
766 This does the low-level grunge that uses Unix system calls to do a
767 "fork and exec" to start up a child process.
770 This is the low level interface to inferior processes for systems
771 using the Unix `ptrace' call in a vanilla way.
773 Native core file Support
774 ========================
776 `core-aout.c::fetch_core_registers()'
777 Support for reading registers out of a core file. This routine
778 calls `register_addr()', see below. Now that BFD is used to read
779 core files, virtually all machines should use `core-aout.c', and
780 should just provide `fetch_core_registers' in `XYZ-nat.c' (or
781 `REGISTER_U_ADDR' in `nm-XYZ.h').
783 `core-aout.c::register_addr()'
784 If your `nm-XYZ.h' file defines the macro `REGISTER_U_ADDR(addr,
785 blockend, regno)', it should be defined to set `addr' to the
786 offset within the `user' struct of GDB register number `regno'.
787 `blockend' is the offset within the "upage" of `u.u_ar0'. If
788 `REGISTER_U_ADDR' is defined, `core-aout.c' will define the
789 `register_addr()' function and use the macro in it. If you do not
790 define `REGISTER_U_ADDR', but you are using the standard
791 `fetch_core_registers()', you will need to define your own version
792 of `register_addr()', put it into your `XYZ-nat.c' file, and be
793 sure `XYZ-nat.o' is in the `NATDEPFILES' list. If you have your
794 own `fetch_core_registers()', you may not need a separate
795 `register_addr()'. Many custom `fetch_core_registers()'
796 implementations simply locate the registers themselves.
798 When making GDB run native on a new operating system, to make it
799 possible to debug core files, you will need to either write specific
800 code for parsing your OS's core files, or customize `bfd/trad-core.c'.
801 First, use whatever `#include' files your machine uses to define the
802 struct of registers that is accessible (possibly in the u-area) in a
803 core file (rather than `machine/reg.h'), and an include file that
804 defines whatever header exists on a core file (e.g. the u-area or a
805 `struct core'). Then modify `trad_unix_core_file_p()' to use these
806 values to set up the section information for the data segment, stack
807 segment, any other segments in the core file (perhaps shared library
808 contents or control information), "registers" segment, and if there are
809 two discontiguous sets of registers (e.g. integer and float), the
810 "reg2" segment. This section information basically delimits areas in
811 the core file in a standard way, which the section-reading routines in
812 BFD know how to seek around in.
814 Then back in GDB, you need a matching routine called
815 `fetch_core_registers()'. If you can use the generic one, it's in
816 `core-aout.c'; if not, it's in your `XYZ-nat.c' file. It will be
817 passed a char pointer to the entire "registers" segment, its length,
818 and a zero; or a char pointer to the entire "regs2" segment, its
819 length, and a 2. The routine should suck out the supplied register
820 values and install them into GDB's "registers" array.
822 If your system uses `/proc' to control processes, and uses ELF
823 format core files, then you may be able to use the same routines for
824 reading the registers out of processes and out of core files.
841 When GDB is configured and compiled, various macros are defined or
842 left undefined, to control compilation when the host and target systems
843 are the same. These macros should be defined (or left undefined) in
847 If defined, then GDB will include support for the `attach' and
850 `CHILD_PREPARE_TO_STORE'
851 If the machine stores all registers at once in the child process,
852 then define this to ensure that all values are correct. This
853 usually entails a read from the child.
855 [Note that this is incorrectly defined in `xm-SYSTEM.h' files
858 `FETCH_INFERIOR_REGISTERS'
859 Define this if the native-dependent code will provide its own
860 routines `fetch_inferior_registers' and `store_inferior_registers'
861 in `HOST-nat.c'. If this symbol is *not* defined, and
862 `infptrace.c' is included in this configuration, the default
863 routines in `infptrace.c' are used for these functions.
866 (Only defined for Convex.)
869 This macro is normally defined to be the number of the first
870 floating point register, if the machine has such registers. As
871 such, it would appear only in target-specific code. However,
872 /proc support uses this to decide whether floats are in use on
876 For most machines, this is a target-dependent parameter. On the
877 DECstation and the Iris, this is a native-dependent parameter,
878 since <setjmp.h> is needed to define it.
880 This macro determines the target PC address that longjmp() will
881 jump to, assuming that we have just stopped at a longjmp
882 breakpoint. It takes a CORE_ADDR * as argument, and stores the
883 target PC value through this pointer. It examines the current
884 state of the machine as needed.
887 Define this to the address of the `u' structure (the "user
888 struct", also known as the "u-page") in kernel virtual memory. GDB
889 needs to know this so that it can subtract this address from
890 absolute addresses in the upage, that are obtained via ptrace or
891 from core files. On systems that don't need this value, set it to
895 Define this to cause GDB to determine the address of `u' at
896 runtime, by using Berkeley-style `nlist' on the kernel's image in
900 Define this to cause GDB to determine the address of `u' at
901 runtime, by using HP-style `nlist' on the kernel's image in the
904 `ONE_PROCESS_WRITETEXT'
905 Define this to be able to, when a breakpoint insertion fails, warn
906 the user that another process may be running with the same
910 Defines the format for the name of a `/proc' device. Should be
911 defined in `nm.h' *only* in order to override the default
912 definition in `procfs.c'.
918 The type of the third argument to the `ptrace' system call, if it
919 exists and is different from `int'.
922 Defines the offset of the registers in the "u area".
924 `SHELL_COMMAND_CONCAT'
925 If defined, is a string to prefix on the shell command used to
929 If defined, this is the name of the shell to use to run the
930 inferior. Defaults to `"/bin/sh"'.
932 `SOLIB_ADD (filename, from_tty, targ)'
933 Define this to expand into an expression that will cause the
934 symbols in FILENAME to be added to GDB's symbol table.
936 `SOLIB_CREATE_INFERIOR_HOOK'
937 Define this to expand into any shared-library-relocation code that
938 you want to be run just after the child process has been forked.
940 `START_INFERIOR_TRAPS_EXPECTED'
941 When starting an inferior, GDB normally expects to trap twice;
942 once when the shell execs, and once when the program itself execs.
943 If the actual number of traps is something other than 2, then
944 define this macro to expand into the number expected.
947 Define this to indicate that SVR4-style shared libraries are in
951 This determines whether small routines in `*-tdep.c', which
952 translate register values between GDB's internal representation
953 and the /proc representation, are compiled.
956 This is the offset of the registers in the upage. It need only be
957 defined if the generic ptrace register access routines in
958 `infptrace.c' are being used (that is, `infptrace.c' is configured
959 in, and `FETCH_INFERIOR_REGISTERS' is not defined). If the
960 default value from `infptrace.c' is good enough, leave it
963 The default value means that u.u_ar0 *points to* the location of
964 the registers. I'm guessing that `#define U_REGS_OFFSET 0' means
965 that u.u_ar0 *is* the location of the registers.
971 Define this to debug ptrace calls.
974 File: gdbint.info, Node: Support Libraries, Next: Coding, Prev: Native Debugging, Up: Top
982 BFD provides support for GDB in several ways:
984 *identifying executable and core files*
985 BFD will identify a variety of file types, including a.out, coff,
986 and several variants thereof, as well as several kinds of core
989 *access to sections of files*
990 BFD parses the file headers to determine the names, virtual
991 addresses, sizes, and file locations of all the various named
992 sections in files (such as the text section or the data section).
993 GDB simply calls BFD to read or write section X at byte offset Y
996 *specialized core file support*
997 BFD provides routines to determine the failing command name stored
998 in a core file, the signal with which the program failed, and
999 whether a core file matches (i.e. could be a core dump of) a
1000 particular executable file.
1002 *locating the symbol information*
1003 GDB uses an internal interface of BFD to determine where to find
1004 the symbol information in an executable file or symbol-file. GDB
1005 itself handles the reading of symbols, since BFD does not
1006 "understand" debug symbols, but GDB uses BFD's cached information
1007 to find the symbols, string table, etc.
1012 The opcodes library provides GDB's disassembler. (It's a separate
1013 library because it's also used in binutils, for `objdump').
1048 File: gdbint.info, Node: Coding, Next: Porting GDB, Prev: Support Libraries, Up: Top
1053 This chapter covers topics that are lower-level than the major
1059 Cleanups are a structured way to deal with things that need to be
1060 done later. When your code does something (like `malloc' some memory,
1061 or open a file) that needs to be undone later (e.g. free the memory or
1062 close the file), it can make a cleanup. The cleanup will be done at
1063 some future point: when the command is finished, when an error occurs,
1064 or when your code decides it's time to do cleanups.
1066 You can also discard cleanups, that is, throw them away without doing
1067 what they say. This is only done if you ask that it be done.
1071 `struct cleanup *OLD_CHAIN;'
1072 Declare a variable which will hold a cleanup chain handle.
1074 `OLD_CHAIN = make_cleanup (FUNCTION, ARG);'
1075 Make a cleanup which will cause FUNCTION to be called with ARG (a
1076 `char *') later. The result, OLD_CHAIN, is a handle that can be
1077 passed to `do_cleanups' or `discard_cleanups' later. Unless you
1078 are going to call `do_cleanups' or `discard_cleanups' yourself,
1079 you can ignore the result from `make_cleanup'.
1081 `do_cleanups (OLD_CHAIN);'
1082 Perform all cleanups done since `make_cleanup' returned OLD_CHAIN.
1084 make_cleanup (a, 0);
1085 old = make_cleanup (b, 0);
1088 will call `b()' but will not call `a()'. The cleanup that calls
1089 `a()' will remain in the cleanup chain, and will be done later
1090 unless otherwise discarded.
1092 `discard_cleanups (OLD_CHAIN);'
1093 Same as `do_cleanups' except that it just removes the cleanups from
1094 the chain and does not call the specified functions.
1096 Some functions, e.g. `fputs_filtered()' or `error()', specify that
1097 they "should not be called when cleanups are not in place". This means
1098 that any actions you need to reverse in the case of an error or
1099 interruption must be on the cleanup chain before you call these
1100 functions, since they might never return to your code (they `longjmp'
1103 Wrapping Output Lines
1104 =====================
1106 Output that goes through `printf_filtered' or `fputs_filtered' or
1107 `fputs_demangled' needs only to have calls to `wrap_here' added in
1108 places that would be good breaking points. The utility routines will
1109 take care of actually wrapping if the line width is exceeded.
1111 The argument to `wrap_here' is an indentation string which is
1112 printed *only* if the line breaks there. This argument is saved away
1113 and used later. It must remain valid until the next call to
1114 `wrap_here' or until a newline has been printed through the
1115 `*_filtered' functions. Don't pass in a local variable and then return!
1117 It is usually best to call `wrap_here()' after printing a comma or
1118 space. If you call it before printing a space, make sure that your
1119 indentation properly accounts for the leading space that will print if
1120 the line wraps there.
1122 Any function or set of functions that produce filtered output must
1123 finish by printing a newline, to flush the wrap buffer, before switching
1124 to unfiltered ("`printf'") output. Symbol reading routines that print
1125 warnings are a good example.
1127 GDB Coding Standards
1128 ====================
1130 GDB follows the GNU coding standards, as described in
1131 `etc/standards.texi'. This file is also available for anonymous FTP
1132 from GNU archive sites. GDB takes a strict interpretation of the
1133 standard; in general, when the GNU standard recommends a practice but
1134 does not require it, GDB requires it.
1136 GDB follows an additional set of coding standards specific to GDB,
1137 as described in the following sections.
1139 You can configure with `--enable-build-warnings' to get GCC to check
1140 on a number of these rules. GDB sources ought not to engender any
1141 complaints, unless they are caused by bogus host systems. (The exact
1142 set of enabled warnings is currently `-Wall -Wpointer-arith
1143 -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations'.
1148 The standard GNU recommendations for formatting must be followed
1151 Note that while in a definition, the function's name must be in
1152 column zero; in a function declaration, the name must be on the same
1153 line as the return type.
1155 In addition, there must be a space between a function or macro name
1156 and the opening parenthesis of its argument list (except for macro
1157 definitions, as required by C). There must not be a space after an open
1158 paren/bracket or before a close paren/bracket.
1160 While additional whitespace is generally helpful for reading, do not
1161 use more than one blank line to separate blocks, and avoid adding
1162 whitespace after the end of a program line (as of 1/99, some 600 lines
1163 had whitespace after the semicolon). Excess whitespace causes
1164 difficulties for diff and patch.
1169 The standard GNU requirements on comments must be followed strictly.
1171 Block comments must appear in the following form, with no `/*'- or
1172 '*/'-only lines, and no leading `*':
1174 /* Wait for control to return from inferior to debugger. If inferior
1175 gets a signal, we may decide to start it up again instead of
1176 returning. That is why there is a loop in this function. When
1177 this function actually returns it means the inferior should be left
1178 stopped and GDB should read more commands. */
1180 (Note that this format is encouraged by Emacs; tabbing for a
1181 multi-line comment works correctly, and M-Q fills the block
1184 Put a blank line between the block comments preceding function or
1185 variable definitions, and the definition itself.
1187 In general, put function-body comments on lines by themselves, rather
1188 than trying to fit them into the 20 characters left at the end of a
1189 line, since either the comment or the code will inevitably get longer
1190 than will fit, and then somebody will have to move it anyhow.
1195 Code must not depend on the sizes of C data types, the format of the
1196 host's floating point numbers, the alignment of anything, or the order
1197 of evaluation of expressions.
1199 Use functions freely. There are only a handful of compute-bound
1200 areas in GDB that might be affected by the overhead of a function call,
1201 mainly in symbol reading. Most of GDB's performance is limited by the
1202 target interface (whether serial line or system call).
1204 However, use functions with moderation. A thousand one-line
1205 functions are just as hard to understand as a single thousand-line
1211 Prototypes must be used to *declare* functions but never to *define*
1212 them. Prototypes for GDB functions must include both the argument type
1213 and name, with the name matching that used in the actual function
1216 For the sake of compatibility with pre-ANSI compilers, define
1217 prototypes with the `PARAMS' macro:
1219 extern int memory_remove_breakpoint PARAMS ((CORE_ADDR addr,
1220 char *contents_cache));
1222 Note the double parentheses around the parameter types. This allows
1223 an arbitrary number of parameters to be described, without freaking out
1224 the C preprocessor. When the function has no parameters, it should be
1227 extern void noprocess PARAMS ((void));
1229 The `PARAMS' macro expands to its argument in ANSI C, or to a simple
1230 `()' in traditional C.
1232 All external functions should have a `PARAMS' declaration in a
1233 header file that callers include, except for `_initialize_*' functions,
1234 which must be external so that `init.c' construction works, but
1235 shouldn't be visible to random source files.
1237 All static functions must be declared in a block near the top of the
1243 In addition to getting the syntax right, there's the little question
1244 of semantics. Some things are done in certain ways in GDB because long
1245 experience has shown that the more obvious ways caused various kinds of
1248 You can't assume the byte order of anything that comes from a target
1249 (including VALUEs, object files, and instructions). Such things must
1250 be byte-swapped using `SWAP_TARGET_AND_HOST' in GDB, or one of the swap
1251 routines defined in `bfd.h', such as `bfd_get_32'.
1253 You can't assume that you know what interface is being used to talk
1254 to the target system. All references to the target must go through the
1255 current `target_ops' vector.
1257 You can't assume that the host and target machines are the same
1258 machine (except in the "native" support modules). In particular, you
1259 can't assume that the target machine's header files will be available
1260 on the host machine. Target code must bring along its own header files
1261 - written from scratch or explicitly donated by their owner, to avoid
1264 Insertion of new `#ifdef''s will be frowned upon. It's much better
1265 to write the code portably than to conditionalize it for various
1268 New `#ifdef''s which test for specific compilers or manufacturers or
1269 operating systems are unacceptable. All `#ifdef''s should test for
1270 features. The information about which configurations contain which
1271 features should be segregated into the configuration files. Experience
1272 has proven far too often that a feature unique to one particular system
1273 often creeps into other systems; and that a conditional based on some
1274 predefined macro for your current system will become worthless over
1275 time, as new versions of your system come out that behave differently
1276 with regard to this feature.
1278 Adding code that handles specific architectures, operating systems,
1279 target interfaces, or hosts, is not acceptable in generic code. If a
1280 hook is needed at that point, invent a generic hook and define it for
1281 your configuration, with something like:
1283 #ifdef WRANGLE_SIGNALS
1284 WRANGLE_SIGNALS (signo);
1287 In your host, target, or native configuration file, as appropriate,
1288 define `WRANGLE_SIGNALS' to do the machine-dependent thing. Take a bit
1289 of care in defining the hook, so that it can be used by other ports in
1290 the future, if they need a hook in the same place.
1292 If the hook is not defined, the code should do whatever "most"
1293 machines want. Using `#ifdef', as above, is the preferred way to do
1294 this, but sometimes that gets convoluted, in which case use
1296 #ifndef SPECIAL_FOO_HANDLING
1297 #define SPECIAL_FOO_HANDLING(pc, sp) (0)
1300 where the macro is used or in an appropriate header file.
1302 Whether to include a "small" hook, a hook around the exact pieces of
1303 code which are system-dependent, or whether to replace a whole function
1304 with a hook depends on the case. A good example of this dilemma can be
1305 found in `get_saved_register'. All machines that GDB 2.8 ran on just
1306 needed the `FRAME_FIND_SAVED_REGS' hook to find the saved registers.
1307 Then the SPARC and Pyramid came along, and `HAVE_REGISTER_WINDOWS' and
1308 `REGISTER_IN_WINDOW_P' were introduced. Then the 29k and 88k required
1309 the `GET_SAVED_REGISTER' hook. The first three are examples of small
1310 hooks; the latter replaces a whole function. In this specific case, it
1311 is useful to have both kinds; it would be a bad idea to replace all the
1312 uses of the small hooks with `GET_SAVED_REGISTER', since that would
1313 result in much duplicated code. Other times, duplicating a few lines
1314 of code here or there is much cleaner than introducing a large number
1317 Another way to generalize GDB along a particular interface is with an
1318 attribute struct. For example, GDB has been generalized to handle
1319 multiple kinds of remote interfaces - not by #ifdef's everywhere, but
1320 by defining the "target_ops" structure and having a current target (as
1321 well as a stack of targets below it, for memory references). Whenever
1322 something needs to be done that depends on which remote interface we are
1323 using, a flag in the current target_ops structure is tested (e.g.
1324 `target_has_stack'), or a function is called through a pointer in the
1325 current target_ops structure. In this way, when a new remote interface
1326 is added, only one module needs to be touched - the one that actually
1327 implements the new remote interface. Other examples of
1328 attribute-structs are BFD access to multiple kinds of object file
1329 formats, or GDB's access to multiple source languages.
1331 Please avoid duplicating code. For example, in GDB 3.x all the code
1332 interfacing between `ptrace' and the rest of GDB was duplicated in
1333 `*-dep.c', and so changing something was very painful. In GDB 4.x,
1334 these have all been consolidated into `infptrace.c'. `infptrace.c' can
1335 deal with variations between systems the same way any
1336 system-independent file would (hooks, #if defined, etc.), and machines
1337 which are radically different don't need to use infptrace.c at all.
OSDN Git Service
