diff --git a/README.md b/README.md index 59e3435..d1b05db 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,25 @@ -## Dapper Mime +# DapperMime-JTAG -This unearths the name of a weekend project that I did in 2014. Both then and now, this is a port of [ARM's CMSIS-DAP code](https://github.com/arm-software/CMSIS_5) to a platform without the need for an expensive proprietary compiler and USB drivers. +(name is still WIP) -Whereas the original code used ST's STM32 USB drivers, this new iteration uses [TinyUSB](https://github.com/hathach/tinyusb), an open source cross-platform USB stack for embedded systems. +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. ## Variants @@ -18,28 +35,39 @@ For BOARD=stm32f072disco, the inexpensive [32F072BDISCOVERY evaluation board](ht ## Building -After initially downloading this project's code, issue the following command to download TinyUSB and CMSIS_5 code: +After initially downloading this project's code, issue the following command to download TinyUSB and CMSIS 5 code: ``` git submodule update --init --recursive ``` -Follow the TinyUSB build instructions [available here](https://github.com/hathach/tinyusb/tree/master/docs), but issue the make command in the base directory of Dapper Mime. - -Note that each TinyUSB board name being targeted needs a corresponding subdirectory under the Dapper Mime ./bsp/ subdirectory and a customized version of DAP_config.h for the target. - -Alternatively, one can compile with CMake: +Compilation is done using CMake: ``` mkdir cmake-build && cd cmake-build -cmake -DBOARD=raspberry_pi_pico -DFAMILIY=rp2040 -DCMAKE_BUILD_TYPE=Debug .. +cmake -DBOARD=raspberry_pi_pico -DFAMILIY=rp2040 -DCMAKE_BUILD_TYPE=RelWithDebInfo .. ``` +`BOARD` and `FAMILY` should correspond to those used in the TinyUSB `hw` folder, +and with the folders used in `./bsp` as well. + +Possible BOARD/FAMILY combinations are: + +| `FAMILY` | `BOARD` | description | +|:------- |:-------- |:----------- | +| `rp2040`|`raspberry_pi_pico`|Raspberry Pi Pico | +| `stm32f072disco`|`stm32f072disco`| STM 32072B "Discovery" | + 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. +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 debuggin + ## Usage These microcontrollers support the following protocols: @@ -49,7 +77,7 @@ These microcontrollers support the following protocols: | RP2040 | X | X | X | X | X | Planned | | STM32F072B Discovery | X | | | | | | -The [original repository](https://github.com/majbthrd/DapperMime/) (Dapper +The [original repository]() (Dapper Mime) supported only SWD and UART, and worked for these two boards. This fork focusses on adding more protocols, but the author of this fork only has a Raspberry Pi Pico. @@ -84,6 +112,8 @@ 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. +### 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, @@ -91,6 +121,8 @@ 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 debuggin + 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) @@ -101,6 +133,8 @@ 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): @@ -113,6 +147,8 @@ 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. +### I2C-Tiny-USB + 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 @@ -132,6 +168,8 @@ 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 @@ -193,7 +231,7 @@ $ ./dmctl.py /dev/ttyACM1 --ctsrts true TinyUSB is licensed under the [MIT license](https://opensource.org/licenses/MIT). -ARM's CMSIS_5 code is licensed under the [Apache 2.0 license](https://opensource.org/licenses/Apache-2.0). +ARM's CMSIS 5 code is licensed under the [Apache 2.0 license](https://opensource.org/licenses/Apache-2.0). libco is licensed under the [ISC license](https://opensource.org/licenses/ISC) @@ -236,6 +274,7 @@ libco is licensed under the [ISC license](https://opensource.org/licenses/ISC) - AVR ISP is hardly used anymore - TPI/UPDI requires 5V levels, Pico doesn't do that :/ - debugWIRE???? +- [ ] FT2232 emulation mode? - Renesas E7-{0,1,2} programming thing???? - Renesas tell us how this works pls - Maybe steal other features from the Bus Pirate, [HydraBus](https://github.com/hydrabus/hydrafw) or Glasgow or so