Better error handling, bounds check, bug fixes. Fixes #7, #8, #13, #14

Author: aw

README.md

@@ -21,8 +21,8 @@ Development progress has been logged regularly in the [devlogs](https://aw.githu
 
 The quickest way to get started is to download and flash one of the firmware binaries listed below:.
 
-* [fiveforths-longan-nano-lite.bin](https://github.com/aw/fiveforths/releases/download/v0.2/fiveforths-longan-nano-lite.bin) (64K Flash, 20K RAM)
-* [fiveforths-longan-nano.bin](https://github.com/aw/fiveforths/releases/download/v0.2/fiveforths-longan-nano.bin) (128K Flash, 32K RAM)
+* [fiveforths-longan-nano-lite.bin](https://github.com/aw/fiveforths/releases/download/v0.3/fiveforths-longan-nano-lite.bin) (64K Flash, 20K RAM)
+* [fiveforths-longan-nano.bin](https://github.com/aw/fiveforths/releases/download/v0.3/fiveforths-longan-nano.bin) (128K Flash, 32K RAM)
 
 See the [TUTORIALS](docs/TUTORIALS.md) for detailed download and flashing information.
 
@@ -35,8 +35,6 @@ See the [TUTORIALS](docs/TUTORIALS.md) for detailed download and flashing inform
 
 # TODO
 
-- [ ] Implement bounds checks for stacks and dictionary
-- [ ] Add example Forth code to turn it into a "real" Forth (ex: `[`, `]`, `branch`, etc)
 - [ ] Code cleanup and optimizations
 
 # Contributing
@@ -45,6 +43,17 @@ Please create a pull-request or [open an issue](https://github.com/aw/picolisp-k
 
 # Changelog
 
+## 0.3 (2023-01-19)
+
+  * Fix issue #7 - Implement bounds checks for stacks
+  * Fix issue #8 - Implement bounds checks for user dictionary
+  * Fix issue #13 - `TOIN` should not be an address
+  * Fix issue #14 - `STORE` primitive is incorrect
+  * Add better error messages
+  * Add detailed documentation in [docs](docs/)
+  * Add `djb2.c` to generate a word's hash locally
+  * Add RAM zerofill of unused dictionary space on reset
+
 ## 0.2 (2023-01-10)
 
   * Fix issue #9 - Handling of carriage return

docs/HOWTO.md

@@ -95,7 +95,7 @@ Accessing _FiveForths_ through the terminal should look similar to this:
 ```
 --- Miniterm on /dev/ttyUSB0  115200,8,N,1 ---
 --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
-FiveForths v0.2, Copyright (c) 2021~ Alexander Williams, https://a1w.ca 
+FiveForths v0.3, Copyright (c) 2021~ Alexander Williams, https://a1w.ca
 
 ```
 

docs/REFERENCE.md

@@ -34,6 +34,7 @@ Below is a list of specifications for _FiveForths_, most can be changed in the s
 * Return character newline: `\n`
 * Maximum word length: `32 characters`
 * Stack effects comments support `( x -- x )`: **yes**
+* Stack and memory overflow/underflow protection: **yes**
 * Backslash comments support `\ comment`: **yes**
 * Multiline code definitions support: **no**
 * OK message: `"   ok\n"`
@@ -167,7 +168,6 @@ The hash is a 32-bit hash with the last 8 bits (from the LSB) used for the Flags
 | FLAGS | LENGTH |      HASH        |
 +-------+--------+------------------+
  3-bits  5-bits   24-bits
-
 ```
 
 ### Other Forths

docs/TUTORIALS.md

@@ -54,8 +54,8 @@ It is possible to download a pre-built firmware binary, or build the firmware ma
 
 Download one of the firmware binaries from the [releases page](https://github.com/aw/fiveforths/releases).
 
-* [fiveforths-longan-nano-lite.bin](https://github.com/aw/fiveforths/releases/download/v0.2/fiveforths-longan-nano-lite.bin) (64K Flash, 20K RAM)
-* [fiveforths-longan-nano.bin](https://github.com/aw/fiveforths/releases/download/v0.2/fiveforths-longan-nano.bin) (128K Flash, 32K RAM)
+* [fiveforths-longan-nano-lite.bin](https://github.com/aw/fiveforths/releases/download/v0.3/fiveforths-longan-nano-lite.bin) (64K Flash, 20K RAM)
+* [fiveforths-longan-nano.bin](https://github.com/aw/fiveforths/releases/download/v0.3/fiveforths-longan-nano.bin) (128K Flash, 32K RAM)
 
 ### Build it
 
@@ -87,7 +87,7 @@ $ make
 
 Additional build options are explained in the [HOWTO](HOWTO.md) section.
 
-The firmware file is called `fiveforths.bin` and is **under 2 KBytes** as of _release v0.1_ since _January 08, 2023_.
+The firmware file is called `fiveforths.bin` and is **nearly 2.5 KBytes** as of _release v0.3_ since _January 19, 2023_.
 
 ### Flash it
 

src/01-variables-constants.s

@@ -2,7 +2,7 @@
 # Variables and constants
 ##
 
-.equ FORTH_VERSION, 2
+.equ FORTH_VERSION, 3
 
 ##
 # Memory map

src/02-macros.s

@@ -18,25 +18,27 @@
 
 # push register to top of stack and move DSP
 .macro PUSH reg
-    sw \reg, -CELL(sp)  # store the value in the register to the top of the DSP
-    addi sp, sp, -CELL  # move the DSP down by 1 cell
-.endm
+    li t0, RSP_TOP+CELL         # load address of bottom of stack + 1 CELL
+    blt sp, t0, err_overflow    # jump to error handler if stack overflow
 
-# push variable to top of stack
-.macro PUSHVAR var
-    li t0, \var         # load variable into temporary
-    sw t0, -CELL(sp)    # store the variable value to the top of the DSP
+    sw \reg, -CELL(sp)  # store the value in the register to the top of the DSP
     addi sp, sp, -CELL  # move the DSP down by 1 cell
 .endm
 
 # push register to return stack
 .macro PUSHRSP reg
+    li t0, TIB_TOP+CELL         # load address of bottom of stack + 1 CELL
+    blt s2, t0, err_overflow    # jump to error handler if stack overflow
+
     sw \reg, -CELL(s2)  # store value from register into RSP
     addi s2, s2, -CELL  # decrement RSP by 1 cell
 .endm
 
 # pop top of return stack to register
 .macro POPRSP reg
+    li t0, RSP_TOP              # load address of top of RSP
+    bge s2, t0, err_underflow   # jump to error handler if stack underflow
+
     lw \reg, 0(s2)      # load value from RSP into register
     addi s2, s2, CELL   # increment RSP by 1 cell
 .endm
@@ -67,3 +69,31 @@
     li t0, \char        # load character into temporary
     beq a0, t0, \dest   # jump to the destination if the char matches
 .endm
+
+# print a message
+.macro print_error name, size, jump
+    .balign CELL
+  err_\name :
+    la a1, msg_\name    # load string message
+    addi a2, a1, \size  # load string length
+    call uart_print     # call uart print function
+    j \jump             # jump when print returns
+.endm
+
+# restore HERE and LATEST variables
+.macro restorevars reg
+    # update HERE
+    li t0, HERE         # load HERE variable into temporary
+    sw \reg, 0(t0)      # store the address of LATEST back into HERE
+
+    # update LATEST
+    li t0, LATEST       # load LATEST variable into temporary
+    lw t1, 0(\reg)      # load LATEST variable value into temporary
+    sw t1, 0(t0)        # store LATEST word into LATEST variable
+.endm
+
+# check for stack underflow
+.macro checkunderflow stacktop
+    li t0, DSP_TOP-\stacktop    # load address of top of stack
+    bge sp, t0, err_underflow   # jump to error handler if stack underflow
+.endm

src/05-internal-functions.s

@@ -97,32 +97,24 @@ lookup_loop:
     lw t0, 4(a1)                # load the hash of the word from the X working register
 
     # check if the word is hidden
-    li t1, F_HIDDEN            # load the HIDDEN flag into temporary
-    and t1, t0, t1             # read the hidden flag bit
-    bnez t1, lookup_next       # skip the word if it's hidden
+    li t1, F_HIDDEN             # load the HIDDEN flag into temporary
+    and t1, t0, t1              # read the hidden flag bit
+    bnez t1, lookup_next        # skip the word if it's hidden
 
     # remove the 3-bit flags using a mask
-    li t1, ~FLAGS_MASK         # load the inverted 3-bit flags mask into temporary
-    and t0, t0, t1             # ignore flags when comparing the hashes
-    beq t0, a0, lookup_done    # done if the hashes match
+    li t1, ~FLAGS_MASK          # load the inverted 3-bit flags mask into temporary
+    and t0, t0, t1              # ignore flags when comparing the hashes
+    beq t0, a0, lookup_done     # done if the hashes match
 lookup_next:
-    lw a1, 0(a1)               # follow link to next word in dict
+    lw a1, 0(a1)                # follow link to next word in dict
     j lookup_loop
 lookup_error:
     # check the STATE
     li t0, STATE                # load the address of the STATE variable into temporary
     lw t0, 0(t0)                # load the current state into a temporary
-    beqz t0, error              # if in execute mode (STATE = 0), jump to error handler to reset
+    beqz t0, err_error          # if in execute mode (STATE = 0), jump to error handler to reset
 
-    # update HERE since we're in compile mode
-    li t0, HERE                 # load HERE variable into temporary
-    sw t2, 0(t0)                # store the address of LATEST back into HERE
-
-    # update LATEST since we're in compile mode
-    li t0, LATEST               # load LATEST variable into temporary
-    lw t1, 0(t2)                # load LATEST variable value into temporary
-    sw t1, 0(t0)                # store LATEST word into LATEST variable
-
-    j error                     # jump to error handler
+    restorevars t2              # restore HERE and LATEST (t2)
+    j err_error                 # jump to error handler
 lookup_done:
     ret

src/06-initialization.s

@@ -41,13 +41,29 @@ reset:
     li t0, STATE        # load STATE variable
     sw zero, 0(t0)      # initialize STATE variable (0 = execute)
 
+.balign CELL
+# reset the RAM from the last defined word
+ram_init:
+    li t0, HERE         # load HERE memory address
+    lw t0, 0(t0)        # load HERE value
+    li t1, PAD          # load PAD variable
+ram_zerofill:
+    # initialize the memory cells
+    beq t0, t1,ram_done # loop until counter (HERE) == PAD
+    sw zero, 0(t0)      # zero-fill the memory address
+    addi t0, t0, CELL   # increment counter by 1 CELL
+    j ram_zerofill      # repeat
+ram_done:
+    # continue to tib_init
+
+.balign CELL
 # reset the terminal input buffer
 tib_init:
     # initialize TOIN variable
     li t0, TIB          # load TIB memory address
     li t1, TOIN         # load TOIN variable
     li t2, TIB_TOP      # load TIB_TOP variable
-    sw t0, 0(t1)        # initialize TOIN variable to contain TIB start address
+    sw zero, 0(t1)      # initialize TOIN variable to contain zero
 tib_zerofill:
     # initialize the TIB
     beq t2, t0,tib_done # loop until TIB_TOP == TIB
@@ -57,4 +73,4 @@ tib_zerofill:
 tib_done:
     j interpreter_start # jump to the main interpreter REPL
 
-msg_boot: .ascii "FiveForths v0.2, Copyright (c) 2021~ Alexander Williams, https://a1w.ca \n\n"
+msg_boot: .ascii "FiveForths v0.3, Copyright (c) 2021~ Alexander Williams, https://a1w.ca \n\n"

src/07-error-handling.s

@@ -2,30 +2,20 @@
 # Error handling
 ##
 
-.balign CELL
-# print an error message to the UART
-error:
-    la a1, msg_error    # load string message
-    addi a2, a1, 4      # load string length
-    call uart_print     # call uart print function
-    j reset             # jump to reset the stack pointers, variables, etc before jumping to the interpreter
-
-.balign CELL
-# print an OK message to the UART
-ok:
-    la a1, msg_ok       # load string message
-    addi a2, a1, 6      # load string length
-    call uart_print     # call uart print function
-    j tib_init          # jump to reset the terminal input buffer before jumping to the interpreter
-
-.balign CELL
-# print a REBOOTING message to the UART
-reboot:
-    la a1, msg_reboot   # load string message
-    addi a2, a1, 12     # load string length
-    call uart_print     # call uart print function
-    j _start            # reboot when print returns
+print_error error, 4, reset
+print_error ok, 6, tib_init
+print_error reboot, 16, _start
+print_error tib, 14, reset
+print_error mem, 16, reset
+print_error token, 14, reset
+print_error underflow, 20, reset
+print_error overflow, 20, reset
 
 msg_error: .ascii "  ?\n"
 msg_ok: .ascii "   ok\n"
-msg_reboot: .ascii "  rebooting\n"
+msg_reboot: .ascii "   ok rebooting\n"
+msg_tib: .ascii "   ? tib full\n"
+msg_mem: .ascii "  ? memory full\n"
+msg_token: .ascii "  ? big token\n"
+msg_underflow: .ascii "  ? stack underflow\n"
+msg_overflow: .ascii "   ? stack overflow\n"