Skip to content
Emulator of the IBM PC running DOS written in Rust
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Adds a "disassemble executable" option Feb 17, 2020
.travis.yml Fixes arithmetic overflows and underflows in Feb 3, 2020
Cargo.toml Implements DOS environments and command line arguments. Unifies vario… Feb 3, 2020
LICENSE Adds license and hopefully fixes Travis-CI Jan 16, 2020
config.toml Makes the CLI more consistent and adds a default config file Feb 1, 2020

Build Status


VGA Window and Debugger CLI

While this is inspired by DOSBox, it is not a direct port. Many features are implemented differently or not at all. The goal was just to implement enough to play one of my favorite games and learn some rust and emulation principles along the way.

Run the Example

Checkout and build the emulator or download a prebuilt binary from the releases tab.

git clone
cd DOS-Emulator
cargo build --release

Download and unpack the guest application and start the emulator.

curl -GOL
target/release/dos-emulator -C DOS/ DOS/TOM/ROBJUN/ROBJUN.EXE

Then setup your keyboard layout (press 'k' in the CLI and follow instructions below) and enjoy the game!

Command Line Interface

  • Ctrl-c: Quit
  • p: Pause (enter the debugger)
  • k: Enter the keyboard-mapping-tool


Note: The terminal needs to be at least 80 characters wide to correctly display the debugger.

  • p: Profile instructions (and save them to a file)
  • a: Data overview to DS:SI (string source)
  • s: Data overview to SS:SP (stack pointer)
  • d: Data overview to ES:DI (string destination)
  • Page-Up / Page-Down: Scroll data overview
  • F5: Continue (leave the debugger)
  • F10: Step over / out (places a one-shot break point behind the current instruction)
  • F11: Single step


Keyboard-Mapping-Tool Type in the CLI to control the keybinding process and type in the video window to register a scancode at the selection. The tool will automatically advance the selection to the next entry so you can continuously type in the keys it highlights. Note: The terminal needs to be at least 147 characters wide to correctly display the tool.

  • Escape: Leave the keyboard-mapping-tool
  • Arrows: Navigate / select
  • Backspace: Unregister the selected entry

Supported Software

Currently only the Game of ROBOT episodes 0, 1, 3 and 4 are known to be playable. As host macOS is tested and Ubuntu builds. Windows does not support ANSI escape sequences which are needed by the CLI (inside the termion dependency).


Overview Diagram

There are the following threads (without the ones spawned by dependencies):

  • GUI: Renders the video output and handles the input events of the window
  • Audio: Synthesizes the signal of the sound blaster and beeper
  • CLI: Debugger and actual emulation


In release mode on a 2,6 GHz Intel Core i7 the emulation does 10 to 19 (up to 23 using PGO) million instructions per second. As this is much faster than the original hardware was, the emulation is done in batches with sleeps in between, in order to have a consistent timing behavior and not burn the host CPU unnecessarily. This way about 45% of one host CPU core and 32 MiB of RAM are used. The code base is about 5 KLoC of rust (without lookup tables and bindings). Some threads read data from others using raw pointers which is definitely not the rust way but an easy workaround.


These are the sources I used.





Sound / Audio

Video / Graphics / Mouse

You can’t perform that action at this time.