A programming language for the Uxn virtual machine.

Uxn programs are written in a stack-based flavor of assembly designed especially for this portable virtual machine. Tal files are textual source files, Rom files are binary program files; applications that transform Tal files into Rom files are called Assemblers.

• Zine, by Clemens Scott.
• Cheatsheet, by Weeble.
• Tutorial, by Compudanzas
• Manual(7), by Eiríkr Åsheim.
• BNF Notation, by Jack Leightcap.

Setup

Here is a quick way to get started writing programs with a little self-hosted assembler and an emulator which includes the Console device:

# Build the emulator
cc uxnmin.c -o uxnmin

# Build the assembler
xxd -r -p drifloon.rom uxnasm.rom

# Assemble a tal file
cat opctest.tal | uxnmin uxnasm.rom > opctest.rom

# Run a rom file
uxnmin opctest.rom

Uxntal Syntax

In stack programming there are no variables and no precedence rules, the calculations are merely performed in the sequence in which they are presented. The order with which elements come off the stack is known as Last In, First Out. In the stack a b c, the c item was the last to be added, and will be the first to be removed.

#01 DUP ADD #03 MUL program

 01  01  02  03  06 stack
     01      02

Numbers in Uxntal are not decimal, they are expressed in hexadecimal. Which means that counting goes like: one, two, three, four, five, six, seven, eight, nine, ha, be, ce, de, he, fe, ten! It takes some getting used to, but don't worry, you'll get the hang of it.

Now, without further ado..

Let's dive into it!

The following example program prints the phrase "Hello World!" by pushing the address to a label on the stack, and iterating through each letter found at that address with a loop that increments the pointer until it reaches end of the phrase, at which point, the stack is emptied and the evaluation halts.

A word starting with @ defines a label, and one starting with ; pushes the absolute address of a label to the stack. With that in mind, ;text pushes the two bytes equal to the address of the @text label to the stack. In the interpreter above, press "step" to walk through each step of the evaluation.

Next, we define a new label named @while, to mark the start of the loop that will print each character stored at the text label.

The LDAk opcode loads a byte at the address currently at the top of the stack, in this case, the ascii letter H(48). The k-mode indicates that the operator will not consume the address.

The DUP opcode makes a copy of the letter. The ?{ pops that letter from the stack, and if it is not zero, we jump to the corresponding }, which is an anonymous label(λ00).

( Disassembly of the example above:
|addr   bytecode   Uxntal
-----   --------   ------- )
|0100   a0 01 12   ( ;text )

@while
|0103   94         ( LDAk )
|0104   06         ( DUP )
|0105   20 00 03   ( ?λ00 )
|0108   02         ( POP )
|0109   22         ( POP2 )
|010a   00         ( BRK )

The #18 word pushes a number to the stack, which maps to the Console/write port(#18), followed by the DEO opcode that pops both bytes(the letter and the port) and sends the letter to that device port, telling the Console to print it, leaving only the address on top of the stack.

The INC2 opcode increments the address, moving the text pointer to the next letter. The 2-mode is used because the address is made of two bytes.

@λ00
|010b   80 18      ( #18 )
|010d   17         ( DEO )
|010e   21         ( INC2 )
|010f   40 ff f1   ( !while )

Finally, with !while we jump back to the @while label, and repeat the loop until there are no more letters to load. When that happens, we POP to remove the duplicated letter, and POP2 to remove the address on the stack to keep the stack clean at the end of the evaluation.

@text
|0112   48 65 6c   ( H e l )
|0115   6c 6f 20   ( l o   )
|0117   57 6f 72   ( W o r )
|011b   6c 64 21   ( l d ! )

Summary

Comments are within parentheses, numbers are lowercase hexadecimal shorts or bytes and opcodes are uppercased reserved words with lowercased modes. A rune is a non-alphanumeric symbol at the start of a word, literal numbers are prefixed with a # rune, addressing is done by one of six runes. Labels and macros are unique non-numeric, non-opcode and non-runic symbols.

Uxntal Stacks

All programming in Uxntal is done by manipulating the working stack, and return stack, each stack contains 256 bytes. Here are some stack primitives assuming the initial state of the stack is a b c where c is the top of the stack:

A byte is a number between 0-255(256 values), a short is a number between 0-65535(65536 values) made of two bytes, each byte in a short can be manipulated individually:

#0a #0b POP 0a
#12 #3456 NIP 12 56
#1234 DUP 12 34 34

The two stacks are circular, to pop an empty stack does not trigger an error, but merely means to set the stack pointer to 255. There are no invalid programs, any sequence of bytes is a potential Uxn program. Values are moved between stacks with the STH opcode.

WST 00 00 00 00 00 00|12 34 <02
RST 00 00 00 00 00 00 00|56 <01

The program above contains 12 and 34 on the working stack, and 56 on the return stack. The stack content can always be printed by sending a non-null byte to the System/debug port.

Uxntal Notation

The Uxntal notation follows that of the Forth programming language, where each item on the left of the -- spacer is the state of the stack before, and to the right, the state of the stack after:

@routine ( a b -- a b c )
	ADDk JMP2r

By default, single items are a byte long, and shorts are indicated with a * suffix, the order in which they appear is the order of the stack with the top item to the right:

@routine ( a b* -- b* a )
	ROT JMP2r

The dot notation is used to indicate that stack effects to the right of the dot are happening on the return stack:

@routine ( a . b -- c )
	STHr ADD JMP2r

If a routine is a vector, it uses the arrow notation.

@on-event ( -> )
	BRK

Validation

Program validation is done at compile-time by comparing a routine's stack effect, against the resulting balance of all stack changes occurring in the routine's code. Words that do not pass the stack-checker are generating a warning, and so essentially this defines a very basic and permissive type system that nevertheless catches some invalid programs and enables compiler optimizations. For more details, see Uxnbal.

The simplest case is when a piece of code does not have any branches or recursion, and merely pushes literals and calls words. The stack effect routines is always known statically from the declaration.

@add-eight ( a -- a+8 )
	#0008 ADD JMP2r

Working-stack imbalance of +1, in add-eight.

In the case of branching, each branch is evaluated and if an imbalance occurs inside one of the branches, the branch name is indicated:

@branching ( a* -- c )
	LDAk #01 EQU ?&one
	LDAk #02 EQU ?&two
	POP2 #ff JMP2r
	&one ( a* -- c ) POP2 #12 JMP2r
	&two ( a* -- c d ) ADD JMP2r

Working-stack imbalance of -1, in branching/two.

In the case of a recursion, the validator will use the stack effect instead of repeatedly walking through the body of the routine.

@print-string ( str* -- )
	LDAk DUP ?{ POP POP2 JMP2r }
	emit-letter 
	INC2 !print-string

For loops that exits without affecting the stack depth, a > prefixed label is used as a shorthand to reduce the need for extraneous stack effect definitions in cases where it can be inferred:

@many-times ( a -- )
	DUP
	&>l
		INC DUP ?&>l
	POP2 JMP2r

Routines that pull items from the stack beyond their allowed depth will also raise a warning, making the stack effect act a sort of boundary:

@shallow ( a -- )
	POP2 JMP2r

Working-stack depth error of 1, in shallow.

Lastly, a runtime specific solution to validate the stack state at any one point during the execution of a program, is to read the System/wst port and compare it against a given stack pointer byte value.

@on-reset ( -> )
	#abcd DUP2 
	.System/wst DEI #05 EQU ?{
		#01 .System/debug DEO }
	BRK

Comments

A comment starts with any token beginning with opened parenthesis, and ends at its corresponding closed parenthesis. Comments may be nested, the enclosed comments parentheses must be whitespace separated on both sides.

( ( nested ) )
( 1+2*(4/3) )

Outermost comments may be named, which means that sometimes the open parenthesis is immediately followed by a word used to indicates some meaning to external tools.

(doc
	This is a docstring. )

Brackets

The square brackets do nothing, they are there merely for readability and formatting, they are useful for making explicit certain things like grouping behaviors, joining literals or indicating lookup tables.

@routine ( -- )
	[ LIT2 20 -Console/write ] DEO JMP2r

%min ( a b -- r ) {
	GTHk [ JMP SWP ] POP }

@sprite [ 00 66 ff ff ff 7e 3c 18 ]

Uxntal Opcodes

Uxn has 32 standard opcodes and 4 immediate opcodes. In the table below, the | character indicates an effect on the return stack, the pc is the program counter, an value8 indicates a byte length, a value* indicates a short length, an unspecified length follows the short mode and a [value] is read from memory.

Stack I             Logic              Memory I            Arithmetic
BRK --              EQU a b -- a=b     LDZ abs8 -- [abs8]  ADD a b -- a+b  
INC a -- a+1        NEQ a b -- a≠b     STZ val abs8 --     SUB a b -- a-b  
POP a --            GTH a b -- a>b     LDR rel8 -- [rel8]  MUL a b -- a×b  
NIP a b -- b        LTH a b -- a<b     STR val rel8 --     DIV a b -- a÷b

Stack II            Stash              Memory II           Bitwise
SWP a b -- b a      JMP addr --        LDA abs* -- [abs*]  AND a b -- a&b
ROT a b c -- b c a  JCN cond8 addr --  STA val abs* --     ORA a b -- a|b
DUP a -- a a        JSR addr -- | pc*  DEI dev -- [dev]    EOR a b -- a^b
OVR a b -- a b a    STH a -- | a       DEO val dev --      SFT a sft8 -- res

LIT -- [pc*]        JCI cond8 --       JMI --              JSI -- | pc*

Modes

An opcode is any name in which the 3 first characters are found in the opcode table, followed by any combination of 2, k and r. Each opcode has 3 possible modes, which can combined:

• The short mode 2 operates on shorts, instead of bytes.
• The keep mode k operates without consuming items.
• The return mode r operates on the return stack.

By default, operators consume bytes from the working stack, notice how in the following example only the last two bytes #45 and #67 are added, even if there are two shorts on the stack.

#1234 #4567 ADD12 34 ac

The short mode consumes two bytes from the stack. In the case of jump opcodes, the short-mode operation jumps to an absolute address in memory. For the memory accessing opcodes, the short mode operation indicates the size of the data to read and write.

#1234 #4567 ADD2 57 9b

The keep mode does not consume items from the stack, and pushes the result on top. Every opcode begins by popping values from the stack before operating on them. This mode keeps a copy of the stack pointer to recover after the popping stage.

#1234 #4567 ADD2k 12 34 45 67 57 9b

The return mode swaps the stacks on which an opcode operates. Under this mode, a return address will be pushed to the working stack, and stashing will take from the return stack. For that reason, there is no return opcode. For example, the JSR opcode pushes the return address onto the return stack, and JMP2r jumps to that address.

LITr 12 #34 STH ADDr STHr 46

Immediate opcodes

Immediate opcodes are operators that do not take items from the stack, but read values stored immediately after the opcode in the program's memory. Uxntal has 4 immediate opcodes:

• The literal LIT opcode, also written as #.
• The jump !routine.
• The conditional jump ?routine.
• The subroutine routine.

The immediate jump opcodes are slightly faster than their standard opcode counterparts, but do not have modes and cannot be used to do pointer arithmetic. The address value of the immediate opcodes are stored in memory as relative shorts, enabling routines making use of these opcodes to be moved around in the program's memory.

@on-reset ( -> )
	#0007 fact
	BRK

@fact ( n* -- res* )
	ORAk ?{ POP2 #0001 JMP2r }
	DUP2 #0001 SUB2 fact MUL2
	JMP2r

To learn more about each opcode, see the Opcode Reference.

Uxntal Numbers

Uxntal uses only lowercase unsigned hexadecimal numbers of either 2 or 4 characters in length. There are two types of numbers:

• A Literal Hex, like #ab, denotes a number that will be pushed on the stack when evaluated, it is made of a LIT opcode that matches its length, followed by a Raw Hex number.
• A Raw Hex, like aa, is the standard textual encoding of data in a program, generally speaking these are more often loaded than evaluated. It can be anything, an opcode, an ascii byte, an address, part of a sprite.

#12 #34 LIT2 5678 ADD2 68 ac

Uxntal Labels

A label is a non-numeric, non-opcode, and non-runic symbol that correspond to a number between 0 and 65536. A label name is made of two parts, a scope and a sublabel. Sublabels can be added to a scope with the &name rune, or by writing the full name, like @scope/name. Note that a labels like bed, add and cafe are considered numeric.

Functions are simply labels that will be jumped to, and returned from.

@func ( a b -- c )
	&loop
		INC GTHk ?&loop
	ADD JMP2r

Constants are labels that hold a specific value through the entire execution of the program. They allow to assign a name to a number, making the code more readable.

|1400 @limit

Enums are labels with padded members of equal sizes that can be used as constants in a program, they typically begin by rolling back the program address with |00:

|00 @Suit &clubs $1 &diamonds $1 &hearts $1 &spades

Structs are labels with padded members of different sizes, that maps on a data-structure, they typically space the different members with $1:

|00 @Person &name $2 &age $1 &height $2

Labels can also be used with the padding runes to define a global length. For example, if one needs to specify a length of 0x30 for multiple members of a struct, a value can be specified as follow:

|30 @length
|00 @Struct &field $length

Scope

Uxntal objects are defined statically and allow for the enclosed methods to access encapsulated local &members. The example below contains an object with the method set-color, accessible from outside the scope as pen/set-color.

@pen
	&position &x $2 &y $2
	&color $1

&set-color ( color -- )
	,/color STR
	JMP2r

New methods and members can extend an existing scope from anywhere by creating a label with the scope name followed by a slash and the name of the extension. The &labels declared within the extension have the same access to local labels as the rest of the object.

@pen/get-position ( -- x* y* )
	,/x LDR2 ,/y LDR2
	JMP2r

When calling local methods the scope's name can be omitted, starting at the slash, like /method:

@pen/paint ( -- )
	/get-position canvas/draw-line-to
	JMP2r

Addressing

A labels is a way of assigning a name to a number. There are six ways to get the number corresponding to that label. Literal addressing prefixes the label with a LIT for Relative and Zero-Page addressing, and LIT2 for absolute addressing.

• Literal Relative, like ,label, pushes a relative distance byte to the label.
• Literal Zero-Page, like .label, pushes an absolute address byte to the label.
• Literal Absolute, like ;label, pushes an absolute address short to the label.
• Raw Relative, like _label, writes a relative distance byte to the label.
• Raw Zero-Page, like -label, writes an absolute address byte to the label.
• Raw Absolute, like =label, writes an absolute address short to the label.

Raw addressing is used for building data-structures and more advanced programs. A relatively common usage of raw runes is to create literals directly into the return stack:

[ LIT2r 08 -label ] LDZr ADDr | [.label]+8

Anonymous Labels

Anonymous labels are designated with a curly bracket that points to its associated closing bracket, and can be nested. Under the hood, the opening bracket assembles to the address of the closing bracket which allows the destination address to be used like any other label such as a JCI ?{, a JMI, !{ or a plain literal ;{. Here are some example data-structures:

@counted-string
	_{ "foo 20 "bar }

@linked-list
	={ ={ "A } ={ "B ={ "C } } }

Unless Blocks

It is important to notice that in the case of a conditional jump, the lambda's content is jumped over when the flag byte is true.

[ LIT2 &last $1 -Mouse/state ] DEI DUP ,&last STR
DUP2 #0001 NEQ2 ?{ ( on down ) }
DUP2 #0101 NEQ2 ?{ ( on drag ) }
DUP2 #0100 NEQ2 ?{ ( on release ) }
POP2

The opening curly bracket assembles to a unique label reference, and the closing bracket to a corresponding matching label definition. They do not affect the scope.

Uxntal Macros

A macro is a way of defining inline routines, it allows to create new words that will be replaced by the body of the macro, as opposed to a jump where the program counter will move to a routine and back, therefore it needs to be defined before its usage, as follow:

%modulo ( num denum -- res ) {
	DIVk MUL SUB }

@routine ( -- c* )
	#18 #03 modulo JMP2r

In the previous example, the token modulo will get replaced by the body of the macro during assembly:

@routine ( -- c* )
	#18 #03 DIVk MUL SUB JMP2r

Uxntal Memory

There are 64kb of addressable memory. Roms are always loaded at 0x0100, which is the address of the Reset Vector and where evaluation begins. During boot, the stacks, device and addressable memories are zeroed. During a soft-reboot, the content of the zero-page is preserved.

The device page and stacks are located outside of addressable memory.

• An Absolute Padding, like |100 moves the program generation to an address specified by a number or label.
• A Relative Padding, like $18 moves the program generation by a distance specified by a number or label.

|18 @width

|100 @on-reset ( -> )
	;buffer/end BRK 02 18

|200 @buffer $width &end

Memory is big-endian, when writing or reading a short from memory, the position is that of the high-byte. The low-byte of a short written at 0xffff wraps to 0x0000.

#12 #0200 STA 0x0200=12
#3456 #0400 STA2 0x0400=34, 0x0401=56
#0400 LDA 34

The zero-page is the memory located below 0x0100, its purpose is to store variables that will be accessed often, or needs to be preserved across a soft-reboot. It is sligthly faster to read and write from the zero-page using the LDZ and STZ opcodes as they use only a single byte instead of a short. This memory space cannot be pre-filled in the rom prior to initialization. The low-byte of a short written at 0xff wraps to 0x00.

#1234 #80 STZ2 0x0080=12, 0x0081=34
#81 LDZ 34

Uxntal Devices

Uxn is non-interruptible, vectors are locations in programs that are evaluated when certain events occur. A vector is evaluated until a BRK opcode is encountered. Uxn can communicate with a maximum of 16 devices, each device has 16 ports, each port handles a specific I/O message. Ports are mapped to the devices memory page, which is located outside of the main addressable memory.

All programs begin by executing the reset vector located at 0x100. The content of the stacks are preserved between vectors, but it is discouraged to use the stacks to pass data between vectors.

@on-reset ( -> )
	( set vector )
	;on-mouse .Mouse/vector DEO2
	BRK

@on-mouse ( -> )
	( read state )
	.Mouse/state DEI ?&on-touch
	BRK

&on-touch ( -> )
	( A mouse button is pressed )
	BRK

For example, the address stored in the Mouse/vector ports points to a part of the program to be evaluated when the cursor is moved, or a button state has changed.

Uxntal Utilities

Here's a list of small self-hosted development tools:

• Drifblim is an assembler that also emits a symbols file.
• Uxnfor is a formatter that standardize the source code, this is the formatting style used across the Uxntal documentation.
• Uxnlin is a peephole optimizer that reveals potential optimizations in opcode sequences.
• Uxnbal is a program validator that warns when routines do not match their definitions.
• Uxndis is a disassembler that prints the opcodes in a rom file.

incoming left noodle drifblim catclock theme oquonie bifurcan yufo programming languages gly format ufx format ulz format proquints brainfuck uxn uxntal reference uxntal alphabet bicycle beetbug arvelie about oscean computer 2025 2021