650 lines
13 KiB
Markdown
650 lines
13 KiB
Markdown
# Nga
|
|
|
|
## Overview
|
|
|
|
Nga is a minimalistic virtual machine emulating a dual stack computer
|
|
with a simple instruction set.
|
|
|
|
This is the specification and reference implementation of Nga. All code
|
|
provided is in the C language.
|
|
|
|
## Quick Overview of the VM Model
|
|
|
|
**Memory** is a single, linear addressing space of signed integer
|
|
values. Each location is called a **cell**. Addressing starts at zero
|
|
and counts up.
|
|
|
|
The VM does not expose any registers via the instruction set. This
|
|
implementation makes use of an *instruction pointer* or **IP**, *data
|
|
stack pointer* or **SP**, and *address stack pointer* or **RP**.
|
|
|
|
Nga provides two LIFO stacks. The primary one is for data and the
|
|
secondary one is used to hold return addresses for subroutine calls.
|
|
Stack depths may vary depending on the underlying hardware and
|
|
application needs.
|
|
|
|
Instructions each take one cell. The **LIT** instruction requires a
|
|
value in the following cell; it will push this value to the stack when
|
|
executed.
|
|
|
|
Instruction processing: the **IP** is incremented and the opcode at the
|
|
current address is invoked. This process then repeats. Execution ends
|
|
if the **END** instruction is run or end of memory is reached.
|
|
|
|
Endian: the image files are stored in little endian format.
|
|
|
|
## Legal
|
|
|
|
Nga derives from my earlier work on Ngaro. The following block lists
|
|
the people who helped work on the C implementation.
|
|
|
|
````
|
|
/* Nga ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
Copyright (c) 2008 - 2017, Charles Childers
|
|
Copyright (c) 2009 - 2010, Luke Parrish
|
|
Copyright (c) 2010, Marc Simpson
|
|
Copyright (c) 2010, Jay Skeer
|
|
Copyright (c) 2011, Kenneth Keating
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */
|
|
````
|
|
|
|
## Boilerplate
|
|
|
|
Since the code is in C, we have to include some headers.
|
|
|
|
````
|
|
#include <stdio.h>
|
|
#include <stdint.h>
|
|
#include <stdlib.h>
|
|
#include <unistd.h>
|
|
#include <string.h>
|
|
````
|
|
|
|
## Configuration
|
|
|
|
To make it easier to adapt Nga to a specific target, we keep some
|
|
important constants grouped together at the start of the file.
|
|
|
|
These defaults are targeted towards a 32-bit model, with several
|
|
megabytes of RAM.
|
|
|
|
For smaller targets, drop the IMAGE_SIZE considerably as that's the
|
|
biggest pool of memory needed. Alternately, for use on machines with
|
|
plenty of RAM, consider increasing these and reaping the benefits of
|
|
a much larger memory and stack space.
|
|
|
|
````
|
|
#define CELL int32_t
|
|
#define IMAGE_SIZE 524288 * 16
|
|
#define ADDRESSES 2048
|
|
#define STACK_DEPTH 512
|
|
````
|
|
|
|
## Numbering The Instructions
|
|
|
|
For this implementation an enum is used to name each of the
|
|
instructions. For reference, here are the instructions and their
|
|
corresponding values (in decimal):
|
|
|
|
0 nop 7 jump 14 gt 21 and
|
|
1 lit <v> 8 call 15 fetch 22 or
|
|
2 dup 9 ccall 16 store 23 xor
|
|
3 drop 10 return 17 add 24 shift
|
|
4 swap 11 eq 18 sub 25 zret
|
|
5 push 12 neq 19 mul 26 end
|
|
6 pop 13 lt 20 divmod
|
|
|
|
````
|
|
enum vm_opcode {
|
|
VM_NOP, VM_LIT, VM_DUP, VM_DROP, VM_SWAP, VM_PUSH, VM_POP,
|
|
VM_JUMP, VM_CALL, VM_CCALL, VM_RETURN, VM_EQ, VM_NEQ, VM_LT,
|
|
VM_GT, VM_FETCH, VM_STORE, VM_ADD, VM_SUB, VM_MUL, VM_DIVMOD,
|
|
VM_AND, VM_OR, VM_XOR, VM_SHIFT, VM_ZRET, VM_END
|
|
};
|
|
#define NUM_OPS VM_END + 1
|
|
````
|
|
|
|
## VM State
|
|
|
|
The VM state is held in a few global variables. (It'd be better to use
|
|
a struct here, as Ngaro does, but this makes everything else a bit less
|
|
readable.)
|
|
|
|
Some things to note:
|
|
|
|
The data stack (**data**), address stack (**address**), and memory
|
|
(**memory**) are simple linear arrays.
|
|
|
|
There are stack pointers (**sp** for **data** and **rp** for
|
|
**address**), and an instruction pointer (**ip**). These are *not*
|
|
exposed via the instruction set.
|
|
|
|
````
|
|
CELL sp, rp, ip;
|
|
CELL data[STACK_DEPTH];
|
|
CELL address[ADDRESSES];
|
|
CELL memory[IMAGE_SIZE + 1];
|
|
````
|
|
|
|
## A Little More Boilerplate
|
|
|
|
Here we have a few bits of shorthand that'll be handled by the C
|
|
preprocessor. These are used for readability purposes.
|
|
|
|
````
|
|
#define TOS data[sp]
|
|
#define NOS data[sp-1]
|
|
#define TORS address[rp]
|
|
````
|
|
|
|
## Loading an Image File
|
|
|
|
A standard image file is a raw memory dump of signed integer values.
|
|
(The size of these is determined by the value of CELL; Nga defaults
|
|
to 32-bit)
|
|
|
|
What we do here is:
|
|
|
|
* attempt to open the file
|
|
* use **fseek()** and **ftell()** to find the length of the file.
|
|
* divide the length by the size of a cell to determine the number of cells
|
|
* read the cells into memory (**image**)
|
|
* return the size of the data read (in bytes)
|
|
|
|
````
|
|
CELL ngaLoadImage(char *imageFile) {
|
|
FILE *fp;
|
|
CELL imageSize;
|
|
long fileLen;
|
|
|
|
if ((fp = fopen(imageFile, "rb")) != NULL) {
|
|
/* Determine length (in cells) */
|
|
fseek(fp, 0, SEEK_END);
|
|
fileLen = ftell(fp) / sizeof(CELL);
|
|
rewind(fp);
|
|
|
|
/* Read the file into memory */
|
|
imageSize = fread(&memory, sizeof(CELL), fileLen, fp);
|
|
fclose(fp);
|
|
}
|
|
else {
|
|
printf("Unable to find the ngaImage!\n");
|
|
exit(1);
|
|
}
|
|
return imageSize;
|
|
}
|
|
````
|
|
|
|
## Preparations
|
|
|
|
This function initializes all of the variables and fills the arrays
|
|
with known values. Memory is filled with **VM_NOP** instructions; the
|
|
others are populated with zeros.
|
|
|
|
````
|
|
void ngaPrepare() {
|
|
ip = sp = rp = 0;
|
|
|
|
for (ip = 0; ip < IMAGE_SIZE; ip++)
|
|
memory[ip] = VM_NOP;
|
|
|
|
for (ip = 0; ip < STACK_DEPTH; ip++)
|
|
data[ip] = 0;
|
|
|
|
for (ip = 0; ip < ADDRESSES; ip++)
|
|
address[ip] = 0;
|
|
}
|
|
````
|
|
|
|
## The Instructions
|
|
|
|
I've chosen to implement each instruction as a separate function. This
|
|
keeps them shorter, and lets me simplify the instruction processor
|
|
later on.
|
|
|
|
The **NOP** instruction does nothing.
|
|
|
|
````
|
|
void inst_nop() {
|
|
}
|
|
````
|
|
|
|
**LIT** is a special case: it's followed by a value to push to the
|
|
stack. This needs to increment the **sp** and **ip** and push the value
|
|
at the incremented **ip** to the stack.
|
|
|
|
````
|
|
void inst_lit() {
|
|
sp++;
|
|
ip++;
|
|
TOS = memory[ip];
|
|
}
|
|
````
|
|
|
|
**DUP** duplicates the top item on the stack.
|
|
|
|
````
|
|
void inst_dup() {
|
|
sp++;
|
|
data[sp] = NOS;
|
|
}
|
|
````
|
|
|
|
**DROP** removes the top item from the stack.
|
|
|
|
````
|
|
void inst_drop() {
|
|
data[sp] = 0;
|
|
if (--sp < 0)
|
|
ip = IMAGE_SIZE;
|
|
}
|
|
````
|
|
|
|
**SWAP** switches the top and second items on the stack.
|
|
|
|
````
|
|
void inst_swap() {
|
|
int a;
|
|
a = TOS;
|
|
TOS = NOS;
|
|
NOS = a;
|
|
}
|
|
````
|
|
|
|
**PUSH** moves the top value from the data stack to the address stack.
|
|
|
|
````
|
|
void inst_push() {
|
|
rp++;
|
|
TORS = TOS;
|
|
inst_drop();
|
|
}
|
|
````
|
|
|
|
**POP** moves the top item on the address stack to the data stack.
|
|
|
|
````
|
|
void inst_pop() {
|
|
sp++;
|
|
TOS = TORS;
|
|
rp--;
|
|
}
|
|
````
|
|
|
|
**JUMP** moves execution to the address on the top of the stack.
|
|
|
|
````
|
|
void inst_jump() {
|
|
ip = TOS - 1;
|
|
inst_drop();
|
|
}
|
|
````
|
|
|
|
**CALL** calls a subroutine at the address on the top of the stack.
|
|
|
|
````
|
|
void inst_call() {
|
|
rp++;
|
|
TORS = ip;
|
|
ip = TOS - 1;
|
|
inst_drop();
|
|
}
|
|
````
|
|
|
|
**CCALL** is a conditional call. It takes two values: a flag and a
|
|
pointer for an address to jump to if the flag is true.
|
|
|
|
A false flag is zero. Any other value is true.
|
|
|
|
Example:
|
|
|
|
:t
|
|
lit 100
|
|
return
|
|
:f
|
|
lit 200
|
|
return
|
|
:main
|
|
lit 1
|
|
lit 2
|
|
eq
|
|
lit t
|
|
ccall
|
|
li f
|
|
call
|
|
end
|
|
|
|
````
|
|
void inst_ccall() {
|
|
int a, b;
|
|
a = TOS; inst_drop(); /* False */
|
|
b = TOS; inst_drop(); /* Flag */
|
|
if (b != 0) {
|
|
rp++;
|
|
TORS = ip;
|
|
ip = a - 1;
|
|
}
|
|
}
|
|
````
|
|
|
|
**RETURN** ends a subroutine and returns flow to the instruction
|
|
following the last **CALL** or **CCALL**.
|
|
|
|
````
|
|
void inst_return() {
|
|
ip = TORS;
|
|
rp--;
|
|
}
|
|
````
|
|
|
|
**EQ** compares two values for equality and returns a flag.
|
|
|
|
````
|
|
void inst_eq() {
|
|
NOS = (NOS == TOS) ? -1 : 0;
|
|
inst_drop();
|
|
}
|
|
````
|
|
|
|
**NEQ** compares two values for inequality and returns a flag.
|
|
|
|
````
|
|
void inst_neq() {
|
|
NOS = (NOS != TOS) ? -1 : 0;
|
|
inst_drop();
|
|
}
|
|
````
|
|
|
|
**LT** compares two values for less than and returns a flag.
|
|
|
|
````
|
|
void inst_lt() {
|
|
NOS = (NOS < TOS) ? -1 : 0;
|
|
inst_drop();
|
|
}
|
|
````
|
|
|
|
**GT** compares two values for greater than and returns a flag.
|
|
|
|
````
|
|
void inst_gt() {
|
|
NOS = (NOS > TOS) ? -1 : 0;
|
|
inst_drop();
|
|
}
|
|
````
|
|
|
|
**FETCH** takes an address and returns the value stored there.
|
|
|
|
This doubles as a means of introspection into the VM state. Negative
|
|
addresses correspond to VM queries:
|
|
|
|
| Address | Returns |
|
|
| ------- | ------------------- |
|
|
| -1 | Data stack depth |
|
|
| -2 | Address stack depth |
|
|
| -3 | Maximum Image Size |
|
|
|
|
An implementation may use negative values below -100 for implementation
|
|
specific inquiries.
|
|
|
|
````
|
|
void inst_fetch() {
|
|
switch (TOS) {
|
|
case -1: TOS = sp - 1; break;
|
|
case -2: TOS = rp; break;
|
|
case -3: TOS = IMAGE_SIZE; break;
|
|
default: TOS = memory[TOS]; break;
|
|
}
|
|
}
|
|
````
|
|
|
|
**STORE** stores a value into an address.
|
|
|
|
````
|
|
void inst_store() {
|
|
memory[TOS] = NOS;
|
|
inst_drop();
|
|
inst_drop();
|
|
}
|
|
````
|
|
|
|
**ADD** adds two numbers together.
|
|
|
|
````
|
|
void inst_add() {
|
|
NOS += TOS;
|
|
inst_drop();
|
|
}
|
|
````
|
|
|
|
**SUB** subtracts two numbers.
|
|
|
|
````
|
|
void inst_sub() {
|
|
NOS -= TOS;
|
|
inst_drop();
|
|
}
|
|
````
|
|
|
|
**MUL** multiplies two numbers.
|
|
|
|
````
|
|
void inst_mul() {
|
|
NOS *= TOS;
|
|
inst_drop();
|
|
}
|
|
````
|
|
|
|
**DIVMOD** divides and returns the quotient and remainder.
|
|
|
|
````
|
|
void inst_divmod() {
|
|
int a, b;
|
|
a = TOS;
|
|
b = NOS;
|
|
TOS = b / a;
|
|
NOS = b % a;
|
|
}
|
|
````
|
|
|
|
**AND** performs a bitwise AND operation.
|
|
|
|
````
|
|
void inst_and() {
|
|
NOS = TOS & NOS;
|
|
inst_drop();
|
|
}
|
|
````
|
|
|
|
**OR** performs a bitwise OR operation.
|
|
|
|
````
|
|
void inst_or() {
|
|
NOS = TOS | NOS;
|
|
inst_drop();
|
|
}
|
|
````
|
|
|
|
**XOR** performs a bitwise XOR operation.
|
|
|
|
````
|
|
void inst_xor() {
|
|
NOS = TOS ^ NOS;
|
|
inst_drop();
|
|
}
|
|
````
|
|
|
|
**SHIFT** performs a bitwise arithmetic SHIFT operation.
|
|
|
|
This takes two values:
|
|
|
|
xy
|
|
|
|
And returns a single one:
|
|
|
|
z
|
|
|
|
If `y` is positive, this shifts right. If negative, it shifts
|
|
left.
|
|
|
|
````
|
|
void inst_shift() {
|
|
CELL y = TOS;
|
|
CELL x = NOS;
|
|
if (TOS < 0)
|
|
NOS = NOS << (TOS * -1);
|
|
else {
|
|
if (x < 0 && y > 0)
|
|
NOS = x >> y | ~(~0U >> y);
|
|
else
|
|
NOS = x >> y;
|
|
}
|
|
inst_drop();
|
|
}
|
|
````
|
|
|
|
**ZRET** returns from a subroutine if the top item on the stack is
|
|
zero. If not, it acts like a **NOP** instead.
|
|
|
|
````
|
|
void inst_zret() {
|
|
if (TOS == 0) {
|
|
inst_drop();
|
|
ip = TORS;
|
|
rp--;
|
|
}
|
|
}
|
|
````
|
|
|
|
**END** tells Nga that execution should end.
|
|
|
|
````
|
|
void inst_end() {
|
|
ip = IMAGE_SIZE;
|
|
}
|
|
````
|
|
|
|
## Instruction Handler
|
|
|
|
In the past I handled the instructions via a big switch. With Nga, I
|
|
changed this to use a jump table. This is significantly more concise
|
|
and makes maintenance easier overall.
|
|
|
|
So first up, the jump table itself. Just a list of pointers to the
|
|
instruction implementations, in the proper order.
|
|
|
|
````
|
|
typedef void (*Handler)(void);
|
|
|
|
Handler instructions[NUM_OPS] = {
|
|
inst_nop, inst_lit, inst_dup, inst_drop, inst_swap, inst_push, inst_pop,
|
|
inst_jump, inst_call, inst_ccall, inst_return, inst_eq, inst_neq, inst_lt,
|
|
inst_gt, inst_fetch, inst_store, inst_add, inst_sub, inst_mul, inst_divmod,
|
|
inst_and, inst_or, inst_xor, inst_shift, inst_zret, inst_end
|
|
};
|
|
````
|
|
|
|
And now **ngaProcessOpcode()** which calls the functions in the jump
|
|
table.
|
|
|
|
````
|
|
void ngaProcessOpcode(CELL opcode) {
|
|
instructions[opcode]();
|
|
}
|
|
````
|
|
|
|
Nga also allows (optionally) support for packing multiple instructions
|
|
per cell. This has benefits on memory constained targets as four
|
|
instructions can be packed into each cell, reducing memory usage
|
|
significantly.
|
|
|
|
Consider:
|
|
|
|
lit 100
|
|
lit 200
|
|
add
|
|
|
|
In a standard image this will be five cells. One for each instruction
|
|
and one for each data item. With packed instructions it would be three
|
|
cells: one for each four instructions (we only have three here, so the
|
|
unused one is a simple NOP) and one for each data item.
|
|
|
|
This implementation provides two functions for handling these. The
|
|
first takes a packed instruction and validates each instruction as
|
|
being valid. The second will process each of the stored opcodes.
|
|
|
|
Note for those using this: packing should stop when instructions that
|
|
modify the IP for flow control are used. These are:
|
|
|
|
* JUMP
|
|
* CCALL
|
|
* CALL
|
|
* RET
|
|
* ZRET
|
|
|
|
Nga will not stop processing code, but execution flow errors may arise
|
|
if the packing tool does not take these into account.
|
|
|
|
````
|
|
int ngaValidatePackedOpcodes(CELL opcode) {
|
|
CELL raw = opcode;
|
|
CELL current;
|
|
int valid = -1;
|
|
int i;
|
|
for (i = 0; i < 4; i++) {
|
|
current = raw & 0xFF;
|
|
if (!(current >= 0 && current <= 26))
|
|
valid = 0;
|
|
raw = raw >> 8;
|
|
}
|
|
return valid;
|
|
}
|
|
|
|
void ngaProcessPackedOpcodes(int opcode) {
|
|
CELL raw = opcode;
|
|
int i;
|
|
for (i = 0; i < 4; i++) {
|
|
ngaProcessOpcode(raw & 0xFF);
|
|
raw = raw >> 8;
|
|
}
|
|
}
|
|
````
|
|
|
|
Nga is intended to be used as a part of a larger environment adding
|
|
host-specific I/O and functionality. For testing purposes, it is
|
|
possible to run non-interactive images by building defining STANDALONE
|
|
when compiling this source. A sample `main()` is included below showing
|
|
how to use this.
|
|
|
|
````
|
|
#ifdef STANDALONE
|
|
int main(int argc, char **argv) {
|
|
ngaPrepare();
|
|
if (argc == 2)
|
|
ngaLoadImage(argv[1]);
|
|
else
|
|
ngaLoadImage("ngaImage");
|
|
|
|
CELL opcode, i;
|
|
|
|
ip = 0;
|
|
while (ip < IMAGE_SIZE) {
|
|
opcode = memory[ip];
|
|
if (ngaValidatePackedOpcodes(opcode) != 0) {
|
|
ngaProcessPackedOpcodes(opcode);
|
|
} else if (opcode >= 0 && opcode < 27) {
|
|
ngaProcessOpcode(opcode);
|
|
} else {
|
|
printf("Invalid instruction!\n");
|
|
printf("At %d, opcode %d\n", ip, opcode);
|
|
exit(1);
|
|
}
|
|
ip++;
|
|
}
|
|
|
|
for (i = 1; i <= sp; i++)
|
|
printf("%d ", data[i]);
|
|
printf("\n");
|
|
exit(0);
|
|
}
|
|
#endif
|