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.

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.

Garbeled Text

You get garbeled (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

Test Memory

Paste the following Word in the terminal, line by line. Make sure you get a “OK” after each line, if not press the board reset and start again:

: flashfree compiletoram? $10000 compiletoflash here - swap if compiletoram then ;
: ramfree compiletoram? not flashvar-here compiletoram here - swap if compiletoflash then ;
: free ." (bytes) " cr
." FLASH.. TOTAL: " $1FFFF7CC @ abs dup . ." USED: " flashfree dup >r - . ." FREE: " r> . cr ." RAM.... FREE: " ramfree .
cr cr ;

You should see something like:

free (bytes)
FLASH.. TOTAL: 65472 USED: 20704 FREE: 44768
RAM.... FREE: 7172

Are the FLASH and RAM values reported accurate for your chip ?

Usually they are not as this is a different chip, but you can change them to match the data sheet for your chip.

Change the Memory config in mecrisp-stellaris-X.X.X/mecrisp-stellaris-source/your-mcu/your-mcu.s/

@ 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.

Change 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"

Build a new kernel

See rebuilding the 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 Kernel

md5sum mecrisp-stellaris-X.X.X-for-mcu-xyz.bin

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

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