[openocd] Add support for custom OpenOCD path

Based on discussion #845

Raspberry Pi Pico provides its own version of OpenOCD
which can be used with Raspberry Pi Picoprobe.

Assuming you have RPi Pico stuff stored under ~/projects/pico/...:

 1. Build and install OpenOCD

  cd ~/projects/pico
  git clone https://github.com/raspberrypi/openocd.git
  cd openocd
  ./bootstrap
  mkdir build
  cd build
  ../configure --prefix=$(realpath ../install)
  make install

 2. Use it in your build terminal

   export MODM_OPENOCD_BINARY=$HOME/projects/pico/openocd/install/bin/openocd
   scons program

scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
╭────────────── build/scons-release/pico-blinky.elf
╰───OpenOCD───> rp2040
Open On-Chip Debugger 0.11.0-g4f2ae61 (2022-04-12-12:01)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'swd'
Info : Hardware thread awareness created
Info : Hardware thread awareness created
Info : RP2040 Flash Bank Command
Info : clock speed 5000 kHz
Info : SWD DPIDR 0x0bc12477
Info : SWD DLPIDR 0x00000001
Info : SWD DPIDR 0x0bc12477
Info : SWD DLPIDR 0x10000001
Info : rp2040.core0: hardware has 4 breakpoints, 2 watchpoints
Info : rp2040.core1: hardware has 4 breakpoints, 2 watchpoints
Info : starting gdb server for rp2040.core0 on 3333
Info : Listening on port 3333 for gdb connections
target halted due to debug-request, current mode: Thread
xPSR: 0xf1000000 pc: 0x000000ee msp: 0x20041f00
target halted due to debug-request, current mode: Thread
xPSR: 0xf1000000 pc: 0x000000ee msp: 0x20041f00
** Programming Started **
Info : RP2040 B0 Flash Probe: 2097152 bytes @10000000, in 512 sectors

target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0000012a msp: 0x20041f00
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0000012a msp: 0x20041f00
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0000012a msp: 0x20041f00
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0000012a msp: 0x20041f00
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0000012a msp: 0x20041f00
Info : Writing 4096 bytes starting at 0x0
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0000012a msp: 0x20041f00
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0000012a msp: 0x20041f00
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0000012a msp: 0x20041f00
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0000012a msp: 0x20041f00
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0000012a msp: 0x20041f00
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0000012a msp: 0x20041f00
** Programming Finished **
** Verify Started **
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0000012a msp: 0x20041f00
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0000012a msp: 0x20041f00
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0000012a msp: 0x20041f00
** Verified OK **
shutdown command invoked
scons: done building targets

src/modm/board/rp_pico/module.lb

@@ -21,11 +21,62 @@ See https://www.raspberrypi.com/products/raspberry-pi-pico
 
 ## Programming
 
+### UF2
+
 The RP2040 ships with a [UF2 bootloader in ROM](https://github.com/microsoft/uf2).
 
 To upload your application, connect the RP2040 via USB, convert the ELF to UF2
 format by calling `scons uf2` or `make uf2` and copy the generated `.uf2` file
 to the mounted virtual disk.
+
+
+### OpenOCD
+
+Another option is to use Picoprobe and custom version of OpenOCD provided by RPi.
+
+You would need to build and program one of the boards with the Picoprobe firmware,
+configure and build RPi OpenOCD, and connect the boards via SWD.
+The wiring diagram and detailed description is available in the
+[Pico Documentation](https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf#Appendix%20A:%20Using%20Picoprobe).
+
+The how-to shows steps for building and installing the RPi OpenOCD into your
+system globally, however, if you still want to be able to work with other OpenOCD
+binaries, you should only install it locally:
+
+```sh
+sudo apt install automake autoconf build-essential texinfo libtool libftdi-dev libusb-1.0-0-dev
+
+cd ~/pico
+git clone https://github.com/raspberrypi/openocd.git --branch rp2040 --depth=1 --no-single-branch
+
+cd openocd
+./bootstrap
+
+mkdir build
+cd build
+../configure --enable-picoprobe --prefix=$(realpath ../install)
+
+make -j4
+make install
+```
+
+[Additional steps are needed](https://forums.raspberrypi.com/viewtopic.php?t=312867)
+to get access to the device from a non-privileged user on Linux.
+Edit or create the `/etc/udev/rules.d/60-openocd.rules` file and append these
+lines to it:
+
+```
+# Raspberry Pi Picoprobe
+ATTRS{idVendor}=="2e8a", ATTRS{idProduct}=="0004", MODE="660", GROUP="plugdev", TAG+="uaccess"
+```
+
+Once you have both of your Pico boards connected according to the wiring diagram,
+you can run `scons program` to program the dev board:
+
+```sh
+export MODM_OPENOCD_BINARY=$HOME/pico/openocd/install/bin/openocd
+scons program
+```
 """
 
 def prepare(module, options):
@@ -49,3 +100,6 @@ def build(env):
     env.template("../board.cpp.in", "board.cpp")
     env.copy('.')
 
+    env.outbasepath = "modm/openocd/modm/board/"
+    env.copy(repopath("tools/openocd/modm/rp2040_picoprobe.cfg"), "rp2040_picoprobe.cfg")
+    env.collect(":build:openocd.source", "modm/board/rp2040_picoprobe.cfg")

tools/modm_tools/openocd.py

@@ -25,6 +25,14 @@
 python3 modm/modm_tools/openocd.py -f modm/openocd.cfg --reset
 ```
 
+You can use a different OpenOCD binary by setting the `MODM_OPENOCD_BINARY`
+environment variable before calling this script. This can be useful when
+using a custom OpenOCD build for specific targets.
+
+```sh
+export MODM_OPENOCD_BINARY=/path/to/other/openocd
+```
+
 (\* *only ARM Cortex-M targets*)
 """
 
@@ -78,7 +86,10 @@ def call(commands=None, config=None, search=None, blocking=True, silent=False, v
     # See http://openocd.org/doc/html/Running.html
     # os.environ.get("OPENOCD_SCRIPTS", "")
 
-    command_openocd = "openocd {} {} {}".format(
+    binary = os.environ.get("MODM_OPENOCD_BINARY", "openocd")
+
+    command_openocd = "{} {} {} {}".format(
+        binary,
         " ".join(map('-s "{}"'.format, search)),
         " ".join(map('-f "{}"'.format, config)),
         " ".join(map('-c "{}"'.format, commands))

tools/openocd/modm/rp2040_picoprobe.cfg

@@ -0,0 +1,6 @@
+# Script for working with RP2040 boards using Picoprobe
+
+# Must be specified by the user via `modm:build:openocd.cfg` option
+
+source [find interface/picoprobe.cfg]
+source [find target/rp2040.cfg]