commit 365e406

Add uxn.doc and varvara.doc (the latter is incomplete).

  1@@ -0,0 +1,138 @@
  2+This document describes the Uxn virtual machine.
  3+
  4+
  5+=== Memory ===
  6+
  7+There is 64K of RAM, which stores both the program and data. (Devices use
  8+a separate memory; they are not stored in this RAM.)
  9+
 10+All numbers are big-endian unsigned, except where otherwise specified. All
 11+arithmetic will keep only the low 8-bits or low 16-bits of the result;
 12+there are no arithmetic overflow errors.
 13+
 14+
 15+=== Stacks ===
 16+
 17+There are two stacks, which are the data stack and return stack. Each
 18+stack can store at least 254 bytes of data.
 19+
 20+If a 16-bit value is in the stack, then the top will be the low 8-bits
 21+of that value and beneath that will be the high 8-bits of that value.
 22+
 23+
 24+=== Instruction encoding ===
 25+
 26+The low 5-bits are the opcode bits. The other bits are the mode bits:
 27+
 28+* bit5 = If set, then use 16-bit operands, if clear then 8-bit operands.
 29+
 30+* bit6 = If set, then operate on the return stack, but if clear then
 31+operate on the data stack. Some instructions use both stacks; in this
 32+case, this bit specifies which is the main stack to use, and the result
 33+is then stored in the other stack.
 34+
 35+* bit7 = If set, then the input operands are not removed from the stack.
 36+
 37+
 38+=== Instructions ===
 39+
 40+In the list below, entries with "8" means they are always 8-bits regardless
 41+of the instruction flags, and "16" means always 16-bits regardless of the
 42+instruction flags. If they are <> then it operates on the other stack. If
 43+marked ! then it is a branch address; if it is 16-bits then it is absolute
 44+but if 8-bits then it is a signed relative address.
 45+
 46+00 BRK ( -- )
 47+  Stops execution; all mode bits must be clear. Execution will continue
 48+  when a vector is called.
 49+01 INC ( old -- new )
 50+  Increment.
 51+02 POP ( x -- )
 52+  Stack operation.
 53+03 NIP ( x y -- y )
 54+  Stack operation.
 55+04 SWP ( x y -- y x )
 56+  Stack operation.
 57+05 ROT ( a b c -- b c a )
 58+  Stack operation.
 59+06 DUP ( a -- a a )
 60+  Stack operation.
 61+07 OVR ( a b -- a b a )
 62+  Stack operation.
 63+08 EQU ( a b -- bool8 )
 64+  Result is one if the inputs are equal or zero if unequal.
 65+09 NEQ ( a b -- bool8 )
 66+  Result is one if the inputs are unequal or zero if equal.
 67+0A GTH ( a b -- bool8 )
 68+  Result is one if (a) is greater than (b) or zero otherwise.
 69+0B LTH ( a b -- bool8 )
 70+  Result is one if (a) is less than (b) or zero otherwise.
 71+0C JMP ( addr! -- )
 72+  Unconditional jump.
 73+0D JCN ( cond8 addr! -- )
 74+  Jump if the condition is nonzero.
 75+0E JSR ( addr -- <old_addr> )
 76+  Unconditional jump, but the address of the next instruction if it
 77+  would not jump is saved in the other stack.
 78+0F STH ( a -- <a> )
 79+  Moves a value between stacks.
 80+10 LDZ ( addr8 -- value )
 81+  Read from memory.
 82+11 STZ ( value addr8 -- )
 83+  Write to memory.
 84+12 LDR ( rel_addr8 -- value )
 85+  Read from memory given a signed relative address.
 86+13 STR ( value rel_addr8 -- )
 87+  Write to memory given a signed relative address.
 88+14 LDA ( addr16 -- value )
 89+  Read from memory. (Same as LDZ but using a 16-bit address.)
 90+15 STA ( value addr16 -- )
 91+  Write to memory. (Same as LDZ but using a 16-bit address.)
 92+16 DEI ( port8 -- value )
 93+  Read a value from a device. If it is a 16-bit read, then it reads the
 94+  specified port and also the next port. (See varvara.doc for an
 95+  explanation of what each port number means.)
 96+17 DEO ( value port8 -- )
 97+  Write a value to a device. If it is a 16-bit write, then it writes the
 98+  high octet to the specified port and then writes the low octet of the
 99+  value to the next port.
100+18 ADD ( a b -- c )
101+  Addition (a+b).
102+19 SUB ( a b -- c )
103+  Subtraction (a-b).
104+1A MUL ( a b -- c )
105+  Multiplication.
106+1B DIV ( a b -- c )
107+  Division. (Division by zero is an error.)
108+1C AND ( a b -- c )
109+  Bitwise AND.
110+1D ORA ( a b -- c )
111+  Bitwise OR.
112+1E EOR ( a b -- c )
113+  Bitwise XOR.
114+1F SFT ( a shift8 -- c )
115+  Bitwise shift. First shifts right by the number of bits indicated by the
116+  low nybble of the shift amount byte, and the shifts left by the number of
117+  bits indicated by the high nybble of the shift amount byte.
118+80 LIT ( -- x )
119+  This instruction must have the high (keep) bit set. It will push a
120+  following one-byte or two-byte number to the stack, which are skipped.
121+
122+Instructions 0x20, 0x40, and 0x60 have undefined behaviour.
123+
124+
125+=== Execution ===
126+
127+The contents of the program file are loaded starting at address 0x0100, and
128+then it starts executing from address 0x0100.
129+
130+After a BRK instruction is executed, then it will wait for the next event,
131+and start executing at the vector for that event, if it is nonzero. (If the
132+vector is zero, then that event is ignored.) Events will never interrupt
133+the program; if it is already running then it will wait until BRK before
134+the next event is processed.
135+
136+
137+Stacks and memory are retained between events.
138+
139+

  1@@ -0,0 +1,183 @@
  2+This document describes the devices of Uxn virtual machine.
  3+
  4+The high nybble of the port number selects one of the following devices:
  5+  0 = System
  6+  1 = Standard I/O
  7+  2 = Screen
  8+  3 = Audio
  9+  4 = Audio
 10+  5 = Audio
 11+  6 = Audio
 12+  7 = MIDI
 13+  8 = Keyboard/joypad
 14+  9 = Mouse
 15+  A = File
 16+  B = File
 17+  C = Date/time
 18+  D = ---
 19+  E = Implementation dependent
 20+  F = Implementation dependent
 21+
 22+Note that there are four audio channels, and two files can be opened at
 23+the same time.
 24+
 25+In the below lists, asterisks indicate 16-bit ports.
 26+
 27+
 28+=== System ===
 29+
 30+00 = Vector *
 31+02 = Data stack
 32+03 = Return stack
 33+08 = Colours (red) *
 34+0A = Colours (green) *
 35+0C = Colours (blue) *
 36+0E = Debug
 37+0F = Quit
 38+
 39+Some implementations call the system vector if an error occurs.
 40+
 41+The data stack and return stack ports have a different meaning in different
 42+implementations, and probably should not be used by most programs.
 43+
 44+The colours control the colours of the display, where the high nybble of
 45+each controls the value for colour index 0, and the low nybble of each
 46+controls the value for colour index 3.
 47+
 48+Writing nonzero to the debug port will display some debug info.
 49+
 50+Writing nonzero to the quit port terminates the program.
 51+
 52+
 53+=== Standard I/O ===
 54+
 55+10 = Vector *
 56+12 = Input
 57+18 = Output
 58+19 = Error
 59+
 60+Each byte of input is received from stdin will result in setting the input
 61+port to the byte read and calls the vector. Immediately after the first
 62+BRK (and before any other events), any command-line arguments are also
 63+sent in this way as though each one is a line of input from stdin
 64+terminated by a line feed.
 65+
 66+Writing to the output and error ports write a byte to stdout or stderr.
 67+
 68+
 69+=== Screen ===
 70+
 71+20 = Vector *
 72+22 = Width *
 73+24 = Height *
 74+26 = Auto
 75+28 = X *
 76+2A = Y *
 77+2C = Sprite address *
 78+2E = Pixel command
 79+2F = Sprite command
 80+
 81+The screen has two layers (background and foreground), and can display four
 82+colours. If the foreground colour is zero then the background is displayed.
 83+
 84+The vector is called during each video frame (60 frames per second).
 85+
 86+The auto port works as follows:
 87+  bit7-bit4 = One less than number of sprites to draw
 88+  bit3 = Unused (should be clear)
 89+  bit2 = Address
 90+  bit1 = Y
 91+  bit0 = X
 92+
 93+Writing to the pixel command port will change the pixel at the specified
 94+coordinates. The low 2-bits specify what colour to use, and bit6 specifies
 95+the layer (set for foreground, clear for background). It will automatically
 96+increment X and/or Y if the corresponding bits of the auto port are set.
 97+
 98+Writing to the sprite command port will draw one or more sprites. The bits
 99+are as follows:
100+  bit7 = Set for 2bpp sprites, clear for 1bpp
101+  bit6 = Set for foreground layer, clear for background layer
102+  bit5 = Vertical flip
103+  bit4 = Horizontal flip
104+  bit3-bit0 = Colour
105+
106+
107+=== Audio ===
108+
109+(TODO)
110+
111+
112+=== MIDI ===
113+
114+(TODO)
115+
116+
117+=== Keyboard/joypad ===
118+
119+80 = Vector *
120+82 = Joypad
121+83 = Key
122+
123+The vector is called if a key is pushed, or if any button on the joypad is
124+pushed or released.
125+
126+The joypad byte has bits as follows:
127+  bit7 = Right
128+  bit6 = Left
129+  bit5 = Down
130+  bit4 = Up
131+  bit3 = Start (or home)
132+  bit2 = Select (or left shift)
133+  bit1 = B (or left alt)
134+  bit0 = A (or left control)
135+
136+The key is the ASCII code of the key pushed.
137+
138+
139+=== Mouse ===
140+
141+90 = Vector *
142+92 = X *
143+94 = Y *
144+96 = Buttons
145+9A = Scroll X *
146+9C = Scroll Y *
147+
148+The vector is called when the mouse is moved or if any mouse buttons are
149+pushed or released.
150+
151+
152+=== Files ===
153+
154+A2 = Number of bytes transferred *
155+A4 = Stat (address to store data) *
156+A6 = Delete
157+A7 = Append
158+A8 = Address of file name *
159+AA = Maximum number of bytes to transfer *
160+AC = Read (address to store data) *
161+AE = Write (address to take data from) *
162+
163+If the address of a null-terminated file name is written to that port,
164+then the device is reset and it remembers the file name (so the memory
165+used to store it can be reused afterward).
166+
167+All other operations need the maximum length in that port, and then
168+write the address of the data to the stat/read/write port.
169+
170+(TODO)
171+
172+
173+=== Date/time ===
174+
175+C0 = Year *
176+C2 = Month (zero-based)
177+C3 = Day of month (one-based)
178+C4 = Hours
179+C5 = Minutes
180+C6 = Seconds
181+C7 = Day of the week (0=Sunday)
182+C8 = Day of the year *
183+CA = Daylight saving time
184+