! This repo is very out of date and I have not kept it up to date with any changes to the spec since January 2022 !
I have lost interest in this project and am unlikely to update it any time soon. The instruction set itself has changed and I believe there have been lots of changes to various devices in the interim. Take everything still here with a grain of salt.
Uxn is a stack-based virtual machine that describes an Instruction Set Architecture. Varvara is a specification for a set of I/O devices connected to a Uxn cpu.
https://git.sr.ht/~rabbits/uxn is the reference implementation of Uxn+Varvara.
- <uxn.md> - Information on the CPU core and instruction set
- <devices.md> - The device interrupt model of the Uxn CPU
- <devices/console.md> - Byte stream device
- <devices/audio.md> - 8-bit sampled audio channels
- <devices/datetime.md> - System to poll the real-world time
- <devices/controller.md> - Keyboard/gamepad input device
- <devices/file.md> - Access to external data sources
- <devices/screen.md> - The graphics system.
The reference implementation uses SDL 2 and C89.
uxn.c implements the CPU core and can be copied into your project without modifications.
uxnemu.c contains SDL event handling code and window management. It also contains all of the "glue" code to set up the CPU core and initialize memory with ROM contents.
If your target has SDL support then the project may build on its own. Otherwise, you will have to re-implement the devices and glue code for your target platform. The device implementations are mixed between uxnemu.c and the "device" subdirectory.
So you want to port Uxn to a new programming language?
The first thing you should do is read <uxn.md> as well as the Uxntal overview. These provide an overview of the guts of the virtual machine and its instructions. <uxn.md> also contains more detail where it is lacking in the official references. You'll need to implement a stack as well as some sort of buffer that can store 64Kb of data.
Depending on the bitwise support in your language of choice, it may be useful to create some helper methods to translate between shorts and bytes.
Once you have the basic data structures implemented, you should move on to the Uxn instruction set reference. This reference describes each of the Uxn instructions in detail with examples of what the stack should look like for each operation.
As you implement the different opcodes, you may find it helpful to run these test programs. Each test program covers one set of related opcodes and should help find errors if one of your opcodes is not implemented correctly.
By the end of this process your CPU implementation should be able to take in a 16-bit address and execute opcodes from memory until it hits a BRK opcode ( 0x00 )