sys64738
/
DragonProbe
1
0
Fork 0
Code Issues 1 Pull Requests 1 Releases Wiki Activity
Page: MehFET USB protocol
Pages
Common interfaces Default/standard mode Home Linux kernel modules MehFET USB protocol Mode 3: debug interface pinout detector Persistent storage SUMP Logic Analyzer mode USB config & command protocol dpctl xvc2dap
4 MehFET USB protocol
sys64738 edited this page 2021-10-08 19:25:45 +00:00
Table of Contents

MehFET

MehFET is a USB-based protocol meant for debugging MSP430 MCUs. It has been created because all existing ones either operated at a high level (eg. commands to insert breakpoints, which would require a lot of reimplementing existing code), or at a low level (bit-banging GPIO lines, which would be very slow over USB). Instead, the basic commands MehFET operates with, are reads and writes to the IR and DR registers. This is mostly the same abstraction level as used in CMSIS-DAP.

This document specifies version 0x0001 of the protocol.

USB descriptors

A USB device should be treated as a MehFET-capable device if one of its vendor interfaces has a "MehFET" substring in its iInterface string, and has '4' and '3' as subclass and protocol, respectively. It should have one bulk in endpoint, and one bulk out endpoint. No requirements on e.g. USB device VID and PID exist.

Command and response format

The main protocol consists of command-response transfers initiated by the USB host. A command consists of a command byte, up to four length bytes, and an optional payload (with a number of bytes specified in the length) used as argument data. A response starts with a status byte, followed by up to four length bytes, and optional response data.

More specifically, the lowest seven bits of a command byte indicate the command number, while the highest bit indicates the presence of length bytes and a payload. The length bytes are encoded using a "variable-length quantity" (VLQ) manner: of the first length byte, the lowest seven bits are data bits. If the highest bit is one, another lenght byte follows, with the same format. Seven-bit length data units are sent from lowest-significance to highest-significance. The length has a maximum length of four bytes, so the most-significant bit of the fourth length byte is treated as a data bit, and the next byte is a payload byte.

Examples

> 04
< 00

The host sends a single command, 4. As the highest bit of the command byte is low, no length and payload follow.

> 83 01 01
< FF 02 6E 6F

The host sends command 3, and as the highest bit is now high, the next byte indicates the length: 1. As the highest bit of the second byte is low, the third byte is the start of the payload, and not an extra length byte. The payload data consists of one byte (as indicated by the length), and has the value 0x01.

Similarly, the response status is 0x7F, and has two response bytes: 0x6E 0x6F.

> 88 80 04 FB 01 00 00 FF AA AA AA AA AA ...
< FE 00

Here the host sends command 8, with length 0x200, and data bytes 0xFB 0x01 0x00 0x00 0xFF 0xAA 0xAA .... Note that the device sends a response with a length byte, but the length is zero so no response data follows.

Commands

0x01: Info
0x02: Status
0x03: Connect
0x04: Disconnect
0x05: Delay
0x06: SetClkSpeed
0x07: GetOldLines
0x08: TdioSequence
0x09: TmsSequence
0x0a: TclkEdge
0x0b: TclkStrobe
0x0c: ResetTAP
0x0d: IRshift
0x0e: DRshift

Info

Info requests information of the MehFET debugging device.

Parameters: None.

Response data:

  • 4 bytes: capabilities bitflags (see below), little-endiant
  • 2 bytes: protocol version (little-endian integer), currently 0x0001
  • 1 byte: log2 of the maximum packet size (and the USB buffer size) on the device.
  • 1 byte: reserved
  • null-terminated string: Debugger hardware name. The null terminator must be the final byte of the response.

Capabilities bitflags:

  • 0: can debug MSP430 devices using JTAG that do not require a TEST/nRESET entry sequence
  • 1: can debug MSP430 devices using JTAG that do require a TEST/nRESET entry sequence
  • 2: can debug MSP430 devices using SBW that do require a TEST/nRESET entry sequence
  • 8: the ResetTAP command is implemented
  • 9: the IRshift command is implemented
  • 10: the DRshift command is implemented

Status

Status requests the device status, that is, whether it is currently debugging.

Parameters: None.

Response data:

  • 1 byte: connection status:
    • 0: no connection
    • 1: JTAG connection
    • 2: Spy-Bi-Wire connection

Connect

Connect to a device to be debugged. Performs the TEST/nRESET entry sequence when requested, and reset the TAP to a known state. The host is responsible for checking the JTAG ID, fuse status, and so on.

Parameters:

  • 1 byte: method:
    • 0: JTAG without TEST/nRESET entry sequence
    • 1: JTAG with TEST/nRESET entry sequence
    • 2: SBW with TEST/nRESET entry sequence
    • 0x80: bitflag: initial value of the nRESET/NMI line

Disconnect

Disconnect from the device that is being debugged.

Parameters: None.

Response data: None.

Delay

Perform a delay.

Parameters:

  • 4 bytes: delay value (little-endian)
    • bit 31: bitflag: exact delay. If low, the delay may overshoot the specified duration in order to service USB messages. If high, the device is allowed to busy-wait in order to perform the specified delay.
    • bit 30: bitflag: units. If low, the delay value is specified in milliseconds. If high, it is specified in microseconds.
    • bit 29..0: delay value.

Response data: None.

SetClkSpeed

Set the clock (TCK) speed to either a 'fast' or a 'slow' speed. The 'slow' speed, which is the default, is the speed used to perform a JTAG fuse check. The 'fast' speed is meant to send usable TCLK strobes used during flash programming and erasing.

Parameters

  • 1 byte: speed. If zero, switch to the slow speed mode. If nonzero, switch to fast mode.

Response data: None.

GetOldLines

Responds the values the TCK, TMS and TDI lines were last set at.

Parameters: None.

Response data:

  • 1 byte: bitflag:
    • bit 0: TCLK level
    • bit 1: TMS level
    • bit 2: TDI level

TdioSequence

Perform a JTAG or SBW data sequence. Shift data through TDI and TDO while holding TMS constant.

Parameters:

  • 4 bytes: number of bits to shift (which is the same as the number of cycles) (little-endian)
  • 1 byte: TMS line level to be held during the entire sequence, zero for low, nonzero for high.
  • length-5 bytes: TDI data bits to shift into the debugged device. Data is shifted in from the low bit to the high bit. The number of TDI data bytes must also be equal to (num_bits + 7) >> 3.

Response data:

  • TDO data shifted out from the debugged device. Same format and number of bytes as for the TDI bytes.

TmsSequence

Perform a JTAG or SBW sequence changing the TAP state.

WARNING: The host software must use GetOldLines when going through the Run-Test/IDLE JTAG state to specify the TDI level, to avoid spurious TCLK edges.

Parameters:

  • 4 bytes: number of bits to shift (little-endian)
  • 1 byte: TDI line level to be held during the entire sequence, zero for low, nonzero for high.
  • length-5 bytes: TMS data bits to shift into the debugged device. Data is shifted in from the low bit to the high bit. The number of TMS data bytes must also be equal to (num_bits + 7) >> 3.

Response data: None.

TclkEdge

Perform a single TCLK edge, setting the clock low or high.

Parameters:

  • 1 byte: new TCLK value: zero for low, nonzero for high. The debugger device keeps track of the old TCLK value.

Response data: None.

TclkStrobe

Perform a TCLK burst/strobe, that is, perform a number of full TCLK cycles.

Parameters:

  • 4 bytes: clock cycle count (little-endian). This is half the number of TCLK edges.

Response data: None.

ResetTAP

Reset the TAP state to the Run-Test/IDLE state, and optionally perform a JTAG fuse check.

Parameters:

  • 1 byte: bitflags:
    • bit 0: reset TAP to Run-Test/IDLE
    • bit 1: perform JTAG fuse check on device to be debugged (that is, perform the TMS sequence used to make the device check its internal fuse).
    • bit 2: read back the results of the JTAG fuse check (that is, return the result of the operation performed by setting bit 1).

Response data:

  • 1 byte: bitflags:
    • bit 7: high: JTAG fuse is blown. (Only valid if bit 2 set in parameters.)

IRshift

Shift bits into and out of the IR. The IR is always presumed to be 8 bit wide.

Parameters:

  • 1 byte: new IR data to be shifted into the debugged device.

Response data:

  • 1 byte: old IR data shifted out of the debugged device.

DRshift

Shift bits into and out of the DR. The DR can have a varying bit width.

Parameters:

  • 1 byte: number of bits
  • length-1 bytes: new DR value. Bits are shifted in from lowest to highest, byte by byte.

Response data:

  • Old DR value shifted out of the device. Same format and number of bytes as the new DR in the parameters.

Statuses

0x00: OK
....: Reserved
0x7C: Cannot perform specified command, as the device has indicated in its capabilities listing.
0x7D: Bad state (e.g. calling Disconnect when unconnected)
0x7E: Invalid/unknown command
0x7F: Unspecified error

With a non-OK response status, the response data is an optional error string (also null-terminated).