Document procedure for debugging with another Pico board.

.gitignore

@@ -1 +1,2 @@
 build
+build_debug

firmware/README.md

@@ -19,14 +19,76 @@ Then do this to build.
     mkdir build
     cd build
     cmake ..
-    make trackball
+    make -j4 trackball
 
 And flash the resulting `trackball.uf2` file to your Pico as usual.
 
 For convenience you can use the included `flash.sh`, as long as you flashed the binary manually once before.
 
-    make trackball
+    make -j4 trackball
     ../flash.sh trackball.uf2
 
-For debugging a serial port will be presented by the firmware.
+This will use the mass storage bootloader to upload a new uf2 image.
+
+For old-school debugging a serial port will be presented by the firmware.
 Open it using eg. `picocom`, or with the included `debug.sh` script.
+
+## Proper Debugging
+
+You can also use the SWD interface for proper hardware debugging.
+
+This follows the instructions from the [RP2040 Getting Started document](https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf) from chapter 5 and 6.
+
+For ease of reading the disassembly, create a debug build.
+
+    mkdir build_debug
+    cd build_debug
+    cmake -DCMAKE_BUILD_TYPE=Debug ..
+    make -j4 trackball
+
+You need a hardware SWD probe.
+This can be made from another Pico, see Appendix A in the document linked above.
+For this you need to compile the `picoprobe` firmware, like this.
+
+    git clone https://github.com/raspberrypi/picoprobe.git
+    cd picoprobe
+    git submodule update --init
+    mkdir build
+    cd build
+    PICO_SDK_PATH=../../../pico-sdk cmake ..
+    make -j4
+
+And flash the resulting `picoprobe.uf2` to your probe.
+Connect `GP2` of the probe to `SWCLK` of the target and `GP3` of the probe to `SWDIO` of the target.
+Of course you also need to connect GND between both.
+
+You need some dependencies, mainly `gdb-multiarch` and the RP2040 fork of `OpenOCD`.
+
+    sudo apt install gdb-multiarch   # Debian / Ubuntu
+    sudo pacman -S arm-none-eabi-gdb # Arch Linux
+
+    cd ../.. # back to build_debug directory from before
+
+    git clone https://github.com/raspberrypi/openocd.git --branch rp2040 --recursive --depth=1
+    cd openocd
+
+    # install udev rules
+    sudo cp contrib/60-openocd.rules /etc/udev/rules.d
+    sudo udevadm control --reload-rules && sudo udevadm trigger
+
+    ./bootstrap
+    ./configure --enable-ftdi --enable-sysfsgpio --enable-bcm2835gpio
+    make -j4
+
+Now we can flash a firmware image via OpenOCD.
+
+    ./openocd/src/openocd -s openocd/tcl -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000" -c "cmsis_dap_vid_pid 0x2e8a 0x000c" -c "program trackball.elf verify reset exit"
+
+And also start a GDB debugging session.
+
+    ./openocd/src/openocd -s openocd/tcl -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000" -c "cmsis_dap_vid_pid 0x2e8a 0x000c"
+    arm-none-eabi-gdb trackball.elf
+    target extended-remote localhost:3333
+
+These commands have also been put in the `flash_swd.sh` and `debug_swd.sh` scripts, respectively.
+Call them from the `build_debug` folder where you checked out and built OpenOCD.

firmware/debug_swd.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+set -euo pipefail
+
+echo Starting OpenOCD in background
+./openocd/src/openocd -s openocd/tcl -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000" -c "cmsis_dap_vid_pid 0x2e8a 0x000c" &
+OPENOCD_PID=$!
+
+# give OpenOCD some time to output stuff
+sleep 1
+
+echo -n Waiting for debugger to appear
+while ! netstat -tna | grep 'LISTEN\>' | grep -q ':3333\>'; do
+    echo -n .
+    sleep 1
+done
+
+echo Starting GDB
+arm-none-eabi-gdb -ex "target extended-remote localhost:3333" $1
+
+echo Killing OpenOCD instance in background
+kill $OPENOCD_PID

firmware/flash_swd.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+set -euo pipefail
+
+./openocd/src/openocd -s openocd/tcl -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000" -c "cmsis_dap_vid_pid 0x2e8a 0x000c" -c "program $1 verify reset exit"