d6
/
uxn11
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve formatting in small terms. 

This change does a few things:

 1. Uses .nf and .fi to disable fill during block
 2. Shortens block lines likely to wrap
 3. Moves instruction stack effect to subsection header
This commit is contained in:
~d6 2024-08-05 23:34:59 -04:00
parent f59563d750
commit a444725772
1 changed files with 49 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
doc/man/uxntal.7
View File

@ -75,14 +75,18 @@ Regular instructions have a single stack effect which is modified in a predictab
For example the generic effect for \fBADD\fP is ( x y -- x+y ). The eight combinations of modes have the following effects: For example the generic effect for \fBADD\fP is ( x y -- x+y ). The eight combinations of modes have the following effects:
\fBADD\fP ( x^ y^ -- x+y^ ) sum two bytes using \fBwst\fP .nf
\fBADDr\fP ( [x^ y^] -- [x+y^] ) sum two bytes using \fBrst\fP
\fBADD2\fP ( x* y* -- x+y* ) sum two shorts using \fBwst\fP \fBADD\fP ( x^ y^ -- x+y^ ) sum bytes from \fBwst\fP
\fBADD2r\fP ( [x* y*] -- [x+y*] ) sum two shorts using \fBrst\fP \fBADDr\fP ( [x^ y^] -- [x+y^] ) sum bytes from \fBrst\fP
\fBADDk\fP ( x^ y^ -- x^ y^ x+y^ ) sum two bytes using \fBwst\fP, retain arguments \fBADD2\fP ( x* y* -- x+y* ) sum shorts from \fBwst\fP
\fBADDkr\fP ( [x^ y^] -- [x^ y^ x+y^] ) sum two bytes using \fBrst\fP, retain arguments \fBADD2r\fP ( [x* y*] -- [x+y*] ) sum shorts from \fBrst\fP
\fBADD2k\fP ( x* y* -- x* y* x+y* ) sum two shorts using \fBwst\fP, retain arguments \fBADDk\fP ( x^ y^ -- x^ y^ x+y^ ) sum and keep bytes from \fBwst\fP
\fBADD2kr\fP ( [x* y*] -- [x* y* x+y*] ) sum two shorts using \fBrst\fP, retain arguments \fBADDkr\fP ( [x^ y^] -- [x^ y^ x+y^] ) sum and keep bytes from \fBrst\fP
\fBADD2k\fP ( x* y* -- x* y* x+y* ) sum and keep shorts from \fBwst\fP
\fBADD2kr\fP ( [x* y*] -- [x* y* x+y*] ) sum and keep shorts from \fBrst\fP
.fi
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. 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.
@ -98,77 +102,65 @@ We consider the top of the stack to be the first value of the stack, and count b
.BR .BR
.SS INC .SS INC ( x -- x+1 )
( x -- x+1 )
Increment the top value of the stack by 1. Increment the top value of the stack by 1.
Overflow will be truncated, so \fB#ff INC\fP will evaluate to \fB0x00\fP. Overflow will be truncated, so \fB#ff INC\fP will evaluate to \fB0x00\fP.
.SS POP .SS POP ( x -- )
( x -- )
Remove the top value of the stack. Remove the top value of the stack.
\fBPOPk\fP is guaranteed to have no effect (it will not change the stack). \fBPOPk\fP is guaranteed to have no effect (it will not change the stack).
.SS NIP .SS NIP ( x y -- y )
( x y -- y )
Remove the second value of the stack. Remove the second value of the stack.
\fBNIPk\fP is guaranteed to have no effect (it will not change the stack). \fBNIPk\fP is guaranteed to have no effect (it will not change the stack).
.SS SWP .SS SWP ( x y -- y x )
( x y -- y x )
Swap the top two values of the stack. Swap the top two values of the stack.
.SS ROT .SS ROT ( x y z -- y z x )
( x y z -- y z x )
Rotate the top three values of the stack. The lowest becomes the top and the others are each shifted down one place. Rotate the top three values of the stack. The lowest becomes the top and the others are each shifted down one place.
.SS DUP .SS DUP ( x -- x x )
( x -- x x )
Place a copy of the top value of the stack on top of the stack. Place a copy of the top value of the stack on top of the stack.
.SS OVR .SS OVR ( x y -- x y x )
( x y -- x y x )
Place a copy of the second value of the stack on top of the stack. Place a copy of the second value of the stack on top of the stack.
.SS EQU .SS EQU ( x y -- x==y^ )
( x y -- x==y^ )
Test whether the top two values of the stack are equal. Test whether the top two values of the stack are equal.
Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP). Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
.SS NEQ .SS NEQ ( x y -- x!=y^ )
( x y -- x!=y^ )
Test whether the top two values of the stack are not equal. Test whether the top two values of the stack are not equal.
Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP). Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
.SS GTH .SS GTH ( x y -- x>y^ )
( x y -- x>y^ )
Test whether the second value of the stack is greater than the top. Test whether the second value of the stack is greater than the top.
Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP). Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
.SS LTH .SS LTH ( x y -- x<y^ )
( x y -- x<y^ )
Test whether the second value of the stack is less than the top. Test whether the second value of the stack is less than the top.
Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP). Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
.SS JMP .SS JMP ( x -- ; pc <- x )
( x -- ; pc <- x )
Jump to a location. Jump to a location.
@ -178,15 +170,13 @@ It is common to \fBJMP\fP with boolean bytes (0-1) to handle simple conditionals
@max ( x^ y^ -- max^ ) GTHk JMP SWP POP JMP2r @max ( x^ y^ -- max^ ) GTHk JMP SWP POP JMP2r
.SS JCN .SS JCN ( x bool^ -- ; pc <- x if bool )
( x bool^ -- ; pc <- x if bool )
Jump to a location when a condition is true. Jump to a location when a condition is true.
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). 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).
.SS JSR .SS JSR ( x -- [pc+1*] )
( x -- [pc+1*] )
Jump to a location, saving a reference to return to. Jump to a location, saving a reference to return to.
@ -194,82 +184,69 @@ Stores the next address to execute before unconditionally updating the program c
The saved address will always be a short regardless of \fIshort mode\fP. The saved address will always be a short regardless of \fIshort mode\fP.
.SS STH .SS STH ( x -- [x] )
( x -- [x] )
Move the top value of the stack to the return stack. Move the top value of the stack to the return stack.
.SS LDZ .SS LDZ ( zp^ -- x )
( zp^ -- x )
Load data from a zero-page address (\fB0x00 - 0xff\fP). Load data from a zero-page address (\fB0x00 - 0xff\fP).
.SS STZ .SS STZ ( x zp^ -- )
( x zp^ -- )
Store data at a zero-page address (\fB0x00 - 0xff\fP). Store data at a zero-page address (\fB0x00 - 0xff\fP).
.SS LDR .SS LDR ( rel^ -- x )
( rel^ -- x )
Load data from a relative address (\fBpc + x\fP). Load data from a relative address (\fBpc + x\fP).
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). 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).
.SS STR .SS STR ( x rel^ -- )
( x rel^ -- )
Store data at a relative address (\fBpc + x\fP). Store data at a relative address (\fBpc + x\fP).
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). 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).
.SS LDA .SS LDA ( abs* -- x )
( abs* -- x )
Load data from an absolute address (\fB0x0000 - 0xffff\fP). Load data from an absolute address (\fB0x0000 - 0xffff\fP).
.SS STA .SS STA ( x abs* -- )
( x abs* -- )
Store data at an absolute address (\fB0x0000 - 0xffff\fP). Store data at an absolute address (\fB0x0000 - 0xffff\fP).
.SS DEI .SS DEI ( dev^ -- x )
( dev^ -- x )
Read data from a device port (\fB0x00 - 0xff\fP). Read data from a device port (\fB0x00 - 0xff\fP).
Reading from some ports may have an effect on the underlying VM; in other cases it will simply read values from device memory. See Varvara device documentation for more details. Reading from some ports may have an effect on the underlying VM; in other cases it will simply read values from device memory. See Varvara device documentation for more details.
.SS DEO .SS DEO ( x dev^ -- )
( x dev^ -- )
Write data to a device port (\fB0x00 - 0xff\fP). Write data to a device port (\fB0x00 - 0xff\fP).
Writing to some ports may have an effect on the underlying VM; in other cases it will simply write values to device memory. See Varvara device documentation for more details. Writing to some ports may have an effect on the underlying VM; in other cases it will simply write values to device memory. See Varvara device documentation for more details.
.SS ADD .SS ADD ( x y -- x+y )
( x y -- x+y )
Add the top two values of the stack. Add the top two values of the stack.
Overflow will be truncated, so \fB#ff #03 ADD\fP will evaluate to \fB0x02\fP. Overflow will be truncated, so \fB#ff #03 ADD\fP will evaluate to \fB0x02\fP.
.SS SUB .SS SUB ( x y -- x-y )
( x y -- x-y )
Subtract the top of the stack from the second value of the stack. Subtract the top of the stack from the second value of the stack.
Underflow will be truncated, so \fB#01 #03 SUB\fP will evaluate to \fB0xfe\fP. Underflow will be truncated, so \fB#01 #03 SUB\fP will evaluate to \fB0xfe\fP.
.SS MUL .SS MUL ( x y -- xy )
( x y -- xy )
Multiply the top two values of the stack. Multiply the top two values of the stack.
Overflow will be truncated, so \fB#11 #11 MUL\fP will evaluate to \fB0x21\fP. Overflow will be truncated, so \fB#11 #11 MUL\fP will evaluate to \fB0x21\fP.
.SS DIV .SS DIV ( x y -- x/y )
( x y -- x/y )
Divide the second value of the stack by the top of the stack. Divide the second value of the stack by the top of the stack.
@ -281,23 +258,19 @@ Unlike \fBADD\fP, \fBSUB\fP, and \fBMUL\fP, \fBDIV\fP does not behave correctly
There is no \fIremainder\fP instruction, but the phrase \fBDIVk MUL SUB\fP can be used to compute the remainder. There is no \fIremainder\fP instruction, but the phrase \fBDIVk MUL SUB\fP can be used to compute the remainder.
.SS AND .SS AND ( x y -- x&y )
( x y -- x&y )
Compute the bitwise union of the top two values of the stack. Compute the bitwise union of the top two values of the stack.
.SS ORA .SS ORA ( x y -- x|y )
( x y -- x|y )
Compute the bitwise intersection of the top two values of the stack. Compute the bitwise intersection of the top two values of the stack.
.SS EOR .SS EOR ( x y -- x^y )
( x y -- x^y )
Compute the bitwise exclusive-or (\fIxor\fP) of the top two values of the stack. Compute the bitwise exclusive-or (\fIxor\fP) of the top two values of the stack.
.SS SFT .SS SFT ( x rl^ -- (x>>l)<<r )
( x rl^ -- (x>>l)<<r )
Compute a bit shift of the second value of the stack; the directions and distances are determined by the top value of the stack. Compute a bit shift of the second value of the stack; the directions and distances are determined by the top value of the stack.
@ -325,7 +298,7 @@ The "immediate jump" instructions are produced by the assembler. They interpret
\fBJMI\fP ( -- ) jump to \fIaddr\fP unconditionally \fBJMI\fP ( -- ) jump to \fIaddr\fP unconditionally
\fBJCI\fP ( bool^ -- ) jump to \fIaddr\fP if \fIbool\fP is non-zero \fBJCI\fP ( bool^ -- ) jump to \fIaddr\fP if \fIbool\fP is non-zero
\fBJSI\fP ( -- [pc*] ) jump to \fIaddr\fP saving the current address (\fIpc\fP) on the return stack \fBJSI\fP ( -- [pc*] ) jump to \fIaddr\fP saving the current address (\fIpc\fP) on \fIrst\fP
(The instruction pointer will be moved forward 2 bytes, past the relative address.) (The instruction pointer will be moved forward 2 bytes, past the relative address.)