README


			GDB on the Nintendo 64
		    by Steve Shepard (sjs@sgi.com)

Building the Library
--------------------
To make the GDB library, type:
	
	make libgdb

To make the mdebug patch tool, type:

	make -f Makefile.whang whang

Using GDB with Nintendo64 Apps
------------------------------

0) Make sure the correct version of the u64 driver is installed.

1) Build libgdb

2) Build whang

3) Link the app with libgdb. Make sure the library is linked BEFORE
libultra.

4) Run whang on the resulting elf file (not the rom image).

5) Run the app

6) Run GDB with the elf file

7) Connect to the target with the GDB command 

	target remote /dev/u64_debug

TO DO
-----

* Add better thread support. Currently, GDB only knows about threads
if you happen to stop/break in one. The protocol should be enhanced to
allow the target code to announce *all* threads when it contacts the
GDB host.

* Add code to the GDB exception handler to handle bad
addresses. Currently, if GDB--via the protocol--requests a memory
write to an invalid address, the target code will hang. Should patch
the exception vectors to simply set a bit if the handler takes an
exception.

* Remove dependency on internal header files. Libgdb currently
requires osint.h, threadasm.h, and exceptasm.h from the PR/libultra/os
directory. When a better solution for patching the exception handler
is discovered, the need for these should go away. Until then, if you
are building the lib outside the SGI (or Nintendo?) tree, you'll need
to make sure you have these files.

BUGS
----

* odd-even fp registers are sent in the wrong order. fp7 is really
fp8, and fp8 is really fp7.

* procedures nested *1* level from the top are reported as the top
stack frame.

* nld puts bogus file offsets in .mdebug section. We currently get
around this with the "whang" tool, which patches the .mdebug section.