move docs to wiki
This commit is contained in:
parent
fe209edbbb
commit
b22f97694a
209
README.md
209
README.md
|
|
@ -59,212 +59,7 @@ Other options are:
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
These microcontrollers support the following protocols:
|
For detailed usage notes, please visit the [wiki](https://git.lain.faith/sys64738/DapperMime-JTAG/wiki/Home).
|
||||||
|
|
||||||
| MCU | SWD | JTAG | UART | SPI (flashrom) | I2C | Other stuff |
|
|
||||||
|:------ |:---:|:----:|:----:|:-------------- |:--- |:--------------- |
|
|
||||||
| RP2040 | X | X | X | X | X | Planned |
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
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>|
|
|
||||||
|
|
||||||
On the RP2040, two USB CDC interfaces are exposed: the first is the UART
|
|
||||||
interface, the second is for Serprog. If you have no other USB-CDC intefaces,
|
|
||||||
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.
|
|
||||||
|
|
||||||
### UART
|
|
||||||
|
|
||||||
The UART pins are for connecting to the device to be debugged, the data is
|
|
||||||
echoed back over the USB CDC interface (typically a `/dev/ttyACMx` device on
|
|
||||||
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.
|
|
||||||
|
|
||||||
### SWD and JTAG debugging
|
|
||||||
|
|
||||||
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)
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
### Serprog/Flashrom
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
### SPI, I2C and temperature sensor
|
|
||||||
|
|
||||||
This functionality depends on custom kernel modules being loaded: In the
|
|
||||||
`host/modules/` directory, one can find the sources and a Makefile.
|
|
||||||
|
|
||||||
After loading the modules (and modprobing `i2c-dev` and `spidev`), devices for
|
|
||||||
these interfaces should appear in `/dev`.
|
|
||||||
|
|
||||||
SPI and I2C can be controlled using the standard tools for these (eg. the
|
|
||||||
utilities from `i2c-tools` package), and the temperature sensor should show
|
|
||||||
up in `lm_sensors`.
|
|
||||||
|
|
||||||
Using `i2cdetect -l`, you should be able to see which I2C device belongs to
|
|
||||||
the tool:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ sudo i2cdetect -l
|
|
||||||
[...]
|
|
||||||
i2c-1 i2c i915 gmbus dpb I2C adapter
|
|
||||||
i2c-8 i2c Radeon i2c bit bus 0x95 I2C adapter
|
|
||||||
i2c-15 i2c dmj-i2c-1-1:1.0 I2C adapter
|
|
||||||
i2c-6 i2c Radeon i2c bit bus 0x93 I2C adapter
|
|
||||||
i2c-13 i2c AUX C/DDI C/PHY C I2C adapter
|
|
||||||
```
|
|
||||||
|
|
||||||
#### I2C temperature sensor emulation
|
|
||||||
|
|
||||||
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):
|
|
||||||
```
|
|
||||||
$ ./dmctl.sh tempsensor --set 0x18 # need to give it an address first
|
|
||||||
$ sudo modprobe jc42
|
|
||||||
$ # now tell the jc42 module that the device can be found at this address
|
|
||||||
$ echo "jc42 0x18" | sudo tee /sys/bus/i2c/devices/i2c-BUSNUM/new_device
|
|
||||||
$ 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)
|
|
||||||
```
|
|
||||||
|
|
||||||
Temperature readout may be a bit higher than the ambient temperature.
|
|
||||||
|
|
||||||
### Runtime configuration
|
|
||||||
|
|
||||||
Several settings can be applied at runtime, using the `dmctl` Python script.
|
|
||||||
Settings are communicated over a vendor USB interface.
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./dmctl.sh --help
|
|
||||||
usage: dmctl [-h] [--conn CONN] subcommand ...
|
|
||||||
|
|
||||||
optional arguments:
|
|
||||||
-h, --help show this help message and exit
|
|
||||||
--conn CONN Connection string. Either a dmj-char device in /dev, a USB
|
|
||||||
bus.device number, or a USB VID:PID pair. Defaults to trying
|
|
||||||
/dev/dmj-* (if there is only one), and cafe:1312 otherwise.
|
|
||||||
|
|
||||||
subcommands:
|
|
||||||
For more info on each subcommand, run the program with 'subcommand --help' as
|
|
||||||
arguments.
|
|
||||||
|
|
||||||
subcommand Command to send to the device
|
|
||||||
get-device-info
|
|
||||||
Shows device info
|
|
||||||
get-mode-info Shows mode info. A mode can optionally be specified, default
|
|
||||||
is the current mode.
|
|
||||||
set-mode Set the device mode
|
|
||||||
uart-cts-rts Get, enable/disable UART hardware flow control
|
|
||||||
tempsensor Get or set the IRC emulation enable/address of the
|
|
||||||
temperature sensor.
|
|
||||||
jtag-scan JTAG pinout scanner
|
|
||||||
sump-overclock
|
|
||||||
SUMP logic analyzer overclock settings
|
|
||||||
```
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./dmctl.py --conn cafe:1312 get-device-info
|
|
||||||
```
|
|
||||||
|
|
||||||
### SUMP Logic Analyzer mode
|
|
||||||
|
|
||||||
The device can act as a logic analyzer, implementing the SUMP protocol. It
|
|
||||||
first needs to be put into mode 4, which can be done using the following
|
|
||||||
command:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./dmctl.sh set-mode 4
|
|
||||||
```
|
|
||||||
|
|
||||||
As soon as this is done, the SUMP logic analyzer should be available on the
|
|
||||||
first USB-CDC interface of the device. It can be used with a connection string
|
|
||||||
such as `ols:conn=/dev/ttyACM0` in sigrok and PulseView.
|
|
||||||
|
|
||||||
### XVC2DAP
|
|
||||||
|
|
||||||
`xvc2dap.py` is a Python script that implements a Xilinx Virtual Cable server
|
|
||||||
and talks to a CMSIS-DAP device, acting like a bridge between the two. This way,
|
|
||||||
you can use any CMSIS-DAP device (including this project) as a fake Xilinx
|
|
||||||
Platform Cable.
|
|
||||||
|
|
||||||
It requires pyOCD as a dependency (for its builtin `pydapaccess` module).
|
|
||||||
|
|
||||||
Usage:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./xvc2dap.py --help
|
|
||||||
usage: xvc2dap.py [-h] [--serial SERIAL] address [port]
|
|
||||||
|
|
||||||
positional arguments:
|
|
||||||
address Host to bind to, for the XVC server, default localhost
|
|
||||||
port port to bind to, for the XVC server, default 2542
|
|
||||||
|
|
||||||
optional arguments:
|
|
||||||
-h, --help show this help message and exit
|
|
||||||
--serial SERIAL Connection string to the CMSIS-DAP device, as a serial
|
|
||||||
number, defaults to the first device found.
|
|
||||||
```
|
|
||||||
|
|
||||||
### USB Vendor interface protocol
|
|
||||||
|
|
||||||
The USB vendor interface protocol is described
|
|
||||||
[here](./wiki/USB-config-%26-command-protocol) in the wiki.
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
|
|
@ -303,7 +98,7 @@ projects. These respective licenses can be found in
|
||||||
- interface 1 ("B"): index 2, epin 0x04, epout 0x83
|
- interface 1 ("B"): index 2, epin 0x04, epout 0x83
|
||||||
- interface 2 ("C"): index 3, epin 0x06, epout 0x85
|
- interface 2 ("C"): index 3, epin 0x06, epout 0x85
|
||||||
- interface 3 ("D"): index 4, epin 0x08, epout 0x87
|
- 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 )
|
- ~~or, FX2 emulation mode??? (useful links: https://sigrok.org/wiki/Fx2lafw ; https://sigrok.org/wiki/CWAV_USBee_SX/Info )~~ has a ROM/fw and everything, so, maybe not
|
||||||
- [ ] Mode where you can define custom PIO stuff for custom pinouts/protocols??????
|
- [ ] Mode where you can define custom PIO stuff for custom pinouts/protocols??????
|
||||||
- Maybe also with code that auto-reacts to stuff from the environment?
|
- Maybe also with code that auto-reacts to stuff from the environment?
|
||||||
- [ ] Facedancer implementation by connecting two picos via GPIO, one doing host
|
- [ ] Facedancer implementation by connecting two picos via GPIO, one doing host
|
||||||
|
|
|
||||||
|
|
@ -201,14 +201,14 @@ def main() -> int:
|
||||||
parser = argparse.ArgumentParser()
|
parser = argparse.ArgumentParser()
|
||||||
|
|
||||||
parser.add_argument('--serial', type=str, default=None,
|
parser.add_argument('--serial', type=str, default=None,
|
||||||
help="Connection string to the CMSIS-DAP device, as "+\
|
help="Connect to the CMSIS-DAP device with the "+\
|
||||||
"a serial number, defaults to the first device found.")
|
"specified serial number, defaults to the first device found.")
|
||||||
|
|
||||||
parser.add_argument('address', type=str, default='localhost', nargs='?',
|
parser.add_argument('address', type=str, default='localhost', nargs='?',
|
||||||
help="Host to bind to, for the XVC server, default "+\
|
help="Host to bind to, for the XVC server, default "+\
|
||||||
"localhost")
|
"localhost")
|
||||||
parser.add_argument('port', type=int, default=2542, nargs='?',
|
parser.add_argument('port', type=int, default=2542, nargs='?',
|
||||||
help="port to bind to, for the XVC server, default 2542")
|
help="Port to bind to, for the XVC server, default 2542")
|
||||||
|
|
||||||
args = parser.parse_args()
|
args = parser.parse_args()
|
||||||
return xvc2dap_do(args)
|
return xvc2dap_do(args)
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue