From 8b5854c43b7ea6a0ee0e97b6e1f4ad8b41209385 Mon Sep 17 00:00:00 2001
From: d_m <d_m@plastic-idolatry.com>
Date: Fri, 2 Aug 2024 13:26:17 -0400
Subject: [PATCH] all instructions supported

---
 uxntal.1 | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 58 insertions(+), 1 deletion(-)

diff --git a/uxntal.1 b/uxntal.1
index 7d5aa94..4a2ce1b 100644
--- a/uxntal.1
+++ b/uxntal.1
@@ -90,15 +90,23 @@ Thus for regular instructions writing a "generic" effect (leaving sigils off val
 .SS EQU
 ( x y -- x==y^ )
 
+Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
+
 .SS NEQ
 ( x y -- x!=y^ )
 
+Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
+
 .SS GTH
 ( x y -- x>y^ )
 
+Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
+
 .SS LTH
 ( x y -- x<y^ )
 
+Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
+
 .SS JMP
 ( x -- ; pc <- x )
 
@@ -134,7 +142,6 @@ 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).
 
-
 .SS STR
 ( x rel^ -- )
 
@@ -166,6 +173,56 @@ 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.
 
+.SS ADD
+( x y -- x+y )
+
+Overflow will be truncated, so \fB#ff #03 ADD\fP will evaluate to \fB0x02\fP.
+
+.SS SUB
+( x y -- x-y )
+
+Underflow will be truncated, so \fB#01 #03 SUB\fP will evaluate to \fB0xfe\fP.
+
+.SS MUL
+( x y -- xy )
+
+Overflow will be truncated, so \fB#11 #11 MUL\fP will evaluate to \fB0x21\fP.
+
+.SS DIV
+( x y -- x/y )
+
+\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.
+
+Division by zero will return zero (instead of signaling an error).
+
+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).
+
+There is no \fIremainder\fP instruction, but the phrase \fBDIVk MUL SUB\fP can be used to compute the remainder.
+
+.SS AND
+( x y -- x&y )
+
+.SS ORA
+( x y -- x|y )
+
+.SS EOR
+( x y -- x^y )
+
+.SS SFT
+( x rl^ -- (x>>l)<<r )
+
+Given a byte \fIrl\fP consisting of a low nibble (\fIl\fP) and a high nibble (\fIh\fP), this instruction shifts \fIx\fP left by \fIl\fP and then right by \fIr\fP.
+
+Right shifts are unsigned (they introduce zero bits); there are no signed shifts.
+
+Since the largest values (\fIshort\fP) are 16-bit, one nibble (\fB0x0 - 0xf\fP) is sufficient to express all useful left or right shifts.
+
+Right: \fB#ff #03 SFT\fP evaluates to \fB0x1f\fP.
+
+Left: \fB#ff #20 SFT\fP evaluates to \fB0xfc\fP.
+
+Both: \fB#ff #23 SFT\fP evaluates to \fB0x7c\fP.
+
 .SH SPECIAL INSTRUCTIONS
 
 These instructions do not accept all mode flags (some do not accept any).