0xxxxxxx xxxxxxxx - reserved for private use by stdlib
1xxxxxxx xxxxxxxx - available for use in user programs
-## Heap ##
+## Heap and Pointers ##
- The first 256 heap addresses are reserved when using the stdlib.
+The first 16 heap addresses (`0-15`) are reserved when using the stdlib.
+
+By convention, functions which return a pointer will use the address `0` to
+represent a `NULL` pointer.
# Entry Points #
11010 ----- memrand (heap.pvvs)
11011 ----- memcmp (heap.pvvs)
11100 ----- memsrch (heap.pvvs)
+ 11101 ----- <empty>
+ 11110 ----- slurp (heap.pvvs)
+ 11111 ----- spew (heap.pvvs)
100xxx - unassigned
101xxx - unassigned
110xxx - conversion functions
00001001 xxxxxxxx - for use by 1001
...etc
-Also by convention, functions which return a pointer will use the value `0` to
-represent a `NULL` pointer.
+# Slurp and Spew #
+
+The stdlib uses heap[1] to heap[15] as registers.
+
+The `slurp` and `spew` functions facilitate this by `spew`ing the stack onto
+the heap's pseudo-registers or `slurp`ing the pseudo-registers back to the
+stack. The functions preserve order in complementary fashion.
+
+The `spew` function uses `heap[0]` for storage.
#define VVS_STDLIB_HEAP
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@ Name:
+@ memset (11000)
@ Description:
-@ This function writes pattern into the memory locations:
-@ startaddr -> startaddr+count
+@ Writes 'pattern' in memory locations 'startaddr' to 'startaddr+count'.
@ Call Stack:
@ pattern
@ startaddr
@ <empty>
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
NSSVTTSSSN | Mark: 11000 (memset)
+SSSTTN | PUSH 3
+NSTTTTTTN | JSR > 11111 (spew)
-@ Prepare the stack for computation.
-@ Addr | Contents
-@ 0 | count
-@ 1 | startaddr
-@ 2 | pattern
-
-SSSSN | PUSH 0 (ptr)
-SNT | SWAP
-TTS | STORE
-SSSTN | PUSH 1 (ptr)
-SNT | SWAP
-TTS | STORE
-SSSTSN | PUSH 2 (ptr)
-SNT | SWAP
-TTS | STORE
-
-@ Store pattern into one memory location on each pass through this loop.
+@ Store 'pattern' into one memory location on each pass through this loop.
NSSVSSSTTSSSSSSSSSSSN | Mark: 00011000 00000000
-SSSSN | PUSH 0 (ptr)
-TTT | LOAD
SSSTN | PUSH 1 (ptr)
TTT | LOAD
-TSSS | ADD
SSSTSN | PUSH 2 (ptr)
TTT | LOAD
+TSSS | ADD
+SSSTTN | PUSH 3 (ptr)
+TTT | LOAD
TTS | STORE
-@ Decrement and check for loop end condition count == 0.
-SSSSN | PUSH 0 (ptr)
+@ Decrement and check for loop end condition 'count == 0'.
+SSSTN | PUSH 1 (ptr)
TTT | LOAD
SNS | DUP
NTSSSSTTSSSSSSSSSSTN | BRZ > 00011000 00000001
SSSTN | PUSH 1
TSST | SUBTRACT
-SSSSN | PUSH 0 (ptr)
+SSSTN | PUSH 1 (ptr)
SNT | SWAP
TTS | STORE
NSNSSSTTSSSSSSSSSSSN | JMP > 00011000 00000000
NTN | RTS
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@ Name:
+@ memcpy (11001)
@ Description:
-@ This function copies count+1 words from source to destination.
+@ Copies 'count+1' words from 'source' to 'destination'.
@ Call Stack:
@ source
@ destination
@ <empty>
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
NSSVTTSSTN | Mark: 11001 (memcpy)
-
-@ Prepare the stack for computation.
-@ Addr | Contents
-@ 0 | count
-@ 1 | destination
-@ 2 | source
-
-SSSSN | PUSH 0 (ptr)
-SNT | SWAP
-TTS | STORE
-SSSTN | PUSH 1 (ptr)
-SNT | SWAP
-TTS | STORE
-SSSTSN | PUSH 2 (ptr)
-SNT | SWAP
-TTS | STORE
+SSSTTN | PUSH 3
+NSTTTTTTN | JSR > 11111 (spew)
@ Copy one word on each pass through this loop.
NSSVSSSTTSSTSSSSSSSSN | Mark: 00011001 00000000
-SSSTN | PUSH 1 (ptr)
+SSSTSN | PUSH 2 (ptr)
TTT | LOAD
-SSSSN | PUSH 0 (ptr)
+SSSTN | PUSH 1 (ptr)
TTT | LOAD
TSSS | ADD
-SSSTSN | PUSH 2 (ptr)
+SSSTTN | PUSH 3 (ptr)
TTT | LOAD
-SSSSN | PUSH 0 (ptr)
+SSSTN | PUSH 1 (ptr)
TTT | LOAD
TSSS | ADD
TTT | LOAD
TTS | STORE
@ Decrement and check for loop end conditions.
-SSSSN | PUSH 0 (ptr)
+SSSTN | PUSH 1 (ptr)
TTT | LOAD
SNS | DUP
NTSSSSTTSSTSSSSSSSTN | BRZ > 00011001 00000001
SSSTN | PUSH 1
TSST | SUBTRACT
-SSSSN | PUSH 0 (ptr)
+SSSTN | PUSH 1 (ptr)
SNT | SWAP
TTS | STORE
NSNSSSTTSSTSSSSSSSSN | JMP > 00011001 00000000
NTN | RTS
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@ Name:
+@ memrand (11010)
@ Description:
-@ This function writes random words into the memory locations:
-@ startaddr -> startaddr+count
+@ Writes random words into memory locations 'startaddr' to 'startaddr+count'.
@ Call Stack:
@ count
@ startaddr <-- TOS
@ Return Stack:
@ <empty>
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+#include <math.pvvs>
NSSVTTSTSN | Mark: 11010 (memrand)
-SSSSN | PUSH 0 (ptr)
-SNT | SWAP
-TTS | STORE
+SSSTN | PUSH 1
+NSTTTTTTN | JSR > 11111 (spew)
@ Store random word into one memory location on each pass through this loop.
NSSVSSSTTSTSSSSSSSSSN | Mark: 00011010 00000000
SNS | DUP
-SSSSN | PUSH 0 (ptr)
+SSSTN | PUSH 1 (ptr)
TTT | LOAD
TSSS | ADD
NSTTSSSSN | JSR > 10000 (random)
NTN | RTS
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@ Name:
+@ memcmp (11011)
@ Description:
-@ This function compares two blocks of memory:
+@ Compares two blocks of memory:
@ blk1ptr -> blk1ptr+count
@ -- versus --
@ blk2ptr -> blk2ptr+count
@ retvalue <-- TOS
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
NSSVTTSTTN | Mark: 11011 (memcmp)
-
-@ Prepare the stack for computation.
-@ Addr | Contents
-@ 0 | blk2ptr
-@ 1 | blk1ptr
-
-SSSSN | PUSH 0 (ptr)
-SNT | SWAP
-TTS | STORE
-SSSTN | PUSH 1 (ptr)
-SNT | SWAP
-TTS | STORE
+SSSTSN | PUSH 2
+NSTTTTTTN | JSR > 11111 (spew)
@ Compare one word on each pass through this loop.
NSSVSSSTTSTTSSSSSSSSN | Mark: 00011011 00000000
SNS | DUP
SNS | DUP
-SSSSN | PUSH 0 (ptr)
+SSSTN | PUSH 1 (ptr)
TTT | LOAD
TSSS | ADD
TTT | LOAD
SNT | SWAP
-SSSTN | PUSH 1 (ptr)
+SSTSN | PUSH 2 (ptr)
TTT | LOAD
TSSS | ADD
TTT | LOAD
NTN | RTS
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@ Name:
+@ memsrch (11100)
@ Description:
-@ This function searches the heap from address to address+count.
-@ If pattern is found, the return value is a pointer to the matching word.
+@ Searches the heap from 'address' to 'address+count'.
+@ If 'pattern' is found, the return value is a pointer to the matching word.
@ If not found, the return value is a null pointer.
@ Call Stack:
@ pattern
@ pointer <-- TOS
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
NSSVTTTSSN | Mark: 11100 (memsrch)
-
-@ Prepare the stack for computation.
-@ Stack:
-@ offset <-- TOS
-@ Addr | Contents
-@ 0 | address
-@ 1 | count
-@ 2 | pattern
-
-SSSSN | PUSH 0 (ptr)
-SNT | SWAP
-TTS | STORE
-SSSTN | PUSH 1 (ptr)
-SNT | SWAP
-TTS | STORE
-SSSTSN | PUSH 2 (ptr)
-SNT | SWAP
-TTS | STORE
+SSSTTN | PUSH 3
+NSTTTTTTN | JSR > 11111 (spew)
@ Compare one word on each pass through this loop.
NSSVSSSTTTSSSSSSSSSSN | Mark: 00011100 00000000
SNS | DUP
-SSSSN | PUSH 0 (ptr)
+SSSTN | PUSH 1 (ptr)
TTT | LOAD
TSSS | ADD
TTT | LOAD
-SSSTSN | PUSH 2 (ptr)
+SSSTTN | PUSH 3 (ptr)
TTT | LOAD
TSST | SUBTRACT
NTSSSSTTTSSSSSSSSSTN | BRZ > 00011100 00000001
SNS | DUP
-SSSTN | PUSH 1 (ptr)
+SSSTSN | PUSH 2 (ptr)
TTT | LOAD
TSST | SUBTRACT
NTSSSSTTTSSSSSSSSTSN | BRZ > 00011100 00000010
@ Found a match. Clean up and return.
NSSVSSSTTTSSSSSSSSSTN | Mark: 00011100 00000001
-SSSSN | PUSH 0 (ptr)
+SSSTN | PUSH 1 (ptr)
TTT | LOAD
TSSS | ADD
NTN | RTS
SSSSN | PUSH 0
NTN | RTS
-#include <math.pvvs>
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@ Name:
+@ slurp (11110)
+@ Description:
+@ Reads 'count' values from heap to stack in complementary order to 'spew'.
+@ Call Stack:
+@ count
+@ Return Stack:
+@ heap[count]
+@ ...
+@ heap[2]
+@ heap[1] <-- TOS
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+NSSVTTTTSN | Mark: 11110 (slurp)
+
+@ Load one word from heap on each pass.
+NSSVSSSTTTTSSSSSSSSSN | Mark: 00011110 00000000
+SNS | DUP
+TTT | LOAD
+SNT | SWAP
+
+@ Check for loop completion.
+@ As a side effect, prepare the next address.
+SSSTN | PUSH 1
+TSST | SUBTRACT
+SNS | DUP
+NTSSSSTTTTSSSSSSSSTN | BRZ > 00011110 00000001
+NSNSSSTTTTSSSSSSSSSN | JMP > 00011110 00000000
+NSSVSSSTTTTSSSSSSSSTN | Mark: 00011110 00000001
+SNN | DROP
+NTN | RTS
+
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@ Name:
+@ spew (11111)
+@ Description:
+@ Writes 'count' values from stack to heap in this order:
+@ TOS -> heap[1]
+@ TOS+1 -> heap[2]
+@ ...
+@ TOS+n -> heap[count]
+@ This is the only stdlib function which uses heap[0] for storage.
+@ Call Stack:
+@ data-words
+@ ...
+@ data-words
+@ count <-- TOS
+@ Return Stack:
+@ <empty>
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+NSSVTTTTTN | Mark: 11111 (spew)
+
+@ Create a counter in heap[0] that doubles as a destination pointer generator.
+SSSSN | PUSH 0 (ptr)
+SSSTN | PUSH 1
+TTS | STORE
+
+@ Store one word to heap on each pass.
+NSSVSSSTTTTTSSSSSSSSN | Mark: 00011111 00000000
+SNT | SWAP
+SSSSN | PUSH 0 (ptr)
+TTT | LOAD
+SNT | SWAP
+TTS | STORE
+
+@ Check for loop completion.
+SNS | DUP
+SSSSN | PUSH 0 (ptr)
+TTT | LOAD
+TSST | SUBTRACT
+NTSSSSTTTTTSSSSSSSTN | BRZ > 00011111 00000001
+
+@ Increment heap[0] if continuing.
+SSSSN | PUSH 0 (ptr)
+SNS | DUP
+TTT | LOAD
+SSSTN | PUSH 1
+TSSS | ADD
+TTS | STORE
+NSNSSSTTTTTSSSSSSSSN | JMP > 00011111 00000000
+
+@ Clean up and return.
+NSSVSSSTTTTTSSSSSSSTN | Mark: 00011111 00000001
+SNN | DROP
+NTN | RTS
#endif
#define VVS_STDLIB_STDIO
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@ Name:
+@ printstackstring (1000)
@ Description:
-@ This function prints a null-terminated string from the stack.
+@ Prints a null-terminated string from the stack.
@ Call Stack:
@ null-terminator (ASCII '\0')
@ char n
NTN | RTS
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@ Name:
+@ printheapstring (1001)
@ Description:
-@ This function prints a null-terminated string from the heap.
+@ Prints a null-terminated string from the heap.
@ Call Stack:
@ pointer to first character <-- TOS
@ Return Stack:
NTN | RTS
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@ Name:
+@ printstacknumber (1010)
@ Description:
-@ This functions prints a number from the stack in sign-magnitude format.
+@ Prints 'number' from the stack in sign-magnitude format.
@ Leading zeros are suppressed.
@ Call Stack:
-@ number to print <-- TOS
+@ number <-- TOS
@ Return Stack:
@ <empty>
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
NTN | RTS
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@ Name:
+@ printstacknumbersign (1000000)
@ Description:
-@ This functions prints the sign of a number from the stack.
+@ Prints the sign of 'number' from the stack.
@ Call Stack:
-@ number to print <-- TOS
+@ number <-- TOS
@ Return Stack:
@ <empty>
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
NTN | RTS
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@ Name:
+@ printstacknumbermagnitude (1000001)
@ Description:
-@ This functions prints the magnitude of a number from the stack.
+@ Prints the magnitude of 'number' from the stack.
@ Call Stack:
-@ number to print <-- TOS
+@ number <-- TOS
@ Return Stack:
@ <empty>
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+#include <math.pvvs>
NSSVTSSSSSTN | Mark: 1000001 (print magnitude of number from stack)
NSTTSSSTN | JSR > 10001 (absolute value)
NSTTSSSN | JSR > 1000 (print string from stack)
NTN | RTS
-#include <math.pvvs>
-
#endif