Debugging TMote Sky with GDB

Debugging the TMote Sky with GDB and JTAG

Matt Welsh
December 20, 2005

This page describes the various software tools needed to use GDB with the TMote Sky wireless sensor node from Moteiv, Inc. I have put these tools together in one place to simplify the process of getting GDB working. These instructions are only valid for Linux systems. I am using Fedora Core 3 with TinyOS 1.1.13 and msp430-gcc version 3.2.3. I am not sure what changes are required to get this to work on Windows.

First, grab the tarball of the software here:

mspgdb.tar.gz

To use GDB with the TMote Sky mote, you need two pieces of hardware:

A parallel-port version of the MSP430 Flash Emulation Tool (FET) from TI:
http://focus.ti.com/docs/toolsw/folders/print/msp-fet430pif.html
Note! There is also a USB version of the FET, however, I am not sure whether this works with GDB.
A TMote Sky JTAG Adapter:
http://www.moteiv.com/xcart/product.php?productid=3
This is a small board that attaches to the TMote Sky and plugs into the FET.

Before you begin, read the TMote Sky JTAG Guide here:

http://www.moteiv.com/products/docs/moteiv-an-002.pdf

You will need to solder the small header included with the TMote Sky JTAG Adapter onto the TMote Sky itself, then plug the JTAG adapter into the header. Connect the FET to your PC's parallel port, and the short ribbon cable to the JTAG adaptor on the mote. Be sure you put the connectors on correctly -- see the TMote Sky JTAG Guide above for details.

First, build "libHIL.so" which is required by msp430-gdbproxy. This is a library that provides access to your computer's parallel port.

     cd mspgcc-cvs-8Mar2005/jtag/hardware_access
     make
     sudo cp libHIL.so /usr/local/lib
     sudo chmod 755 /usr/local/lib/libHIL.so
     sudo ldconfig

Be sure that /usr/local/lib is on your LD_LIBRARY_PATH:

     export LD_LIBRARY_PATH=/usr/local/lib

The "msp430-gdbproxy" program included here is a Linux binary that acts as a bridge from the JTAG to GDB. It is a binary because the source code cannot be released under an open license. I obtained this binary using a Google search for "msp430-gdbproxy". There are several binaries floating around; not all versions seem to work with the TMote Sky (which uses the MSP430 F1611 processor).

Test msp430-gdbproxy by running (as root!)

     ./msp430-gdbproxy --port=2000 msp430

You should see something like:

Remote proxy for GDB, v0.7.1, Copyright (C) 1999 Quality Quorum Inc.
MSP430 adaption Copyright (C) 2002 Chris Liechti and Steve Underwood

GDBproxy comes with ABSOLUTELY NO WARRANTY; for details
use `--warranty' option. This is Open Source software. You are
welcome to redistribute it under certain conditions. Use the
'--copying' option for details.

debug: MSP430_Initialize()
About to init '/dev/parport0'
debug: MSP430_VCC(3000)
debug: MSP430_Identify()
info:      msp430: Target device is a 'MSP430F1611' (type 42)
debug: MSP430_Configure()
notice:    msp430-gdbproxy: waiting on TCP port 2000

If it reports "Target device is 'unknown'" then it is possible that the proxy is not detecting your MSP430 processor correctly.

Build gdb. I have provided a version of gdb-5.1.1 that includes the patches for msp430 support from mspgcc.sourceforge.net. (The original patches are in mspgcc-cvs-8Mar2005/gdb).
```
     cd gdb-5.1.1-msp430-patched
     ./configure --target=msp430 --prefix=/opt/msp430
     make
     sudo make install
   
```
Note!! This assumes you already have installed the msp430 binutils and gcc in /opt/msp430. If you have installed msp430-gcc and friends using the script in the TinyOS tree:
```
	tinyos-1.x/tools/src/mspgcc/build-mspgcc
   
```
this will be done for you.

Create the file $HOME/.gdbinit and add to it the following lines:

     set remoteaddresssize 64
     set remotetimeout 999999
     target remote localhost:2000

Create a TinyOS binary of your choice:

     cd tinyos-1.x/apps/Blink

     # Before compiling the program, edit the Makefile and add 
     #    PFLAGS += -g
     # to be sure the binary is compiled with debugging symbols
     # included.

     make telosb

Run GDB with the "main.exe" that results from building the binary:
```
     cd build/telosb
     msp430-gdb main.exe
   
```
Be sure you use msp430-gdb, not plain old gdb.
Now, you need to erase the flash and load the binary onto the mote. Normally you would do this using "make telosb install ...", however, with the JTAG connected to the mote this does not seem to work. Instead, within gdb run the following commands:
```
      (gdb) monitor erase
      (gdb) load main.exe
   
```
This will install the binary on the mote. It will take a LONG TIME (several minutes). You will see msp430-gdbproxy printing out a number of debug messages such as:
```
      debug: MSP430_Memory(WRITE)
   
```
during this time.
Start the program running using the gdb 'continue' command:
```
     (gdb) cont
   
```

You can now do things like:

Hit Ctrl-C to break execution (use "cont" to resume).
Set breakpoints:
```
      break 'LedsC$Leds$init'
   
```
You must use the single quotes around the function name if it contains "$". Note that gdb does not understand NesC. Therefore, the symbols that you use are as they appear in "build/telosb/app.c", which include the $ character as shown above.
Also keep in mind that because NesC inlines many functions, you may not be able to set a breakpoint for a function that no longer exists in the binary.
Look at breakpoints:
```
      info break
   
```
Look at registers:
```
      info reg
   
```
Look at the current stack trace:
```
      where
   
```
Look at the current source code listing:
```
      list
   
```
Look at disassembly:
```
      disass
   
```

You may also wish to install DDD, a nice GUI front-end to GDB. To use it, run

	ddd --debugger msp430-gdb main.exe

Here is a screenshot of DDD being used to debug the TinyOS radio stack on a live TMote Sky:

If you have updates to this information please contact me at the email address found on my main web page. Thanks!