Merge pull request #3653 from hathach/ch32_warning

add device specific issues

4 files changed, 57 insertions, 0 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 9e9784fb7..86ddcf672 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: | ... `... <docs/...>`_ ... |
+        # change into:   | ... `... <...>`_ ...      |
+        def _rewrite_table_line(line):
+            if not (line.startswith('|') and line.rstrip().endswith('|')):
+                return line
+
+            rewritten = re.sub(r"<docs/([^>]+)>", 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"):
diff --git a/docs/reference/device_issues.rst b/docs/reference/device_issues.rst
new file mode 100644
index 000000000..ae9cd55f1
--- /dev/null
+++ b/docs/reference/device_issues.rst
@@ -0,0 +1,35 @@
+Device specific known issues and workarounds
+===============================================
+This page lists known issues and workarounds for specific devices.
+
+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 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 CH32F20x/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 148e8a63b..c66ce618f 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -13,4 +13,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 bb9f15166..613c7fcef 100644
--- a/docs/troubleshooting.rst
+++ b/docs/troubleshooting.rst
@@ -76,6 +76,8 @@ Invalid board name in build command.
 Runtime Issues
 ==============
 
+Check :doc:`reference/device_issues` for known hardware-specific issues that may affect USB functionality on your device.
+
 Device Mode Problems
 --------------------