About Zeal 8-bit Computer emulator

The purpose of this project is to provide an easy way to try Zeal 8-bit Computer, as well as develop and debug for it thanks to the embedded debugger. The emulation is cycle accurate, so the behavior of the programs run inside this emulator should be the exact same as on the real hardware.

You can find more information about Zeal 8-bit Computer on Youtube or on the project official website zeal8bit.com

Source code

The source code of the emulator is available on the official Github repository: https://github.com/Zeal8bit/Zeal-WebEmulator

Licence

The CPU core (Z80.js) is distributed under the MIT license (originated from Molly Howell repository)

All the other files of the project are distributed under the Apache 2.0 License.

Credits

People involved in the project:

• Zeal8bit: owner, main developer and maintainer
• JasonMo: contributor
• ZT-Pepite: contributor

For more details about the contributors, follow this link.

Getting started with the emulator

The interface of Zeal 8-bit Computer emulator is rich in tools. They make it possible to simulate almost every part of the actual computer.

1. ROM/EEPROM loading
2. Emulated screen and PS/2 keyboard
3. Bottom views: disassembler, memory viewer and UART monitor
4. Debugging actions: start/resume CPU, step in, step over, stop, reset, clean
5. Breakpoint management
6. CPU registers value

Loading a ROM

Loading a ROM can be done through the left panel section:

The emulator offers two ways to load code inside the ROM:

• Select a pre-built ROM image of Zeal 8-bit OS. This includes the latest version, nightly builds and the releases. All of them are compiled from Zeal 8-bit OS official repository.
• Load your own image of the ROM, and an optional (64KB) EEPROM image. Since the images will directly be copied inside the emulated ROM and EEPROM respectively, this image does not necessarily contain Zeal 8-bit OS, it can contain any Z80 code. The system map file, as its name states, is the .map file generated by z88dk-z80asm when assembling a program. Providing this file will add symbols inside the disassembler.

The first option is preferred if you want to quickly test Zeal 8-bit OS, or if you want to load your own programs, while the second option is preferred if you want to debug the operating system itself or a ROM image you have.

Note: when loading your own images and clicking Read file(s) button, it is necessary to press debugger's Continue button to start the CPU!

Emulated screen and PS/2 keyboard

At the middle of the interface lies a 640x480px canvas that emulates Zeal 8-bit VGA video board. This interface will draw all the pixels that would be drawn by the VGA video board.

This canvas also contains a keyboard listener that will send all the keys typed to the PS/2 protocol emulator. Therefore, the canvas must be focused first (by clicking on it) before trying to type anything.

Disassembler

The disassembler, as its name states, disassembles the binary code being executed by the Z80 CPU into assembly code. It also shows the current breakpoints with a small red dot on the left. It is possible to add or remove breakpoints from there by clicking on the corresponding instruction.

The current instruction (current PC) will always be at the top of the disassembler view. The format of each line is as follows:

[dot] instruction ; [virtual address] raw bytes of the instruction

The code is only disassembled when the CPU is stopped, either because it encountered a breakpoint or when the stop button is manually pressed.

Note: If a .map file was provided when loading the ROM, the symbols, such as the routines or labels name, will also be shown. Constants are not replaced in ld or related instructions since these information are not provided by the map file.

Memory viewer

The memory viewer tool is convenient to see the content of memory at any address. The address and size to dump can be provided via the text inputs. The address must be provided in hexadecimal whereas the size is provided in decimal.

The provided address is a virtual address and not physical address. This is important since Zeal 8-bit Computer has an MMU, so each 16KB virtual pages can be mapped to any 16KB physical page.

The dump memory lines are presented as follows:

virtual address (physical address) 32-byte dump ASCII representation

This view also provides two buttons to dump the current ROM and (I2C) EEPROM content respectively.

Note: This view is only updated when the dump button is pressed. If a byte in memory changes, the view won't show the new value until the view is refreshed (dump button pressed)

UART monitor

Zeal 8-bit Computer provides has a UART interface. Even though it is a software UART implemented with the Z80 PIO, it can also be used on the emulator thanks to the cycle accurate emulation.

This tool can be used to see the data sent by the computer through UART, but also to send text, including files. The baudrate can be configured by using the option menu.

Keep in mind that if it seems like the monitor doesn't have any reaction when typing in the monitor, it is because the CPU is not currently listening on the UART, sending anything ot the UART.

Debug actions

The right panel is dedicated to debug actions. It contains the follow actions:

• Start/resume CPU execution (F9 shortcut)
• Step into (F10): clicking this button when performing step by step debugging will follow the destination of jump instructions such as rst, call, jp, jr...
• Step over (F11): clicking this button when performing step by step debugging will execute the following jump instructions but will break after it.
• Stop: stop the CPU execution, showing the registers value
• Reset: performs a CPU reset
• Clean: completely cleans the ROM, RAM and EEPROM in order to load a new program to the board. This feature is used when switching between pre-built ROMs

Breakpoint management

Just like a regular debugger, it is possible to put breakpoints that will stop the CPU execution, showing the current value of the CPU registers and code disassembly.

The text entry accepts hexadecimal values, with or without 0x prefix. Moreover, if a .map file is provided, it is possible to write the name of label to break on. This is convenient to debug a program's function/routine that often has a different address.

Breakpoints can be disabled by clicking on the red dot and re-enabled by clicking them again.

It is currently not possible to completely remove breakpoints.

CPU registers

The left panel present a direct way to see the CPU register value when the CPU stops because of a breakpoint or a manual stop.

The 16-bit registers, BC, DE, HL, PC, SP have an underlines value to show that they are clickable. By clinking on a value, the memory viewer will be opened and will show the content of the address.