commit a405e1c
d_m
·
2024-08-06 03:36:21 +0000 UTC
parent 5a41189
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
1 files changed,
+49,
-76
+49,
-76
1@@ -75,14 +75,18 @@ Regular instructions have a single stack effect which is modified in a predictab
2
3 For example the generic effect for \fBADD\fP is ( x y -- x+y ). The eight combinations of modes have the following effects:
4
5- \fBADD\fP ( x^ y^ -- x+y^ ) sum two bytes using \fBwst\fP
6- \fBADDr\fP ( [x^ y^] -- [x+y^] ) sum two bytes using \fBrst\fP
7- \fBADD2\fP ( x* y* -- x+y* ) sum two shorts using \fBwst\fP
8- \fBADD2r\fP ( [x* y*] -- [x+y*] ) sum two shorts using \fBrst\fP
9- \fBADDk\fP ( x^ y^ -- x^ y^ x+y^ ) sum two bytes using \fBwst\fP, retain arguments
10- \fBADDkr\fP ( [x^ y^] -- [x^ y^ x+y^] ) sum two bytes using \fBrst\fP, retain arguments
11- \fBADD2k\fP ( x* y* -- x* y* x+y* ) sum two shorts using \fBwst\fP, retain arguments
12- \fBADD2kr\fP ( [x* y*] -- [x* y* x+y*] ) sum two shorts using \fBrst\fP, retain arguments
13+.nf
14+
15+ \fBADD\fP ( x^ y^ -- x+y^ ) sum bytes from \fBwst\fP
16+ \fBADDr\fP ( [x^ y^] -- [x+y^] ) sum bytes from \fBrst\fP
17+ \fBADD2\fP ( x* y* -- x+y* ) sum shorts from \fBwst\fP
18+ \fBADD2r\fP ( [x* y*] -- [x+y*] ) sum shorts from \fBrst\fP
19+ \fBADDk\fP ( x^ y^ -- x^ y^ x+y^ ) sum and keep bytes from \fBwst\fP
20+ \fBADDkr\fP ( [x^ y^] -- [x^ y^ x+y^] ) sum and keep bytes from \fBrst\fP
21+ \fBADD2k\fP ( x* y* -- x* y* x+y* ) sum and keep shorts from \fBwst\fP
22+ \fBADD2kr\fP ( [x* y*] -- [x* y* x+y*] ) sum and keep shorts from \fBrst\fP
23+
24+.fi
25
26 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.
27
28@@ -98,77 +102,65 @@ We consider the top of the stack to be the first value of the stack, and count b
29
30 .BR
31
32-.SS INC
33-( x -- x+1 )
34+.SS INC ( x -- x+1 )
35
36 Increment the top value of the stack by 1.
37
38 Overflow will be truncated, so \fB#ff INC\fP will evaluate to \fB0x00\fP.
39
40-.SS POP
41-( x -- )
42+.SS POP ( x -- )
43
44 Remove the top value of the stack.
45
46 \fBPOPk\fP is guaranteed to have no effect (it will not change the stack).
47
48-.SS NIP
49-( x y -- y )
50+.SS NIP ( x y -- y )
51
52 Remove the second value of the stack.
53
54 \fBNIPk\fP is guaranteed to have no effect (it will not change the stack).
55
56-.SS SWP
57-( x y -- y x )
58+.SS SWP ( x y -- y x )
59
60 Swap the top two values of the stack.
61
62-.SS ROT
63-( x y z -- y z x )
64+.SS ROT ( x y z -- y z x )
65
66 Rotate the top three values of the stack. The lowest becomes the top and the others are each shifted down one place.
67
68-.SS DUP
69-( x -- x x )
70+.SS DUP ( x -- x x )
71
72 Place a copy of the top value of the stack on top of the stack.
73
74-.SS OVR
75-( x y -- x y x )
76+.SS OVR ( x y -- x y x )
77
78 Place a copy of the second value of the stack on top of the stack.
79
80-.SS EQU
81-( x y -- x==y^ )
82+.SS EQU ( x y -- x==y^ )
83
84 Test whether the top two values of the stack are equal.
85
86 Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
87
88-.SS NEQ
89-( x y -- x!=y^ )
90+.SS NEQ ( x y -- x!=y^ )
91
92 Test whether the top two values of the stack are not equal.
93
94 Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
95
96-.SS GTH
97-( x y -- x>y^ )
98+.SS GTH ( x y -- x>y^ )
99
100 Test whether the second value of the stack is greater than the top.
101
102 Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
103
104-.SS LTH
105-( x y -- x<y^ )
106+.SS LTH ( x y -- x<y^ )
107
108 Test whether the second value of the stack is less than the top.
109
110 Result is guaranteed to be boolean (\fB0x00\fP or \fB0x01\fP).
111
112-.SS JMP
113-( x -- ; pc <- x )
114+.SS JMP ( x -- ; pc <- x )
115
116 Jump to a location.
117
118@@ -178,15 +170,13 @@ It is common to \fBJMP\fP with boolean bytes (0-1) to handle simple conditionals
119
120 @max ( x^ y^ -- max^ ) GTHk JMP SWP POP JMP2r
121
122-.SS JCN
123-( x bool^ -- ; pc <- x if bool )
124+.SS JCN ( x bool^ -- ; pc <- x if bool )
125
126 Jump to a location when a condition is true.
127
128 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).
129
130-.SS JSR
131-( x -- [pc+1*] )
132+.SS JSR ( x -- [pc+1*] )
133
134 Jump to a location, saving a reference to return to.
135
136@@ -194,82 +184,69 @@ Stores the next address to execute before unconditionally updating the program c
137
138 The saved address will always be a short regardless of \fIshort mode\fP.
139
140-.SS STH
141-( x -- [x] )
142+.SS STH ( x -- [x] )
143
144 Move the top value of the stack to the return stack.
145
146-.SS LDZ
147-( zp^ -- x )
148+.SS LDZ ( zp^ -- x )
149
150 Load data from a zero-page address (\fB0x00 - 0xff\fP).
151
152-.SS STZ
153-( x zp^ -- )
154+.SS STZ ( x zp^ -- )
155
156 Store data at a zero-page address (\fB0x00 - 0xff\fP).
157
158-.SS LDR
159-( rel^ -- x )
160+.SS LDR ( rel^ -- x )
161
162 Load data from a relative address (\fBpc + x\fP).
163
164 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).
165
166-.SS STR
167-( x rel^ -- )
168+.SS STR ( x rel^ -- )
169
170 Store data at a relative address (\fBpc + x\fP).
171
172 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).
173
174-.SS LDA
175-( abs* -- x )
176+.SS LDA ( abs* -- x )
177
178 Load data from an absolute address (\fB0x0000 - 0xffff\fP).
179
180-.SS STA
181-( x abs* -- )
182+.SS STA ( x abs* -- )
183
184 Store data at an absolute address (\fB0x0000 - 0xffff\fP).
185
186-.SS DEI
187-( dev^ -- x )
188+.SS DEI ( dev^ -- x )
189
190 Read data from a device port (\fB0x00 - 0xff\fP).
191
192 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.
193
194-.SS DEO
195-( x dev^ -- )
196+.SS DEO ( x dev^ -- )
197
198 Write data to a device port (\fB0x00 - 0xff\fP).
199
200 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.
201
202-.SS ADD
203-( x y -- x+y )
204+.SS ADD ( x y -- x+y )
205
206 Add the top two values of the stack.
207
208 Overflow will be truncated, so \fB#ff #03 ADD\fP will evaluate to \fB0x02\fP.
209
210-.SS SUB
211-( x y -- x-y )
212+.SS SUB ( x y -- x-y )
213
214 Subtract the top of the stack from the second value of the stack.
215
216 Underflow will be truncated, so \fB#01 #03 SUB\fP will evaluate to \fB0xfe\fP.
217
218-.SS MUL
219-( x y -- xy )
220+.SS MUL ( x y -- xy )
221
222 Multiply the top two values of the stack.
223
224 Overflow will be truncated, so \fB#11 #11 MUL\fP will evaluate to \fB0x21\fP.
225
226-.SS DIV
227-( x y -- x/y )
228+.SS DIV ( x y -- x/y )
229
230 Divide the second value of the stack by the top of the stack.
231
232@@ -281,23 +258,19 @@ Unlike \fBADD\fP, \fBSUB\fP, and \fBMUL\fP, \fBDIV\fP does not behave correctly
233
234 There is no \fIremainder\fP instruction, but the phrase \fBDIVk MUL SUB\fP can be used to compute the remainder.
235
236-.SS AND
237-( x y -- x&y )
238+.SS AND ( x y -- x&y )
239
240 Compute the bitwise union of the top two values of the stack.
241
242-.SS ORA
243-( x y -- x|y )
244+.SS ORA ( x y -- x|y )
245
246 Compute the bitwise intersection of the top two values of the stack.
247
248-.SS EOR
249-( x y -- x^y )
250+.SS EOR ( x y -- x^y )
251
252 Compute the bitwise exclusive-or (\fIxor\fP) of the top two values of the stack.
253
254-.SS SFT
255-( x rl^ -- (x>>l)<<r )
256+.SS SFT ( x rl^ -- (x>>l)<<r )
257
258 Compute a bit shift of the second value of the stack; the directions and distances are determined by the top value of the stack.
259
260@@ -325,7 +298,7 @@ The "immediate jump" instructions are produced by the assembler. They interpret
261
262 \fBJMI\fP ( -- ) jump to \fIaddr\fP unconditionally
263 \fBJCI\fP ( bool^ -- ) jump to \fIaddr\fP if \fIbool\fP is non-zero
264- \fBJSI\fP ( -- [pc*] ) jump to \fIaddr\fP saving the current address (\fIpc\fP) on the return stack
265+ \fBJSI\fP ( -- [pc*] ) jump to \fIaddr\fP saving the current address (\fIpc\fP) on \fIrst\fP
266
267 (The instruction pointer will be moved forward 2 bytes, past the relative address.)
268
269@@ -356,8 +329,8 @@ Literal values can be updated dynamically using store instructions:
270
271 .SH SEE ALSO
272
273- https://wiki.xxiivv.com/site/uxntal_opcodes.html \fIUxntal Opcodes\fP
274- https://wiki.xxiivv.com/site/uxntal_syntax.html \fIUxntal Syntax\fP
275- https://wiki.xxiivv.com/site/uxntal_modes.html \fIUxntal Modes\fP
276- https://wiki.xxiivv.com/site/uxntal_immediate.html \fIImmediate opcodes\fP
277- https://wiki.xxiivv.com/site/varvara.html \fIVarvara\fP
278+ https://wiki.xxiivv.com/site/uxntal_opcodes.html \fIUxntal Opcodes\fP
279+ https://wiki.xxiivv.com/site/uxntal_syntax.html \fIUxntal Syntax\fP
280+ https://wiki.xxiivv.com/site/uxntal_modes.html \fIUxntal Modes\fP
281+ https://wiki.xxiivv.com/site/uxntal_immediate.html \fIImmediate opcodes\fP
282+ https://wiki.xxiivv.com/site/varvara.html \fIVarvara\fP