Using the LM3S811 Evaluation Board under Linux
This article details the steps I took to get Luminary Micro's LM3S811 Evaluation Board running under Kubuntu Linux 6.06. (Updated for 7.04, 7.10)
Introduction
Luminary Micro have created the first family of 32-bit microcontrollers based on ARM's Cortex-M3 processor core.
They have also, to their great credit, also designed and built a $50 evaluation board for one of the largest and most capable of these, the LM38S11. As with most of these kits, it comes with a CD full of Windows drivers and software. As I use Kubuntu at home (no Microsoft stuff for me, thanks), this is of limited use to me, although the PDFs of the datasheets are invaluable.
There is information out there on the web detailing how to connect the board to a Linux machine, but no real step-by-step guide. So when I set mine up, I decided to record exactly what I had to do to get it working, and publish it so that others can do the same.
USB Drivers
The board communicates with the host PC using USB, so we need USB drivers. There are two choices for the USB controller being used, the FTDI2232.
The first is the open-source libftdi, which is available as a Debian package. I tried this first, (a) because it's a package and therefore easy to find and install, and (b) because it's open. Unfortunately, (c), I could not get it to work.
So I then downloaded and installed FTDI's closed-source drivers, D2XX. I downloaded and installed it according to the instructions. This leaves the library at /usr/lib/libftd2xx.so.
Get Ready to Build
In order to transfer programs to the chip and debug it, we need a debugger interface. Luckily, on the day that the kit was delivered, Magnus Lundin contributed a Cortex-M3 communications module to the open-source OpenOCD project (documentation here).
In order to actually build the program, you will need autoconf, automake, make and gcc. Again, these are all standard Ubuntu packages. I selected the latest autoconf, automake and make, and gcc version 4.0.3.
After installation, you should be able to check on the compiler: open a terminal and type gcc -v. You should get a message about the configuration and version of gcc. If this does not work, you need to create a symbolic link:
sudo ln -s /usr/bin/gcc-4.0 /usr/bin/gcc
You will need to supply your password, since this is in a directory owned by the root user.
Build OpenOCD
Update for Ubuntu 7.10
OpenOCD is now a supported package under Unbuntu 7.10, with the M3 support in it, so you can just install package "openocd" and skip this whole step. If you are running 7.04 or below, carry on reading...
At time of writing, Magnus's Cortex-M3 code is checked in to a branch in the subversion repository, rather than being part of the main development. You therefore need to check it out using Subversion and build it yourself.
To check out, you need to install subversion if you don't already have it - this is a standard Ubuntu package.
To get the source code, create a new working directory and change to it, then type:
svn checkout http://svn.berlios.de/svnroot/repos/openocd/branches/cortex-m3
Change into the cortex-m3 directory. You need to configure the build system. Full details of this are in the OpenOCD documentation, but here is what I used.
./bootstrap
As it says, "Bootstrap generates the configure script, and prepares building on your system".
./configure --enable-ft2232_ftd2xx --with-ftd2xx=/usr/lib/libftd2xx.so
Configure generates the Makefiles used to build OpenOCD. The options specify which interface to use, and where to find the library. Now we're ready to build. Type:
make
You should now be able to check that the executable program has been built by typing:
src/openocd
This should complain about the lack of a configuration file, since we haven't actually made one yet. Luckily for us, Magnus has already done the hard work and put together a template file. It is in the doc/configs directory. Copy it to where openocd expects it to be (i.e. in the current directory):
cp doc/configs/cortex-ft2232.cfg openocd.cfg
Editing the file with my favorite editor, I found that I needed to make a couple of changes on my machine. First, I neede to comment out the line:
working_area 0 0x20000800 0x1200 nobackup
This just needs a # on the front:
#working_area 0 0x20000800 0x1200 nobackup
Second, I needed to reduce the JTAG speed a little to avoid errors. Edit this line:
jtag_speed 6
to read
jtag_speed 10
Running OpenOCD
We are now ready to test the interface. Ensure that the board is not pluged in and start the OpenOCD daemon:
src/openocd
You should see an error message like this:
Info: openocd.c:82 main(): Open On-Chip Debugger (2006-10-12 18:00 CEST) Error: ft2232.c:1032 ft2232_init(): unable to open ftdi device: 2 Error: ft2232.c:1047 ft2232_init(): ListDevices: 0
If you now plug in the board, and start it again, you should see something like this:
Info: openocd.c:82 main(): Open On-Chip Debugger (2006-10-12 18:00 CEST)
This does not return to the command line - it's meant to run as a daemon (you can kill it using Ctrl-C as usual). You can connect to it via telnet to test it out.
Update for 7.04
After upgrading to Kubuntu Feisty (7.04), something odd happened and I could no longer connect. The library continually returned error code 18 ("unknown error") which was very unhelpful.
I tried many things, including debugging into the FTDI library calls without source. Yes, nasty.
In the end, it turned out that something in the USB permissions had changed. I am not sure whether this was my fault, part of the 7.04 update, or something else. Anyway, one thing to try if you find this is to use:
sudo src/openocd
Testing the Connection
Open a second terminal, and type
telnet localhost 4444
You should see:
Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. Open On-Chip Debugger >
And on the original terminal, you should also see the connection go through:
Info: server.c:67 add_connection(): accepted 'telnet' connection from 0
Now we can try a few commands. At the telnet interface, try:
reg
This should show the current state of the registers on the chip.
mdw 0 16
This should show the first 16 words of the flash memory.
exit
Exits from telnet.
Getting Ready to Build Programs
Now we can talk to the board, we need to create some programs to run on it. Here, Martin Thomas's Cortex M3 Projects Page was invaluable. I will leave you to explore that page in more depth, and just give you the step-by-step here.
The latest toolchain from Codesourcery was the one I used (2006q3-26) - select ARM EABI as the target type and IA32 GNU/Linux as the host OS.
Download the zip file to a temporary folder, open a terminal in that folder and extract it using:
tar xvf arm-2006q3-26-arm-none-eabi-i686-pc-linux-gnu.tar.bz2
This will create a large folder under the temporary folder, called arm-2006q3. We need to move this somewhere accessible - I put mine into /usr/local/share:
sudo mv arm-2006q3 /usr/local/share
You can now delete the temporary directory if you wish.
So that the build system can see the compiler, we need to add the /usr/local/share/arm-2006q3/bin directory to your path. You can do this permanently by editing your ~/.bashrc file, and appending this line:
export PATH=$PATH:/usr/local/share/arm-2006q3/bin
Next time you open a terminal, the path will be set so that the binaries can be found. Check this by opening a new terminal and typing
arm-none-eabi-gcc -v
You should see a version message.
Build an Example Program
Download Martin's example source, from here, and extract it into a working folder - by default this is called lm3s811_evalboard. The example files are in the directory lm3s811_evalboard/ev-lm3s811, so change into that.
The OpenOCD debugger interface does not load hex files, so you will have to edit the examples.mk file in this folder to out a binary format instead. Change these lines:
FORMAT = ihex #FORMAT = binary
to
#FORMAT = ihex FORMAT = binary
Let us build the quintessential "hello world" application, which is in the hello directory. Change into there and type
make
The make script should run and after a few seconds you will see that there is a new file in the current folder: main.bin. This is the file you need to upload to the board.
Flash the Chip
If you've followed this through in one go, you will still have the OpenOCD daemon running in another terminal. If not, start it again in another terminal.
In the terminal where you built the example, telnet to the OpenOCD daemon as before:
telnet localhost 4444
Then type the following:
halt
Ensure that the chip is halted - the flash cannot be programmed while it is running.
flash erase 0 0 3
This erases flash bank 0 (the only one), pages 0 to 3 (1 page = 1KiB), which is enough to put the hello world program into. This is important - the flash programming algorithm does not auto-erase for you. Forget this and you will waste hours. I did.
flash write 0 /...path-to.../lm3s811_evalboard/ev-lm3s811/hello/main.bin 0
This writes flash bank 0, from the named file (which must have a fully-qualified path, as far as I can tell), at address 0. After a few seconds, you should see a confirmation message.
reset run
Resets the target and lets it run. You should see "Hello World!" on the display.
exit
Exits you from telnet.
GDB
It is possible to run gdb - the the GNU debugger - on top of OpenOCD. I will post info here when I find out how to make it work reliably.
Thanks
Thanks to Luminary, CodeSourcery, and of course especially to Magnus and Martin, without any whom none of this would be possible.
Errors and Updates
If you find errors, or have new information, then please contact me via the OpenOCD discussion forums on this thread.