Merge remote-tracking branch 'upstream/master' into hcd-template-comments

Signed-off-by: HiFiPhile <[email protected]>

1 files changed, 150 insertions, 107 deletions

diff --git a/README.rst b/README.rst
index 1ae8c5375..efbfa354b 100644
--- a/README.rst
+++ b/README.rst
@@ -1,4 +1,4 @@
-|Build Status| |Documentation Status| |Fuzzing Status| |License|
+|Build Status| |CircleCI Status| |Documentation Status| |Fuzzing Status| |License|
 
 Sponsors
 ========
@@ -15,10 +15,7 @@ TinyUSB Project
 .. figure:: docs/assets/logo.svg
    :alt: TinyUSB
 
-TinyUSB is an open-source cross-platform USB Host/Device stack for
-embedded system, designed to be memory-safe with no dynamic allocation
-and thread-safe with all interrupt events are deferred then handled in
-the non-ISR task function. Check out the online `documentation <https://docs.tinyusb.org/>`__ for more details.
+TinyUSB is an open-source cross-platform USB Host/Device stack for embedded system, designed to be memory-safe with no dynamic allocation and thread-safe with all interrupt events are deferred then handled in the non-ISR task function. Check out the online `documentation <https://docs.tinyusb.org/>`__ for more details.
 
 .. figure:: docs/assets/stack.svg
    :width: 500px
@@ -32,7 +29,7 @@ the non-ISR task function. Check out the online `documentation <https://docs.tin
     ├── hw
     │   ├── bsp         # Supported boards source files
     │   └── mcu         # Low level mcu core & peripheral drivers
-    ├── lib             # Sources from 3rd party such as freeRTOS, fatfs ...
+    ├── lib             # Sources from 3rd party such as FreeRTOS, FatFs ...
     ├── src             # All sources files for TinyUSB stack itself.
     ├── test            # Tests: unit test, fuzzing, hardware test
     └── tools           # Files used internally
@@ -43,12 +40,12 @@ Getting started
 
 See the `online documentation <https://docs.tinyusb.org>`_ for information about using TinyUSB and how it is implemented.
 
+Check out `Getting Started`_ guide for adding TinyUSB to your project or building the examples. If you are new to TinyUSB, we recommend starting with the ``cdc_msc`` example. There is a handful of `Supported Boards`_ that should work out of the box.
+
 We use `GitHub Discussions <https://github.com/hathach/tinyusb/discussions>`_ as our forum. It is a great place to ask questions and advice from the community or to discuss your TinyUSB-based projects.
 
 For bugs and feature requests, please `raise an issue <https://github.com/hathach/tinyusb/issues>`_ and follow the templates there.
 
-Check out `Getting Started`_ guide for adding TinyUSB to your project or building the examples. If you are new to TinyUSB, we recommend starting with the `cdc_msc` example.
-
 See `Porting`_ guide for adding support for new MCUs and boards.
 
 Device Stack
@@ -69,7 +66,7 @@ Supports multiple device configurations by dynamically changing USB descriptors,
 -  Vendor-specific class support with generic In & Out endpoints. Can be used with MS OS 2.0 compatible descriptor to load winUSB driver without INF file.
 -  `WebUSB <https://github.com/WICG/webusb>`__ with vendor-specific class
 
-If you have a special requirement, `usbd_app_driver_get_cb()` can be used to write your own class driver without modifying the stack. Here is how the RPi team added their reset interface `raspberrypi/pico-sdk#197 <https://github.com/raspberrypi/pico-sdk/pull/197>`_
+If you have a special requirement, ``usbd_app_driver_get_cb()`` can be used to write your own class driver without modifying the stack. Here is how the RPi team added their reset interface `raspberrypi/pico-sdk#197 <https://github.com/raspberrypi/pico-sdk/pull/197>`_
 
 Host Stack
 ==========
@@ -77,13 +74,13 @@ Host Stack
 - Human Interface Device (HID): Keyboard, Mouse, Generic
 - Mass Storage Class (MSC)
 - Communication Device Class: CDC-ACM
-- Vendor serial over USB: FTDI, CP210x
+- Vendor serial over USB: FTDI, CP210x, CH34x
 - Hub with multiple-level support
 
-Similar to the Device Stack, if you have a special requirement, `usbh_app_driver_get_cb()` can be used to write your own class driver without modifying the stack.
+Similar to the Device Stack, if you have a special requirement, ``usbh_app_driver_get_cb()`` can be used to write your own class driver without modifying the stack.
 
-TypeC PD Stack
-==============
+Power Delivery Stack
+====================
 
 - Power Delivery 3.0 (PD3.0) with USB Type-C support (WIP)
 - Super early stage, only for testing purpose
@@ -102,101 +99,150 @@ TinyUSB is completely thread-safe by pushing all Interrupt Service Request (ISR)
 Supported CPUs
 ==============
 
-Following CPUs are supported, check out `Supported Devices`_ for comprehensive list of driver, features for each CPU.
-
-+--------------+------------------------------------------------------------+
-| Manufacturer | Family                                                     |
-+==============+============================================================+
-| Allwinner    | F1C100s/F1C200s                                            |
-+--------------+------------------------------------------------------------+
-| Analog       | MAX3421E (usb host shield)                                 |
-+--------------+------------------------------------------------------------+
-| Brigetek     | FT90x                                                      |
-+--------------+------------------------------------------------------------+
-| Broadcom     | BCM2711, BCM2837                                           |
-+--------------+------------------------------------------------------------+
-| Dialog       | DA1469x                                                    |
-+--------------+------------------------------------------------------------+
-| Espressif    | ESP32 S2, S3                                               |
-+--------------+------------------------------------------------------------+
-| GigaDevice   | GD32VF103                                                  |
-+--------------+------------------------------------------------------------+
-| Infineon     | XMC4500                                                    |
-+--------------+------------------------------------------------------------+
-|              | SAM:  D11, D21, D51, E5x, G55, L2x, E7x, S7x, V7x          |
-|  MicroChip   |                                                            |
-|              | PIC:  24, 32mm, 32mk, 32mx, 32mz, dsPIC33                  |
-+--------------+------------------------------------------------------------+
-| Mind Montion | mm32                                                       |
-+--------------+------------------------------------------------------------+
-| NordicSemi   | nRF52833, nRF52840, nRF5340                                |
-+--------------+------------------------------------------------------------+
-| Nuvoton      | NUC 120, 121, 125, 126, 505                                |
-+--------------+------------------------------------------------------------+
-| NXP          | iMXRT: RT10xx, RT11xx                                      |
-|              |                                                            |
-|              | Kinetis: KL, K32L2                                         |
-|              |                                                            |
-|              | LPC: 11u, 13, 15, 17, 18, 40, 43, 51u, 54, 55              |
-|              |                                                            |
-|              | MCX: A15, N9                                               |
-+--------------+------------------------------------------------------------+
-| Raspberry Pi | RP2040                                                     |
-+--------------+-----+------------------------------------------------------+
-| Renesas      | RA: 4M1, 4M3, 6M1, 6M5                                     |
-|              |                                                            |
-|              | RX: 63N, 65N, 72N                                          |
-+--------------+-----+------------------------------------------------------+
-| Silabs       | EFM32GG12                                                  |
-+--------------+------------------------------------------------------------+
-| Sony         | CXD56                                                      |
-+--------------+------------------------------------------------------------+
-| ST STM32     | F0, F1, F2, F3, F4, F7, G0, G4, H5, H7,                    |
-|              |                                                            |
-|              | L0, L1, L4, L4+, L5, U5, WB                                |
-+--------------+------------------------------------------------------------+
-| TI           | MSP430, MSP432E4, TM4C123                                  |
-+--------------+------------------------------------------------------------+
-| ValentyUSB   | eptri                                                      |
-+--------------+------------------------------------------------------------+
-| WCH          | CH32F: F20x                                                |
-|              |                                                            |
-|              | CH32V: V20x, V307                                          |
-+--------------+------------------------------------------------------------+
-
-License
-=======
-
-All TinyUSB sources in the ``src`` folder are licensed under MIT
-license, the `Full license is here <LICENSE>`__. However, each file can be
-individually licensed especially those in ``lib`` and ``hw/mcu`` folder.
-Please make sure you understand all the license term for files you use
-in your project.
-
-Docs
-====
-
-- Info
-
-  - `Uses`_
-  - `Changelog`_
-  - `Contributors`_
-
-- `Reference`_
++--------------+-----------------------------+--------+------+-----------+------------------------+-------------------+
+| 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                    |        |      |           |                        |                   |
++--------------+-----------------------------+--------+------+-----------+------------------------+-------------------+
+| Brigetek     | FT90x                       | ✔      |      | ✔         | ft9xx                  | 1-dir ep          |
++--------------+-----------------------------+--------+------+-----------+------------------------+-------------------+
+| Broadcom     | BCM2711, BCM2837            | ✔      |      | ✔         | dwc2                   |                   |
++--------------+-----------------------------+--------+------+-----------+------------------------+-------------------+
+| Dialog       | DA1469x                     | ✔      | ✖    | ✖         | da146xx                |                   |
++--------------+-----------------------------+--------+------+-----------+------------------------+-------------------+
+| Espressif    | S2, S3                      | ✔      | ✔    | ✖         | dwc2 or esp32sx        |                   |
+|   ESP32      +-----------------------------+--------+------+-----------+------------------------+-------------------+
+|              | P4                          | ✔      | ✔    | ✔         | dwc2                   |                   |
++--------------+----+------------------------+--------+------+-----------+------------------------+-------------------+
+| GigaDevice   | GD32VF103                   | ✔      |      | ✖         | dwc2                   |                   |
++--------------+-----------------------------+--------+------+-----------+------------------------+-------------------+
+| 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      |
++--------------+-----+-----------------------+--------+------+-----------+------------------------+-------------------+
+| Mind Montion | mm32                        | ✔      |      | ✖         | mm32f327x_otg          | ci_fs variant     |
++--------------+-----+-----------------------+--------+------+-----------+------------------------+-------------------+
+| NordicSemi   | nRF 52833, 52840, 5340      | ✔      | ✖    | ✖         | nrf5x                  | only ep8 is ISO   |
++--------------+-----------------------------+--------+------+-----------+------------------------+-------------------+
+| Nuvoton      | NUC120                      | ✔      | ✖    | ✖         | nuc120                 |                   |
+|              +-----------------------------+--------+------+-----------+------------------------+-------------------+
+|              | NUC121/NUC125               | ✔      | ✖    | ✖         | nuc121                 |                   |
+|              +-----------------------------+--------+------+-----------+------------------------+-------------------+
+|              | NUC126                      | ✔      | ✖    | ✖         | nuc121                 |                   |
+|              +-----------------------------+--------+------+-----------+------------------------+-------------------+
+|              | NUC505                      | ✔      |      | ✔         | nuc505                 |                   |
++--------------+---------+-------------------+--------+------+-----------+------------------------+-------------------+
+| NXP          | iMXRT   | RT 10xx, 11xx     | ✔      | ✔    | ✔         | ci_hs                  |                   |
+|              +---------+-------------------+--------+------+-----------+------------------------+-------------------+
+|              | Kinetis | KL                | ✔      | ⚠    | ✖         | ci_fs, khci            |                   |
+|              |         +-------------------+--------+------+-----------+------------------------+-------------------+
+|              |         | K32L2             | ✔      |      | ✖         | khci                   | ci_fs variant     |
+|              +---------+-------------------+--------+------+-----------+------------------------+-------------------+
+|              | LPC     | 11u, 13, 15       | ✔      | ✖    | ✖         | lpc_ip3511             |                   |
+|              |         +-------------------+--------+------+-----------+------------------------+-------------------+
+|              |         | 17, 40            | ✔      | ⚠    | ✖         | lpc17_40               |                   |
+|              |         +-------------------+--------+------+-----------+------------------------+-------------------+
+|              |         | 18, 43            | ✔      | ✔    | ✔         | ci_hs                  |                   |
+|              |         +-------------------+--------+------+-----------+------------------------+-------------------+
+|              |         | 51u               | ✔      | ✖    | ✖         | lpc_ip3511             |                   |
+|              |         +-------------------+--------+------+-----------+------------------------+-------------------+
+|              |         | 54, 55            | ✔      |      | ✔         | lpc_ip3511             |                   |
+|              +---------+-------------------+--------+------+-----------+------------------------+-------------------+
+|              | MCX     | N9, A15           | ✔      |      | ✔         | ci_fs, ci_hs           |                   |
++--------------+---------+-------------------+--------+------+-----------+------------------------+-------------------+
+| 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                          | ✔      | ✖    | ✖         | stm32_fsdev            |                   |
+|              +----+------------------------+--------+------+-----------+------------------------+-------------------+
+|              | F1 | 102, 103               | ✔      | ✖    | ✖         | stm32_fsdev            |                   |
+|              |    +------------------------+--------+------+-----------+------------------------+-------------------+
+|              |    | 105, 107               | ✔      | ✔    | ✖         | dwc2                   |                   |
+|              +----+------------------------+--------+------+-----------+------------------------+-------------------+
+|              | F2, F4, F7, H7              | ✔      | ✔    | ✔         | dwc2                   |                   |
+|              +-----------------------------+--------+------+-----------+------------------------+-------------------+
+|              | F3                          | ✔      | ✖    | ✖         | stm32_fsdev            |                   |
+|              +-----------------------------+--------+------+-----------+------------------------+-------------------+
+|              | C0, G0, H5                  | ✔      |      | ✖         | stm32_fsdev            |                   |
+|              +-----------------------------+--------+------+-----------+------------------------+-------------------+
+|              | G4                          | ✔      | ✖    | ✖         | stm32_fsdev            |                   |
+|              +-----------------------------+--------+------+-----------+------------------------+-------------------+
+|              | L0, L1                      | ✔      | ✖    | ✖         | stm32_fsdev            |                   |
+|              +----+------------------------+--------+------+-----------+------------------------+-------------------+
+|              | L4 | 4x2, 4x3               | ✔      | ✖    | ✖         | stm32_fsdev            |                   |
+|              |    +------------------------+--------+------+-----------+------------------------+-------------------+
+|              |    | 4x5, 4x6               | ✔      | ✔    | ✖         | dwc2                   |                   |
+|              +----+------------------------+--------+------+-----------+------------------------+-------------------+
+|              | L4+                         | ✔      | ✔    | ✖         | dwc2                   |                   |
+|              +-----------------------------+--------+------+-----------+------------------------+-------------------+
+|              | L5                          | ✔      | ✖    | ✖         | stm32_fsdev            |                   |
+|              +----+------------------------+--------+------+-----------+------------------------+-------------------+
+|              | U5 | 535, 545               | ✔      |      | ✖         | stm32_fsdev            |                   |
+|              |    +------------------------+--------+------+-----------+------------------------+-------------------+
+|              |    | 575, 585               | ✔      | ✔    | ✖         | dwc2                   |                   |
+|              |    +------------------------+--------+------+-----------+------------------------+-------------------+
+|              |    | 59x,5Ax,5Fx,5Gx        | ✔      | ✔    | ✔         | dwc2                   |                   |
+|              +----+------------------------+--------+------+-----------+------------------------+-------------------+
+|              | WBx5                        | ✔      | ✖    | ✖         | stm32_fsdev            |                   |
++--------------+-----------------------------+--------+------+-----------+------------------------+-------------------+
+| TI           | MSP430                      | ✔      | ✖    | ✖         | msp430x5xx             |                   |
+|              +-----------------------------+--------+------+-----------+------------------------+-------------------+
+|              | MSP432E4                    | ✔      |      | ✖         | musb                   |                   |
+|              +-----------------------------+--------+------+-----------+------------------------+-------------------+
+|              | TM4C123                     | ✔      |      | ✖         | musb                   |                   |
++--------------+-----------------------------+--------+------+-----------+------------------------+-------------------+
+| ValentyUSB   | eptri                       | ✔      | ✖    | ✖         | eptri                  |                   |
++--------------+-----------------------------+--------+------+-----------+------------------------+-------------------+
+| WCH          | CH32F20x                    | ✔      |      | ✔         | ch32_usbhs             |                   |
+|              +-----------------------------+--------+------+-----------+------------------------+-------------------+
+|              | CH32V20x                    | ✔      |      | ✖         | stm32_fsdev/ch32_usbfs |                   |
+|              +-----------------------------+--------+------+-----------+------------------------+-------------------+
+|              | CH32V307                    | ✔      |      | ✔         | ch32_usbfs/hs          |                   |
++--------------+-----------------------------+--------+------+-----------+------------------------+-------------------+
 
-  - `Supported Devices`_
-  - `Getting Started`_
-  - `Dependencies`_
-  - `Concurrency`_
+Table Legend
+------------
 
-- `Contributing`_
+========= =========================
+✔         Supported
+⚠         Partial support
+✖         Not supported by hardware
+\[empty\] Unknown
+========= =========================
 
-  - `Code of Conduct`_
-  - `Structure`_
-  - `Porting`_
 
-.. |Build Status| image:: https://github.com/hathach/tinyusb/actions/workflows/cmake_arm.yml/badge.svg
+.. |Build Status| image:: https://github.com/hathach/tinyusb/actions/workflows/build.yml/badge.svg
    :target: https://github.com/hathach/tinyusb/actions
+.. |CircleCI Status| image:: https://dl.circleci.com/status-badge/img/circleci/4AYHvUhFxdnY4rA7LEsdqW/QmrpoL2AjGqetvFQNqtWyq/tree/master.svg?style=svg
+   :target: https://dl.circleci.com/status-badge/redirect/circleci/4AYHvUhFxdnY4rA7LEsdqW/QmrpoL2AjGqetvFQNqtWyq/tree/master
 .. |Documentation Status| image:: https://readthedocs.org/projects/tinyusb/badge/?version=latest
    :target: https://docs.tinyusb.org/en/latest/?badge=latest
 .. |Fuzzing Status| image:: https://oss-fuzz-build-logs.storage.googleapis.com/badges/tinyusb.svg
@@ -205,15 +251,12 @@ Docs
    :target: https://opensource.org/licenses/MIT
 
 
-.. _Uses: docs/info/uses.rst
 .. _Changelog: docs/info/changelog.rst
 .. _Contributors: CONTRIBUTORS.rst
-.. _Reference: docs/reference/index.rst
-.. _Supported Devices: docs/reference/supported.rst
 .. _Getting Started: docs/reference/getting_started.rst
+.. _Supported Boards: docs/reference/boards.rst
 .. _Dependencies: docs/reference/dependencies.rst
 .. _Concurrency: docs/reference/concurrency.rst
 .. _Contributing: docs/contributing/index.rst
 .. _Code of Conduct: CODE_OF_CONDUCT.rst
-.. _Structure: docs/contributing/structure.rst
 .. _Porting: docs/contributing/porting.rst