FET Firmware from MSP430.DLL

by Travis Goodspeed <travis at radiantmachines.com>

The firmware of the MSP430 FET is distributed for purposes of upgrades within MSP430.dll. In this brief article, I'll describe its location and a method for extraction.

Firmware as Regions

All of these examples will use MSP430.dll with the following checksum. My previous FET articles have used a firmware image from the last revision of libMSP430.so, so addresses and code fragments will differ slightly.
f0685a0eca0545dfc542530afff8159f



A bit of quick searching reveals that the firmware of the MSP430 FET is contained within MSP430.dll as little-endian words at these addresses.
Bootloader code at offset of 0x1BFE8, region [0xF800,0xFFE0).
Application code at offset of 0x1EB38, region [0x2500,0xF7E0).
IVT at offset of 0x1BDBC, region [0xFFE0,0xFFFF].

That is, to recover the bootloader, copy 32 bytes (0x10000-0xFFE0=0x20) from the DLL at (0x1BDBC+0xFFE0=0x2BD9C) offset to the target MSP430 image at 0xFFE0.

Below are memory maps of my first attempt at extraction and an old EZ430 FET. It's clear that a lot of junk has been included by accident, which is why tabular entries, rather than regions should be used.



In addition to the large segments, there are also a few scattered bytes that form the lower IVT. (See Repurposing the TI EZ430U, Part 3 for an explanation of why there are two Interrupt Vector Tables.) Because the lower IVT is sparse, only those words which are not 0xFFFF are included. For example, the lower RESET vector--which, incidentally, is never read by the bootloader, in which the lower RESET is hard-coded--resides at 0xF7FE and points to 0x2502.

Searching MSP430.DLL for the interrupt vector, "02 25", yields a few results, one of which is "fe f7 d9 02 02 25". That's quite clearly an entry in a table of some sort. Searching around it yields a few more entries.

Firmware as a Table

By this point is should be clear that while it might be possible to extract the different fragments of the firmware manually, it would by much nicer to dump the whole damned thing as a table. This can be done.

Each entry is of the form {adr, len, data} where adr is the 16-bit address of the fragment within the firmware image, len is the length of the data in 16-bit words, and data is a collection of 16-bit words as little-endian. Following one entry is another, ending with an invalid address. (Anything less than 0x200 is I/O, anything less than 0x2500 is not flash.) Adding 4+(len<<1) to an entry's pointer gives the next entry.

Using this technique and finding an initial entry point of 0x21036, I generated a dump that produces the following image (left) as compared to the previous attempt (right).


The new attempt contains everything important, including a few bytes which were missed in the first attempt. It also lacks all of the vestigial bytes that got roped in by the previous method. Further, as each binary is defined by a single entry point, it shouldn't be terribly difficult to search for the entry point in order to generically dump any version of the library.

This cleanliness is confirmed by the callgraph below, which properly shows no function calls between the bootloader (right) and the application (left). (Branches are not graphed.)

The Code

The MSP430 Flash Emulation Tool's firmware is available for free download in MSP430.DLL, and anyone wishing to experiment with it need only download the library and extract the code.

A hastily written extraction utility can be found by subversion. A screenshot follows.
svn co https://goodfet.svn.sourceforge.net/svnroot/goodfet/contrib/fetextract

Improving the MSP430 FET

by Travis Goodspeed <travis at radiantmachines.com>



To celebrate 4/30 day, I am happy to announce my own variant of the MSP430 FET debugger. My variant is compatible with a patched version of the original firmware, but my goal is to eventually have open firmware as well.

For an overview of the internal functioning of the original FET, see my three part series on Repurposing the EZ430, or torrent my 25C3 lecture on the same topic.

For the purposes of this discussion, a FET is any Flash Emulation Tool containing an MSP430F1612, including the FET UIF and EZ430 debuggers. The parallel-port FET operates differently and is outside the bounds of this discussion.

To follow along with this discussion, be sure to print the FET schematics from the relevant TI application notes. The FET UIF's schematic can be found on page 64 of SLAU138K. Version 1.0 of the EZ430U can found on page 12 of SLAU176B, while Version 2.0 can be found on page 13 of SLAU227B. As I've likely made a few mistakes in the write-up, please kindly inform me of them.

FT232 for TUSB3410

All present FETs use the TUSB3410 usb to serial converter. Support for this chip is a pain in Linux, with kernel module requirements varying often. It's so bad that I keep a script in my private svn repository for fixing support as quickly as possible, and despite the recent appearance of open FET clients, using them on an obscure operating system is impossible without kernel support.

Internally, the '3410 is an 8051 microcontroller with a USB 2.0 Full Speed (12Mb/s) peripheral and a single UART. The traditional FET and most other devices use this chip with its default usb/serial firmware, but the second-generation EZ430 firmware uses various tricks to make a second, bit-banged, asynchronous serial port to the debugging target. On Windows, this leads to reliability issues, and on Linux, this leads to utter incompatibility. The '3410 also requires several external components, complicated the design and making hand soldering less feasible.

The FT232R from FTDI is a perfect replacement. It is available in an SSOP28 package for easy soldering, every operating system on Earth supports it, and its only external components are decoupling capacitors.

Bootstrap Loader

The MSP430 Bootstrap Loader (BSL) and I have had some good times together. While I still consider it to be a security risk for locked devices, it's damned handy for an unlocked board such as the FET. Likely for historical reasons, the BSL runs on P1.1 and P2.2, rather than the hardware UART pins. It also requires a special reset sequence, in which the RTS and DTS serial lines are connected to the RST and TCK pins.

Early revisions of the FET did not connect the BSL I/O pins, making the software bootloader that I describe in my articles on the EZ430 necessary. (The FET and first-generation EZ430 share a flash bootloader, while the second-generation EZ430 has a different, larger bootloader.) While later hardware revisions of the UIF connect the BSL pins, I've not seen the masked-ROM BSL used in practice. My design supports the BSL, preventing bricking and allowing for TI's firmware and open firmware to be exchanged at a whim.

To program the board by BSL, use tos-bsl with the --invert-reset and --invert-test switches.

MSP430F1612/1611

The MSP430F1612 was chosen for compatibility with the original FET. It has 55K of flash and 5K of RAM. Alternately, the MSP430F1611 with an identical footprint might be used for applications which require additional RAM but are willing to use less flash, at the expense of compatibility with the original chip. (MSP430 firmware grows upward from the bottom of flash memory, making it easy to port code from a device with less flash to a device with more, but difficult to port in the opposite direction.)

All custom firmware should be compiled to run in the intersection of memory of the two chips. In that way, most applications will run on either chip, with only those that need more stack depth requiring the 1611 and only those requiring more flash memory requiring the 1612.

Crystals

The MSP430 supports both high-speed and low-speed crystals, with the low-speed crystal's frequency being multiplied. Stable timing is not necessary for synchronous protocols such as JTAG or Spy-Bi-Wire, but only for asynchronous serial communication. While the EZ430 and FET firmwares both demand high-frequency crystals for absurdly high serial baud rates, I expect to reduce the data rate and source an external low-frequency crystal to reduce the parts count.

It is also possible to use bit-banged serial, or to call bit-banging serial routines from the bootloader (BSL) ROM. The BSL's code is particularly elegant because it resyncs the timing with the 0x80 SYN byte. This byte in 8/E/1 (8 bits, Event parity, 1 stop bit) appears as 8 marks surrounded by spaces, so rather than being read it is measured. The measured width is right shifted three times to get a bit's width, then once more for a half-bit. This measurement is used to bit-bang one transaction, then a new measurement is made for the next transaction. In this manner, even without a crystal, the BSL is able to perform fast, reliable serial communication in spite of clock drift. By calling this code--which is already resident in each chip--crystal-free operation is possible.

A high-frequency crystal is required to run unpatched variants of TI's firmware, but I've decided against including one in the design at this stage. Perhaps this will change in the future.

I/O Pins

The first four pins of P5 are used as JTAG and SBW I/O. Starting with P5.0 and continuing to P5.3, they are TMS, TDI, TDO, and TCK. I've chosen to omit the FET UIF's optical isolation in favor of the EZ430's simpler protection, which consists of 47K pull up resistors and 100R current-limiting resistors. Unlike the EZ430, which only support spy-bi-wire, my design has a full 14-pin JTAG connector.

Firmware, Old

The above image is the firmware of an EZ430U FET, generated by msp430static. 0x0000 is the bottom left corner, 0xFF00 the top left, and 0xFFFF the top right. Blue represents the target of an immediate pointer, black is empty flash memory, red is potentially executable code, and grey is information which is certainly not executable.

The image is composed of two parts. The upper red region is a bootloader which is used to reflash the chip, while the lower region does the actual work. As compilers ship with firmware upgrades, it is not necessary to distribute any copyrighted code. A replacement bootloader could accept a firmware upgrade, then patch it, while retaining software compatibility. More information on the bootloader can be found in Part 3 of my series on repurposing the TI EZ430U.

Firmware, New

Ideally, replacement firmware will be written for various applications, beyond MSP430 debugging. The same hardware could program competing microcontrollers, serial eeproms, FPGAs, and all sort of other things in the same way that the Hackaday Bus Pirate does.

So far as replacement firmware for debugging MSP430 chips goes, documentation is slim. Enough of the JTAG protocol has been documented to implement programming, but the setting of hardware breakpoints and other advanced features are not described by any public documentation. Custom firmware is not yet functional, but that ought to change in the near future.

Second Serial

The red board variants of the EZ430, those shipping with the RF kits, use drastically different firmware to facilitate a second serial port that connects to the target board. This breaks Linux compatibility, requiring firmware of both the MSP430 and the CAT24 EEPROM of the board to be downgraded.

To support low voltage serial communications, I brought out the second UART of the board's MSP430 to test points. This might also be used for timing attacks or similar things. Series and pull-up resistors would be nice on these lines, but they were omitted in the first design.

Availability

I've ordered a panel of the first revision, GOODFET10, and I'll send a board to anyone who is willing to assemble the device and help construct its firmware. Schematics, gerbers, and construction details have been posted to http://goodfet.sourceforge.net/, and "hello world" firmware has already been committed to the subversion repository.

An Open GDBProxy!

Howdy everybody,

Rob Spanton and Tom Bennellick have recently released fetproxy, an open-source replacement for gdbproxy. They reverse engineered the protocol the week before I did, and their implementation--unlike mine--acts as a replacement for gdbproxy. They also managed to get approval from Texas Instruments, which is quite neighborly indeed.

I'll be closing up my msp430fet project, which was only intended as a stop-gap until Rob and Tom were able to make their release. The final state will be a standalone C client for programming; I won't be adding support for debugging.

--Travis

Implementing the MSP430 FET Protocol

by Travis Goodspeed <travis at radiantmachines.com>
continuing initial observations.

Following a comment posted to the prior article, I discovered that, as suggested, the PPP FCS-16 checksum is the one used for communicated with the FET. Searching MSP430.dll for the initial bytes of the checksumming table which is presented on Section C.2 of RFC1662, yields the following table,


The 16-bit entries from the table appear as little endian, so {0x1189, 0x2312} becomes {0x89, 0x11, 0x12, 0x23}. Running a quick test with the RFC's FCS-16 code yields a proper checksum, with which messages can be signed.

The result of this is an open source too, MSP430FET, for programming chips with the MSP430 FET tools. The present version can read and write memory, but it is limited to spy-bi-wire and is unable to erase memory. Expect those features, and a website, in a later revision.

svn co https://msp430fet.svn.sourceforge.net/svnroot/msp430fet/trunk msp430fet

Sniffing the MSP430 FET Protocol

by Travis Goodspeed <travis at radiantmachines.com>
regarding his independent recreation of anonymous, unpublished by other neighborly fellows. update: see here for the original implementation.

As the MSP430's gdbproxy relies upon closed-source libraries, which are not available for platforms other that Windows and i386 Linux, it would be valuable to generate an open-source alternative. Further, these closed libraries do not allow the debugging of all MSP430's. As reverse engineering the protocol by code review would be prohibitively complicated, grabbing serial traffic is an effective alternative. The following method allows for the dumping of serial frames for later analysis.

It is also a worthy goal to reverse engineer the proprietary aspects of TI's JTAG standard, but that is not the subject of this article. Here I will only investigate the protocol between a workstation and the MSP430 JTAG tool.

The simplest means of doing so is by using LD_PRELOAD to proxy--and print--calls to the write() and read() methods. To do so, I authored serspy.

Serspy works by proxying each call to the read() and write() system calls. For example, to trap the write() command,

//trap the write command
static ssize_t (*_write)(int fd, const void *buf, size_t count)=0;
int write(int fd, const void *buf, size_t count){
  int num;
  
  //This grabs a pointer to the original function.
  if(!_write)
    _write=(ssize_t (*) (int fd, const void *buf, size_t count)) dlsym(RTLD_NEXT,"write");
  
  //Now really write.
  num=_write(fd,buf,count);
  
  //And log it.
  logdataw(fd,buf,count);
  return num;
}

The code above is a replacement for the write() function which uses dlsym() to request a pointer to the original write() function, to which it forwards the call before logging it. As msp430-gdbproxy doesn't link against libdl and it is a 32-bit application, LD_PRELOAD must be set to ``./serspy.so:/usr/lib32/libdl.so''. Further, serspy.so itself must be compiled with the -m32 switch on 64-bit workstations.

Consider an example transaction, such as

W  7e 01 01 16 07 7e
R  0c 00
R  01 02 00 00 01 00 50 9e 98 00 67 4b

Writes (W) from the workstation begin and end with 0x7e, which never appears within the request. An encoding method of some sort is used to remove them. Reads (R) from the FET device begin with a 16-bit, little endian length. Following this length are the bytes themselves.

Consider also the following Writes, all of which are fetches for memory.

x/h 0x0200
7e 0d 02 02 00 00 02 00 00 02 00 00 00 b0 17 7e
x/h 0xfc00
7e 0d 02 02 00 00 fc 00 00 02 00 00 00 c0 06 7e
x/h 0xfc02
7e 0d 02 02 00 02 fc 00 00 02 00 00 00 af 0d 7e

All addresses are found intact as little endian: "00 02" for 0x200, "00 fc" for 0xfc00, and "02 fc" for 0xfc02. That won't be true for bytes which contain illicit characters, as I'll demonstrate later. Also note that the final two bytes of each message vary drastically; these are most likely a checksum of some sort.

Regarding the checksum, there are two common possibilities. The first is a CRC16 checksum, while the latter is the XOR of all transmitted bytes. The MSP430's serial bootstrap loader uses the latter method, but it is easy to rule out here. As the examples above for fetching 0xfc00 and 0xfc02 differ by only one bit apart from the checksum, yet the checksums show no resemblance, this checksumming function must be more complicated. A solution to the checksumming problem will be presented in a later article.

Illicit characters are dealt with by escaping. Consider the following queries,

x/h 0xeeee
7e 0d 02 02 00 ee ee 00 00 02 00 00 00 5c ac 7e
x/h 0xee7e
7e 0d 02 02 00 7d 5e ee 00 00 02 00 00 00 c6 3c 7e
x/h 0xee7d
7e 0d 02 02 00 7d 5d ee 00 00 02 00 00 00 16 b6 7e
x/h 0xee7f
7e 0d 02 02 00 7f ee 00 00 02 00 00 00 79 bd 7e
x/h 0xee7c
7e 0d 02 02 00 7c ee 00 00 02 00 00 00 a9 37 7e

From this it can be seen that 0x7d is the escape character, and that 0x7d and 0x7e are the characters to be escaped. Each is escaped by following 0x7d with either 0x5e or 0x5d, taking the lesser nybble.

Performing a few more queries exposes the length field of the memory read, as queries for 2, 1, and 4 bytes yield

x/h 0xeeee
7e 0d 02 02 00 ee ee 00 00 02 00 00 00 5c ac 7e
x/b 0xeeee
7e 0d 02 02 00 ee ee 00 00 01 00 00 00 91 89 7e
x/w 0xeeee
7e 0d 02 02 00 ee ee 00 00 04 00 00 00 c6 e7 7e

The first byte after the frame-start is 0xd, which is also the first byte of the response. Taking this further, a command/response code can be discovered, which is the first byte of both the encapsulated request and the response. In the follwoing case, an examine query has the code 0x0d while the set query has a code of 0x0e.

set *0xffd0=0xdead
W  7e 0e 04 01 00 d0 ff 00 00 02 00 00 00 ad de 49 6e 7e
R  06 00
R  0e 00 00 00 9c 52
x/h 0xffd0
W  7e 0d 02 02 00 e0 ff 00 00 02 00 00 00 4d b6 7e
R  0c 00
R  0d 03 00 00 02 00 00 00 ff ff 03 b8

This series will be continued once the checksumming routine has been reimplemented, at which point a custom client may be written.

See this post for details on my implementation.