gdb/doc/gdbint.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
  61 @end menu
  62
  63 @node Cleanups, Wrapping, Top, Top
  64 @chapter Cleanups
  65
  66 Cleanups are a structured way to deal with things that need to be done
  67 later.  When your code does something (like malloc some memory, or open
  68 a file) that needs to be undone later (e.g. free the memory or close
  69 the file), it can make a cleanup.  The cleanup will be done at some
  70 future point:  when the command is finished, when an error occurs, or
  71 when your code decides it's time to do cleanups.
  72
  73 You can also discard cleanups, that is, throw them away without doing
  74 what they say.  This is only done if you ask that it be done.
  75
  76 Syntax:
  77
  78 @table @code
  79 @item old_chain = make_cleanup (function, arg);
  80 This makes a cleanup which will cause FUNCTION to be called with ARG
  81 (a char *) later.  The result, OLD_CHAIN, is a handle that can be
  82 passed to do_cleanups or discard_cleanups later.  Unless you are
  83 going to call do_cleanups or discard_cleanups yourself,
  84 you can ignore the result from make_cleanup.
  85
  86
  87 @item do_cleanups (old_chain);
  88 Performs all cleanups done since make_cleanup returned OLD_CHAIN.
  89 E.g.:   make_cleanup (a, 0); old = make_cleanup (b, 0); do_cleanups (old);
  90 will call b() but will not call a().  The cleanup that calls a() will remain
  91 in the cleanup chain, and will be done later unless otherwise discarded.
  92
  93 @item discard_cleanups (old_chain);
  94 Same as do_cleanups except that it just removes the cleanups from the
  95 chain and does not call the specified functions.
  96
  97 @end table
  98
  99 Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify that they
 100 ``should not be called when cleanups are not in place''.  This means
 101 that any actions you need to reverse in the case of an error or
 102 interruption must be on the cleanup chain before you call these functions,
 103 since they might never return to your code (they @samp{longjmp} instead).
 104
 105
 106 @node Wrapping, Releases, Cleanups, Top
 107 @chapter Wrapping output lines
 108
 109 Output that goes through printf_filtered or fputs_filtered or
 110 fputs_demangled needs only to have calls to wrap_here() added
 111 in places that would be good breaking points.  The utility routines
 112 will take care of actually wrapping if the line width is exceeded.
 113
 114 The argument to wrap_here() is an indentation string which is printed
 115 ONLY if the line breaks there.  This argument is saved away and used
 116 later.  It must remain valid until the next call to wrap_here() or
 117 until a newline has been printed through the *_filtered functions.
 118 Don't pass in a local variable and then return!
 119
 120 It is usually best to call wrap_here() after printing a comma or space.
 121 If you call it before printing a space, make sure that your indentation
 122 properly accounts for the leading space that will print if the line wraps
 123 there.
 124
 125 Any function or set of functions that produce filtered output must finish
 126 by printing a newline, to flush the wrap buffer, before switching to
 127 unfiltered ("printf") output.  Symbol reading routines that print
 128 warnings are a good example.
 129
 130
 131 @node Releases, README, Wrapping, Top
 132 @chapter Configuring GDB for release
 133
 134
 135 GDB should be released after doing @samp{config.gdb none} in the top level
 136 directory.  This will leave a makefile there, but no tm- or xm- files.
 137 The makefile is needed, for example, for @samp{make gdb.tar.Z}@dots{}  If you
 138 have tm- or xm-files in the main source directory, C's include rules
 139 cause them to be used in preference to tm- and xm-files in the
 140 subdirectories where the user will actually configure and build the
 141 binaries.
 142
 143 @samp{config.gdb none} is also a good way to rebuild the top level Makefile
 144 after changing Makefile.dist, alldeps.mak, etc.
 145
 146
 147
 148 @node README, New Architectures, Releases, Top
 149 @chapter The README file
 150
 151
 152 Check the README file, it often has useful information that does not
 153 appear anywhere else in the directory.
 154
 155
 156
 157 @node New Architectures,  , README, Top
 158 @chapter Defining a new host or target architecture
 159
 160
 161 When building support for a new host and/or target, this will help you
 162 organize where to put the various parts.  @var{ARCH} stands for the
 163 architecture involved.
 164
 165 Object files needed when the host system is an @var{ARCH} are listed in
 166 the file @file{xconfig/@var{ARCH}}, in the Makefile macro @samp{XDEPFILES
 167 = }@dots{}.  You can also define XXXXXX in there.
 168
 169 There are some ``generic'' versions of routines that can be used by
 170 various host systems.  If these routines work for the @var{ARCH} host,
 171 you can just include the generic file's name (with .o, not .c) in
 172 @code{XDEPFILES}.  Otherwise, you will need to write routines that
 173 perform the same functions as the generic file, put them into
 174 @code{@var{ARCH}-xdep.c}, and put @code{@var{ARCH}-xdep.o} into
 175 @code{XDEPFILES}.  These generic host support files include:
 176
 177 @example
 178         coredep.c, coredep.o
 179 @end example
 180
 181 @table @code
 182 @item fetch_core_registers()
 183 Support for reading registers out of a core file.  This routine calls
 184 @code{register_addr(}), see below.
 185
 186 @item register_addr()
 187 If your @code{xm-@var{ARCH}.h} file defines the macro @code{REGISTER_U_ADDR(reg)} to be the
 188 offset within the @samp{user} struct of a register (represented as a GDB
 189 register number), @file{coredep.c} will define the @code{register_addr()} function
 190 and use the macro in it.  If you do not define @code{REGISTER_U_ADDR}, but
 191 you are using the standard @code{fetch_core_registers}, you
 192 will need to define your own version of @code{register_addr}, put it into
 193 your @code{@var{ARCH}-xdep.c} file, and be sure @code{@var{ARCH}-xdep.o} is in the @code{XDEPFILES} list.
 194 If you have your own @code{fetch_core_registers}, you only need to define
 195 @code{register_addr} if your @code{fetch_core_registers} calls it.  Many custom
 196 @code{fetch_core_registers} implementations simply locate the registers
 197 themselves.
 198 @end table
 199
 200 Files needed when the target system is an @var{ARCH} are listed in the file
 201 @file{tconfig/@var{ARCH}}, in the @code{Makefile} macro @samp{TDEPFILES = }@dots{}.  You can also
 202 define XXXXXX in there.
 203
 204 Similar generic support files for target systems are:
 205
 206 @example
 207         exec.c, exec.o:
 208 @end example
 209
 210 This file defines functions for accessing files that are executable
 211 on the target system.  These functions open and examine an exec file,
 212 extract data from one, write data to one, print information about one,
 213 etc.  Now that executable files are handled with BFD, every architecture
 214 should be able to use the generic exec.c rather than its own custom code.
 215
 216 @contents
 217 @bye
 218