mspdebug(1)

📦
version 0.25 · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💅 MSPDebug — the manual, but make it cute 💅

okay bestie, welcome to the mspdebug(1) page, straight out of General Commands Manual. this is part one of five so buckle up, we are NOT done, but we ARE about to understand this tool fr fr 🦋

✨ NAME ✨

MSPDebug — a debugging tool for MSP430 MCUs 🎀

✨ SYNOPSIS ✨

mspdebug [options] driver [command ...]

✨ DESCRIPTION ✨

So like, MSPDebug is this command-line tool and its whole thing is debugging and programming the MSP430 family of MCUs. She's versatile. She supports the eZ430-F2013, eZ430-RF2500, Launchpad, Chronos, FET430UIF, GoodFET, Olimex MSP430-JTAG-TINY and MSP430-JTAG-ISO programming tools — plus a simulation mode. Iconic lineup honestly 👑

When you start her up with the right options, MSPDebug will try to connect to the debugging tool you specified and identify the device under test. Once she's connected, you get a command prompt. From there you can reflash the device memory, inspect memory and registers, set registers, and control the CPU (single step, run, and run to breakpoint). Full main character energy, she does it all 💅

She supports a variety of file formats — those are described down in the BINARY FORMATS section. She can also be used as a remote stub for gdb(1). slay.

On startup, MSPDebug will look for a file called .mspdebug — first in the current directory, and then in the user's home directory. If either file exists, commands will be read and executed from it before any other commands run or before the interactive reader starts. Lowkey important, don't skip this.

Alternatively, you can explicitly specify a configuration file with the -C option. no cap.

✨ COMMAND-LINE OPTIONS ✨

These are the command-line options MSPDebug accepts. Here's the tea:

If commands are specified at the end of the command-line, they get executed after connecting to the device, and the interactive prompt is not started. 🫶

⚠️ heads up bestie: commands that consist of multiple words need to be enclosed in quotation marks, otherwise they get treated as single commands. So the common prog command would be used as "prog main.elf". See the section labelled COMMANDS for more info.
  • -q — Start in quiet mode. See the "quiet" option described below. 🤫
  • -v voltage — Set the programming voltage. The voltage should be specified as an integer in millivolts. It defaults to 3000 (that's 3.0 V). ⚡
  • -j — Use JTAG instead of Spy-Bi-Wire to communicate with the MSP430.
🚨 okay so listen: this option doesn't work with eZ430 or eZ430-RF2500 devices, because those support Spy-Bi-Wire only. periodt.
  • -d device — Specify that the driver should connect via a tty device rather than USB. The supported connection methods vary depending on the driver. See the DRIVERS section below for details.
  • -U bus:device — Specify a particular USB device to connect to. Without this option, the first device of the appropriate type is opened. 🎯
  • -s serial — Specify a particular USB device serial number to connect to. Use this option to distinguish between multiple devices of the same type. (you know, when you've got like five of them plugged in and you're like, which one 😭)
  • -n — Do not process the startup file (~/.mspdebug).
  • -C file — Specify an alternative configuration file (default is ~/.mspdebug). If -n is specified as well, no file will be read.
  • --long-password — When using the flash-bsl driver, send a 32-byte BSL password instead of the standard 16-byte password. 🔐
  • --help — Display a brief help message and exit.
  • --fet-list — Display a list of chips supported by the FET driver (the driver used for UIF, RF2500 and Olimex devices).
  • --fet-force-id string — When using a FET device, force the connected chip to be recognised by MSPDebug as one of the given type during initialization. This overrides the device ID returned by the FET. The given string should be a chip name in long form, for example "MSP430F2274".
  • --fet-skip-close — When using a FET device, skip the JTAG close procedure when disconnecting. With some boards, this removes the need to replug the debugger after use. (obsessed, honestly 🙈)
  • --usb-list — List available USB devices and exit.
  • --force-reset — When using a FET device, always send a reset during initialization. By default, an initialization without reset will be tried first.
  • --allow-fw-update — When using a V3 FET device via the TI library, allow the library to perform a firmware update if the FET firmware is incompatible with the library.
  • --require-fw-update image.txt — When using a V3 FET device, or certain Olimex devices, force a firmware update using the given firmware image. The firmware format depends on the driver.
  • --version — Show program version and copyright information.
  • --embedded — Start mspdebug as an embedded subprocess. See the documentation accompanying the source release for more information on embedded mode.
  • --bsl-entry-sequence seq — Specify a BSL entry sequence. Each character specifies a modem control line transition (R: RTS on, r: RTS off, D: DTR on, d: DTR off). A comma indicates a delay. The entry and exit sequences are separated by a colon. The default value is dR,r,R,r,R,D:dR,DR, for the flash-bsl driver. 🌸

and that's part one bestie!! there is SO much more coming, don't you dare go anywhere 💖

🚗 DRIVERS 🚗

Okay bestie, so drivers. For drivers that support both USB and tty access, USB is the default, unless you say otherwise (peep -d above, iykyk).

On Linux, if USB access is used, the kernel driver (if any) is detached from the tty device. If you need to get back to the tty device after that, you have to unload and re-load the driver (like cdc-acm.ko, for example). No cap.

A driver name must be specified on the command line for MSPDebug to connect to. Valid driver names are listed here. Periodt.

  • rf2500 — Connect to an eZ430-RF2500, Launchpad or Chronos device. Only USB connection is supported. ✨
  • olimex — Connect to an Olimex MSP430-JTAG-TINY device. Both USB and tty access are supported. 💅
  • olimex-v1 — Connect to an Olimex MSP430-JTAG-TINY (V1) device. Both USB and tty access are supported. This driver must be used instead of olimex if connecting to a V1 device via a tty interface. 🎀
  • olimex-iso — Connect to an Olimex MSP430-JTAG-ISO device. Both USB and tty access are supported.
  • olimex-iso-mk2 — Connect to an Olimex MSP430-JTAG-ISO-MK2 device. Both USB and tty access are supported.
  • sim — Do not connect to any hardware device, but instead start in simulation mode. A 64k buffer is allocated to simulate the device memory.

During simulation, addresses below 0x0200 are assumed to be IO memory. Programmed IO writes to and from IO memory are handled by the IO simulator, which can be configured and controlled with the simio command, described below.

This mode is intended for testing of changes to MSPDebug, and for aiding the disassembly of MSP430 binaries (as all binary and symbol table formats are still usable in this mode). 🧚

  • uif — Connect to an eZ430-F2013 or a FET430UIF device. The device argument should be the filename of the appropriate tty device. The TI serial converter chips on these devices are supported by newer versions of the Linux kernel, and should appear as /dev/ttyXX when attached.

USB connection is supported for this driver. The USB interface chip in these devices is a TI3410, which requires a firmware download on startup. MSPDebug will search for a file called ti_3410.fw.ihex in the configured library directory and the current directory. You can specify an alternate location for the file via the MSPDEBUG_TI3410_FW environment variable. 💖

  • uif-bsl — Connect to the bootloader on a FET430UIF device. These devices contain MSP430F1612 chips. By sending a special command sequence, you can obtain access to the bootloader and inspect memory on the MSP430F1612 in the programming device itself.

Currently, only memory read/write and erase are supported. CPU control via the bootloader is not possible. 😭

  • flash-bsl — Connect to the built-in bootloader in MSP430 devices with flash bootloader memory. Devices with ROM bootloaders require another driver. Currently, this driver must mass-erase the device in order to gain access. Read, write, and erase operations are supported.

USB connection is not supported for this driver. Connection is via serial port, and bootloader entry is accomplished via the RTS and DTR lines. Connect RTS to the device's TEST pin and DTR to the device's RST pin. Use an appropriate serial level-shifter to make the connection, if necessary. If connecting to a device with non-multiplexed JTAG pins, connect RTS to the device's TCK pin via an inverter. 🔌

  • gdbc — GDB client mode. Connect to a server which implements the GDB remote protocol and provide an interface to it. To use this driver, specify the remote address in hostname:port format using the -d option. 🖥️
  • tilib — Use the Texas Instruments MSP430.DLL to access the device. The library file (MSP430.DLL for Windows, libmsp430.so for Unix-like systems) must be present in the dynamic loader search path.

USB connection is not supported for this driver. This driver supports watchpoints. Note that the -d option for this driver passes its argument straight through to the library's MSP430_Initialize function. Any special argument supported by that function is therefore accessible via the -d option.

Automatic device discovery works only on Linux and Windows. On other systems, the appropriate ACM serial node must be explicitly specified. 👑

  • goodfet — Connect to a GoodFET device. JTAG mode must be used, and only tty access is supported. This device can be used for memory access (read, erase and program), but CPU control is limited. The CPU may be halted, run and reset, but register access and breakpoints aren't supported. 💀
  • pif — Connect to a parallel-port JTAG controller. JTAG mode must be used, and only tty access is supported. Currently, this driver is only supported on Linux, FreeBSD and DragonFly BSD. A parallel port device (ppdev on Linux, ppi on FreeBSD and DragonFly BSD) must be specified via the -d option. 🖨️
  • gpio — Connect to system gpios. JTAG mode must be used, and only tty access is supported. Currently, this driver is only supported on Linux, FreeBSD and DragonFly BSD. The gpios to used must defined using a string like "tdi=7 tdo=8 tms=9 tck=4 rst=10 tst=11" via the -d option. (dont forget the quotes) 🌈
  • load-bsl — Connect to a USB bootloader. The stub bootloader will be used to load a fuller-featured bootloader into RAM for execution. 🚀
  • ezfet — This driver is for Texas Instruments' eZ-FET devices. It supports USB and tty access. It does not support breakpoint control. ✨
  • rom-bsl — This driver is for the old-style (ROM) bootstrap loader. It supports tty access only. Entry is attempted via the RTS/DTR signals. The default sequence is DR,r,R,r,d,R:DR,r, but you can override this with the --bsl-entry-sequence option.
WARNING: this driver unlocks the BSL by performing a mass erase. There are reports of this operation causing an erase of info A in some devices. Use at your own risk. ⚠️
  • bus-pirate — Raw JTAG using Bus Pirate devices. 🏴‍☠️

💬 COMMANDS 💬

MSPDebug can accept commands either through an interactive prompt, or non-interactively when specified on the command line. The supported commands are listed below. 🫶

Commands take arguments separated by spaces. Any text string enclosed in double-quotation marks is considered to be a single argument, even if it contains space characters. Within a quoted string, the usual C-style backslash substitutions can be used. 💅

Commands can be specified by giving the first few characters of the command name, provided that the prefix is unambiguous. Some commands support automatic repeat. For these commands, pressing enter at the reader prompt without typing anything will cause repeat execution. 🔁

  • ! [command [args ...]] — Invoke an interactive operating system shell. If any arguments are specified, the first one is taken as a command to execute, with the rest of the arguments as the arguments to the command.

This command is not yet available on non-POSIX systems. 🐚

  • = expression — Evaluate an address expression and show both its value, and the result when the value is looked up in reverse in the current symbol table. This result is of the form symbol+offset, where symbol is the name of the nearest symbol not past the address in question.

See the section marked ADDRESS EXPRESSIONS for more information on the syntax of expressions. 🔍

  • alias — Show a list of defined command aliases.
  • alias name — Remove a previously defined command alias.
  • alias name command — Define a command alias. The text command will be substituted for name when looking up commands. The given command text may contain a command plus arguments, if the entire text is wrapped in quotes when defining the alias. To avoid alias substitution when interpreting commands, prefix the command with \ (a backslash character). 🪄
  • blow_jtag_fuse — Blow the device's JTAG fuse.
WARNING: this is an irreversible operation! 💥
  • break — Show a list of active breakpoints. Breakpoints can be added and removed with the setbreak and delbreak commands. Each breakpoint is numbered with an integer index starting at 0. 🛑
  • cgraph address length [address] — Construct the call graph of all functions contained or referenced in the given range of memory. If a particular function is specified, then details for that node of the graph are displayed. Otherwise, a summary of all nodes is displayed.

Information from the symbol table is used for hinting at the possible locations of function starts. Any symbol which does not contain a . is considered a possible function start.

Callers and callee names are shown prefixed by a * where the transition is a tail-call type transition. 📊

  • delbreak [index] — Delete one or all breakpoints. If an index is given, the selected breakpoint is deleted. Otherwise, all breakpoints are cleared. 🗑️
  • dis address [length] — Dissassemble a section of memory. Both arguments may be address expressions. If no length is specified, a section of the default length (64 bytes) is disassembled and shown.

If symbols are available, then all addresses used as operands are translated into symbol+offset form.

This command supports repeat execution. If repeated, it continues to disassemble another block of memory following that last printed. 🔎

  • erase [all|segment|segrange] [address] [size] [segrange] — Erase the device under test. With no arguments, all code memory is erased (but not information or boot memory). With the argument "all", a mass erase is performed (the results may depend on the state of the LOCKA bit in the flash memory controller).

Specify "segment" and a memory address to erase an individual flash segment. Specify "segrange", an address, size and segment size to erase an arbitrary set of contiguous segments. 🧽

  • exit — Exit from MSPDebug. 👋
  • fill address length b0 [b1 b2 ...] — Fill the memory region of size length starting at address with the pattern of bytes given (specified in hexadecimal). The pattern will be repeated without padding as many times as necessary without exceeding the bounds of the specified region. 🎨

🌸 gdb [port]

okay so this one starts up a GDB remote stub, and you can optionally tell it which TCP port to listen on. no port? then the default port is whatever the gdb_default_port option is set to, periodt. MSPDebug will just sit there waiting for a connection on that port like 🫶, and then it acts as a GDB remote stub until GDB disconnects.

and here's the cute part: GDB's "monitor" command lets you throw MSPDebug commands at it straight through the GDB interface. those supplied commands run non-interactively, and their output gets sent right back to be displayed in GDB. slay.

✨ help [command]

shows you a lil' listing of all the available commands. give it an argument and it'll show you the syntax for that specific command instead. also — the help text you get when you pass no argument? that's the exact same text MSPDebug shows you when it starts up. so if you were ever like "wait what did it say at launch" — it's this. 💖

🎀 hexout address length filename

reads the section of device memory you point at and saves it out as an Intel HEX file. both address and length can be address expressions, ngl that's handy.

if the file already exists, it gets overwritten — no warning, just gone 💀. and if you need to dump memory from several disjoint memory regions? do it one section at a time, each into its own separate file. then you can concatenate the resulting files together to make one single valid HEX file. iconic workaround.

🦋 isearch address length [options ...]

searches over the given range for an instruction that matches your search criteria. you narrow it down with one or more of these terms:

  • opcode opcode — match the specified opcode. byte/word specifiers are not recognised here, because those get specified with other options instead.
  • byte — match only byte operations.
  • word — match only word operations.
  • aword — match only address-word (20-bit) operations.
  • jump — match only jump instructions (conditional and unconditional jumps, but not instructions like BR which load the program counter explicitly).
  • single — match only single-operand instructions.
  • double — match only double-operand instructions.
  • noarg — match only instructions with no arguments.
  • src address — match instructions with the specified value in the source operand. the value may be given as an address expression. specifying this implies matching of only double-operand instructions.
  • dst address — match instructions with the specified value in the destination operand. this option implies that no-argument instructions are not matched.
  • srcreg register — match instructions using the specified register in the source operand. implies matching of only double-operand instructions.
  • dstreg register — match instructions using the specified register in the destination operand. implies that no-argument instructions are not matched.
  • srcmode mode — match instructions using the specified mode in the source operand (list of modes is right below). implies matching of only double-operand instructions.
  • dstmode mode — match instructions using the specified mode in the destination operand (modes below). implies that no-argument instructions are not matched.

for single-operand instructions, the operand counts as the destination operand. iykyk.

the seven addressing modes the MSP430 uses are each represented by a single character, and here they all are:

  • R — register mode.
  • I — indexed mode.
  • S — symbolic mode.
  • & — absolute mode.
  • @ — register-indirect mode.
  • + — register-indirect mode with auto-increment.
  • # — immediate mode.

💜 load filename

programs the device under test with the binary file you hand it. this is like prog, except it does not load symbols or erase the device before programming. different vibe, same energy.

the CPU is reset and halted before and after programming. every time. 🫶

🌈 load_raw filename address

writes the data sitting inside a raw binary file to the given memory address. no fancy formats, just raw bytes.

the CPU is reset and halted before and after programming. again. it's a whole thing.

⭐ md address [length]

reads the section of device memory you point at and shows it as a canonical-style hexdump. both arguments can be address expressions. skip the length and you get the default length — that's 64 bytes — of section shown. cute.

the output is split into three columns:

  1. the starting address for the line.
  2. the hexadecimal values of the bytes.
  3. the ASCII characters corresponding to printable bytes, and . for non-printing characters.

and bestie, this command supports repeat execution 🔥 — repeat it and it just keeps printing the next block of memory following the last one it printed. chef's kiss.

🍓 mw address bytes ...

writes a sequence of bytes at the given memory address. the address you give can be an address expression. the byte values are two-digit hexadecimal numbers separated by spaces. that's it, that's the command.

🧚 opt [name] [value]

queries, sets or lists option variables. MSPDebug's whole behaviour can be configured through option variables, and they're described below in the section OPTIONS.

option variables come in three types: boolean, numeric or text. numeric values may be specified as address expressions, which is lowkey delightful.

  • no arguments at all? it displays all the available option variables.
  • just an option name as the argument? it displays the current value of that option.

👑 power info

shows basic power statistics gathered over the last few sessions. that includes total charge consumption, run time and average current. the receipts, basically. ✨

💅 power clear

clears all recorded power statistics. poof, gone, fresh start.

🌸 power all [granularity]

shows sample data gathered over all sessions. you can optionally pass a granularity, in microseconds. for each time slice you get: relative session time, charge consumption, current consumption and the approximate code location.

🦋 power session N [granularity]

exactly the same as power all, except the data shown is only for the Nth session. one session, one moment, main character energy.

🎀 power export-csv N filename

exports the raw sample data for the Nth session to the given file, in CSV format. for each line, the columns are, in order:

  1. relative time in microseconds
  2. current consumption in microamps
  3. memory address

💖 power profile

if a symbol table is loaded, this compiles and correlates all the gathered power data against that symbol table. then you get a single table showing, per function, charge consumption, run time and average current.

the functions are listed in order of charge consumption — biggest consumers first. yes, we're ranking them. somebody's getting exposed 🙈.

🔥 prog filename

erases and reprograms the device under test using the binary file you supply. the file format gets auto-detected and may be any of the supported file formats.

if the file contains symbols, those symbols get automatically loaded from the file into the symbol table — and heads up, that discards any existing symbols 💀 — but only if they're actually present in the file.

the CPU is reset and halted before and after programming. you know the drill by now.

🫶 read filename

reads commands from the given file, line by line, and processes each one. any lines whose first non-space character is # are ignored (comments, we love her). and if an error happens while processing a command, the rest of the file is not processed. it just stops. no cap.

🌈 regs

shows the current value of all CPU registers in the device under test. the whole roster, on display.

⭐ reset

resets (and halts) the CPU of the device under test. little nap. 😴

💜 run

starts running the CPU. while the CPU is going, the interactive command prompt is blocked — you won't see the prompt again until the CPU halts. it halts if it hits a breakpoint, or if you hit Ctrl-C yourself.

after the CPU halts, you get the current register values shown, plus a disassembly of the first few instructions at the address selected by the program counter. so you know exactly where you ended up. 👑

🧚 save_raw address length filename

saves a region of memory out to a raw binary file. both address and length can be address expressions.

if the specified file already exists, it will be overwritten. bye bestie.

🍓 set register value

alters the value of a register. registers are specified as numbers from 0 through 15. any leading non-numeric characters are ignored — so yeah, you can write a register as, for example, "R12". the value argument is an address expression.

🎀 setbreak address [index]

adds a new breakpoint. the breakpoint location is an address expression. you can optionally pass an index, which means this new breakpoint should overwrite an existing slot. no index? then the breakpoint gets stored in the next unused slot. tidy. ✨

💅 setwatch address [index]

adds a new watchpoint. the watchpoint location is an address expression, and an optional index may be specified too. watchpoints count as a type of breakpoint, so you can inspect or remove them with the break and delbreak commands.

heads up though: not all drivers support watchpoints. so if it's not working, that might be why 😭

🌸 setwatch_r address [index]

adds a watchpoint that only triggers on read access.

🦋 setwatch_w address [index]

adds a watchpoint that only triggers on write access.

🔥 simio add class name [args ...]

adds a new peripheral to the IO simulator. the class parameter can be any of the peripheral types named in the output of the simio classes command. the name parameter is a unique name that you assign to this peripheral instance, and it's how other commands refer to this particular instance of the peripheral.

some peripheral classes take arguments when you create them. those are documented in the output of the simio help command.

💖 simio classes

lists the names of the different types of peripherals you can add to the simulator. use the simio help command if you want more info about each peripheral type. go explore, bestie 🧚

  • simio config name param [args ...] — pokes at a peripheral you already made. It configures the instance or makes it do a lil action. The param you pass is specific to whatever peripheral type you're messing with — every class does its own thing. Wanna know which params exist? Run simio help, it'll spill the whole list bestie 🫶
  • simio del name — yeet a peripheral instance you added earlier. The name has to be the exact name you gave it back when you ran simio add.
  • simio devices — lists every peripheral instance currently attached to the simulator, plus each one's type and interrupt status. Want the tea, not just the headline? Hit simio info for the details on each instance 🔍
  • simio help class — gives you more info about a peripheral class. The docs it hands you list the constructor arguments and the configuration parameters for that device type. Super handy, no cap.
  • simio info name — detailed status for one specific peripheral. Heads up though: what gets displayed is different for every peripheral type, so don't expect a universal layout 💅
  • step [count] — walks the CPU through one or more instructions. After each step it shows you the new register values plus a disassembly of the instructions sitting at whatever address the program counter is pointing at. Iconic.

You can hand it an optional count to step multiple times. No argument? CPU steps once. This command supports repeat execution ✨

  • sym clear — nukes the symbol table. Every symbol, gone, bye 👋
  • sym set name value — sets or changes a symbol's value. That value can be an address expression, so go wild.
  • sym del name — deletes just that one symbol from the table. Surgical, we love that.
  • sym import filename — loads symbols from the given file and adds them into the symbol table. The format gets auto-detected, and it can be either ELF32 or a BSD-style symbol listing (the kind of thing nm(1) spits out).

Fun fact: symbols can be combined from many sources, since the syms command adds to the existing symbol table without discarding what's already there 🎀

  • sym import+ filename — basically sym import's twin, except the symbol table is not cleared first. This is the move when you wanna stack symbols from multiple sources together.
  • sym export filename — saves all currently defined symbols to the file you name. They go out as a BSD-style symbol table. Important though: MSPDebug does not store symbol types, so literally every symbol gets saved as type t. Periodt.
  • sym find [regex] — searches for symbols. Give it a regular expression and it prints everything matching. Give it nothing and it dumps the entire symbol table. Either way you're fed 🍓
  • sym rename regex string — renames symbols by finding everything that matches the regex and substituting your string in for the matched portion. It shows you the symbols it renamed, plus a total count of how many got renamed. Very satisfying ngl.
  • verify filename — compares the contents of the given binary file against chip memory. If there's any mismatch, it prints a message for the first mismatched byte. 💀
  • verify_raw filename address — same energy, but compares a raw binary file against device memory starting at the given address. Differences get flagged with a message for the first mismatched byte.

🦋 BINARY FORMATS 🦋

MSPDebug speaks these formats, and here's the full roster — no gatekeeping:

  • ELF32
  • COFF
  • Intel HEX (program only)
  • BSD symbol table (symbols only)
  • TI Text (program only)
  • SREC (program only)
Not me pointing out that the "(program only)" and "(symbols only)" tags are doing <em>so</em> much work here — respect the tags, bestie.

🎀 IO SIMULATOR 🎀

Okay so the IO simulator subsystem is made of two things: a database of device classes, and a list of instances of those classes. Every device class comes with its own different set of constructor arguments, configuration parameters and information it can show you. This section breaks down how each available device class actually operates, in detail. 👑

Down in the list below, each device class shows up first, followed by its constructor arguments.

gpio

Digital IO port simulator. This one simulates any of the digital ports, with or without interrupt capability. Configuration parameters:

  • base address — sets the base address for this port. Careful though: for ports without interrupt capability, the resistor enable port has a special address that's computable from the base address.
  • irq vector — turns on interrupt functionality for this port by giving it an interrupt vector number.
  • noirq — turns interrupt functionality off.
  • verbose — prints a state change message <em>every single time</em> the port output changes. Chatty king 👑
  • quiet — prints nothing when the port state changes. This is the default.
  • set pin value — sets the input pin state for the given pin on this port. pin should be an index between 0 and 7. value should be either zero (low state) or non-zero (high state).

hwmult

This peripheral simulates the hardware multiplier. It has no constructor or configuration parameters, and it doesn't hand out any extended information. Low maintenance. Minimalist. Honestly? Respect ✨

timer [size]

This peripheral simulates Timer_A modules, and it can also stand in for Timer_B modules — <em>provided</em> you don't need the extended features.

The constructor takes a size argument that says how many capture/compare registers this peripheral instance has. That number may not be less than 2, and may not be greater than 7. Them's the rules.

The IO addresses and IRQs are configurable. The default IO addresses are the ones specified for Timer_A in the MSP430 hardware documentation.

  • base address — changes the base IO address. Default is 0x0160. Set it to 0x0180 and boom, you can simulate a Timer_B module.
  • irq0 number — sets the TACCR0 interrupt vector number. Default is interrupt vector 9. Heads up: this interrupt is self-clearing, and it has higher priority than the TACCR1/TAIFG vector.
  • irq1 number — sets the TACCR1/TAIFG interrupt vector. Default is interrupt vector 8.
  • iv address — changes the address of the interrupt vector register. Default is 0x012E. Set it to 0x011E and a Timer_B module can be simulated.
  • set channel value — when Timer_A is in capture mode, the CCI bit in each capture register reflects the state of the corresponding input pin, and it can't be altered in software. This configuration command lets you simulate changes in input pin state, and it will trigger the corresponding interrupts if the peripheral is configured for that. 🎯

tracer [history-size]

The tracer peripheral is a debugging device. Use it to investigate and record the IO activity of a running program, to benchmark execution time, and to simulate interrupts. It's giving detective 🔍

The info the tracer shows you includes a running count of clock cycles from each of the system clocks, plus an instruction count. It also shows a list of the N most recent IO events — and that N is configurable through the history-size argument of the constructor. Every IO event gets timestamped by the number of MCLK cycles that have elapsed since the last reset of the device's counter.

The IO events it records are: programmed IO reads and writes, interrupt acceptance, and system resets. On top of keeping those events in a <em>rotating buffer</em>, the tracer can be configured to display events as they happen.

Note: since clock cycles don't advance while the CPU isn't running, this peripheral is lowkey perfect for calculating execution times of code blocks. The whole ritual: set a breakpoint at the end of the code block, set the program counter to the start of the code block, clear the tracer, then run the code. Once the breakpoint hits, the info the tracer displays will contain a count of MCLK cycles elapsed during the last run. Obsessed.

Configuration parameters for this device class:

  • verbose — starts displaying IO events as they occur, <em>as well as</em> recording them in the rotating buffer.
  • quiet — stops displaying IO events as they occur and just records them in the buffer.
  • trigger irq — signals an interrupt request to the CPU. This request stays raised until accepted by the CPU or cleared by the user.
  • untrigger — clears a signalled interrupt request.
  • clear — resets the clock cycle and instruction counts to 0, and clears the IO event history.

wdt

This peripheral simulates the Watchdog Timer+, which can be used in software either as a watchdog or as an interval timer. It has no constructor arguments.

The simulated state of the NMI/RST# pin can be controlled through a configuration parameter. Big warning though: if this pin state is held low with the pin mode selected as a reset (the default), the CPU will not run. So maybe don't do that accidentally 😭

The extended information for this peripheral shows all register states, including the hidden counter register. Configuration parameters are:

  • nmi state — sets the NMI/RST# pin state. The argument should be zero for a low state, or non-zero for a high state.
  • irq irq — selects the interrupt vector for interval timer mode. The default is to use interrupt vector 10.

✨ ADDRESS EXPRESSIONS ✨

Okay bestie, so any command that takes a memory address, a length, or a register value as an argument? It can also take an address expression. And an address expression is literally just an algebraic combo of values. Math class but make it firmware. 💅

An address value can be one of these lil guys:

  • A symbol name
  • A CPU register name preceded with @
  • A hex value preceded with the specifier 0x
  • A decimal value preceded with the specifier 0d
  • A number in the default input radix (no specifier needed). See the option iradix for more info.

The operators it recognises are the usual algebraic suspects: +, -, *, /, %, ( and ). Operator precedence is the same as in C-like languages, and the - operator can be used as a unary negation operator. Not me loving a unary minus. 😭

The following are all valid examples of address expressions:

2+2
table_start + (elem_size + elem_pad)*4
main+0x3f
__bss_end-__bss_start
@sp

💅 OPTIONS 💅

MSPDebug's behaviour can be configured via the following variables:

  • color (boolean) — If true, MSPDebug will colorize debugging output. rainbow terminal era 🌈
  • fet_block_size (numeric) — Change the size of the buffer used to transfer memory to and from the FET. Increasing the value from the default of 64 will improve transfer speed, but may cause problems with some chips. speed vs chaos ✨
  • enable_bsl_access (boolean) — If set, some drivers will allow erase/program access to flash BSL memory. If in doubt, do not enable this. fr fr, be careful 🚨
  • enable_locked_flash_access (boolean) — If set, some drivers will allow erase/program access to the info A segment. If in doubt, do not enable this. Currently, the tilib and uif drivers are affected by this option. locked flash? not today 🔐
  • enable_fuse_blow — If set, some drivers will allow the JTAG security fuse to be blown.
WARNING: this is an irreversible operation!

If in doubt, do not enable this option. IRREVERSIBLE. like, no take-backs. 💀

  • gdb_default_port (numeric) — This option controls the default TCP port for the GDB server, if no argument is given to the gdb command. port vibes 🎀
  • gdb_loop (boolean) — Automatically restart the GDB server after disconnection. If this option is set, then the GDB server keeps running until an error occurs, or the user interrupts with Ctrl+C. loop it and leave it 🔁
  • gdbc_xfer_size (numeric) — Maximum size of memory transfers for the GDB client. Increasing this value will result in faster transfers, but may cause problems with some servers. bigger = faster = maybe messy ⚡
  • iradix (numeric) — Default input radix for address expressions. For address values with no radix specifier, this value gives the input radix, which is 10 (decimal) by default. base-10 bestie 🔢
  • quiet (boolean) — If set, MSPDebug will suppress most of its debug-related output. This option defaults to false, but can be set true on start-up using the -q command-line option. shhhh era 🤫

🌈 ENVIRONMENT 🌈

  • MSPDEBUG_TI3410_FW — Specifies the location of TI3410 firmware, for raw USB access to FET430UIF or eZ430 devices. This variable should contain the path to an Intel HEX file containing suitable firmware for the TI3410. firmware path bestie 🧚

🦋 FILES 🦋

  • ~/.mspdebug — File containing commands to be executed on startup. your lil autostart script ✨
  • ti_3410.fw.ihex — Firmware image for the TI3410 USB interface chip. This file is only required for raw USB access to FET430UIF or eZ430 devices. only if you're doing the raw USB thing 🔌

🔥 SEE ALSO 🔥

Go peek at nm(1), gdb(1), objcopy(1). friend group of tools 🫶

💀 BUGS 💀

If you find any bugs, you should report them to the author at dlbeer@gmail.com. It would help if you could include a transcript of an MSPDebug session illustrating the program, as well as any relevant binaries or other files. receipts help! 📝

Copyright (C) 2009-2013 Daniel Beer <dlbeer@gmail.com>

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. free software, iconic behavior 💖

That's the whole mspdebug(1) page, bestie! Version 0.25, dated 24 Jul 2017. Periodt. 🎀💅

📦 where this page comes from