Debugging Tools for the ARM Cortex-M3

The first set of chips containing a Cortex-M3 core were delivered by Luminary Micro® as their Stellaris® series of chips. The evaluation boards from Luminary Micro contain an FTDI® 2232 chip The 2232 is a USB to Serial converter chip that also has several bit banging modes that can be used to drive serial bus interfaces. One such interface that the 2232 can drive is a JTAG interface and the Luminary evaluation boards are set up to use the 2232 to drive the JTAG and SWD capability of the Cortex-M3 core.

The Debugging Tools for the Tcl-CM3 project use the FTDI 2232 chip to interface with the JTAG on-chip debugging capability of the Luminary Micro chips. This is accomplished by a set of Tcl packages:

ftd2chan
A Tcl channel driver that interfaces to the D2XX driver available from FTDI.
ftd2jtag
A Tcl package that uses ftd2chan to implement basic JTAG functionality. This package contains commands to drive the JTAG TAP, issue instructions and scan registers.
armdbg
A Tcl package that uses ftd2jtag to allow access to the ARM Debug Access Port. The Debug Access Port is the primary on-chip interface to the debugging facilities of the Cortex-M3.
dbgreg
A Tcl package that uses armdbg to provide symbolic access to the register and fields defined for the Cortex-M3 core and Luminary Micro Stellaris peripherals.
In addition to these packages which form a scripting base, two application programs are available. The first application is called lm3sFlasher and is a program that will burn an ELF executable file into the flash memory of an LM3S chip. The second application is called lm3sBrowser and is a interactive GUI program to read and display the values of the core registers and some Stellaris peripheral registers.

Installation

N.B. in order to use any of the Tcl-CM3 tools you must install the D2XX driver from FTDI. Also note that the instructions that come with the Linux installation for this driver make suggestions regarding mounting the usbfs. I have found the following line for /etc/fstab to work well on my Kubuntu 7.10 installation:
usbfs           /proc/bus/usb   usbfs   busmode=0555,devmode=0666    0     0

lm3sFlasher

The program lm3sFlasher is delivered as a Tcl Starpack. This is a single file x86 Linux executable with no external dependencies other than the D2XX driver. This is the simplest approach to using the tools if all you want to do is flash code into an evaluation board.

lm3sBrowser

The program lm3sBrowser is also delivered as a Tcl Starpack. This program is a simple, interactive GUI program that presents the hardware blocks and registers in a hierarchy. Selecting a block expands the registers and selecting a register will read its value from via the debug port. If the register has bit fields defined for it, then it may also be expanded to show the values of the fields. At this point this is a simple program that only reads registers when they are selected and no writing is supported. The program provides a few controls, such as the ability to halt, resume or reset the core. Note that is its possible to browse the registers without halting the core and when program first connects to a target it does not automatically halt the core.

This program could be enhanced in a number of ways, such as being able to browse the non-automatic variables of a running program by reading the symbol table from the ELF file (via the elf2ral package).

Tcl-CM3 Packages

The Tcl packages in Tcl-CM3 specifically require Tcl version 8.5. I suggest that the easiest way to have a complete version 8.5 environment is to download ActiveTcl® from ActiveState®. To obtain a complete distribution, make sure to download and install the latest version 8.4 release and then download and install the version 8.5 release in the same directory as 8.4.

The ftd2chan package is a Tcl channel driver and is thus written in "C" and is delivered in compiled form for x86 Linux. Source is available via CVS. With the source is a TEA compatible build mechanism and should compile out of the box on the usual suspects of Linux/Unix machines. It may compile under Windows using MSYS, but that has not been tested.

The ftd2jtag, armdbg and dbgreg packages are pure Tcl and need only be placed in a directory that is in your package path or in a directory included in your TCLLIBPATH environment variable. The dbgreg package also depends on TclRAL to store its internal database that maps symbolic register names to physical addresses and you will need to obtain that if you wish to use this package.

Documentation

Future Directions

The first release of the debugging tools contain enough to write simple tool applications. Since memory and registers can be read while the Cortex-M3 core is running, even this simple scripting capability is useful for probing, testing and automation purposes. The dbgreg package needs some additional work to define all the registers for LM3S peripherals. The package contains a complete set of register definitions for the Cortex-M3 defined registers, but only the System Control and Flash Control peripheral blocks are currently defined for the Stellaris chips.

Register Database Schema

The following drawing shows the schema of the internal database used by the dbgreg package.

Register database schema