Atari800MacX Help
Graphical Debugger



The Graphical Debugger 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.  The debugger has the command line Debug Monitor at the top, followed by displays of the CPU Registers, Assembly Code listing, Stepping buttons, and a tabbed interface which can display memory, watchpoints, stack trace, breakpoints, label management, and hardware registers.



CPU Registers



The CPU register display displays each of the CPU registers, and breaks the P register out into the flags contained within it.  If the register has changed since the last time the display has been updated, the registers will be displayed in red.  In the above example, the PC, A, and P registers have changed, as well as the C flag.

Assembly Code



The assembly code display shows the disassembled code around the current program counter.  The current location of the program counter is indicated by the small red arrow on the left column of the display.  The other two indicators in that column in the above picture are indicators for breakpoints.  The light blue breakpoint is disabled, while the one that is dark blue is enabled.  A new breakpoint may be created by left clicking in this left column on a row where no breakpoint exists.  If a breakpoint does exist, clicking in this column with enable/disable it. 

The address of the memory disassembly may be changed by entering either a hex address or a label name in the Address: field.

In addition, right clicking in the assembly language area will produce the following menu:



There are 5 options in the menu.  The Run To Here.. menu option sets a temporary breakpoint at the selected line and restarts the emulator.  (Note for those using the command line monitor, this uses the simple "BREAK" breakpoint from the monitor).

If there is is a breakpoint on the line that is right clicked, three options to manage that breakpoint are available.  First, the breakpoint may be deleted.  If it is enabled, it may be disabled, or if it is disabled, it may be enabled.  Finally, the breakpoint may be edited using the Breakpoint Editor.  If there is no breakpoint on the line that is clicked, a breakpoint may be added.

Stepping Buttons



These four buttons allow the user to control program execution.  The GO button causes program execution to continue, exiting the debugger (this has the same function as the monitor "CONT" command).
The STEP button is used to execute the next instruction, and return to the debugger.  This is also known as step into, as it will follow a JSR instruction.  It works the same as the "G" command in the monitor.
The OVER button is used to execute a step over.  It works the same as the STEP button for most instructions, but it will step over JSR instructions, stopping after the CPU returns from executing the subroutine that is called.  This works the same as the "O" command in the monitor.  (Note, this also uses the temporary breakpoint that is used by the Run to Here command).
The OUT button is used to step out of a subroutine.  It will execute until a RTS instruction.  It works the same as the "R" command from the monitor.

Memory Display



The memory display shows 128 bytes at a time of the Atari memory map.  The starting memory address that is displayed may be changed by entering a value in the Address: field.  You may enter a hex address or a label value in this field.  The memory address can also by changed by the stepper control next to the address field. It will move the address by 0x10 or 16 bytes up or down.  In the right column, the ASCII values of the memory locations in each row are displayed. The value of memory locations may be changed by left clicking on a location and entering the new hex value. If a memory value has changed since the last debugger update, it will be displayed in Red.

Memory may be searched by entering a string of values to search for into the Find field.  For example to search for a sequence of three bytes valued 0x01, 0x02, and 0x03, you would enter "01 02 03" into the field.  Then pressing the First button, will find the first occurrence of this sequence in memory, moving the memory window starting address if needed.  The sequence will be highlighted in inverse text.  Pressing Next will move to the next occurrence of the sequence, until the last occurrence is found (which will be indicated by a system beep).

Finally, right clicking on a memory location in the table will bring up the following menu:



This may be used to add a Watchpoint for the address, either 8 or 16 bits.  Watches are explained in the next section.

Watchpoints/Stack Display



On the right side of this tab, the stack trace is displayed, showing the return locations for subroutines, and the associated subroutine call.

The left side of the window shows the current watchpoints,  these are Atari memory locations that are read and displayed after every debugger update.  There are four columns in the display.  The Expression column is where the user enters the memory address to be watched.  This may be either a hex address or a Label name.  The address column displays the hex address being watched.  The Value column displays the value at the Watch address, either a 8 bit or 16 bit value.  The format of the Value column may be changed using a right click menu.  This same menu is also used to create a new Watch line in the table:



When a Watch is added with this menu, it is added with an Expression value of "----" which must be edited to the desired address.

The next menu items allow the user to select if the Watch point is a Byte (8 bits) or a Word (16 bits).  The following menu items allow the user to select the format of the watch display, as either signed or unsigned decimal, hex, or ASCII characters.

Finally, the final items allow you manage memory breakpoints at the watch location.  You can set a breakpoint that will fire when the location is read, written, or accessed (either read or written).  Or, you can set a breakpoint when the watch value is equal to a certain value.  When this option is chosen, and small window is opened to allow the user to enter the value.

Breakpoints



This display shows the current breakpoints set in the emulator.  The first two breakpoints listed are the PC breakpoints which we saw earlier in the assembly language display.  The second column checkbox shows if the breakpoint is enabled or disabled. The third column shows the value of the breakpoint.  In addition to PC and memory breakpoints, other register values may be used to qualify the breakpoint.  All of the conditions listed in the third column must be true for the breakpoint to fire.  Therefore,  the third breakpoint will fire if either memory address 0x68 or 0x69 is accessed.  This is the memory watch breakpoint we saw set on the second watch in the above description of watches.

Right clicking in the Breakpoint table will bring up the breakpoint menu which allows the user to delete a breakpoint, edit it in the Breakpoint editor, or add a new breakpoint.  The final menu item allows the user to delete all breakpoints.  Double clicking on a breakpoint will also bring up the Breakpoint editor.



Breakpoint Editor



The breakpoint editor allows you to add conditions to a breakpoint, delete conditions, enable/disable conditions, or add new conditions to a breakpoint.  The '-' button next to each condition is used to delete a condition.  The Add condition button is used to add a new condition.  The checkbox next to each condition is used to enable or disable a condition.  All enabled conditions must be true for a breakpoint to fire.  (Note, also in the main breakpoint window, disabled conditions will appear in gray text, while enabled conditions will appear in black text.).  The first text field in each condition is only used for Memory Location conditions to specify the address of the memory location.  The second text field is used to specify the value of the memory location for a memory location condition, the value of a register for a register condition, or the memory address for a read, write, or access condition.  Neither text field is used for a flag condition.

Clicking on the type of condition will bring up the following Popup menu, which allows you to chose the type of condition:



You can chose to break on the value of one of the registers, one of the flags, the value of a memory location, or a read, write, or access of a memory location. 

Clicking on the type of comparison will bring up the following Popup menu:



You can chose an equal, not equal, less than, greater than, less than or equal, or greater than equal comparison for the Breakpoint.

Setting breakpoints in the assembly language table or the Watch table uses a small percentage of the capabilities of the Breakpoint table which is fully described in the Debug Monitor command line description.  However, they provide a much easier interface.  Also, the user must be careful, as they can specify conditions that cause a breakpoint to occur all of the time (for example, PC Reg >= 0), which may cause the debugger to break after every instruction.

Labels



This display allows the user to manage builtin and user labels.  Builtin labels are well known memory locations and hardware registers in the Atari.  There are two different sets of these, one for Atari 800 class machines, and one for the Atari 5200.  Builtin labels may be enabled or disabled using the checkbox in the middle.

The user is also able to define labels.  One way to do this is by entering a label and value and pressing the Add Label button.  The second way is to use the "Load Label File" button to load a file with label definitions.  These are output by most Atari assemblers.  Several files may be loaded, and the labels will be added.  If the user wants to have only labels from one file, the Delete User Labels button should be used before the Load Label File button.

The table at the right of the display shows the currently defined labels.  The table may be sorted on any field by clicking on the header of that column (in either ascending or descending order).  The third column 'B' contains a B if it is a Builtin label, and an U if it is a User label.  The fourth contains a R or W for those builtin locations which have different names for reads and writes.  A 'W' in this column indicates the label is for write label, a 'R" is in the column for a read label.

Hardware



This display shows the contents of 4 of the hardware chips in the Atari.  Like memory and register values, if they have changed since the last debugger update, the register value will be displayed in Red.  The register values may also be edited, but be aware, that not all bits of a register may change, as they may not be writable, and there may be other side effects from changing these registers.