Skip to content

Commit

Permalink
nit: Fix trivial markdownlint warnings
Browse files Browse the repository at this point in the history
Signed-off-by: Joel Van Eenwyk <joel.vaneenwyk@gmail.com>
  • Loading branch information
joelvaneenwyk committed Jul 8, 2024
1 parent d130e46 commit 1c54578
Show file tree
Hide file tree
Showing 6 changed files with 38 additions and 20 deletions.
18 changes: 10 additions & 8 deletions Readme.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
# `js-v86` - x86 Virtualization in JavaScript

[![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
Expand Down Expand Up @@ -106,18 +108,18 @@ Here's an overview of the operating systems supported in v86:
- 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.
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
- `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
Expand Down Expand Up @@ -212,4 +214,4 @@ Shoot me an email to `copy@copy.sh`. Please report bugs on GitHub.

## Author

Fabian Hemmer (https://copy.sh/, `copy@copy.sh`)
Fabian Hemmer (<https://copy.sh/>, `copy@copy.sh`)
13 changes: 11 additions & 2 deletions docs/archlinux.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ faster way to automatically build Linux images for v86.
Choosing an installer ISO
-------------------------

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

Basic installation using QEMU
-----------------------
Expand Down Expand Up @@ -44,6 +44,7 @@ Installing the ISO by hand takes a long time if you intend to recreate the image
[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 and 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'
Expand Down Expand Up @@ -98,13 +99,15 @@ After gaining SSH connectivity to the VM, packer will run the `scripts/provision
### 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"
Expand Down Expand Up @@ -179,7 +182,7 @@ mkdir -p /mnt/etc/initcpio/install
cat << 'EOF' > /mnt/etc/initcpio/install/9p_root
#!/bin/bash
build() {
add_runscript
add_runscript
}
EOF

Expand Down Expand Up @@ -310,6 +313,7 @@ Now that we have an image that contains a filesystem, we can convert that filesy
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
```
Expand Down Expand Up @@ -406,6 +410,7 @@ We can then edit `examples/arch.html`, we have two options:
acpi: false,
autostart: true,
```

2. Boot the Arch Linux from the qemu raw disk image:

```sh
Expand Down Expand Up @@ -444,6 +449,7 @@ If you refresh `http://localhost:8000/examples/arch.html` you will see that the
### 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/",
```
Expand All @@ -453,17 +459,20 @@ This will make the emulator try to connect to a [WebSockets proxy](https://githu
```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
Expand Down
10 changes: 7 additions & 3 deletions docs/cpu-idling.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,25 +2,29 @@ Some operating systems don't support `hlt` instruction, because of this, the CPU
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:).

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

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.
2 changes: 1 addition & 1 deletion docs/how-it-works.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ The major limitations of WebAssembly are (for the purpose of making emulators wi

- 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 `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
Expand Down
2 changes: 1 addition & 1 deletion docs/linux-9p-image.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
In order to create a Linux image that can mount the 9p file system, add the following lines to the kernel configuration:

```
```bash
CONFIG_NET_9P=y
CONFIG_NET_9P_VIRTIO=y
CONFIG_NET_9P_DEBUG=y
Expand Down
13 changes: 8 additions & 5 deletions docs/windows-xp.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
You can download Windows 2000 from [WinWorld](https://winworldpc.com/download/413638c2-8d18-c39a-11c3-a4e284a2c3a5).
Use QEMU to create `winxp.img`:

```
```bash
qemu-img create winxp.img 2G
qemu-system-x86_64 -m 512 -drive file=winxp.img,format=raw -cdrom en_windows_xp_professional_with_service_pack_3_x86_cd_vl_x14-73974.iso
```
Expand All @@ -22,8 +22,8 @@ Now, `winxp.img` is ready for v86. You can use [the website](https://copy.sh/v86
Specify `winxp.img` as a hard disk, and optionally set the memory size to 512 MB.
Or run it in a custom HTML file as described below.

Get seabios.bin and vgabios.bin from [here](https://github.com/copy/v86/tree/master/bios),
and get libv86.js and v86.wasm from [releases](https://github.com/copy/v86/releases/tag/latest).
Get `seabios.bin` and `vgabios.bin` from [here](https://github.com/copy/v86/tree/master/bios),
and get `libv86.js` and `v86.wasm` from [releases](https://github.com/copy/v86/releases/tag/latest).
Create `winxp.htm` with this content (assuming all the files are in the same folder):

```html
Expand Down Expand Up @@ -58,12 +58,15 @@ onload = function()
To open this HTML file locally, a HTTP server is needed. The standard Python server `python -m http.server` doesn't support HTTP range requests.
You can use [http-server](https://www.npmjs.com/package/http-server) or [devd](https://github.com/cortesi/devd).
Start the server (from the same folder as `winxp.htm`):
```

```bash
npx http-server
```
Open http://localhost:8080/winxp.htm in the browser.

Open <http://localhost:8080/winxp.htm> in the browser.

Windows XP load time (until start button becomes responsive) in Chromium on my computer:

* 3 min second time
* 4 min (first time or if cache is disabled)
* 12 min second time if Network tab in Developer Tools is open
Expand Down

0 comments on commit 1c54578

Please sign in to comment.