Diagnostics

In addition to the command line arguments shown on the Usage page, MEMU has arguments which are of interest when debugging Z80 programs and when debugging MEMU itself :-

Option Description
-diag-console Log diagnostic information to the console. Cannot be used with -mon-th as this would cause the diagnostic information to interfere with the text mode screen output.
-diag-file Append diagnostic information to a file called memu.log.
-diag-file=filename As above, but to file of your choice.
-diag-ring Log diagnostic information to a ring buffer in memory. When MEMU terminates, dump this to memu.ring. A great way to avoid filling the disk with memu.log when all you care about is recent activity prior to failure.
-diag-ring=filename As above, but to file of your choice.
-diag-win-unknown-key Displays host operating system specific keycodes typed in the windows which are not recognised by MEMUs window handling code. These will be XWindows KeySym values or Windows virtual keycodes. Recognised values are passed on to the emulation of the MTX keyboard.
-diag-win Turn on all diagnostic options with names starting with -diag-win
-diag-mem-iobyte Show when the IOBYTE is written to.
-diag-mem-subpage Show when the ROM subpage register is written to.
-diag-mem-dump When the program terminates, write the Z80 address space to a file called memu.mem.
-diag-mem Turn on all diagnostic options with names starting with -diag-mem.
-diag-vid-status Show when the VDP status register is read.
-diag-vid-registers Show when VDP registers are written to.
-diag-vid-address Show when the VDP address register is set, and whether for read or write.
-diag-vid-data Show all data transferred to/from the VDP memory. Tries to log the data in formats allowing you to recognise which graphics data is being uploaded. Will cause a lot of logging.
-diag-vid-refresh Show when the VDP screen is repainted to the Window on the host screen. This is the point at which the VDP interrupt bit becomes set.
-diag-vid-markers Show additional markers on the Window. One is a line which moves down the screen, one pixel per frame, which can be observed to see if time is progressing smoothly in the emulation. Another shows on which scan lines there are >=5 sprites.
-diag-vid-time-check Perform VDP timing sanity checks. Information about the timing parameters is given below.
-diag-vid-time-check-abort Terminate if timing check fails.
-diag-vid-time-check-drop Fail to store the data in VRAM, or return 0xff, if timing check fails.
-diag-vid Turn on all diagnostic options with names starting with -diag-vid.
-diag-kbd-win-key Show recognised key presses and releases in the VDP window which are not understood.
-diag-kbd-drive Show keyboard drive values returned.
-diag-kbd-sense Show keyboard drive and sense values returned.
-diag-kbd-auto-type Show the workings of the auto-type mechanism.
-diag-kbd-remap Show diagnostics relating to the keyboard remapping feature.
-diag-kbd Turn on all diagnostic options with names starting with -diag-kbd.
-diag-joy-init Show joystick initialisation messages.
-diag-joy-usage Show joystick messages generated as joystick data is read.
-diag-joy Turn on all diagnostics options with names starting with -diag-joy.
-diag-dart-ports Show accesses to DART ports.
-diag-dart-config Show DART configuration.
-diag-dart-data Show DART data transfer.
-diag-dart Turn on all diagnostics options with names starting with -diag-dart.
-diag-snd-registers Show accesses to the sound chip registers.
-diag-snd-latency Show information relating to the latency parameters passed to PortAudio.
-diag-snd-init Don't suppress stderr during Pa_Initialize() call.
-diag-snd Turn on all diagnostic options with names starting with -diag-snd.
-diag-ctc-registers Show when CTC registers are written to.
-diag-ctc-pending Show when an interrupt becomes pending on a channel.
-diag-ctc-interrupt Show when the fact the interrupt is pending is communicated to the Z80 chip (usually within 1000 clks).
-diag-ctc Turn on all diagnostic options with names starting with -diag-ctc.
-diag-mon-hw Show diagnostics relating to the hardware level emulation of the 6845 CRTC card and underlying memory.
-diag-mon-kbd-win-key Show recognised key presses and releases sent to 80-column window. Only applies if -mon-win is being used.
-diag-mon-kbd-map-th Show keycodes read from TH. Only applies if -mon-th is being used.
-diag-mon Turn on all diagnostic options with names starting with -diag-mon.
-diag-sdxfdc-port Turn on all diagnostic relating to SDX FDC port access.
-diag-sdxfdc-hw Turn on all diagnostic relating to SDX FDC hardware.
-diag-sdxfdc-data Turn on all diagnostic relating to SDX FDC data.
-diag-sdxfdc-status Turn on all diagnostic relating to SDX FDC status.
-diag-sdxfdc Turn on all diagnostic options with names starting with -diag-sdxfdc.
-diag-sidisc-file Turn on all diagnostic relating to Silicon Disc file reading and writing.
-diag-sidisc-address Turn on all diagnostic relating to Silicon Disc sector address control.
-diag-sidisc-data Turn on all diagnostic relating to Silicon Disc data transfer.
-diag-sidisc Turn on all diagnostic options with names starting with -diag-sidisc.
-diag-print Show characters that are printed.
-diag-spec-ports Log accesses to Speculator ports.
-diag-spec-interrupts Log things relating to Speculator interrupts.
-diag-spec Turn on all diagnostic options with names starting with -diag-spec.
-diag-cpm-driver Log all calls to driver code in high memory.
-diag-cpm-cbios Log all calls to CBIOS routines.
-diag-cpm-bdos-file Log all calls to CP/M BDOS relating to file access.
-diag-cpm-bdos-other Log other calls to CP/M BDOS.
-diag-cpm-bdos Turn on all diagnostic options with names starting with -diag-cpm-bdos.
-diag-cpm Turn on all diagnostic options with names starting with -diag-cpm.
-diag-z80-instructions Log CPU registers and disassemble instruction prior to executing each instruction. Will cause a lot of logging.
-diag-z80-instructions-exclude from-to Turn off logging CPU registers and disassemble instructions for instructions at addresses between from and to (eg: 0x0000-0x3fff).
-diag-z80-instructions-include from-to Turn on logging CPU registers and disassemble instructions for instructions at addresses between from and to.
-diag-z80-interrupts Log when the Z80 takes an interrupt, and show the peripheral supplied low byte of the vector table address.
-diag-z80-time Include timing information in the Z80 instructions logged.
-diag-z80 Turn on all diagnostic options with names starting with -diag-z80 (except -diag-z80-instructions-exclude).
-diag-bad-port-display Display when unemulated ports are accessed.
-diag-bad-port-ignore Do not halt MEMU when certain unemulated ports are accessed. By default, termination happens for ports which are known to be used by particular hardware.
-diag-bad-port Turn on all diagnostic options with names starting with -diag-bad-port.
-diag-panel-hack Diagnostics relating to the hack which allows PANEL and VDEB.COM single-stepping to work.
-diag-tape Diagnostics relating to the MTX BASIC LOAD/SAVE/VERIFY commands. It also shows diagnostics relating to the Z ZX Spectrum LOAD/SAVE/VERIFY commands.
-diag-speed Every second, output an estimate of the emulated chip speed. If running with -fast this could be much higher than 4MHz. If running with -mon-console and the program waits for keyboard input, because the simulation is suspended this could to drop to near zero.
-diag-exit Display the reason for the termination of MEMU.
-diag-all Turn on all of the above (except -diag-console and -diag-file).

Option	Description
`-diag-console`	Log diagnostic information to the console. Cannot be used with `-mon-th` as this would cause the diagnostic information to interfere with the text mode screen output.
`-diag-file`	Append diagnostic information to a file called `memu.log`.
`-diag-file=filename`	As above, but to file of your choice.
`-diag-ring`	Log diagnostic information to a ring buffer in memory. When MEMU terminates, dump this to `memu.ring`. A great way to avoid filling the disk with `memu.log` when all you care about is recent activity prior to failure.
`-diag-ring=filename`	As above, but to file of your choice.
`-diag-win-unknown-key`	Displays host operating system specific keycodes typed in the windows which are not recognised by MEMUs window handling code. These will be XWindows KeySym values or Windows virtual keycodes. Recognised values are passed on to the emulation of the MTX keyboard.
`-diag-win`	Turn on all diagnostic options with names starting with `-diag-win`
`-diag-mem-iobyte`	Show when the IOBYTE is written to.
`-diag-mem-subpage`	Show when the ROM subpage register is written to.
`-diag-mem-dump`	When the program terminates, write the Z80 address space to a file called `memu.mem`.
`-diag-mem`	Turn on all diagnostic options with names starting with `-diag-mem`.
`-diag-vid-status`	Show when the VDP status register is read.
`-diag-vid-registers`	Show when VDP registers are written to.
`-diag-vid-address`	Show when the VDP address register is set, and whether for read or write.
`-diag-vid-data`	Show all data transferred to/from the VDP memory. Tries to log the data in formats allowing you to recognise which graphics data is being uploaded. Will cause a lot of logging.
`-diag-vid-refresh`	Show when the VDP screen is repainted to the Window on the host screen. This is the point at which the VDP interrupt bit becomes set.
`-diag-vid-markers`	Show additional markers on the Window. One is a line which moves down the screen, one pixel per frame, which can be observed to see if time is progressing smoothly in the emulation. Another shows on which scan lines there are >=5 sprites.
`-diag-vid-time-check`	Perform VDP timing sanity checks. Information about the timing parameters is given below.
`-diag-vid-time-check-abort`	Terminate if timing check fails.
`-diag-vid-time-check-drop`	Fail to store the data in VRAM, or return 0xff, if timing check fails.
`-diag-vid`	Turn on all diagnostic options with names starting with `-diag-vid`.
`-diag-kbd-win-key`	Show recognised key presses and releases in the VDP window which are not understood.
`-diag-kbd-drive`	Show keyboard drive values returned.
`-diag-kbd-sense`	Show keyboard drive and sense values returned.
`-diag-kbd-auto-type`	Show the workings of the auto-type mechanism.
`-diag-kbd-remap`	Show diagnostics relating to the keyboard remapping feature.
`-diag-kbd`	Turn on all diagnostic options with names starting with `-diag-kbd`.
`-diag-joy-init`	Show joystick initialisation messages.
`-diag-joy-usage`	Show joystick messages generated as joystick data is read.
`-diag-joy`	Turn on all diagnostics options with names starting with `-diag-joy`.
`-diag-dart-ports`	Show accesses to DART ports.
`-diag-dart-config`	Show DART configuration.
`-diag-dart-data`	Show DART data transfer.
`-diag-dart`	Turn on all diagnostics options with names starting with `-diag-dart`.
`-diag-snd-registers`	Show accesses to the sound chip registers.
`-diag-snd-latency`	Show information relating to the latency parameters passed to PortAudio.
`-diag-snd-init`	Don't suppress stderr during `Pa_Initialize()` call.
`-diag-snd`	Turn on all diagnostic options with names starting with `-diag-snd`.
`-diag-ctc-registers`	Show when CTC registers are written to.
`-diag-ctc-pending`	Show when an interrupt becomes pending on a channel.
`-diag-ctc-interrupt`	Show when the fact the interrupt is pending is communicated to the Z80 chip (usually within 1000 clks).
`-diag-ctc`	Turn on all diagnostic options with names starting with `-diag-ctc`.
`-diag-mon-hw`	Show diagnostics relating to the hardware level emulation of the 6845 CRTC card and underlying memory.
`-diag-mon-kbd-win-key`	Show recognised key presses and releases sent to 80-column window. Only applies if `-mon-win` is being used.
`-diag-mon-kbd-map-th`	Show keycodes read from TH. Only applies if `-mon-th` is being used.
`-diag-mon`	Turn on all diagnostic options with names starting with `-diag-mon`.
`-diag-sdxfdc-port`	Turn on all diagnostic relating to SDX FDC port access.
`-diag-sdxfdc-hw`	Turn on all diagnostic relating to SDX FDC hardware.
`-diag-sdxfdc-data`	Turn on all diagnostic relating to SDX FDC data.
`-diag-sdxfdc-status`	Turn on all diagnostic relating to SDX FDC status.
`-diag-sdxfdc`	Turn on all diagnostic options with names starting with `-diag-sdxfdc`.
`-diag-sidisc-file`	Turn on all diagnostic relating to Silicon Disc file reading and writing.
`-diag-sidisc-address`	Turn on all diagnostic relating to Silicon Disc sector address control.
`-diag-sidisc-data`	Turn on all diagnostic relating to Silicon Disc data transfer.
`-diag-sidisc`	Turn on all diagnostic options with names starting with `-diag-sidisc`.
`-diag-print`	Show characters that are printed.
`-diag-spec-ports`	Log accesses to Speculator ports.
`-diag-spec-interrupts`	Log things relating to Speculator interrupts.
`-diag-spec`	Turn on all diagnostic options with names starting with `-diag-spec`.
`-diag-cpm-driver`	Log all calls to driver code in high memory.
`-diag-cpm-cbios`	Log all calls to CBIOS routines.
`-diag-cpm-bdos-file`	Log all calls to CP/M BDOS relating to file access.
`-diag-cpm-bdos-other`	Log other calls to CP/M BDOS.
`-diag-cpm-bdos`	Turn on all diagnostic options with names starting with `-diag-cpm-bdos`.
`-diag-cpm`	Turn on all diagnostic options with names starting with `-diag-cpm`.
`-diag-z80-instructions`	Log CPU registers and disassemble instruction prior to executing each instruction. Will cause a lot of logging.
`-diag-z80-instructions-exclude from-to`	Turn off logging CPU registers and disassemble instructions for instructions at addresses between `from` and `to` (eg: `0x0000-0x3fff`).
`-diag-z80-instructions-include from-to`	Turn on logging CPU registers and disassemble instructions for instructions at addresses between `from` and `to`.
`-diag-z80-interrupts`	Log when the Z80 takes an interrupt, and show the peripheral supplied low byte of the vector table address.
`-diag-z80-time`	Include timing information in the Z80 instructions logged.
`-diag-z80`	Turn on all diagnostic options with names starting with `-diag-z80` (except `-diag-z80-instructions-exclude`).
`-diag-bad-port-display`	Display when unemulated ports are accessed.
`-diag-bad-port-ignore`	Do not halt MEMU when certain unemulated ports are accessed. By default, termination happens for ports which are known to be used by particular hardware.
`-diag-bad-port`	Turn on all diagnostic options with names starting with `-diag-bad-port`.
`-diag-panel-hack`	Diagnostics relating to the hack which allows PANEL and `VDEB.COM` single-stepping to work.
`-diag-tape`	Diagnostics relating to the MTX BASIC LOAD/SAVE/VERIFY commands. It also shows diagnostics relating to the Z ZX Spectrum LOAD/SAVE/VERIFY commands.
`-diag-speed`	Every second, output an estimate of the emulated chip speed. If running with `-fast` this could be much higher than 4MHz. If running with `-mon-console` and the program waits for keyboard input, because the simulation is suspended this could to drop to near zero.
`-diag-exit`	Display the reason for the termination of MEMU.
`-diag-all`	Turn on all of the above (except `-diag-console` and `-diag-file`).

By default the VDP timing checks assume the Z80 is running at 4MHz, the video is refreshing at 50Hz and a PAL video format. The 80000T between frames is therefore comprised of 120 vertical blank and 192 active scan lines, giving 30769T in which 8T between VDP I/Os is fine and 49230T in which the must be a 32T gap between VDP I/Os. The physical reality may be slightly different, so the sanity check may complain where it shouldn't, or fail to complain where it should. This default setup is equivalent to specifying -vid-time-check 8,32,30769 on the command line. You can vary these parameters.

In addition to the above, MEMU supports three diagnostic windows :-

Option Description
-diag-ui-mem The Memu Memory Inspector window allows you to specify an IOBYTE (and ROM subpage) and then to show what the Z80 processor sees at various addresses.

i - focus on the IOBYTE
u - focus on the ROM subpage
s - focus on the start address
p - focus on the highlighted address
t - focus on the data table
o - take a RAM snapshot
v - toggle whether current or snapshot RAM is shown
Tab - move focus
Left,Right,Up,Down,PageUp,PageDown - move the highlighted address
hex digits - edit the value where the cursor is

-diag-ui-vram The Memu VRAM Inspector window allows you to show the contents of VRAM.

s - focus on the start address
p - focus on the highlighted address
t - focus on the data table
Tab - move focus
Left,Right,Up,Down,PageUp,PageDown - move the highlighted address
hex digits - edit the value where the cursor is

-diag-ui-dis The Memu Disassembly Inspector window allows you to specify an IOBYTE (and ROM subpage) and disassemble the code seen by the Z80 at various addresses.

i - focus on the IOBYTE
u - focus on the ROM subpage
s - focus on the start address
Tab - move focus
j - jump to indicated address
k or Right - push current listing, list from indicated address
l - toggle display of illegal instruction infomation
m - toggle MTX specific disassembly
Escape or Left - pop to previous listing
Up,Down,PageUp,PageDown - move the highlighted address
When an instruction references (ie: jumps or calls) another address, an indication is given to the right of the instruction where the jump or call will go.

Option	Description
`-diag-ui-mem`	The Memu Memory Inspector window allows you to specify an IOBYTE (and ROM subpage) and then to show what the Z80 processor sees at various addresses. i - focus on the IOBYTE u - focus on the ROM subpage s - focus on the start address p - focus on the highlighted address t - focus on the data table o - take a RAM snapshot v - toggle whether current or snapshot RAM is shown Tab - move focus Left,Right,Up,Down,PageUp,PageDown - move the highlighted address hex digits - edit the value where the cursor is
`-diag-ui-vram`	The Memu VRAM Inspector window allows you to show the contents of VRAM. s - focus on the start address p - focus on the highlighted address t - focus on the data table Tab - move focus Left,Right,Up,Down,PageUp,PageDown - move the highlighted address hex digits - edit the value where the cursor is
`-diag-ui-dis`	The Memu Disassembly Inspector window allows you to specify an IOBYTE (and ROM subpage) and disassemble the code seen by the Z80 at various addresses. i - focus on the IOBYTE u - focus on the ROM subpage s - focus on the start address Tab - move focus j - jump to indicated address k or Right - push current listing, list from indicated address l - toggle display of illegal instruction infomation m - toggle MTX specific disassembly Escape or Left - pop to previous listing Up,Down,PageUp,PageDown - move the highlighted address When an instruction references (ie: jumps or calls) another address, an indication is given to the right of the instruction where the jump or call will go.

MEMU has a special RAM snapshot feature. First, you tell MEMU how many of the RAM pages are to be included in the snapshot using the -mem-blocks-snapshot N command line argument. N is the number of 16KB RAM pages. This number is normally 0, but might reasonably be 4 when debugging. MEMU takes a snapshot just before the Z80 is started, and if you're running a RUN file from the MEMU command line, just before it is given control. In the Memu Memory Inspector window colours communicate the following :-

blue - no memory present here
magenta - ROM
cyan - RAM, but not a part that has a snapshot
green - RAM, which matches the snapshot
white - RAM, different to the snapshot

Pressing o takes a new snapshot. Pressing v toggles whether you are looking at the current value, or the value in the snapshot.

Remember to use -diag-console, -diag-file or -diag-ring (or a combination of these), or you won't see any diagnostic output.

MEMU also responds to the following diagnostic key presses. F9 is used like a Shift key :-

Key Description
F9+c Toggles -diag-console
F9+a Toggles accelerated mode
F9+b Toggles -diag-mem-iobyte
F9+d Dump memory to memu.mem
F9+f Toggles -diag-cpm-bdos-file
F9+i Toggles -diag-z80-interrupts
F9+k Toggles -diag-kbd-sense
F9+l Loads ZX snapshot file, as specified by -sna-file
F9+m Toggles -diag-speed
F9+p Toggles -diag-bad-port-display
F9+q Toggles -diag-bad-port-ignore
F9+r Dumps a snapshot of the Z80 registers
F9+s Saves ZX snapshot file, as specified by -sna-file
F9+t Rewinds to the start of a ZX tape file
F9+v Dumps a snapshot of the VDP registers
F9+n Dumps the VDP to memuNNNNNN.vdp. This writes 16KB VRAM, 8 register bytes, and 1 status register byte.
F9+o Toggles auto VDP dump mode on or off
F9+w Snapshots the VDP screen to memuNNNNNN.bmp
F9+x Toggles auto VDP snapshot mode on or off
F9+y Toggles -diag-spec-ports
F9+z Toggles -diag-z80-instructions

Key	Description
F9+c	Toggles `-diag-console`
F9+a	Toggles accelerated mode
F9+b	Toggles `-diag-mem-iobyte`
F9+d	Dump memory to `memu.mem`
F9+f	Toggles `-diag-cpm-bdos-file`
F9+i	Toggles `-diag-z80-interrupts`
F9+k	Toggles `-diag-kbd-sense`
F9+l	Loads ZX snapshot file, as specified by `-sna-file`
F9+m	Toggles `-diag-speed`
F9+p	Toggles `-diag-bad-port-display`
F9+q	Toggles `-diag-bad-port-ignore`
F9+r	Dumps a snapshot of the Z80 registers
F9+s	Saves ZX snapshot file, as specified by `-sna-file`
F9+t	Rewinds to the start of a ZX tape file
F9+v	Dumps a snapshot of the VDP registers
F9+n	Dumps the VDP to `memuNNNNNN.vdp`. This writes 16KB VRAM, 8 register bytes, and 1 status register byte.
F9+o	Toggles auto VDP dump mode on or off
F9+w	Snapshots the VDP screen to `memuNNNNNN.bmp`
F9+x	Toggles auto VDP snapshot mode on or off
F9+y	Toggles `-diag-spec-ports`
F9+z	Toggles `-diag-z80-instructions`

During development of MEMU, one of my games scrolled unevenly, due to an initially incorrect Z80 CTC implementation. I eventually tracked down what was going on using :-

$ memu -diag-console -diag-vid-refresh -diag-ctc -diag-z80-interrupts \
       -vid-win-big SMG2M.COM

The author is likely to add and/or remove -diag options and/or diagnostic key presses, depending on what he finds is needed to debug problems, and which options turn out to be seldom used. Don't get too attached to them.

Another trick you can use is to force MEMU to terminate when it reaches a given address. This relies on the fact MEMU only expects magic patch instructions to be at certain addresses. If patch.dat contains the 2 magic patch instruction bytes 0xed 0xfe, then you can cause MEMU to halt when it reaches 0x9999, dumping the last few thousand instructions it executed just before it got there :-

$ memu -diag-ring -diag-z80 \
       -addr 0x9999 -mem patch.dat \
       -vid-win-big -snd-portaudio \
        SOMEGAME.COM
memu: magic instruction unexpectedly encountered at 0x9999

On UNIX or Windows versions of MEMU, a backdoor can be enabled, allowing BE to access memory and VDP content via the BEMEMU memory extension. This can provide a better view inside emulated memory than is possible using -diag-ui-mem, -diag-ui-dis, and -diag-ui-vram, as BE supports sophisticated structured data decode, navigation, use of disassemblers, with reference to symbol tables.

The above example shows me disassembling Speculator.mtx, as it is running, which is possible as BE is also using the BEZ80 disassembler extension.