❤
npm
Sign UpSign In

v86
TypeScript icon, indicating that this package has built-in type declarations

0.4.0 • Public • Published

v86

Bundler-friendly version of the v86 PC Emulator!

Example

Using Vite you can load binaries and wasm files directly!

import { V86Starter } from "v86";
import v86Wasm from "v86/build/v86.wasm";
import bios from "v86/bios/seabios.bin?url";
import vgabios from "v86/bios/vgabios.bin?url";
import cdrom from "./images/linux.iso?url";

new V86Starter({
    wasm_fn: v86Wasm,
    memory_size: 32 * 1024 * 1024,
    vga_memory_size: 2 * 1024 * 1024,
    screen_container: document.getElementById("screen_container"),
    bios: { url: bios },
    vga_bios: { url: vgabios },
    cdrom: { url: cdrom },
    autostart: true,
});
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
  </head>

  <body>
    <div id="screen_container">
      <div
        style="white-space: pre; font: 14px monospace; line-height: 14px"
      ></div>
      <canvas style="display: none"></canvas>
    </div>
    <script src="./index.js" type="module"></script>
  </body>
</html>

Alternative: Base64 binaries

If you want to test the library without specific loaders for wasm and binary files, you can also use the base64 version:

import { V86Starter } from "v86";
import { v86WASM, seabios, vgabios } from 'v86/build/binaries';
import cdrom from "./images/linux.iso?url";

async function main() {
    new V86Starter({
        wasm_fn: async (param) => (await WebAssembly.instantiate(await v86WASM, param)).instance.exports,
        memory_size: 32 * 1024 * 1024,
        vga_memory_size: 2 * 1024 * 1024,
        screen_container: document.getElementById("screen_container"),
        bios: { buffer: await seabios },
        vga_bios: { buffer: await vgabios },
        cdrom: { url: cdrom },
        autostart: true,
    });
}
main();

Original Readme

Join the chat at https://gitter.im/copy/v86 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 III 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

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 up to 16.04 works.
    • 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.0, 95, 98, ME and 2000 work. Other versions currently don't (see #86, #208).
    • In Windows 2000 and higher the PC type has to be changed from ACPI PC to Standard PC
  • 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)

Readme

Keywords

none

Package Sidebar

Install

npm i v86

Repository

github.com/giulioz/v86-module

Homepage

github.com/giulioz/v86-module#readme

Weekly Downloads

23

Version

0.4.0

License

BSD-2-Clause

Unpacked Size

24.9 MB

Total Files

442

Last publish

Collaborators

  • giulioz
Try on RunKit
Report malware