aw / fiveforths

32-bit RISC-V Forth for microcontrollers

Hi there 👋

fiveforths's Issues

Handle incomplete word definitions

When defining a new word, if an undefined word is used in the definition, then the interpreter correctly prints a ? but it incorrectly leaves the half-defined word in memory (and HERE remains at the previously added word). I think in this case it should reset HERE to the beginning of the word (assuming it's in compile mode), whose address might be found in LATEST.

The lookup function will need to be modified to jump to a different error handler.

Enable multi-line definitions

When processing characters, a newline is replaced by a space regardless of compile/execute mode, and then process_token is entered. When the character 0x0 is found, the token size is set to 0 and ok is called because it considers the last token to have been processed.

This procedure should be changed somehow to continue processing more tokens on the next line when in compilation mode (STATE = 1).

STORE primitive is incorrect

After some testing, it appears the STORE primitive is incorrect. Its definition:

# ! ( x addr -- )       Store x at addr

Is actually doing the opposite and trying to store addr at x.

Fix handling of carriage return

The interpreter behaves well when a \n (LF) is issued, but not when a \r (CR) is sent. There is some code to handle this but it's obviously not working correctly. It also doesn't work well when a \r\n (CRLF) is sent, which I believe is the default behaviour of a few terminal programs.

TOIN should not be an address

The TOIN variable should not contain the address of the current location into the buffer, but rather the number of bytes into the buffer. That's how it works in other Forths, and this current implementation would make it difficult to use >in as intended (ex: as a counter) without first subtracting the value of TIB.

Since TOIN is used in quite a few places, it might be difficult to change this functionality without breaking something... so some tests should be written beforehand.

Add bounds checks for stacks: overflow and underflow

It is currently possible to POP from the stacks even if nothing is there (underflow), and PUSH to the stacks if it's full (overflow). This applies to the DSP and RSP stack only, since TIB already has bounds checks.

Fix backspace bug

There's a bug where typing backspace completely messes up the definition of the word being defined.

Add tests

Many tests were written during development, but they were written in RISC-V assembly and can only run in a simulator/qemu environment.

It might be better to write tests in Forth which can be uploaded through the terminal to the actual microcontroller.

Allow numbers to be added to word definitions

Numbers are added to the stack by the outer interpreter, and they can be used just fine in execute mode, but this doesn't get reflected in a colon definition. A word such as LIT (literal handler) is probably needed to force the interpreter to add the stack number to memory when it sees the lit word.. or something like that. It might need to be immediate as well.

Flash with dfu-util

I see dfu-util mentioned in TUTORIALS.md but not used in the code.

Here is example of successful flashing with the tool to "Sipeed Longan nano" board:

 % dfu-util -l                                      
dfu-util 0.11

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2021 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

Found DFU: [28e9:0189] ver=1000, devnum=12, cfg=1, intf=0, path="1-4.4", alt=1, name="@Option Bytes  /0x1FFFF800/01*016 g", serial="3CBJ"
Found DFU: [28e9:0189] ver=1000, devnum=12, cfg=1, intf=0, path="1-4.4", alt=0, name="@Internal Flash  /0x08000000/512*002Kg", serial="3CBJ"

 % dfu-util -d 28e9:0189 --alt 0 -s 0x08000000:leave -D fiveforths.bin
dfu-util 0.11

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2021 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Warning: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release
Opening DFU capable USB device...
Device ID 28e9:0189
Device DFU version 011a
Claiming USB DFU Interface...
Setting Alternate Interface #0 ...
Determining device status...
DFU state(10) = dfuERROR, status(10) = Device's firmware is corrupt. It cannot return to run-time (non-DFU) operations
Clearing status
Determining device status...
DFU state(2) = dfuIDLE, status(0) = No error condition is present
DFU mode device DFU version 011a
Device returned transfer size 2048
DfuSe interface name: "Internal Flash  "
Found GD32VF103, which reports a bad page size and count for its internal memory.
Fixed layout based on part number: page size 1024, count 128.
Downloading element to address = 0x08000000, size = 2602
Erase   	[=========================] 100%         2602 bytes
Erase    done.
Download	[=========================] 100%         2602 bytes
Download done.
File downloaded successfully
Submitting leave request...

P.S.: without --alt 0 it returns an error:

dfu-util: More than one DFU capable USB device found! Try `--list' and specify the serial number or disconnect all but one device

I can try to improve the documentation and Makefile when find how to automate arguments selection.

Fix bug when defining multiple colon words

When defining a colon word which contains other colon words, the codeword definition doesn't seem to point to the correct address. It appears to point to docol in each case, but I think it might need to point to the next memory address right after that (+4).

Example:

: dup sp@ @ ;   ok
: invert dup nand ;   ok
0 invert<??crash??>

Technically this invert should take the top stack value, duplicate it, then uses nand to bitwise AND and NOT the two identical values, thus inverting them, thus giving -1 (or 0xFFFFFFFF).

TODO goal: working version 1

This TODO's goal is to aim for an initial working version 1 which can be flash to a Longan Nano MCU. The list is unsorted and a work in progress (i.e: more items can/will be added as needed).

• Validate location of constants in Flash memory
• Validate location of variables in RAM
• Validate memory locations of stacks (and their size -- 256 Bytes each)
• Test program loading and register values in Ripes and GDB
• Add SOS register and use it as the second top of stack item instead of DSP
• Verify existing primitives for proper use of TOS and SOS registers
• Implement missing primitives:
  • :
  • ;
  • >in
  • key
  • emit
• Implement interpreter loop
• Implement terminal input buffer functions (UART)
• Implement lookup function to find a word in the dictionary
• Implement compile and execute functions

Check for printable characters

The UART should only accept printable characters between the range 0x20 and 0x7E for now.

Actually we should also allow 0x08 (backspace), 0x10 (newline) control characters. Everything else can be ignored, including 0x0D (carriage return) which would resolve #9 as well.

Add README

Add bounds check for full user dictionary

The user dictionary has limited memory space. A limit should be placed when adding words to the dictionary, perhaps with the help of the constant FORTH_SIZE.

Handle hex numbers

Currently it is not possible to input a hex number. It would be quite useful if we could enter something like 0x20000000 and store it in memory as the decimal 536870912. This would make it easier to work with memory addresses for GPIOs and other MCU hardware features.

Add support for saving and restoring RAM to Flash

Since the initial state of this Forth is extremely minimal, and there's no way to "upload" files or paste large chunks without causing a disaster, it would be nice to have the ability to save the defined colon words (from RAM) into Flash... and restore it on reboot (automatically? manually?).

Alternatively I could add support for uploading files over the UART, which would require switching to DMA for handling the input buffer, or implement interrupts for handling input.

For the moment this issue will focus on saving and restoring RAM contents to Flash.

Error build with fresh tools: extension `zicsr' required

Hello!
Thank you for this great project with opensource license! I don't know Forth, but I'm interesting in pure Assembly code examples for RISC-V boards.

I tried to build the code with the latest Devuan testing, and it failed:

 % make build BOARD=longan-nano
/usr/bin/riscv64-unknown-elf-as -g -march=rv32imac -I src/boards/longan-nano -I src/mcus/gd32vf103 -I src -o fiveforths.o fiveforths.s
src/03-interrupts.s: Assembler messages:
src/03-interrupts.s:15: Error: unrecognized opcode `csrc mstatus,0x08', extension `zicsr' required
src/03-interrupts.s:18: Error: unrecognized opcode `csrs mie,zero', extension `zicsr' required
src/03-interrupts.s:22: Error: unrecognized opcode `csrw mtvec,t0', extension `zicsr' required
make: *** [Makefile:27: fiveforths.o] Error 1

Then I modified Makefile: ARCH ?= rv32imac_zicsr, and the code compiled successfully:

 % make build BOARD=longan-nano
/usr/bin/riscv64-unknown-elf-as -g -march=rv32imac_zicsr -I src/boards/longan-nano -I src/mcus/gd32vf103 -I src -o fiveforths.o fiveforths.s
/usr/bin/riscv64-unknown-elf-ld -m elf32lriscv -T src/boards/longan-nano/linker.ld -o fiveforths.elf fiveforths.o
/usr/bin/riscv64-unknown-elf-objcopy -O binary fiveforths.elf fiveforths.bin
/usr/bin/riscv64-unknown-elf-objcopy -O ihex fiveforths.elf fiveforths.hex
/usr/bin/riscv64-unknown-elf-objdump -D -S fiveforths.elf > fiveforths.dump

Software versions:

 % dpkg -l|grep riscv
ii  binutils-riscv64-unknown-elf          2.39-8+4                                     amd64        GNU assembler, linker and binary utilities for Risc-V processors
ii  gcc-riscv64-unknown-elf               12.1.0-7+11                                  amd64        GCC cross compiler for Risc-V processors

Just FYI.