Added slurp & spew functions to VVS stdlib.

General cleanup of stdlib.

diff --git a/stdlib/README.md b/stdlib/README.md
index 925c82c..cef4cd4 100644 (file)
--- a/stdlib/README.md
+++ b/stdlib/README.md
@@ -16,9 +16,12 @@ following reservations:
     0xxxxxxx xxxxxxxx - reserved for private use by stdlib
     1xxxxxxx xxxxxxxx - available for use in user programs
 
     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 #
 
 
 # Entry Points #
 


@@ -39,6 +42,9 @@ header comment for each function to learn the call and return stack.
           11010 ----- memrand                       (heap.pvvs)
           11011 ----- memcmp                        (heap.pvvs)
           11100 ----- memsrch                       (heap.pvvs)
           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
          100xxx - unassigned
          101xxx - unassigned
          110xxx - conversion functions


@@ -57,5 +63,12 @@ private label space associated with it, formed as follows:
     00001001 xxxxxxxx - for use by 1001
     ...etc
 
     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.

diff --git a/stdlib/debug.pvvs b/stdlib/debug.pvvs
index db61a96..5261984 100644 (file)
--- a/stdlib/debug.pvvs
+++ b/stdlib/debug.pvvs
@@ -2,14 +2,17 @@
 #define VVS_STDLIB_DEBUG
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 #define VVS_STDLIB_DEBUG
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+@ Name:
+@   dumpheap (111000)

 @ Description:
 @ Description:

-@   This function dumps the heap from startaddr to endaddr.
+@   Dumps the heap from 'startaddr' to 'endaddr'.

 @ Call Stack:
 @   endaddr
 @   startaddr  <-- TOS
 @ Return Stack:
 @   <empty>
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 @ Call Stack:
 @   endaddr
 @   startaddr  <-- TOS
 @ Return Stack:
 @   <empty>
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+#include <stdio.pvvs>

 NSSVTTTSSSN              | Mark: 111000 (dump heap)
 
 @ Prepare a numeric address and value on the stack
 NSSVTTTSSSN              | Mark: 111000 (dump heap)
 
 @ Prepare a numeric address and value on the stack


@@ -29,15 +32,15 @@ SSSTSTSN                 | PUSH ASCII '\n'
 TNSS                     | PUTC
 
 @ Figure out if the loop is complete.
 TNSS                     | PUTC
 
 @ Figure out if the loop is complete.

-SSSSN                    | PUSH 0 (ptr)
+SSSTN                    | PUSH 1 (ptr)

 SNT                      | SWAP
 TTS                      | STORE
 SNS                      | DUP
 SNT                      | SWAP
 TTS                      | STORE
 SNS                      | DUP

-SSSSN                    | PUSH 0 (ptr)
+SSSTN                    | PUSH 1 (ptr)

 TTT                      | LOAD
 TSST                     | SUBTRACT
 NTSSSTTTSSSSSSSSSSSN     | BRZ > 00111000 00000000
 TTT                      | LOAD
 TSST                     | SUBTRACT
 NTSSSTTTSSSSSSSSSSSN     | BRZ > 00111000 00000000

-SSSSN                    | PUSH 0 (ptr)
+SSSTN                    | PUSH 1 (ptr)

 TTT                      | LOAD
 SSSTN                    | PUSH 1
 TSSS                     | ADD
 TTT                      | LOAD
 SSSTN                    | PUSH 1
 TSSS                     | ADD


@@ -48,6 +51,4 @@ NSSVSSTTTSSSSSSSSSSSN    | Mark: 00111000 00000000
 SNN                      | DROP
 NTN                      | RTS
 
 SNN                      | DROP
 NTN                      | RTS
 

-#include <stdio.pvvs>
-

 #endif
 #endif

diff --git a/stdlib/heap.pvvs b/stdlib/heap.pvvs
index 7a3ddc3..d753363 100644 (file)
--- a/stdlib/heap.pvvs
+++ b/stdlib/heap.pvvs
@@ -2,9 +2,10 @@
 #define VVS_STDLIB_HEAP
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 #define VVS_STDLIB_HEAP
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+@ Name:
+@   memset (11000)

 @ Description:
 @ 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
 @ Call Stack:
 @   pattern
 @   startaddr


@@ -13,42 +14,28 @@
 @   <empty>
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 NSSVTTSSSN              | Mark: 11000 (memset)
 @   <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
 NSSVSSSTTSSSSSSSSSSSN   | Mark: 00011000 00000000

-SSSSN                   | PUSH 0 (ptr)
-TTT                     | LOAD

 SSSTN                   | PUSH 1 (ptr)
 TTT                     | LOAD
 SSSTN                   | PUSH 1 (ptr)
 TTT                     | LOAD

-TSSS                    | ADD

 SSSTSN                  | PUSH 2 (ptr)
 TTT                     | LOAD
 SSSTSN                  | PUSH 2 (ptr)
 TTT                     | LOAD

+TSSS                    | ADD
+SSSTTN                  | PUSH 3 (ptr)
+TTT                     | LOAD

 TTS                     | STORE
 
 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
 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
 SNT                     | SWAP
 TTS                     | STORE
 NSNSSSTTSSSSSSSSSSSN    | JMP > 00011000 00000000


@@ -59,8 +46,10 @@ SNN                     | DROP
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+@ Name:
+@   memcpy (11001)

 @ Description:
 @ Description:

-@   This function copies count+1 words from source to destination.
+@   Copies 'count+1' words from 'source' to 'destination'.

 @ Call Stack:
 @   source
 @   destination
 @ Call Stack:
 @   source
 @   destination


@@ -69,46 +58,32 @@ NTN                     | RTS
 @   <empty>
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 NSSVTTSSTN              | Mark: 11001 (memcpy)
 @   <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
 
 @ Copy one word on each pass through this loop.
 NSSVSSSTTSSTSSSSSSSSN   | Mark: 00011001 00000000

-SSSTN                   | PUSH 1 (ptr)
+SSSTSN                  | PUSH 2 (ptr)

 TTT                     | LOAD
 TTT                     | LOAD

-SSSSN                   | PUSH 0 (ptr)
+SSSTN                   | PUSH 1 (ptr)

 TTT                     | LOAD
 TSSS                    | ADD
 TTT                     | LOAD
 TSSS                    | ADD

-SSSTSN                  | PUSH 2 (ptr)
+SSSTTN                  | PUSH 3 (ptr)

 TTT                     | LOAD
 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.
 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
 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
 SNT                     | SWAP
 TTS                     | STORE
 NSNSSSTTSSTSSSSSSSSN    | JMP > 00011001 00000000


@@ -119,24 +94,25 @@ SNN                     | DROP
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+@ Name:
+@   memrand (11010)

 @ Description:
 @ 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>
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 @ Call Stack:
 @   count
 @   startaddr  <-- TOS
 @ Return Stack:
 @   <empty>
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+#include <math.pvvs>

 NSSVTTSTSN              | Mark: 11010 (memrand)
 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
 
 @ 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)
 TTT                     | LOAD
 TSSS                    | ADD
 NSTTSSSSN               | JSR > 10000 (random)


@@ -155,8 +131,10 @@ SNN                     | DROP
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+@ Name:
+@   memcmp (11011)

 @ Description:
 @ Description:

-@   This function compares two blocks of memory:
+@   Compares two blocks of memory:

 @     blk1ptr -> blk1ptr+count
 @       -- versus --
 @     blk2ptr -> blk2ptr+count
 @     blk1ptr -> blk1ptr+count
 @       -- versus --
 @     blk2ptr -> blk2ptr+count


@@ -169,29 +147,19 @@ NTN                     | RTS
 @   retvalue <-- TOS
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 NSSVTTSTTN              | Mark: 11011 (memcmp)
 @   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
 
 @ 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
 TTT                     | LOAD
 TSSS                    | ADD
 TTT                     | LOAD
 SNT                     | SWAP

-SSSTN                   | PUSH 1 (ptr)
+SSTSN                   | PUSH 2 (ptr)

 TTT                     | LOAD
 TSSS                    | ADD
 TTT                     | LOAD
 TTT                     | LOAD
 TSSS                    | ADD
 TTT                     | LOAD


@@ -218,9 +186,11 @@ SSSSN                   | PUSH 0
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+@ Name:
+@   memsrch (11100)

 @ Description:
 @ 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
 @   If not found, the return value is a null pointer.
 @ Call Stack:
 @   pattern


@@ -230,38 +200,22 @@ NTN                     | RTS
 @   pointer <-- TOS
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 NSSVTTTSSN              | Mark: 11100 (memsrch)
 @   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
 
 @ 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
 TTT                     | LOAD
 TSSS                    | ADD
 TTT                     | LOAD

-SSSTSN                  | PUSH 2 (ptr)
+SSSTTN                  | PUSH 3 (ptr)

 TTT                     | LOAD
 TSST                    | SUBTRACT
 NTSSSSTTTSSSSSSSSSTN    | BRZ > 00011100 00000001
 SNS                     | DUP
 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
 TTT                     | LOAD
 TSST                    | SUBTRACT
 NTSSSSTTTSSSSSSSSTSN    | BRZ > 00011100 00000010


@@ -271,7 +225,7 @@ NSNSSSTTTSSSSSSSSSSN    | JMP > 00011100 00000000
 
 @ Found a match. Clean up and return.
 NSSVSSSTTTSSSSSSSSSTN   | Mark: 00011100 00000001
 
 @ 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
 TTT                     | LOAD
 TSSS                    | ADD
 NTN                     | RTS


@@ -282,6 +236,90 @@ SNN                     | DROP
 SSSSN                   | PUSH 0
 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
 
 #endif

diff --git a/stdlib/math.pvvs b/stdlib/math.pvvs
index 0df09ed..8bbe5da 100644 (file)
--- a/stdlib/math.pvvs
+++ b/stdlib/math.pvvs
@@ -2,8 +2,10 @@
 #define VVS_STDLIB_MATH
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 #define VVS_STDLIB_MATH
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+@ Name:
+@   random (10000)

 @ Description:
 @ Description:

-@   This function returns a random IEEE-vetted number per RFC 1149.5.
+@   Returns a random IEEE-vetted number per RFC 1149.5.

 @ Call Stack:
 @   empty
 @ Return Stack:
 @ Call Stack:
 @   empty
 @ Return Stack:


@@ -14,8 +16,10 @@ SSSTSSN                 | PUSH +4
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+@ Name:
+@   abs (10001)

 @ Description:
 @ Description:

-@   This function returns the absolute value of its argument
+@   Returns the absolute value of its argument

 @ Call Stack:
 @   signed number  <-- TOS
 @ Return Stack:
 @ Call Stack:
 @   signed number  <-- TOS
 @ Return Stack:

diff --git a/stdlib/stdio.pvvs b/stdlib/stdio.pvvs
index e0ff711..12e0ed7 100644 (file)
--- a/stdlib/stdio.pvvs
+++ b/stdlib/stdio.pvvs
@@ -2,8 +2,10 @@
 #define VVS_STDLIB_STDIO
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 #define VVS_STDLIB_STDIO
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+@ Name:
+@   printstackstring (1000)

 @ Description:
 @ 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
 @ Call Stack:
 @   null-terminator (ASCII '\0')
 @   char n


@@ -23,8 +25,10 @@ SNN                     | DROP
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+@ Name:
+@   printheapstring (1001)

 @ Description:
 @ 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:
 @ Call Stack:
 @   pointer to first character  <-- TOS
 @ Return Stack:


@@ -45,11 +49,13 @@ SNN                     | DROP
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+@ Name:
+@   printstacknumber (1010)

 @ Description:
 @ 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:
 @   Leading zeros are suppressed.
 @ Call Stack:

-@   number to print  <-- TOS
+@   number  <-- TOS

 @ Return Stack:
 @   <empty>
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 @ Return Stack:
 @   <empty>
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@


@@ -60,10 +66,12 @@ NSTTSSSSSTN             | JSR > 1000001
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+@ Name:
+@   printstacknumbersign (1000000)

 @ Description:
 @ Description:

-@   This functions prints the sign of a number from the stack.
+@   Prints the sign of 'number' from the stack.

 @ Call Stack:
 @ Call Stack:

-@   number to print  <-- TOS
+@   number  <-- TOS

 @ Return Stack:
 @   <empty>
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 @ Return Stack:
 @   <empty>
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@


@@ -78,13 +86,16 @@ TNSS                    | PUTC
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 NTN                     | RTS
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+@ Name:
+@   printstacknumbermagnitude (1000001)

 @ Description:
 @ Description:

-@   This functions prints the magnitude of a number from the stack.
+@   Prints the magnitude of 'number' from the stack.

 @ Call Stack:
 @ Call Stack:

-@   number to print  <-- TOS
+@   number  <-- TOS

 @ Return Stack:
 @   <empty>
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 @ Return Stack:
 @   <empty>
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

+#include <math.pvvs>

 NSSVTSSSSSTN            | Mark: 1000001 (print magnitude of number from stack)
 NSTTSSSTN               | JSR > 10001 (absolute value)
 
 NSSVTSSSSSTN            | Mark: 1000001 (print magnitude of number from stack)
 NSTTSSSTN               | JSR > 10001 (absolute value)
 


@@ -115,6 +126,4 @@ SNN                     | DROP
 NSTTSSSN                | JSR > 1000 (print string from stack)
 NTN                     | RTS
 
 NSTTSSSN                | JSR > 1000 (print string from stack)
 NTN                     | RTS
 

-#include <math.pvvs>
-

 #endif
 #endif