| \input texinfo |
| @setfilename gdbint.info |
| @include gdb-cfg.texi |
| @ifinfo |
| @format |
| START-INFO-DIR-ENTRY |
| * Gdb-Internals: (gdbint). The GNU debugger's internals. |
| END-INFO-DIR-ENTRY |
| @end format |
| @end ifinfo |
| |
| @ifinfo |
| This file documents the internals of the GNU debugger @value{GDBN}. |
| |
| Copyright 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, |
| 2001 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. |
| |
| @ignore |
| Permission is granted to process this file through Tex and print the |
| results, provided the printed document carries copying permission notice |
| identical to this one except for the removal of this paragraph (this |
| paragraph not being relevant to the printed manual). |
| |
| @end ignore |
| 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). |
| @end ifinfo |
| |
| @setchapternewpage off |
| @settitle @value{GDBN} Internals |
| |
| @syncodeindex fn cp |
| @syncodeindex vr cp |
| |
| @titlepage |
| @title @value{GDBN} Internals |
| @subtitle{A guide to the internals of the GNU debugger} |
| @author John Gilmore |
| @author Cygnus Solutions |
| @author Second Edition: |
| @author Stan Shebs |
| @author Cygnus Solutions |
| @page |
| @tex |
| \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ |
| \xdef\manvers{\$Revision$} % For use in headers, footers too |
| {\parskip=0pt |
| \hfill Cygnus Solutions\par |
| \hfill \manvers\par |
| \hfill \TeX{}info \texinfoversion\par |
| } |
| @end tex |
| |
| @vskip 0pt plus 1filll |
| Copyright @copyright{} 1990-1999 Free Software Foundation, Inc. |
| |
| 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. |
| |
| @end titlepage |
| |
| @c TeX can handle the contents at the start but makeinfo 3.12 can not |
| @iftex |
| @contents |
| @end iftex |
| |
| @node Top |
| @c Perhaps this should be the title of the document (but only for info, |
| @c not for TeX). Existing GNU manuals seem inconsistent on this point. |
| @top Scope of this Document |
| |
| This document documents the internals of the GNU debugger, @value{GDBN}. It |
| includes description of @value{GDBN}'s key algorithms and operations, as well |
| as the mechanisms that adapt @value{GDBN} to specific hosts and targets. |
| |
| @menu |
| * Requirements:: |
| * Overall Structure:: |
| * Algorithms:: |
| * User Interface:: |
| * Symbol Handling:: |
| * Language Support:: |
| * Host Definition:: |
| * Target Architecture Definition:: |
| * Target Vector Definition:: |
| * Native Debugging:: |
| * Support Libraries:: |
| * Coding:: |
| * Porting GDB:: |
| * Testsuite:: |
| * Hints:: |
| * Index:: |
| @end menu |
| |
| @node Requirements |
| |
| @chapter Requirements |
| @cindex requirements for @value{GDBN} |
| |
| Before diving into the internals, you should understand the formal |
| requirements and other expectations for @value{GDBN}. Although some |
| of these may seem obvious, there have been proposals for @value{GDBN} |
| that have run counter to these requirements. |
| |
| First of all, @value{GDBN} is a debugger. It's not designed to be a |
| front panel for embedded systems. It's not a text editor. It's not a |
| shell. It's not a programming environment. |
| |
| @value{GDBN} is an interactive tool. Although a batch mode is |
| available, @value{GDBN}'s primary role is to interact with a human |
| programmer. |
| |
| @value{GDBN} should be responsive to the user. A programmer hot on |
| the trail of a nasty bug, and operating under a looming deadline, is |
| going to be very impatient of everything, including the response time |
| to debugger commands. |
| |
| @value{GDBN} should be relatively permissive, such as for expressions. |
| While the compiler should be picky (or have the option to be made |
| picky), since source code lives for a long time usuazlly, the |
| programmer doing debugging shouldn't be spending time figuring out to |
| mollify the debugger. |
| |
| @value{GDBN} will be called upon to deal with really large programs. |
| Executable sizes of 50 to 100 megabytes occur regularly, and we've |
| heard reports of programs approaching 1 gigabyte in size. |
| |
| @value{GDBN} should be able to run everywhere. No other debugger is |
| available for even half as many configurations as @value{GDBN} |
| supports. |
| |
| |
| @node Overall Structure |
| |
| @chapter Overall Structure |
| |
| @value{GDBN} consists of three major subsystems: user interface, |
| symbol handling (the @dfn{symbol side}), and target system handling (the |
| @dfn{target side}). |
| |
| The user interface consists of several actual interfaces, plus |
| supporting code. |
| |
| The symbol side consists of object file readers, debugging info |
| interpreters, symbol table management, source language expression |
| parsing, type and value printing. |
| |
| The target side consists of execution control, stack frame analysis, and |
| physical target manipulation. |
| |
| The target side/symbol side division is not formal, and there are a |
| number of exceptions. For instance, core file support involves symbolic |
| elements (the basic core file reader is in BFD) and target elements (it |
| supplies the contents of memory and the values of registers). Instead, |
| this division is useful for understanding how the minor subsystems |
| should fit together. |
| |
| @section The Symbol Side |
| |
| The symbolic side of @value{GDBN} can be thought of as ``everything |
| you can do in @value{GDBN} without having a live program running''. |
| For instance, you can look at the types of variables, and evaluate |
| many kinds of expressions. |
| |
| @section The Target Side |
| |
| The target side of @value{GDBN} is the ``bits and bytes manipulator''. |
| Although it may make reference to symbolic info here and there, most |
| of the target side will run with only a stripped executable |
| available---or even no executable at all, in remote debugging cases. |
| |
| Operations such as disassembly, stack frame crawls, and register |
| display, are able to work with no symbolic info at all. In some cases, |
| such as disassembly, @value{GDBN} will use symbolic info to present addresses |
| relative to symbols rather than as raw numbers, but it will work either |
| way. |
| |
| @section Configurations |
| |
| @cindex host |
| @cindex target |
| @dfn{Host} refers to attributes of the system where @value{GDBN} runs. |
| @dfn{Target} refers to the system where the program being debugged |
| executes. In most cases they are the same machine, in which case a |
| third type of @dfn{Native} attributes come into play. |
| |
| Defines and include files needed to build on the host are host support. |
| Examples are tty support, system defined types, host byte order, host |
| float format. |
| |
| Defines and information needed to handle the target format are target |
| dependent. Examples are the stack frame format, instruction set, |
| breakpoint instruction, registers, and how to set up and tear down the stack |
| to call a function. |
| |
| Information that is only needed when the host and target are the same, |
| is native dependent. One example is Unix child process support; if the |
| host and target are not the same, doing a fork to start the target |
| process is a bad idea. The various macros needed for finding the |
| registers in the @code{upage}, running @code{ptrace}, and such are all |
| in the native-dependent files. |
| |
| Another example of native-dependent code is support for features that |
| are really part of the target environment, but which require |
| @code{#include} files that are only available on the host system. Core |
| file handling and @code{setjmp} handling are two common cases. |
| |
| When you want to make @value{GDBN} work ``native'' on a particular machine, you |
| have to include all three kinds of information. |
| |
| |
| @node Algorithms |
| |
| @chapter Algorithms |
| @cindex algorithms |
| |
| @value{GDBN} uses a number of debugging-specific algorithms. They are |
| often not very complicated, but get lost in the thicket of special |
| cases and real-world issues. This chapter describes the basic |
| algorithms and mentions some of the specific target definitions that |
| they use. |
| |
| @section Frames |
| |
| @cindex frame |
| @cindex call stack frame |
| A frame is a construct that @value{GDBN} uses to keep track of calling |
| and called functions. |
| |
| @findex create_new_frame |
| @vindex FRAME_FP |
| @code{FRAME_FP} in the machine description has no meaning to the |
| machine-independent part of @value{GDBN}, except that it is used when |
| setting up a new frame from scratch, as follows: |
| |
| @example |
| create_new_frame (read_register (FP_REGNUM), read_pc ())); |
| @end example |
| |
| @cindex frame pointer register |
| Other than that, all the meaning imparted to @code{FP_REGNUM} is |
| imparted by the machine-dependent code. So, @code{FP_REGNUM} can have |
| any value that is convenient for the code that creates new frames. |
| (@code{create_new_frame} calls @code{INIT_EXTRA_FRAME_INFO} if it is |
| defined; that is where you should use the @code{FP_REGNUM} value, if |
| your frames are nonstandard.) |
| |
| @cindex frame chain |
| Given a @value{GDBN} frame, define @code{FRAME_CHAIN} to determine the |
| address of the calling function's frame. This will be used to create |
| a new @value{GDBN} frame struct, and then @code{INIT_EXTRA_FRAME_INFO} |
| and @code{INIT_FRAME_PC} will be called for the new frame. |
| |
| @section Breakpoint Handling |
| |
| @cindex breakpoints |
| In general, a breakpoint is a user-designated location in the program |
| where the user wants to regain control if program execution ever reaches |
| that location. |
| |
| There are two main ways to implement breakpoints; either as ``hardware'' |
| breakpoints or as ``software'' breakpoints. |
| |
| @cindex hardware breakpoints |
| @cindex program counter |
| Hardware breakpoints are sometimes available as a builtin debugging |
| features with some chips. Typically these work by having dedicated |
| register into which the breakpoint address may be stored. If the PC |
| (shorthand for @dfn{program counter}) |
| ever matches a value in a breakpoint registers, the CPU raises an |
| exception and reports it to @value{GDBN}. |
| |
| Another possibility is when an emulator is in use; many emulators |
| include circuitry that watches the address lines coming out from the |
| processor, and force it to stop if the address matches a breakpoint's |
| address. |
| |
| A third possibility is that the target already has the ability to do |
| breakpoints somehow; for instance, a ROM monitor may do its own |
| software breakpoints. So although these are not literally ``hardware |
| breakpoints'', from @value{GDBN}'s point of view they work the same; |
| @value{GDBN} need not do nothing more than set the breakpoint and wait |
| for something to happen. |
| |
| Since they depend on hardware resources, hardware breakpoints may be |
| limited in number; when the user asks for more, @value{GDBN} will |
| start trying to set software breakpoints. |
| |
| @cindex software breakpoints |
| Software breakpoints require @value{GDBN} to do somewhat more work. |
| The basic theory is that @value{GDBN} will replace a program |
| instruction with a trap, illegal divide, or some other instruction |
| that will cause an exception, and then when it's encountered, |
| @value{GDBN} will take the exception and stop the program. When the |
| user says to continue, @value{GDBN} will restore the original |
| instruction, single-step, re-insert the trap, and continue on. |
| |
| Since it literally overwrites the program being tested, the program area |
| must be writeable, so this technique won't work on programs in ROM. It |
| can also distort the behavior of programs that examine themselves, |
| although such a situation would be highly unusual. |
| |
| Also, the software breakpoint instruction should be the smallest size of |
| instruction, so it doesn't overwrite an instruction that might be a jump |
| target, and cause disaster when the program jumps into the middle of the |
| breakpoint instruction. (Strictly speaking, the breakpoint must be no |
| larger than the smallest interval between instructions that may be jump |
| targets; perhaps there is an architecture where only even-numbered |
| instructions may jumped to.) Note that it's possible for an instruction |
| set not to have any instructions usable for a software breakpoint, |
| although in practice only the ARC has failed to define such an |
| instruction. |
| |
| @findex BREAKPOINT |
| The basic definition of the software breakpoint is the macro |
| @code{BREAKPOINT}. |
| |
| Basic breakpoint object handling is in @file{breakpoint.c}. However, |
| much of the interesting breakpoint action is in @file{infrun.c}. |
| |
| @section Single Stepping |
| |
| @section Signal Handling |
| |
| @section Thread Handling |
| |
| @section Inferior Function Calls |
| |
| @section Longjmp Support |
| |
| @cindex @code{longjmp} debugging |
| @value{GDBN} has support for figuring out that the target is doing a |
| @code{longjmp} and for stopping at the target of the jump, if we are |
| stepping. This is done with a few specialized internal breakpoints, |
| which are visible in the output of the @samp{maint info breakpoint} |
| command. |
| |
| @findex GET_LONGJMP_TARGET |
| To make this work, you need to define a macro called |
| @code{GET_LONGJMP_TARGET}, which will examine the @code{jmp_buf} |
| structure and extract the longjmp target address. Since @code{jmp_buf} |
| is target specific, you will need to define it in the appropriate |
| @file{tm-@var{target}.h} file. Look in @file{tm-sun4os4.h} and |
| @file{sparc-tdep.c} for examples of how to do this. |
| |
| @node User Interface |
| |
| @chapter User Interface |
| |
| @value{GDBN} has several user interfaces. Although the command-line interface |
| is the most common and most familiar, there are others. |
| |
| @section Command Interpreter |
| |
| @cindex command interpreter |
| The command interpreter in @value{GDBN} is fairly simple. It is designed to |
| allow for the set of commands to be augmented dynamically, and also |
| has a recursive subcommand capability, where the first argument to |
| a command may itself direct a lookup on a different command list. |
| |
| For instance, the @samp{set} command just starts a lookup on the |
| @code{setlist} command list, while @samp{set thread} recurses |
| to the @code{set_thread_cmd_list}. |
| |
| @findex add_cmd |
| @findex add_com |
| To add commands in general, use @code{add_cmd}. @code{add_com} adds to |
| the main command list, and should be used for those commands. The usual |
| place to add commands is in the @code{_initialize_@var{xyz}} routines at |
| the ends of most source files. |
| |
| @cindex deprecating commands |
| @findex deprecate_cmd |
| Before removing commands from the command set it is a good idea to |
| deprecate them for some time. Use @code{deprecate_cmd} on commands or |
| aliases to set the deprecated flag. @code{deprecate_cmd} takes a |
| @code{struct cmd_list_element} as it's first argument. You can use the |
| return value from @code{add_com} or @code{add_cmd} to deprecate the |
| command immediately after it is created. |
| |
| The first time a comamnd is used the user will be warned and offered a |
| replacement (if one exists). Note that the replacement string passed to |
| @code{deprecate_cmd} should be the full name of the command, i.e. the |
| entire string the user should type at the command line. |
| |
| @section Console Printing |
| |
| @section TUI |
| |
| @section libgdb |
| |
| @cindex @code{libgdb} |
| @code{libgdb} was an abortive project of years ago. The theory was to |
| provide an API to @value{GDBN}'s functionality. |
| |
| @node Symbol Handling |
| |
| @chapter Symbol Handling |
| |
| Symbols are a key part of @value{GDBN}'s operation. Symbols include variables, |
| functions, and types. |
| |
| @section Symbol Reading |
| |
| @cindex symbol reading |
| @cindex reading of symbols |
| @cindex symbol files |
| @value{GDBN} reads symbols from @dfn{symbol files}. The usual symbol |
| file is the file containing the program which @value{GDBN} is |
| debugging. @value{GDBN} can be directed to use a different file for |
| symbols (with the @samp{symbol-file} command), and it can also read |
| more symbols via the @samp{add-file} and @samp{load} commands, or while |
| reading symbols from shared libraries. |
| |
| @findex find_sym_fns |
| Symbol files are initially opened by code in @file{symfile.c} using |
| the BFD library (@pxref{Support Libraries}). BFD identifies the type |
| of the file by examining its header. @code{find_sym_fns} then uses |
| this identification to locate a set of symbol-reading functions. |
| |
| @findex add_symtab_fns |
| @cindex @code{sym_fns} structure |
| @cindex adding a symbol-reading module |
| Symbol-reading modules identify themselves to @value{GDBN} by calling |
| @code{add_symtab_fns} during their module initialization. The argument |
| to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the |
| name (or name prefix) of the symbol format, the length of the prefix, |
| and pointers to four functions. These functions are called at various |
| times to process symbol files whose identification matches the specified |
| prefix. |
| |
| The functions supplied by each module are: |
| |
| @table @code |
| @item @var{xyz}_symfile_init(struct sym_fns *sf) |
| |
| @cindex secondary symbol file |
| Called from @code{symbol_file_add} when we are about to read a new |
| symbol file. This function should clean up any internal state (possibly |
| resulting from half-read previous files, for example) and prepare to |
| read a new symbol file. Note that the symbol file which we are reading |
| might be a new ``main'' symbol file, or might be a secondary symbol file |
| whose symbols are being added to the existing symbol table. |
| |
| The argument to @code{@var{xyz}_symfile_init} is a newly allocated |
| @code{struct sym_fns} whose @code{bfd} field contains the BFD for the |
| new symbol file being read. Its @code{private} field has been zeroed, |
| and can be modified as desired. Typically, a struct of private |
| information will be @code{malloc}'d, and a pointer to it will be placed |
| in the @code{private} field. |
| |
| There is no result from @code{@var{xyz}_symfile_init}, but it can call |
| @code{error} if it detects an unavoidable problem. |
| |
| @item @var{xyz}_new_init() |
| |
| Called from @code{symbol_file_add} when discarding existing symbols. |
| This function needs only handle the symbol-reading module's internal |
| state; the symbol table data structures visible to the rest of |
| @value{GDBN} will be discarded by @code{symbol_file_add}. It has no |
| arguments and no result. It may be called after |
| @code{@var{xyz}_symfile_init}, if a new symbol table is being read, or |
| may be called alone if all symbols are simply being discarded. |
| |
| @item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline) |
| |
| Called from @code{symbol_file_add} to actually read the symbols from a |
| symbol-file into a set of psymtabs or symtabs. |
| |
| @code{sf} points to the @code{struct sym_fns} originally passed to |
| @code{@var{xyz}_sym_init} for possible initialization. @code{addr} is |
| the offset between the file's specified start address and its true |
| address in memory. @code{mainline} is 1 if this is the main symbol |
| table being read, and 0 if a secondary symbol file (e.g. shared library |
| or dynamically loaded file) is being read.@refill |
| @end table |
| |
| In addition, if a symbol-reading module creates psymtabs when |
| @var{xyz}_symfile_read is called, these psymtabs will contain a pointer |
| to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called |
| from any point in the @value{GDBN} symbol-handling code. |
| |
| @table @code |
| @item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst) |
| |
| Called from @code{psymtab_to_symtab} (or the @code{PSYMTAB_TO_SYMTAB} macro) if |
| the psymtab has not already been read in and had its @code{pst->symtab} |
| pointer set. The argument is the psymtab to be fleshed-out into a |
| symtab. Upon return, @code{pst->readin} should have been set to 1, and |
| @code{pst->symtab} should contain a pointer to the new corresponding symtab, or |
| zero if there were no symbols in that part of the symbol file. |
| @end table |
| |
| @section Partial Symbol Tables |
| |
| @value{GDBN} has three types of symbol tables: |
| |
| @itemize @bullet |
| @cindex full symbol table |
| @cindex symtabs |
| @item |
| Full symbol tables (@dfn{symtabs}). These contain the main |
| information about symbols and addresses. |
| |
| @cindex psymtabs |
| @item |
| Partial symbol tables (@dfn{psymtabs}). These contain enough |
| information to know when to read the corresponding part of the full |
| symbol table. |
| |
| @cindex minimal symbol table |
| @cindex minsymtabs |
| @item |
| Minimal symbol tables (@dfn{msymtabs}). These contain information |
| gleaned from non-debugging symbols. |
| @end itemize |
| |
| @cindex partial symbol table |
| This section describes partial symbol tables. |
| |
| A psymtab is constructed by doing a very quick pass over an executable |
| file's debugging information. Small amounts of information are |
| extracted---enough to identify which parts of the symbol table will |
| need to be re-read and fully digested later, when the user needs the |
| information. The speed of this pass causes @value{GDBN} to start up very |
| quickly. Later, as the detailed rereading occurs, it occurs in small |
| pieces, at various times, and the delay therefrom is mostly invisible to |
| the user. |
| @c (@xref{Symbol Reading}.) |
| |
| The symbols that show up in a file's psymtab should be, roughly, those |
| visible to the debugger's user when the program is not running code from |
| that file. These include external symbols and types, static symbols and |
| types, and @code{enum} values declared at file scope. |
| |
| The psymtab also contains the range of instruction addresses that the |
| full symbol table would represent. |
| |
| @cindex finding a symbol |
| @cindex symbol lookup |
| The idea is that there are only two ways for the user (or much of the |
| code in the debugger) to reference a symbol: |
| |
| @itemize @bullet |
| @findex find_pc_function |
| @findex find_pc_line |
| @item |
| By its address (e.g. execution stops at some address which is inside a |
| function in this file). The address will be noticed to be in the |
| range of this psymtab, and the full symtab will be read in. |
| @code{find_pc_function}, @code{find_pc_line}, and other |
| @code{find_pc_@dots{}} functions handle this. |
| |
| @cindex lookup_symbol |
| @item |
| By its name |
| (e.g. the user asks to print a variable, or set a breakpoint on a |
| function). Global names and file-scope names will be found in the |
| psymtab, which will cause the symtab to be pulled in. Local names will |
| have to be qualified by a global name, or a file-scope name, in which |
| case we will have already read in the symtab as we evaluated the |
| qualifier. Or, a local symbol can be referenced when we are ``in'' a |
| local scope, in which case the first case applies. @code{lookup_symbol} |
| does most of the work here. |
| @end itemize |
| |
| The only reason that psymtabs exist is to cause a symtab to be read in |
| at the right moment. Any symbol that can be elided from a psymtab, |
| while still causing that to happen, should not appear in it. Since |
| psymtabs don't have the idea of scope, you can't put local symbols in |
| them anyway. Psymtabs don't have the idea of the type of a symbol, |
| either, so types need not appear, unless they will be referenced by |
| name. |
| |
| It is a bug for @value{GDBN} to behave one way when only a psymtab has |
| been read, and another way if the corresponding symtab has been read |
| in. Such bugs are typically caused by a psymtab that does not contain |
| all the visible symbols, or which has the wrong instruction address |
| ranges. |
| |
| The psymtab for a particular section of a symbol file (objfile) could be |
| thrown away after the symtab has been read in. The symtab should always |
| be searched before the psymtab, so the psymtab will never be used (in a |
| bug-free environment). Currently, psymtabs are allocated on an obstack, |
| and all the psymbols themselves are allocated in a pair of large arrays |
| on an obstack, so there is little to be gained by trying to free them |
| unless you want to do a lot more work. |
| |
| @section Types |
| |
| @unnumberedsubsec Fundamental Types (e.g., @code{FT_VOID}, @code{FT_BOOLEAN}). |
| |
| @cindex fundamental types |
| These are the fundamental types that @value{GDBN} uses internally. Fundamental |
| types from the various debugging formats (stabs, ELF, etc) are mapped |
| into one of these. They are basically a union of all fundamental types |
| that @value{GDBN} knows about for all the languages that @value{GDBN} |
| knows about. |
| |
| @unnumberedsubsec Type Codes (e.g., @code{TYPE_CODE_PTR}, @code{TYPE_CODE_ARRAY}). |
| |
| @cindex type codes |
| Each time @value{GDBN} builds an internal type, it marks it with one |
| of these types. The type may be a fundamental type, such as |
| @code{TYPE_CODE_INT}, or a derived type, such as @code{TYPE_CODE_PTR} |
| which is a pointer to another type. Typically, several @code{FT_*} |
| types map to one @code{TYPE_CODE_*} type, and are distinguished by |
| other members of the type struct, such as whether the type is signed |
| or unsigned, and how many bits it uses. |
| |
| @unnumberedsubsec Builtin Types (e.g., @code{builtin_type_void}, @code{builtin_type_char}). |
| |
| These are instances of type structs that roughly correspond to |
| fundamental types and are created as global types for @value{GDBN} to |
| use for various ugly historical reasons. We eventually want to |
| eliminate these. Note for example that @code{builtin_type_int} |
| initialized in @file{gdbtypes.c} is basically the same as a |
| @code{TYPE_CODE_INT} type that is initialized in @file{c-lang.c} for |
| an @code{FT_INTEGER} fundamental type. The difference is that the |
| @code{builtin_type} is not associated with any particular objfile, and |
| only one instance exists, while @file{c-lang.c} builds as many |
| @code{TYPE_CODE_INT} types as needed, with each one associated with |
| some particular objfile. |
| |
| @section Object File Formats |
| @cindex object file formats |
| |
| @subsection a.out |
| |
| @cindex @code{a.out} format |
| The @code{a.out} format is the original file format for Unix. It |
| consists of three sections: @code{text}, @code{data}, and @code{bss}, |
| which are for program code, initialized data, and uninitialized data, |
| respectively. |
| |
| The @code{a.out} format is so simple that it doesn't have any reserved |
| place for debugging information. (Hey, the original Unix hackers used |
| @samp{adb}, which is a machine-language debugger!) The only debugging |
| format for @code{a.out} is stabs, which is encoded as a set of normal |
| symbols with distinctive attributes. |
| |
| The basic @code{a.out} reader is in @file{dbxread.c}. |
| |
| @subsection COFF |
| |
| @cindex COFF format |
| The COFF format was introduced with System V Release 3 (SVR3) Unix. |
| COFF files may have multiple sections, each prefixed by a header. The |
| number of sections is limited. |
| |
| The COFF specification includes support for debugging. Although this |
| was a step forward, the debugging information was woefully limited. For |
| instance, it was not possible to represent code that came from an |
| included file. |
| |
| The COFF reader is in @file{coffread.c}. |
| |
| @subsection ECOFF |
| |
| @cindex ECOFF format |
| ECOFF is an extended COFF originally introduced for Mips and Alpha |
| workstations. |
| |
| The basic ECOFF reader is in @file{mipsread.c}. |
| |
| @subsection XCOFF |
| |
| @cindex XCOFF format |
| The IBM RS/6000 running AIX uses an object file format called XCOFF. |
| The COFF sections, symbols, and line numbers are used, but debugging |
| symbols are @code{dbx}-style stabs whose strings are located in the |
| @code{.debug} section (rather than the string table). For more |
| information, see @ref{Top,,,stabs,The Stabs Debugging Format}. |
| |
| The shared library scheme has a clean interface for figuring out what |
| shared libraries are in use, but the catch is that everything which |
| refers to addresses (symbol tables and breakpoints at least) needs to be |
| relocated for both shared libraries and the main executable. At least |
| using the standard mechanism this can only be done once the program has |
| been run (or the core file has been read). |
| |
| @subsection PE |
| |
| @cindex PE-COFF format |
| Windows 95 and NT use the PE (@dfn{Portable Executable}) format for their |
| executables. PE is basically COFF with additional headers. |
| |
| While BFD includes special PE support, @value{GDBN} needs only the basic |
| COFF reader. |
| |
| @subsection ELF |
| |
| @cindex ELF format |
| The ELF format came with System V Release 4 (SVR4) Unix. ELF is similar |
| to COFF in being organized into a number of sections, but it removes |
| many of COFF's limitations. |
| |
| The basic ELF reader is in @file{elfread.c}. |
| |
| @subsection SOM |
| |
| @cindex SOM format |
| SOM is HP's object file and debug format (not to be confused with IBM's |
| SOM, which is a cross-language ABI). |
| |
| The SOM reader is in @file{hpread.c}. |
| |
| @subsection Other File Formats |
| |
| @cindex Netware Loadable Module format |
| Other file formats that have been supported by @value{GDBN} include Netware |
| Loadable Modules (@file{nlmread.c}. |
| |
| @section Debugging File Formats |
| |
| This section describes characteristics of debugging information that |
| are independent of the object file format. |
| |
| @subsection stabs |
| |
| @cindex stabs debugging info |
| @code{stabs} started out as special symbols within the @code{a.out} |
| format. Since then, it has been encapsulated into other file |
| formats, such as COFF and ELF. |
| |
| While @file{dbxread.c} does some of the basic stab processing, |
| including for encapsulated versions, @file{stabsread.c} does |
| the real work. |
| |
| @subsection COFF |
| |
| @cindex COFF debugging info |
| The basic COFF definition includes debugging information. The level |
| of support is minimal and non-extensible, and is not often used. |
| |
| @subsection Mips debug (Third Eye) |
| |
| @cindex ECOFF debugging info |
| ECOFF includes a definition of a special debug format. |
| |
| The file @file{mdebugread.c} implements reading for this format. |
| |
| @subsection DWARF 1 |
| |
| @cindex DWARF 1 debugging info |
| DWARF 1 is a debugging format that was originally designed to be |
| used with ELF in SVR4 systems. |
| |
| @c CHILL_PRODUCER |
| @c GCC_PRODUCER |
| @c GPLUS_PRODUCER |
| @c LCC_PRODUCER |
| @c If defined, these are the producer strings in a DWARF 1 file. All of |
| @c these have reasonable defaults already. |
| |
| The DWARF 1 reader is in @file{dwarfread.c}. |
| |
| @subsection DWARF 2 |
| |
| @cindex DWARF 2 debugging info |
| DWARF 2 is an improved but incompatible version of DWARF 1. |
| |
| The DWARF 2 reader is in @file{dwarf2read.c}. |
| |
| @subsection SOM |
| |
| @cindex SOM debugging info |
| Like COFF, the SOM definition includes debugging information. |
| |
| @section Adding a New Symbol Reader to @value{GDBN} |
| |
| @cindex adding debugging info reader |
| If you are using an existing object file format (@code{a.out}, COFF, ELF, etc), |
| there is probably little to be done. |
| |
| If you need to add a new object file format, you must first add it to |
| BFD. This is beyond the scope of this document. |
| |
| You must then arrange for the BFD code to provide access to the |
| debugging symbols. Generally @value{GDBN} will have to call swapping routines |
| from BFD and a few other BFD internal routines to locate the debugging |
| information. As much as possible, @value{GDBN} should not depend on the BFD |
| internal data structures. |
| |
| For some targets (e.g., COFF), there is a special transfer vector used |
| to call swapping routines, since the external data structures on various |
| platforms have different sizes and layouts. Specialized routines that |
| will only ever be implemented by one object file format may be called |
| directly. This interface should be described in a file |
| @file{bfd/lib@var{xyz}.h}, which is included by @value{GDBN}. |
| |
| |
| @node Language Support |
| |
| @chapter Language Support |
| |
| @cindex language support |
| @value{GDBN}'s language support is mainly driven by the symbol reader, |
| although it is possible for the user to set the source language |
| manually. |
| |
| @value{GDBN} chooses the source language by looking at the extension |
| of the file recorded in the debug info; @file{.c} means C, @file{.f} |
| means Fortran, etc. It may also use a special-purpose language |
| identifier if the debug format supports it, like with DWARF. |
| |
| @section Adding a Source Language to @value{GDBN} |
| |
| @cindex adding source language |
| To add other languages to @value{GDBN}'s expression parser, follow the |
| following steps: |
| |
| @table @emph |
| @item Create the expression parser. |
| |
| @cindex expression parser |
| This should reside in a file @file{@var{lang}-exp.y}. Routines for |
| building parsed expressions into a @code{union exp_element} list are in |
| @file{parse.c}. |
| |
| @cindex language parser |
| Since we can't depend upon everyone having Bison, and YACC produces |
| parsers that define a bunch of global names, the following lines |
| @strong{must} be included at the top of the YACC parser, to prevent the |
| various parsers from defining the same global names: |
| |
| @example |
| #define yyparse @var{lang}_parse |
| #define yylex @var{lang}_lex |
| #define yyerror @var{lang}_error |
| #define yylval @var{lang}_lval |
| #define yychar @var{lang}_char |
| #define yydebug @var{lang}_debug |
| #define yypact @var{lang}_pact |
| #define yyr1 @var{lang}_r1 |
| #define yyr2 @var{lang}_r2 |
| #define yydef @var{lang}_def |
| #define yychk @var{lang}_chk |
| #define yypgo @var{lang}_pgo |
| #define yyact @var{lang}_act |
| #define yyexca @var{lang}_exca |
| #define yyerrflag @var{lang}_errflag |
| #define yynerrs @var{lang}_nerrs |
| @end example |
| |
| At the bottom of your parser, define a @code{struct language_defn} and |
| initialize it with the right values for your language. Define an |
| @code{initialize_@var{lang}} routine and have it call |
| @samp{add_language(@var{lang}_language_defn)} to tell the rest of @value{GDBN} |
| that your language exists. You'll need some other supporting variables |
| and functions, which will be used via pointers from your |
| @code{@var{lang}_language_defn}. See the declaration of @code{struct |
| language_defn} in @file{language.h}, and the other @file{*-exp.y} files, |
| for more information. |
| |
| @item Add any evaluation routines, if necessary |
| |
| @cindex expression evaluation routines |
| @findex evaluate_subexp |
| @findex prefixify_subexp |
| @findex length_of_subexp |
| If you need new opcodes (that represent the operations of the language), |
| add them to the enumerated type in @file{expression.h}. Add support |
| code for these operations in the @code{evaluate_subexp} function |
| defined in the file @file{eval.c}. Add cases |
| for new opcodes in two functions from @file{parse.c}: |
| @code{prefixify_subexp} and @code{length_of_subexp}. These compute |
| the number of @code{exp_element}s that a given operation takes up. |
| |
| @item Update some existing code |
| |
| Add an enumerated identifier for your language to the enumerated type |
| @code{enum language} in @file{defs.h}. |
| |
| Update the routines in @file{language.c} so your language is included. |
| These routines include type predicates and such, which (in some cases) |
| are language dependent. If your language does not appear in the switch |
| statement, an error is reported. |
| |
| @vindex current_language |
| Also included in @file{language.c} is the code that updates the variable |
| @code{current_language}, and the routines that translate the |
| @code{language_@var{lang}} enumerated identifier into a printable |
| string. |
| |
| @findex _initialize_language |
| Update the function @code{_initialize_language} to include your |
| language. This function picks the default language upon startup, so is |
| dependent upon which languages that @value{GDBN} is built for. |
| |
| @findex allocate_symtab |
| Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading |
| code so that the language of each symtab (source file) is set properly. |
| This is used to determine the language to use at each stack frame level. |
| Currently, the language is set based upon the extension of the source |
| file. If the language can be better inferred from the symbol |
| information, please set the language of the symtab in the symbol-reading |
| code. |
| |
| @findex print_subexp |
| @findex op_print_tab |
| Add helper code to @code{print_subexp} (in @file{expprint.c}) to handle any new |
| expression opcodes you have added to @file{expression.h}. Also, add the |
| printed representations of your operators to @code{op_print_tab}. |
| |
| @item Add a place of call |
| |
| @findex parse_exp_1 |
| Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in |
| @code{parse_exp_1} (defined in @file{parse.c}). |
| |
| @item Use macros to trim code |
| |
| @cindex trimming language-dependent code |
| The user has the option of building @value{GDBN} for some or all of the |
| languages. If the user decides to build @value{GDBN} for the language |
| @var{lang}, then every file dependent on @file{language.h} will have the |
| macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to |
| leave out large routines that the user won't need if he or she is not |
| using your language. |
| |
| Note that you do not need to do this in your YACC parser, since if @value{GDBN} |
| is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the |
| compiled form of your parser) is not linked into @value{GDBN} at all. |
| |
| See the file @file{configure.in} for how @value{GDBN} is configured |
| for different languages. |
| |
| @item Edit @file{Makefile.in} |
| |
| Add dependencies in @file{Makefile.in}. Make sure you update the macro |
| variables such as @code{HFILES} and @code{OBJS}, otherwise your code may |
| not get linked in, or, worse yet, it may not get @code{tar}red into the |
| distribution! |
| @end table |
| |
| |
| @node Host Definition |
| |
| @chapter Host Definition |
| |
| With the advent of Autoconf, it's rarely necessary to have host |
| definition machinery anymore. |
| |
| @section Adding a New Host |
| |
| @cindex adding a new host |
| @cindex host, adding |
| Most of @value{GDBN}'s host configuration support happens via |
| Autoconf. New host-specific definitions should be rarely needed. |
| @value{GDBN} still uses the host-specific definitions and files listed |
| below, but these mostly exist for historical reasons, and should |
| eventually disappear. |
| |
| Several files control @value{GDBN}'s configuration for host systems: |
| |
| @table @file |
| @vindex XDEPFILES |
| @item gdb/config/@var{arch}/@var{xyz}.mh |
| Specifies Makefile fragments needed when hosting on machine @var{xyz}. |
| In particular, this lists the required machine-dependent object files, |
| by defining @samp{XDEPFILES=@dots{}}. Also specifies the header file |
| which describes host @var{xyz}, by defining @code{XM_FILE= |
| xm-@var{xyz}.h}. You can also define @code{CC}, @code{SYSV_DEFINE}, |
| @code{XM_CFLAGS}, @code{XM_ADD_FILES}, @code{XM_CLIBS}, @code{XM_CDEPS}, |
| etc.; see @file{Makefile.in}. |
| |
| @item gdb/config/@var{arch}/xm-@var{xyz}.h |
| (@file{xm.h} is a link to this file, created by @code{configure}). Contains C |
| macro definitions describing the host system environment, such as byte |
| order, host C compiler and library. |
| |
| @item gdb/@var{xyz}-xdep.c |
| Contains any miscellaneous C code required for this machine as a host. |
| On most machines it doesn't exist at all. If it does exist, put |
| @file{@var{xyz}-xdep.o} into the @code{XDEPFILES} line in |
| @file{gdb/config/@var{arch}/@var{xyz}.mh}. |
| @end table |
| |
| @subheading Generic Host Support Files |
| |
| @cindex generic host support |
| 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 @file{xm-@var{xyz}.h} file. If these routines work for |
| the @var{xyz} host, you can just include the generic file's name (with |
| @samp{.o}, not @samp{.c}) in @code{XDEPFILES}. |
| |
| 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 @code{@var{xyz}-xdep.c}, and put @code{@var{xyz}-xdep.o} |
| into @code{XDEPFILES}. |
| |
| @table @file |
| @cindex remote debugging support |
| @cindex serial line support |
| @item ser-unix.c |
| This contains serial line support for Unix systems. This is always |
| included, via the makefile variable @code{SER_HARDWIRE}; override this |
| variable in the @file{.mh} file to avoid it. |
| |
| @item ser-go32.c |
| This contains serial line support for 32-bit programs running under DOS, |
| using the DJGPP (a.k.a.@: GO32) execution environment. |
| |
| @cindex TCP remote support |
| @item ser-tcp.c |
| This contains generic TCP support using sockets. |
| @end table |
| |
| @section Host Conditionals |
| |
| When @value{GDBN} is configured and compiled, various macros are |
| defined or left undefined, to control compilation based on the |
| attributes of the host system. These macros and their meanings (or if |
| the meaning is not documented here, then one of the source files where |
| they are used is indicated) are: |
| |
| @ftable @code |
| @item @value{GDBN}INIT_FILENAME |
| The default name of @value{GDBN}'s initialization file (normally |
| @file{.gdbinit}). |
| |
| @item MEM_FNS_DECLARED |
| Your host config file defines this if it includes declarations of |
| @code{memcpy} and @code{memset}. Define this to avoid conflicts between |
| the native include files and the declarations in @file{defs.h}. |
| |
| @item NO_STD_REGS |
| This macro is deprecated. |
| |
| @item NO_SYS_FILE |
| Define this if your system does not have a @code{<sys/file.h>}. |
| |
| @item SIGWINCH_HANDLER |
| If your host defines @code{SIGWINCH}, you can define this to be the name |
| of a function to be called if @code{SIGWINCH} is received. |
| |
| @item SIGWINCH_HANDLER_BODY |
| Define this to expand into code that will define the function named by |
| the expansion of @code{SIGWINCH_HANDLER}. |
| |
| @item ALIGN_STACK_ON_STARTUP |
| @cindex stack alignment |
| Define this if your system is of a sort that will crash in |
| @code{tgetent} if the stack happens not to be longword-aligned when |
| @code{main} is called. This is a rare situation, but is known to occur |
| on several different types of systems. |
| |
| @item CRLF_SOURCE_FILES |
| @cindex DOS text files |
| Define this if host files use @code{\r\n} rather than @code{\n} as a |
| line terminator. This will cause source file listings to omit @code{\r} |
| characters when printing and it will allow @code{\r\n} line endings of files |
| which are ``sourced'' by gdb. It must be possible to open files in binary |
| mode using @code{O_BINARY} or, for fopen, @code{"rb"}. |
| |
| @item DEFAULT_PROMPT |
| @cindex prompt |
| The default value of the prompt string (normally @code{"(gdb) "}). |
| |
| @item DEV_TTY |
| @cindex terminal device |
| The name of the generic TTY device, defaults to @code{"/dev/tty"}. |
| |
| @item FCLOSE_PROVIDED |
| Define this if the system declares @code{fclose} in the headers included |
| in @code{defs.h}. This isn't needed unless your compiler is unusually |
| anal. |
| |
| @item FOPEN_RB |
| Define this if binary files are opened the same way as text files. |
| |
| @item GETENV_PROVIDED |
| Define this if the system declares @code{getenv} in its headers included |
| in @code{defs.h}. This isn't needed unless your compiler is unusually |
| anal. |
| |
| @item HAVE_MMAP |
| @findex mmap |
| In some cases, use the system call @code{mmap} for reading symbol |
| tables. For some machines this allows for sharing and quick updates. |
| |
| @item HAVE_SIGSETMASK |
| @findex sigsetmask |
| Define this if the host system has job control, but does not define |
| @code{sigsetmask}. Currently, this is only true of the RS/6000. |
| |
| @item HAVE_TERMIO |
| Define this if the host system has @code{termio.h}. |
| |
| @item HOST_BYTE_ORDER |
| @cindex byte order |
| The ordering of bytes in the host. This must be defined to be either |
| @code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. |
| |
| @item INT_MAX |
| @item INT_MIN |
| @item LONG_MAX |
| @item UINT_MAX |
| @item ULONG_MAX |
| Values for host-side constants. |
| |
| @item ISATTY |
| Substitute for isatty, if not available. |
| |
| @item LONGEST |
| This is the longest integer type available on the host. If not defined, |
| it will default to @code{long long} or @code{long}, depending on |
| @code{CC_HAS_LONG_LONG}. |
| |
| @item CC_HAS_LONG_LONG |
| @cindex @code{long long} data type |
| Define this if the host C compiler supports @code{long long}. This is set |
| by the @code{configure} script. |
| |
| @item PRINTF_HAS_LONG_LONG |
| Define this if the host can handle printing of long long integers via |
| the printf format conversion specifier @code{ll}. This is set by the |
| @code{configure} script. |
| |
| @item HAVE_LONG_DOUBLE |
| Define this if the host C compiler supports @code{long double}. This is |
| set by the @code{configure} script. |
| |
| @item PRINTF_HAS_LONG_DOUBLE |
| Define this if the host can handle printing of long double float-point |
| numbers via the printf format conversion specifier @code{Lg}. This is |
| set by the @code{configure} script. |
| |
| @item SCANF_HAS_LONG_DOUBLE |
| Define this if the host can handle the parsing of long double |
| float-point numbers via the scanf format conversion specifier |
| @code{Lg}. This is set by the @code{configure} script. |
| |
| @item LSEEK_NOT_LINEAR |
| Define this if @code{lseek (n)} does not necessarily move to byte number |
| @code{n} in the file. This is only used when reading source files. It |
| is normally faster to define @code{CRLF_SOURCE_FILES} when possible. |
| |
| @item L_SET |
| This macro is used as the argument to @code{lseek} (or, most commonly, |
| @code{bfd_seek}). FIXME, should be replaced by SEEK_SET instead, |
| which is the POSIX equivalent. |
| |
| @item MALLOC_INCOMPATIBLE |
| Define this if the system's prototype for @code{malloc} differs from the |
| @sc{ansi} definition. |
| |
| @item MMAP_BASE_ADDRESS |
| When using HAVE_MMAP, the first mapping should go at this address. |
| |
| @item MMAP_INCREMENT |
| when using HAVE_MMAP, this is the increment between mappings. |
| |
| @item NEED_POSIX_SETPGID |
| @findex setpgid |
| Define this to use the POSIX version of @code{setpgid} to determine |
| whether job control is available. |
| |
| @item NORETURN |
| If defined, this should be one or more tokens, such as @code{volatile}, |
| that can be used in both the declaration and definition of functions to |
| indicate that they never return. The default is already set correctly |
| if compiling with GCC. This will almost never need to be defined. |
| |
| @item ATTR_NORETURN |
| If defined, this should be one or more tokens, such as |
| @code{__attribute__ ((noreturn))}, that can be used in the declarations |
| of functions to indicate that they never return. The default is already |
| set correctly if compiling with GCC. This will almost never need to be |
| defined. |
| |
| @item USE_GENERIC_DUMMY_FRAMES |
| @cindex generic dummy frames |
| Define this to 1 if the target is using the generic inferior function |
| call code. See @code{blockframe.c} for more information. |
| |
| @item USE_MMALLOC |
| @findex mmalloc |
| @value{GDBN} will use the @code{mmalloc} library for memory allocation |
| for symbol reading if this symbol is defined. Be careful defining it |
| since there are systems on which @code{mmalloc} does not work for some |
| reason. One example is the DECstation, where its RPC library can't |
| cope with our redefinition of @code{malloc} to call @code{mmalloc}. |
| When defining @code{USE_MMALLOC}, you will also have to set |
| @code{MMALLOC} in the Makefile, to point to the @code{mmalloc} library. This |
| define is set when you configure with @samp{--with-mmalloc}. |
| |
| @item NO_MMCHECK |
| @findex mmcheck |
| Define this if you are using @code{mmalloc}, but don't want the overhead |
| of checking the heap with @code{mmcheck}. Note that on some systems, |
| the C runtime makes calls to @code{malloc} prior to calling @code{main}, and if |
| @code{free} is ever called with these pointers after calling |
| @code{mmcheck} to enable checking, a memory corruption abort is certain |
| to occur. These systems can still use @code{mmalloc}, but must define |
| @code{NO_MMCHECK}. |
| |
| @item MMCHECK_FORCE |
| Define this to 1 if the C runtime allocates memory prior to |
| @code{mmcheck} being called, but that memory is never freed so we don't |
| have to worry about it triggering a memory corruption abort. The |
| default is 0, which means that @code{mmcheck} will only install the heap |
| checking functions if there has not yet been any memory allocation |
| calls, and if it fails to install the functions, @value{GDBN} will issue a |
| warning. This is currently defined if you configure using |
| @samp{--with-mmalloc}. |
| |
| @item NO_SIGINTERRUPT |
| @findex siginterrupt |
| Define this to indicate that @code{siginterrupt} is not available. |
| |
| @item R_OK |
| Define if this is not in a system header file (typically, @file{unistd.h}). |
| |
| @item SEEK_CUR |
| @item SEEK_SET |
| Define these to appropriate value for the system @code{lseek}, if not already |
| defined. |
| |
| @item STOP_SIGNAL |
| This is the signal for stopping @value{GDBN}. Defaults to |
| @code{SIGTSTP}. (Only redefined for the Convex.) |
| |
| @item USE_O_NOCTTY |
| Define this if the interior's tty should be opened with the @code{O_NOCTTY} |
| flag. (FIXME: This should be a native-only flag, but @file{inflow.c} is |
| always linked in.) |
| |
| @item USG |
| Means that System V (prior to SVR4) include files are in use. (FIXME: |
| This symbol is abused in @file{infrun.c}, @file{regex.c}, |
| @file{remote-nindy.c}, and @file{utils.c} for other things, at the |
| moment.) |
| |
| @item lint |
| Define this to help placate @code{lint} in some situations. |
| |
| @item volatile |
| Define this to override the defaults of @code{__volatile__} or |
| @code{/**/}. |
| @end ftable |
| |
| |
| @node Target Architecture Definition |
| |
| @chapter Target Architecture Definition |
| |
| @cindex target architecture definition |
| @value{GDBN}'s target architecture defines what sort of |
| machine-language programs @value{GDBN} can work with, and how it works |
| with them. |
| |
| At present, the target architecture definition consists of a number of C |
| macros. |
| |
| @section Registers and Memory |
| |
| @value{GDBN}'s model of the target machine is rather simple. |
| @value{GDBN} assumes the machine includes a bank of registers and a |
| block of memory. Each register may have a different size. |
| |
| @value{GDBN} 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 @code{REGISTER_NAME} and related macros. |
| |
| @value{GDBN} can handle big-endian, little-endian, and bi-endian architectures. |
| |
| @section Pointers Are Not Always Addresses |
| @cindex pointer representation |
| @cindex address representation |
| @cindex word-addressed machines |
| @cindex separate data and code address spaces |
| @cindex spaces, separate data and code address |
| @cindex address spaces, separate data and code |
| @cindex code pointers, word-addressed |
| @cindex converting between pointers and addresses |
| @cindex D10V addresses |
| |
| On almost all 32-bit architectures, the representation of a pointer is |
| indistinguishable from the representation of some fixed-length number |
| whose value is the byte address of the object pointed to. On such |
| machines, the words ``pointer'' and ``address'' can be used interchangeably. |
| However, architectures with smaller word sizes are often cramped for |
| address space, so they may choose a pointer representation that breaks this |
| identity, and allows a larger code address space. |
| |
| For example, the Mitsubishi D10V is a 16-bit VLIW processor whose |
| instructions are 32 bits long@footnote{Some D10V instructions are |
| actually pairs of 16-bit sub-instructions. However, since you can't |
| jump into the middle of such a pair, code addresses can only refer to |
| full 32 bit instructions, which is what matters in this explanation.}. |
| If the D10V used ordinary byte addresses to refer to code locations, |
| then the processor would only be able to address 64kb of instructions. |
| However, since instructions must be aligned on four-byte boundaries, the |
| low two bits of any valid instruction's byte address are always |
| zero---byte addresses waste two bits. So instead of byte addresses, |
| the D10V uses word addresses---byte addresses shifted right two bits---to |
| refer to code. Thus, the D10V can use 16-bit words to address 256kb of |
| code space. |
| |
| However, this means that code pointers and data pointers have different |
| forms on the D10V. The 16-bit word @code{0xC020} refers to byte address |
| @code{0xC020} when used as a data address, but refers to byte address |
| @code{0x30080} when used as a code address. |
| |
| (The D10V also uses separate code and data address spaces, which also |
| affects the correspondence between pointers and addresses, but we're |
| going to ignore that here; this example is already too long.) |
| |
| To cope with architectures like this---the D10V is not the only |
| one!---@value{GDBN} tries to distinguish between @dfn{addresses}, which are |
| byte numbers, and @dfn{pointers}, which are the target's representation |
| of an address of a particular type of data. In the example above, |
| @code{0xC020} is the pointer, which refers to one of the addresses |
| @code{0xC020} or @code{0x30080}, depending on the type imposed upon it. |
| @value{GDBN} provides functions for turning a pointer into an address |
| and vice versa, in the appropriate way for the current architecture. |
| |
| Unfortunately, since addresses and pointers are identical on almost all |
| processors, this distinction tends to bit-rot pretty quickly. Thus, |
| each time you port @value{GDBN} to an architecture which does |
| distinguish between pointers and addresses, you'll probably need to |
| clean up some architecture-independent code. |
| |
| Here are functions which convert between pointers and addresses: |
| |
| @deftypefun CORE_ADDR extract_typed_address (void *@var{buf}, struct type *@var{type}) |
| Treat the bytes at @var{buf} as a pointer or reference of type |
| @var{type}, and return the address it represents, in a manner |
| appropriate for the current architecture. This yields an address |
| @value{GDBN} can use to read target memory, disassemble, etc. Note that |
| @var{buf} refers to a buffer in @value{GDBN}'s memory, not the |
| inferior's. |
| |
| For example, if the current architecture is the Intel x86, this function |
| extracts a little-endian integer of the appropriate length from |
| @var{buf} and returns it. However, if the current architecture is the |
| D10V, this function will return a 16-bit integer extracted from |
| @var{buf}, multiplied by four if @var{type} is a pointer to a function. |
| |
| If @var{type} is not a pointer or reference type, then this function |
| will signal an internal error. |
| @end deftypefun |
| |
| @deftypefun CORE_ADDR store_typed_address (void *@var{buf}, struct type *@var{type}, CORE_ADDR @var{addr}) |
| Store the address @var{addr} in @var{buf}, in the proper format for a |
| pointer of type @var{type} in the current architecture. Note that |
| @var{buf} refers to a buffer in @value{GDBN}'s memory, not the |
| inferior's. |
| |
| For example, if the current architecture is the Intel x86, this function |
| stores @var{addr} unmodified as a little-endian integer of the |
| appropriate length in @var{buf}. However, if the current architecture |
| is the D10V, this function divides @var{addr} by four if @var{type} is |
| a pointer to a function, and then stores it in @var{buf}. |
| |
| If @var{type} is not a pointer or reference type, then this function |
| will signal an internal error. |
| @end deftypefun |
| |
| @deftypefun CORE_ADDR value_as_pointer (value_ptr @var{val}) |
| Assuming that @var{val} is a pointer, return the address it represents, |
| as appropriate for the current architecture. |
| |
| This function actually works on integral values, as well as pointers. |
| For pointers, it performs architecture-specific conversions as |
| described above for @code{extract_typed_address}. |
| @end deftypefun |
| |
| @deftypefun CORE_ADDR value_from_pointer (struct type *@var{type}, CORE_ADDR @var{addr}) |
| Create and return a value representing a pointer of type @var{type} to |
| the address @var{addr}, as appropriate for the current architecture. |
| This function performs architecture-specific conversions as described |
| above for @code{store_typed_address}. |
| @end deftypefun |
| |
| |
| @value{GDBN} also provides functions that do the same tasks, but assume |
| that pointers are simply byte addresses; they aren't sensitive to the |
| current architecture, beyond knowing the appropriate endianness. |
| |
| @deftypefun CORE_ADDR extract_address (void *@var{addr}, int len) |
| Extract a @var{len}-byte number from @var{addr} in the appropriate |
| endianness for the current architecture, and return it. Note that |
| @var{addr} refers to @value{GDBN}'s memory, not the inferior's. |
| |
| This function should only be used in architecture-specific code; it |
| doesn't have enough information to turn bits into a true address in the |
| appropriate way for the current architecture. If you can, use |
| @code{extract_typed_address} instead. |
| @end deftypefun |
| |
| @deftypefun void store_address (void *@var{addr}, int @var{len}, LONGEST @var{val}) |
| Store @var{val} at @var{addr} as a @var{len}-byte integer, in the |
| appropriate endianness for the current architecture. Note that |
| @var{addr} refers to a buffer in @value{GDBN}'s memory, not the |
| inferior's. |
| |
| This function should only be used in architecture-specific code; it |
| doesn't have enough information to turn a true address into bits in the |
| appropriate way for the current architecture. If you can, use |
| @code{store_typed_address} instead. |
| @end deftypefun |
| |
| |
| Here are some macros which architectures can define to indicate the |
| relationship between pointers and addresses. These have default |
| definitions, appropriate for architectures on which all pointers are |
| simple byte addresses. |
| |
| @deftypefn {Target Macro} CORE_ADDR POINTER_TO_ADDRESS (struct type *@var{type}, char *@var{buf}) |
| Assume that @var{buf} holds a pointer of type @var{type}, in the |
| appropriate format for the current architecture. Return the byte |
| address the pointer refers to. |
| |
| This function may safely assume that @var{type} is either a pointer or a |
| C@t{++} reference type. |
| @end deftypefn |
| |
| @deftypefn {Target Macro} void ADDRESS_TO_POINTER (struct type *@var{type}, char *@var{buf}, CORE_ADDR @var{addr}) |
| Store in @var{buf} a pointer of type @var{type} representing the address |
| @var{addr}, in the appropriate format for the current architecture. |
| |
| This function may safely assume that @var{type} is either a pointer or a |
| C@t{++} reference type. |
| @end deftypefn |
| |
| |
| @section Using Different Register and Memory Data Representations |
| @cindex raw representation |
| @cindex virtual representation |
| @cindex representations, raw and virtual |
| @cindex register data formats, converting |
| @cindex @code{struct value}, converting register contents to |
| |
| Some architectures use one representation for a value when it lives in a |
| register, but use a different representation when it lives in memory. |
| In @value{GDBN}'s terminology, the @dfn{raw} representation is the one used in |
| the target registers, and the @dfn{virtual} representation is the one |
| used in memory, and within @value{GDBN} @code{struct value} objects. |
| |
| For almost all data types on almost all architectures, the virtual and |
| raw representations are identical, and no special handling is needed. |
| However, they do occasionally differ. For example: |
| |
| @itemize @bullet |
| @item |
| The x86 architecture supports an 80-bit @code{long double} type. However, when |
| we store those values in memory, they occupy twelve bytes: the |
| floating-point number occupies the first ten, and the final two bytes |
| are unused. This keeps the values aligned on four-byte boundaries, |
| allowing more efficient access. Thus, the x86 80-bit floating-point |
| type is the raw representation, and the twelve-byte loosely-packed |
| arrangement is the virtual representation. |
| |
| @item |
| Some 64-bit MIPS targets present 32-bit registers to @value{GDBN} as 64-bit |
| registers, with garbage in their upper bits. @value{GDBN} ignores the top 32 |
| bits. Thus, the 64-bit form, with garbage in the upper 32 bits, is the |
| raw representation, and the trimmed 32-bit representation is the |
| virtual representation. |
| @end itemize |
| |
| In general, the raw representation is determined by the architecture, or |
| @value{GDBN}'s interface to the architecture, while the virtual representation |
| can be chosen for @value{GDBN}'s convenience. @value{GDBN}'s register file, |
| @code{registers}, holds the register contents in raw format, and the |
| @value{GDBN} remote protocol transmits register values in raw format. |
| |
| Your architecture may define the following macros to request |
| conversions between the raw and virtual format: |
| |
| @deftypefn {Target Macro} int REGISTER_CONVERTIBLE (int @var{reg}) |
| Return non-zero if register number @var{reg}'s value needs different raw |
| and virtual formats. |
| |
| You should not use @code{REGISTER_CONVERT_TO_VIRTUAL} for a register |
| unless this macro returns a non-zero value for that register. |
| @end deftypefn |
| |
| @deftypefn {Target Macro} int REGISTER_RAW_SIZE (int @var{reg}) |
| The size of register number @var{reg}'s raw value. This is the number |
| of bytes the register will occupy in @code{registers}, or in a @value{GDBN} |
| remote protocol packet. |
| @end deftypefn |
| |
| @deftypefn {Target Macro} int REGISTER_VIRTUAL_SIZE (int @var{reg}) |
| The size of register number @var{reg}'s value, in its virtual format. |
| This is the size a @code{struct value}'s buffer will have, holding that |
| register's value. |
| @end deftypefn |
| |
| @deftypefn {Target Macro} struct type *REGISTER_VIRTUAL_TYPE (int @var{reg}) |
| This is the type of the virtual representation of register number |
| @var{reg}. Note that there is no need for a macro giving a type for the |
| register's raw form; once the register's value has been obtained, @value{GDBN} |
| always uses the virtual form. |
| @end deftypefn |
| |
| @deftypefn {Target Macro} void REGISTER_CONVERT_TO_VIRTUAL (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to}) |
| Convert the value of register number @var{reg} to @var{type}, which |
| should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer |
| at @var{from} holds the register's value in raw format; the macro should |
| convert the value to virtual format, and place it at @var{to}. |
| |
| Note that @code{REGISTER_CONVERT_TO_VIRTUAL} and |
| @code{REGISTER_CONVERT_TO_RAW} take their @var{reg} and @var{type} |
| arguments in different orders. |
| |
| You should only use @code{REGISTER_CONVERT_TO_VIRTUAL} with registers |
| for which the @code{REGISTER_CONVERTIBLE} macro returns a non-zero |
| value. |
| @end deftypefn |
| |
| @deftypefn {Target Macro} void REGISTER_CONVERT_TO_RAW (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to}) |
| Convert the value of register number @var{reg} to @var{type}, which |
| should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer |
| at @var{from} holds the register's value in raw format; the macro should |
| convert the value to virtual format, and place it at @var{to}. |
| |
| Note that REGISTER_CONVERT_TO_VIRTUAL and REGISTER_CONVERT_TO_RAW take |
| their @var{reg} and @var{type} arguments in different orders. |
| @end deftypefn |
| |
| |
| @section Frame Interpretation |
| |
| @section Inferior Call Setup |
| |
| @section Compiler Characteristics |
| |
| @section Target Conditionals |
| |
| This section describes the macros that you can use to define the target |
| machine. |
| |
| @table @code |
| |
| @item ADDITIONAL_OPTIONS |
| @itemx ADDITIONAL_OPTION_CASES |
| @itemx ADDITIONAL_OPTION_HANDLER |
| @itemx ADDITIONAL_OPTION_HELP |
| @findex ADDITIONAL_OPTION_HELP |
| @findex ADDITIONAL_OPTION_HANDLER |
| @findex ADDITIONAL_OPTION_CASES |
| @findex ADDITIONAL_OPTIONS |
| These are a set of macros that allow the addition of additional command |
| line options to @value{GDBN}. They are currently used only for the unsupported |
| i960 Nindy target, and should not be used in any other configuration. |
| |
| @item ADDR_BITS_REMOVE (addr) |
| @findex ADDR_BITS_REMOVE |
| If a raw machine instruction address includes any bits that are not |
| really part of the address, then define this macro to expand into an |
| expression that zeroes those bits in @var{addr}. This is only used for |
| addresses of instructions, and even then not in all contexts. |
| |
| For example, the two low-order bits of the PC on the Hewlett-Packard PA |
| 2.0 architecture contain the privilege level of the corresponding |
| instruction. Since instructions must always be aligned on four-byte |
| boundaries, the processor masks out these bits to generate the actual |
| address of the instruction. ADDR_BITS_REMOVE should filter out these |
| bits with an expression such as @code{((addr) & ~3)}. |
| |
| @item ADDRESS_TO_POINTER (@var{type}, @var{buf}, @var{addr}) |
| @findex ADDRESS_TO_POINTER |
| Store in @var{buf} a pointer of type @var{type} representing the address |
| @var{addr}, in the appropriate format for the current architecture. |
| This macro may safely assume that @var{type} is either a pointer or a |
| C@t{++} reference type. |
| @xref{Target Architecture Definition, , Pointers Are Not Always Addresses}. |
| |
| @item BEFORE_MAIN_LOOP_HOOK |
| @findex 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, @value{GDBN} will probably not compile, let alone run |
| correctly. This macro is currently used only for the unsupported i960 Nindy |
| target, and should not be used in any other configuration. |
| |
| @item BELIEVE_PCC_PROMOTION |
| @findex BELIEVE_PCC_PROMOTION |
| Define if the compiler promotes a @code{short} or @code{char} |
| parameter to an @code{int}, but still reports the parameter as its |
| original type, rather than the promoted type. |
| |
| @item BELIEVE_PCC_PROMOTION_TYPE |
| @findex BELIEVE_PCC_PROMOTION_TYPE |
| Define this if @value{GDBN} should believe the type of a @code{short} |
| argument when compiled by @code{pcc}, but look within a full int space to get |
| its value. Only defined for Sun-3 at present. |
| |
| @item BITS_BIG_ENDIAN |
| @findex BITS_BIG_ENDIAN |
| Define this if the numbering of bits in the targets does @strong{not} match the |
| endianness of the target byte order. A value of 1 means that the bits |
| are numbered in a big-endian bit order, 0 means little-endian. |
| |
| @item BREAKPOINT |
| @findex 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. |
| |
| @code{BREAKPOINT} has been deprecated in favor of |
| @code{BREAKPOINT_FROM_PC}. |
| |
| @item BIG_BREAKPOINT |
| @itemx LITTLE_BREAKPOINT |
| @findex LITTLE_BREAKPOINT |
| @findex BIG_BREAKPOINT |
| Similar to BREAKPOINT, but used for bi-endian targets. |
| |
| @code{BIG_BREAKPOINT} and @code{LITTLE_BREAKPOINT} have been deprecated in |
| favor of @code{BREAKPOINT_FROM_PC}. |
| |
| @item REMOTE_BREAKPOINT |
| @itemx LITTLE_REMOTE_BREAKPOINT |
| @itemx BIG_REMOTE_BREAKPOINT |
| @findex BIG_REMOTE_BREAKPOINT |
| @findex LITTLE_REMOTE_BREAKPOINT |
| @findex REMOTE_BREAKPOINT |
| Similar to BREAKPOINT, but used for remote targets. |
| |
| @code{BIG_REMOTE_BREAKPOINT} and @code{LITTLE_REMOTE_BREAKPOINT} have been |
| deprecated in favor of @code{BREAKPOINT_FROM_PC}. |
| |
| @item BREAKPOINT_FROM_PC (@var{pcptr}, @var{lenptr}) |
| @findex BREAKPOINT_FROM_PC |
| 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 *@var{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 @var{BREAKPOINT} macros. |
| |
| @item MEMORY_INSERT_BREAKPOINT (@var{addr}, @var{contents_cache}) |
| @itemx MEMORY_REMOVE_BREAKPOINT (@var{addr}, @var{contents_cache}) |
| @findex MEMORY_REMOVE_BREAKPOINT |
| @findex MEMORY_INSERT_BREAKPOINT |
| Insert or remove memory based breakpoints. Reasonable defaults |
| (@code{default_memory_insert_breakpoint} and |
| @code{default_memory_remove_breakpoint} respectively) have been |
| provided so that it is not necessary to define these for most |
| architectures. Architectures which may want to define |
| @code{MEMORY_INSERT_BREAKPOINT} and @code{MEMORY_REMOVE_BREAKPOINT} will |
| likely have instructions that are oddly sized or are not stored in a |
| conventional manner. |
| |
| It may also be desirable (from an efficiency standpoint) to define |
| custom breakpoint insertion and removal routines if |
| @code{BREAKPOINT_FROM_PC} needs to read the target's memory for some |
| reason. |
| |
| @item CALL_DUMMY_P |
| @findex CALL_DUMMY_P |
| A C expresson that is non-zero when the target suports inferior function |
| calls. |
| |
| @item CALL_DUMMY_WORDS |
| @findex CALL_DUMMY_WORDS |
| Pointer to an array of @code{LONGEST} words of data containing |
| host-byte-ordered @code{REGISTER_BYTES} sized values that partially |
| specify the sequence of instructions needed for an inferior function |
| call. |
| |
| Should be deprecated in favor of a macro that uses target-byte-ordered |
| data. |
| |
| @item SIZEOF_CALL_DUMMY_WORDS |
| @findex SIZEOF_CALL_DUMMY_WORDS |
| The size of @code{CALL_DUMMY_WORDS}. When @code{CALL_DUMMY_P} this must |
| return a positive value. See also @code{CALL_DUMMY_LENGTH}. |
| |
| @item CALL_DUMMY |
| @findex CALL_DUMMY |
| A static initializer for @code{CALL_DUMMY_WORDS}. Deprecated. |
| |
| @item CALL_DUMMY_LOCATION |
| @findex CALL_DUMMY_LOCATION |
| See the file @file{inferior.h}. |
| |
| @item CALL_DUMMY_STACK_ADJUST |
| @findex CALL_DUMMY_STACK_ADJUST |
| Stack adjustment needed when performing an inferior function call. |
| |
| Should be deprecated in favor of something like @code{STACK_ALIGN}. |
| |
| @item CALL_DUMMY_STACK_ADJUST_P |
| @findex CALL_DUMMY_STACK_ADJUST_P |
| Predicate for use of @code{CALL_DUMMY_STACK_ADJUST}. |
| |
| Should be deprecated in favor of something like @code{STACK_ALIGN}. |
| |
| @item CANNOT_FETCH_REGISTER (@var{regno}) |
| @findex CANNOT_FETCH_REGISTER |
| A C expression that should be nonzero if @var{regno} cannot be fetched |
| from an inferior process. This is only relevant if |
| @code{FETCH_INFERIOR_REGISTERS} is not defined. |
| |
| @item CANNOT_STORE_REGISTER (@var{regno}) |
| @findex CANNOT_STORE_REGISTER |
| A C expression that should be nonzero if @var{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, |
| @value{GDBN} will assume that all registers may be written. |
| |
| @item DO_DEFERRED_STORES |
| @itemx CLEAR_DEFERRED_STORES@item |
| @findex CLEAR_DEFERRED_STORES |
| @findex DO_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? |
| |
| @item COERCE_FLOAT_TO_DOUBLE (@var{formal}, @var{actual}) |
| @findex COERCE_FLOAT_TO_DOUBLE |
| @cindex promotion to @code{double} |
| If we are calling a function by hand, and the function was declared |
| (according to the debug info) without a prototype, should we |
| automatically promote @code{float}s to @code{double}s? This macro |
| must evaluate to non-zero if we should, or zero if we should leave the |
| value alone. |
| |
| The argument @var{actual} is the type of the value we want to pass to |
| the function. The argument @var{formal} is the type of this argument, |
| as it appears in the function's definition. Note that @var{formal} may |
| be zero if we have no debugging information for the function, or if |
| we're passing more arguments than are officially declared (for example, |
| varargs). This macro is never invoked if the function definitely has a |
| prototype. |
| |
| @findex set_gdbarch_coerce_float_to_double |
| @findex standard_coerce_float_to_double |
| The default behavior is to promote only when we have no type information |
| for the formal parameter. This is different from the obvious behavior, |
| which would be to promote whenever we have no prototype, just as the |
| compiler does. It's annoying, but some older targets rely on this. If |
| you want @value{GDBN} to follow the typical compiler behavior---to always |
| promote when there is no prototype in scope---your gdbarch @code{init} |
| function can call @code{set_gdbarch_coerce_float_to_double} and select |
| the @code{standard_coerce_float_to_double} function. |
| |
| @item CPLUS_MARKER |
| @findex CPLUS_MARKERz |
| Define this to expand into the character that G@t{++} uses to distinguish |
| compiler-generated identifiers from programmer-specified identifiers. |
| By default, this expands into @code{'$'}. Most System V targets should |
| define this to @code{'.'}. |
| |
| @item DBX_PARM_SYMBOL_CLASS |
| @findex DBX_PARM_SYMBOL_CLASS |
| Hook for the @code{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. |
| |
| @item DECR_PC_AFTER_BREAK |
| @findex 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 |
| @code{BREAKPOINT}, though not always. For most targets this value will be 0. |
| |
| @item DECR_PC_AFTER_HW_BREAK |
| @findex DECR_PC_AFTER_HW_BREAK |
| Similarly, for hardware breakpoints. |
| |
| @item DISABLE_UNSETTABLE_BREAK (@var{addr}) |
| @findex DISABLE_UNSETTABLE_BREAK |
| If defined, this should evaluate to 1 if @var{addr} is in a shared |
| library in which breakpoints cannot be set and so should be disabled. |
| |
| @item DO_REGISTERS_INFO |
| @findex DO_REGISTERS_INFO |
| If defined, use this to print the value of a register or all registers. |
| |
| @item DWARF_REG_TO_REGNUM |
| @findex DWARF_REG_TO_REGNUM |
| Convert DWARF register number into @value{GDBN} regnum. If not defined, |
| no conversion will be performed. |
| |
| @item DWARF2_REG_TO_REGNUM |
| @findex DWARF2_REG_TO_REGNUM |
| Convert DWARF2 register number into @value{GDBN} regnum. If not |
| defined, no conversion will be performed. |
| |
| @item ECOFF_REG_TO_REGNUM |
| @findex ECOFF_REG_TO_REGNUM |
| Convert ECOFF register number into @value{GDBN} regnum. If not defined, |
| no conversion will be performed. |
| |
| @item END_OF_TEXT_DEFAULT |
| @findex END_OF_TEXT_DEFAULT |
| This is an expression that should designate the end of the text section. |
| @c (? FIXME ?) |
| |
| @item EXTRACT_RETURN_VALUE(@var{type}, @var{regbuf}, @var{valbuf}) |
| @findex EXTRACT_RETURN_VALUE |
| Define this to extract a function's return value of type @var{type} from |
| the raw register state @var{regbuf} and copy that, in virtual format, |
| into @var{valbuf}. |
| |
| @item EXTRACT_STRUCT_VALUE_ADDRESS(@var{regbuf}) |
| @findex EXTRACT_STRUCT_VALUE_ADDRESS |
| When @code{EXTRACT_STRUCT_VALUE_ADDRESS_P} is non-zero, this is used to extract |
| from an array @var{regbuf} (containing the raw register state) the |
| address in which a function should return its structure value, as a |
| @code{CORE_ADDR} (or an expression that can be used as one). |
| |
| @item EXTRACT_STRUCT_VALUE_ADDRESS_P |
| @findex EXTRACT_STRUCT_VALUE_ADDRESS_P |
| Predicate for @code{EXTRACT_STRUCT_VALUE_ADDRESS}. |
| |
| @item FLOAT_INFO |
| @findex FLOAT_INFO |
| If defined, then the @samp{info float} command will print information about |
| the processor's floating point unit. |
| |
| @item FP_REGNUM |
| @findex FP_REGNUM |
| If the virtual frame pointer is kept in a register, then define this |
| macro to be the number (greater than or equal to zero) of that register. |
| |
| This should only need to be defined if @code{TARGET_READ_FP} and |
| @code{TARGET_WRITE_FP} are not defined. |
| |
| @item FRAMELESS_FUNCTION_INVOCATION(@var{fi}) |
| @findex FRAMELESS_FUNCTION_INVOCATION |
| Define this to an expression that returns 1 if the function invocation |
| represented by @var{fi} does not have a stack frame associated with it. |
| Otherwise return 0. |
| |
| @item FRAME_ARGS_ADDRESS_CORRECT@item |
| @findex FRAME_ARGS_ADDRESS_CORRECT |
| See @file{stack.c}. |
| |
| @item FRAME_CHAIN(@var{frame}) |
| @findex FRAME_CHAIN |
| Given @var{frame}, return a pointer to the calling frame. |
| |
| @item FRAME_CHAIN_COMBINE(@var{chain}, @var{frame}) |
| @findex FRAME_CHAIN_COMBINE |
| 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. |
| |
| @item FRAME_CHAIN_VALID(@var{chain}, @var{thisframe}) |
| @findex FRAME_CHAIN_VALID |
| Define this to be an expression that returns zero if the given frame is |
| an outermost frame, with no caller, and nonzero otherwise. Several |
| common definitions are available: |
| |
| @itemize @bullet |
| @item |
| @code{file_frame_chain_valid} is nonzero if the chain pointer is nonzero |
| and given frame's PC is not inside the startup file (such as |
| @file{crt0.o}). |
| |
| @item |
| @code{func_frame_chain_valid} is nonzero if the chain |
| pointer is nonzero and the given frame's PC is not in @code{main} or a |
| known entry point function (such as @code{_start}). |
| |
| @item |
| @code{generic_file_frame_chain_valid} and |
| @code{generic_func_frame_chain_valid} are equivalent implementations for |
| targets using generic dummy frames. |
| @end itemize |
| |
| @item FRAME_INIT_SAVED_REGS(@var{frame}) |
| @findex FRAME_INIT_SAVED_REGS |
| See @file{frame.h}. Determines the address of all registers in the |
| current stack frame storing each in @code{frame->saved_regs}. Space for |
| @code{frame->saved_regs} shall be allocated by |
| @code{FRAME_INIT_SAVED_REGS} using either |
| @code{frame_saved_regs_zalloc} or @code{frame_obstack_alloc}. |
| |
| @code{FRAME_FIND_SAVED_REGS} and @code{EXTRA_FRAME_INFO} are deprecated. |
| |
| @item FRAME_NUM_ARGS (@var{fi}) |
| @findex FRAME_NUM_ARGS |
| For the frame described by @var{fi} return the number of arguments that |
| are being passed. If the number of arguments is not known, return |
| @code{-1}. |
| |
| @item FRAME_SAVED_PC(@var{frame}) |
| @findex FRAME_SAVED_PC |
| Given @var{frame}, return the pc saved there. This is the return |
| address. |
| |
| @item FUNCTION_EPILOGUE_SIZE |
| @findex FUNCTION_EPILOGUE_SIZE |
| For some COFF targets, the @code{x_sym.x_misc.x_fsize} field of the |
| function end symbol is 0. For such targets, you must define |
| @code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a |
| function's epilogue. |
| |
| @item FUNCTION_START_OFFSET |
| @findex FUNCTION_START_OFFSET |
| An integer, giving the offset in bytes from a function's address (as |
| used in the values of symbols, function pointers, etc.), and the |
| function's first genuine instruction. |
| |
| This is zero on almost all machines: the function's address is usually |
| the address of its first instruction. However, on the VAX, for example, |
| each function starts with two bytes containing a bitmask indicating |
| which registers to save upon entry to the function. The VAX @code{call} |
| instructions check this value, and save the appropriate registers |
| automatically. Thus, since the offset from the function's address to |
| its first instruction is two bytes, @code{FUNCTION_START_OFFSET} would |
| be 2 on the VAX. |
| |
| @item GCC_COMPILED_FLAG_SYMBOL |
| @itemx GCC2_COMPILED_FLAG_SYMBOL |
| @findex GCC2_COMPILED_FLAG_SYMBOL |
| @findex GCC_COMPILED_FLAG_SYMBOL |
| If defined, these are the names of the symbols that @value{GDBN} will |
| look for to detect that GCC compiled the file. The default symbols |
| are @code{gcc_compiled.} and @code{gcc2_compiled.}, |
| respectively. (Currently only defined for the Delta 68.) |
| |
| @item @value{GDBN}_MULTI_ARCH |
| @findex @value{GDBN}_MULTI_ARCH |
| If defined and non-zero, enables suport for multiple architectures |
| within @value{GDBN}. |
| |
| This support can be enabled at two levels. At level one, only |
| definitions for previously undefined macros are provided; at level two, |
| a multi-arch definition of all architecture dependant macros will be |
| defined. |
| |
| @item @value{GDBN}_TARGET_IS_HPPA |
| @findex @value{GDBN}_TARGET_IS_HPPA |
| This determines whether horrible kludge code in @file{dbxread.c} and |
| @file{partial-stab.h} is used to mangle multiple-symbol-table files from |
| HPPA's. This should all be ripped out, and a scheme like @file{elfread.c} |
| used instead. |
| |
| @item GET_LONGJMP_TARGET |
| @findex 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 |
| trhe header file @file{setjmp.h} is needed to define it. |
| |
| This macro determines the target PC address that @code{longjmp} will jump to, |
| assuming that we have just stopped at a @code{longjmp} breakpoint. It takes a |
| @code{CORE_ADDR *} as argument, and stores the target PC value through this |
| pointer. It examines the current state of the machine as needed. |
| |
| @item GET_SAVED_REGISTER |
| @findex GET_SAVED_REGISTER |
| @findex get_saved_register |
| Define this if you need to supply your own definition for the function |
| @code{get_saved_register}. |
| |
| @item HAVE_REGISTER_WINDOWS |
| @findex HAVE_REGISTER_WINDOWS |
| Define this if the target has register windows. |
| |
| @item REGISTER_IN_WINDOW_P (@var{regnum}) |
| @findex REGISTER_IN_WINDOW_P |
| Define this to be an expression that is 1 if the given register is in |
| the window. |
| |
| @item IBM6000_TARGET |
| @findex 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 a haste and we are |
| repenting at leisure. |
| |
| @item SYMBOLS_CAN_START_WITH_DOLLAR |
| @findex SYMBOLS_CAN_START_WITH_DOLLAR |
| Some systems have routines whose names start with @samp{$}. Giving this |
| macro a non-zero value tells @value{GDBN}'s expression parser to check for such |
| routines when parsing tokens that begin with @samp{$}. |
| |
| On HP-UX, certain system routines (millicode) have names beginning with |
| @samp{$} or @samp{$$}. For example, @code{$$dyncall} is a millicode |
| routine that handles inter-space procedure calls on PA-RISC. |
| |
| @item IEEE_FLOAT |
| @findex IEEE_FLOAT |
| Define this if the target system uses IEEE-format floating point numbers. |
| |
| @item INIT_EXTRA_FRAME_INFO (@var{fromleaf}, @var{frame}) |
| @findex INIT_EXTRA_FRAME_INFO |
| If additional information about the frame is required this should be |
| stored in @code{frame->extra_info}. Space for @code{frame->extra_info} |
| is allocated using @code{frame_obstack_alloc}. |
| |
| @item INIT_FRAME_PC (@var{fromleaf}, @var{prev}) |
| @findex INIT_FRAME_PC |
| This is a C statement that sets the pc of the frame pointed to by |
| @var{prev}. [By default...] |
| |
| @item INNER_THAN (@var{lhs}, @var{rhs}) |
| @findex INNER_THAN |
| Returns non-zero if stack address @var{lhs} is inner than (nearer to the |
| stack top) stack address @var{rhs}. Define this as @code{lhs < rhs} if |
| the target's stack grows downward in memory, or @code{lhs > rsh} if the |
| stack grows upward. |
| |
| @item IN_SIGTRAMP (@var{pc}, @var{name}) |
| @findex IN_SIGTRAMP |
| Define this to return non-zero if the given @var{pc} and/or @var{name} |
| indicates that the current function is a @code{sigtramp}. |
| |
| @item SIGTRAMP_START (@var{pc}) |
| @findex SIGTRAMP_START |
| @itemx SIGTRAMP_END (@var{pc}) |
| @findex SIGTRAMP_END |
| Define these to be the start and end address of the @code{sigtramp} for the |
| given @var{pc}. On machines where the address is just a compile time |
| constant, the macro expansion will typically just ignore the supplied |
| @var{pc}. |
| |
| @item IN_SOLIB_CALL_TRAMPOLINE (@var{pc}, @var{name}) |
| @findex IN_SOLIB_CALL_TRAMPOLINE |
| Define this to evaluate to nonzero if the program is stopped in the |
| trampoline that connects to a shared library. |
| |
| @item IN_SOLIB_RETURN_TRAMPOLINE (@var{pc}, @var{name}) |
| @findex IN_SOLIB_RETURN_TRAMPOLINE |
| Define this to evaluate to nonzero if the program is stopped in the |
| trampoline that returns from a shared library. |
| |
| @item IN_SOLIB_DYNSYM_RESOLVE_CODE (@var{pc}) |
| @findex IN_SOLIB_DYNSYM_RESOLVE_CODE |
| Define this to evaluate to nonzero if the program is stopped in the |
| dynamic linker. |
| |
| @item SKIP_SOLIB_RESOLVER (@var{pc}) |
| @findex SKIP_SOLIB_RESOLVER |
| Define this to evaluate to the (nonzero) address at which execution |
| should continue to get past the dynamic linker's symbol resolution |
| function. A zero value indicates that it is not important or necessary |
| to set a breakpoint to get through the dynamic linker and that single |
| stepping will suffice. |
| |
| @item IS_TRAPPED_INTERNALVAR (@var{name}) |
| @findex IS_TRAPPED_INTERNALVAR |
| 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 @value{GDBN}. Currently only used by the h8500. Note that this |
| could be either a host or target conditional. |
| |
| @item NEED_TEXT_START_END |
| @findex NEED_TEXT_START_END |
| Define this if @value{GDBN} should determine the start and end addresses of the |
| text section. (Seems dubious.) |
| |
| @item NO_HIF_SUPPORT |
| @findex NO_HIF_SUPPORT |
| (Specific to the a29k.) |
| |
| @item POINTER_TO_ADDRESS (@var{type}, @var{buf}) |
| @findex POINTER_TO_ADDRESS |
| Assume that @var{buf} holds a pointer of type @var{type}, in the |
| appropriate format for the current architecture. Return the byte |
| address the pointer refers to. |
| @xref{Target Architecture Definition, , Pointers Are Not Always Addresses}. |
| |
| @item REGISTER_CONVERTIBLE (@var{reg}) |
| @findex REGISTER_CONVERTIBLE |
| Return non-zero if @var{reg} uses different raw and virtual formats. |
| @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. |
| |
| @item REGISTER_RAW_SIZE (@var{reg}) |
| @findex REGISTER_RAW_SIZE |
| Return the raw size of @var{reg}. |
| @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. |
| |
| @item REGISTER_VIRTUAL_SIZE (@var{reg}) |
| @findex REGISTER_VIRTUAL_SIZE |
| Return the virtual size of @var{reg}. |
| @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. |
| |
| @item REGISTER_VIRTUAL_TYPE (@var{reg}) |
| @findex REGISTER_VIRTUAL_TYPE |
| Return the virtual type of @var{reg}. |
| @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. |
| |
| @item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to}) |
| @findex REGISTER_CONVERT_TO_VIRTUAL |
| Convert the value of register @var{reg} from its raw form to its virtual |
| form. |
| @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. |
| |
| @item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to}) |
| @findex REGISTER_CONVERT_TO_RAW |
| Convert the value of register @var{reg} from its virtual form to its raw |
| form. |
| @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. |
| |
| @item RETURN_VALUE_ON_STACK(@var{type}) |
| @findex RETURN_VALUE_ON_STACK |
| @cindex returning structures by value |
| @cindex structures, returning by value |
| |
| Return non-zero if values of type TYPE are returned on the stack, using |
| the ``struct convention'' (i.e., the caller provides a pointer to a |
| buffer in which the callee should store the return value). This |
| controls how the @samp{finish} command finds a function's return value, |
| and whether an inferior function call reserves space on the stack for |
| the return value. |
| |
| The full logic @value{GDBN} uses here is kind of odd. |
| |
| @itemize @bullet |
| @item |
| If the type being returned by value is not a structure, union, or array, |
| and @code{RETURN_VALUE_ON_STACK} returns zero, then @value{GDBN} |
| concludes the value is not returned using the struct convention. |
| |
| @item |
| Otherwise, @value{GDBN} calls @code{USE_STRUCT_CONVENTION} (see below). |
| If that returns non-zero, @value{GDBN} assumes the struct convention is |
| in use. |
| @end itemize |
| |
| In other words, to indicate that a given type is returned by value using |
| the struct convention, that type must be either a struct, union, array, |
| or something @code{RETURN_VALUE_ON_STACK} likes, @emph{and} something |
| that @code{USE_STRUCT_CONVENTION} likes. |
| |
| Note that, in C and C@t{++}, arrays are never returned by value. In those |
| languages, these predicates will always see a pointer type, never an |
| array type. All the references above to arrays being returned by value |
| apply only to other languages. |
| |
| @item SOFTWARE_SINGLE_STEP_P |
| @findex SOFTWARE_SINGLE_STEP_P |
| Define this as 1 if the target does not have a hardware single-step |
| mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined. |
| |
| @item SOFTWARE_SINGLE_STEP(@var{signal}, @var{insert_breapoints_p}) |
| @findex SOFTWARE_SINGLE_STEP |
| A function that inserts or removes (depending on |
| @var{insert_breapoints_p}) breakpoints at each possible destinations of |
| the next instruction. See @file{sparc-tdep.c} and @file{rs6000-tdep.c} |
| for examples. |
| |
| @item SOFUN_ADDRESS_MAYBE_MISSING |
| @findex SOFUN_ADDRESS_MAYBE_MISSING |
| Somebody clever observed that, the more actual addresses you have in the |
| debug information, the more time the linker has to spend relocating |
| them. So whenever there's some other way the debugger could find the |
| address it needs, you should omit it from the debug info, to make |
| linking faster. |
| |
| @code{SOFUN_ADDRESS_MAYBE_MISSING} indicates that a particular set of |
| hacks of this sort are in use, affecting @code{N_SO} and @code{N_FUN} |
| entries in stabs-format debugging information. @code{N_SO} stabs mark |
| the beginning and ending addresses of compilation units in the text |
| segment. @code{N_FUN} stabs mark the starts and ends of functions. |
| |
| @code{SOFUN_ADDRESS_MAYBE_MISSING} means two things: |
| |
| @itemize @bullet |
| @item |
| @code{N_FUN} stabs have an address of zero. Instead, you should find the |
| addresses where the function starts by taking the function name from |
| the stab, and then looking that up in the minsyms (the |
| linker/assembler symbol table). In other words, the stab has the |
| name, and the linker/assembler symbol table is the only place that carries |
| the address. |
| |
| @item |
| @code{N_SO} stabs have an address of zero, too. You just look at the |
| @code{N_FUN} stabs that appear before and after the @code{N_SO} stab, |
| and guess the starting and ending addresses of the compilation unit from |
| them. |
| @end itemize |
| |
| @item PCC_SOL_BROKEN |
| @findex PCC_SOL_BROKEN |
| (Used only in the Convex target.) |
| |
| @item PC_IN_CALL_DUMMY |
| @findex PC_IN_CALL_DUMMY |
| See @file{inferior.h}. |
| |
| @item PC_LOAD_SEGMENT |
| @findex PC_LOAD_SEGMENT |
| If defined, print information about the load segment for the program |
| counter. (Defined only for the RS/6000.) |
| |
| @item PC_REGNUM |
| @findex PC_REGNUM |
| If the program counter is kept in a register, then define this macro to |
| be the number (greater than or equal to zero) of that register. |
| |
| This should only need to be defined if @code{TARGET_READ_PC} and |
| @code{TARGET_WRITE_PC} are not defined. |
| |
| @item NPC_REGNUM |
| @findex NPC_REGNUM |
| The number of the ``next program counter'' register, if defined. |
| |
| @item NNPC_REGNUM |
| @findex NNPC_REGNUM |
| The number of the ``next next program counter'' register, if defined. |
| Currently, this is only defined for the Motorola 88K. |
| |
| @item PARM_BOUNDARY |
| @findex PARM_BOUNDARY |
| If non-zero, round arguments to a boundary of this many bits before |
| pushing them on the stack. |
| |
| @item PRINT_REGISTER_HOOK (@var{regno}) |
| @findex PRINT_REGISTER_HOOK |
| If defined, this must be a function that prints the contents of the |
| given register to standard output. |
| |
| @item PRINT_TYPELESS_INTEGER |
| @findex PRINT_TYPELESS_INTEGER |
| This is an obscure substitute for @code{print_longest} that seems to |
| have been defined for the Convex target. |
| |
| @item PROCESS_LINENUMBER_HOOK |
| @findex PROCESS_LINENUMBER_HOOK |
| A hook defined for XCOFF reading. |
| |
| @item PROLOGUE_FIRSTLINE_OVERLAP |
| @findex PROLOGUE_FIRSTLINE_OVERLAP |
| (Only used in unsupported Convex configuration.) |
| |
| @item PS_REGNUM |
| @findex PS_REGNUM |
| If defined, this is the number of the processor status register. (This |
| definition is only used in generic code when parsing "$ps".) |
| |
| @item POP_FRAME |
| @findex POP_FRAME |
| @findex call_function_by_hand |
| @findex return_command |
| Used in @samp{call_function_by_hand} to remove an artificial stack |
| frame and in @samp{return_command} to remove a real stack frame. |
| |
| @item PUSH_ARGUMENTS (@var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr}) |
| @findex PUSH_ARGUMENTS |
| Define this to push arguments onto the stack for inferior function |
| call. Returns the updated stack pointer value. |
| |
| @item PUSH_DUMMY_FRAME |
| @findex PUSH_DUMMY_FRAME |
| Used in @samp{call_function_by_hand} to create an artificial stack frame. |
| |
| @item REGISTER_BYTES |
| @findex REGISTER_BYTES |
| The total amount of space needed to store @value{GDBN}'s copy of the machine's |
| register state. |
| |
| @item REGISTER_NAME(@var{i}) |
| @findex REGISTER_NAME |
| Return the name of register @var{i} as a string. May return @code{NULL} |
| or @code{NUL} to indicate that register @var{i} is not valid. |
| |
| @item REGISTER_NAMES |
| @findex REGISTER_NAMES |
| Deprecated in favor of @code{REGISTER_NAME}. |
| |
| @item REG_STRUCT_HAS_ADDR (@var{gcc_p}, @var{type}) |
| @findex REG_STRUCT_HAS_ADDR |
| Define this to return 1 if the given type will be passed by pointer |
| rather than directly. |
| |
| @item SAVE_DUMMY_FRAME_TOS (@var{sp}) |
| @findex SAVE_DUMMY_FRAME_TOS |
| Used in @samp{call_function_by_hand} to notify the target dependent code |
| of the top-of-stack value that will be passed to the the inferior code. |
| This is the value of the @code{SP} after both the dummy frame and space |
| for parameters/results have been allocated on the stack. |
| |
| @item SDB_REG_TO_REGNUM |
| @findex SDB_REG_TO_REGNUM |
| Define this to convert sdb register numbers into @value{GDBN} regnums. If not |
| defined, no conversion will be done. |
| |
| @item SHIFT_INST_REGS |
| @findex SHIFT_INST_REGS |
| (Only used for m88k targets.) |
| |
| @item SKIP_PERMANENT_BREAKPOINT |
| @findex SKIP_PERMANENT_BREAKPOINT |
| Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally |
| steps over a breakpoint by removing it, stepping one instruction, and |
| re-inserting the breakpoint. However, permanent breakpoints are |
| hardwired into the inferior, and can't be removed, so this strategy |
| doesn't work. Calling @code{SKIP_PERMANENT_BREAKPOINT} adjusts the processor's |
| state so that execution will resume just after the breakpoint. This |
| macro does the right thing even when the breakpoint is in the delay slot |
| of a branch or jump. |
| |
| @item SKIP_PROLOGUE (@var{pc}) |
| @findex SKIP_PROLOGUE |
| A C expression that returns the address of the ``real'' code beyond the |
| function entry prologue found at @var{pc}. |
| |
| @item SKIP_PROLOGUE_FRAMELESS_P |
| @findex SKIP_PROLOGUE_FRAMELESS_P |
| A C expression that should behave similarly, but that can stop as soon |
| as the function is known to have a frame. If not defined, |
| @code{SKIP_PROLOGUE} will be used instead. |
| |
| @item SKIP_TRAMPOLINE_CODE (@var{pc}) |
| @findex SKIP_TRAMPOLINE_CODE |
| 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. |
| |
| @item SP_REGNUM |
| @findex SP_REGNUM |
| If the stack-pointer is kept in a register, then define this macro to be |
| the number (greater than or equal to zero) of that register. |
| |
| This should only need to be defined if @code{TARGET_WRITE_SP} and |
| @code{TARGET_WRITE_SP} are not defined. |
| |
| @item STAB_REG_TO_REGNUM |
| @findex STAB_REG_TO_REGNUM |
| Define this to convert stab register numbers (as gotten from `r' |
| declarations) into @value{GDBN} regnums. If not defined, no conversion will be |
| done. |
| |
| @item STACK_ALIGN (@var{addr}) |
| @findex STACK_ALIGN |
| Define this to adjust the address to the alignment required for the |
| processor's stack. |
| |
| @item STEP_SKIPS_DELAY (@var{addr}) |
| @findex STEP_SKIPS_DELAY |
| 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, @value{GDBN} will single-step over that instruction before resuming |
| normally. Currently only defined for the Mips. |
| |
| @item STORE_RETURN_VALUE (@var{type}, @var{valbuf}) |
| @findex STORE_RETURN_VALUE |
| A C expression that stores a function return value of type @var{type}, |
| where @var{valbuf} is the address of the value to be stored. |
| |
| @item SUN_FIXED_LBRAC_BUG |
| @findex SUN_FIXED_LBRAC_BUG |
| (Used only for Sun-3 and Sun-4 targets.) |
| |
| @item SYMBOL_RELOADING_DEFAULT |
| @findex SYMBOL_RELOADING_DEFAULT |
| The default value of the ``symbol-reloading'' variable. (Never defined in |
| current sources.) |
| |
| @item TARGET_BYTE_ORDER_DEFAULT |
| @findex TARGET_BYTE_ORDER_DEFAULT |
| The ordering of bytes in the target. This must be either |
| @code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. This macro replaces |
| @code{TARGET_BYTE_ORDER} which is deprecated. |
| |
| @item TARGET_BYTE_ORDER_SELECTABLE_P |
| @findex TARGET_BYTE_ORDER_SELECTABLE_P |
| Non-zero if the target has both @code{BIG_ENDIAN} and |
| @code{LITTLE_ENDIAN} variants. This macro replaces |
| @code{TARGET_BYTE_ORDER_SELECTABLE} which is deprecated. |
| |
| @item TARGET_CHAR_BIT |
| @findex TARGET_CHAR_BIT |
| Number of bits in a char; defaults to 8. |
| |
| @item TARGET_COMPLEX_BIT |
| @findex TARGET_COMPLEX_BIT |
| Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}. |
| |
| At present this macro is not used. |
| |
| @item TARGET_DOUBLE_BIT |
| @findex TARGET_DOUBLE_BIT |
| Number of bits in a double float; defaults to @code{8 * TARGET_CHAR_BIT}. |
| |
| @item TARGET_DOUBLE_COMPLEX_BIT |
| @findex TARGET_DOUBLE_COMPLEX_BIT |
| Number of bits in a double complex; defaults to @code{2 * TARGET_DOUBLE_BIT}. |
| |
| At present this macro is not used. |
| |
| @item TARGET_FLOAT_BIT |
| @findex TARGET_FLOAT_BIT |
| Number of bits in a float; defaults to @code{4 * TARGET_CHAR_BIT}. |
| |
| @item TARGET_INT_BIT |
| @findex TARGET_INT_BIT |
| Number of bits in an integer; defaults to @code{4 * TARGET_CHAR_BIT}. |
| |
| @item TARGET_LONG_BIT |
| @findex TARGET_LONG_BIT |
| Number of bits in a long integer; defaults to @code{4 * TARGET_CHAR_BIT}. |
| |
| @item TARGET_LONG_DOUBLE_BIT |
| @findex TARGET_LONG_DOUBLE_BIT |
| Number of bits in a long double float; |
| defaults to @code{2 * TARGET_DOUBLE_BIT}. |
| |
| @item TARGET_LONG_LONG_BIT |
| @findex TARGET_LONG_LONG_BIT |
| Number of bits in a long long integer; defaults to @code{2 * TARGET_LONG_BIT}. |
| |
| @item TARGET_PTR_BIT |
| @findex TARGET_PTR_BIT |
| Number of bits in a pointer; defaults to @code{TARGET_INT_BIT}. |
| |
| @item TARGET_SHORT_BIT |
| @findex TARGET_SHORT_BIT |
| Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}. |
| |
| @item TARGET_READ_PC |
| @findex TARGET_READ_PC |
| @itemx TARGET_WRITE_PC (@var{val}, @var{pid}) |
| @findex TARGET_WRITE_PC |
| @itemx TARGET_READ_SP |
| @findex TARGET_READ_SP |
| @itemx TARGET_WRITE_SP |
| @findex TARGET_WRITE_SP |
| @itemx TARGET_READ_FP |
| @findex TARGET_READ_FP |
| @itemx TARGET_WRITE_FP |
| @findex TARGET_WRITE_FP |
| @findex read_pc |
| @findex write_pc |
| @findex read_sp |
| @findex write_sp |
| @findex read_fp |
| @findex write_fp |
| These change the behavior of @code{read_pc}, @code{write_pc}, |
| @code{read_sp}, @code{write_sp}, @code{read_fp} and @code{write_fp}. |
| For most targets, these may be left undefined. @value{GDBN} will call the read |
| and write register functions with the relevant @code{_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. |
| |
| @item TARGET_VIRTUAL_FRAME_POINTER(@var{pc}, @var{regp}, @var{offsetp}) |
| @findex TARGET_VIRTUAL_FRAME_POINTER |
| Returns a @code{(register, offset)} pair representing the virtual |
| frame pointer in use at the code address @var{pc}. If virtual |
| frame pointers are not used, a default definition simply returns |
| @code{FP_REGNUM}, with an offset of zero. |
| |
| @item USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type}) |
| @findex USE_STRUCT_CONVENTION |
| If defined, this must be an expression that is nonzero if a value of the |
| given @var{type} being returned from a function must have space |
| allocated for it on the stack. @var{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. |
| |
| @item VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p}) |
| @findex VARIABLES_INSIDE_BLOCK |
| For dbx-style debugging information, if the compiler puts variable |
| declarations inside LBRAC/RBRAC blocks, this should be defined to be |
| nonzero. @var{desc} is the value of @code{n_desc} from the |
| @code{N_RBRAC} symbol, and @var{gcc_p} is true if @value{GDBN} has noticed the |
| presence of either the @code{GCC_COMPILED_SYMBOL} or the |
| @code{GCC2_COMPILED_SYMBOL}. By default, this is 0. |
| |
| @item OS9K_VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p}) |
| @findex OS9K_VARIABLES_INSIDE_BLOCK |
| Similarly, for OS/9000. Defaults to 1. |
| @end table |
| |
| Motorola M68K target conditionals. |
| |
| @ftable @code |
| @item BPT_VECTOR |
| Define this to be the 4-bit location of the breakpoint trap vector. If |
| not defined, it will default to @code{0xf}. |
| |
| @item REMOTE_BPT_VECTOR |
| Defaults to @code{1}. |
| @end ftable |
| |
| @section Adding a New Target |
| |
| @cindex adding a target |
| The following files define a target to @value{GDBN}: |
| |
| @table @file |
| @vindex TDEPFILES |
| @item gdb/config/@var{arch}/@var{ttt}.mt |
| Contains a Makefile fragment specific to this target. Specifies what |
| object files are needed for target @var{ttt}, by defining |
| @samp{TDEPFILES=@dots{}} and @samp{TDEPLIBS=@dots{}}. Also specifies |
| the header file which describes @var{ttt}, by defining @samp{TM_FILE= |
| tm-@var{ttt}.h}. |
| |
| You can also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, @samp{TM_CDEPS}, |
| but these are now deprecated, replaced by autoconf, and may go away in |
| future versions of @value{GDBN}. |
| |
| @item gdb/config/@var{arch}/tm-@var{ttt}.h |
| (@file{tm.h} is a link to this file, created by @code{configure}). Contains |
| macro definitions about the target machine's registers, stack frame |
| format and instructions. |
| |
| @item gdb/@var{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 |
| @file{tm-@var{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. |
| |
| @item gdb/config/@var{arch}/tm-@var{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 |
| @file{tm-@var{ttt}.h}. It can be shared among many targets that use the |
| same processor. |
| |
| @item gdb/@var{arch}-tdep.c |
| Similarly, there are often common subroutines that are shared by all |
| target machines that use this particular architecture. |
| @end table |
| |
| If you are adding a new operating system for an existing CPU chip, add a |
| @file{config/tm-@var{os}.h} file that describes the operating system |
| facilities that are unusual (extra symbol table info; the breakpoint |
| instruction needed; etc.). Then write a @file{@var{arch}/tm-@var{os}.h} |
| that just @code{#include}s @file{tm-@var{arch}.h} and |
| @file{config/tm-@var{os}.h}. |
| |
| |
| @node Target Vector Definition |
| |
| @chapter Target Vector Definition |
| @cindex target vector |
| |
| The target vector defines the interface between @value{GDBN}'s |
| abstract handling of target systems, and the nitty-gritty code that |
| actually exercises control over a process or a serial port. |
| @value{GDBN} includes some 30-40 different target vectors; however, |
| each configuration of @value{GDBN} includes only a few of them. |
| |
| @section File Targets |
| |
| Both executables and core files have target vectors. |
| |
| @section Standard Protocol and Remote Stubs |
| |
| @value{GDBN}'s file @file{remote.c} talks a serial protocol to code |
| that runs in the target system. @value{GDBN} provides several sample |
| @dfn{stubs} that can be integrated into target programs or operating |
| systems for this purpose; they are named @file{*-stub.c}. |
| |
| The @value{GDBN} 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 |
| @code{trap_low}: |
| |
| @enumerate |
| @item |
| %l1 and %l2 contain pc and npc respectively at the time of the trap; |
| |
| @item |
| traps are disabled; |
| |
| @item |
| you are in the correct trap window. |
| @end enumerate |
| |
| 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 @code{exceptionHandler()}, |
| which is provided by the external environment. For instance, this could |
| set up 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 @code{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 @value{GDBN}. |
| |
| @section ROM Monitor Interface |
| |
| @section Custom Protocols |
| |
| @section Transport Layer |
| |
| @section Builtin Simulator |
| |
| |
| @node Native Debugging |
| |
| @chapter Native Debugging |
| @cindex native debugging |
| |
| Several files control @value{GDBN}'s configuration for native support: |
| |
| @table @file |
| @vindex NATDEPFILES |
| @item gdb/config/@var{arch}/@var{xyz}.mh |
| Specifies Makefile fragments needed when hosting @emph{or native} on |
| machine @var{xyz}. In particular, this lists the required |
| native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}. |
| Also specifies the header file which describes native support on |
| @var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}. You can also |
| define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS}, |
| @samp{NAT_CDEPS}, etc.; see @file{Makefile.in}. |
| |
| @item gdb/config/@var{arch}/nm-@var{xyz}.h |
| (@file{nm.h} is a link to this file, created by @code{configure}). Contains C |
| macro definitions describing the native system environment, such as |
| child process control and core file support. |
| |
| @item gdb/@var{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. |
| @end table |
| |
| 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 @file{nm-@var{xyz}.h} file. If these routines work for |
| the @var{xyz} host, you can just include the generic file's name (with |
| @samp{.o}, not @samp{.c}) in @code{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 @file{@var{xyz}-nat.c}, and put @file{@var{xyz}-nat.o} |
| into @code{NATDEPFILES}. |
| |
| @table @file |
| @item inftarg.c |
| This contains the @emph{target_ops vector} that supports Unix child |
| processes on systems which use ptrace and wait to control the child. |
| |
| @item procfs.c |
| This contains the @emph{target_ops vector} that supports Unix child |
| processes on systems which use /proc to control the child. |
| |
| @item 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. |
| |
| @item infptrace.c |
| This is the low level interface to inferior processes for systems using |
| the Unix @code{ptrace} call in a vanilla way. |
| @end table |
| |
| @section Native core file Support |
| @cindex native core files |
| |
| @table @file |
| @findex fetch_core_registers |
| @item core-aout.c::fetch_core_registers() |
| Support for reading registers out of a core file. This routine calls |
| @code{register_addr()}, see below. Now that BFD is used to read core |
| files, virtually all machines should use @code{core-aout.c}, and should |
| just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or |
| @code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}). |
| |
| @item core-aout.c::register_addr() |
| If your @code{nm-@var{xyz}.h} file defines the macro |
| @code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to |
| set @code{addr} to the offset within the @samp{user} struct of @value{GDBN} |
| register number @code{regno}. @code{blockend} is the offset within the |
| ``upage'' of @code{u.u_ar0}. If @code{REGISTER_U_ADDR} is defined, |
| @file{core-aout.c} will define the @code{register_addr()} function and |
| use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but |
| you are using the standard @code{fetch_core_registers()}, you will need |
| to define your own version of @code{register_addr()}, put it into your |
| @code{@var{xyz}-nat.c} file, and be sure @code{@var{xyz}-nat.o} is in |
| the @code{NATDEPFILES} list. If you have your own |
| @code{fetch_core_registers()}, you may not need a separate |
| @code{register_addr()}. Many custom @code{fetch_core_registers()} |
| implementations simply locate the registers themselves.@refill |
| @end table |
| |
| When making @value{GDBN} 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 |
| @file{bfd/trad-core.c}. First, use whatever @code{#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 |
| @file{machine/reg.h}), and an include file that defines whatever header |
| exists on a core file (e.g. the u-area or a @code{struct core}). Then |
| modify @code{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 @value{GDBN}, you need a matching routine called |
| @code{fetch_core_registers}. If you can use the generic one, it's in |
| @file{core-aout.c}; if not, it's in your @file{@var{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 @value{GDBN}'s ``registers'' array. |
| |
| If your system uses @file{/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. |
| |
| @section ptrace |
| |
| @section /proc |
| |
| @section win32 |
| |
| @section shared libraries |
| |
| @section Native Conditionals |
| @cindex native conditionals |
| |
| When @value{GDBN} 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 @file{nm-@var{system}.h}. |
| |
| @table @code |
| @item ATTACH_DETACH |
| @findex ATTACH_DETACH |
| If defined, then @value{GDBN} will include support for the @code{attach} and |
| @code{detach} commands. |
| |
| @item CHILD_PREPARE_TO_STORE |
| @findex 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 @file{xm-@var{system}.h} files |
| currently.] |
| |
| @item FETCH_INFERIOR_REGISTERS |
| @findex FETCH_INFERIOR_REGISTERS |
| Define this if the native-dependent code will provide its own routines |
| @code{fetch_inferior_registers} and @code{store_inferior_registers} in |
| @file{@var{host}-nat.c}. If this symbol is @emph{not} defined, and |
| @file{infptrace.c} is included in this configuration, the default |
| routines in @file{infptrace.c} are used for these functions. |
| |
| @item FILES_INFO_HOOK |
| @findex FILES_INFO_HOOK |
| (Only defined for Convex.) |
| |
| @item FP0_REGNUM |
| @findex 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, @file{/proc} support uses this |
| to decide whether floats are in use on this target. |
| |
| @item GET_LONGJMP_TARGET |
| @findex 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 |
| @file{setjmp.h} is needed to define it. |
| |
| This macro determines the target PC address that @code{longjmp} will jump to, |
| assuming that we have just stopped at a longjmp breakpoint. It takes a |
| @code{CORE_ADDR *} as argument, and stores the target PC value through this |
| pointer. It examines the current state of the machine as needed. |
| |
| @item KERNEL_U_ADDR |
| @findex KERNEL_U_ADDR |
| Define this to the address of the @code{u} structure (the ``user |
| struct'', also known as the ``u-page'') in kernel virtual memory. @value{GDBN} |
| 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. |
| |
| @item KERNEL_U_ADDR_BSD |
| @findex KERNEL_U_ADDR_BSD |
| Define this to cause @value{GDBN} to determine the address of @code{u} at |
| runtime, by using Berkeley-style @code{nlist} on the kernel's image in |
| the root directory. |
| |
| @item KERNEL_U_ADDR_HPUX |
| @findex KERNEL_U_ADDR_HPUX |
| Define this to cause @value{GDBN} to determine the address of @code{u} at |
| runtime, by using HP-style @code{nlist} on the kernel's image in the |
| root directory. |
| |
| @item ONE_PROCESS_WRITETEXT |
| @findex 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. |
| |
| @item PREPARE_TO_PROCEED (@var{select_it}) |
| @findex PREPARE_TO_PROCEED |
| This (ugly) macro allows a native configuration to customize the way the |
| @code{proceed} function in @file{infrun.c} deals with switching between |
| threads. |
| |
| In a multi-threaded task we may select another thread and then continue |
| or step. But if the old thread was stopped at a breakpoint, it will |
| immediately cause another breakpoint stop without any execution (i.e. it |
| will report a breakpoint hit incorrectly). So @value{GDBN} must step over it |
| first. |
| |
| If defined, @code{PREPARE_TO_PROCEED} should check the current thread |
| against the thread that reported the most recent event. If a step-over |
| is required, it returns TRUE. If @var{select_it} is non-zero, it should |
| reselect the old thread. |
| |
| @item PROC_NAME_FMT |
| @findex PROC_NAME_FMT |
| Defines the format for the name of a @file{/proc} device. Should be |
| defined in @file{nm.h} @emph{only} in order to override the default |
| definition in @file{procfs.c}. |
| |
| @item PTRACE_FP_BUG |
| @findex PTRACE_FP_BUG |
| See @file{mach386-xdep.c}. |
| |
| @item PTRACE_ARG3_TYPE |
| @findex PTRACE_ARG3_TYPE |
| The type of the third argument to the @code{ptrace} system call, if it |
| exists and is different from @code{int}. |
| |
| @item REGISTER_U_ADDR |
| @findex REGISTER_U_ADDR |
| Defines the offset of the registers in the ``u area''. |
| |
| @item SHELL_COMMAND_CONCAT |
| @findex SHELL_COMMAND_CONCAT |
| If defined, is a string to prefix on the shell command used to start the |
| inferior. |
| |
| @item SHELL_FILE |
| @findex SHELL_FILE |
| If defined, this is the name of the shell to use to run the inferior. |
| Defaults to @code{"/bin/sh"}. |
| |
| @item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ}) |
| @findex SOLIB_ADD |
| Define this to expand into an expression that will cause the symbols in |
| @var{filename} to be added to @value{GDBN}'s symbol table. |
| |
| @item SOLIB_CREATE_INFERIOR_HOOK |
| @findex 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. |
| |
| @item START_INFERIOR_TRAPS_EXPECTED |
| @findex START_INFERIOR_TRAPS_EXPECTED |
| When starting an inferior, @value{GDBN} 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. |
| |
| @item SVR4_SHARED_LIBS |
| @findex SVR4_SHARED_LIBS |
| Define this to indicate that SVR4-style shared libraries are in use. |
| |
| @item USE_PROC_FS |
| @findex USE_PROC_FS |
| This determines whether small routines in @file{*-tdep.c}, which |
| translate register values between @value{GDBN}'s internal |
| representation and the @file{/proc} representation, are compiled. |
| |
| @item U_REGS_OFFSET |
| @findex 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 |
| @file{infptrace.c} are being used (that is, @file{infptrace.c} is |
| configured in, and @code{FETCH_INFERIOR_REGISTERS} is not defined). If |
| the default value from @file{infptrace.c} is good enough, leave it |
| undefined. |
| |
| The default value means that u.u_ar0 @emph{points to} the location of |
| the registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means |
| that @code{u.u_ar0} @emph{is} the location of the registers. |
| |
| @item CLEAR_SOLIB |
| @findex CLEAR_SOLIB |
| See @file{objfiles.c}. |
| |
| @item DEBUG_PTRACE |
| @findex DEBUG_PTRACE |
| Define this to debug @code{ptrace} calls. |
| @end table |
| |
| |
| @node Support Libraries |
| |
| @chapter Support Libraries |
| |
| @section BFD |
| @cindex BFD library |
| |
| BFD provides support for @value{GDBN} in several ways: |
| |
| @table @emph |
| @item 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. |
| |
| @item 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). @value{GDBN} simply |
| calls BFD to read or write section @var{x} at byte offset @var{y} for |
| length @var{z}. |
| |
| @item 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. |
| |
| @item locating the symbol information |
| @value{GDBN} uses an internal interface of BFD to determine where to find the |
| symbol information in an executable file or symbol-file. @value{GDBN} itself |
| handles the reading of symbols, since BFD does not ``understand'' debug |
| symbols, but @value{GDBN} uses BFD's cached information to find the symbols, |
| string table, etc. |
| @end table |
| |
| @section opcodes |
| @cindex opcodes library |
| |
| The opcodes library provides @value{GDBN}'s disassembler. (It's a separate |
| library because it's also used in binutils, for @file{objdump}). |
| |
| @section readline |
| |
| @section mmalloc |
| |
| @section libiberty |
| |
| @section gnu-regex |
| @cindex regular expressions library |
| |
| Regex conditionals. |
| |
| @table @code |
| @item C_ALLOCA |
| |
| @item NFAILURES |
| |
| @item RE_NREGS |
| |
| @item SIGN_EXTEND_CHAR |
| |
| @item SWITCH_ENUM_BUG |
| |
| @item SYNTAX_TABLE |
| |
| @item Sword |
| |
| @item sparc |
| @end table |
| |
| @section include |
| |
| @node Coding |
| |
| @chapter Coding |
| |
| This chapter covers topics that are lower-level than the major |
| algorithms of @value{GDBN}. |
| |
| @section Cleanups |
| @cindex cleanups |
| |
| Cleanups are a structured way to deal with things that need to be done |
| later. When your code does something (like @code{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: |
| |
| @table @code |
| @item struct cleanup *@var{old_chain}; |
| Declare a variable which will hold a cleanup chain handle. |
| |
| @findex make_cleanup |
| @item @var{old_chain} = make_cleanup (@var{function}, @var{arg}); |
| Make a cleanup which will cause @var{function} to be called with |
| @var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a |
| handle that can be passed to @code{do_cleanups} or |
| @code{discard_cleanups} later. Unless you are going to call |
| @code{do_cleanups} or @code{discard_cleanups} yourself, you can ignore |
| the result from @code{make_cleanup}. |
| |
| @findex do_cleanups |
| @item do_cleanups (@var{old_chain}); |
| Perform all cleanups done since @code{make_cleanup} returned |
| @var{old_chain}. E.g.: |
| |
| @example |
| make_cleanup (a, 0); |
| old = make_cleanup (b, 0); |
| do_cleanups (old); |
| @end example |
| |
| @noindent |
| will call @code{b()} but will not call @code{a()}. The cleanup that |
| calls @code{a()} will remain in the cleanup chain, and will be done |
| later unless otherwise discarded.@refill |
| |
| @findex discard_cleanups |
| @item discard_cleanups (@var{old_chain}); |
| Same as @code{do_cleanups} except that it just removes the cleanups from |
| the chain and does not call the specified functions. |
| @end table |
| |
| Some functions, e.g. @code{fputs_filtered()} or @code{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 |
| @samp{longjmp} instead). |
| |
| @section Wrapping Output Lines |
| @cindex line wrap in output |
| |
| @findex wrap_here |
| Output that goes through @code{printf_filtered} or @code{fputs_filtered} |
| or @code{fputs_demangled} needs only to have calls to @code{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 @code{wrap_here} is an indentation string which is |
| printed @emph{only} if the line breaks there. This argument is saved |
| away and used later. It must remain valid until the next call to |
| @code{wrap_here} or until a newline has been printed through the |
| @code{*_filtered} functions. Don't pass in a local variable and then |
| return! |
| |
| It is usually best to call @code{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 (@code{printf}) output. Symbol reading routines that |
| print warnings are a good example. |
| |
| @section @value{GDBN} Coding Standards |
| @cindex coding standards |
| |
| @value{GDBN} follows the GNU coding standards, as described in |
| @file{etc/standards.texi}. This file is also available for anonymous |
| FTP from GNU archive sites. @value{GDBN} takes a strict interpretation of the |
| standard; in general, when the GNU standard recommends a practice but |
| does not require it, @value{GDBN} requires it. |
| |
| @value{GDBN} follows an additional set of coding standards specific to |
| @value{GDBN}, as described in the following sections. |
| |
| @cindex compiler warnings |
| You can configure with @samp{--enable-build-warnings} or |
| @samp{--enable-gdb-build-warnings} to get GCC to check on a number of |
| these rules. @value{GDBN} sources ought not to engender any complaints, |
| unless they are caused by bogus host systems. (The exact set of enabled |
| warnings is currently @samp{-Wimplicit -Wreturn-type -Wcomment |
| -Wtrigraphs -Wformat -Wparentheses -Wpointer-arith -Wuninitialized}. |
| |
| @subsection Formatting |
| |
| @cindex source code 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 |
| @code{diff} and @code{patch} utilities. |
| |
| @subsection Comments |
| |
| @cindex comment formatting |
| The standard GNU requirements on comments must be followed strictly. |
| |
| Block comments must appear in the following form, with no @samp{/*}- or |
| @samp{*/}-only lines, and no leading @samp{*}: |
| |
| @example |
| /* 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 @value{GDBN} should read more commands. */ |
| @end example |
| |
| (Note that this format is encouraged by Emacs; tabbing for a multi-line |
| comment works correctly, and @kbd{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. |
| |
| @subsection C Usage |
| |
| @cindex C data types |
| 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. |
| |
| @cindex function usage |
| Use functions freely. There are only a handful of compute-bound areas |
| in @value{GDBN} that might be affected by the overhead of a function |
| call, mainly in symbol reading. Most of @value{GDBN}'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. |
| |
| @subsection Function Prototypes |
| |
| @cindex function prototypes |
| Prototypes must be used to @emph{declare} functions, and may be used |
| to @emph{define} them. Prototypes for @value{GDBN} functions must |
| include both the argument type and name, with the name matching that |
| used in the actual function definition. |
| |
| All external functions should have a declaration in a header file that |
| callers include, except for @code{_initialize_*} functions, which must |
| be external so that @file{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. |
| |
| @subsection Clean Design |
| |
| @cindex design |
| In addition to getting the syntax right, there's the little question of |
| semantics. Some things are done in certain ways in @value{GDBN} because long |
| experience has shown that the more obvious ways caused various kinds of |
| trouble. |
| |
| @cindex assumptions about targets |
| You can't assume the byte order of anything that comes from a target |
| (including @var{value}s, object files, and instructions). Such things |
| must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in |
| @value{GDBN}, or one of the swap routines defined in @file{bfd.h}, |
| such as @code{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 @code{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. |
| |
| @cindex portability |
| Insertion of new @code{#ifdef}'s will be frowned upon. It's much better |
| to write the code portably than to conditionalize it for various |
| systems. |
| |
| @cindex system dependencies |
| New @code{#ifdef}'s which test for specific compilers or manufacturers |
| or operating systems are unacceptable. All @code{#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: |
| |
| @example |
| #ifdef WRANGLE_SIGNALS |
| WRANGLE_SIGNALS (signo); |
| #endif |
| @end example |
| |
| In your host, target, or native configuration file, as appropriate, |
| define @code{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 @code{#ifdef}, as above, is the preferred way to do this, |
| but sometimes that gets convoluted, in which case use |
| |
| @example |
| #ifndef SPECIAL_FOO_HANDLING |
| #define SPECIAL_FOO_HANDLING(pc, sp) (0) |
| #endif |
| @end example |
| |
| @noindent |
| where the macro is used or in an appropriate header file. |
| |
| Whether to include a @dfn{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 @code{get_saved_register}. All machines that @value{GDBN} 2.8 ran on |
| just needed the @code{FRAME_FIND_SAVED_REGS} hook to find the saved |
| registers. Then the SPARC and Pyramid came along, and |
| @code{HAVE_REGISTER_WINDOWS} and @code{REGISTER_IN_WINDOW_P} were |
| introduced. Then the 29k and 88k required the @code{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 @code{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 @value{GDBN} along a particular interface is with an |
| attribute struct. For example, @value{GDBN} has been generalized to handle |
| multiple kinds of remote interfaces---not by @code{#ifdef}s everywhere, but |
| by defining the @code{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., |
| @code{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 @value{GDBN}'s access to multiple source languages. |
| |
| Please avoid duplicating code. For example, in @value{GDBN} 3.x all |
| the code interfacing between @code{ptrace} and the rest of |
| @value{GDBN} was duplicated in @file{*-dep.c}, and so changing |
| something was very painful. In @value{GDBN} 4.x, these have all been |
| consolidated into @file{infptrace.c}. @file{infptrace.c} can deal |
| with variations between systems the same way any system-independent |
| file would (hooks, @code{#if defined}, etc.), and machines which are |
| radically different don't need to use @file{infptrace.c} at all. |
| |
| Don't put debugging @code{printf}s in the code. |
| |
| @node Porting GDB |
| |
| @chapter Porting @value{GDBN} |
| @cindex porting to new machines |
| |
| Most of the work in making @value{GDBN} compile on a new machine is in |
| specifying the configuration of the machine. This is done in a |
| dizzying variety of header files and configuration scripts, which we |
| hope to make more sensible soon. Let's say your new host is called an |
| @var{xyz} (e.g., @samp{sun4}), and its full three-part configuration |
| name is @code{@var{arch}-@var{xvend}-@var{xos}} (e.g., |
| @samp{sparc-sun-sunos4}). In particular: |
| |
| @itemize @bullet |
| @item |
| In the top level directory, edit @file{config.sub} and add @var{arch}, |
| @var{xvend}, and @var{xos} to the lists of supported architectures, |
| vendors, and operating systems near the bottom of the file. Also, add |
| @var{xyz} as an alias that maps to |
| @code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by |
| running |
| |
| @example |
| ./config.sub @var{xyz} |
| @end example |
| |
| @noindent |
| and |
| |
| @example |
| ./config.sub @code{@var{arch}-@var{xvend}-@var{xos}} |
| @end example |
| |
| @noindent |
| which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}} |
| and no error messages. |
| |
| @noindent |
| You need to port BFD, if that hasn't been done already. Porting BFD is |
| beyond the scope of this manual. |
| |
| @item |
| To configure @value{GDBN} itself, edit @file{gdb/configure.host} to recognize |
| your system and set @code{gdb_host} to @var{xyz}, and (unless your |
| desired target is already available) also edit @file{gdb/configure.tgt}, |
| setting @code{gdb_target} to something appropriate (for instance, |
| @var{xyz}). |
| |
| @item |
| Finally, you'll need to specify and define @value{GDBN}'s host-, native-, and |
| target-dependent @file{.h} and @file{.c} files used for your |
| configuration. |
| @end itemize |
| |
| @section Configuring @value{GDBN} for Release |
| |
| @cindex preparing a release |
| @cindex making a distribution tarball |
| From the top level directory (containing @file{gdb}, @file{bfd}, |
| @file{libiberty}, and so on): |
| |
| @example |
| make -f Makefile.in gdb.tar.gz |
| @end example |
| |
| @noindent |
| This will properly configure, clean, rebuild any files that are |
| distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}), |
| and will then make a tarfile. (If the top level directory has already |
| been configured, you can just do @code{make gdb.tar.gz} instead.) |
| |
| This procedure requires: |
| |
| @itemize @bullet |
| |
| @item |
| symbolic links; |
| |
| @item |
| @code{makeinfo} (texinfo2 level); |
| |
| @item |
| @TeX{}; |
| |
| @item |
| @code{dvips}; |
| |
| @item |
| @code{yacc} or @code{bison}. |
| @end itemize |
| |
| @noindent |
| @dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.). |
| |
| @subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION |
| |
| @file{gdb.texinfo} is currently marked up using the texinfo-2 macros, |
| which are not yet a default for anything (but we have to start using |
| them sometime). |
| |
| For making paper, the only thing this implies is the right generation of |
| @file{texinfo.tex} needs to be included in the distribution. |
| |
| For making info files, however, rather than duplicating the texinfo2 |
| distribution, generate @file{gdb-all.texinfo} locally, and include the |
| files @file{gdb.info*} in the distribution. Note the plural; |
| @code{makeinfo} will split the document into one overall file and five |
| or so included files. |
| |
| @node Testsuite |
| |
| @chapter Testsuite |
| @cindex test suite |
| |
| The testsuite is an important component of the @value{GDBN} package. |
| While it is always worthwhile to encourage user testing, in practice |
| this is rarely sufficient; users typically use only a small subset of |
| the available commands, and it has proven all too common for a change |
| to cause a significant regression that went unnoticed for some time. |
| |
| The @value{GDBN} testsuite uses the DejaGNU testing framework. |
| DejaGNU is built using @code{Tcl} and @code{expect}. The tests |
| themselves are calls to various @code{Tcl} procs; the framework runs all the |
| procs and summarizes the passes and fails. |
| |
| @section Using the Testsuite |
| |
| @cindex running the test suite |
| To run the testsuite, simply go to the @value{GDBN} object directory (or to the |
| testsuite's objdir) and type @code{make check}. This just sets up some |
| environment variables and invokes DejaGNU's @code{runtest} script. While |
| the testsuite is running, you'll get mentions of which test file is in use, |
| and a mention of any unexpected passes or fails. When the testsuite is |
| finished, you'll get a summary that looks like this: |
| |
| @example |
| === gdb Summary === |
| |
| # of expected passes 6016 |
| # of unexpected failures 58 |
| # of unexpected successes 5 |
| # of expected failures 183 |
| # of unresolved testcases 3 |
| # of untested testcases 5 |
| @end example |
| |
| The ideal test run consists of expected passes only; however, reality |
| conspires to keep us from this ideal. Unexpected failures indicate |
| real problems, whether in @value{GDBN} or in the testsuite. Expected |
| failures are still failures, but ones which have been decided are too |
| hard to deal with at the time; for instance, a test case might work |
| everywhere except on AIX, and there is no prospect of the AIX case |
| being fixed in the near future. Expected failures should not be added |
| lightly, since you may be masking serious bugs in @value{GDBN}. |
| Unexpected successes are expected fails that are passing for some |
| reason, while unresolved and untested cases often indicate some minor |
| catastrophe, such as the compiler being unable to deal with a test |
| program. |
| |
| When making any significant change to @value{GDBN}, you should run the |
| testsuite before and after the change, to confirm that there are no |
| regressions. Note that truly complete testing would require that you |
| run the testsuite with all supported configurations and a variety of |
| compilers; however this is more than really necessary. In many cases |
| testing with a single configuration is sufficient. Other useful |
| options are to test one big-endian (Sparc) and one little-endian (x86) |
| host, a cross config with a builtin simulator (powerpc-eabi, |
| mips-elf), or a 64-bit host (Alpha). |
| |
| If you add new functionality to @value{GDBN}, please consider adding |
| tests for it as well; this way future @value{GDBN} hackers can detect |
| and fix their changes that break the functionality you added. |
| Similarly, if you fix a bug that was not previously reported as a test |
| failure, please add a test case for it. Some cases are extremely |
| difficult to test, such as code that handles host OS failures or bugs |
| in particular versions of compilers, and it's OK not to try to write |
| tests for all of those. |
| |
| @section Testsuite Organization |
| |
| @cindex test suite organization |
| The testsuite is entirely contained in @file{gdb/testsuite}. While the |
| testsuite includes some makefiles and configury, these are very minimal, |
| and used for little besides cleaning up, since the tests themselves |
| handle the compilation of the programs that @value{GDBN} will run. The file |
| @file{testsuite/lib/gdb.exp} contains common utility procs useful for |
| all @value{GDBN} tests, while the directory @file{testsuite/config} contains |
| configuration-specific files, typically used for special-purpose |
| definitions of procs like @code{gdb_load} and @code{gdb_start}. |
| |
| The tests themselves are to be found in @file{testsuite/gdb.*} and |
| subdirectories of those. The names of the test files must always end |
| with @file{.exp}. DejaGNU collects the test files by wildcarding |
| in the test directories, so both subdirectories and individual files |
| get chosen and run in alphabetical order. |
| |
| The following table lists the main types of subdirectories and what they |
| are for. Since DejaGNU finds test files no matter where they are |
| located, and since each test file sets up its own compilation and |
| execution environment, this organization is simply for convenience and |
| intelligibility. |
| |
| @table @file |
| @item gdb.base |
| This is the base testsuite. The tests in it should apply to all |
| configurations of @value{GDBN} (but generic native-only tests may live here). |
| The test programs should be in the subset of C that is valid K&R, |
| ANSI/ISO, and C++ (@code{#ifdef}s are allowed if necessary, for instance |
| for prototypes). |
| |
| @item gdb.@var{lang} |
| Language-specific tests for any language @var{lang} besides C. Examples are |
| @file{gdb.c++} and @file{gdb.java}. |
| |
| @item gdb.@var{platform} |
| Non-portable tests. The tests are specific to a specific configuration |
| (host or target), such as HP-UX or eCos. Example is @file{gdb.hp}, for |
| HP-UX. |
| |
| @item gdb.@var{compiler} |
| Tests specific to a particular compiler. As of this writing (June |
| 1999), there aren't currently any groups of tests in this category that |
| couldn't just as sensibly be made platform-specific, but one could |
| imagine a @file{gdb.gcc}, for tests of @value{GDBN}'s handling of GCC |
| extensions. |
| |
| @item gdb.@var{subsystem} |
| Tests that exercise a specific @value{GDBN} subsystem in more depth. For |
| instance, @file{gdb.disasm} exercises various disassemblers, while |
| @file{gdb.stabs} tests pathways through the stabs symbol reader. |
| @end table |
| |
| @section Writing Tests |
| @cindex writing tests |
| |
| In many areas, the @value{GDBN} tests are already quite comprehensive; you |
| should be able to copy existing tests to handle new cases. |
| |
| You should try to use @code{gdb_test} whenever possible, since it |
| includes cases to handle all the unexpected errors that might happen. |
| However, it doesn't cost anything to add new test procedures; for |
| instance, @file{gdb.base/exprs.exp} defines a @code{test_expr} that |
| calls @code{gdb_test} multiple times. |
| |
| Only use @code{send_gdb} and @code{gdb_expect} when absolutely |
| necessary, such as when @value{GDBN} has several valid responses to a command. |
| |
| The source language programs do @emph{not} need to be in a consistent |
| style. Since @value{GDBN} is used to debug programs written in many different |
| styles, it's worth having a mix of styles in the testsuite; for |
| instance, some @value{GDBN} bugs involving the display of source lines would |
| never manifest themselves if the programs used GNU coding style |
| uniformly. |
| |
| @node Hints |
| |
| @chapter Hints |
| |
| Check the @file{README} file, it often has useful information that does not |
| appear anywhere else in the directory. |
| |
| @menu |
| * Getting Started:: Getting started working on @value{GDBN} |
| * Debugging GDB:: Debugging @value{GDBN} with itself |
| @end menu |
| |
| @node Getting Started,,, Hints |
| |
| @section Getting Started |
| |
| @value{GDBN} is a large and complicated program, and if you first starting to |
| work on it, it can be hard to know where to start. Fortunately, if you |
| know how to go about it, there are ways to figure out what is going on. |
| |
| This manual, the @value{GDBN} Internals manual, has information which applies |
| generally to many parts of @value{GDBN}. |
| |
| Information about particular functions or data structures are located in |
| comments with those functions or data structures. If you run across a |
| function or a global variable which does not have a comment correctly |
| explaining what is does, this can be thought of as a bug in @value{GDBN}; feel |
| free to submit a bug report, with a suggested comment if you can figure |
| out what the comment should say. If you find a comment which is |
| actually wrong, be especially sure to report that. |
| |
| Comments explaining the function of macros defined in host, target, or |
| native dependent files can be in several places. Sometimes they are |
| repeated every place the macro is defined. Sometimes they are where the |
| macro is used. Sometimes there is a header file which supplies a |
| default definition of the macro, and the comment is there. This manual |
| also documents all the available macros. |
| @c (@pxref{Host Conditionals}, @pxref{Target |
| @c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete |
| @c Conditionals}) |
| |
| Start with the header files. Once you have some idea of how |
| @value{GDBN}'s internal symbol tables are stored (see @file{symtab.h}, |
| @file{gdbtypes.h}), you will find it much easier to understand the |
| code which uses and creates those symbol tables. |
| |
| You may wish to process the information you are getting somehow, to |
| enhance your understanding of it. Summarize it, translate it to another |
| language, add some (perhaps trivial or non-useful) feature to @value{GDBN}, use |
| the code to predict what a test case would do and write the test case |
| and verify your prediction, etc. If you are reading code and your eyes |
| are starting to glaze over, this is a sign you need to use a more active |
| approach. |
| |
| Once you have a part of @value{GDBN} to start with, you can find more |
| specifically the part you are looking for by stepping through each |
| function with the @code{next} command. Do not use @code{step} or you |
| will quickly get distracted; when the function you are stepping through |
| calls another function try only to get a big-picture understanding |
| (perhaps using the comment at the beginning of the function being |
| called) of what it does. This way you can identify which of the |
| functions being called by the function you are stepping through is the |
| one which you are interested in. You may need to examine the data |
| structures generated at each stage, with reference to the comments in |
| the header files explaining what the data structures are supposed to |
| look like. |
| |
| Of course, this same technique can be used if you are just reading the |
| code, rather than actually stepping through it. The same general |
| principle applies---when the code you are looking at calls something |
| else, just try to understand generally what the code being called does, |
| rather than worrying about all its details. |
| |
| @cindex command implementation |
| A good place to start when tracking down some particular area is with |
| a command which invokes that feature. Suppose you want to know how |
| single-stepping works. As a @value{GDBN} user, you know that the |
| @code{step} command invokes single-stepping. The command is invoked |
| via command tables (see @file{command.h}); by convention the function |
| which actually performs the command is formed by taking the name of |
| the command and adding @samp{_command}, or in the case of an |
| @code{info} subcommand, @samp{_info}. For example, the @code{step} |
| command invokes the @code{step_command} function and the @code{info |
| display} command invokes @code{display_info}. When this convention is |
| not followed, you might have to use @code{grep} or @kbd{M-x |
| tags-search} in emacs, or run @value{GDBN} on itself and set a |
| breakpoint in @code{execute_command}. |
| |
| @cindex @code{bug-gdb} mailing list |
| If all of the above fail, it may be appropriate to ask for information |
| on @code{bug-gdb}. But @emph{never} post a generic question like ``I was |
| wondering if anyone could give me some tips about understanding |
| @value{GDBN}''---if we had some magic secret we would put it in this manual. |
| Suggestions for improving the manual are always welcome, of course. |
| |
| @node Debugging GDB,,,Hints |
| |
| @section Debugging @value{GDBN} with itself |
| @cindex debugging @value{GDBN} |
| |
| If @value{GDBN} is limping on your machine, this is the preferred way to get it |
| fully functional. Be warned that in some ancient Unix systems, like |
| Ultrix 4.2, a program can't be running in one process while it is being |
| debugged in another. Rather than typing the command @kbd{@w{./gdb |
| ./gdb}}, which works on Suns and such, you can copy @file{gdb} to |
| @file{gdb2} and then type @kbd{@w{./gdb ./gdb2}}. |
| |
| When you run @value{GDBN} in the @value{GDBN} source directory, it will read a |
| @file{.gdbinit} file that sets up some simple things to make debugging |
| gdb easier. The @code{info} command, when executed without a subcommand |
| in a @value{GDBN} being debugged by gdb, will pop you back up to the top level |
| gdb. See @file{.gdbinit} for details. |
| |
| If you use emacs, you will probably want to do a @code{make TAGS} after |
| you configure your distribution; this will put the machine dependent |
| routines for your local machine where they will be accessed first by |
| @kbd{M-.} |
| |
| Also, make sure that you've either compiled @value{GDBN} with your local cc, or |
| have run @code{fixincludes} if you are compiling with gcc. |
| |
| @section Submitting Patches |
| |
| @cindex submitting patches |
| Thanks for thinking of offering your changes back to the community of |
| @value{GDBN} users. In general we like to get well designed enhancements. |
| Thanks also for checking in advance about the best way to transfer the |
| changes. |
| |
| The @value{GDBN} maintainers will only install ``cleanly designed'' patches. |
| This manual summarizes what we believe to be clean design for @value{GDBN}. |
| |
| If the maintainers don't have time to put the patch in when it arrives, |
| or if there is any question about a patch, it goes into a large queue |
| with everyone else's patches and bug reports. |
| |
| @cindex legal papers for code contributions |
| The legal issue is that to incorporate substantial changes requires a |
| copyright assignment from you and/or your employer, granting ownership |
| of the changes to the Free Software Foundation. You can get the |
| standard documents for doing this by sending mail to @code{gnu@@gnu.org} |
| and asking for it. We recommend that people write in "All programs |
| owned by the Free Software Foundation" as "NAME OF PROGRAM", so that |
| changes in many programs (not just @value{GDBN}, but GAS, Emacs, GCC, |
| etc) can be |
| contributed with only one piece of legalese pushed through the |
| bureacracy and filed with the FSF. We can't start merging changes until |
| this paperwork is received by the FSF (their rules, which we follow |
| since we maintain it for them). |
| |
| Technically, the easiest way to receive changes is to receive each |
| feature as a small context diff or unidiff, suitable for @code{patch}. |
| Each message sent to me should include the changes to C code and |
| header files for a single feature, plus @file{ChangeLog} entries for |
| each directory where files were modified, and diffs for any changes |
| needed to the manuals (@file{gdb/doc/gdb.texinfo} or |
| @file{gdb/doc/gdbint.texinfo}). If there are a lot of changes for a |
| single feature, they can be split down into multiple messages. |
| |
| In this way, if we read and like the feature, we can add it to the |
| sources with a single patch command, do some testing, and check it in. |
| If you leave out the @file{ChangeLog}, we have to write one. If you leave |
| out the doc, we have to puzzle out what needs documenting. Etc., etc. |
| |
| The reason to send each change in a separate message is that we will not |
| install some of the changes. They'll be returned to you with questions |
| or comments. If we're doing our job correctly, the message back to you |
| will say what you have to fix in order to make the change acceptable. |
| The reason to have separate messages for separate features is so that |
| the acceptable changes can be installed while one or more changes are |
| being reworked. If multiple features are sent in a single message, we |
| tend to not put in the effort to sort out the acceptable changes from |
| the unacceptable, so none of the features get installed until all are |
| acceptable. |
| |
| If this sounds painful or authoritarian, well, it is. But we get a lot |
| of bug reports and a lot of patches, and many of them don't get |
| installed because we don't have the time to finish the job that the bug |
| reporter or the contributor could have done. Patches that arrive |
| complete, working, and well designed, tend to get installed on the day |
| they arrive. The others go into a queue and get installed as time |
| permits, which, since the maintainers have many demands to meet, may not |
| be for quite some time. |
| |
| Please send patches directly to |
| @email{gdb-patches@@sourceware.cygnus.com, the @value{GDBN} maintainers}. |
| |
| @section Obsolete Conditionals |
| @cindex obsolete code |
| |
| Fragments of old code in @value{GDBN} sometimes reference or set the following |
| configuration macros. They should not be used by new code, and old uses |
| should be removed as those parts of the debugger are otherwise touched. |
| |
| @table @code |
| @item STACK_END_ADDR |
| This macro used to define where the end of the stack appeared, for use |
| in interpreting core file formats that don't record this address in the |
| core file itself. This information is now configured in BFD, and @value{GDBN} |
| gets the info portably from there. The values in @value{GDBN}'s configuration |
| files should be moved into BFD configuration files (if needed there), |
| and deleted from all of @value{GDBN}'s config files. |
| |
| Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR |
| is so old that it has never been converted to use BFD. Now that's old! |
| |
| @item PYRAMID_CONTROL_FRAME_DEBUGGING |
| pyr-xdep.c |
| @item PYRAMID_CORE |
| pyr-xdep.c |
| @item PYRAMID_PTRACE |
| pyr-xdep.c |
| |
| @item REG_STACK_SEGMENT |
| exec.c |
| |
| @end table |
| |
| @node Index |
| @unnumbered Index |
| |
| @printindex cp |
| |
| @c TeX can handle the contents at the start but makeinfo 3.12 can not |
| @ifinfo |
| @contents |
| @end ifinfo |
| @ifhtml |
| @contents |
| @end ifhtml |
| |
| @bye |