]>
Commit | Line | Data |
---|---|---|
ca714d03 RP |
1 | \input texinfo |
2 | @setfilename gdb-internals | |
3 | @ifinfo | |
4 | This file documents the internals of the GNU debugger GDB. | |
f222d23d | 5 | |
ca714d03 RP |
6 | Copyright (C) 1990, 1991 Free Software Foundation, Inc. |
7 | Contributed by Cygnus Support. Written by John Gilmore. | |
cfddbd02 | 8 | |
ca714d03 RP |
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 | |
cfddbd02 JG |
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 | ||
ca714d03 RP |
78 | @table @code |
79 | @item old_chain = make_cleanup (function, arg); | |
cfddbd02 JG |
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 | ||
cfddbd02 | 86 | |
ca714d03 | 87 | @item do_cleanups (old_chain); |
cfddbd02 JG |
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 | ||
ca714d03 | 93 | @item discard_cleanups (old_chain); |
cfddbd02 JG |
94 | Same as do_cleanups except that it just removes the cleanups from the |
95 | chain and does not call the specified functions. | |
96 | ||
ca714d03 | 97 | @end table |
cfddbd02 | 98 | |
ca714d03 RP |
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 | |
cfddbd02 JG |
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, | |
ca714d03 | 103 | since they might never return to your code (they @samp{longjmp} instead). |
7f27984e JG |
104 | |
105 | ||
ca714d03 RP |
106 | @node Wrapping, Releases, Cleanups, Top |
107 | @chapter Wrapping output lines | |
bbb5013f JG |
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 | ||
056c1b2c JG |
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. | |
bbb5013f JG |
129 | |
130 | ||
ca714d03 RP |
131 | @node Releases, README, Wrapping, Top |
132 | @chapter Configuring GDB for release | |
7f27984e JG |
133 | |
134 | ||
ca714d03 | 135 | GDB should be released after doing @samp{config.gdb none} in the top level |
7f27984e | 136 | directory. This will leave a makefile there, but no tm- or xm- files. |
ca714d03 | 137 | The makefile is needed, for example, for @samp{make gdb.tar.Z}@dots{} If you |
7f27984e JG |
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 | ||
ca714d03 | 143 | @samp{config.gdb none} is also a good way to rebuild the top level Makefile |
7f27984e JG |
144 | after changing Makefile.dist, alldeps.mak, etc. |
145 | ||
146 | ||
147 | ||
ca714d03 RP |
148 | @node README, New Architectures, Releases, Top |
149 | @chapter The README file | |
7f27984e JG |
150 | |
151 | ||
152 | Check the README file, it often has useful information that does not | |
153 | appear anywhere else in the directory. | |
46bc46eb JG |
154 | |
155 | ||
156 | ||
ca714d03 RP |
157 | @node New Architectures, , README, Top |
158 | @chapter Defining a new host or target architecture | |
46bc46eb JG |
159 | |
160 | ||
161 | When building support for a new host and/or target, this will help you | |
ca714d03 | 162 | organize where to put the various parts. @var{ARCH} stands for the |
46bc46eb JG |
163 | architecture involved. |
164 | ||
ca714d03 RP |
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. | |
46bc46eb | 168 | |
ca714d03 RP |
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: | |
46bc46eb | 176 | |
ca714d03 | 177 | @example |
46bc46eb | 178 | coredep.c, coredep.o |
ca714d03 | 179 | @end example |
46bc46eb | 180 | |
ca714d03 RP |
181 | @table @code |
182 | @item fetch_core_registers() | |
46bc46eb | 183 | Support for reading registers out of a core file. This routine calls |
ca714d03 RP |
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 | |
46bc46eb | 197 | themselves. |
ca714d03 | 198 | @end table |
46bc46eb | 199 | |
ca714d03 RP |
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 | |
46bc46eb JG |
202 | define XXXXXX in there. |
203 | ||
204 | Similar generic support files for target systems are: | |
205 | ||
ca714d03 | 206 | @example |
46bc46eb | 207 | exec.c, exec.o: |
ca714d03 | 208 | @end example |
46bc46eb JG |
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. | |
ca714d03 RP |
215 | |
216 | @contents | |
217 | @bye | |
218 |