gdb/gdb-int.texinfo

   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