BBC Debugger
============


1. INTRODUCTION

This application provides a graphical debugging environment to the BBC Microcomputer emulator.


2. ENTERING COMMANDS

2.1. Commands

help					Print list of available commands.
help <command>				Print help for specified command.

quit					Quits the debugger.

reset					Resets the emulated computer.

dump					Print memory dump of 32 bytes, nearest to the current value of the program counter
					to the command window.
dump <address>				Print memory dump of 32 bytes, containing the memory location <address> to the
					command window.
dump <start> <end>			Print memory dump, starting at memory location <start> and ending at <end> to the
					command window.

disassemble <start> <end>		Disassembles instructions between <start> and <end> using SMART disassembly
disassemble <start> <end> true		Disassembles instructions between <start> and <end> using SMART disassembly
disassemble <start> <end> false		Disassembles instructions between memory locations <start> and <end>
					"SMART" disassembly means follow subroutines etc.

step					Execute instruction pointed to by the program counter.
step <n>				Execute <n> instructions starting with the instruction pointed to by the program counter.
					Execution is stopped if a breakpoint is reached or "Interrupt" button is pressed.

next					As step, except subroutines are executed as one instruction.
next <n>				As step <n>, except subroutines are executed as one instruction.

run					Execute instructions until a breakpoint is reached or "Interrupt" button is pressed.
run <n>					Execute instructions until the <n>th breakpoint is reached or "Interrupt" button is pressed.

set <register> <data>			Set the CPU register to <data>.
set <register> | <data>			Bitwise OR the contents of CPU register with <data>.
set <register> & <data>			Bitwise AND the contents of CPU register with <data>.
set <address> | <data>			Bitwise OR the contents of memory location <address> with <data>.
set <address> & <data>			Bitwise AND the contents of memory location <address> with <data>.
set <address> <data 0> [<data 1> ...]	Set concurrent memory location(s) starting at <address> to <data n>.

print <register>			Display the contents of the CPU register.
print <address>				Display the contents of memory location <address>.

break <address>				Sets or removes a breakpoint at memory location <address>.

clear					Removes all breakpoints.

display disassembly <address>		Displays disassembly at memory location <address>.
display memory <address>		Displays a memory dump at memory location <address>.


2.2. Format of Parameters

<register>	One of the CPU registers: A, X, Y, PC, SP, PSR

<address>	16-bit address specified in hex, i.e. 0000 - FFFF

<data>		Data element specified in one of following formats:
		15	= 13 decimal
  		&0d	= 0d hex (13 decimal)
  		%1101	= 1101 binary (13 decimal)
  		'A'     = ASCII character 'A' (65 decimal)
		"A"     = ASCII character 'A' (65 decimal)
		
The set command can take a mixture of data formats, the following examples are all legal:
		
set 100 65			= Sets memory 0100 hex to 65 decimal.
set 100 &10     		= Sets memory 0100 hex to 10 hex.
set 100 %10000000		= Sets memory 0100 hex to 80 hex.
set 100 'A'			= Sets memory 0100 hex to 65 decimal.
set 100 "ABC"			= Places the ASCII character 'A' (65 decimal) into memory 0100 hex,
				  'B' (66 decimal) into 0101 hex, and 'C' (66 decimal) into memory 0102 hex.
set a00 &10 %1100 "Test" 'z' 0	= Places data as above for each element into memory starting at 0a00 hex.



3. GRAPHICAL INTERFACE

3.1. File Menu

3.1.1. Load

Loads the contents of a file into memory at the specified address.
If data is loaded between 8000 hex and C000 hex, it is loaded into the specified paged
memory bank.


3.1.2. Save

Saves the contents of memory from the start address to the end address inclusive,
to a file. If data is saved between 8000 hex and C000 hex, it is saved from the specified
paged memory bank.


3.1.3. Exit

Terminates the debugger.


3.2. Debugger Menu

3.2.1. Wide Memory Display

Toggles between memory display width of 16 bytes and 32 bytes.


3.2.2. Hardware Status

Not yet implemented.


3.3. Help Menu

3.3.1. About

Displays short program version information.


3.4. Run Button

Executes CPU instructions until a breakpoint is reached or the 'Interrupt' button is pressed.
Display will only update once execution has stopped.


3.5. Interrupt Button

Interrupts execution of CPU instructions, applies to 'run', 'step' and 'next' commands.


3.6. Step Button

Execute the instruction pointed to by the program counter.

3.7. Next Button

Execute the instruction pointed to by the program counter. Subroutines are executed as one
instruction.


3.8. Disassembly Window

The disassembly window displays instruction disassembly. Instructions in RED are UNDOCUMENTED
instructions. A green arrow shows the instruction pointed to by the program counter (PC).
Breakpoints are shown by a red 'stop' sign.

The commands 'run', 'step' or 'next' will cause automatic disassembly of instructions as
the program counter encounters un-disassembled memory.

If memory has been modified and auto-disassembly has not occurred, manual disassembly can
be performed via the 'disassemble' command.


3.9. CPU Status Window

The CPU status window displays the current status of CPU registers and the clock count.


3.10. Memory Window

The memory window displays a memory dump, hex and ASCII.


3.11. Command Window

The command window is used to enter commands.
Entering a 'blank' command, i.e. just pressing <RETURN> will perform the last
command entered.



4. REQUIRED ROM IMAGES

No ROM images are required, although the emulator attempts to load the following:
    OS12.ROM		Acorn BBC Operating System ROM version 1.2
    BASIC2.ROM		BASIC version 2
    
All ROM images must be placed in the ROM directory.



5. REPORTING BUGS

Any comments or bug reports should be made to bbcmicro@qualsar.co.uk