Saturday, October 17, 2009

CC2430 Debug Protocol, First Notes

by Travis Goodspeed <travis at radiantmachines.com>
with thanks to Peter Kuhar

CC2430 Node

The following are my notes on the debugging mechanism of the CC2430 and other chips (such as the CC2530) from Chipcon using an 8051 core. These notes do not apply to the upcoming CC430. As most of this was written before I implemented the protocol, plenty of errata are likely to exist.

These notes are intended for those who wish to understand how the device is programmed, not for those who merely want a device programmer. See CCFlasher or the GoodFET for that.

Be sure to have a copy of SWRA124, which is the official documentation for this protocol.

Concerning pins, there are three related to debugging. Debug Data (DATA) is a synchronous, bidirectional data line. Debug Clock (DCLK) is its clock, but its edges also control when commands are interpreted, and it is crucial to initializing the chip's debugging unit. The third pin, !RST, puts the chip into a reset state when pulled low, but is also used to start the chip with the debugger enabled. The clock idles low, while !RST idles high. Data is posted during the rising edge, sampled during the falling edge. As there is no equivalent of the SPI !SS pin, it is necessary to dead-reckon commands; a command of incorrect length will cause unneighborly consequences.

To initialize the debugger, pull !RST low while sending two clock pulses on DCLK. It will look something like this,
CC2430 Debug Initialization

The command byte 0x34 looks something like this,
CC2430 Data

Concerning commands, once the debugger has been initialized, the chip will accept a command byte, optionally followed by up to three additional parameter bytes. It will then reply with at least one byte, which might be discarded. Some commands reply with two bytes rather than one.

A command byte is composed of 8 bits. Bits 1 and 0--the least significant--contain the number of data bytes following the command. Bit 2 is labeled "return input byte to host", but it doesn't appear to be observed regularly by the documented examples. The remaining five bits specify the command itself.

Only twelve commands are described in the documentation, but either 16 or 32 commands are possible, depending upon whether the MSBit is variable or fixed to 0 as a sort of start bit.

These commands were chosen to be easy to implement in hardware. They include CHIP_ERASE, RD_CONFIG, WR_CONFIG, HALT, RESUME, GET_PC, and DEBUG_INSTR. There are no primitive commands for peeking or poking memory, nor for managing flash. Instead, macro commands are built up by using DEBUG_INSTR.

Concerning command execution, it is clear from the documentation that a command with no parameters begins to execute at the instant of the eighth falling debug clock edge. Multi-byte commands likely execute on multiple clock edges, each being the last falling edge of an instruction.

In any case, to debug a command, you simply send DEBUG_INSTR (0x54) summed with the length of the instruction, up to 3 bytes, then read a single byte reply. So to execute "NOP", send {0x55, 0x00}. Except for a jump, this will not affect the program counter.

Concerning memory access, there are no debugging commands to read or write memory. Instead, DEBUG_INSTR (0x54) is used to do the same. For example, to fetch from Data memory, first debug {0x90, AH, AL} to move the address into the data pointer. Then debug {0xE0, 0, 0} to MOVX from the data pointer into A. The 0's aren't part of the instruction, but they are necessary to give the device time to fetch the target of the pointer.

The is the code that fetches a byte from Data memory,
cc_peekdatabyte

Concerning the writing of Flash, it is necessary to load a RAM buffer, then to copy that buffer into Flash by use of a short assembly script. Flash may only be erased in 2kB pages, and it may only be written as 32-bit words. The code that performs this is found on page 11 of SWRA124, and you'll find it in Data memory if you look hard enough after a programmer that doesn't cover its tracks.

You will find this code in the GoodFET source.
CC2430 Flash Routine

You will find the same code in RAM after programming.
CC2430 Flash Routine

Concerning the protection of Code memory, there is a lock bit in a hidden page of Flash memory. By setting the lowest configuration bit (by WR_CONFIG), the lowest 2kB of flash memory will be mapped to a special information region. Clearing the least significant bit of the first byte will lock the chip, causing it to refuse debugging after a full-power reset. Access to debugging instructions can only be regained after executing a CHIP_ERASE, which erases all of Flash memory.

At Black Hat USA in August of 2009, I presented a paper entitled Extracting Keys from Second Generation Zigbee Chips. The vulnerability, demonstrated in the image below, is that Data memory is not cleared along with Flash memory during a CHIP_ERASE. By booting a wireless sensor, then erasing it, then dumping RAM, the attacker can find any keys which are stored within the unit. This works even for constant keys, as 8051 compilers will copy them into RAM in order to make C pointers consistent.
CC2430 Vulnerability Test

In implementing a debugger, it's also necessary to watch out for a minor bug. Upon connecting, be sure to DEBUG_INSTR a NOP so as to have the lock bit checked. Failure to do so might cause the lock bit to be misrepresented when checking the device's status.

In conclusion, the protocol is blessedly simple and the 16 pages of documentation are quite complete when supplemented with the CC2430 datasheet. I hope that these notes might allow you to implement the protocol with less of a headache than I have.

7 comments:

tinho said...

Nicely written. I have a new custom board where CC2430 is set to communicate with another CC2430 through the debug interface. The basic idea is that I will be able (hope so) to send .hex -file from PC like TI's Flash Programmer does with Chipcons(TI's) development board. I am just little worry about the coding?!? How long it took from you to code the interface?

Travis Goodspeed said...

Howdy Tinho,

I didn't take too terribly long for me to write the library, but you can grab my code and port it to your board. (BSD License, just leave the copyright statements intact and buy me a beer if we should ever meet.)

--Travis

svn co https://goodfet.svn.sourceforge.net/svnroot/goodfet

Travis Goodspeed said...

Thanks to a neighbor for pointing out that CC2530 and CC2531 extensions are in SWRU191.

andre said...
This comment has been removed by the author.
tinho said...

Hi Travis,

Took me a little time to check this page again. Many thanks for sharing your library. At least your name is easy to remember so I'll by you a beer if we meet:)

aex said...

Fantastic post! Tank you!

Travis Goodspeed said...

For a practical target of this, check out Dave's post on IM-ME Hacking. The CC1110 in the IM-ME is compatible with this protocol.

--Travis