|
Atari800MacX
Help
Debug Monitor
|
The Debug Monitor on the Atari800MacX emulator allows you to debug
programs written for the Atari800 on the emulator. With it you
can single step programs, display memory, set breakpoints, and much,
much more. Starting with version 4.2, a graphical debugger has
been added.. To access the debugger, simply press F8 while the
emulator is running. The standard command line monitor and the
graphical debugger may be toggled on and off by the Debugger GUI button
on the top of the monitor windows. The following picture shows
the graphical debugger on (the command line monitor is still available
at the top of the graphical debugger). .The graphical debugger is
documented on the Graphical Debugger page.

or, if you are in Fullscreen mode, and Fullscreen Monitor is enabled in
the Display Tab of the Preferences, the following will be displayed:

Commands are typed in the input box at the bottom of the window, or on the command line in Fullscreen mode, and
are executed by pressing return. There is also command history,
so you can get to commands you have entered before with the up an down
arrows. To exit the monitor and continue your program, use the
command 'cont'. To get a list of all of the commands, and simple
help on them type 'help' or '?'. To quit the emulator from the
monitor screen, type 'quit'.
Whenever the monitor stops, it prints out the processor's current status. In the above example, the line is:
262 2 F2FD LDA $02FC ;CH (00FF) A=ff S=f5 X=80 Y=01 P=--*B--ZC
The meaning of the fields in this line are as follows:
262 Vertical scan position when processor
was stopped
2 Horizontal scan position when processor was
stopped
F2FD
Current value of the Program Counter
LDA $02FC Disassembly of the instruction at the PC location
;CH A symbol that is referenced by the instruction
($2FC in this
case)
(00FF)
Value at memory location referenced by instruction,
or in the case of
a conditional branch, a Y or N
which indicates if the branch will be taken. In
this case $02FC contains 00FF.
A=ff S=f5 X=80 Y=01 Current value of the other processor registers
P=--*B--ZC Current value of the processor flags.
The full set of commands and an explanation of their use follows. A parameter in brackets [] means that it is optional:
Monitor Control Commands
HELP
?
Print a list of all commands plus a brief description of each.
CONT
Exits the monitor and continues emulation
QUIT
Quit the emulator.
COLDSTART,
Execute a coldstart on the emulator, and leave the monitor.
WARMSTART,
Execute a warmstart on the emulator, and leave the monitor.
Processor Related Commands
SHOW
Shows the current state of processor registers. (The display is similar to the line displayed when the monitor is entered.
SETPC hexval
SETA hexval
SETS hexval
SETX hexval
SETY hexval
Set the processor register (PC, A, S, X, or Y) to the hexadecimal value specified by hexval.
SETN
SETV
SETD
SETI
SETZ
SETC
Set the specified flag (N,V,D,I,Z, or C).
CLRN
CLRV
CLRD
CLRI
CLRZ
CLRC
Clear the specified flag (N,V,D,I,Z, or C).
Memory Commands
C startaddr hexval...
Change memory starting at the hexadecimal address specified by startaddr with a series of bytes specified by hexval. For example, the command "C 0 00 01 02" would set the byte at address 0 to 0, address 1 to 1, and address 2 to 2.
D [startaddr]
Disassemble memory starting at hexadecimal address startaddr. If startaddr is not specified, then disassembly will continue from the last disassembled location.
F startaddr endaddr hexval
Fill memory starting at hexadecimal address startaddr and ending at address endaddr with the hex byte value specified by hexval.
M [startaddr]
Display memory starting at startaddr location. If startaddr is not specified, then memory dumping will continue from the last dumped location.
MM srcaddr destaddr bytecnt
Move bytecnt bytes of memory starting at address srcaddr to address destaddr. Memory move will handle overlapping regions correctly, reversing the order of copying as needed.
S startaddr endaddr hexval...
Search memory from startaddr to endaddr for a sequence of bytes specified by the hexadecminal values that follow.
STACK
Show the current stack contents.
Each JSR that has occurred will show it's calling location and the
called subroutine. Parameters that have been passed on the stack
are shown separately. The following is an example:
> stack
01F6 : 5E F2 F25C : JSR F2FD
01F8 : EE E6 E6EC : JSR E6F4
01FA : D2 E5 E5D0 : JSR E6EA
01FC : F6 BD BDF4 : JSR BD0F
01FE : 70 A0 A06E : JSR BDED
ROM startaddr endaddr
Convert memory from address startaddr to address endaddr to be considered by the emulator as ROM
RAM startaddr endaddr
Convert memory from address startaddr to address endaddr to be considered by the emulator as RAM
HARDWARE startaddr endaddr
Convert memory from address startaddr to address endaddr to be considered by the emulator as HARDWARE
BANK [banknum]
Switch current memory bank in use to banknum. If the parameter is omitted, then show the current bank number. (XE systems)
READ file startaddr nbytes
Read from the host file named file into memory starting at startaddr for nbytes bytes
READSEC drive sector count addr
Read count disk sectors starting at sector number sector from drive number drive into memory at address addr.
WRITE startaddr endaddr [file] [init>0] [run>0]
Write memory from startaddr to endaddr to a file. If the file parameter is specified, it is used as the filename, otherwise "memdump.dat" is used. The two other optional parameters init and run specify the initialization and run address used for a Atari binary loadable file. If either of init or run is specified, the Atari binary file header is written before the data.
WRITESEC drive# count addr
Write count disk sectors starting at sector number sector and drive number drive from memory starting at address addr.
SUM startaddr endaddr
Add the bytes of memory from startaddr to endaddr and display the result as a 32 bit sum.
Tracing and Execution Control Commands
TRON file
Turn tracing of instructions to a file on. The instruction trace is saved in a file named file.
Each line of the file represents the log of execution of one
instructions, and is similar to the line displayed when the monitor is
entered.
TROFF
Trace instruction tracing previously turned on with the TRON command off.
BREAK [addr]
Set a simple breakpoint at the address specified by addr. If addr is omitted, then display the currently set breakpoint, if any. Specifying a value of zero for addr will turn a previously enabled breakpoint off.
YBREAK [pos]
Set a scanline breakpoint at scanline pos. If pos is omitted, the current scanline breakpoint setting will be displayed. If pos
is -1, the breakpoint will be disabled. Specifying a value for
pos of a scanline + 1000 will cause that scanline to flicker when it is
displayed. For example, ybreak 1100 will cause scanline 100 to
flicker.
BRKHERE [on|off]
Sets BRK opcode behavior to stop in the monitor (on) or not (off).
MONHIST [on|off]
Turn monitor history keeping on/off.
Keeping history will slow down the emulation, so this allows the
debugger to only keep the history when the programmer needs it.
See the HISTORY command next.
HISTORY
H
Display disassembly of last 32 PC
address executed if monitor history keeping has been turned on with
MONHIST. Display is the same format as displayed when the monitor
is entered.
JUMPS
List last 32 locations of JMP/JSR
G
Single step one instruction and return to the monitor.
O
Step over the instruction, which is used to step over subroutine jumps.
R
Execute until a return instruction is executed and return to monitor.
B
Complex Breakpoint Commands.
Complex breakpoints function through a breakpoint table made up
of possibly many breakpoint conditions. The breakpoint checking
has been optimized to have as little impact on emulation execution
speed as possible, however all of the conditions may be checked each
emulated cycle, and the memory location conditions are especially
processor intensive. Each condition (entry) is explicitly anded
with the next, so that a breakpoint only fires if all of the entries
are true. However, the exception to this is the OR condition,
which allows you to have several chains of anded conditions ored
together. An example follows at the end of the subcommand
descriptions. A description of each subcommand follows:
B
Using the B command without a subcommand will print out the current breakpoint table.
B ?
This will print out a brief help summary on the complex breakpoint commands.
B C
This subcommand will clear all breakpoints in the table.
B D num
This subcommand deletes one entry in entry in the breakpoint table, whose number is num. Breakpoint table entries are numbered starting at 0.
B ON
The on subcommand with no parameters
turns the entire breakpoint table ON. Individual breakpoint table
entries must also be on for them to be active.
B ON num1 [num2 ...]
The on subcommand followed by
breakpoint table entry numbers turns the entries associated with those
numbers on. This allows the user to enter breakpoint entries, and
turn them on and off individually.
B OFF
The
off subcommand with no parameters turns the entire breakpoint table OFF.
This means that even if the individual breakpoint table entries are on, no breakpoints will fire.
B OFF num1 [num2 ...]
The
off subcommand followed by breakpoint table entry numbers turns the
entries associated with those numbers off. This allows the user to
enter breakpoint entries, and turn them on and off individually.
B [num] cond1 [cond2 ... ]
This subcommand is used to insert breakpoint table entries. If the option
num
parameter is specified, the entries will be inserted at that breakpoint
number, and existing entries will be shifted to higher numbers.
If
num is not
specified, or is higher than the highest entry plus one, the entry will
be added at the end of the table. A condition (
cond1,
cond2) is on of the following:
TYPE OPERATOR VALUE
This triplet of type operator value is entered with no spaces in between the three components.
Where TYPE is:
PC, A, X, Y, S, READ, WRITE, or ACCESS
Where OPERATOR is:
<, <=, =, ==, >, >=, !=. or <>
And finally VALUE, in hex, is what TYPE is compared to.
For example:
PC=1000 Will break when the program counter is 1000
A<45 Will break when the accumulator is less than 45
X>=4 Will break when the x register is greater than or equal to 4
Y!=2 Will break when the y register is not equal to 2
S==1F6 Will break when the s register is equal to 1f6
READ<1000 Will break when a memory address less than 1000 is read
WRITE>2000 Will break when a memory address greater than 2000 is written.
ACCESS==200 Will break when memory address 200 is read or written
MEM ADDR OPERATOR VALUE
Where MEM is a constant string 'MEM'.
Where ADDR is the memory address, in hex, whose contents is to be compared.
Where OPERATOR is:
<, <=, =, ==, >, >=, !=. or <>
And finally VALUE is what the contents of the memory, in hex, is compared to.
For example:
MEM100=45 Will break when the program counter is 1000
MEM1000>78 Will break when the accumulator is less than 45
SETN
SETV
SETB
SETD
SETI
SETZ
SETC
The condition breaks when the processor flag specified is set.
CLRN
CLRV
CLRB
CLRD
CLRI
CLRZ
CLRC
The condition breaks when the processor flag specified is clear.
OR
The OR condition is a special case and
indicates that the break will fire when the conditions prior to it in
the breakpoint table occur or the conditions after it occur. There can be multiple OR's in the breakpoint table.
Finally, here are some examples of the B commands
B PC>=203f A<3a OR PC=3a7f X<>0
Creates a breakpoint table with 5
entries. Note that ands are implied between conditions, so this
table says the breakpoint will fire if condition1 AND condition2 occur
OR condition4 AND condition5 occur.
B 2
MEM1000=4a
Adds a new entry on position 2
B D
1
Deletes entry on position 1
B OR
SETD
Adds 2 new entries at the end of the table
Atari Hardware Register Commands
ANTIC
GTIA
PIA
POKEY
Display hardware registers for a specific chip.
DLIST [startaddr]
Show the Display List starting at address startaddr. If startaddr is not specified, it will show the display list continuing from where it was last displayed.
DLIST CURR
Show the Display List from the currently in use location.
Assembler Commands
A [startaddr]
Start simple assembler, with assembled code being stored at startaddr. The assembler is exited by entering a blank line.
LABELS OFF
Turn all labels off, both builtin and any loaded by the user.
LABELS LOAD filename
Load user labels from an assembler
output file. This version turns off builtin labels, if you want
builtins enabled, use "LABELS ADD" insead. In versions 4.2 and
greater is does not clear the current user labels, but allows the user
to merge two label files.
LABELS ADD filename
Load user labels from an assembler output file. This turns turn on builtin
labels. In versions 4.2 and greater is does not clear the current user
labels, but allows the user to merge two label files.
LABELS SET name value
Add a user label with the given name and value.
LABELS LIST
List user defined labels.
LABELS VALUE
Lookup label value given name.
LABELS NAME
Lookup label name given value.