.. index:: compiling,building,kernel,patching,patch,ra-kernel,source assembly code,source,arm-none-eabi .. _compiling: Compiling ========= .. image:: pics/compiler.jpg When altering the Mecrisp-Stellaris Forth kernel/image for the MCU of choice one sometimes needs to modify the source, perhaps to change the USART device to accommodate the pin or a particular board layout or alter the Baud rate, change the clock speed, or clock source and so on. And this can be done in the image itself by modifying the Source Assembly code. A variant of a :ref:`supported MCU` may have less or more on board memory which needs to be changed so that Mecrisp-Stellaris can correctly advise when memory is running low and so on. Modifying the Assembly code source means the system can boot up in your preferred state and negates the need to load Forth Words after the system has booted with the attendant requirement that you may need to make your own :ref:`patches` to update to a later Mecrisp-Stellaris release. Whatever the reason, this article attempts to explain the usual compiling technique. Get the latest Kernel/Image --------------------------- This code may be found for all the MCU types in the :ref:`Mecrisp-Stellaris Release`. Modify The source ----------------- The source is always found in the individual directory for each MCU. A STM32F051 RA kernel is shown here for release 2.6.1. I will refer to this directory at the *MCU home directory* from now on. Remember to change it for *your* MCU. :: mecrisp-stellaris-2.6.1/mecrisp-stellaris-source/stm32f051-ra Directory Contents ^^^^^^^^^^^^^^^^^^ :: . ├── Makefile ├── flash.s ├── interrupts.s ├── mecrisp-stellaris-stm32f051.s ├── memmap ├── terminal.s └── vectors.s Compile The Kernel/Image ------------------------ Dependencies ^^^^^^^^^^^^ This guide is for Unix Open Source OS's, such as Linux, FreeBSD, OpenBSD or OSX. Cross compiler ~~~~~~~~~~~~~~ Your distro will have this for Cortex-M * arm-none-eabi The Usual Utilities ~~~~~~~~~~~~~~~~~~~ Bash or Shell work fine. Compiling --------- In the *MCU home directory* execute *make*, don't be afraid of any errors, they are logical, well explained, (most often it's a typo) and if you need help the Mecrisp-Stellaris community has a lot of experts, so once you have *tried everything*, email the mailing list at: https://sourceforge.net/projects/mecrisp/ For a good compile you should see something like this: Make ---- :: make arm-none-eabi-as mecrisp-stellaris-stm32f051.s -o mecrisp-stellaris-stm32f051.o arm-none-eabi-ld -o mecrisp-stellaris-stm32f051.elf -T memmap mecrisp-stellaris-stm32f051.o arm-none-eabi-objdump -D mecrisp-stellaris-stm32f051.elf > mecrisp-stellaris-stm32f051.list arm-none-eabi-objcopy mecrisp-stellaris-stm32f051.elf mecrisp-stellaris-stm32f051.bin -O binary Directory New Additions ----------------------- :: . ├── mecrisp-stellaris-stm32f051.bin ├── mecrisp-stellaris-stm32f051.elf ├── mecrisp-stellaris-stm32f051.list ├── mecrisp-stellaris-stm32f051.o ├── mecrisp-stellaris-stm32f051.s Naturally mecrisp-stellaris-stm32f051.bin is the file you now need to :ref:`flash` to your MCU. Make Clean ^^^^^^^^^^ To clear the *MCU Home Directory* of all new additions, simply run *make clean* to restore the release. Altering Memory --------------- Two files are associated with the MCU memory. 1. mecrisp-stellaris-stm32f051.s ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This is the file that needs to be altered when changing Flash or Ram sizes. Don't forget to change for your MCU. 2. memmap ^^^^^^^^^ Do not change the memmap file as it is only for checking core size while assembling, (so that the Forth core won't silently grow into the start of the erasable user dictionary). This can be confusing when compiling a binary image that uses memory outside the *memmap* config but don't worry about it, Mecrisp-Stellaris is designed for this. .. _mem-changing: Memory ^^^^^^ Ram ~~~ Here we see that 0x20002000 minus 0x20000000 = 0x2000 which is 8192 decimal bytes as this MCU has only 8KB Ram. If I had a new chip with 16KB Ram I would change *only* RamEnde to 0x20004000. Ram Code Section ~~~~~~~~~~~~~~~~ :: @ ----------------------------------------------------------------------------- @ Speicherkarte für Flash und RAM @ Memory map for Flash and RAM @ ----------------------------------------------------------------------------- @ Konstanten für die Größe des Ram-Speichers .equ RamAnfang, 0x20000000 @ Start of RAM Porting: Change this ! .equ RamEnde, 0x20002000 @ End of RAM. 8 kb. Porting: Change this ! Flash ----- Here, 16KB is reserved for the core, *DON'T CHANGE THIS*. Let's assume that the new MCU has 128 KB Flash ? In this case FlashDictionaryEnde would be changed from 0x00010000 which is 64KB decimal, to 0x00020000 which is double that value or 128KB. This leaves 128KB minus 16KB or 0x1E000 (122880 decimal) bytes for user code in the Dictionary. Such a mod may then read: :: .equ FlashDictionaryEnde, 0x00020000 @ leaves 0x1E000 bytes for the Flash-Dictionary. Flash Code Section ^^^^^^^^^^^^^^^^^^ :: @ Konstanten für die Größe und Aufteilung des Flash-Speichers .equ Kernschutzadresse, 0x00005000 @ Darunter wird niemals etwas geschrieben ! Mecrisp core never writes flash below this address. .equ FlashDictionaryAnfang, 0x00005000 @ 16 kb für den Kern reserviert... 16 kb Flash reserved for core. .equ FlashDictionaryEnde, 0x00010000 @ 48 kb Platz für das Flash-Dictionary 48 kb Flash available. Porting: Change this .equ Backlinkgrenze, RamAnfang @ Ab dem Ram-Start. .. seealso:: :ref:`PATCHES`, :ref:`The RA Kernel` and :ref:`The Terminal Problem`, :ref:`Porters Guide` and :ref:`Bringing up a new MCU`