From da038673936cefdff0e4aacfd2602c665b9f114d Mon Sep 17 00:00:00 2001 From: Zixun LI Date: Wed, 27 May 2026 14:38:53 +0200 Subject: [PATCH 1/6] Add data loss warning to CH32 USBFS/USBHS According to WCH FAE transfer complete interrupt is not queued, later completed EP will overwrite INT_ST and RX_LEN. Which means to guarantee data integrity when multiples EPs are enabled: - USB IRQ must have highest priority - IRQ processing time must be less than ZLP duration (~600ns), which is absurd for a 144MHz CPU (85 cycles) Signed-off-by: Zixun LI --- README.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 04998abaaa..e1e73c3ad0 100644 --- a/README.rst +++ b/README.rst @@ -262,11 +262,11 @@ Supported CPUs +--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ | ValentyUSB | eptri | ✔ | ✖ | ✖ | eptri | | +--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| WCH | CH32F20x | ✔ | | ✔ | ch32_usbhs | | +| WCH | CH32F20x | ⚠ | | ✔ | ch32_usbhs | Data loss possible | | +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | CH32V20x | ✔ | | ✖ | stm32_fsdev/ch32_usbfs | | +| | CH32V20x | ⚠ | | ✖ | stm32_fsdev/ch32_usbfs | Data loss possible | | +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | CH32V305, CH32V307 | ✔ | | ✔ | ch32_usbfs/hs | | +| | CH32V305, CH32V307 | ⚠ | | ✔ | ch32_usbfs/hs | Data loss possible | +--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ Table Legend From 9c316a458cdfcc00f1d349e24f3504337a59daa1 Mon Sep 17 00:00:00 2001 From: HiFiPhile Date: Mon, 1 Jun 2026 22:37:14 +0200 Subject: [PATCH 2/6] add device errata document Signed-off-by: HiFiPhile --- README.rst | 275 +++++++++++++++++++-------------------- docs/index.rst | 1 + docs/troubleshooting.rst | 2 + 3 files changed, 140 insertions(+), 138 deletions(-) diff --git a/README.rst b/README.rst index e1e73c3ad0..c376599ec5 100644 --- a/README.rst +++ b/README.rst @@ -130,144 +130,143 @@ TinyUSB is completely thread-safe by pushing all Interrupt Service Request (ISR) Supported CPUs -------------- - -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| Manufacturer | Family | Device | Host | Highspeed | Driver | Note | -+==============+=============================+========+======+===========+========================+====================+ -| Allwinner | F1C100s/F1C200s | ✔ | | ✔ | sunxi | musb variant | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| Analog | MAX3421E | | ✔ | ✖ | max3421 | via SPI | -| +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | MAX32 650, 666, 690, | ✔ | | ✔ | musb | 1-dir ep | -| | MAX78002 | | | | | | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| Artery AT32 | F403a_407, F413 | ✔ | | | fsdev | 512 USB RAM | -| +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | F415, F435_437, F423, | ✔ | ✔ | | dwc2 | | -| | F425, F45x | | | | | | -| +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | F402_F405 | ✔ | ✔ | ✔ | dwc2 | F405 is HS | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| Bridgetek | FT90x | ✔ | | ✔ | ft9xx | 1-dir ep | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| Broadcom | BCM2711, BCM2837 | ✔ | | ✔ | dwc2 | | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| Dialog | DA1469x | ✔ | ✖ | ✖ | da146xx | | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| Espressif | S2, S3, H4 | ✔ | ✔ | ✖ | dwc2 | | -| ESP32 +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | P4 | ✔ | ✔ | ✔ | dwc2 | | -| +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | S31 | ✔ | ✔ | ✔ | dwc2 | | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| GigaDevice | GD32VF103 | ✔ | | ✖ | dwc2 | | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| HPMicro | HPM6750 | ✔ | ✔ | ✔ | ci_hs, ehci | | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| Infineon | XMC4500 | ✔ | ✔ | ✖ | dwc2 | | -+--------------+-----+-----------------------+--------+------+-----------+------------------------+--------------------+ -| MicroChip | SAM | D11, D21, L21, L22 | ✔ | | ✖ | samd | | -| | +-----------------------+--------+------+-----------+------------------------+--------------------+ -| | | D51, E5x | ✔ | | ✖ | samd | | -| | +-----------------------+--------+------+-----------+------------------------+--------------------+ -| | | G55 | ✔ | | ✖ | samg | 1-dir ep | -| | +-----------------------+--------+------+-----------+------------------------+--------------------+ -| | | E70,S70,V70,V71 | ✔ | | ✔ | samx7x | 1-dir ep | -| +-----+-----------------------+--------+------+-----------+------------------------+--------------------+ -| | PIC | 24 | ✔ | | | pic | ci_fs variant | -| | +-----------------------+--------+------+-----------+------------------------+--------------------+ -| | | 32 mm, mk, mx | ✔ | | | pic | ci_fs variant | -| | +-----------------------+--------+------+-----------+------------------------+--------------------+ -| | | dsPIC33 | ✔ | | | pic | ci_fs variant | -| | +-----------------------+--------+------+-----------+------------------------+--------------------+ -| | | 32mz | ✔ | | | pic32mz | musb variant | -+--------------+-----+-----------------------+--------+------+-----------+------------------------+--------------------+ -| MindMotion | mm32 | ✔ | | ✖ | mm32f327x_otg | ci_fs variant | -+--------------+-----+-----------------------+--------+------+-----------+------------------------+--------------------+ -| NordicSemi | nRF52, nRF53 | ✔ | ✖ | ✖ | nrf5x | only ep8 is ISO | -| +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | nRF54 | ✔ | ✖ | ✔ | dwc2 | | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| Nuvoton | NUC120 | ✔ | ✖ | ✖ | nuc120 | | -| +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | NUC121/NUC125, NUC126 | ✔ | ✖ | ✖ | nuc121 | | -| +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | NUC505 | ✔ | | ✔ | nuc505 | | -+--------------+---------+-------------------+--------+------+-----------+------------------------+--------------------+ -| NXP | iMXRT | RT 10xx, 11xx | ✔ | ✔ | ✔ | ci_hs, ehci | | -| +---------+-------------------+--------+------+-----------+------------------------+--------------------+ -| | Kinetis | KL | ✔ | ⚠ | ✖ | ci_fs, khci | | -| | +-------------------+--------+------+-----------+------------------------+--------------------+ -| | | K32L2 | ✔ | | ✖ | khci | ci_fs variant | -| +---------+-------------------+--------+------+-----------+------------------------+--------------------+ -| | LPC | 11u, 13, 15 | ✔ | ✖ | ✖ | lpc_ip3511 | | -| | +-------------------+--------+------+-----------+------------------------+--------------------+ -| | | 17, 40 | ✔ | ⚠ | ✖ | lpc17_40, ohci | | -| | +-------------------+--------+------+-----------+------------------------+--------------------+ -| | | 18, 43 | ✔ | ✔ | ✔ | ci_hs, ehci | | -| | +-------------------+--------+------+-----------+------------------------+--------------------+ -| | | 51u | ✔ | ✖ | ✖ | lpc_ip3511 | | -| | +-------------------+--------+------+-----------+------------------------+--------------------+ -| | | 54 | ⚠ | ⚠ | ✔ | lpc_ip3511, lpc_ip3516 | NRND, read errata | -| | +-------------------+--------+------+-----------+------------------------+--------------------+ -| | | 55 | ✔ | ✔ | ✔ | lpc_ip3511, lpc_ip3516 | | -| +---------+-------------------+--------+------+-----------+------------------------+--------------------+ -| | MCX | N9 | ✔ | | ✔ | ci_fs, ci_hs, ehci | | -| | +-------------------+--------+------+-----------+------------------------+--------------------+ -| | | A15 | ✔ | | | ci_fs | | -| +---------+-------------------+--------+------+-----------+------------------------+--------------------+ -| | RW61x | ✔ | ✔ | ✔ | ci_hs, ehci | | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| Raspberry Pi | RP2040, RP2350 | ✔ | ✔ | ✖ | rp2040, pio_usb | | -+--------------+-----+-----------------------+--------+------+-----------+------------------------+--------------------+ -| Renesas | RX | 63N, 65N, 72N | ✔ | ✔ | ✖ | rusb2 | | -| +-----+-----------------------+--------+------+-----------+------------------------+--------------------+ -| | RA | 4M1, 4M3, 6M1 | ✔ | ✔ | ✖ | rusb2 | | -| | +-----------------------+--------+------+-----------+------------------------+--------------------+ -| | | 6M5 | ✔ | ✔ | ✔ | rusb2 | | -+--------------+-----+-----------------------+--------+------+-----------+------------------------+--------------------+ -| Silabs | EFM32GG12 | ✔ | | ✖ | dwc2 | | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| Sony | CXD56 | ✔ | ✖ | ✔ | cxd56 | | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| ST STM32 | F0, F3, L0, L1, L5, WBx5 | ✔ | ✖ | ✖ | stm32_fsdev | | -| +----+------------------------+--------+------+-----------+------------------------+--------------------+ -| | F1 | 102, 103 | ✔ | ✖ | ✖ | stm32_fsdev | 512 USB RAM | -| | +------------------------+--------+------+-----------+------------------------+--------------------+ -| | | 105, 107 | ✔ | ✔ | ✖ | dwc2 | | -| +----+------------------------+--------+------+-----------+------------------------+--------------------+ -| | F2, F4, F7, H7, H7RS | ✔ | ✔ | ✔ | dwc2 | | -| +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | C0, G0, H5, U3 | ✔ | ✔ | ✖ | stm32_fsdev | 2KB USB RAM | -| +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | G4 | ✔ | ✖ | ✖ | stm32_fsdev | 1KB USB RAM | -| +----+------------------------+--------+------+-----------+------------------------+--------------------+ -| | L4 | 4x2, 4x3 | ✔ | ✖ | ✖ | stm32_fsdev | 1KB USB RAM | -| | +------------------------+--------+------+-----------+------------------------+--------------------+ -| | | 4x5, 4x6, 4+ | ✔ | ✔ | ✖ | dwc2 | | -| +----+------------------------+--------+------+-----------+------------------------+--------------------+ -| | N6 | ✔ | ✔ | ✔ | dwc2 | | -| +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | U0 | ✔ | ✖ | ✖ | stm32_fsdev | 1KB USB RAM | -| +----+------------------------+--------+------+-----------+------------------------+--------------------+ -| | U5 | 535, 545 | ✔ | ✔ | ✖ | stm32_fsdev | 2KB USB RAM | -| | +------------------------+--------+------+-----------+------------------------+--------------------+ -| | | 575, 585 | ✔ | ✔ | ✖ | dwc2 | | -| | +------------------------+--------+------+-----------+------------------------+--------------------+ -| | | 59x,5Ax,5Fx,5Gx | ✔ | ✔ | ✔ | dwc2 | | -+--------------+----+------------------------+--------+------+-----------+------------------------+--------------------+ -| TI | MSP430 | ✔ | ✖ | ✖ | msp430x5xx | | -| +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | MSP432E4, TM4C123 | ✔ | | ✖ | musb | | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| ValentyUSB | eptri | ✔ | ✖ | ✖ | eptri | | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ -| WCH | CH32F20x | ⚠ | | ✔ | ch32_usbhs | Data loss possible | -| +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | CH32V20x | ⚠ | | ✖ | stm32_fsdev/ch32_usbfs | Data loss possible | -| +-----------------------------+--------+------+-----------+------------------------+--------------------+ -| | CH32V305, CH32V307 | ⚠ | | ✔ | ch32_usbfs/hs | Data loss possible | -+--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+ ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| Manufacturer | Family | Device | Host | Highspeed | Driver | Note | ++==============+=============================+========+======+===========+========================+=============================================+ +| Allwinner | F1C100s/F1C200s | ✔ | | ✔ | sunxi | musb variant | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| Analog | MAX3421E | | ✔ | ✖ | max3421 | via SPI | +| +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | MAX32 650, 666, 690, | ✔ | | ✔ | musb | 1-dir ep | +| | MAX78002 | | | | | | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| Artery AT32 | F403a_407, F413 | ✔ | | | fsdev | 512 USB RAM | +| +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | F415, F435_437, F423, | ✔ | ✔ | | dwc2 | | +| | F425, F45x | | | | | | +| +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | F402_F405 | ✔ | ✔ | ✔ | dwc2 | F405 is HS | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| Bridgetek | FT90x | ✔ | | ✔ | ft9xx | 1-dir ep | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| Broadcom | BCM2711, BCM2837 | ✔ | | ✔ | dwc2 | | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| Dialog | DA1469x | ✔ | ✖ | ✖ | da146xx | | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| Espressif | S2, S3, H4 | ✔ | ✔ | ✖ | dwc2 | | +| ESP32 +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | P4 | ✔ | ✔ | ✔ | dwc2 | | +| +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | S31 | ✔ | ✔ | ✔ | dwc2 | | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| GigaDevice | GD32VF103 | ✔ | | ✖ | dwc2 | | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| HPMicro | HPM6750 | ✔ | ✔ | ✔ | ci_hs, ehci | | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| Infineon | XMC4500 | ✔ | ✔ | ✖ | dwc2 | | ++--------------+-----+-----------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| MicroChip | SAM | D11, D21, L21, L22 | ✔ | | ✖ | samd | | +| | +-----------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | D51, E5x | ✔ | | ✖ | samd | | +| | +-----------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | G55 | ✔ | | ✖ | samg | 1-dir ep | +| | +-----------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | E70,S70,V70,V71 | ✔ | | ✔ | samx7x | 1-dir ep | +| +-----+-----------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | PIC | 24 | ✔ | | | pic | ci_fs variant | +| | +-----------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | 32 mm, mk, mx | ✔ | | | pic | ci_fs variant | +| | +-----------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | dsPIC33 | ✔ | | | pic | ci_fs variant | +| | +-----------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | 32mz | ✔ | | | pic32mz | musb variant | ++--------------+-----+-----------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| MindMotion | mm32 | ✔ | | ✖ | mm32f327x_otg | ci_fs variant | ++--------------+-----+-----------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| NordicSemi | nRF52, nRF53 | ✔ | ✖ | ✖ | nrf5x | only ep8 is ISO | +| +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | nRF54 | ✔ | ✖ | ✔ | dwc2 | | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| Nuvoton | NUC120 | ✔ | ✖ | ✖ | nuc120 | | +| +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | NUC121/NUC125, NUC126 | ✔ | ✖ | ✖ | nuc121 | | +| +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | NUC505 | ✔ | | ✔ | nuc505 | | ++--------------+---------+-------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| NXP | iMXRT | RT 10xx, 11xx | ✔ | ✔ | ✔ | ci_hs, ehci | | +| +---------+-------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | Kinetis | KL | ✔ | ⚠ | ✖ | ci_fs, khci | | +| | +-------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | K32L2 | ✔ | | ✖ | khci | ci_fs variant | +| +---------+-------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | LPC | 11u, 13, 15 | ✔ | ✖ | ✖ | lpc_ip3511 | | +| | +-------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | 17, 40 | ✔ | ⚠ | ✖ | lpc17_40, ohci | | +| | +-------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | 18, 43 | ✔ | ✔ | ✔ | ci_hs, ehci | | +| | +-------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | 51u | ✔ | ✖ | ✖ | lpc_ip3511 | | +| | +-------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | 54 | ⚠ | ⚠ | ✔ | lpc_ip3511, lpc_ip3516 | :ref:`NRND, read errata ` | +| | +-------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | 55 | ✔ | ✔ | ✔ | lpc_ip3511, lpc_ip3516 | | +| +---------+-------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | MCX | N9 | ✔ | | ✔ | ci_fs, ci_hs, ehci | | +| | +-------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | A15 | ✔ | | | ci_fs | | +| +---------+-------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | RW61x | ✔ | ✔ | ✔ | ci_hs, ehci | | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| Raspberry Pi | RP2040, RP2350 | ✔ | ✔ | ✖ | rp2040, pio_usb | | ++--------------+-----+-----------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| Renesas | RX | 63N, 65N, 72N | ✔ | ✔ | ✖ | rusb2 | | +| +-----+-----------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | RA | 4M1, 4M3, 6M1 | ✔ | ✔ | ✖ | rusb2 | | +| | +-----------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | 6M5 | ✔ | ✔ | ✔ | rusb2 | | ++--------------+-----+-----------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| Silabs | EFM32GG12 | ✔ | | ✖ | dwc2 | | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| Sony | CXD56 | ✔ | ✖ | ✔ | cxd56 | | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| ST STM32 | F0, F3, L0, L1, L5, WBx5 | ✔ | ✖ | ✖ | stm32_fsdev | | +| +----+------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | F1 | 102, 103 | ✔ | ✖ | ✖ | stm32_fsdev | 512 USB RAM | +| | +------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | 105, 107 | ✔ | ✔ | ✖ | dwc2 | | +| +----+------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | F2, F4, F7, H7, H7RS | ✔ | ✔ | ✔ | dwc2 | | +| +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | C0, G0, H5, U3 | ✔ | ✔ | ✖ | stm32_fsdev | 2KB USB RAM | +| +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | G4 | ✔ | ✖ | ✖ | stm32_fsdev | 1KB USB RAM | +| +----+------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | L4 | 4x2, 4x3 | ✔ | ✖ | ✖ | stm32_fsdev | 1KB USB RAM | +| | +------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | 4x5, 4x6, 4+ | ✔ | ✔ | ✖ | dwc2 | | +| +----+------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | N6 | ✔ | ✔ | ✔ | dwc2 | | +| +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | U0 | ✔ | ✖ | ✖ | stm32_fsdev | 1KB USB RAM | +| +----+------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | U5 | 535, 545 | ✔ | ✔ | ✖ | stm32_fsdev | 2KB USB RAM | +| | +------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | 575, 585 | ✔ | ✔ | ✖ | dwc2 | | +| | +------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | | 59x,5Ax,5Fx,5Gx | ✔ | ✔ | ✔ | dwc2 | | ++--------------+----+------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| TI | MSP430 | ✔ | ✖ | ✖ | msp430x5xx | | +| +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | MSP432E4, TM4C123 | ✔ | | ✖ | musb | | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| ValentyUSB | eptri | ✔ | ✖ | ✖ | eptri | | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| WCH | CH32F20x | ⚠ | | ✔ | ch32_usbhs | :ref:`ISO data loss ` | +| +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | CH32V20x | ⚠ | | ✖ | stm32_fsdev/ch32_usbfs | :ref:`ISO data loss ` | +| +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ +| | CH32V305, CH32V307 | ⚠ | | ✔ | ch32_usbfs/hs | :ref:`ISO data loss ` | ++--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ Table Legend ^^^^^^^^^^^^ diff --git a/docs/index.rst b/docs/index.rst index 39d30a038a..a8762c2c2b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,6 +10,7 @@ reference/index faq troubleshooting + reference/errata .. toctree:: :maxdepth: 1 diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index bb9f15166c..531d471edd 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -76,6 +76,8 @@ Invalid board name in build command. Runtime Issues ============== +Check :doc:`reference/errata` for known hardware-specific issues that may affect USB functionality on your device. + Device Mode Problems -------------------- From e35b070dae92fd2750b8116a6ca0f1de393c7a6a Mon Sep 17 00:00:00 2001 From: HiFiPhile Date: Tue, 2 Jun 2026 10:41:27 +0200 Subject: [PATCH 3/6] rename to device issues Signed-off-by: HiFiPhile --- README.rst | 8 +++---- docs/index.rst | 2 +- docs/reference/device_issues.rst | 39 ++++++++++++++++++++++++++++++++ docs/reference/index.rst | 1 + docs/troubleshooting.rst | 2 +- 5 files changed, 46 insertions(+), 6 deletions(-) create mode 100644 docs/reference/device_issues.rst diff --git a/README.rst b/README.rst index c376599ec5..e039c2b61e 100644 --- a/README.rst +++ b/README.rst @@ -207,7 +207,7 @@ Supported CPUs | | +-------------------+--------+------+-----------+------------------------+---------------------------------------------+ | | | 51u | ✔ | ✖ | ✖ | lpc_ip3511 | | | | +-------------------+--------+------+-----------+------------------------+---------------------------------------------+ -| | | 54 | ⚠ | ⚠ | ✔ | lpc_ip3511, lpc_ip3516 | :ref:`NRND, read errata ` | +| | | 54 | ⚠ | ⚠ | ✔ | lpc_ip3511, lpc_ip3516 | :ref:`NRND, read errata ` | | | +-------------------+--------+------+-----------+------------------------+---------------------------------------------+ | | | 55 | ✔ | ✔ | ✔ | lpc_ip3511, lpc_ip3516 | | | +---------+-------------------+--------+------+-----------+------------------------+---------------------------------------------+ @@ -261,11 +261,11 @@ Supported CPUs +--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ | ValentyUSB | eptri | ✔ | ✖ | ✖ | eptri | | +--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ -| WCH | CH32F20x | ⚠ | | ✔ | ch32_usbhs | :ref:`ISO data loss ` | +| WCH | CH32F20x | ⚠ | | ✔ | ch32_usbhs | :ref:`ISO data loss ` | | +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ -| | CH32V20x | ⚠ | | ✖ | stm32_fsdev/ch32_usbfs | :ref:`ISO data loss ` | +| | CH32V20x | ⚠ | | ✖ | stm32_fsdev/ch32_usbfs | :ref:`ISO data loss ` | | +-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ -| | CH32V305, CH32V307 | ⚠ | | ✔ | ch32_usbfs/hs | :ref:`ISO data loss ` | +| | CH32V305, CH32V307 | ⚠ | | ✔ | ch32_usbfs/hs | :ref:`ISO data loss ` | +--------------+-----------------------------+--------+------+-----------+------------------------+---------------------------------------------+ Table Legend diff --git a/docs/index.rst b/docs/index.rst index a8762c2c2b..b80804ad47 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,7 +10,7 @@ reference/index faq troubleshooting - reference/errata + reference/device_issues .. toctree:: :maxdepth: 1 diff --git a/docs/reference/device_issues.rst b/docs/reference/device_issues.rst new file mode 100644 index 0000000000..22677f9673 --- /dev/null +++ b/docs/reference/device_issues.rst @@ -0,0 +1,39 @@ +Device specific known issues and workarounds +=============================================== +This page lists known issues and workarounds for specific devices. + +.. _LPC54600 Issues: + +NXP LPC54600 +---------------- +**Severity: High** + +**Not recommended for USB device applications (except high-speed host controller)** + +Reference: `LPC54600 Errata Sheet`_ + +.. _LPC54600 Errata Sheet: https://www.nxp.com/docs/en/errata/ES_LPC546XX.pdf + +The LPC54600 series have a very buggy USB controller, with totally 17 issues listed in the errata which is more than half of the total issues. + +Most severe issues are: + +- USB.2: In USB high-speed device mode, the NBytes field is not correct after BULK IN transfer +- USB.5: In USB full-speed host mode, linked list on done queue is broken. +- USB.15: USB high-speed device in endpoint TX data corruption + +.. _WCH CH32X Issues: + +WCH CH32V10X/CH32V20X/CH32V30X +--------------------------------- +**Severity: Medium** + +**Not recommended for USB audio applications** + +Reference: `CH32V30X Reference Manual`_ USBFS/USBHS controller chapter + +.. _CH32V30X Reference Manual: https://www.wch-ic.com/downloads/CH32FV2x_V3xRM_PDF.html + +Data corruption may occur on isochronous endpoints. Due to the lacking of FIFO for interrupt status registers, later completed transfer will overwrite `INT_ST` and `RX_LEN` register if previous transfer processing is not completed. + +Other types of transfers are not affected. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index d3c96eeee5..fe504627dd 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -12,4 +12,5 @@ Complete reference documentation for TinyUSB APIs, configuration, and supported boards dependencies concurrency + device_issues glossary diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 531d471edd..613c7fceff 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -76,7 +76,7 @@ Invalid board name in build command. Runtime Issues ============== -Check :doc:`reference/errata` for known hardware-specific issues that may affect USB functionality on your device. +Check :doc:`reference/device_issues` for known hardware-specific issues that may affect USB functionality on your device. Device Mode Problems -------------------- From 22c2ece872262c1331482f8e80881ab1f5f36c0b Mon Sep 17 00:00:00 2001 From: HiFiPhile Date: Tue, 2 Jun 2026 11:10:15 +0200 Subject: [PATCH 4/6] try to get render right Signed-off-by: HiFiPhile --- README.rst | 8 ++++---- docs/conf.py | 19 +++++++++++++++++++ 2 files changed, 23 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index fac098c1cc..ecfbeb7ccc 100644 --- a/README.rst +++ b/README.rst @@ -251,7 +251,7 @@ Supported CPUs | | +-------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ | | | 51u | ✔ | ✖ | ✖ | lpc_ip3511 | | | | +-------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ -| | | 54 | ⚠ | ⚠ | ✔ | lpc_ip3511, lpc_ip3516 | `NRND, read errata `_ | +| | | 54 | ⚠ | ⚠ | ✔ | lpc_ip3511, lpc_ip3516 | `NRND, read errata `_ | | | +-------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ | | | 55 | ✔ | ✔ | ✔ | lpc_ip3511, lpc_ip3516 | | | +---------+-------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ @@ -305,11 +305,11 @@ Supported CPUs +--------------+-----------------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ | ValentyUSB | eptri | ✔ | ✖ | ✖ | eptri | | +--------------+-----------------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ -| WCH | CH32F20x | ⚠ | | ✔ | ch32_usbhs | `ISO data loss `_ | +| WCH | CH32F20x | ⚠ | | ✔ | ch32_usbhs | `ISO data loss `_ | | +-----------------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ -| | CH32V20x | ⚠ | | ✖ | stm32_fsdev/ch32_usbfs | `ISO data loss `_ | +| | CH32V20x | ⚠ | | ✖ | stm32_fsdev/ch32_usbfs | `ISO data loss `_ | | +-----------------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ -| | CH32V305, CH32V307 | ⚠ | | ✔ | ch32_usbfs/hs | `ISO data loss `_ | +| | CH32V305, CH32V307 | ⚠ | | ✔ | ch32_usbfs/hs | `ISO data loss `_ | +--------------+-----------------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ Table Legend diff --git a/docs/conf.py b/docs/conf.py index 9e9784fb70..86ddcf6726 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -53,6 +53,25 @@ def preprocess_readme(): tgt = Path(__file__).parent.parent / "README_processed.rst" if src.exists(): content = src.read_text(encoding='utf-8') + # if the matching is inside a table, keep the table cell width by adding the same number of spaces in the end of the line + # match pattern: | ... `... `_ ... | + # change into: | ... `... <...>`_ ... | + def _rewrite_table_line(line): + if not (line.startswith('|') and line.rstrip().endswith('|')): + return line + + rewritten = re.sub(r"]+)>", r"<\1>", line) + delta = len(line) - len(rewritten) - 1 # -1 for rst->html + + if delta > 0: + last_pipe = rewritten.rfind('|') + if last_pipe >= 0: + rewritten = rewritten[:last_pipe] + (' ' * delta) + rewritten[last_pipe:] + + return rewritten + + content = ''.join(_rewrite_table_line(line) for line in content.splitlines(keepends=True)) + content = re.sub(r"docs/", r"", content) content = re.sub(r"\.rst\b", r".html", content) if not content.endswith("\n"): From ff3fef931dd2be604fd525814654d1cfcd7c725c Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Tue, 2 Jun 2026 16:01:23 +0000 Subject: [PATCH 5/6] docs: fix review issues in device_issues and README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove duplicate toctree entry for reference/device_issues from docs/index.rst (already included via docs/reference/index.rst) - Fix WCH section title: CH32V10X/CH32V20X/CH32V30X → CH32F20x/CH32V20x/CH32V30x to match the three actual README table entries (CH32F20x, CH32V20x, CH32V305/307) - Update README anchor links to match the renamed section - Qualify USBFS non-ISO transfer safety claim: USBHS is protected by USBHS_INT_BUSY_EN but USBFS behavior is not yet confirmed - Fix LPC54600 note: "read errata" → "see device issues" - Remove "totally" from LPC54600 description Co-authored-by: Ha Thach --- README.rst | 8 ++++---- docs/index.rst | 1 - docs/reference/device_issues.rst | 6 +++--- 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index ecfbeb7ccc..67149a4f2d 100644 --- a/README.rst +++ b/README.rst @@ -251,7 +251,7 @@ Supported CPUs | | +-------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ | | | 51u | ✔ | ✖ | ✖ | lpc_ip3511 | | | | +-------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ -| | | 54 | ⚠ | ⚠ | ✔ | lpc_ip3511, lpc_ip3516 | `NRND, read errata `_ | +| | | 54 | ⚠ | ⚠ | ✔ | lpc_ip3511, lpc_ip3516 | `NRND, see device issues `_ | | | +-------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ | | | 55 | ✔ | ✔ | ✔ | lpc_ip3511, lpc_ip3516 | | | +---------+-------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ @@ -305,11 +305,11 @@ Supported CPUs +--------------+-----------------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ | ValentyUSB | eptri | ✔ | ✖ | ✖ | eptri | | +--------------+-----------------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ -| WCH | CH32F20x | ⚠ | | ✔ | ch32_usbhs | `ISO data loss `_ | +| WCH | CH32F20x | ⚠ | | ✔ | ch32_usbhs | `ISO data loss `_ | | +-----------------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ -| | CH32V20x | ⚠ | | ✖ | stm32_fsdev/ch32_usbfs | `ISO data loss `_ | +| | CH32V20x | ⚠ | | ✖ | stm32_fsdev/ch32_usbfs | `ISO data loss `_ | | +-----------------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ -| | CH32V305, CH32V307 | ⚠ | | ✔ | ch32_usbfs/hs | `ISO data loss `_ | +| | CH32V305, CH32V307 | ⚠ | | ✔ | ch32_usbfs/hs | `ISO data loss `_ | +--------------+-----------------------------+--------+------+-----------+------------------------+-----------------------------------------------------------------------------------------+ Table Legend diff --git a/docs/index.rst b/docs/index.rst index b80804ad47..39d30a038a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,7 +10,6 @@ reference/index faq troubleshooting - reference/device_issues .. toctree:: :maxdepth: 1 diff --git a/docs/reference/device_issues.rst b/docs/reference/device_issues.rst index a69f6ba807..6dafe4de23 100644 --- a/docs/reference/device_issues.rst +++ b/docs/reference/device_issues.rst @@ -12,7 +12,7 @@ Reference: `LPC54600 Errata Sheet`_ .. _LPC54600 Errata Sheet: https://www.nxp.com/docs/en/errata/ES_LPC546XX.pdf -The LPC54600 series have a very buggy USB controller, with totally 17 issues listed in the errata which is more than half of the total issues. +The LPC54600 series have a very buggy USB controller, with 17 issues listed in the errata which is more than half of the total issues. Most severe issues are: @@ -20,7 +20,7 @@ Most severe issues are: - USB.5: In USB full-speed host mode, linked list on done queue is broken. - USB.15: USB high-speed device in endpoint TX data corruption -WCH CH32V10X/CH32V20X/CH32V30X +WCH CH32F20x/CH32V20x/CH32V30x --------------------------------- **Severity: Medium** @@ -32,4 +32,4 @@ Reference: `CH32V30X Reference Manual`_ USBFS/USBHS controller chapter Data corruption may occur on isochronous endpoints. Due to the lacking of FIFO for interrupt status registers, later completed transfer will overwrite `INT_ST` and `RX_LEN` register if previous transfer processing is not completed. -Other types of transfers are not affected. +For USBHS devices (CH32F20x, CH32V305/CH32V307), other transfer types are protected by the ``USBHS_INT_BUSY_EN`` mechanism which holds off new transfers while an interrupt is being processed. USBFS device behavior is not fully confirmed. From f19c01216fc5fc0f07789932df1db6fde82f525b Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Tue, 2 Jun 2026 16:59:14 +0000 Subject: [PATCH 6/6] docs: revert USBFS non-ISO transfer qualification in device_issues Restore original "Other types of transfers are not affected" statement, removing the conditional USBHS_INT_BUSY_EN / USBFS-unconfirmed wording. Co-authored-by: Zixun LI --- docs/reference/device_issues.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/device_issues.rst b/docs/reference/device_issues.rst index 6dafe4de23..ae9cd55f16 100644 --- a/docs/reference/device_issues.rst +++ b/docs/reference/device_issues.rst @@ -32,4 +32,4 @@ Reference: `CH32V30X Reference Manual`_ USBFS/USBHS controller chapter Data corruption may occur on isochronous endpoints. Due to the lacking of FIFO for interrupt status registers, later completed transfer will overwrite `INT_ST` and `RX_LEN` register if previous transfer processing is not completed. -For USBHS devices (CH32F20x, CH32V305/CH32V307), other transfer types are protected by the ``USBHS_INT_BUSY_EN`` mechanism which holds off new transfers while an interrupt is being processed. USBFS device behavior is not fully confirmed. +Other types of transfers are not affected.