Skip to content

Notes on how to implement the Uxn/Varvara virtual machine specification

Notifications You must be signed in to change notification settings

DeltaF1/uxn-impl-guide

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

7 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

! 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 implementation guide

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.

Index

The Basics

  • <uxn.md> - Information on the CPU core and instruction set
  • <devices.md> - The device interrupt model of the Uxn CPU

Varvara device spec

  • <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.

Porting the C code

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.

Porting to a new language

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.

Opcodes

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 )

Devices

About

Notes on how to implement the Uxn/Varvara virtual machine specification

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published