First draft of a real README for the VVS stdlib.
[vvhitespace] / stdlib / debug.pvvs
CommitLineData
48f88489
AT
1@ (c) 2020 Aaron Taylor <ataylor at subgeniuskitty dot com>
2@ See LICENSE.txt file for copyright and license details.
3
1a56830d
AT
4#ifndef VVS_STDLIB_DEBUG
5#define VVS_STDLIB_DEBUG
6
9f7f68e5
AT
7@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
8@ Some of the subroutines in this file duplicate other stdlib subroutines.
9@ This is to avoid outside dependencies and allow debugging of stdlib code.
10@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
11
1a56830d 12@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
bb21580a
AT
13@ Name:
14@ dumpheap (111000)
1a56830d 15@ Description:
bb21580a 16@ Dumps the heap from 'startaddr' to 'endaddr'.
6cb31a3e
AT
17@ This subroutine stomps on heap[1] after printing the first heap location.
18@ If you dump starting from heap[0], then heap[1] will print inaccurately.
19@ Starting the dump from any other location will work without error.
20@ TODO: Should I use heap[0] and DIE rather than RTS?
21@ At the moment, the ability to continue is too useful to me.
22@ If it's useful to me, it's probably useful to other people.
23@ For now, leave dumpheap as-is.
9f7f68e5 24@ Call Stack:
1a56830d
AT
25@ endaddr
26@ startaddr <-- TOS
27@ Return Stack:
28@ <empty>
29@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
4fba07dc 30NSSVTTTSSSN | Mark: 111000 (debug:dumpheap)
1a56830d
AT
31
32@ Prepare a numeric address and value on the stack
33SNS | DUP
34SNS | DUP
35TTT | LOAD
36SNT | SWAP
37
38@ Print output line for this memory location
9f7f68e5 39NSTTTTSTTN | JSR > 111011 (debug:printmagnitude)
1a56830d 40SSSTSSTN | PUSH ASCII '\t'
c6e2791f 41SSSTTTSTSN | PUSH ASCII ':'
1a56830d
AT
42TNSS | PUTC
43TNSS | PUTC
9f7f68e5
AT
44SNS | DUP
45NSTTTTSTSN | JSR > 111010 (debug:printsign)
46NSTTTTSTTN | JSR > 111011 (debug:printmagnitude)
1a56830d
AT
47SSSTSTSN | PUSH ASCII '\n'
48TNSS | PUTC
49
50@ Figure out if the loop is complete.
bb21580a 51SSSTN | PUSH 1 (ptr)
1a56830d
AT
52SNT | SWAP
53TTS | STORE
54SNS | DUP
bb21580a 55SSSTN | PUSH 1 (ptr)
1a56830d
AT
56TTT | LOAD
57TSST | SUBTRACT
58NTSSSTTTSSSSSSSSSSSN | BRZ > 00111000 00000000
bb21580a 59SSSTN | PUSH 1 (ptr)
1a56830d
AT
60TTT | LOAD
61SSSTN | PUSH 1
62TSSS | ADD
9f7f68e5 63NSNTTTSSSN | JMP > 111000 (dump heap)
1a56830d
AT
64
65@ Clean up and return
66NSSVSSTTTSSSSSSSSSSSN | Mark: 00111000 00000000
67SNN | DROP
68NTN | RTS
69
ae1f85a1
AT
70@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
71@ Name:
72@ dumpstack (111001)
73@ Description:
74@ Dumps 'count' entries from the stack.
75@ Call Stack:
76@ count <-- TOS
77@ Return Stack:
78@ <empty>
79@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
4fba07dc 80NSSVTTTSSTN | Mark: 111001 (debug:dumpstack)
ae1f85a1 81
9f7f68e5
AT
82@ Orient the user
83SSSSSSSSSN | PUSH ASCII '\0'
84SSSSSSTSTSN | PUSH ASCII '\n'
85SSSSTTTSTSN | PUSH ASCII ':'
86SSSTSTSSTTN | PUSH ASCII 'S'
87SSSTSSTTTTN | PUSH ASCII 'O'
88SSSTSTSTSSN | PUSH ASCII 'T'
89NSTTTTTSSN | JSR > 111100 (debug:printstring)
90
ae1f85a1 91@ Print output line for the current TOS.
9f7f68e5 92NSSVSSTTTSSTSSSSSSSTN | Mark: 00111001 00000001
ae1f85a1 93SNS | DUP
9f7f68e5 94NSTTTTSTTN | JSR > 111011 (debug:printmagnitude)
ae1f85a1 95SSSTSSTN | PUSH ASCII '\t'
c6e2791f 96SSSTTTSTSN | PUSH ASCII ':'
ae1f85a1
AT
97TNSS | PUTC
98TNSS | PUTC
99SNT | SWAP
9f7f68e5
AT
100SNS | DUP
101NSTTTTSTSN | JSR > 111010 (debug:printsign)
102NSTTTTSTTN | JSR > 111011 (debug:printmagnitude)
ae1f85a1
AT
103SSSTSTSN | PUSH ASCII '\n'
104TNSS | PUTC
105
106@ Figure out if the loop is complete.
ae1f85a1
AT
107SSSTN | PUSH 1
108TSST | SUBTRACT
63a60fe0
AT
109SNS | DUP
110NTSSSTTTSSTSSSSSSSSN | BRZ > 00111001 00000000
9f7f68e5 111NSNSSTTTSSTSSSSSSSTN | JMP > 00111001 00000001
ae1f85a1
AT
112
113@ Clean up and return
114NSSVSSTTTSSTSSSSSSSSN | Mark: 00111001 00000000
115SNN | DROP
116NTN | RTS
117
9f7f68e5
AT
118@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
119@ Name:
120@ printsign (111010)
121@ Description:
122@ Prints the sign of 'number'.
123@ Call Stack:
124@ number <-- TOS
125@ Return Stack:
126@ <empty>
127@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
128NSSVTTTSTSN | Mark: 111010 (debug:printsign)
129NTTSSTTTSTSSSSSSSSTN | BMI > 00111010 00000001
130SSSTSTSTTN | PUSH ASCII '+'
131NSNSSTTTSTSSSSSSSTSN | JMP > 00111010 00000010
132NSSVSSTTTSTSSSSSSSSTN | Mark: 00111010 00000001
133SSSTSTTSTN | PUSH ASCII '-'
134NSSVSSTTTSTSSSSSSSTSN | Mark: 00111010 00000010
135TNSS | PUTC
136NTN | RTS
137
138@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
139@ Name:
140@ printmagnitude (111011)
141@ Description:
142@ Prints the magnitude of 'number'.
143@ Call Stack:
144@ number <-- TOS
145@ Return Stack:
146@ <empty>
147@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
148NSSVTTTSTTN | Mark: 111011 (debug:printmagnitude)
149
150@ Extract the magnitude of the number.
151SNS | DUP
152NTTSSTTTSTTSSSSSSSSN | BMI > 00111011 00000000
153NSNSSTTTSTTSSSSSSSTN | JMP > 00111011 00000001
154NSSVSSTTTSTTSSSSSSSSN | Mark: 00111011 00000000
155SSTTN | PUSH -1
156TSSN | MULTIPLY
157NSSVSSTTTSTTSSSSSSSTN | Mark: 00111011 00000001
158
159@ Prepare for building a string on the stack.
160SSSSN | PUSH ASCII '\0'
161SNT | SWAP
162
163@ Pick off one digit on each pass through this loop.
164NSSVSSTTTSTTSSSSSSTSN | Mark: 00111011 00000010
165SNS | DUP
166
167@ Mod-off a digit, convert to ASCII, store on stack as part of the string.
168SSSTSTSN | PUSH +10
169TSTT | MODULO
170SSSTTSSSSN | PUSH ASCII '0'
171TSSS | ADD
172SNT | SWAP
173
174@ Divide down to next digit and keep looping if number != 0 yet.
175SSSTSTSN | PUSH +10
176TSTS | DIVIDE
177SNS | DUP
178NTSSSTTTSTTSSSSSSTTN | BRZ > 00111011 00000011
179NSNSSTTTSTTSSSSSSTSN | JMP > 00111011 00000010
180
181@ Print the string we have built on the stack.
182NSSVSSTTTSTTSSSSSSTTN | Mark: 00111011 00000011
183SNN | DROP
184NSTTTTTSSN | JSR > 111100 (debug:printstring)
185NTN | RTS
186
187@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
188@ Name:
189@ printstring (111100)
190@ Description:
191@ Prints a null-terminated string from the stack.
192@ Call Stack:
193@ null-terminator (ASCII '\0')
194@ char n
195@ ...
196@ char 2
197@ char 1 <-- TOS
198@ Return Stack:
199@ <empty>
200@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
201NSSVTTTTSSN | Mark: 111100 (debug:printstring)
202SNS | DUP
203NTSSSTTTTSSSSSSSSSTN | BRZ > 00111100 00000001
204TNSS | Print character
205NSNTTTTSSN | JMP > 111100
206NSSVSSTTTTSSSSSSSSSTN | Mark: 00111100 00000001
207SNN | DROP
208NTN | RTS
209
4fba07dc
AT
210@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
211@ Name:
212@ printsignednumber (111101)
213@ Description:
214@ Prints 'number' from the stack in sign-magnitude format.
215@ Leading zeros are suppressed.
216@ Call Stack:
217@ number <-- TOS
218@ Return Stack:
219@ <empty>
220@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
221NSSVTTTTSTN | Mark: 111101 (debug:printsignednumber)
222SNS | DUP
223NSTTTTSTSN | JSR > 111010 (debug:printsign)
224NSTTTTSTTN | JSR > 111011 (debug:printmagnitude)
225NTN | RTS
226
aa1914c3
AT
227@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
228@ Name:
229@ stdlib_version (111110)
230@ Description:
231@ Returns the version of the stdlib.
232@ The version number should be a monotonically increasing integer.
233@ Call Stack:
234@ <empty> <-- TOS
235@ Return Stack:
236@ version_number <-- TOS
237@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
238NSSVTTTTTSN | Mark: 111110 (debug:printsignednumber)
239SSSTN | PUSH 1 (version)
240NTN | RTS
241
1a56830d 242#endif