Overview

amforth is an interactive and extendable command interpreter for the Atmel AVR8 Atmega microcontroller family. It features a simple turnkey-solution for embedded use as well.

The command language is FORTH. amforth implements an almost compatible ANS94 indirect threading 16bit Forth with very few missing CORE words, some words from the extension word sets (including some words from the Forth200x) and a few of its own words.

The system runs completly on the controller. It does not need additional hardware beyond a power supply. It places no restrictions for hardware extensions that can be connected with the controller, e.g. external RAM.

The interactive feature requires a serial line via RS232 (usb2serial converters work well). Other connections like TCP/IP telnet or radio links are possible as well, may require some implemention work however.

amforth is published under the GNU Public License v2 (GPL).

amforth needs approx. 8KB Flash memory, 80 bytes EEPROM and approx 200 bytes RAM for the core system (including the compiler words).

Karl Lunt has written an excellent User guide on how to use and work with amforth. For those who want to take a deeper look into the system is the Technical Documentation (PDF, ePUB 4.3.2012) and the reference card.

News

Work In Progress

  • lib: case did not work at all. Thanks to Jan for telling.
  • core: the new variable latest has the XT of the currently being defined colon word.
  • core: unused should tell the free amount of memory in the area here points to: RAM. Thanks to Carsten for the hint.
  • core: introducing an environment query for basic controller information: memory sizes, max dictionary address: mcu-info. The structure itself is not yet finalized. See at the end of a core/<device>/device.asm file for details.
  • tools: The upload utilities were unable to process absolute filenames (those beginning with a /) Thanks to Carsten for the fix.
  • core: Rvalue from lib/ans94/Rvalue.frt can be used to get a VALUE in RAM instead of EEPROM.

26.3.2012: release 4.8

  • core: fixed a bug in na@ and nb@ (extended VM registers).
  • core: redesigned to for use in LOCALs and RAM-based values.
  • core: .s is stripped down to a single line output of the stack content only. Looks better in the call tracer and is more like other forth's.
  • core: small atxmega updates. Unfortunatly avrdude cannot flash the boot loader section as expected.
  • core: optional unified memory address space. @ and ! use the range from 0 to RAMEND as RAM, from RAMEND+1 upwards the next addresses from EEPROM, until EEPROMEND is reached and the remaining addresses from flash.
  • core: environment? can now be used in colon definitions. changed into loadable forth source instead of compile-time assembly.
  • core: itype now sends proper (e.g. single byte) characters to emit.
  • core: type is made more robust against emit errors.
  • lib: macro and a recipe for using them.
  • recipes:: A Profiler to count the number of calls.
  • lib: evaluate for both RAM and Flash based strings.

4.2.2012: release 4.7

  • recipes: New Multitasking HOWTO, show the Reason For Reset, and a tracing utility.
  • core: new words from the STRINGS word set: sliteral and compare. Latter is a simplified version of the ANS94 spec: max 255 chars, (in)equality tests only.
  • core: source, refill are now deferred words, based on the USER area. >in likewise. Based on ideas from Strong Forth.
  • core: /key removed, it can be implemented by changing refill.
  • lib: The multitasker could not work after power cycles. Thanks to Erich for fixing.

6.10.2011: release 4.6

  • core: words shows the first entry in the search order list as specified by DPANS94.
  • lib: new word m*/ (d1 n1 n2 -- d2), uses a triple cell intermediate for d1*n1.
  • lib: new words bm-set, bm-clear and bm-toggle that efficiently change bits in RAM byte addresses. e.g. %0010 here bm-toggle changes bit 2 in the RAM location at here.
  • lib: renamed spirw to c!@spi, new word !@spi exchanges two bytes via SPI. Follows remotly the memory access word naming conventions.

29.6.2011: release 4.5

  • arduino: re-arranged word placing to maximize usable flash (at least on a duemilanove device, the bigger variants like the sanguino and mega* still have room for improvement). The target mega is now called mega128.
  • lib: lib/buffer.frt implements Forth 200x buffer:.
  • doc: improved refcard. Thanks to Erich for input and patches.
  • core: changed API of the recognizers to the final addr/len pairs. Do not use counted strings any longer!
  • core: new words find-name and parse-name operate on the current input buffer, word is no longer used internally. Lots of internal code simplifications.
  • core: (create) throws exception -16 if no name is given.
  • core: exception -42 is really -4 (stack underflow).
  • core: digit? again. Stack effect now compatible to gforth: ( char -- n true | false). Current setting of base is now taken internally.

24.5.2011: release 4.4

  • examples: added a game of life and a queens puzzle solver.
  • core: restructure of the RAM usage. You need to remove the .set here = ... line from your application definition file (template.asm).
  • core: turn cold into the main initialization word and warm into some high level initialization.
  • doc: updated Technical Documentation of Recognizers and Interrupt Processing. Reformatted the reference card to a more compact style.
  • core: added n>r and nr> from Forth 200x.
  • core: Redesign of Interrupt Handling. ISR Routines are still normal Colon Words and can deal with every kind of interupts. There are no lost interupts any longer. Based on Ideas from Wojciech (Tracker ID 2781547) and Al (mailling list).
  • appl: Fixed a regression in the floating point library due to changes in number in post 4.0 releases. >float can now be used as the main part of a recognizer.
  • core: added a compile time option WANT_IGNORECASE to make amforth case-insensitve, disabled by default.

1.5.2011: release 4.3

  • core: u> had wrong stack effect in case of true result.
  • core: int-trap triggers an interrupt from software.
  • core: /user environment query gives the size of the USER area
  • core: sleep takes the sleep mode as parameter.
  • ex: added timer-interrupt.frt as an example for using interrupts with forth.
  • pub: Erich has presented amforth at the Fosdem 2011 slides and proceedings (published with permission). Thanks Erich!
  • core: simplified get/set-order with a changed eeprom content.
  • doc: new user guide version from Karl (for version 4.2).
  • core: renamed e@/e! to @e/!e to comply with the memory access wordset from forth200x, same with i@/i!.
  • core: documentation fixes in many files: reference card.
  • core: re-design of the (outer) interpreter using recognizers (dynamically extend the interpeter to deal with new semantics. Defined get/set-recognizer similiar to get/set-order.

19.9.2010: release 4.2

  • core: fixed a regression for i! which made marker useless (among other oddities). Thanks to Marcin for the fix
  • core: currently defined colon words are invisible until the final ;.
  • applications: Leon contributed a IEEE754 floating point library in plain forth, Pito translated some basic words into assembly for speed.

2.9.2010: release 4.1

  • core: new words 2>r, 2r> and 2literal.
  • core: converted most of the atmega part definition files with the pd2amforth utility. Please report any success / failure. Controller Matrix
  • doc: set the fuses to make the bootloader size as large as the NRWW size.
  • core: abort assembling if flash usage is above limits.
  • core: allow double cell numbers in colon definitions. Thanks to Pito for reporting the bug.

1.7.2010: release 4.0

  • tools: amforth-upload.py optionally loads a device specific module and replaces register definitions with their values prior to sent the code to the controller. The device modules are auto-generated from the part description files.
  • core: ANS94 mention that HERE points to the data (RAM) region. Re-introduced DP as the dictionary (Flash) pointer. HEAP is gone. Migrate old HEAP to HERE and old HERE to DP.
  • core: save and clear the initial value of the MCU Status Register at address 10.
  • tools: pd2amforth is now capable to generate the device definition files. It is no longer necessary to edit them manually.
  • core: finally separated the terminal IO settings from the device definition files.
  • core: optionally set WANT_SPI (or any other IO Module) to include the register definion names at build time.
  • core: massivly restructured the devices/ filesystem entry. Change your application files to include "device.asm" instead of the device name. Set the include directory to the proper subdirectory under core/devices as well.
  • core: s" /pad" environment? dynamically calculates the free space. Do not use all of it however, the data stack may grow..
  • core: Simplified the Pictured Numeric Output words. They now use the memory area below PAD (which is 100 bytes above HEAP) as the buffer region.
  • appl: added the arduino board with some example codes. Currently with the Mega (Atmega1280), Duemilanove (Atmega328) and Sanguino (Atmega644p) controller types.

Notes

amforth uses a serial line interface as the terminal. Serial line settings are 9600 8N1, no flow control.

The source is developed with and for Atmels avrasm2. The alternative assembler avra (linux) needs a few patches to get it work.

Some word names like find-name may change in future releases to keep contact to forth 20xy.

Known Bugs

These are known effects that one may call bugs for the lastest development revision (trunk). They may or may not get fixed for the next release(s).

  • evaluate cannot be used to define words. 
         > s" : foo 123 ; " evaluate
     ok
     > words
     fo<garbage> ...
     ok
     >

Not Really Bugs

amforth has the following known effects, that someone may call bugs. This list is not complete. And the entries are not considered bugs.

  • The return stack has an off-by-one effect when using it's addresses: 

    > : rstest 1234 >r rp@ @ . r@ . r> ;
 ok
> rstest
 3405 1234 ok
> : rstest2 1234 >r rp@ 1+ @ . r@ . r> ;
 ok
> rstest2
 1234 1234 ok
>

  • +loop assumes signed values for both loop counter and loop limit.
  • s" does not copy the string into a buffer but returns a substring from the current source- buffer.