uxn/doc/uxn.md

# UXN

Reformatted from [the reference document](https://wiki.xxiivv.com/site/uxntal_reference.html)

UXN is a deterministic, non-interrupting, 8-bit instruction set and word stack machine with a 16bi address space.
It interacts with the outside world via port mapped I/O devices, of which 16 are supported.

## Memory model
UXN presents a linear uniform main memory with a 16bi address space.
Programs may do I/O across the entire address space using the `LDR2` and `STR2` instructions.

The UXN address space is divided into chunks called pages, each with 8bi of addressing.
The 0 page (`0x00[00-FF]`) is special and, for convenience, can be accessed using the `LDZ` and `STRZ` instructions.

The UXN stack machine, in keeping with [the forth tradition](http://www.forth.org/svfig/Len/softstak.htm) has two stacks.
These are referred to as `DATA` (stack 0) and `RETURN` (stack 1) by convention.
Instructions may choose to transpose the stacks, allowing for computation on either stack.
See below for more on the `return` flag.

The `LDR` and `STR` instructions are stack relative and allow for computed loads and stores.

## Instruction set

UXN instructions are 8-bit values.

| k    | r      | 2     | opcode    |
|------|--------|-------|-----------|
| keep | return | short | 0 0 0 0 0 |

The three most significant bits of the instructions are mode flags of which we will say more.
The least significant five bits select an instruction.

Effects are written using forth-style notation `inputs -- outputs`

| Opcode | Memonic | Long name                | Data stack effect                           | Control stack effect | PC effect           | Memory effect     |
|--------|---------|--------------------------|---------------------------------------------|----------------------|---------------------|-------------------|
| 0x00   | BRK     | Break                    | --                                          | --                   |                     |                   |
| 0x01   | INC     | Increment                | a -- a+1                                    |                      |                     |                   |
| 0x02   | POP     | Pop                      | a --                                        |                      |                     |                   |
| 0x03   | NIP     | Nip                      | b a -- a                                    |                      |                     |                   |
| 0x04   | SWP     | Swap                     | b a -- a b                                  |                      |                     |                   |
| 0x05   | ROT     | Rotate                   | a b c -- b c a                              |                      |                     |                   |
| 0x06   | DUP     | Duplicate                | a -- a a                                    |                      |                     |                   |
| 0x07   | OVR     | Over                     | a b -- a b a                                |                      |                     |                   |
| 0x08   | EQU     | Equal                    | b a -- (a == b)                             |                      |                     |                   |
| 0x09   | NEQ     | Not equal                | b a -- (a != b)                             |                      |                     |                   |
| 0x0A   | GTH     | Greater than             | b a -- (b > a)                              |                      |                     |                   |
| 0x0B   | LTH     | Less than                | b a -- (b < a)                              |                      |                     |                   |
| 0x0C   | JMP     | Jump                     | a --                                        |                      | PC+=a               |                   |
| 0x0D   | JCN     | Conditional jump         | b a --                                      |                      | PC+=(a if b else 1) |                   |
| 0x0E   | JSR     | Jump stash return (call) | a --                                        | -- pc                | PC+=a               |                   |
| 0x0F   | STH     | Stash                    | a --                                        | -- a                 |                     |                   |
| 0x10   | LDZ     | Load zero page           | a: u8 -- MEM[a]                             |                      |                     |                   |
| 0x11   | STZ     | Store zero page          | b a: u8 --                                  |                      |                     | MEM[a] = b        |
| 0x12   | LDR     | Load                     | a: i8 -- MEM[DATA + a]                      |                      |                     |                   |
| 0x13   | STR     | Store                    | b a: i8 --                                  |                      |                     | MEM[DATA + a] = b |
| 0x14   | LDA     | Load absolute            | a: i16 -- MEM[a]                            |                      |                     |                   |
| 0x15   | STA     | Store absolute           | b a: i16 --                                 |                      |                     | MEM[a] = b        |
| 0x16   | DEI     | Device input             | a: u8 -- DEV[a]                             |                      |                     |                   |
| 0x17   | DEO     | Device output            | b a: u8 --                                  |                      |                     | DEV[a] = b        |
| 0x18   | ADD     | Add                      | b a -- a + b                                |                      |                     |                   |
| 0x19   | SUB     | Subtract                 | b a -- a - b                                |                      |                     |                   |
| 0x1A   | MUL     | Multiply                 | b a -- a * b                                |                      |                     |                   |
| 0x1B   | DIV     | Divide                   | b a -- a / b                                |                      |                     |                   |
| 0x1C   | AND     | And                      | b a -- a && b                               |                      |                     |                   |
| 0x1D   | ORA     | Or                       | b a -- a\|b                                 |                      |                     |                   |
| 0x1E   | EOR     | Exclusive or (xor)       | b a -- a^b                                  |                      |                     |                   |
| 0x1F   | SFT     | Shift                    | b a -- b >> (a & 0x0f) << ((a & 0xf0) >> 4) |                      |                     |                   |

### Mode bits
Note that all these instructions are listed with `keep=0,return=0,short=0`.

The UXN documentation refers to `ADD` with `keep=1` as `ADDk`.
`ADD` with `short=1` is `ADD2`, and with `keep=1` would be `ADD2k`.
`POP` with `return=1` is `POPr`. 

Conventionally these suffixes are formatted `%/2?k?r?/` as required.

#### Short mode
In When the `short` bit is set, the opcode will pop two 8bi quantities from the stack where it would only consume one in `byte` mode.
Each `b a` pair so popped is considered to be the unsigned 16bi quantity `a + b<<8`
For instance `ADDs` would be `a b c d –- (a<<8 + b) + (c<<8+d)`.

**Exceptions:**
- The load/store operations move two 8bi values not one. `STR` becomes `c b a -- MEM[DATA + a] = ` Relative address computation is unaffected.
- The jump opcodes become absolute rather than computed relative jumps.

#### Keep mode
When the `keep` bit is set, no values are popped from the stack.
For instance `ADD2k` would be `a b c d -- a b c d e f`.

#### Return mode
"return mode" flips the stacks.

If `STH` pops from data and pushes to return, `STHr` pops from return and pushes to data.
Likewise if `ADD` pops from data and pushes to data, `ADDr` would pop from data and push to data.

`JMP2` would load `b a` from the data stack and branch absolutely, `JMP2r` would do the same from the control stack.
`DUP2r` would `a b -- a b a b` the return stack.

The bytecode sequence `LIT 0x01 STH JSRr BRK` would load `0x1` to the data stack, pop and stash it to the return stack, perform a relative jump by `+1` while pushing `PC` to the data stack and halt.