Standard Wordlists

Forth 2012

amforth implements most or all words from many Forth 2012 word sets. Most words are already included in the standard setup, others are loadable from files in the lib/forth2012 directory. A floating point library is available from the community repository. Words from the word set FILE-ACCESS are dropped completely. The others are at least partially implemented.

Core and Core EXT

All words from the CORE word set are available. CORE EXT drops the (deprecated) words C", CONVERT, EXPECT, SPAN and ROLL.

Loop counters are checked on signed compares.

Number Prefixes
The number base can be specified by prepending the $, # or % signs. Single characters such as ‘a’ are supported via a loadable module.
Defer and IS
defer gives the possibility of vectored execution. Amforth has 3 different kind of such vectors, varying in how they are stored: EEPROM, RAM or the USER area. The EEPROM makes it possible to save the settings permanently, the RAM enables frequent changes. Finally the user area is for multitasking.
Buffer:
The buffer allocates a named memory (RAM) region. It is superior to the usual create foo xx allot since amforth has a non-unified memory model and the code snippet does not the same as an unified memory model forth (with the dictionary being at the same memory as the allot command works).

Block

Amforth has almost complete block support to work with the flash memory and I2C eeprom devices.

To work with different backends, a layered design is used. The low level hardware access words load-buffer and save-buffer are deferred words that are called with a RAM buffer location (addr/len pair) and the block number. All thay have to do is to transfer the buffer content from/to the backend storage. The highlevel words from the BLOCK wordset do the buffer management and provide the user visible API.

Double Number

Double cell numbers work as expected. Not all words are implemented. Entering them directly using the dot- notation work for dots at the end of the number, not if the dot is somewhere within it.

Exception

Exceptions are fully supported. The words ABORT and ABORT" use them internally.

The implementation is based upon a variable HANDLER which holds the current return stack pointer position. This variable is a USER variable.

Facility

The basic system uses the KEY? and EMIT? words as deferred words in the USER area.

The word MS is implemented with the word 1MS that busy waits almost exactly 1 millisecond. The calculation is based upon the frequency specified at compile time. There are variants which are multitasking friendly but less accurate.

The words EKEY and EKEY>CHAR are not implemented.

To control a VT100 terminal the words AT-XY and PAGE are written in forth code. They emit the ANSI control codes according to the VT100 terminal codes.

File Access

amforth does not have filesystem support. It does not contain any words from this word set.

Floating Point

amforth has a loadable floating point library. It contains the basic words to deal with single precision floats. The floats are managed on the standard data stack. After loading the library floats can be entered directly at the command prompt. Some speed sensitive words are available as assembly code as well.

Locals

The locals support offers a single local value with the name X. It can easily expanded to support more by the user.

Memory Allocation

amforth does not support the words from the memory allocation word set.

Programming Tools

Variants of the words .S, ? and DUMP are implemented or can easily be done. The word SEE is available as well.

STATE works as specified.

The word WORDS does not sort the word list and does not take care of screen sizes.

The words ;CODE and ASSEMBLER are not supported. amforth has a loadable assembler which can be used with the words CODE and END-CODE.

The control stack commands CS-ROLL and CS-PICK are not implemented. The compiler words operate with the more traditional MARK / RESOLVE word pairs.

FORGET is not implemented since it would be nearly impossible to reset the search order word list with reasonable efforts. The better way is using MARKER from the library.

An EDITOR is not implemented.

[IF], [ELSE] and [THEN] are not implemented.

n>r and nr>
Fully supported
Traverse-wordlist
Iterating over a wordlist works. The name>xy words are supported.

Word Lists and Search Order

Amforth supports the ANS Search Order word list. A word list consist of a linked list of words in the dictionary. There are no limits on the number of word lists defined. Only the length of the active search order is limited: There can be up to 8 entries at any given moment. This limit can be changed at compile time in the application definition file.

Internally the word list identifier is the address where the word list start address is stored in the EEPROM. Creating a new word list means to allocate a new EEPROM cell. Since the ANS standard does not give named word list there is library code available that implements the old fashioned vocabulary.

Strings

All words from the strings word set are supported.

Amforth

COLD

The startup code is in the file cold.asm. It gets called directly from the MCU reset vector.

This assembly part of the startup code creates the basic runtime environment to start the virtual forth machine. It sets up the stack pointers and the user pointer and places the forth instruction pointer on the word WARM. Then it boots the forth virtual machine by jumping to the inner interpreter.

The start addresses of the stacks are placed to the user area for later use as well.

WARM

The word WARM is the high level part of the forth VM initialization. When called from within forth it is the equivalent to a RESET. WARM initializes the PAUSE deferred word to do nothing, calls the application defined TURNKEY action and finally hands over to QUIT.

TURNKEY

The turnkey is a EEPROM deferred word that points to an application specific startup word.

Its main task is to initialize the character IO to enable the forth interpreter to interact with the command prompt. The examples shipped with amforth do this by “opening” the serial port, switching to decimal number conversion and setting up the character IO deferred words (KEY, EMIT etc).

QUIT

QUIT initializes both data and return stack pointers by reading them from the user area and enters the traditional ACCEPT – INTERPRET loop that never ends. It provides the topmost exception catcher as well. Depending on the exception thrown, it prints an error message and restarts itself.

MCU Access

amforth provides wrapper words for the micro controller instructions SLEEP and WDR (watch dog reset). To work properly, the MCU needs more configuration. amforth itself does not call these words.

Assembler

Lubos Pekny has written an AVR8 assembler for amforth. To support it, amforth provides the two words CODE and END-CODE. The first creates a dictionary entry and sets the code field to the data filed address. The interpreter will thus jump directly into the data field assuming some machine code there. The word END-CODE places a JUMP NEXT into the data field. This finishes the machine instruction execution and jumps back to the forth interpreter.

Memories

Atmega micro controller have three different types of memory. RAM, EEPROM and Flash. The words @ and ! work on the RAM address space (which includes IO Ports and the CPU register), the words @e and !e operate on the EEPROM and @i and !i deal with the flash memory. All these words transfer one cell (2 bytes) between the memory and the data stack. The address is always the native address of the target storage: byte-based for EEPROM and RAM, word-based for flash. Therefore the flash addresses 64 KWords or 128 KBytes address space.

External RAM shares the normal RAM address space after initialization (which can be done in the turnkey action). It is accessible without further changes.

For RAM only there is the special word pair c@/c! which operate with the lower half of a stack cell. The upper byte is either ignored or set to 0 (zero).

All other types of external memory need special handling, which may be masked with the block word set.

Input Output

amforth uses character terminal IO. A serial console is used. All IO is based upon the standard words EMIT/EMIT? and KEY/KEY?. Additionally the word /KEY is used to signal the sender to stop. All these words are deferred words in the USER area and can be changed with the IS command.

The predefined words use an interrupt driven IO with a buffer for input and output. They do not implement a handshake procedure (XON/XOFF or CTS/RTS). The default terminal device is selected at compile time.

These basic words include a call to the PAUSE command to enable the use of multitasking.

Other IO depend on the hardware connected to the micro controller. Code exists to use LCD and TV devices. CAN, USB or I2C are possible as well. Another use of the redirect feature is the following: consider some input data in external EEPROM (or SD-Cards). To read it, the words KEY and KEY? can be redirected to fetch the data from them.

Strings

Strings can be stored in two areas: RAM and FLASH. It is not possible to distinguish between the storage areas based on the addresses found on the data stack, it’s up to the developer to keep track.

Strings are stored as counted strings with a 16 bit counter value (1 flash cell) Strings in flash are compressed: two consecutive characters (bytes) are placed into one flash cell. The standard word S" copies the string from the RAM into flash using the word S,.