Installing on Atmega and Arduino

Compile the code with MPLABX/XC8 and program the hex file with a suitable JTAG or ICSP programmer to your chip.
The fuses must be set to BOOTSIZE=256 words.

Compiling with Microchip XC8:

• Install MPLABX and XC8
• Add avr/src/ff-xc8.asm as only source file in a project.
• Select a chip
• Add linker option "-nostartfiles"
• Configure options according to your hardware and preferences in avr/src/config-xc8.inc
• Compile
• Get the hex file from dist/default/production/
• Program the chip with avrdude or some other tool using fuses: extended(see below) high(0xdf) low(0xff). The extended fuse should be set to the highest Brown-Out-Detection level your design can use. Without BOD in use there has been some eeprom corruption observed at address zero of the eeprom. For 5 volt (Arduino) boards the extended fuse should be 0xfc for the 328 and 2560. For the 32u4 it should be 0xf8.

FlashForth has been tested on Atmega 2560, 128, 328 and 32u4 sofar.
It should also work on Atmegas 168, 644 and 16u2.

FlashForth has been tested on the Arduino Leonardo, Mega 2560 R3 and Uno R3.

For the Arduino boards there are four hex files in the avr/hex directory. These images have been compiled by the Microchip XC8 compiler.

• The 328-16MHz-38400.hex file is for the Atmega328P and the Atmega328 chip on the Arduino UNO board.
• The 2560-16MHz-38400.hex file is for the Atmega2560 chip on the Arduino MEGA board.
• The 32u4-16MHz-USB and the 32u4-16MHz-UART38400 are for the Atmega32u4 chip on the Arduino Leonardo board. The -USB image has the USB interface as operator interface. The -UART38400 image has the UART as the operator interface.

Programming the Arduino UNO board with the 328-16MHz-38400.hex file.

• Get an AVR In-Circuit-Programming device, like Pololu USB AVR programmer or the OLIMEX ISP-500. These are AVR STK-500 compatible ISP programmers.
• Install Avrdude. Avrdude is available for Windows, Linux and Mac.

Connect the ISP programmer to your PC and to your Arduino UNO board

The avrdude command line for programming the FF image looks like this on a linux machine.

$ avrdude -p m328p -c stk500 -P /dev/ttyACM1 -e -u -U flash:w:328-16MHz-38400.hex:i -U efuse:w:0xff:m -U hfuse:w:0xdf:m -U lfuse:w:0xff:m

Inlining of words

FF can compile location independent assembler primitives as inline code. The shortest of these words have the inline bit set in the word header for automatic inlining.

Individual words can be inlined by prefixing the word with INLINE.

: newswap inline swap ; 

When compiling a new word that should be inlined automatically, the inline flag can be set with the word INLINED.

On the Atmega the following words are always inlined by the compiler.

rp@ >< cell+ cells char+ chars invert 1+ 1- 2+ 2- 2* 2/
p+ @p p2+ ei di dup drop rdrop >body idle busy

On the Atmega the following words can be prefixed with INLINE.

ticks 1 over swap + - and or xor mset mclr lshift rshift
sp@ sp! !p p++ flash eeprom ram cell false true state ticks >pr
d+ d2/ dinvert fl- fl+

Also words defined by CONSTANT, VARIABLE, 2CONSTANT and 2VARIABLE can be inlined. They compile the constant and the variable address as inline literal code.

If you append the definition with INLINED, the compiler will later compile the constant as an inline literal.

34 constant thirtyfour inlined 
: literal-34 thirtyfour ;

Interrupt handling

Interrupt routines can be written in assembly or in Forth. FF interrupt words have to be ended with ;I .

The interrupts use the parameter stack of task that happened to be executing when the interrupt occured.

In general Forth words that normally would be used in an interrupt word are interrupt safe.
Words that start the interpreter or compile new words should not be used in an interrupt.
It is not possible to store to flash or eeprom in an interrupt routine.

The following registers are always preserved before the interrupt word is executed:

R0 R1 R16 R17 R24 R25 R26 R27 R28 R29 R30 R31

To activate the interrupt you store the interrupt word xt into the interrupt vector.

' my_irq 10 int!

The interrupt vectors are stored in ram. The interrupt vectors in ram are cleared at warm start, so to enable the interrupt word at startup, a initialization word must be used.

: irq_init ['] my_irq 10 int! ;
' irq_init is turnkey 

To use individual interrupt sources, the interrupt enable bits and flag bits for each interrupt source must be used.

Register usage and memory usage

SP: The return stack pointer
Y(R28, R29) : The parameter stack pointer
X(R26, R27), Z(R30, R31): Temporary data and pointers
R24, R25: Cached TOS value
R22, R23: Internal flags
R20, R21: The P register
R18, R19: The A register
R0, R1, R16, R17: Temporary data for assembler words.
R4, R12, R13: CPU load measurement result (optional).
R14, R15: Millisecond counter.
R10, R11: Buffered flash page address.