mikaelpatel / arduino-fvm

Byte Token Threaded Forth Virtual Machine (FVM) for Arduino

Arduino-FVM

This library provides a token threaded Forth kernel that may be embedded in Arduino sketches. The kernel can be used as a debug shell or even full scale Forth applications.

The Forth Virtual Machine allows multi-tasking which makes it easy to integrate with the Arduino core library functions. Context switch to and from the virtual machine is as low as 8 us (halt) and 10 us (yield/branch).

A code generator, token compiler, example sketch is available. Forth declarations are translated to the Forth Virtual Machine instruction set and dictionary format. The token compiler is also an excellent example of mixing forth, C/C++ and Arduino library functions in the same sketch.

The Forth Virtual Machine (FVM) with 130 instructions is approx. 5.4 Kbyte without kernel dictionary table and strings. This adds approx. 1 Kbyte. The instruction level trace adds an additional 500 bytes. Many of the kernel instructions are defined in both C++ and FVM instructions. This allows tailoring for speed and/or size.

Tokens

The Forth Virtual Machine is byte token threaded. Most kernel and application tokens are a single byte. A prefix token is used to extend beyond 256 tokens. A total of 512 tokens are allowed; 0..255 are kernel tokens and 256..511 are application tokens. Kernel tokens are operations codes. These can be C++ code and/or threaded code (in FVM.cpp). The application tokens are always threaded code.

Kernel tokens 0..127 are direct operation codes while tokens 128..255 require a prefix token (OP_KERNEL). Application tokens 256..383 (-1..-128) are direct nested by the kernel. The token value are the one-complement index to threaded code in a table in program memory.

Application tokens 384..511 require a token prefix (OP_CALL) to the mapped values 0..127 which are the index to threaded code in a table in data memory (i.e. token minus 384).

Optimizations

The token threading inner interpreter uses several optimizations to reduce calls, i.e. return stack push and pop of return addresses.

The first optimization, the token mapping (-1..-128) allows the inner interpreter to directly handle calls of threaded code. The inner interpreter will perform the nesting.

The second optimization, tail call reduction, allows the inner interpreter to perform a jump to threaded code instead of call when the succeeding operation is EXIT. This reduces return stack depth, pushing and poping return address. The optimization is also used for prefix operations (OP_KERNEL and OP_CALL).

Install

Download and unzip the Arduino-FVM library into your sketchbook libraries directory. Rename from Arduino-FVM-master to FVM.

The FVM library and examples should be found in the Arduino IDE File>Examples menu.

arduino-fvm's Issues

Missing words

This issue is a list of missing words (Forth94 Core).

' NAME ( -- xt )
['] NAME ( -- xt )
unloop ( -- )
*/mod ( n1 n2 n3 -- n4 n5 )
2! ( x1 x2 a-addr -- )
2@ ( a-addr -- x1 x2 )
2>r ( x1 x2 -- )
2r> ( -- x1 x2 )
2r@ ( -- x1 x2 )
cell+ ( a-addr1 -- a-addr2 )
count ( c-addr1 -- c-addr2 u )
c>s ( c-char -- n )
fill ( c-addr u char -- )
fm/mod ( d1 n1 -- n2 n3 )
m* ( n1 n2 -- d )
um* ( u1 u2 -- ud )
um/mod ( ud u1 -- u2 u3 )
scan => word ( char -- )
compile NAME => postpone NAME 
lookup => find ( c-addr -- c-addr 0 | xt 1 | xt -1 )
>number ( ... )
:noname ( -- xt )
marker NAME ( -- )
value NAME ( x -- )
[compile] NAME 

Allow more than 128 kernel words

The current token mapping allows for at most 128 kernel and 128 application words. Byte positive values (0..127) are for kernel implementation and negative (-128..-1) for application.

Add multi-tasking exemple sketch(es)

Add support for tail call

Performance optimization: jump to function instead of call, avoid exit to exit return. See also https://en.wikipedia.org/wiki/Tail_call.

Add token compiler

Compile forth statements to virtual machine instructions (in C++).

Allow multi-tasking on scan/interpret

Add template task struct with parameterized stack size

Add pulseIn and pulseOut

Minor changes needed for Arduino Nano Every

Arduino have defined a new architecture, megaavr, for the ATmega4809 chip on this board.
There are some minor code changes needed to make it work. Patch available.

Add callback on illegal token/operation code

The VM is byte coded and allows for 256 tokens. The inner interpreter uses signed byte to determine if the token is executed direct (C++) or threaded call. To extend two special tokens are used. These allow the token value to exceed -128..127.

Kernel tokens are 0..127 direct, 128..255 extended.
User tokens are 256..383 direct (mapped to -1..-128), 384..511 extended.

The token space is not continues. There exists illegal tokens that needs to be captured.

What license does this project use?

This project looks like it could be useful - what license are you using?

Add optional support for SPI

Use standard naming of kernel words

http://forth-standard.org/standard/alpha

Add support for print of string literals (in PROGMEM)

Add local echo

Allow the scanner to be configured to echo all characters read during the parsing of a word.

Compiler failure in Arduino IDE 1.8.12 (current)

/home/ga/Arduino/sketches/libraries/FVM/src/FVM.cpp: In function 'int8_t fetch_byte(FVM::code_P)':
/home/ga/Arduino/sketches/libraries/FVM/src/FVM.cpp:105:31: internal compiler error: in type_hash_canon, at tree.c:7158
if (ip < (FVM::code_P) FVM::CODE_P_MAX)
^~~~~~~~~~
Please submit a full bug report,

The bug has been logged with GCC: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=94437
In the meantime, I have a patch available to work around it.

Add token compiler generated code

Use the Compiler to generate code for some of the example sketches, i.e. Blink.

The screenshots have broken links

The screenshots in the README have broken links.

Add support for do/loop/+loop/leave/i/j

Arduino Library integration example

Allow threaded code in SRAM and/or EEPROM

The AVR is a Harvard Architecture with separate memory spaces (SRAM, EEMEM, PROGMEM). To allows threaded code in all memory spaces a synthetic unified address spaces is needed. This will impose a run-time penalty on the inner interpreter and any operation that access the instruction pointer, i.e. branch, literals, etc.

Consider symmetry in context switch

tos is pushed and poped from parameter stack on context switch. ip is not, it is stored in the context struct, but should for symmetry be also pushed and poped from the return stack.

Allow call to C/C++ functions

Add virtual machine instruction to allow call of C/C++ function. Use same structure as for CREATE-DOES>, VARIABLE and CONSTANT.

Add forth code for demo sketch (and use token compiler)

Support SAM/SAMD based Arduino boards

Support 32-bit MCU based on ARM core such as Arduino Due. These have the advantage of much more memory and allow symmetrical memory model (i.e. data structures in RAM).

Add optional support for TWI