AmForth is published under the GNU Public License v3 (GPL).
The virt machine of qemu-system-arm is a generic Cortex-A system with large RAM capacity
and choice of Cortex-A cores. This AmForth build targets the 32-bit cortex-a15.
This build is configured for 256K of RAM backed FLASH memory region and 256K of RAM memory region (see qemu.ld for details). There is no point giving QEMU more than 1M of memory to run it (a lot less than the default QEMU setup).
To run this AmForth build you will need qemu-system-arm which is best installed through
the package management facilities of the host OS.
To run AmForth you need just the QEMU executable and amforth.elf file. The basic command to run it is
qemu-system-arm -M virt -cpu cortex-a15 -m 1M -kernel amforth.elf -display none -serial stdio
The stdio interface is very basic and uncomfortable to use for anything but a quick test. For regular use
it is better to run the serial interface connected to a PTY. You will need a terminal emulator to
interact with AmForth through this serial setup. It is highly recommended to use amforth-shell.py
as the terminal emulator as it provides a lot of AmForth specific usability features.
amforth-shell.py requires Python3 and the pyserial package. Python3 is often pre-installed by the host OS. If it isn't follow the recommended installation approach for your OS. The pyserial package usually needs to be installed with pip3 install pyserial command. If this gives you error: externally-managed-environment, and you don't want to heed its warnings and deal with Python virtual environments, then pip3 install --user --break-system-packages pyserial should be a relatively safe work-around.
See amforth-shell.py comments for more details on how to use it.
The command to run AmForth connected to PTY is
qemu-system-arm -M virt -cpu cortex-a15 -m 1M -kernel amforth.elf -nographic -serial pty
In this configuration the I/O of the qemu process is connected to the QEMU monitor, which facilitates control of the emulation process. It will output the file name of the PTY to connect to on start, it looks something like this:
QEMU 10.2.0 monitor - type 'help' for more information
char device redirected to /dev/ttys012 (label serial0)
(qemu)
To connect to AmForth you need to start the terminal emulator and connect it to the indicated PTY device.
To connect amforth-shell.py to the indicated PTY the command would be
amforth-shell.py --port /dev/ttys012 --speed 115200 -i
Note that amforth.txt and amforth.html contain an autogenerated reference card of all words built into this AmForth build.
Besides executing known words, AmForth supports compiling new words at runtime. It has a separate FLASH and RAM based dictionary.
Words >flash and >ram switch the destination for newly compiled words. The RAM dictionary is a scratch space that can
be used for words being developed, words can be redefined, the whole dictionary can be emptied, etc. When the development of
a word is finished it can be compiled into the FLASH dictionary and thus become persistent (assuming FLASH is persistent on a given target).
Words in the RAM dictionary will disappear when the system restarts.
Typical development cycle would use amforth-shell to load and reload word definitions from a file on the host computer. At the start the words are loaded into the RAM dictionary, tested, changed, reloaded again, tested, etc. Repeat as many times as necessary. Once the file has words in the shape that satisfies all tests and requirements. The mode is switched to FLASH and the file is loaded one last time. Then the words are persisted in the FLASH memory and ready to be used at any time later.
Note that the only tools needed for this process are AmForth running on the target device and a terminal emulator, like amforth-shell. This makes AmForth a powerful tool to explore the target platform with ease.
- amforth.bin - binary file for uploads into physical board
- amforth.hex - Intel hex file for uploads into physical board
- amforth.elf - executable for emulation
- readme.md - this file
- LICENSE.txt - GPL3 license text applies to this distribution
- amforth.html - reference card of all words in this build
- amforth.txt - reference card of all words in this build
- amforth.toc - list of headers of all words in this build
-
amforth.dep - list of files used in the build
-
amforth.map - linker map of the executable
-
amforth.sym - list of all symbols of the executable
-
amforth.lst - assembler listing from the linker
-
amforth.lst-as - assembler listing from the assembler
-
amforth.sal - symbol and source line listing (debug info)
-
amforth-shell.py - terminal emulator for AmForth
- amforth32 documentation: https://amforth32.github.io/amforth32/
- AmForth documentation: https://amforth.sourceforge.net/
- AmForth mailing list: https://sourceforge.net/p/amforth/mailman/amforth-devel/
- ARM virt machine: https://www.qemu.org/docs/master/system/arm/virt.html
- ARM virt machine UART: PL011 https://developer.arm.com/documentation/ddi0183/g