.\" Manpage reference for varvara.
.\" by Eiríkr Åsheim
.\" Contact d_m@plastic-idolatry.com to correct errors or typos.
.TH varvara 7 "14 Nov 2024" "1.0" "Varvara Reference Guide"
.SH NAME
varvara \- virtual machine for the Uxn CPU
.SH DESCRIPTION
Varvara is a virtual machine for the Uxn CPU. It provides devices that allow
ROMs to perform effects such as I/O, drawing to the screen, playing sounds,
and more.

.SH DEVICES
Each device consists of 16 ports, each of which are one byte of device memory. Data can be read from ports with \fBDEI\fP and written to them with \fBDEO\fP.

.SH TERMS

.SS Devices

.SS Ports

.SS Vectors

.SS Banks

.SH DEVICE LAYOUT
 0x00 \fBSystem\fP      0x80 \fBController\fP
 0x10 \fBConsole\fP     0x90 \fBMouse\fP
 0x20 \fBScreen\fP      0xa0 \fBFile 0\fP
 0x30 \fBAudio 0\fP     0xb0 \fBFile 1\fP
 0x40 \fBAudio 1\fP     0xc0 \fBDateTime\fP
 0x50 \fBAudio 2\fP     0xd0 \fB(reserved)\fP
 0x60 \fBAudio 3\fP     0xe0 \fB(reserved)\fP
 0x70 \fB(unused)\fP    0xf0 \fB(unused)\fP

.SH SYSTEM (0x00)

 0x00 \fBvector*\fP       0x08 \fBred*\fP
 0x01               0x09
 0x02 \fBexpansion*\fP    0x0a \fBgreen*\fP
 0x03               0x0b
 0x04 \fBwst\fP           0x0c \fBblue*\fP
 0x05 \fBrst\fP           0x0d
 0x06 \fBmetadata*\fP     0x0e \fBdebug\fP
 0x07               0x0f \fBstate\fP

.SS System/vector
Currently unused.

.SS System/expansion
Values written to the expansion port will be interpreted as an absolute address pointing to memory containing an expansion command.

 \fBCODE  NAME  DATA\fP
  00   \fBfill\fP  00 length* bank* addr* const
  01   \fBcpyl\fP  01 length* src-bank* src-addr* dst-bank* dst-addr*
  02   \fBcpyr\fP  02 length* src-bank* src-addr* dst-bank* dst-addr*

 \fBCODE  NAME  DESC\fP
  00   \fBfill\fP  fill a range of memory with a constant value.
  01   \fBcpyl\fP  copy a range of memory starting from the first byte.
  02   \fBcpyr\fP  copy a range of memory starting from the last byte.

Each bank contains 64k (65536 bytes) of data. Bank 0 is main memory. Banks are optional but emulators are encouraged to support at least 16 of them when possible.

.SH CONSOLE (0x10)

.SH SCREEN (0x20)

.SH AUDIO (0x30, 0x40, 0x50, 0x60)

.SH CONTROLLER (0x80)

.SH MOUSE (0x90)

.SH FILE (0xa0, 0xb0)

.SH DATETIME (0xc0)

.SH RESERVED (0xd0, 0xe0)

.SH UNUSED (0x70, 0xf0)

.SH SEE ALSO

 https://wiki.xxiivv.com/site/uxntal_opcodes.html   \fIUxntal Opcodes\fP
 https://wiki.xxiivv.com/site/uxntal_syntax.html    \fIUxntal Syntax\fP
 https://wiki.xxiivv.com/site/uxntal_modes.html     \fIUxntal Modes\fP
 https://wiki.xxiivv.com/site/uxntal_immediate.html \fIImmediate opcodes\fP
 https://wiki.xxiivv.com/site/varvara.html          \fIVarvara\fP