Toyboxica is a small suite of programs consisting of a small stack based VM, an assembler and a disassembler. It was made for the UBA computing week stand competition 2022 edition. The name is in honor of Toyboxica, the album by Locust Toybox.
Warning: setting a high clock rate in the VM may result in flashing or flickering that will be disturbing for photosensitive people. I hope to address this issue in a future version. If someone wants to give me a hand then they are more than welcome to message me on mastodon: fsan at tilde.zone
The idea was to have the program memory and the video memory share the same address space so that people could visualize values being modified and how the stack was behaving. The project won the competition but it was, sadly, never exhibited due to bad managment by the university.
The VM
The main toy of the project is the virtual machine.
The virtual machines uses 2 stacks: a "cpu stack" and the function stack. When pushing and popping you will always be working with the cpu stack, the function stack is only used to store return addresses and local variables.
It implements the following 14 instructions:
Memory handling
| Instruction | Parameter | Result |
| push | Pushes a 0 to the top of the stack | |
| pop | Pops the top of the stack | |
| lit | data | Pushes data to the top of the stack |
| load | Pop an element and push the data pointed by the element to the stack | |
| store | Pop two elements store the second element to the position pointed by the first one | |
| local load | Pop an element and push the data pointed by the element, offset by the function stack pointer, to the stack | |
| local store | Pop two elements store the second element to the position pointed by the first one, offset by the function stack pointer |
Arithmetic
| Instruction | Parameter | Result |
| add | Pops two elements from the top of the stack, adds them and pushes the result to the top of the stack | |
| sub | Pops two elements from the top of the stack, substracts them and pushes the result to the top of the stack | |
| mul | Pops two elements from the top of the stack, multiplies them and pushes the result to the top of the stack | |
| div | Pops two elements from the top of the stack, divides them and pushes the result to the top of the stack |
Branching
| Instruction | Parameter | Result |
| bgt | position | Peeks two elements from the top of the stack and branches to position if the top is greater than the second |
| beq | position | Peeks two elements from the top of the stack and branches to position if the top is equal to the second |
| call | func | Calls to func |
| ret | Returns from a call |
The writer
Writer is the assembler of the toybox.
You can mostly write 3 things: instructions, literal values and labels
Below is an example program which should be self explanatory for anyone who has already written assembly. I'm very sorry but I don't really have time for a tutorial though I hope one day I will be able to write one.
.main:
brn .start
.var1: 0x0001
.start:
lit_n .var1
load
lit_n .var1
load
add
The reader
The reader is the writers sibling, even though they don't know how to write they do know their brothers handwriting and are able to descipher the instructions of their siblings programs.
This desciphering is just a dessasembly of the programs produced.
Cancionero
Cancionero was supposed to be a holder of songs, the idea was that cancionero would "sing" to the writer who would then transcribe the songs into programs and the VM would run them.
Sadly this compiler was never finished as there are some structural issues with the VM which should be solved first.
A small gif of a test program in action
Go to project repo.