-
Notifications
You must be signed in to change notification settings - Fork 8
A Machine-Independent Debugger
License
drh/cdb
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
<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>
About
A Machine-Independent Debugger
Resources
License
Stars
Watchers
Forks
Packages 0
No packages published