Customize AmForth¶
Customization takes place when you create the hex files. It requires to edit files and re-generate them using the assembler.
All customization is done in the application master file. A good
starting point is template/template.asm. If you change any other
file, good luck. You can look for these options in the code however.
Application / Board specific¶
Every application is unique. Thus you need to create your own amforth specific to your intended environment. There is no generic image that works everywhere.
First make a copy of the appl/template directory (myapp in this example).
mt@ayla:~/amforth/appl$ cp -r template myapp
Next edit the template.asm in the mayapp directory. You may
want to rename the file later. There are only a few lines that
need your attention.
; include the amforth device definition file. These
; files include the *def.inc from atmel internally.
.include "device.asm"
This line is tricky. It uses the generated include file but does not specify the controller type itself. The magic is in the list of INCLUDE directory that is defined in the Makefile. Alternatively change the line to
.include "devices/atmega1280/device.asm"
please use the same directory name from the pd2amforth run above. The downside of using the controller-dependent directory name instead of some makefile variables is that you have to keep the definition of the controller type in sync in <em>two</em> files. The makefile always need the information for the programmer.
The next essential information is the frequency your controller
uses. It is necessary (at least) to calculate the proper usart settings
and to get the right delay in the forth word ms.
; amforth needs two essential parameters
; cpu clock in hertz, 1MHz is factory default
.equ F_CPU = 16000000
The last setting is the command terminal for the prompt. There are a few predefined settings. Unfortunately Atmel has changed the wording over time. In most cases make sure that the number in the _0 reflects the number in the RXEN0 definitions and the final 0 in the UCSZ00. Elder controllers do not have a number suffix, just delete it (atmega32 may serve as an example for it).
; initial baud rate of terminal
.include "drivers/usart_0.asm"
.equ BAUD = 9600
.equ USART_B_VALUE = (1<<TXEN0) | (1<<RXEN0) | (1<<RXCIE0)
.equ USART_C_VALUE = (3<<UCSZ00)
The next file to edit is the Makefile (or the build.xml if you want
to use the ant utility). First set the right controller type:
# the MCU should be identical to the device
# setting in template.asm, it set
MCU=atmega1280
The last change is the placement of the avrasm2.exe and the
Appnotes2 directory.
# directories
DIR_ATMEL=../../Atmel
To flash the controller, the program avrdude is used. Depending on your programmer, define the BURNER variable as well:
# programmers / flags
USB=-c avr911 -P /dev/ttyUSB3
PP=-c stk200 -P /dev/parport0
JTAG=-c jtag2 -P /dev/ttyUSB2
BURNER=$(USB)
AVRDUDE=avrdude
AVRDUDE_FLAGS=-q $(BURNER) -p $(MCU)
All other settings can be kept for now. Just run make and look for errors.
WANT - Options¶
WANT Options are used to select certain features. There is always a default value in place (0).
The files core/devices/$MCU/device.asm contain among other things a
complete list of WANT Options that can be used to include device specific
Names into the dictionary.
.set WANT_AD_CONVERTER = 0
.set WANT_ANALOG_COMPARATOR = 0
.set WANT_BOOT_LOAD = 0
.set WANT_CPU = 0
....
Changing these options to 1 includes the matching sections from device.inc
into the generated dictionary. The same effect could be achieved by selectively
send the device.frt file sections.
Another such option is the WANT_IGNORECASE option. If it is set to 1, the amforth dictionary lookup routine is extended to handle upper and lower case words the same. This makes foo and FOO the same. This is a dictionary wide setting, valid for both pre-defined and self-defined words.
The 3rd group switches the USART terminal communication between interrupt and poll based routines:
.set WANT_ISR_TX = 0
.set WANT_ISR_RX = 1
Settings the value of 1 select the interrupt based routines, otherwise the poll driven routines are used. It is recommended to leave the options as they are set.
See also