Add library for reset interface

docs/index.h

@@ -128,5 +128,6 @@
  * \cond boot_picoboot_headers \defgroup boot_picoboot_headers boot_picoboot_headers \endcond
  * \cond boot_uf2_headers \defgroup boot_uf2_headers boot_uf2_headers \endcond
  * \cond pico_usb_reset_interface_headers \defgroup pico_usb_reset_interface_headers pico_usb_reset_interface_headers \endcond
+ * \cond pico_usb_reset_interface \defgroup pico_usb_reset_interface pico_usb_reset_interface \endcond
  * @}
 */

src/cmake/rp2_common.cmake

@@ -124,6 +124,7 @@ if (NOT PICO_BARE_METAL)
     endif()
     pico_add_subdirectory(rp2_common/tinyusb)
     pico_add_subdirectory(rp2_common/pico_stdio_usb)
+    pico_add_subdirectory(rp2_common/pico_usb_reset_interface)
     pico_add_subdirectory(rp2_common/pico_i2c_slave)
 
     # networking libraries - note dependency order is important

src/common/pico_usb_reset_interface_headers/BUILD.bazel

@@ -4,6 +4,11 @@ package(default_visibility = ["//visibility:public"])
 
 cc_library(
     name = "pico_usb_reset_interface_headers",
-    hdrs = ["include/pico/usb_reset_interface.h"],
+    hdrs = [
+        "include/pico/usb_reset_interface.h",
+        "include/pico/usb_reset_interface_config.h",
+        "include/pico/usb_reset_interface_device.h",
+        "include/pico/usb_reset_interface_tusb.h",
+    ],
     includes = ["include"],
 )

src/common/pico_usb_reset_interface_headers/CMakeLists.txt

@@ -1,6 +1,4 @@
 # don't use pico_add_library here as picotool includes it directly
 add_library(pico_usb_reset_interface_headers INTERFACE)
-add_library(pico_usb_reset_interface INTERFACE)
-target_link_libraries(pico_usb_reset_interface INTERFACE pico_usb_reset_interface_headers)
 
 target_include_directories(pico_usb_reset_interface_headers SYSTEM INTERFACE ${CMAKE_CURRENT_LIST_DIR}/include)

src/common/pico_usb_reset_interface_headers/include/pico/usb_reset_interface_config.h

@@ -0,0 +1,132 @@
+/*
+ * Copyright (c) 2025 Raspberry Pi (Trading) Ltd.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef _PICO_USB_RESET_INTERFACE_CONFIG_H
+#define _PICO_USB_RESET_INTERFACE_CONFIG_H
+
+// PICO_CONFIG: PICO_USB_RESET_BOOTSEL_ACTIVITY_LED, Optionally define a pin to use as bootloader activity LED when BOOTSEL mode is entered via USB (either VIA_BAUD_RATE or VIA_VENDOR_INTERFACE), type=int, min=0, max=47 on RP2350B, 29 otherwise, group=pico_usb_reset_interface
+#ifdef PICO_STDIO_USB_RESET_BOOTSEL_ACTIVITY_LED // backwards compatibility with SDK <= 2.2.0
+#define PICO_USB_RESET_BOOTSEL_ACTIVITY_LED PICO_STDIO_USB_RESET_BOOTSEL_ACTIVITY_LED
+#endif // default is undefined
+
+// PICO_CONFIG: PICO_USB_RESET_BOOTSEL_ACTIVITY_LED_ACTIVE_LOW, Whether pin to use as bootloader activity LED when BOOTSEL mode is entered via USB (either VIA_BAUD_RATE or VIA_VENDOR_INTERFACE) is active low, type=bool, default=0, group=pico_usb_reset_interface
+#ifndef PICO_USB_RESET_BOOTSEL_ACTIVITY_LED_ACTIVE_LOW
+#ifdef PICO_STDIO_USB_RESET_BOOTSEL_ACTIVITY_LED_ACTIVE_LOW // backwards compatibility with SDK <= 2.2.0
+#define PICO_USB_RESET_BOOTSEL_ACTIVITY_LED_ACTIVE_LOW PICO_STDIO_USB_RESET_BOOTSEL_ACTIVITY_LED_ACTIVE_LOW
+#else
+#define PICO_USB_RESET_BOOTSEL_ACTIVITY_LED_ACTIVE_LOW 0
+#endif
+#endif
+
+// PICO_CONFIG: PICO_USB_RESET_BOOTSEL_FIXED_ACTIVITY_LED, Whether the pin specified by PICO_USB_RESET_BOOTSEL_ACTIVITY_LED is fixed or can be modified by picotool over the VENDOR USB interface, type=bool, default=0, group=pico_usb_reset_interface
+#ifndef PICO_USB_RESET_BOOTSEL_FIXED_ACTIVITY_LED
+#ifdef PICO_STDIO_USB_RESET_BOOTSEL_FIXED_ACTIVITY_LED // backwards compatibility with SDK <= 2.2.0
+#define PICO_USB_RESET_BOOTSEL_FIXED_ACTIVITY_LED PICO_STDIO_USB_RESET_BOOTSEL_FIXED_ACTIVITY_LED
+#else
+#define PICO_USB_RESET_BOOTSEL_FIXED_ACTIVITY_LED 0
+#endif
+#endif
+
+// Any modes disabled here can't be re-enabled by picotool via VENDOR_INTERFACE.
+// PICO_CONFIG: PICO_USB_RESET_BOOTSEL_INTERFACE_DISABLE_MASK, Optionally disable either the mass storage interface (bit 0) or the PICOBOOT interface (bit 1) when entering BOOTSEL mode via USB (either VIA_BAUD_RATE or VIA_VENDOR_INTERFACE), type=int, min=0, max=3, default=0, group=pico_usb_reset_interface
+#ifndef PICO_USB_RESET_BOOTSEL_INTERFACE_DISABLE_MASK
+#ifdef PICO_STDIO_USB_RESET_BOOTSEL_INTERFACE_DISABLE_MASK // backwards compatibility with SDK <= 2.2.0
+#define PICO_USB_RESET_BOOTSEL_INTERFACE_DISABLE_MASK PICO_STDIO_USB_RESET_BOOTSEL_INTERFACE_DISABLE_MASK
+#else
+#define PICO_USB_RESET_BOOTSEL_INTERFACE_DISABLE_MASK 0u
+#endif
+#endif
+
+// PICO_CONFIG: PICO_ENABLE_USB_RESET_VIA_BAUD_RATE, Enable/disable resetting into BOOTSEL mode if the host sets the baud rate to a magic value (PICO_USB_RESET_MAGIC_BAUD_RATE), type=bool, default=1 if application is not using TinyUSB directly, group=pico_usb_reset_interface
+#ifndef PICO_ENABLE_USB_RESET_VIA_BAUD_RATE
+#ifdef PICO_STDIO_USB_ENABLE_RESET_VIA_BAUD_RATE // backwards compatibility with SDK <= 2.2.0
+#define PICO_ENABLE_USB_RESET_VIA_BAUD_RATE PICO_STDIO_USB_ENABLE_RESET_VIA_BAUD_RATE
+#elif !LIB_TINYUSB_HOST && !LIB_TINYUSB_DEVICE
+#define PICO_ENABLE_USB_RESET_VIA_BAUD_RATE 1
+#else
+#define PICO_ENABLE_USB_RESET_VIA_BAUD_RATE 0
+#endif
+#endif
+
+// PICO_CONFIG: PICO_USB_RESET_MAGIC_BAUD_RATE, Baud rate that if selected causes a reset into BOOTSEL mode (if PICO_ENABLE_USB_RESET_VIA_BAUD_RATE is set), default=1200, group=pico_usb_reset_interface
+#ifndef PICO_USB_RESET_MAGIC_BAUD_RATE
+#ifdef PICO_STDIO_USB_RESET_MAGIC_BAUD_RATE // backwards compatibility with SDK <= 2.2.0
+#define PICO_USB_RESET_MAGIC_BAUD_RATE PICO_STDIO_USB_RESET_MAGIC_BAUD_RATE
+#else
+#define PICO_USB_RESET_MAGIC_BAUD_RATE 1200
+#endif
+#endif
+
+// PICO_CONFIG: PICO_ENABLE_USB_RESET_VIA_VENDOR_INTERFACE, Enable/disable resetting into BOOTSEL mode via an additional VENDOR USB interface - enables picotool based reset, type=bool, default=1 if application is not using TinyUSB directly, group=pico_usb_reset_interface
+#ifndef PICO_ENABLE_USB_RESET_VIA_VENDOR_INTERFACE
+#ifdef PICO_STDIO_USB_ENABLE_RESET_VIA_VENDOR_INTERFACE // backwards compatibility with SDK <= 2.2.0
+#define PICO_ENABLE_USB_RESET_VIA_VENDOR_INTERFACE PICO_STDIO_USB_ENABLE_RESET_VIA_VENDOR_INTERFACE
+#elif !LIB_TINYUSB_HOST && !LIB_TINYUSB_DEVICE
+#define PICO_ENABLE_USB_RESET_VIA_VENDOR_INTERFACE 1
+#else
+#define PICO_ENABLE_USB_RESET_VIA_VENDOR_INTERFACE 0
+#endif
+#endif
+
+// PICO_CONFIG: PICO_USB_RESET_INCLUDE_DEFAULT_APP_DRIVER_CB, Set to 0 if your application defines its own usbd_app_driver_get_cb function, type=bool, default=1 when using pico_stdio_usb, 0 otherwise, group=pico_usb_reset_interface
+#ifndef PICO_USB_RESET_INCLUDE_DEFAULT_APP_DRIVER_CB
+#ifdef PICO_STDIO_USB_RESET_INCLUDE_DEFAULT_APP_DRIVER_CB // backwards compatibility with SDK <= 2.2.0
+#define PICO_USB_RESET_INCLUDE_DEFAULT_APP_DRIVER_CB PICO_STDIO_USB_RESET_INCLUDE_DEFAULT_APP_DRIVER_CB
+#else
+#define PICO_USB_RESET_INCLUDE_DEFAULT_APP_DRIVER_CB LIB_PICO_STDIO_USB
+#endif
+#endif
+
+// PICO_CONFIG: PICO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_BOOTSEL, If vendor reset interface is included allow rebooting to BOOTSEL mode, type=bool, default=1, group=pico_usb_reset_interface
+#ifndef PICO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_BOOTSEL
+#ifdef PICO_STDIO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_BOOTSEL // backwards compatibility with SDK <= 2.2.0
+#define PICO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_BOOTSEL PICO_STDIO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_BOOTSEL
+#else
+#define PICO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_BOOTSEL 1
+#endif
+#endif
+
+// PICO_CONFIG: PICO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_FLASH_BOOT, If vendor reset interface is included allow rebooting with regular flash boot, type=bool, default=1, group=pico_usb_reset_interface
+#ifndef PICO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_FLASH_BOOT
+#ifdef PICO_STDIO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_FLASH_BOOT // backwards compatibility with SDK <= 2.2.0
+#define PICO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_FLASH_BOOT PICO_STDIO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_FLASH_BOOT
+#else
+#define PICO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_FLASH_BOOT 1
+#endif
+#endif
+
+// PICO_CONFIG: PICO_USB_RESET_RESET_TO_FLASH_DELAY_MS, Delay in ms before rebooting via regular flash boot, default=100, group=pico_usb_reset_interface
+#ifndef PICO_USB_RESET_RESET_TO_FLASH_DELAY_MS
+#ifdef PICO_STDIO_USB_RESET_RESET_TO_FLASH_DELAY_MS // backwards compatibility with SDK <= 2.2.0
+#define PICO_USB_RESET_RESET_TO_FLASH_DELAY_MS PICO_STDIO_USB_RESET_RESET_TO_FLASH_DELAY_MS
+#else
+#define PICO_USB_RESET_RESET_TO_FLASH_DELAY_MS 100
+#endif
+#endif
+
+// PICO_CONFIG: PICO_USB_RESET_INTERFACE_SUPPORT_MS_OS_20_DESCRIPTOR, If vendor reset interface is included add support for Microsoft OS 2.0 Descriptor, type=bool, default=1 if application is not using TinyUSB directly, 0 otherwise, group=pico_usb_reset_interface
+#ifndef PICO_USB_RESET_INTERFACE_SUPPORT_MS_OS_20_DESCRIPTOR
+#ifdef PICO_STDIO_USB_RESET_INTERFACE_SUPPORT_MS_OS_20_DESCRIPTOR // backwards compatibility with SDK <= 2.2.0
+#define PICO_USB_RESET_INTERFACE_SUPPORT_MS_OS_20_DESCRIPTOR PICO_STDIO_USB_RESET_INTERFACE_SUPPORT_MS_OS_20_DESCRIPTOR
+#elif !LIB_TINYUSB_HOST && !LIB_TINYUSB_DEVICE
+#define PICO_USB_RESET_INTERFACE_SUPPORT_MS_OS_20_DESCRIPTOR 1
+#else
+#define PICO_USB_RESET_INTERFACE_SUPPORT_MS_OS_20_DESCRIPTOR 0
+#endif
+#endif
+
+// PICO_CONFIG: PICO_USB_RESET_INTERFACE_MS_OS_20_DESCRIPTOR_ITF, If vendor reset interface is included this specifies the USB interface number for the reset interface, type=int, default=2 if application is not using TinyUSB directly, undefined otherwise, group=pico_usb_reset_interface
+#ifndef PICO_USB_RESET_INTERFACE_MS_OS_20_DESCRIPTOR_ITF
+#ifdef PICO_STDIO_USB_RESET_INTERFACE_MS_OS_20_DESCRIPTOR_ITF // backwards compatibility with SDK <= 2.2.0
+#define PICO_USB_RESET_INTERFACE_MS_OS_20_DESCRIPTOR_ITF PICO_STDIO_USB_RESET_INTERFACE_MS_OS_20_DESCRIPTOR_ITF
+#elif !LIB_TINYUSB_HOST && !LIB_TINYUSB_DEVICE
+#define PICO_USB_RESET_INTERFACE_MS_OS_20_DESCRIPTOR_ITF 2
+#elif PICO_USB_RESET_INTERFACE_SUPPORT_MS_OS_20_DESCRIPTOR
+#error Must set PICO_USB_RESET_INTERFACE_MS_OS_20_DESCRIPTOR_ITF to the reset interface number when using PICO_USB_RESET_INTERFACE_SUPPORT_MS_OS_20_DESCRIPTOR with custom USB descriptors
+#endif
+#endif
+
+#endif

src/common/pico_usb_reset_interface_headers/include/pico/usb_reset_interface_device.h

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2025 Raspberry Pi (Trading) Ltd.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef _PICO_USB_RESET_INTERFACE_DEVICE_H
+#define _PICO_USB_RESET_INTERFACE_DEVICE_H
+
+/** \file usb_reset_interface_device.h
+ *  \defgroup pico_usb_reset_interface pico_usb_reset_interface
+ *
+ * \brief Functionality to enable the RP-series microcontroller to be reset over the USB interface.
+ *
+ * This library can be used to enable the RP-series microcontroller to be reset over the USB interface.
+ *
+ * This functionality is included by default when using the `pico_stdio_usb` library and not using TinyUSB directly.
+ *
+ * To add this functionality to a project using TinyUSB directly, you need to:
+ * 1. Link the pico_usb_reset_interface library, and include the `pico/usb_reset_interface_device.h` header file where needed.
+ * 2. Define PICO_ENABLE_USB_RESET_VIA_VENDOR_INTERFACE=1
+ * 3. Add `TUD_RPI_RESET_DESCRIPTOR(<ITF_NUM>, <STR_IDX>)` to your USB descriptors (length is `TUD_RPI_RESET_DESC_LEN`)
+ * 4. Check if your project has an existing `usbd_app_driver_get_cb` function:
+ *    - If it does, you need to add the `usb_reset_interface_driver` to the drivers returned
+ *    - If it does not, and you aren't using the `pico_stdio_usb` library, you need to define `PICO_USB_RESET_INCLUDE_DEFAULT_APP_DRIVER_CB=1`
+ * 5. Check if your project has an existing Microsoft OS 2.0 Descriptor:
+ *    - If it does, you need to add the Function Subset header `RPI_RESET_MS_OS_20_DESCRIPTOR(<ITF_NUM>)` to your Microsoft OS 2.0 Descriptor (length is `RPI_RESET_MS_OS_20_DESC_LEN`)
+ *    - If it does not, you need to define `PICO_USB_RESET_INTERFACE_SUPPORT_MS_OS_20_DESCRIPTOR=1` and `PICO_USB_RESET_INTERFACE_MS_OS_20_DESCRIPTOR_ITF=<ITF_NUM>`
+ */
+
+#include "pico/usb_reset_interface.h"
+#include "pico/usb_reset_interface_config.h"
+#include "pico/usb_reset_interface_tusb.h"
+
+#endif

src/common/pico_usb_reset_interface_headers/include/pico/usb_reset_interface_tusb.h

@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) 2025 Raspberry Pi (Trading) Ltd.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef _PICO_USB_RESET_INTERFACE_TUSB_H
+#define _PICO_USB_RESET_INTERFACE_TUSB_H
+
+// Interface descriptor
+#define TUD_RPI_RESET_DESC_LEN  9
+#define TUD_RPI_RESET_DESCRIPTOR(_itfnum, _stridx) \
+  /* Interface */\
+  TUD_RPI_RESET_DESC_LEN, TUSB_DESC_INTERFACE, _itfnum, 0, 0, TUSB_CLASS_VENDOR_SPECIFIC, RESET_INTERFACE_SUBCLASS, RESET_INTERFACE_PROTOCOL, _stridx
+
+
+// Microsoft OS 2.0 Descriptor
+#define RPI_RESET_MS_OS_20_DESC_LEN (0x08 + 0x14 + 0x80)
+#define RPI_RESET_MS_OS_20_DESCRIPTOR(itf_num) \
+  /* Function Subset header: length, type, first interface, reserved, subset length */ \
+  U16_TO_U8S_LE(0x0008), U16_TO_U8S_LE(MS_OS_20_SUBSET_HEADER_FUNCTION), itf_num, 0, U16_TO_U8S_LE(RPI_RESET_MS_OS_20_DESC_LEN), \
+  \
+  /* MS OS 2.0 Compatible ID descriptor: length, type, compatible ID, sub compatible ID */ \
+  U16_TO_U8S_LE(0x0014), U16_TO_U8S_LE(MS_OS_20_FEATURE_COMPATBLE_ID), 'W', 'I', 'N', 'U', 'S', 'B', 0x00, 0x00, \
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, /* sub-compatible */ \
+  \
+  /* MS OS 2.0 Registry property descriptor: length, type */ \
+  U16_TO_U8S_LE(0x0080), U16_TO_U8S_LE(MS_OS_20_FEATURE_REG_PROPERTY), \
+  U16_TO_U8S_LE(0x0001), U16_TO_U8S_LE(0x0028), /* wPropertyDataType, wPropertyNameLength and PropertyName "DeviceInterfaceGUID" in UTF-16 */ \
+  'D', 0x00, 'e', 0x00, 'v', 0x00, 'i', 0x00, 'c', 0x00, 'e', 0x00, 'I', 0x00, 'n', 0x00, 't', 0x00, 'e', 0x00, \
+  'r', 0x00, 'f', 0x00, 'a', 0x00, 'c', 0x00, 'e', 0x00, 'G', 0x00, 'U', 0x00, 'I', 0x00, 'D', 0x00, 0x00, 0x00, \
+  U16_TO_U8S_LE(0x004E), /* wPropertyDataLength */ \
+  /* Vendor-defined Property Data: {bc7398c1-73cd-4cb7-98b8-913a8fca7bf6} */ \
+  '{', 0,     'b', 0,     'c', 0,     '7', 0,     '3', 0,     '9', 0, \
+  '8', 0,     'c', 0,     '1', 0,     '-', 0,     '7', 0,     '3', 0, \
+  'c', 0,     'd', 0,     '-', 0,     '4', 0,     'c', 0,     'b', 0, \
+  '7', 0,     '-', 0,     '9', 0,     '8', 0,     'b', 0,     '8', 0, \
+  '-', 0,     '9', 0,     '1', 0,     '3', 0,     'a', 0,     '8', 0, \
+  'f', 0,     'c', 0,     'a', 0,     '7', 0,     'b', 0,     'f', 0, \
+  '6', 0,     '}', 0,       0, 0
+
+#include "stdint.h"
+#include "device/usbd_pvt.h"
+
+void usb_reset_interface_init(void);
+void usb_reset_interface_reset(uint8_t __unused rhport);
+uint16_t usb_reset_interface_open(uint8_t __unused rhport, tusb_desc_interface_t const *itf_desc, uint16_t max_len);
+bool usb_reset_interface_control_xfer_cb(uint8_t __unused rhport, uint8_t stage, tusb_control_request_t const * request);
+bool usb_reset_interface_xfer_cb(uint8_t __unused rhport, uint8_t __unused ep_addr, xfer_result_t __unused result, uint32_t __unused xferred_bytes);
+
+static usbd_class_driver_t const usb_reset_interface_driver =
+{
+#if CFG_TUSB_DEBUG >= 2
+    .name = "RESET",
+#endif
+    .init             = usb_reset_interface_init,
+    .reset            = usb_reset_interface_reset,
+    .open             = usb_reset_interface_open,
+    .control_xfer_cb  = usb_reset_interface_control_xfer_cb,
+    .xfer_cb          = usb_reset_interface_xfer_cb,
+    .sof              = NULL
+};
+
+#endif

src/rp2_common/pico_stdio_usb/BUILD.bazel

@@ -56,7 +56,6 @@ cc_library(
 cc_library(
     name = "pico_stdio_usb_enabled",
     srcs = [
-        "reset_interface.c",
         "stdio_usb.c",
         "stdio_usb_descriptors.c",
     ],
@@ -72,10 +71,9 @@ cc_library(
         "//src/common/pico_binary_info",
         "//src/common/pico_sync",
         "//src/rp2_common/hardware_irq",
-        "//src/rp2_common/hardware_watchdog",
-        "//src/rp2_common/pico_bootrom",
         "//src/rp2_common/pico_stdio:pico_stdio_headers",
         "//src/rp2_common/pico_unique_id",
+        "//src/rp2_common/pico_usb_reset_interface",
     ],
     # Ensure `stdio_usb_descriptors.c` isn't affected by link order.
     alwayslink = True,

src/rp2_common/pico_stdio_usb/CMakeLists.txt

@@ -4,7 +4,6 @@ if (TARGET tinyusb_device_unmarked)
     target_include_directories(pico_stdio_usb_headers SYSTEM INTERFACE ${CMAKE_CURRENT_LIST_DIR}/include)
 
     target_sources(pico_stdio_usb INTERFACE
-        ${CMAKE_CURRENT_LIST_DIR}/reset_interface.c
         ${CMAKE_CURRENT_LIST_DIR}/stdio_usb.c
         ${CMAKE_CURRENT_LIST_DIR}/stdio_usb_descriptors.c
     )