commit 9df7c3e

cleanup

 1@@ -1,23 +0,0 @@
 2-environment:
 3-  BUILD_SUBMITTER: git.sr.ht
 4-  SITE: rabbits.srht.site/uxn2
 5-image: debian/stable
 6-packages:
 7-- curl
 8-- libsdl2-dev
 9-shell: false
10-oauth: pages.sr.ht/PAGES:RW
11-sources:
12-- https://git.sr.ht/~rabbits/uxn2
13-tasks:
14-- build: |
15-    mkdir bin/
16-    cc -I/usr/include/SDL2 -DNDEBUG -O2 -g0 -s -lSDL2 uxn2/src/uxn2.c -o bin/uxn2 $(sdl2-config --cflags --libs)
17-- upload: |
18-    tar -czf out.tar.gz bin/
19-    acurl() {
20-        set +x
21-        curl -H "Authorization: Bearer ${OAUTH2_TOKEN}" "${@}"
22-        set -x
23-    }
24-    acurl -fsS "https://pages.sr.ht/publish/${SITE}" -Fcontent=@out.tar.gz

 1@@ -1,22 +0,0 @@
 2-AlignAfterOpenBracket: DontAlign
 3-AlignEscapedNewlines: DontAlign
 4-AlignOperands: DontAlign
 5-AllowShortBlocksOnASingleLine: Always
 6-AllowShortCaseLabelsOnASingleLine: true
 7-AllowShortEnumsOnASingleLine: true
 8-AllowShortIfStatementsOnASingleLine: true
 9-AllowShortLoopsOnASingleLine: true
10-AlwaysBreakAfterDefinitionReturnType: TopLevel
11-BreakBeforeTernaryOperators: false
12-BinPackArguments: false
13-BinPackParameters: false
14-BreakBeforeBraces: WebKit
15-IndentCaseLabels: false
16-TabWidth: 4
17-IndentWidth: 4
18-ContinuationIndentWidth: 4
19-UseTab: ForContinuationAndIndentation
20-ColumnLimit: 0
21-ReflowComments: false
22-SortIncludes: false
23-SpaceBeforeParens: false

1@@ -1 +0,0 @@
2-prg/not88aonly.uhs

 1@@ -1,19 +0,0 @@
 2-on:
 3-  issues:
 4-    types:
 5-      - opened
 6-  pull_request:
 7-    types:
 8-      - opened
 9-permissions:
10-  contents: read
11-  issues: write
12-  pull-requests: write
13-jobs:
14-  default:
15-    runs-on: ubuntu-latest
16-    steps:
17-      - run: gh issue edit ${{ github.event.issue.number }} --add-assignee ${{ github.repository_owner }}
18-        env:
19-          GH_TOKEN: ${{ github.token }}
20-          GH_REPO: ${{ github.repository }}

 1@@ -8,9 +8,10 @@
 2 *.bak
 3 /*-test
 4 /screenshot-*.bmp
 5-
 6+*.tns
 7+*.o
 8+*.elf
 9 *snarf
10 *theme
11-
12 bios.rom
13 bios.rom.sym

  1@@ -1,112 +0,0 @@
  2-# Uxn2
  3-
  4-A graphical emulator for the [Varvara Computer](https://wiki.xxiivv.com/site/varvara.html), written in C99(SDL2). 
  5-
  6-## Building 
  7-
  8-You must have [SDL2](https://www.libsdl.org/) installed.
  9-
 10-```sh
 11-cc -I/usr/include/SDL2 -DNDEBUG -O2 -g0 -s -lSDL2 src/uxn2.c -o bin/uxn2
 12-```
 13-
 14-For your convenience a [Makefile](https://en.wikipedia.org/wiki/Make_(software)#Makefile) is provided. 
 15-
 16-```sh
 17-make run
 18-```
 19-
 20-You can run `make install` to build and install the files. By default, files are installed into `~/.local` but this can be overridden using `PREFIX`:
 21-
 22-```sh
 23-# installs files into /opt/uxn/bin
 24-$ make PREFIX=/opt/uxn install
 25-```
 26-
 27-### Plan 9
 28-
 29-If you're on plan 9.
 30-
 31-```sh
 32-cd src/
 33-cc -p -I/sys/include/npe -I /sys/include/npe/SDL2/ uxn2.c
 34-6l -o uxn2 uxn2.6
 35-```
 36-
 37-If do not wish to build it yourself, you can [download linux binaries](https://rabbits.srht.site/uxn2/bin/uxn2).
 38-
 39-[![builds.sr.ht status](https://builds.sr.ht/~rabbits/uxn2.svg)](https://builds.sr.ht/~rabbits/uxn2?)
 40-
 41-## Usage
 42-
 43-The first parameter is the rom file, the subsequent arguments will be accessible to the rom, via the [Console vector](https://wiki.xxiivv.com/site/varvara.html#console).
 44-
 45-```sh
 46-bin/uxn2 bin/example.rom arg1 arg2
 47-```
 48-
 49-- `-f` to start in fullscreen
 50-- `-2` to start in zoomed x2
 51-
 52-## Assembler
 53-
 54-This repository comes with a copy of the compiled [Drifblim](https://git.sr.ht/~rabbits/drifblim) assembler. 
 55-
 56-```sh
 57-cat etc/utils/drifblim.rom.txt | bin/uxn2 etc/utils/xh.rom > bin/drifblim.rom
 58-bin/uxn2 bin/drifblim.rom etc/tests/opctest.tal bin/opctest.rom
 59-```
 60-
 61-## Devices
 62-
 63-The file device is _not_ sandboxed, it is able read or write outside of the working directory.
 64-
 65-- `00` system
 66-- `10` console
 67-- `20` screen
 68-- `40` audio
 69-- `50` audio
 70-- `60` audio
 71-- `70` audio
 72-- `80` controller
 73-- `90` mouse
 74-- `a0` file(a)
 75-- `b0` file(b)
 76-- `c0` datetime
 77-
 78-## Emulator Controls
 79-
 80-- `F1` toggle zoom
 81-- `F2` toggle debugger
 82-- `F4` reboot
 83-- `F5` reboot(soft)
 84-
 85-### Buttons
 86-
 87-- `LCTRL` A
 88-- `LALT` B
 89-- `LSHIFT` SEL 
 90-- `HOME` START
 91-
 92-## SDL2
 93-
 94-To build this emulator, you must install [SDL2](https://wiki.libsdl.org/) for your distro. If you are using a package manager:
 95-
 96-```sh
 97-sudo pacman -Sy sdl2             # Arch
 98-sudo apt install libsdl2-dev     # Ubuntu
 99-sudo xbps-install SDL2-devel     # Void Linux
100-brew install sdl2                # OS X
101-```
102-
103-## Need a hand?
104-
105-The following resources are a good place to start:
106-
107-* [XXIIVV — uxntal](https://wiki.xxiivv.com/site/uxntal.html)
108-* [XXIIVV — uxntal reference](https://wiki.xxiivv.com/site/uxntal_reference.html)
109-* [compudanzas — uxn tutorial](https://compudanzas.net/uxn_tutorial.html)
110-
111-## Contributing
112-
113-Submit patches using [`git send-email`](https://git-send-email.io/) to the [~rabbits/public-inbox mailing list](https://lists.sr.ht/~rabbits/public-inbox).

  1@@ -1,370 +0,0 @@
  2-This document describes the Uxn assembler, including the nonstandard
  3-extensions of the implementation included in this repository.
  4-
  5-Specify two or three command-line arguments:
  6-
  7-* Input file name (you can specify /dev/stdin to read from stdin).
  8-
  9-* Output file name (you can specify /dev/stdout to write to stdout, or you
 10-can specify /dev/null to discard the output).
 11-
 12-* Name output file name (you can specify /dev/stdout to write to stdout).
 13-This is optional, and if specified, then it will write a list of labels
 14-(including unused labels too) and their addresses to this file. (This is a
 15-nonstandard feature.)
 16-
 17-Switches are also allowed if preceding the other arguments:
 18-
 19- -a will set the starting address to 0x0100.
 20-
 21- -i followed by a token will parse that token before parsing the input
 22- file. This must be a single token, and not the beginning of a macro or a
 23- comment. This switch may occur multiple times.
 24-
 25-
 26-=== Tokens ===
 27-
 28-A token consists of a sequence of one or more non-whitespace characters
 29-(you can have whitespace characters to separate them). The maximum length
 30-of each token is sixty-three characters.
 31-
 32-All numbers must be lowercase hexadecimal, and normally must be either two
 33-or four hex digits.
 34-
 35-The following standard tokens are available:
 36-
 37- ( which begins a block comment; all further tokens up to ) are ignored.
 38- Comments can be nested.
 39-
 40- [ or ] has no meaning. Anything inside this block is still assembled as
 41- though the [ and ] commands are not present.
 42-
 43- ~ and a file name will include that file as a source file.
 44-
 45- % and a macro name will define a macro; you will need tokens { and }
 46- around the definition of the macro.
 47-
 48- The name of a previously defined macro without % in front will call that
 49- macro, as though its definition is substituted in its place.
 50-
 51- | and a number or label name will set the current address to that number
 52- (or to the address of that label). Any address is possible, but you cannot
 53- assemble anything in the zero page nor can anything be assembled out of
 54- order, although you can skip any space.
 55-
 56- $ and a number or label name will advance the address by that number (or
 57- by the address of that label). (The padding will  be all zeros if not
 58- filled in.)
 59-
 60- @ and a name will make a label with that name. If the label name starts
 61- with a uppercase letter, then warnings about that label being unused are
 62- suppressed. (Otherwise, a warning is emitted if the label is never used.)
 63-
 64- & and a name will make a label whose name is the same as the most recent
 65- @ command and then / and then the name specified by the & command.
 66-
 67- # and a number will make a LIT or LIT2 opcode with the specified number
 68- (the number of hex digits determines which opcode).
 69-
 70- A number without # is similar but the opcode is omitted, so raw data is
 71- emitted instead.
 72-
 73- . and a name will make a LIT opcode whose value is the low 8-bits of the
 74- address of the specified name.
 75-
 76- , and a name will make a LIT opcode whose value is a signed 8-bit value
 77- which is a relative offset of the address of the specified name; this
 78- should be used immediately preceding a JMP, JSR, or JCN instruction.
 79-
 80- ; and a name will make a LIT2 opcode whose value is the address of the
 81- specified name.
 82-
 83- : and a name will write the 16-bit address of the specified name directly,
 84- without any opcode. (It is like ; but excluding the LIT2 instruction.)
 85-
 86- = and a name is the same as : and a name.
 87-
 88- - and a name is like . but without the LIT opcode.
 89-
 90- _ and a name is like , but without the LIT opcode.
 91-
 92- ? and a name will make a JCI instruction jumping to that label.
 93-
 94- ! and a name will make a JMI instruction jumping to that label.
 95-
 96- / and a name will treat it like & but instead of making the label, it will
 97- be a JSI to that label (since & cannot be used with JSI due to being used
 98- for a different purpose, / is available for this purpose instead).
 99-
100- " and any characters (other than whitespaces) will emit that sequence of
101- characters without any opcodes or delimiters. (If you need spaces, then
102- you must use separate tokens such as 20 for spaces.)
103-
104- { and } can be used around a lambda block (they can also be used for
105- macros as described above). This is the same as the nonstandard [& ]@
106- block (described below), but internally uses a separate stack. You can
107- also use other runes at the beginning e.g. ?{ } is like the [? ]@ block.
108-
109- An instruction opcode consists of three uppercase letters, optionally
110- followed by any combination of instruction flags which can be "2" for
111- 16-bit operands, "r" to work with the other stack, and/or "k" to keep
112- the input operands in the stack. (You cannot code the JCI, JMI, and JSI
113- instructions in this way, although BRK can be coded in this way.)
114-
115- A name by itself to make a JSI instruction (if it does not match any
116- of the other tokens mentioned above).
117-
118-The following nonstandard tokens are available:
119-
120- \\ begins a line comment, which ends at the next line break.
121-
122- \~ and a file name will include the contents of the binary file.
123-
124- \. or \, is like . or , but excluding the LIT instruction. (These are
125- like - and _ but are nonstandard; they were added before the - and _
126- signs were made standard.)
127-
128- \ and a number pushes the number to the special stack (which is a stack
129- which exists only at compile-time).
130-
131- \: and a name will push the address of the name to the special stack.
132- The label must come before this command; forward references cannot be
133- used with this command, and & also cannot be used.
134-
135- \@ and a name will pop an address from the special stack and define a
136- label whose address is the address which has been popped in this way.
137-
138- \_ and further text is a special calculation; see the below section
139- about special calculations. These are executed immediately at compile
140- time, before the compiled program is written to the output file.
141-
142- \` is like \_ but the calculation is deferred until when references
143- are being resolved. By this time, any references that come before this
144- command will already be resolved, and the memory containing them can
145- be read and overwritten by the calculation if desired.
146-
147- \- or \= followed by eight more characters and optionally ; will make
148- a graphical tile; you should have eight such commands per tile, and
149- a semicolon at the end of the last one. Use \- for 1bpp tiles and \=
150- for 2bpp tiles. The colour codes are . or 0 for the background colour,
151- and numbers 1 2 3 for the other colours.
152-
153- \r will cause it to automatically change opcodes without "r" to the ones
154- with "r" and vice-versa until the next \r token. This also affects the
155- # and , and . and ; tokens, and causes the uses of JSI and JCI to be
156- errors (but JMI and BRK are OK and are not affected by \r).
157-
158- [@ makes a anonymous label; the matching ] command will reference the
159- same anonymous label as this one. (Nesting is allowed.)
160-
161- ]@ will make a anonymous label which the matching [ before it will
162- reference it.
163-
164- [, [. [; [: [? [! will act like a , . ; : ? ! referencing the anonymous
165- label defined by the matching ]@ command.
166-
167- ], ]. ]; ]: ]? ]! will act like a , . ; : ? ! referencing the anonymous
168- label defined by the matching [@ command.
169-
170- [& and ]& are like [! and ]! but the opcode is JSI instead of JMI.
171-
172- ]\ acts like \: for the matching [@ command.
173-
174- ][ is like [! corresponding to a later ] and then ]@ corresponding to a
175- earlier [ command (it can be used like a else block).
176-
177-For the . , : ; commands, the name can optionally start with & to mean
178-that it is interpreted the same as for a & command.
179-
180-Another nonstandard feature is that if you define a macro whose name
181-starts with a character which has a special meaning, then that special
182-meaning is ignored in the rest of the file.
183-
184-
185-=== Special calculations ===
186-
187-Each instruction is a single character.
188-
189-Numbers 0 to 9 and a to f push that number to the special stack.
190-
191-'  ( y z -- yz )  Calculates z+(y<<4).
192-
193-"  ( w x y z -- wxyz )  Calculates z+(y<<4)+(x<<8)+(w<<12).
194-
195-_  ( -- )  Set loop point.
196-
197-!  ( x -- )  Set current address.
198-
199-@  ( -- x )  Get current address.
200-
201-#  ( x -- )  Set current length. (This length includes the zero page,
202-even though the zero page is not written to the output file.)
203-
204-$  ( -- x )  Get current length.
205-
206-+  ( x y -- z )  Addition x+y.
207-
208--  ( x y -- z )  Subtraction x-y.
209-
210-*  ( x y -- z )  Multiplication x*y.
211-
212-/  ( x y -- z )  Division x/y.
213-
214-%  ( x y -- z )  Modulo x&y.
215-
216-&  ( x y -- z )  Bitwise AND.
217-
218-|  ( x y -- z )  Bitwise OR.
219-
220-^  ( x y -- z )  Bitwise XOR.
221-
222-<  ( x y -- z )  Left shift x by y bits.
223-
224->  ( x y -- z )  Right shift x by y bits.
225-
226-:  ( x -- x x )  Duplicate.
227-
228-,  ( x y -- y x )  Swap.
229-
230-.  ( x -- )  Discard.
231-
232-E  ( code -- )  Emit an error and stop compiling.
233-
234-g  ( address -- value )  Read 8-bits from memory.
235-
236-G  ( address -- value )  Read 16-bits from memory.
237-
238-k  ( count -- count? )  Similar to o (below) but ends the loop if the new
239-count is zero instead of the old count.
240-
241-L  ( condition -- )  Go back to beginning of loop if condition is nonzero.
242-
243-o  ( count -- count? )  If count is nonzero, decrement and go back to the
244-beginning; if it is already zero then just discards it and continues the
245-execution from here instead.
246-
247-p  ( value address -- )  Write 8-bits to memory. You can write anywhere
248-including the zero page and can also overwrite memory that has already
249-been written. Anything written to the zero page can be read back by other
250-special calculations but will not be written to the output file; anything
251-written outside of the zero page is written to the output file too.
252-
253-P  ( value address -- )  Write 16-bits to memory.
254-
255-w  ( value -- )  Write 8-bits at the current address and advance. You
256-cannot write in the zero page or overwrite what is already written.
257-
258-W  ( value -- )  Write 16-bits at the current address and advance. You
259-cannot write in the zero page or overwrite what is already written.
260-
261-x  ( length -- )  Add padding into expanded memory.
262-
263-()  ( condition -- )  Put other commands in the () block; it will be
264-executed only if the condition is zero, and skipped if nonzero. Conditional
265-blocks of the same kind cannot be nested.
266-
267-[]  ( condition -- )  Put other commands in the [] block; it will be
268-executed only if the condition is nonzero, and skipped if zero. Conditional
269-blocks of the same kind cannot be nested.
270-
271-
272-=== Name output format ===
273-
274-The name output format has each record on a line by itself, and each
275-record will be like:   |xxxx @yyyy
276-
277-xxxx is four lowercase hex digits being the address of that label.
278-
279-yyyy is the name of that label.
280-
281-
282-=== Expanded memory ===
283-
284-A nonstandard feature allows writing large files that have preset data in
285-expanded memory. Any expanded memory data comes after the conventional
286-memory data. It is possible that some data will fit in conventional memory
287-in which case such data will be entered into conventional memory, but you
288-can override this using alignment and padding commands.
289-
290-The following nonstandard tokens are used for expanded memory:
291-
292- \* followed by a name will make a label that refers to the address within
293- expanded memory. The plain name refers to the low 16-bits of the address
294- and the name followed by ^ refers to the high 16-bits (the page number).
295- This also sets the initial scope name of any sub-assemblies that follow.
296-
297- \^ followed by a file name is similar to \~ but writes the data into
298- expanded memory.
299-
300- \B \E \F followed by a digit 0 to 9 or a letter a to u (representing a
301- number ten to thirty) will begin a new expanded memory block which is
302- aligned to begin or end at an address divisible by two to the power of
303- that number, or to fit into an aligned space with that size. For example,
304- \Bg will require the data to begin on a page boundary, while \Fg will
305- require this block to fit in a single page (which might be the same page
306- as the previous block if it fits).
307-
308- \A followed by a number (which can be a 32-bit number) will begin a new
309- expanded memory block which begins at the specified absolute address. If
310- everything before it is already beyond that address, then it is an error.
311-
312- \C followed by a number will begin a new expanded memory block which must
313- fit into the specified number of pages, otherwise it is an error. If
314- necessary, it will align it to a new page, but if the data is small enough
315- then this will be unnecessary and it will not do alignment.
316-
317- \D followed by a number will begin a new expanded memory block which must
318- start on the specified page but not necessarily at the beginning.
319-
320- [^ ]^ surround a block which will be entered into expanded memory. This
321- can contain assembly code which makes up to sixty-four bytes of data, and
322- should not contain any labels nor references (including anonymous labels
323- and references due to the [@ ]@ blocks). (However, \: is allowed.)
324-
325- ^ followed by a file name makes a sub-assembly. This is similar to ~ but
326- the data which is assembled from that file is written to expanded memory
327- like \^ instead of like \~ does. This is parsed after the rest of the main
328- file is parsed, instead of before like the ~ command does. The initial
329- internal address in the sub-assembly, which is also the starting address
330- that data will be copied from, is the same as the outer address; you can
331- use | to change this if desired. (The intended use of this is for making
332- overlays which contain absolute addressing within the overlay. If you
333- only use relative addressing then this is not important.) A temporary file
334- named ".uxn_subassembly" will be created; it can safely be deleted.
335-
336- \+ followed by a name of a label or macro will export that label or macro
337- to all sub-assemblies; inside of a sub-assembly it will export a name (you
338- cannot export a macro from a sub-assembly) into the main code (which can
339- be exported to later sub-assemblies, but not ones that come before). Even
340- if it is exported from the main code, a label defined by \* cannot be
341- referenced by sub-assemblies in the same or an earlier block than the \*
342- is in, but can be referenced by sub-assemblies in any later block.
343-
344-
345-=== Compact fonts ===
346-
347-There is also a nonstandard feature to make 8x8 fonts compact. This uses
348-the following nonstandard tokens:
349-
350- [' and ]' surround a block that contains character codes to be remapped.
351- Within this block, # and " and \~ and direct numeric data is affected,
352- and anything else is not affected.
353-
354- \m followed by a number and then ~ and a file name will treat that file
355- as a raw 8x8 1bpp font, and will be copied into the output like \~ does
356- but will delete unused characters from the font, and renumber the rest
357- of the characters and change the data in the [' and ]' to the renumbered
358- character codes; the number before ~ is the first character code number.
359- After this, the address of character code zero (which is not necessarily
360- a valid character code) is pushed to the special stack so that \@ can be
361- used. The \m command cannot occur more than once. Any character codes
362- that are beyond the end of the (full) font will be renumbered to numbers
363- after the end of the font with the deleted characters, so that you can
364- still add more characters in your own program beyond those in the font
365- file that is specified.
366-
367- \mk followed by two or four hex digits will cause those characters to be
368- kept even if they are not used. If there are four hex digits, then it is
369- a range (inclusive on both ends), and it will guarantee that they will be
370- a contiguous range of character codes.
371-

 1@@ -1,26 +0,0 @@
 2-This document contains instructions for compiling the programs in this
 3-repository, in case they are helpful for anyone.
 4-
 5-Note that these programs are designed for Linux. There is no guarantee
 6-that they will work on Windows; if you wish to use them on Windows, you
 7-may consider using WSL (although I have not tried this, because I do not
 8-have Microsoft Windows).
 9-
10-
11-=== Assembler ===
12-
13-The uxnasm.c file is the assembler and does not have any dependencies
14-other than the C standard library; you can just compile it normally,
15-using gcc or clang (although I have not tried clang).
16-
17-
18-=== Emulator ===
19-
20-The main.c file is the emulator itself, and requires SDL1. The top of
21-the main.c file contains a shell command to compile it which works on
22-my computer, although your computer might be set up differently.
23-
24-One person, who was using Windows 11, WSL2, Ubuntu, compiled it using the
25-below command, with the "libsdl1.2-compat-dev" package:
26-  gcc main.c -o uxn38 -I/usr/include/SDL -D_GNU_SOURCE=1 -D_REENTRANT -lSDL -L/usr/local/lib
27-

  1@@ -1,347 +0,0 @@
  2-.\" Manpage reference for uxntal.
  3-.\" by Eiríkr Åsheim
  4-.\" Contact d_m@plastic-idolatry.com to correct errors or typos.
  5-.TH uxntal 7 "12 Aug 2026" "1.0" "Uxntal Reference Guide"
  6-.SH NAME
  7-uxntal \- assembly language for Varvara virtual machine
  8-.SH DESCRIPTION
  9-Uxntal is an 8-bit instruction set for programming the Varvara virtual machine.
 10-It uses the lower 5-bits to specify an opcode, and the upper 3-bits to specify
 11-optional modes.
 12-
 13-ROMs consist of a 16-bit address space of bytes. Any byte can be interpreted as either data or an instruction. A 2-byte program counter (\fIpc\fP) determines the address of the next instruction to decode and run.
 14-
 15-Instructions manipulate data using two stacks: a working stack (\fBwst\fP) and a return stack (\fBrst\fP). Each stack consists of 256 bytes, and in the case of overflow or underflow the stack pointer will wrap (the stacks are circular).
 16-
 17-There are also 256 bytes of device memory, which are used to interact with the virtual machine and its devices.
 18-
 19-Instructions deal with unsigned 8-bit values (\fIbytes\fP) and unsigned 16-bit values (\fIshorts\fP). There are no other built-in data types. Occasionally values are treated as signed, such as when loading, storing, or jumping with a relative address.
 20-
 21-Short values are stored on the stack in big-endian byte order: the least significant byte will be on the top of the stack. This makes \fB#abcd\fP equivalent to \fB#ab #cd\fP.
 22-
 23-.SH INSTRUCTION LAYOUT
 24-
 25- 0x01 ----
 26- 0x02     \\
 27- 0x04      +- \fIopcode\fP
 28- 0x08     /
 29- 0x10 ----
 30- 0x20 ---- 2: \fIshort mode\fP
 31- 0x40 ---- r: \fIreturn mode\fP
 32- 0x80 ---- k: \fIkeep mode\fP
 33-
 34-.SH OPCODE LAYOUT
 35-
 36-There are 32 base values for opcodes:
 37-
 38-    0x00 \fBBRK*\fP   0x08 \fBEQU\fP    0x10 \fBLDZ\fP    0x18 \fBADD\fP
 39-    0x01 \fBINC\fP    0x09 \fBNEQ\fP    0x11 \fBSTZ\fP    0x19 \fBSUB\fP
 40-    0x02 \fBPOP\fP    0x0a \fBGTH\fP    0x12 \fBLDR\fP    0x1a \fBMUL\fP
 41-    0x03 \fBNIP\fP    0x0b \fBLTH\fP    0x13 \fBSTR\fP    0x1b \fBDIV\fP
 42-    0x04 \fBSWP\fP    0x0c \fBJMP\fP    0x14 \fBLDA\fP    0x1c \fBAND\fP
 43-    0x05 \fBROT\fP    0x0d \fBJCN\fP    0x15 \fBSTA\fP    0x1d \fBORA\fP
 44-    0x06 \fBDUP\fP    0x0e \fBJSR\fP    0x16 \fBDEI\fP    0x1e \fBEOR\fP
 45-    0x07 \fBOVR\fP    0x0f \fBSTH\fP    0x17 \fBDEO\fP    0x1f \fBSFT\fP
 46-
 47-The "complete" opcode's value can be derived by combining the base value with its flags.
 48-
 49-For example, \fBADD2k\fP is \fB(ADD | 2 | k)\fP = \fB(0x18 | 0x20 | 0x80)\fP = \fB0xb8\fP.
 50-
 51-Unlike other opcodes, \fB0x00\fP (\fBBRK*\fP) is contextual: its meaning depends on the \fImode\fP bits provided:
 52-
 53-    0x00 \fBBRK\fP    0x80 \fBLIT\fP
 54-    0x20 \fBJCI\fP    0xa0 \fBLIT2\fP
 55-    0x40 \fBJMI\fP    0xc0 \fBLITr\fP
 56-    0x60 \fBJSI\fP    0xe0 \fBLIT2r\fP
 57-
 58-.SH STACK EFFECTS
 59-
 60-.BR
 61-
 62-.SS NOTATION
 63-
 64-Given a stack effect \fB( a^ b^ c^ -- c^ a^ b^ )\fP here is what each symbol means:
 65-
 66-    \fB(\fP and \fB)\fP are comment delimiters
 67-    \fBa^\fP, \fBb^\fP, and \fBc^\fP are values on the stack
 68-    \fB^\fP indicates that each value is a \fIbyte\fP (\fB*\fP would indicate \fIshort\fP)
 69-    \fB--\fP separates the "before" and "after" of the stack effect
 70-
 71-The effect here is to move the top byte of the stack below the next two bytes, which could be achieved with \fBROT ROT\fP.
 72-
 73-By default stack effects describe the effect on \fBwst\fP. When \fBrst\fP is involved we use \fB[]\fP to differentiate the stacks. For example \fB( a* [b*] -- a+1* [b+1*] )\fP will increment the top short of both \fBwst\fP and \fBrst\fP.
 74-
 75-.SS EFFECTS AND MODES
 76-
 77-Regular instructions have a single stack effect which is modified in a predictable way by any additional modes.
 78-
 79-For example the generic effect for \fBADD\fP is ( x y -- x+y ). The eight combinations of modes have the following effects:
 80-
 81-.nf
 82-
 83-    \fBADD\fP    ( x^ y^   -- x+y^ )         sum bytes from \fBwst\fP
 84-    \fBADDr\fP   ( [x^ y^] -- [x+y^] )       sum bytes from \fBrst\fP
 85-    \fBADD2\fP   ( x* y*   -- x+y* )         sum shorts from \fBwst\fP
 86-    \fBADD2r\fP  ( [x* y*] -- [x+y*] )       sum shorts from \fBrst\fP
 87-    \fBADDk\fP   ( x^ y^   -- x^ y^ x+y^ )   sum and keep bytes from \fBwst\fP
 88-    \fBADDkr\fP  ( [x^ y^] -- [x^ y^ x+y^] ) sum and keep bytes from \fBrst\fP
 89-    \fBADD2k\fP  ( x* y*   -- x* y* x+y* )   sum and keep shorts from \fBwst\fP
 90-    \fBADD2kr\fP ( [x* y*] -- [x* y* x+y*] ) sum and keep shorts from \fBrst\fP
 91-
 92-.fi
 93-
 94-Thus for regular instructions writing a "generic" effect (leaving sigils off values whose size depends on \fIshort mode\fP) is sufficient to describe its behavior across all eight variations. Note that some instructions always read values of a fixed size. For example the boolean condition read by \fBJCN\fP is always one byte, no matter what modes are used.
 95-
 96-In \fIreturn mode\fP the stacks are reversed. Effects on \fBwst\fP will instead affect \fBrst\fP, and effects on \fBrst\fP will instead affect \fBwst\fP. For example, \fBSTH\fP reads a byte from \fBwst\fP and writes it to \fBrst\fP, but \fBSTHr\fP reads a byte from \fBrst\fP and writes it to \fBwst\fP.
 97-
 98-In \fIkeep mode\fP all the values on the left-hand side of the stack effect will also appear on the right-hand side before the outputs. For example, \fBSWP\fP is \fB(x y -- y x)\fP but \fBSWPk\fP is \fB(x y -- x y y x)\fP.
 99-
100-.SS TERMINOLOGY
101-
102-We consider the top of the stack to be the first value of the stack, and count back from there. For example, given the stack effect \fB( a b c -- )\fP we would say that \fBc\fP is the top of the stack, \fBb\fP is the second value (second from the top), and \fBa\fP is the third value (third from the top).
103-
104-.SH REGULAR INSTRUCTIONS
105-
106-.BR
107-
108-.SS INC ( x -- x+1 )
109-
110-Increment the top value of the stack by 1.
111-
112-Overflow will be truncated, so \fB#ff INC\fP will evaluate to \fB0x00\fP.
113-
114-.SS POP ( x -- )
115-
116-Remove the top value of the stack.
117-
118-\fBPOPk\fP is guaranteed to have no effect (it will not change the stack).
119-
120-.SS NIP ( x y -- y )
121-
122-Remove the second value of the stack.
123-
124-Note that \fBNIPk\fP is identical to \fBDUP\fP.
125-
126-.SS SWP ( x y -- y x )
127-
128-Swap the top two values of the stack.
129-
130-.SS ROT ( x y z -- y z x )
131-
132-Rotate the top three values of the stack. The lowest becomes the top and the others are each shifted down one place.
133-
134-.SS DUP ( x -- x x )
135-
136-Place a copy of the top value of the stack on top of the stack.
137-
138-.SS OVR ( x y -- x y x )
139-
140-Place a copy of the second value of the stack on top of the stack.
141-
142-.SS EQU ( x y -- x==y^ )
143-
144-Test whether the top two values of the stack are equal.
145-
146-Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
147-
148-.SS NEQ ( x y -- x!=y^ )
149-
150-Test whether the top two values of the stack are not equal.
151-
152-Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
153-
154-.SS GTH ( x y -- x>y^ )
155-
156-Test whether the second value of the stack is greater than the top.
157-
158-Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
159-
160-.SS LTH ( x y -- x<y^ )
161-
162-Test whether the second value of the stack is less than the top.
163-
164-Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
165-
166-.SS JMP ( x -- ; pc <- x )
167-
168-Jump to a location.
169-
170-The program counter (\fIpc\fP) is unconditionally updated. When \fIx\fP is a byte, it is treated as relative (\fBpc += x\fP) and when \fIx\fP is a short it is treated as absolute (\fBpc = x\fP).
171-
172-It is common to \fBJMP\fP with boolean bytes (0-1) to handle simple conditionals. For example:
173-
174-    \fB@max ( x^ y^ -- max^ ) GTHk JMP SWP POP JMP2r\fP
175-
176-.SS JCN ( bool^ x -- ; pc <- x if bool )
177-
178-Jump to a location when a condition is true.
179-
180-The program counter (\fIpc\fP) is updated when \fIbool\fP is non-zero. When \fIx\fP is a byte, it is treated as relative (\fBpc += x\fP) and when \fIx\fP is a short it is treated as absolute (\fBpc = x\fP).
181-
182-.SS JSR ( x -- [pc+1*] )
183-
184-Jump to a location, saving a reference to return to.
185-
186-Stores the next address to execute before unconditionally updating the program counter (\fIpc\fP). This instruction is usually used to invoke subroutines, which use the \fBJMP2r\fP to return. When \fIx\fP is a byte, it is treated as relative (\fBpc += x\fP) and when \fIx\fP is a short it is treated as absolute (\fBpc = x\fP).
187-
188-The saved address will always be a short regardless of \fIshort mode\fP.
189-
190-.SS STH ( x -- [x] )
191-
192-Move the top value of the stack to the return stack.
193-
194-.SS LDZ ( zp^ -- x )
195-
196-Load data from a zero-page address (\fB0x00 - 0xff\fP).
197-
198-.SS STZ ( x zp^ -- )
199-
200-Store data at a zero-page address (\fB0x00 - 0xff\fP).
201-
202-.SS LDR ( rel^ -- x )
203-
204-Load data from a relative address (\fBpc + x\fP).
205-
206-Note that unlike \fBLDZk\fP and \fBLDAk\fP the \fBLDRk\fP instruction is not very useful, since a relative address is usually only meaningful when run from a particular address (i.e. for a particular \fIpc\fP value).
207-
208-.SS STR ( x rel^ -- )
209-
210-Store data at a relative address (\fBpc + x\fP).
211-
212-Note that unlike \fBSTZk\fP and \fBSTAk\fP the \fBSTRk\fP instruction is not very useful, since a relative address is usually only meaningful when run from a particular address (i.e. for a particular \fIpc\fP value).
213-
214-.SS LDA ( abs* -- x )
215-
216-Load data from an absolute address (\fB0x0000 - 0xffff\fP).
217-
218-.SS STA ( x abs* -- )
219-
220-Store data at an absolute address (\fB0x0000 - 0xffff\fP).
221-
222-.SS DEI ( dev^ -- x )
223-
224-Read data from a device port (\fB0x00 - 0xff\fP).
225-
226-Reading from some ports may have an effect on the underlying VM; in other cases it will simply read values from device memory. For two-byte device ports the effect (if any) is triggered by reading the higher byte (the most significant byte).
227-
228-See Varvara device documentation for more details.
229-
230-.SS DEO ( x dev^ -- )
231-
232-Write data to a device port (\fB0x00 - 0xff\fP).
233-
234-Writing to some ports may have an effect on the underlying VM; in other cases it will simply write values to device memory. For two-byte device ports the effect (if any) is triggered by writing the lower byte (the least significant byte).
235-
236-See Varvara device documentation for more details.
237-
238-.SS ADD ( x y -- x+y )
239-
240-Add the top two values of the stack.
241-
242-Overflow will be truncated, so \fB#ff #03 ADD\fP will evaluate to \fB0x02\fP.
243-
244-.SS SUB ( x y -- x-y )
245-
246-Subtract the top of the stack from the second value of the stack.
247-
248-Underflow will be truncated, so \fB#01 #03 SUB\fP will evaluate to \fB0xfe\fP.
249-
250-.SS MUL ( x y -- xy )
251-
252-Multiply the top two values of the stack.
253-
254-Overflow will be truncated, so \fB#11 #11 MUL\fP will evaluate to \fB0x21\fP.
255-
256-.SS DIV ( x y -- x/y )
257-
258-Divide the second value of the stack by the top of the stack.
259-
260-\fBDIV\fP implements \fIEuclidean division\fP, which is also known as \fIinteger division\fP. It returns whole numbers, so \fB#08 #09 DIV\fP evaluates to \fB0x00\fP.
261-
262-Division by zero will return zero (instead of signaling an error).
263-
264-Unlike \fBADD\fP, \fBSUB\fP, and \fBMUL\fP, \fBDIV\fP does not behave correctly for numbers which should be treated as signed. For example, the signed byte representation of \fB-2\fP is \fB0xfe\fP, but \fB#06 #fe DIV\fP evaluates to \fB0x00\fP (\fB6 / 254 = 0\fP). For signed values the correct result should instead be \fB0xfd\fP (\fB6 / -2 = -3\fP).
265-
266-There is no \fIremainder\fP instruction, but the phrase \fBDIVk MUL SUB\fP can be used to compute the remainder.
267-
268-.SS AND ( x y -- x&y )
269-
270-Compute the bitwise intersection of the top two values of the stack.
271-
272-.SS ORA ( x y -- x|y )
273-
274-Compute the bitwise union of the top two values of the stack.
275-
276-.SS EOR ( x y -- x^y )
277-
278-Compute the bitwise exclusive-or (\fIxor\fP) of the top two values of the stack.
279-
280-.SS SFT ( x rl^ -- (x>>l)<<r )
281-
282-Compute a bit shift of the second value of the stack; the directions and distances of the shift are determined by the top value of the stack.
283-
284-Given a byte \fIrl\fP consisting of a low nibble (\fIl\fP) and a high nibble (\fIr\fP), this instruction shifts \fIx\fP left by \fIl\fP and then right by \fIr\fP.
285-
286-Right shifts are unsigned (they introduce zero bits). There are no signed shifts.
287-
288-For 16-bit (and 8-bit) values, one nibble (\fB0x0 - 0xf\fP) is sufficient to express all useful left or right shifts.
289-
290-  Right: \fB#ff #03 SFT\fP evaluates to \fB0x1f\fP
291-  Left:  \fB#ff #20 SFT\fP evaluates to \fB0xfc\fP
292-  Both:  \fB#ff #23 SFT\fP evaluates to \fB0x7c\fP
293-
294-There is no rotation instruction but one-byte rotations can be accomplished with \fBDUP\fP and \fBSFT2\fP:
295-
296-    \fB#87 DUP #03 SFT2 NIP\fP ( 0x87 rotated right by 3 is 0xf0 )
297-    \fB#87 DUP #20 SFT2 POP\fP ( 0x87 rotated left by 2 is 0x1e )
298-
299-.SH SPECIAL INSTRUCTIONS
300-
301-These instructions do not accept all mode flags (some do not accept any).
302-
303-.SS BRK
304-
305-The break instruction is used to end a vector call and return control to the virtual machine.
306-
307-.SS JCI, JMI, and JSI
308-
309-The "immediate jump" instructions are produced by the assembler. They interpret the next 2 bytes of the ROM as a relative address (\fIaddr\fP) and have the following effects:
310-
311- \fBJMI\fP ( -- )       jump to \fIaddr\fP unconditionally
312- \fBJCI\fP ( bool^ -- ) jump to \fIaddr\fP if \fIbool\fP is non-zero
313- \fBJSI\fP ( -- [pc*] ) jump to \fIaddr\fP saving the current address (\fIpc\fP) on \fIrst\fP
314-
315-(The instruction pointer will be moved forward 2 bytes, past the relative address.)
316-
317-These instructions are created by the assembler from special syntax:
318-
319-    \fB!dest\fP produces \fBJMI wx yz\fP
320-    \fB?dest\fP produces \fBJCI wx yz\fP
321-    \fBdest\fP  produces \fBJSI wx yz\fP (assuming \fBdest\fP is not a macro or reserved)
322-
323-.SS LIT, LIT2, LITr, and LIT2r
324-
325-Push a literal value on the stack.
326-
327-The "literal" instructions are used to push new data onto the stacks. They interpret the next 1-2 bytes of the ROM (\fIwx\fP, \fIwxyz\fP) as data and push it onto the corresponding stack:
328-
329-    \fBLIT\fP   ( -- wx^ )     push literal byte \fIwx\fP onto the \fBwst\fP
330-    \fBLITr\fP  ( -- [wx^] )   push literal byte \fIwx\fP onto the \fBrst\fP
331-    \fBLIT2\fP  ( -- wxyz* )   push literal short \fIwxyz\fP (2 bytes) onto the \fBwst\fP
332-    \fBLIT2r\fP ( -- [wxyz*] ) push literal short \fIwxyz\fP (2 bytes) onto the \fBrst\fP
333-
334-(The instruction pointer will be moved forward 1-2 bytes, past the literal data.)
335-
336-Literal values can be updated dynamically using store instructions:
337-
338-    #abcd ;x STA2
339-    ( later on... )
340-    LIT2 [ @x $2 ]
341-
342-.SH SEE ALSO
343-
344- https://wiki.xxiivv.com/site/uxntal_opcodes.html   \fIUxntal Opcodes\fP
345- https://wiki.xxiivv.com/site/uxntal_syntax.html    \fIUxntal Syntax\fP
346- https://wiki.xxiivv.com/site/uxntal_modes.html     \fIUxntal Modes\fP
347- https://wiki.xxiivv.com/site/uxntal_immediate.html \fIImmediate opcodes\fP
348- https://wiki.xxiivv.com/site/varvara.html          \fIVarvara\fP

  1@@ -1,394 +0,0 @@
  2-
  3-=== Command-line switches ===
  4-
  5--D
  6-  Use double buffering for the display.
  7-
  8--F
  9-  Start in full screen mode. It will decide the appropriate screen size
 10-  automatically if you do not specify the -w and -h switches. This does
 11-  not imply -S but you may specify both switches.
 12-
 13--I
 14-  Use a separate thread to read from stdin.
 15-
 16--J #
 17-  Set joystick mode. See the below section about joystick for details.
 18-
 19--N
 20-  Tells the window manager to omit the frame.
 21-
 22--O
 23-  Emulate touch screen. (This is an experimental feature, and may be
 24-  changed or removed in future.)
 25-
 26--Q
 27-  Disable the mouse initially (it can still be enabled at run time).
 28-
 29--S
 30-  Disallow the uxn program to change the screen size.
 31-
 32--T year.month.day.hours.minutes.seconds.wday.yday.yday.isdst
 33-  Use a fixed value for the date/time, by numbers with dots in between. In
 34-  this case, it will read the same values from the date/time device each
 35-  time it is read. If you put less numbers than expected, then zero will
 36-  be used for the remaining values; however, some programs will use these
 37-  values to seed a random number generator and will not work correctly if
 38-  they are zero. (Note that the month number is zero-based, while the day
 39-  number is one-based.)
 40-
 41--T @unixtime
 42-  Use a fixed value for the date/time like the other -T does, but treat
 43-  the argument as UNIX time if the argument starts with a at sign; it will
 44-  be converted to the corresponding date/time in the Gregorian calendar.
 45-  In this case, the presence or absence of the -Z switch does matter,
 46-  since it will convert it to local time if the -Z switch is not specified
 47-  or to UTC if the -Z switch is specified.
 48-
 49--Y
 50-  Enable file system access including writing.
 51-
 52--Z
 53-  Use UTC instead of local time. (Has no effect in combination with -T,
 54-  unless the UNIX time variant of -T is used.)
 55-
 56--a #
 57-  Set audio. See the below section about audio for details. If both -a and
 58-  -n switches are used, then audio data is written to stdout (it is signed
 59-  16-bits big-endian).
 60-
 61--d
 62-  Enable some debugging features. (Some will work even without this.)
 63-
 64--e #
 65-  Execute another program (with "sh -c"), which will be connected to this
 66-  one using the standard I/O. For example, it can be used with nc to make
 67-  remote two players.
 68-
 69--h #
 70-  Set default screen height.
 71-
 72--i
 73-  Hide the system mouse cursor. (The Uxn program might still draw its own
 74-  mouse cursor, which most do.)
 75-
 76--j
 77-  Enable key repeat for joypad emulation.
 78-
 79--m #
 80-  Specify memory writes and device writes to do before or after loading the
 81-  file. See the "Memory/device scripts" section below for details.
 82-
 83--n
 84-  Disable GUI. Either this switch or -I is required in order to read stdin.
 85-  If neither -n nor -I is specified, then stdin cannot be read (although
 86-  command-line arguments can still be read).
 87-
 88--p #
 89-  Select the palette. Valid palette numbers are 0 to 7, where 7 is the
 90-  default setting and means that the running Uxn program can set colours.
 91-  If you follow the palette number by a equal sign and then RGB hex codes
 92-  then it will define that palette. Specify eight RGB colours each of which
 93-  is six hex digits, with commas in between.
 94-
 95--q
 96-  Disable standard I/O.
 97-
 98--s #
 99-  Define scroll amount.
100-
101--t #
102-  Set the frame rate, in milliseconds per frame.
103-
104--w #
105-  Set default screen width.
106-
107--x
108-  Enable nonstandard features.
109-
110--y
111-  Enable read-only file system access.
112-
113--z #
114-  Set zoom level.
115-
116-
117-=== Function keys ===
118-
119-F1
120-  Advance one frame, even if paused.
121-
122-F2
123-  Mute/unmute audio.
124-
125-F3
126-  Toggle the mouse mode. When the mouse mode is disabled, the mouse device
127-  does not work; the mouse vector is not called and the mouse coordinates
128-  and button state is not updated.
129-
130-F4
131-  Change which graphics layers are displayed. Either both layers, or only
132-  foreground or only background.
133-
134-F5
135-  Redraw screen. If the right shift key is also pushed, then also sends
136-  some debug output to stderr.
137-
138-F6 / F7
139-  Palette selection.
140-
141-F8
142-  Debug menu.
143-
144-F9
145-  Restart.
146-
147-F10
148-  Quit.
149-
150-PAUSE
151-  Pause/unpause VM.
152-
153-PAGE-UP / PAGE-DOWN
154-  Scroll up/down.
155-
156-Some programs use shortcut keys with control and letters. This does not
157-work in this program; therefore, END is an alias for the joypad A button
158-(the left control key also corresponds to the joypad A button, but if used
159-together with letter keys, will enter control characters instead).
160-
161-
162-=== Audio ===
163-
164-The audio setting consists of a sequence of letters and numbers; each item
165-is one letter "a" to "z" followed by a number of any number of digits. (It
166-can optionally have - at first for negative numbers, although most options
167-cannot use negative numbers.)
168-
169-b = Buffer size.
170-
171-c = Number of output channels, which can be 1 (mono) or 2 (stereo).
172-
173-e = Envelope speed. If not specified, then it is fifteenths of seconds.
174-
175-m = If set to 1, then audio is initially muted. (This option is ignored if
176-the -n switch is used.)
177-
178-n = Transpose amount.
179-
180-r = Sample rate in hertz. Normally, this setting is also the sample rate
181-for middle C.
182-
183-v = Output volume from 0 to 273. If not all of the four VM audio channels
184-are being used, then this number may be set higher than 273.
185-
186-(Currently there is not the setting of interpolation, filter, etc.)
187-
188-
189-=== Joystick ===
190-
191-The joystick parameter can be ? to list joysticks, or ? and a number to
192-display details about that joystick, or it can be the below specification
193-in order to configure joysticks.
194-
195-The first part is numbers with commas in between, being the joystick ID
196-numbers (as shown by the ? list); up to four numbers can be specified. If
197-a number is omitted, then that slot is not used.
198-
199-After the first part is a forward slash, and then the mapping (all
200-joysticks must use an identical mapping). Each item is a letter and then
201-a number, with no delimiters in between. The letters can be:
202-
203-A B S T U D L R
204-  Specify which joystick button to map to the uxn joypad button;
205-  respectively, A, B, SELECT, START, UP, DOWN, LEFT, RIGHT. Only the first
206-  128 buttons can be mapped.
207-
208-X Y x y
209-  Specify which axis to use as the X and Y axis. Uppercase letters means
210-  that axis is reversed; do not specify both "X" and "x", and do not
211-  specify both "Y" and "y".
212-
213-s
214-  Set sensitivity, from 1 to 32767. Higher numbers mean the joystick must
215-  be moved more in order to register, while lower numbers means that it
216-  does not need to moved much in order to be registered.
217-
218-H h I i
219-  Specify the hat number to use. Different letters correspond to different
220-  orientations (specify only up to one of these letters, not all of them).
221-  "h" is normal, "H" is reverse, "I" and "i" are sideways.
222-
223-
224-=== Nonstandard features ===
225-
226-The -x switch enables the following nonstandard features, which include
227-some nonstandard expansion commands and nonstandard ports. They should not
228-be used in portable programs until they become standardized, though (you
229-can discuss in the mailing list of Uxn; changes may also be made in future,
230-possibly as a result of the discussions).
231-
232-If any such features listed below become standardized in future, then their
233-documentation will be moved to the varvara.doc file, and the -x switch will
234-no longer be required in order to use them.
235-
236-The list of expansion commands below uses > for output parameters (from the
237-emulator to the program), ? for parameters that may be input and/or output,
238-* for 16-bit values, and % for values of lengths other than 8-bits or
239-16-bits or if they are of a variable length.
240-
241-03 device_id uuid% >version ?extra%
242-  Loads a nonstandard device, or a nonstandard command for an existing
243-  device or that applies globally; see below section for details. This is
244-  called a "UUID-based extension".
245-
246-04 >pages*
247-  Tells number of expanded memory pages. (This is the maximum valid value
248-  for src_page and dst_page in expanded memory operations.) (If some of the
249-  pages are read-only, then this is only the number of writable pages. The
250-  number of writable pages might be less than the tital number of pages on
251-  systems with insufficient memory but that is able to emulate larger
252-  memory by reading from the program file instead.)
253-
254-a0 offset%
255-  Given a 32-bit offset, seek the currently opened file to the specified
256-  absolute offset. (The effect of seeking (absolute or relative) when a
257-  file is opened in append mode is unspecified.) If the file is not already
258-  open, it is opened for reading and writing (the append flag is ignored);
259-  if writing is not allowed, then it is opened for reading only.
260-
261-a1 offset%
262-  Given a signed 32-bit offset, seek the currently opened file to the
263-  specified offset relative to the current file position.
264-
265-a2 offset%
266-  Given a signed 32-bit offset, seek the currently opened file to the
267-  specified offset relative to the end of the file.
268-
269-a3 >offset%
270-  Tell the current offset of the currently opened file; the 32-bit offset
271-  will be stored in the expansion command buffer.
272-
273-b_ ?offset%
274-  Same as a_ but for the second file.
275-
276-Nonstandard ports of devices are:
277-
278-16
279-  Input flags. Currently only the low bit is used (the rest must be clear).
280-  If the low bit is set, then EOF trigger is enabled; the vector is called
281-  on EOF, with the type and input both set to zero.
282-
283-36*/46*/56*/66*
284-  Detune register. This is treated as sixteen fraction bits, and is then
285-  added to 1.0 and multiplied by the frequency which has been specified by
286-  the pitch and length ports.
287-
288-a7/b7
289-  In addition to the usual effect (sets the append mode), writing anything
290-  to this port (whether or not it is the same value that was previously
291-  written) will close the file.
292-
293-
294-=== Extensions ===
295-
296-This describes the nonstandard "03 extensions" command mentioned above.
297-
298-The parts of the command are:
299-
300-* Command code: Always 0x03.
301-
302-* Device number: A command that does not load or override a device into a
303-device slot is zero, otherwise it is a nonzero multiple of sixteen. Some
304-extensions and some implementations may have further restrictions. If this
305-number is not a multiple of sixteen (but must be at least sixteen), then
306-the low nybble indicates how many additional consecutive devices to be
307-affected; e.g. #33 means to affect all four audio devices (the high nybble
308-is 3 for the first audio device, and the low nybble 3 means the other 3).
309-
310-* UUID: Sixteen bytes, which identifies the extension.
311-
312-* Version: One byte. The emulator writes a nonzero value here (the specific
313-value is defined by the extension) if it is supported in this mode with
314-this device number and other parameters, or zero if it is not implemented.
315-(The uxn program should put zero here by default, so that if running on an
316-emulator that doesn't process the 03 command at all, it will work.)
317-
318-* Extra data: The number of bytes and meaning is defined by the specific
319-extension; this may be read-only, write-only, or some combination. If the
320-extension is not implemented, then the emulator MUST ignore it and MUST NOT
321-attempt to write anything here, and MUST NOT override any devices.
322-
323-An example of how to use this:
324-
325-  @load-ext1 ( -- success ) ;ext1 #02 DEO2 ;ext1/v LDA JMP2r
326-  @ext1 03 d0 <uuid> &v 00
327-
328-This example does not use any extra data, and selects an extension for
329-device #d0. The <uuid> must be replaced by the appropriate sixteen-byte
330-UUID for the extension being selected.
331-
332-
333-=== Implemented extensions ===
334-
335-This section lists the UUID-based extensions that are implemented in
336-this emulator (the -x switch is required, since they use nonstandard
337-expansion commands to activate them).
338-
339-See the file extension.doc for the definition of the extensions.
340-
341-* 4105259c-e061-11f0-963f-002618745416 (uses /dev/urandom)
342-
343-* 80175132-e263-11ed-b8c9-002618745416
344-
345-* 970b5a0c-2c44-11ee-ac3b-002618745416
346-
347-* 9c5f1356-6bc5-11ef-a6c9-002618745416 (also requires -I and -Y)
348-
349-
350-=== Memory/device scripts ===
351-
352-A command with the -m switch has the subcommands which have the format of
353-an optional "." to indicate executed after instead of before loading, and
354-then an optional letter "g" to "z" to specify the specific command (if none
355-is specified, then it is a memory command), and then the address in hex,
356-and then optionally = and the data in hex. The address is treated as a pure
357-number while the data is a sequence of bytes so the number of digits must
358-be an even number.
359-
360-It can also optionally be @ and a file name, in which case the commands are
361-loaded from a file. The file cannot itself have @ commands, but it may have
362-lines starting with # as comments.
363-
364-The subcommands are:
365-
366-Memory (no letter)
367-  Write memory starting at the specified address.
368-
369-Device trigger (p)
370-  Write and trigger devices starting at the specified address. If there are
371-  multiple bytes of data, then multiple consecutive ports are written to
372-  and are triggered.
373-
374-Device set (s)
375-  Same as device trigger but omit the trigger; only writes are done.
376-
377-Extension set (u)
378-  The data is the same as the 03 expansion command but without the initial
379-  03; it is automatically written into memory and executed as an expansion
380-  command. (This is a shortcut for the specific case of loading an
381-  extension that is not loaded by the uxn program itself, rather than
382-  having to use the -m and -mp switches. The address can be omitted,
383-  since the expansion command does not care about the address.)
384-
385-Execute (x)
386-  Execute uxn code at the specified address, which must be nonzero, and
387-  cannot be in expanded memory. (The data of this command is not used.)
388-
389-Screen compatibility flag (z2)
390-  The first byte of the data is the screen compatibility mode; see
391-  extension.doc for a list of the valid flags.
392-
393-During the execution of any of these commands, it behaves as though the -x
394-switch is specified, even if it isn't specified.
395-