Add pico-debug support (earlephilhower#239)

Author: majbthrd

README.md

@@ -102,8 +102,25 @@ The first line creates a file with the USB vendor and ID of the Picoprobe and te
 
 Once Picoprobe permissions are set up properly, then select the board "Raspberry Pi Pico (Picoprobe)" in the Tools menu and upload as normal.
 
-# Debugging with Picoprobe, OpenOCD, and GDB
-The installed tools include a version of OpenOCD (in the pqt-openocd directory) and GDB (in the pqt-gcc directory).  These may be used to run GDB in an interactive window as documented in the Pico Getting Started manuals from the Raspberry Pi Foundation.
+# Uploading Sketches with pico-debug
+[pico-debug](https://github.com/majbthrd/pico-debug/) differs from Picoprobe in that pico-debug is a virtual debug pod that runs side-by-side on the same RP2040 that you run your code on; so, you only need one RP2040 board instead of two.  pico-debug also differs from Picoprobe in that pico-debug is standards-based; it uses the CMSIS-DAP protocol, which means even software not specially written for the Raspberry Pi Pico can support it.  pico-debug uses OpenOCD to handle your sketch uploads, and debugging can be accomplished with CMSIS-DAP capable debuggers including GDB.
+
+Under Windows and macOS, any user should be able to access pico-debug automatically, but under Linux `udev` must be told about the device and to allow normal users access.
+
+To set up user-level access to all CMSIS-DAP adapters on Ubuntu (and other OSes which use `udev`):
+````
+echo 'ATTRS{product}=="*CMSIS-DAP*", MODE="664", GROUP="plugdev"' | sudo tee -a /etc/udev/rules.d/98-CMSIS-DAP.rules
+sudo udevadm control --reload
+````
+
+The first line creates a file that recognizes all CMSIS-DAP adapters and tells UDEV to give users full access to it.  The second causes `udev` to load this new rule.  Note that you will need to unplug and re-plug in your device the first time you create this file, to allow udev to make the device node properly.
+
+Once CMSIS-DAP permissions are set up properly, then select the board "Raspberry Pi Pico (pico-debug)" in the Tools menu.
+
+When first connecting the USB port to your PC, you must copy [pico-debug-gimmecache.uf2](https://github.com/majbthrd/pico-debug/releases/) to the Pi Pico to load pico-debug into RAM; after this, upload as normal.
+
+# Debugging with Picoprobe/pico-debug, OpenOCD, and GDB
+The installed tools include a version of OpenOCD (in the pqt-openocd directory) and GDB (in the pqt-gcc directory).  These may be used to run GDB in an interactive window as documented in the Pico Getting Started manuals from the Raspberry Pi Foundation.  For [pico-debug](https://github.com/majbthrd/pico-debug/), replace the raspberrypi-swd and picoprobe example OpenOCD arguments of "-f interface/raspberrypi-swd.cfg -f target/rp2040.cfg" or "-f interface/picoprobe.cfg -f target/rp2040.cfg" respectively in the Pico Getting Started manual with "-f board/pico-debug.cfg".
 
 # Features
 * Adafruit TinyUSB Arduino (USB mouse, keyboard, flash drive, generic HID, CDC Serial, MIDI, WebUSB, others)

boards.txt

@@ -19,7 +19,7 @@
     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */
 
-#ifndef USE_TINYUSB
+#if !defined(USE_TINYUSB) && !defined(NO_USB)
 
 #include <Arduino.h>
 #include "CoreMutex.h"

cores/rp2040/RP2040USB.cpp

@@ -20,7 +20,7 @@
     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */
 
-#ifndef USE_TINYUSB
+#if !defined(USE_TINYUSB) && !defined(NO_USB)
 
 #include <Arduino.h>
 #include "CoreMutex.h"

cores/rp2040/SerialUSB.cpp

@@ -61,6 +61,7 @@ extern "C" int main() {
     mutex_init(&_pioMutex);
     initVariant();
 
+#ifndef NO_USB
 #ifdef USE_TINYUSB
     TinyUSB_Device_Init(0);
 
@@ -72,18 +73,21 @@ extern "C" int main() {
     Serial.begin(115200);
 #endif
 #endif
+#endif
 
 #if defined DEBUG_RP2040_PORT
     DEBUG_RP2040_PORT.begin();
 #endif
 
+#ifndef NO_USB
     if (setup1 || loop1) {
         rp2040.fifo.begin(2);
         multicore_launch_core1(main1);
     } else {
         rp2040.fifo.begin(1);
     }
     rp2040.fifo.registerCore();
+#endif
 
     setup();
     while (true) {

cores/rp2040/main.cpp

@@ -135,6 +135,25 @@ The first line creates a file with the USB vendor and ID of the Picoprobe and te
 
 Once Picoprobe permissions are set up properly, then select the board "Raspberry Pi Pico (Picoprobe)" in the Tools menu and upload as normal.
 
-Debugging with Picoprobe, OpenOCD, and GDB
-------------------------------------------
-The installed tools include a version of OpenOCD (in the pqt-openocd directory) and GDB (in the pqt-gcc directory).  These may be used to run GDB in an interactive window as documented in the Pico Getting Started manuals from the Raspberry Pi Foundation.
+Uploading Sketches with pico-debug
+----------------------------------
+pico-debug differs from Picoprobe in that pico-debug is a virtual debug pod that runs side-by-side on the same RP2040 that you run your code on; so, you only need one RP2040 board instead of two.  pico-debug also differs from Picoprobe in that pico-debug is standards-based; it uses the CMSIS-DAP protocol, which means even software not specially written for the Raspberry Pi Pico can support it.  pico-debug uses OpenOCD to handle your sketch uploads, and debugging can be accomplished with CMSIS-DAP capable debuggers including GDB.
+
+Under Windows and macOS, any user should be able to access pico-debug automatically, but under Linux `udev` must be told about the device and to allow normal users access.
+
+To set up user-level access to all CMSIS-DAP adapters on Ubuntu (and other OSes which use `udev`):
+
+.. code::
+
+        echo 'ATTRS{product}=="*CMSIS-DAP*", MODE="664", GROUP="plugdev"' | sudo tee -a /etc/udev/rules.d/98-CMSIS-DAP.rules
+        sudo udevadm control --reload
+
+The first line creates a file that recognizes all CMSIS-DAP adapters and tells UDEV to give users full access to it.  The second causes `udev` to load this new rule.  Note that you will need to unplug and re-plug in your device the first time you create this file, to allow udev to make the device node properly.
+
+Once CMSIS-DAP permissions are set up properly, then select the board "Raspberry Pi Pico (pico-debug)" in the Tools menu.
+
+When first connecting the USB port to your PC, you must copy pico-debug-gimmecache.uf2 to the Pi Pico to load pico-debug into RAM; after this, upload as normal.
+
+Debugging with Picoprobe/pico-debug, OpenOCD, and GDB
+-----------------------------------------------------
+The installed tools include a version of OpenOCD (in the pqt-openocd directory) and GDB (in the pqt-gcc directory).  These may be used to run GDB in an interactive window as documented in the Pico Getting Started manuals from the Raspberry Pi Foundation.  For pico-debug, replace the raspberrypi-swd and picoprobe example OpenOCD arguments of "-f interface/raspberrypi-swd.cfg -f target/rp2040.cfg" or "-f interface/picoprobe.cfg -f target/rp2040.cfg" respectively in the Pico Getting Started manual with "-f board/pico-debug.cfg".

docs/install.rst

@@ -24,7 +24,7 @@
 MEMORY
 {
     FLASH(rx) : ORIGIN = 0x10000000, LENGTH = __FLASH_LENGTH__
-    RAM(rwx) : ORIGIN =  0x20000000, LENGTH = 256k
+    RAM(rwx) : ORIGIN =  0x20000000, LENGTH = __RAM_LENGTH__
     SCRATCH_X(rwx) : ORIGIN = 0x20040000, LENGTH = 4k
     SCRATCH_Y(rwx) : ORIGIN = 0x20041000, LENGTH = 4k
 }

lib/memmap_default.ld

@@ -107,7 +107,7 @@ archive_file_path={build.path}/{archive_file}
 recipe.ar.pattern="{compiler.path}{compiler.ar.cmd}" {compiler.ar.flags} {compiler.ar.extra_flags} "{archive_file_path}" "{object_file}"
 
 ## Generate the linker map with specific flash sizes/locations
-recipe.hooks.linking.prelink.1.pattern="{runtime.tools.pqt-python3.path}/python3" "{runtime.platform.path}/tools/simplesub.py" --input "{runtime.platform.path}/lib/memmap_default.ld" --out "{build.path}/memmap_default.ld" --sub __FLASH_LENGTH__ {build.flash_length} --sub __EEPROM_START__ {build.eeprom_start} --sub __FS_START__ {build.fs_start} --sub __FS_END__ {build.fs_end}
+recipe.hooks.linking.prelink.1.pattern="{runtime.tools.pqt-python3.path}/python3" "{runtime.platform.path}/tools/simplesub.py" --input "{runtime.platform.path}/lib/memmap_default.ld" --out "{build.path}/memmap_default.ld" --sub __FLASH_LENGTH__ {build.flash_length} --sub __EEPROM_START__ {build.eeprom_start} --sub __FS_START__ {build.fs_start} --sub __FS_END__ {build.fs_end} --sub __RAM_LENGTH__ {build.ram_length}
 
 ## Compile the boot stage 2 blob
 recipe.hooks.linking.prelink.2.pattern="{compiler.path}{compiler.S.cmd}" {compiler.c.elf.flags} {compiler.c.elf.extra_flags} -c "{runtime.platform.path}/boot2/{build.boot2}.S" "-I{runtime.platform.path}/pico-sdk/src/rp2040/hardware_regs/include/" "-I{runtime.platform.path}/pico-sdk/src/common/pico_binary_info/include" -o "{build.path}/boot2.o"
@@ -147,3 +147,9 @@ tools.picoprobe.upload.protocol=picoprobe
 tools.picoprobe.upload.params.verbose=
 tools.picoprobe.upload.params.quiet=
 tools.picoprobe.upload.pattern="{cmd}/bin/openocd" -f "interface/picoprobe.cfg" -f "target/rp2040.cfg" -s "{cmd}/share/openocd/scripts" -c "program {build.path}/{build.project_name}.elf verify reset exit"
+
+tools.picodebug.cmd={runtime.platform.path}/system/openocd
+tools.picodebug.upload.protocol=pico-debug
+tools.picodebug.upload.params.verbose=
+tools.picodebug.upload.params.quiet=
+tools.picodebug.upload.pattern="{cmd}/bin/openocd" -f "board/pico-debug.cfg" -s "{cmd}/share/openocd/scripts" -c "program {build.path}/{build.project_name}.elf verify reset exit"

platform.txt

@@ -50,22 +50,26 @@ def BuildUSBStack(name):
     print("%s.menu.usbstack.tinyusb=Adafruit TinyUSB" % (name))
     print('%s.menu.usbstack.tinyusb.build.usbstack_flags=-DUSE_TINYUSB "-I{runtime.platform.path}/libraries/Adafruit_TinyUSB_Arduino/src/arduino"' % (name))
 
-def BuildHeader(name, vendor_name, product_name, pidtouse, vid, pid, boarddefine, variant, uploadtool, flashsize, boot2):
+def BuildWithoutUSBStack(name):
+    print("%s.menu.usbstack.nousb=No USB" % (name))
+    print('%s.menu.usbstack.nousb.build.usbstack_flags="-DNO_USB -DDISABLE_USB_SERIAL -I{runtime.platform.path}/tools/libpico"' % (name))
+
+def BuildHeader(name, vendor_name, product_name, vidtouse, pidtouse, vid, pid, boarddefine, variant, uploadtool, flashsize, ramsize, boot2):
     prettyname = vendor_name + " " + product_name
     print()
     print("# -----------------------------------")
     print("# %s" % (prettyname))
     print("# -----------------------------------")
     print("%s.name=%s" % (name, prettyname))
-    print("%s.vid.0=%s" % (name, vid))
+    print("%s.vid.0=%s" % (name, vidtouse))
     print("%s.pid.0=%s" % (name, pidtouse))
     print("%s.build.usbpid=-DSERIALUSB_PID=%s" % (name, pid))
     print("%s.build.board=%s" % (name, boarddefine))
     print("%s.build.mcu=cortex-m0plus" % (name))
     print("%s.build.variant=%s" % (name, variant))
     print("%s.upload.tool=%s" % (name, uploadtool))
     print("%s.upload.maximum_size=%d" % (name, flashsize))
-    print("%s.upload.maximum_data_size=262144" % (name))
+    print("%s.upload.maximum_data_size=%d" % (name, ramsize))
     print("%s.upload.wait_for_upload_port=true" % (name))
     print("%s.upload.erase_cmd=" % (name))
     print("%s.serial.disableDTR=false" % (name))
@@ -75,6 +79,7 @@ def BuildHeader(name, vendor_name, product_name, pidtouse, vid, pid, boarddefine
     print("%s.build.core=rp2040" % (name))
     print("%s.build.mcu=rp2040" % (name))
     print("%s.build.ldscript=memmap_default.ld" % (name))
+    print("%s.build.ram_length=%dk" % (name, ramsize / 1024))
     print("%s.build.boot2=%s" % (name, boot2))
     print("%s.build.vid=%s" % (name, vid))
     print("%s.build.pid=%s" % (name, pid))
@@ -92,17 +97,23 @@ def BuildGlobalMenuList():
 
 
 def MakeBoard(name, vendor_name, product_name, vid, pid, boarddefine, flashsizemb, boot2):
-    for a, b, c in [ ["", "", "uf2conv"], ["picoprobe", " (Picoprobe)", "picoprobe"]]:
+    for a, b, c in [ ["", "", "uf2conv"], ["picoprobe", " (Picoprobe)", "picoprobe"], ["picodebug", " (pico-debug)", "picodebug"]]:
         n = name + a
         p = product_name + b
         fssizelist = [ 0, 64 * 1024, 128 * 1024, 256 * 1024, 512 * 1024 ]
         for i in range(1, flashsizemb):
             fssizelist.append(i * 1024 * 1024)
+        vidtouse = vid;
+        ramsizekb = 256;
         if a == "picoprobe":
             pidtouse = '0x0004'
+        elif a == "picodebug":
+            vidtouse = '0x1209'
+            pidtouse = '0x2488'
+            ramsizekb = 240;
         else:
             pidtouse = pid
-        BuildHeader(n, vendor_name, p, pidtouse, vid, pid, boarddefine, name, c, flashsizemb * 1024 * 1024, boot2)
+        BuildHeader(n, vendor_name, p, vidtouse, pidtouse, vid, pid, boarddefine, name, c, flashsizemb * 1024 * 1024, ramsizekb * 1024, boot2)
         if name == "generic":
             BuildFlashMenu(n, 2*1024*1024, [0, 1*1024*1024])
             BuildFlashMenu(n, 4*1024*1024, [0, 2*1024*1024])
@@ -113,7 +124,10 @@ def MakeBoard(name, vendor_name, product_name, vid, pid, boarddefine, flashsizem
         BuildFreq(n)
         BuildDebugPort(n)
         BuildDebugLevel(n)
-        BuildUSBStack(n)
+        if a == "picodebug":
+            BuildWithoutUSBStack(n)
+        else:
+            BuildUSBStack(n)
         if name == "generic":
             BuildBoot(n)