diff --git a/README.md b/README.md index ec66c30..18ea001 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,9 @@ # The Simplest Virtual Computer (16 bit) +
Logo
-This is the spec for an extremely simple "virtual computer" that can be emulated. +This is the specification for an extremely simple "virtual computer" that can be emulated. The goal in one word is **simplicity**. It should be simple to understand every instruction, to write machine code that runs on it, and to write a compiler for it. @@ -10,14 +11,17 @@ The instruction set and the design in general are in no way meant to be "realist It is also not intended to be as simple and elegant as it could possibly be. This repo contains an emulator to run games or programs. It can be installed with cargo: + ```sh cargo install --git https://github.com/JanNeuendorf/SVC16 ``` You can then run a program from the cli: + ```sh svc16 /path/to/my_rom.svc16 ``` + Use `--help` to see some basic options. I do not want to provide an assembler, any kind of compiler or even any ideas about things like call conventions. @@ -27,8 +31,8 @@ The idea is that you have to build that yourself. You can play a game from the e - ## Quick Overview + ### No Registers There are no CPU registers, just one chunk of memory. Values can be loaded from every memory address and written to every memory address. @@ -45,8 +49,8 @@ The screen-buffer is the same size as the memory and there is one pixel for ever ### No Fluff There are as few features as possible. -That means limited input, no sound, no variable display size etc. -It also means that there are no accelerators or trick to help with performance. +That means limited input, no sound, no variable display size etc. +It also means that there are no accelerators or tricks to help with performance. ### Setup Here is a sketch of all components of the virtual computer: @@ -55,7 +59,7 @@ Here is a sketch of all components of the virtual computer: ### Instruction-pointer -This value is an address in the main memory. It starts as zero. Then, it is manipulated by the instructions. All operations are wrapping. +This value is an address in the main memory. It starts as zero. Then, it is manipulated by the instructions. All operations performed on the instruction pointer are wrapping. ### Screen @@ -67,22 +71,28 @@ The only supported inputs are the mouse position and the left and right mouse ke On synchronization the input on the last frame is loaded into the input-buffer. -The "Position code" is the index of the pixel, the mouse is currently on. -The "Key code" is given by left_mouse+2*right_mouse. So it can have the values 0 1 2 or 3. +The *position code* is the index of the pixel, the mouse is currently on. +The *key code* is given by left_mouse+2*right_mouse. So it can have the values 0 1 2 or 3. There is no guarantee that the inputs are synced on the next frame. Before the first synchronization, the input codes are zero. ### Synchronization -When the console executes the **Sync** instruction, the screen-buffer is drawn to the screen. It is not cleared. The input-buffer is updated. The system will be put to sleep until the beginning of the next frame. The targeted timing is 30fps. There is a hard limit of 3000000 instructions per frame. This means that if the **Sync** command has not be called for 3000000 instructions, it will be performed automatically. +When the console executes the **Sync** instruction, the screen-buffer is drawn to the screen. +It is not cleared. The input-buffer is updated. +The system will be put to sleep until the beginning of the next frame. +The targeted timing is 30fps. There is a hard limit of 3000000 instructions per frame. +This means that if the **Sync** command has not be called for 3000000 instructions, it will be performed automatically. -## CPU +### CPU -All instructions are 4 values long. A value is, of course, a u16. +All instructions are 4 values long. A value is, of course, a u16. -The instructions have the form `opcode arg1 arg2 arg3`. +The instructions have the form `opcode arg1 arg2 arg3`. -In the following table, all instructions are listed. `@arg1` refers to the value at the memory address `arg1`. If the opcode is greater than 15, it is treated as being zero. If one of the three arguments is not used, it can be set to any value, but it can not be omitted. +In the following table, all instructions are listed. `@arg1` refers to the value at the memory address `arg1`. +If the opcode is greater than 15, the system will abort. +If one of the three arguments is not used, it can be set to any value, but it can not be omitted. When the instruction-pointer advances, it does so by four positions. @@ -95,39 +105,73 @@ When the instruction-pointer advances, it does so by four positions. | 4 | **Sub** | yes | `@arg3=(@arg1-@arg2)` | | 5 | **Mul** | yes | `@arg3=(@arg1*@arg2)` | | 6 | **Div** | yes | `@arg3=(@arg1/@arg2)` | -| 7 | **Cmp** | yes | `@arg3=(@arg1<@arg2)` as unsigned | +| 7 | **Cmp** | yes | `@arg3=(@arg1<@arg2)` as unsigned | | 8 | **Deref** | yes | `@arg2=@(@arg1+arg3)` | | 9 | **Ref** | yes | `@(@arg1+arg3)=@arg2` | | 10 | **Inst** | yes | `@arg1=inst_ptr` | | 11 | **Print** | yes | Writes `color=@arg1` to `index=@arg2` of screen-buffer. | -| 12 | **Read** | yes | Copies `index=@arg1` of screen-buffer to `@arg2` | +| 12 | **Read** | yes | Copies `index=@arg1` of screen-buffer to `@arg2` | | 13 | **Band** | yes | `@arg3=@arg1&@arg2` | | 14 | **Xor** | yes | `@arg3=@arg1^@arg2` | | 15 | **Sync** | yes | Puts `@arg1=position_code`, `@arg2=key_code` and synchronizes in that order | -## Constructing a Program +### Constructing a Program -A program is really just the state of the main memory. There is no distinction between memory that contains instructions and memory that contains some other asset. The initial state is loaded from a binary file that is read as containing the (le) u16 values in order. The maximum size is $2*2^{16}=$ bytes ($\approx$ 131.1kB). -It can be shorter, in which case the end is padded with zeroes. +A program is really just the initial state of the main memory. +There is no distinction between memory that contains instructions and memory that contains some other asset. +The initial state is loaded from a binary file that is read as containing the (le) u16 values in order. The maximum size is $2*2^{16}=$ bytes ($\approx$ 131.1kB). +It can be shorter, in which case the end is padded with zeroes. The computer will begin by executing the instruction at index 0. -## Example +### Example -A simple example would be to print all $2^{16}$ possible colors to the screen. -We make our lives easier, by mapping each index of the screen-buffer to the color which is encoded with the index. +A simple example would be to print all $2^{16}$ possible colors to the screen. +We make our lives easier, by mapping each index of the screen-buffer to the color which is encoded with the index. Here, we use the names of the opcodes instead of their numbers. ``` -Set 501 1 0 // Set the number one to 501 -Set 502 65535 0 // Set the number one to 501 -Print 500 500 0 // Print the color at 500 to the index at 500 -Add 500 501 500 // Increment the color value -Cmp 500 502 503   // See if we are not at the max number -Xor 503 501 503   // Negate it -Skip 0 4 503 // unless we are at the max number, go back +Set 501 1 0 // Write the value 1 to address 501 +Set 502 65535 0 // Write the largest possible value to 502 +Print 500 500 0 // Display color=@500 at screen-index=@500 +Add 500 501 500 // Increment the color/screen-index +Cmp 500 502 503 // See if we are not at the max number +Xor 503 501 503 // Negate it +Skip 0 4 503 // Unless we are at the max number, go back 4 instructions Sync 0 0 0 // Sync GoTo 0 0 0 // Repeat to keep the window open ``` +We could rely on the fact that the value at index 500 starts at zero and we did not have to initialize it. -We get the following output: +To build a program that we can execute, we could use python: -![](colors_scaled.png) +```python +import struct + +code = [ + 0, 501, 1, 0, #Opcodes replaced with numbers + 0, 502, 65535, 0, + 11, 500, 500, 0, + # ... +] +with open("all_colors.svc16", "wb") as f: + for value in code: + f.write(struct.pack("