-
Notifications
You must be signed in to change notification settings - Fork 9
/
readme.html
178 lines (156 loc) · 7.9 KB
/
readme.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>cdb 3.1</title>
<link HREF="https://drh.github.io" REV="made" TITLE="David R. Hanson">
</head>
<body>
<h1>cdb 3.1</h1>
<p>This hierarchy holds the implementation of cdb version 3.1, the debugger described in
D. R. Hanson,
‘A Machine-Independent Debugger—Revisited’,
<cite>Software—Practice and Experience</cite> <strong>29</strong> (10), 849-862, Aug. 1999;
<a href="docs/cdb3-spe.pdf">PDF</a>.</p>
<p>The initial version of cdb is described in
D. R. Hanson and M. Raghavachari,
‘A Machine-Independent Debugger’,
<cite>Software—Practice and Experience</cite> <strong>26</strong> (11), 1277-1299, Nov. 1996;
<a href="docs/cdb.pdf">PDF</a>.</p>
<h2>Contents</h2>
<dl>
<dt><a href="readme.html"><code>readme.html</code></a></dt>
<dd>this file.</dd>
<dt><a href="makefile"><code>makefile</code></a></dt>
<dd><code>make</code> instructions for building cdb.</dd>
<dt><code>lookup.[ch] wf.c</code></dt>
<dd>sample program described in ‘A Machine-Independent Debugger’.</dd>
<dt><code><a href="src">src</a>/*.[ch]</code></dt>
<dd>source code for cdb, the nub, the RPC code, the prelinker script, and the symbol-table
emitter additions to lcc.</dd>
<dt><code><a href="etc">etc</a>/*.c</code></dt>
<dd>lcc driver back ends modified to support the -Wo-g4 option.</dd>
<dt><code>startup/{*.o,*.obj}</code></dt>
<dd>platform-specific startup code modified to start the nub. Only startup/solaris.o,
startup/linux.o, and startup/win32.obj have been tested.</dd>
<dt><a href="docs">docs</a>/*.pdf</a></dt>
<dd>PDFs for the papers cited above.</dd>
</dl>
<h2>Differences</h2>
<p>‘A Machine-Independent Debugger’ describes the initial version of cdb. The list below
summarizes the differences between version 3.1 and cdb 2.2. For all the details, see
‘A Machine-Independent Debugger—Revisited’.</p>
<p>This version works only with <a href="https://github.com/drh/lcc">lcc</a> 4.1, and it requires the ASDL generator,
<a href="http://sourceforge.net/projects/asdl/">asdlGen</a>),
and the <a href="https://github.com/drh/cii"></a>C Interfaces and Implementations (CII) library.</p>
<p>In the two-process version, cdb is the server and the target (the program being
debugged) is the client. <a href="src/server.c"><code>src/server.c</code></a> is the
server side of the RPC channel and <a href="src/client.c"><code>src/client.c</code></a> is
the client side. (These roles are reversed in Table 1 and Figure 6 in the initial cdb
paper.) cdb can run on a different machine than the target, but the machines must have the
same type metrics and endianness.</p>
<p>All strings, types, and symbol-table entries are stored in an ASDL ‘pickle’,
which is named <em>X</em><code>.pickle</code>, where <em>X</em> is the unique module
identifier. <a href="src/sym.asdl"><code>src/sym.asdl</code></a> defines the relevant data
structures. cdb reads pickles when a client attaches.</p>
<p>Modules hold only an unique module identifier and a pointer to an array of addresses of
globals and statics, which is stored in read-only memory.</p>
<p><code>_Nub_bp</code> takes only one argument, the index of the stopping point i, and
switches to cdb if <code>_Nub_bpflags[i]</code> is nonzero. cdb determines if a breakpoint
<code>i</code> is set in the module that caused the switch; if no breakpoint is set,
control is returned to the client.</p>
<h2>Installation</h2>
<p>This version of cdb has been installed and (lightly) tested on RedHat Linux 2.1,
Solaris 2.5.1, and Windows NT 4.0. Installation involves building cdb, the nub library (<code>libnub.a</code>),
and rebuilding rcc (lcc's compiler proper) and lcc (lcc's compilation driver).</p>
<p>The following steps describe the installation under Solaris and Linux. Similar steps
apply to Windows NT 4.0. Under NT, you'll need a UNIX-style shell and Visual C++ 5.0 or
6.0.
<ol>
<li>Install lcc 4.1, asdlGen 1.2, and the CII library.</li>
<li>Create a file, <code>custom.mk</code>, that redefines the definitions at the top of the
makefile to suit your local configuration. Make sure <code>BUILDDIR</code> points to the
lcc 4.1 build directory (or a copy of it) and <code>ASDL_HOME</code> points to the root of
the asdlGen installation.</li>
<li>Edit <a href="etc/solaris.c"><code>etc/solaris.c</code></a>
or <a href="etc/linux.c"><code>etc/linux.c</code></a>
(or a copy) to suit your local configuration, and set <code>HOSTNAME</code> to the name of
the appropriate file in <code>custom.mk</code>. These files are variants of the driver
back ends included in the lcc 4.1 distribution. They support the -Wo-g4 option, which
causes lcc to emit cdb-style symbol tables as ASDL pickles.</li>
<li>Linux doesn't have <code>-lsocket</code> (the socket library), so, if you're running on
Linux, redefine <code>LIBS</code> in <code>custom.mk</code>; e.g., I use <blockquote>
<pre>LIBS=-lasdl -lcii -lnsl</pre>
</blockquote>
</li>
<li>Run make: <blockquote>
<pre>1% make CUSTOM=custom.mk</pre>
</blockquote>
<p>You can omit the assignment if your local configuration is in <code>custom.mk</code>. I
use different names for different platforms, e.g., </p>
<blockquote>
<pre>1% make CUSTOM=linux.mk</pre>
</blockquote>
<p>Depending on the values of file timestamps, you might have to touch <a
href="etc/solaris.c"><code>etc/solaris.c</code></a>,
<a href="etc/linux.c"><code>etc/linux.c</code></a>,
or <a href="src/inits.c"><code>src/inits.c</code></a>,
or remove the corresponding object
files, to force rebuilding of lcc or rcc. <strong>IMPORTANT</strong>: Use the same C
compiler you used to build lcc.</p>
</li>
<li>Copy the startup code to the build directory, e.g.,<blockquote>
<pre>1% cp startup/solaris.o ${BUILDDIR}/startup.o</pre>
</blockquote>
<p>Notice that the name of the installed startup code is always <code>startup.o</code>.</p>
</li>
<li>Test the single-process version of cdb by building the sample program:<blockquote>
<pre>1% make CUSTOM=custom.mk stubtest</pre>
</blockquote>
<p>Then run a.out:</p>
<blockquote>
<pre>1% a.out
fetching module [1571580302] inhaling lookup.c[1571580302]
fetching module [1571580299] inhaling wf.c[1571580299]
cdb></pre>
</blockquote>
<p>The documentation in ‘A Machine-Independent Debugger’ applies; the
‘h’ command summarizes the commands.</p>
</li>
<li>Test the two-process version of cdb. Build the sample program with<blockquote>
<pre>1% make CUSTOM=custom.mk test</pre>
</blockquote>
<p>Then run cdb:</p>
<blockquote>
<pre>1% ${BUILDDIR}/cdb
/u/drh/pkg/4.1/sparc-solaris/cdb listening on 0.0.0.0:9001</pre>
</blockquote>
<p>In a separate window, set the <code>DEBUGGER</code> environment variable and run a.out:</p>
<blockquote>
<pre>2% setenv DEBUGGER localhost:9001
2% a.out
client: connected on 127.0.0.1:47632 to 127.0.0.1:9001</pre>
</blockquote>
<p>In the cdb window, you should see something like:</p>
<blockquote>
<pre>/u/drh/pkg/4.1/sparc-solaris/cdb: now serving 127.0.0.1:1428
fetching module [1571576238] inhaling wf.c[1571576238]
fetching module [1571576369] inhaling lookup.c[1571576369]
cdb></pre>
</blockquote>
<p>When you exit the client, cdb waits for another connection.</p>
</li>
<li>The command <code>make CUSTOM=custom.mk clean</code>; cleans up.</li>
<li>(Optional) Add a link to cdb from <code>/usr/local/bin</code>, e.g.,<blockquote>
<pre>1% ln -s ${BUILDDIR}/cdb /usr/local/bin/cdb</pre>
</blockquote>
</li>
</ol>
<h2>Bugs and Suggestions</h2>
<p>Send me email. I can’t promise
timely responses or patches, but I intend to keep cdb in sync with lcc. </p>
<hr>
<address>
<a href="https://drh.github.io">David R. Hanson</a>
</address>
</body>
</html>