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:

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.

  1. 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
       

  2. Be sure that /usr/local/lib is on your LD_LIBRARY_PATH:
         export LD_LIBRARY_PATH=/usr/local/lib
       

  3. 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.

  4. 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.

  5. Create the file $HOME/.gdbinit and add to it the following lines:
         set remoteaddresssize 64
         set remotetimeout 999999
         target remote localhost:2000
       

  6. 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
       

  7. 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.

  8. 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.

  9. 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!