Documentation

BunsDev · Jan 11, 2015 · 1094c67 · 1094c67
1 parent 8e55445
commit 1094c67
Show file tree

Hide file tree

Showing 4 changed files with 283 additions and 6 deletions.
diff --git a/Readme.md b/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
 

diff --git a/docs/api.md b/docs/api.md
@@ -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: -->
diff --git a/docs/events.md b/docs/events.md
@@ -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]`
+
+
diff --git a/docs/networking.md b/docs/networking.md
@@ -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.