= ok - A Minimal Stack-Based Virtual Machine

This repository contains the specification and reference implementation for the 
`ok` (virtual) computer.

> WARNING: this virtual computer and its specification are still in beta; expect 
limited documentation and potential non-backwards-compatible updates in the 
future.

== Including as a library

The VM is implemented as a single C header, so creating your own minimal emulator
is very easy. Here is an example:

```
#define OK_IMPLEMENTATION
#include "ok.h"
// okvm.h includes stdio already, so we don't need to include it again

// device functions must have this signature
uint8_t serial_output(uint8_t* ram, uint8_t* rom);

int main(int argc, char* argv[]) {
  if (argc != 2) {
    printf("usage: okmin file.rom\n");
    return 1;
  }

  OkVM vm;
  int init_failed = okvm_init_from_file(&vm, argv[1]); // allocates memory
  if (init_failed) return 1;
  
  // registering an external device
  // since the port is 55, the opcodes "#37 INT1" will trigger the device
  int reg_failed = okvm_register_device(&vm, serial_output, 55);
  if (reg_failed) return 1;

  vm.status = OK_RUNNING;
  while (vm.status == OK_RUNNING) okvm_tick(&vm);

  okvm_free(&vm); // this frees the memory allocated at init
  return vm.status != OK_HALTED;
}

// our device function just prints the byte at a specific RAM address
uint8_t serial_output(uint8_t* ram, uint8_t* rom) {
  char c = ram[0x37]; // here is that "magic" address
  putchar(c);
  return c;
}
```

== Running examples/tests

If you have [just] installed, simply clone this repository, navigate to the 
repository folder, and run `just build-example` to build the example emulator.

[just]: https://github.com/casey/just

Run tests using `just test`.

== Goals

`ok` is a simple stack-based virtual machine designed with the following goals 
in mind:

- Ease of implementation
- Ease of language targeting
- Minimalism
- Expressiveness

`ok` aspires to be useful for educational purposes (such as teaching low-level 
concepts as well as compiler development) by being a simple compiler target.

`ok` also aspires to run well on older or more constrained hardware- 
the original reference implementation was implemented on a 15-year old 32-bit
machine with only 1.5 gigabytes of RAM.

== Features

- Two 256-byte circular stacks
- 24-bit computing!
- Up to 4 GiB of virtual RAM and 4 GiB of instruction memory (by default only 16 MiB of each, however)
- Configurable word sizes
- 16 primitive stack operations
- Simple C interoperability (VM devices are just C function calls)

== More Info

See the [specification] for the VM specification (instruction set, 
memory model, etc.)

The base virtual machine specification is the only "canonical" part of the `ok` 
computing stack- creating your own unique assemblers, compilers, emulators, and 
specific device specifications is recommended and highly encouraged.