uxn/doc/varvara.md

# Varvara

[Varvara](https://wiki.xxiivv.com/site/varvara.html) is a personal computer, using the [uxn](./uxn.md) instruction set, programmed in [tal](./tal.md).

UXN presents 16 I/O ports via the `DEI` and `DEO` instructions.
Each port consists of 16 words of memory, and has its own I/O memory mapping behavior.
Note that while other memory read and write instructions can interface with port memory, only `DEI` and `DEO` will trigger port effects.

The Varvara computer presents the following canonical port mappings -

- `0x0000`, System device
- `0x0010`, Console device (text output)
- `0x0020`, Screen device (bitmap output)
- `0x0030`, Audio device (`audio0`)
- `0x0040`, Audio device (`audio1`)
- `0x0050`, Audio device (`audio2`)
- `0x0060`, Audio device (`audio3`)
- `0x0070`, Unused
- `0x0080`, D-pad controller
- `0x0090`, Mouse
- `0x00A0`, File (`file0`)
- `0x00B0`, File (`file1`)
- `0x00C0`, Datetime
- `0x00D0`, Unused
- `0x00E0`, Unused
- `0x00F0`, ROM metadata on some implementations

Note that while ports have memory addresses, the 0 page is normal memory.
The `DEI` and `DEO` port I/O instructions have memory effects, but loads/stores to port mapped memory does not have I/O effects.

Varvara executes ROMS starting at `0x0100` until the `BRK` instruction occurs.
`BRK` does not halt the machine.
Instead it signals that the present 'thread' of execution has completed, and returns control so that an interrupt handler can occur.
Machine termination can be accomplished with `%BYE { #01 #000F DEO BRK }` which writes `#01` to the `System/state` port, marking the machine as halted and breaks.

Varvara provides 'interrupt' based I/O.
The 'vector' of a given device is a program point.
That point will be invoked with no stack arguments when an event on the device occurs.
Threads of execution precede until they yield using the `BRK` instruction.

Typically the 'main' program starting at `0x0100` will initialize handler vectors and then `BRK` to enable I/O.

**WARNING**: `BRK` does not alter or reset either stack.
It is possible to perform (deliberate or accidental) communication between vectors due to this.

## Devices

### The system

[themes](https://wiki.xxiivv.com/site/theme.html)


### The console

### The screen

The screen device's vector is a clock which ticks at 60hz.

### Audio

### The controller
The controller device similarly fires on input changes.

### The mouse
The mouse device's vector likewise fires when a mouse event such as movement or a button press occurs.

### Files

### Datetime

### Metadata

[metadata](https://wiki.xxiivv.com/site/metadata.html)