mspdebug fork adding the MehFET driver (USB device code at )
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

853 lines
39 KiB

5 years ago
10 years ago
10 years ago
4 months ago
9 years ago
5 years ago
4 months ago
11 years ago
9 years ago
  1. .TH mspdebug 1 "24 Jul 2017" "Version 0.25"
  2. .SH NAME
  3. MSPDebug - debugging tool for MSP430 MCUs
  5. \fBmspdebug\fR [options] \fIdriver\fR [\fIcommand\fR ...]
  7. MSPDebug is a command-line tool designed for debugging and programming
  8. the MSP430 family of MCUs. It supports the eZ430-F2013, eZ430-RF2500,
  9. Launchpad, Chronos, FET430UIF, GoodFET, Olimex MSP430-JTAG-TINY and
  10. MSP430-JTAG-ISO programming tools, as well as a simulation mode.
  11. When started with appropriate options, MSPDebug will attempt to
  12. connect to the debugging tool specified and identify the device under
  13. test. Once connected, the user is presented with a command prompt
  14. which can be used to reflash the device memory, inspect memory and
  15. registers, set registers, and control the CPU (single step, run and
  16. run to breakpoint).
  17. It supports a variety of file formats, described in the section
  18. \fBBINARY FORMATS\fR below. It can also be used as a remote stub
  19. for \fBgdb\fR(1).
  20. On startup, MSPDebug will look for a file called .mspdebug first in the
  21. current directory, and then in the user's home directory. If either file
  22. exists, commands will be read and executed from this file before
  23. executing any other commands or starting the interactive reader.
  24. Alternatively, a configuration file can be explicitly specified with the
  25. \fB-C\fR option.
  27. Command-line options accepted by MSPDebug are described below. If
  28. commands are specified on the end of the command-line, then they are
  29. executed after connecting to the device, and the interactive prompt is
  30. not started. Please be aware that commands consisting of multiple
  31. words need to be enclosed in quotation marks, otherwise they are
  32. treated as single commands. Thus the common prog command would be
  33. used as "prog main.elf".
  34. See the section labelled \fBCOMMANDS\fR for more information.
  35. .IP "\-q"
  36. Start in quiet mode. See the "quiet" option described below.
  37. .IP "\-v \fIvoltage\fR"
  38. Set the programming voltage. The voltage should be specified as an integer
  39. in millivolts. It defaults to 3000 (3.0 V).
  40. .IP "\-j"
  41. Use JTAG instead of Spy-Bi-Wire to communicate with the MSP430. This
  42. option doesn't work with eZ430 or eZ430-RF2500 devices, which support
  43. Spy-Bi-Wire only.
  44. .IP "\-d \fIdevice\fR"
  45. Specify that the driver should connect via a tty device rather than USB.
  46. The supported connection methods vary depending on the driver. See the
  47. section \fBDRIVERS\fR below for details.
  48. .IP "\-U \fIbus\fR:\fIdevice\fR"
  49. Specify a particular USB device to connect to. Without this option,
  50. the first device of the appropriate type is opened.
  51. .IP "\-V \fIvid\fR:\fIpid\fR"
  52. Specify a VID and PID of the USB device to connect to, or override the
  53. default VID and PID. Some drives, such as \fBmehfet\fR, require this option,
  54. while others have a default VID and PID which can be overridden.
  55. .IP "\-s \fIserial\fR"
  56. Specify a particular USB device serial number to connect to. Use this
  57. option to distinguish between multiple devices of the same type.
  58. .IP "\-n"
  59. Do not process the startup file (~/.mspdebug).
  60. .IP "\-C \fIfile\fR"
  61. Specify an alternative configuration file (default is ~/.mspdebug). If -n
  62. is specified as well, no file will be read.
  63. .IP "\--long-password"
  64. When using the flash-bsl driver, send a 32-byte BSL password instead
  65. of the standard 16-byte password.
  66. .IP "\-\-help"
  67. Display a brief help message and exit.
  68. .IP "\-\-fet\-list"
  69. Display a list of chips supported by the FET driver (the driver used
  70. for UIF, RF2500 and Olimex devices).
  71. .IP "\-\-fet\-force\-id \fIstring\fR"
  72. When using a FET device, force the connected chip to be recognised by
  73. MSPDebug as one of the given type during initialization. This overrides
  74. the device ID returned by the FET. The given string should be a chip
  75. name in long form, for example "MSP430F2274".
  76. .IP "\-\-fet\-skip\-close"
  77. When using a FET device, skip the JTAG close procedure when disconnecting.
  78. With some boards, this removes the need to replug the debugger after use.
  79. .IP "\-\-usb\-list"
  80. List available USB devices and exit.
  81. .IP "\-\-force-reset"
  82. When using a FET device, always send a reset during initialization. By
  83. default, an initialization without reset will be tried first.
  84. .IP "\-\-allow-fw-update"
  85. When using a V3 FET device via the TI library, allow the library to
  86. perform a firmware update if the FET firmware is incompatible with the
  87. library.
  88. .IP "\-\-require-fw-update \fIimage.txt\fR"
  89. When using a V3 FET device, or certain Olimex devices, force a firmware
  90. update using the given firmware image. The firmware format depends on
  91. the driver.
  92. .IP "\-\-version"
  93. Show program version and copyright information.
  94. .IP "\-\-embedded"
  95. Start mspdebug as an embedded subprocess. See the documentation
  96. accompanying the source release for more information on embedded mode.
  97. .IP "\-\-bsl\-entry\-sequence \fIseq\fR"
  98. Specify a BSL entry sequence. Each character specifies a modem control
  99. line transition (R: RTS on, r: RTS off, D: DTR on, d: DTR off). A comma
  100. indicates a delay. The entry and exit sequences are separated by a
  101. colon. The default value is \fBdR,r,R,r,R,D:dR,DR\fR, for the
  102. \fBflash-bsl\fR driver.
  103. .IP "\-\-bsl\-entry\-password \fIhex\-string\fR"
  104. Specify a BSL unlock password as a hexadecimal byte string. This
  105. option affects both the flash and ROM BSL drivers. The password will
  106. be padded with 0xff bytes, and the default password is a sequence
  107. consisting of only 0xff bytes.
  108. .SH DRIVERS
  109. For drivers supporting both USB and tty access, USB is the default,
  110. unless specified otherwise (see \fB-d\fR above).
  111. On Linux, if USB access is used, the kernel driver (if any) is
  112. detached from the tty device. If further access to the tty device is
  113. needed, unloading and re-loading of the driver (e.g. cdc-acm.ko) is required.
  114. A driver name must be specified on the command line for MSPDebug to
  115. connect to. Valid driver names are listed here.
  116. .IP "\fBrf2500\fR"
  117. Connect to an eZ430-RF2500, Launchpad or Chronos device. Only USB
  118. connection is supported.
  119. .IP "\fBolimex\fR"
  120. Connect to an Olimex MSP430-JTAG-TINY device. Both USB and tty access are
  121. supported.
  122. .IP "\fBolimex-v1\fR"
  123. Connect to an Olimex MSP430-JTAG-TINY (V1) device. Both USB and tty access are
  124. supported. This driver must be used instead of \fBolimex\fR if connecting
  125. to a V1 device via a tty interface.
  126. .IP "\fBolimex-iso\fR"
  127. Connect to an Olimex MSP430-JTAG-ISO device. Both USB and tty access are
  128. supported.
  129. .IP "\fBolimex-iso-mk2\fR"
  130. Connect to an Olimex MSP430-JTAG-ISO-MK2 device. Both USB and tty
  131. access are supported.
  132. .IP "\fBsim\fR"
  133. Do not connect to any hardware device, but instead start in simulation
  134. mode. A 64k buffer is allocated to simulate the device memory.
  135. During simulation, addresses below 0x0200 are assumed to be IO memory.
  136. Programmed IO writes to and from IO memory are handled by the IO
  137. simulator, which can be configured and controlled with the \fBsimio\fR
  138. command, described below.
  139. This mode is intended for testing of changes to MSPDebug, and for
  140. aiding the disassembly of MSP430 binaries (as all binary and symbol
  141. table formats are still usable in this mode).
  142. .IP "\fBuif\fR"
  143. Connect to an eZ430-F2013 or a FET430UIF device. The device argument
  144. should be the filename of the appropriate tty device. The TI serial
  145. converter chips on these devices are supported by newer versions of the
  146. Linux kernel, and should appear as /dev/tty\fIXX\fR when attached.
  147. USB connection is supported for this driver. The USB interface chip in
  148. these devices is a TI3410, which requires a firmware download on
  149. startup. MSPDebug will search for a file called ti_3410.fw.ihex in
  150. the configured library directory and the current directory. You can
  151. specify an alternate location for the file via the
  152. \fBMSPDEBUG_TI3410_FW\fR environment variable.
  153. .IP "\fBuif-bsl\fR"
  154. Connect to the bootloader on a FET430UIF device. These devices contain
  155. MSP430F1612 chips. By sending a special command sequence, you can obtain
  156. access to the bootloader and inspect memory on the MSP430F1612 in the
  157. programming device itself.
  158. Currently, only memory read/write and erase are supported. CPU control
  159. via the bootloader is not possible.
  160. .IP "\fBflash-bsl\fR"
  161. Connect to the built-in bootloader in MSP430 devices with flash bootloader
  162. memory. Devices with ROM bootloaders require another driver. Currently,
  163. this driver must mass-erase the device in order to gain access. Read,
  164. write, and erase operations are supported.
  165. USB connection is not supported for this driver. Connection is via serial
  166. port, and bootloader entry is accomplished via the RTS and DTR lines.
  167. Connect RTS to the device's TEST pin and DTR to the device's RST pin.
  168. Use an appropriate serial level-shifter to make the connection, if necessary.
  169. If connecting to a device with non-multiplexed JTAG pins, connect RTS to
  170. the device's TCK pin via an inverter.
  171. .IP "\fBgdbc\fR"
  172. GDB client mode. Connect to a server which implements the GDB remote
  173. protocol and provide an interface to it. To use this driver, specify
  174. the remote address in \fIhostname:port\fR format using the \fB-d\fR
  175. option.
  176. .IP "\fBtilib\fR"
  177. Use the Texas Instruments MSP430.DLL to access the device. The library
  178. file (MSP430.DLL for Windows, for Unix-like systems) must
  179. be present in the dynamic loader search path, unless the
  180. \fBMSPDEBUG_TILIB_PATH\fR environment variable is present in which
  181. case it will look there.
  182. USB connection is not supported for this driver. This driver supports
  183. watchpoints. Note that the \fB-d\fR option for this driver passes its
  184. argument straight through to the library's \fBMSP430_Initialize\fR
  185. function. Any special argument supported by that function is therefore
  186. accessible via the \fB-d\fR option.
  187. Automatic device discovery works only on Linux and Windows. On other
  188. systems, the appropriate ACM serial node must be explicitly specified.
  189. .IP "\fBgoodfet\fR"
  190. Connect to a GoodFET device. JTAG mode must be used, and only tty access
  191. is supported. This device can be used for memory access (read, erase and
  192. program), but CPU control is limited. The CPU may be halted, run and
  193. reset, but register access and breakpoints aren't supported.
  194. .IP "\fBpif\fR"
  195. Connect to a parallel-port JTAG controller. JTAG mode must be used, and
  196. only tty access is supported. Currently, this driver is only supported
  197. on Linux, FreeBSD and DragonFly BSD. A parallel port device (ppdev on
  198. Linux, ppi on FreeBSD and DragonFly BSD) must be specified via the
  199. \fB-d\fR option.
  200. .IP "\fBgpio\fR"
  201. Connect to system gpios. JTAG mode must be used, and
  202. only tty access is supported. Currently, this driver is only supported
  203. on Linux, FreeBSD and DragonFly BSD. The gpios to used must defined using
  204. a string like "tdi=7 tdo=8 tms=9 tck=4 rst=10 tst=11" via the
  205. \fB-d\fR option. (don't forget the quotes)
  206. .IP "\fBload-bsl\fR"
  207. Connect to a USB bootloader. The stub bootloader will be used to load a
  208. fuller-featured bootloader into RAM for execution.
  209. .IP "\fBezfet\fR"
  210. This driver is for Texas Instruments' eZ-FET devices. It supports USB
  211. and tty access. It does not support breakpoint control.
  212. .IP "\fBrom-bsl\fR"
  213. This driver is for the old-style (ROM) bootstrap loader. It supports tty
  214. access only. Entry is attempted via the RTS/DTR signals. The default
  215. sequence is \fBDR,r,R,r,d,R:DR,r\fR, but you can override this with the
  216. \fB\-\-bsl\-entry\-sequence\fR option.
  217. \fBWARNING:\fR this driver unlocks the BSL by performing a mass erase.
  218. There are reports of this operation causing an erase of info A in some
  219. devices. Use at your own risk.
  220. .IP "\fBbus-pirate\fR"
  221. Raw JTAG using Bus Pirate devices.
  222. .IP "\fBmehfet\fR"
  223. Connect to a MehFET USB-based debugging protocol-capable device. It can
  224. support both JTAG and Spy-Bi-Wire. For now, only 16-bit CPUs (that is,
  225. non-430X or Xv2) are suppored, as with the \fBpif\fR, \fBgpio\fR,
  226. \fBbus-pirate\fR and \fBgoodfet\fR rivers.
  227. For documentation on the USB protocol, see the \fBSEE ALSO\fR section.
  229. MSPDebug can accept commands either through an interactive prompt, or
  230. non-interactively when specified on the command line. The supported
  231. commands are listed below.
  232. Commands take arguments separated by spaces. Any text string enclosed
  233. in double-quotation marks is considered to be a single argument, even
  234. if it contains space characters. Within a quoted string, the usual
  235. C-style backslash substitutions can be used.
  236. Commands can be specified by giving the first few characters of the
  237. command name, provided that the prefix is unambiguous. Some commands
  238. support automatic repeat. For these commands, pressing enter at the
  239. reader prompt without typing anything will cause repeat execution.
  240. .IP "\fB!\fR [\fIcommand\fR [\fIargs ...\fR]]"
  241. Invoke an interactive operating system shell. If any arguments
  242. are specified, the first one is taken as a command to execute, with the
  243. rest of the arguments as the arguments to the command.
  244. This command is not yet available on non-POSIX systems.
  245. .IP "\fB=\fR \fIexpression\fR"
  246. Evaluate an address expression and show both its value, and the result
  247. when the value is looked up in reverse in the current symbol
  248. table. This result is of the form \fIsymbol\fR+\fIoffset\fR, where
  249. \fIsymbol\fR is the name of the nearest symbol not past the address in
  250. question.
  251. See the section marked \fBADDRESS EXPRESSIONS\fR for more information on
  252. the syntax of expressions.
  253. .IP "\fBalias\fR"
  254. Show a list of defined command aliases.
  255. .IP "\fBalias\fR \fIname\fR"
  256. Remove a previously defined command alias.
  257. .IP "\fBalias\fR \fIname\fR \fIcommand\fR"
  258. Define a command alias. The text \fIcommand\fR will be substituted for
  259. \fIname\fR when looking up commands. The given command text may contain
  260. a command plus arguments, if the entire text is wrapped in quotes when
  261. defining the alias. To avoid alias substitution when interpreting
  262. commands, prefix the command with \\ (a backslash character).
  263. .IP "\fBblow_jtag_fuse\fR"
  264. Blow the device's JTAG fuse.
  265. .B WARNING: this is an irreversible operation!
  266. .IP "\fBbreak\fR"
  267. Show a list of active breakpoints. Breakpoints can be added and removed
  268. with the \fBsetbreak\fR and \fBdelbreak\fR commands. Each breakpoint is
  269. numbered with an integer index starting at 0.
  270. .IP "\fBcgraph\fR \fIaddress\fR \fIlength\fR [\fIaddress\fR]"
  271. Construct the call graph of all functions contained or referenced in
  272. the given range of memory. If a particular function is specified, then
  273. details for that node of the graph are displayed. Otherwise, a summary
  274. of all nodes is displayed.
  275. Information from the symbol table is used for hinting at the possible
  276. locations of function starts. Any symbol which does not contain a "."
  277. is considered a possible function start.
  278. Callers and callee names are shown prefixed by a "*" where the
  279. transition is a tail-call type transition.
  280. .IP "\fBdelbreak\fR [\fIindex\fR]"
  281. Delete one or all breakpoints. If an index is given, the selected breakpoint
  282. is deleted. Otherwise, all breakpoints are cleared.
  283. .IP "\fBdis\fR \fIaddress\fR [\fIlength\fR]"
  284. Dissassemble a section of memory. Both arguments may be address
  285. expressions. If no length is specified, a section of the default
  286. length (64 bytes) is disassembled and shown.
  287. If symbols are available, then all addresses used as operands are
  288. translated into \fIsymbol\fR+\fIoffset\fR form.
  289. This command supports repeat execution. If repeated, it continues to
  290. disassemble another block of memory following that last printed.
  291. .IP "\fBerase\fR [\fBall\fR|\fBsegment\fR|\fBsegrange\fR] [\fIaddress\fR] [\fIsize\fR] [\fIsegrange\fR]"
  292. Erase the device under test. With no arguments, all code memory is erased
  293. (but not information or boot memory). With the argument "all", a mass
  294. erase is performed (the results may depend on the state of the LOCKA
  295. bit in the flash memory controller).
  296. Specify "segment" and a memory address to erase an individual flash
  297. segment. Specify "segrange", an address, size and segment size to erase
  298. an arbitrary set of contiguous segments.
  299. .IP "\fBexit\fR"
  300. Exit from MSPDebug.
  301. .IP "\fBfill\fR \fIaddress\fR \fIlength\fR \fIb0\fR [\fIb1\fR \fIb2\fR ...]
  302. Fill the memory region of size \fIlength\fR starting at \fIaddress\fR with
  303. the pattern of bytes given (specified in hexadecimal). The pattern will be
  304. repeated without padding as many times as necessary without exceeding the
  305. bounds of the specified region.
  306. .IP "\fBgdb\fR [\fIport\fR]"
  307. Start a GDB remote stub, optionally specifying a TCP port to listen on.
  308. If no port is given, the default port is controlled by the option
  309. \fBgdb_default_port\fR.
  310. MSPDebug will wait for a connection on this port, and then act as a
  311. GDB remote stub until GDB disconnects.
  312. GDB's "monitor" command can be used to issue MSPDebug commands via the
  313. GDB interface. Supplied commands are executed non-interactively, and
  314. the output is sent back to be displayed in GDB.
  315. .IP "\fBhelp\fR [\fIcommand\fR]"
  316. Show a brief listing of available commands. If an argument is
  317. specified, show the syntax for the given command. The help text shown
  318. when no argument is given is also shown when MSPDebug starts up.
  319. .IP "\fBhexout\fR \fIaddress\fR \fIlength\fR \fIfilename\fR"
  320. Read the specified section of the device memory and save it to an
  321. Intel HEX file. The address and length arguments may both be address
  322. expressions.
  323. If the specified file already exists, then it will be overwritten. If
  324. you need to dump memory from several disjoint memory regions, you can
  325. do this by saving each section to a separate file. The resulting files
  326. can then be concatenated together to form a single valid HEX file.
  327. .IP "\fBisearch\fR \fIaddress\fR \fIlength\fR [\fIoptions\fR ...]"
  328. Search over the given range for an instruction which matches the specified
  329. search criteria. The search may be narrowed by specifying one or more of
  330. the following terms:
  331. .RS
  332. .IP "\fBopcode\fR \fIopcode\fR"
  333. Match the specified opcode. Byte/word specifiers are not recognised, as
  334. they are specified with other options.
  335. .IP "\fBbyte\fR"
  336. Match only byte operations.
  337. .IP "\fBword\fR"
  338. Match only word operations.
  339. .IP "\fBaword\fR"
  340. Match only address-word (20-bit) operations.
  341. .IP "\fBjump\fR"
  342. Match only jump instructions (conditional and unconditional jumps, but
  343. not instructions such as BR which load the program counter explicitly).
  344. .IP "\fBsingle\fR"
  345. Match only single-operand instructions.
  346. .IP "\fBdouble\fR"
  347. Match only double-operand instructions.
  348. .IP "\fBnoarg\fR"
  349. Match only instructions with no arguments.
  350. .IP "\fBsrc\fR \fIaddress\fR"
  351. Match instructions with the specified value in the source operand. The value
  352. may be given as an address expression. Specifying this option implies matching
  353. of only double-operand instructions.
  354. .IP "\fBdst\fR \fIaddress\fR"
  355. Match instructions with the specified value in the destination
  356. operand. This option implies that no-argument instructions are not
  357. matched.
  358. .IP "\fBsrcreg\fR \fIregister\fR"
  359. Match instructions using the specified register in the source operand. This
  360. option implies matching of only double-operand instructions.
  361. .IP "\fBdstreg\fR \fIregister\fR"
  362. Match instructions using the specified register in the destination operand.
  363. This option implies that no-argument instructions are not matched.
  364. .IP "\fBsrcmode\fR \fImode\fR"
  365. Match instructions using the specified mode in the source operand. See
  366. below for a list of modes recognised. This option implies matching of
  367. only double-operand instructions.
  368. .IP "\fBdstmode\fR \fImode\fR"
  369. Match instructions using the specified mode in the destination operand. See
  370. below for a list of modes. This option implies that no-argument instructions
  371. are not matched.
  372. .RE
  373. .IP
  374. For single-operand instructions, the operand is considered to be the
  375. destination operand.
  376. The seven addressing modes used by the MSP430 are represented by single
  377. characters, and are listed here:
  378. .RS
  379. .IP "\fBR\fR"
  380. Register mode.
  381. .IP "\fBI\fR"
  382. Indexed mode.
  383. .IP "\fBS\fR"
  384. Symbolic mode.
  385. .IP "\fB&\fR"
  386. Absolute mode.
  387. .IP "\fB@\fR"
  388. Register-indirect mode.
  389. .IP "\fB+\fR"
  390. Register-indirect mode with auto-increment.
  391. .IP "\fB#\fR"
  392. Immediate mode.
  393. .RE
  394. .IP "\fBload\fR \fIfilename\fR"
  395. Program the device under test using the binary file supplied. This
  396. command is like \fBprog\fR, but it does not load symbols or erase
  397. the device before programming.
  398. The CPU is reset and halted before and after programming.
  399. .IP "\fBload_raw\fR \fIfilename\fR \fIaddress\fR"
  400. Write the data contained in a raw binary file to the given memory address.
  401. The CPU is reset and halted before and after programming.
  402. .IP "\fBmd\fR \fIaddress\fR [\fIlength\fR]"
  403. Read the specified section of device memory and display it as a
  404. canonical\-style hexdump. Both arguments may be address expressions. If
  405. no length is specified, a section of the default length (64 bytes) is
  406. shown.
  407. The output is split into three columns. The first column shows the
  408. starting address for the line. The second column lists the hexadecimal
  409. values of the bytes. The final column shows the ASCII characters
  410. corresponding to printable bytes, and . for non-printing characters.
  411. This command supports repeat execution. If repeated, it continues to
  412. print another block of memory following that last printed.
  413. .IP "\fBmw\fR \fIaddress\fR \fIbytes\fR ..."
  414. Write a sequence of bytes at the given memory address. The address given
  415. may be an address expression. Bytes values are two-digit hexadecimal
  416. numbers separated by spaces.
  417. .IP "\fBopt\fR [\fIname\fR] [\fIvalue\fR]"
  418. Query, set or list option variables. MSPDebug's behaviour can be configured
  419. using option variables, described below in the section \fBOPTIONS\fR.
  420. Option variables may be of three types: boolean, numeric or text. Numeric
  421. values may be specified as address expressions.
  422. With no arguments, this command displays all available option variables.
  423. With just an option name as its argument, it displays the current value
  424. of that option.
  425. .IP "\fBpower info\fR"
  426. Show basic power statistics gathered over the last few sessions. This
  427. includes total charge consumption, run time and average current.
  428. .IP "\fBpower clear\fR"
  429. Clear all recorded power statistics.
  430. .IP "\fBpower all\fR [\fIgranularity\fR]"
  431. Show sample data gathered over all sessions. An optional granularity can
  432. be specified, in microseconds. For each time slice, relative session time,
  433. charge consumption, current consumption and approximate code location are
  434. shown.
  435. .IP "\fBpower session\fR \fIN\fR [\fIgranularity\fR]"
  436. Same as \fBpower all\fR, except that data is shown only for the \fIN\fRth
  437. session.
  438. .IP "\fBpower export-csv\fR \fIN\fR \fIfilename\fR"
  439. Export raw sample data for the \fIN\fRth session to the given file in CSV
  440. format. For each line, the columns are, in order: relative time in
  441. microseconds, current consumption in microamps, memory address.
  442. .IP "\fBpower profile\fR"
  443. If a symbol table is loaded, compile and correlate all gathered power data
  444. against the symbol table. A single table is then shown listing, per function,
  445. charge consumption, run time and average current. The functions are listed
  446. in order of charge consumption (biggest consumers first).
  447. .IP "\fBprog\fR \fIfilename\fR"
  448. Erase and reprogram the device under test using the binary file
  449. supplied. The file format will be auto-detected and may be any of
  450. the supported file formats.
  451. In the case of a file containing symbols, symbols will be automatically
  452. loaded from the file into the symbol table (discarding any existing
  453. symbols), if they are present.
  454. The CPU is reset and halted before and after programming.
  455. .IP "\fBread\fR \fIfilename\fR"
  456. Read commands from the given file, line by line and process each one.
  457. Any lines whose first non-space character is \fB#\fR are ignored. If
  458. an error occurs while processing a command, the rest of the file is not
  459. processed.
  460. .IP "\fBregs\fR"
  461. Show the current value of all CPU registers in the device under test.
  462. .IP "\fBreset\fR"
  463. Reset (and halt) the CPU of the device under test.
  464. .IP "\fBrun\fR"
  465. Start running the CPU. The interactive command prompt is blocked when
  466. the CPU is started and the prompt will not appear again until the CPU
  467. halts. The CPU will halt if it encounters a breakpoint, or if Ctrl\-C
  468. is pressed by the user.
  469. After the CPU halts, the current register values are shown as well as
  470. a disassembly of the first few instructions at the address selected
  471. by the program counter.
  472. .IP "\fBsave_raw\fR \fIaddress\fR \fIlength\fR \fIfilename\fR"
  473. Save a region of memory to a raw binary file. The address and length
  474. arguments may both be address expressions.
  475. If the specified file already exists, then it will be overwritten.
  476. .IP "\fBset\fR \fIregister\fR \fIvalue\fR"
  477. Alter the value of a register. Registers are specified as numbers from
  478. 0 through 15. Any leading non-numeric characters are ignored (so a
  479. register may be specified as, for example, "R12"). The value argument
  480. is an address expression.
  481. .IP "\fBsetbreak\fR \fIaddress\fR [\fIindex\fR]"
  482. Add a new breakpoint. The breakpoint location is an address expression. An
  483. optional index may be specified, indicating that this new breakpoint should
  484. overwrite an existing slot. If no index is specified, then the breakpoint
  485. will be stored in the next unused slot.
  486. .IP "\fBsetwatch\fR \fIaddress\fR [\fIindex\fR]"
  487. Add a new watchpoint. The watchpoint location is an address expression, and
  488. an optional index may be specified. Watchpoints are considered to be a type
  489. of breakpoint and can be inspected or removed using the \fBbreak\fR and
  490. \fBdelbreak\fR commands. Note that not all drivers support watchpoints.
  491. .IP "\fBsetwatch_r\fR \fIaddress\fR [\fIindex\fR]"
  492. Add a watchpoint which is triggered only on read access.
  493. .IP "\fBsetwatch_w\fR \fIaddress\fR [\fIindex\fR]"
  494. Add a watchpoint which is triggered only on write access.
  495. .IP "\fBsimio add\fR \fIclass\fR \fIname\fR [\fIargs ...\fR]"
  496. Add a new peripheral to the IO simulator. The \fIclass\fR parameter may be
  497. any of the peripheral types named in the output of the \fBsimio classes\fR
  498. command. The \fIname\fR parameter is a unique name assigned by the user to
  499. this peripheral instance, and is used with other commands to refer to this
  500. instance of the peripheral.
  501. Some peripheral classes take arguments upon creation. These are documented
  502. in the output to the \fBsimio help\fR command.
  503. .IP "\fBsimio classes\fR"
  504. List the names of the different types of peripherals which may be added to
  505. the simulator. You can use the \fBsimio help\fR command to obtain more
  506. information about each peripheral type.
  507. .IP "\fBsimio config\fR \fIname\fR \fIparam\fR [\fIargs ...\fR]"
  508. Configure or perform some action on a peripheral instance. The \fIparam\fR
  509. argument is specific to the peripheral type. A list of valid configuration
  510. commands can be obtained by using the \fBsimio help\fR command.
  511. .IP "\fBsimio del\fR \fIname\fR"
  512. Remove a previously added peripheral instance. The \fIname\fR argument
  513. should be the name of the peripheral that was assigned with the
  514. \fBsimio add\fR command.
  515. .IP "\fBsimio devices\fR"
  516. List all peripheral instances currently attached to the simulator, along
  517. with their types and interrupt status. You can obtain more detailed
  518. information for each instance with the \fBsimio info\fR command.
  519. .IP "\fBsimio help\fR \fIclass\fR"
  520. Obtain more information about a peripheral class. The documentation
  521. given will list constructor arguments and configuration parameters for
  522. the device type.
  523. .IP "\fBsimio info\fR \fIname\fR"
  524. Display detailed status information for a particular peripheral. The type
  525. of information displayed is specific to each type of peripheral.
  526. .IP "\fBstep\fR [\fIcount\fR]"
  527. Step the CPU through one or more instructions. After stepping, the new
  528. register values are displayed, as well as a disassembly of the
  529. instructions at the address selected by the program counter.
  530. An optional count can be specified to step multiple times. If no
  531. argument is given, the CPU steps once. This command supports repeat
  532. execution.
  533. .IP "\fBsym clear\fR"
  534. Clear the symbol table, deleting all symbols.
  535. .IP "\fBsym set\fR \fIname\fR \fIvalue\fR"
  536. Set or alter the value of a symbol. The value given may be an address
  537. expression.
  538. .IP "\fBsym del\fR \fIname\fR"
  539. Delete the given symbol from the symbol table.
  540. .IP "\fBsym import\fR \fIfilename\fR"
  541. Load symbols from the specified file and add them to the symbol table.
  542. The file format will be auto-detected and may be either ELF32 or a
  543. BSD-style symbol listing (like the output from \fBnm\fR(1)).
  544. Symbols can be combined from many sources, as the syms command adds
  545. to the existing symbol table without discarding existing symbols.
  546. .IP "\fBsym import+\fR \fIfilename\fR"
  547. This command is similar to \fBsym import\fR, except that the symbol table
  548. is not cleared first. By using this command, symbols from multiple
  549. sources can be combined.
  550. .IP "\fBsym export\fR \fIfilename\fR"
  551. Save all symbols currently defined to the given file. The symbols are
  552. saved as a BSD-style symbol table. Note that symbol types are not stored
  553. by MSPDebug, and all symbols are saved as type \fBt\fR.
  554. .IP "\fBsym find\fR [\fIregex\fR]"
  555. Search for symbols. If a regular expression is given, then all symbols
  556. matching the expression are printed. If no expression is specified, then
  557. the entire symbol table is listed.
  558. .IP "\fBsym rename\fR \fIregex\fR \fIstring\fR"
  559. Rename symbols by searching for those matching the given regular
  560. expression and substituting the given string for the matched portion. The
  561. symbols renamed are displayed, as well as a total count of all symbols
  562. renamed.
  563. .IP "\fBverify \fIfilename\fR"
  564. Compare the contents of the given binary file to the chip memory. If any
  565. differences are found, a message is printed for the first mismatched
  566. byte.
  567. .IP "\fBverify_raw \fIfilename\fR \fIaddress\fR"
  568. Compare the contents of a raw binary file to the device memory at the given
  569. address. If any differences are found, a message is printed for the first
  570. mismatched byte.
  572. The following binary/symbol formats are supported by MSPDebug:
  573. .RS
  574. ELF32
  575. .br
  576. COFF
  577. .br
  578. Intel HEX (program only)
  579. .br
  580. BSD symbol table (symbols only)
  581. .br
  582. TI Text (program only)
  583. .br
  584. SREC (program only)
  585. .RE
  587. The IO simulator subsystem consists of a database of device classes, and a
  588. list of instances of those classes. Each device class has a different
  589. set of constructor arguments, configuration parameters and information which
  590. may be displayed. This section describes the operation of the available
  591. device classes in detail.
  592. In the list below, each device class is listed, followed by its constructor
  593. arguments.
  594. .IP "\fBgpio\fR"
  595. Digital IO port simulator. This device simulates any of the digital ports
  596. with or without interrupt capability. It has the following configuration
  597. parameters:
  598. .RS
  599. .IP "\fBbase\fR \fIaddress\fR"
  600. Set the base address for this port. Note that for ports without interrupt
  601. capability, the resistor enable port has a special address which is
  602. computable from the base address.
  603. .IP "\fBirq\fR \fIvector\fR"
  604. Enable interrupt functionality for this port by specifying an interrupt
  605. vector number.
  606. .IP "\fBnoirq\fR"
  607. Disable interrupt functionality for this port.
  608. .IP "\fBverbose\fR"
  609. Print a state change message every time the port output changes.
  610. .IP "\fBquiet\fR"
  611. Don't print anything when the port state changes (the default).
  612. .IP "\fBset\fR \fIpin\fR \fIvalue\fR"
  613. Set the input pin state for the given pin on this port. The \fIpin\fR
  614. parameter should be an index between 0 and 7. The \fIvalue\fR should be
  615. either zero (for a low state) or non-zero (for a high state).
  616. .RE
  617. .IP "\fBhwmult\fR"
  618. This peripheral simulates the hardware multiplier. It has no constructor or
  619. configuration parameters, and does not provide any extended information.
  620. .IP "\fBtimer\fR [\fIsize\fR]"
  621. This peripheral simulators Timer_A modules, and can be used to simulate
  622. Timer_B modules, provided that the extended features aren't required.
  623. The constructor takes a size argument specifying the number of capture/compare
  624. registers in this peripheral instance. The number of such registers may not
  625. be less than 2, or greater than 7.
  626. The IO addresses and IRQs used are configurable. The default IO addresses used
  627. are those specified for Timer_A in the MSP430 hardware documentation.
  628. .RS
  629. .IP "\fBbase\fR \fIaddress\fR"
  630. Alter the base IO address. By default, this is 0x0160. By setting this to 0x0180,
  631. a Timer_B module may be simulated.
  632. .IP "\fBirq0\fR \fInumber\fR"
  633. Set the TACCR0 interrupt vector number. By default, this is interrupt vector 9.
  634. This interrupt is self-clearing, and higher priority than the TACCR1/TAIFG
  635. vector.
  636. .IP "\fBirq1\fR \fInumber\fR"
  637. Set the TACCR1/TAIFG interrupt vector. By default, this is interrupt vector 8.
  638. .IP "\fBiv\fR \fIaddress\fR"
  639. Alter the address of the interrupt vector register. By default, this is 0x012E.
  640. By setting this to 0x011E, a Timer_B module may be simulated.
  641. .IP "\fBset\fR \fIchannel\fR \fIvalue\fR"
  642. When Timer_A is used in capture mode, the CCI bit in each capture register reflects
  643. the state of the corresponding input pin, and can't be altered in software. This
  644. configuration command can be used to simulate changes in input pin state, and will
  645. trigger the corresponding interrupts if the peripheral is so configured.
  646. .RE
  647. .IP "\fBtracer\fR [\fIhistory-size\fR]"
  648. The tracer peripheral is a debugging device. It can be used to investigate
  649. and record the IO activity of a running program, to benchmark execution time,
  650. and to simulate interrupts.
  651. The information displayed by the tracer gives a running count of clock cycles
  652. from each of the system clocks, and an instruction count. A list of the \fIN\fR
  653. most recent IO events is also displayed (this is configurable via the \fIhistory-size\fR
  654. argument of the constructor). Each IO event is timestamped by the number of
  655. MCLK cycles that have elapsed since the last reset of the device's counter.
  656. The IO events that it records consist of programmed IO reads and writes,
  657. interrupt acceptance, and system resets. As well as keeping the IO events in a
  658. rotating buffer, the tracer can be configured to display the events as they
  659. occur.
  660. Note that since clock cycles don't advance while the CPU isn't running, this
  661. peripheral can be used to calculate execution times for blocks of code. This
  662. can be achieved by setting a breakpoint at the end of the code block, setting the
  663. program counter to the start of the code block, clearing the tracer and running
  664. the code. After the breakpoint is reached, the information displayed by the
  665. tracer will contain a count of MCLK cycles elapsed during the last run.
  666. The configuration parameters for this device class are:
  667. .RS
  668. .IP "\fBverbose\fR"
  669. Start displaying IO events as they occur, as well as recording them in the
  670. rotating buffer.
  671. .IP "\fBquiet\fR"
  672. Stop displaying IO events as they occur, and just record them in the buffer.
  673. .IP "\fBtrigger\fR \fIirq\fR"
  674. Signal an interrupt request to the CPU. This request will remain raised until
  675. accepted by the CPU or cleared by the user.
  676. .IP "\fBuntrigger\fR"
  677. Clear a signalled interrupt request.
  678. .IP "\fBclear\fR"
  679. Reset the clock cycle and instruction counts to 0, and clear the IO event
  680. history.
  681. .RE
  682. .IP "\fBwdt\fR"
  683. This peripheral simulates the Watchdog Timer+, which can be used in software
  684. either as a watchdog or as an interval timer. It has no constructor arguments.
  685. The simulated state of the NMI/RST# pin can be controlled through a configuration
  686. parameter. Note that if this pin state is held low with the pin mode selected
  687. as a reset (the default), the CPU will not run.
  688. The extended information for this peripheral shows all register states, including
  689. the hidden counter register. Configuration parameters are:
  690. .RS
  691. .IP "\fBnmi\fR \fIstate\fR"
  692. Set the NMI/RST# pin state. The argument should be zero to indicate a low state
  693. or non-zero for a high state.
  694. .IP "\fBirq\fR \fIirq\fR"
  695. Select the interrupt vector for interval timer mode. The default is to use
  696. interrupt vector 10.
  698. Any command which accepts a memory address, length or register value
  699. as an argument may be given an address expression. An address
  700. expression consists of an algebraic combination of values.
  701. An address value can be one of the following:
  702. .RS
  703. A symbol name
  704. .br
  705. A CPU register name preceded with "@"
  706. .br
  707. A hex value preceded with the specifier "0x"
  708. .br
  709. A decimal value preceded with the specifier "0d"
  710. .br
  711. A number in the default input radix (without a specifier). See the option
  712. \fBiradix\fR for more information.
  713. .RE
  714. The operators recognised are the usual algebraic operators: \fB+\fR, \fB-\fR,
  715. \fB*\fR, \fB/\fR, \fB%\fR, \fB(\fR and \fB)\fR. Operator precedence is the
  716. same as in C-like languages, and the \fB-\fR operator may be used as a
  717. unary negation operator.
  718. The following are all valid examples of address expressions:
  719. .B 2+2
  720. .br
  721. .B table_start + (elem_size + elem_pad)*4
  722. .br
  723. .B main+0x3f
  724. .br
  725. .B __bss_end-__bss_start
  726. .br
  727. .B @sp
  728. .SH OPTIONS
  729. MSPDebug's behaviour can be configured via the following variables:
  730. .IP "\fBcolor\fR (boolean)"
  731. If true, MSPDebug will colorize debugging output.
  732. .IP "\fBfet_block_size\fR (numeric)"
  733. Change the size of the buffer used to transfer memory to and from the
  734. FET. Increasing the value from the default of 64 will improve transfer
  735. speed, but may cause problems with some chips.
  736. .IP "\fBenable_bsl_access\fR (boolean)"
  737. If set, some drivers will allow erase/program access to flash
  738. BSL memory. If in doubt, do not enable this.
  739. .IP "\fBenable_locked_flash_access\fR (boolean)"
  740. If set, some drivers will allow erase/program access to the info A
  741. segment. If in doubt, do not enable this. Currently, the tilib and uif
  742. drivers are affected by this option.
  743. .IP "\fBenable_fuse_blow\fR"
  744. If set, some drivers will allow the JTAG security fuse to be blown.
  745. .B WARNING: this is an irreversible operation!
  746. If in doubt, do not enable this option.
  747. .IP "\fBgdb_default_port\fR (numeric)"
  748. This option controls the default TCP port for the GDB server, if no
  749. argument is given to the "\fBgdb\fR" command.
  750. .IP "\fBgdb_loop\fR (boolean)"
  751. Automatically restart the GDB server after disconnection. If this
  752. option is set, then the GDB server keeps running until an error occurs,
  753. or the user interrupts with Ctrl+C.
  754. .IP "\fBgdbc_xfer_size\fR (numeric)"
  755. Maximum size of memory transfers for the GDB client. Increasing this
  756. value will result in faster transfers, but may cause problems with some
  757. servers.
  758. .IP "\fBiradix\fR (numeric)"
  759. Default input radix for address expressions. For address values with
  760. no radix specifier, this value gives the input radix, which is
  761. 10 (decimal) by default.
  762. .IP "\fBquiet\fR (boolean)"
  763. If set, MSPDebug will suppress most of its debug-related output. This option
  764. defaults to false, but can be set true on start-up using the \fB-q\fR
  765. command-line option.
  767. .IP "\fBMSPDEBUG_TI3410_FW\fI"
  768. Specifies the location of TI3410 firmware, for raw USB access to FET430UIF
  769. or eZ430 devices. This variable should contain the path to an Intel HEX
  770. file containing suitable firmware for the TI3410.
  772. Specifies the directory to find the Texas Instruments MSP430.DLL library.
  773. .SH FILES
  774. .IP "~/.mspdebug"
  775. File containing commands to be executed on startup.
  776. .IP "ti_3410.fw.ihex"
  777. Firmware image for the TI3410 USB interface chip. This file is only
  778. required for raw USB access to FET430UIF or eZ430 devices.
  779. .SH SEE ALSO
  780. \fBnm\fR(1), \fBgdb\fR(1), \fBobjcopy\fR(1)
  781. \fBmehfet\fR protocol documentation can be found at the following URL:
  783. .SH BUGS
  784. If you find any bugs, you should report them to the author at
  785. It would help if you could include a transcript
  786. of an MSPDebug session illustrating the program, as well as any
  787. relevant binaries or other files.
  789. Copyright (C) 2009-2013 Daniel Beer <>
  790. MSPDebug is free software, distributed under the terms of the GNU
  791. General Public license (version 2 or later). See the file COPYING
  792. included with the source code for more details.