1.1 --- a/.rootkeys	Wed Jun 15 14:37:13 2005 +0000
     1.2 +++ b/.rootkeys	Wed Jun 15 14:41:49 2005 +0000
     1.3 @@ -17,7 +17,6 @@ 4187c1c7IWmBinGdI19kL4MuZ6RLbQ docs/chec
     1.4  3f9e7d60PWZJeVh5xdnk0nLUdxlqEA docs/figs/xenlogo.eps
     1.5  418a3248xjIqmNKo0v_XQSfAvlBGFw docs/html.sty
     1.6  41c0c4116itF389v0CEWcmzue6zJkA docs/misc/VMX_changes.txt
     1.7 -4022a73cgxX1ryj1HgS-IwwB6NUi2A docs/misc/XenDebugger-HOWTO
     1.8  412f4bd9sm5mCQ8BkrgKcAKZGadq7Q docs/misc/blkif-drivers-explained.txt
     1.9  420b949cy9ZGzED74Fz_DaWlK7tT4g docs/misc/crashdb.txt
    1.10  4251a1f82AexscYEiF4Iku8Gc_kWfQ docs/misc/grant-tables.txt

     2.1 --- a/docs/misc/XenDebugger-HOWTO	Wed Jun 15 14:37:13 2005 +0000
     2.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.3 @@ -1,304 +0,0 @@
     2.4 -Pervasive Debugging 
     2.5 -===================
     2.6 -
     2.7 -Alex Ho (alex.ho at cl.cam.ac.uk)
     2.8 -
     2.9 -Introduction
    2.10 -------------
    2.11 -
    2.12 -The pervasive debugging project is leveraging Xen to 
    2.13 -debug distributed systems.  We have added a gdb stub
    2.14 -to Xen to allow for remote debugging of both Xen and
    2.15 -guest operating systems.  More information about the
    2.16 -pervasive debugger is available at: http://www.cl.cam.ac.uk/netos/pdb
    2.17 -
    2.18 -
    2.19 -Implementation
    2.20 ---------------
    2.21 -
    2.22 -The gdb stub communicates with gdb running over a serial line.
    2.23 -The main entry point is pdb_handle_exception() which is invoked
    2.24 -from:    pdb_key_pressed()    ('D' on the console)
    2.25 -         do_int3_exception()  (interrupt 3: breakpoint exception)
    2.26 -         do_debug()           (interrupt 1: debug exception)
    2.27 -
    2.28 -This accepts characters from the serial port and passes gdb
    2.29 -commands to pdb_process_command() which implements the gdb stub
    2.30 -interface.  This file draws heavily from the kgdb project and
    2.31 -sample gdbstub provided with gdb.
    2.32 -
    2.33 -The stub can examine registers, single step and continue, and
    2.34 -read and write memory (in Xen, a domain, or a Linux process'
    2.35 -address space).  The debugger does not currently trace the 
    2.36 -current process, so all bets are off if context switch occurs
    2.37 -in the domain.
    2.38 -
    2.39 -
    2.40 -Setup
    2.41 ------
    2.42 -
    2.43 - +-------+ telnet +-----------+ serial +-------+ 
    2.44 - |  GDB  |--------|  nsplitd  |--------|  Xen  |
    2.45 - +-------+        +-----------+        +-------+ 
    2.46 -
    2.47 -To run pdb, Xen must be appropriately configured and 
    2.48 -a suitable serial interface attached to the target machine.
    2.49 -GDB and nsplitd can run on the same machine.
    2.50 -
    2.51 -Xen Configuration
    2.52 -
    2.53 -  Add the "pdb=xxx" option to your Xen boot command line
    2.54 -  where xxx is one of the following values:
    2.55 -     com1    gdb stub should communicate on com1
    2.56 -     com1H   gdb stub should communicate on com1 (with high bit set)
    2.57 -     com2    gdb stub should communicate on com2
    2.58 -     com2H   gdb stub should communicate on com2 (with high bit set)
    2.59 -
    2.60 -  Symbolic debugging infomration is quite helpful too:
    2.61 -  xeno.bk/xen/arch/x86/Rules.mk
    2.62 -    add -g to CFLAGS to compile Xen with symbols
    2.63 -  xeno.bk/linux-2.4.27-xen-sparse/arch/xen/Makefile
    2.64 -    add -g to CFLAGS to compile Linux with symbols
    2.65 -
    2.66 -  You may also want to consider dedicating a register to the
    2.67 -  frame pointer (disable the -fomit-frame-pointer compile flag).
    2.68 -
    2.69 -  When booting Xen and domain 0, look for the console text 
    2.70 -  "pdb: pervasive debugger" just before DOM0 starts up.
    2.71 -
    2.72 -Serial Port Configuration
    2.73 -
    2.74 -  pdb expects to communicate with gdb using the serial port.  Since 
    2.75 -  this port is often shared with the machine's console output, pdb can
    2.76 -  discriminate its communication by setting the high bit of each byte.
    2.77 -
    2.78 -  A new tool has been added to the source tree which splits 
    2.79 -  the serial output from a remote machine into two streams: 
    2.80 -  one stream (without the high bit) is the console and 
    2.81 -  one stream (with the high bit stripped) is the pdb communication.
    2.82 -
    2.83 -  See:  xeno.bk/tools/misc/nsplitd
    2.84 -
    2.85 -  nsplitd configuration
    2.86 -  ---------------------
    2.87 -  hostname$ more /etc/xinetd.d/nsplit
    2.88 -  service nsplit1
    2.89 -  {
    2.90 -        socket_type             = stream
    2.91 -        protocol                = tcp
    2.92 -        wait                    = no
    2.93 -        user                    = wanda
    2.94 -        server                  = /usr/sbin/in.nsplitd
    2.95 -        server_args             = serial.cl.cam.ac.uk:wcons00
    2.96 -        disable                 = no
    2.97 -        only_from               = 128.232.0.0/17 127.0.0.1
    2.98 -  }
    2.99 -
   2.100 -  hostname$ egrep 'wcons00|nsplit1' /etc/services
   2.101 -  wcons00         9600/tcp        # Wanda remote console
   2.102 -  nsplit1         12010/tcp       # Nemesis console splitter ports.
   2.103 -
   2.104 -  Note: nsplitd was originally written for the Nemesis project
   2.105 -  at Cambridge.
   2.106 -
   2.107 -  After nsplitd accepts a connection on <port> (12010 in the above
   2.108 -  example), it starts listening on port <port + 1>.  Characters sent 
   2.109 -  to the <port + 1> will have the high bit set and vice versa for 
   2.110 -  characters received.
   2.111 -
   2.112 -  You can connect to the nsplitd using
   2.113 -  'tools/misc/xencons <host> <port>'
   2.114 -
   2.115 -GDB 6.0
   2.116 -  pdb has been tested with gdb 6.0.  It should also work with
   2.117 -  earlier versions.
   2.118 -
   2.119 -
   2.120 -Usage
   2.121 ------
   2.122 -
   2.123 -1. Boot Xen and Linux
   2.124 -2. Interrupt Xen by pressing 'D' at the console
   2.125 -   You should see the console message: 
   2.126 -   (XEN) pdb_handle_exception [0x88][0x101000:0xfc5e72ac]
   2.127 -   At this point Xen is frozen and the pdb stub is waiting for gdb commands 
   2.128 -   on the serial line.
   2.129 -3. Attach with gdb
   2.130 -   (gdb) file xeno.bk/xen/xen
   2.131 -   Reading symbols from xeno.bk/xen/xen...done.
   2.132 -   (gdb) target remote <hostname>:<port + 1>              /* contact nsplitd */
   2.133 -   Remote debugging using serial.srg:12131
   2.134 -   continue_cpu_idle_loop () at current.h:10
   2.135 -   warning: shared library handler failed to enable breakpoint
   2.136 -   (gdb) break __enter_scheduler
   2.137 -   Breakpoint 1 at 0xfc510a94: file schedule.c, line 330.
   2.138 -   (gdb) cont
   2.139 -   Continuing.
   2.140 -
   2.141 -   Program received signal SIGTRAP, Trace/breakpoint trap.
   2.142 -   __enter_scheduler () at schedule.c:330
   2.143 -   (gdb) step
   2.144 -   (gdb) step
   2.145 -   (gdb) print next            /* the variable prev has been optimized away! */
   2.146 -   $1 = (struct task_struct *) 0x0
   2.147 -   (gdb) delete
   2.148 -   Delete all breakpoints? (y or n) y
   2.149 -4. You can add additional symbols to gdb
   2.150 -   (gdb) add-sym xeno.bk/linux-2.4.27-xen0/vmlinux
   2.151 -   add symbol table from file "xeno.bk/linux-2.4.27-xen0/vmlinux" at
   2.152 -   (y or n) y
   2.153 -   Reading symbols from xeno.bk/linux-2.4.27-xen0/vmlinux...done.
   2.154 -   (gdb) x/s cpu_vendor_names[0]
   2.155 -   0xc01530d2 <cpdext+62898>:	 "Intel"
   2.156 -   (gdb) break free_uid
   2.157 -   Breakpoint 2 at 0xc0012250
   2.158 -   (gdb) cont
   2.159 -   Continuing.                                  /* run a command in domain 0 */
   2.160 -
   2.161 -   Program received signal SIGTRAP, Trace/breakpoint trap.
   2.162 -   free_uid (up=0xbffff738) at user.c:77
   2.163 -
   2.164 -   (gdb) print *up
   2.165 -   $2 = {__count = {counter = 0}, processes = {counter = 135190120}, files = {
   2.166 -       counter = 0}, next = 0x395, pprev = 0xbffff878, uid = 134701041}
   2.167 -   (gdb) finish
   2.168 -   Run till exit from #0  free_uid (up=0xbffff738) at user.c:77
   2.169 -
   2.170 -   Program received signal SIGTRAP, Trace/breakpoint trap.
   2.171 -   release_task (p=0xc2da0000) at exit.c:51
   2.172 -   (gdb) print *p
   2.173 -   $3 = {state = 4, flags = 4, sigpending = 0, addr_limit = {seg = 3221225472},
   2.174 -     exec_domain = 0xc016a040, need_resched = 0, ptrace = 0, lock_depth = -1, 
   2.175 -     counter = 1, nice = 0, policy = 0, mm = 0x0, processor = 0, 
   2.176 -     cpus_runnable = 1, cpus_allowed = 4294967295, run_list = {next = 0x0, 
   2.177 -       prev = 0x0}, sleep_time = 18995, next_task = 0xc017c000, 
   2.178 -     prev_task = 0xc2f94000, active_mm = 0x0, local_pages = {next = 0xc2da0054,
   2.179 -       prev = 0xc2da0054}, allocation_order = 0, nr_local_pages = 0, 
   2.180 -     ...
   2.181 -5. To resume Xen, enter the "continue" command to gdb.
   2.182 -   This sends the packet $c#63 along the serial channel.
   2.183 -
   2.184 -   (gdb) cont
   2.185 -   Continuing.
   2.186 -
   2.187 -Debugging Multiple Domains & Processes
   2.188 ---------------------------------------
   2.189 -
   2.190 -pdb supports debugging multiple domains & processes.  You can switch
   2.191 -between different domains and processes within domains and examine
   2.192 -variables in each.
   2.193 -
   2.194 -The pdb context identifies the current debug target.  It is stored
   2.195 -in the xen variable pdb_ctx and defaults to xen.
   2.196 -
   2.197 -   target    pdb_ctx.domain    pdb_ctx.process
   2.198 -   ------    --------------    ---------------
   2.199 -    xen           -1                 -1
   2.200 -  guest os      0,1,2,...            -1
   2.201 -   process      0,1,2,...          0,1,2,...
   2.202 -
   2.203 -Unfortunately, gdb doesn't understand debugging multiple process
   2.204 -simultaneously (we're working on it), so at present you are limited 
   2.205 -to just one set of symbols for symbolic debugging.  When debugging
   2.206 -processes, pdb currently supports just Linux 2.4.
   2.207 -
   2.208 -   define setup
   2.209 -      file xeno-clone/xeno.bk/xen/xen
   2.210 -      add-sym xeno-clone/xeno.bk/linux-2.4.27-xen0/vmlinux
   2.211 -      add-sym ~ach61/a.out
   2.212 -   end
   2.213 -
   2.214 -
   2.215 -1. Connect with gdb as before.  A couple of Linux-specific 
   2.216 -   symbols need to be defined.
   2.217 -
   2.218 -   (gdb) target remote <hostname>:<port + 1>              /* contact nsplitd */
   2.219 -   Remote debugging using serial.srg:12131
   2.220 -   continue_cpu_idle_loop () at current.h:10
   2.221 -   warning: shared library handler failed to enable breakpoint
   2.222 -   (gdb) set pdb_pidhash_addr = &pidhash
   2.223 -   (gdb) set pdb_init_task_union_addr = &init_task_union
   2.224 -
   2.225 -2. The pdb context defaults to Xen and we can read Xen's memory.
   2.226 -   An attempt to access domain 0 memory fails.
   2.227 -  
   2.228 -   (gdb) print pdb_ctx
   2.229 -   $1 = {valid = 0, domain = -1, process = -1, ptbr = 1052672}
   2.230 -   (gdb) print hexchars
   2.231 -   $2 = "0123456789abcdef"
   2.232 -   (gdb) print cpu_vendor_names
   2.233 -   Cannot access memory at address 0xc0191f80
   2.234 -
   2.235 -3. Now we change to domain 0.  In addition to changing pdb_ctx.domain,
   2.236 -   we need to change pdb_ctx.valid to signal pdb of the change.
   2.237 -   It is now possible to examine Xen and Linux memory.
   2.238 -
   2.239 -   (gdb) set pdb_ctx.domain=0
   2.240 -   (gdb) set pdb_ctx.valid=1
   2.241 -   (gdb) print hexchars
   2.242 -   $3 = "0123456789abcdef"
   2.243 -   (gdb) print cpu_vendor_names
   2.244 -   $4 = {0xc0158b46 "Intel", 0xc0158c37 "Cyrix", 0xc0158b55 "AMD", 
   2.245 -     0xc0158c3d "UMC", 0xc0158c41 "NexGen", 0xc0158c48 "Centaur", 
   2.246 -     0xc0158c50 "Rise", 0xc0158c55 "Transmeta"}
   2.247 -
   2.248 -4. Now change to a process within domain 0.  Again, we need to
   2.249 -   change pdb_ctx.valid in addition to pdb_ctx.process.
   2.250 -
   2.251 -   (gdb) set pdb_ctx.process=962
   2.252 -   (gdb) set pdb_ctx.valid =1
   2.253 -   (gdb) print pdb_ctx
   2.254 -   $1 = {valid = 0, domain = 0, process = 962, ptbr = 52998144}
   2.255 -   (gdb) print aho_a
   2.256 -   $2 = 20
   2.257 -
   2.258 -5. Now we can read the same variable from another process running
   2.259 -   the same executable in another domain.
   2.260 -
   2.261 -   (gdb) set pdb_ctx.domain=1
   2.262 -   (gdb) set pdb_ctx.process=1210
   2.263 -   (gdb) set pdb_ctx.valid=1
   2.264 -   (gdb) print pdb_ctx
   2.265 -   $3 = {valid = 0, domain = 1, process = 1210, ptbr = 70574080}
   2.266 -   (gdb) print aho_a
   2.267 -   $4 = 27
   2.268 -
   2.269 -
   2.270 -Some Helpful .gdbinit Commands
   2.271 -------------------------------
   2.272 -
   2.273 -define setup
   2.274 -  file    .../install/boot/xen-syms
   2.275 -  add-sym .../install/boot/vmlinux-syms-2.4.27-xen0
   2.276 -  add-sym /homes/aho/a.out
   2.277 -end
   2.278 -document setup
   2.279 -  load symbols for xen, xenolinux (dom 0), and "a.out"
   2.280 -end
   2.281 -
   2.282 -define setup-linux
   2.283 -  set pdb_pidhash_addr = &pidhash
   2.284 -  set pdb_init_task_union_addr = &init_task_union
   2.285 -
   2.286 -  set task_struct_mm_offset           = (void *)&(init_task_union.task.mm) - (void *)&(init_task_union.task)
   2.287 -  set task_struct_next_task_offset    = (void *)&(init_task_union.task.next_task) - (void *)&(init_task_union.task)
   2.288 -  set task_struct_pid_offset          = (void *)&(init_task_union.task.pid) - (void *)&(init_task_union.task)
   2.289 -  set task_struct_pidhash_next_offset = (void *)&(init_task_union.task.pidhash_next) - (void *)&(init_task_union.task)
   2.290 -  set task_struct_comm_offset         = (void *)&(init_task_union.task.comm) - (void *)&(init_task_union.task)
   2.291 -  set task_struct_comm_length         = sizeof (init_task_union.task.comm)
   2.292 -
   2.293 -  set mm_struct_pgd_offset            = sizeof (struct vm_area_struct *) * 2 + sizeof (rb_root_t)
   2.294 -end
   2.295 -document setup-linux
   2.296 -  define various xenolinux specific offsets and sizes in pdb
   2.297 -end
   2.298 -
   2.299 -
   2.300 -
   2.301 -
   2.302 -Changes
   2.303 --------
   2.304 -
   2.305 -04.07.15 aho .gdbinit
   2.306 -04.02.05 aho creation
   2.307 -04.03.31 aho add description on debugging multiple domains