Manual
mspdebug(1) mspdebug(1)
NAME
MSPDebug - debugging tool for MSP430 MCUs
SYNOPSIS
mspdebug [options] driver [command ...]
DESCRIPTION
MSPDebug is a command-line tool designed for debugging and programming
the MSP430 family of MCUs. It supports the eZ430-F2013, eZ430-RF2500,
Launchpad, Chronos, FET430UIF, Olimex MSP430-JTAG-TINY and MSP430-JTAG-
ISO programming tools, as well as a simulation mode.
When started with appropriate options, MSPDebug will attempt to connect
to the debugging tool specified and identify the device under test.
Once connected, the user is presented with a command prompt which can
be used to reflash the device memory, inspect memory and registers, set
registers, and control the CPU (single step, run and run to break-
point).
It supports a variety of file formats, described in the section BINARY
FORMATS below. It can also be used as a remote stub for gdb(1).
On startup, MSPDebug will look for a file called .mspdebug in the
user's home directory. If it exists, commands will be read and executed
from this file before executing any other commands or starting the
interactive reader.
COMMAND-LINE OPTIONS
Command-line options accepted by MSPDebug are described below. If com-
mands are specified on the end of the command-line, then they are exe-
cuted after connecting to the device, and the interactive prompt is not
started. Please be aware that commands consisting of multiple words
need to be enclosed in quotation marks, otherwise they are treated as
single commands. Thus the common prog command would be used as "prog
main.elf". See the section labelled COMMANDS for more information.
-q Start in quiet mode. See the "quiet" option described below.
-v voltage
Set the programming voltage. The voltage should be specified as
an integer in millivolts. It defaults to 3000 (3.0 V).
-j Use JTAG instead of Spy-Bi-Wire to communicate with the MSP430.
This option doesn't work with eZ430 or eZ430-RF2500 devices,
which support Spy-Bi-Wire only.
-d device
Specify that the driver should connect via a tty device rather
than USB. The supported connection methods vary depending on
the driver. See the section DRIVERS below for details.
-U bus:device
Specify a particular USB device to connect to. Without this
option, the first device of the appropriate type is opened.
-s serial
Specify a particular USB device serial number to connect to. Use
this option to distinguish between multiple devices of the same
type.
-n Do not process the startup file (~/.mspdebug).
--long-password
When using the flash-bsl driver, send a 32-byte BSL password
instead of the standard 16-byte password.
--help Display a brief help message and exit.
--fet-list
Display a list of chips supported by the FET driver (the driver
used for UIF, RF2500 and Olimex devices)>
--fet-force-id string
When using a FET device, force the connected chip to be recog-
nised by MSPDebug as one of the given type during initializa-
tion. This overrides the device ID returned by the FET. The
given string should be a chip name in long form, for example
"MSP430F2274".
--usb-list
List available USB devices and exit.
--force-reset
When using a FET device, always send a reset during initializa-
tion. By default, an initialization without reset will be tried
first.
--allow-fw-update
When using a V3 FET device via the TI library, allow the library
to perform a firmware update if the FET firmware is incompatible
with the library.
--require-fw-update image.txt
When using a V3 FET device, force a firmware update using the
given firmware image. The firmware file must be in TI Text for-
mat.
--version
Show program version and copyright information.
DRIVERS
A driver name must be specified on the command line for MSPDebug to
connect to. Valid driver names are listed here.
rf2500 Connect to an eZ430-RF2500, Launchpad or Chronos device. Only
USB connection is supported.
olimex Connect to an Olimex MSP-JTAG-TINY device. Both USB and tty
access are supported.
olimex-v1
Connect to an Olimex MSP-JTAG-TINY (V1) device. Both USB and tty
access are supported. This driver must be used instead of olimex
if connecting to a V1 device via a tty interface.
olimex-iso
Connect to an Olimex MSP-JTAG-ISO device. Both USB and tty
access are supported.
sim Do not connect to any hardware device, but instead start in sim-
ulation mode. A 64k buffer is allocated to simulate the device
memory.
During simulation, addresses below 0x0200 are assumed to be IO
memory. Programmed IO writes to and from IO memory are handled
by the IO simulator, which can be configured and controlled with
the simio command, described below.
This mode is intended for testing of changes to MSPDebug, and
for aiding the disassembly of MSP430 binaries (as all binary and
symbol table formats are still usable in this mode).
uif Connect to an eZ430-F2013 or a FET430UIF device. The device
argument should be the filename of the appropriate tty device.
The TI serial converter chips on these devices are supported by
newer versions of the Linux kernel, and should appear as
/dev/ttyXX when attached.
USB connection is supported for this driver. The USB interface
chip in these devices is a TI3410, which requires a firmware
download on startup. MSPDebug will search for a file called
ti_3410.fw.ihex in the configured library directory and the cur-
rent directory. You can specify an alternate location for the
file via the MSPDEBUG_TI3410_FW environment variable.
uif-bsl
Connect to the bootloader on a FET430UIF device. These devices
contain MSP430F1612 chips. By sending a special command
sequence, you can obtain access to the bootloader and inspect
memory on the MSP430F1612 in the programming device itself.
Currently, only memory read/write and erase are supported. CPU
control via the bootloader is not possible.
USB connection is not supported for this driver.
flash-bsl
Connect to the built-in bootloader in MSP430 devices with flash
bootloader memory. Devices with ROM bootloaders require another
driver. Currently, this driver must mass-erase the device in
order to gain access. Read, write, and erase operations are sup-
ported.
USB connection is not supported for this driver. Connection is
via serial port, and bootloader entry is accomplished via the
RTS and DTR lines. Connect RTS to the device's TEST pin and DTR
to the device's RST pin. Use an appropriate serial level-
shifter to make the connection, if necessary. If connecting to
a device with non-multiplexed JTAG pins, connect RTS to the
device's TCK pin via an inverter.
gdbc GDB client mode. Connect to a server which implements the GDB
remote protocol and provide an interface to it. To use this
driver, specify the remote address in hostname:port format using
the -d option.
tilib Use the Texas Instruments MSP430.DLL to access the device. The
library file (MSP430.DLL for Windows, libmsp430.so for Unix-like
systems) must be present in the dynamic loader search path.
USB connection is not supported for this driver.
COMMANDS
MSPDebug can accept commands either through an interactive prompt, or
non-interactively when specified on the command line. The supported
commands are listed below.
Commands take arguments separated by spaces. Any text string enclosed
in double-quotation marks is considered to be a single argument, even
if it contains space characters. Within a quoted string, the usual C-
style backslash substitutions can be used.
Commands can be specified by giving the first few characters of the
command name, provided that the prefix is unambiguous. Some commands
support automatic repeat. For these commands, pressing enter at the
reader prompt without typing anything will cause repeat execution.
= expression
Evaluate an address expression and show both its value, and the
result when the value is looked up in reverse in the current
symbol table. This result is of the form symbol+offset, where
symbol is the name of the nearest symbol not past the address in
question.
See the section marked ADDRESS EXPRESSIONS for more information
on the syntax of expressions.
alias Show a list of defined command aliases.
alias name
Remove a previously defined command alias.
alias name command
Define a command alias. The text command will be substituted for
name when looking up commands. The given command text may con-
tain a command plus arguments, if the entire text is wrapped in
quotes when defining the alias. To avoid alias substitution when
interpreting commands, prefix the command with \ (a backslash
character).
break Show a list of active breakpoints. Breakpoints can be added and
removed with the setbreak and delbreak commands. Each breakpoint
is numbered with an integer index starting at 0.
cgraph address length [address]
Construct the call graph of all functions contained or refer-
enced in the given range of memory. If a particular function is
specified, then details for that node of the graph are dis-
played. Otherwise, a summary of all nodes is displayed.
Information from the symbol table is used for hinting at the
possible locations of function starts. Any symbol which does not
contain a "." is considered a possible function start.
Callers and callee names are shown prefixed by a "*" where the
transition is a tail-call type transition.
delbreak [index]
Delete one or all breakpoints. If an index is given, the
selected breakpoint is deleted. Otherwise, all breakpoints are
cleared.
dis address [length]
Dissassemble a section of memory. Both arguments may be address
expressions. If no length is specified, a section of the default
length (64 bytes) is disassembled and shown.
If symbols are available, then all addresses used as operands
are translated into symbol+offset form.
This command supports repeat execution. If repeated, it contin-
ues to disassemble another block of memory following that last
printed.
erase [all|segment] [address]
Erase the device under test. With no arguments, all code memory
is erased (but not information or boot memory). With the argu-
ment "all", a mass erase is performed (the results may depend on
the state of the LOCKA bit in the flash memory controller).
Specify "segment" and a memory address to erase an individual
flash segment.
exit Exit from MSPDebug.
gdb [port]
Start a GDB remote stub, optionally specifying a TCP port to
listen on. If no port is given, the default port is 2000.
MSPDebug will wait for a connection on this port, and then act
as a GDB remote stub until GDB disconnects.
GDB's "monitor" command can be used to issue MSPDebug commands
via the GDB interface. Supplied commands are executed non-inter-
actively, and the output is sent back to be displayed in GDB.
help [command]
Show a brief listing of available commands. If an argument is
specified, show the syntax for the given command. The help text
shown when no argument is given is also shown when MSPDebug
starts up.
hexout address length filename
Read the specified section of the device memory and save it to
an Intel HEX file. The address and length arguments may both be
address expressions.
If the specified file already exists, then it will be overwrit-
ten. If you need to dump memory from several disjoint memory
regions, you can do this by saving each section to a separate
file. The resulting files can then be concatenated together to
form a single valid HEX file.
isearch address length [options ...]
Search over the given range for an instruction which matches the
specified search criteria. The search may be narrowed by speci-
fying one or more of the following terms:
opcode opcode
Match the specified opcode. Byte/word specifiers are not
recognised, as they are specified with other options.
byte Match only byte operations.
word Match only word operations.
aword Match only address-word (20-bit) operations.
jump Match only jump instructions (conditional and uncondi-
tional jumps, but not instructions such as BR which load
the program counter explicitly).
single Match only single-operand instructions.
double Match only double-operand instructions.
noarg Match only instructions with no arguments.
src address
Match instructions with the specified value in the source
operand. The value may be given as an address expression.
Specifying this option implies matching of only double-
operand instructions.
dst address
Match instructions with the specified value in the desti-
nation operand. This option implies that no-argument
instructions are not matched.
srcreg register
Match instructions using the specified register in the
source operand. This option implies matching of only dou-
ble-operand instructions.
dstreg register
Match instructions using the specified register in the
destination operand. This option implies that no-argu-
ment instructions are not matched.
srcmode mode
Match instructions using the specified mode in the source
operand. See below for a list of modes recognised. This
option implies matching of only double-operand instruc-
tions.
dstmode mode
Match instructions using the specified mode in the desti-
nation operand. See below for a list of modes. This
option implies that no-argument instructions are not
matched.
For single-operand instructions, the operand is considered to be
the destination operand.
The seven addressing modes used by the MSP430 are represented by
single characters, and are listed here:
R Register mode.
I Indexed mode.
S Symbolic mode.
& Absolute mode.
@ Register-indirect mode.
+ Register-indirect mode with auto-increment.
# Immediate mode.
load filename
Program the device under test using the binary file supplied.
This command is like prog, but it does not load symbols or erase
the device before programming.
The CPU is reset and halted before and after programming.
locka [set|clear]
Show or change the status of the LOCKA bit in the chip's memory
controller. The LOCKA bit is set on POR and acts as a write-pro-
tect bit for info segment A. This segment contains factory-con-
figured calibration data, and under normal circumstances, should
not be changed.
If the LOCKA bit is cleared, erasing the info A segment is pos-
sible.
The LOCKA bit also affects the behaviour of the "erase all" com-
mand. If LOCKA is set (the default), only main memory is erased.
If LOCKA is cleared, main and information memory are both
erased.
md address [length]
Read the specified section of device memory and display it as a
canonical-style hexdump. Both arguments may be address expres-
sions. If no length is specified, a section of the default
length (64 bytes) is shown.
The output is split into three columns. The first column shows
the starting address for the line. The second column lists the
hexadecimal values of the bytes. The final column shows the
ASCII characters corresponding to printable bytes, and . for
non-printing characters.
This command supports repeat execution. If repeated, it contin-
ues to print another block of memory following that last
printed.
mw address bytes ...
Write a sequence of bytes at the given memory address. The
address given may be an address expression. Bytes values are
two-digit hexadecimal numbers separated by spaces.
Unless used in the simulation mode, this command can only be
used for programming flash memory.
opt [name] [value]
Query, set or list option variables. MSPDebug's behaviour can be
configured using option variables, described below in the sec-
tion OPTIONS.
Option variables may be of three types: boolean, numeric or
text. Numeric values may be specified as address expressions.
With no arguments, this command displays all available option
variables. With just an option name as its argument, it dis-
plays the current value of that option.
prog filename
Erase and reprogram the device under test using the binary file
supplied. The file format will be auto-detected and may be any
of the supported file formats.
In the case of a file containing symbols, symbols will be auto-
matically loaded from the file into the symbol table (discarding
any existing symbols), if they are present.
The CPU is reset and halted before and after programming.
read filename
Read commands from the given file, line by line and process each
one. Any lines whose first non-space character is # are
ignored. If an error occurs while processing a command, the rest
of the file is not processed.
regs Show the current value of all CPU registers in the device under
test.
reset Reset (and halt) the CPU of the device under test.
run Start running the CPU. The interactive command prompt is blocked
when the CPU is started and the prompt will not appear again
until the CPU halts. The CPU will halt if it encounters a break-
point, or if Ctrl-C is pressed by the user.
After the CPU halts, the current register values are shown as
well as a disassembly of the first few instructions at the
address selected by the program counter.
set register value
Alter the value of a register. Registers are specified as num-
bers from 0 through 15. Any leading non-numeric characters are
ignored (so a register may be specified as, for example, "R12").
The value argument is an address expression.
setbreak address [index]
Add a new breakpoint. The breakpoint location is an address
expression. An optional index may be specified, indicating that
this new breakpoint should overwrite an existing slot. If no
index is specified, then the breakpoint will be stored in the
next unused slot.
simio add class name [args ...]
Add a new peripheral to the IO simulator. The class parameter
may be any of the peripheral types named in the output of the
simio classes command. The name parameter is a unique name
assigned by the user to this peripheral instance, and is used
with other commands to refer to this instance of the peripheral.
Some peripheral classes take arguments upon creation. These are
documented in the output to the simio help command.
simio classes
List the names of the different types of peripherals which may
be added to the simulator. You can use the simio help command to
obtain more information about each peripheral type.
simio config name param [args ...]
Configure or perform some action on a peripheral instance. The
param argument is specific to the peripheral type. A list of
valid configuration commands can be obtained by using the simio
help command.
simio del name
Remove a previously added peripheral instance. The name argument
should be the name of the peripheral that was assigned with the
simio add command.
simio devices
List all peripheral instances currently attached to the simula-
tor, along with their types and interrupt status. You can obtain
more detailed information for each instance with the simio info
command.
simio help class
Obtain more information about a peripheral class. The documenta-
tion given will list constructor arguments and configuration
parameters for the device type.
simio info name
Display detailed status information for a particular peripheral.
The type of information displayed is specific to each type of
peripheral.
step [count]
Step the CPU through one or more instructions. After stepping,
the new register values are displayed, as well as a disassembly
of the instructions at the address selected by the program
counter.
An optional count can be specified to step multiple times. If no
argument is given, the CPU steps once. This command supports
repeat execution.
sym clear
Clear the symbol table, deleting all symbols.
sym set name value
Set or alter the value of a symbol. The value given may be an
address expression.
sym del name
Delete the given symbol from the symbol table.
sym import filename
Load symbols from the specified file and add them to the symbol
table. The file format will be auto-detected and may be either
ELF32 or a BSD-style symbol listing (like the output from
nm(1)).
Symbols can be combined from many sources, as the syms command
adds to the existing symbol table without discarding existing
symbols.
sym import+ filename
This command is similar to sym import, except that the symbol
table is not cleared first. By using this command, symbols from
multiple sources can be combined.
sym export filename
Save all symbols currently defined to the given file. The sym-
bols are saved as a BSD-style symbol table. Note that symbol
types are not stored by MSPDebug, and all symbols are saved as
type t.
sym find [regex]
Search for symbols. If a regular expression is given, then all
symbols matching the expression are printed. If no expression is
specified, then the entire symbol table is listed.
sym rename regex string
Rename symbols by searching for those matching the given regular
expression and substituting the given string for the matched
portion. The symbols renamed are displayed, as well as a total
count of all symbols renamed.
SUPPORTED CHIPS
The following chips are supported when using FET-compatible drivers:
CC430F5133 MSP430F169 MSP430F2370 MSP430F47197 MSP430F5528
CC430F5137 MSP430F2012 MSP430F247 MSP430F4784 MSP430F5529
CC430F6137 MSP430F2013 MSP430F249 MSP430F5418 MSP430FG4618
MSP430AFE253 MSP430F2121 MSP430F2616 MSP430F5437 MSP430FR5739
MSP430F1121 MSP430F2122 MSP430F2617 MSP430F5437A MSP430G2231
MSP430F1232 MSP430F2131 MSP430F2618 MSP430F5438 MSP430G2252
MSP430F147 MSP430F2132 MSP430F413 MSP430F5438A MSP430G2452
MSP430F148 MSP430F2234 MSP430F427 MSP430F5510 MSP430G2553
MSP430F149 MSP430F2272 MSP430F4270 MSP430F5525
MSP430F1611 MSP430F2274 MSP430F449 MSP430F5526
MSP430F1612 MSP430F235 MSP430F47173 MSP430F5527
BINARY FORMATS
The following binary/symbol formats are supported by MSPDebug:
ELF32
COFF
Intel HEX (program only)
BSD symbol table (symbols only)
TI Text (program only)
SREC (program only)
IO SIMULATOR
The IO simulator subsystem consists of a database of device classes,
and a list of instances of those classes. Each device class has a dif-
ferent set of constructor arguments, configuration parameters and
information which may be displayed. This section describes the opera-
tion of the available device classes in detail.
In the list below, each device class is listed, followed by its con-
structor arguments.
gpio Digital IO port simulator. This device simulates any of the dig-
ital ports with or without interrupt capability. It has the fol-
lowing configuration parameters:
base address
Set the base address for this port. Note that for ports
without interrupt capability, the resistor enable port
has a special address which is computable from the base
address.
irq vector
Enable interrupt functionality for this port by specify-
ing an interrupt vector number.
noirq Disable interrupt functionality for this port.
verbose
Print a state change message every time the port output
changes.
quiet Don't print anything when the port state changes (the
default).
set pin value
Set the input pin state for the given pin on this port.
The pin parameter should be an index between 0 and 7. The
value should be either zero (for a low state) or non-zero
(for a high state).
hwmult This peripheral simulates the hardware multiplier. It has no
constructor or configuration parameters, and does not provide
any extended information.
timer [size]
This peripheral simulators Timer_A modules, and can be used to
simulate Timer_B modules, provided that the extended features
aren't required.
The constructor takes a size argument specifying the number of
capture/compare registers in this peripheral instance. The num-
ber of such registers may not be less than 2, or greater than 7.
The IO addresses and IRQs used are configurable. The default IO
addresses used are those specified for Timer_A in the MSP430
hardware documentation.
base address
Alter the base IO address. By default, this is 0x0160. By
setting this to 0x0180, a Timer_B module may be simu-
lated.
irq0 number
Set the TACCR0 interrupt vector number. By default, this
is interrupt vector 9. This interrupt is self-clearing,
and higher priority than the TACCR1/TAIFG vector.
irq1 number
Set the TACCR1/TAIFG interrupt vector. By default, this
is interrupt vector 8.
iv address
Alter the address of the interrupt vector register. By
default, this is 0x012E. By setting this to 0x011E, a
Timer_B module may be simulated.
set channel value
When Timer_A is used in capture mode, the CCI bit in each
capture register reflects the state of the corresponding
input pin, and can't be altered in software. This config-
uration command can be used to simulate changes in input
pin state, and will trigger the corresponding interrupts
if the peripheral is so configured.
tracer [history-size]
The tracer peripheral is a debugging device. It can be used to
investigate and record the IO activity of a running program, to
benchmark execution time, and to simulate interrupts.
The information displayed by the tracer gives a running count of
clock cycles from each of the system clocks, and an instruction
count. A list of the N most recent IO events is also displayed
(this is configurable via the history-size argument of the con-
structor). Each IO event is timestamped by the number of MCLK
cycles that have elapsed since the last reset of the device's
counter.
The IO events that it records consist of programmed IO reads and
writes, interrupt acceptance, and system resets. As well as
keeping the IO events in a rotating buffer, the tracer can be
configured to display the events as they occur.
Note that since clock cycles don't advance while the CPU isn't
running, this peripheral can be used to calculate execution
times for blocks of code. This can be achieved by setting a
breakpoint at the end of the code block, setting the program
counter to the start of the code block, clearing the tracer and
running the code. After the breakpoint is reached, the informa-
tion displayed by the tracer will contain a count of MCLK cycles
elapsed during the last run.
The configuration parameters for this device class are:
verbose
Start displaying IO events as they occur, as well as
recording them in the rotating buffer.
quiet Stop displaying IO events as they occur, and just record
them in the buffer.
trigger irq
Signal an interrupt request to the CPU. This request will
remain raised until accepted by the CPU or cleared by the
user.
untrigger
Clear a signalled interrupt request.
clear Reset the clock cycle and instruction counts to 0, and
clear the IO event history.
wdt This peripheral simulates the Watchdog Timer+, which can be used
in software either as a watchdog or as an interval timer. It has
no constructor arguments.
The simulated state of the NMI/RST# pin can be controlled
through a configuration parameter. Note that if this pin state
is held low with the pin mode selected as a reset (the default),
the CPU will not run.
The extended information for this peripheral shows all register
states, including the hidden counter register. Configuration
parameters are:
nmi state
Set the NMI/RST# pin state. The argument should be zero
to indicate a low state or non-zero for a high state.
irq irq
Select the interrupt vector for interval timer mode. The
default is to use interrupt vector 10.
ADDRESS EXPRESSIONS
Any command which accepts a memory address, length or register value as
an argument may be given an address expression. An address expression
consists of an algebraic combination of values.
An address value may be either a symbol name, a hex value preceded with
the specifier "0x", a decimal value preceded with the specifier "0d",
or a number in the default input radix (without a specifier). See the
option iradix for more information.
The operators recognised are the usual algebraic operators: +, -, *, /,
%, ( and ). Operator precedence is the same as in C-like languages, and
the - operator may be used as a unary negation operator.
The following are all valid examples of address expressions:
2+2
table_start + (elem_size + elem_pad)*4
main+0x3f
__bss_end-__bss_start
OPTIONS
MSPDebug's behaviour can be configured via the following variables:
color (boolean)
If true, MSPDebug will colorize debugging output.
fet_block_size (numeric)
Change the size of the buffer used to transfer memory to and
from the FET. Increasing the value from the default of 64 will
improve transfer speed, but may cause problems with some chips.
gdb_loop (boolean)
Automatically restart the GDB server after disconnection. If
this option is set, then the GDB server keeps running until an
error occurs, or the user interrupts with Ctrl+C.
gdbc_xfer_size (numeric)
Maximum size of memory transfers for the GDB client. Increasing
this value will result in faster transfers, but may cause prob-
lems with some servers.
iradix (numeric)
Default input radix for address expressions. For address values
with no radix specifier, this value gives the input radix, which
is 10 (decimal) by default.
quiet (boolean)
If set, MSPDebug will supress most of its debug-related output.
This option defaults to false, but can be set true on start-up
using the -q command-line option.
ENVIRONMENT
MSPDEBUG_TI3410_FW
Specifies the location of TI3410 firmware, for raw USB access to
FET430UIF or eZ430 devices. This variable should contain the
path to an Intel HEX file containing suitable firmware for the
TI3410.
FILES
~/.mspdebug
File containing commands to be executed on startup.
ti_3410.fw.ihex
Firmware image for the TI3410 USB interface chip. This file is
only required for raw USB access to FET430UIF or eZ430 devices.
SEE ALSO
nm(1), gdb(1), objcopy(1)
BUGS
If you find any bugs, you should report them to the author at
dlbeer@gmail.com. It would help if you could include a transcript of an
MSPDebug session illustrating the program, as well as any relevant
binaries or other files.
COPYRIGHT
Copyright (C) 2009-2012 Daniel Beer <dlbeer@gmail.com>
MSPDebug is free software, distributed under the terms of the GNU Gen-
eral Public license (version 2 or later). See the file COPYING included
with the source code for more details.
Version 0.19 3 Mar 2012 mspdebug(1)