DU Debug
(w)1997, by Craig Graham / Data Uncertain Software
---
DU Debug is (in this form) a simple trace debugger for MiNT.
It uses the standard MiNT debugging interface (no tricky messing
in the vector table or anything).

It was really written to allow me to debug XaAES over the serial
port, but I thought that maybe other folks will find it useful
as well so here it is...

Features include:
- Text interface (use a serial console to debug graphical apps)
- Uses Pexec() mode 0x8000| to launch children in trace mode.
- Use of the u:/proc filesystem to access process contexts.
- PTRACESTEP/PTRACEFLOW/PTRACEGO stepping via Fcntl()
- Understands Lattice C 5.52 extended debug info for source
  level debugging.
- Multiple breakpoints via ILLEGAL substitution & caught SIGILL 
  to the child being debugged.
- Step over breakpoints
- C source level single step tracing
- 68000 Disassembler
- Register dump, with modified register highlighting
- Memory dump (Hex/ASCII)
- Global Variable inspection

All the techniques used are 100% MiNT legal, although the
breakpoint setting probably wont work with memory protection
turned on. I've included source (it's pretty small).

Instructions
-------------

DU Debug is aimed at a rather specialised area - programs
compiled with Lattice C. It only runs under MiNT, so don't
bother trying it under TOS - it just won't work.

To debug a program, you should compile it with full extended
debug turned on for the modules you wish to debug.

Then, type:

	debug myprog.prg
	
and away you go.

What Happens First
-------------------
First, DU Debug will load the executable and attempt to find
some debug info in it. It will then launch the executable
using MiNT's 0x8000|100 mode.

As soon as the program you are debugging is loaded, it will
stop on the first instruction. DU Debug then sets a breakpoint
on the main() function, runs to it then clears the breakpoint.

You should then see a display with a register dump, details
of the current function, module and line number and
a source view with the first line of the main() function
highlighted.

The Source Listing
-------------------
The source listing displays (wherever possible) the current
line (displayed in inverse video) plus two lines above and
two lines below the current. The current line is also
disassembled immediately below the source display.

The disassembly begins at the current program counter, so
you should see disassembly change when stepping one instruction
at a time.

The Register Display
---------------------
The register display shows the values of the standard 68000
registers (not the extra 68030 registers at the moment).
If any registers have changed since the last time they were
displayed (eg. between one instruction and the next when single
stepping), then the changed registers are highlighted in inverse
video.

Single Stepping
----------------
There are four step modes in DU Debug:

<t>	Step 68K Instruction
    This will step by a single 68K assembler instruction.

<z> Step C line
    This will step to the next C line in the current source file.

<f> Step to Flow Change
    Runs until some change in program flow occurs (eg. a 68K 
    Branch instruction)

<s> Step over breakpoint
	If the program is stopped at a breakpoint, s allows you to step
	past the breakpoint without clearing it. It will step one 68K
	instruction past it.

Go
---
Hitting <g> will allow the program to free run. If no breakpoints
are set, you wont be able to get back into the program.

Breakpoints
------------
<b> allows you to set a breakpoint in the program. You are prompted
for an address, and may specify it in one of a number of ways:

Absolute Address			[$]<addr>
Any address in memory, specified in decimal or hex.
		eg.	
			233140		decimal address
			$38eb4		hex address		
		
Symbol Address				<symbol name>
The address is calculated by DU Debug from the executables symbol
table. For example, _main is the label for the start of the main()
function of the program - DU Debug sets a breakpoint using this
to run past the C.O bootstrap code.
		eg.
			_main
			_test_ex
			
Line Address				@<module>:<line>
The really useful one, this allows you to set a breakpoint on
specific lines of code. You should always give just the filename
for the module (no path) and specifiy the line number in decimal.
		eg.
			@test.c:7
			@my_file.c:25


Hitting <l> will list the breakpoints currently set, and
give a source listing of the files.

Hitting <c> allows you to clear a breakpoint (give the address
in the same formats as when setting a breakpoint).

<s> is used to step past a breakpoint without clearing it. 

Credits
--------
Scott Sanders for the excellent (if a little wrong in places)
guide to using the MiNT debug and trace facilities.

Mark Lawrence for donating the nice 68K disassembler (even if
it is written in assembler itself). A dodgy looking bit of code,
but very reliable...
(Mark is my partner in crime in the Intelligent Research Playstation
project)

Written with Lattice C 5.52.

PS. Every Falcon owner should get a Nemesis board - they're dead good.