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 SSE2 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 (8390) PCI network card.
- A virtio filesystem.
- A SoundBlaster 16 sound card.
Demos
Arch Linux —
Damn Small Linux —
Buildroot Linux —
ReactOS —
Windows 2000 —
Windows 98 —
Windows 95 —
Windows 1.01 —
MS-DOS —
FreeDOS —
FreeBSD —
OpenBSD —
9front —
Haiku —
Oberon —
KolibriOS —
QNX —
Android 1.6-r2 —
Android 4.4 —
SkiftOS
Docs
How it works —
Networking —
Archlinux guest setup —
Windows 2000/XP guest setup —
9p filesystem —
Linux rootfs on 9p —
Profiling
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 Kernel) 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 1.6-r2 works if one selects VESA mode at the boot prompt. Newer
versions may work if compiled without SSE3. See #224.
- 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.
You can get some infos 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.14 .
from the root directory to generate docker image.
- Then you can simply run
docker run -it -p 8000:8000 v86:alpine-3.14
to start the server.
- Check
localhost:8000
for hosted server.
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/{linux.iso,linux4.iso,buildroot-bzimage.bin,openbsd-floppy.img,kolibri.img,windows101.img,os8.img,freedos722.img}
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 infos.
API examples
Using v86 for your own purposes is as easy as:
var emulator = new V86Starter({
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
)