VVS stdlib changes to `random` and `spewreg`, reallocating heap[0] and [15].

diff --git a/examples/random-heap-dump/randomheap.pvvs b/examples/random-heap-dump/randomheap.pvvs
index 2cd3532..8cc142c 100644 (file)
--- a/examples/random-heap-dump/randomheap.pvvs
+++ b/examples/random-heap-dump/randomheap.pvvs
@@ -1,3 +1,8 @@
+@@ Seed the RNG
+SSSSN                                | PUSH 0 (ptr)
+SSSTTSTTTTSTSTSTTSTTSTTTTTSTTTSTTTTN | PUSH Seed value
+TTS                                  | STORE
+
 @@ Populate heap[18]-heap[29] with random values
 SSSTSTTN   | PUSH 11
 SSSTSSTSN  | PUSH 18

diff --git a/stdlib/README.md b/stdlib/README.md
index c64be4b..00d0fb5 100644 (file)
--- a/stdlib/README.md
+++ b/stdlib/README.md
@@ -19,6 +19,9 @@ following reservations:
 ## Heap and Pointers ##
 
 The first 16 heap addresses (`0-15`) are reserved when using the stdlib.
+Within that reservation, heap[0] is used by `random` and heap[15] is used
+by `spewreg`. The remaining 14 locations, heap[1]-heap[14] are used as
+general-purpose registers.
 
 By convention, functions which return a pointer will use the address `0` to
 represent a `NULL` pointer.
@@ -66,13 +69,3 @@ private label space associated with it, formed as follows:
     00001000 xxxxxxxx - for use by 1000
     00001001 xxxxxxxx - for use by 1001
     ...etc
-
-# Slurp and Spew #
-
-The stdlib uses heap[1] to heap[15] as registers.
-
-The `slurpreg` and `spewreg` 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 `spewreg` function uses `heap[0]` for storage.

diff --git a/stdlib/heap.pvvs b/stdlib/heap.pvvs
index 3fa352c..69ed992 100644 (file)
--- a/stdlib/heap.pvvs
+++ b/stdlib/heap.pvvs
@@ -277,7 +277,10 @@ NTN                     | RTS
 @     TOS+1 -> heap[2]
 @     ...
 @     TOS+n -> heap[count]
-@   This is the only stdlib function which uses heap[0] for storage.
+@   This function uses heap[15] for temporary storage, thus limiting the total
+@   registers to 14 since heap[0] is reserved. Since this function populates
+@   the registers, encoding the value here seems a natural location to document
+@   the limit. TODO: Should this be turned into a CPP define?
 @ Call Stack:
 @   data-words
 @   ...
@@ -288,28 +291,28 @@ NTN                     | RTS
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 NSSVTSSSSSTN            | Mark: 1000001 (spewreg)
 
-@ Create a counter in heap[0] that doubles as a destination pointer generator.
-SSSSN                   | PUSH 0 (ptr)
+@ Create a counter in heap[15] that doubles as a destination pointer generator.
+SSSTTTTN                | PUSH 15 (ptr)
 SSSTN                   | PUSH 1
 TTS                     | STORE
 
 @ Store one word to heap on each pass.
 NSSVSTSSSSSTSSSSSSSSN   | Mark: 01000001 00000000
 SNT                     | SWAP
-SSSSN                   | PUSH 0 (ptr)
+SSSTTTTN                | PUSH 15 (ptr)
 TTT                     | LOAD
 SNT                     | SWAP
 TTS                     | STORE
 
 @ Check for loop completion.
 SNS                     | DUP
-SSSSN                   | PUSH 0 (ptr)
+SSSTTTTN                | PUSH 15 (ptr)
 TTT                     | LOAD
 TSST                    | SUBTRACT
 NTSSTSSSSSTSSSSSSSTN    | BRZ > 01000001 00000001
 
-@ Increment heap[0] if continuing.
-SSSSN                   | PUSH 0 (ptr)
+@ Increment heap[15] if continuing.
+SSSTTTTN                | PUSH 15 (ptr)
 SNS                     | DUP
 TTT                     | LOAD
 SSSTN                   | PUSH 1