DOS-Emulator

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 https://github.com/Lichtso/DOS-Emulator
cd DOS-Emulator
cargo build --release

Download and unpack the guest application and start the emulator.

curl -GOL https://cors.archive.org/cors/msdos_Robot_Junior_1991/Robot_Junior_1991.zip
mkdir -p DOS/TOM/ROBJUN
unzip -j Robot_Junior_1991.zip RobotJun/ROBJUN.EXE RobotJun/ROBJUN.MUC RobotJun/ROBJUN.SCN RobotJun/ITEMJE.CRN RobotJun/ITEMJG.CRN RobotJun/SASJ.CRN -d DOS/TOM/ROBJUN/
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

Debugger

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).

Architecture

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

Evaluation

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.

References

These are the sources I used.

ISA / CPU

• http://mlsite.net/8086/
• http://www.mlsite.net/8086/8086_table.txt
• http://shell-storm.org/online/Online-Assembler-and-Disassembler/
• https://www.felixcloutier.com/x86/index.html
• https://en.wikipedia.org/wiki/Intel_8086
• https://en.wikipedia.org/wiki/X86_instruction_listings
• https://en.wikibooks.org/wiki/X86_Assembly/Machine_Language_Conversion
• https://en.wikipedia.org/wiki/Intel_BCD_opcode
• https://en.wikipedia.org/wiki/Half-carry_flag
• http://teaching.idallen.com/dat2343/10f/notes/040_overflow.txt

BUS

• http://www.ctyme.com/intr/int.htm
• http://bochs.sourceforge.net/techspec/PORTS.LST
• https://wiki.osdev.org/I/O_Ports
• https://wiki.osdev.org/IRQ
• http://staff.ustc.edu.cn/~xyfeng/research/cos/resources/machine/mem.htm

BIOS

• https://en.wikipedia.org/wiki/BIOS_interrupt_call
• http://staff.ustc.edu.cn/~xyfeng/research/cos/resources/BIOS/Resources/biosdata.htm
• http://flint.cs.yale.edu/cs422/doc/art-of-asm/pdf/CH13.PDF

DOS

• https://www.pcjs.org/pubs/pc/reference/microsoft/mspl13/msdos/
• http://bytepointer.com/resources/dos_programmers_ref_exe_format.htm
• http://tuttlem.github.io/2015/03/28/mz-exe-files.html
• http://www.piclist.com/techref/dos/pss.htm
• http://www.piclist.com/techref/dos/psps.htm
• https://en.wikipedia.org/wiki/File_Control_Block
• https://en.wikipedia.org/wiki/Program_Segment_Prefix
• https://en.wikipedia.org/wiki/Job_File_Table

Sound / Audio

• https://shipbrook.net/jeff/sb.html
• https://pdf1.alldatasheet.com/datasheet-pdf/view/103368/ETC/YMF262.html

Video / Graphics / Mouse

• http://www.osdever.net/FreeVGA/vga/vga.htm
• http://www.brackeen.com/vga/