## File: Readme.md

[](https://gitter.im/copy/v86) or #v86 on [irc.libera.chat](https://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, network and balloon.
- A SoundBlaster 16 sound card.
- A hayes-compatible dial-up Modem.

## Demos

[9front](https://copy.sh/v86/?profile=9front) —
[Arch Linux](https://copy.sh/v86/?profile=archlinux) —
[Android-x86 1.6-r2](https://copy.sh/v86?profile=android) —
[Android-x86 4.4-r2](https://copy.sh/v86?profile=android4) —
[BasicLinux](https://copy.sh/v86/?profile=basiclinux) —
[Buildroot Linux](https://copy.sh/v86/?profile=buildroot) —
[Damn Small Linux](https://copy.sh/v86/?profile=dsl) —
[ELKS](https://copy.sh/v86/?profile=elks) —
[FreeDOS](https://copy.sh/v86/?profile=freedos) —
[FreeBSD](https://copy.sh/v86/?profile=freebsd) —
[FiwixOS](https://copy.sh/v86/?profile=fiwix) —
[Haiku](https://copy.sh/v86/?profile=haiku) —
[SkiffOS](https://copy.sh/v86/?profile=copy/skiffos) —
[ReactOS](https://copy.sh/v86/?profile=reactos) —
[Windows 2000](https://copy.sh/v86/?profile=windows2000) —
[Windows 98](https://copy.sh/v86/?profile=windows98) —
[Windows 95](https://copy.sh/v86/?profile=windows95) —
[Windows 1.01](https://copy.sh/v86/?profile=windows1) —
[MS-DOS 6.22](https://copy.sh/v86/?profile=msdos) —
[OpenBSD](https://copy.sh/v86/?profile=openbsd) —
[Oberon](https://copy.sh/v86/?profile=oberon) —
[KolibriOS](https://copy.sh/v86/?profile=kolibrios) —
[SkiftOS](https://copy.sh/v86?profile=skift) —
[QNX](https://copy.sh/v86/?profile=qnx)

## Documentation

[How it works](docs/how-it-works.md) —
[Networking](docs/networking.md) —
[Dial-up modem networking](docs/modem.md) —
[Alpine Linux guest setup](tools/docker/alpine/) —
[Arch Linux guest setup](docs/archlinux.md) —
[MS-DOS/FreeDOS guest setup](docs/dos.md) —
[Windows 3.1x guest setup](docs/windows-31x.md) —
[Windows 9x guest setup](docs/windows-9x.md) —
[Windows NT guest setup](docs/windows-nt.md) —
[9p filesystem](docs/filesystem.md) —
[Linux rootfs on 9p](docs/linux-9p-image.md) —
[Profiling](docs/profiling.md) —
[CPU Idling](docs/cpu-idling.md)

## Compatibility

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

- Linux works pretty well. 64-bit kernels are not supported.
  - [Buildroot](https://buildroot.org/) can be used to build a minimal image.
    [humphd/browser-vm](https://github.com/humphd/browser-vm) and
    [darin755/browser-buildroot](https://github.com/Darin755/browser-buildroot) have some useful scripts for building one.
  - [SkiffOS](https://github.com/skiffos/SkiffOS/tree/master/configs/browser/v86) (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/](tools/docker/alpine/).
  - Arch Linux 32 works. See [archlinux.md](docs/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](https://github.com/copy/v86/issues/250), [#433](https://github.com/copy/v86/issues/433), [#507](https://github.com/copy/v86/issues/507), [#555](https://github.com/copy/v86/issues/555), [#620](https://github.com/copy/v86/issues/620), [#645](https://github.com/copy/v86/issues/645))
  - See [Windows 9x guest setup](docs/windows-9x.md)
- Windows XP, Vista and 8 work under certain conditions (see [#86](https://github.com/copy/v86/issues/86), [#208](https://github.com/copy/v86/issues/208))
  - See [Windows NT guest setup](docs/windows-nt.md)
- 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](https://github.com/copy/v86/issues/350).
- SerenityOS works (only 32-bit versions).
- [SkiftOS](https://skiftos.org/) 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, v24.16 is known to be working)
- To run tests: nasm, gdb, qemu-system, gcc, libc-i386 and rustfmt

See [tools/docker/test-image/Dockerfile](tools/docker/test-image/Dockerfile)
for a full setup on Debian or
[WSL](https://docs.microsoft.com/en-us/windows/wsl/install).

- 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](examples/). You can download it from the [release section](https://github.com/copy/v86/releases).
- For bundler-based setups (Vite/React/Next/Webpack), there is also an official npm package:
https://www.npmjs.com/package/v86

  This package was originally maintained by [@giulioz](https://github.com/giulioz) (bundler-optimized fork) and was made "official" for this repo by [@basicer](https://github.com/basicer) with the author's permission.
  It is published automatically from this repository via GitHub Actions ([.github/workflows/ci.yml](.github/workflows/ci.yml), Upload release job) on pushes to `master` and uses `npm publish --provenance`.

  Install: `npm install 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](tests/Readme.md) for more information.

## API examples

- [Basic](examples/basic.html)
- [Programatically using the serial terminal](examples/serial.html)
- [A Lua interpreter](examples/lua.html)
- [Two instances in one window](examples/two_instances.html)
- [Networking between browser windows/tabs using the Broadcast Channel API](examples/broadcast-network.html)
- [TCP Terminal (fetch-based networking)](examples/tcp_terminal.html)
- [Saving and restoring emulator state](examples/save_restore.html)

Using v86 for your own purposes is as easy as:

```javascript
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 [v86.d.ts](v86.d.ts) for TypeScript definitions. You can use `make doc` (TypeDoc) or `make denodoc` (Deno) to generate HTML documentation in `./docs/api/`.

## Generative AI

At this time, v86 does not accept pull requests or issues written partially or entirely by generative AI tools.
Exceptions may be made on a case-by-case basis.

## License

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

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

## Credits

- CPU test cases via [QEMU](https://wiki.qemu.org/Main_Page)
- More tests via [kvm-unit-tests](https://www.linux-kvm.org/page/KVM-unit-tests)
- [zstd](https://github.com/facebook/zstd) support is included for better compression of state images
- [Berkeley SoftFloat](http://www.jhauser.us/arithmetic/SoftFloat.html) is included to precisely emulate 80-bit floating point numbers
- [The jor1k project](https://github.com/s-macke/jor1k) for 9p, filesystem and uart drivers
- [WinWorld](https://winworldpc.com/) sources of some old operating systems
- [OS/2 Museum](https://www.os2museum.com/) sources of some old operating systems
- [ArchiveOS](https://archiveos.org/) sources of several operating systems

## More questions?

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

---

## File: docs/archlinux.md

See [Alpine setup](../tools/docker/alpine/Readme.md) for a more reliable and
faster way to automatically build Linux images for v86.

(This document partly also applies to other Linuxes)

Choosing an installer ISO
-------------------------

Download Arch Linux 32 from  https://archlinux32.org.

Basic installation using QEMU
-----------------------

Installing Arch Linux with these instructions will result in a raw disk image that can be booted by v86.

```sh
# fetch archlinux32 installer
wget https://mirror.archlinux32.org/archisos/archlinux32-2021.12.01-i686.iso

# Create a 10 gigabyte disk image. If you intend to pacstrap only 'base' then 1.5G should be fine also.
qemu-img create arch.img 10G

# Follow the normal installation process (you can add accel=kvm if your system supports it to speed up the installation)
qemu-system-x86_64 -m 256 -drive file=arch.img,format=raw -cdrom archlinux32-2021.12.01-i686.iso
```

For keyboard support, it is necessary to open /etc/mkinitcpio.conf and edit the following line:

```sh
MODULES="atkbd i8042"
```

For the changes to take effect, you need to regenerate the initial ramdisk with `mkinitcpio -p linux`

The resulting `arch.img` file is a bootable disk image for v86.

Scripting image creation for v86
--------------------------------

Installing the ISO by hand takes a long time if you intend to recreate the image many times. There are various reasons why you might want to do this more than once. For example: because the emulator is slow you might want to compile any new software release in QEMU which is much faster and then use the resulting image in v86 instead of making the emulator compile the software. Another reason is that the build progress potentially takes long and if you want to do automated builds in parallel to find out what configurations do and don't work you can just throw more computing power at the problem in order to solve it. This example requires that you have `packer`, `qemu` and `kpartx` installed.

### Creating a packer template

[Packer](https://www.packer.io/docs/builders/qemu.html) is a tool that lets you boot an ISO in any of multiple emulators (so QEMU in our case) and send pre-scripted keystrokes to bootstrap an SSH server. Once the SSH connection is established a script can be started for further provisioning.

Create a template for automating the base installation:
```sh
mkdir -p packer
cat > packer/template.json << 'EOF'
{
  "provisioners": [
    {
      "type": "shell",
      "override": {
        "qemu": {
          "scripts": ["scripts/provision.sh"]
        }
      }
    }
  ],
  "builders": [
    {
      "accelerator": "kvm",
      "type": "qemu",
      "boot_command": [
        "<enter><wait30><enteropenssl passwd help<wait10>",
        "dhcpcd<enter><wait5>",
        "echo root:root | chpasswd<enter><wait5>",
        "systemctl start sshd<enter>"
      ],
      "headless": true,
      "boot_wait": "10s",
      "disk_size": 1500,
      "disk_interface": "ide",
      "iso_url": "https://mirror.archlinux32.org/archisos/archlinux32-2021.12.01-i686.iso",
      "iso_checksum": "90c6f5aecb095d5578f6c9970539da7c5e9324ec",
      "iso_checksum_type": "sha1",
      "ssh_wait_timeout": "120s",
      "ssh_pty": true,
      "ssh_username": "root",
      "ssh_password": "root",
      "ssh_port": 22,
      "format": "raw",
      "vm_name": "archlinux",
      "disk_detect_zeroes": "unmap",
      "memory": 2048,
      "vnc_bind_address": "0.0.0.0"
    }
  ]
}
EOF
```

You can tweak the options a bit to match your situation. For debugging, you can set `headless` to `false`. That will show you the VNC connection instead of running the `boot_command` in the background. For a `base` pacstrap, using a 2 GB disk image should be sufficient. The `raw` disk format is important. v86 does not read qcow2 images, only raw disk images. If your system does not support KVM (the default accelerator), you can change `"accelerator": "none"` to the settings, in macos you may use `"accelerator": "hvf"`. Other accelerator options can be found [here](https://www.packer.io/docs/builders/qemu.html#accelerator).

After gaining SSH connectivity to the VM, packer will run the `scripts/provisioning.sh` script in the guest.

### Creating the Arch Linux installation script

Create a script for your Arch Linux installation. This runs in the live Arch Linux environment, so you need to partition the disk, do a pacstrap, and install a bootloader.
```sh
mkdir -p packer/scripts
### Write your own or copy paste the example below
vim packer/scripts/provision.sh
```

An example script to install Arch Linux with the root mounted using the 9p network filesystem:
```
/* Detailed source-code truncated for AI context efficiency. */
```

With the packer template and the script you have enough to create an image that can be booted by v86. But because this example script installs an Arch Linux that wants to mount root over the network with 9p, we need to host that filesystem first. If you do not want to use 9p, you can just run `(cd packer && packer build -force template.json)` to build the image.

### Creating the 9p filesystem

Now that we have an image that contains a filesystem, we can convert that filesystem into something we can host on the webserver together with the v86 library.

To do so, we need to mount the image once and create a json mapping of the filesystem. The following script shows how to map the filesystem in an automated fashion.

Create a script to builds the image and then creates v86 compatible artifacts:
```sh
vim build.sh
```

Example script:

```sh
#!/bin/sh

SRC=packer
TARGET=output

# build the boxfile from the iso
(cd $SRC && sudo PACKER_LOG=1 PACKER_LOG_PATH="./packer.log" packer build -force template.json)

# test if there is a boxfile where we expected it
if [ ! -f $SRC/output-qemu/archlinux ]; then
    echo "Looks like something went wrong building the image, maybe try again?"
    exit 1
fi;

# clean up any previous loops and mounts
echo "Making sure mountpoint is empty"
LOOP_DEV=$(sudo losetup -f)

sudo umount diskmount -f || /bin/true
sudo kpartx -d $LOOP_DEV || /bin/true
sudo losetup -d $LOOP_DEV || /bin/true

# mount the generated raw image, we do that so we can create
# a json mapping of it and copy it to host on the webserver
mkdir -p diskmount
echo "Mounting the created image so we can convert it to a p9 image"
sudo losetup $LOOP_DEV $SRC/output-qemu/archlinux
sudo kpartx -a $LOOP_DEV
sudo mount /dev/mapper/$(basename $LOOP_DEV)p1 diskmount

# make images dir
mkdir -p $TARGET
mkdir -p $TARGET/images
mkdir -p $TARGET/images/arch

# map the filesystem to json with fs2json
sudo ./tools/fs2json.py --out $TARGET/images/fs.json diskmount
sudo ./tools/copy-to-sha256.py diskmount $TARGET/images/arch

# copy the filesystem and chown to nonroot user
echo "Copying the filesystem to $TARGET/arch"
mkdir $TARGET/arch -p
sudo rsync -q -av diskmount/ $TARGET/arch
sudo chown -R $(whoami):$(whoami) $TARGET/arch

# clean up mount
echo "Cleaning up mounts"
sudo umount diskmount -f
sudo kpartx -d $LOOP_DEV
sudo losetup -d $LOOP_DEV

# Move the image to the images dir
sudo mv $SRC/output-qemu/archlinux $TARGET/images/arch.img
```

Given that the packer template and provision.sh is rooted at `packer` (adjust the value of `$SRC` otherwise), run the `build.sh` at root of your `v86` repo:

```
chmod +x build.sh
./build.sh
```

Generated artifacts are now available for serving from `output`.

### Using the created artifacts in v86

Now that we have everything we need to host a server that serves an Arch Linux environment over the network.

Create a checkout of v86 and run `make build/libv86.js`.
We can then edit `examples/arch.html`, we have two options:

1. Boot Arch Linux from the 9p filesystem (generated .bin artifacts at `/output/images/arch`):

  ```sh
  filesystem: {
    baseurl: "../output/images/arch/",
    basefs: "../output/images/fs.json",
  },

  bzimage_initrd_from_filesystem: true,

  cmdline: [
    "rw",
    "root=host9p rootfstype=9p rootflags=trans=virtio,cache=loose",
  ].join(" "),

  acpi: false,
  autostart: true,
  ```
2. Boot the Arch Linux from the qemu raw disk image:

  ```sh
  hda: {
      url: "../output/images/arch.img",
      # set to true if you want to load it asynchrously during runtime (for this option we need to run a webserver that supports the Range header)
      # NOTE: async: false is slow but proved to be more realiable
      async: false,

      # This needs to be the size of the raw disk.
      size: 1.5 * 1024 * 1024 * 1024,
      # See the `disk_size` item in the packer template.
  },

  acpi: false,
  autostart: true,
  ```

Next, we need a webserver that supports the Range header. For example [this extension of the SimpleHTTPServer](https://github.com/smgoller/rangehttpserver). At your `v86` root, run:

```sh
wget https://raw.githubusercontent.com/smgoller/rangehttpserver/master/RangeHTTPServer.py
python2 RangeHTTPServer.py
```

Now that the webserver is running, point your browser to `http://localhost:8000/examples/arch.html`. Wait for the Linux to boot. When the system is up, click 'Save state to file'. Your browser will download a `v86state.bin` file. Copy that file to `/your/v86/dir/images`. You can then edit `examples/arch.html` again and add a 'state' key to the `V86` array.

```sh
initial_state: {
    "url": "http://localhost:8000/images/v86state.bin",
},
```

If you refresh `http://localhost:8000/examples/arch.html` you will see that the state is restored instantly and all required files are loaded over the network on the fly.

### Networking

The emulator can emulate a network card. For more information [look at the networking documentation](https://github.com/copy/v86/blob/master/docs/networking.md). To set up networking in the VM, add the following item to the `V86` array in the `examples/arch.html` file:
```sh
network_relay_url: "ws://localhost:8080/",
```

This will make the emulator try to connect to a [WebSockets proxy](https://github.com/benjamincburns/websockproxy). Running the proxy is very easy if you use the Docker container.

```sh
sudo docker run --privileged -p 8080:80 --name relay bennottelling/websockproxy
```
**NOTE:** original `benjamincburns/jor1k-relay:latest` has throttling built-in by default which will degrade the networking. `bennottelling/websockproxy` has this throttling removed via [websockproxy/issues/4#issuecomment-317255890](https://github.com/benjamincburns/websockproxy/issues/4#issuecomment-317255890).

You can check if the relay is running correctly by going to `http://localhost:8080/` in your browser. There you should see a message that reads `Can "Upgrade" only to "Websocket".`.

Now you should be able to get network connectivity in the virtual machine. If you are restoring from a saved state, you might need to first run:
```sh
ip link set enp0s5 down
rmmod ne2k-pci
```

To bring the network up, run:
```sh
modprobe ne2k-pci
dhcpcd -w4 enp0s5
```

It might take a while for a carrier to become available on the interface. If the `dhcpcd` command fails shortly after booting, wait a bit and try again a bit later. If you are using the 9p network filesystem you can use the developer tools networking tab (in chrome) to get a sense of what is going on by looking at the files that are being downloaded.

When the network is up you should be able to curl a website. To check, run `curl icanhazip.com`. There you should see the public IP of the machine running the proxy.

You can't do inbound traffic into the VM with the websockproxy Docker container because it uses a basic NAT. To SSH into the VM running in the browser, you can create a reverse SSH tunnel to expose the SSH port of the sshd in the VM to the outside world. You may need to start `sshd` first, it may also be reasonable to change root password:

```sh
passwd root
systemctl start sshd
```

then create a reverse SSH tunnel:

```sh
# This will create a port 1122 on the example.com server
# which forwards to the SSH in the VM
ssh root@example.com -R 1122:localhost:22
```

Now on the `example.com` server you should be able to SSH into your browser tab by running `ssh root@localhost -p 1122`.

---

## File: docs/cpu-idling.md

Some operating systems don't support `hlt` instruction, because of this, the CPU spin loops instead of idling.
Here are some solutions for different OSes:

## MS-DOS (using DOSIdle)
1. Download `DOSID251.zip` from https://www.vogons.org/viewtopic.php?p=438763#p438763
2. Unzip DOSIDLE.EXE from archive in any location (recommended to root of C:).
3. Run `edit C:\autoexec.bat`
4. Add to file: `C:\path\to\dosidle.exe`
5. Save changes (*press Alt + F and x*) and restart the VM.

**Note:** To hide output when starting DOSIdle, change `C:\path\to\dosidle.exe` to `C:\path\to\dosidle.exe > nul` on step №4.

## FreeDOS ([source](https://narkive.com/UGrcO8wU.2))
1. Run `edit C:\fdconfig.sys` (or `edit C:\config.sys`)
2. Add to file: `IDLEHALT=1`
3. Save changes (*press Alt + F and x*) and restart FreeDOS.

## Windows 9x (using AmnHLT)
1. Download `amnhltm.zip` from http://toogam.com/software/archive/drivers/cpu/cpuidle/amnhltm.zip ([mirror](https://web.archive.org/web/20060212132151/http://www.user.cityline.ru/~maxamn/amnhltm.zip))
2. Unzip the archive in any location.
3. **Note**: If you have installed VBE9x, restart Windows, press F8 on boot, select *Command prompt only*, run `cd C:\path\to\amnhlt\`, and follow to the next step.
4. Run `AMNHLT.BAT`
5. Restart Windows, and AmnHLT will start automatically on next boot (you can safely delete archive and unpacked folder).

## Windows 98+ and Unix-like
These systems are already supports `hlt`, no further action is required.

---

## File: docs/filesystem.md

A 9p filesystem is supported by v86, using a virtio transport. There are several
ways it can be set up.

### Guest mount

In all cases, the filesystem is mounted in the guest system using the `9p`
filesystem type and the `host9p` device tag. Typically you want to be specific
with the version and transport options:

```sh
mount -t 9p -o trans=virtio,version=9p2000.L host9p /mnt/9p/
```

Here are kernel arguments you can use to boot directly off the 9p filesystem:

```
rw root=host9p rootfstype=9p rootflags=trans=virtio,version=9p2000.L
```

The `aname` option can be used to pick the directory from 9p to mount. The `rw`
argument makes this a read-write root filesystem.


### JSON/HTTP Filesystem

This is the standard way to setup the 9p filesystem. It loads files over
HTTP on-demand into an in-memory filesystem in JS. This allows files to be
exchanged with the guest OS. See `create_file` and `read_file` in
[`starter.js`](https://github.com/copy/v86/blob/master/src/browser/starter.js).

This mode is enabled by passing the following options to `V86`:

```javascript
filesystem: {
    basefs: "../9p/fs.json",
    baseurl: "../9p/base/",
}
```

Here, `basefs` is a json file created using
[fs2json.py](tools/fs2json.py) and the `baseurl` directory is created using
[copy-to-sha256.py](tools/copy-to-sha256.py).

If `basefs` and `baseurl` are omitted, an empty 9p filesystem is created. Unless
you configure one of the alternative modes.


### Function Handler

You can handle 9p messages directly in JavaScript yourself by providing a
function as `handle9p` under `filesystem`:

```javascript
filesystem: {
    handle9p: async (reqBuf, reply) => {
        // reqBuf is a Uint8Array of the entire request frame.
        // you can parse these bytes using a library or reading the 9p spec.
        // once you formulate a response, you send the reply frame as a
        // Uint8Array by passing it to reply: reply(respBuf)
    }
}
```

This allows you to implement a 9p server or custom proxy in JS. However, this
filesystem will not be cached (unless cached in the guest OS), functions like
`create_file` and `read_file` will not be available, and you will be responsible
for keeping its state in sync with any machine save states.


### WebSocket Proxy

You can also back the 9p virtio filesystem with a 9p server over WebSocket by
providing a WS proxy URL:

```javascript
filesystem: {
    proxy_url: "ws://localhost:8080/"
}
```

Simlar to using `handle9p`, this filesystem will not be available in JS and
will need to be re-mounted after restoring state.

The WS proxy just needs to hand off messages with a connection to a normal 9p
server. Each binary WebSocket message is the full buffer of a request or a
reply.

To implement, request message bytes can just be sent directly to the 9p
connection, but the 9p reply stream needs to be buffered into a single binary
WebSocket message. The proxy must at least parse the first 4 bytes to get the
message size and use it to buffer a full message before sending over WebSocket.

The [wanix](https://github.com/tractordev/wanix) CLI has a `serve` command that
not only serves a directory over HTTP, but also over 9P via WebSocket. You can
see how it [implements a proxy][1] in Go.

[1]: https://github.com/tractordev/wanix/blob/main/cmd/wanix/serve.go#L117-L177

---

## File: docs/how-it-works.md

Here's an overview of v86's workings. For details, check the
[source](https://github.com/copy/v86/tree/master/src).

The major limitations of WebAssembly are (for the purpose of making emulators with jit):

- structured control flow (no arbitrary jumps)
- no control over registers (you can't keep hardware registers in wasm locals across functions)
- no mmap (paging needs to be fully emulated)
- no patching
- module generation is fairly slow, but at least it's asynchronous, so other things can keep running
- there is some memory overhead per module, so you can't generate more than a few thousand

v86 has an interpreted mode, which collects entry points (targets of function
calls and indirect jumps). It also measures the hotness per page, so that
compilation is focused on code that is often executed. Once a page is
considered hot, code is generated for the entire page and up to `MAX_PAGES`
that are directly reachable from it.

v86 generates a single function with a big switch statement (brtable), to
ensure that all functions and targets of indirect jumps are reachable from
other modules. The remaining control flow is handled using the "stackifier"
algorithm (well-explained in
[this blog post](https://medium.com/leaningtech/solving-the-structured-control-flow-problem-once-and-for-all-5123117b1ee2)).
At the moment, there is no linking of wasm modules. The current module is
exited, and the main loop detects if a new module can be entered.

In practice, I found that browsers don't handle this structure (deep brtables,
with locals being used across the entire function) very well, and `MAX_PAGES`
has to be set to fairly low, otherwise memory usage blows up. It's likely that
improvements are possible (generating fewer entry points, splitting code across
multiple functions).

Code-generation happens in two passes. The first pass finds all basic block
boundaries, the second generates code for each basic block. Instruction
decoding is generated by a [set of
scripts](https://github.com/copy/v86/tree/master/gen) from a [table of
instructions](https://github.com/copy/v86/blob/master/gen/x86_table.js). It's
also used to [generate
tests](https://github.com/copy/v86/blob/master/tests/nasm/create_tests.js).

To handle paging, v86 generates code similar to this (see `gen_safe_read`):

```
entry <- tlb[addr >> 12 << 2]
if entry & MASK == TLB_VALID && (addr & 0xFFF) <= 0xFFC - bytes: goto fast
entry <- safe_read_jit_slow(addr, instruction_pointer)
if page_fault: goto exit-with-pagefault
fast: mem[(entry & ~0xFFF) ^ addr]
```

There is a 4 MB cache that acts like a tlb. It contains the physical address,
read-only bit, whether the page contains code (in order to invalidate it on
write) and whether the page points to mmio. Any of those cases are handled in
the slow path (`safe_read_jit_slow`), as well as walking the page tables and
triggering page faults. The fast path is taken in the vast majority of times.

The remaining code generation is mostly a straight-forward, 1-to-1 translation
of x86 to wasm. The only analysis done is to optimise generation of condional
jumps immediately after arithmetic instructions, e.g.:

```
cmp eax, 52
setb eax
```

becomes:

```
... // code for cmp
eax <- eax < 52
```

A lazy flag mechanism is used to speed arithmetic (applies to both jit and
interpreted mode, see
[`arith.rs`](https://github.com/copy/v86/blob/master/src/rust/cpu/arith.rs) and
[`misc_instr.rs`](https://github.com/copy/v86/blob/master/src/rust/cpu/misc_instr.rs)).
There's a wip that tries to elide most lazy-flags updates:
https://github.com/copy/v86/pull/466

FPU instructions are emulated using softfloat (very slow, but unfortunately
some code relies on 80 bit floats).

---

## File: docs/linux-9p-image.md

In order to create a Linux image that can mount the 9p file system, add the following lines to the kernel configuration:

```
CONFIG_NET_9P=y
CONFIG_NET_9P_VIRTIO=y
CONFIG_NET_9P_DEBUG=y
CONFIG_VIRTIO=y
CONFIG_VIRTIO_PCI=y
CONFIG_9P_FS=y
CONFIG_9P_FSCACHE=y
CONFIG_9P_FS_POSIX_ACL=y
```

A Dockerfile for this build is here: https://github.com/ysangkok/build-v86-9p-linux

Using initcpio
--------------

This allows you to remount the root file system using 9p. No changes are necessary if you only want to mount a 9p filesystem after booting.

Add the following files:

`/etc/initcpio/hooks/9p_root`

```bash
#!/usr/bin/bash

run_hook() {
    mount_handler="mount_9p_root"
}

mount_9p_root() {
    msg ":: mounting '$root' on real root (9p)"
    if ! mount -t 9p host9p "$1"; then
        echo "You are now being dropped into an emergency shell."
        launch_interactive_shell
        msg "Trying to continue (this will most likely fail) ..."
    fi
}
```

<hr>

`/etc/initcpio/install/9p_root`

```bash
#!/bin/bash
build() {
	add_runscript
}
```

Change the following options in `/etc/mkinitcpio.conf`:

```bash
MODULES="virtio_pci 9p 9pnet 9pnet_virtio"
HOOKS="base udev autodetect modconf block filesystems keyboard fsck 9p_root" # appended 9p_root
```

---

## File: docs/networking.md

# v86 networking

User guide to networking in v86.

## Introduction

On the most basic level, networking in v86 is comprised of two components:

* an emulation of the guest's [Network Interface Controller](https://en.wikipedia.org/wiki/Network_interface_controller) (NIC), and
* a network backend which passes ethernet frames between the NIC and a virtual and/or physical [ethernet network](https://en.wikipedia.org/wiki/Ethernet).

There are two **NIC emulations** supported by v86 to chose from, either **`ne2k`** (NE2000/RTL8390-compatible NIC) or **`virtio`** ([VirtIO](http://wiki.osdev.org/Virtio)-compatible device). The right choice simply depends on the driver support in the guest OS, older OSes like FreeDOS only support NE2000, more modern ones usually support VirtIO. In case both are supported by the guest OS it's recommended to try VirtIO first and only fall back to NE2000 if that fails. In some cases it will also be necessary to manually load a driver or similar to activate the NIC and/or networking in the guest OS, yet modern systems usually auto-detect an available NIC during installation and when booting.

There are also several **network backends** to chose from which emulate the network that the virtual NIC is connected to, they differ in their requirements and in the degree of network access and services provided to guests. Some provide only limited network access, others full access to a physical network which may include a gateway to the Internet. Backends may require a specific type of proxy server to operate.

### Backend URL schemes

The active network backend is configured through a user-specified **backend URL**. Each backend has at least one distinct URL scheme as specified below, where `PROXY` is the DNS hostname or IP address of a compatible proxy server, `PORT` its optional TCP port number (and its default), and `QUERY` is some HTTP query field fragment:

| Backend | Backend URL scheme(s) | Example(s) |
| :------ | :-------------------- | :--------- |
| **[inbrowser](#the-inbrowser-backend)** | `inbrowser` | `inbrowser` |
| **[wsproxy](#the-wsproxy-backend)** | `"ws://" PROXY [":" PORT=80] ["/" ...]``"wss://" PROXY [":" PORT=443] ["/" ...]` | `wss://relay.widgetry.org/` |
| **[wisp](#the-wisp-backend)** | `"wisp://" PROXY [":" PORT=80] ["/" ...]``"wisps://" PROXY [":" PORT=443] ["/" ...]` | `wisp://localhost:12345` |
| **[fetch](#the-fetch-backend)** | `"fetch" [ "://" PROXY [":" PORT] ["/" QUERY] ]` | `fetch``fetch://localhost:1234/?url=` |

Note that `wss://` and `wisps://` are the TLS-secured transports of `ws://` and `wisp://`, respectively.

> [!TIP]
> Since public proxy servers provide only limited bandwidth it is recommended to install and use a local, private proxy server for best results. All proxy servers allow to be executed on the local machine, in a VM running on the local machine, in a local network or even publicly on the Internet (which is generally not recommended, of course). Many proxy servers are distributed as Docker containers which is the recommended way of installing them, otherwise install into a VM.

## Network setup

### Web interface setup

Network setup in the v86 web interface at **https://copy.sh/v86/** is straightforward, simply copy the backend URL into the text box named **`Networking proxy`** or select one of the presets to configure the network backend. The guest's NIC emulation (NE2000 or VirtIO) is automatically configured when selecting the guest image in the web interface.

### Embedded v86 setup

JavaScript applications that do not use the v86 web interface (but instead embed V86 into their architecture) setup their network by using the common `config` object that they pass to the V86 constructor. Network settings are members of the object **`config.net_device`**, all settings are optional except for `relay_url`, see [v86.d.ts](../v86.d.ts).

#### Example `net_device` settings

* **Example 1:** Provide an emulated NE2000 NIC to the guest OS and use the `wsproxy` backend with a secure wsproxy server at public host `relay.widgetry.org` listening at default TLS port 443:
   ```javascript
   let example_1 = new V86({
       net_device: {
           relay_url: "wss://relay.widgetry.org/"
       },
       // ...
   });
   ```

* **Example 2:** Provide a VirtIO NIC to the guest OS and use the `fetch` backend with a CORS proxy server at the local machine listening at port number 23456:
   ```javascript
   let example_2 = new V86({
       net_device: {
           type: "virtio",
           relay_url: "fetch",
           cors_proxy: "https://localhost:23456/?url="
       },
       // ...
   });
   ```

## Network backends

One way to compare the different network backends is how they operate on different layers of the TCP/IP Model (see [Wikipedia](https://en.wikipedia.org/wiki/OSI_model#Comparison_with_TCP/IP_model) for a comparison to the OSI model), approximately:

     Network Peer              Backend                 v86 Guest

    [ Application ] <---- fetch ----> +-----+       [ Application ]
    [   Transport ] <---- wisp -----> | v86 |       [ Transport   ]
    [     Network ]                   |     |       [ Network     ]
    [      Access ] <--- wsproxy ---> +-----+ <---> [ Access      ]
                      and inbrowser

                    Fig. 1: Network backends in v86

v86 guests strictly expect to exchange raw ethernet frames with their (emulated) network card, hence the higher the layer that a v86 network backend operates on the more virtualized the network becomes and the more work has to be done by the backend to fill in for the missing layers.

In order to facilitate this for backend implementations, v86 provides helper functions to encode/decode ethernet frames, ARP and IPv4 packets, UDP datagrams, TCP streams and HTTP requests/responses. v86 can also provide minimal but sufficient ARP, ICMP-echo, DHCP, DNS (including DoH) and NTP services to guests.

The v86 architecture is open for additional network backend implementations, for a basic example see [examples/two_instances.html](../examples/two_instances.html).

### The `inbrowser` backend

This backend provides raw ethernet services for multiple v86 guests running within the same browser process (meaning within the same web page and/or in separate browser tabs). It works standalone without a proxy server, but it also does not provide any access to external networks.

The `inbrowser` backend is implemented using the browser-internal [BroadcastChannel](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel) API, due to its simplicity it is the most efficient backend, however all VMs have to share the same browser resources.

### The `wsproxy` backend

A backend based on a proxy server that provides raw ethernet services to guests using the [WebSocket](https://en.wikipedia.org/wiki/WebSocket) protocol for transport. It depends on the specific proxy server what kind of network configuration it presents to guests, but usually a separate IP subnet with DHCP and DNS services and optional access to the server's physical network and possibly Internet are provided.

Since this backend (including its proxy server) only forwards unmodified ethernet frames it is inherently efficient while providing full physical network emulation to guests.

**Proxy server**

* **[websockproxy](https://github.com/benjamincburns/websockproxy)** -- one TAP device for all clients, integrates dnsmasq for DHCP/DNS, no TLS, original server by benjamincburns
  * Docker container [`benjamincburns/jor1k-relay`](https://hub.docker.com/r/benjamincburns/jor1k-relay) is throttled, see [this comment](https://github.com/benjamincburns/websockproxy/issues/4#issuecomment-317255890)
  * Docker container [`bellenottelling/websockproxy`](https://hub.docker.com/r/bellenottelling/websockproxy) is unthrottled
  * [See here](https://github.com/copy/v86/discussions/1175#discussioncomment-11199254) for step-by-step instructions on how to unthrottle websockproxy manually.
* **[go-websockproxy](https://github.com/gdm85/go-websockproxy)** -- one TAP device for all clients, written in Go, without integraded DHCP but with integrated TLS support
* **[node-relay](https://github.com/krishenriksen/node-relay)** -- like websockproxy but written for NodeJS (dnsmasq/no TLS), see [New websocket ethernet switch built using Node.js #777](https://github.com/copy/v86/discussions/777)
* **[wsnic](https://github.com/chschnell/wsnic)** -- uses a single bridge and one TAP device per client, integrates dnsmasq for DHCP/DNS and stunnel for TLS
* **[RootlessRelay](https://github.com/obegron/rootlessRelay)** -- uses its own network stack that doesn't require TUN/TAP devices, has a built-in reverse proxy and admin interface, see [RootlessRelay #1442](https://github.com/copy/v86/discussions/1442)

[See here](https://github.com/copy/v86/discussions/1199#discussioncomment-12026845) for a benchmark comparing the download performance of these proxy servers.

### The `wisp` backend

The `wisp` backend implements the client side of the [WISP protocol](https://github.com/MercuryWorkshop/wisp-protocol). WISP is a client/server protocol designed to exchange messages containing UDP and TCP payloads between a WebSocket client and a WISP-compatible proxy server. Note that WISP transports only the packet payloads, not the raw UDP or TCP packets.

This backend monitors outbound traffic from guests and wraps/unwraps TCP payload data in WISP messages. A TCP state machine is included to terminate the guest's TCP stream. In addition to the TCP stream, virtual replies to ARP, DHCP, DNS, NTP, ICMP-Ping and UDP-Echo requests from guests are generated (to a certain degree). See PR [#1097](https://github.com/copy/v86/pull/1097) for additional information about this backend.

v86 guests are isolated from each other when using the `wisp` backend.

**WISP-compatible proxy server**

* **[wisp-js](https://www.npmjs.com/package/@mercuryworkshop/wisp-js)**
* **[epoxy-tls](https://github.com/MercuryWorkshop/epoxy-tls)**

> [!NOTE]
> The WISP protocol only supports UDP and TCP client sockets in the v86 guest, any server sockets listening in the guest are not supported.

> [!NOTE]
> This WISP implementation does not support UDP, only TCP. Once UDP is added, regular DNS over UDP will become the default (instead of DoH), and the builtin NTP and UDP-Echo servers will be removed.

### The `fetch` backend

The `fetch` backend uses the browser's [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) API to allow guests to send HTTP requests to external HTTP servers and to receive related HTTP responses. This is however complicated by the fact that browsers add [CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) to HTTP requests initiated by `fetch()`, and that they check the CORS headers of related HTTP responses to block access to external web resources not authorized to `fetch()` in the given context.

This backend is efficient and very useful in cases where CORS is not in the way, otherwise (and in general) a CORS proxy server must be used to provide access to HTTP servers on the open Internet.

Like the [`wisp`](#the-wisp-backend) backend, the `fetch` backend handles DHCP and ARP requests from guests internally, and additionally monitors the guest's outbound traffic for HTTP requests which it translates into calls to `fetch()`. NTP, ICMP pings and UDP echo packets are handled to a certain degree. Note that `fetch()` performs the DNS lookup using the browser's internal DNS client. See PR [#1061](https://github.com/copy/v86/pull/1061) for additional technical details.

Starting with PR [#1233](https://github.com/copy/v86/pull/1233), the TCP guest listener can be accessed from JS API, see the [examples/tcp_terminal.html](../examples/tcp_terminal.html) example.

v86 guests are isolated from each other when using the `fetch` backend.

v86 guests have HTTP access to the host's `localhost` using the URL `http://.external` (e.g. `1234.external` -> `localhost:1234`).

**CORS proxy server**

* **[cors-anywhere](https://github.com/Rob--W/cors-anywhere)** -- NodeJS
* **[uncors](https://github.com/chschnell/uncors)** -- A simple PHP-based CORS proxy server for Apache2.

> [!TIP]
> You can pass the following flags to **chromium** to allow browsing without restrictions when using the fetch backend:
>
>     --disable-web-security --user-data-dir=/tmp/test
>
> **NOTE:** This turns off the same-origin policy and should only be used temporarily!

## Related topics

### v86 run-time state images

v86 supports saving and restoring the guest's and emulator's run-time state in **state image** files.

When restoring a state image, v86 randomises the restored guest's MAC address to make sure that multiple VMs restored from the same state image use different MAC addresses. However, the restored guest OS is unaware that its NIC's MAC address has changed which prevents it from sending and receiving packets correctly. There are several workarounds:

- Unload the network driver before saving the state. On Linux, unloading can be
  done using `rmmod ne2k-pci` or `echo 0000:00:05.0 >
  /sys/bus/pci/drivers/ne2k-pci/unbind` and loading (after the state has been
  loaded) using `modprobe ne2k-pci` or `echo 0000:00:05.0 >
  /sys/bus/pci/drivers/ne2k-pci/bind`
- Pass `preserve_mac_from_state_image: true` to the V86 constructor. This
  causes MAC addresses to be shared between all VMs with the same state image.
- Pass `mac_address_translation: true` to the V86 constructor. This causes v86
  to present the old MAC address to the guest OS, but translate it to a
  randomised MAC address in outgoing packets (and vice-versa for incoming
  packets). This mechanism currently only supports the ethernet, ipv4, dhcp and
  arp protcols. See `translate_mac_address` in
  [`src/ne2k.js`](https://github.com/copy/v86/blob/master/src/ne2k.js). This is
  currently used in Windows, ReactOS and SerenityOS profiles.
- Some OSes don't cache the MAC address when the driver loads and therefore
  don't need any of the above workarounds. This seems to be the case for Haiku,
  OpenBSD and FreeBSD.

Note that the same applies to IP addresses, so a DHCP client should only be run
after the state has been loaded.

### NodeJS

Network backends `wsproxy` and `wisp` depend on a browser-compatible `WebSocket` constructor being present which is the case since NodeJS v22, backends `inbrowser` and `fetch` should work straightaway.

## Links

* [`examples/two_instances.html`](../examples/two_instances.html), example code that shows how to connect two VMs in a web page with a virtual ethernet crossover cable.
* [`examples/broadcast-network.html`](../examples/broadcast-network.html), example code that shows the raw packet API.
* [`examples/tcp_terminal.html`](../examples/tcp_terminal.html), example code that shows how to communicate with a guest TCP port on the `fetch` backend.
* [DC through windows OS for experimental lab #1195](https://github.com/copy/v86/discussions/1195), demonstrates how to setup a Domain Controller for two Windows VMs (XP and Server 2003) using a virtual crossover cable.
* [Working on a new cross-platform network relay that is a full virtualized network #1064](https://github.com/copy/v86/discussions/1064) (used in [env86 #1085](https://github.com/copy/v86/discussions/1085))

---

## File: docs/profiling.md

v86 has a built-in profiler, which instruments generated code to count certain
events and types of instructions. It can be used by building with `make
debug-with-profiler` and opening debug.html.

For debugging networking, packet logging is available in the UI in both debug
and release builds. The resulting `traffic.hex` file can be loaded in Wireshark
using file -> import from hex -> tick direction indication, timestamp %s.%f.

---

## File: docs/windows-9x.md

## Installing using QEMU

Recommended versions:
 - Windows 95 OSR2(.5)
 - Windows 98 Second Edition (SE)

-------------

1. Create a disk image (up to 2 GB):
```sh
qemu-img create -f raw hdd.img <size in megabytes>M
```
2. Run QEMU with the following settings:
```sh
qemu-system-i386 -m 128 -M pc,acpi=off -drive file=hdd.img,format=raw
```
 - add `-cdrom /path/to/installCD.iso`, if you use a CD version.
 - add `-fda /path/to/boot_floppy.img -boot a`, if you use a floppy version or your install CD is non-bootable.
 - (optionally) add `-device sb16` to enable sound
 - (optionally) add `-nic user,model=ne2k_pci` or `-device ne2k_pci,netdev=<...>` to enable networking

3. For Windows 98: select "Start Windows 98 Setup from CD-ROM". For Windows 95: select "Load NEC IDE CDROM driver" and run `fdisk` to create partition, restart emulator, run `format c:` and `D:\WIN95\SETUP`.

4. To change floppy disk, press *Ctrl+Alt+2* to switch to the QEMU Monitor, run `change floppy0 /path/to/new_floppy_image` and press *Ctrl+Alt+1* to switch to VGA.
5. Follow the installation guide on the screen.

> [!TIP]
> For transfer files from host to guest, use [genisoimage](https://wiki.debian.org/genisoimage) ([UltraISO](https://www.ultraiso.com/) and [PowerISO](https://www.poweriso.com/) for Windows and Mac) for creating CD-ISO image or [dosfstools](https://github.com/dosfstools/dosfstools) ([WinImage](https://www.winimage.com/download.htm) for Windows) for creating floppy disk images, then mount the created image to QEMU.

## Troubleshooting

### "Windows protection" errors during startup

Apply [FIX95CPU](http://lonecrusader.x10host.com/fix95cpu.html) or [patcher9x](https://github.com/JHRobotics/patcher9x#installation).

### "VFBACKUP could no load VFD.VXD" on startup (Windows 95)

**Workaround #1**:
*Source: [#1185](https://github.com/copy/v86/issues/1185)*

1. Mount the installation CD (or `Disk 3` for the RTM version on floppy disks).
2. Open the "MS-DOS prompt" and run:

For the CD version:
```bat
extract /a /l C:\Windows\System <cd-rom letter>:\WIN95\WIN95_02.CAB vfd.vxd
```

For the floppy version:
```bat
extract /a /l C:\Windows\System <floppy drive letter>:\WIN95_03.CAB vfd.vxd
```

**Workaround #2**:
*Source: [#289](https://github.com/copy/v86/issues/289)*

1. Open the Start menu, click on "Run" and run `sysedit`.
2. Find `C:\AUTOEXEC.BAT` and add `smartdrv` to the top of the file.
3. Press File -> Save.

## Floppy disk support

Currently, the floppy drive in v86 works only with MS-DOS compatibility mode.

To check this: open the Start menu, click on "Control Panel" and "System", select "Performance" tab.
If it says *"Drive A is using MS-DOS compatibility mode file system"*, the floppy drive should work properly in v86. If not, try this solution:

1. Click on "Device Manager" in "System Properties".
2. Open "Floppy disk controllers", select "Standard Floppy Disk Controller" and press "Remove" at the bottom.
3. Restart Windows.

## Enabling True Color (32 bpp)

The default VGA display driver only supports 640x480x4 video mode, to fix this, you can install **Universal VBE9x Video Display Driver** or **VMDisp9x**.

### Universal VBE9x Video Display Driver

> [!WARNING]
> After installing, DOS Mode (and other programs and games that require it) may not work properly.
> This is a problem in VBE9x, not v86, see [#110](https://github.com/copy/v86/issues/110).
> Also, this driver doesn't support DirectX, DirectDraw and OpenGL.

1. Download driver from https://bearwindows.zcm.com.au/vbe9x.htm and unpack into Windows.
2. Right-click on the Desktop, click on "Properties".
3. Click "Advanced" > "Adapter" > "Change".
4. Press "Next", select "Display a of all the drivers in a specific location..." and press again "Next".
5. Press "Have Disk...", click "Browse" and go to folder with unpacked driver. Inside the folder with driver, should be folders like `032mb`, `064mb`, `128mb`. Choose a version based on needed video memory size (for example, `032mb`), then select `vbemp.inf` inside.
6. Select "VBE Miniport" adapter, press "OK" and "Next".
7. After installing, restart Windows.

### VMDisp9x (Windows 95)

> [!WARNING]
> This driver can run DOS Mode with some graphical glitches. However, DirectX and/or DirectDraw may not work properly with this driver.
> Also, this driver doesn't support OpenGL.

1. Download `vmdisp9x-<...>-driver-2d.img` from https://github.com/JHRobotics/vmdisp9x/releases.
2. Mount as floppy image, right-click on the Desktop, click on "Properties".
3. Click "Advanced" > "Adapter" > "Change".
4. Press "Have Disk...", click "Browse" and go to the floppy.
5. Select "VESA ISA" adapter and press "OK".
6. After installing, restart Windows.

## Enabling absolute mouse positioning (VBMOUSE)

v86 emulates the VMware absolute pointing device. With an absolute mouse driver installed in the guest, the guest cursor follows the host cursor directly, without having to lock the mouse.

[VBADOS](https://git.javispedro.com/cgit/vbados.git/about/) provides VBMOUSE, an open-source DOS mouse driver with VMware mouse support, together with a 16-bit Windows mouse driver on top of it that Windows 9x can use.

1. Download [vbados.flp](https://depot.javispedro.com/vbox/vbados/vbados.flp) and mount it as a floppy image (or copy its contents into the guest in some other way).
2. Copy `VBMOUSE.EXE` from the floppy to the hard disk (for example to `C:\VBADOS`) and `VBMOUSE.DRV` to `C:\WINDOWS\SYSTEM`.
3. Add `C:\VBADOS\VBMOUSE.EXE` to `C:\AUTOEXEC.BAT`, so the DOS part of the driver is loaded before Windows starts.
4. In `C:\WINDOWS\SYSTEM.INI`, change the `mouse.drv` line in the `[boot]` section to `mouse.drv=vbmouse.drv`.
5. Restart Windows.

## CPU idling on Windows 95
See about [installing AmnHLT](cpu-idling.md#windows-9x-using-amnhlt).

## Enabling networking on Windows 95 (requires install CD)

1. Open the Start menu, click on "Control Panel" and "Add New Hardware".
2. Press "Next", select "No" and select next options:

| Option        | Value             |
|:--------------|:------------------|
| Hardware type | Network adapters  |
| Manufacturers | Novell            |
| Models        | NE2000 Compatible |

3. Press "Next" and restart Windows.
4. After restarting, right-click on "My computer", select "Propeties".
5. Open "Device Manager" tab, select "NE2000 Compatible" (in "Network adapters") and press "Properties"
6. Open "Resources", change values by selecting the properties and click on "Change Setting":

| Option             | Value       |
|:-------------------|:------------|
| Interrupt Request  | 10          |
| Input/Output Range | 0300 - 031F |

7. In "Control Panel", open "Network", click on "Add", choose "Protocol" and select the following options:

| Option            | Value     |
|:------------------|:----------|
| Manufacturers     | Microsoft |
| Network Protocols | TCP/IP    |

8. (optionally) Set "Primary Network Logon" to `Windows Logon`.

## Enabling sound manually

> [!NOTE]
> If you don't have an install CD, use the Sound Blaster 16 driver from https://web.archive.org/web/20210814023225/https://www.claunia.com/qemu/drivers/index.html (unpack `sbw9xup.exe` as a zip archive).

1. Open "Start" menu, click on "Control Panel" and "Add New Hardware".
2. Press "Next", select "No" and select the following options:

| Option        | Value                                    |
|:--------------|:-----------------------------------------|
| Hardware type | Sound, video and game cotrollers         |
| Manufacturers | Creative Labs                            |
| Models        | Creative Labs Sound Blaster 16 or AWE-32 |

3. Restart Windows.

---

## File: docs/windows-nt.md

- [Windows NT 3.1](#windows-nt-31) / [3.51](#windows-nt-351) / [4.0](#windows-nt-40)
 - [Windows 2000/XP](#windows-2000xp)
 - [Windows Vista and newer](#windows-vista-and-newer)

------------------------
## Windows NT 3.1

### Installing using QEMU

1. Install MS-DOS and [Oak CD-ROM Driver](https://www.dosdays.co.uk/topics/Software/optical_downloads.php).
2. Create 4 blank floppy disk images:

 - run `qemu-img create -f raw floppy.img 1440K`
 - mount (`-fda floppy.img`) and run `format A:` in a VM

3. Run QEMU with the following settings for installation:

```sh
qemu-system-i386 -m 64 -drive file=hdd.img,format=raw -cpu pentium -M pc,acpi=off -cdrom InstallCD.iso
```

4. Run `xcopy /v <CD-ROM letter>:\I386\ C:\install\` in a VM to copy all files, disable the CD-ROM driver.
5. Run QEMU with the following settings:

```sh
qemu-system-i386 -m 64 -drive file=hdd.img,format=raw -cpu pentium -M pc,acpi=off
```

6. Run `C:\install\winnt /F /C` in a VM.
7. Follow the setup instructions. To change floppy disk, press *Ctrl+Alt+2* to switch to the QEMU Monitor, run `change floppy0 /path/to/new_floppy_image` and press *Ctrl+Alt+1* to switch to VGA.


## Windows NT 3.51

### Installing

> [!NOTE]
> In newer versions of QEMU, the Windows Setup may not work, you can use an older version of QEMU, PCem, 86Box or PCBox instead.

1. If you install via MS-DOS, install [the Oak CD-ROM Driver](https://www.dosdays.co.uk/topics/Software/optical_downloads.php) and run `<CD-ROM letter>:\I386\WINNT /B`.
2. Follow the setup instructions.
3. After installing, download NT 3.51 SuperPack ([here](https://bearwindows.zcm.com.au/winnt351.htm#4) or [here](https://alter.org.ua/en/soft/nt_spack/nt3/)), unpack the archive into a Windows and copy files from `FAT32` (`SYS\FAT32`) and `RENEW` (`SYS\RENEW`) folders in `C:\WINNT35\system32\drivers` with replacing.

### Enabling networking

1. Open "Control Panel" > "Network", install Windows NT Networking (installation CD required).
2. In "Network Adapter Card Detection", press Continue three times, set `Network Adapter Card: Novell NE2000 Compatible Adapter`.
3. Set the following settings and click Continue:

```
IRQ Level: 10
I/O Port Address: 0x300
```

4. In "Bus Location", press OK. Check the boxes "TCP/IP Transport" and "Enable Automatic DHCP Configuration" in the next window.
5. In "TCP/IP Configuration", check the box "Enable Automatic DHCP Configuration".
6. Restart the VM.


## Windows NT 4.0

Recommended version: Windows NT 4.0 SP1

### Installing using QEMU

1. Run QEMU with the following settings for installation:

```sh
qemu-system-i386 -m 64 -drive file=hdd.img,format=raw -cdrom InstallCD.iso -cpu pentium -M pc,acpi=off
```

2. On setup startup, press F5 and select "Standard PC".
3. Follow the setup instructions.

### Running in v86

Due to a problem with CPUID, you need to add `cpuid_level: 2` and `acpi: false` to the V86 constructor (not supported in the UI):

```js
var emulator = new V86({
    ...
    cpuid_level: 2,
    acpi: false
});
```

### Enable True Color

*Source: https://computernewb.com/wiki/QEMU/Guests/Windows_NT_4.0*

1. Download driver (version `2010.07.09`) from https://bearwindows.zcm.com.au/vbemp.htm and unpack into Windows.
2. Right-click on the Desktop, click on "Properties".
3. Click "Settings" > "Display Type" > "Change".
4. Press "Have disk", click "Browse" and go to folder with unpacked driver. Go to `VBE20\NT4`, then select `vbemp4.inf` inside.
5. Select "AnaPa Corp VBE Miniport" adapter, press "Yes" and "OK".
6. After installing, restart the VM.

### Enabling absolute mouse positioning

1. Download [VMware Tools 6.0](https://archive.org/download/vmware-tools-collection/vmware-tools-600-win.iso) and mount the ISO to the VM.
2. Open Start menu, select "Settings" -> "Control Panel".
3. Open "Mouse", press "General" -> "Change"
4. Press "Have disk" and "Browse". Go to `<CD letter>:\program files\VMware\VMware Tools\Drivers\mouse\winnt` and select `vmmouse.inf`.
5. Press "OK" and restart the VM.


## Windows 2000/XP

### Installing using QEMU

1. Run QEMU with the following settings for installation:

```sh
qemu-system-i386 -m 512 -drive file=hdd.img,format=raw -cdrom InstallCD.iso
```

Optional:
 - add `-device sb16` to enable sound
 - add `-nic user,model=ne2k_pci` or `-device ne2k_pci,netdev=<...>` to enable networking

2. Follow the setup instructions.
3. This step fixes the error `Uncaught RangeError: Maximum call stack size exceeded` in Chromium during Windows 2000/XP startup in v86.

After installation, change the computer type to "Standard PC" as described [here](http://web.archive.org/web/20220528021535/https://www.scm-pc-card.de/file/manual/FAQ/acpi_uninstallation_windows_xp_english.pdf):
1. Open Start menu, right-click on "My Computer", select "Manage"
2. Open Device Manager, open Computer, right-click on "ACPI Uniprocessor PC"
3. Select "Update Driver..." > "No, not this time"
4. Select "Install from a list or specific location (Advanced)" > Next > "Don't search. I will choose the driver to install."
5. Choose "Standard PC", press Next > Finish.
6. Restart the VM, follow multiple "Found New Hardware Wizard" dialogs with default options.

### Enabling True Color (for Windows 2000)

> [!NOTE]
> This driver doesn't support DirectX, DirectDraw and OpenGL.

1. Download driver from https://bearwindows.zcm.com.au/vbemp.htm and unpack into Windows.
2. Open Start menu, right-click on "My Computer", select "Manage"
3. Open Device Manager, open Computer and right-click on "Video Controller".
4. Press "Properties", select "Driver" tab and press "Update Driver".
5. Select "Display a list of the known drivers for this device...", choose "Display adapters".
5. Press "Have Disk...", click "Browse" and go to folder with unpacked driver. Go to `VBE20\W2K\PNP`, then select `vbemppnp.inf` inside.
6. Select "VBE Miniport" adapter, press "Yes" and "Next".
7. After installing, restart the VM.

### Enabling sound

*Source: [#1049](https://github.com/copy/v86/issues/1049)*

1. Right-click on "My computer" > "System Properties", select "Hardware" tab, press "Hardware Wizard"
2. Press "Next" > "Add/Troubleshoot a device" > "Add a new device"
3. Select "No, I want to select the hardware from a list" > "Sound, video and game controllers"
4. Select the following options and press "Next":

```
Hardware type: Sound, video and game cotrollers
Manufacturers: Creative Technology Ltd.
Models: Sound Blaster 16 or AWE32 or compatible (WDM)
```


## Windows Vista and newer

### Installing using QEMU

1. Run QEMU with the following settings for installation:

```sh
qemu-system-i386 -m 1024 -drive file=hdd.img,format=raw -cdrom InstallCD.iso
```

Optionally add `-accel kvm` (for Linux host), `-accel whpx` (for Windows host) or `-accel hvf` (for MacOS host) to use hypervisor acceleration.

2. Follow the setup instructions.

### Running in v86

Enable ACPI and set the memory size to 512 MB or more.

### Enabling networking (ne2k)

*Source: https://phaq.phunsites.net/2007/05/21/vista-on-xen-using-ne2000-in-favor-to-rtl8139/*

1. Download https://phaq.phunsites.net/files/2007/05/drivercd.iso_.zip, unpack the archive, mount the ISO to the VM (`-cdrom path/to/drivercd.iso` or `change ide1-cd0 path/to/drivercd.iso` in QEMU Monitor), unpack the archive from CDROM into Windows.
2. Open Start Menu > "Control Panel" > "System" > "Device Manager"
3. Right-click on "Ethernet Controller" > "Update Driver Software", press "Browse my computer for driver software".
4. Click "Browse" and go to folder with unpacked driver, select `WIN2000` folder, press "Install this driver software anyway".