GDB Task Debugger Installation Notes.


1) Presentation.
~~~~~~~~~~~~~~~~

Tgdb is a Mach task which allows setting of breakpoints, stepping, writing
or reading data in any other user Mach task (including Unix processes). It
uses a UDP networking interface to get requests from and send commands to a
remote port.

The front-end used is a remote gdb command modified to send UDP requests
over the network.

2) Installation.
~~~~~~~~~~~~~~~~

Tgdb can be launched independently of the kernel or the servers configurations.

To build tgdb from the microkernel sources, just go into the directory src/tgdb and
type 'build' (build is part of the ODE tools).

o On the test machine:

	- copy the binary in the /mach_servers directory.
	- add the entry in the /mach_servers/bootstrap.conf file
	  for example:
  
	bash# cat /mach_servers/bootstrap.conf
	task_debugger tgdb
	default_pager default_pager.main sd14b
	name_server name_server.main
	-k startup osf1_server.main+afs+debug sd14a

o On the machine running gdb:

	add these entries in the /etc/services file

	remote-debug 468/udp                 # remote debug
	remote-task-debug 469/udp            # remote task debug

	add the permanent entry in the ethernet cache:

	bash# /etc/arp -s machinename xx:xx:xx:xx:xx:xx
		
where machinename is the name of the machine running tgdb.
xx:xx:xx:xx:xx:xx is its ethernet address displayed during boot.

Note: tgdb is not used to debug the kernel, although the same
remote gdb is used. Therefore you can attach to the kernel only
if it is compiled with the KGDB option.
To attach to the kernel, use the task id 0.

3) Attaching a task.
~~~~~~~~~~~~~~~~~~~~

You need to have access to the sources and binary of the debugged task 
of the remote host.
Building with -g is not mandatory if you don't need the symbols
(eg just set some variables).

The commands are the same as the standard gdb, plus the following:

o target ether 'machinename' 
  set the remote machine to be debugged.

o attach 'task #'		    
  attach to the task. 
  You can only debug one task in a session.

o info threads 'task #'
  show the list of threads running in the attached task.
  You can list threads of other tasks only when attached to the kernel.
	
o info tasks
  only valid when debugging the kernel.

o set $thread = 'thread #'
  switch current thread.

o set task = 'task #'. 
  switch current task (only in debugging the kernel).

4) Example.
~~~~~~~~~~~
Attaching the osf1_server running on host 'fang'

hpux# gdb osf1_server
GDB is free software and you are welcome to distribute copies of it
 under certain conditions; type "show copying" to see the conditions.
There is absolutely no warranty for GDB; type "show warranty" for details.
GDB 4.10-01/14/94 (hppa1.1-hp-hpux),
Copyright 1993 Free Software Foundation, Inc...
(gdb) target ether fang
Remote debugging machinename (remote-debug)
(gdb) att 5		
Attaching program:
  osf1_server task 5 on fang
Error reading remote memory
(gdb) detach
Detached from remote task.
(gdb) quit
hpux#