1mspdebug(1) General Commands Manual mspdebug(1)
2
6 MSPDebug - debugging tool for MSP430 MCUs
7
9 mspdebug [options] driver [command ...]
10
12 MSPDebug is a command-line tool designed for debugging and programming
13 the MSP430 family of MCUs. It supports the eZ430-F2013, eZ430-RF2500,
14 FET430UIF and Olimex MSP-JTAG-TINY programming tools, as well as a sim‐
15 ulation mode.
16 When started with appropriate options, MSPDebug will attempt to connect
18 to the debugging tool specified and identify the device under test.
19 Once connected, the user is presented with a command prompt which can
20 be used to reflash the device memory, inspect memory and registers, set
21 registers, and control the CPU (single step, run and run to break‐
22 point).
23 It supports a variety of file formats, described in the section BINARY
25 FORMATS below. It can also be used as a remote stub for gdb(1).
26 On startup, MSPDebug will look for a file called .mspdebug in the
28 user's home directory. If it exists, commands will be read and executed
29 from this file before executing any other commands or starting the
30 interactive reader.
31
33 Command-line options accepted by MSPDebug are described below. If com‐
34 mands are specified on the end of the command-line, then they are exe‐
35 cuted after connecting to the device, and the interactive prompt is not
36 started. See the section labelled COMMANDS for more information.
37 -q Start in quiet mode. See the "quiet" option described below.
39 -v voltage
41 Set the programming voltage. The voltage should be specified as
42 an integer in millivolts. It defaults to 3000 (3.0 V).
43 -j Use JTAG instead of Spy-Bi-Wire to communicate with the MSP430.
45 This option only works on FET430UIF devices.
46 -d device
48 Specify that the driver should connect via a tty device rather
49 than USB. The supported connection methods vary depending on
50 the driver. See the section DRIVERS below for details.
51 -U bus:device
53 Specify a particular USB device to connect to. Without this
54 option, the first device of the appropriate type is opened.
55 -n Do not process the startup file (~/.mspdebug).
57 --long-password
59 When using the flash-bsl driver, send a 32-byte BSL password
60 instead of the standard 16-byte password.
61 --help Display a brief help message and exit.
63 --fet-list
65 Display a list of chips supported by the FET driver (the driver
66 used for UIF, RF2500 and Olimex devices)>
67 --fet-force-id string
69 When using a FET device, force the connected chip to be recog‐
70 nised by MSPDebug as one of the given type during initializa‐
71 tion. This overrides the device ID returned by the FET.
72 --usb-list
74 List available USB devices and exit.
75 --force-reset
77 When using a FET device, always send a reset during initializa‐
78 tion. By default, an initialization without reset will be tried
79 first.
80 --version
82 Show program version and copyright information.
83
85 A driver name must be specified on the command line for MSPDebug to
86 connect to. Valid driver names are listed here.
87 rf2500 Connect to an eZ430-RF2500 device. Only USB connection is sup‐
89 ported.
90 olimex Connect to an Olimex MSP-JTAG-TINY device. Both USB and tty
92 access are supported.
93 olimex-iso
95 Connect to an Olimex MSP-JTAG-ISO device. Only tty access is
96 supported.
97 sim Do not connect to any hardware device, but instead start in sim‐
99 ulation mode. A 64k buffer is allocated to simulate the device
100 memory.
101 During simulation, addresses below 0x0200 are assumed to be IO
103 memory. Programmed IO writes to and from IO memory are handled
104 by the IO simulator, which can be configured and controlled with
105 the simio command, described below.
106 This mode is intended for testing of changes to MSPDebug, and
108 for aiding the disassembly of MSP430 binaries (as all binary and
109 symbol table formats are still usable in this mode).
110 uif Connect to an eZ430-F2013 or a FET430UIF device. The device
112 argument should be the filename of the appropriate tty device.
113 The TI serial converter chips on these devices are supported by
114 newer versions of the Linux kernel, and should appear as
115 /dev/ttyXX when attached.
116 USB connection is not supported for this driver.
118 uif-bsl
120 Connect to the bootloader on a FET430UIF device. These devices
121 contain MSP430F419 chips. By sending a special command sequence,
122 you can obtain access to the bootloader and inspect memory on
123 the MSP430F419 in the programming device itself.
124 Currently, only memory read/write and erase are supported. CPU
126 control via the bootloader is not possible.
127 USB connection is not supported for this driver.
129 flash-bsl
131 Connect to the built-in bootloader in MSP430 devices with flash
132 bootloader memory. Devices with ROM bootloaders require another
133 driver. Currently, this driver must mass-erase the device in
134 order to gain access. Read, write, and erase operations are sup‐
135 ported.
136 USB connection is not supported for this driver. Connection is
138 via serial port, and bootloader entry is accomplished via the
139 RTS and DTR lines. Connect RTS to the device's TEST pin and DTR
140 to the device's RST pin. Use an appropriate serial level-
141 shifter to make the connection, if necessary. If connecting to
142 a device with non-multiplexed JTAG pins, connect RTS to the
143 device's TCK pin via an inverter.
144
146 MSPDebug can accept commands either through an interactive prompt, or
147 non-interactively when specified on the command line. The supported
148 commands are listed below.
149 Commands take arguments separated by spaces. Any text string enclosed
151 in double-quotation marks is considered to be a single argument, even
152 if it contains space characters. Within a quoted string, the usual C-
153 style backslash substitutions can be used.
154 Commands can be specified by giving the first few characters of the
156 command name, provided that the prefix is unambiguous. Some commands
157 support automatic repeat. For these commands, pressing enter at the
158 reader prompt without typing anything will cause repeat execution.
159 = expression
161 Evaluate an address expression and show both its value, and the
162 result when the value is looked up in reverse in the current
163 symbol table. This result is of the form symbol+offset, where
164 symbol is the name of the nearest symbol not past the address in
165 question.
166 See the section marked ADDRESS EXPRESSIONS for more information
168 on the syntax of expressions.
169 alias Show a list of defined command aliases.
171 alias name
173 Remove a previously defined command alias.
174 alias name command
176 Define a command alias. The text command will be substituted for
177 name when looking up commands. The given command text may con‐
178 tain a command plus arguments, if the entire text is wrapped in
179 quotes when defining the alias. To avoid alias substitution when
180 interpreting commands, prefix the command with \ (a backslash
181 character).
182 break Show a list of active breakpoints. Breakpoints can be added and
184 removed with the setbreak and delbreak commands. Each breakpoint
185 is numbered with an integer index starting at 0.
186 cgraph address length [address]
188 Construct the call graph of all functions contained or refer‐
189 enced in the given range of memory. If a particular function is
190 specified, then details for that node of the graph are dis‐
191 played. Otherwise, a summary of all nodes is displayed.
192 Information from the symbol table is used for hinting at the
194 possible locations of function starts. Any symbol which does not
195 contain a "." is considered a possible function start.
196 Callers and callee names are shown prefixed by a "*" where the
198 transition is a tail-call type transition.
199 delbreak [index]
201 Delete one or all breakpoints. If an index is given, the
202 selected breakpoint is deleted. Otherwise, all breakpoints are
203 cleared.
204 dis address [length]
206 Dissassemble a section of memory. Both arguments may be address
207 expressions. If no length is specified, a section of the default
208 length (64 bytes) is disassembled and shown.
209 If symbols are available, then all addresses used as operands
211 are translated into symbol+offset form.
212 This command supports repeat execution. If repeated, it contin‐
214 ues to disassemble another block of memory following that last
215 printed.
216 erase [all|segment] [address]
218 Erase the device under test. With no arguments, all code memory
219 is erased (but not information or boot memory). With the argu‐
220 ment "all", a mass erase is performed (the results may depend on
221 the state of the LOCKA bit in the flash memory controller).
222 Specify "segment" and a memory address to erase an individual
224 flash segment.
225 exit Exit from MSPDebug.
227 gdb [port]
229 Start a GDB remote stub, optionally specifying a TCP port to
230 listen on. If no port is given, the default port is 2000.
231 MSPDebug will wait for a connection on this port, and then act
233 as a GDB remote stub until GDB disconnects.
234 GDB's "monitor" command can be used to issue MSPDebug commands
236 via the GDB interface. Supplied commands are executed non-inter‐
237 actively, and the output is sent back to be displayed in GDB.
238 help [command]
240 Show a brief listing of available commands. If an argument is
241 specified, show the syntax for the given command. The help text
242 shown when no argument is given is also shown when MSPDebug
243 starts up.
244 hexout address length filename
246 Read the specified section of the device memory and save it to
247 an Intel HEX file. The address and length arguments may both be
248 address expressions.
249 If the specified file already exists, then it will be overwrit‐
251 ten. If you need to dump memory from several disjoint memory
252 regions, you can do this by saving each section to a separate
253 file. The resulting files can then be concatenated together to
254 form a single valid HEX file.
255 isearch address length [options ...]
257 Search over the given range for an instruction which matches the
258 specified search criteria. The search may be narrowed by speci‐
259 fying one or more of the following terms:
260 opcode opcode
262 Match the specified opcode. Byte/word specifiers are not
263 recognised, as they are specified with other options.
264 byte Match only byte operations.
266 word Match only word operations.
268 aword Match only address-word (20-bit) operations.
270 jump Match only jump instructions (conditional and uncondi‐
272 tional jumps, but not instructions such as BR which load
273 the program counter explicitly).
274 single Match only single-operand instructions.
276 double Match only double-operand instructions.
278 noarg Match only instructions with no arguments.
280 src address
282 Match instructions with the specified value in the source
283 operand. The value may be given as an address expression.
284 Specifying this option implies matching of only double-
285 operand instructions.
286 dst address
288 Match instructions with the specified value in the desti‐
289 nation operand. This option implies that no-argument
290 instructions are not matched.
291 srcreg register
293 Match instructions using the specified register in the
294 source operand. This option implies matching of only dou‐
295 ble-operand instructions.
296 dstreg register
298 Match instructions using the specified register in the
299 destination operand. This option implies that no-argu‐
300 ment instructions are not matched.
301 srcmode mode
303 Match instructions using the specified mode in the source
304 operand. See below for a list of modes recognised. This
305 option implies matching of only double-operand instruc‐
306 tions.
307 dstmode mode
309 Match instructions using the specified mode in the desti‐
310 nation operand. See below for a list of modes. This
311 option implies that no-argument instructions are not
312 matched.
313 For single-operand instructions, the operand is considered to be
315 the destination operand.
316 The seven addressing modes used by the MSP430 are represented by
318 single characters, and are listed here:
319 R Register mode.
321 I Indexed mode.
323 S Symbolic mode.
325 & Absolute mode.
327 @ Register-indirect mode.
329 + Register-indirect mode with auto-increment.
331 # Immediate mode.
333 load filename
335 Program the device under test using the binary file supplied.
336 This command is like prog, but it does not load symbols or erase
337 the device before programming.
338 The CPU is reset and halted before and after programming.
340 locka [set|clear]
342 Show or change the status of the LOCKA bit in the chip's memory
343 controller. The LOCKA bit is set on POR and acts as a write-pro‐
344 tect bit for info segment A. This segment contains factory-con‐
345 figured calibration data, and under normal circumstances, should
346 not be changed.
347 If the LOCKA bit is cleared, erasing the info A segment is pos‐
349 sible.
350 The LOCKA bit also affects the behaviour of the "erase all" com‐
352 mand. If LOCKA is set (the default), only main memory is erased.
353 If LOCKA is cleared, main and information memory are both
354 erased.
355 md address [length]
357 Read the specified section of device memory and display it as a
358 canonical-style hexdump. Both arguments may be address expres‐
359 sions. If no length is specified, a section of the default
360 length (64 bytes) is shown.
361 The output is split into three columns. The first column shows
363 the starting address for the line. The second column lists the
364 hexadecimal values of the bytes. The final column shows the
365 ASCII characters corresponding to printable bytes, and . for
366 non-printing characters.
367 This command supports repeat execution. If repeated, it contin‐
369 ues to print another block of memory following that last
370 printed.
371 mw address bytes ...
373 Write a sequence of bytes at the given memory address. The
374 address given may be an address expression. Bytes values are
375 two-digit hexadecimal numbers separated by spaces.
376 Unless used in the simulation mode, this command can only be
378 used for programming flash memory.
379 opt [name] [value]
381 Query, set or list option variables. MSPDebug's behaviour can be
382 configured using option variables, described below in the sec‐
383 tion OPTIONS.
384 Option variables may be of three types: boolean, numeric or
386 text. Numeric values may be specified as address expressions.
387 With no arguments, this command displays all available option
389 variables. With just an option name as its argument, it dis‐
390 plays the current value of that option.
391 prog filename
393 Erase and reprogram the device under test using the binary file
394 supplied. The file format will be auto-detected and may be any
395 of the supported file formats.
396 In the case of a file containing symbols, symbols will be auto‐
398 matically loaded from the file into the symbol table (discarding
399 any existing symbols), if they are present.
400 The CPU is reset and halted before and after programming.
402 read filename
404 Read commands from the given file, line by line and process each
405 one. Any lines whose first non-space character is # are
406 ignored. If an error occurs while processing a command, the rest
407 of the file is not processed.
408 regs Show the current value of all CPU registers in the device under
410 test.
411 reset Reset (and halt) the CPU of the device under test.
413 run Start running the CPU. The interactive command prompt is blocked
415 when the CPU is started and the prompt will not appear again
416 until the CPU halts. The CPU will halt if it encounters a break‐
417 point, or if Ctrl-C is pressed by the user.
418 After the CPU halts, the current register values are shown as
420 well as a disassembly of the first few instructions at the
421 address selected by the program counter.
422 set register value
424 Alter the value of a register. Registers are specified as num‐
425 bers from 0 through 15. Any leading non-numeric characters are
426 ignored (so a register may be specified as, for example, "R12").
427 The value argument is an address expression.
428 setbreak address [index]
430 Add a new breakpoint. The breakpoint location is an address
431 expression. An optional index may be specified, indicating that
432 this new breakpoint should overwrite an existing slot. If no
433 index is specified, then the breakpoint will be stored in the
434 next unused slot.
435 simio add class name [args ...]
437 Add a new peripheral to the IO simulator. The class parameter
438 may be any of the peripheral types named in the output of the
439 simio classes command. The name parameter is a unique name
440 assigned by the user to this peripheral instance, and is used
441 with other commands to refer to this instance of the peripheral.
442 Some peripheral classes take arguments upon creation. These are
444 documented in the output to the simio help command.
445 simio classes
447 List the names of the different types of peripherals which may
448 be added to the simulator. You can use the simio help command to
449 obtain more information about each peripheral type.
450 simio config name param [args ...]
452 Configure or perform some action on a peripheral instance. The
453 param argument is specific to the peripheral type. A list of
454 valid configuration commands can be obtained by using the simio
455 help command.
456 simio del name
458 Remove a previously added peripheral instance. The name argument
459 should be the name of the peripheral that was assigned with the
460 simio add command.
461 simio devices
463 List all peripheral instances currently attached to the simula‐
464 tor, along with their types and interrupt status. You can obtain
465 more detailed information for each instance with the simio info
466 command.
467 simio help class
469 Obtain more information about a peripheral class. The documenta‐
470 tion given will list constructor arguments and configuration
471 parameters for the device type.
472 simio info name
474 Display detailed status information for a particular peripheral.
475 The type of information displayed is specific to each type of
476 peripheral.
477 step [count]
479 Step the CPU through one or more instructions. After stepping,
480 the new register values are displayed, as well as a disassembly
481 of the instructions at the address selected by the program
482 counter.
483 An optional count can be specified to step multiple times. If no
485 argument is given, the CPU steps once. This command supports
486 repeat execution.
487 sym clear
489 Clear the symbol table, deleting all symbols.
490 sym set name value
492 Set or alter the value of a symbol. The value given may be an
493 address expression.
494 sym del name
496 Delete the given symbol from the symbol table.
497 sym import filename
499 Load symbols from the specified file and add them to the symbol
500 table. The file format will be auto-detected and may be either
501 ELF32 or a BSD-style symbol listing (like the output from
502 nm(1)).
503 Symbols can be combined from many sources, as the syms command
505 adds to the existing symbol table without discarding existing
506 symbols.
507 sym import+ filename
509 This command is similar to sym import, except that the symbol
510 table is not cleared first. By using this command, symbols from
511 multiple sources can be combined.
512 sym export filename
514 Save all symbols currently defined to the given file. The sym‐
515 bols are saved as a BSD-style symbol table. Note that symbol
516 types are not stored by MSPDebug, and all symbols are saved as
517 type t.
518 sym find [regex]
520 Search for symbols. If a regular expression is given, then all
521 symbols matching the expression are printed. If no expression is
522 specified, then the entire symbol table is listed.
523 sym rename regex string
525 Rename symbols by searching for those matching the given regular
526 expression and substituting the given string for the matched
527 portion. The symbols renamed are displayed, as well as a total
528 count of all symbols renamed.
529
531 The following binary/symbol formats are supported by MSPDebug:
532 ELF32
534 COFF
535 Intel HEX (program only)
536 BSD symbol table (symbols only)
537 TI Text (program only)
538 SREC (program only)
539
541 The IO simulator subsystem consists of a database of device classes,
542 and a list of instances of those classes. Each device class has a dif‐
543 ferent set of constructor arguments, configuration parameters and
544 information which may be displayed. This section describes the opera‐
545 tion of the available device classes in detail.
546 In the list below, each device class is listed, followed by its con‐
548 structor arguments.
549 gpio Digital IO port simulator. This device simulates any of the dig‐
551 ital ports with or without interrupt capability. It has the fol‐
552 lowing configuration parameters:
553 base address
555 Set the base address for this port. Note that for ports
556 without interrupt capability, the resistor enable port
557 has a special address which is computable from the base
558 address.
559 irq vector
561 Enable interrupt functionality for this port by specify‐
562 ing an interrupt vector number.
563 noirq Disable interrupt functionality for this port.
565 verbose
567 Print a state change message every time the port output
568 changes.
569 quiet Don't print anything when the port state changes (the
571 default).
572 set pin value
574 Set the input pin state for the given pin on this port.
575 The pin parameter should be an index between 0 and 7. The
576 value should be either zero (for a low state) or non-zero
577 (for a high state).
578 hwmult This peripheral simulates the hardware multiplier. It has no
580 constructor or configuration parameters, and does not provide
581 any extended information.
582 timer [size]
584 This peripheral simulators Timer_A modules, and can be used to
585 simulate Timer_B modules, provided that the extended features
586 aren't required.
587 The constructor takes a size argument specifying the number of
589 capture/compare registers in this peripheral instance. The num‐
590 ber of such registers may not be less than 2, or greater than 7.
591 The IO addresses and IRQs used are configurable. The default IO
593 addresses used are those specified for Timer_A in the MSP430
594 hardware documentation.
595 base address
597 Alter the base IO address. By default, this is 0x0160. By
598 setting this to 0x0180, a Timer_B module may be simu‐
599 lated.
600 irq0 number
602 Set the TACCR0 interrupt vector number. By default, this
603 is interrupt vector 9. This interrupt is self-clearing,
604 and higher priority than the TACCR1/TAIFG vector.
605 irq1 number
607 Set the TACCR1/TAIFG interrupt vector. By default, this
608 is interrupt vector 8.
609 iv address
611 Alter the address of the interrupt vector register. By
612 default, this is 0x012E. By setting this to 0x011E, a
613 Timer_B module may be simulated.
614 set channel value
616 When Timer_A is used in capture mode, the CCI bit in each
617 capture register reflects the state of the corresponding
618 input pin, and can't be altered in software. This config‐
619 uration command can be used to simulate changes in input
620 pin state, and will trigger the corresponding interrupts
621 if the peripheral is so configured.
622 tracer [history-size]
624 The tracer peripheral is a debugging device. It can be used to
625 investigate and record the IO activity of a running program, to
626 benchmark execution time, and to simulate interrupts.
627 The information displayed by the tracer gives a running count of
629 clock cycles from each of the system clocks, and an instruction
630 count. A list of the N most recent IO events is also displayed
631 (this is configurable via the history-size argument of the con‐
632 structor). Each IO event is timestamped by the number of MCLK
633 cycles that have elapsed since the last reset of the device's
634 counter.
635 The IO events that it records consist of programmed IO reads and
637 writes, interrupt acceptance, and system resets. As well as
638 keeping the IO events in a rotating buffer, the tracer can be
639 configured to display the events as they occur.
640 Note that since clock cycles don't advance while the CPU isn't
642 running, this peripheral can be used to calculate execution
643 times for blocks of code. This can be achieved by setting a
644 breakpoint at the end of the code block, setting the program
645 counter to the start of the code block, clearing the tracer and
646 running the code. After the breakpoint is reached, the informa‐
647 tion displayed by the tracer will contain a count of MCLK cycles
648 elapsed during the last run.
649 The configuration parameters for this device class are:
651 verbose
653 Start displaying IO events as they occur, as well as
654 recording them in the rotating buffer.
655 quiet Stop displaying IO events as they occur, and just record
657 them in the buffer.
658 trigger irq
660 Signal an interrupt request to the CPU. This request will
661 remain raised until accepted by the CPU or cleared by the
662 user.
663 untrigger
665 Clear a signalled interrupt request.
666 clear Reset the clock cycle and instruction counts to 0, and
668 clear the IO event history.
669 wdt This peripheral simulates the Watchdog Timer+, which can be used
671 in software either as a watchdog or as an interval timer. It has
672 no constructor arguments.
673 The simulated state of the NMI/RST# pin can be controlled
675 through a configuration parameter. Note that if this pin state
676 is held low with the pin mode selected as a reset (the default),
677 the CPU will not run.
678 The extended information for this peripheral shows all register
680 states, including the hidden counter register. Configuration
681 parameters are:
682 nmi state
684 Set the NMI/RST# pin state. The argument should be zero
685 to indicate a low state or non-zero for a high state.
686 irq irq
688 Select the interrupt vector for interval timer mode. The
689 default is to use interrupt vector 10.
690
692 Any command which accepts a memory address, length or register value as
693 an argument may be given an address expression. An address expression
694 consists of an algebraic combination of values.
695 An address value may be either a symbol name, a hex value preceeded
697 with the specifier "0x", a decimal value preceeded with the specifier
698 "0d", or a number in the default input radix (without a specifier). See
699 the option iradix for more information.
700 The operators recognised are the usual algebraic operators: +, -, *, /,
702 %, ( and ). Operator precedence is the same as in C-like languages, and
703 the - operator may be used as a unary negation operator.
704 The following are all valid examples of address expressions:
706 2+2
708 table_start + (elem_size + elem_pad)*4
709 main+0x3f
710 __bss_end-__bss_start
711
713 MSPDebug's behaviour can be configured via the following variables:
714 color (boolean)
716 If true, MSPDebug will colorize debugging output.
717 fet_block_size (numeric)
719 Change the size of the buffer used to transfer memory to and
720 from the FET. Increasing the value from the default of 64 will
721 improve transfer speed, but may cause problems with some chips.
722 gdb_loop (boolean)
724 Automatically restart the GDB server after disconnection. If
725 this option is set, then the GDB server keeps running until an
726 error occurs, or the user interrupts with Ctrl+C.
727 iradix (numeric)
729 Default input radix for address expressions. For address values
730 with no radix specifier, this value gives the input radix, which
731 is 10 (decimal) by default.
732 quiet (boolean)
734 If set, MSPDebug will supress most of its debug-related output.
735 This option defaults to false, but can be set true on start-up
736 using the -q command-line option.
737
739 nm(1), gdb(1), objcopy(1)
740
742 If you find any bugs, you should report them to the author at
743 dlbeer@gmail.com. It would help if you could include a transcript of an
744 MSPDebug session illustrating the program, as well as any relevant
745 binaries or other files.
746
748 Copyright (C) 2009-2011 Daniel Beer <dlbeer@gmail.com>
749 MSPDebug is free software, distributed under the terms of the GNU Gen‐
751 eral Public license (version 2 or later). See the file COPYING included
752 with the source code for more details.
753Version 0.15 5 Apr 2011 mspdebug(1)