Forth Cross Compiler¶
The package also includes a limited Forth like language cross compiler.
Warning
This feature is under development.
Attention
Documentation is incomplete. Also reading the source is recommended.
Traditional methods to use Forth on a different target system involve meta-compilers and the assembler for the target is often implemented in Forth itself. Not this one.
The idea of this tool chain is to cross compile Forth into assembler for the MSP430 and then use the normal assembler and linker. This means that other assembler (or C modules etc.) can be combined in one program.
led.forth -> led.S -> led.o4 --+--> led.titext
intvec.S -> intvec.o4 --/
startup.S -> startup.o4 --/
Available Words¶
A list of supported words is available here:
Availability of words depends on their definition. There are words that can
only be executed on the host. These words can not be used within definitions
that are cross compiled. In contrast, CODE
words are only allowed within
definitions that are cross compiled. Normal definitions using :
can run on
host and target, unless they depend on words described before. In that case the
restrictions of that type applies.
Command line tools¶
Cross compilation¶
The file given to msp430.asm.forth
is executed on the host.
Only words used in the program for the target are translated. This makes the use of libraries simple - it does not matter how many words are defined or used by the program on the host.
There are three dictionaries in the host interpreter.
- built-in name space: The words here are implemented in Python (the language the host interpreter is written in). These can not be cross compiled (unless they are provided in the target dictionary).
- normal name space: normal
:
/;
definitions go here. The words here can be used on the host as well as on the target. - target name space:
CODE
definitions go here. These words can be referenced by the host but they can not be executed (they won’t do the expected).
All three dictionaries are available to the host but cross compiled words must exist in one of the later two.
- Cross compilation of normal words (
:
) - The words are already translated into a list of references by the host interpreter. They can be output 1:1 as list of words for the target (exceptions are branch distances, they are multiplied by two).
- Cross compilation of
CODE
words These words are executed to get the cross compilation. So each
CODE
word simply outputs assembler code. Forth words must include the code forNEXT
.This allows that
CODE
word definitions can also be used to generate helper functions for other assembler parts.- Cross compilation of
INTERRUPT
words - A special assembler start code is included and the exit functionality is handled specially. The function itself is translated the same way a normal word is.
MSP430 specific features¶
VARIABLE
andVALUE
are supported, they allocate a 16 bit variable in RAM (.data
segment).- The word
INTERRUPT
defines a new interrupt function. It takes the vector number from the stack and it expects that a function name follows. It creates symbolsvector_NN
which have to be manually added to the interrupt vector table. Interrupt declarations end with the wordEND-INTERRUPT
. - Words defined using
CODE
/END-CODE
are executed when cross compiling. They are expected to write out MSP430 assembler. INCLUDE
loads and executes the given file. There is a search path that can be influenced with the-I
command line option. Some files are built-in, e.g.core.forth
is part of the package.- Escapes are decoded in strings. e.g.
." \n"
outputs a newline. - The
DEPENDS-ON
word can be used inCODE
words. It adds the given word as dependency so that it is also cross compiled. This is useful when the assembler in theCODE
words wants to use some shared code.
Internals¶
- SP is used as data stack.
- Interrupts and other asm/C functions called so then use the data stack.
- The return stack and instruction pointers are also kept in registers. All other registers can be used in Forth words (see generated assembler for register usage).
Caution
There is no stack depth checking implemented. Not maintaining the stack balance usually ends up in executing random parts or the program (A.K.A. “crash”).
Limitations¶
The current language is not quite Forth. Some important words such as
DOES>
are missing.
- Not ANS Forth compliant.
- The Forth interpreter only reads in words. There is no access to the
characters of the source file and whitespace and newlines are discarded. So
the strings
." Hello World"
and." Hello World"
are identical. Some words such as."
partially emulate byte wise access by processing each word by character (that’s why the closing"
is detected in the previous examples). \
Comments are not supported due to the limitation discussed above.*
,/
,/MOD
are currently not available on the target.CREATE
,ALLOT
have limited functionality.ERASE
was namedZERO
due to a naming conflict with a bit of the MSP430 Flash module.- No double precision math.
- Input/output functions are missing.
- There are more…
Thanks¶
A number of core Forth words that are implemented in Forth itself are taken
from JonesForth (Licensed as Public Domain) which is a well documented
experimental Forth for x386 computers (used in
msp430/asm/forth/__init__.forth
).