x86 virtualization in JavaScript, running in your browser and NodeJS (mirror)

Joey Mezzacappa 2bcfa9d8c4 Virtio console: Send bytes to the right queues 2 weeks ago
.cargo 853bf477cc minor fixes 3 years ago
.devcontainer dc8667f23b Feature: Add development environment setup (#970) 2 months ago
.github fe7a0fbd0f Publish artifacts 3 months ago
.vscode dc8667f23b Feature: Add development environment setup (#970) 2 months ago
bios b8a39b11dd Update SeaBIOS to 1.16.2 (#890) 7 months ago
docs a8cc97d838 Improve documentation some more (#955) 3 months ago
examples 4928c9165d (breaking change) replace *-output-char with *-output-byte (#928) 6 months ago
gen 611cb611c1 correct undefined flags for bsf/bsr 3 months ago
lib b96665285b Allow sharing files with guest using UI, even with custom profile (#702) 1 year ago
src 2bcfa9d8c4 Virtio console: Send bytes to the right queues 1 week ago
tests df0d136208 add NetBSD multiboot and crazierl tests 2 months ago
tools 2f24859bce added dockerfile and changed build-container.sh 2 weeks ago
.editorconfig 0766da0fa0 Only use vga color linked list for small changes 6 years ago
.gitattributes 741e09569a Add .gitattributes 3 years ago
.gitignore 497f618cab Merge branch 'wasm' into master 3 years ago
.jshint.json d5c9b29942 Upgrade jshint 3 years ago
.rustfmt.toml 75dbbbc55a Update rustfmt 3 years ago
Cargo.toml 95d35d1b21 enable wasm multivalue 5 months ago
LICENSE fe74b8d332 Fix license 3 years ago
Makefile 609d79454d add test for virtio_console 2 months ago
Readme.md 21cf9ad75c Update Dockerfile for building (#988) 1 month ago
debug.html 7660cbfb64 Implement Virtio Console device. (#949) 2 months ago
index.html 95614967d1 make icons smaller 5 months ago
v86.css d8c0acb57a Fullscreen centering 3 months ago

Readme.md

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.
  • An NE2000 (RTL8390) PCI network card.
  • A VirtIO filesystem.
  • A SoundBlaster 16 sound card.

Demos

9frontArch LinuxAndroid-x86 1.6-r2Android-x86 4.4-r2BasicLinuxBuildroot LinuxDamn Small LinuxELKSFreeDOSFreeBSDFiwixOSHaikuSkiffOSReactOSWindows 2000Windows 98Windows 95Windows 1.01MS-DOS 6.22OpenBSDOberonKolibriOSSkiftOSQNX

Documentation

How it worksNetworkingArch Linux guest setupWindows 2000/XP guest setup9p filesystemLinux rootfs on 9pProfilingCPU Idling

Compatibility

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

  • Linux works pretty well. 64-bit kernels are not supported.
    • Damn Small Linux (2.4.31 kernel) works.
    • Fedora 30 works.
    • All tested versions of TinyCore work.
    • 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.
    • Archlinux works. See archlinux.md for building an image.
    • Debian works. An image can be built from a Dockerfile, see tools/docker/debian/.
    • Ubuntu works up to the latest version that supported i386 (16.04 LTS or 18.04 LTS for some variants).
    • Alpine Linux works.
  • 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)
  • Windows XP, Vista and 8 work under certain conditions (see #86, #208)
  • 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.
  • 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:

  • make
  • Rust with the wasm32-unknown-unknown target
  • A version of clang compatible with Rust
  • java (for Closure Compiler, not necessary when using debug.html)
  • nodejs (a recent version is required, v16.11.1 is known to be working)
  • To run tests: nasm, gdb, qemu-system, gcc, libc-i386 and rustfmt

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

  • Run make to build the debug build (at debug.html).
  • Run make all to build the optimized build (at index.html).
  • ROM and disk images are loaded via XHR, so if you want to try out index.html locally, make sure to serve it 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 you can use libv86.js. For usage, check out the examples. You can download it from the release section.

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 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 Devcontainer

  • If you are using an IDE that supports Devcontainers, such as Github Codespaces, VSCode Remote Container extension, or possibly others such as Jetbrains 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:

wget -P images/ https://k.copy.sh/{linux3.iso,linux.iso,linux4.iso,buildroot-bzimage.bin,openbsd-floppy.img,kolibri.img,windows101.img,os8.img,freedos722.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

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

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:

Credits

More questions?

Shoot me an email to copy@copy.sh. Please report bugs on GitHub.

Author

Fabian Hemmer (https://copy.sh/, copy@copy.sh)