From fe01853335e674449aa4479a22a8647787cfb3a9 Mon Sep 17 00:00:00 2001 From: Daniel Beer Date: Thu, 18 Mar 2010 14:02:05 +1300 Subject: [PATCH] Added manual page. --- Makefile | 6 ++ mspdebug.man | 221 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 227 insertions(+) create mode 100644 mspdebug.man diff --git a/Makefile b/Makefile index 2b9955e..13d27a1 100644 --- a/Makefile +++ b/Makefile @@ -16,6 +16,8 @@ # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA CC = gcc +INSTALL = /usr/bin/install +PREFIX ?= /usr/local all: mspdebug @@ -23,6 +25,10 @@ clean: /bin/rm -f *.o /bin/rm -f mspdebug +install: mspdebug mspdebug.man + $(INSTALL) -o root -m 0755 -s mspdebug $(PREFIX)/bin/mspdebug + $(INSTALL) -o root -m 0644 mspdebug.man $(PREFIX)/share/man/man1/mspdebug.1 + .SUFFIXES: .c .o mspdebug: main.o fet.o rf2500.o dis.o uif.o ihex.o elf32.o stab.o util.o \ diff --git a/mspdebug.man b/mspdebug.man new file mode 100644 index 0000000..989edbd --- /dev/null +++ b/mspdebug.man @@ -0,0 +1,221 @@ +.TH mspdebug 1 "18 Mar 2010" "Version 0.4" +.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)). +.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. All of +the memory inspection and programming commands can be used on this +buffer, but CPU control is not supported. + +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 "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" +Step the CPU through a single instruction. After stepping, the new +register values are displayed, as well as a disassembly of the +instructions at the address selected by the program counter. +.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 +.BR nm (1), +.BR objcopy (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 0x3100 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 + +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.