add device specific issues

[HiFiPhile]

With LPC54600 and WCH CH32X issues inplace and a link from supported device table.

@hathach due to numerous issues we had about Pi-PIO, maybe also note it's limitations ?

[Copilot]

Pull request overview

Updates the TinyUSB “Supported CPUs” matrix to warn that CH32 USBFS/USBHS device-controller drivers may experience data loss due to hardware interrupt behavior, aligning the documentation with the reported WCH FAE guidance.

Changes:

• Mark WCH CH32F20x, CH32V20x, and CH32V305/CH32V307 device support as partial (⚠).
• Add a “Data loss possible” note for the affected CH32 entries in the support table.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[rhgndf]

Does this also affect CH32H417? I am working on a port for it #3642 and possibly a superspeed one.

[HiFiPhile]

@rhgndf I didn't ask for H417. For FS I think it's the same, for HS I hope it's not jugging from the new register layout where each EP has own status and length fields.
As RB_UDIF_RTX_ACT is cleared by RB_UEP_R_DONE/RB_UEP_T_DONE flag, I hope INT_ST will update each time the flag is cleared so we can easily use a loop to process all completed EPs.

[HiFiPhile]

@rhgndf After more testing the situation is not that bad, data loss will only occurs on ISO transfers.

For other transfer types with USBHS_INT_BUSY_EN=1 the controller will set all EPs to NAK once transfer complete IRQ is fired.

In this capture:

1. first 2 PINGs checked that both OUT EPs are ready to receive
2. EP3 received packet, IRQ fired after ACK
3. EP2 reply with NAK automatically
4. IRQ is finished
5. EP2 change back to ACK and receive data

I will add more detail to the doc and add the issue of LPC54600.

[github-actions]

MemBrowse Memory Report

No memory changes detected across 2332 targets. View Project Dashboard →

[hathach]

thank @HiFiPhile I think you forgot to add the actual errata doc

[HiFiPhile]

thank @HiFiPhile I think you forgot to add the actual errata doc

I should rename it to device specific issues instead of errata.

[hathach]

thank @HiFiPhile I think you forgot to add the actual errata doc

I should rename it to device specific issues instead of errata.

yeah, I think it is a better name, may be device/cpu known issues. We may make an mistake especially when there is no offical errata doc.

[HiFiPhile]

I forgot the document itself...

[hathach]

@claude review

[claude]

Claude finished @hathach's task in 2m 31s —— View job

---

Code Review

• Gather context and understand request
• Read changed files
• Review README.rst changes
• Review new device_issues.rst document
• Review docs configuration changes
• Post review findings

---

Summary

Good addition of device-specific issue documentation. The intent is clear and the information is useful. A few issues need attention before merge.

---

Issues

1. Duplicate toctree entry (docs/index.rst)

docs/reference/device_issues appears in two toctrees: the top-level docs/index.rst directly and also through docs/reference/index.rst. Sphinx will generate a warning for this and may produce confusing navigation.

# docs/index.rst — line 13:
   reference/device_issues      ← this should be removed

# docs/reference/index.rst — line 16:
   device_issues                ← this is the canonical location

The reference/device_issues entry should be removed from docs/index.rst, keeping it only in docs/reference/index.rst. The troubleshooting page already cross-references it with :doc: which works regardless.

Fix this →

---

2. CH32 section title vs README coverage mismatch (docs/reference/device_issues.rst line 23)

The section heading is WCH CH32V10X/CH32V20X/CH32V30X, but in README.rst, CH32F20x (which uses the USBHS driver) is also marked ⚠ and linked to this same anchor (#wch-ch32v10x-ch32v20x-ch32v30x). CH32F20x is missing from the section title entirely.

Additionally, CH32V10X is in the section title but has no entry in the README's supported CPUs table.

Suggested title: WCH CH32F20x/CH32V20x/CH32V30x or WCH CH32 USBFS/USBHS (to cover both the FS and HS variants that are actually in the table).

Fix this →

---

3. "Other types of transfers are not affected" may be inaccurate for USBFS (device_issues.rst line 35)

Based on the PR comment thread, the USBHS_INT_BUSY_EN busy-lock mechanism — which prevents data loss on non-ISO transfers — is an USBHS-specific feature. For USBFS (CH32V20x, CH32V30x FS side), it's unclear whether non-ISO transfers also have the same protection.

The current wording "Other types of transfers are not affected" is blanket for all CH32 devices. Either qualify it (For USBHS devices, other transfer types are protected by USBHS_INT_BUSY_EN...) or remove the sentence until the USBFS behavior is confirmed.

---

4. LPC54600 README note says "read errata" but links to "device issues" (README.rst)

The note text reads NRND, read errata but the linked document is titled "Device specific known issues and workarounds" — it is not an official errata sheet (the errata sheet is linked from within that page). The note text should say "see device issues" or "NRND, known issues" to avoid confusion.

Fix this →

---

Minor

• device_issues.rst line 15: "with totally 17 issues listed" → "with 17 issues listed" (remove "totally").
• device_issues.rst line 15: "which is more than half of the total issues" — this should be verified against the actual errata sheet. If the total errata count changes, this becomes stale. Consider dropping the relative comparison or citing the total count.
• RP2040 PIO-USB limitations: The PR body asks about adding notes for PIO-USB limitations — this is not addressed in the PR. Consider a follow-up or adding a stub entry.
• docs/conf.py: The _rewrite_table_line nested function and delta calculation looks correct. The -1 correctly compensates for .rst→.html adding one character. Good implementation.

---

Verdict

The core content is accurate and useful. The main blockers are the duplicate toctree entry (will cause Sphinx warnings) and the CH32 section title not matching the README table entries. The accuracy concern on USBFS non-ISO transfers is a softer issue but worth clarifying.
| Branch: ch32_warning

[hathach]

@claude fix your own above review

[claude]

Claude finished @hathach's task in 2m 39s —— View job

---

Fixed Review Issues

• Gather context and read files
• Fix duplicate toctree entry in docs/index.rst — removed reference/device_issues from the top-level toctree (already included via docs/reference/index.rst)
• Fix CH32 section title in docs/reference/device_issues.rst — WCH CH32V10X/CH32V20X/CH32V30X → WCH CH32F20x/CH32V20x/CH32V30x to match the three README table entries; updated all three anchor links in README.rst accordingly
• Qualify USBFS non-ISO transfer claim — replaced blanket "Other types of transfers are not affected" with: USBHS devices are protected by USBHS_INT_BUSY_EN; USBFS behavior is not yet confirmed
• Fix README.rst LPC54600 note — "NRND, read errata" → "NRND, see device issues"
• Fix "totally" wording in device_issues.rst — "with totally 17 issues" → "with 17 issues"
• Committed all changes (ff3fef9)
  | Branch: ch32_warning

[hathach]

@HiFiPhile sorry, trying to test claude to make changes, it is a bit aggressive toward origin fork since it think this may be a local branch. Could tell it to make pr to pr instead.

[hathach]

@claude fix claude code review ci workflow failed

[HiFiPhile]

@claude Revert Fix "Qualify USBFS non-ISO transfer claim — replaced blanket "Other types of transfers are not affected" with: USBHS devices are protected by USBHS_INT_BUSY_EN; USBFS behavior is not yet confirmed"

[claude]

Claude finished @HiFiPhile's task in 37s —— View job

---

Reverted USBFS qualification change

• Gather context and understand request
• Read docs/reference/device_issues.rst to find the current text
• Revert to original "Other types of transfers are not affected" statement
• Commit changes

Restored docs/reference/device_issues.rst line 35 back to the original blanket statement:

Other types of transfers are not affected.

Removed the conditional text about USBHS_INT_BUSY_EN and the unconfirmed USBFS note. Commit: f19c012.

Branch: ch32_warning

[hathach]

perfect, thank you

[hathach]

PS: PIO-USB is software bit-banging usb host, so yeah, it will have issues. But it is fixable, since it is entirely software. Its limitation is probably it takes lots of efforts and testing to get the timing and code right to fix an issue.