From bb21580a5abba6a1e6666e9fb363f68d40f785d7 Mon Sep 17 00:00:00 2001 From: Aaron Taylor Date: Tue, 16 Jul 2019 15:36:10 -0700 Subject: [PATCH] Added slurp & spew functions to VVS stdlib. General cleanup of stdlib. --- stdlib/README.md | 21 ++++- stdlib/debug.pvvs | 13 +-- stdlib/heap.pvvs | 226 +++++++++++++++++++++++++++------------------- stdlib/math.pvvs | 8 +- stdlib/stdio.pvvs | 29 ++++-- 5 files changed, 181 insertions(+), 116 deletions(-) diff --git a/stdlib/README.md b/stdlib/README.md index 925c82c..cef4cd4 100644 --- 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 -## 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 # @@ -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) + 11101 ----- + 11110 ----- slurp (heap.pvvs) + 11111 ----- spew (heap.pvvs) 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 -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 --- a/stdlib/debug.pvvs +++ b/stdlib/debug.pvvs @@ -2,14 +2,17 @@ #define VVS_STDLIB_DEBUG @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +@ Name: +@ dumpheap (111000) @ Description: -@ This function dumps the heap from startaddr to endaddr. +@ Dumps the heap from 'startaddr' to 'endaddr'. @ Call Stack: @ endaddr @ startaddr <-- TOS @ Return Stack: @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +#include 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. -SSSSN | PUSH 0 (ptr) +SSSTN | PUSH 1 (ptr) SNT | SWAP TTS | STORE SNS | DUP -SSSSN | PUSH 0 (ptr) +SSSTN | PUSH 1 (ptr) TTT | LOAD TSST | SUBTRACT NTSSSTTTSSSSSSSSSSSN | BRZ > 00111000 00000000 -SSSSN | PUSH 0 (ptr) +SSSTN | PUSH 1 (ptr) TTT | LOAD SSSTN | PUSH 1 TSSS | ADD @@ -48,6 +51,4 @@ NSSVSSTTTSSSSSSSSSSSN | Mark: 00111000 00000000 SNN | DROP NTN | RTS -#include - #endif diff --git a/stdlib/heap.pvvs b/stdlib/heap.pvvs index 7a3ddc3..d753363 100644 --- a/stdlib/heap.pvvs +++ b/stdlib/heap.pvvs @@ -2,9 +2,10 @@ #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 @@ -13,42 +14,28 @@ @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ 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 @@ -59,8 +46,10 @@ SNN | DROP 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 @@ -69,46 +58,32 @@ NTN | RTS @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ 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 @@ -119,24 +94,25 @@ SNN | DROP 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: @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +#include 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) @@ -155,8 +131,10 @@ SNN | DROP 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 @@ -169,29 +147,19 @@ NTN | RTS @ 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 @@ -218,9 +186,11 @@ SSSSN | PUSH 0 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 @@ -230,38 +200,22 @@ NTN | RTS @ 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 @@ -271,7 +225,7 @@ NSNSSSTTTSSSSSSSSSSN | JMP > 00011100 00000000 @ 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 @@ -282,6 +236,90 @@ SNN | DROP SSSSN | PUSH 0 NTN | RTS -#include +@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +@ 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: +@ +@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +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 diff --git a/stdlib/math.pvvs b/stdlib/math.pvvs index 0df09ed..8bbe5da 100644 --- a/stdlib/math.pvvs +++ b/stdlib/math.pvvs @@ -2,8 +2,10 @@ #define VVS_STDLIB_MATH @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +@ Name: +@ random (10000) @ 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: @@ -14,8 +16,10 @@ SSSTSSN | PUSH +4 NTN | RTS @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +@ Name: +@ abs (10001) @ Description: -@ This function returns the absolute value of its argument +@ Returns the absolute value of its argument @ Call Stack: @ signed number <-- TOS @ Return Stack: diff --git a/stdlib/stdio.pvvs b/stdlib/stdio.pvvs index e0ff711..12e0ed7 100644 --- a/stdlib/stdio.pvvs +++ b/stdlib/stdio.pvvs @@ -2,8 +2,10 @@ #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 @@ -23,8 +25,10 @@ SNN | DROP 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: @@ -45,11 +49,13 @@ SNN | DROP 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: @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@ -60,10 +66,12 @@ NSTTSSSSSTN | JSR > 1000001 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: @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@ -78,13 +86,16 @@ TNSS | PUTC 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: @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +#include 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 -#include - #endif -- 2.20.1