@aptre/v86

This is a fork of copy/v86 with the following enhancements:

• TypeScript migration: JavaScript frontend translated to TypeScript with esbuild + tsgo build tooling. Published as @aptre/v86 on npm with ESM and TypeScript declarations.
• Growable memory: growMemory(bytes) API for dynamically expanding guest RAM at runtime using WebAssembly imported memory.
• virtio-v86fs: Custom virtio filesystem device with a purpose-built binary protocol, DMA-based data transfer, page cache integration, push invalidation, and 256-tag concurrent request support. Enables mounting host directories into the guest with full POSIX semantics (tested with git).
• virtio-mem: Memory hotplug device for guest-initiated memory management.
• State save/restore fixes: last_result register now correctly persisted across state snapshots, fixing intermittent assertion failures after restore.

The virtio-v86fs kernel module and related kernel patches live in the aperturerobotics/linux repository on the v86 branch. The Rust/WASM backend is unchanged from upstream.

or #v86 on irc.libera.chat

v86 emulates an x86-compatible CPU and hardware. Machine code is translated to WebAssembly modules at runtime in order to achieve decent performance. Here's a list of emulated hardware:

• An x86-compatible CPU. The instruction set is around Pentium 4 level, including full SSE3 support. Some features are missing, in particular:
  • Task gates, far calls in protected mode
  • Some 16 bit protected mode features
  • Single stepping (trap flag, debug registers)
  • Some exceptions, especially floating point and SSE
  • Multicore
  • 64-bit extensions
• A floating point unit (FPU). Calculations are done using the Berkeley SoftFloat library and therefore should be precise (but slow). Trigonometric and log functions are emulated using 64-bit floats and may be less precise. Not all FPU exceptions are supported.
• A floppy disk controller (8272A).
• An 8042 Keyboard Controller, PS2. With mouse support.
• An 8254 Programmable Interval Timer (PIT).
• An 8259 Programmable Interrupt Controller (PIC).
• Partial APIC support.
• A CMOS Real Time Clock (RTC).
• A generic VGA card with SVGA support and Bochs VBE Extensions.
• A PCI bus. This one is partly incomplete and not used by every device.
• An IDE disk controller.
  • A built-in ISO 9660 CD-ROM generator.
• An NE2000 (RTL8390) PCI network card.
• Various virtio devices: Filesystem (9p and v86fs), network, balloon, and memory hotplug.
• A SoundBlaster 16 sound card.

Demos

9front — Arch Linux — Android-x86 1.6-r2 — Android-x86 4.4-r2 — BasicLinux — Buildroot Linux — Damn Small Linux — ELKS — FreeDOS — FreeBSD — FiwixOS — Haiku — SkiffOS — ReactOS — Windows 2000 — Windows 98 — Windows 95 — Windows 1.01 — MS-DOS 6.22 — OpenBSD — Oberon — KolibriOS — SkiftOS — QNX

Documentation

How it works — Networking — Alpine Linux guest setup — Arch Linux guest setup — Windows NT guest setup — Windows 9x guest setup — 9p filesystem — Linux rootfs on 9p — Profiling — CPU Idling

Compatibility

Here's an overview of the operating systems supported in v86:

• Linux works pretty well. 64-bit kernels are not supported.
  • Buildroot can be used to build a minimal image. humphd/browser-vm and darin755/browser-buildroot have some useful scripts for building one.
  • SkiffOS (based on Buildroot) can cross-compile a custom image.
  • Ubuntu and other Debian derivatives works up to the latest version that supported i386 (16.04 LTS or 18.04 LTS for some variants).
  • Alpine Linux works. An image can be built from a Dockerfile, see tools/docker/alpine/.
  • Arch Linux 32 works. See archlinux.md for building an image.
• ReactOS works.
• FreeDOS, Windows 1.01 and MS-DOS run very well.
• KolibriOS works.
• Haiku works.
• Android-x86 has been tested up to 4.4-r2.
• Windows 1, 3.x, 95, 98, ME, NT and 2000 work reasonably well.
  • In Windows 2000 and higher the PC type has to be changed from ACPI PC to Standard PC
  • There are some known boot issues (#250, #433, #507, #555, #620, #645)
  • See Windows 9x guest setup
• Windows XP, Vista and 8 work under certain conditions (see #86, #208)
  • See Windows NT guest setup
• Many hobby operating systems work.
• 9front works.
• Plan 9 doesn't work.
• QNX works.
• OS/2 doesn't work.
• FreeBSD works.
• OpenBSD works with a specific boot configuration. At the boot> prompt type boot -c, then at the UKC> prompt disable mpbios and exit.
• NetBSD works only with a custom kernel, see #350.
• SerenityOS works (only 32-bit versions).
• SkiftOS works.

You can get some information on the disk images here: https://github.com/copy/images.

How to build, run and embed?

You need:

• bun (runtime and package manager)
• Rust with the wasm32-unknown-unknown target (for the WASM backend)
• A version of clang compatible with Rust
• To run tests: nasm, gdb, qemu-system, gcc, libc-i386 and rustfmt

bun install        # install dependencies
bun run build      # production build (ESM + browser bundle in dist/)
bun run build:debug # debug build (with DEBUG=true)
bun run typecheck  # type-check with tsgo
bun run lint       # lint with eslint
bun run format     # format with prettier
bun run test       # run tests with vitest

See tools/docker/test-image/Dockerfile for a full setup on Debian or WSL.

The WASM backend is still built with make (Rust toolchain required). Run make for the debug build (debug.html) or make all for the optimized build (index.html). The TypeScript/JavaScript frontend is built with the bun commands above.

ROM and disk images are loaded via XHR, so if you want to try out the HTML files locally, make sure to serve them from a local webserver. You can use make run to serve the files using Python's http module.

If you only want to embed v86 in a webpage, check out the examples. For bundler-based setups, install from npm: bun add @aptre/v86

Alternatively, to build using Docker

• If you have Docker installed, you can run the whole system inside a container.
• See tools/docker/exec to find the Dockerfile required for this.
• You can run docker build -f tools/docker/exec/Dockerfile -t v86:alpine-3.19 . from the root directory to generate docker image.
• Then you can simply run docker run -it -p 8000:8000 v86:alpine-3.19 to start the server.
• Check localhost:8000 for hosted server.

Running via Dev Container

• If you are using an IDE that supports Dev Containers, such as GitHub Codespaces, the Visual Studio Code Remote Container extension, or possibly others such as Jetbrains' IntelliJ IDEA, you can setup the development environment in a Dev Container.
• Follow the instructions from your development environment to setup the container.
• Run the Task "Fetch images" in order to download images for testing.

Testing

The disk images for testing are not included in this repository. You can download them directly from the website using:

curl --compressed --output-dir images/ --remote-name-all https://i.copy.sh/{linux.iso,linux3.iso,linux4.iso,buildroot-bzimage68.bin,TinyCore-11.0.iso,oberon.img,msdos.img,openbsd-floppy.img,kolibri.img,windows101.img,os8.img,freedos722.img,mobius-fd-release5.img,msdos622.img}

Run integration tests: make tests

Run all tests: make jshint rustfmt kvm-unit-test nasmtests nasmtests-force-jit expect-tests jitpagingtests qemutests rust-test tests

See tests/Readme.md for more information.

API examples

• Basic
• Programatically using the serial terminal
• A Lua interpreter
• Two instances in one window
• Networking between browser windows/tabs using the Broadcast Channel API
• TCP Terminal (fetch-based networking)
• Saving and restoring emulator state

Using v86 for your own purposes is as easy as:

var emulator = new V86({
    screen_container: document.getElementById("screen_container"),
    bios: {
        url: "../../bios/seabios.bin",
    },
    vga_bios: {
        url: "../../bios/vgabios.bin",
    },
    cdrom: {
        url: "../../images/linux.iso",
    },
    autostart: true,
});

See starter.ts for the full API.

License

v86 is distributed under the terms of the Simplified BSD License, see LICENSE. The following third-party dependencies are included in the repository under their own licenses:

• lib/softfloat/softfloat.c
• lib/zstd/zstddeclib.c
• tests/kvm-unit-tests/
• tests/qemutests/
• src/floppy.js/ contains parts ported from qemu under the MIT license, see LICENSE.MIT.

Credits

• CPU test cases via QEMU
• More tests via kvm-unit-tests
• zstd support is included for better compression of state images
• Berkeley SoftFloat is included to precisely emulate 80-bit floating point numbers
• The jor1k project for 9p, filesystem and uart drivers
• WinWorld sources of some old operating systems
• OS/2 Museum sources of some old operating systems
• ArchiveOS sources of several operating systems

More questions?

Shoot me an email to [email protected]. Please report bugs on GitHub.