diff options
author | Stan Shebs <shebs@codesourcery.com> | 1999-04-16 01:34:49 +0000 |
---|---|---|
committer | Stan Shebs <shebs@codesourcery.com> | 1999-04-16 01:34:49 +0000 |
commit | 9733ab3f56072534b447188f48d3d5bc9911189e (patch) | |
tree | 26640d911c16263ab87ed1f12b60700a2cd390c2 /gdb/doc/gdbint.info-2 | |
parent | 071ea11e85eb9d529cc5eb3d35f6247466a21b99 (diff) | |
download | gdb-9733ab3f56072534b447188f48d3d5bc9911189e.zip gdb-9733ab3f56072534b447188f48d3d5bc9911189e.tar.gz gdb-9733ab3f56072534b447188f48d3d5bc9911189e.tar.bz2 |
Initial creation of sourceware repository
Diffstat (limited to 'gdb/doc/gdbint.info-2')
-rw-r--r-- | gdb/doc/gdbint.info-2 | 1338 |
1 files changed, 1338 insertions, 0 deletions
diff --git a/gdb/doc/gdbint.info-2 b/gdb/doc/gdbint.info-2 new file mode 100644 index 0000000..612cf0f --- /dev/null +++ b/gdb/doc/gdbint.info-2 @@ -0,0 +1,1338 @@ +This is Info file gdbint.info, produced by Makeinfo version 1.68 from +the input file ./gdbint.texinfo. + +START-INFO-DIR-ENTRY +* Gdb-Internals: (gdbint). The GNU debugger's internals. +END-INFO-DIR-ENTRY + + This file documents the internals of the GNU debugger GDB. + + Copyright 1990-1999 Free Software Foundation, Inc. Contributed by +Cygnus Solutions. Written by John Gilmore. Second Edition by Stan +Shebs. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy or distribute modified versions of this +manual under the terms of the GPL (for which purpose this text may be +regarded as a program in the language TeX). + + +File: gdbint.info, Node: Target Architecture Definition, Next: Target Vector Definition, Prev: Host Definition, Up: Top + +Target Architecture Definition +****************************** + + GDB's target architecture defines what sort of machine-language +programs GDB can work with, and how it works with them. + + At present, the target architecture definition consists of a number +of C macros. + +Registers and Memory +==================== + + GDB's model of the target machine is rather simple. GDB assumes the +machine includes a bank of registers and a block of memory. Each +register may have a different size. + + GDB does not have a magical way to match up with the compiler's idea +of which registers are which; however, it is critical that they do +match up accurately. The only way to make this work is to get accurate +information about the order that the compiler uses, and to reflect that +in the `REGISTER_NAME' and related macros. + + GDB can handle big-endian, little-endian, and bi-endian +architectures. + +Frame Interpretation +==================== + +Inferior Call Setup +=================== + +Compiler Characteristics +======================== + +Target Conditionals +=================== + + This section describes the macros that you can use to define the +target machine. + +`ADDITIONAL_OPTIONS' + +`ADDITIONAL_OPTION_CASES' + +`ADDITIONAL_OPTION_HANDLER' + +`ADDITIONAL_OPTION_HELP' + These are a set of macros that allow the addition of additional + command line options to GDB. They are currently used only for the + unsupported i960 Nindy target, and should not be used in any other + configuration. + +`ADDR_BITS_REMOVE (addr)' + If a raw machine address includes any bits that are not really + part of the address, then define this macro to expand into an + expression that zeros those bits in ADDR. For example, the two + low-order bits of a Motorola 88K address may be used by some + kernels for their own purposes, since addresses must always be + 4-byte aligned, and so are of no use for addressing. Those bits + should be filtered out with an expression such as `((addr) & ~3)'. + +`BEFORE_MAIN_LOOP_HOOK' + Define this to expand into any code that you want to execute + before the main loop starts. Although this is not, strictly + speaking, a target conditional, that is how it is currently being + used. Note that if a configuration were to define it one way for + a host and a different way for the target, GDB will probably not + compile, let alone run correctly. This is currently used only for + the unsupported i960 Nindy target, and should not be used in any + other configuration. + +`BELIEVE_PCC_PROMOTION' + Define if the compiler promotes a short or char parameter to an + int, but still reports the parameter as its original type, rather + than the promoted type. + +`BELIEVE_PCC_PROMOTION_TYPE' + Define this if GDB should believe the type of a short argument when + compiled by pcc, but look within a full int space to get its value. + Only defined for Sun-3 at present. + +`BITS_BIG_ENDIAN' + Define this if the numbering of bits in the targets does *not* + match the endianness of the target byte order. A value of 1 means + that the bits are numbered in a big-endian order, 0 means + little-endian. + +`BREAKPOINT' + This is the character array initializer for the bit pattern to put + into memory where a breakpoint is set. Although it's common to + use a trap instruction for a breakpoint, it's not required; for + instance, the bit pattern could be an invalid instruction. The + breakpoint must be no longer than the shortest instruction of the + architecture. + +`BIG_BREAKPOINT' + +`LITTLE_BREAKPOINT' + Similar to BREAKPOINT, but used for bi-endian targets. + +`REMOTE_BREAKPOINT' + +`LITTLE_REMOTE_BREAKPOINT' + +`BIG_REMOTE_BREAKPOINT' + Similar to BREAKPOINT, but used for remote targets. + +`BREAKPOINT_FROM_PC (pcptr, lenptr)' + Use the program counter to determine the contents and size of a + breakpoint instruction. It returns a pointer to a string of bytes + that encode a breakpoint instruction, stores the length of the + string to *lenptr, and adjusts pc (if necessary) to point to the + actual memory location where the breakpoint should be inserted. + + Although it is common to use a trap instruction for a breakpoint, + it's not required; for instance, the bit pattern could be an + invalid instruction. The breakpoint must be no longer than the + shortest instruction of the architecture. + + Replaces all the other BREAKPOINTs. + +`CALL_DUMMY' + valops.c + +`CALL_DUMMY_LOCATION' + inferior.h + +`CALL_DUMMY_STACK_ADJUST' + valops.c + +`CANNOT_FETCH_REGISTER (regno)' + A C expression that should be nonzero if REGNO cannot be fetched + from an inferior process. This is only relevant if + `FETCH_INFERIOR_REGISTERS' is not defined. + +`CANNOT_STORE_REGISTER (regno)' + A C expression that should be nonzero if REGNO should not be + written to the target. This is often the case for program + counters, status words, and other special registers. If this is + not defined, GDB will assume that all registers may be written. + +`DO_DEFERRED_STORES' + +`CLEAR_DEFERRED_STORES' + Define this to execute any deferred stores of registers into the + inferior, and to cancel any deferred stores. + + Currently only implemented correctly for native Sparc + configurations? + +`CPLUS_MARKER' + Define this to expand into the character that G++ uses to + distinguish compiler-generated identifiers from + programmer-specified identifiers. By default, this expands into + `'$''. Most System V targets should define this to `'.''. + +`DBX_PARM_SYMBOL_CLASS' + Hook for the `SYMBOL_CLASS' of a parameter when decoding DBX symbol + information. In the i960, parameters can be stored as locals or as + args, depending on the type of the debug record. + +`DECR_PC_AFTER_BREAK' + Define this to be the amount by which to decrement the PC after the + program encounters a breakpoint. This is often the number of + bytes in BREAKPOINT, though not always. For most targets this + value will be 0. + +`DECR_PC_AFTER_HW_BREAK' + Similarly, for hardware breakpoints. + +`DISABLE_UNSETTABLE_BREAK addr' + If defined, this should evaluate to 1 if ADDR is in a shared + library in which breakpoints cannot be set and so should be + disabled. + +`DO_REGISTERS_INFO' + If defined, use this to print the value of a register or all + registers. + +`END_OF_TEXT_DEFAULT' + This is an expression that should designate the end of the text + section (? FIXME ?) + +`EXTRACT_RETURN_VALUE(type,regbuf,valbuf)' + Define this to extract a function's return value of type TYPE from + the raw register state REGBUF and copy that, in virtual format, + into VALBUF. + +`EXTRACT_STRUCT_VALUE_ADDRESS(regbuf)' + Define this to extract from an array REGBUF containing the (raw) + register state, the address in which a function should return its + structure value, as a CORE_ADDR (or an expression that can be used + as one). + +`FLOAT_INFO' + If defined, then the `info float' command will print information + about the processor's floating point unit. + +`FP_REGNUM' + The number of the frame pointer register. + +`FRAMELESS_FUNCTION_INVOCATION(fi, frameless)' + Define this to set the variable FRAMELESS to 1 if the function + invocation represented by FI does not have a stack frame + associated with it. Otherwise set it to 0. + +`FRAME_ARGS_ADDRESS_CORRECT' + stack.c + +`FRAME_CHAIN(frame)' + Given FRAME, return a pointer to the calling frame. + +`FRAME_CHAIN_COMBINE(chain,frame)' + Define this to take the frame chain pointer and the frame's nominal + address and produce the nominal address of the caller's frame. + Presently only defined for HP PA. + +`FRAME_CHAIN_VALID(chain,thisframe)' + Define this to be an expression that returns zero if the given + frame is an outermost frame, with no caller, and nonzero + otherwise. Three common definitions are available. + `default_frame_chain_valid' (the default) is nonzero if the chain + pointer is nonzero and given frame's PC is not inside the startup + file (such as `crt0.o'). `alternate_frame_chain_valid' is nonzero + if the chain pointer is nonzero and the given frame's PC is not in + `main()' or a known entry point function (such as `_start()'). + +`FRAME_INIT_SAVED_REGS(frame)' + See `frame.h'. Determines the address of all registers in the + current stack frame storing each in `frame->saved_regs'. Space for + `frame->saved_regs' shall be allocated by `FRAME_INIT_SAVED_REGS' + using either `frame_saved_regs_zalloc' or `frame_obstack_alloc'. + + FRAME_FIND_SAVED_REGS and EXTRA_FRAME_INFO are deprecated. + +`FRAME_NUM_ARGS (val, fi)' + For the frame described by FI, set VAL to the number of arguments + that are being passed. + +`FRAME_SAVED_PC(frame)' + Given FRAME, return the pc saved there. That is, the return + address. + +`FUNCTION_EPILOGUE_SIZE' + For some COFF targets, the `x_sym.x_misc.x_fsize' field of the + function end symbol is 0. For such targets, you must define + `FUNCTION_EPILOGUE_SIZE' to expand into the standard size of a + function's epilogue. + +`GCC_COMPILED_FLAG_SYMBOL' + +`GCC2_COMPILED_FLAG_SYMBOL' + If defined, these are the names of the symbols that GDB will look + for to detect that GCC compiled the file. The default symbols are + `gcc_compiled.' and `gcc2_compiled.', respectively. (Currently + only defined for the Delta 68.) + +`GDB_TARGET_IS_HPPA' + This determines whether horrible kludge code in dbxread.c and + partial-stab.h is used to mangle multiple-symbol-table files from + HPPA's. This should all be ripped out, and a scheme like elfread.c + used. + +`GDB_TARGET_IS_MACH386' + +`GDB_TARGET_IS_SUN3' + +`GDB_TARGET_IS_SUN386' + Kludges that should go away. + +`GET_LONGJMP_TARGET' + For most machines, this is a target-dependent parameter. On the + DECstation and the Iris, this is a native-dependent parameter, + since <setjmp.h> is needed to define it. + + This macro determines the target PC address that longjmp() will + jump to, assuming that we have just stopped at a longjmp + breakpoint. It takes a CORE_ADDR * as argument, and stores the + target PC value through this pointer. It examines the current + state of the machine as needed. + +`GET_SAVED_REGISTER' + Define this if you need to supply your own definition for the + function `get_saved_register'. Currently this is only done for + the a29k. + +`HAVE_REGISTER_WINDOWS' + Define this if the target has register windows. + +`REGISTER_IN_WINDOW_P (regnum)' + Define this to be an expression that is 1 if the given register is + in the window. + +`IBM6000_TARGET' + Shows that we are configured for an IBM RS/6000 target. This + conditional should be eliminated (FIXME) and replaced by + feature-specific macros. It was introduced in haste and we are + repenting at leisure. + +`IEEE_FLOAT' + Define this if the target system uses IEEE-format floating point + numbers. + +`INIT_EXTRA_FRAME_INFO (fromleaf, frame)' + If additional information about the frame is required this should + be stored in `frame->extra_info'. Space for `frame->extra_info' + is allocated using `frame_obstack_alloc'. + +`INIT_FRAME_PC (fromleaf, prev)' + This is a C statement that sets the pc of the frame pointed to by + PREV. [By default...] + +`INNER_THAN (lhs,rhs)' + Returns non-zero if stack address LHS is inner than (nearer to the + stack top) stack address RHS. Define this as `lhs < rhs' if the + target's stack grows downward in memory, or `lhs > rsh' if the + stack grows upward. + +`IN_SIGTRAMP (pc, name)' + Define this to return true if the given PC and/or NAME indicates + that the current function is a sigtramp. + +`SIGTRAMP_START (pc)' + +`SIGTRAMP_END (pc)' + Define these to be the start and end address of the sigtramp for + the given PC. On machines where the address is just a compile time + constant, the macro expansion will typically just ignore the + supplied PC. + +`IN_SOLIB_CALL_TRAMPOLINE pc name' + Define this to evaluate to nonzero if the program is stopped in the + trampoline that connects to a shared library. + +`IN_SOLIB_RETURN_TRAMPOLINE pc name' + Define this to evaluate to nonzero if the program is stopped in the + trampoline that returns from a shared library. + +`IS_TRAPPED_INTERNALVAR (name)' + This is an ugly hook to allow the specification of special actions + that should occur as a side-effect of setting the value of a + variable internal to GDB. Currently only used by the h8500. Note + that this could be either a host or target conditional. + +`NEED_TEXT_START_END' + Define this if GDB should determine the start and end addresses of + the text section. (Seems dubious.) + +`NO_HIF_SUPPORT' + (Specific to the a29k.) + +`SOFTWARE_SINGLE_STEP_P' + Define this as 1 if the target does not have a hardware single-step + mechanism. The macro `SOFTWARE_SINGLE_STEP' must also be defined. + +`SOFTWARE_SINGLE_STEP(signal,insert_breapoints_p)' + A function that inserts or removes (dependant on + INSERT_BREAPOINTS_P) breakpoints at each possible destinations of + the next instruction. See `sparc-tdep.c' and `rs6000-tdep.c' for + examples. + +`PCC_SOL_BROKEN' + (Used only in the Convex target.) + +`PC_IN_CALL_DUMMY' + inferior.h + +`PC_LOAD_SEGMENT' + If defined, print information about the load segment for the + program counter. (Defined only for the RS/6000.) + +`PC_REGNUM' + If the program counter is kept in a register, then define this + macro to be the number of that register. This need be defined + only if `TARGET_WRITE_PC' is not defined. + +`NPC_REGNUM' + The number of the "next program counter" register, if defined. + +`NNPC_REGNUM' + The number of the "next next program counter" register, if defined. + Currently, this is only defined for the Motorola 88K. + +`PRINT_REGISTER_HOOK (regno)' + If defined, this must be a function that prints the contents of the + given register to standard output. + +`PRINT_TYPELESS_INTEGER' + This is an obscure substitute for `print_longest' that seems to + have been defined for the Convex target. + +`PROCESS_LINENUMBER_HOOK' + A hook defined for XCOFF reading. + +`PROLOGUE_FIRSTLINE_OVERLAP' + (Only used in unsupported Convex configuration.) + +`PS_REGNUM' + If defined, this is the number of the processor status register. + (This definition is only used in generic code when parsing "$ps".) + +`POP_FRAME' + Used in `call_function_by_hand' to remove an artificial stack + frame. + +`PUSH_ARGUMENTS (nargs, args, sp, struct_return, struct_addr)' + Define this to push arguments onto the stack for inferior function + call. + +`PUSH_DUMMY_FRAME' + Used in `call_function_by_hand' to create an artificial stack + frame. + +`REGISTER_BYTES' + The total amount of space needed to store GDB's copy of the + machine's register state. + +`REGISTER_NAME(i)' + Return the name of register I as a string. May return NULL or NUL + to indicate that register I is not valid. + +`REG_STRUCT_HAS_ADDR (gcc_p, type)' + Define this to return 1 if the given type will be passed by pointer + rather than directly. + +`SDB_REG_TO_REGNUM' + Define this to convert sdb register numbers into GDB regnums. If + not defined, no conversion will be done. + +`SHIFT_INST_REGS' + (Only used for m88k targets.) + +`SKIP_PROLOGUE (pc)' + A C statement that advances the PC across any function entry + prologue instructions so as to reach "real" code. + +`SKIP_PROLOGUE_FRAMELESS_P' + A C statement that should behave similarly, but that can stop as + soon as the function is known to have a frame. If not defined, + `SKIP_PROLOGUE' will be used instead. + +`SKIP_TRAMPOLINE_CODE (pc)' + If the target machine has trampoline code that sits between + callers and the functions being called, then define this macro to + return a new PC that is at the start of the real function. + +`SP_REGNUM' + Define this to be the number of the register that serves as the + stack pointer. + +`STAB_REG_TO_REGNUM' + Define this to convert stab register numbers (as gotten from `r' + declarations) into GDB regnums. If not defined, no conversion + will be done. + +`STACK_ALIGN (addr)' + Define this to adjust the address to the alignment required for the + processor's stack. + +`STEP_SKIPS_DELAY (addr)' + Define this to return true if the address is of an instruction + with a delay slot. If a breakpoint has been placed in the + instruction's delay slot, GDB will single-step over that + instruction before resuming normally. Currently only defined for + the Mips. + +`STORE_RETURN_VALUE (type, valbuf)' + A C expression that stores a function return value of type TYPE, + where VALBUF is the address of the value to be stored. + +`SUN_FIXED_LBRAC_BUG' + (Used only for Sun-3 and Sun-4 targets.) + +`SYMBOL_RELOADING_DEFAULT' + The default value of the `symbol-reloading' variable. (Never + defined in current sources.) + +`TARGET_BYTE_ORDER_DEFAULT' + The ordering of bytes in the target. This must be either + `BIG_ENDIAN' or `LITTLE_ENDIAN'. This macro replaces + TARGET_BYTE_ORDER which is deprecated. + +`TARGET_BYTE_ORDER_SELECTABLE_P' + Non-zero if the target has both `BIG_ENDIAN' and `LITTLE_ENDIAN' + variants. This macro replaces TARGET_BYTE_ORDER_SELECTABLE which + is deprecated. + +`TARGET_CHAR_BIT' + Number of bits in a char; defaults to 8. + +`TARGET_COMPLEX_BIT' + Number of bits in a complex number; defaults to `2 * + TARGET_FLOAT_BIT'. + +`TARGET_DOUBLE_BIT' + Number of bits in a double float; defaults to `8 * + TARGET_CHAR_BIT'. + +`TARGET_DOUBLE_COMPLEX_BIT' + Number of bits in a double complex; defaults to `2 * + TARGET_DOUBLE_BIT'. + +`TARGET_FLOAT_BIT' + Number of bits in a float; defaults to `4 * TARGET_CHAR_BIT'. + +`TARGET_INT_BIT' + Number of bits in an integer; defaults to `4 * TARGET_CHAR_BIT'. + +`TARGET_LONG_BIT' + Number of bits in a long integer; defaults to `4 * + TARGET_CHAR_BIT'. + +`TARGET_LONG_DOUBLE_BIT' + Number of bits in a long double float; defaults to `2 * + TARGET_DOUBLE_BIT'. + +`TARGET_LONG_LONG_BIT' + Number of bits in a long long integer; defaults to `2 * + TARGET_LONG_BIT'. + +`TARGET_PTR_BIT' + Number of bits in a pointer; defaults to `TARGET_INT_BIT'. + +`TARGET_SHORT_BIT' + Number of bits in a short integer; defaults to `2 * + TARGET_CHAR_BIT'. + +`TARGET_READ_PC' + +`TARGET_WRITE_PC (val, pid)' + +`TARGET_READ_SP' + +`TARGET_WRITE_SP' + +`TARGET_READ_FP' + +`TARGET_WRITE_FP' + These change the behavior of `read_pc', `write_pc', `read_sp', + `write_sp', `read_fp' and `write_fp'. For most targets, these may + be left undefined. GDB will call the read and write register + functions with the relevant `_REGNUM' argument. + + These macros are useful when a target keeps one of these registers + in a hard to get at place; for example, part in a segment register + and part in an ordinary register. + +`TARGET_VIRTUAL_FRAME_POINTER(pc,regp,offsetp)' + Returns a `(register, offset)' pair representing the virtual frame + pointer in use at the code address `"pc"'. If virtual frame + pointers are not used, a default definition simply returns + `FP_REGNUM', with an offset of zero. + +`USE_STRUCT_CONVENTION (gcc_p, type)' + If defined, this must be an expression that is nonzero if a value + of the given TYPE being returned from a function must have space + allocated for it on the stack. GCC_P is true if the function + being considered is known to have been compiled by GCC; this is + helpful for systems where GCC is known to use different calling + convention than other compilers. + +`VARIABLES_INSIDE_BLOCK (desc, gcc_p)' + For dbx-style debugging information, if the compiler puts variable + declarations inside LBRAC/RBRAC blocks, this should be defined to + be nonzero. DESC is the value of `n_desc' from the `N_RBRAC' + symbol, and GCC_P is true if GDB has noticed the presence of + either the `GCC_COMPILED_SYMBOL' or the `GCC2_COMPILED_SYMBOL'. + By default, this is 0. + +`OS9K_VARIABLES_INSIDE_BLOCK (desc, gcc_p)' + Similarly, for OS/9000. Defaults to 1. + + Motorola M68K target conditionals. + +`BPT_VECTOR' + Define this to be the 4-bit location of the breakpoint trap + vector. If not defined, it will default to `0xf'. + +`REMOTE_BPT_VECTOR' + Defaults to `1'. + +Adding a New Target +=================== + + The following files define a target to GDB: + +`gdb/config/ARCH/TTT.mt' + Contains a Makefile fragment specific to this target. Specifies + what object files are needed for target TTT, by defining + `TDEPFILES=...'. Also specifies the header file which describes + TTT, by defining `TM_FILE= tm-TTT.h'. You can also define + `TM_CFLAGS', `TM_CLIBS', `TM_CDEPS', but these are now deprecated + and may go away in future versions of GDB. + +`gdb/config/ARCH/tm-TTT.h' + (`tm.h' is a link to this file, created by configure). Contains + macro definitions about the target machine's registers, stack frame + format and instructions. + +`gdb/TTT-tdep.c' + Contains any miscellaneous code required for this target machine. + On some machines it doesn't exist at all. Sometimes the macros in + `tm-TTT.h' become very complicated, so they are implemented as + functions here instead, and the macro is simply defined to call the + function. This is vastly preferable, since it is easier to + understand and debug. + +`gdb/config/ARCH/tm-ARCH.h' + This often exists to describe the basic layout of the target + machine's processor chip (registers, stack, etc). If used, it is + included by `tm-TTT.h'. It can be shared among many targets that + use the same processor. + +`gdb/ARCH-tdep.c' + Similarly, there are often common subroutines that are shared by + all target machines that use this particular architecture. + + If you are adding a new operating system for an existing CPU chip, +add a `config/tm-OS.h' file that describes the operating system +facilities that are unusual (extra symbol table info; the breakpoint +instruction needed; etc). Then write a `ARCH/tm-OS.h' that just +`#include's `tm-ARCH.h' and `config/tm-OS.h'. + + +File: gdbint.info, Node: Target Vector Definition, Next: Native Debugging, Prev: Target Architecture Definition, Up: Top + +Target Vector Definition +************************ + + The target vector defines the interface between GDB's abstract +handling of target systems, and the nitty-gritty code that actually +exercises control over a process or a serial port. GDB includes some +30-40 different target vectors; however, each configuration of GDB +includes only a few of them. + +File Targets +============ + + Both executables and core files have target vectors. + +Standard Protocol and Remote Stubs +================================== + + GDB's file `remote.c' talks a serial protocol to code that runs in +the target system. GDB provides several sample "stubs" that can be +integrated into target programs or operating systems for this purpose; +they are named `*-stub.c'. + + The GDB user's manual describes how to put such a stub into your +target code. What follows is a discussion of integrating the SPARC +stub into a complicated operating system (rather than a simple +program), by Stu Grossman, the author of this stub. + + The trap handling code in the stub assumes the following upon entry +to trap_low: + + 1. %l1 and %l2 contain pc and npc respectively at the time of the trap + + 2. traps are disabled + + 3. you are in the correct trap window + + + As long as your trap handler can guarantee those conditions, then +there is no reason why you shouldn't be able to `share' traps with the +stub. The stub has no requirement that it be jumped to directly from +the hardware trap vector. That is why it calls `exceptionHandler()', +which is provided by the external environment. For instance, this could +setup the hardware traps to actually execute code which calls the stub +first, and then transfers to its own trap handler. + + For the most point, there probably won't be much of an issue with +`sharing' traps, as the traps we use are usually not used by the kernel, +and often indicate unrecoverable error conditions. Anyway, this is all +controlled by a table, and is trivial to modify. The most important +trap for us is for `ta 1'. Without that, we can't single step or do +breakpoints. Everything else is unnecessary for the proper operation +of the debugger/stub. + + From reading the stub, it's probably not obvious how breakpoints +work. They are simply done by deposit/examine operations from GDB. + +ROM Monitor Interface +===================== + +Custom Protocols +================ + +Transport Layer +=============== + +Builtin Simulator +================= + + +File: gdbint.info, Node: Native Debugging, Next: Support Libraries, Prev: Target Vector Definition, Up: Top + +Native Debugging +**************** + + Several files control GDB's configuration for native support: + +`gdb/config/ARCH/XYZ.mh' + Specifies Makefile fragments needed when hosting *or native* on + machine XYZ. In particular, this lists the required + native-dependent object files, by defining `NATDEPFILES=...'. + Also specifies the header file which describes native support on + XYZ, by defining `NAT_FILE= nm-XYZ.h'. You can also define + `NAT_CFLAGS', `NAT_ADD_FILES', `NAT_CLIBS', `NAT_CDEPS', etc.; see + `Makefile.in'. + +`gdb/config/ARCH/nm-XYZ.h' + (`nm.h' is a link to this file, created by configure). Contains C + macro definitions describing the native system environment, such as + child process control and core file support. + +`gdb/XYZ-nat.c' + Contains any miscellaneous C code required for this native support + of this machine. On some machines it doesn't exist at all. + + There are some "generic" versions of routines that can be used by +various systems. These can be customized in various ways by macros +defined in your `nm-XYZ.h' file. If these routines work for the XYZ +host, you can just include the generic file's name (with `.o', not +`.c') in `NATDEPFILES'. + + Otherwise, if your machine needs custom support routines, you will +need to write routines that perform the same functions as the generic +file. Put them into `XYZ-nat.c', and put `XYZ-nat.o' into +`NATDEPFILES'. + +`inftarg.c' + This contains the *target_ops vector* that supports Unix child + processes on systems which use ptrace and wait to control the + child. + +`procfs.c' + This contains the *target_ops vector* that supports Unix child + processes on systems which use /proc to control the child. + +`fork-child.c' + This does the low-level grunge that uses Unix system calls to do a + "fork and exec" to start up a child process. + +`infptrace.c' + This is the low level interface to inferior processes for systems + using the Unix `ptrace' call in a vanilla way. + +Native core file Support +======================== + +`core-aout.c::fetch_core_registers()' + Support for reading registers out of a core file. This routine + calls `register_addr()', see below. Now that BFD is used to read + core files, virtually all machines should use `core-aout.c', and + should just provide `fetch_core_registers' in `XYZ-nat.c' (or + `REGISTER_U_ADDR' in `nm-XYZ.h'). + +`core-aout.c::register_addr()' + If your `nm-XYZ.h' file defines the macro `REGISTER_U_ADDR(addr, + blockend, regno)', it should be defined to set `addr' to the + offset within the `user' struct of GDB register number `regno'. + `blockend' is the offset within the "upage" of `u.u_ar0'. If + `REGISTER_U_ADDR' is defined, `core-aout.c' will define the + `register_addr()' function and use the macro in it. If you do not + define `REGISTER_U_ADDR', but you are using the standard + `fetch_core_registers()', you will need to define your own version + of `register_addr()', put it into your `XYZ-nat.c' file, and be + sure `XYZ-nat.o' is in the `NATDEPFILES' list. If you have your + own `fetch_core_registers()', you may not need a separate + `register_addr()'. Many custom `fetch_core_registers()' + implementations simply locate the registers themselves. + + When making GDB run native on a new operating system, to make it +possible to debug core files, you will need to either write specific +code for parsing your OS's core files, or customize `bfd/trad-core.c'. +First, use whatever `#include' files your machine uses to define the +struct of registers that is accessible (possibly in the u-area) in a +core file (rather than `machine/reg.h'), and an include file that +defines whatever header exists on a core file (e.g. the u-area or a +`struct core'). Then modify `trad_unix_core_file_p()' to use these +values to set up the section information for the data segment, stack +segment, any other segments in the core file (perhaps shared library +contents or control information), "registers" segment, and if there are +two discontiguous sets of registers (e.g. integer and float), the +"reg2" segment. This section information basically delimits areas in +the core file in a standard way, which the section-reading routines in +BFD know how to seek around in. + + Then back in GDB, you need a matching routine called +`fetch_core_registers()'. If you can use the generic one, it's in +`core-aout.c'; if not, it's in your `XYZ-nat.c' file. It will be +passed a char pointer to the entire "registers" segment, its length, +and a zero; or a char pointer to the entire "regs2" segment, its +length, and a 2. The routine should suck out the supplied register +values and install them into GDB's "registers" array. + + If your system uses `/proc' to control processes, and uses ELF +format core files, then you may be able to use the same routines for +reading the registers out of processes and out of core files. + +ptrace +====== + +/proc +===== + +win32 +===== + +shared libraries +================ + +Native Conditionals +=================== + + When GDB is configured and compiled, various macros are defined or +left undefined, to control compilation when the host and target systems +are the same. These macros should be defined (or left undefined) in +`nm-SYSTEM.h'. + +`ATTACH_DETACH' + If defined, then GDB will include support for the `attach' and + `detach' commands. + +`CHILD_PREPARE_TO_STORE' + If the machine stores all registers at once in the child process, + then define this to ensure that all values are correct. This + usually entails a read from the child. + + [Note that this is incorrectly defined in `xm-SYSTEM.h' files + currently.] + +`FETCH_INFERIOR_REGISTERS' + Define this if the native-dependent code will provide its own + routines `fetch_inferior_registers' and `store_inferior_registers' + in `HOST-nat.c'. If this symbol is *not* defined, and + `infptrace.c' is included in this configuration, the default + routines in `infptrace.c' are used for these functions. + +`FILES_INFO_HOOK' + (Only defined for Convex.) + +`FP0_REGNUM' + This macro is normally defined to be the number of the first + floating point register, if the machine has such registers. As + such, it would appear only in target-specific code. However, + /proc support uses this to decide whether floats are in use on + this target. + +`GET_LONGJMP_TARGET' + For most machines, this is a target-dependent parameter. On the + DECstation and the Iris, this is a native-dependent parameter, + since <setjmp.h> is needed to define it. + + This macro determines the target PC address that longjmp() will + jump to, assuming that we have just stopped at a longjmp + breakpoint. It takes a CORE_ADDR * as argument, and stores the + target PC value through this pointer. It examines the current + state of the machine as needed. + +`KERNEL_U_ADDR' + Define this to the address of the `u' structure (the "user + struct", also known as the "u-page") in kernel virtual memory. GDB + needs to know this so that it can subtract this address from + absolute addresses in the upage, that are obtained via ptrace or + from core files. On systems that don't need this value, set it to + zero. + +`KERNEL_U_ADDR_BSD' + Define this to cause GDB to determine the address of `u' at + runtime, by using Berkeley-style `nlist' on the kernel's image in + the root directory. + +`KERNEL_U_ADDR_HPUX' + Define this to cause GDB to determine the address of `u' at + runtime, by using HP-style `nlist' on the kernel's image in the + root directory. + +`ONE_PROCESS_WRITETEXT' + Define this to be able to, when a breakpoint insertion fails, warn + the user that another process may be running with the same + executable. + +`PROC_NAME_FMT' + Defines the format for the name of a `/proc' device. Should be + defined in `nm.h' *only* in order to override the default + definition in `procfs.c'. + +`PTRACE_FP_BUG' + mach386-xdep.c + +`PTRACE_ARG3_TYPE' + The type of the third argument to the `ptrace' system call, if it + exists and is different from `int'. + +`REGISTER_U_ADDR' + Defines the offset of the registers in the "u area". + +`SHELL_COMMAND_CONCAT' + If defined, is a string to prefix on the shell command used to + start the inferior. + +`SHELL_FILE' + If defined, this is the name of the shell to use to run the + inferior. Defaults to `"/bin/sh"'. + +`SOLIB_ADD (filename, from_tty, targ)' + Define this to expand into an expression that will cause the + symbols in FILENAME to be added to GDB's symbol table. + +`SOLIB_CREATE_INFERIOR_HOOK' + Define this to expand into any shared-library-relocation code that + you want to be run just after the child process has been forked. + +`START_INFERIOR_TRAPS_EXPECTED' + When starting an inferior, GDB normally expects to trap twice; + once when the shell execs, and once when the program itself execs. + If the actual number of traps is something other than 2, then + define this macro to expand into the number expected. + +`SVR4_SHARED_LIBS' + Define this to indicate that SVR4-style shared libraries are in + use. + +`USE_PROC_FS' + This determines whether small routines in `*-tdep.c', which + translate register values between GDB's internal representation + and the /proc representation, are compiled. + +`U_REGS_OFFSET' + This is the offset of the registers in the upage. It need only be + defined if the generic ptrace register access routines in + `infptrace.c' are being used (that is, `infptrace.c' is configured + in, and `FETCH_INFERIOR_REGISTERS' is not defined). If the + default value from `infptrace.c' is good enough, leave it + undefined. + + The default value means that u.u_ar0 *points to* the location of + the registers. I'm guessing that `#define U_REGS_OFFSET 0' means + that u.u_ar0 *is* the location of the registers. + +`CLEAR_SOLIB' + objfiles.c + +`DEBUG_PTRACE' + Define this to debug ptrace calls. + + +File: gdbint.info, Node: Support Libraries, Next: Coding, Prev: Native Debugging, Up: Top + +Support Libraries +***************** + +BFD +=== + + BFD provides support for GDB in several ways: + +*identifying executable and core files* + BFD will identify a variety of file types, including a.out, coff, + and several variants thereof, as well as several kinds of core + files. + +*access to sections of files* + BFD parses the file headers to determine the names, virtual + addresses, sizes, and file locations of all the various named + sections in files (such as the text section or the data section). + GDB simply calls BFD to read or write section X at byte offset Y + for length Z. + +*specialized core file support* + BFD provides routines to determine the failing command name stored + in a core file, the signal with which the program failed, and + whether a core file matches (i.e. could be a core dump of) a + particular executable file. + +*locating the symbol information* + GDB uses an internal interface of BFD to determine where to find + the symbol information in an executable file or symbol-file. GDB + itself handles the reading of symbols, since BFD does not + "understand" debug symbols, but GDB uses BFD's cached information + to find the symbols, string table, etc. + +opcodes +======= + + The opcodes library provides GDB's disassembler. (It's a separate +library because it's also used in binutils, for `objdump'). + +readline +======== + +mmalloc +======= + +libiberty +========= + +gnu-regex +========= + + Regex conditionals. + +`C_ALLOCA' + +`NFAILURES' + +`RE_NREGS' + +`SIGN_EXTEND_CHAR' + +`SWITCH_ENUM_BUG' + +`SYNTAX_TABLE' + +`Sword' + +`sparc' +include +======= + + +File: gdbint.info, Node: Coding, Next: Porting GDB, Prev: Support Libraries, Up: Top + +Coding +****** + + This chapter covers topics that are lower-level than the major +algorithms of GDB. + +Cleanups +======== + + Cleanups are a structured way to deal with things that need to be +done later. When your code does something (like `malloc' some memory, +or open a file) that needs to be undone later (e.g. free the memory or +close the file), it can make a cleanup. The cleanup will be done at +some future point: when the command is finished, when an error occurs, +or when your code decides it's time to do cleanups. + + You can also discard cleanups, that is, throw them away without doing +what they say. This is only done if you ask that it be done. + + Syntax: + +`struct cleanup *OLD_CHAIN;' + Declare a variable which will hold a cleanup chain handle. + +`OLD_CHAIN = make_cleanup (FUNCTION, ARG);' + Make a cleanup which will cause FUNCTION to be called with ARG (a + `char *') later. The result, OLD_CHAIN, is a handle that can be + passed to `do_cleanups' or `discard_cleanups' later. Unless you + are going to call `do_cleanups' or `discard_cleanups' yourself, + you can ignore the result from `make_cleanup'. + +`do_cleanups (OLD_CHAIN);' + Perform all cleanups done since `make_cleanup' returned OLD_CHAIN. + E.g.: + make_cleanup (a, 0); + old = make_cleanup (b, 0); + do_cleanups (old); + + will call `b()' but will not call `a()'. The cleanup that calls + `a()' will remain in the cleanup chain, and will be done later + unless otherwise discarded. + +`discard_cleanups (OLD_CHAIN);' + Same as `do_cleanups' except that it just removes the cleanups from + the chain and does not call the specified functions. + + Some functions, e.g. `fputs_filtered()' or `error()', specify that +they "should not be called when cleanups are not in place". This means +that any actions you need to reverse in the case of an error or +interruption must be on the cleanup chain before you call these +functions, since they might never return to your code (they `longjmp' +instead). + +Wrapping Output Lines +===================== + + Output that goes through `printf_filtered' or `fputs_filtered' or +`fputs_demangled' needs only to have calls to `wrap_here' added in +places that would be good breaking points. The utility routines will +take care of actually wrapping if the line width is exceeded. + + The argument to `wrap_here' is an indentation string which is +printed *only* if the line breaks there. This argument is saved away +and used later. It must remain valid until the next call to +`wrap_here' or until a newline has been printed through the +`*_filtered' functions. Don't pass in a local variable and then return! + + It is usually best to call `wrap_here()' after printing a comma or +space. If you call it before printing a space, make sure that your +indentation properly accounts for the leading space that will print if +the line wraps there. + + Any function or set of functions that produce filtered output must +finish by printing a newline, to flush the wrap buffer, before switching +to unfiltered ("`printf'") output. Symbol reading routines that print +warnings are a good example. + +GDB Coding Standards +==================== + + GDB follows the GNU coding standards, as described in +`etc/standards.texi'. This file is also available for anonymous FTP +from GNU archive sites. GDB takes a strict interpretation of the +standard; in general, when the GNU standard recommends a practice but +does not require it, GDB requires it. + + GDB follows an additional set of coding standards specific to GDB, +as described in the following sections. + + You can configure with `--enable-build-warnings' to get GCC to check +on a number of these rules. GDB sources ought not to engender any +complaints, unless they are caused by bogus host systems. (The exact +set of enabled warnings is currently `-Wall -Wpointer-arith +-Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations'. + +Formatting +---------- + + The standard GNU recommendations for formatting must be followed +strictly. + + Note that while in a definition, the function's name must be in +column zero; in a function declaration, the name must be on the same +line as the return type. + + In addition, there must be a space between a function or macro name +and the opening parenthesis of its argument list (except for macro +definitions, as required by C). There must not be a space after an open +paren/bracket or before a close paren/bracket. + + While additional whitespace is generally helpful for reading, do not +use more than one blank line to separate blocks, and avoid adding +whitespace after the end of a program line (as of 1/99, some 600 lines +had whitespace after the semicolon). Excess whitespace causes +difficulties for diff and patch. + +Comments +-------- + + The standard GNU requirements on comments must be followed strictly. + + Block comments must appear in the following form, with no `/*'- or +'*/'-only lines, and no leading `*': + + /* Wait for control to return from inferior to debugger. If inferior + gets a signal, we may decide to start it up again instead of + returning. That is why there is a loop in this function. When + this function actually returns it means the inferior should be left + stopped and GDB should read more commands. */ + + (Note that this format is encouraged by Emacs; tabbing for a +multi-line comment works correctly, and M-Q fills the block +consistently.) + + Put a blank line between the block comments preceding function or +variable definitions, and the definition itself. + + In general, put function-body comments on lines by themselves, rather +than trying to fit them into the 20 characters left at the end of a +line, since either the comment or the code will inevitably get longer +than will fit, and then somebody will have to move it anyhow. + +C Usage +------- + + Code must not depend on the sizes of C data types, the format of the +host's floating point numbers, the alignment of anything, or the order +of evaluation of expressions. + + Use functions freely. There are only a handful of compute-bound +areas in GDB that might be affected by the overhead of a function call, +mainly in symbol reading. Most of GDB's performance is limited by the +target interface (whether serial line or system call). + + However, use functions with moderation. A thousand one-line +functions are just as hard to understand as a single thousand-line +function. + +Function Prototypes +------------------- + + Prototypes must be used to *declare* functions but never to *define* +them. Prototypes for GDB functions must include both the argument type +and name, with the name matching that used in the actual function +definition. + + For the sake of compatibility with pre-ANSI compilers, define +prototypes with the `PARAMS' macro: + + extern int memory_remove_breakpoint PARAMS ((CORE_ADDR addr, + char *contents_cache)); + + Note the double parentheses around the parameter types. This allows +an arbitrary number of parameters to be described, without freaking out +the C preprocessor. When the function has no parameters, it should be +described like: + + extern void noprocess PARAMS ((void)); + + The `PARAMS' macro expands to its argument in ANSI C, or to a simple +`()' in traditional C. + + All external functions should have a `PARAMS' declaration in a +header file that callers include, except for `_initialize_*' functions, +which must be external so that `init.c' construction works, but +shouldn't be visible to random source files. + + All static functions must be declared in a block near the top of the +source file. + +Clean Design +------------ + + In addition to getting the syntax right, there's the little question +of semantics. Some things are done in certain ways in GDB because long +experience has shown that the more obvious ways caused various kinds of +trouble. + + You can't assume the byte order of anything that comes from a target +(including VALUEs, object files, and instructions). Such things must +be byte-swapped using `SWAP_TARGET_AND_HOST' in GDB, or one of the swap +routines defined in `bfd.h', such as `bfd_get_32'. + + You can't assume that you know what interface is being used to talk +to the target system. All references to the target must go through the +current `target_ops' vector. + + You can't assume that the host and target machines are the same +machine (except in the "native" support modules). In particular, you +can't assume that the target machine's header files will be available +on the host machine. Target code must bring along its own header files +- written from scratch or explicitly donated by their owner, to avoid +copyright problems. + + Insertion of new `#ifdef''s will be frowned upon. It's much better +to write the code portably than to conditionalize it for various +systems. + + New `#ifdef''s which test for specific compilers or manufacturers or +operating systems are unacceptable. All `#ifdef''s should test for +features. The information about which configurations contain which +features should be segregated into the configuration files. Experience +has proven far too often that a feature unique to one particular system +often creeps into other systems; and that a conditional based on some +predefined macro for your current system will become worthless over +time, as new versions of your system come out that behave differently +with regard to this feature. + + Adding code that handles specific architectures, operating systems, +target interfaces, or hosts, is not acceptable in generic code. If a +hook is needed at that point, invent a generic hook and define it for +your configuration, with something like: + + #ifdef WRANGLE_SIGNALS + WRANGLE_SIGNALS (signo); + #endif + + In your host, target, or native configuration file, as appropriate, +define `WRANGLE_SIGNALS' to do the machine-dependent thing. Take a bit +of care in defining the hook, so that it can be used by other ports in +the future, if they need a hook in the same place. + + If the hook is not defined, the code should do whatever "most" +machines want. Using `#ifdef', as above, is the preferred way to do +this, but sometimes that gets convoluted, in which case use + + #ifndef SPECIAL_FOO_HANDLING + #define SPECIAL_FOO_HANDLING(pc, sp) (0) + #endif + + where the macro is used or in an appropriate header file. + + Whether to include a "small" hook, a hook around the exact pieces of +code which are system-dependent, or whether to replace a whole function +with a hook depends on the case. A good example of this dilemma can be +found in `get_saved_register'. All machines that GDB 2.8 ran on just +needed the `FRAME_FIND_SAVED_REGS' hook to find the saved registers. +Then the SPARC and Pyramid came along, and `HAVE_REGISTER_WINDOWS' and +`REGISTER_IN_WINDOW_P' were introduced. Then the 29k and 88k required +the `GET_SAVED_REGISTER' hook. The first three are examples of small +hooks; the latter replaces a whole function. In this specific case, it +is useful to have both kinds; it would be a bad idea to replace all the +uses of the small hooks with `GET_SAVED_REGISTER', since that would +result in much duplicated code. Other times, duplicating a few lines +of code here or there is much cleaner than introducing a large number +of small hooks. + + Another way to generalize GDB along a particular interface is with an +attribute struct. For example, GDB has been generalized to handle +multiple kinds of remote interfaces - not by #ifdef's everywhere, but +by defining the "target_ops" structure and having a current target (as +well as a stack of targets below it, for memory references). Whenever +something needs to be done that depends on which remote interface we are +using, a flag in the current target_ops structure is tested (e.g. +`target_has_stack'), or a function is called through a pointer in the +current target_ops structure. In this way, when a new remote interface +is added, only one module needs to be touched - the one that actually +implements the new remote interface. Other examples of +attribute-structs are BFD access to multiple kinds of object file +formats, or GDB's access to multiple source languages. + + Please avoid duplicating code. For example, in GDB 3.x all the code +interfacing between `ptrace' and the rest of GDB was duplicated in +`*-dep.c', and so changing something was very painful. In GDB 4.x, +these have all been consolidated into `infptrace.c'. `infptrace.c' can +deal with variations between systems the same way any +system-independent file would (hooks, #if defined, etc.), and machines +which are radically different don't need to use infptrace.c at all. + |