Porters Guide¶
Your chip isn’t listed in the suported hardware list, but you’d like to see if you can get it going, what to do ?
1) Find a close relative¶
Look through the suported hardware list and see if you can find a similar chip, one from the same family, remember even a image for a CortexM0 will run on a CortexM4 etc as they’re all upwards compatible.
2) Install the Image from a similar chip onto your chip/board¶
Using the recommended method just flash the Image youve decided is the closest fit.
Warning
Make sure your chip has enough Flash to accomodate the Image, but this is rarely a problem as most Mecrisp-Stellaris Images are less than 20KB and will run in a chip with 32KB Flash. If your chip has only 16KB Flash or less, chances are it won’t run, or run well. Even if it does run, you won’t have any room for application code or libraries etc.
Warning
I have observed that failure to fully erase the Flash memory prior to flashing Mecrisp-Stellaris often results in endless “Unhandled Interrupt 00000003” messages
3) Connect a USB/3/3v Dongle¶
Connect a serial usb/3.3 volt dongle to your PC. Run Picocom with the following command:
picocom -f h -b 115200 /dev/cuaU0 --imap lfcrlf,crcrlf --omap delbs,crlf
Warning
change /dev/cuaU0 to suit your serial device, and if you don’t have permissions to use it, you may have to run this as root.
Double check the Terminal¶
Loopback test:
Connect the 3.3v TX and RX wires from your serial dongle together and type something in your terminal, what you type should be echoed back exactly.
Connect to chip/board¶
Look in the Serial Connections Table and connect the RX and TX wires from the dongle to the chip/board.
Note
remember TX –> RX and RX –> TX, terminal – chip/board
Now press the reset button on your board/chip and look for the Mecrisp-Stellaris Greeting…
If you don’t get it, try the other Serial Uarts on your chip, try other pins, perhaps it has a usb connector you can try plugging into your pc to try ?
Warning
I have transposed the TX and RX many times, so make sure that you have the right connections.
Garbled Text¶
You get garbled (unreadable) text when you press the chip/board reset button ?
Sounds like the wrong Baud Rate, but you’re very close to getting it working
4) It’s running!¶
Congrats, well done!
5) Change Memory Values¶
To suit your MCU variant
Testing Memory¶
See the Memstat utility.
Warning
Ram and Flash values reported by Memstat are totally seperate from values the Mecrisp-Stellaris Kernel uses. These values are preset and used when the Kernel is compiled. To configure the Kernel memory values for your MCU see Changing Kernel Flash and Ram values. Using these preset Kernel memory values, Mecrisp-Stellaris will print warnings when Flash or Ram reserves are exhausted.
Changing Kernel Flash and Ram values¶
Change the Memory config in mecrisp-stellaris-X.X.X/mecrisp-stellaris-source/your-mcu/your-mcu.s/ so the actual MCU memory will be available to Mecrisp-Stellaris to use.
@ 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 !
@ Konstanten für die Größe und Aufteilung des Flash-Speichers
.equ Kernschutzadresse, 0x00004000 @ Darunter wird niemals etwas geschrieben ! Mecrisp core never writes flash below this address.
.equ FlashDictionaryAnfang, 0x00004000 @ 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.
Note
Mecrisp-Stellaris checks Ram and Flash used against the values in RamEnde and FlashDictionaryEnde and will print warnings when no more memory is available.
Memory Full Warning Examples¶
3 OF lmt01-3.power.on ENDOF Ram full <---- RAM FULL ERROR !!!
nvic_icer_clrena-tim6 Flash full <---- FLASH FULL ERROR !!!
6) Changing MCU Name¶
Edit mecrisp-stellaris-X.X.X/mecrisp-stellaris-source/common/datastackandmacros.s line 91 and change the name:
.macro welcome Meldung
bl dotgaensefuesschen
.byte 8f - 7f @ Compute length of name field.
- .ascii "Mecrisp-Stellaris RA X.X.X"
+ .ascii "Mecrisp-Stellaris RA X.X.X for mcu-xyz"
7) Building a new kernel¶
Rename your mecrisp-stellaris-X.X.X.bin to mecrisp-stellaris-X.X.X-for-mcu-xyz.bin
Test New Kernel¶
is the name right ?
is the memory right ?
Checksum The Kernel¶
md5sum mecrisp-stellaris-X.X.X-for-mcu-xyz.bin
8) Write a README¶
A short for users, telling them what board/cpu this is for, how to connect, how to Flash and any other interesting details.
Email me a copy of the image, md5sum, your README and your name/email (whatever you want to release online) and I’ll put it on my doc site for users to download, and forward to you any emails I receive about it.
I’ll also email Matthias Koch who may add it to the official release, and even put your name on the famed list of contributors.
Flash Memory Operation¶
Mecrisp-Stellaris internally uses individual 2 byte writes (=opcode size!) and has buffer layers for ECC flash controllers with up to 16-bytes-at-once writes.
This generally means that MCU’s with Flash requiring more than 16-bytes-at-once writes cannot be supported.
Problem MCU’s¶
These MCU’s are problematic to port to Mecrisp-StellarisForth and therefore have no support.
Atmel SAM based chips¶
The Atmel series chip has a flash controller which supports only 256-bytes-at-once writes.
Mecrisp needs at least two separate writes for every definition, and every definition being at least 2*256 bytes large simply isn’t practical.
There is one contributed experimental target for atsame70, but it lacks “compiletoflash” mode, in other words Flash can’t be used, only Ram.
If you want to port a Atmel SAM based MCU, you’ll need to first check the datasheet on flash write granularity.
Examples Atmel Sam Boards¶
Adafruit Trinket M0
Arduino Due, Genuino
Cypress PSoC’s¶
Horribly bad documentation which makes finding out any details on initialisation very, very difficult.
See also
