Special Chip?¶
Where To start ?¶
You have a favorite MCU that you’d like to run Mecrisp on, but it’s not in the supported hardware list, where do you start ?
What Language is Mecrisp Written in ?¶
Every MCU listed in the supported hardware list is written by [matthias.koch] entirely in Assembly Language.
Methods for adding a new MCU break down into two groups¶
1) Similar To one in the Supported Hardware List ?¶
Are you sure that your MCU variant doesn’t work already ?
Just because it’s not listed doesn’t mean it won’t work, just that no one has reported it working already. Matthias has a limited hardware selection so unless you send him a board with your mcu ready to test, then you will have to do the testing.
Testing your board is usually as easy as flashing the binary image from the family member that is on the supported hardware list into your MCU and seeing if the:
Mecrisp-Stellaris X.X.X for <chiptype> by Matthias Koch
greeting appears on your serial terminal.
No Greeting Message¶
Look into the USART code (written in Assembly Language), usually named “terminal.s” in your target directory. It’s possible the USART in your variant is slightly different, uses different pins, is used for some other purpose, has a different Baudrate setting etc. See “Building Mecrisp-Stellaris” below
Not a Assembly Code kind of person ? see “Sending Matthias Koch a Board” below.
Garbled Greeting Message¶
Almost working! try a different Baud rate on your serial terminal.
2) Entirely New Architecture ?¶
Mecrisp will need to be ported to your MCU architecture. If you’re not into Assembly Language, see “Sending Matthias Koch a Board” below, but this is really a last resort as Matthias favourite way to get to new ports up and running is to offer his assistance to someone who wishes to do so.
Building Mecrisp-Stellaris¶
Building is usually done with the Makefile in the mecrisp-stellaris-source target subfolder. If you are using Debian, you should get everything necessary to do so by installing “apt-get install build-essential binutils-arm-none-eabi” For a complete package rebuild, run the “release” script, which has more dependencies, though, as the assembled cores get emulated in order to precompile Forth code.
Every MCU in the supported hardware list has its own sub directory and from there, the Mecrisp-Stellaris binary image is compiled.
Your PC must have the required applications installed, such as Gcc, Bash etc, and some minor script changes may be needed depending on your OS.
For instance I use FreeBSD and don’t have the utility “md5sum” as required by Mecrisp-Stellaris, but I do have “md5” so I’ve added a symlink on my pc for md5sum –> md5. Or I can just change the name to “md5” in the distribution.
Compiling all the supported chip types in the one operation is done by executing the “release” script in the distribution root directory.
Individual chips may be compiled in their own directory located in “mecrisp-stellaris-source” by executing “make”.
Sending Matthias Koch a Board¶
This is really a last resort, but it doesn’t hurt to ask. Like the rest of us he is very busy and may not even have the time to reply for weeks.
If you want to give [matthias.koch] a development board with your MCU to test/port, email asking if he is interested. If he is then include some postcards from your area with the board (which won’t be returned to you). There is no timeframe, but if it has heavy analogs, marvellous ADCs/DACs in combination with a lot of RAM, I know Matthias won’t be able to resist looking at it for long :)
My preferred MCU is the STM32F051 and so I sent Matthias a STM32F0 Discovery Board back in May 2014. It was soon running Mecrisp-Stellaris, but at that time, mine was the first STM32F0 MCU to be supported (V2.00).
Note
There is no guarantee that Matthias will accept a board, especially if he doesn’t like the architecture such as Z80, or STM8. Assembly Wizards are like artists, they won’t and can’t use bad paint …
Hacking Mecrisp-Stellaris¶
Forth Users are very diverse range of individuals and love to customise their Forth to best suit their own needs … which are usually quite different from other Forth Users.
Forth is all about customisation in my opinion.
I recommend the following methods when you begin to hack Mecrisp-Stellaris, because once you start …
Use a SCM¶
Version your MCU directory (or the entire Mecrisp-Stellaris distribution. I use Fossil SCM, but a wide range of SCM’s are available, i.e. Git, bzr, mecurial etc.
A SCM will avoid the inevitable 3000 uniquely modified copies of Mecrisp-Stellaris and make life much, much easier.
Scripts¶
Create a bunch of shell scripts to do the most repetitive tasks.
My Mecrisp-Stellaris Hacks¶
These are my favorite Mecrisp-Stellaris Kernel hacks.
Hardware handshaking¶
Because Forth has a “COC” (Compiler on Chip) the compiler can “choke up” from being fed Source Code faster than it can digest so I add RTS Hardware Handshaking which ensures a fast orderly flow.
Faster Serial¶
The default serial speed of 115200 Baud isn’t nearly fast enough for me, so I use 460,800 Baud. If Forth was not as fast, or faster that using C, Gcc, and OpenOCD with GDB, for Embedded Development I wouldn’t use it.
Speed is even more important for Forth because Forth Users have immediate nearly realtime access to the hardware. If I want to light a led on the target hardware, I can do it right now at the terminal, I don’t have to compile a test program and download it like a C Programming User.
COC hardware Error Detection¶
Traditionally Forth users watched the Source Code slowly upload via their 9600 Baud terminal and read back any errors. This can be very time consuming, error prone and frustrating at 9600 Baud, but absolutely impossible at 460800 Baud!
However since the Mecrisp-Stellaris COC knows when it sees a Source Code Error I use that with RTS Handshaking to halt the Source Code upload right at the ERROR LINE.
I also add code that makes a LED turn on when a Source Code Error is detected by the COC.
Gnu Screen¶
I believe that Gnu Screen is the best serial terminal for Forth because it can send commands to Mecrisp Stellaris plus upload source files, all under control of a script, editor and so on.
But GnuScreen has one annoying issue, namely it ‘Stair Steps’ the data from Mecrisp Stellaris and ignores any configuration to stop it. The issue is that Mecrisp-Stellaris sends only the traditional Unix newline (NL) character at the end of line, but GnuScreen must have both a newline (NL) and a carriage return (CR) just like DOS.
So I add a CR to the NL in Mecrisp-Stellaris which solves this issue.
Word Hacks¶
I prefer a simpler stack print word “.s”
Default Stack Print Word¶
.s Stack: [4 ] 42 2 3 4 TOS: 5 *>
My Stack Print Word¶
.s Stack: [4 ] 42 2 3 4 5
