Add USB SuperSpeed (USB 3.2) device support with WCH CH569 and CH32H417 ports

.claude/skills/usbtest/SKILL.md

@@ -98,6 +98,10 @@ whose recovery flasher is not convoy-safe or has no probe reset are refused.
   without `--recover-board` leaves a HUNG device wedged. `wedged` is also set with no HUNG case
   when the serial matches two devices or cannot be read after a case; stderr names which
   (`reported wedged: ...`).
+- **Never hand-write a bare `echo "vid pid" > usbtest/new_id`.** A dynamic id without the 5-field
+  ref form (`vid pid 0 0525 a4a0`, copying Gadget Zero's driver_info) probes with driver_info=NULL:
+  a kernel NULL-deref Oops, a D-state testusb and a forced reboot. Binding a foreign device (a
+  vendor demo for an A/B) uses the same 5-field form.
 
 ## Failed case
 
@@ -126,6 +130,7 @@ under a timer.
 | FAIL "did not run" | testusb never reached the ioctl (open or usage error): read the case's captured `stderr`   |
 | HUNG               | testusb not reaped 35 s after SIGKILL                                                      |
 | BUDGET             | never dispatched: the battery stopped first; its detail names why                          |
+| SKIP               | never dispatched: the device's bcdDevice quirk bits declare it unsupported at this speed   |
 
 | Failing case(s)    | Exercises                                  | First suspect                                                              |
 |--------------------|--------------------------------------------|----------------------------------------------------------------------------|
@@ -140,7 +145,11 @@ under a timer.
 
 Case 29 (`test_toggle_sync`: clear halt, write, clear halt, write) is the most common DCD bug here:
 reset the toggle to DATA0 **and** keep the pending transfer armed (fixed that way in rp2040
-ad7acc849, fsdev 046463687, ch32_usbhs d63a45509).
+ad7acc849, fsdev 046463687, ch32_usbhs 99044894a).
+
+WCH SuperSpeed silicon fails cases 13 (CH569, CH32H417) and 14, 21 (CH569) for good and quirk-skips them
+(`QUIRK_SKIPS`); the errata are in `docs/reference/device_issues.rst`. The 14/21 strike rate depends on the host: an
+onboard AMD xHCI ran clean and once retired the quirk by mistake, so run it on a uPD720201 before removing a quirk.
 
 Escalate in order:
 1. The case's `detail` and captured `dmesg` in the JSON verdict (`TEST n` lines bracket each case).
@@ -150,6 +159,15 @@ Escalate in order:
 3. Target-side evidence: `target-debug` (`esp-target-debug` on Espressif) on the failing case.
 4. The reference manual and errata (`read-doc`) before changing any register-level code: DCD
    comments have been wrong about what the hardware can do.
+5. **Prove or refute "it's the silicon" with a vendor-stack A/B.** Build the vendor's reference
+   firmware, patch in the gadget-zero 0x5b/0x5c control store (mirror its existing control-OUT
+   request, ~10 lines), flash it to the same board and port, bind usbtest to the foreign VID:PID
+   (5-field form) and run the failing case. The same failure is an erratum (document and
+   quirk-skip it); a clean run puts the difference in our DCD. Nothing else closes the debate.
+6. **A flake may be value-gated, not random:** sweep one parameter at a time.
+   `L=513; testusb -A <node> -D <node> -t 14 -c 4000 -s "$L" -v "$((L-1))"` alternates lengths 1
+   and L; sweeping L exposed a wLength-mod-4 gate that the stock `-s 512 -v 61` (one hot length in its
+   9-cycle) diluted into "0.3% random".
 
 ## Isochronous rules
 
@@ -188,6 +206,11 @@ From USB 2.0 §8.5.5 (Calibre book 775, p. 229-230):
    to chase, not noise.
 5. Add the board to the HIL roster (`test/hil/*.json`) when roster edits are in the task's scope;
    otherwise hand it to the owner. Automated PR repair never touches the rosters.
+6. **A silicon-impossible case gets a quirk flag, not a dodge.** Once proven an erratum (vendor-stack
+   A/B above), advertise it in bcdDevice bits 4-7 (`USBTEST_QUIRKS` in `src/usb_descriptors.h`;
+   skip table `QUIRK_SKIPS` in `usbtest.py`, keyed by link speed) so the battery skips it visibly
+   ("27/30 passed, 3 skipped") instead of flaking. Never mask an erratum by tuning parameters or
+   dropping the board. Prove an erratum on more than one host before removing its quirk.
 
 ## Wrong profile
 

.github/ci-pinned-boards.json

@@ -11,6 +11,7 @@
     { "board": "feather_nrf52840_express", "note": "nrf5x FS" },
     { "board": "fomu", "note": "eptri FS" },
     { "board": "frdm_k64f", "note": "ci_fs FS, host" },
+    { "board": "hydrausb3_v1", "note": "ch56x usb30 SS + usbhs HS fallback" },
     { "board": "lpcxpresso11u68", "note": "ip3511 FS" },
     { "board": "lpcxpresso55s69", "note": "ip3511 HS, ohci host" },
     { "board": "max32666fthr", "note": "musb HS" },
@@ -19,6 +20,7 @@
     { "board": "mimxrt1064_evk", "note": "ci_hs HS, ehci host" },
     { "board": "mm900evxb", "note": "ft9xx HS" },
     { "board": "msp_exp430f5529lp", "note": "msp430x5xx FS" },
+    { "board": "nanoch32h417", "note": "ch32h417 usb30 SS + usbhs HS" },
     { "board": "nanoch32v203", "note": "ch32 usbfs + fsdev FS, host" },
     { "board": "ra6m5_ek", "note": "rusb2 HS, host" },
     { "board": "raspberry_pi_pico", "note": "rp2040 FS, host" },

.github/scripts/ci_set_matrix.py

@@ -41,6 +41,8 @@
     "ch32v30x": ["riscv-gcc"],
     "ch32v4x7": ["riscv-gcc"],
     "ch32x035": ["riscv-gcc"],
+    "ch32h417": ["riscv-gcc"],
+    "ch569": ["riscv-gcc"],
     "ch583": ["riscv-gcc"],
     "cxd56": ["arm-gcc"],
     "da1469x": ["arm-gcc"],
@@ -108,6 +110,17 @@
     "xmc4000": ["arm-gcc"],
 }
 
+# family: extra build.py legs on the family's toolchains, emitted after it in every unpinned
+# matrix (full or scoped) the family is in.
+# The WCH SuperSpeed families default to SPEED=super, which compiles their USB2 dcd out
+# entirely (dcd_ch32h417_usbhs.c) or all but its dcd_* entry points (dcd_ch56x_usbhs.c).
+# One SPEED=high build per family type-checks that half; --build-name keeps its metrics.json
+# out of the default build's artifact path.
+family_variants = {
+    "ch32h417": ["-bnanoch32h417 -DSPEED=high --build-name nanoch32h417-hs"],
+    "ch569": ["-bhydrausb3_v1 -DSPEED=high --build-name hydrausb3_v1-hs"],
+}
+
 
 REPO = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 # the toolchains cmake-required builds a changed board with: every one a GitHub runner
@@ -180,10 +193,16 @@ def required_json(select):
 
 def example_map_json(select):
     """{family: [examples]} for build_util.yml/config2.yml's -e filter: a family that
-    builds every example has no entry, and an unusable selection filters nothing."""
+    builds every example has no entry, and an unusable selection filters nothing.
+    The consumers look a leg up by its whole matrix arg, so a family_variants leg is
+    keyed too, with its family's list."""
     select = usable(select)
     fams = select['build']['families'] if select else {}
-    print(json.dumps({f: v['examples'] for f, v in fams.items() if v['examples'] != 'all'}))
+    out = {}
+    for f, v in fams.items():
+        if v['examples'] != 'all':
+            out.update((leg, v['examples']) for leg in (f, *family_variants.get(f, ())))
+    print(json.dumps(out))
 
 
 def leg_key(arg):
@@ -251,6 +270,11 @@ def set_matrix_json(select=None, pinned=False):
         # family selected", not a selection to widen back to the full matrix.
         keep = pinned_families()
         matrix = {tc: [f for f in fams if f in keep] for tc, fams in matrix.items()}
+    else:
+        # compile checks only: the pinned (size) leg leaves them out, as membrowse_json's
+        # universe has no identical upload for a variant board
+        matrix = {tc: [leg for f in fams for leg in (f, *family_variants.get(f, ()))]
+                  for tc, fams in matrix.items()}
     print(json.dumps(matrix))
 
 

docs/porting.rst

@@ -240,6 +240,51 @@ The arguments are:
 
 Stalling is one way an endpoint can indicate failure such as when an unsupported command is transmitted. The pair of ``dcd_edpt_stall()``, ``dcd_edpt_clear_stall()`` help manage the stall state of all endpoints.
 
+SuperSpeed
+----------
+
+To the stack, SuperSpeed is one more speed. The DCD hides the link layer (LTSSM, LMP, warm and hot reset) and
+reports ordinary events; usbd only needs the operating speed to size EP0 transactions and to pick descriptors. The
+reference drivers are ``src/portable/wch/wch_ss1`` (CH569, with its own USB2 driver ``dcd_ch56x_usbhs.c``) and
+``src/portable/wch/wch_ss2`` (CH32H417, whose USB3 driver owns ``dcd_*`` and drives ``wch_hs2`` for the USB2
+fallback).
+
+What the port provides:
+
+* ``CFG_TUSB_SUPER_SPEED_DEFAULT 1`` in its ``tusb_mcu.h`` block. ``TUD_OPT_SUPER_SPEED`` follows it while
+  ``CFG_TUD_MAX_SPEED`` is left at default; ``tusb_config.h`` may override it with ``CFG_TUSB_SUPER_SPEED``.
+* ``TUP_DCD_SS_BULK_BURST_PACKETS``, the bulk burst (1..16 packets) the endpoint engine handles. Examples encode
+  ``bMaxBurst`` as ``TUD_OPT_SS_BULK_BURST_PACKETS - 1``.
+* The actual link speed in every ``dcd_event_bus_reset()``: ``TUSB_SPEED_SUPER`` once the link is up, the USB2 speed
+  after a fallback. Where in the link bring-up to report it is the controller's choice.
+
+A USB2 fallback on a second controller stays behind the same rhport: the USB3 driver owns ``dcd_*`` and calls the USB2
+driver under a private prefix. A timer bounds SuperSpeed training and then brings USB2 up, and usbd re-initializes on
+its bus reset. ``dcd_int_enable()`` runs on every task-loop queue operation without an RTOS, so it must honour the
+fallback state and any vector the driver masked itself, instead of unmasking every vector.
+
+What the stack already does:
+
+* EP0 max packet size is fixed at 512 (USB 3.2 §9.6.1): ``CFG_TUD_ENDPOINT0_SIZE`` defaults to it, and a SuperSpeed
+  build rejects any other value.
+* With ``CFG_TUSB_DEBUG``, ``tu_edpt_validate()`` requires a bulk max packet size of exactly 1024 (512 at high
+  speed); without it the check only rejects a zero size, so a release build accepts a wrong one.
+* The class drivers that support SuperSpeed skip the endpoint companion that follows every endpoint descriptor
+  (``usbd_skip_ss_ep_companion()``) and include its bytes in the length ``open()`` returns; a class driver gaining
+  SuperSpeed support must do both.
+* SET_SEL, SET_ISOCH_DELAY, U1/U2 enable and FUNCTION_SUSPEND are handled in ``usbd.c``.
+
+Examples switch descriptors on ``tud_speed_get()``; ``examples/device/cdc_msc`` is the pattern: ``desc_device_ss``
+(bcdUSB 0x0320, ``bMaxPacketSize0`` 9, an exponent), a USB2 device descriptor reporting bcdUSB 0x0210 in SuperSpeed
+builds (USB 3.2 §9.6.1), a configuration built from the ``TUD_*_SS_DESCRIPTOR`` templates, and a BOS with the USB 2.0
+extension and SuperSpeed capabilities (``TUD_BOS_SUPERSPEED_SPEEDS``).
+
+To verify: build the examples for both the SuperSpeed and high-speed configuration; check that ``wTotalLength`` matches
+the SuperSpeed configuration array (a wrong length builds and then enumerates wrong); confirm a 0-byte code-size delta on
+a non-SuperSpeed board; run usbtest at 5 Gbps, and data integrity before throughput; repeat replug and suspend/resume
+cycles, and the USB2 fallback on a USB2-only port. ``uhubctl -l <hub> -p <port>`` shows the link state of a hub port:
+``Rx.Detect`` is receiver detection or reset, ``Polling`` is link training, ``U0`` is trained.
+
 Validate with usbtest
 ---------------------
 

docs/reference/boards.rst

@@ -382,6 +382,8 @@ WCH
 Board                      Name                           Family    URL                                                                    Note
 =========================  =============================  ========  =====================================================================  ======
 ch32f205r-r0               CH32F205r-r0                   ch32f20x  https://github.com/openwch/ch32f20x
+ch32h417_r0                CH32H417QEU6-R0 EVT            ch32h417  https://www.wch-ic.com/products/CH32H417.html
+nanoch32h417               nanoCH32H417                   ch32h417  https://github.com/wuxx/nanoCH32H417
 ch32v103c_bluepill         CH32V103C8T6-Bluepill          ch32v10x  https://stm32-base.org/boards/STM32F103C8T6-Blue-Pill
 ch32v103r_r1_1v0           CH32V103R-R1-1v1               ch32v10x  https://github.com/openwch/ch32v103/tree/main/SCHPCB/CH32V103R-R1-1v1
 ch32v203c_r0_1v0           CH32V203C-R0-1v0               ch32v20x  https://github.com/openwch/ch32v20x/tree/main/SCHPCB/CH32V203C-R0
@@ -391,6 +393,7 @@ ch32v307v_r1_1v0           CH32V307V-R1-1v0               ch32v30x  https://gith
 nanoch32v305               nanoCH32V305                   ch32v30x  https://github.com/wuxx/nanoCH32V305
 ch32v407_r0                CH32V407VET6-EVT-R0            ch32v4x7  https://www.wch-ic.com/products/CH32V407.html
 weact_ch32x035_core_board  WeAct CH32X035 Core Board      ch32x035  https://github.com/WeActStudio/WeActStudio.CH32X035CoreBoard
+hydrausb3_v1               HydraUSB3 v1                   ch569     https://github.com/hydrausb3/hydrausb3_hw
 ch582m_evt                 CH582M-EVT evaluation board    ch583     https://www.wch-ic.com/products/CH582.html
 yd-ch582m                  yd-ch582m from vcc-gnd studio  ch583     http://vcc-gnd.com/
 =========================  =============================  ========  =====================================================================  ======

docs/reference/dependencies.rst

@@ -91,11 +91,13 @@ hw/mcu/st/stm32wbaxx_hal_driver           https://github.com/STMicroelectronics/
 hw/mcu/st/stm32wbxx_hal_driver            https://github.com/STMicroelectronics/stm32wbxx_hal_driver.git    d60dd46996876506f1d2e9abd6b1cc110c8004cd  stm32wb
 hw/mcu/ti                                 https://github.com/hathach/ti_driver.git                          083944907e7d08fcb1f614b47598ce45935b8da1  msp430 msp432e4 tm4c
 hw/mcu/wch/ch32f20x                       https://github.com/openwch/ch32f20x.git                           77c4095087e5ed2c548ec9058e655d0b8757663b  ch32f20x
+hw/mcu/wch/ch32h417                       https://github.com/openwch/ch32h417.git                           a0a56fa830b860297a64a72315a731b71c841329  ch32h417
 hw/mcu/wch/ch32v103                       https://github.com/openwch/ch32v103.git                           ff367d8fec5c9f40029355b2806cd059d9508e4e  ch32v10x
 hw/mcu/wch/ch32v20x                       https://github.com/openwch/ch32v20x.git                           b375bbbc7dfe8642d6fb7c17e6d3207ee1c3c9c1  ch32v20x
 hw/mcu/wch/ch32v307                       https://github.com/openwch/ch32v307.git                           8b3699d9e4eafc3102e382b74266a1165a2bb584  ch32v30x
 hw/mcu/wch/ch32v407_ch32v467              https://github.com/openwch/ch32v407_ch32v467.git                  17394a1f9aa484c9b2ca0c9fdfe5730ec31c06c7  ch32v4x7
 hw/mcu/wch/ch32x035                       https://github.com/openwch/ch32x035.git                           c6253942b29ff2a3f5e2829182a874afffa45881  ch32x035
+hw/mcu/wch/ch569                          https://github.com/openwch/ch569.git                              0424d2968d1f9802e91b9cc4b72bad75f82b342b  ch569
 hw/mcu/wch/ch583                          https://github.com/openwch/ch583.git                              bd508ad7ceed48377619837051412a651952857f  ch583
 lib/CMSIS_5                               https://github.com/ARM-software/CMSIS_5.git                       2b7495b8535bdcb306dac29b9ded4cfb679d7e5c  kinetis_k kinetis_kl lpc54 rw61x mm32 msp432e4 nrf samd2x_l2x lpc11 lpc13 lpc15 lpc17 lpc18 lpc40 lpc43 stm32c0 stm32f0 stm32f1 stm32f2 stm32f3 stm32f4 stm32f7 stm32g0 stm32g4 stm32h5 stm32h7 stm32h7rs stm32l0 stm32l1 stm32l4 stm32l5 stm32u0 stm32u5 stm32wb stm32wba sam3x samd11 samd21 samd2x_l2x samd51 samd5x_e5x same5x same7x samg tm4c efm32
 lib/CMSIS_6                               https://github.com/ARM-software/CMSIS_6.git                       6f0a58d01aa9bd2feba212097f9afe7acd991d52  imxrt kinetis_k32l ra stm32n6 lpc51 lpc55 mcx stm32c5

docs/reference/device_issues.rst

@@ -65,6 +65,28 @@ USB.5: An isochronous IN endpoint sending a 1024-byte maximum-packet-size packet
 interrupt and its command/status entry is not updated. Workaround: cap the isochronous IN maximum
 packet size at 1023 bytes in the descriptor.
 
+WCH CH569/CH32H417 USBSS
+------------------------
+**Severity: Low**
+
+Reference: observed during `PR #3779`_ with the Linux ``usbtest`` battery at 5 Gbps on a Renesas uPD720201 host. The
+``examples/device/usbtest`` firmware declares both through its bcdDevice quirk bits, and ``test/hil/usbtest.py`` skips
+the affected cases of its tier battery at 5 Gbps instead of failing them. Cases chosen with ``--tests``, and ``testusb``
+run directly, still run them.
+
+.. _PR #3779: https://github.com/hathach/tinyusb/pull/3779
+
+**1. A halted endpoint answers a single STALL** (CH569 and CH32H417)
+
+After ``dcd_edpt_stall()`` a SuperSpeed data endpoint answers the first transaction with a STALL TP and then nothing. A
+host that retries before clearing the halt sees a transaction error instead of a second STALL. Affects usbtest case 13
+(quirk 0x20).
+
+**2. EP0 OUT data stages with wLength % 4 == 1 are intermittently dropped** (CH569)
+
+The host sees a transaction error and the full residual. The rate depends on the host: a uPD720201 failed most runs of
+usbtest cases 14 and 21 (quirk 0x10), an AMD xHCI ran clean.
+
 WCH CH32F20x/CH32V20x/CH32V30x
 ---------------------------------
 **Severity: High**

docs/reference/glossary.rst

@@ -74,7 +74,7 @@ Glossary
       USB protocol mechanism where an endpoint responds with a STALL handshake to indicate an error condition or unsupported request. Used for error handling, not flow control.
 
    Super Speed
-      USB 3.0 speed mode operating at 5 Gbps. Not supported by TinyUSB.
+      USB 3.0 speed mode operating at 5 Gbps. Supported in device mode on WCH CH569 and CH32H417.
 
    tud
       TinyUSB Device. Function prefix for all device stack APIs (e.g., ``tud_task()``, ``tud_cdc_write()``).

docs/reference/usb_concepts.rst

@@ -58,12 +58,12 @@ Used for device configuration and control commands.
 **Characteristics**:
 - Bidirectional (uses both IN and OUT)
 - Guaranteed delivery with error detection
-- Limited data size (8-64 bytes per packet)
+- Limited data size per packet: 8 bytes at Low Speed, 8, 16, 32 or 64 at Full Speed, 64 at High Speed, 512 at SuperSpeed
 - All devices must support control transfers on endpoint 0
 
 **Usage**: Device enumeration, configuration changes, class-specific commands
 
-**TinyUSB Context**: Handled automatically by the core stack for standard requests; class drivers handle class-specific requests. Endpoint 0 is managed by ``src/device/usbd.c`` and ``src/host/usbh.c``. Configure buffer size with ``CFG_TUD_ENDPOINT0_SIZE`` (typically 64 bytes).
+**TinyUSB Context**: Handled automatically by the core stack for standard requests; class drivers handle class-specific requests. Endpoint 0 is managed by ``src/device/usbd.c`` and ``src/host/usbh.c``. Configure buffer size with ``CFG_TUD_ENDPOINT0_SIZE`` (defaults to 64 bytes, 512 for a SuperSpeed build).
 
 Bulk Transfers
 --------------
@@ -252,7 +252,7 @@ USB supports multiple speed modes:
 
 **Super Speed (5 Gbps)**:
 - USB 3.0 and later
-- Not supported by TinyUSB
+- Supported in device mode on WCH CH569 and CH32H417 (see the SuperSpeed section of :doc:`../porting`)
 
 **TinyUSB Speed Support**: Most TinyUSB ports support Full Speed and High Speed. Speed is typically auto-detected by hardware. Configure speed requirements in board configuration (``hw/bsp/FAMILY/boards/BOARD/board.mk``) and ensure your MCU supports the desired speed.
 

examples/device/audio_4_channel_mic/skip.txt

@@ -5,3 +5,5 @@ family:espressif
 mcu:CH583
 mcu:CH32X035
 mcu:APM32F103
+mcu:CH569
+mcu:CH32H417

examples/device/audio_4_channel_mic_freertos/skip.txt

@@ -25,3 +25,5 @@ family:hpmicro
 # same7x has no FreeRTOSConfig.h wired up in the tree (hw/bsp/same7x/FreeRTOSConfig/
 # does not exist): fatal error: FreeRTOSConfig.h: No such file or directory
 family:same7x
+mcu:CH569
+mcu:CH32H417

examples/device/audio_test/skip.txt

@@ -3,3 +3,5 @@ mcu:SAMG
 family:espressif
 mcu:CH583
 mcu:CH32X035
+mcu:CH569
+mcu:CH32H417

examples/device/audio_test_freertos/skip.txt

@@ -22,3 +22,5 @@ family:hpmicro
 # same7x has no FreeRTOSConfig.h wired up in the tree (hw/bsp/same7x/FreeRTOSConfig/
 # does not exist): fatal error: FreeRTOSConfig.h: No such file or directory
 family:same7x
+mcu:CH569
+mcu:CH32H417

examples/device/audio_test_multi_rate/skip.txt

@@ -3,4 +3,6 @@ mcu:SAMG
 family:espressif
 mcu:CH583
 mcu:CH32X035
+mcu:CH569
+mcu:CH32H417
 board:spresense