appendix-monitor.tex

\chapter{Machine Language Monitor}
\label{cha:MLMonitor}
\section{Introduction}

A machine language monitor is a program for inspecting and experimenting with the internal state of a computer's CPU and memory, useful for debugging machine language programs and exploring how the computer works. A typical monitor can view and modify the contents the CPU registers and memory, disassemble machine code, assemble instructions directly to memory, and manipulate memory in other ways, among other features.

The MEGA65 has two separate machine language monitors built in: one in the ROM (the MEGA65 monitor), and one that is part of the Matrix Mode debug interface (the Matrix Mode/serial monitor). Each monitor has different features and uses.

The monitor in the MEGA65 ROM is similar to one that was included with the original C65 ROM, more complete and with more features. It is included in both the MEGA65 closed ROM and the enhanced MEGA65 OpenROM. If you are using an original C65 ROM, its monitor works similarly.


\section{The MEGA65 Machine Language Monitor}
\index{MONITOR!MEGA65 Monitor}

The machine language monitor included with the MEGA65 ROM can be invoked in several ways. From BASIC, you can invoke the monitor with the {\screentext MONITOR} command. You can also cause the MEGA65 to boot directly into the monitor by holding the \specialkey{STOP} key during start-up.

The MEGA65 monitor activates automatically when program execution encounters the {\bf BRK} instruction (byte value {\tt 00}). You can cause your program to pause and open the monitor at a specific point by including a {\bf BRK} instruction in the program code at that point.

When the monitor starts, it displays the register contents, then waits for a command:

\begin{tcolorbox}[colback=blue,coltext=white]
\verbatimfont{\codefont}
\begin{verbatim}
MONITOR
    PC   SR AC XR YR ZR BP SP
; 000000 00 00 00 00 00 00 F8
\end{verbatim}
\end{tcolorbox}

\subsection{Numbers}
\label{sec:numbers}

The monitor uses hexadecimal (base 16) to display numbers, such as memory addresses and values. Hexadecimal values are printed without a leading `\$` character, such as {\tt 5A} or {\tt D020}.

You can enter a value in hexadecimal, decimal (base 10), octal (base 8), or binary (base 2). Each number format uses a character prefix, as shown in the table below. If you omit the prefix, the monitor assumes the value is in hexadecimal. (This is unlike BASIC, which assumes decimal without a prefix.) You can also enter a byte value as a PETSCII character, with the appropriate prefix.

Hexadecimal is the default number format for assembly instructions as well. This can be confusing! Consider what happens when you tell the monitor to assemble the following instruction:

\begin{verbatim}
LDA #10
\end{verbatim}

A typical assembler interprets this as loading the decimal value 10 (hex {\tt 0A}) into the accumulator. The monitor assumes this is the hexadecimal value {\tt \$10} (decimal 16). To avoid confusion, always provide an explicit prefix character for numbers in assembly instructions. The monitor's disassembler shows all values as hexadecimal starting with the {\tt \$} prefix.

All numbers must be literal values. The monitor does not understand arithmetic expressions.

You can use the monitor to show all the base conversions of a given number or PETSCII character. To do this, enter the number as if it were a command, using its prefix. The {\tt \$} is required for hexadecimal numbers in this case to distinguish it from other monitor commands.

The following table shows the prefixes for each way a value can be entered:

{\ttfamily
{\setlength{\tabcolsep}{1mm}
\begin{center}
\begin{tabular}{|l|l|l|l|l|}
\hline
 base  & name & prefix & digits characters & example     \\
\hline
16 & hexadecimal  &     & 0123456789ABCDEF &   100       \\
16 & hexadecimal  & \$  & 0123456789ABCDEF & \$100       \\
10 & decimal      &  +  & 0123456789       & +256        \\
 8 & octal        & \&  & 01234567         & \&400       \\
 2 & binary       & \%  & 01               & \%100000000 \\
   & character    &  '  & all              & 'A          \\
\hline
\end{tabular}
\end{center}
}
}

\subsection{The Assembler}

The monitor has a builtin mini-assembler that can be used to write machine language code using the standard mnemonics like {\bf LDA} or {\bf STA}.

This is not a full assembler like you might use to write large programs. In particular, it does not support symbols, such as labels for subroutines or KERNAL addresses. Instead of {\ttfamily {\bf JSR CHROUT}}, you must look up the address of {\ttfamily {\bf CHROUT}} and enter the number value: {\ttfamily {\bf JSR FFD2}}

For convenience, you can provide a full address to a branch instruction. The monitor calculates the relative address offset to assemble the instruction.

The assembler knows all of the instructions and address modes of the MEGA65
CPU 45GS02. An instruction like {\ttfamily \bf LDA [TXTPTR],Z}
will be assembled as loading the accumulator using a 32-bit pointer
at the addresses {\ttfamily \bf TXTPTR, TXTPTR+1, TXTPTR+2, TXTPTR+3}.

\subsection{Differences from the C65 Monitor}

The MEGA65 monitor is similar to the monitor included with the C65. It includes multiple enhancements beyond the C65 monitor, both to make the monitor more generally useful and to extend it to support features specific to the MEGA65 architecture.

The MEGA65 monitor has the following exclusive features:

\begin{description}[leftmargin=1cm,style=nextline]
\item[Addresses:] All addresses are used as 32-bit (4 bytes) addresses.
   This allows access to the whole MEGA65 address range, which needs
   28-bit. This is especially useful for the access to the 8MB RAM blocks
   called attic RAM at \$8000000 (builtin) and cellar RAM at
   \$8800000 (optional). Setting bit 31 of an address to 1 gives access
   to a special (banked) configuration. In this case the I/O area at \$D000
   and the ROM area \$6000 - \$7FFF (monitor ROM) and \$E000 - \$FFFF
   (KERNAL ROM) overlay the current bank.

\item[Commands:] The additional command {\bf B} displays character bitmaps.

\item[Disk access:] The disk command character {\bf \@} knows two more
  functions: {\bf U1} for reading a sequence of disk blocks to memory and
  {\bf U2} for writing a memory range to disk blocks. This enables disk
  disk editing, for example modifying directory entries or can be even
  used to backup whole floppy contents or disk images. The attic RAM is
  large enough to hold the contents of 8 complete 1581 floppies.

\item[Disassembler:] The disassembler can decode all additional
  address modes, like the 32-bit indirect mode $[\$nn],Z$
  and the compound instructions involving the use of the 32-bit Q register.

\item[Register:] The register displays the full 16-bit stack pointer
 and the base page register and accepts new settings for ithem.

\end{description}



\subsection{Table of MEGA65 Monitor Commands}

{
\ttfamily
\setlength{\tabcolsep}{1mm}
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
C & mnemonic & description \\
\hline
A &     ASSEMBLE        & Assemble a line of 45GS02 code\\
B &     BITMAPS         & Display 8x8 bitmaps (characters)\\
C &     COMPARE         & Compare two sections of memory\\
D &     DISASSEMBLE     & Disassemble a line of 45GS02 code\\
F &     FILL            & Fill a section of memory with a value \\
G &     GO              & Start execution at specified address\\
H &     HUNT            & Find specified data in a section of memory\\
J &     JUMP            & Jump to a subroutine at specified address\\
L &     LOAD            & Load a file from disk\\
M &     MEMORY          & Dump a section of memory\\
R &     REGISTERS       & Display the contents of the 45GS02 registers\\
S &     SAVE            & Save a section of memory to a disk file\\
T &     TRANSFER        & Transfer memory to another location\\
V &     VERIFY          & Compare a section of memory with a disk file\\
X &     EXIT            & Exit Monitor mode\\
\hline
 . &     <period>        & Assembles a line of 45GS02 code\\
 > &     <greater>       & Modifies memory\\
 ; &     <semicolon>     & Modifies register contents\\
 @ &     <at sign>       & Disk command, directory or status\\
\hline
\$ &     <hex>           & Display hex, decimal, octal, and binary value \\
 + &     <decimal>       & Display hex, decimal, octal, and binary value\\
\& &     <octal>         & Display hex, decimal, octal, and binary value\\
\% &     <binary>        & Display hex, decimal, octal, and binary value\\
\hline
\end{tabular}
\end{center}
}

% ======================================
% Start of the monitor command reference
% ======================================

\titleformat*{\subsubsection}{\normalfont\huge\bfseries\color{blue}}

% ********
% ASSEMBLE
% ********

\subsubsection{A : ASSEMBLE}

\index{ASSEMBLE}
\index{MONITOR Commands!ASSEMBLE}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf A address mnemonic operand}
\item [Usage:] The mini assembler allows entry of machine language instructions
               using easy to remember mnemonics instead of opcodes.
               The operand may be entered as hex, decimal, binary or character.
               Branch targets are automatically converted to relative distances.
               After each entered instruction, the mini assembler generates
               the 1-5 byte long machine code, prints this code along with the
               instruction and advances the program counter. A new line
               is generated with the command {\bf A} and the new value of the
               program counter printed. This eases the fast entry of instructions.
               The assembly input mode is stopped by pressing RETURN only.
               Any line of the entered code or a line in disassembly format
               can be changed by moving the cursor into that line and changing
               the desired element, for example the mnemonic or the operand.
               Listed hex values before the mnemonic are ignored.

               If the monitor shall be reentered after executing the code,
               the last instruction must be a {\bf BRK} instruction
               and the program must be called with I/O and monitor ROM active.
               This is done by setting the bit 31 of the execution address.
               If the program was entered in bank 0 on address 1500,
               it should be started with: \screentext{G 80001500}.

               If the entered code is a subroutine, it must end with a
               {\bf RTS} instruction.

\item [Remarks:] The assembler recognises all 45GS02 instructions of the
                 MEGA65, including the instructions that use the Q register.
                 {\bf NOP} and {\bf AUG} can be entered, but will be interpreted
                 as {\bf EOM} and {\bf MAP}, respectively.

                 32-bit Base-Page Indirect instructions use square brackets
                 ({\bf [} and {\bf ]}).

\end{description}
\includegraphics[width=\linewidth]{images/monitor-a}

% *******
% BITMAPS
% *******

\subsubsection{B : BITMAPS}

\index{BITMAPS}
\index{MONITOR Commands!BITMAPS}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf B start}
\item [Usage:] Displays memory values interpreted as character bitmaps.

\item [Remarks:] The B command displays the contents of memory cells bitwise
                 by printing an asterisk for 1 and a dot for 0.
                 The special arrangement of character data with 8 bytes
                 forming one character cell, is considered.
                 8 characters are displayed for each call.

                 There are three ROM character sets builtin
                 in the {\tt 92XXXX} ROMs:

\begin{tcolorbox}[colback=blue,coltext=white]
\verbatimfont{\codefont}
\begin{verbatim}
FONT A : REM $029000 : ASCII [\]^_ {|}~ included
FONT B : REM $03D000 : serif version of A
FONT C : REM $02D000 : original C64 font
\end{verbatim}
\end{tcolorbox}
\end{description}
\includegraphics[width=\linewidth]{images/monitor-b}

% *******
% COMPARE
% *******

\subsubsection{C : COMPARE}
\index{COMPARE}
\index{MONITOR Commands!COMPARE}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf C start end start-b}
\item [Usage:] Compares two regions of memory, then lists the addresses whose values differ.

\item [Remarks:] The end address is one beyond the last address to compare.

    The second memory region to compare starts at {\bf start-b} and is the same size as the region described by {\bf start} and {\bf end}.

    Addresses are printed as hex values.

\end{description}
% TODO: screenshot  \includegraphics[width=\linewidth]{images/monitor-c}

% ***********
% DISASSEMBLE
% ***********

\subsubsection{D : DISASSEMBLE}
\index{DISASSEMBLE}
\index{MONITOR Commands!DISASSEMBLE}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf D [from [to]]}
\item [Usage:] Prints a machine language listing for the specified
               address range assuming, that it contains code.
               If only one argument is present, the disassembler
               disassembles the next 21 bytes. If no argument is
               given, the disassembly continues with the last used
               disassemble address.
               The contents are printed as hex values.

\item [Remarks:] The rows start with the dot character '.'.
                 This enables direct full screen editing of the disassembly.
                 Typing return in any row will assemble the changed
                 command of the cursor row back to memory, if writable RAM is there.
                 See monitor command {\bf .}.

                 The disassembler knows the instruction set of the MEGA65 CPU, the
                 45GS02. When an instruction is prefixed by {\bf NEG NEG}, those hex values
                 are elided and instead an asterisk ({\bf *}) is displayed between the address
                 and the hex values.

\item [Example:] Using {\bf D}
\end{description}
\includegraphics[width=\linewidth]{images/monitor-d}

% ****
% FILL
% ****

\subsubsection{F : FILL}
\index{FILL}
\index{MONITOR Commands!FILL}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf F start end value}
\item [Usage:] Fills a region of memory with a value.

\item [Remarks:] The end address is one beyond the last address to fill.
\end{description}
% TODO: screenshot  \includegraphics[width=\linewidth]{images/monitor-f}

% **
% GO
% **

\subsubsection{G : GO}
\index{GO}
\index{MONITOR Commands!GO}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf G [addr]}
\item [Usage:] Executes code at an address. If {\bf addr} is omitted, the current program counter is used as the address.

\item [Remarks:] This is equivalent to a {\bf JMP} instruction.

    The {\bf G} command without an argument is a convenient way to resume execution of a program after starting the monitor with a {\bf BRK} instruction.

    Because this uses a {\bf JMP}, it must not be used to call subroutines. See {\bf J}.

\end{description}
% TODO: screenshot  \includegraphics[width=\linewidth]{images/monitor-g}

% ****
% HUNT
% ****

\subsubsection{H : HUNT}
\index{HUNT}
\index{MONITOR Commands!HUNT}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf H start end byte [byte...]}
\item [Usage:] Searches for every occurrence of a byte sequence in a range of memory, then lists the starting address of each occurrence.

\item [Remarks:] The end address is one beyond the last address to search.

    Addresses are printed as hex values.

\end{description}
% TODO: screenshot  \includegraphics[width=\linewidth]{images/monitor-h}

% ****
% JUMP
% ****

\subsubsection{J : JUMP}
\index{JUMP}
\index{MONITOR Commands!JUMP}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf J addr}
\item [Usage:] Jumps to a subroutine at an address.

\item [Remarks:] This is equivalent to a {\bf JSR} instruction. When the subroutine returns with {\tt RTS}, the monitor resumes.

    To simply continue execution at an address without expecting to return to the monitor, use {\bf G}.

\end{description}
% TODO: screenshot  \includegraphics[width=\linewidth]{images/monitor-j}

% ****
% LOAD
% ****

\subsubsection{L : LOAD}
\index{LOAD}
\index{MONITOR Commands!LOAD}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf L "filename",unit [start]}
\item [Usage:] Loads data from a file into memory.

\item [Remarks:] The filename must be surrounded by double-quotes.

    The {\bf unit} number (such as 8 or 9) is required. {\bf Unit} is specified using the monitor's normal number system (defaulting to hex). See \hyperref[sec:numbers]{Numbers}.

    If the {\bf start} address is omitted, the starting address is taken from the first two bytes of the file. The file must be of type {\tt PRG}. If {\bf start} is provided, the two byte {\tt PRG} header is ignored.

\end{description}
% TODO: screenshot  \includegraphics[width=\linewidth]{images/monitor-l}

% ******
% MEMORY
% ******

\subsubsection{M : MEMORY}
\index{MEMORY}
\index{MONITOR Commands!MEMORY}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf M [from [,to]]}
\item [Usage:] Prints a memory dump for the given address range.
               The dump displays memory contents, organised in rows
               of 16 consecutive addresses starting with the
               address, given as 1st. argument. The dump continues
               until a row has been printed, containing the value
               of the address given as 2nd. argument.
               If no 2nd. argument is present, the dump displays
               a full page of 256 bytes in 16 rows.
               The contents are printed as 16 byte values in hex,
               followed by the character representation.

\item [Remarks:] The rows start with the character '>'.
                 This enables direct full screen editing of the dump.
                 Typing return in any row will write the changed
                 values of the cursor row back to memory, if writable RAM is there.
                 See monitor command {\bf >}.

\item [Example:] Using {\bf M}
\end{description}
\includegraphics[width=\linewidth]{images/monitor-m}

% *********
% REGISTERS
% *********

\subsubsection{R : REGISTERS}
\index{REGISTERS}
\index{MONITOR Commands!REGISTERS}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf R}
\item [Usage:] Displays the contents of the registers from just before the monitor was started.

\item [Remarks:] The output begins with a {\tt ;} character so that you can change the register values by moving the cursor up to the line, changing the values, then pressing \specialkey{RETURN}.

\end{description}
% TODO: screenshot  \includegraphics[width=\linewidth]{images/monitor-r}

% ****
% SAVE
% ****

\subsubsection{S : SAVE}
\index{SAVE}
\index{MONITOR Commands!SAVE}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf S "filename",unit start end}
\item [Usage:] Saves a region of memory to a file on disk, of type {\tt PRG}.

\item [Remarks:] The filename must be surrounded by double-quotes.

    The {\bf unit} number (such as 8 or 9) is required. {\bf Unit} is specified using the monitor's normal number system (defaulting to hex). See \hyperref[sec:numbers]{Numbers}.

    The end address is one beyond the last address to save.

    To overwrite an existing file, put {\tt 0:} before the filename, such as: {\tt "0:MYFILE"}

\end{description}
% TODO: screenshot  \includegraphics[width=\linewidth]{images/monitor-s}

% ********
% TRANSFER
% ********

\subsubsection{T : TRANSFER}
\index{TRANSFER}
\index{MONITOR Commands!TRANSFER}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf T start end destination-start}
\item [Usage:] Transfers (copies) a region of memory to another region.

\item [Remarks:] The end address is one beyond the last address to copy.

    The destination region is assumed to be the same length as the source region. All bytes are copied.

\end{description}
% TODO: screenshot  \includegraphics[width=\linewidth]{images/monitor-t}

% ******
% VERIFY
% ******

\subsubsection{V : VERIFY}
\index{VERIFY}
\index{MONITOR Commands!VERIFY}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf V "filename",unit start}
\item [Usage:] Verifies that a region of memory matches a file on disk.

\item [Remarks:] The filename must be surrounded by double-quotes.

    The {\bf unit} number (such as 8 or 9) is required. {\bf Unit} is specified using the monitor's normal number system (defaulting to hex). See \hyperref[sec:numbers]{Numbers}.

    The length of the data to verify is assumed to be the length of the file.

    If the data in memory does not match, an error will be shown.  Otherwise, nothing more is shown, and success should be assumed.

\end{description}
% TODO: screenshot  \includegraphics[width=\linewidth]{images/monitor-v}

% ****
% EXIT
% ****

\subsubsection{X : EXIT}
\index{EXIT}
\index{MONITOR Commands!EXIT}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf X}
\item [Usage:] Exits the monitor to BASIC.

\item [Remarks:] If the monitor was started by a {\bf BRK} instruction in a program, exiting the monitor effectively aborts the program. To continue a paused program, use {\bf G} instead.

\end{description}

% ************
% . (ASSEMBLE)
% ************

\subsubsection{. : ASSEMBLE}
\index{MONITOR Commands!.}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf . address opcode operand}
\item [Usage:] An alias for {\bf A}.

\item [Remarks:] The output of the disassembler starts each line with a {\tt .} character. You can edit the assembly instructions printed by the disassembler by moving the cursor up to a line, editing it, and pressing \specialkey{RETURN}. This changes the {\tt .} to a {\tt A} so you can see which lines have been reassembled.

\end{description}
% TODO: screenshot  \includegraphics[width=\linewidth]{images/monitor-dot}

% *****************
% > (MODIFY MEMORY)
% *****************

\subsubsection{> : MODIFY MEMORY}
\index{MONITOR Commands!>}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf > addr byte [byte...]}
\item [Usage:] Modifies one or more bytes starting at an address.

\item [Remarks:] The output of the {\bf M} command starts each line with a {\tt >} character. You can edit the memory values printed by the {\bf M} command by moving the cursor up to a line, editing it, and pressing \specialkey{RETURN}.

\end{description}
% TODO: screenshot  \includegraphics[width=\linewidth]{images/monitor-gt}

% ********************
% ; (MODIFY REGISTERS)
% ********************

\subsubsection{; : MODIFY REGISTERS}
\index{MONITOR Commands!.}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf ; pc sr ac xr yr zr bp sp nvebdizc}
\item [Usage:] Modifies the CPU registers. Arguments are in the format output by the {\bf R} command.

\item [Remarks:] The output of the {\bf R} command starts the line with a {\tt ;} character. You can edit the memory values printed by the {\bf R} command by moving the cursor up to the line, editing it, and pressing \specialkey{RETURN}.

\end{description}
% TODO: screenshot  \includegraphics[width=\linewidth]{images/monitor-semi}

% ****************
% @ (DISK COMMAND)
% ****************

\subsubsection{@ : DISK COMMAND}
\index{MONITOR Commands!@}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf @ [unit] [,command]}
\item [Usage:] Perform a disk command.

\item [Remarks:] Without a {\bf command}, this displays the drive status.

    The default {\bf unit} is 8. {\bf Unit} is specified using the monitor's normal number system (defaulting to hex). See \hyperref[sec:numbers]{Numbers}.

    A {\bf command} of {\bf \$[pattern]} will request a directory listing from the specified {\bf unit} and display it.  An optional {\bf pattern} may be given to limit the files listed. The wildcard characters {\bf *} and {\bf ?} may be used

    The {\bf command} can be any Commodore DOS command. For example, to rename a file: {\tt @R0:NEWNAME=OLDNAME}

    The {\bf command} can be {\tt U1} to load raw disk sectors to memory, or {\tt U2} to save memory to raw disk sectors. These {\bf command}s take this form:

    {\bf @8,U1 mem-start track sector [sector-count]}

    Tracks are numbered 1-80, and sectors are numbered 0-39. If {\bf sector-count} is omitted, only one sector is read from or written to.

\end{description}
% TODO: screenshot  \includegraphics[width=\linewidth]{images/monitor-at}



\section{The Matrix Mode/Serial Monitor}
\label{sec:matrix-mode}
\index{MONITOR!Matrix Mode/Serial Monitor}

The Matrix Mode monitor can do something that the MEGA65 monitor cannot: instead of pausing a program to run the monitor, the Matrix Mode monitor runs concurrently with the active program. That is, you can view and modify the memory the MEGA65, {\em while a program is running}.

This works using dedicated hardware in the MEGA65 design that implements a little
helper processor that runs this monitor interface. This hardware has a special access mechanism
to the memory and CPU of the MEGA65.

In comparison with the ROM-based monitors that execute on the MEGA65's primary processor,
the Matrix Mode monitor has several advantages and disadvantages:
\begin{itemize}
\item It can be used while a program is running.
\item It can be used, even if the ROM area is being used for program code or data,
  instead of containing a standard C65 or MEGA65 ROM.
\item It can be accessed via the serial debug interface, via the JB1 connector.
\item It can be instructed to stop the processor as soon as the program counter (PC)
  register of the main processor reaches a user specified address. That is, it supports
  a (single) hardware breakpoint.
\item It can be instructed to stop the processor whenever a specified memory address
  is written to. That is, it supports a ``write watch'' on a single memory address.
  The memory address is specified as a full 28-bit address, allowing it to detect memory
  writes via any means. Note that DMA operations will complete, before the watch point
  takes effect.
\item It can be instructed to stop the processor whenever specific CPU flags are set
  or cleared, which can also be used to support debugging of programs.
\item On some models of the MEGA65, the integrated ROM of the monitor processor is
  very small, which means that functionality may be limited. This is why, for example,
  there is no ``assemble'' command for this monitor.  This may be corrected in future
  core updates for MEGA65 models that have capacity for a larger monitor processor ROM.
\end{itemize}

\subsection{Table of Matrix Mode Monitor Commands}

{
\ttfamily
\setlength{\tabcolsep}{1mm}
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
C & mnemonic & description \\
\hline
<Enter> & STEP & Step into next instruction \\
\# & HYPERTRAP & Enable/disable CPU hypervisor traps \\
+ & UARTDIVISOR & Set UART bitrate divisor \\
? & HELP & help \\
@ & CPUMEM & (show memory from CPU context) \\
\hline
B & BREAKPOINT & Set/clear CPU execution break point \\
D & DISASSEMBLE & Disassemble memory \\
E & FLAGWATCH & Set/clear CPU flags watch point \\
F & FILL & Fill memory with a value \\
G & SETPC & Set CPU program counter \\
H & HELP & help \\
I & INTERRUPTS & Enable/disable CPU IRQs (clear/set CPU I flag) \\
J & DEBUGMON & Various debug functions for the monitor itself \\
L & LOADMEMORY & Load data into memory \\
M & MEMORY & Show memory contents \\
R & REGISTERS & show registers \\
S & SETMEMORY & Set memory contents \\
T & TRACE & set CPU trace/run mode \\
W & MEMORYWATCH & Set/clear memory write watch point \\
Z & CPUHISTORY & CPU history \\
\hline
\end{tabular}
\end{center}
}

\subsection {Calling the Monitor}

To enter or exit the monitor hold down \megasymbolkey and press \specialkey{TAB}.
You will see an animation of green characters raining down from the top of the screen, and
then be presented with a simple text terminal interface which is transparent, so that you can
see the screen output of your running program at the same time.

\subsubsection{<Enter> : Single-step}

\index{STEP}
\index{MONITOR Commands!STEP}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf <Enter Key> Step into next instruction}
\item [Usage:] <Enter Key>
\item [Remarks:] When the CPU is in trace mode {\bf t1}, pressing the Enter (or Return) key at the prompt without a command executes the next CPU instruction and advances the program counter. See ``Trace,'' below.
\end{description}


\subsubsection{\# : Hypervisor trap enable/disable}

\index{HYPERTRAP}
\index{MONITOR Commands!HYPERTRAP}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf \# Enable or disable Hypervisor Traps}
\item [Usage:] \#[0|1]

\item [Remarks:] If the argument is 1, then Hypervisor traps are enabled,
  otherwise they are disabled.

  {\em It is not confirmed if this command is currently functional.}
\end{description}


\subsubsection{+ : Set Serial Interface UART Divisor}

\index{UARTDIVISOR}
\index{MONITOR Commands!UARTDIVISOR}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf + Set Serial Interface UART Divisor}
\item [Usage:] + divisor

\item [Remarks:] Sets the divisor for the serial monitor interface.
  This allows changing the baud rate of the serial monitor interface
  from the default 2,000,000 bits per second.  The baud rate will be
  equal to $40,500,000 \div (divisor-1)$. This affects only the
  serial UART interface, and does not affect accessing this monitor
  via the Matrix Mode composited display.

  For example, to slow the
  serial monitor interface down to 19,200 bits per second, the divisor
  would need to be $40,500,000 \div (19,200 - 1) = 2108$.
  The + command then requires that you convert this value to hexadecimal,
  thus the command would be {\tt +83c}.

  Note that this command does {\em no} sanity checking of the provided value.
  If you accidentally provide an incorrect value for your needs, you can
  recover from this situation by activating the Matrix Mode interface by holding
  down \megasymbolkey and tapping \specialkey{TAB}, and entering
  the appropriate command to correct the divisor, e.g., {\tt +14} to return
  to the default of 2,000,000 bits per second.

  You must then exit the Matrix
  Mode again by repeating the \megasymbolkey + \specialkey{TAB} key combination,
  before the serial UART interface will become active again. This is because
  the Matrix Mode disables the serial UART interface when active.
\end{description}

\subsubsection{@ : CPUMEMORY}
\index{CPUMEMORY}
\index{MONITOR Commands!CPUMEMORY}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf @ [address]}
\item [Usage:] Prints a memory dump for the given 16-bit address,
  {\em as interpreted by the current CPU memory mapping}.
  If you wish to inspect the contents of memory anywhere in the 28-bit
  address space, use the M command instead.

  The dump displays memory contents, organised in rows
  of 16 consecutive addresses starting with the
  address. The dump displays
  a full page of 256 bytes in 16 rows.
  The contents are printed as 16 byte values in hex,
  followed by the character representation.

\item [Remarks:] If no address is provided, it will show the next 256 bytes.

\end{description}

\subsubsection{? or H : HELP}
\index{HELP}
\index{MONITOR Commands!HELP}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf ?} {\em or} {\bf h}
\item [Usage:] Displays a (very) brief message identifying the monitor.
  On some models of the MEGA65 that have more memory available to the
  monitor processor, this command may display information about each
  of the available commands.

\end{description}


\subsubsection{B : BREAKPOINT}
\index{BREAKPOINT}
\index{MONITOR Commands!BREAKPOINT}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf b [address]}
\item [Usage:] Sets or clears the hardware breakpoint. If no address is provided,
  then the breakpoint will be disabled. Otherwise the breakpoint is set to the
  provided 16-bit address.

  Whenever the program counter (PC) register of the MEGA65's processor equals the value
  provided to this command, the processor will halt, and the Matrix Mode monitor interface
  will display the last instruction executed and current register values to alert the user
  to this event. It does not activate the Matrix Mode display when this occurs. It is
  normally expected that Matrix Mode will either already be active, or that the user is
  interacting via the serial interface.

\end{description}


\subsubsection{D : DISASSEMBLE}
\index{DISASSEMBLE}
\index{MONITOR Commands!DISASSEMBLE}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf <d|D> [address]}
\item [Usage:] Disassembles and displays the instruction stored at the
  indicated 28-bit address.

  To disassemble instructions from the CPU's
  current memory context, taking into account current memory banking,
  prefix the address with 777, e.g., {\tt d777080D} would disassemble
  the instruction at \$080D, as currently visible to the MEGA65's
  processor.

  Use {\tt D} instead of {\tt d} to disassemble 16 instructions at a time, instead of just one.

\end{description}

\subsubsection{E : FLAGWATCH}
\index{FLAGWATCH}
\index{MONITOR Commands!FLAGWATCH}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf e [value]}
\item [Usage:]
  Sets or clears the CPU flag watch point: If no argument is provided, the
  flag watch point is disabled. If a value is provided, it is assumed to be
  a 16-bit value, where the first two hexadecimal digits indicate the processor
  flags that will trigger the watch point if they are set. The second two
  hexadecimal digits indicate which processor flags will trigger the watch point
  if they are clear.  In this way any combination of processor flag values can
  be monitored.

  {\em This command does not function correctly at the time of writing.}

\item [Example:]

  To cause the watch point to trigger when the Negative Flag is asserted, the
  command {\tt e8000} would be used.

\end{description}

\subsubsection{F : FILL}
\index{FILL}
\index{MONITOR Commands!FILL}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf f [start] [end+1] [value] }
\item [Usage:] Fills the indicated 28-bit address range with
  the indicated value.
\item [Remarks:]
  The end address should be one more than the last address
  that is desired to be filled.

\end{description}

\subsubsection{G : SETPC}
\index{SETPC}
\index{MONITOR Commands!SETPC}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf g address}
\item [Usage:] Sets the Program Counter (PC) register of the MEGA65's processor
  to the supplied 16-bit address.  If the processor is running at the time, execution
  will immediately proceed from that address. If the processor is halted at the time,
  e.g., due to the use of the {\tt t1} command, the processor remains halted, but with
  the Program Counter set to the indicated address, ready for when the processor is
  again allowed to run.

\end{description}


\subsubsection{I : INTERRUPTS}
\index{INTERRUPTS}
\index{MONITOR Commands!INTERRUPTS}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf i[0|1]}
\item [Usage:] Enables or disables Interrupt Requests (IRQs) on the MEGA65's
  processor. Disabling IRQs can be helpful when single-stepping
  through a program, as otherwise you will tend to end up only
  stepping through the interrupt handler code, because the interrupts
  will happen more frequently than the steps through the code.

  {\bf i1} sets the CPU ``IRQs disabled'' (I) flag. This causes the CPU to not respond to causes of IRQs, such as CIA timers or VIC raster beam watches. This does not disable Non-Maskable Interrupts (NMIs). There is no way to disable NMIs from the serial debugger (or from a program).

  {\bf i0} clears the CPU I flag. This re-enables IRQs.

\item [Remarks:] If the CPU is paused by {\bf t1}, the change to the I flag will not be reflected by the register display ({\bf r}) until after the next instruction is executed.

\end{description}

\subsubsection{J : DEBUGMON}
\index{DEBUGMON}
\index{MONITOR Commands!DEBUGMON}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf j [value]}
\item [Usage:] Display, and optionally set, internal signals of the matrix
  mode monitor interface.

\end{description}


\subsubsection{L : LOADMEMORY}
\index{LOADMEMORY}
\index{MONITOR Commands!LOADMEMORY}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf l <start addr> <end addr + 1>}
\item [Usage:] Fast-load a block of memory via the serial monitor
  interface.  Immediately after sending this command, the bytes of
  memory to be loaded should be sent to the serial monitor interface.
  The bytes are read as-is, and thus should be provided as natural
  bytes, not encoded in hexadecimal.  This allows loading data at
  approximately 200KB per second at the default serial baud rate
  of 2,000,000 bits per second.

\end{description}

\subsubsection{M : MEMORY}
\index{MEMORY}
\index{MONITOR Commands!MEMORY}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf <m|M> [address]}
\item [Usage:] Prints a memory dump for the given 28-bit address.
  If you wish to inspect the contents of memory as currently seen
  by the processor's current banking configuration, use the {\bf @}
  command instead.

  The dump displays memory contents, organised in rows
  of 16 consecutive addresses starting with the
  address. The dump displays
  a full page of 256 bytes in 16 rows.
  The contents are printed as 16 byte values in hex,
  followed by the character representation.

  To view memory from the CPU's current memory context, taking into account
  current memory banking, prefix the address with 777, e.g., {\tt m777080D}
  would view memory at \$080D, as currently visible to the MEGA65's processor.


\item [Remarks:] If not address is provided, it will show the next 256 bytes.

\end{description}

\subsubsection{R : REGISTERS}
\index{REGISTERS}
\index{MONITOR Commands!REGISTERS}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf r}
\item [Usage:] Displays the current value of various processor registers
  and flags, as well as a disassembly of the most recently executed
  instruction.

\end{description}

\subsubsection{S : SETMEMORY}
\index{SETMEMORY}
\index{MONITOR Commands!SETMEMORY}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf s addr <value ...>}
\item [Usage:] Sets the contents of the indicated memory location to the supplied value.
  If more than one space-separated value is provided, then multiple consecutive memory
  locations will be set.

  This command uses 28-bit addresses, and therefore ignores the current selected memory banking
  configuration.

\end{description}


\subsubsection{T : TRACE}
\index{TRACE}
\index{MONITOR Commands!TRACE}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf t<0|1|c>}
\item [Usage:] Selects the trace or run mode of the processor: {\tt t0} means that the
  processor runs freely, {\tt t1} halts the processor, and {\tt tc} runs the processor
  in continuous-trace mode, where it displays each instruction and the register values
  immediately following its execution, as though {\tt t1} had been selected, and the user
  were to then immediately press return or enter to request the next instruction to be
  executed.

  If {\tt t1} is selected, pressing Enter or Return in the Matrix Mode monitor will cause
  the next instruction to be executed.

  The {\tt t0} command is also used following the triggering of a break-point or watch-point,
  to allow the processor to resume.

\end{description}

\subsubsection{W : WATCHPOINT}
\index{WATCHPOINT}
\index{MONITOR Commands!WATCHPOINT}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf w [address]}
\item [Usage:] Sets or clears the hardware watch-point. If no address is provided,
  then the watch-point will be disabled. Otherwise the watch-point is set to the
  provided 28-bit address.

  Whenever the MEGA65's processor writes to the address
  provided to this command, the processor will halt, and the Matrix Mode monitor interface
  will display the last instruction executed and current register values to alert the user
  to this event.  It does not activate the Matrix Mode display when this occurs.
  It is
  normally expected that Matrix Mode will either already be active, or that the user is
  interacting via the serial interface.

\end{description}

\subsubsection{Z : CPUHISTORY}
\index{CPUHISTORY}
\index{MONITOR Commands!CPUHISTORY}
\begin{description}[leftmargin=2cm,style=nextline]
\item [Format:] {\bf z [address]}
\item [Usage:] Displays information about the instructions recently executed by
  the MEGA65's processor.

\item [Remarks:] {\em This command is suspected to not be correctly operational at
  the time of writing.}

\end{description}