DragonProbe/README.md

313 lines
14 KiB
Markdown
Raw Normal View History

2021-06-21 16:11:02 +00:00
# DapperMime-JTAG
2021-01-31 03:43:09 +00:00
2021-06-21 16:11:02 +00:00
(name is still WIP)
2021-01-31 03:43:09 +00:00
2021-06-21 16:11:02 +00:00
This project attempts to add Bus Pirate/...-like functionality to a number of
MCUs, mainly the Raspberry Pi Pico. It was originally based on [Dapper
Mime](https://github.com/majbthrd/DapperMime/), an SWD debugger probe implementation,
with the goal of adding JTAG support as well. However, more and more features
got added over time.
## Variants
Most support and development effort goes to the RP2040/Pico, but, due to the
projects' structure still being based on Dapper Mime's, it is relatively easy
to add support for another MCU/board. Any MCU supported by [TinyUSB
](https://github.com/hathach/tinyusb) should work. Features can also be disabled
per MCU.
Adding support for another MCU is a matter of adding another subfolder in the
`./bsp` folder, implementing the functionality (which only concerns itself with
sending commands to the hardware, protocol parsing is done by shared code),
and handling it in the `CMakeFiles.txt` file.
2021-01-31 03:43:09 +00:00
## Building
2021-06-21 16:11:02 +00:00
After initially downloading this project's code, issue the following command to download TinyUSB and CMSIS 5 code:
2021-01-31 03:43:09 +00:00
```
git submodule update --init --recursive
2021-01-31 03:43:09 +00:00
```
2021-06-21 16:11:02 +00:00
Compilation is done using CMake:
```
mkdir cmake-build && cd cmake-build
cmake -DBOARD=raspberry_pi_pico -DFAMILY=rp2040 -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
```
2021-06-21 16:11:02 +00:00
`BOARD` and `FAMILY` should correspond to those used in the TinyUSB `hw` folder,
and with the folders used in `./bsp` as well.
2021-06-21 16:20:19 +00:00
A non-exhaustive list of possible BOARD/FAMILY combinations:
2021-06-21 16:11:02 +00:00
| `FAMILY` | `BOARD` | description | notes |
|:-------- |:------------------ |:----------------- |:------- |
| `rp2040` |`raspberry_pi_pico` | Raspberry Pi Pico | default |
### Notes on compiling for the RP2040 Pico
2021-06-21 16:11:02 +00:00
If you have the Pico SDK installed on your system, and the `PICO_SDK_PATH`
environment variable is specified properly, you can omit the `--recursive` flag
in the `git submodule` invocation (to avoid many many git clones), and pass
the `-DUSE_SYSTEMWIDE_PICOSDK=On` flag to CMake, too.
2021-06-21 16:11:02 +00:00
Other options are:
* `-DPICO_NO_FLASH=[On|Off]`: store the binary in RAM only, useful for development.
* `-DPICO_COPY_TO_RAM=[On|Off]`: write to flash, but always run from RAM
* `-DUSE_USBCDC_FOR_STDIO=[On|Off]`: export an extra USB-CDC interface for debugging
2021-06-21 16:11:02 +00:00
## Usage
2021-06-02 22:45:32 +00:00
These microcontrollers support the following protocols:
2021-06-14 01:43:21 +00:00
| MCU | SWD | JTAG | UART | SPI (flashrom) | I2C | Other stuff |
2021-06-02 22:48:28 +00:00
|:------ |:---:|:----:|:----:|:-------------- |:--- |:--------------- |
2021-06-20 21:58:26 +00:00
| RP2040 | X | X | X | X | X | Planned |
2021-06-02 22:45:32 +00:00
2021-06-21 16:11:02 +00:00
The [original repository]() (Dapper
Mime) supported only SWD and UART, and worked for the RP2040 Pico and the
STM32F072 Discovery. This fork focusses on adding more protocols, but the
author of this fork only has a Raspberry Pi Pico.
2021-06-02 22:45:32 +00:00
The pin mapping for the RP2040 is as follows:
| Pin number | Usage | Usage | Pin number |
|:---------- |:-------------- | --------------:| ----------:|
| GP0 | stdio UART TX | | VBUS |
| GP1 | stdio UART RX | | VSYS |
| GND | <ground> | <ground> | GND |
| GP2 | SWCLK/TCK | | 3V3 EN |
| GP3 | SWDIO/TMS | | 3V3 OUT |
| GP4 | TDI | | ADC VREF |
| GP5 | TDO | | GP28 / ADC2|
| GND | <ground> | <ground> | GND / AGND|
| GP6 | nTRST | | GP27 / ADC1|
| GP7 | nRESET | | GP26 / ADC0|
| GP8 | UART TX | | RUN |
| GP9 | UART RX | (1-wire, TODO) | GP22 |
| GND | <ground> | <ground> | GND |
| GP10 | UART CTS | SCL | GP21 |
| GP11 | UART RTS | SDA | GP20 |
| GP12 | MISO | | GP19 |
| GP13 | nCS | | GP18 |
| GND | <ground> | <ground> | GND |
| GP14 | SCLK | | GP17 |
| GP15 | MOSI | | GP16 |
| <end>| <bottom> | <bottom> | <end>|
2021-06-08 00:32:06 +00:00
On the RP2040, two USB CDC interfaces are exposed: the first is the UART
2021-06-12 19:55:09 +00:00
interface, the second is for Serprog. If you have no other USB-CDC intefaces,
2021-06-21 16:14:53 +00:00
these will be `/dev/ttyACM0` and `/dev/ttyACM1`, respectively. If you have
enabled the `USE_USBCDC_FOR_STDIO` option, there will be a third device file.
2021-06-08 00:32:06 +00:00
2021-06-21 16:11:02 +00:00
### UART
The UART pins are for connecting to the device to be debugged, the data is
2021-05-31 10:51:07 +00:00
echoed back over the USB CDC interface (typically a `/dev/ttyACMx` device on
2021-06-12 19:55:09 +00:00
Linux). If you want to get stdio readout of this program on your computer,
connect GP0 to GP5, and GP1 to GP4, or alternatively, use the
`USE_USBCDC_FOR_STDIO` CMake flag, which adds an extra USB-CDC interface for
which stdio is used exclusively, while disabling stdio on the UART.
2021-06-21 16:14:53 +00:00
### SWD and JTAG debugging
2021-06-21 16:11:02 +00:00
In SWD mode, the pin mapping is entirely as with the standard Picoprobe setup,
as described in Chapter 5 and Appendix A of [Getting Started with Raspberry Pi
Pico](https://datasheets.raspberrypi.org/pico/getting-started-with-pico.pdf)
2021-06-02 22:45:32 +00:00
In JTAG mode, TCK and TMS have the same pins as SWCLK and SWDIO, respectively,
TDI and TDO are on the next two consecutive free pins.
In your OpenOCD flags, use `-f interface/cmsis-dap.cfg`. Default transport is
JTAG, if OpenOCD doesn't specify a default to the probe.
2021-06-21 16:11:02 +00:00
### Serprog/Flashrom
2021-06-08 00:32:06 +00:00
For Serprog, use the following `flashrom` options (if `/dev/ttyACM1` is the USB
serial device on your machine corresponding to the Serprog CDC interface of the
Pico):
```
flashrom -c <flashchip> -p serprog:dev=/dev/ttyACM1:115200 <rest of the read/write cmd>
```
Different serial speeds can be used, too. Serprog support is *techincally*
untested, as in it does output the correct SPI commands as seen by my logic
analyzer, but I don't have a SPI flash chip to test it on.
2021-06-21 16:11:02 +00:00
### I2C-Tiny-USB
2021-06-14 01:40:19 +00:00
The I2C-Tiny-USB functionality can be used as follows: first, load the
`i2c-dev` and `i2c-tiny-usb` modules (for now you need a patched version of the
latter, can be found in the `i2c-tiny-usb-misc/` folder in this repo). Then you
can use the I2C USB bridge as any other I2C device on your computer. For
example, the `i2cdetect`, `i2cget` and `i2cset` tools from `i2c-tools` should
2021-06-21 14:28:32 +00:00
all work. You can find which I2C device corresponds to the I2C-Tiny-USB, by
running `i2cdetect -l`:
```
$ sudo i2cdetect -l
[...]
i2c-1 i2c i915 gmbus dpb I2C adapter
i2c-8 i2c Radeon i2c bit bus 0x95 I2C adapter
i2c-15 i2c i2c-tiny-usb at bus 001 device 011 I2C adapter # <---- !
i2c-6 i2c Radeon i2c bit bus 0x93 I2C adapter
i2c-13 i2c AUX C/DDI C/PHY C I2C adapter
[...]
```
2021-06-28 01:31:07 +00:00
**NOTE**: I2C functionality sometimes breaks with certain USB hubs. If this is
the case, try unplugging and replugging the entire hub.
2021-06-21 16:11:02 +00:00
#### I2C temperature sensor emulation
2021-06-21 14:28:32 +00:00
If the board/MCU has a builtin temperature sensor, a fake I2C device on the bus
can optionally be enabled to use it as a Jedec JC42.2-compliant temperature
sensor (the exact sensor emulated is the Microchip MCP9808). To have it show
up in `sensors`, do the following (with `BUSNUM` the number from the above
`i2cdetect -l` output):
```
2021-06-21 15:55:06 +00:00
$ ./dmctl.py /dev/ttyACM1 --i2ctemp 0x18 # need to give it an address first
2021-06-21 14:28:32 +00:00
$ sudo modprobe jc42
2021-06-21 15:55:06 +00:00
$ # now tell the jc42 module that the device can be found at this address
2021-06-28 01:31:07 +00:00
$ echo "jc42 0x18" | sudo tee /sys/bus/i2c/devices/i2c-BUSNUM/new_device
2021-06-21 15:55:06 +00:00
$ sudo sensors # it should show up now:
jc42-i2c-BUSNUM-18
Adapter: i2c-tiny-usb at bus 001 device 032
temp1: +23.1°C (low = -20.0°C)
(high = +75.0°C, hyst = +75.0°C)
(crit = +80.0°C, hyst = +80.0°C)
2021-06-21 14:28:32 +00:00
```
2021-06-21 15:55:06 +00:00
Temperature readout may be a bit higher than the ambient temperature.
2021-06-14 01:40:19 +00:00
2021-06-12 19:55:09 +00:00
### Runtime configuration
Several settings can be applied at runtime, using the `dmctl` Python script.
Settings are communicated over the Serprog USB serial port.
The currently implemented options are:
2021-06-21 14:28:32 +00:00
- `support`: tells you which features this implementation/board supports
2021-06-12 19:55:09 +00:00
- `ctsrts`: Enable/disable CTS/RTS-based hardware flow control for the UART port
2021-06-21 14:28:32 +00:00
- `i2ctemp`: Get or set the I2C address of the fake I2C device of the temperature
sensor. Use 0 for getting the value, 0xff for disabling, and any
other for setting the address. The I2C device emulated is an MCP9808.
2021-06-21 15:55:06 +00:00
When setting a value, the old value is printed.
2021-06-12 19:55:09 +00:00
```
usage: dmctl [-h] [-v] [--ctsrts [CTSRTS]] tty
Runtime configuration control for DapperMime-JTAG
positional arguments:
tty Path to DapperMime-JTAG Serprog UART device
optional arguments:
2021-06-21 14:28:32 +00:00
-h, --help show this help message and exit
-v, --verbose Verbose logging (for this utility)
--ctsrts [CTSRTS] Enable or disable CTS/RTS flow control (--ctsrts [true|false])
--i2ctemp [I2CTEMP] Control the builtin I2C temperature controller: get (0),
disable (-1/0xff) or set/enable (other) the current
status and I2C bus address
--support Get list of supported/implemented functionality
2021-06-12 19:55:09 +00:00
```
example:
```
$ ./dmctl.py /dev/ttyACM1 --ctsrts true
```
2021-01-31 03:43:09 +00:00
## License
TinyUSB is licensed under the [MIT license](https://opensource.org/licenses/MIT).
2021-06-21 16:11:02 +00:00
ARM's CMSIS 5 code is licensed under the [Apache 2.0 license](https://opensource.org/licenses/Apache-2.0).
2021-01-31 03:43:09 +00:00
2021-06-08 00:32:06 +00:00
libco is licensed under the [ISC license](https://opensource.org/licenses/ISC)
2021-06-02 22:45:32 +00:00
## TODO
2021-06-28 20:44:02 +00:00
- [ ] A name
2021-07-13 01:41:38 +00:00
- [ ] A (VID and) PID, and maybe better subclass & protocol IDs for the vnd cfg itf
2021-07-18 20:22:21 +00:00
- [x] More Pico SDK meta/buildinfo
- [x] CMSIS-DAP JTAG implementation
2021-06-08 00:32:06 +00:00
- [x] Flashrom/SPI support using Serprog
- Parallel ROM flashing support, too, by having the device switch into a
separate mode that temporarily disables all other IO protocols
- Not enough IO, rip.
2021-06-12 19:35:06 +00:00
- [x] UART with CTS/RTS flow control
- [x] Needs configurable stuff as well, as some UART interfaces won't use this.
- [x] Debug interface to send printf stuff directly to USB, instead of having
2021-06-14 01:42:12 +00:00
to use the UART interface as a loopback thing.
2021-06-20 21:58:26 +00:00
- [ ] Second UART port for when stdio UART is disabled?
- [x] I2C support by emulating the I2C Tiny USB
2021-06-21 15:55:06 +00:00
- [x] Expose RP2040-internal temperature ADC on I2C-over-USB bus?
2021-06-20 22:10:12 +00:00
- [ ] ~~Does SMBus stuff need special treatment here?~~ ~~No.~~ Actually, some
2021-06-19 20:26:18 +00:00
parts do, but, laziness.
2021-06-20 22:10:12 +00:00
- [x] 10-bit I2C address support (Needs poking at the Pico SDK, as it only
2021-06-14 01:42:12 +00:00
supports 7-bit ones).
2021-06-29 02:27:41 +00:00
- [ ] Better USB interface stuff, because I2C-Tiny-USB sucks and serprog can only
do flash chips instead of being a real spidev. General idea can probably be
taken from the DLN2 Linux drivers, except better (dynamic interface
signalled in the protocol (eg. does the device actually have I2C/SPI/..?),
dynamic I2C and SPI capabilities, add 1wire stuff, maybe yeet the GPIO bc
it'll be used for other stuff anyway, etc.). Means a custom Linux driver but
oh well, I2C-Tiny-USB needs patching either way.
- [ ] 1-wire using ↑
2021-07-13 01:41:38 +00:00
- [x] A proper interface for sending commands etc. instead of shoehorning it
2021-06-28 20:44:02 +00:00
into Serprog.
2021-06-29 02:27:41 +00:00
- Can probably be included in the "Better USB interface stuff".
- [ ] make modes persistent?
2021-06-28 01:31:07 +00:00
- [ ] JTAG pinout detector
- https://github.com/cyphunk/JTAGenum
- https://github.com/travisgoodspeed/goodfet/blob/master/firmware/apps/jscan/jscan.c
2021-06-12 19:35:06 +00:00
- [ ] Host-side script that is an XVC (or hw_server) cable and communicates
with the device to perform the JTAG commands, because Vivado no likey
OpenOCD.
- CMSIS-DAP interface can be used directly, see CMSIS_5/CMSIS/DoxyGen/DAP/src/dap_USB_cmds.txt
- https://github.com/BerkeleyLab/XVC-FTDI-JTAG
- https://www.eevblog.com/forum/fpga/xilinx-jtag-and-tcf/
- https://git.eclipse.org/c/tcf/org.eclipse.tcf.git/plain/docs/TCF%20Linux%20Agent%20Prototype.html
- http://www.eclipse.org/tcf/
- https://debugmo.de/2012/02/xvcd-the-xilinx-virtual-cable-daemon/
- https://github.com/Xilinx/XilinxVirtualCable/
- https://github.com/derekmulcahy/xvcpi
- OpenOCD as XVC client??
2021-07-18 20:22:21 +00:00
- [x] SUMP logic analyzer mode?
2021-06-28 20:44:02 +00:00
- see also [this](https://github.com/perexg/picoprobe-sump)
- [ ] runtime config options for overclocking, logging
2021-06-28 20:44:02 +00:00
- [ ] FT2232 emulation mode?
- watch out, still need a vnd cfg interface! libftdi expects the following stuff: (TODO: acquire detailed protocol description)
- interface 0 ("A"): index 1, epin 0x02, epout 0x81
- interface 1 ("B"): index 2, epin 0x04, epout 0x83
- interface 2 ("C"): index 3, epin 0x06, epout 0x85
- interface 3 ("D"): index 4, epin 0x08, epout 0x87
- or, FX2 emulation mode??? (useful links: https://sigrok.org/wiki/Fx2lafw ; https://sigrok.org/wiki/CWAV_USBee_SX/Info )
2021-06-28 20:44:02 +00:00
- [ ] Mode where you can define custom PIO stuff for custom pinouts/protocols??????
- Maybe also with code that auto-reacts to stuff from the environment?
2021-06-29 02:27:41 +00:00
- [ ] Facedancer implementation by connecting two picos via GPIO, one doing host
stuff, the other device, commands being sent over GPIO to do stuff
- [ ] Maybe use the ADCs for something?
2021-06-13 16:47:46 +00:00
- [ ] SD/MMC/SDIO (will be a pain)
- [ ] MSP430 programming
- https://dlbeer.co.nz/mspdebug/usb.html
- https://github.com/dlbeer/mspdebug
- https://www.ti.com/lit/an/slaa754/slaa754.pdf
- https://www.ti.com/lit/ug/slau320aj/slau320aj.pdf
2021-06-02 22:45:32 +00:00
- [ ] AVR programming (USBavr emulation?)
- AVR ISP is hardly used anymore
- TPI/UPDI requires 5V levels, Pico doesn't do that :/
- debugWIRE????
- https://github.com/travisgoodspeed/goodfet/blob/master/firmware/apps/avr/avr.c
- [ ] PIC programming
- https://github.com/travisgoodspeed/goodfet/tree/master/firmware/apps/pic
2021-06-28 01:31:07 +00:00
- iCE40 programming??
- Renesas E7-{0,1,2} programming thing????
- Renesas tell us how this works pls
2021-06-13 16:47:46 +00:00
- Maybe steal other features from the Bus Pirate, [HydraBus](https://github.com/hydrabus/hydrafw) or Glasgow or so
2021-06-29 02:27:41 +00:00
- 3-wire? Never seen this one in the wild
2021-06-28 01:31:07 +00:00
- CAN? LIN? MOD? If I'd first be able to find a CAN device to test it with, sure
2021-06-02 22:45:32 +00:00