bitkeeper revision 1.1713.1.10 (42b03d19TAy64Sdjkm7M7nVoGNwCVw)

readme for pdb 0.3

2 files changed, 85 insertions, 0 deletions

diff --git a/.rootkeys b/.rootkeys
index f8d113f0e6..b4448b79e7 100644
--- a/.rootkeys
+++ b/.rootkeys
@@ -542,6 +542,7 @@
 42a0c8dasiso9c-2sCvHBzP6YVjATA tools/debugger/pdb/evtchn.mli
 42a0c8daXD_6Y62A_u5-PO_Klrhi0w tools/debugger/pdb/pdb_caml_xc.c
 42a0c8danJXun9ay5SPBhhkKvuUPfg tools/debugger/pdb/pdb_xen.c
+42b03d06llc_GE7fXGQ6-rYR4VFAcw tools/debugger/pdb/readme
 42a0c8dbjK6Du89D2SUcxsuAdlUu3w tools/debugger/pdb/server.ml
 401d7e160vaxMBAUSLSicuZ7AQjJ3w tools/examples/Makefile
 401d7e16UgeqroJQTIhwkrDVkoWgZQ tools/examples/README
diff --git a/tools/debugger/pdb/readme b/tools/debugger/pdb/readme
new file mode 100644
index 0000000000..be1c44279e
--- /dev/null
+++ b/tools/debugger/pdb/readme
@@ -0,0 +1,84 @@
+
+PDB 0.3 
+http://www.cl.cam.ac.uk/netos/pdb
+
+Alex Ho  
+June 2005
+
+
+This is the latest incarnation of the pervasive debugger.
+PDB is a remote stub for GDB.  Running as a user-space
+application in domain 0, it can debug any other domain.
+
+
++------+    tcp/ip    +-------+  
+| GDB  |--------------|  PDB  |
++------+              +-------+   +-------+
+                      | Dom 0 |   | Dom U |
+                      +-------+---+-------+
+                      |  Xen              |
+                      +-------------------+
+
+Installation
+
+- Install OCaml 3.08 in domain 0.
+  http://caml.inria.fr/download.en.html  is a good place to start.
+
+- Build Xen with debugger support
+  make domu_debug=y xen
+
+- (optional)
+  Build the target domains with debugging symbols.
+  make CONFIG_DEBUG_INFO=true CONFIG_FRAME_POINTER=false linux-2.6-xenU-build
+
+  You can also change linux-2.6.11-xenU/Makefile
+  CONFIG_CC_OPTIMIZE_FOR_SIZE from -O2 to -O
+
+- Build PDB
+  (cd tools/debugger/libxendebug; make install)
+  (cd tools/debugger/pdb; make)
+
+Usage
+
+- PDB does not currently support SMP.  Please boot xen with "maxcpus=1"
+
+- Run PDB
+  domain-0.xeno# ./pdb <port>
+
+- Run GDB
+  hostname% gdb <xeno.bk>/dist/install/boot/vmlinux-syms-2.6.11.11-xenU
+
+  (gdb) target remote domain-0.xeno:<port>
+
+  At this point, you'll get an error message such as:
+  Remote debugging using domain-0.xeno:5000
+  0x00000000 in ?? ()
+  warning: shared library handler failed to enable breakpoint
+  Although GDB is connected to PDB, PDB doesn't know which domain
+  you'd like to debug, so it's just feeding GDB a bunch of zeros.
+
+  (gdb) maint packet x context = domain <domid> <vcpu>
+
+  This tells PDB that we'd like to debug a particular domain & vcpu.
+  However, since we're sending the command directly to PDB, GDB doesn't 
+  know that we now have a proper target.  We can force GDB to invalidate
+  its register cache.  This is optional; the next time the program
+  stops GDB will query for the registers automatically.
+
+  (gdb) flushreg
+
+  
+  the following gdb commands should work :)
+
+  break
+  step,   stepi
+  next,   nexti
+  continue
+  print
+
+
+To Do
+
+- watchpoints
+- support for SMP
+- support for user applications