239 lines
10 KiB
Groff
239 lines
10 KiB
Groff
.TH mspdebug 1 "20 Mar 2010" "Version 0.5"
|
|
.SH NAME
|
|
MSPDebug - debugging tool for MSP430 MCUs
|
|
.SH SYNOPSIS
|
|
\fBmspdebug\fR \-R [\-v \fIvoltage\fR] [\fIcommand\fR ...]
|
|
.br
|
|
\fBmspdebug\fR \-u \fIdevice\fR [\-j] [\-v \fIvoltage\fR] [\fIcommand\fR ...]
|
|
.br
|
|
\fBmspdebug\fR \-B \fIdevice\fR [\fIcommand\fR ...]
|
|
.br
|
|
\fBmspdebug\fR \-s [\fIcommand\fR ...]
|
|
.SH DESCRIPTION
|
|
MSPDebug is a command-line tool designed for debugging and programming
|
|
the MSP430 family of MCUs. It supports the eZ430-F2013, eZ430-RF2500
|
|
and FET430UIF programming tools.
|
|
|
|
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 breakpoint).
|
|
|
|
It supports ELF32, Intel HEX and BSD-style symbol tables (such as the
|
|
output produced by \fBnm\fR(1)). It can also be used as a remote stub
|
|
for \fBgdb\fR(1).
|
|
.SH OPTIONS
|
|
Command-line options accepted by MSPDebug are described below. If
|
|
commands are specified on the end of the command-line, then they are
|
|
executed after connecting to the device, and the interactive prompt is
|
|
not started. See the section labelled \fBCOMMANDS\fR for more
|
|
information.
|
|
.IP "\-R"
|
|
Connect to an eZ430-RF2500 device. The USB bus will be searched for
|
|
the first available device. You must have write permission for usbfs
|
|
in order for this to work. You can achieve this by running as root
|
|
(not recommended), or by remounting usbfs using the
|
|
devuid/devgid/devmode options.
|
|
.IP "\-v \fIvoltage\fR"
|
|
Set the programming voltage. The voltage should be specified as an integer
|
|
in millivolts. It defaults to 3000 (3.0 V).
|
|
.IP "\-u \fIdevice\fR"
|
|
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/tty\fIXX\fR when attached.
|
|
.IP "\-j"
|
|
Use JTAG instead of Spy-Bi-Wire to communicate with the MSP430. This
|
|
option only works on FET430UIF devices.
|
|
.IP "\-B \fIdevice\fR"
|
|
Connect to the bootloader on a FET430UIF device. These devices contain
|
|
MSP430F419 chips. By sending a special command sequence, you can obtain
|
|
access to the bootloader and inspect memory on the MSP430F419 in the
|
|
programming device itself.
|
|
|
|
Currently, only memory inspection is supported. CPU control via the
|
|
bootloader is not possible. Memory erase and write is possible, but is
|
|
currently not implemented, for lack of ability to test it. If implemented,
|
|
this would allow firmware updates to FET430UIF devices.
|
|
|
|
The argument should be the filename of the appropriate tty device.
|
|
.IP "\-s"
|
|
Do not connect to any hardware device, but instead start in simulation
|
|
mode. A 64k buffer is allocated to simulate the device memory. The CPU
|
|
core alone is emulated (no peripheral emulation).
|
|
|
|
During simulation, addresses below 0x0200 are assumed to be IO memory.
|
|
When data is written to an IO memory address, a message is displayed
|
|
on the console showing the program counter location, address written
|
|
to, and data. When data is read from IO memory, the user is notified
|
|
similarly and prompted to supply the data. At this prompt, address
|
|
expressions can be entered. The user can press Ctrl+C to abort an IO
|
|
request and stop execution.
|
|
|
|
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).
|
|
.SH 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.
|
|
.IP "= \fIexpression\fR"
|
|
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 \fIsymbol\fR+\fIoffset\fR, where
|
|
\fIsymbol\fR is the name of the nearest symbol not past the address in
|
|
question.
|
|
|
|
See the section marked \fBADDRESS EXPRESSIONS\fR for more information on
|
|
the syntax of expressions.
|
|
.IP "dis \fIaddress\fR [\fIlength\fR]"
|
|
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 \fIsymbol\fR+\fIoffset\fR form.
|
|
.IP "gdb [\fIport\fR]"
|
|
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. The basic GDB protocol is
|
|
supported, plus the monitor commands "erase" and "reset".
|
|
.IP "help [\fIcommand\fR]"
|
|
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.
|
|
.IP "hexout \fIaddress\fR \fIlength\fR \fIfilename\fR"
|
|
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 overwritten. 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.
|
|
.IP "md \fIaddress\fR [\fIlength\fR]"
|
|
Read the specified section of device memory and display it as a
|
|
canonical\-style hexdump. Both arguments may be address expressions. 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.
|
|
.IP "nosyms"
|
|
Clear all symbols from the symbol table. Symbols may be reloaded with
|
|
the \fBsyms\fR command.
|
|
.IP "prog \fIfilename\fR"
|
|
Erase and reprogram the device under test using the binary file
|
|
supplied. The file format will be auto-detected and may be either
|
|
Intel HEX or ELF32.
|
|
|
|
In the case of an ELF32 file, symbols will be automatically loaded
|
|
from the file into the symbol table (discarding any existing symbols),
|
|
if they are present.
|
|
|
|
The CPU is reset and halted before programming.
|
|
.IP "regs"
|
|
Show the current value of all CPU registers in the device under test.
|
|
.IP "reset"
|
|
Reset (and halt) the CPU of the device under test.
|
|
.IP "run [\fIbreakpoint\fR]"
|
|
Run the CPU, optionally specifying a breakpoint. The breakpoint can be
|
|
specified as an address expression.
|
|
|
|
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 the specified breakpoint, 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.
|
|
.IP "set \fIregister\fR \fIvalue\fR"
|
|
Alter the value of a register. Registers are specified as numbers 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.
|
|
.IP "step [\fIcount\fR]"
|
|
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.
|
|
.IP "syms \fIfilename\fR"
|
|
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 \fBnm\fR(1)).
|
|
|
|
Symbols can be combined from many sources, as the syms command adds
|
|
to the existing symbol table without discarding existing symbols.
|
|
.SH 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 a sequence of one or more address values
|
|
separated by the operators \fB+\fR or \fB\-\fR.
|
|
|
|
An address value may be either a decimal value, a hexadecimal value
|
|
preceeded by the prefix \fB0x\fR, or a symbol name.
|
|
|
|
The following are all valid examples of address expressions:
|
|
|
|
.B 64
|
|
.br
|
|
.B 0xffe0
|
|
.br
|
|
.B main+0x3f
|
|
.br
|
|
.B __bss_end-__bss_start
|
|
.SH SEE ALSO
|
|
\fBnm\fR(1), \fBgdb\fR(1), \fBobjcopy\fR(1)
|
|
.SH BUGS
|
|
If you find any bugs, you should report them to the author at
|
|
daniel@tortek.co.nz. 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. Below, known bugs in the current
|
|
version of MSPDebug are described.
|
|
|
|
Memory addresses above 0x10000 (in devices with more than 64k of
|
|
memory) are not accessible. All other memory in these devices is
|
|
accessible as normal.
|
|
|
|
Most of the popular device IDs are recognized, but the set is not
|
|
complete. If you see a message like the following after connecting:
|
|
|
|
.B Unknown device ID: 0x\fI1234\fP
|
|
|
|
Please report it, as well as the model of the device you are using.
|
|
|
|
Some firmware versions of the FET430UIF are not supported. If you
|
|
encounter a version which doesn't work, you should try to extract
|
|
the firmware using the command:
|
|
|
|
.B mspdebug -B \fIdevice\fP 'hexout 0x2500 0xdb00 firmware.hex'
|
|
|
|
Please send the HEX file, along with the firmware version. The
|
|
firmware version is reported in the transcript when connecting
|
|
with the \fB-u\fR option.
|
|
|
|
Firmware version 20107000 is known to work with MSPDebug, and you can
|
|
update your FET to this version using the proprietary
|
|
\fBmsp430\-gdbproxy\fR program:
|
|
|
|
.B msp430-gdbproxy msp430 \fIdevice\fP --update-usb-fet
|
|
|
|
This command updates the FET firmware using the same bootloader
|
|
supported by MSPDebug's \fB\-B\fR option. However, as mentioned above,
|
|
MSPDebug does not support erase or programming in this mode.
|
|
.SH COPYRIGHT
|
|
Copyright (C) 2009, 2010 Daniel Beer <daniel@tortek.co.nz>
|
|
|
|
MSPDebug is free software, distributed under the terms of the GNU
|
|
General Public license (version 2 or later). See the file COPYING
|
|
included with the source code for more details.
|