The complete tutorial for Stellaris Launchpad development with GNU/Linux (II)

Did you follow my previous tutorial? We set up the toolchain, built StellarisWare libraries, compiled lm4flash tool and flashed an example to the Stellaris LaunchPad. So... you are brave and even started writing your own code. That's great news! Unfortunately programs have a nasty tendency to fail, and debugging using LEDs and traces is not convenient for big projects. Don't worry, in this chapter we will learn how to set up a full debugger (gdb + openocd). This way you will be able to debug the code setting up breakpoints and watching variable values. This tutorial is based on this tutorial by Mauro Scomparin (scompo). You can follow it instead of this one, I just wanted to write it again to have all the tutorials in one place, and to fit the directory structure I'm using. But there are almost no differences between both tutorials.

Building OpenOCD

At the time of writing this tutorial, there is not official support in OpenOCD for the ICDI protocol used in the Stellaris LaunchPad integrated debugger. But don't worry, Spencer Oliver has patched it to add support. When this patch is pushed into the main OpenOCD branch, it will not be necessary to follow this tutorial. Just install it using the repository of your distro, and it's done. But now we will have to do it the long way:

1. Download the sources

cd ~/src/stellaris
git clone git://openocd.git.sourceforge.net/gitroot/openocd/openocd

2. Install the required dependencies

sudo apt-get install libtool libusb-dev

3. Apply Spencer Oliver patches:

cd openocd
git pull http://openocd.zylin.com/openocd refs/changes/22/922/14

4. And build it:

./bootstrap
./configure --enable-maintainer-mode  --enable-ti-icdi
make

5. To install it I have also followed scompo's suggestion about not executing make install but copying the required files manually:

cd ~/src/stellaris
mkdir openocd-bin
cp -r openocd/tcl/* openocd-bin
cp openocd/src/openocd openocd-bin

gdb is already built. We built it in the previous chapter, when we built the toolchain. So we can start using it, but before, we must build something to debug.

Avoiding Stellarisware obscure licenses

As I wrote in previous chapter, there's no problem with StellarisWare library license, but the examples that come bundled with it use a more obscure license terms, including the startup code, the linker scripts and the makefiles. So to avoid problems with this license, you should not use these files. Again, scompo comes to rescue us. He wrote a template project, including a makefile, startup code and a linker script you can use in your own projects. You just have to preserve the header in the files (with the copyright notice) and everything should be fine. Let's build this template project:

1. Download the project

cd ~/src/stellaris
git clone https://github.com/scompo/stellaris-launchpad-template-gcc.git
cd stellaris-launchpad-template-gcc

2. Edit the makefile to set the path to the StellarisWare library. Change this line:

STELLARISWARE_PATH=~/stellaris/stellaris/

to this:

STELLARISWARE_PATH=~/src/stellaris/stellarisware/

3. And build:

make

At last, it's time to start debugging!

Using the debugger

First of all, you have to create a config file for openocd. Rickta59, a Stellarisiti forum user, wrote one working perfect. Then you'll only have to start both openocd and gdb.

1. Download the config file:

cd ~/src/stellaris/openocd-bin
wget http://pastebin.com/download.php?i=qXxeYsVx -O LM4F120XL.cfg

2. With the Stellaris LaunchPad debug port connected to the PC, and the power select switch in the "debug" position, run openocd. Before starting it, make sure you created the udev rule for the Stellaris LaunchPad as written in the previous chapter, to avoid having to run openocd with root privileges:

./openocd --file LM4F120XL.cfg

3. openocd should be running without problems. If it fails, try running it as superuser (with the sudo prefix). If it works with sudo, maybe you have not properly created the udev rule! If it's working, now you'll only have to start gdb. Open another terminal and type:

cd ~/src/stellaris/stellaris-launchpad-template-gcc
arm-none-eabi-gdb main.axf

4. gdb should have started, and you should be greeted by the (gdb) prompt. At this prompt you should start writing some commands. The first one will connect gdb to openocd, and the following ones will load the program and initialize the debug process:

target extended-remote :3333
monitor reset halt
load
monitor reset init

5. You can enable some breakpoints and watch the contents of the count variable. Then continue execution with the 'c' command:

b main.c:51
b Timer1A_ISR
display count
c

6. The execution will hit a breakpoint, and the line at which the code is stopped will be printed, along with the value of the count variable. You can type 'c' command several times to continue execution and watch the contents of the count variable each time the program stops at a breakpoint. When you finish debugging, you can exit gdb with the 'q' command. To exit openocd, just switch to it and hit [CTRL] + C.

And that's all. Now you can build and debug anything you want for your StellarisLaunchpad using GNU/Linux. What did you say? You don't like command-line debugging? Me neither! So stay tuned, because in the next chapter, you'll learn how to set-up an Eclipse project, using its full code building and debugging capabilities!

Happy hacking and stay tuned!

Troubleshooting

You followed the steps without changing a single thing, and got to step 4 of the "Using the debugger" sub-chapter. But then something went wrong and when trying to connect to openocd with the target command, you received this cryptic error message:

Remote 'g' packet reply is too long:
000000000000000000000000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000010000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000000000000000000000000
000000000000

It looks like there's a known bug in openocd causing this issue with some versions of gdb. Until this bug gets fixed, you can workaround it:

1. Download this target description file to the directory where the project you want to debug is (in this case, to ~/src/stellaris/stellaris-launchpad-template-gcc).

cd ~/src/stellaris/stellaris-launchpad-template-gcc
wget http://pastebin.com/download.php?i=0Lu3Bu0R -O target.xml

2. Start gdb as usual, but before issuing any other command, write this one at the gdb prompt:

set tdesc filename target.xml

3. Continue writing commands as usual, hopefully the error should be gone, and everything should work perfect now!