2018-10-02 17:41:58 +02:00
|
|
|
Building
|
|
|
|
-
|
|
|
|
|
|
|
|
See `docker/test-image/Dockerfile` for a full setup on Debian.
|
|
|
|
|
|
|
|
You need:
|
|
|
|
|
|
|
|
- java
|
|
|
|
- gcc, make, libc-i386
|
|
|
|
- nasm, gdb and qemu (for running tests)
|
|
|
|
- rust-nightly with the wasm32-unknown-unknown target
|
|
|
|
- nodejs (a latest version is required, 10.11.0 is known to be working)
|
2015-09-11 03:38:43 +02:00
|
|
|
|
2018-10-02 17:41:58 +02:00
|
|
|
Run `make all-debug` to build the debug build (at `debug.html`).
|
|
|
|
Run `make all` to build the optimized build (at `index.html`).
|
2014-12-14 16:44:31 +01:00
|
|
|
|
2018-10-02 17:41:58 +02:00
|
|
|
Testing
|
2014-12-14 16:44:31 +01:00
|
|
|
-
|
|
|
|
|
2018-10-02 17:41:58 +02:00
|
|
|
Run all tests: `make jshint rustfmt kvm-unit-test nasmtests nasmtests-force-jit expect-tests jitpagingtests qemutests rust-test tests`
|
|
|
|
|
|
|
|
Creating a Linux image for use in v86
|
|
|
|
-
|
|
|
|
|
|
|
|
See `docker/debian-full/Readme.md`.
|
|
|
|
|
2015-01-11 23:40:39 +01:00
|
|
|
|
2018-10-02 17:41:58 +02:00
|
|
|
Below is the readme of the open-source version of v86 (not everything applies)
|
|
|
|
=
|
2015-01-11 23:40:39 +01:00
|
|
|
|
|
|
|
API examples
|
|
|
|
-
|
|
|
|
|
2015-08-22 16:37:55 +02:00
|
|
|
- [Basic](examples/basic.html)
|
|
|
|
- [Programatically using the serial terminal](examples/serial.html)
|
2016-04-23 19:27:37 +02:00
|
|
|
- [A Lua interpreter](examples/lua.html)
|
2015-08-22 16:37:55 +02:00
|
|
|
- [Two instances in one window](examples/two_instances.html)
|
|
|
|
- [Saving and restoring emulator state](examples/save_restore.html)
|
2015-01-11 23:40:39 +01:00
|
|
|
|
|
|
|
Using v86 for your own purposes is as easy as:
|
|
|
|
|
|
|
|
```javascript
|
|
|
|
var emulator = new V86Starter({
|
|
|
|
screen_container: document.getElementById("screen_container"),
|
|
|
|
bios: {
|
|
|
|
url: "../../bios/seabios.bin",
|
|
|
|
},
|
|
|
|
vga_bios: {
|
|
|
|
url: "../../bios/vgabios.bin",
|
|
|
|
},
|
|
|
|
cdrom: {
|
|
|
|
url: "../../images/linux.iso",
|
|
|
|
},
|
|
|
|
autostart: true,
|
|
|
|
});
|
|
|
|
```
|
|
|
|
|
|
|
|
See [API](docs/api.md).
|
2013-11-06 18:19:13 +01:00
|
|
|
|
|
|
|
|
2013-11-06 01:12:55 +01:00
|
|
|
How does it work?
|
|
|
|
-
|
|
|
|
|
|
|
|
v86 emulates an x86-compatible CPU and hardware. Here's a list of emulated hardware:
|
|
|
|
|
|
|
|
- An x86 compatible CPU. The instruction set is around Pentium 1 level. Some
|
|
|
|
features are missing, more specifically:
|
|
|
|
- Task gates, far calls in protected mode
|
2014-07-23 01:11:06 +02:00
|
|
|
- 16 bit protected mode features
|
2013-11-06 01:12:55 +01:00
|
|
|
- Single stepping
|
|
|
|
- MMX, SSE
|
2014-07-23 01:11:06 +02:00
|
|
|
- A bunch of FPU instructions
|
|
|
|
- Some exceptions
|
2013-11-06 01:12:55 +01:00
|
|
|
- A floating point unit (FPU). Calculations are done with JavaScript's double
|
|
|
|
precision numbers (64 bit), so they are not as precise as calculations on a
|
|
|
|
real FPU (80 bit).
|
|
|
|
- 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).
|
|
|
|
- A CMOS Real Time Clock (RTC).
|
2014-12-14 16:44:31 +01:00
|
|
|
- A VGA controller with SVGA support and Bochs VBE Extensions.
|
2013-11-26 21:58:12 +01:00
|
|
|
- A PCI bus. This one is partly incomplete and not used by every device.
|
|
|
|
- An IDE disk controller.
|
2014-10-11 02:15:37 +02:00
|
|
|
- An NE2000 (8390) PCI network card.
|
2014-12-02 19:01:13 +01:00
|
|
|
- A virtio filesystem.
|
2013-11-06 01:12:55 +01:00
|
|
|
|
|
|
|
|
2015-09-15 07:25:20 +02:00
|
|
|
Testing
|
|
|
|
-
|
|
|
|
|
|
|
|
The disk images are not included in this repository. You can download them
|
|
|
|
directly from the website using:
|
|
|
|
|
2016-08-04 19:30:39 +02:00
|
|
|
`wget -P images/ https://copy.sh/v86/images/{linux.iso,linux3.iso,kolibri.img,windows101.img,os8.dsk,freedos722.img,openbsd.img}`.
|
2015-09-15 07:25:20 +02:00
|
|
|
|
|
|
|
A testsuite is available in `tests/full/`. Run it using `node tests/full/run.js`.
|
|
|
|
|
|
|
|
|
2013-11-06 01:12:55 +01:00
|
|
|
How to build, run and embed?
|
|
|
|
-
|
|
|
|
|
2017-04-28 02:14:49 +02:00
|
|
|
- Building is only necessary for releases, open debug.html and everything should load out of the box
|
2014-07-23 01:11:06 +02:00
|
|
|
- If you want a compressed and fast (i.e. with debug code removed) version, you
|
2015-01-31 17:56:29 +01:00
|
|
|
need Closure Compiler. Download it as shown below and run `make build/v86_all.js`.
|
2014-01-10 23:12:56 +01:00
|
|
|
- ROM and disk images are loaded via XHR, so if you want to try out `index.html`
|
2014-12-14 16:37:27 +01:00
|
|
|
locally, make sure to serve it from a local webserver. You can use `make run`
|
|
|
|
to serve the files using Python's SimpleHTTPServer.
|
2016-08-23 11:32:08 +02:00
|
|
|
- If you only want to embed v86 in a webpage you can use libv86.js. For
|
2015-08-22 16:37:55 +02:00
|
|
|
usage, check out the [API](docs/api.md) and [examples](examples/).
|
2014-12-14 16:37:27 +01:00
|
|
|
- A couple of disk images are provided for testing. You can check them out
|
2016-08-04 19:30:39 +02:00
|
|
|
using `wget -P images/ https://copy.sh/v86/images/{linux.iso,linux3.iso,kolibri.img,windows101.img,os8.dsk,freedos722.img,openbsd.img}`.
|
2014-12-14 16:37:27 +01:00
|
|
|
|
|
|
|
|
2015-09-15 07:25:20 +02:00
|
|
|
**Short summary:**
|
2014-12-14 16:37:27 +01:00
|
|
|
|
2015-01-11 23:40:39 +01:00
|
|
|
```bash
|
2015-01-20 01:04:53 +01:00
|
|
|
# grab the main repo
|
2016-11-21 20:06:29 +01:00
|
|
|
git clone https://github.com/copy/v86.git && cd v86
|
2015-01-20 01:04:53 +01:00
|
|
|
|
|
|
|
# grab the disk images
|
2016-08-04 19:30:39 +02:00
|
|
|
wget -P images/ https://copy.sh/v86/images/{linux.iso,linux3.iso,kolibri.img,windows101.img,os8.dsk,freedos722.img,openbsd.img}
|
2015-01-20 01:04:53 +01:00
|
|
|
|
|
|
|
# grab closure compiler
|
2016-08-04 19:30:39 +02:00
|
|
|
wget -P closure-compiler https://dl.google.com/closure-compiler/compiler-latest.zip
|
2017-04-27 12:32:34 +02:00
|
|
|
unzip -d closure-compiler closure-compiler/compiler-latest.zip *.jar
|
2014-12-14 16:37:27 +01:00
|
|
|
|
2015-09-15 07:25:20 +02:00
|
|
|
# build the library
|
2015-11-11 04:26:43 +01:00
|
|
|
make build/libv86.js
|
2014-12-14 16:37:27 +01:00
|
|
|
|
2015-09-15 07:25:20 +02:00
|
|
|
# run the tests
|
|
|
|
./tests/full/run.js
|
2014-12-14 16:37:27 +01:00
|
|
|
```
|
|
|
|
|
2014-01-10 23:12:56 +01:00
|
|
|
Compatibility
|
|
|
|
-
|
|
|
|
|
|
|
|
Here's an overview of the operating systems supported in v86:
|
|
|
|
|
2014-07-23 01:11:06 +02:00
|
|
|
- Linux works pretty well. Graphical boot fails in many versions, but you
|
|
|
|
mostly get a shell. The mouse is often not detected automatically.
|
2016-11-21 20:06:29 +01:00
|
|
|
- Damn Small Linux (2.4 Kernel): Works, takes circa 10 minutes to boot.
|
2014-07-23 01:11:06 +02:00
|
|
|
- Tinycore (3.0 kernel): `udev` and `X` fail, but you get a
|
2014-01-10 23:12:56 +01:00
|
|
|
terminal.
|
2014-07-23 01:11:06 +02:00
|
|
|
- Nanolinux works.
|
2017-04-28 02:14:49 +02:00
|
|
|
- Archlinux works with some caveats. See [archlinux.md](docs/archlinux.md).
|
2017-03-23 19:25:46 +01:00
|
|
|
- ReactOS works
|
2017-03-23 18:46:05 +01:00
|
|
|
- FreeDOS, Windows 1.01 and MS-DOS run very well.
|
2014-07-23 01:11:06 +02:00
|
|
|
- KolibriOS works. A few applications need SSE.
|
2016-11-21 20:06:29 +01:00
|
|
|
- Haiku boots, but takes very long (around 30 minutes).
|
2014-07-23 01:11:06 +02:00
|
|
|
- No Android version seems to work, you still get a shell.
|
2017-03-23 18:46:05 +01:00
|
|
|
- Windows 1, 95 and 98 work. Other versions currently don't.
|
2016-11-21 20:06:29 +01:00
|
|
|
- Many hobby operating systems work.
|
2017-04-02 22:21:40 +02:00
|
|
|
- FreeBSD works
|
2014-01-10 23:12:56 +01:00
|
|
|
|
2015-01-11 23:40:39 +01:00
|
|
|
You can get some infos on the disk images here: https://github.com/copy/images.
|
2014-01-10 23:12:56 +01:00
|
|
|
|
2013-11-06 01:12:55 +01:00
|
|
|
|
|
|
|
How can I contribute?
|
|
|
|
-
|
|
|
|
|
2014-07-23 01:11:06 +02:00
|
|
|
- Add new features (hardware devices, fill holes in the CPU), fix bugs. Check
|
2014-12-14 16:37:27 +01:00
|
|
|
out the issues section and contact me if you need help.
|
2014-07-23 01:11:06 +02:00
|
|
|
- Report bugs.
|
2015-09-12 01:11:49 +02:00
|
|
|
- If you want to donate, let me know.
|
2013-11-06 01:12:55 +01:00
|
|
|
|
|
|
|
License
|
|
|
|
-
|
|
|
|
|
|
|
|
Simplified BSD License, see [LICENSE](LICENSE), unless otherwise noted.
|
|
|
|
|
|
|
|
|
|
|
|
Credits
|
|
|
|
-
|
|
|
|
|
2016-11-21 20:06:29 +01:00
|
|
|
- CPU test cases via QEMU, http://wiki.qemu.org/Main_Page
|
2017-04-02 22:20:55 +02:00
|
|
|
- More tests via [kvm-unit-tests](https://www.linux-kvm.org/page/KVM-unit-tests)
|
2014-07-12 20:22:02 +02:00
|
|
|
- [Disk Images](https://github.com/copy/images)
|
2016-11-21 20:06:29 +01:00
|
|
|
- [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
|
2013-11-06 01:12:55 +01:00
|
|
|
|
|
|
|
|
|
|
|
More questions?
|
|
|
|
-
|
|
|
|
|
|
|
|
Shoot me an email to `copy@copy.sh`. Please don't tell about bugs via mail,
|
2014-07-23 01:11:06 +02:00
|
|
|
create a bug report on GitHub instead.
|
2013-11-06 01:12:55 +01:00
|
|
|
|
|
|
|
|
|
|
|
Author
|
|
|
|
-
|
|
|
|
|
|
|
|
Fabian Hemmer (http://copy.sh/, `copy@copy.sh`)
|
2014-07-23 01:11:06 +02:00
|
|
|
|