cdb 3.1

This hierarchy holds the implementation of cdb version 3.1, the debugger described in D. R. Hanson, ‘A Machine-Independent Debugger—Revisited’, Software—Practice and Experience 29 (10), 849-862, Aug. 1999; this paper is available at http://storage.webhop.net/documents/cdb3.pdf.

The initial version of cdb is described in D. R. Hanson and M. Raghavachari, ‘A Machine-Independent Debugger’, Software—Practice and Experience 26 (11), 1277-1299, 11/96, which is available at http://storage.webhop.net/documents/cdb.pdf.

For more information about cdb, visit http://www.cs.princeton.edu/software/lcc/cdb/.

Contents

readme.html

this file.

makefile

make instructions for building cdb.

lookup.[ch] wf.c

sample program described in ‘A Machine-Independent Debugger’.

src/*.[ch]

source code for cdb, the nub, the RPC code, the prelinker script, and the symbol-table emitter additions to lcc.

etc/*.c

lcc driver back ends modified to support the -Wo-g4 option.

startup/{*.o,*.obj}

platform-specific startup code modified to start the nub. Only startup/solaris.o, startup/linux.o, and startup/win32.obj have been tested.

Differences

‘A Machine-Independent Debugger’ describes the initial version of cdb. http://www.cs.princeton.edu/software/lcc/cdb/2.x.html 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 ‘A Machine-Independent Debugger—Revisited’.

This version works only with lcc 4.1, and it requires the ASDL generator, asdlGen (http://sourceforge.net/projects/asdl/), and the C Interfaces and Implementations (CII) library (http://www.cs.princeton.edu/software/cii/).

In the two-process version, cdb is the server and the target (the program being debugged) is the client. src/server.c is the server side of the RPC channel and src/client.c 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.

All strings, types, and symbol-table entries are stored in an ASDL ‘pickle’, which is named X.pickle, where X is the unique module identifier. src/sym.asdl defines the relevant data structures. cdb reads pickles when a client attaches.

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.

_Nub_bp takes only one argument, the index of the stopping point i, and switches to cdb if _Nub_bpflags[i] is nonzero. cdb determines if a breakpoint i is set in the module that caused the switch; if no breakpoint is set, control is returned to the client.

Installation

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 (libnub.a), and rebuilding rcc (lcc's compiler proper) and lcc (lcc's compilation driver).

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.

1. Install lcc 4.1 (http://www.cs.princeton.edu/software/lcc/), asdlGen 1.2 (http://sourceforge.net/projects/asdl/), and the CII library (http://www.cs.princeton.edu/software/cii/).
2. Create a file, custom.mk, that redefines the definitions at the top of the makefile to suit your local configuration. Make sure BUILDDIR points to the lcc 4.1 build directory (or a copy of it) and ASDL_HOME points to the root of the asdlGen installation.
3. Edit etc/solaris.c or etc/linux.c (or a copy) to suit your local configuration, and set HOSTNAME to the name of the appropriate file in custom.mk. 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.
4. Linux doesn't have -lsocket (the socket library), so, if you're running on Linux, redefine LIBS in custom.mk; e.g., I use

   LIBS=-lasdl -lcii -lnsl

5. Run make:

   1% make CUSTOM=custom.mk

   You can omit the assignment if your local configuration is in custom.mk. I use different names for different platforms, e.g.,

   1% make CUSTOM=linux.mk

   Depending on the values of file timestamps, you might have to touch etc/solaris.c, etc/linux.c, or src/inits.c, or remove the corresponding object files, to force rebuilding of lcc or rcc. IMPORTANT: Use the same C compiler you used to build lcc.

6. Copy the startup code to the build directory, e.g.,

   1% cp startup/solaris.o ${BUILDDIR}/startup.o

   Notice that the name of the installed startup code is always startup.o.

7. Test the single-process version of cdb by building the sample program:

   1% make CUSTOM=custom.mk stubtest

   Then run a.out:

   1% a.out
   fetching module [1571580302] inhaling lookup.c[1571580302]
   fetching module [1571580299] inhaling wf.c[1571580299]
   cdb>

   The documentation in ‘A Machine-Independent Debugger’ applies; the ‘h’ command summarizes the commands.

8. Test the two-process version of cdb. Build the sample program with

   1% make CUSTOM=custom.mk test

   Then run cdb:

   1% ${BUILDDIR}/cdb
   /u/drh/pkg/4.1/sparc-solaris/cdb listening on 0.0.0.0:9001

   In a separate window, set the DEBUGGER environment variable and run a.out:

   2% setenv DEBUGGER localhost:9001
   2% a.out
   client: connected on 127.0.0.1:47632 to 127.0.0.1:9001

   In the cdb window, you should see something like:

   /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>

   When you exit the client, cdb waits for another connection.

9. The command make CUSTOM=custom.mk clean; cleans up.
10. (Optional) Add a link to cdb from /usr/local/bin, e.g.,

    1% ln -s ${BUILDDIR}/cdb /usr/local/bin/cdb

Bugs and Suggestions

Send me email. I can’t promise timely responses or patches, but I intend to keep cdb in sync with lcc.