The overall memory layout is defined by the main core/amforth32.ld linker file that defines the memory sections (see comments in the file for more details on specific sections). It is included by MCU specific linker files defining the physical memory regions that the sections are allocated in, for example arm/mcu/ra4m1/unor4.ld. If there are multiple build targets for a given MCU, there will be a dedicated linker file for each target (see make help for the list of recognized targets for a given MCU).

This arrangement ensures that the basic structure of the memory layout is the same everywhere and provides firm foundation for the large number of shared core words.

FLASH region

This is persistent, executable memory region that contains primarily the predefined AmForth words. The end of the used part of this region is tracked by dp.flash. User defined words can be compiled into FLASH when the compilation mode is set to FLASH using the >flash word. Words compiled into FLASH are tracked by forth-wordlist.

For some, usually emulated, MCU targets, the FLASH region can be allocated in transient RAM memory. However in these cases runtime updates in FLASH will not persist through resets and restarts of the system.

PVFLASH region

This is persistent data memory region used to store update records for persistent values, pvalues. Sufficient amount of PVFLASH is required for the >flash mode to work correctly. Without it AmForth is unable to remember new words compiled into FLASH across resets/restarts of the system.

PVFLASH region can be allocated in regular code flash memory, usually at the end of it, to allow the runtime FLASH dictionary to grow up to it. For more information see Persistent values.

RAM region

This is non-peristent, executable memory used for multiple purposes. It is divided into multiple sections, sometimes subdivided into parts with different purposes.

New words can also be compiled into the RAM dictionary when the mode is set to RAM using the >ram word. Such words will not persist, but this mode is very useful for development of new words, when many iterations of the same words need to be compiled and tested. This would use up space in the persistent FLASH memory relatively quickly, space that can only be reclaimed by erasing the FLASH using the word empty.flash or by re-uploading AmForth from scratch.

Section amramlo is used for RAM allocated by the predefined AmForth words. This includes parameter and return stacks, user block, system buffers etc.

Section amramhi is used for RAM allocated at runtime.

The lower part of amramhi, the RAM pool, is used for RAM allocated for words that are compiled into FLASH at runtime (variables, values, defers, etc). The end of the used part of this section is tracked by vp.

The higher part of amramhi is used for the RAM dictionary, i.e. words compiled into RAM at runtime. The end of the used part of this section is tracked by dp.ram. The words of the RAM dictionary are tracked by ram-wordlist.

Word stats from lib/stats.frt provides a convenient way to see current memory statistics. It shows USED / TOTAL (in bytes) and % used for each memory area and area start address at the end after @

> stats
FLASH:      33388 / 253876 B  13%  @ 4000004C 
PVFLASH:       56 /   4096 B   1%  @ 4003E000   A1: 0 
RAM pool:       0 /   8192 B   0%  @ 400408C8 
RAM dict:     696 / 249648 B   0%  @ 400428C8