fossimon v0.04 -------------- An NMI based monitor for esxDOS. Features -------- - Z80 disassembler. - Register display. - Trace / single step Z80 instructions. - POKE memory. - Find text, addresses and byte sequences. - Save to and load memory from esxDOS files. - List, delete files and change folders from esxDOS. - Log output from the monitor to a file to capture memory dumps and disassemblies as text files. - Save and load memory snapshots from the monitor. - Configurable colours, number display and disassembly output options. - Integration with Long Filename Browser through NMI menu. Requirements ------------ - A ZX Spectrum with at least 48k of RAM. - A DivMMC with 128k of additional memory (e.g. the DivMMC Future). - esxDOS 0.8.9 - I have received a report of it working on 0.8.7. - My .browse long file name browser for the 'Browser' option in the NMI menu. Installation ------------ Copy the contents of the BIN folder to the BIN folder on your SD card. To permamently install the monitor: 1. If you only want the monitor, copy SYS/NMI_MON.SYS to SYS/NMI.SYS on your SD card, replacing the existing NMI.SYS. 2. If you want to run both the monitor and long filename browser from a menu, copy SYS/NMI_MENU.SYS to SYS/NMI.SYS on your SD card, replacing the existing NMI.SYS. 3. If you want to run the monitor by pressing SYMBOL SHIFT and the NMI button and the long filename browser otherwise, copy SYS/NMI_KEY.SYS to SYS/NMI.SYS on your SD card, replacing the existing NMI.SYS. 4. Pressing the NMI button should take you directly into the monitor if you followed step 1, into the menu if you followed step 2 or into the monitor if SYMBOL SHIFT is also held down at the same time if you followed step 3. To temporarily install the monitor (hard reset or power cycle will remove it): 1. Copy SYS/NMI_MON.SYS, SYS/NMI_MENU.SYS and SYS/NMI_KEY.SYS to the SYS folder on your SD card. 2. If you only want the monitor, from BASIC enter: .fossimon -d 3. If you want to run both the monitor and long filename browser, from BASIC enter: .fossimon -m 4. If you want to run the monitor when SYMBOL SHIFT is held down with the NMI button, from BASIC enter: .fossimon -k 5. Pressing the NMI button should take you directly into the monitor if you followed step 2, into the menu if you followed step 3, or into the monitor if SYMBOL SHIFT is held down if you followed step 4. Usage ----- If you have installed NMI_MON.SYS, pressing the NMI button will take you directly into the monitor. If you have installed NMI_MENU.SYS, pressing the NMI button will take you into the NMI menu. The monitor can be entered by pressing M. The browser can be launched by pressing B. If you have installed NMI_KEY.SYS, pressing the NMI button and holding the SYMBOL SHIFT key down will take you into the monitor, otherwise the browser will be launched. The monitor is controlled via a command prompt, > where you type a command and optional parameters into. Pressing ENTER executes the command. You can edit the command using the cursor left, cursor right and delete keyes. Pressing cursor up will recall the last entered command. Number parameters prefixed with $ are treated as hexadecimal. Otherwise they are assumed to be decimal. Parameters are separated by spaces. String parameters can be specified using one or two double quotes: >sa "snap.sna and >sa "snap.sna" are the same. If you want to include spaces inside a string you need to end the string with double quotes - otherwise the command tokeniser will see the space as the end marker for the parameter. Command list ------------ The following commands are available. h Shows a brief list of available commands. Pressing BREAK or 'n' at the 'More...' prompt exits the listing. -- x Exits the monitor and returns you to the point at which you pressed the NMI button. -- xx Exits the monitor and resets the computer. -- cls Clears the screen and returns the cursor to the top of the screen. -- r Show the content of the Z80 registers at the point of pressing the NMI button. Shadow registers are indicated with the ' character. Contents of the flags and shadow flags are shown after the registers. -- rs "register" Sets the Z80 register specified in "register" to the value specified in . >rs "hl 16384 would set the hl register to 16384. -- ? ? Shows the binary, decimal and hex values of a 16 bit value. >? 16384 16384 $4000 %0100000000000000 You can also specify one of four operators: + - / * and a second value to perform simple 16 bit calculations. >? 32768 / 2 16384 $4000 %0100000000000000 -- d
Disassembles Z80 opcodes starting at
. Any key advances the disassembly. BREAK key exits. Entering the command without an address will carry on from the last address disassembled from, or address 0 if you haven't performed a previous disassembly. The disassembler should handle all prefixed and undocumented opcodes. You can also disassemble from a register. >d "hl This would start the disassembly from the value contained in the hl register. -- m
Dumps memory starting at
as ASCII and hexadecimal character values. Any key advances the dump. BREAK key exits. Entering the command without an address will carry on from the last address dumped from, or address 0 if you haven't performed a previous memory dump. You can also dump memory from a register. >m "hl This would start the memory dump from the value contained in the hl register. -- ma
Dumps ASCII characters only starting at
. Any key advances the dump. BREAK key exits. Entering the command without an address will carry on from the last address dumped from, or address 0 if you haven't performed a previous memory dump. You can also dump from a register. >ma "hl This would start the dump from the value contained in the hl register. -- tr Executes a single opcode from the current program counter. Control will briefly switch back to the program to execute the opcode and then switch back to the monitor. On return the current register values and flags will be displayed alongside the current opcode. Error 1 is returned if you try to trace inside a ROM address (0-16384). This isn't supported. Error 2 is returned if you try to trace the following instructions: reti, retn If you have executed a tr command and are back in the monitor, pressing EXTEND MODE (caps shift and symbol shift together) will execute another trace command immediately. The monitor will try and do a fast trace - where the opcode is executed in the context of the monitor - wherever possible. However for some opcodes, the monitor will need to return control back to the program to successfully execute the opcode and then jump back into the monitor. Fast trace will fail under the following circumstances: 1. One of these opcodes is encountered: call di in jp ldir outi cpd djnz ind jr otdr pop cpdr ei indr ldd otir push cpi halt ini lddr out ret cpir im inir ldi outd rst 2. The opcode uses indirect registers, e.g. (de) (bc) (hl) (ix +) (iy +). 3. The opcode uses the content of an address ld n, (nnnnn) / ld (nnnnn), a -- sm
"filename" Saves memory of bytes starting from
to "filename". The following command will save the screen to a file. >sm 16384 6912 "screen$ You can save a file with a PLUS3DOS header with the following command: >sm 16384 6912 "screen$ + With the '+' specified, a header is appended to the start of the file. This lets you do LOAD * "filename" CODE from BASIC without having to specify a load address as this is taken from the header. Otherwise, the file is just the raw memory bytes and will need a load address specifying. -- lm
"filename" Loads bytes from "filename" to
. The following command will replace the contents of the screen with the contents of the file 'screen$'. >lm 16384 6912 "screen$ You can also use * so the monitor uses the file size (up to a maximum of 65535 bytes) for the parameter. > lm 16384 * "screen$ -- sr
Performs a soft reset back to basic which preserves the contents of memory. If
is not specified or is less than 23999, the value of 23999 is used which preserves memory from address 24000 upwards. >sr 32767 Would soft reset and preserve memory from address 32768 upwards. This can be useful if you need to try and return control from a stuck program without losing your program by having to do a full reset. -- br
Adds an NMI breakpoint at
. When the program counter register reaches this address, the monitor will break back in. Breakpoints are not supported for ROM addresses (0-16384). Breakpoints work by modifying the code at the given address. If subsequent code alters the code at the breakpoint address, the breakpoint will not fire. -- fi Searches memory for an address, string or sequence of bytes. >fi "GAME 32768 40000 Would search for the string GAME in addresses 32768 to 40000. If is not specified, the value is set to 65535. >fi $8000 40000 Would search for the hex value $8000 in addresses 40000 to 65535. This can be useful to references to addresses in opcodes. >fi $31,$ff,$7f 50000 Would search for byte sequence $31,$ff,$7f (the opcode ld sp, $7fff) in addresses 50000 to 65535. -- fm
Fills memory from
with , times. >fm 96 22528 768 Would turn the screen bright green as the screen attribute area has been filled with the value PAPER 4 (32) + BRIGHT (64). -- st
Shows the content of
as a stack or current stack pointer if
is not specified. -- pg Page in the specified 128 bank of memory. is the bank number between 0 and 7. Calling this command without a value will display the current bank that is paged in. This will alter the memory available between 49152 and 65535. Any commands that use this memory in this range will use the currently paged in memory. Whatever bank you have paged in, on exit the bank that was paged in before the NMI was entered will be restored. This command has no effect on 48k machines. -- p
POKE
with . >p 50000 201 Would POKE 201 into address 50000. >p 50000 $11,$00,$c0 Would POKE the sequence of values $11,$00,$c0 (ld de, $c000) from address 50000. >p 50000 "hello world!" Would POKE the sequence of characters "hello world!" (minus the quotes) from address 50000. -- s$ Displays the current screen image. Pressing 'a' toggles screen attributes on or off. When attributes are off, you can press 'g' to show a BRIGHT grid to show the positioning of screen elements. Pressing any other key in this mode returns you to the monitor. -- sa "filename" Saves all memory and registers to "filename" in .SNA format. This will be a 49179 bytes long file on 48k machines and 1331103 bytes on 128k machines. -- la "filename" Loads a .SNA format snapshot or file previously saved with the sa command back into the monitor. On successful load the current register state is shown in the monitor. Execution of the snapshot resumes when you exit the monitor. -- cfg This command lets you configure various options in the monitor. >cfg "bo 0 Would set the BORDER colour to 0. is 0-7. >cfg "sa 56 Would set the screen attributes to INK 0: PAPER 7 (black text on white background). The value is calculated with INK + (PAPER * 8). Add 64 to the value for BRIGHT. >cfg "hx 1 Would set hexadecimal number output. All addresses, registers and opcodes will now use hexadecimal numbering. Setting this back to 0 restores decimal numbering. >cfg "uc 1 Would set uppercase disassembly output. Setting this back to 0 restores lower case output. >cfg * Saves your current config to /bin/mon.cfg. -- ls Shows the contents of . >ls "/sys Would list the content of the root folder SYS. If is not specified the current directory is used. Pressing BREAK at the 'More...' prompt exits the listing. -- cd Changes the current esxDOS path to . >cd Would show the current path. >cd "/bin" Would change the current path to /BIN, -- rm Deletes the specified esxDOS file without confirmation. It won't delete folders. -- lg lg "your message goes here" lg ! lg + lg - The lg command displays and writes data to the monitor log file in /tmp/mon_log.txt. lg Display the contents of the log file. lg "your message goes here" Appends the line of text "your message goes here" (without the quotes) to the log file. lg ! Clears the content of the log file without confirmation. lg + Start monitor output command logging. Subsequent monitor output from the commands, e.g. memory dump, disassembly will be added to the log file as lines of text. This lets you export memory dumps and disassembly from the monitor into a plain text format. lg - Stop monitor output command logging. -- fc
"filename" Compares memory from
with the contents of "filename". Any differences between the memory and file content will be printed to the console in the following format:
This command may be useful in detecting changes in memory, e.g. to find counters in games. You could save an area of memory with the sm command (sm 32768 10000 "dmp), return to the game and lose a life or fire a weapon and then use the fc command to compare the current memory area with the saved memory area (fc 32768 "dmp). -- cm Copies bytes from address to address. Questions --------- Q: Why? A: Yes, rather pointless with modern Spectrum emulators and their integrated debuggers but I thought there might be at least 5 people out there who would appreciate or actually want an NMI based monitor for esxDOS on real hardware. Surprisingly, it turns out there are at least 5 people people who do appreciate or actually want an NMI based monitor for esxDOS on real hardware. Q: Why doesn't it work or look like Genie / VAST / devastace / ? A: I wanted a monitor program that looked like Action Replay III and functioned like the Amiga Monitor / Rossimon I used to mess about with on the Amiga many moons ago. These take in, parse and execute comands rather than using menus or relying on you to remember which combination of keys you need to press to do something. Q: Can I enter the monitor programatically? A: Calling address 102 / $66 will enter the monitor. Known Issues ------------ - Memory dumped or disassembled between addresses 0 and 16383 will be from the esxDOS ROM and not the original ROM. Information ----------- Tools Used: MX Linux KDE (laptop) z80asm / z88dk - assembler Fuse - testing / debugging code in an esxDOS environment hdfmonkey / mtools - HDF file creation and file image manipulation SciTE - Text / source code editor Acknowledgements ---------------- Decoding Z80 Opcodes - Christian Dinu - http://www.z80.info/decoding.htm bob_fossil 2024