MykesBug Debugger Version 1.02
©1986,1987,1988,1989,1990,1991 Mike Schwartz, all rights reserved.

This software is NOT public domain and can only be distributed
on a beta-test basis with the permission of the author.  Currently,
the only people that are allowed to beta test this program are
employees of CBM.

* Differences between 1.01 and 1.02 are denoted by '*'.  It is a 
* good idea to read through the document to fully realize the
* extent of the latest changes (a lot happens in a day :)

This is a very preliminary version of a new debugger for the
Amiga that I am currently working on.  This represents only
a few days of work, so as you can expect, it lacks the ultimate
polish it will have, as well as many features that it will
have.  However, what is implemented is stable - I've run
the SAS 'C' compiler, LMK, and various other programs through
the debugger with no problems.

* PLANNED ENHANCEMENTS (Blue Sky)

	1.	Fuller source level debugging support (i.e. >d1)
		for SAS 6.0.
	2.	Source level debugging support for Manx (and DICE?).
	3.	Enforcer/Mungewall/MemMunge features (use MMU).
	4.	Remote debugging via serial port

* PLANNED ENHANCEMENTS (Fer sher)

	1.	Addition of Mixed mode display
	2.	Mouse Input (lots of good ideas here).
		Mouse click on source/dism line will do a
			go (to that line)
		Mouse click on address part of line will
			simply set a breakpoint at the line.
		Mouse click on numbers will autotype them
			on the command line.
		Mouse click on registers...
	3.	Color support (there are 2 planes :)
		Highlight changed registers
		Highlight current PC in display window
		Highlight breakpoints
	4.	"Consistency" check
		validate memory list
		validate low memory addresses
		check stack against bounds
		checksum memory regions
		etc.
	5.	"poor man's history trace"
		Use the trace bit and record history
		of program execution.
	6.	Command line switches for Debug program 
		history size, etc.
	7.	Library breakpoint
		run until somebody calls AllocMem()
	8.	Library trace
		Record calls to library routines
	9.	Command line history and editing improvements
	10.	DOS library structure dumps
	11.	Graphics library structure dumps
	12.	Intuition library structure dumps
	13.	Stack Trace
	14.	Modifyable global symbol table
		This will allow you to comment and label OS
		routines :)
	15.	Context display
		Show symbols
		Select different context/task to debug
	16.	Display of the source file name on screen
	17.	Signal command (sets signal bit of a task)
	18.	CLI local environment variables to be used to
		specify source code directories.  This will
		prevent the need for running Debug from the
		same directory as the sources.
	19.	Full-blown 68010/68020/68030/68040/68851/68881/68882
		disassembly support.
	20.	Display info about MMU setup and usage.

CHANGE HISTORY

1.03 Changes
	1.	*Color added to display.
	2.	*Cursor Up/Down in source mode - use line #
	3.	X Breakpoints use line # if in source mode
	4.	*breakpoints in supervisor context
	5.	*case insensitivity
	6.	Uses GfxBase routines to contruct CopperList.
		(temporarily removed)

1.02 Changes

	1.	MykesBug now does SetFunction on Debug()
		(assembly programmers can just use a TRAP instruction
		 anywhere they want in their code, as well)
	2.	Added Info command, moved library base display
		to info display.
	3.	Added ExecBase command, dumps ExecBase structure.
	4.	Added MemList, ResourceList, DeviceList, IntrList,
		LibList, PortList, TaskList commands for displaying
		Exec lists.
	5.	InitDebugger and CleanDebugger now called via
		Supervisor() and the VBR register is used to locate
		the exception vectors!
	6.	VBL handler no longer cycles pointer color

1.01 Changes

	1.	32 sticky breakpoints implemented, using
		bs,br, and bd commands.
	2.	Single Step changed to restore system before
		stepping.
	3.	Source level single step improved to work
		as good as CPR.
	4.	Source level stepover function is same as
		single step.
	5.	Copper List disassembler implemented, using
		dc command.  Initial dc address is GfxBase->LofList.
	6.	Fixed bug in the mr command that prevented modification
		of data and address registers ('C' syntax problem :)
	7.	Debugger now revectors Alert() to catch OS errors as
		well as CPU exceptions.
	8.	suspend.info added to distribution
	9.	MykesBug now checks for the existance of suspend.info
		and prints instructions on how to create one if it is
		missing.
	10.	Bug fixed in suspend routine to handle case where suspend.info
		doesn't exist (used to try to FreeDiskObject(NULL), which is
		a NONO).
	11.	Bugs fixed in the bc,wc,lc commands.  These now should work.

CONTENTS

This archive should contain the following files:

readme.txt - this file
features.txt - a preliminary features list for the debugger
mykesbug - the resident portion of the debugger
debug - the debug-time portion of the debugger (CLI usage)
test - a very simple demo program that I test debug with
test.s - source to test program above
hello - a 'C' test program to test CLI compatibility and 'C'
hello.c - source to hello program
umain.c - source to _main from SAS (required for source level
	  debugging of hello)
suspend.info - icon for suspend mode AppIcon (this was missing
		from 1.00)

INSTRUCTIONS

* WARNING:  Be sure to turn Enforcer OFF, or MykesBug will fail.

MykesBug is the resident portion of the debugger.  It exists
half in OS land and half in supervisor state.  This program
should be RUN with the RUN command (segment splitting or TSR
functionality to be added, perhaps).  Once MykesBug is running,
it will have revectored all of the low level CPU exception vectors
so it can catch any of these exceptions.  The only vector not 
currently handled is the privilidge violation, because of some
specialized code that exists in the ROM version of the handler.
This will be addressed in the next release.

MykesBug can be installed in your startup-sequence:
	RUN <NIL: >NIL: MykesBug >nil: <nil:

There are two ways to initially activate the supervisor mode
debugger.  The first way is to run a program that gurus.  The
second is to use the Debug program.  The second is the one that
is desired.

To use the debug program, use:

	{RUN} Debug program {parm...}

Debug is a wedge between the CLI and MykesBug (workbench support
to be added).  Debug does a LoadSeg() on the program and also
parses the executable file for symbol and debug hunks.  Currently,
only debug level 1 debug hunks are processed and others ignored.
The symbolic and source level debugging information and other
information is stored in a debugging CONTEXT structure for use
by MykesBug.  This CONTEXT structure is registered with MykesBug -
note that as many CONTEXTs can be handled by MykesBug as you have
RAM for (this allows multiple concurrent debugging sessions).
Debug updates various parts of the CLI structure, sets a breakpoint
at the first instruction in the debugged program (so MykesBug gains
control right away) and then does a JSR to the loaded program.  When
the program returns, Debug prints the exit code and passes this
on via its exit() parameter.

NOTE:  The resident MykesBug can be told to exit by running MykesBug a
second time.  I use this feature to remove an old version and install
a new one.  For example, Run MykesBug (installs mykesbug), Run MykesBug
(Kills first MykesBug), Run MykesBug (installs mykesbug again).

MYKESBUG

MykesBug operates in Supervisor mode of the 68030 (68000 support may
be added in the future).  It is specifically designed to use ZERO
OS functions or resources (i.e. blitter, etc.) and is designed not
to interfere with the OS.  The reasoning is that there is no excuse
for a debugger to crash because the OS has been trashed.  MykesBug
is careful to preserve the state of the OS and hardware, to drive
the hardware directly (as minimally as needed) while in operation,
and to restore the OS and hardware states to allow return to the OS.

MykesBug currently uses the VBL interrupt for mouse counter reading,
keyboard I/O polling (system friendly), and timing.  This is the only
interrupt that will be enabled while the supervisor mode debugger is
running.  MykesBug uses its own copper list, uses two 640x400 planes
(for color support), and renders its own font with the CPU to the
bitplanes (to avoid use of the OS Text() routines).

The MykesBug display screen consists of 5 specific areas.  At the top
of the screen, the current task status is displayed.  The left side
of the display contains Amiga Hardware register display (currently
only INTENA and DMACON).  Below this, on the left side, is the CPU
register display (currently FFP and MMU registers are not displayed).
Included in the CPU register display are the Library base values for
most of the Amiga libraries.  A large window to the right of the
register display is used to display diassembly, hex dumps, source
code, help, etc. (this is a general purpose display window).  The
bottom two windows are used for command line input and for debugger
messages.

COMMAND LINE

The command line entry system for MykesBug is very preliminary and
needs a bit of work.  However, it is quite usable in its current
form.  The concept behind the command line is that you should be
allowed to enter a command and then hit return to execute it.  The
previous command line is retained and displayed.  If you start to
type a new command, the previous line is erased and new command
line input is begun.  Otherwise, you are able to hit return again
to execute the last command again.  You are also allowed to edit
the previous command line by using the backspace key (cursor key
command line editing will be added).  Also mouse support is to be
added, but the mouse is there and works and there is even a mouse
blanker so the pointer doesn't get in the (visual) way.

There are several keys that are accepted during command line input
that perform different features.  For example, the TAB key can be
hit and this causes the SYSTEM copper list (obtained from GfxBase)
to be displayed by the copper until a key is hit.  Other keys that
work similarly are the ^X key which clears the command line, HELP
key which displays on-line help, the ^C key which terminates a
debugging session (see below), and the up and down cursor keys
which scroll the general purpose window (disassembly/source...).

The Up and Down keys on the keypad now scroll the display up/down.
The cursor left/right keys should now allow command line editing.
The cursor up/down keys will be used to implement command line
history.

Function keys are now supported, minimally.  The current bindings
are displayed by the he (help) command.  There will be a startup
script and commands to set these per debugging context.

IMPLEMENTED COMMANDS

* ?                    Display Task Info
* ExecBase             Display ExecBase
* MemList              Display Mem List
* ResourceList         Display Resource List
* DeviceList           Display Device List
* IntrList             Display Intr List
* LibList              Display Lib List
* PortList             Display Port List
* TaskList             Display Task List

bs addr              set sticky breakpoint at addr
br addr|ALL          clear breakpoint at addr or clear all
bd                   display breakpoint table
dc addr              display copper list {at addr}

he                   this list (HELP KEY)
db {addr}            display bytes at addr
go {addr}            go {to addr}
lm {addr}            list (disassemble) memory {at addr}
so {addr}            display source {at addr}
b? addr              display byte at addr
w? addr              display word at addr
l? addr              display longword at addr
bc addr              run until byte changes
wc addr              run until word changes
lc addr              run until long changes
mb addr val {val...} modify bytes at addr to val {val...}
mw addr val {val...} modify words at addr to val {val...}
ml addr val {val...} modify longs at addr to val {val...}
REBOOT               reboot the machine
ss                   single step
st                   step over
ex                   exit debugging context (^C)
su                   suspend debugging session/context (^Z)
mr reg val           modify a register to a value

All commands must be lower case (the first two letters).  Symbols
may be mixed case.

Three commands are currently bound to keys during command input.
These are HELP KEY (he command), ^C key (ex command), and ^Z key
(su command).

COMMAND DISCUSSION

The ex command only works if the debugged program has a routine
named "abort", "Abort", or "XCEXIT".  The command works by changing
PC to point at this routine and then a GO command is done.

The su command causes an AppIcon to be added to the workbench screen
for the context and the system is restored.  The AppIcon name will be
the name of the task.  To reactivate the debugging context, double
click on the AppIcon.

The st command is implemented by setting a breakpoint after the current
instruction.  It allows you to step over jsr,bsr, etc.  It also allows
you to step over a DBRA (handy!).  It is not yet smart enough to not
fail at an RTS (trivial to fix).  It is also not yet smart enough to
detect source display mode and to set the breakpoint at the next source
line.

The b?, w?, and l? commands are similar to their equivialents in the
JForth environment.  These cause a single value to be displayed in
the prompt area.

ADDRESS EXPRESSIONS

Whenever command line input requires an address or other number, 
certain expressions are allowed.  Any hex number may be typed in 
(hex is the default).  If a decimal number is desired, precede it
with a period (.).  In addition, the following strings are recognized:

(pc)	where program counter points
(ip)	where program counter points
*	where program counter points
(sp)	where stack pointer points (note this is system stack pointer)
(usp)	where user stack pointer points (this is the application's SP)
(d0)	where d0 points
(d1)	where d1 points
(d2)	where d2 points
(d3)	where d3 points
(d4)	where d4 points
(d5)	where d5 points
(d6)	where d6 points
(d7)	where d7 points
(a0)	where a0 points
(a1)	where a1 points
(a2)	where a2 points
(a3)	where a3 points
(a4)	where a4 points
(a5)	where a5 points
(a6)	where a6 points
(a7)	where a7 points

No arithmetic expressions or otherwise more complex expressions are supported
(yet).  This means that 1+1 is illegal, as is 24(a6).  Note:  lower case is
required for the above expressions.


BUGS/PROBLEMS

The source mode display has problems because of the way level 1
debug hunks are generated by SAS.  Multiple source lines may have
the same PC value.  This display mode is going to be replaced with
a MIXED mode of source and disassembly.

MykesBug copperlist and bitplanes are permanently allocated in CHIP RAM.  This
makes the debugger vulnerable to wild blits, wild stores, etc.  This will be
fixed by having the debugger swap what CHIP RAM it needs with FAST RAM.

MykesBug does not currently use the MMU to protect itself from wild stores by
the OS or other programs.  This can make MykesBug not seem as bulletproof as
it will shortly become.

The Task Name is derived from the task.node.ln_Name.  For CLI programs, this
string is "Background CLI".  This will be fixed to show the program name.

MykesBug is currently 41 hunks.  It needs to become 1 contiguous hunk so it
can easily be protected with the MMU.

Since MykesBug operates in SuperVisor mode, it does not have access to OS
routines.  This makes it not possible to do DOS, for example.  For this
reason, the Debug program will read 100% of your source files (if -D1 hunks
are present) into RAM.  For HUGE projects, this can either take a lot of
time or may require a lot of RAM.

The disassembler has a few bugs in it and only disassembles 68000 instructions.

* Keys don't autorepeat!

* Mouse does NOTHING ( YET! :)

* The debugger used to ALWAYS return from suspended state to exactly the state
* it was in (i.e. if you were displaying help, you are still displaying help).
* With the addition of the Exec oriented list commands and info command, this
* is no longer true.

* From time to time, the command line is trashed (displays garbage) when 
* running debug (first command) or unsuspending a debug session.

* 'C' is such a hog that the program is getting big.  Global optimizer is
* not being used currently, though (too slow for development purposes).

* 'C' compiler complains about valid syntax for the code that does SetFunction()
* and if the instructions aren't tweaked to just the right order, the compiler
* quits with a CXERR #25 message.  BLINK is taking a long long time.  Wonderful, no?

* When Exec lists are displayed, they can be too long to fit in the window.  The
* keypad cursor keys don't scroll these displays.

* Workbench support for MykesBug and Debug is not fully implemented.  MykesBug should
* create an AppIcon so you can drag programs onto it to debug them (mykesbug will
* run Debug automatically).  Additionally, double clicking on this icon should activate
* the resident MykesBug debugger.

* It is not clear if MykesBug works on an 040 processor.  MykesBug certainly does not
* work on a 68000!

* The copper list used by MykesBug is not aware of future/enhanced chipset registers.
* It is likely/possible that these registers may be set to an incompatible state
* with the copper list.

* MykesBug does not support the FPU or MMU at all.  The FPU and MMU registers should
* be preserved and restored as the rest of the registers are.  These registers should
* also be displayed on the screen and should be alterable with the mr command.