XXIIVV
The Sound Of Plumpkins
The Sound Of Plumpkins

Varvara is a clean-slate computing stack based on the Uxn CPU.

This personal computer system was designed with a focus on portability, built on top of the Uxn virtual machine. It is an ideal platform for running small audio/visual applications. To see a list of compatible software, see roms, and the community projects.

While this project aspires to be a platform that lasts, it is in its infancy, the design may still change and break compatibility.

Devices are external systems connected to the Uxn CPU, such as the screen, the mouse and the keyboard. Each device has 16 bytes, also called ports, of I/O memory. Vectors are ports holding the address to an entry point into a program that triggers when the mouse is moved, or a key is pressed.

Varvara
00system80controller
10console90mouse
20screena0file
30audiob0
40c0datetime
50d0---
60e0Reserved
70midif0

The two reserved devices can be used for implementation specific systems that do not need to be part of the specs, or other Uxn/Varvara instances.

System Device

The System device is used to control the execution of a varvara program.

system 00vector*08red*
0109
02wst0agreen*
03rst0b
04--0cblue*
05--0d
06--0edebug
07--0fstate

This device is holding 3 shorts to be used for application customization. For a device that does not use a screen, these bytes may be used for speech controls, or other system globals, for simplicity we call them the Red*, Green* and Blue* shorts.

Sending a non-null byte to the 0x0e port will print the system's status, sending a non-null byte to the 0x0f port will terminate the application.

Console Device

console 10vector*18write
1119error
12read1a--
13--1b--
14--1c--
15--1d--
16--1e--
17--1f--

The console device is the standard I/O device, it allows for communication between programs on the host computer. The console vector triggers when a stdio event occurs.

#41 .Console/write DEO ( to send the letter "A" )

To send data from one Uxn to another, when using a Unix host, use the following pattern:

uxnemu orca.rom | uxnemu piano.rom

For example, a program sending the line of text "hello", will trigger the console's vector 6 times; one for each character and a line ending character.

Screen Device

screen 20vector*28x*
2129
22width*2ay*
232b
24height*2caddr*
252d
26auto2epixel
27--2fsprite

The screen device is made of two layers, each displaying 2-bits graphics in up to 4 colors. Drawing to the screen is done by writing values to the screen's x*, y* and pixel/sprite ports of the screen device. The screen vector triggers 60 times per seconds.

M L Y X            D C B A          
| | | +---- Flipx  | | | +---- Blend 
| | +------ Flipy  | | +------ Blend 
| +-------- Layer  | +-------- Blend
+---------- Mode   +---------- Blend
Effects(MLYX)Blending(DBCA)
0bg1bit 4fg1bit 8bg2bit cfg2bit 0 4 8 c
1flipx 5flipx 9flipx dflipx 1 5 9d
2flipy 6flipy aflipy eflipy 2 6 a e
3flipxy 7flipxy bflipxy fflipxy 3 7 bf

To draw a single teal pixel on the foreground, at the position 20,30:

@paint-pixel
	#0020 .Screen/x DEO2 ( set x* position )
	#0030 .Screen/y DEO2 ( set y* position )
	#42 .Screen/pixel DEO2 ( draw 4-fg 2-color2 )
JMP2r

The screen can also draw 8x8 sprites by writing an addr* which points to the sprite data in memory. The sprite byte defines the layer to draw on, the type of data to draw, and the colors to use.

@paint-sprite
	#0020 .Screen/x DEO2 ( set x* position )
	#0030 .Screen/y DEO2 ( set y* position )
	;sprite .Screen/addr DEO2 ( set addr* position )
	#03 .Screen/sprite DEO ( draw 0-bg 3-color3 )
JMP2r

@sprite
	0f38 675f dfbf bfbf

Sprites are 8x8 tiles, stored in memory as sequences of 8 bytes for a 1-bit sprite, and 16 bytes for a 2-bits sprite. For example, the color byte #01 will paint a 1bpp sprite on the background with the first system color, and #c2 will paint a 2-bits sprite on the foreground with the second system color.

The screen's auto byte automates the position and sprite address whenever a drawing command is sent, so the program does not need to manually move to the next sprite, or the next tile. A pixel drawing will increment the positions by 1, and a sprite drawing, by 8. A 1bpp sprite drawing will increment the address by 8, and a 2bpp drawing, by 16.

L L L L             * A Y X
| | | +---- Length  | | | +---- Auto X
| | +------ Length  | | +------ Auto Y
| +-------- Length  | +-------- Auto Addr
+---------- Length  +---------- Unused

The high nibble of the auto byte is the length of sprites to draw at once. This allows to draw a 2x3 sprite without needing complex logic:

@paint-sprite
	#0020 .Screen/x DEO2 ( set x* position )
	#0030 .Screen/y DEO2 ( set y* position )
	#16 .Screen/auto DEO ( set 2w y addr auto )
	;23x-icns .Screen/addr DEO2 ( set addr* )
	#01 .Screen/sprite DEOk DEOk DEO ( draw 3 rows )
JMP2r

@23x-icns
	0010 2847 2810 0001 0000 00e0 2040 8000
	0204 080f 0000 0001 0000 00e0 2040 8000
	0204 080f 0000 0000 0010 28c4 2810 0000

Audio Device

audio 30vector*38adsr*
3139
32position*3alength*
333b
34output3caddr*
35--3d
36--3evolume
37--3fpitch

When pitch is written to any of the audio devices, it starts playing an audio sample from Uxn's memory, pointed to by addr* and length*. It loops the sample (unless told not to) until it reaches the end of the ADSR envelope defined by adsr*. The audio vector triggers when a note ends.

Several fields contain more than one component:

ADSR*PitchVolume
SubfieldAttackDecaySustainReleaseLoopNoteLeftRight
Size (bits)44441744

Each of the ADSR components is measured in 15ths of a second, so writing #ffff to adsr* will play a note that lasts for exactly four seconds, with each section of the envelope lasting one second. If adsr* is #0000 then no envelope will be applied: this is most useful for longer samples that are set to play once by setting the most significant bit of pitch to 1.

The envelope varies the amplitude as follows: starting at 0%, rising to 100% over the Attack section, falling to 50% over the Decay section, remaining at 50% throughout the Sustain section and finally falling to 0% over the Release section. The envelope is linearly interpolated throughout each section.

The two volume components set how loudly the next sample will play. #ff sets maximum volume for both speakers.

When pitch is written, any sample that is currently playing will be replaced with the sample defined by all the values set in the device. While the sample is playing, the output byte can be read to find the loudness of the envelope at that moment.

Audio Sample Format

All samples used by the audio devices are mono and unsigned 8-bit (also known as u8), so the space taken up by samples is minimized. The sample rate of the samples depends on length*:

length*Sample typeSample rate
> 256Middle-C pitched sample44,100 Hz
2–256Single wavelengthVariable

Long samples are assumed to be already pitched to Middle C and will loop (unless No Loop is 1) until the end of the envelope. To play the sample at the same rate as it was recorded, write the Middle C MIDI note number, #3c, to pitch. To play at double or half speed, for example, write an octave higher or lower to pitch.

The minimum sample size that can be pitched at 44.1 kHz to Middle C with reasonable accuracy is 337 bytes long, which represents two cycles of the 261 Hz wave. The single wavelength mode in Uxn allows much smaller samples to be used, even down to only two bytes for a square wave. In this mode the length of the entire sample is taken to be one cycle of the Middle C note, so the pitch is not heard to vary even if length* were to change between sample plays.

Midi Device

This device is currently a work in progress, more details shortly.

midi 30vector*38send*
3139
32bpm3anum
33--3bden
34--3cswing
35read-chan3dsend-chan
36read-pitch3esend-pitch
37read-velocity3fsend-velocity

Controller Device

controller 80vector*88--
8189--
82button8a--
83key8b--
84func8c--
85--8d--
86--8e--
87--8f--

The button byte works similarly to a NES controller, where there the state of each one of the 8 buttons is stored as a bit in a single byte. The keys byte contains the ascii character that is currently pressed. The controller vector triggers when a button, is pressed or released, and when a key is pressed.

0x01A Ctrl0x10Up
0x02B Alt0x20Down
0x04Select Shift0x40Left
0x08Start Home0x80Right

Mouse Device

mouse 90vector*98--
9199--
92x*9ascrollx*
939b
94y*9cscrolly*
959d
96state9e--
97--9f--

The mouse device's state port holds a byte in which each bit is a button state. The byte value of holding down the mouse1 button is 01, and holding down mouse1+mouse3 button is 05. The scroll values are signed shorts, normally ffff and 0001, for -1 and +1. The mouse vector triggers when the mouse is moved and when a button is pressed or released.

File Device

file a0vector*a8addr(name)*
a1a9
a2success*aalength*
a3ab
a4addr(stat)*acaddr(read)*
a5ad
a6deleteaeaddr(write)*
a7appendaf

The file device supports reading and writing files, listing directories, obtaining file information and deleting files. The file vector is unused.

The general approach is to write name* with the address of the filename in memory, length* with the length of the memory region to use in the data exchange, and finally one of the addr* shorts with the address of that memory region. Once the operation has completed, the success* short can be read to find the number of bytes successfully exchanged.

When name* resolves to a file, writing the address to addr(read)* will read the file's data into the memory region. success* will be less than length* if the file is shorter than length*, and will be zero if the file does not exist or the filename is invalid. If the file is longer than length*, subsequent writes to addr(read)* will read the next chunk of data into the memory region, so it is possible to read the contents of very large files one chunk at a time.

When name* resolves to a directory, writing the address to addr(read)* will read the directory as if it were a text file listing each of the directory's contents:

001a small text file.txt
---- subdirectory
???? huge file.mp4

The listing has each file or directory on its own line, prefixed with the file size in four hex characters and a space. The ending newline is always present. If the file is too big to fit in four hex characters (> 64 kB) then ???? will be used instead; for directories, ---- takes the place of the file size. As for reading file data, if the listing length exceeds length* then subsequent writes to addr(read)* will read more entries. Unlike file data, directory entries will be returned as atomic units that won't be broken across chunks, so success* will usually be lower than length* even when more data is available. When success* reads zero, the listing is complete.

The directory listing for a single file or directory can be obtained when addr(stat)* is written, and will write the same format as above, including the newline, into the memory buffer. If success* reads zero, the file or directory doesn't exist or the region is too small to fit the line.

Writing files is performed by writing to addr(write)*. If append is set to 0x01, then the data in the memory region will be written after the end of the file, if it is 0x00 (the default) it will replace the contents of the file. If the file doesn't previously exist then it will be created and append makes no difference. success* will be set to length* if the write was successful, otherwise it will read as zero. As with reading files and directories, subsequent writes to addr(write)* will write more chunks of data to the file.

In all cases, writing to name* closes the file/directory and new calls to the addr* shorts will start from the beginning (or writing after the end when append is 0x01).

Finally, to delete a file, write any value to the delete byte.

Datetime Device

datetime c0year*c8doty
c1c9
c2monthcaisdst
c3daycb--
c4hourcc--
c5minutecd--
c6secondce--
c7dotwcf--

Incoming: donsol roms nebu noodle adelie shim icn format chr format gly format ufx format tga format paradise chip8 uxn uxntal playdate devlog 2021 devine lu linvega computer ayatori