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

Speaking at 25C3

At the 25th Chaos Communications Congress in Berlin this December, I'll be presenting some new research in the security of the MSP430's serial bootstrap loader (BSL) as well as a nice little lecture/workshop combo on reverse-engineering the TI EZ430 development tool.

I intend to travel through France and England, returning in late January for S4, Miami. Please email me if you'd like to meet.

Cracking the MSP430 BSL
Day 1 (2008-12-27), 20h30 (8:30 pm) in Saal 3.

The Texas Instruments MSP430 low-power microcontroller is used in many medical, industrial, and consumer devices. When its JTAG fuse is blown, the device's firmware is kept private only a serial bootstrap loader (BSL), certain revisions of which are vulnerable to a side-channel timing analysis attack. This talk continues that from Black Hat USA by describing the speaker's adventures in creating a hardware device for exploiting this vulnerability.

While the previous part focused on the discovery of the timing vulnerability and its origin, this lecture will focus on the exploitation. Topics include a brief review of the vulnerability itself, PCB design and fabrication, the malicious stretching of timing in a bit-banged serial port, observation of timing differences on the order of a microsecond, and the hell of debugging such a device.

Repurposing the TI EZ430U
Lecture: Day 3 (2008-12-29), 12h45 (pm) in Saal 3
Workshop: Not yet scheduled.

USB devices are sometimes composed of little more than a microcontroller and a USB device controller. This lecture describes how to reprogram one such device, greatly expanding its potential.

At only twenty dollars, the Texas Instruments EZ430U is a bargain of an in-circuit debugger for the MSP430 microcontroller. The board itself is composed of little more than an MSP430 and a USB to Serial controller. The board's JTAG fuse is unblown, and full schematics are included in public documentation. This lecture will discuss the use of the EZ430U, not as a debugging tool, but as a development platform in and of itself. Topics will include the writing of replacement firmware, analysis of the default firmware, reprogramming the USB to Serial controller, and potential target applications.

--
Travis Goodspeed
<travis at radiantmachines.com>

Repurposing the TI EZ430U, Part 3

by Travis Goodspeed <travis at utk.edu>
of Southern Appalachia



The first installment of this series described a method of accessing the EZ430's MSP430 firmware by way of JTAG, while the second installment took a detour to discuss the TUSB3410 usb controller of the board. This third installment is concerned with the analysis of the green EZ430U firmware; that is to say, it is concerned with the firmware of the six-pin EZ430f2013 kit, which might differ from the four-pin EZ430f2013 kit and drastically differs from the red EZ430rf2500 kit.

Section 1, wherein we make general, even visual observations regarding the organization of firmware, as well as the locations of important objects.

Observe the following memory map, which was generated by the .memmap.gd.xview macro of msp430static.

In an m4s memory map, the X axis represent the less-significant byte while the Y axis represents the more significant byte. 0xFF00 would be the top left, and 0xFFFF would be the top right. As the interrupt vector table (IVT) of the MSP430f1612 ranges from 0xFFE0 to 0xFFFF, it appears as a green band in the upper right of the image. Entries within it all point to the upper red band, with addresses varying from 0xfb78 to 0xfdb0, in regular increments of 4. The only exception to this rule is the RESET vector at 0xfffe, which points to 0xfdaa.

Why such an arrangement? Each of these regularly-spaced interrupt handlers is a branch to a lower interrupt handler. The blue line that you see at the top of the black expanse is a second IVT, entries of which are called from above. 0xffe0, the DMA vector, point to a branch to &0xf7e0, which is to say that address which is contained within 0xf7e0. Similarly, 0xffe2 points to a branch to 0xf7e2. In fact, every interrupt except for RESET points to nothing but a branch to its equivalent in the table that begins 0xf7e0.

It should be clear, then, that not one but two programs reside in this image. The first-stage firmware, which rests at the top of memory, performs its own initialization when the chip is reset, but differs all interrupt handling to the lower firmware, which grows from the beginning of flash to 0xf7e0. It shouldn't be hard to instruct a compiler to build a second-stage firmware compatible with the first-stage, but it would be imprudent to spring into such a task without at least a casual analysis of the first stage.

Section 2, wherein we examine the first-stage firmware in depth.

The first-stage firmware is a bootloader which resides from 0xf800 to 0xffff in flash memory of an MSP430F1612. A quick search with MSP430static--which I'll refer to as 'm4s' for the sake of brevity--reveals that 30 functions have been found in this area. Fifteen of these, those in the range [0xfb78,0xfbb0], are merely branches to interrupt handlers in lower memory. The interrupt handler is a function which I'll call init() that resides at 0xfdaa, calling a config() function at 0xf828 to set registers to their proper values. The only call made by config() is to delay() at 0xf812 that uses nested loops to implement a timing delay.

I/O is performed by putbyte() and getbyte() functions at 0xfbc6 and 0xfbd2 respectively. These use USART0 in UART mode. This port is configured, as are many other peripherals, in the previously mentioned config() function.

As the purpose of this series of articles is to describe the process for writing a complete replacement firmware, I should mention that such information is to be found within this stage. Port 3 is especially important, as it is tied into both UARTS and I2C. As you'll recall from the early articles of this series, the TUSB3410 refuses to load with ports in the default configuration. By matching the configuration of the original firmware, we ought to be able to get something going.

To that end, Port 3 is configured as follows within the config() function.

f88e: bis.b #48, &P3SEL
f894: bis.b #16, &P3OUT
f89a: bis.b #16, &P3DIR

Clocks and such must also be reconfigured, but I come bearing good news! There's an easier way, in that by relocating the IVT or reconfiguring your compiler, you can generate a custom second stage firmware without rewriting the first stage.

Section 3, wherein we examine the second-stage firmware in brief.

By comparison to the simple, neighborly firmware of the preceding section, the second stage firmware is gigantic and multi-tasking, with a rats-nest of function calls to a few key functions. Although it serves little immediate value, I'll cover second stage as an example of a few analysis techniques.

Which function calls are most popular, and what do they do? The .calls.top10 macro results in the following:

163     4c3e    4c3e
151     4f54    4f54
142     4b6a    4b6a
29      4eca    4eca
28      6100    6100
27      2ba2    2ba2
24      8d0e    8d0e
24      a784    a784
20      5f4c    5f4c
17      756e    756e

Note the sharp dropoff after the third. In a multi-tasking application, such as a TinyOS wireless sensor node, it would be logical to assume these to be mutex locks. In a JTAG adapter, however, it is much more likely that these serve an I/O purpose. Sure enough, all three are I/O related with 0x4f54 performing I/O through function calls and the other two doing it directly.

As I am not concerned with reverse-engineering the TI's proprietary debugging protocol, but rather only with making software capable of running on the EZ430 programmer, I'll delve no further into the second-stage firmware. Remember only the following: (1) That the IVT of the second-stage code resides at 0xf7e0, (2) that all else remains unchanged.

The question then becomes one of relocating the IVT, which may be accomplished either by altering linker scripts or by rewriting the firmware image before flashing it to the device. We shall begin with the prior method.

Section 4, wherein we rewrite the linker scripts of two popular compilers so as to generate our own second-stage code for this fine platform.

Moving the IVT is accomplished in GCC by forking msp430x1612.x to ez430u.x, then changing line 8 to the following:

vectors (rw) : ORIGIN = 0xf7e0, LENGTH = 0x20

Call GCC with the -T switch followed by your forked linker script, and the output will direct to the proper address. Use msp430-objdump to verify the address in your output. For further details, consult my article on Retargetting the MSPGCC Linker. In the case of the IAR compiler, the IVT range is defined near the end of lnk430F1612.xcl.

Please note that, for no reason that I can fathom, the RESET vector of the second-stage IVT has been hard-coded to be 0x2502 in some places. You must set the .text section to begin at 0x2502, or the reset will land in the middle of a two-word instruction.

Section 5, wherein your author makes a shameless plug his upcoming appearance at the tenth annual Toorcon San Diego but provides little else of substance.

A fourth installment of this series will wrap up the replacement MSP430 code, concluding with a complete and commented `hello world' example for GCC.

Repurposing the TI EZ430U, Part 2

by Travis Goodspeed <travis at utk.edu>
at the Extreme Measurement Communications Center
of the Oak Ridge National Laboratory




Section 1, wherein topics of discussion are enumerated and datasheets cited.

The first installment of this series described a method of accessing the EZ430's MSP430 firmware by way of JTAG. That's dandy, but the MSP430 isn't the only microprocessor on the board! This installment will focus on the firmware and reprogramming of the TUSB3410 USB to serial chip, which contains an 8052 microprocessor core.

Section 11 of SLLS519 describes the boot sequence of the TUSB3410. In brief, an I2C EEPROM is used if such a chip is present and it contains an image with the proper signatures. Firmware may also be loaded over USB, in which case the EEPROM is either absent or provides only such minutia as the device ID.

The EEPROM on the Revision 2.0 boards--those with six pins for the target device--is the CAT24C32 by Catalyst Semiconductor. Revision 1.1 used the smaller CAT24C16 chip, presumably because that revision had no need for such complicated software. (See Part 1 for details.)

Section 2, wherein firmware is forcefully extracted by use of hypodermic syringe and our heroes contemplate an intriguing fragment of a schematic diagram.

The 24C32 chip, like all I2C devices, uses two lines for communication. These are SDA and SCL. Addressing lines, allowing for multiple units of the same chip to reside on a board, are unused and tied to ground. Thus, the chip looks something like the following schematic.



To read the chip, it is necessary to have an I2C host adapter, such as the Total Phase Aardvark. So as to avoid soldering headers to the chip, I attached two of my syringe logic probes to the Aardvark's SDA and SCL lines. Power was shared through USB, negating the need to tie it into the target board. I tapped an unlabeled via near R23 for SDA and tapped SCL directly on a leg of the EEPROM. I2C's multi-master feature allows this to be done without disabled anything in the board.

Section 3, wherein our heroes--having extracted the firmware of the 24C32 of the EZ430U--conspire to similarly free the firmware of an I2C EEPROM of a much finer vintage.

Dumping firmware from similar chips on the green EZ430U and a USB-FET gave samples for comparison. The contents of the green board and the FET were nearly identical, differing only by a few bytes. They are also significantly smaller than the red firmware, even though the FET contains a larger EEPROM. Unused bytes are padded as 0xFF.

The most common complaint regarding the EZ430-RF series is that, unlike the original EZ430, there exist no Linux drivers for the board. By reflashing the firmware of both the MSP430 and the 24C32 chips, a red EZ430 can be reverted to the green firmware, making it compatible with Linux.

For those without access to an I2C programmer, it is worth noting that the MSP430 of this board is tied to the 24C32 EEPROM. It is possible to write an MSP430 firmware image that, upon booting, does nothing but reprogram the TUSB3410's ROM.

Section 4, wherein your esteemed author prematurely concludes this article of the series.

The third installment contains instructions for compiling new firmware for the EZ430 by retargetting GCC and manually linking in the USB bootloader.

Repurposing the TI EZ430U, Part 1

by Travis Goodspeed <travis at utk.edu>
at the Extreme Measurement Communications Center
of the Oak Ridge National Laboratory



Lately I've been playing with the EZ430U, which is the adapter that ships with the TI EZ430 kits. The kits are an amazing deal, $20 gets you a spy-bi-wire MSP430 FET, while $50 gets you a similar FET with two wireless sensor nodes. Page 13 of SLAU227 contains the schematic diagram for Rev 2.0 of the MSP430U board, which ships packages as both the classic EZ430f2013 and the new EZ430rf2500; the only hardware difference is the color of the board, being green or red respectively.

The software differences, however, aren't so forgiving. While the classic kit readily creates a USB->serial device under Linux, the RF kit is as yet unusable in Linux as the interface was altered to support a second serial line, one to target board.

Each kit is composed of two types of boards, a programmer (EZ430U) and a target (RF2500T or T2012). While the target boards are a lot of fun, an email I received after my initial release of msp430static introduced me to something just as fun. Namely, the JTAG fuse of the EZ430U board is left unblown. The following diagram shows pin connections from the row of 5 testpoints on the side of the board.

The lack of a common ground is no problem, as ground and power both come from the same computer through USB. You'll need a proper JTAG FET; another EZ430 won't do. (The EZ430 programmer only supports spy-bi-wire; it cannot program traditional JTAG boards.)

Having ripped the firmware from both the RF kit and the 2013 kit, I thought it might be interesting to compare the two. For a brief visual comparison, consider the following memory maps. The first is of an EZ430U from a classic 2013 kit, the second is of the EZ430U from an RF kit.

Taking the difference of the two images yields

The lowest bands of the image, being ram and I/O, ought to be ignored. Still, higher memory makes it visually clear that the firmware images are different. Comparing library checksums confirms this: few functions are identical between the two revisions.

The RF firmware reports itself to the USB controller as "0451:f432" while the classic board reports itself as "0451:f430". The identification appears must reside in the ROM of the 3410 chip, as the RF variant identifies itself as f432 even when loaded with the classic variant's firmware.

The second installment of this series continues with details of the TUSB3410 firmware, which resides on an EEPROM.

TI EZ430 in Linux with IAR Kickstart

by Travis Goodspeed [travis at utk.edu]
at the Extreme Measurement Communications Center
of the Oak Ridge National Laboratory


What follows are instructions for running the free version of IAR's C compiler for the MSP430 with Texas Instruments' EZ430 development tool in Linux under Wine. This will not work for Mac OS X until msp430-gdbproxy is made available for that platform. Also, this might not work with the full version of the compiler.

These instructions assume that you've installed wine, mspgcc, and msp430-gdbproxy. The assumption is also made that you've purchased the EZ430-F2013 development tool from Texas Instruments.

IAR Embedded Workbench

First, download slac050q.zip from the EZ430-F2013 page. Unzip it to get FET_R510.exe. Running wine FET_R510.exe installs the compiler to your C: drive under wine.



Next, you must find the executable and run it.

karen% find ~/.wine/drive_c -name icc\*.exe
/home/travis/.wine/drive_c/Program Files/IAR Systems/Embedded Workbench 4.0/430/bin/icc430.exe
karen% wine "C:\Program Files\IAR Systems\Embedded Workbench 4.0\430\bin\icc430.exe"
  IAR MSP430 C/C++ Compiler V4.09A/W32  [Kickstart]
  Copyright 1996-2007 IAR Systems. All rights reserved.

Available command line options:
--char_is_signed
               'Plain' char is treated as signed char
--core {430|430X}
               The processor core
                  430       (default)
                  430X    
--data_model {small|medium|large}
               Select data model (only for 430X core)
                  small      Small model
                        16 bit registers. __data16 default. (default)
                  medium     Medium model
                        20 bit registers. __data16 default. __data20 allowed.
                  large      Large model
                        20 bit registers. __data20 default. __data16 allowed.
--debug
-r              Insert debug info in object file
--dependencies=[i][m] file|directory
               List file dependencies
                  i     Include filename only (default)
                  m     Makefile style
--diagnostics_tables file|directory
               Dump diagnostic message tables to file
--diag_error tag,tag,...
               Treat the list of tags as error diagnostics
--diag_remark tag,tag,...
               Treat the list of tags as remark diagnostics
--diag_suppress tag,tag,...
               Suppress the list of tags as diagnostics
--diag_warning tag,tag,...
               Treat the list of tags as warning diagnostics
--discard_unused_publics
               Discard unused public functions and variables (experimental)
--dlib_config pathname
               Specify DLib library configuration file
--double {32|64}
               The size of the double floating point type
                  32     32 bits (default)
                  64     64 bits
--ec++          Embedded C++
--eec++         Extended EC++ (EC++ with templates/namespaces/mutable/casts)
--enable_multibytes
               Enable multibyte support
--error_limit limit
               Stop after this many errors (0 = no limit)
--header_context
               Adds include file context to diagnostics
--library_module
               Make a library module
--lock_r4       Exclude register R4 from use by the compiler
--lock_r5       Exclude register R5 from use by the compiler
--mfc           Enable multiple file compilation (experimental)
--migration_preprocessor_extensions
               Enable IAR migration preprocessor extensions
--misrac        Enable MISRA C diagnostics (not available)
--misrac_verbose
               Enable verbose MISRA C messages (not available)
--module_name name
               Set module name
--no_code_motion
               Disable code motion
--no_cse        Disable common sub-expression elimination
--no_fragments  Do not generate section fragments
--no_inline     Disable function inlining
--no_path_in_file_macros
               Strip path from __FILE__ and __BASE_FILE__ macros
--no_tbaa       Disable type based alias analysis
--no_typedefs_in_diagnostics
               Don't use typedefs when printing types
--no_unroll     Disable loop unrolling
--no_warnings   Disable generation of warnings
--no_wrap_diagnostics
               Don't wrap long lines in diagnostic messages
--omit_types    Omit function/variable type info in object output
--only_stdout   Use stdout only (no console output on stderr)
--output file|path
-o file|path    Specify object file
--pic           Generate position independent code
--preinclude filename
               Include file before normal source
--preprocess=[c][n][l] file|directory
               Preprocessor output
                  c     Include comments
                  n     Preprocess only
                  l     Include #line directives
--public_equ symbol[=value]
               Define public assembler symbol (EQU)
--reduce_stack_usage
               Reduce usage of stack at the cost of larger and slower code
--regvar_r4     Allow register R4 to be used as a global register variable
--regvar_r5     Allow register R5 to be used as a global register variable
--remarks       Enable generation of remarks
--require_prototypes
               Require prototypes for all called or public functions
--save_reg20    Save 20-bit registers in interrupt functions
--silent        Silent operation
--strict_ansi   Strict ANSI rules
--warnings_affect_exit_code
               Warnings affect exit code
--warnings_are_errors
               All warnings are errors
-D symbol[=value]
               Define macro (same as #define symbol [value])
-e              Enable IAR C/C++ language extensions
-f file         Read command line options from file
-I directory    Add #include search directory
-l[c|C|D|E|a|A|b|B][N][H] file|directory
               Output list file
                  c     C source listing
                  C        with assembly code
                  D        with pure assembly code
                  E        with non-sequential assembly code
                  a     Assembler file
                  A        with C source
                  b     Basic assembler file
                  B        with C source
                  N     Don't include diagnostics
                  H     Include header file source lines
-O[n|l|m|h|hs|hz]
               Select level of optimization:
                  n   No optimizations
                  l   Low optimizations (default)
                  m   Medium optimizations
                  h   High optimizations
                  hz  High optimizations, tuned for small code size
                  hs  High optimizations, tuned for high speed
                      (-O without argument) The same setting as -Oh
-s{0-9}         Optimize for speed:
                  0-2   Debug
                  3     Low
                  4-6   Medium
                  7-9   High
-z{0-9}         Optimize for size:
                  0-2   Debug
                  3     Low (default)
                  4-6   Medium
                  7-9   High
karen%

The usage information will be valuable, but is too long to scroll through. Pipe it to a textfile for later reference. Also, make some symlinks to more easily get at include files and the documentation:

karen% sudo ln -s /home/travis/.wine/drive_c/Program\ Files/IAR\ Systems/Embedded\ Workbench\ 4.0 /opt/IAR
karen% ls /opt/IAR/430/doc/
EW430_AssemblerReference.pdf  HelpMISRAC.chm              embOS_IAR_plugin.pdf
EW430_CompilerReference.pdf   IAR_Systems.jpg             ew430.htm
EW430_MigrationGuide.pdf      MSP-FET430 Users Guide.pdf  htm.gif
EW430_UserGuide.pdf           a430.htm                    icc430.htm
EW_MisraCReference.pdf        a430_msg.htm                icc430_msg.htm
Help430Compiler.chm           appnotes                    migration.htm
Help430Contents.ENU.chm       clib.pdf                    pdf.gif
Help430IDE1.chm               cs430.htm                   readme.htm
Help430IDE2.chm               embOSRelease.htm            uC-OS-II-KA-CSPY-UserGuide.pdf
karen%

Make scripts for both the compiler and the assembler. I'm uninterested in the IDE.

#!/bin/sh
#/usr/local/bin/a430
wine "C:\Program Files\IAR Systems\Embedded Workbench 4.0\430\bin\a430.exe" $*

#!/bin/sh
#/usr/local/bin/icc430
wine "C:\Program Files\IAR Systems\Embedded Workbench 4.0\430\bin\icc430.exe" $*

The compiler's options are very different from those of GCC, and you must remember (or update your script) to include the IAR include directory if you intend to use its headers. A test compile of the LED blinker from slac080b.zip follows.

karen% icc430 -I "Z:\opt\IAR\430\inc" msp430x20x3_1.c --output blink.exe

  IAR MSP430 C/C++ Compiler V4.09A/W32  [Kickstart]
  Copyright 1996-2007 IAR Systems. All rights reserved.

34 bytes of CODE memory
 0 bytes of DATA memory (+ 4 bytes shared)

Errors: none
Warnings: none
karen%

Now that the compiler is working, you'll need a linker. I use the following script:

#!/bin/sh
opts="-f Z:\opt\IAR\430\config\lnk430F2013.xcl -Fintel-standard  Z:\opt\IAR\430\LIB\CLIB\cl430f.r43 -s __program_start "
xlink="C:\Program Files\IAR Systems\Embedded Workbench 4.0\common\bin\xlink.exe"
wine "$xlink" $* $opts

msp430-objcopy aout.a43 aout.exe

The format switch, -Fintel-standard, makes the output file in the ihex format, one which msp430-objcopy can handle. This will let us program the board using msp430-gdb, so the GNU tools may be used to load the executable. Also note that you'll need to uncomment lines 76 and 77 of /opt/IAR/430/config/lnk430F2013.xcl to define the stack and heap sizes. This script is called as xlink msp430x20x3_1.r43.

The following is a functional, if inelegant, Makefile:

ALL=msp430x20x3_1.exe

all: $(ALL)

msp430x20x3_1.r43:  msp430x20x3_1.c
       icc430 -I "Z:\opt\IAR\430\inc" msp430x20x3_1.c
msp430x20x3_1.exe: msp430x20x3_1.r43
       xlink msp430x20x3_1.r43
       cp aout.exe msp430x20x3_1.exe

GDB

Assuming that msp430-gdb and the USB-FET drivers have been properly installed, the GDB server can be loaded as

karen% msp430-gdbproxy msp430 --spy-bi-wire /dev/ttyUSB0

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()
debug: MSP430_Configure()
debug: MSP430_VCC(3000)
debug: MSP430_Identify()
info:      msp430: Target device is a 'MSP430F20x3' (type 52)
debug: MSP430_Configure()
notice:    msp430-gdbproxy: waiting on TCP port 2000

Your ~/.gdbinit file should be

set remoteaddresssize 16
set remotetimeout 999999
target remote localhost:2000
monitor interface spy-bi-wire

msp430-gdb runs with no options. Use load foo.exe to load an executable that has been made by msp430-objcopy.

karen% msp430-gdb
GNU gdb 6.0
Copyright 2003 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "--host=i686-pc-linux-gnu --target=msp430".notice:    msp430-gdbproxy: connected
debug: MSP430_Registers(READ)
0x0000f800 in ?? ()

(gdb) load aout.exe
Loading section .sec1, size 0x38 lma 0xf800
debug: MSP430_Memory(WRITE)
Loading section .sec2, size 0x2 lma 0xfffe
debug: MSP430_Memory(WRITE)
Start address 0xf800, load size 58
Transfer rate: 464 bits in <1>

Note that without "monitor interface spy-bi-wire" in .gdbinit and "--spy-bi-wire" to msp430-gdbproxy, load will still work but many debugging functions will not. Also note that the run command seems to have issues with spy-bi-wire; use continue instead.

You should now be able to play around with the MSP430. Grab the msp430f2013 datasheet and family guide if you'll be doing anything fancy.