Table of content

• 1. Introduction
• 2. openmsp430-loader
• 3. openmsp430-minidebug
• 4. openmsp430-gdbproxy
• 5. MSPGCC Toolchain
  • 5.1 Compiler options
  • 5.2 MCU selection
  • 5.3 Custom linker script

1. Introduction

Building on the serial debug interface capabilities provided by the openMSP430, three utility programs are provided:

• openmsp430-loader: a simple command line boot loader.
• openmsp430-minidebug: a minimalistic debugger with simple GUI.
• openmsp430-gdbproxy: GDB Proxy server to be used together with MSP430-GDB and the Eclipse, DDD, or Insight GUI front-ends.

All these software development tools have been developed in TCL/TK and were successfully tested on both Linux and Windows (XP/Vista/7).

Note: to be able to execute the scripts, TCL/TK needs to be installed on your system.

In order to connect the host PC to the openMSP430 serial debug interface, a serial cable is required.
Typically, the following solutions will suit any kind of development board:

• USB to RS232 converter
• USB to Serial TTL converter
  

2. openmsp430-loader

This simple program allows the user to load the openMSP430 program memory with an executable file (ELF or Intel-HEX format) provided as argument.
It is typically used in conjunction with 'make' in order to automatically load the program after the compile step (see 'Makefile' from software examples provided with the project's FPGA implementation).
The program can be called with the following syntax:

openmsp430-loader.tcl [-device <communication device>] [-baudrate <communication speed>] <elf/ihex-file> Examples: openmsp430-loader.tcl -device /dev/ttyUSB0 -baudrate 9600 leds.elf           openmsp430-loader.tcl -device COM2: -baudrate 38400 ta_uart.ihex

These screenshots show the script in action under Linux and Windows:

3. openmsp430-minidebug

This small program provides a minimalistic graphical interface enabling simple interaction with the openMSP430:



As you can see from the screenshot, it allows the following actions:

• (1)  Connect to the openMSP430 Serial Debug Interface.
• (2)  Load the program memory with an ELF or Intel-HEX file
• (3)  Control the CPU: Reset, Stop, Start, Single-Step and Software breakpoints
• (4)  Read/Write access of the CPU registers
• (5)  Read/Write access of the whole memory range (program, data, peripherals)
• (6)  Basic disassembled view of the loaded program (current PC location is highlighted in green, software breakpoints in yellow, pink and violet)
• (7)  Choose the disassembled view type
• (8)  Source a custom external TCL script

4. openmsp430-gdbproxy

The purpose of this program is to replace the 'msp430-gdbproxy' utility provided by the mspgcc toolchain.
Typically, a GDB proxy creates a local port for GDB to connect to, and handles the communication with the target hardware. In our case, it is basically a bridge between the RSP communication protocol from GDB and the serial debug interface from the openMSP430.
Schematically the communication flow looks as following:



Like the original 'msp430-gdbproxy' program, 'openmsp430-gdbproxy' can be controlled from the command line. However, it also provides a simple graphical interface:



These two additional screenshots show the script in action together with the Eclipse and DDD graphical frontends:





Tip 1: There are several tutorials on Internet explaining how to configure Eclipse for the MSP430. As an Eclipse newbie, I found the followings quite helpful (the msp430-gdbproxy sections should of course be ignored as we are using our own openmsp430-gdbproxy program :-) ):

• A Step By Step Guide To MSP430 Programming Under Linux (English)
• MSP430 eclipse helios mspgcc4 (German)

Tip 2: You probably want to install this excellent Eclipse plugin (see screenshot above): EmbSysRegView

5. MSPGCC Toolchain

5.1 Compiler options

The msp430-gcc compiler accepts the following MSP430 specific command line parameters (copied from the MSPGCC manual page):

-mmcu=	Specify the MCU name
-mno-volatile-workaround	Do not perform a volatile workaround for bitwise operations.
-mno-stack-init	Do not initialize the stack as main()starts.
-minit-stack=	Specify the initial stack address.
-mendup-at=	Jump to the specified routine at the end of main().
-mforce-hwmul	Force use of a hardware multiplier.
-mdisable-hwmul	Do not use the hardware multiplier.
-minline-hwmul	Issue inline code for 32-bit integer operations for devices with a hardware multiplier.
-mnoint-hwmul	Do not disable and enable interrupts around hardware multiplier operations. This makes multiplication faster when you are certain no hardware multiplier operations will occur at deeper interrupt levels.
-mcall-shifts	Use subroutine calls for shift operations. This may save some space for shift intensive applications.

5.2 MCU selection

The following table aims to help selecting the proper MCU name for the -mmcu option during the msp430-gcc call:

-mmcu option	Program   Memory	Data    Memory	Hardware   Multiplier
Program Memory Size: 1 kB
msp430x110	1 kB	128 B	No
msp430x1101	1 kB	128 B	No
msp430x2001	1 kB	128 B	No
msp430x2002	1 kB	128 B	No
msp430x2003	1 kB	128 B	No
msp430x2101	1 kB	128 B	No
Program Memory Size: 2 kB
msp430x1111	2 kB	128 B	No
msp430x2011	2 kB	128 B	No
msp430x2012	2 kB	128 B	No
msp430x2013	2 kB	128 B	No
msp430x2111	2 kB	128 B	No
msp430x2112	2 kB	128 B	No
msp430x311	2 kB	128 B	No
Program Memory Size: 4 kB
msp430x112	4 kB	256 B	No
msp430x1121	4 kB	256 B	No
msp430x1122	4 kB	256 B	No
msp430x122	4 kB	256 B	No
msp430x1222	4 kB	256 B	No
msp430x2122	4 kB	256 B	No
msp430x2121	4 kB	256 B	No
msp430x312	4 kB	256 B	No
msp430x412	4 kB	256 B	No
Program Memory Size: 8 kB
msp430x123	8 kB	256 B	No
msp430x133	8 kB	256 B	No
msp430x313	8 kB	256 B	No
msp430x323	8 kB	256 B	No
msp430x413	8 kB	256 B	No
msp430x423	8 kB	256 B	Yes
msp430xE423	8 kB	256 B	Yes
msp430xE4232	8 kB	256 B	Yes
msp430xW423	8 kB	256 B	No
msp430x1132	8 kB	256 B	No
msp430x1232	8 kB	256 B	No
msp430x1331	8 kB	256 B	No
msp430x2131	8 kB	256 B	No
msp430x2132	8 kB	256 B	No
msp430x2232	8 kB	512 B	No
msp430x2234	8 kB	512 B	No
msp430x233	8 kB	1024 B	Yes
msp430x2330	8 kB	1024 B	Yes
Program Memory Size: 12 kB
msp430xE4242	12 kB	512 B	Yes
msp430x314	12 kB	512 B	No
Program Memory Size: 16 kB
msp430x4250	16 kB	256 B	No
msp430xG4250	16 kB	256 B	No
msp430x135	16 kB	512 B	No
msp430x1351	16 kB	512 B	No
msp430x155	16 kB	512 B	No
msp430x2252	16 kB	512 B	No
msp430x2254	16 kB	512 B	No
msp430x315	16 kB	512 B	No
msp430x325	16 kB	512 B	No
msp430x415	16 kB	512 B	No
msp430x425	16 kB	512 B	Yes
msp430xE425	16 kB	512 B	Yes
msp430xW425	16 kB	512 B	No
msp430xE4252	16 kB	512 B	Yes
msp430x435	16 kB	512 B	No
msp430x4351	16 kB	512 B	No
msp430x235	16 kB	2048 B	Yes
msp430x2350	16 kB	2048 B	Yes
Program Memory Size: 24 kB
msp430x4260	24 kB	256 B	No
msp430xG4260	24 kB	256 B	No
msp430x156	24 kB	512 B	No
msp430x4361	24 kB	1024 B	No
msp430x436	24 kB	1024 B	No
msp430x336	24 kB	1024 B	Yes
Program Memory Size: 32 kB
msp430x4270	32 kB	256 B	No
msp430xG4270	32 kB	256 B	No
msp430x147	32 kB	1024 B	Yes
msp430x1471	32 kB	1024 B	Yes
msp430x157	32 kB	1024 B	No
msp430x167	32 kB	1024 B	Yes
msp430x2272	32 kB	1024 B	No
msp430x2274	32 kB	1024 B	No
msp430x337	32 kB	1024 B	Yes
msp430x417	32 kB	1024 B	No
msp430x427	32 kB	1024 B	Yes
msp430xE427	32 kB	1024 B	Yes
msp430xE4272	32 kB	1024 B	Yes
msp430xW427	32 kB	1024 B	No
msp430x437	32 kB	1024 B	No
msp430xG437	32 kB	1024 B	No
msp430x4371	32 kB	1024 B	No
msp430x447	32 kB	1024 B	Yes
msp430x2370	32 kB	2048 B	Yes
msp430x247	32 kB	4096 B	Yes
msp430x2471	32 kB	4096 B	Yes
msp430x1610	32 kB	5120 B	Yes
Program Memory Size: 41 kB
msp430x5438	41 kB	16384 B	No
msp430x5437	41 kB	16384 B	No
msp430x5436	41 kB	16384 B	No
msp430x5435	41 kB	16384 B	No
msp430x5419	41 kB	16384 B	No
msp430x5418	41 kB	16384 B	No
Program Memory Size: 48 kB
msp430x1611	48 kB	10240 B	Yes
msp430x248	48 kB	4096 B	Yes
msp430x2481	48 kB	4096 B	Yes
msp430x4783	48 kB	2048 B	Yes
msp430xG438	48 kB	2048 B	No
msp430x4784	48 kB	2048 B	Yes
msp430x148	48 kB	2048 B	Yes
msp430x168	48 kB	2048 B	Yes
msp430x1481	48 kB	2048 B	Yes
msp430x448	48 kB	2048 B	Yes
Program Memory Size: 51 kB
msp430xG4617	51 kB	8192 B	Yes
msp430x2418	51 kB	8192 B	Yes
msp430x2618	51 kB	8192 B	Yes
msp430x2417	51 kB	8192 B	Yes
msp430xG4618	51 kB	8192 B	Yes
msp430x2617	51 kB	8192 B	Yes
Program Memory Size: 54 kB
msp430x1612	54 kB	5120 B	Yes
Program Memory Size: 55 kB
msp430x2619	55 kB	4096 B	Yes
msp430xG4619	55 kB	4096 B	Yes
msp430xG4616	55 kB	4096 B	Yes
msp430x2416	55 kB	4096 B	Yes
msp430x2419	55 kB	4096 B	Yes
msp430x2616	55 kB	4096 B	Yes
msp430x2410	55 kB	4096 B	Yes
Program Memory Size: 59 kB
msp430x4794	59 kB	2560 B	Yes
msp430x4793	59 kB	2560 B	Yes
msp430x2491	59 kB	2048 B	Yes
msp430x1491	59 kB	2048 B	Yes
msp430x149	59 kB	2048 B	Yes
msp430xG439	59 kB	2048 B	No
msp430x249	59 kB	2048 B	Yes
msp430x449	59 kB	2048 B	Yes
msp430x169	59 kB	2048 B	Yes

Note: the program memory size should imperatively match the openMSP430 configuration.

5.3 Custom linker script

The use of the -mmcu switch is of course NOT mandatory. It is simply a convenient way to use the pre-existing linker scripts provided with the MSPGCC4 toolchain.

However, if the peripheral address space is larger than the standard 512B of the original MSP430 (see the Advanced System Configuration section), a customized linker script MUST be provided.

To create a custom linker script, the simplest way is to start from an existing one:

• the MSPGCC toolchain provides a wide range of examples for all supported MSP430 models (see "msp430/lib/ldscripts/" sub-directory, in the MSPGCC installation directory).
• the openMSP430 project also provide a simple linker script example: ldscript_example.x

From there, the script can be modified to match YOUR openMSP430 configuration:

• In the text (rx) section definition, update the ORIGIN and LENGTH fields to match the PROGRAM MEMORY configuration.
• In the data (rwx) section definition, update the ORIGIN field to match the PERIPHERAL SPACE configuration and the LENGTH field to match the DATA MEMORY configuration.
• At last, update the stack pointer initialization value (look for the "PROVIDE (__stack =" section) and make sure that it falls in the data memory space (the stack size should also matches your application requirements, i.e. not to small... and not to big :-P ).