Skip to content

drh/cdb

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
3 branches 5 tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
etc
 
 
src
 
 
startup
 
 
LICENSE
 
 
custom.mk
 
 
lookup.c
 
 
lookup.h
 
 
makefile
 
 
readme.html
 
 
wf.c
 
 

readme.html 

<html>

<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>cdb 3.1</title>
<link HREF="http://drh.home.dyndns.org/" 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,
&lsquo;A Machine-Independent Debugger&mdash;Revisited&rsquo;,
<cite>Software&mdash;Practice and Experience</cite> <strong>29</strong> (10), 849-862, Aug. 1999; 
this paper is available at
<a href="http://storage.webhop.net/documents/cdb3.pdf">http://storage.webhop.net/documents/cdb3.pdf</a>.</p>

<p>The initial version of cdb is described in
D. R. Hanson and M. Raghavachari,
&lsquo;A Machine-Independent Debugger&rsquo;,
<cite>Software&mdash;Practice and Experience</cite> <strong>26</strong> (11), 1277-1299, 11/96,
which is available at
<a href="http://storage.webhop.net/documents/cdb.pdf">http://storage.webhop.net/documents/cdb.pdf</a>.</p>

<p>For more information about cdb, visit <a
href="http://www.cs.princeton.edu/software/lcc/cdb/">http://www.cs.princeton.edu/software/lcc/cdb/</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 &lsquo;A Machine-Independent Debugger&rsquo;.</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>
</dl>

<h2>Differences</h2>

<p>&lsquo;A Machine-Independent Debugger&rsquo; describes the initial version of cdb. <a
href="http://www.cs.princeton.edu/software/lcc/cdb/2.x.html">http://www.cs.princeton.edu/software/lcc/cdb/2.x.html</a>
describes the differences between the initial version and version 2.2. The list below
summarizes the differences between version 3.1 and cdb 2.2. For all the details, see
&lsquo;A Machine-Independent Debugger&mdash;Revisited&rsquo;.</p>

<p>This version works only with lcc 4.1, and it requires the ASDL generator, asdlGen (<a
href="http://sourceforge.net/projects/asdl/">http://sourceforge.net/projects/asdl/</a>),
and the C Interfaces and Implementations (CII) library (<a
href="http://www.cs.princeton.edu/software/cii/">http://www.cs.princeton.edu/software/cii/</a>).</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 &lsquo;pickle&rsquo;,
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 (<a href="http://www.cs.princeton.edu/software/lcc/">http://www.cs.princeton.edu/software/lcc/</a>),
    asdlGen 1.2 (<a href="http://sourceforge.net/projects/asdl/">http://sourceforge.net/projects/asdl/</a>),
    and the CII library (<a href="http://www.cs.princeton.edu/software/cii/">http://www.cs.princeton.edu/software/cii/</a>).</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&gt;</pre>
    </blockquote>
    <p>The documentation in &lsquo;A Machine-Independent Debugger&rsquo; applies; the
    &lsquo;h&rsquo; 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&gt;</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&rsquo;t promise
timely responses or patches, but I intend to keep cdb in sync with lcc. </p>

<hr>

<address>
  <a href="http://drh.home.dyndns.org/">David R. Hanson</a><br>
  $Id$ 
</address>
</body>
</html>

About

A Machine-Independent Debugger

Resources

Readme

License

View license

Stars

22 stars

Watchers

3 watching

Forks

7 forks
Report repository

Releases

5 tags

Packages

No packages published

Languages