MartyPC: a cycle-accurate 8088 emulator built for retro PC developers

An emulator for people who write 8088 software

MartyPC started as a hobby: the author wanted to write an emulator from scratch while learning Rust. The stated niche never drifted away from that origin. The project describes itself as an aide for retro PC development, packed with debugging tools and logging facilities, and it names the 8088 programmer as the user who benefits, since those developers can see and measure the exact cycle by cycle execution of their own code.

That audience explains most of the design decisions. An emulator built for nostalgia would prioritize compatibility with a game library; MartyPC prioritizes an instruction timing model faithful enough to say how many cycles a sequence took and whether a demo effect lands on the right scanline. The project is candid about the trade-off, noting that it may not be as user friendly to set up as other emulators and that the target user is someone comfortable editing configuration files.

The hardware it emulates is the early IBM PC family. The supported machines are the IBM Model 5150 (PC), the IBM Model 5160 (XT), the Generic Turbo XT, the IBM PCjr and the Tandy 1000. Written in Rust, it supports Windows, Linux and macOS, and a build also runs in a browser. The repository holds BUILDING.md, CHANGELOG.md, CREDITS.md, an install/ directory, a doc/ directory, a util/ directory and a tests/ directory alongside the crates/ workspace.

The 8088 core and how the cycle claims were checked

The Intel 8088 is implemented as a cycle-accurate core including the asynchronous BIU, the processor instruction queue and prefetch logic. Cycle accuracy work on that core began in November 2022, after the project started in April 2022, and the method of validation is the interesting part.

The author validated the emulator against real silicon: a physical 8088 connected to an Arduino MEGA microcontroller, so that an instruction executes on the emulator and on the real CPU at the same time and the results are compared cycle by cycle. Peripheral work was researched the same way, with the 8253 timer chip investigated using an Arduino, DMA timings explored with an oscilloscope, and a bus sniffer built with a logic analyzer to study the IBM 5150.

The June 2024 update to the test suite added coverage for the 8088 prefetch queue, and that work found and corrected a set of further cycle inaccuracies. According to the project, MartyPC passes the 8088 V2 Test Suite with 99.9997% cycle-accuracy. Treat that as a claim by the project rather than an independent measurement, but it is attached to a named suite and a reproducible procedure.

A second CPU, the NEC V20, has a preliminary implementation. It is cycle-based but not fully cycle-accurate and not as fast as the real part, because the timings were carried over from the 8088 it was based on. All native-mode V20 instructions are implemented and tested for correctness against hardware.

CGA that simulates the whole display field, including overscan

The video side is where the accuracy effort is most visible. CGA is a dynamic, cycle-or-character clocked implementation of the IBM CGA including the Motorola MC6845 CRTC controller, and the project credits it with running demanding demos such as 8088MPH and Area5150. In April 2023 MartyPC became accurate enough to run 8088 MPH, and in May 2023 the project states it was the first PC emulator able to emulate every effect in the Area 5150 demo.

The approach is unusual enough to be worth naming: rather than approximating the card's behaviour, the simulator reproduces the entire display field, overscan included. Composite output and monitor simulation are supported through composite conversion code credited to reenigne, the same code cited as being used by DOSBox and 86Box.

Other adapters are simpler. MDA and EGA are character-clocked implementations, EGA is structured to replicate the logical functions of the LSI chips on the original hardware and adds redefinable fonts, vsync interrupts and per-scanline pel-panning. The MDA device can optionally emulate the Hercules Graphics Adapter. TGA for the PCjr and Tandy is a character-clocked implementation still described as work in progress. VGA emulation is in development, with graphics modes such as Mode 13h and Mode X working.

Where the peripheral support runs out

Device support is uneven, and the differences are more useful to a reader than a flat feature list. The 8255 PPI handles low-level keyboard emulation, including the keyboard shift register and the turbo bit found in TurboXT clones. The 8253 PIT is described as highly accurate and supports PCM audio, and the PC speaker is driven by that timer emulation rather than being a separate sound device, which is enough to produce the PWM audio heard in demos.

Other chips are partial. The 8259 PIC is mostly complete but still lacks priority rotation and nested modes. The 8237 DMAC is mostly implemented, but DMA transfers are currently faked, with DRAM refresh simulated through a scheduling system. The parallel port is emulated only well enough to be detected and is not functional for any purpose yet, which rules it out for anyone whose program depends on printing or on a parallel port dongle. The 8250 UART supports serial passthrough or mouse emulation, and the game port supports two analog joysticks with two buttons each.

Sound is mixed. Adlib is emulated with OPL2 provided by the nuked-opl3 core through the author's opl3-rs bindings, and the project warns that this is CPU heavy and needs a fast computer. The SN76489 three-voice chip from the PCjr and Tandy line is emulated, with a debug display offering UV meters and oscilloscope views per channel.

A Cargo workspace split into library crates and binaries

The build is a Cargo workspace, and the layout tells you how the project is put together. The workspace members are the glob crates/lib/* and crates/bin/*, with resolver 2, and the default member is the binary crate crates/bin/martypc_eframe:

[workspace]
members = [
    "crates/lib/*",
    "crates/bin/*"
]
resolver = "2"
default-members = ["crates/bin/martypc_eframe"]

Package metadata is declared once at the workspace level:

[workspace.package]
version = "0.5.0"
edition = "2021"
rust-version = "1.92"
license = "MIT"
authors = ["Daniel Balsom"]

The rust-version key sets a floor of Rust 1.92, and a rust-toolchain.toml file pins the toolchain for the repository. The graphics stack is winit 0.30 for windows, wgpu 29.0 with the vulkan, dx12, metal, gles and webgpu backends, and glow 0.17 for the older path. The same dependency list mixes a small set of focused libraries: thiserror 2.0, anyhow 1.0, serde with derive, binrw 0.14 for binary parsing, fatfs pulled from the author's fluxfox_fat fork, chrono, regex and strum for enum plumbing.

There is also a dedicated block of wasm dependencies, wasm-bindgen 0.2.108, wasm-bindgen-futures and wasm-bindgen-rayon, which is how the browser build at martypc.net is produced from the same source tree.

Getting a binary: releases, workflow artifacts and the browser build

Prebuilt binaries are published through periodic releases, and the version history shows 0.4.0 on 2025-05-12 and 0.4.1 on 2025-05-31, with 0.2.2 earlier on 2024-06-22. Newer automatic builds are available from the Actions tab under the Artifacts for each workflow run, and the documentation notes that you need to be logged in to GitHub to download those artifacts.

If you are not on Windows, or you want the newest code, the project expects you to build from source. The build instructions live on the MartyPC Wiki in the Building MartyPC guide, and the repository also ships BUILDING.md. The documented version split is worth noting: the last released version is 0.4.1 while the current development version is 0.5.0, and 0.5.0 is what the workspace version field carries. A build from source is therefore ahead of any tagged release.

The setup burden is the acknowledged weak point. Configuration is file based, and the project says plainly that it may not be as user friendly to set up as other emulators, while reassuring the reader that anyone comfortable editing configuration files should not hit major problems. A web build is available at https://martypc.net if you would rather not install anything.

Licence status, release cadence and the state of the tree

The licence field on the repository says Other, described as a custom licence that GitHub cannot classify, with the LICENSE file as the authoritative text. That conflicts with the manifest, where Cargo.toml declares license = "MIT" and lists Daniel Balsom as the author. Anyone shipping MartyPC in a product should read the LICENSE file directly rather than relying on either label, and note that crates.io publication of a dependency with a non-standard licence is a distribution question the LICENSE file governs.

The repository is not archived, and the last push was on 2026-10-15, so the tree is being worked on. The 0.5.0 development version against a 0.4.1 release also indicates the gap between what ships and what is in the tree is a full minor version, and that the release tags lag behind development rather than tracking it closely.

A separate licence question is the code MartyPC depends on. OPL2 audio comes from the nuked-opl3 core through the opl3-rs bindings, and the composite conversion for CGA output is credited to reenigne and is described as also used by DOSBox and 86Box. Those are upstream projects with their own terms, and the CREDITS.md file in the repository is the place to trace them. None of this changes how the emulator behaves, but it matters if you redistribute a build.

Editorial conclusion

MartyPC fits a developer who is writing or debugging 8088 era software and needs instruction level timing, a prefetch queue model and a CGA that reproduces demo effects frame by frame. It does not fit someone who wants a quick game of a floppy image, since the parallel port is not functional, DMA transfers are faked and the project itself warns that setup is less friendly than in other emulators. Verify the emulator's own claim before you rely on it, by running your workload on it and comparing timing against the 8088 V2 Test Suite figure of 99.9997% cycle-accuracy the project reports, then check the device list in the README for the specific chip your program depends on.

Frequently asked questions

Official sources

1. dbalsom/martypc on GitHub
2. Issues
3. README
4. Releases