Upload 553 files

.cargo/config.toml

@@ -0,0 +1,2 @@
+[build]
+target-dir = "build"

.devcontainer/Dockerfile

@@ -0,0 +1,11 @@
+FROM library/node:lts-bookworm
+
+ARG DEBIAN_FRONTEND=noninteractive
+RUN apt update && \
+    apt-get install -y nodejs nasm gdb unzip p7zip-full openjdk-17-jre wget python3 qemu-system-x86 git-core build-essential libc6-dev-i386-cross libc6-dev-i386 clang curl time
+RUN npm install -g jshint
+RUN curl https://sh.rustup.rs -sSf | sh -s -- -y
+RUN /root/.cargo/bin/rustup toolchain install stable && \
+    /root/.cargo/bin/rustup target add wasm32-unknown-unknown && \
+    /root/.cargo/bin/rustup component add rustfmt-preview && \
+    /root/.cargo/bin/rustup update && /root/.cargo/bin/rustup update nightly

.devcontainer/devcontainer.json

@@ -0,0 +1,28 @@
+{
+	"name": "v86 dev container",
+	"build": {
+		"dockerfile": "Dockerfile",
+		"args": {
+			"VARIANT": "ubuntu"
+		}
+	},
+	"features": {
+		"ghcr.io/devcontainers-contrib/features/curl-apt-get:1": {},
+		"ghcr.io/jungaretti/features/ripgrep:1": {}
+	},
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"ms-azuretools.vscode-docker",
+				"yzhang.markdown-all-in-one",
+				"DavidAnson.vscode-markdownlint",
+				"christian-kohler.npm-intellisense",
+				"dbaeumer.vscode-eslint",
+				"dustypomerleau.rust-syntax",
+				"serayuzgur.crates",
+				"ms-vscode.makefile-tools",
+				"rust-lang.rust-analyzer"
+			]
+		}
+	}
+}

.editorconfig

@@ -0,0 +1,6 @@
+root=true
+
+[*.js]
+charset = utf-8
+indent_style = space
+indent_size = 4

.gitattributes

@@ -1,35 +1,4 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+lib/zstd/* linguist-vendored
+lib/softfloat/* linguist-vendored
+bios/seabios-debug.bin filter=lfs diff=lfs merge=lfs -text
+bios/seabios.bin filter=lfs diff=lfs merge=lfs -text

.github/ISSUE_TEMPLATE/issue.md

@@ -0,0 +1,24 @@
+---
+name: Issue
+about: Bug reports or feature requests
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+<!--
+Welcome to v86's issue tracker!
+
+We use this tracker for bug reports or feature requests. For user support, questions or general comments, use the chat at https://gitter.im/copy/v86 or the forum at https://github.com/copy/v86/discussions
+
+Please don't ask for support for any version of Windows. There are many existing issues at https://github.com/copy/v86/issues?q=is%253Aissue+windows. See also docs/windows-nt.md and docs/windows-9x.md.
+
+Before reporting OS incompatibilities, check existing issues and the compatibility section of the readme.
+
+When reporting issues, please provide the following information:
+- Version of v86 (see the bottom of index.html or the output of `git describe --tags HEAD`)
+- Browser/OS
+- The browser's console output: Open debug.html and press ctrl+shift+k (firefox) or ctrl+shift+j (chromium)
+- If relevant, upload the disk images to allow developers to reproduce the problem locally
+-->

.github/workflows/ci.yml

@@ -0,0 +1,180 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  eslint:
+    name: eslint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Run eslint
+        run: sudo npm install -g eslint; make eslint
+
+  test:
+    runs-on: ubuntu-latest
+    name: Build and test
+    timeout-minutes: 60
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          filter: tree:0
+
+      - name: Setup Node.js version
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          check-latest: true
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Setup toolchain
+        run: |
+          rustup toolchain install stable --profile minimal
+          rustup target add wasm32-unknown-unknown
+          rustup component add rustfmt
+
+      - name: Install APT packages
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install nasm gdb qemu-system-x86 libc6-dev-i386 -y
+
+      - name: Build all-debug
+        run: make all-debug
+
+      - name: Build all
+        run: make all
+
+      - name: Build fallback
+        run: make build/v86-fallback.wasm
+
+      - name: rustfmt check
+        run: make rustfmt
+
+      - name: Fetch kvm-unit-test cache
+        uses: actions/cache@v4
+        id: cache-kvm-unit-test
+        with:
+          path: tests/kvm-unit-tests/
+          key: ${{ runner.os }}-kvm-unit-test
+
+      - name: Build kvm-unit-test
+        if: steps.cache-kvm-unit-test.outputs.cache-hit != 'true'
+        run: (cd tests/kvm-unit-tests && ./configure && make x86/realmode.flat)
+
+      - name: Run kvm-unit-test
+        run: tests/kvm-unit-tests/run.mjs tests/kvm-unit-tests/x86/realmode.flat
+
+      - name: Fetch namsmtests cache
+        uses: actions/cache@v4
+        id: cache-nasmtests
+        with:
+          path: tests/nasm/build/
+          key: ${{ runner.os }}-nasmtests
+
+      - name: Run nasmtests
+        run: MAX_PARALLEL_TESTS=1 make nasmtests
+
+      - name: Run nasmtests-force-jit
+        run: MAX_PARALLEL_TESTS=1 make nasmtests-force-jit
+
+      - name: Run rust-test
+        run: make rust-test
+
+      - name: Fetch image cache
+        uses: actions/cache@v4
+        id: cache-images
+        with:
+          path: images/
+          key: ${{ runner.os }}-images-v2
+
+      - name: Download uncached images
+        if: steps.cache-images.outputs.cache-hit != 'true'
+        run: mkdir -p images && 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}
+
+      - name: Run api-tests
+        run: make api-tests
+
+      - name: Run qemutests
+        run: make qemutests
+
+      - name: Run qemutests-release
+        run: make qemutests-release
+
+      - name: Run jitpagingtests
+        run: make jitpagingtests
+
+      - name: Run integration tests
+        run: MAX_PARALLEL_TESTS=1 make tests
+
+      - name: Run devices tests
+        run: make devices-test
+
+      - name: Run expect tests
+        run: make expect-tests
+
+      - name: Update package.json version
+        run: make update-package-json-version
+
+      - name: Upload the artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: v86
+          path: |
+            package.json
+            LICENSE
+            Readme.md
+            build/libv86*.js
+            build/libv86*.js.map
+            build/v86*.wasm
+            build/*.mjs
+
+  upload:
+    name: Upload release
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.ref == 'refs/heads/master'
+
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - name: Delete old release and tag
+        uses: dev-drprasad/delete-tag-and-release@v1.0.1
+        with:
+          delete_release: true
+          tag_name: latest
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Get artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: v86
+
+      - name: Display structure of downloaded files
+        run: ls -R
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Release to GitHub
+        uses: ncipollo/release-action@v1
+        with:
+          name: Latest Release
+          tag: latest
+          commit: master
+          body: ${{ github.event.head_commit.message }}
+          artifacts: "build/libv86*.js,build/libv86*.js.map,build/*.mjs,build/v86*.wasm"
+          prerelease: true
+
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

.gitignore

@@ -0,0 +1,28 @@
+*.swp
+*.swo
+tests/qemu/test-i386
+tests/jit-paging/test-jit
+*.map
+build/
+closure-compiler/
+images/
+*.bak
+*.orig
+*.wasm
+*.o
+*.bin
+*.img
+*.fixture
+*.fuse_hidden*
+*.DS_Store
+node_modules/
+Cargo.lock
+build-head
+src/rust/gen/interpreter.rs
+src/rust/gen/interpreter0f.rs
+src/rust/gen/analyzer.rs
+src/rust/gen/analyzer0f.rs
+src/rust/gen/jit.rs
+src/rust/gen/jit0f.rs
+bios/seabios
+bench-results

.rustfmt.toml

@@ -0,0 +1,6 @@
+use_field_init_shorthand = true
+match_block_trailing_comma = true
+fn_single_line = true
+imports_indent = "Block"
+control_brace_style = "ClosingNextLine"
+single_line_if_else_max_width = 92

.vscode/tasks.json

@@ -0,0 +1,12 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Fetch images",
+            "type": "shell",
+            "command": "wget -P images/ https://i.copy.sh/{linux3.iso,linux.iso,linux4.iso,buildroot-bzimage.bin,openbsd-floppy.img,kolibri.img,windows101.img,os8.img,freedos722.img}"
+        }
+    ]
+}

Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "v86"
+version = "0.1.0"
+publish = false
+edition = "2021"
+
+[features]
+default = []
+profiler = []
+
+[lib]
+crate-type = ["cdylib"]
+path = "src/rust/lib.rs"
+
+[profile.test]
+lto = false
+opt-level = 2
+overflow-checks = false
+
+[profile.dev]
+lto = true
+opt-level = 2
+panic = "abort"
+overflow-checks = false
+
+[profile.release]
+lto = true
+opt-level = 3
+incremental = false
+panic = "abort"

LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012, The v86 contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

LICENSE.MIT

@@ -0,0 +1,22 @@
+QEMU Floppy disk emulator (Intel 82078)
+
+Copyright (c) 2003, 2007 Jocelyn Mayer
+Copyright (c) 2008 Hervé Poussineau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

Makefile

@@ -0,0 +1,398 @@
+CLOSURE_DIR=closure-compiler
+CLOSURE=$(CLOSURE_DIR)/compiler.jar
+NASM_TEST_DIR=./tests/nasm
+
+INSTRUCTION_TABLES=src/rust/gen/jit.rs src/rust/gen/jit0f.rs \
+		   src/rust/gen/interpreter.rs src/rust/gen/interpreter0f.rs \
+		   src/rust/gen/analyzer.rs src/rust/gen/analyzer0f.rs \
+
+# Only the dependencies common to both generate_{jit,interpreter}.js
+GEN_DEPENDENCIES=$(filter-out gen/generate_interpreter.js gen/generate_jit.js gen/generate_analyzer.js, $(wildcard gen/*.js))
+JIT_DEPENDENCIES=$(GEN_DEPENDENCIES) gen/generate_jit.js
+INTERPRETER_DEPENDENCIES=$(GEN_DEPENDENCIES) gen/generate_interpreter.js
+ANALYZER_DEPENDENCIES=$(GEN_DEPENDENCIES) gen/generate_analyzer.js
+
+STRIP_DEBUG_FLAG=
+ifeq ($(STRIP_DEBUG),true)
+STRIP_DEBUG_FLAG=--v86-strip-debug
+endif
+
+WASM_OPT ?= false
+
+default: build/v86-debug.wasm
+all: build/v86_all.js build/libv86.js build/libv86.mjs build/v86.wasm
+all-debug: build/libv86-debug.js build/libv86-debug.mjs build/v86-debug.wasm
+browser: build/v86_all.js
+
+# Used for nodejs builds and in order to profile code.
+# `debug` gives identifiers a readable name, make sure it doesn't have any side effects.
+CLOSURE_READABLE=--formatting PRETTY_PRINT --debug
+
+CLOSURE_SOURCE_MAP=\
+		--source_map_format V3\
+		--create_source_map '%outname%.map'
+
+CLOSURE_FLAGS=\
+		--generate_exports\
+		--externs src/externs.js\
+		--warning_level VERBOSE\
+		--jscomp_error accessControls\
+		--jscomp_error checkRegExp\
+		--jscomp_error checkTypes\
+		--jscomp_error checkVars\
+		--jscomp_error conformanceViolations\
+		--jscomp_error const\
+		--jscomp_error constantProperty\
+		--jscomp_error deprecated\
+		--jscomp_error deprecatedAnnotations\
+		--jscomp_error duplicateMessage\
+		--jscomp_error es5Strict\
+		--jscomp_error externsValidation\
+		--jscomp_error globalThis\
+		--jscomp_error invalidCasts\
+		--jscomp_error misplacedTypeAnnotation\
+		--jscomp_error missingProperties\
+		--jscomp_error missingReturn\
+		--jscomp_error msgDescriptions\
+		--jscomp_error nonStandardJsDocs\
+		--jscomp_error suspiciousCode\
+		--jscomp_error strictModuleDepCheck\
+		--jscomp_error typeInvalidation\
+		--jscomp_error undefinedVars\
+		--jscomp_error unknownDefines\
+		--jscomp_error visibility\
+		--use_types_for_optimization\
+		--assume_function_wrapper\
+		--summary_detail_level 3\
+		--language_in ECMASCRIPT_2020\
+		--language_out ECMASCRIPT_2020
+
+CARGO_FLAGS_SAFE=\
+		--target wasm32-unknown-unknown \
+		-- \
+		-C linker=tools/rust-lld-wrapper \
+		-C link-args="--import-table --global-base=4096 $(STRIP_DEBUG_FLAG)" \
+		-C link-args="build/softfloat.o" \
+		-C link-args="build/zstddeclib.o" \
+		--verbose
+
+CARGO_FLAGS=$(CARGO_FLAGS_SAFE) -C target-feature=+bulk-memory -C target-feature=+multivalue -C target-feature=+simd128
+
+CORE_FILES=cjs.js const.js io.js main.js lib.js buffer.js ide.js pci.js floppy.js \
+	   dma.js pit.js vga.js ps2.js rtc.js uart.js \
+	   acpi.js iso9660.js \
+	   state.js ne2k.js sb16.js virtio.js virtio_console.js virtio_net.js virtio_balloon.js \
+	   bus.js log.js cpu.js \
+	   elf.js kernel.js
+LIB_FILES=9p.js filesystem.js marshall.js
+BROWSER_FILES=screen.js keyboard.js mouse.js speaker.js serial.js \
+	      network.js starter.js worker_bus.js dummy_screen.js \
+	      inbrowser_network.js fake_network.js wisp_network.js fetch_network.js \
+          print_stats.js filestorage.js
+
+RUST_FILES=$(shell find src/rust/ -name '*.rs') \
+	   src/rust/gen/interpreter.rs src/rust/gen/interpreter0f.rs \
+	   src/rust/gen/jit.rs src/rust/gen/jit0f.rs \
+	   src/rust/gen/analyzer.rs src/rust/gen/analyzer0f.rs
+
+CORE_FILES:=$(addprefix src/,$(CORE_FILES))
+LIB_FILES:=$(addprefix lib/,$(LIB_FILES))
+BROWSER_FILES:=$(addprefix src/browser/,$(BROWSER_FILES))
+
+build/v86_all.js: $(CLOSURE) src/*.js src/browser/*.js lib/*.js
+	mkdir -p build
+	-ls -lh build/v86_all.js
+	java -jar $(CLOSURE) \
+		--js_output_file build/v86_all.js\
+		--define=DEBUG=false\
+		$(CLOSURE_SOURCE_MAP)\
+		$(CLOSURE_FLAGS)\
+		--compilation_level ADVANCED\
+		--js $(CORE_FILES)\
+		--js $(LIB_FILES)\
+		--js $(BROWSER_FILES)\
+		--js src/browser/main.js
+	ls -lh build/v86_all.js
+
+build/v86_all_debug.js: $(CLOSURE) src/*.js src/browser/*.js lib/*.js
+	mkdir -p build
+	java -jar $(CLOSURE) \
+		--js_output_file build/v86_all_debug.js\
+		--define=DEBUG=true\
+		$(CLOSURE_SOURCE_MAP)\
+		$(CLOSURE_FLAGS)\
+		--compilation_level ADVANCED\
+		--js $(CORE_FILES)\
+		--js $(LIB_FILES)\
+		--js $(BROWSER_FILES)\
+		--js src/browser/main.js
+
+build/libv86.js: $(CLOSURE) src/*.js lib/*.js src/browser/*.js
+	mkdir -p build
+	-ls -lh build/libv86.js
+	java -jar $(CLOSURE) \
+		--js_output_file build/libv86.js\
+		--define=DEBUG=false\
+		$(CLOSURE_FLAGS)\
+		--compilation_level SIMPLE\
+		--jscomp_off=missingProperties\
+		--output_wrapper ';(function(){%output%}).call(this);'\
+		--js $(CORE_FILES)\
+		--js $(BROWSER_FILES)\
+		--js $(LIB_FILES)
+	ls -lh build/libv86.js
+
+build/libv86.mjs: $(CLOSURE) src/*.js lib/*.js src/browser/*.js
+	mkdir -p build
+	-ls -lh build/libv86.js
+	java -jar $(CLOSURE) \
+		--js_output_file build/libv86.mjs\
+		--define=DEBUG=false\
+		$(CLOSURE_FLAGS)\
+		--compilation_level SIMPLE\
+		--jscomp_off=missingProperties\
+		--output_wrapper ';let module = {exports:{}}; %output%; export default module.exports.V86; export let {V86, CPU} = module.exports;'\
+		--js $(CORE_FILES)\
+		--js $(BROWSER_FILES)\
+		--js $(LIB_FILES)\
+		--chunk_output_type=ES_MODULES\
+		--emit_use_strict=false
+	ls -lh build/libv86.mjs
+
+build/libv86-debug.js: $(CLOSURE) src/*.js lib/*.js src/browser/*.js
+	mkdir -p build
+	java -jar $(CLOSURE) \
+		--js_output_file build/libv86-debug.js\
+		--define=DEBUG=true\
+		$(CLOSURE_FLAGS)\
+		$(CLOSURE_READABLE)\
+		--compilation_level SIMPLE\
+		--jscomp_off=missingProperties\
+		--output_wrapper ';(function(){%output%}).call(this);'\
+		--js $(CORE_FILES)\
+		--js $(BROWSER_FILES)\
+		--js $(LIB_FILES)
+
+build/libv86-debug.mjs: $(CLOSURE) src/*.js lib/*.js src/browser/*.js
+	mkdir -p build
+	java -jar $(CLOSURE) \
+		--js_output_file build/libv86-debug.mjs\
+		--define=DEBUG=true\
+		$(CLOSURE_FLAGS)\
+		--compilation_level SIMPLE\
+		--jscomp_off=missingProperties\
+		--output_wrapper ';let module = {exports:{}}; %output%; export default module.exports.V86; export let {V86, CPU} = module.exports;'\
+		--js $(CORE_FILES)\
+		--js $(BROWSER_FILES)\
+		--js $(LIB_FILES)\
+		--chunk_output_type=ES_MODULES\
+		--emit_use_strict=false
+	ls -lh build/libv86-debug.mjs
+
+src/rust/gen/jit.rs: $(JIT_DEPENDENCIES)
+	./gen/generate_jit.js --output-dir build/ --table jit
+src/rust/gen/jit0f.rs: $(JIT_DEPENDENCIES)
+	./gen/generate_jit.js --output-dir build/ --table jit0f
+
+src/rust/gen/interpreter.rs: $(INTERPRETER_DEPENDENCIES)
+	./gen/generate_interpreter.js --output-dir build/ --table interpreter
+src/rust/gen/interpreter0f.rs: $(INTERPRETER_DEPENDENCIES)
+	./gen/generate_interpreter.js --output-dir build/ --table interpreter0f
+
+src/rust/gen/analyzer.rs: $(ANALYZER_DEPENDENCIES)
+	./gen/generate_analyzer.js --output-dir build/ --table analyzer
+src/rust/gen/analyzer0f.rs: $(ANALYZER_DEPENDENCIES)
+	./gen/generate_analyzer.js --output-dir build/ --table analyzer0f
+
+build/v86.wasm: $(RUST_FILES) build/softfloat.o build/zstddeclib.o Cargo.toml
+	mkdir -p build/
+	-BLOCK_SIZE=K ls -l build/v86.wasm
+	cargo rustc --release $(CARGO_FLAGS)
+	cp build/wasm32-unknown-unknown/release/v86.wasm build/v86.wasm
+	-$(WASM_OPT) && wasm-opt -O2 --strip-debug build/v86.wasm -o build/v86.wasm
+	BLOCK_SIZE=K ls -l build/v86.wasm
+
+build/v86-debug.wasm: $(RUST_FILES) build/softfloat.o build/zstddeclib.o Cargo.toml
+	mkdir -p build/
+	-BLOCK_SIZE=K ls -l build/v86-debug.wasm
+	cargo rustc $(CARGO_FLAGS)
+	cp build/wasm32-unknown-unknown/debug/v86.wasm build/v86-debug.wasm
+	BLOCK_SIZE=K ls -l build/v86-debug.wasm
+
+build/v86-fallback.wasm: $(RUST_FILES) build/softfloat.o build/zstddeclib.o Cargo.toml
+	mkdir -p build/
+	cargo rustc --release $(CARGO_FLAGS_SAFE)
+	cp build/wasm32-unknown-unknown/release/v86.wasm build/v86-fallback.wasm || true
+
+debug-with-profiler: $(RUST_FILES) build/softfloat.o build/zstddeclib.o Cargo.toml
+	mkdir -p build/
+	cargo rustc --features profiler $(CARGO_FLAGS)
+	cp build/wasm32-unknown-unknown/debug/v86.wasm build/v86-debug.wasm || true
+
+with-profiler: $(RUST_FILES) build/softfloat.o build/zstddeclib.o Cargo.toml
+	mkdir -p build/
+	cargo rustc --release --features profiler $(CARGO_FLAGS)
+	cp build/wasm32-unknown-unknown/release/v86.wasm build/v86.wasm || true
+
+watch:
+	cargo watch -x 'rustc $(CARGO_FLAGS)' -s 'cp build/wasm32-unknown-unknown/debug/v86.wasm build/v86-debug.wasm'
+
+build/softfloat.o: lib/softfloat/softfloat.c
+	mkdir -p build
+	clang -c -Wall \
+	    --target=wasm32 -O3 -flto -nostdlib -fvisibility=hidden -ffunction-sections -fdata-sections \
+	    -DSOFTFLOAT_FAST_INT64 -DINLINE_LEVEL=5 -DSOFTFLOAT_FAST_DIV32TO16 -DSOFTFLOAT_FAST_DIV64TO32 \
+	    -o build/softfloat.o \
+	    lib/softfloat/softfloat.c
+
+build/zstddeclib.o: lib/zstd/zstddeclib.c
+	mkdir -p build
+	clang -c -Wall \
+	    --target=wasm32 -O3 -flto -nostdlib -fvisibility=hidden -ffunction-sections -fdata-sections \
+	    -DZSTDLIB_VISIBILITY="" \
+	    -o build/zstddeclib.o \
+	    lib/zstd/zstddeclib.c
+
+clean:
+	-rm build/libv86.js
+	-rm build/libv86.mjs
+	-rm build/libv86-debug.js
+	-rm build/libv86-debug.mjs
+	-rm build/v86_all.js
+	-rm build/v86.wasm
+	-rm build/v86-debug.wasm
+	-rm $(INSTRUCTION_TABLES)
+	-rm build/*.map
+	-rm build/*.wast
+	-rm build/*.o
+	$(MAKE) -C $(NASM_TEST_DIR) clean
+
+run:
+	python3 -m http.server 2> /dev/null
+
+update_version:
+	set -e ;\
+	COMMIT=`git log --format="%h" -n 1` ;\
+	DATE=`git log --date="format:%b %e, %Y %H:%m" --format="%cd" -n 1` ;\
+	SEARCH='<code>Version: <a id="version" href="https://github.com/copy/v86/commits/[a-f0-9]\+">[a-f0-9]\+</a> ([^(]\+)</code>' ;\
+	REPLACE='<code>Version: <a id="version" href="https://github.com/copy/v86/commits/'$$COMMIT'">'$$COMMIT'</a> ('$$DATE')</code>' ;\
+	sed -i "s@$$SEARCH@$$REPLACE@g" index.html ;\
+	SEARCH='<script src="build/v86_all.js?[a-f0-9]\+"></script>' ;\
+	REPLACE='<script src="build/v86_all.js?'$$COMMIT'"></script>' ;\
+	sed -i "s@$$SEARCH@$$REPLACE@g" index.html ;\
+	grep $$COMMIT index.html
+
+
+$(CLOSURE):
+	mkdir -p $(CLOSURE_DIR)
+	# don't upgrade until https://github.com/google/closure-compiler/issues/3972 is fixed
+	wget -nv -O $(CLOSURE) https://repo1.maven.org/maven2/com/google/javascript/closure-compiler/v20210601/closure-compiler-v20210601.jar
+
+build/integration-test-fs/fs.json: images/buildroot-bzimage68.bin
+	mkdir -p build/integration-test-fs/flat
+	cp images/buildroot-bzimage68.bin build/integration-test-fs/bzImage
+	touch build/integration-test-fs/initrd
+	cd build/integration-test-fs && tar cfv fs.tar bzImage initrd
+	./tools/fs2json.py build/integration-test-fs/fs.tar --out build/integration-test-fs/fs.json
+	./tools/copy-to-sha256.py build/integration-test-fs/fs.tar build/integration-test-fs/flat
+	rm build/integration-test-fs/fs.tar build/integration-test-fs/bzImage build/integration-test-fs/initrd
+
+tests: build/v86-debug.wasm build/integration-test-fs/fs.json
+	LOG_LEVEL=3 ./tests/full/run.js
+
+tests-release: build/libv86.js build/v86.wasm build/integration-test-fs/fs.json
+	TEST_RELEASE_BUILD=1 ./tests/full/run.js
+
+nasmtests: build/v86-debug.wasm
+	$(NASM_TEST_DIR)/create_tests.js
+	$(NASM_TEST_DIR)/gen_fixtures.js
+	$(NASM_TEST_DIR)/run.js
+
+nasmtests-force-jit: build/v86-debug.wasm
+	$(NASM_TEST_DIR)/create_tests.js
+	$(NASM_TEST_DIR)/gen_fixtures.js
+	$(NASM_TEST_DIR)/run.js --force-jit
+
+jitpagingtests: build/v86-debug.wasm
+	$(MAKE) -C tests/jit-paging test-jit
+	./tests/jit-paging/run.js
+
+qemutests: build/v86-debug.wasm
+	$(MAKE) -C tests/qemu test-i386
+	LOG_LEVEL=3 ./tests/qemu/run.js build/qemu-test-result
+	./tests/qemu/run-qemu.js > build/qemu-test-reference
+	diff build/qemu-test-result build/qemu-test-reference
+
+qemutests-release: build/libv86.mjs build/v86.wasm
+	$(MAKE) -C tests/qemu test-i386
+	TEST_RELEASE_BUILD=1 time ./tests/qemu/run.js build/qemu-test-result
+	./tests/qemu/run-qemu.js > build/qemu-test-reference
+	diff build/qemu-test-result build/qemu-test-reference
+
+kvm-unit-test: build/v86-debug.wasm
+	(cd tests/kvm-unit-tests && ./configure && make x86/realmode.flat)
+	tests/kvm-unit-tests/run.mjs tests/kvm-unit-tests/x86/realmode.flat
+
+kvm-unit-test-release: build/libv86.mjs build/v86.wasm
+	(cd tests/kvm-unit-tests && ./configure && make x86/realmode.flat)
+	TEST_RELEASE_BUILD=1 tests/kvm-unit-tests/run.mjs tests/kvm-unit-tests/x86/realmode.flat
+
+expect-tests: build/v86-debug.wasm build/libwabt.cjs
+	make -C tests/expect/tests
+	./tests/expect/run.js
+
+devices-test: build/v86-debug.wasm
+	./tests/devices/virtio_9p.js
+	./tests/devices/virtio_console.js
+	./tests/devices/fetch_network.js
+	USE_VIRTIO=1 ./tests/devices/fetch_network.js
+	./tests/devices/wisp_network.js
+	./tests/devices/virtio_balloon.js
+
+rust-test: $(RUST_FILES)
+	env RUSTFLAGS="-D warnings" RUST_BACKTRACE=full RUST_TEST_THREADS=1 cargo test -- --nocapture
+	./tests/rust/verify-wasmgen-dummy-output.js
+
+rust-test-intensive:
+	QUICKCHECK_TESTS=100000000 make rust-test
+
+api-tests: build/v86-debug.wasm
+	./tests/api/clean-shutdown.js
+	./tests/api/state.js
+	./tests/api/reset.js
+	./tests/api/floppy.js
+	./tests/api/cdrom-insert-eject.js
+	./tests/api/serial.js
+	./tests/api/reboot.js
+	./tests/api/pic.js
+
+all-tests: eslint kvm-unit-test qemutests qemutests-release jitpagingtests api-tests nasmtests nasmtests-force-jit rust-test tests expect-tests
+	# Skipping:
+	# - devices-test (hangs)
+
+eslint:
+	eslint src tests gen lib examples tools
+
+rustfmt: $(RUST_FILES)
+	cargo fmt --all -- --check --config fn_single_line=true,control_brace_style=ClosingNextLine
+
+build/capstone-x86.min.js:
+	mkdir -p build
+	wget -nv -P build https://github.com/AlexAltea/capstone.js/releases/download/v3.0.5-rc1/capstone-x86.min.js
+
+build/libwabt.cjs:
+	mkdir -p build
+	wget -nv -P build https://github.com/WebAssembly/wabt/archive/1.0.6.zip
+	unzip -j -d build/ build/1.0.6.zip wabt-1.0.6/demo/libwabt.js
+	mv build/libwabt.js build/libwabt.cjs
+	rm build/1.0.6.zip
+
+build/xterm.js:
+	curl https://cdn.jsdelivr.net/npm/xterm@5.2.1/lib/xterm.min.js > build/xterm.js
+	curl https://cdn.jsdelivr.net/npm/xterm@5.2.1/lib/xterm.js.map > build/xterm.js.map
+	curl https://cdn.jsdelivr.net/npm/xterm@5.2.1/css/xterm.css > build/xterm.css
+
+update-package-json-version:
+	git describe --tags --exclude latest | sed 's/-/./' | tr - + | tee build/version
+	jq --arg version "$$(cat build/version)" '.version = $$version' package.json > package.json.tmp
+	mv package.json.tmp package.json

Readme.md

@@ -0,0 +1,215 @@
+[![Join the chat at https://gitter.im/copy/v86](https://badges.gitter.im/Join%20Chat.svg)](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.
+
+## 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) —
+[Alpine Linux guest setup](tools/docker/alpine/) —
+[Arch Linux guest setup](docs/archlinux.md) —
+[Windows NT guest setup](docs/windows-nt.md) —
+[Windows 9x guest setup](docs/windows-9x.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.uclibc.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, 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](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.
+
+### 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 [starter.js](src/browser/starter.js).
+
+## 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.

bios/.gitignore

@@ -0,0 +1 @@
+*.gz

bios/COPYING.LESSER

@@ -0,0 +1,165 @@
+		   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions. 
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version. 
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

bios/fetch-and-build-seabios.sh

@@ -0,0 +1,13 @@
+set -e
+git clone https://git.seabios.org/seabios.git || true
+(cd seabios && git checkout rel-1.16.2)
+
+cp seabios.config seabios/.config
+make -C seabios
+cp seabios/out/bios.bin seabios.bin
+cp seabios/out/vgabios.bin vgabios.bin
+
+cp seabios-debug.config seabios/.config
+make -C seabios
+cp seabios/out/bios.bin seabios-debug.bin
+cp seabios/out/vgabios.bin vgabios-debug.bin

bios/seabios-debug.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:24174391d6612384bfaabe315d5b8405b16740a37bfd69367dc37fc321bcde1a
+size 262144

bios/seabios-debug.config

@@ -0,0 +1,119 @@
+#
+# Automatically generated file; DO NOT EDIT.
+# SeaBIOS Configuration
+#
+
+#
+# General Features
+#
+# CONFIG_COREBOOT is not set
+CONFIG_QEMU=y
+# CONFIG_CSM is not set
+CONFIG_QEMU_HARDWARE=y
+CONFIG_XEN=y
+CONFIG_THREADS=y
+# CONFIG_RELOCATE_INIT is not set
+# CONFIG_BOOTMENU is not set
+CONFIG_BOOTORDER=y
+CONFIG_HOST_BIOS_GEOMETRY=y
+CONFIG_ENTRY_EXTRASTACK=y
+CONFIG_MALLOC_UPPERMEMORY=y
+CONFIG_ROM_SIZE=0
+
+#
+# Hardware support
+#
+CONFIG_ATA=y
+CONFIG_ATA_DMA=y
+CONFIG_ATA_PIO32=y
+CONFIG_AHCI=y
+CONFIG_SDCARD=y
+CONFIG_VIRTIO_BLK=y
+CONFIG_VIRTIO_SCSI=y
+CONFIG_PVSCSI=y
+CONFIG_ESP_SCSI=y
+CONFIG_LSI_SCSI=y
+CONFIG_MEGASAS=y
+CONFIG_MPT_SCSI=y
+CONFIG_FLOPPY=y
+CONFIG_FLASH_FLOPPY=y
+# CONFIG_NVME is not set
+CONFIG_PS2PORT=y
+# CONFIG_USB is not set
+CONFIG_SERIAL=y
+# CONFIG_SERCON is not set
+CONFIG_LPT=y
+CONFIG_RTC_TIMER=y
+CONFIG_HARDWARE_IRQ=y
+CONFIG_USE_SMM=y
+CONFIG_CALL32_SMM=y
+CONFIG_MTRR_INIT=y
+CONFIG_PMTIMER=y
+CONFIG_TSC_TIMER=y
+
+#
+# BIOS interfaces
+#
+CONFIG_DRIVES=y
+CONFIG_CDROM_BOOT=y
+CONFIG_CDROM_EMU=y
+CONFIG_PCIBIOS=y
+CONFIG_APMBIOS=y
+CONFIG_PNPBIOS=y
+CONFIG_OPTIONROMS=y
+CONFIG_PMM=y
+CONFIG_BOOT=y
+CONFIG_KEYBOARD=y
+CONFIG_KBD_CALL_INT15_4F=y
+CONFIG_MOUSE=y
+CONFIG_S3_RESUME=y
+CONFIG_VGAHOOKS=y
+# CONFIG_DISABLE_A20 is not set
+# CONFIG_WRITABLE_UPPERMEMORY is not set
+CONFIG_TCGBIOS=y
+
+#
+# BIOS Tables
+#
+CONFIG_PIRTABLE=y
+CONFIG_MPTABLE=y
+# CONFIG_SMBIOS is not set
+CONFIG_ACPI=y
+CONFIG_ACPI_DSDT=y
+CONFIG_FW_ROMFILE_LOAD=y
+CONFIG_ACPI_PARSE=y
+
+#
+# VGA ROM
+#
+# CONFIG_NO_VGABIOS is not set
+# CONFIG_VGA_STANDARD_VGA is not set
+# CONFIG_VGA_CIRRUS is not set
+# CONFIG_VGA_ATI is not set
+CONFIG_VGA_BOCHS=y
+# CONFIG_VGA_GEODEGX2 is not set
+# CONFIG_VGA_GEODELX is not set
+# CONFIG_DISPLAY_BOCHS is not set
+# CONFIG_VGA_RAMFB is not set
+CONFIG_VGA_BOCHS_STDVGA=y
+# CONFIG_VGA_BOCHS_VMWARE is not set
+# CONFIG_VGA_BOCHS_QXL is not set
+# CONFIG_VGA_BOCHS_VIRTIO is not set
+CONFIG_BUILD_VGABIOS=y
+CONFIG_VGA_STDVGA_PORTS=y
+CONFIG_VGA_FIXUP_ASM=y
+CONFIG_VGA_ALLOCATE_EXTRA_STACK=y
+CONFIG_VGA_EXTRA_STACK_SIZE=512
+CONFIG_VGA_VBE=y
+CONFIG_VGA_PCI=y
+CONFIG_OVERRIDE_PCI_ID=y
+CONFIG_VGA_VID=0x1234
+CONFIG_VGA_DID=0x1111
+
+#
+# Debugging
+#
+CONFIG_DEBUG_LEVEL=8
+# CONFIG_DEBUG_SERIAL is not set
+# CONFIG_DEBUG_SERIAL_MMIO is not set
+CONFIG_DEBUG_IO=y

bios/seabios.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:73e3f359102e3a9982c35fce98eb7cd08f18303ac7f1ba6ebfbe6cdc1c244d98
+size 131072

bios/seabios.config

@@ -0,0 +1,116 @@
+#
+# Automatically generated file; DO NOT EDIT.
+# SeaBIOS Configuration
+#
+
+#
+# General Features
+#
+# CONFIG_COREBOOT is not set
+CONFIG_QEMU=y
+# CONFIG_CSM is not set
+CONFIG_QEMU_HARDWARE=y
+CONFIG_XEN=y
+CONFIG_THREADS=y
+# CONFIG_RELOCATE_INIT is not set
+# CONFIG_BOOTMENU is not set
+CONFIG_BOOTORDER=y
+CONFIG_HOST_BIOS_GEOMETRY=y
+CONFIG_ENTRY_EXTRASTACK=y
+CONFIG_MALLOC_UPPERMEMORY=y
+CONFIG_ROM_SIZE=0
+
+#
+# Hardware support
+#
+CONFIG_ATA=y
+CONFIG_ATA_DMA=y
+CONFIG_ATA_PIO32=y
+CONFIG_AHCI=y
+CONFIG_SDCARD=y
+CONFIG_VIRTIO_BLK=y
+CONFIG_VIRTIO_SCSI=y
+CONFIG_PVSCSI=y
+CONFIG_ESP_SCSI=y
+CONFIG_LSI_SCSI=y
+CONFIG_MEGASAS=y
+CONFIG_MPT_SCSI=y
+CONFIG_FLOPPY=y
+CONFIG_FLASH_FLOPPY=y
+# CONFIG_NVME is not set
+CONFIG_PS2PORT=y
+# CONFIG_USB is not set
+CONFIG_SERIAL=y
+# CONFIG_SERCON is not set
+CONFIG_LPT=y
+CONFIG_RTC_TIMER=y
+CONFIG_HARDWARE_IRQ=y
+CONFIG_USE_SMM=y
+CONFIG_CALL32_SMM=y
+CONFIG_MTRR_INIT=y
+CONFIG_PMTIMER=y
+CONFIG_TSC_TIMER=y
+
+#
+# BIOS interfaces
+#
+CONFIG_DRIVES=y
+CONFIG_CDROM_BOOT=y
+CONFIG_CDROM_EMU=y
+CONFIG_PCIBIOS=y
+CONFIG_APMBIOS=y
+CONFIG_PNPBIOS=y
+CONFIG_OPTIONROMS=y
+CONFIG_PMM=y
+CONFIG_BOOT=y
+CONFIG_KEYBOARD=y
+CONFIG_KBD_CALL_INT15_4F=y
+CONFIG_MOUSE=y
+CONFIG_S3_RESUME=y
+CONFIG_VGAHOOKS=y
+# CONFIG_DISABLE_A20 is not set
+# CONFIG_WRITABLE_UPPERMEMORY is not set
+CONFIG_TCGBIOS=y
+
+#
+# BIOS Tables
+#
+CONFIG_PIRTABLE=y
+CONFIG_MPTABLE=y
+# CONFIG_SMBIOS is not set
+CONFIG_ACPI=y
+CONFIG_ACPI_DSDT=y
+CONFIG_FW_ROMFILE_LOAD=y
+CONFIG_ACPI_PARSE=y
+
+#
+# VGA ROM
+#
+# CONFIG_NO_VGABIOS is not set
+# CONFIG_VGA_STANDARD_VGA is not set
+# CONFIG_VGA_CIRRUS is not set
+# CONFIG_VGA_ATI is not set
+CONFIG_VGA_BOCHS=y
+# CONFIG_VGA_GEODEGX2 is not set
+# CONFIG_VGA_GEODELX is not set
+# CONFIG_DISPLAY_BOCHS is not set
+# CONFIG_VGA_RAMFB is not set
+CONFIG_VGA_BOCHS_STDVGA=y
+# CONFIG_VGA_BOCHS_VMWARE is not set
+# CONFIG_VGA_BOCHS_QXL is not set
+# CONFIG_VGA_BOCHS_VIRTIO is not set
+CONFIG_BUILD_VGABIOS=y
+CONFIG_VGA_STDVGA_PORTS=y
+CONFIG_VGA_FIXUP_ASM=y
+CONFIG_VGA_ALLOCATE_EXTRA_STACK=y
+CONFIG_VGA_EXTRA_STACK_SIZE=512
+CONFIG_VGA_VBE=y
+CONFIG_VGA_PCI=y
+CONFIG_OVERRIDE_PCI_ID=y
+CONFIG_VGA_VID=0x1234
+CONFIG_VGA_DID=0x1111
+
+#
+# Debugging
+#
+CONFIG_DEBUG_LEVEL=0

debug.html

@@ -0,0 +1,313 @@
+<!doctype html>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+
+<title>v86 (debug)</title>
+<meta name="viewport" content="width=device-width,minimum-scale=1.0,maximum-scale=1.0,user-scalable=no,interactive-widget=resizes-content">
+
+<script src="build/capstone-x86.min.js"></script>
+<script src="build/libwabt.cjs"></script>
+<script type="module" src="src/browser/main.js"></script>
+
+<link rel="stylesheet" href="v86.css">
+
+<div>
+    <div id="boot_options">
+        <h4>Debugger</h4>
+        <input type="button" value="ReactOS" id="start_reactos">
+        <input type="button" value="ReactOS (boot)" id="start_reactos-boot">
+        <br>
+
+        <input type="button" value="MS-DOS" id="start_msdos">
+        <input type="button" value="FreeDOS" id="start_freedos">
+        <input type="button" value="FreeDOS with FreeGEM" id="start_freegem">
+        <br>
+
+        <input type="button" value="Windows 1.01" id="start_windows1">
+        <input type="button" value="Windows 3.0" id="start_windows30">
+        <input type="button" value="Windows 3.1" id="start_windows31">
+        <input type="button" value="Windows 95" id="start_windows95">
+        <input type="button" value="Windows 95 (boot)" id="start_windows95-boot">
+        <br>
+        <input type="button" value="Windows 98" id="start_windows98">
+        <input type="button" value="Windows 98 (boot)" id="start_windows98-boot">
+        <input type="button" value="Windows NT 3.1" id="start_windowsnt3">
+        <input type="button" value="Windows NT 4.0" id="start_windowsnt4">
+        <input type="button" value="Windows 2000" id="start_windows2000">
+        <input type="button" value="Windows 2000 (boot)" id="start_windows2000-boot">
+        <br>
+
+        <input type="button" value="Linux 2.6 (Buildroot)" id="start_linux26">
+        <input type="button" value="Linux 3.18 (Buildroot)" id="start_linux3">
+        <input type="button" value="Linux 4.16 (Buildroot)" id="start_linux4">
+        <input type="button" value="Linux 5.6 (Buildroot)" id="start_buildroot">
+        <input type="button" value="Tiny Core" id="start_tinycore">
+        <input type="button" value="OpenWRT" id="start_openwrt">
+        <br>
+        <input type="button" value="Arch Linux" id="start_archlinux">
+        <input type="button" value="Arch Linux (boot)" id="start_archlinux-boot">
+        <input type="button" value="Damn Small Linux" id="start_dsl">
+        <br>
+
+        <input type="button" value="FreeBSD" id="start_freebsd">
+        <input type="button" value="FreeBSD (boot)" id="start_freebsd-boot">
+        <input type="button" value="OpenBSD" id="start_openbsd">
+        <input type="button" value="NetBSD" id="start_netbsd">
+        <br>
+
+        <input type="button" value="Haiku" id="start_haiku">
+        <input type="button" value="Haiku (boot)" id="start_haiku-boot">
+        <input type="button" value="Minix" id="start_minix">
+        <input type="button" value="SerenityOS" id="start_serenity">
+        <input type="button" value="QNX" id="start_qnx">
+        <input type="button" value="9front" id="start_9front">
+        <br>
+
+        <input type="button" value="Oberon" id="start_oberon">
+        <input type="button" value="KolibriOS" id="start_kolibrios">
+        <input type="button" value="Solar OS" id="start_solos">
+        <input type="button" value="Bootchess" id="start_bootchess">
+        <input type="button" value="HelenOS" id="start_helenos">
+        <br>
+
+        <!--
+        <hr>
+        Restore state: <input type="file" id="restore_state">
+        -->
+
+        <br>
+        <hr>
+
+        <table>
+            <tr>
+                <td width="350"><label for="cdrom_image">CD image</label></td>
+                <td>
+                    <input type="file" id="cdrom_image">
+                </td>
+            </tr>
+
+            <tr>
+                <td><label for="floppy_image">Floppy disk image</label></td>
+                <td><input type="file" id="fda_image"> or <a id="fda_toggle_empty_disk">create empty floppy disk</a><br></td>
+            </tr>
+
+            <tr>
+                <td><label for="floppy_image">Second floppy disk image</label></td>
+                <td><input type="file" id="fdb_image"> or <a id="fdb_toggle_empty_disk">create empty floppy disk</a><br></td>
+            </tr>
+
+            <tr>
+                <td><label for="hda_image">Hard disk image</label></td>
+                <td><input type="file" id="hda_image"> or <a id="hda_toggle_empty_disk">create empty hard disk</a><br></td>
+            </tr>
+
+            <tr>
+                <td>Second hard disk image</td>
+                <td><input type="file" id="hdb_image"> or <a id="hdb_toggle_empty_disk">create empty hard disk</a><br></td>
+            </tr>
+
+            <tr>
+                <td><label for="multiboot_image">Multiboot kernel image (experimental)</label></td>
+                <td><input type="file" id="multiboot_image"><br></td>
+            </tr>
+
+            <tr>
+                <td><label for="bzimage">Kernel image (bzimage)</label></td>
+                <td><input type="file" id="bzimage"><br></td>
+            </tr>
+            <tr>
+                <td><label for="initrd">initrd</label></td>
+                <td><input type="file" id="initrd"><br></td>
+            </tr>
+
+            <tr>
+                <td><label for="bios">BIOS</label></td>
+                <td><input type="file" id="bios"><br></td>
+            </tr>
+
+            <tr>
+                <td><label for="vga_bios">VGA BIOS</label></td>
+                <td><input type="file" id="vga_bios"><br></td>
+            </tr>
+
+            <tr>
+                <td colspan="2"><small>Disk images are not uploaded to the server</small><hr></td>
+            </tr>
+
+            <tr>
+                <td><label for="memory_size">Memory size</label></td>
+                <td>
+                    <input id="memory_size" type="number" value="128" min="16" max="2048" step="16"> MB<br>
+                </td>
+            </tr>
+
+            <tr>
+                <td><label for="vga_memory_size">Video Memory size</label></td>
+                <td>
+                    <input id="vga_memory_size" type="number" value="8" min="1" max="128" step="1"> MB<br>
+                </td>
+            </tr>
+
+            <tr>
+                <td><label for="relay_url">Networking proxy (leave blank to disable)</label></td>
+                <td>
+                    <input id="relay_url" type="text" value="wss://relay.widgetry.org/">
+                </td>
+            </tr>
+
+            <tr>
+                <td colspan="2"><hr></td>
+            </tr>
+
+            <tr>
+                <td><label for="disable_audio">Disable audio</label></td>
+                <td>
+                    <input id="disable_audio" type="checkbox"><br>
+                </td>
+            </tr>
+
+            <tr>
+                <td><label for="acpi">Enable ACPI (experimental)</label></td>
+                <td>
+                    <input id="acpi" type="checkbox"><br>
+                </td>
+            </tr>
+
+            <tr>
+                <td colspan="2"><hr></td>
+            </tr>
+
+            <tr>
+                <td><label for="boot_order">Boot order</label></td>
+                <td>
+                    <select id="boot_order">
+                        <option value="0">Auto</option>
+                        <option value="213">CD / Floppy / Hard Disk</option>
+                        <option value="123">CD / Hard Disk / Floppy</option>
+                        <option value="231">Floppy / CD / Hard Disk</option>
+                        <option value="321">Floppy / Hard Disk / CD</option>
+                        <option value="312">Hard Disk / Floppy / CD</option>
+                        <option value="132">Hard Disk / CD / Floppy</option>
+                    </select>
+                 </td>
+            </tr>
+        </table>
+
+        <br>
+        <button id="start_emulation">Start Emulation</button>
+        <br>
+        <br>
+    </div>
+
+    <div id="runtime_options" style="display: none">
+        <input type="button" value="Dump Registers" id="dump_regs">
+        <input type="button" value="Dump GDT/LDT" id="dump_gdt">
+        <input type="button" value="Dump IDT" id="dump_idt">
+        <input type="button" value="Dump page tables" id="dump_pt">
+        <input type="button" value="Dump log" id="dump_log">
+        <br>
+
+        <input type="button" value="Pause" id="run">
+        <input type="button" value="Reset" id="reset">
+        <input type="button" value="Exit" id="exit">
+        <input type="button" value="Send Ctrl-Alt-Del" id="ctrlaltdel">
+        <input type="button" value="Send Alt-Tab" id="alttab">
+        <input type="button" value="Get floppy image" id="get_fda_image">
+        <input type="button" value="Get second floppy image" id="get_fdb_image">
+        <input type="button" value="Get hard disk image" id="get_hda_image">
+        <input type="button" value="Get second hard disk image" id="get_hdb_image">
+        <input type="button" value="Get CD-ROM image" id="get_cdrom_image">
+        <input type="button" value="Insert floppy image" id="change_fda_image">
+        <input type="button" value="Insert second floppy image" id="change_fdb_image">
+        <input type="button" value="Insert CD image" id="change_cdrom_image">
+        <input type="button" value="Save State" id="save_state">
+        <input type="button" value="Load State" id="load_state"> <input type="file" style="display: none" id="load_state_input">
+        <input type="button" value="Memory Dump" id="memory_dump">
+        <input type="button" value="Capture network traffic" id="capture_network_traffic">
+        <input type="button" value="Disable mouse" id="toggle_mouse">
+        <input type="button" value="Lock mouse" id="lock_mouse">
+        <input type="button" value="Go fullscreen" id="fullscreen">
+        <input type="button" value="Take screenshot" id="take_screenshot">
+        <input type="button" value="Mute" id="mute">
+        <input type="button" value="Enable theatre mode" id="toggle_theatre">
+        <input type="button" style="display: none" value="Enable zoom to fit" id="toggle_zoom_to_fit">
+
+        <label>
+            Scale:
+            <input type="number" min="0.25" step="0.25" value="1.0" id="scale" style="width: 50px">
+        </label>
+    </div>
+
+    <pre style="margin: 0" id="log_levels"></pre>
+    <pre style="display: none" id="loading"></pre>
+    <br>
+</div>
+
+<div id="screen_container" style="display: none">
+    <div id="screen"></div>
+    <canvas id="vga"></canvas>
+
+    <div style="position: absolute; top: 0; z-index: 10">
+        <textarea class="phone_keyboard"></textarea>
+    </div>
+</div>
+
+
+<div id="runtime_infos" style="display: none">
+    Running: <span id="running_time">0s</span> <br>
+    Speed: <span id="speed">0</span> mIPS<br>
+    Avg speed: <span id="avg_speed">0</span> mIPS<br>
+    <br>
+    <div id="info_storage" style="display: none">
+        <b>IDE device<span id="ide_type"></span></b><br>
+        Sectors read: <span id="info_storage_sectors_read">0</span><br>
+        Bytes read: <span id="info_storage_bytes_read">0</span><br>
+        Sectors written: <span id="info_storage_sectors_written">0</span><br>
+        Bytes written: <span id="info_storage_bytes_written">0</span><br>
+        Status: <span id="info_storage_status"></span><br>
+        <br>
+    </div>
+    <div id="info_filesystem" style="display: none">
+        <b>9p Filesystem</b><br>
+        Bytes read: <span id="info_filesystem_bytes_read">0</span><br>
+        Bytes written: <span id="info_filesystem_bytes_written">0</span><br>
+        <div style="white-space: nowrap; overflow-x: hidden">Last file: <span id="info_filesystem_last_file"></span></div>
+        Status: <span id="info_filesystem_status"></span><br>
+        <br>
+    </div>
+    <div id="info_network" style="display: none">
+        <b>Network</b><br>
+        Bytes received: <span id="info_network_bytes_received">0</span><br>
+        Bytes transmitted: <span id="info_network_bytes_transmitted">0</span><br>
+        <br>
+    </div>
+    <b>VGA</b><br>
+    Mode: <span id="info_vga_mode"></span><br>
+    Resolution: <span id="info_res">-</span><br>
+    <br>
+    Mouse: <span id="info_mouse_enabled">No</span><br>
+</div>
+
+<div id="filesystem_panel" style="display: none">
+    <label>
+        Send files to emulator<br>
+        <input type="file" id="filesystem_send_file" multiple>
+    </label>
+    <br><br>
+    <label>
+        Get file from emulator<br>
+        <input type="text" id="filesystem_get_file" placeholder="Absolute path">
+    </label>
+</div>
+
+<div id="debug_panel" style="display: none">
+</div>
+
+<br style="clear: both"><br>
+
+<textarea spellcheck="false" cols="40" rows="12" id="serial" style="display: none">
+</textarea>
+
+<div id="terminal"></div>
+
+<input type="button" value="Hide UI" id="toggle_ui" style="display: none">
+<div id="theatre_background" style="display: none"></div>

docs/.gitignore

@@ -0,0 +1 @@
+node_modules

docs/archlinux.md

@@ -0,0 +1,491 @@
+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:
+```sh
+#!/bin/bash
+echo "Creating a GPT partition on /dev/sda1"
+echo -e "g\nn\n\n\n\nw" | fdisk /dev/sda
+
+# In case you might want to create a DOS partition instead. It doesn't really matter.
+#echo "Creating a DOS partition on /dev/sda1"
+#echo -e "o\nn\np\n1\n\n\nw" | fdisk /dev/sda
+
+echo "Formatting /dev/sda1 to ext4"
+mkfs -t ext4 /dev/sda1
+
+echo "Mounting new filesystem"
+mount -t ext4 /dev/sda1 /mnt
+
+echo "Create pacman package cache dir"
+mkdir -p /mnt/var/cache/pacman/pkg
+
+# We don't want the pacman cache to fill up the image. After reboot whatever tarballs pacman has cached are gone.
+echo "Mount the package cache dir in memory so it doesn't fill up the image"
+mount -t tmpfs none /mnt/var/cache/pacman/pkg
+
+echo "Updating archlinux-keyring"
+pacman -Sy archlinux-keyring --noconfirm
+
+# uncomment to remove signing if unable to resolve signing errors
+sed -i 's/SigLevel.*/SigLevel = Never/g' /etc/pacman.conf
+
+# Install the Arch Linux base system, feel free to add packages you need here
+echo "Performing pacstrap"
+pacstrap -i /mnt base linux dhcpcd curl openssh --noconfirm
+
+echo "Writing fstab"
+genfstab -p /mnt >> /mnt/etc/fstab
+
+# When the Linux boots we want it to automatically log in on tty1 as root
+echo "Ensuring root autologin on tty1"
+mkdir -p /mnt/etc/systemd/system/getty@tty1.service.d
+cat << 'EOF' > /mnt/etc/systemd/system/getty@tty1.service.d/override.conf
+[Service]
+ExecStart=
+ExecStart=-/usr/bin/agetty --autologin root --noclear %I $TERM
+EOF
+
+# This is the tricky part. The current root will be mounted on /dev/sda1 but after we reboot
+# it will try to mount root during boot using the 9p network filesystem. This means the emulator
+# will request all files over the network using XMLHttpRequests from the server. This is great
+# because then you only need to provide the client with a saved state (the memory) and the
+# session will start instantly and load needed files on the fly. This is fast and it saves bandwidth.
+echo "Ensuring root is remounted using 9p after reboot"
+mkdir -p /mnt/etc/initcpio/hooks
+cat << 'EOF' > /mnt/etc/initcpio/hooks/9p_root
+run_hook() {
+    mount_handler="mount_9p_root"
+}
+
+mount_9p_root() {
+    msg ":: mounting '$root' on real root (9p)"
+    # Note the host9p. We won't mount /dev/sda1 on root anymore,
+    # instead we mount the network filesystem and the emulator will
+    # retrieve the files on the fly.
+    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
+}
+EOF
+
+echo "Adding initcpio build hook for 9p root remount"
+mkdir -p /mnt/etc/initcpio/install
+cat << 'EOF' > /mnt/etc/initcpio/install/9p_root
+#!/bin/bash
+build() {
+	add_runscript
+}
+EOF
+
+# We need to load some modules into the kernel for it to play nice with the emulator
+# The atkbd and i8042 modules are for keyboard input in the browser. If you do not
+# want to use the network filesystem you only need these. The 9p, 9pnet and 9pnet_virtio
+# modules are needed for being able to mount 9p network filesystems using the emulator.
+echo "Configure mkinitcpio for 9p"
+sed -i 's/MODULES=()/MODULES=(atkbd i8042 libps2 serio serio_raw psmouse virtio_pci virtio_pci_modern_dev 9p 9pnet 9pnet_virtio fscache netfs)/g' /mnt/etc/mkinitcpio.conf
+
+# Because we want to mount the root filesystem over the network during boot, we need to
+# hook into initcpio. If you do not want to mount the root filesystem during boot but
+# only want to mount a 9p filesystem later, you can leave this out. Once the system
+# has been booted you should be able to mount 9p filesystems with mount -t 9p host9p /blabla
+# without this hook.
+sed -i 's/fsck"/fsck 9p_root"/g' /mnt/etc/mkinitcpio.conf
+
+# enable ssh password auth and root login
+sed -i 's/#PermitRootLogin.*/PermitRootLogin yes/g' /etc/ssh/sshd_config
+sed -i 's/#PasswordAuthentication.*/PasswordAuthentication yes/g' /etc/ssh/sshd_config
+
+echo "Writing the installation script"
+cat << 'EOF' > /mnt/bootstrap.sh
+#!/usr/bin/bash
+echo "Re-generate initial ramdisk environment"
+mkinitcpio -p linux
+
+# uncomment to remove signing if you are unable to resolve signing errors otherwise
+sed -i 's/SigLevel.*/SigLevel = Never/g' /etc/pacman.conf
+
+pacman -S --noconfirm syslinux gptfdisk
+syslinux-install_update -i -a -m
+
+# disabling ldconfig to speed up boot (to remove Rebuild dynamic linker cache...)
+# you may want to comment this out
+echo "Disabling ldconfig service"
+systemctl mask ldconfig.service
+
+sync
+EOF
+
+echo "Chrooting and bootstrapping the installation"
+arch-chroot /mnt bash bootstrap.sh
+
+
+cat << 'EOF' > /mnt/boot/syslinux/syslinux.cfg
+# Config file for Syslinux -
+# /boot/syslinux/syslinux.cfg
+#
+# Comboot modules:
+#   * menu.c32 - provides a text menu
+#   * vesamenu.c32 - provides a graphical menu
+#   * chain.c32 - chainload MBRs, partition boot sectors, Windows bootloaders
+#   * hdt.c32 - hardware detection tool
+#   * reboot.c32 - reboots the system
+#
+# To Use: Copy the respective files from /usr/lib/syslinux to /boot/syslinux.
+# If /usr and /boot are on the same file system, symlink the files instead
+# of copying them.
+#
+# If you do not use a menu, a 'boot:' prompt will be shown and the system
+# will boot automatically after 5 seconds.
+#
+# Please review the wiki: https://wiki.archlinux.org/index.php/Syslinux
+# The wiki provides further configuration examples
+
+DEFAULT arch
+PROMPT 0        # Set to 1 if you always want to display the boot: prompt
+TIMEOUT 100
+
+# Menu Configuration
+# Either menu.c32 or vesamenu32.c32 must be copied to /boot/syslinux
+UI menu.c32
+#UI vesamenu.c32
+
+# Refer to http://syslinux.zytor.com/wiki/index.php/Doc/menu
+MENU TITLE Arch Linux
+#MENU BACKGROUND splash.png
+MENU COLOR border       30;44   #40ffffff #a0000000 std
+MENU COLOR title        1;36;44 #9033ccff #a0000000 std
+MENU COLOR sel          7;37;40 #e0ffffff #20ffffff all
+MENU COLOR unsel        37;44   #50ffffff #a0000000 std
+MENU COLOR help         37;40   #c0ffffff #a0000000 std
+MENU COLOR timeout_msg  37;40   #80ffffff #00000000 std
+MENU COLOR timeout      1;37;40 #c0ffffff #00000000 std
+MENU COLOR msg07        37;40   #90ffffff #a0000000 std
+MENU COLOR tabmsg       31;40   #30ffffff #00000000 std
+
+# boot sections follow
+#
+# TIP: If you want a 1024x768 framebuffer, add "vga=773" to your kernel line.
+#
+#-*
+
+LABEL arch
+    MENU LABEL Arch Linux 9p
+    LINUX ../vmlinuz-linux
+    APPEND root=/dev/sda1 rw quiet
+    INITRD ../initramfs-linux.img
+
+LABEL arch2
+    MENU LABEL Arch Linux Disk
+    LINUX ../vmlinuz-linux
+    APPEND root=/dev/sda1 rw quiet disablehooks=9p_root
+    INITRD ../initramfs-linux.img
+
+LABEL hdt
+        MENU LABEL HDT (Hardware Detection Tool)
+        COM32 hdt.c32
+
+LABEL reboot
+        MENU LABEL Reboot
+        COM32 reboot.c32
+
+LABEL poweroff
+        MENU LABEL Poweroff
+        COM32 poweroff.c32
+EOF
+umount -R /mnt
+```
+
+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`.

docs/cpu-idling.md

@@ -0,0 +1,26 @@
+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.

docs/filesystem.md

@@ -0,0 +1,97 @@
+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

docs/how-it-works.md

@@ -0,0 +1,81 @@
+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).

docs/linux-9p-image.md

@@ -0,0 +1,58 @@
+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
+```

docs/networking.md

@@ -0,0 +1,218 @@
+# 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] ["/" ...]`<br>`"wss://" PROXY [":" PORT=443] ["/" ...]` | `wss://relay.widgetry.org/` |
+| **[wisp](#the-wisp-backend)** | `"wisp://" PROXY [":" PORT=80] ["/" ...]`<br>`"wisps://" PROXY [":" PORT=443] ["/" ...]` | `wisp://localhost:12345` |
+| **[fetch](#the-fetch-backend)** | `"fetch" [ "://" PROXY [":" PORT] ["/" QUERY] ]` | `fetch`<br>`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`.
+
+#### General `net_device` settings
+
+Common options in `config.net_device`:
+
+| net_device    | type | description |
+| :------------ | :--- | :--- |
+| **type**      | str  | The type of emulated NIC provided to the guest OS, either `ne2k` or `virtio`. Default: `ne2k`. |
+| **relay_url** | str  | The network backend URL, see [Backend URL schemes](#backend-url-schemes) for details. Note that the CORS proxy server of the `fetch` backend is defined in field `cors_proxy` below. This option is required. |
+| **id**        | int  | Network id, all v86 network instances with the same id share the same network namespace. Default: `0`.<br>*(TODO: class `NetworkAdapter` should also get options.net_device as an argument, at least options.net_device.id).* |
+
+#### Special `net_device` settings
+
+Backends `fetch` and `wisp` support a couple of special settings in `config.net_device` to control virtual network components emulated by the backend:
+
+| net_device     | type | description |
+| :------------- | :--- | :--- |
+| **router_mac** | str  | MAC address of virtual network peers (ARP, PING, DHCP, DNS, NTP, UDP echo and TCP peers) in common MAC address notation. Default `52:54:0:1:2:3`. |
+| **router_ip**  | str  | IP address of virtual network peers (ARP, PING, DHCP, DNS and TCP peers) in dotted IP notation. Default `192.168.86.1`. |
+| **vm_ip**      | str  | IP address to be assigned to the guest by DHCP in dotted IP notation. Default `192.168.86.100`. |
+| **masquerade** | bool | If `True`, announce `router_ip` as the router's and DNS server's IP addresses in generated DHCP replies, and also generate ARP replies to IPs outside the router's subnet `255.255.255.0`. Default: `True`. |
+| **dns_method** | str  | DNS method to use, either `static` or `doh`. `static`: use built-in DNS server, `doh`: use [DNS-over-HTTPS](https://en.wikipedia.org/wiki/DNS_over_HTTPS) (DoH). Defaults to `static` for `fetch` and to `doh` for `wisp` backend. |
+| **doh_server** | str  | Host name or IP address (and optional port number) of the DoH server if `dns_method` is `doh`. The value is expanded to the URL `https://DOH_SERVER/dns-query`. Default: `cloudflare-dns.com`. |
+| **cors_proxy** | str  | CORS proxy server URL, do not use a proxy if undefined. Default: undefined (`fetch` backend only). |
+
+#### 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
+
+[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://<port>.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))

docs/profiling.md

@@ -0,0 +1,7 @@
+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.

docs/sse-shifts.txt

@@ -0,0 +1,39 @@
+   0F F1     PSLLW 	mm 	mm/m64 	       mmx 	       Shift Packed Data Left Logical
+66 0F F1     PSLLW 	xmm 	xmm/m128       sse2 	       Shift Packed Data Left Logical
+   0F F2     PSLLD 	mm 	mm/m64 	       mmx 	       Shift Packed Data Left Logical
+66 0F F2     PSLLD 	xmm 	xmm/m128       sse2 	       Shift Packed Data Left Logical
+   0F F3     PSLLQ 	mm 	mm/m64 	       mmx 	       Shift Packed Data Left Logical
+66 0F F3     PSLLQ 	xmm 	xmm/m128       sse2 	       Shift Packed Data Left Logical
+
+   0F E1     PSRAW 	mm 	mm/m64 	       mmx             Shift Packed Data Right Arithmetic
+66 0F E1     PSRAW 	xmm 	xmm/m128       sse2	       Shift Packed Data Right Arithmetic
+   0F E2     PSRAD 	mm 	mm/m64 	       mmx	       Shift Packed Data Right Arithmetic
+66 0F E2     PSRAD 	xmm 	xmm/m128       sse2	       Shift Packed Data Right Arithmetic
+
+   0F D1     PSRLW 	mm 	mm/m64 	       mmx 	       Shift Packed Data Right Logical
+66 0F D1     PSRLW 	xmm 	xmm/m128       sse2 	       Shift Packed Data Right Logical
+   0F D2     PSRLD 	mm 	mm/m64 	       mmx 	       Shift Packed Data Right Logical
+66 0F D2     PSRLD 	xmm 	xmm/m128       sse2 	       Shift Packed Data Right Logical
+   0F D3     PSRLQ 	mm 	mm/m64 	       mmx 	       Shift Packed Data Right Logical
+66 0F D3     PSRLQ 	xmm 	xmm/m128       sse2 	       Shift Packed Data Right Logical
+
+   0F 71     PSRLW 	mm 	imm8 	       mmx 	       Shift Packed Data Right Logical
+66 0F 71     PSRLW 	xmm 	imm8 	       sse2 	       Shift Packed Data Right Logical
+   0F 71     PSRAW 	mm 	imm8 	       mmx 	       Shift Packed Data Right Arithmetic
+66 0F 71     PSRAW 	xmm 	imm8 	       sse2 	       Shift Packed Data Right Arithmetic
+   0F 71     PSLLW 	mm 	imm8 	       mmx 	       Shift Packed Data Left Logical
+66 0F 71     PSLLW 	xmm 	imm8 	       sse2 	       Shift Packed Data Left Logical
+
+   0F 72     PSRLD 	mm 	imm8 	       mmx 	       Shift Double Quadword Right Logical
+66 0F 72     PSRLD 	xmm 	imm8 	       sse2 	       Shift Double Quadword Right Logical
+   0F 72     PSRAD 	mm 	imm8 	       mmx 	       Shift Packed Data Right Arithmetic
+66 0F 72     PSRAD 	xmm 	imm8 	       sse2 	       Shift Packed Data Right Arithmetic
+   0F 72     PSLLD 	mm 	imm8 	       mmx 	       Shift Packed Data Left Logical
+66 0F 72     PSLLD 	xmm 	imm8 	       sse2 	       Shift Packed Data Left Logical
+
+   0F 73     PSRLQ 	mm 	imm8 	       mmx 	       Shift Packed Data Right Logical
+66 0F 73     PSRLQ 	xmm 	imm8 	       sse2 	       Shift Packed Data Right Logical
+66 0F 73     PSRLDQ 	xmm 	imm8 	       sse2 	       Shift Double Quadword Right Logical
+   0F 73     PSLLQ 	mm 	imm8 	       mmx 	       Shift Packed Data Left Logical
+66 0F 73     PSLLQ 	xmm 	imm8 	       sse2 	       Shift Packed Data Left Logical
+66 0F 73     PSLLDQ 	xmm 	imm8 	       sse2 	       Shift Double Quadword Left Logical

docs/windows-9x.md

@@ -0,0 +1,106 @@
+## 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 -hda hdd.img
+```
+ - 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.
+6. (optionally) If "Windows protection" errors appears on startup, apply [FIX95CPU](http://lonecrusader.x10host.com/fix95cpu.html) or [patcher9x](https://github.com/JHRobotics/patcher9x#installation).
+
+> [!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.
+
+## 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 640x480x8 video mode, to fix this, install **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.
+
+## 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:
+
+```
+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":
+
+```
+Interrupt Request: 10
+Input/Output Range: 0300 - 031F
+```
+
+7. In "Control Panel", open "Network", click on "Add", choose "Protocol" and select the following options:
+
+```
+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://www.claunia.com/qemu/drivers/index.html.
+
+1. Open "Start" menu, click on "Control Panel" and "Add New Hardware".
+2. Press "Next", select "No" and select the following options:
+
+```
+Hardware type: Sound, video and game cotrollers
+Manufacturers: Creative Labs
+Models: Creative Labs Sound Blaster 16 or AWE-32
+```
+
+3. Restart Windows.

docs/windows-nt.md

@@ -0,0 +1,169 @@
+
+ - [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 -hda hdd.img -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 -hda hdd.img -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 -hda hdd.img -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
+});
+```
+
+
+## Windows 2000/XP
+
+### Installing using QEMU
+
+1. Run QEMU with the following settings for installation: 
+
+```sh
+qemu-system-i386 -m 512 -hda hdd.img -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 -hda hdd.img -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".

eslint.config.mjs

@@ -0,0 +1,140 @@
+export default [
+    {
+        "languageOptions": {
+            "globals": {
+                "process": "readonly",
+                "window": "writable",
+                "navigator": "writable",
+                "location": "writable",
+                "document": "readonly",
+                "console": "readonly",
+                "crypto": "readonly",
+                "alert": "readonly",
+                "performance": "readonly",
+                "URL": "readonly",
+                "WebAssembly": "readonly",
+
+                "setTimeout": "readonly",
+                "setInterval": "readonly",
+                "clearTimeout": "readonly",
+                "clearInterval": "readonly",
+                "requestAnimationFrame": "readonly",
+                "cancelAnimationFrame": "readonly",
+
+                "Buffer": "readonly",
+                "FileReader": "readonly",
+                "TextEncoder": "readonly",
+                "TextDecoder": "readonly",
+                "fetch": "readonly",
+                "Headers": "readonly",
+                "Response": "readonly",
+                "WebSocket": "readonly",
+                "Blob": "readonly",
+                "File": "readonly",
+                "XMLHttpRequest": "readonly",
+                "URLSearchParams": "readonly",
+                "ImageData": "readonly",
+                "Image": "readonly",
+                "OffscreenCanvas": "readonly",
+                "BroadcastChannel": "readonly",
+
+                "AudioContext": "readonly",
+                "AudioWorkletProcessor": "readonly",
+                "webkitAudioContext": "readonly",
+                "AudioWorkletNode": "readonly",
+                "Worker": "readonly",
+                "postMessage": "readonly",
+                "importScripts": "readonly",
+
+                "DEBUG": "writable"
+            }
+        },
+        rules: {
+            "eol-last": "error",
+            //"no-extra-parens": "error",
+            "no-trailing-spaces": "error",
+            "no-extra-semi": "error",
+            "no-tabs": "error",
+            "quotes": ["error", "double", { "avoidEscape": true, "allowTemplateLiterals": true }],
+            "keyword-spacing": ["error", { "overrides": {
+                "if": { "after": false },
+                "for": { "after": false },
+                "while": { "after": false },
+                "switch": { "after": false },
+                "catch": { "after": false },
+            } }],
+            "semi": "error",
+            "no-useless-return": "error",
+            "eqeqeq": "error",
+            "no-multiple-empty-lines": ["error", { "max": 2, "maxBOF": 0, "maxEOF": 0 }],
+            //"no-var": "error",
+            "radix": "error",
+            "comma-style": ["error", "last"],
+            //"comma-dangle": ["error", "always-multiline"],
+            "no-sequences": "error",
+            //"one-var": ["error", "never"],
+            "constructor-super": "error",
+            "for-direction": "error",
+            "getter-return": "error",
+            "no-async-promise-executor": "error",
+            //"no-case-declarations": "error",
+            "no-class-assign": "error",
+            "no-compare-neg-zero": "error",
+            "no-cond-assign": "error",
+            "no-const-assign": "error",
+            "no-constant-binary-expression": "error",
+            //"no-constant-condition": "error",
+            //"no-control-regex": "error",
+            //"no-debugger": "error",
+            "no-delete-var": "error",
+            "no-dupe-args": "error",
+            "no-dupe-class-members": "error",
+            //"no-dupe-else-if": "error",
+            "no-dupe-keys": "error",
+            "no-duplicate-case": "error",
+            //"no-empty": "error",
+            "no-empty-character-class": "error",
+            "no-empty-pattern": "error",
+            "no-empty-static-block": "error",
+            "no-ex-assign": "error",
+            "no-extra-boolean-cast": "error",
+            "no-fallthrough": "error",
+            "no-func-assign": "error",
+            "no-global-assign": "error",
+            "no-import-assign": "error",
+            "no-invalid-regexp": "error",
+            "no-irregular-whitespace": "error",
+            "no-loss-of-precision": "error",
+            "no-misleading-character-class": "error",
+            "no-new-native-nonconstructor": "error",
+            "no-nonoctal-decimal-escape": "error",
+            "no-obj-calls": "error",
+            "no-octal": "error",
+            "no-prototype-builtins": "error",
+            //"no-redeclare": "error",
+            "no-regex-spaces": "error",
+            "no-self-assign": "error",
+            "no-setter-return": "error",
+            "no-shadow-restricted-names": "error",
+            "no-sparse-arrays": "error",
+            "no-this-before-super": "error",
+            "no-undef": "error",
+            "no-unexpected-multiline": "error",
+            //"no-unreachable": "error",
+            "no-unsafe-finally": "error",
+            "no-unsafe-negation": "error",
+            "no-unsafe-optional-chaining": "error",
+            "no-unused-labels": "error",
+            "no-unused-private-class-members": "error",
+            //"no-unused-vars": "error",
+            "no-useless-backreference": "error",
+            "no-useless-catch": "error",
+            //"no-useless-escape": "error",
+            "no-with": "error",
+            "require-yield": "error",
+            "use-isnan": "error",
+            "valid-typeof": "error",
+            "strict": "error"
+        }
+    }
+];

examples/alpine.html

@@ -0,0 +1,29 @@
+<!doctype html>
+<title>Alpine</title>
+<script src="../build/libv86.js"></script>
+<script>
+"use strict";
+window.onload = function()
+{
+    var emulator = new V86({
+        wasm_path: "../build/v86.wasm",
+        memory_size: 512 * 1024 * 1024,
+        vga_memory_size: 8 * 1024 * 1024,
+        screen_container: document.getElementById("screen_container"),
+        bios: { url: "../bios/seabios.bin" },
+        vga_bios: { url: "../bios/vgabios.bin" },
+        filesystem: {
+            baseurl: "../images/alpine-rootfs-flat",
+            basefs: "../images/alpine-fs.json",
+        },
+        autostart: true,
+        bzimage_initrd_from_filesystem: true,
+        cmdline: "rw root=host9p rootfstype=9p rootflags=trans=virtio,cache=loose modules=virtio_pci tsc=reliable",
+        //initial_state: { url: "../images/alpine-state.bin" },
+    });
+};
+</script>
+<div id="screen_container">
+    <div style="white-space: pre; font: 14px monospace; line-height: 14px"></div>
+    <canvas style="display: none"></canvas>
+</div>

examples/arch.html

@@ -0,0 +1,78 @@
+<!doctype html>
+<title>Archlinux</title>
+
+<script src="../build/libv86.js"></script>
+<script>
+"use strict";
+
+window.onload = function()
+{
+    var emulator = new V86({
+        wasm_path: "../build/v86.wasm",
+        memory_size: 512 * 1024 * 1024,
+        vga_memory_size: 8 * 1024 * 1024,
+        screen_container: document.getElementById("screen_container"),
+        bios: {
+            url: "../bios/seabios.bin",
+        },
+        vga_bios: {
+            url: "../bios/vgabios.bin",
+        },
+        filesystem: {
+            baseurl: "../images/arch/",
+            basefs: "../images/fs.json",
+        },
+        autostart: true,
+        bzimage_initrd_from_filesystem: true,
+        cmdline: [
+            "rw",
+            "root=host9p rootfstype=9p rootflags=trans=virtio,cache=loose",
+            "init=/usr/bin/init-openrc",
+        ].join(" "),
+    });
+
+    document.getElementById("save_file").onclick = async function()
+    {
+        const new_state = await emulator.save_state();
+
+        var a = document.createElement("a");
+        a.download = "v86state.bin";
+        a.href = window.URL.createObjectURL(new Blob([new_state]));
+        a.dataset.downloadurl = "application/octet-stream:" + a.download + ":" + a.href;
+        a.click();
+
+        this.blur();
+    };
+
+    document.getElementById("restore_file").onchange = function()
+    {
+        if(this.files.length)
+        {
+            var filereader = new FileReader();
+            emulator.stop();
+
+            filereader.onload = async function(e)
+            {
+                await emulator.restore_state(e.target.result);
+                emulator.run();
+            };
+
+            filereader.readAsArrayBuffer(this.files[0]);
+
+            this.value = "";
+        }
+
+        this.blur();
+    };
+};
+</script>
+
+<input id="save_file" type="button" value="Save state to file">
+Restore from file: <input id="restore_file" type="file">
+<hr>
+
+<!-- A minimal structure for the ScreenAdapter defined in browser/screen.js -->
+<div id="screen_container">
+    <div style="white-space: pre; font: 14px monospace; line-height: 14px"></div>
+    <canvas style="display: none"></canvas>
+</div>

examples/async_load.html

@@ -0,0 +1,43 @@
+<!doctype html>
+<title>Asynchronous loading of disk images</title>
+
+<script src="../build/libv86.js"></script>
+<script>
+"use strict";
+
+window.onload = function()
+{
+    // Async loading of the iso image
+    // Note how the emulation starts without downloading the 50MB image
+
+    // Support of the "Range: bytes=..." header is required on the server, CORS
+    // is required if the server is on a different host
+
+    var emulator = new V86({
+        wasm_path: "../build/v86.wasm",
+        memory_size: 64 * 1024 * 1024,
+        vga_memory_size: 2 * 1024 * 1024,
+        screen_container: document.getElementById("screen_container"),
+        bios: {
+            url: "../bios/seabios.bin",
+        },
+        vga_bios: {
+            url: "../bios/vgabios.bin",
+        },
+        cdrom: {
+            url: "../images/dsl-4.11.rc2.iso",
+            async: true,
+
+            // size can be determined automatically, but costs an extra request
+            // and might not work reliably
+            size: 52824064,
+        },
+        autostart: true,
+    });
+}
+</script>
+
+<div id="screen_container">
+    <div style="white-space: pre; font: 14px monospace; line-height: 14px"></div>
+    <canvas style="display: none"></canvas>
+</div>

examples/basic.html

@@ -0,0 +1,33 @@
+<!doctype html>
+<title>Basic Emulator</title><!-- not BASIC! -->
+
+<script src="../build/libv86.js"></script>
+<script>
+"use strict";
+
+window.onload = function()
+{
+    var emulator = window.emulator = new V86({
+        wasm_path: "../build/v86.wasm",
+        memory_size: 32 * 1024 * 1024,
+        vga_memory_size: 2 * 1024 * 1024,
+        screen_container: document.getElementById("screen_container"),
+        bios: {
+            url: "../bios/seabios.bin",
+        },
+        vga_bios: {
+            url: "../bios/vgabios.bin",
+        },
+        cdrom: {
+            url: "../images/linux.iso",
+        },
+        autostart: true,
+    });
+}
+</script>
+
+<!-- A minimal structure for the ScreenAdapter defined in browser/screen.js -->
+<div id="screen_container">
+    <div style="white-space: pre; font: 14px monospace; line-height: 14px"></div>
+    <canvas style="display: none"></canvas>
+</div>

examples/broadcast-network.html

@@ -0,0 +1,61 @@
+<!doctype html>
+<title>Networking via Broadcast Channel API</title>
+
+<script src="../build/libv86.js"></script>
+<script>
+"use strict";
+
+window.onload = function()
+{
+    var emulator = window.emulator = new V86({
+        wasm_path: "../build/v86.wasm",
+        memory_size: 64 * 1024 * 1024,
+        vga_memory_size: 2 * 1024 * 1024,
+        screen_container: document.getElementById("screen_container"),
+        bios: {
+            url: "../bios/seabios.bin",
+        },
+        vga_bios: {
+            url: "../bios/vgabios.bin",
+        },
+        bzimage: {
+            url: "../images/buildroot-bzimage68.bin",
+        },
+        autostart: true,
+    });
+
+    var broadcast = new BroadcastChannel("v86-network");
+
+    broadcast.addEventListener("message", function(e) {
+        emulator.bus.send("net0-receive", e.data);
+    });
+    emulator.add_listener("net0-send", function(packet) {
+        broadcast.postMessage(packet);
+    });
+}
+</script>
+
+<div id="screen_container">
+    <div style="white-space: pre; font: 14px monospace; line-height: 14px"></div>
+    <canvas style="display: none"></canvas>
+</div>
+
+<pre>
+# This example allows network across multiple browser tabs by using BroadcastChannels.
+
+# Configure a static IP
+ifconfig eth0 up arp 10.5.0.x
+
+# Ping by IP
+ping 10.5.0.x
+
+# Run a DNS server and send a query (10.5.0.x for server, 10.5.0.y for record)
+echo "anotherhost 10.5.0.y" | dnsd -c - -v    - server
+nslookup -type=a anotherhost 10.5.0.x         - client
+
+# Telnet calculator
+socat TCP-L:23,fork exec:bc
+
+# Simple HTTP server
+socat TCP-L:80,crlf,fork system:'echo HTTP/1.1 200 OK;echo;lua /root/test.lua'
+</pre>

examples/destroy.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<title>Destroyable Emulator</title>
+
+<script src="../build/libv86.js"></script>
+<script>
+"use strict";
+
+window.onload = function()
+{
+    var emulator = new V86({
+        wasm_path: "../build/v86.wasm",
+        memory_size: 32 * 1024 * 1024,
+        vga_memory_size: 2 * 1024 * 1024,
+        screen_container: document.getElementById("screen_container"),
+        bios: {
+            url: "../bios/seabios.bin",
+        },
+        vga_bios: {
+            url: "../bios/vgabios.bin",
+        },
+        cdrom: {
+            url: "../images/linux.iso",
+        },
+        autostart: true,
+    });
+
+    setTimeout(() => { emulator.destroy(); }, 1000);
+}
+</script>
+
+<div id="screen_container">
+    <div style="white-space: pre; font: 14px monospace; line-height: 14px"></div>
+    <canvas style="display: none"></canvas>
+</div>

examples/lang.html

@@ -0,0 +1,77 @@
+<!doctype html>
+<title>Basic Emulator</title><!-- not BASIC! -->
+
+<script src="../build/libv86.js"></script>
+<script>
+"use strict";
+
+window.onload = function()
+{
+    var start = Date.now();
+
+    setInterval(function()
+    {
+        document.getElementById("time").textContent = Math.round((Date.now() - start) / 1000);
+    }, 999);
+
+    var emulator = new V86({
+        wasm_path: "../build/v86.wasm",
+        memory_size: 512 * 1024 * 1024,
+        vga_memory_size: 8 * 1024 * 1024,
+        screen_container: document.getElementById("screen_container"),
+        bios: {
+            url: "../bios/seabios.bin",
+        },
+        vga_bios: {
+            url: "../bios/vgabios.bin",
+        },
+        initial_state: {
+            url: "../images/arch_state-v2.bin.zst",
+        },
+        filesystem: {
+            baseurl: "../images/arch/",
+        },
+        autostart: true,
+    });
+
+    document.getElementById("status").textContent += ".";
+
+    emulator.add_listener("emulator-ready", async function()
+    {
+        document.getElementById("status").textContent += ".";
+
+        var code = "console.log(3 * 7);\n";
+        var buffer = new Uint8Array(code.length);
+
+        buffer.set(code.split("").map(function(chr) { return chr.charCodeAt(0); }));
+
+        await emulator.create_file("/root/code.js", buffer);
+        emulator.serial0_send("node /root/code.js > /root/out.txt 2> /root/out.txt\n");
+    });
+
+    var serial_out = "";
+    emulator.add_listener("serial0-output-byte", async function(byte)
+    {
+        var chr = String.fromCharCode(byte);
+        serial_out += chr;
+
+        if(serial_out.endsWith("root@nyu"))
+        {
+            const data = await emulator.read_file("/root/out.txt");
+            document.getElementById("output").textContent += String.fromCharCode.apply(this, data);
+        }
+    });
+}
+</script>
+
+<pre><span id=time></span> <span id=status></span></pre>
+
+<!-- A minimal structure for the ScreenAdapter defined in browser/screen.js -->
+<div id="screen_container">
+    <div style="white-space: pre; font: 14px monospace; line-height: 14px"></div>
+    <canvas style="display: none"></canvas>
+</div>
+
+<hr>
+
+<pre id=output></pre>

examples/lua.html

@@ -0,0 +1,122 @@
+<!doctype html>
+<title>Lua interpreter</title>
+
+<script src="../build/libv86.js"></script>
+<script>
+"use strict";
+
+window.onload = function()
+{
+    var emulator = new V86({
+        wasm_path: "../build/v86.wasm",
+        memory_size: 32 * 1024 * 1024,
+        vga_memory_size: 2 * 1024 * 1024,
+
+        // Uncomment to see what's going on
+        //screen_container: document.getElementById("screen_container"),
+
+        bios: {
+            url: "../bios/seabios.bin",
+        },
+        vga_bios: {
+            url: "../bios/vgabios.bin",
+        },
+        bzimage: {
+            url: "../images/buildroot-bzimage68.bin",
+        },
+        autostart: true,
+        disable_keyboard: true,
+        disable_mouse: true,
+    });
+
+    var data = "";
+    var do_output = false;
+
+    emulator.add_listener("serial0-output-byte", function(byte)
+    {
+        var char = String.fromCharCode(byte);
+        if(char !== "\r")
+        {
+            data += char;
+        }
+
+        if(do_output)
+        {
+            document.getElementById("result").textContent += char;
+        }
+
+        if(data.endsWith("~% "))
+        {
+            console.log("Now ready");
+            document.getElementById("status").textContent = "Ready.\n";
+            document.getElementById("run").disabled = false;
+            do_output = false;
+        }
+    });
+
+    document.getElementById("source").onkeydown = function(e)
+    {
+        if(e.which == 13 && e.ctrlKey)
+        {
+            document.getElementById("run").onclick();
+        }
+    };
+
+    document.getElementById("run").onclick = function()
+    {
+        var code = document.getElementById("source").value;
+
+        emulator.serial0_send("lua -e " + bashEscape(code) + "\n");
+
+        document.getElementById("result").textContent = "";
+        document.getElementById("status").textContent = "Running ...\n";
+        this.disabled = true;
+
+        do_output = true;
+    };
+};
+
+// https://gist.github.com/creationix/2502704
+// Implement bash string escaping.
+function bashEscape(arg)
+{
+    arg = arg.replace(/\t+/g, "");
+    return "'" + arg.replace(/'+/g, function (val) {
+        return "'" + val.replace(/'/g, "\\'") + "'";
+    }) + "'";
+}
+</script>
+
+<textarea id=source rows=20 cols=80>
+k = 1
+x = 0
+
+while k &lt; 1000 do
+    x = x + 1 / (k * k)
+    k = k + 2
+end
+
+print(math.sqrt(x*8))
+
+function factorial(n)
+    if n == 0 then
+        return 1
+    else
+    return n * factorial(n - 1)
+    end
+end
+
+print("factorial(10):", factorial(10))
+</textarea>
+<button disabled id=run>run (ctrl-enter)</button>
+<br>
+<hr>
+<pre id=status>Wait for boot ...</pre>
+<pre id=result></pre>
+
+<hr>
+
+<div id="screen_container">
+    <div style="white-space: pre; font: 14px monospace; line-height: 14px"></div>
+    <canvas style="display: none"></canvas>
+</div>

examples/nodejs.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import fs from "node:fs";
+import url from "node:url";
+import { V86 } from "../build/libv86.mjs";
+
+const __dirname = url.fileURLToPath(new URL(".", import.meta.url));
+
+process.stdin.setRawMode(true);
+process.stdin.resume();
+process.stdin.setEncoding("utf8");
+
+console.log("Now booting, please stand by ...");
+
+var emulator = new V86({
+    bios: { url: __dirname + "/../bios/seabios.bin" },
+    vga_bios: { url: __dirname + "/../bios/vgabios.bin" },
+    cdrom: { url: __dirname + "/../images/linux4.iso" },
+    autostart: true,
+    net_device: {
+        type: "virtio",
+        relay_url: "fetch",
+    },
+});
+
+emulator.add_listener("serial0-output-byte", function(byte)
+{
+    var chr = String.fromCharCode(byte);
+    if(chr <= "~")
+    {
+        process.stdout.write(chr);
+    }
+});
+
+process.stdin.on("data", function(c)
+{
+    if(c === "\u0003")
+    {
+        // ctrl c
+        emulator.destroy();
+        process.stdin.pause();
+    }
+    else
+    {
+        emulator.serial0_send(c);
+    }
+});

examples/nodejs_state.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import url from "node:url";
+import { V86 } from "../build/libv86.mjs";
+
+const __dirname = url.fileURLToPath(new URL(".", import.meta.url));
+
+console.log("Use F2 to save the state and F3 to restore.");
+
+process.stdin.setRawMode(true);
+process.stdin.resume();
+process.stdin.setEncoding("utf8");
+
+console.log("Now booting, please stand by ...");
+
+var emulator = new V86({
+    bios: { url: __dirname + "/../bios/seabios.bin" },
+    cdrom: { url: __dirname + "/../images/linux4.iso" },
+    autostart: true,
+});
+
+emulator.add_listener("serial0-output-byte", function(byte)
+{
+    var chr = String.fromCharCode(byte);
+    if(chr <= "~")
+    {
+        process.stdout.write(chr);
+    }
+});
+
+var state;
+
+process.stdin.on("data", async function(c)
+{
+    if(c === "\u0003")
+    {
+        // ctrl c
+        emulator.destroy();
+        process.stdin.pause();
+    }
+    else if(c === "\x1b\x4f\x51")
+    {
+        // f2
+        state = await emulator.save_state();
+        console.log("--- Saved ---");
+    }
+    else if(c === "\x1b\x4f\x52")
+    {
+        // f3
+        if(state)
+        {
+            console.log("--- Restored ---");
+            await emulator.restore_state(state);
+        }
+    }
+    else
+    {
+        emulator.serial0_send(c);
+    }
+});

examples/save_restore.html

@@ -0,0 +1,94 @@
+<!doctype html>
+<title>Save and restore</title>
+
+<script src="../build/libv86.js"></script>
+<script>
+"use strict";
+
+window.onload = function()
+{
+    var emulator = new V86({
+        wasm_path: "../build/v86.wasm",
+        memory_size: 32 * 1024 * 1024,
+        vga_memory_size: 2 * 1024 * 1024,
+        screen_container: document.getElementById("screen_container"),
+        bios: {
+            url: "../bios/seabios.bin",
+        },
+        vga_bios: {
+            url: "../bios/vgabios.bin",
+        },
+        cdrom: {
+            url: "../images/linux.iso",
+        },
+        autostart: true,
+    });
+
+    var state;
+
+    document.getElementById("save_restore").onclick = async function()
+    {
+        var button = this;
+
+        if(state)
+        {
+            button.value = "Save state";
+            await emulator.restore_state(state);
+            state = undefined;
+        }
+        else
+        {
+            const new_state = await emulator.save_state();
+            console.log("Saved state of " + new_state.byteLength + " bytes");
+            button.value = "Restore state";
+            state = new_state;
+        }
+
+        button.blur();
+    };
+
+    document.getElementById("save_file").onclick = async function()
+    {
+        const new_state = await emulator.save_state();
+        var a = document.createElement("a");
+        a.download = "v86state.bin";
+        a.href = window.URL.createObjectURL(new Blob([new_state]));
+        a.dataset.downloadurl = "application/octet-stream:" + a.download + ":" + a.href;
+        a.click();
+
+        this.blur();
+    };
+
+    document.getElementById("restore_file").onchange = function()
+    {
+        if(this.files.length)
+        {
+            var filereader = new FileReader();
+            emulator.stop();
+
+            filereader.onload = async function(e)
+            {
+                await emulator.restore_state(e.target.result);
+                emulator.run();
+            };
+
+            filereader.readAsArrayBuffer(this.files[0]);
+
+            this.value = "";
+        }
+
+        this.blur();
+    };
+};
+</script>
+
+<input id="save_restore" type="button" value="Save state">
+<input id="save_file" type="button" value="Save state to file">
+Restore from file: <input id="restore_file" type="file">
+<hr>
+
+<!-- A minimal structure for the ScreenAdapter defined in browser/screen.js -->
+<div id="screen_container">
+    <div style="white-space: pre; font: 14px monospace; line-height: 14px"></div>
+    <canvas style="display: none"></canvas>
+</div>