Stellaris Toolchain

Notes on how to set up the toolchain for development in C on Luminary Micro's Stellaris ARM Cortex M3 microcontrollers.

StellarisWare

StellarisWare is Luminary Micro's name for the useful set of libraries that they supply. DriverLib is the Peripheral Driver Library for the on-chip peripherals (and appears to have previously been used as the name of the package as a whole). GrLib is the Graphics Library that provides a set of graphics primitives and a widget set for creating graphical user interfaces on boards that have a graphical display. There is also a bootloader, some (target) utilities and (host) tools. StellarisWare is supplied with evaluation kits and also downloadable from Luminary Micro. Download the version associated with the target board you have to get appropriate example programs.

GCC, binutils, et al

CodeSourcery says "CodeSourcery, in partnership with ARM, Ltd., develops improvements to the GNU Toolchain for ARM processors and provides regular, validated releases of the GNU Toolchain". CodeSourcery also develops proprietary software, principally startup code and various libraries for use on the target, and a debug "sprite" for use on the development host. This is all bundled together in a package named Sourcery G++ which is available in Personal and Professional editions. Ignore this and download the Lite edition which contains just the GNU toolchain without the proprietary components.

Since CodeSourcery contribute patches back upstream in theory one could simply obtain the GCC sources and compile the tools oneself but in practice it is more convenient (and likely more timely) to obtain pre-built binaries from CodeSourcery.

The Sourcery G++ Lite download is an installer that will install the tools, install shortcuts to the documentation, and add the tools directory to the path.

make, et al

To build the StellarisWare libraries and example programs (and your own programs) you need make and an associated shell with standard tools like mkdir, rm, etc. There are various ways of achieving this but the simplest seems to be UnxUtils which is a native Windows build of standard GNU tools.

The download is just a zip archive. Unzip it anywhere and add the /bin and /usr/local/wbin directories to the path.

The advantage of UnxUtils over GnuWin32 is that GnuWin32 does not include a shell. The StellarisWare makefiles use shell built-ins (such as type) and syntax that is not understood by the Windows shell. UnxUtils includes zsh, and make will spawn to this if it is present. UnxUtils is officially endorsed in that sense that it is what is distributed by Luminary Micro with evaluation kits to enable command line use of the CodeSourcery tools.

It is also possible to use cygwin. The StellarisWare makefiles contain code to mugne paths to cygwin style if invoked in a cygwin environment.

At this point it should be possible to build from the command line by invoking make in any of the example project directories.

eclipse IDE

Download and install eclipse with CDT (the C development toolkit). You can download vanilla eclipse and the CDT plugins separately but since there are version-specific dependencies it is better to get the bundle. Once installed use the built-in "Install new software.." functionality to add the Zylin Embedded CDT plug-in and optionally the Eclox plug-in for easily working with Doxygen.

LM Flash Programmer

The LM Flash Programmer tool is not part of StellarisWare per se but is also worth obtaining from Luminary Micro. It allows for programming targets via serial or Ethernet interfaces in conjunction with the bootloader, or via JTAG (but only via the interface built in to the evaluation boards).

In eclipse the LM Flash Programmer can be set up as an External Tool so that you can build and download to the target with a single button click. Create a new external tool configuration, enter appropriate values for the location, working directory and arguments.

Location

Working Directory

Arguments

C:\Program Files\Luminary Micro\LM Flash Programmer\LMFlash.exe

${project_loc}

--quick-set=manual

--interface=ethernet

--net-config=<host IP addr>,<target IP addr>,<target MAC addr>

gcc\${project_name}.bin

(Invoke lmflash from the command line with the --help argument to see a list of all options). Select "Build before launch" and choose to display the new configuration in the External Tools favorites menu.

JTAG Tool

The Olimex ARM-USB-TINY interface appears to have the best price/performance of the FTDI2232-based JTAG dongles. Things to check for if considering an alternative include the target working voltage range (the cheaper DIY dongles do not include level shifters and assume the target works at 3V3), and OpenOCD compatibility.

Install the software from the bundled Olimex CD. This results in a gccfd directory containing an ARM-USB-OCD-DRIVER directory with drivers for the dongle, and an openocd directory with OpenOCD documentation and binaries. Connect the dongle and point Windows at the drivers. Copy the openocd directory somewhere convenient (e.g. C:\Program Files). The gccfd directory is then redundant and can be deleted. The remainder of its contents is actually a complete ARM toolchain including Eclipse, YAGARTO and various example projects which is a convenient starting point for Olimex development boards, but the tool versions are a little old and the focus is not Cortex-M3 because Olimex does not sell Cortex-M3 eval boards.

The driver supplied by Olimex is FTDI's proprietary ftd2xx.dll and the OpenOCD binary supplied is built to work with this. The OpenOCD project is apparently frowning on distribution of binaries linked against ftd2xx.dll for release 0.2.0 onwards so in future this may change.

OpenOCD

The best way to get OpenOCD binaries is from the vendor of your JTAG tool (see above) since the OpenOCD project itself does not distribute official binaries. The OpenOCD website does have source code and documentation. The best (and apparently official) forum is at SparkFun. Binaries are available for recent releases from Fedddie Chopin, one of the OpenOCD developers.

In eclipse OpenOCD can be set up as an External Tool so that you can start it with a single button click. Create a new external tool configuration, enter appropriate values for the location, working directory and arguments.

Location

Working Directory

Arguments

C:\Program Files\openocd\bin\openocd-ftd2xx.exe

${project_loc}

-f openocd.cfg -f arm-usb-ocd-tiny.cfg -f lm3s6918-idm.cfg

The arguments reference one or more configuration files. The division of commands between the files is arbitrary but it is convenient to have one file for general configuration of OpenOCD itself, one containing configuration specific to the JTAG dongle and one specific to the target. I have:

openocd.cfg:

telnet_port 4444

gdb_port 3333

gdb_memory_map enable

gdb_flash_program enable

arm-usb-ocd-tiny.cfg

interface ft2232

ft2232_device_desc "Olimex OpenOCD JTAG TINY A"

ft2232_layout "olimex-jtag"

ft2232_vid_pid 0x15BA 0x0004

jtag_speed 10

lm3s6918-idm.cfg

jtag_nsrst_delay 100

jtag_ntrst_delay 100

reset_config srst_only

jtag_device 4 0x1 0xf 0xe

target cortex_m3 little reset_halt 0 lm3s

working_area 0 0x20000000 0x4000 nobackup

flash bank stellaris 0 0 0 0 0

At this point if you start OpenOCD from either the command line or from the External Tool facility within Eclipse you should be able to telnet to localhost:4444 and try out some commands.

soft_reset_halt

resume

exit

My target-specific configuration file just attaches to the target ready for debugging because I am programming using LM Flash Programmer (see above). It is also possible to program via JTAG.

GDB

A GDB binary is part of the CodeSourcery package. Eclipse can be configured to use it, and to have it connect to the GDB server provided by OpenOCD. In Eclipse create a new Debug configuration of the Zylin Embedded debug (native) type. In the Debugger tab configure the GDB Debugger as C:\Program Files\CodeSourcery\bin\arm-none-eabi-gdb.exe. In the Command tab configure Initialize and Run commands:

Initialize:

target remote localhost:3333

Run

monitor soft_reset_halt

symbol-file "foo.axf"

continue

The symbol-file line should have the full path to the axf file. Quote the path if it contains spaces and escape backslashes. To ensure that the axf file does actually contain symbols define DEBUG in the project makefile.

Other Info