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.