duncanamps / box80

Z80 Virtual Machine

box80 V0.0

One liner: box80 - A cross-platform open-source Virtual Machine to run and debug Z80 code (very much work in progress)

Description

box80 is a multi-platform virtual machine designed to execute Z80 code in a 64K code space. The main objective is to have a rich and capable cross-platform environment for debugging of CP/M assembly language programs, rather than to serve as Yet Another Emulator for CP/M.

Features

Note: Many of these are not yet implemented! Please see the development status further down the page for an update on the status

• General
  • Open Source
  • Dual thread model; one for the user interface and one for the Z80 processor and SIO
  • Multi-platform design - can be used on many different target 32/64 bit machines
• Hardware emulation is based on the CP/M on breadboard by Grant Searle and caters for the following features:
  • Core platform emulation
    • Z80 processor at various speeds from 32768Hz to 500MHz, depending on host hardware capability
    • Z80-SIO used to control serial input and output. This is redirected to the Windows screen and keyboard, there is no real serial link
    • CF card interface to allow storage of the CP/M operating system, CP/M commands, and user installed software and data
    • The ROM disable feature is not currently implemented as it is not actually used (the monitor is loaded into RAM automatically by the VM)
  • Terminal emulation
    • Integrated terminal screen and keyboard emulation using ANSI colour display
    • Ability to receive text/hex files to the terminal
    • Log text output to a file (partly implemented)
  • Debug features (not implemented)
    • Disassembler
    • Memory viewer
    • Watch window with different variable types
    • Conditional breakpoints
    • Traps for illegal instructions, unimplemented ports, etc.
    • Can use debug files created by xa80 cross assembler to access labels and step through source lines
    • Can direct load files into VM memory from host operating system

Dependencies

To use a basic CP/M operating system, this software requires the following components:

1. Monitor image to allow the initial boot. This will interface with the SIO chip and the CF card
2. BIOS image to support the following
   • Z80-ZIO using ports $00..$03
   • Compact Flash IDE interface using ports $10..$17
3. A language or operating system, one of the following:
   • Microsoft BASIC image
   • CP/M image containing:
     • BDOS (Basic Disk Operating System)
     • CP/M CCP (Console Command Processor)
   • Something else

None of the items above can be included with this distribution as they have their own licensing terms. Terms for use of the software can be found on the respective websites and in the source code for the different components. The documents section contains dependencies.pdf which explains how to download and assemble the modules listed above (not implemented).

Development Environment

box80 is written in Free PASCAL hosted under the Lazarus IDE. To modify and compile this software, you will need Lazarus 2.1.0 or later. It has been tested on Windows. There are no "OS specific" twists, so it should be possible to recompile on other hosts which are supported by the Lazarus ecosystem in 32 and 64 bit flavours, including:

• Android
• FreeBSD
• iOS
• Linux
• macOS
• Raspberry Pi
• WinCE
• Windows

You will need at least a 32 bit Operating System, and some sort of multi-threaded environment.

Gimp and Greenfish Icon Editor Pro were used to provide the graphics elements.

Development status

V0.0 current development

Item	Complete	Notes
Dual thread Z80 core	100%	Operational, still to be validated
Standard Z80 instructions	100%	Needs to be run against a test suite
All Z80 instructions	100%	Standard, doesn't include undocumented
CF card interface	100%	Basic setup, but works fine
Terminal output	100%	Now allows colour ANSI emulation
Interrupt processing	33%	IM2 is complete, trigger by SIO
SIO	50%	Very basic implementation, but works
Documentation	TBD

V0.1 future development

Item	Complete	Notes
Create IDE	TBD	Integrate box80, xa80 and an IDE #28
Breakpoints	TBD
Disassembler	TBD
Watch window	TBD
Use of debug files	TBD	xa80 needs to create these first :)
Ports / device changes	TBD	Allow the ability to change the ports used for the SIO/CF

V0.2 future development

Item	Complete	Notes
Undocumented instructions	TBD	489 undocumented instructions to add #27

History

The box80 application is part of a small, but growing ecosystem I've been putting together.

40+ years ago, I wrote assemblers in BASIC, then moved to writing them in assembler itself, for machines like the Apple II (6502) and Sinclair ZX81 (Z80). I didn't understand the concept of parsers and the processing was crude. But they worked and I learnt a lot from them.

As part of my journey, I've been making more of an effort to understand the science of how these things operate and in 2020 wrote LaCoGen, an open-source Lazarus Compiler Generator. It was basically my own home-brewed version of LEX and YACC, the famous Lexer/LALR1 compiler generator tools from the C fraternity, to enable me to have this facility on my favourite Lazarus environment. It was written from the ground up using first principles and knowledge I gained from Compiler Construction: Principles and Practice (Louden) and Compilers: Principles, Techniques, and Tools (Aho, Ullman, Sethi and Lam).

Using the help of LaCoGen, I was able to write xa80, an open-source cross-platform assembler for x80 processors; 8080, 8085, Z80 and Z180. It contains an opcode compiler which was, itself, developed with LaCoGen.

I own a number of Z80 based SBCs; the RC2014, the SC131 and have recently acquired the AgonLight 2 SBC from Olimex. This is a 24 bit EZ80 processor and will undoubtedly result in enhancements to xa80 to cover 24 bit activities. But that's for another day...

The development cycle on some of the retro-hardware can be time consuming: Write Z80 assembly language on the PC. Assemble it. Download via serial link to the target device. Run on the target device. Figure out why it won't work....

For now, it seemed like a good idea to write a simulator to mimic one of the SBCs so that I could eventually integrate this all into an IDE with a Z80 virtual machine, assembler, debugger, etc. This will make it so much easier to work the bugs out of my code, and will drastically shorten the development cycle.

That's the history so far; xA80 is working well and in fact was used to assemble the monitor, CP/M, MS BASIC, etc. box80 is only part complete but is showing promising results so far. It's currently able to run MSBASIC and CP/M 2.2 without issues.

Licence and acknowledgements

All trademarks are acknowledged as belonging to their respective owners.

This software product is not commissioned or endorsed by the semiconductor manufacturers.

box80 is licensed under the GNU GPL Licence V3 or later.

External components which are referenced in this text (monitor, BIOS, CP/M, BASIC) are not included with this distribution and have their own licensing and distribution terms. Please respect the work and rights of the respective authors.

Contact

The author is Duncan Munro
Twitter: @duncanamps
Email: [email protected]

box80's Issues

Need VM Save | As

Have a save command already, now need a Save | As command

Linux fonts and layout doesn't look great

CPU speed 100MHz not setting checkbox

A sample of other speeds looked ok but check/fix all of them

Allow loaded VM to run automatically

If a VM was saved in a running state, it should start running on being loaded.
If, however, it was paused then it will start in a paused state after being loaded

Add licence conditions to each source file

Add the GPL V3 header to each source file and place a link on the Help menu to the GNU website.

UI rearrangement

Rearrange the screen so that:

• The register window is separated out from the main window
• The disassembly / watch windows are separated out too
• The terminal window becomes incorporated in the main window

BASIC part working, but...

When printing an integer value, such as memory available or a BASIC line number, it prints garbage. For example:

Z80 BASIC Ver 4.7b
Copyright (C) 1978 by Microsoft
0>???q~?8?c Bytes free
Ok

Terminal end of line issue

When the end of line is reached, the terminal doesn't automatically go to a new line - the cursor starts going backwards.

Add single step commands

Add the single step commands to step into or step over.

BASIC listing needs keypress to list each line

Type the following:

10 for i = 1 to 10
20 print i
30 next i
list

Just the first program line is listed, then you need to press Enter for each line thereafter. Might be linked to an incorrectly coded processor instruction.

Pressing reset sets processor speed back to 4MHz

Should leave it at whatever speed it was before.

Implement breakpoint capability

Basic at this stage. Need the concept of a permanent breakpoint which has been set by the user, and a temporary breakpoint which is set by the system. Temporary would be used, for example, with step over command by setting a temporary breakpoint after the current instruction.

• Introduce breakpoint array with permanent and temporary breakpoints
• Amend execution module to test for, and handle the breakpoints

Later development will be to set up the step over command, this is dealt with on issue #5

Group menu functions better

File stuff is in multiple places, it should all be under the file menu to cover:

• Compact Flash activities
• Virtual machine save/load

Add Integrated Development Environment (IDE)

Add an Integrated Development Environment (IDE) which will bring together:

• A code editor
• XA80 assembler
• Box80 virtual machine with
  • Debugger
  • Watch windows
  • Memory view
  • etc.

Add CPU speeds to suit SIO chips

Add the following speeds to the options:

• 7,372,800 Hz (64 x 115,200)
• 18,432,000 Hz (160 x 115,200)

Running on Linux causes protection fault

Need to find out what is causing the issue.

Global options screen

Implement a global options screen. For starters, it could contain:

• Option to auto-load last VM at startup. Tied in with #6
• Run after VM load: 1. never, 2. if saved while running, 3. always
• Default terminal width and height
• Default terminal colours at startup
• Terminal default font and size
• Terminal auto-size font
• Terminal allow BEL character (use system sound for this)
• Allow undocumented instructions (will be greyed out as we don't have much undocumented instructions right now)

Replace large buttons with tool buttons

Slow updates on 32768Hz CPU speed option

Need to alter the update speed depending on CPU speed

Create a new blank CF image

Ability to create a new Compact Flash image, either 64MB or 128MB which will depend on the BIOS that's loaded up.

Add main menu

Add main menu and a few features as well:

• Reset capability
• Selection of processor speed

Add MHz indicator

Finish interrupt emulation

Currently only emulates IM2, IM0/1 required. Not desperate for this right now as the only interrupt device is the SIO which is programmed for IM2, but could be used in other modes later on.

Maximum speed time display issue

When CPU speed is set to "maximum" the software sets it to 9,999MHz as this exceeds the capability of my laptop by an order of magnitude.

However, the uS display is not correct as it's based on T States and a theoretical speed of 9,999MHz so it doesn't increment at the correct rate. Need to use the calculated MHz (which is correct) to figure out the uS.

Save VM need error checking in code

Code works but has no error checking, so is susceptible to garbage in corrupted files

Reset not working correctly

Reset is stepping to address 0005 and providing a fault.

Create concept of Projects in the UI

A project should contain things like:

• Window layout
• Processor speed
• List of watches
• List of loaded images

Need a MRU list for projects, and the ability to load the last project at startup

Exec code bug FD CB 07 46

While trying to start the editor in Turbo PASCAL, Box80 fails with an illegal instruction error at $4216

FD CB 07 46

This is the instruction for

        BIT     0,(IY+7)

Which should be a valid (documented) instruction

ANSI keystrokes

Add keyboard facilities for ANSI so that, for example, cursor up / home etc. do more meaningful things.

Add undocumented instructions

There are a total of 489 undocumented Z80 instructions which need to be added. There should be an option to allow them or to raise a fault if they are run.

Add terminal options

Need an options screen for the terminal to cover:

• Screen width and height
• Font selection (style, size)
• Code pages
• Initial colour selection
• Terminal emulation - plain or ANSI
• Bold colour increase
• Amendments to VM load/save routines to take account of varying screen sizes

Rewrite the processor core

Rewrite this before implementing any more instructions or hardware emulation. The key points which need to be addressed are:

• Update the implementation to an Object Oriented design instead of the basic model in place now
• Investigate common parts of instructions rather than each instruction having a separate procedure. For example, instead of LD B.A, LD B.B, LD B.C, etc. have Load8Bit(dst,src). This will reduce coding and introduce less errors.
• Have the processor running in its own thread, but the ability to have non-threaded to help with debugging

Ability to load and save the machine state

Save the memory as a 64K block and all register states including interrupt mode and interrupt enabled.

Specify auto-load on startup

Ability to specify the image file (monitor) to be loaded on startup.

Finish all remaining instructions

30/06/2023 20:00 82.4% std complete, 40.4% total (279/690)
30/06/2023 22:35 96.5% std complete, 46.2% total (319/690)

Move VM Open and Save to File menu

Linux terminal cursor in wrong place

The Linux terminal cursor moves too far to the right when a key is pressed. Also the font doesn't look great

Add disassembler screen

Issues with terminal input from file

Have set up a simple "load to terminal" routine. It seems to be overrunning, locking, etc. etc.

Probably needs a complete overhaul of how the flagging and interaction works in the SIO

Add parameter storage for the app

Need to store defaults, settings, etc.

As this is multi-platform, avoid the windows registry and store in a file (XML?) in the user area.

Terminal losing characters on write

Believe this problem might have existed before and has come back as a result of a major code reversion on #41.

Split UI into panels

Implement ANSI terminal functions

Implement ANSI terminal functions, with colour

uS display incorrect after changing CPU speed

When changing speed from a to b, the uS display gets multiplied by a/b.

Add MRU list to file menu

Changing processor speed causes 4 unfreed mem blocks

Test criteria:

Operation	Result
Start, speed=32768, close	OK
Start, speed=32768, run, close	Access violation
Start, pause, speed=32768, close	OK
Start, pause, speed=32768, run, close	Unfreed blocks

VM load and save code clean up

Need XML document read and write routines in each object (Terminal, Processor, SIO) rather than making the internal registers public

Implement CF hardware

Need to implement the CF (Compact Flash) hardware, however the items listed in issue #1 should be dealt with first.

Create test suite for all instructions

Every feature and flag has to be tested, likely to be a large piece of work.

See if anything available on the web, someone must have done this before.

Add shortcut key to VM save option

Add a shortcut cut, preferably one of the F keys rather than Ctrl+S which may interfere with terminal use.