| 1 | \input texinfo |
| 2 | @setfilename gdb-internals |
| 3 | @ifinfo |
| 4 | This file documents the internals of the GNU debugger GDB. |
| 5 | |
| 6 | Copyright (C) 1990, 1991 Free Software Foundation, Inc. |
| 7 | Contributed by Cygnus Support. Written by John Gilmore. |
| 8 | |
| 9 | Permission is granted to make and distribute verbatim copies of |
| 10 | this manual provided the copyright notice and this permission notice |
| 11 | are preserved on all copies. |
| 12 | |
| 13 | @ignore |
| 14 | Permission is granted to process this file through Tex and print the |
| 15 | results, provided the printed document carries copying permission |
| 16 | notice identical to this one except for the removal of this paragraph |
| 17 | (this paragraph not being relevant to the printed manual). |
| 18 | |
| 19 | @end ignore |
| 20 | Permission is granted to copy or distribute modified versions of this |
| 21 | manual under the terms of the GPL (for which purpose this text may be |
| 22 | regarded as a program in the language TeX). |
| 23 | @end ifinfo |
| 24 | |
| 25 | @setchapternewpage odd |
| 26 | @settitle GDB Internals |
| 27 | @titlepage |
| 28 | @title{Working in GDB} |
| 29 | @subtitle{A guide to the internals of the GNU debugger} |
| 30 | @author John Gilmore |
| 31 | @author Cygnus Support |
| 32 | @page |
| 33 | @tex |
| 34 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ |
| 35 | \xdef\manvers{\$Revision$} % For use in headers, footers too |
| 36 | {\parskip=0pt |
| 37 | \hfill Cygnus Support\par |
| 38 | \hfill \manvers\par |
| 39 | \hfill \TeX{}info \texinfoversion\par |
| 40 | } |
| 41 | @end tex |
| 42 | |
| 43 | @vskip 0pt plus 1filll |
| 44 | Copyright @copyright{} 1990, 1991 Free Software Foundation, Inc. |
| 45 | |
| 46 | Permission is granted to make and distribute verbatim copies of |
| 47 | this manual provided the copyright notice and this permission notice |
| 48 | are preserved on all copies. |
| 49 | |
| 50 | @end titlepage |
| 51 | |
| 52 | @node Top, Cleanups, (dir), (dir) |
| 53 | |
| 54 | @menu |
| 55 | * Cleanups:: Cleanups |
| 56 | * Wrapping:: Wrapping output lines |
| 57 | * Releases:: Configuring GDB for release |
| 58 | * README:: The README file |
| 59 | * New Architectures:: Defining a new host or target architecture |
| 60 | * Host versus Targt:: What features are in which files |
| 61 | |
| 62 | @end menu |
| 63 | |
| 64 | @node Cleanups, Wrapping, Top, Top |
| 65 | @chapter Cleanups |
| 66 | |
| 67 | Cleanups are a structured way to deal with things that need to be done |
| 68 | later. When your code does something (like malloc some memory, or open |
| 69 | a file) that needs to be undone later (e.g. free the memory or close |
| 70 | the file), it can make a cleanup. The cleanup will be done at some |
| 71 | future point: when the command is finished, when an error occurs, or |
| 72 | when your code decides it's time to do cleanups. |
| 73 | |
| 74 | You can also discard cleanups, that is, throw them away without doing |
| 75 | what they say. This is only done if you ask that it be done. |
| 76 | |
| 77 | Syntax: |
| 78 | |
| 79 | @table @code |
| 80 | @item old_chain = make_cleanup (function, arg); |
| 81 | This makes a cleanup which will cause FUNCTION to be called with ARG |
| 82 | (a char *) later. The result, OLD_CHAIN, is a handle that can be |
| 83 | passed to do_cleanups or discard_cleanups later. Unless you are |
| 84 | going to call do_cleanups or discard_cleanups yourself, |
| 85 | you can ignore the result from make_cleanup. |
| 86 | |
| 87 | |
| 88 | @item do_cleanups (old_chain); |
| 89 | Performs all cleanups done since make_cleanup returned OLD_CHAIN. |
| 90 | E.g.: make_cleanup (a, 0); old = make_cleanup (b, 0); do_cleanups (old); |
| 91 | will call b() but will not call a(). The cleanup that calls a() will remain |
| 92 | in the cleanup chain, and will be done later unless otherwise discarded. |
| 93 | |
| 94 | @item discard_cleanups (old_chain); |
| 95 | Same as do_cleanups except that it just removes the cleanups from the |
| 96 | chain and does not call the specified functions. |
| 97 | |
| 98 | @end table |
| 99 | |
| 100 | Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify that they |
| 101 | ``should not be called when cleanups are not in place''. This means |
| 102 | that any actions you need to reverse in the case of an error or |
| 103 | interruption must be on the cleanup chain before you call these functions, |
| 104 | since they might never return to your code (they @samp{longjmp} instead). |
| 105 | |
| 106 | |
| 107 | @node Wrapping, Releases, Cleanups, Top |
| 108 | @chapter Wrapping output lines |
| 109 | |
| 110 | Output that goes through printf_filtered or fputs_filtered or |
| 111 | fputs_demangled needs only to have calls to wrap_here() added |
| 112 | in places that would be good breaking points. The utility routines |
| 113 | will take care of actually wrapping if the line width is exceeded. |
| 114 | |
| 115 | The argument to wrap_here() is an indentation string which is printed |
| 116 | ONLY if the line breaks there. This argument is saved away and used |
| 117 | later. It must remain valid until the next call to wrap_here() or |
| 118 | until a newline has been printed through the *_filtered functions. |
| 119 | Don't pass in a local variable and then return! |
| 120 | |
| 121 | It is usually best to call wrap_here() after printing a comma or space. |
| 122 | If you call it before printing a space, make sure that your indentation |
| 123 | properly accounts for the leading space that will print if the line wraps |
| 124 | there. |
| 125 | |
| 126 | Any function or set of functions that produce filtered output must finish |
| 127 | by printing a newline, to flush the wrap buffer, before switching to |
| 128 | unfiltered ("printf") output. Symbol reading routines that print |
| 129 | warnings are a good example. |
| 130 | |
| 131 | |
| 132 | @node Releases, README, Wrapping, Top |
| 133 | @chapter Configuring GDB for release |
| 134 | |
| 135 | |
| 136 | GDB should be released after doing @samp{config.gdb none} in the top level |
| 137 | directory. This will leave a makefile there, but no tm- or xm- files. |
| 138 | The makefile is needed, for example, for @samp{make gdb.tar.Z}@dots{} If you |
| 139 | have tm- or xm-files in the main source directory, C's include rules |
| 140 | cause them to be used in preference to tm- and xm-files in the |
| 141 | subdirectories where the user will actually configure and build the |
| 142 | binaries. |
| 143 | |
| 144 | @samp{config.gdb none} is also a good way to rebuild the top level Makefile |
| 145 | after changing Makefile.dist, alldeps.mak, etc. |
| 146 | |
| 147 | |
| 148 | |
| 149 | @node README, New Architectures, Releases, Top |
| 150 | @chapter The README file |
| 151 | |
| 152 | |
| 153 | Check the README file, it often has useful information that does not |
| 154 | appear anywhere else in the directory. |
| 155 | |
| 156 | |
| 157 | |
| 158 | @node New Architectures, Host versus Target, README, Top |
| 159 | @chapter Defining a new host or target architecture |
| 160 | |
| 161 | |
| 162 | When building support for a new host and/or target, this will help you |
| 163 | organize where to put the various parts. @var{ARCH} stands for the |
| 164 | architecture involved. |
| 165 | |
| 166 | Object files needed when the host system is an @var{ARCH} are listed in |
| 167 | the file @file{xconfig/@var{ARCH}}, in the Makefile macro @samp{XDEPFILES |
| 168 | = }@dots{}. You can also define XXXXXX in there. |
| 169 | |
| 170 | There are some ``generic'' versions of routines that can be used by |
| 171 | various host systems. If these routines work for the @var{ARCH} host, |
| 172 | you can just include the generic file's name (with .o, not .c) in |
| 173 | @code{XDEPFILES}. Otherwise, you will need to write routines that |
| 174 | perform the same functions as the generic file, put them into |
| 175 | @code{@var{ARCH}-xdep.c}, and put @code{@var{ARCH}-xdep.o} into |
| 176 | @code{XDEPFILES}. These generic host support files include: |
| 177 | |
| 178 | @example |
| 179 | coredep.c, coredep.o |
| 180 | @end example |
| 181 | |
| 182 | @table @code |
| 183 | @item fetch_core_registers() |
| 184 | Support for reading registers out of a core file. This routine calls |
| 185 | @code{register_addr(}), see below. |
| 186 | |
| 187 | @item register_addr() |
| 188 | If your @code{xm-@var{ARCH}.h} file defines the macro @code{REGISTER_U_ADDR(reg)} to be the |
| 189 | offset within the @samp{user} struct of a register (represented as a GDB |
| 190 | register number), @file{coredep.c} will define the @code{register_addr()} function |
| 191 | and use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but |
| 192 | you are using the standard @code{fetch_core_registers}, you |
| 193 | will need to define your own version of @code{register_addr}, put it into |
| 194 | your @code{@var{ARCH}-xdep.c} file, and be sure @code{@var{ARCH}-xdep.o} is in the @code{XDEPFILES} list. |
| 195 | If you have your own @code{fetch_core_registers}, you only need to define |
| 196 | @code{register_addr} if your @code{fetch_core_registers} calls it. Many custom |
| 197 | @code{fetch_core_registers} implementations simply locate the registers |
| 198 | themselves. |
| 199 | @end table |
| 200 | |
| 201 | Files needed when the target system is an @var{ARCH} are listed in the file |
| 202 | @file{tconfig/@var{ARCH}}, in the @code{Makefile} macro @samp{TDEPFILES = }@dots{}. You can also |
| 203 | define XXXXXX in there. |
| 204 | |
| 205 | Similar generic support files for target systems are: |
| 206 | |
| 207 | @example |
| 208 | exec.c, exec.o: |
| 209 | @end example |
| 210 | |
| 211 | This file defines functions for accessing files that are executable |
| 212 | on the target system. These functions open and examine an exec file, |
| 213 | extract data from one, write data to one, print information about one, |
| 214 | etc. Now that executable files are handled with BFD, every architecture |
| 215 | should be able to use the generic exec.c rather than its own custom code. |
| 216 | |
| 217 | @node Host versus Target, , README, Top |
| 218 | @chapter What is considered ``host-dependent'' versus ``target-dependent''? |
| 219 | |
| 220 | The xconfig/*, xm-*.h and *-xdep.c files are for host support. The |
| 221 | question is, what features or aspects of a debugging or cross-debugging |
| 222 | environment are considered to be ``host'' support. |
| 223 | |
| 224 | Defines and include files needed to build on the host are host support. |
| 225 | Examples are tty support, system defined types, host byte order, host |
| 226 | float format. |
| 227 | |
| 228 | Unix child process support is considered an aspect of the host. Since |
| 229 | when you fork on the host you are still on the host, the various macros |
| 230 | needed for finding the registers in the upage, running ptrace, and such |
| 231 | are all in the host-dependent files. |
| 232 | |
| 233 | This is still somewhat of a grey area; I (John Gilmore) didn't do the |
| 234 | xm- and tm- split for gdb (it was done by Jim Kingdon) so I have had to |
| 235 | figure out the grounds on which it was split, and make my own choices |
| 236 | as I evolve it. I have moved many things out of the xdep files |
| 237 | actually, partly as a result of BFD and partly by removing duplicated |
| 238 | code. |
| 239 | |
| 240 | @contents |
| 241 | @bye |
| 242 | |