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

msp430.asm.forth

This is itself a Forth interpreter and is used to do the conversion into an assembler file for the MSP430.

msp430.asm.h2forth

This tool can be used to convert C header to a Forth file. Each #define will be turned into a CONSTANT. It’s main purpose is to get access to the peripheral an bit definitions from the TI header files.

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 for NEXT.

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 and VALUE 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 symbols vector_NN which have to be manually added to the interrupt vector table. Interrupt declarations end with the word END-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 in CODE words. It adds the given word as dependency so that it is also cross compiled. This is useful when the assembler in the CODE 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 named ZERO 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).