The Virtu Debugger: Mr Nosey
============================
--------------------------------------------------------------------------------
1 Overview
==========

    One great thing about an emulated computer is that you can easily extend
the machine in ways that would have been expensive and difficult with the real
thing. Mr Nosey is such an extension to Virtu. It adds basic but invaluable
snooping capabilities normally found only in 'hardware' debugging aids like
snap-shot cards, trace boards and emulators.

    At any time during (full-speed) emulation, pressing <F1> invokes Mr Nosey.
From there you can: view and edit the status of the CPU; view, edit and search
a hex/ASCII dump of memory; view and edit a disassembled listing of memory; set
break/watch-points; save screendumps; drop to the monitor; exit Virtu; step and
trace emulation, or resume full-speed execution. The rest of this document
details these features.

General Notes
~~~~~~~~~~~~~
- all numeric values are in hex
- editing at an address writes only to whichever bank is switched in
  ie. main, aux, language card, ROM; edits to ROM _are_ allowed
- when editing values, use <Left> and <Right> to move <Return> to accept
  value, <Esc> to cancel edit

--------------------------------------------------------------------------------
2 CPU Status Screen
===================

2.0 Invoking
------------
    Virtu periodically checks to see if <F1> is being pressed. If so, (and when
it is released) Mr Nosey is invoked showing the CPU status screen. If Mr Nosey
was in trace mode (see 2.2 <F2>) when last exited, trace mode will still be
enacted. Because <F1> is also the key to exit Mr Nosey, this is a handy way to
briefly pause execution.

2.1 Screen Layout
-----------------
    This screen shows the status of the CPU and, for convenience, the current
display mode and page. The lower case letters in the layout below refer to the
list of symbols that follows.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
SP s/01FE- s1 NVRBDIZC P  A  X  Y  Vid #
sp s/01FF- s2 nv1bdizc pp aa xx yy vvv p

   k/ pc1+ i1                        ;c1
PC j/ pc0- i0                        ;c0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

sp  += stack pointer
s    = stack pointer bank (0=main or 1=aux)
s1  += first (top) value on the stack (at s/0100 + sp + 1)
s2  += second value on the stack (at s/0100 + sp + 2)
n   += negative flag (1=negative)
v   += overflow flag (1=signed overflow)
b   += break flag (1=break occurred)
d   += decimal flag (1=decimal arithmetic mode)
i   += interrupt flag (1=IRQ disabled)
z   += zero flag (1=zero arithmetic result)
c   += carry flag (1=arithmetic carry set)
pp  += processor status (nv1bdizc)
aa  += accumulator
xx  += x index register
yy  += y index register
vvv  = video mode (see notes)
p    = video page (1 or 2)
j    = bank of program counter (0=main or 1=aux)
k    = bank of previous program counter (0=main or 1=aux, if available)
pc0 += program counter (address of next instruction)
       followed by '+' if a breakpoint or '-' if not
pc1  = previous program counter (address of previous instruction, if available)
       followed by '+' if a breakpoint or '-' if not
i0   = disassembly of next instruction
i1   = disassembly of previous instruction (if available)
c0   = comment for effective address of next instruction (if available)
c1   = comment for effective address of previous instruction (if available)

Notes
~~~~~
- in the list above "+=" denotes the value can be modified
- the R (reserved) flag is always asserted by the hardware to 1
- k, pc1, i1 and c1 are available only if the last instruction was
  executed in step, trace or run modes (not full-speed execution)
- c0 and c1 will reflect any registers or indirection involved in i0 and i1
  eg. i0="LDA $40C0,Y" results in c0=";=$416C" when yy=AC
  see disassembly (3.1) for more information on instruction disassembly
- values for vvv (video mode) are:

  LOR = Lores
  TX4 = Text 40
  TX8 = Text 80
  LR4 = Lores & Text 40
  LR8 = Lores & Text 80
  HIR = Hires
  HR4 = Hires & Text 40
  HR8 = Hires & Text 80
  XLR = 7M Lores
  DLR = Double Lores
  XL4 = 7M Lores & Text 40
  DL8 = Double Lores & Text 80
  XHR = ND Hires
  DHR = Double Hires
  XH4 = ND Hires & Text 40
  DH8 = Double Hires & Text 80

2.2 Keys
--------

Execution
~~~~~~~~~
<F1>        = resume full-speed execution (exit Mr Nosey)
              re-enter on <F1>
<Ctrl-F1>   = start run mode (CPU status screen not displayed)
              re-enter on <F1> or break/watchpoint
<F2>        = toggle trace mode (CPU status screen displayed and updated)
              display trace until <F1>, <Ctrl-F1>, <F2>, <F12>, <Ctrl-F12>
              or break/watchpoint
<F3>        = run until instruction after next or break/watchpoint (step over)
              eg. run until branch fails, or JSR returns (or break/watchpoint)
<F4>        = step one instruction (step into)
<Ctrl-F12>  = absolute reset: PC = $FF59 (OldRst), SP = #$FF, resume
              full-speed execution

Mode
~~~~
<F5>        = enter disassembler
<F6>        = enter hex/ASCII dump
<F8>        = enter breakpoint editor
<l> or <L>  = list at pc0 (enter disassembler)
<d> or <D>  = dump at effective address if applicable else at pc0
              (enter dumper)

Editing
~~~~~~~
<Ins>       = toggle breakpoint at pc0: toggles existing breakpoint value
              if listed else uses first disabled breakpoint with value 0
<Left>      = move cursor left
<Right>     = move cursor right
<Up>        = move cursor up
<Down>      = move cursor down
<Return>    = edit cursor selection value

Miscellaneous
~~~~~~~~~~~~~
<F9>        = save a screendump
<F12>       = exit Virtu

--------------------------------------------------------------------------------
3 Disassembly Screen
====================

3.0 Invoking
------------
    From any debugger screen press <F5> to enter the disassembler. The display
defaults to the previous address viewed. Pressing <Esc> returns to the CPU
status screen.

3.1 Screen Layout
-----------------
    A sequential disassembly of five instructions is displayed; the top line is
editable. The lower case letters in the layout below refer to the list of
symbols that follows.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   b/aaaa- i...                    ;c...
   */2000- STZ $0201            ;In+0001
   */2003- STA $20,X                   ;
   */2005- ??? E2                      ;
PC */2007- NOP 5C 5C                   ;
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

b    = bank of instruction address (not displayed: currently '*')
aaaa = address of disassembled instruction
       followed by '+' if a breakpoint or '-' if not
i... = disassembled instruction
c... = comment for instruction (if available)

Notes
~~~~~
- although b is not displayed, its value is whatever is appropriate for
  that address given the current memory map state
- instruction disassembly reflects the state of the 65C02 option: 65C02
  specific opcodes are displayed only if 65C02 is selected (see 2000, above)
- illegal 6502 opcodes are displayed as "???" followed by 0, 1 or 2 bytes
  depending on whether the illegal opcode takes an operand (see 2005, above)
- illegal 65C02 opcodes are displayed as "NOP" followed by 0, 1 or 2 bytes
  depending on whether the illegal opcode takes an operand (see 2007, above)
- when editing instructions, any instruction can be entered that is legal
  according to usual conventions and the state of the 65C02 option; the
  one exception to this is that a 'HEX' opcode may be followed by space
  seperated hex data eg 'HEX 01 02 03'
- comments for effective addresses will not be displayed when instructions
  use X, Y or indirection since these are context sensitive (see 2003, above)
- comment labels are displayed for well-known zero-page, I/O and ROM
  addresses, or nearby offsets when relevant (see 2000, above)
- some addresses display different comment labels depending on whether an
  instruction reads or writes to that location, eg. I/O locations $C000-$C01F
- if the instruction at pc0 is displayed, 'PC' appears (as in 2007, above)

3.2 Keys
--------

Mode
~~~~
<Esc>       = enter CPU status
<F6>        = enter hex/ASCII dump
<F8>        = enter breakpoint editor
<l> or <L>  = list at the effective address of the current instruction
              (if available)
<d> or <D>  = dump at effective address if applicable else at aaaa
              (enter dumper)

Editing
~~~~~~~
<Left>      = list at aaaa - 1
<Right>     = list at aaaa + 1
<Up>        = list at first instruction before aaaa
<Down>      = list at first instruction after aaaa
<Page Up>   = list at five instructions before aaaa
<Page Down> = list at five instructions after aaaa
<Home>      = list at pc0
<Copy>      = list at affective address of i0 (if available)
<Ins>       = toggle breakpoint at aaaa: toggles existing breakpoint value
              if listed else uses first disabled breakpoint with value 0
<Return>    = edit selected instruction: assemble the edited line up to the
              cursor when <Return> is pressed; if the instruction assembles
              successfully, editing continues at the address following
              the instruction entered; if not, edit mode is cancelled
<Tab>       = list at new address (edit current address)
<Backspace> = list at previous address (before last <Tab> etc)

--------------------------------------------------------------------------------
4 Hex/ASCII Dump Screen
=======================

4.0 Invoking
------------
    From any debugger screen press <F6> to enter the dumper. The display
defaults to the previous address viewed. Pressing <Esc> returns to the CPU
status screen.

4.1 Screen Layout
-----------------
    A hex and ASCII dump of 40 bytes is displayed; . The lower case letters in
the layout below refer to the list of symbols that follows.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
b/aaaa- C1 C2 C3 C0 C0 C0 C0 C0 ABC@@@@@
*/2000- C0 C0 C0 C0 C0 C0 C0 C0 @@@@@@@@
*/2008- C0 C0 C0 C0 C0 C0 C0 C0 @@@@@@@@
*/2010- C0 C0 C0 C0 C0 C0 C0 C0 @@@@@@@@
*/2018- C0 C0 C0 C0 C0 C0 C0 C0 @@@@@@@@
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

b    = bank of dump line address (not displayed: currently '*')
aaaa = dump line address

Notes
~~~~~
- although b is not displayed, its value is whatever is appropriate for
  that address given the current memory map state

4.2 Keys
--------

Mode
~~~~
<Esc>       = enter CPU status
<F5>        = enter disassembler
<F8>        = enter breakpoint editor
<l> or <L>  = list at the current address

Editing
~~~~~~~
<Left>      = move cursor to current address - 1
<Right>     = move cursor to current address + 1
<Up>        = move cursor to current address - 8
<Down>      = move cursor to current address + 8
<Page Up>   = dump the previous 40 bytes
<Page Down> = dump the next 40 bytes
<Home>      = dump at pc0
<Copy>      = dump at affective address of i0 (if available)
<Return>    = hex edit: enter hex data, use arrows to move, <Esc> to end
<'>         = ASCII edit: enter ASCII data, use arrows to move, <Alt>
              toggles hight/low ASCII, <Esc> to end
<Tab>       = dump at new address (edit current address)
<Backspace> = dump at previous address (before last <Tab> etc)

Searching
~~~~~~~~~
<p> or <P>  = edit search pattern: edit hex/ASCII using same keys as
              dump screen; leave cursor on last byte of pattern,
              <Esc> to end
<s> or <S>  = search forward for pattern (set by <p>): the cursor disappears
              while searching, then is placed at the first byte matched; the
              search wraps ($FFFF + 1) to $0000

--------------------------------------------------------------------------------
5 Breakpoint Edit Screen
========================

5.0 Invoking
------------
    From any debugger screen press <F8> to enter the breakpoint editor.
Pressing <Esc> returns to the CPU status screen.

5.1 Screen Layout
-----------------
    Ten breakpoint entries, and ten watchpoint entries are displayed. The lower
case letters in the layout below refer to the list of symbols that follows.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
B0-*/bbbb B5-*/0000  W0-*/wwww W5-*/0000
B1-*/0000 B6-*/0000  W1-*/0000 W6-*/0000
B2-*/0000 B7-*/0000  W2-*/0000 W7-*/0000
B3-*/0000 B8-*/0000  W3-*/0000 W8-*/0000
B4-*/0000 B9-*/0000  W4-*/0000 W9-*/0000
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

bbbb = breakpoint address
wwww = watchpoint address

Notes
~~~~~
- a point cannot be set for only one bank, but matches the address in any
  bank (main, aux, language card, ROM)

5.2 Keys
--------

Mode
~~~~
<Esc>       = enter CPU status
<F5>        = enter disassembler
<F6>        = enter hex/ASCII dump

Editing
~~~~~~~
<Left>      = move cursor left
<Right>     = move cursor right
<Up>        = move cursor up
<Down>      = move cursor down
<Ins>       = toggle selected point enabled/disabled
<Home>      = set all non-0 points to enabled/disabled state
              of currently selected point
<Del>       = disable point and set to 0
<Return>    = edit point: enter address, use arrows to move, <Esc> to end

--------------------------------------------------------------------------------
