[Subscribe to the Recursive Labs email Newsletter to get updates][Find out more about our online courses] [Connect with us on Twitter][Facebook Page]

Programming the Stellaris Launchpad with GNU/Linux

28 October 2012

The Stellaris Launchpad is an exciting (and inexpensive!) ARM Cortex-M4F based development board from Texas Instruments.

The tools "officially" provided by TI for programming this board are rather bulky (you will have to download more than 1Gb of stuff from the TI web site) and are IDE based. I prefer working on the Unix command line with vi/gcc. This post will explain how to go about setting up a pure command-line based development environment for the Stellaris Launchpad on GNU/Linux.

[Note: Readers have suggested some modifications to the procedure given here to solve some of the issues they had faced - so please make sure that you go through the comments!]

Flash your stellaris Launchpad with lm4flash

First, download lm4tools from https://github.com/utzig/lm4tools and build "lm4flash" [Thanks to Adrian for pointing out that you may need to install libusb-1.0-dev for building lm4flash; on my Debian system, this is done by running: "apt-get install libusb-1.0-0-dev"]

git clone https://github.com/utzig/lm4tools.git
cd lm4tools/lm4flash; make

The "lm4tools" folder contains the machine code of a simple LED blinking app, "project0.bin". You can test "lm4flash" by flashing the board with this file (you may have to do this step as "root"):

lm4flash project0.bin

Build a bare-metal ARM toolchain

This step is a bit more tricky. You are now going to set up a toolchain (C compiler, assembler, linker etc) which will help you compile C programs written for the cortex-m4f processor on the stellaris launchpad.

You have one or two options. The easiest would be to download a pre-built toolchain from CodeSourcery - you can see some instructions here.

Another option is to build a toolchain from source - there is an excellent program which automates the process of getting the required source packages, applying necessary patches and building everything - it is called the summon arm toolchain. The "summon arm toolchain" is basically a shell script which when executed downloads the required source packages and builds the toolchain. Simply clone the git repo and run the script:

git clone https://github.com/esden/summon-arm-toolchain
cd summon-arm-toolchain; ./summon-arm-toolchain

You will have to install a few packages before executing the "summon-arm-toolchain" script; assuming that you are using a debian based system, simply do:

apt-get install flex bison libgmp3-dev libmpfr-dev libncurses5-dev \
    libmpc-dev autoconf texinfo build-essential libftdi-dev

If everything goes well, after "summon-arm-toolchain" does its job, you will see a folder called "sat" under your login directory - ~/sat/bin/ should contain executables like "arm-none-eabi-gcc" - congratulations, your toolchain is ready! Don't forget to add ~/sat/bin to your PATH.

Build Stellarisware with the GNU toolchain

TI provides a library called "stellarisware" for easy access to the peripherals on the ARM Cortex processor. There are also many example programs which demonstrate the use of many of these library functions.

You can download Stellarisware from http://www.ti.com/tool/sw-ek-lm4f120xl. The download is a single file called "SW-EK-LM4F120XL-9453.exe" which is a zip archive. Building Stellarisware is simple:

mkdir stellarisware; cd stellarisware
unzip ~/Downloads/SW-EK-LM4F120XL-9453.exe
make

"make" will build the peripheral access libraries as well as some example programs using the GNU toolchain installed in the previous step.

You can do a quick test by flashing one of the test programs on the stellaris launchpad:

cd boards/ek-lm4f120xl/blinky/sourcerygxx/
lm4flash blinky.bin

You should now see the green led blinking!

Write and test your own programs!

Using the stellarisware sample programs as a starting point, we can now test small programs of our own. It will be nice if we can avoid the dependency on the stellarisware Makefiles and either create our own makefiles or write simple scripts to directly invoke the required tools. Let's see how this is done.

First, we need a sample C program. Let's use the very simple LED blinker from one of the stellarisware examples (call it "blink.c"):

#include "inc/hw_gpio.h"
#include "inc/hw_memmap.h"
#include "inc/hw_sysctl.h"
#include "inc/hw_types.h"
#include "driverlib/gpio.h"
#include "driverlib/rom.h"
#include "driverlib/sysctl.h"

#define LED_RED GPIO_PIN_1
#define LED_BLUE GPIO_PIN_2
#define LED_GREEN GPIO_PIN_3

int main() 
{
  ROM_SysCtlClockSet(SYSCTL_SYSDIV_4|SYSCTL_USE_PLL|SYSCTL_XTAL_16MHZ|SYSCTL_OSC_MAIN);
  ROM_SysCtlPeripheralEnable(SYSCTL_PERIPH_GPIOF);
  ROM_GPIOPinTypeGPIOOutput(GPIO_PORTF_BASE, LED_RED|LED_BLUE|LED_GREEN);
  
  for (;;) {
    // set the red LED pin high, others low 
    ROM_GPIOPinWrite(GPIO_PORTF_BASE, LED_RED|LED_GREEN|LED_BLUE, LED_RED);
    ROM_SysCtlDelay(5000000);
    ROM_GPIOPinWrite(GPIO_PORTF_BASE, LED_RED|LED_GREEN|LED_BLUE, 0); 
    ROM_SysCtlDelay(5000000);
  }
  
}

Note the use of functions with a "ROM" prefix - the cortex-m4f processor on the stellaris launchpad has the stellarisware peripheral access library burnt into ROM; we are simply invoking some of those functions!

We need two more files to get our code running - a file containing "C startup code" (code which runs before "main" and sets up the proper execution environment required for the functioning of "main" and the rest of the code) and a "linker script". The "linker script" is used by the toolchain to assign proper memory addresses to locations in our program. You can copy both these files from one of the Stellarisware example programs:

cp ~/stellarisware/boards/ek-lm4f120xl/blinky/blinky.ld blink.ld
cp ~/stellarisware/boards/ek-lm4f120xl/blinky/startup-gcc.c .

Now, we can compile our code like this:

arm-none-eabi-gcc blink.c startup_gcc.c -g -mthumb -mcpu=cortex-m4 -mfpu=fpv4-sp-d16 -mfloat-abi=softfp -Os -ffunction-sections -fdata-sections -MD -std=c99 -Wall -pedantic -DPART_LM4F120H5QR -c -I/home/logindir/stellarisware  -DTARGET_IS_BLIZZARD_RA1

Replace "/home/logindir/stellarisware" with the name of the folder under which you have unpacked stellarisware.

Don't worry too much about those command-line options - I got them by examining the stellarisware Makefiles!

The above command generates two object files, blink.o and startup_gcc.o. The next step is to link them:

arm-none-eabi-ld -T blink.ld --entry ResetISR -o a.out startup_gcc.o blink.o --gc-sections

The final step is to prepare a raw binary image by stripping the executable "a.out" of its header and other unnecessary sections:

arm-none-eabi-objcopy -O binary a.out blink.bin

The resulting file, "blink.bin", can be flashed with lm4flash:

lm4flash blink.bin

You should see the RED LED blinking!

You can now build your own Makefile or pack up the above commands into a simple shell script!

That's it, you can now develop for the Stellaris Launchpad on a pure GNU/Linux environment without using complex graphical IDE's!

blog comments powered by Disqus