Documentation of the ATARI DSP56001 Debugger v1.0 (10/02/92).
Updated for 1.01 (11/21/92)

General Interface Overview:
There are two types of windows, the list windows and the action windows.
The list type is used to display:
registers, disassembly, memory, stack, breakpoints and variables.
The action type is used to:
load to memory, set preferences, copy memory, fill memory,
send file, receive file,
evaluate expression, set or edit breakpoint, lock window, goto address/memory
find word and replace word.
A list window can be closed, moved, resized and fulled as the usual way.
An action window can be closed and moved as the latter. The fuller button
is used to reset the window to its old position. The close button acts
always as a Cancel button. The default button can be selected with the
Return key, in wich case the action is done, and the window remains opened. If
the Enter key is pressed, then the action is done and the window is closed.
The same features can be done with the mouse: a single click is equivalent
to the Return key, and a double-click to the Enter key.
If there are other buttons in the window, some are radio-buttons, some are
check buttons and some are other action buttons. They never close the window.

Almost all editable textfields in action windows do scroll. All those fields 
accept regular expression for evaluation (see The Evaluator for regular 
expression syntax).

All the debugger functions are accessible through entries in menus.
You will find the functions description below. At one time,
some menu entries can be disabled because they make no sense in the current 
context.

Mainly, when the program is running, all context actions (except Halt):
Trace Into,
Trace Over,
Skip,
Run
are disabled. The Halt and Host Command functions are selectable.
When the program is stopped, the first four entries are selectable, and
the last two are disabled.

Deeper in Debugging Techniques:
If you use the linker to output the LOD file, you will get the symbols
automatically. Otherwise, if you use the assembler directly, use
asm56000 -a -b source.asm and the cldtolod utility.
Variable names are generated up to 20 characters.
You cannot halt the DSP if the debugged program IPL is higher than 2.
You have no need to change the default IPL level (2), anyway. Note that
you can freely be in IPL0, IPL1 or IPL2 as the debugger polls to communicate
with its remote part. By the way, you should start your program by
setting the HCIE bit of HCR (DSPDebug forces it anyway).
You cannot predefine code between:
P:2 to P:7,			Stack Error, Trace Exception, SWI Exception
P:$1e to P:$1f,		NMI exception
P:$3e to P:$3f,		Illegal exception
P:$7e00 to $7eff,	Remote part of DSPDebug
X:$ffff to X:ffff	DSP ISR

Your program shouldn't use the previous vectors for any purpose when debugging.
For the moment, DSPDebug doesn't check for those addresses when copying,
filling, loading to memory, setting memory by the evaluator ...
Changing HCR during program execution is left to the programmer's
responsibility, except for bits HF2 and HF3. The HCR Host Flags configuration
HF2=1 and HF3=1 are used by the debugger to communicate with its remote part, 
as well as the HSR Host Flags configuration HF0=1 and HF1=1.
Same thing for the OMR bits 0 and 1, which enable the Host Interface.
Remember that the remote debugger uses one stack level when called by the
DSP to handle an exception, or if asked for a Host Interrupt. If there is
no space on the stack for the exception, a Stack Error exception will occur,
and the stack will be reinitialised. This is a difference between running
under the DSP driver and the DSP Debugger, as you have one stack level less.
You can use SWI in your program in order to stop it at some point, in the
same way as the illegal 680x0 instruction. But note that since the SWI 
exception has a lower priority than the Trace exception, the DSP CPU will 
ignore a SWI instruction during a Step Into command.

Software functions description:
DSPDebug menu:
	Informations
Display interesting things as well as the current free memory. The latter
is real time updated and displayed in the window.

File menu:

	Open LOD
Load a LOD file from disk and upload it in the DSP.
The program start address can be set to any address, using the END
statement in the assembler.

ex:
	ORG	p:0
Start:	jmp	Main	;you MUST begin in 0 if you want to be launched
			;by the DSP driver functions DspExec...
			;DSPDebug allows starting from anywhere wich is
			;not a restricted area
	ORG	P:$10
	nop
	nop

	ORG	P:$200
Main:	nop
	nop
	...

	END	Start

The line 'END Start' tells the debugger that the program start address
is the Main function. The default start address of a LOD file is,
of course, the lowest address. For more information about the LOD 
format, read the MOTOROLA DSP Assembler documentation. The debugger
handles P, X, and Y initialized and non-initialized datas.

Warnings:
	"Warning. No _END directive before EOF",
	"Warning. No _DATA directive before EOF",
	"Warning. Tab used",

Error messages:
	"File is empty",
File has a zero length.
	"No _START directive",
File has no "_START" directive, and so is not likely to be a LOD file.
	"Unknown RAM specification",
A RAM specification different from P, X, Y and L is used.
	"Bad number format",
A number which is not of the form FFFF (hexadecimal radix) is used.
	"Bad number size",
A number that exceeds a word size (24 bits) is used.
	"Bad line size",
A line containing more than 10 words is used.
	"Memory access violation",
The program uses vectors which are reserved by the debugger.
	"Invalid RAM address",
A RAM address exceeding the preferences sizes is defined.
	"Invalid block size",
A block size exceeding the preferences sizes is defined.
	"Space or tab expected",
Couldn't find a valid separator.

	Restart LOD
Reloads and restarts the currently debugged LOD program.

	Load ASM
Load an ascii file in a window. This is mainly used to load the source
of the current LOD program.

	Load to memory
Load a file in memory. This allows to load a file into the DSP memory.

	Save from memory
Save a file from memory. This allows to dump part of the DSP memory.
If the file already exists and the expert mode is not set, you will be
warned before overwriting the previous file.

	Preferences
Indicates the available P, X and Y ram sizes on the DSP. They are used in
memory windows, and for the search loop.

Autosave windows. Automatically save current windows configuration at 
quit time.

Autoload windows. Automatically load DEFAULT.DSK windows configuration at 
launch time.

Set expert mode. Skip one-way alerts and less important warnings:
- when quitting the program:
	"Do you really want to quit?"
- when loading a LOD file:
	"Warning. No _END directive before EOF",
	"Warning. No _DATA directive before EOF",
	"Warning. Tabs used.",
- when deleting a breakpoint:
	"Delete breakpoint ?"
- when saving to disk
	"File already exists. Overwrite ?"

Tab size is used in disassembly and source windows.

Set in-line help mode. The options which are described in the in-line help
are indicated by changing the mouse cursor to a magnifier. In-line help
texts are displayed at the bottom of the screen.

Set update mode. (not implemented).

	Save desktop
Save current windows configuration.

	Load desktop
Load a windows configuration.

	Print top window
Prints the top window to ASCII file.

	Quit
Exit the DSP Debugger



Edit menu:

	Copy memory
Copy memory. It manages overlapping memory blocks.

	Fill memory
Fill memory. "Increment" is added to fill value at each loop.

	Modify
Modify breakpoint settings.
If running, the changes will occur at the next context switching.

	Kill
Delete breakpoint
If running, the changes will occur at the next context switching.

	Kill all
Delete all breakpoints
If running, the changes will occur at the next context switching.



Context menu:

	Trace into
Single steps current instruction.
When running, this option is disabled. Use Halt to break program execution.

	Trace over
Sets a breakpoint on the next instruction, and run. Useful for JMP, JScc or
DO LOOP.
When running, this option is disabled. Use Halt to break program execution.

	Skip
Skips the current instruction (sets the PC to the next instruction).
When running, this option is disabled. Use Halt to break program execution.

	Run
Starts program execution from the current instruction.
When running, this option is disabled. Use Halt to break program execution.

	Halt
Halts the program with a NMI exception.
If not running, this option is disabled.

	Send Host Command
Requests the given interrupt vector.
If not running, this option is disabled.

	DSP Reset
Hardware reset of the DSP.
Whether the program is running or not, it hardly resets the DSP and reuploads
the remote debugger part. It restores software and hardware registers.

	Send
Sends a binary words file to the DSP (by the host port).
Data can be 1 word = 3 bytes or 1 word = 4 bytes.

	Receive
Stores all words sent by the running program (by the host port).
Data can be truncated or padded to any byte(s) per word combination.

Actions menu:

	Evaluate exp.
Evaluates a regular expression, display the result in hexadecimal, decimal
and fractional form. See the Evaluator appendice for details on regular
expression syntax.

	Goto
Goto an address/ram on disassembly and memory windows
	
	Lock window
Lock a disassembly or memory window address with an expression/ram.
To unlock the window, enter an empty expression.
 
	Set break
Set a breakpoint with the following parameters:
- address:	where the breakpoint will be set in P ram.
- count:	decremented at each breakpoint hit. The
		context is rerun if count!=0.
- expression:	evaluated at each breakpoint hit. The
		context is rerun if the evaluation doesn't return true (1L).

	Search
Search for word value in memory.
Loop through the specified ram and from the specified address, searching
the "what" word value. If it reaches the top of the memory (as indicated in
the preferences), it restarts from the beginning. It stops when the search
start address is reached.

	Replace			(NOT FINISHED)
Search for word value in memory and replace with another

Windows menu:

	Registers
Displays DSP 56001 registers. Please refer to the Help or DSP Manual.
	
	Disassembly
Displays P ram in assembly code.
Line format:(between [] means optional)
[Check]<address><space>[pc marker]<opcode><[operand]<tab>[operand]...>[Cond]

- [Check] sign ( or $8)
indicates a breakpoint at this address.
One can double-click on the sign in order to edit the breakpoint.
It is also possible to remove it by clicking on the sign, or set one by 
clicking on the space.
If you double-click on a space, a breakpoint will be created at this address
and a breakpoint edit window will open.

- <address>
is the disassembly line address in P ram (16 bits).
If there is a label at this address, its name will be displayed on one line,
with the disassembly line following.
If there is more than one label, they will all be displayed in the same way.

- <space>
is only a separator.

- [pc marker]
indicates if the PC register points to this line of code.
It can be:
	-
 (Up arrow), instruction branches upward.
	- (Down arrow), instruction branches downward.
	- (Right arrow), instruction is not a branch instruction.
	-? (Question mark), instruction branches on memory value.
Memory is not tested to avoid disturbing I/O processing.

- <opcode>
is the instruction opcode.
Help on it is available in-line or by double-clicking on it.

- <tab>
allows the alignement of same types of data
The tab value is set in the preferences.

- [operand]
is one of the instruction's operand.
If it contains an I/O register (X:$ffe? or X:$fff?), its name is printed 
instead of its value, according to the following table:

PBC	is	$ffe0	;Port B Control register
PCC	is	$ffe1	;Port C Control register
PBDDR	is	$ffe2	;Port B Data Direction Register
PCDDR	is	$ffe3	;Port C Data Direction Register
PBD	is	$ffe4	;Port B Data register
PCD	is	$ffe5	;Port C Data register
HCR	is	$ffe8	;Host Control Register
HSR	is	$ffe9	;Host Status Register
CRA	is	$ffec	;SSI Control Register A
CRB	is	$ffed	;SSI Control Register B
SSISR	is	$ffee	;SSI Status Register
SSITSR	is	$ffee	;SSI Time Slot Register
RX	is	$ffef	;SSI Serial Receive data/shift register
TX	is	$ffef	;SSI Serial Transmit data/shift register
SCR	is	$fff0	;SCI Control Register
SSR	is	$fff1	;SCI Status Register
SCCR	is	$fff2	;SCI Clock Control Register
STXA	is	$fff3	;SCI Transmit data Address Register
SRX	is	$fff4	;SCI Receive data register (4-5-6)
STX	is	$fff4	;SCI Transmit data register (4-5-6)
BCR	is	$fffe	;Port A Bus Control Register
IPR	is	$ffff	;Interrupt Priority Register
You can double-click on one to get the help information on it.

- [expr]	the breakpoint expression set at this address, if any.

Note:
the end of loop address of a DO LOOP instruction is incremented by 1
in the display, to allow the symbol address matching.

Buttons:
	I:	Trace Into
	O:	Trace Over
	S:	Skip
	R:	Run
	PC:	If selected, locks the window with the PC
	
	Memory
Displays P, X, Y, or L ram in hexadecimal or fractional base.
(You can't use fractional base in L ram.)
Buttons:
	P:	Selects P ram
	X:	Selects X ram
	Y:	Selects Y ram
	L:	Selects L ram
	H:	Displays in hexadecimal radix
	F:	Displays in fractional form
	
	Stack
Displays the 15 SSH and SSL. The current level of the stack is
indicated by an horizontal line. That means the initialized stack
is from SSH1-SSL1 to the horizontal line.
	
	Breakpoints
Displays the breakpoints list. You can scroll the cursor, and double-click
or press return on one to change its settings.

	Variables
Displays the variables list. You can scroll the cursor, and double-click
or press return on one to go directly to the variable address.
The display is alphabetical.

	Host regs
Edit DSP Host registers
If running, the changes will occur at the next context switching.

	SSI regs
Edit DSP SSI registers
If running, the changes will occur at the next context switching.

	Close window
Closes current window.

	Cycle window
Cycles through the program windows list.

Help menu:

	Index
	Back
	Registers
	Assembly
	Host
	SSI
	User

The Help modes:
There are two kinds of help:
-the in-line help, which is displayed at the bottom of the screen if the
In-line Help flag is set in the preferences. This help mode provides
on line upon each menu title and entry, each active object in action 
windows, and each window button. It also gives a short definition for
software and hardware registers, and for instructions.

-the window help, which provides a full explanation upon the topic 
chosen by a single click on a bold word (in registers, disassembly 
and help windows).

The Evaluator:

-variables:
	A variable name cannot begin with a digit. It can only include
	characters, digits and underscores(_). If you want to use the
	content of a variable instead of its value, you must preceed it
	with the indirection operator '*'.
		ex: *dummy= $4
	The evaluation is always case-dependent.

-constants:
	They are coded on 32 or 64 bits. They can be written in decimal
	(ex: 123), in hexadecimal (ex: $1FC3), in binary (ex:%101) or
	fractional (ex: .123, 100e-3).

-registers:
	Every register used in DSP addressing modes can be written.
	ex: ( A, AB, A10, MR, SR, A2, etc...)

-adresses:
	Access to a memory location is made in a 56001 syntax:
	X:$1234 accesses to X ram at location $1234.

-operators:
	- Add:			+
	- Substract:		-
	- Multiply:		*
	- Divide:		/
	- Rest (modulo):	%
	- And bit to bit:	& (This operator can't be used with fractional)
	- Inclusive Or:		| (This operator can't be used with fractional)
	- Exclusive Or:		^ (This operator can't be used with fractional)
	- Not bit to bit:	~ (This operator can't be used with fractional)
	- Right shift:		>> (This operator can't be used with fractional)
	- Left shift:		<< (This operator can't be used with fractional)
	- Logical Not:		!
	- Logical Or:		||
	- Logical And:		&&
	- Equal:		==
	- Not Equal:		!=
	- Higher:		>
	- Lower:		<
	- Higher or Equal:	>=
	- Lower or Equal:	<=
	- Set:			=
		the left operand must be a variable, an address or a register.
		ex: (dummy = 3, x:$200 = 45, PC = $41, x:(r0 + 10) = $DEAD)
		In that case, the variable doesn't need the indirection
		operator (its content will be set automatically).
	- Unary Plus:		+
	- Unary Minus:		-
	- Indirection:		*
	- Block start:		(
	- Block end:		)

-error messages:
	"Bad expression syntax",
	"No more memory",
	"Incomplete expression",
	"Constant overflow",
	"Address overflow",
	"Unknown label",
	"Incompatible operator",
	"Fractional overflow",
	"Divide by zero",
	"L-value required",
	"Not implemented"

How to communicate with the DSP Debugger:
As shown in the source example contained in the MSGEX folder, an accessory
(or a program, under MultiTOS) can receive the DSP data from the Host Port
via the debugger and gem-pipe messages. Here is the method to do so:

#define	DSPDEBUG_MESAG	127

typedef enum {
	START_RECEIVE=0,
	END_RECEIVE=1
} DSPDEBUG_CMD;

/* appl_find the DSP Debugger: (for instance at program start) */
	DSP_DebugId=appl_find("DSPDEBUG");

/* appl_write to the DSP Debugger that you are ready to receive: */
	msg[0]=DSPDEBUG_MESAG;
	msg[1]=DSP_DebugId;
	msg[2]=0;
	msg[3]=START_RECEIVE;
	appl_write(DSP_DebugId,16,msg);
/*
and then through the event loop, check for a DSPDEBUG_MESAG message et get
the word from the pipe:
*/
	if (evnt&EVNT_MESAG) {
		if (msg[0]==DSPDEBUG_MESAG) {
			DSP_word=((long)(msg[3])<<16)+msg[4];
			/* do stuff with it ... */
		}
	}
/* when you want to finish the pipe: (for instance at program end) */
	msg[0]=DSPDEBUG_MESAG;
	msg[1]=DSP_DebugId;
	msg[2]=0;
	msg[3]=END_RECEIVE;
	appl_write(DSP_DebugId,16,msg);

	Brainstorm