Documentation
This commit is contained in:
parent
8e554458d1
commit
1094c67261
41
Readme.md
41
Readme.md
|
@ -6,6 +6,37 @@ Demos
|
|||
- [KolibriOS](http://copy.sh/v86/?profile=kolibrios)
|
||||
- [FreeDOS](http://copy.sh/v86/?profile=freedos)
|
||||
- [Windows 1.01](http://copy.sh/v86/?profile=windows1)
|
||||
- [Archlinux](http://copy.sh/v86/?profile=archlinux) (possibly unstable)
|
||||
|
||||
|
||||
API examples
|
||||
-
|
||||
|
||||
- [Basic](docs/samples/basic.html)
|
||||
- [Programatically using the serial terminal](docs/samples/serial.html)
|
||||
- [A LUA interpreter](docs/samples/lua.html)
|
||||
- [Two instances in one window](docs/samples/two_instances.html)
|
||||
- [Saving and restoring emulator state](docs/samples/save_restore.html)
|
||||
|
||||
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).
|
||||
|
||||
|
||||
How does it work?
|
||||
|
@ -48,14 +79,14 @@ How to build, run and embed?
|
|||
locally, make sure to serve it from a local webserver. You can use `make run`
|
||||
to serve the files using Python's SimpleHTTPServer.
|
||||
- If you want only want to embed v86 on website you can use libv86.js. For
|
||||
usage, check out [basic.html](docs/samples/basic.html).
|
||||
usage, check out the [API](docs/api.md) and [examples](docs/samples/).
|
||||
- A couple of disk images are provided for testing. You can check them out
|
||||
using `git submodule update --init --recursive images`.
|
||||
|
||||
|
||||
To summarize:
|
||||
**Summary:**
|
||||
|
||||
```
|
||||
```bash
|
||||
git clone https://github.com/copy/v86.git # grab the main repo
|
||||
cd v86
|
||||
git submodule update --init --recursive images # get the disk images
|
||||
|
@ -105,7 +136,7 @@ Here's an overview of the operating systems supported in v86:
|
|||
- ReactOS doesn't work.
|
||||
- No Android version seems to work, you still get a shell.
|
||||
|
||||
You can get some infos on the disk images here: https://github.com/copy/images
|
||||
You can get some infos on the disk images here: https://github.com/copy/images.
|
||||
|
||||
|
||||
How can I contribute?
|
||||
|
@ -128,8 +159,6 @@ Credits
|
|||
-
|
||||
|
||||
- Test cases via QEMU, http://wiki.qemu.org/Main_Page
|
||||
- https://github.com/creationix/node-sdl
|
||||
- ascii.ttf (used in node) from http://www.apollosoft.de/ASCII/indexen.htm
|
||||
- [Disk Images](https://github.com/copy/images)
|
||||
- [The jor1k project](https://github.com/s-macke/jor1k) for 9p and filesystem drivers
|
||||
|
||||
|
|
209
docs/api.md
Normal file
209
docs/api.md
Normal file
|
@ -0,0 +1,209 @@
|
|||
# V86Starter
|
||||
- [`run()`](#run)
|
||||
- [`stop()`](#stop)
|
||||
- [`restart()`](#restart)
|
||||
- [`add_listener(string event, function(*) listener)`](#add_listenerstring-event-function-listener)
|
||||
- [`remove_listener(string event, function(*) listener)`](#remove_listenerstring-event-function-listener)
|
||||
- [`restore_state(ArrayBuffer state)`](#restore_statearraybuffer-state)
|
||||
- [`save_state(function(Object, ArrayBuffer) callback)`](#save_statefunctionobject-arraybuffer-callback)
|
||||
- [`get_statistics() -> Object`](#get_statistics---object)
|
||||
- [`is_running() -> boolean`](#is_running---boolean)
|
||||
- [`keyboard_send_scancodes(Array.<number> codes)`](#keyboard_send_scancodesarraynumber-codes)
|
||||
- [`mouse_set_status(boolean enabled)`](#mouse_set_statusboolean-enabled)
|
||||
- [`keyboard_set_status(boolean enabled)`](#keyboard_set_statusboolean-enabled)
|
||||
- [`serial0_send(string data)`](#serial0_sendstring-data)
|
||||
|
||||
***
|
||||
## `V86Starter`
|
||||
Constructor for emulator instances.
|
||||
|
||||
Usage: `var emulator = new V86Starter(options);`
|
||||
|
||||
Options can have the following properties (all optional, default in parenthesis):
|
||||
|
||||
- `memory_size number` (16 * 1024 * 1024) - The memory size in bytes, should
|
||||
be a power of 2.
|
||||
- `vga_memory_size number` (8 * 1024 * 1024) - VGA memory size in bytes.
|
||||
- `autostart boolean` (false) - If emulation should be started when emulator
|
||||
is ready.
|
||||
- `disable_keyboard boolean` (false) - If the keyboard should be disabled.
|
||||
- `disable_mouse boolean` (false) - If the mouse should be disabled.
|
||||
- `network_relay_url string` (No network card) - The url of a server running
|
||||
websockproxy. See
|
||||
https://github.com/copy/v86/blob/master/docs/networking.md.
|
||||
- `bios Object` (No bios) - Either a url pointing to a bios or an
|
||||
ArrayBuffer, see below.
|
||||
- `vga_bios Object` (No VGA bios) - VGA bios, see below.
|
||||
- `hda Object` (No hard drive) - First hard disk, see below.
|
||||
- `fda Object` (No floppy disk) - First floppy disk, see below.
|
||||
- `cdrom Object` (No cd drive) - CD disk, see below.
|
||||
- `initial_state Object` (Normal boot) - An initial state to load, see
|
||||
[`restore_state`](#restore_statearraybuffer-state) and below.
|
||||
- `serial_container HTMLTextAreaElement` (No serial terminal) - A textarea
|
||||
that will receive and send data to the emulated serial terminal.
|
||||
Alternatively the serial terminal can also be accessed programatically,
|
||||
see https://github.com/copy/v86/blob/master/docs/samples/serial.html.
|
||||
- `screen_container HTMLElement` (No screen) - An HTMLElement. This should
|
||||
have a certain structure, see
|
||||
https://github.com/copy/v86/blob/master/docs/samples/basic.html.
|
||||
|
||||
There are two ways to load images (`bios`, `vga_bios`, `cdrom`, `hda`, ...):
|
||||
|
||||
- Pass an object that has a url: `options.bios = { url:
|
||||
"http://copy.sh/v86/bios/seabios.bin" }`. Optionally, `async: true` can be
|
||||
added to the object, so that sectors of the image are loaded on demand
|
||||
instead of being loaded before boot (slower, but strongly recommended for
|
||||
big files).
|
||||
- Pass an `ArrayBuffer` or `File` object, for instance `options.hda = {
|
||||
buffer: new ArrayBuffer(512 * 1024) }` to add an empty hard drive.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
1. **`Object`** options – Options to initialize the emulator with.
|
||||
|
||||
***
|
||||
#### `run()`
|
||||
Start emulation. Do nothing if emulator is running already. Can be
|
||||
asynchronous.
|
||||
|
||||
***
|
||||
#### `stop()`
|
||||
Stop emulation. Do nothing if emulator is not running. Can be asynchronous.
|
||||
|
||||
***
|
||||
#### `restart()`
|
||||
Restart (force a reboot).
|
||||
|
||||
***
|
||||
#### `add_listener(string event, function(*) listener)`
|
||||
Add an event listener (the emulator is an event emitter). A list of events
|
||||
can be found at https://github.com/copy/v86/blob/master/docs/events.md.
|
||||
|
||||
The callback function gets a single argument which depends on the event.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
1. **`string`** event – Name of the event.
|
||||
2. **`function(*)`** listener – The callback function.
|
||||
|
||||
***
|
||||
#### `remove_listener(string event, function(*) listener)`
|
||||
Remove an event listener.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
1. **`string`** event
|
||||
2. **`function(*)`** listener
|
||||
|
||||
***
|
||||
#### `restore_state(ArrayBuffer state)`
|
||||
Restore the emulator state from the given state, which must be an
|
||||
ArrayBuffer returned by
|
||||
[`save_state`](#save_statefunctionobject-arraybuffer-callback).
|
||||
|
||||
Note that the state can only be restored correctly if this constructor has
|
||||
been created with the same options as the original instance (e.g., same disk
|
||||
images, memory size, etc.).
|
||||
|
||||
Different versions of the emulator might use a different format for the
|
||||
state buffer.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
1. **`ArrayBuffer`** state
|
||||
|
||||
***
|
||||
#### `save_state(function(Object, ArrayBuffer) callback)`
|
||||
Asynchronously save the current state of the emulator. The first argument to
|
||||
the callback is an Error object if something went wrong and is null
|
||||
otherwise.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
1. **`function(Object, ArrayBuffer)`** callback
|
||||
|
||||
***
|
||||
#### `get_statistics() -> Object`
|
||||
Return an object with several statistics. Return value looks similar to
|
||||
(but can be subject to change in future versions or different
|
||||
configurations, so use defensively):
|
||||
|
||||
```
|
||||
{
|
||||
"cpu": {
|
||||
"instruction_counter": 2821610069
|
||||
},
|
||||
"hda": {
|
||||
"sectors_read": 95240,
|
||||
"sectors_written": 952,
|
||||
"bytes_read": 48762880,
|
||||
"bytes_written": 487424,
|
||||
"loading": false
|
||||
},
|
||||
"cdrom": {
|
||||
"sectors_read": 0,
|
||||
"sectors_written": 0,
|
||||
"bytes_read": 0,
|
||||
"bytes_written": 0,
|
||||
"loading": false
|
||||
},
|
||||
"mouse": {
|
||||
"enabled": true
|
||||
},
|
||||
"vga": {
|
||||
"is_graphical": true,
|
||||
"res_x": 800,
|
||||
"res_y": 600,
|
||||
"bpp": 32
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Returns:**
|
||||
|
||||
* **`Object`**
|
||||
|
||||
***
|
||||
#### `is_running() -> boolean`
|
||||
|
||||
**Returns:**
|
||||
|
||||
* **`boolean`**
|
||||
|
||||
***
|
||||
#### `keyboard_send_scancodes(Array.<number> codes)`
|
||||
Send a sequence of scan codes to the emulated PS2 controller. A list of
|
||||
codes can be found at http://stanislavs.org/helppc/make_codes.html.
|
||||
Do nothing if there is not keyboard controller.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
1. **`Array.<number>`** codes
|
||||
|
||||
***
|
||||
#### `mouse_set_status(boolean enabled)`
|
||||
Enable or disable sending mouse events to the emulated PS2 controller.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
1. **`boolean`** enabled
|
||||
|
||||
***
|
||||
#### `keyboard_set_status(boolean enabled)`
|
||||
Enable or disable sending keyboard events to the emulated PS2 controller.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
1. **`boolean`** enabled
|
||||
|
||||
***
|
||||
#### `serial0_send(string data)`
|
||||
Send a string to the first emulated serial terminal.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
1. **`string`** data
|
||||
|
||||
<!-- src/browser/starter.js-->
|
||||
|
||||
<!-- vim: set tabstop=2 shiftwidth=2 softtabstop=2: -->
|
32
docs/events.md
Normal file
32
docs/events.md
Normal file
|
@ -0,0 +1,32 @@
|
|||
Here is a list of events that can be listened to using
|
||||
[`add_listener`](docs/api.md#add_listenerstring-event-function-listener). These
|
||||
can be used to programtically control the emulator. Events cannot be sent to
|
||||
the emulator (although it is internally implemented that way), use the
|
||||
[API](docs/api.md) methods for that.
|
||||
|
||||
### Serial terminal
|
||||
|
||||
See also: [serial.js](src/browser/serial.js).
|
||||
|
||||
- `serial0-output-char` - `string chr`
|
||||
|
||||
### Network
|
||||
|
||||
See also: [network.js](src/browser/network.js).
|
||||
|
||||
- `net0-receive` - `Uint8Array buffer`
|
||||
|
||||
### Screen
|
||||
|
||||
See also: [screen.js](src/browser/screen.js).
|
||||
|
||||
- `screen-set-mode` - `boolean is_graphic`
|
||||
- `screen-put-char` - `[number row, number col, number chr, number bg_color, number fg_color]`
|
||||
- `screen-put-pixel-linear` - `[number addr, number value]`
|
||||
- `screen-put-pixel-linear32` - `[number addr, number value]`
|
||||
- `screen-set-size-text` - `[number cols_count, number rows_count]`
|
||||
- `screen-set-size-graphical` - `[number width, number height]`
|
||||
- `screen-update-cursor` - `[number row, number col]`
|
||||
- `screen-update-cursor-scanline` - `[number cursor_scanline_start, number cursor_scanline_end]`
|
||||
|
||||
|
7
docs/networking.md
Normal file
7
docs/networking.md
Normal file
|
@ -0,0 +1,7 @@
|
|||
Emulating a network card is supported. It can be used by passing the
|
||||
`network_relay_url` option to `V86Starter`. The url must point to a running
|
||||
WebSockets Proxy. The source code for WebSockets Proxy can be found at
|
||||
https://github.com/benjamincburns/websockproxy.
|
||||
|
||||
The network card could also be controlled programatically, but this is
|
||||
currently not exposed.
|
Loading…
Reference in a new issue