Merge remote-tracking branch 'origin/master' into add-ch58x-usbfs

5 files changed, 359 insertions, 2 deletions

diff --git a/docs/reference/boards.rst b/docs/reference/boards.rst
index 517c479fe..7ea9c228b 100644
--- a/docs/reference/boards.rst
+++ b/docs/reference/boards.rst
@@ -221,6 +221,7 @@ nrf52840dk                   Nordic nRF52840DK                      nrf       ht
 nrf52840dongle               Nordic nRF52840 Dongle                 nrf       https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-Dongle
 nrf5340dk                    Nordic nRF5340 DK                      nrf       https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF5340-DK
 nrf54h20dk                   Nordic nRF54H20 DK                     nrf       https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF5340-DK
+nrf54lm20dk                  Nordic nRF54LM20 DK                    nrf       https://www.nordicsemi.com/Products/Development-hardware/nRF54LM20-DK
 ===========================  =====================================  ========  ==============================================================================  ======
 
 Raspberry Pi
@@ -264,7 +265,8 @@ STMicroelectronics
 ===================  =================================  =========  =================================================================  ======
 Board                Name                               Family     URL                                                                Note
 ===================  =================================  =========  =================================================================  ======
-stm32c071nucleo      STM32C071 Nucleo                   stm32c0    https://www.st.com/en/evaluation-tools/nucleo-g071rb.html
+stm32c071nucleo      STM32C071 Nucleo                   stm32c0    https://www.st.com/en/evaluation-tools/nucleo-c071rb.html
+stm32c542nucleo      STM32C542 Nucleo                   stm32c5    https://www.st.com/en/evaluation-tools/nucleo-c542rc.html
 stm32f070rbnucleo    STM32 F070 Nucleo                  stm32f0    https://www.st.com/en/evaluation-tools/nucleo-f070rb.html
 stm32f072disco       STM32 F072 Discovery               stm32f0    https://www.st.com/en/evaluation-tools/32f072bdiscovery.html
 stm32f072eval        STM32 F072 Eval                    stm32f0    https://www.st.com/en/evaluation-tools/stm32072b-eval.html
diff --git a/docs/reference/class_drivers.rst b/docs/reference/class_drivers.rst
new file mode 100644
index 000000000..4a101fabc
--- /dev/null
+++ b/docs/reference/class_drivers.rst
@@ -0,0 +1,316 @@
+***************
+Class Drivers
+***************
+
+USB Class Drivers implement specific USB device classes (CDC, HID, MSC, MIDI, Audio, etc.) and are the main interface between the USB core and application code.
+
+MIDI 2.0 Device Driver
+=======================
+
+Overview
+--------
+
+The MIDI 2.0 Device driver enables TinyUSB to act as a USB MIDI 2.0 device. It implements both Alt Setting 0 (MIDI 1.0 fallback) and Alt Setting 1 (native UMP) as required by the USB-MIDI 2.0 specification.
+
+**Key Features:**
+
+- **Dual Alt Settings**: Alt 0 (MIDI 1.0) and Alt 1 (UMP native) per USB-MIDI 2.0 spec
+- **Protocol Negotiation**: Endpoint Discovery, Config Request/Notify, Function Block Discovery
+- **Group Terminal Block**: Served via GET_DESCRIPTOR automatically
+- **Atomic UMP Framing**: Read/write with correct message boundaries
+- **Memory Safe**: No dynamic allocation, static instances
+
+Configuration
+-------------
+
+Enable MIDI 2.0 Device support in ``tusb_config.h``:
+
+.. code-block:: c
+
+   #define CFG_TUD_ENABLED       1
+   #define CFG_TUD_MIDI2         1
+
+Optional configuration:
+
+.. code-block:: c
+
+   #define CFG_TUD_MIDI2_TX_BUFSIZE          256
+   #define CFG_TUD_MIDI2_RX_BUFSIZE          256
+   #define CFG_TUD_MIDI2_TX_EPSIZE           64
+   #define CFG_TUD_MIDI2_RX_EPSIZE           64
+   #define CFG_TUD_MIDI2_NUM_GROUPS          1     // 1..16
+   #define CFG_TUD_MIDI2_NUM_FUNCTION_BLOCKS 1     // 1..32
+   #define CFG_TUD_MIDI2_EP_NAME             "TinyUSB MIDI 2.0"
+   #define CFG_TUD_MIDI2_PRODUCT_ID          "TinyUSB-MIDI2"
+
+Public API
+----------
+
+Query Functions
+^^^^^^^^^^^^^^^
+
+.. code-block:: c
+
+   bool     tud_midi2_mounted(void);
+   uint32_t tud_midi2_available(void);
+   uint8_t  tud_midi2_alt_setting(void);
+   bool     tud_midi2_negotiated(void);
+   uint8_t  tud_midi2_protocol(void);
+
+I/O Functions
+^^^^^^^^^^^^^
+
+.. code-block:: c
+
+   uint32_t tud_midi2_ump_read(uint32_t* words, uint32_t max_words);
+   uint32_t tud_midi2_ump_write(const uint32_t* words, uint32_t count);
+  uint32_t tud_midi2_packet_read(uint8_t packets[], uint32_t max_packets);
+  uint32_t tud_midi2_packet_write(const uint8_t packets[], uint32_t count);
+
+Callbacks
+^^^^^^^^^
+
+.. code-block:: c
+
+   void tud_midi2_rx_cb(uint8_t itf);
+   void tud_midi2_set_itf_cb(uint8_t itf, uint8_t alt);
+   bool tud_midi2_get_req_itf_cb(uint8_t rhport, const tusb_control_request_t* request);
+
+MIDI 2.0 Host Driver
+=====================
+
+Overview
+--------
+
+The MIDI 2.0 Host driver enables TinyUSB to enumerate and communicate with USB MIDI 2.0 devices. It implements the USB MIDI 2.0 specification, supporting both MIDI 1.0 legacy devices and modern MIDI 2.0 devices with UMP (Universal MIDI Packet) protocol.
+
+**Key Features:**
+
+- **Reactive Architecture**: Auto-detects Alt Setting 1 (MIDI 2.0) capability during enumeration
+- **Auto-Selection**: Automatically selects the highest available protocol and issues SET_INTERFACE to activate Alt Setting 1 when MIDI 2.0 is detected
+- **Transparent Stream Messages**: All data (UMP packets + Stream Messages) flow through callbacks
+- **Memory Safe**: No dynamic allocation, fixed-size instances per device
+
+Configuration
+-------------
+
+Enable MIDI 2.0 Host support in ``tusb_config.h``:
+
+.. code-block:: c
+
+   #define CFG_TUH_ENABLED       1
+   #define CFG_TUH_MIDI2         4    // Number of MIDI 2.0 devices to support
+
+Optional buffer configuration:
+
+.. code-block:: c
+
+   #define CFG_TUH_MIDI2_RX_BUFSIZE  (4 * TUH_EPSIZE_BULK_MAX)
+   #define CFG_TUH_MIDI2_TX_BUFSIZE  (4 * TUH_EPSIZE_BULK_MAX)
+
+Enumeration Lifecycle
+---------------------
+
+When a MIDI 2.0 device is connected, the host stack invokes callbacks in this order:
+
+.. code-block:: none
+
+   Device Connected
+        |
+   [Host detects Alt 0 and Alt 1 descriptors]
+        |
+   tuh_midi2_descriptor_cb()  <- Device detected, NOT yet ready
+        |
+   [Auto-select highest protocol]
+        |
+   tuh_midi2_mount_cb()       <- Device ready to use
+        |
+   [Application can read/write data]
+        |
+   tuh_midi2_rx_cb()          <- Data arrived
+   tuh_midi2_tx_cb()          <- TX buffer space available
+        |
+   [Device disconnects]
+        |
+   tuh_midi2_umount_cb()      <- Device removed
+
+Public API
+----------
+
+Query Functions
+^^^^^^^^^^^^^^^
+
+.. code-block:: c
+
+   bool     tuh_midi2_mounted(uint8_t idx);
+   uint8_t  tuh_midi2_get_protocol_version(uint8_t idx);    // 0=MIDI 1.0, 1=MIDI 2.0
+   uint8_t  tuh_midi2_get_alt_setting_active(uint8_t idx);  // 0 or 1
+   uint8_t  tuh_midi2_get_cable_count(uint8_t idx);
+
+I/O Functions
+^^^^^^^^^^^^^
+
+Read and write UMP (Universal MIDI Packet) data:
+
+.. code-block:: c
+
+   uint32_t tuh_midi2_ump_read(uint8_t idx, uint32_t* words, uint32_t max_words);
+   uint32_t tuh_midi2_ump_write(uint8_t idx, const uint32_t* words, uint32_t count);
+   uint32_t tuh_midi2_write_flush(uint8_t idx);
+
+Callbacks
+---------
+
+Application can define weak callback implementations to respond to device events.
+
+Descriptor Callback
+^^^^^^^^^^^^^^^^^^^
+
+Invoked when device is detected but not yet ready for I/O:
+
+.. code-block:: c
+
+   void tuh_midi2_descriptor_cb(uint8_t idx, const tuh_midi2_descriptor_cb_t *desc_cb_data) {
+     printf("MIDI %s device detected\r\n",
+            desc_cb_data->protocol_version == 0 ? "1.0" : "2.0");
+   }
+
+Mount Callback
+^^^^^^^^^^^^^^
+
+Invoked when device is ready for I/O:
+
+.. code-block:: c
+
+   void tuh_midi2_mount_cb(uint8_t idx, const tuh_midi2_mount_cb_t *mount_cb_data) {
+     printf("Device mounted at idx=%u, protocol=%u, alt_setting=%u\r\n",
+            idx, mount_cb_data->protocol_version, mount_cb_data->alt_setting_active);
+   }
+
+RX Callback
+^^^^^^^^^^^
+
+Invoked when data arrives from device (both UMP packets and Stream Messages):
+
+.. code-block:: c
+
+   void tuh_midi2_rx_cb(uint8_t idx, uint32_t xferred_bytes) {
+     uint32_t words[4];
+     uint32_t n = tuh_midi2_ump_read(idx, words, 4);
+
+     for (uint32_t i = 0; i < n; i++) {
+       uint8_t mt = (words[i] >> 28) & 0x0F;
+       if (mt == 0x0F) {
+         // Stream Message - app handles discovery, negotiation, etc.
+       } else {
+         // Regular MIDI UMP packet
+       }
+     }
+   }
+
+TX Callback
+^^^^^^^^^^^
+
+Invoked when TX buffer space becomes available:
+
+.. code-block:: c
+
+   void tuh_midi2_tx_cb(uint8_t idx, uint32_t xferred_bytes) {
+     // Buffer space available for writing
+   }
+
+Unmount Callback
+^^^^^^^^^^^^^^^^
+
+Invoked when device is disconnected:
+
+.. code-block:: c
+
+   void tuh_midi2_umount_cb(uint8_t idx) {
+     printf("Device at idx=%u disconnected\r\n", idx);
+   }
+
+Complete Example
+----------------
+
+.. code-block:: c
+
+   #include "tusb.h"
+
+   void tuh_midi2_mount_cb(uint8_t idx, const tuh_midi2_mount_cb_t *mount_cb_data) {
+     printf("MIDI 2.0 device mounted\r\n");
+   }
+
+   void tuh_midi2_rx_cb(uint8_t idx, uint32_t xferred_bytes) {
+     uint32_t words[4];
+     uint32_t n = tuh_midi2_ump_read(idx, words, 4);
+
+     for (uint32_t i = 0; i < n; i++) {
+       printf("RX: 0x%08lx\r\n", words[i]);
+     }
+   }
+
+   void tuh_midi2_umount_cb(uint8_t idx) {
+     printf("MIDI 2.0 device disconnected\r\n");
+   }
+
+   int main(void) {
+     board_init();
+
+     tusb_rhport_init_t host_init = {.role = TUSB_ROLE_HOST, .speed = TUSB_SPEED_AUTO};
+     tusb_init(BOARD_TUH_RHPORT, &host_init);
+
+     while (1) {
+       tuh_task();
+     }
+   }
+
+Architecture
+------------
+
+The MIDI 2.0 Host driver uses a **reactive, callback-driven architecture** that mirrors the proven patterns in TinyUSB's existing device drivers (CDC, HID, etc.):
+
+- **Auto-Detection**: Host automatically detects Alt Setting 1 capability
+- **Auto-Selection**: Selects highest protocol available and issues SET_INTERFACE
+- **Transparent I/O**: Stream Messages and UMP packets flow through callbacks
+- **Callback-Driven**: App receives events via callbacks (descriptor, mount, rx, tx, unmount)
+
+Differences from MIDI 1.0 Host
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+
+   * - Aspect
+     - MIDI 1.0 Host
+     - MIDI 2.0 Host
+   * - Alt Settings
+     - Parses only Alt 0
+     - Parses Alt 0 + Alt 1
+   * - Data Format
+     - 4-byte MIDI packets
+     - UMP (32/64/128-bit)
+   * - Version Detection
+     - None
+     - bcdMSC from descriptor
+   * - GTB
+     - N/A
+     - Presence detection
+   * - Stream Messages
+     - N/A
+     - Transparent passthrough
+   * - Callbacks
+     - descriptor_cb, mount_cb, rx_cb, umount_cb
+     - descriptor_cb, mount_cb, rx_cb, tx_cb, umount_cb
+   * - Public API
+     - tuh_midi_*
+     - tuh_midi2_*
+
+Implementation Notes
+--------------------
+
+- All internal state is statically allocated (no dynamic allocation)
+- Endpoint streams use TinyUSB's tu_edpt_stream_t for buffered I/O
+- Protocol version detection via bcdMSC field
+- Alt Setting is automatically selected during mount
+- Compatible with all TinyUSB-supported MCU families
diff --git a/docs/reference/dependencies.rst b/docs/reference/dependencies.rst
index c5b755577..d281e912a 100644
--- a/docs/reference/dependencies.rst
+++ b/docs/reference/dependencies.rst
@@ -59,6 +59,7 @@ hw/mcu/st/cmsis_device_l5                 https://github.com/STMicroelectronics/
 hw/mcu/st/cmsis_device_n6                 https://github.com/STMicroelectronics/cmsis-device-n6.git         7bcdc944fbf7cf5928d3c1d14054ca13261d33ec  stm32n6
 hw/mcu/st/cmsis_device_u5                 https://github.com/STMicroelectronics/cmsis_device_u5.git         6e67187dec98035893692ab2923914cb5f4e0117  stm32u5
 hw/mcu/st/cmsis_device_wb                 https://github.com/STMicroelectronics/cmsis_device_wb.git         cda2cb9fc4a5232ab18efece0bb06b0b60910083  stm32wb
+hw/mcu/st/stm32c5xx-dfp                   https://github.com/STMicroelectronics/stm32c5xx-dfp.git           6d0940882511d9430f83af9bd3da6bcb77f79239  stm32c5
 hw/mcu/st/stm32-mfxstm32l152              https://github.com/STMicroelectronics/stm32-mfxstm32l152.git      7f4389efee9c6a655b55e5df3fceef5586b35f9b  stm32h7
 hw/mcu/st/stm32-tcpp0203                  https://github.com/STMicroelectronics/stm32-tcpp0203.git          9918655bff176ac3046ccf378b5c7bbbc6a38d15  stm32h5 stm32h7rs stm32n6
 hw/mcu/st/stm32c0xx_hal_driver            https://github.com/STMicroelectronics/stm32c0xx_hal_driver.git    c283b143bef6bdaacf64240ee6f15eb61dad6125  stm32c0
@@ -82,13 +83,14 @@ hw/mcu/st/stm32u0xx_hal_driver            https://github.com/STMicroelectronics/
 hw/mcu/st/stm32u5xx_hal_driver            https://github.com/STMicroelectronics/stm32u5xx_hal_driver.git    2c5e2568fbdb1900a13ca3b2901fdd302cac3444  stm32u5
 hw/mcu/st/stm32wbaxx_hal_driver           https://github.com/STMicroelectronics/stm32wbaxx_hal_driver.git   9442fbb71f855ff2e64fbf662b7726beba511a24  stm32wba
 hw/mcu/st/stm32wbxx_hal_driver            https://github.com/STMicroelectronics/stm32wbxx_hal_driver.git    d60dd46996876506f1d2e9abd6b1cc110c8004cd  stm32wb
+hw/mcu/st/stm32c5xx-drivers               https://github.com/STMicroelectronics/stm32c5xx-drivers.git       79b901285a7efeaf87c4c25db81d24cb5d8c9465  stm32c5
 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/ch32v103                       https://github.com/openwch/ch32v103.git                           7578cae0b21f86dd053a1f781b2fc6ab99d0ec17  ch32v10x
 hw/mcu/wch/ch32v20x                       https://github.com/openwch/ch32v20x.git                           c4c38f507e258a4e69b059ccc2dc27dde33cea1b  ch32v20x
 hw/mcu/wch/ch32v307                       https://github.com/openwch/ch32v307.git                           184f21b852cb95eed58e86e901837bc9fff68775  ch32v30x
 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 samd51 samd5x_e5x same5x same7x samg tm4c
-lib/CMSIS_6                               https://github.com/ARM-software/CMSIS_6.git                       6f0a58d01aa9bd2feba212097f9afe7acd991d52  imxrt kinetis_k32l ra stm32n6 lpc51 lpc55 mcx
+lib/CMSIS_6                               https://github.com/ARM-software/CMSIS_6.git                       6f0a58d01aa9bd2feba212097f9afe7acd991d52  imxrt kinetis_k32l ra stm32n6 lpc51 lpc55 mcx stm32c5
 lib/FreeRTOS-Kernel                       https://github.com/FreeRTOS/FreeRTOS-Kernel.git                   cc0e0707c0c748713485b870bb980852b210877f  all
 lib/lwip                                  https://github.com/lwip-tcpip/lwip.git                            159e31b689577dbf69cf0683bbaffbd71fa5ee10  all
 lib/sct_neopixel                          https://github.com/gsteiert/sct_neopixel.git                      e73e04ca63495672d955f9268e003cffe168fcd8  lpc55
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 d3c96eeee..c66ce618f 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -9,7 +9,9 @@ Complete reference documentation for TinyUSB APIs, configuration, and supported
 
    architecture
    usb_concepts
+   class_drivers
    boards
    dependencies
    concurrency
+   device_issues
    glossary