shell/LonganTFReader
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
shell committed 2026-10-11 21:48:59 +08:00
commit b44ce7bd77
2716 files changed
+559005
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

third_party/tinyusb/docs/reference/architecture.rst
Vendored
+282
View File
@@ -0,0 +1,282 @@
************
Architecture
************
This document explains TinyUSB's internal architecture, design principles, and how different components work together.
Design Principles
=================
Memory Safety
-------------
TinyUSB is designed for resource-constrained embedded systems with strict memory requirements:
TinyUSB uses **no dynamic allocation** - all memory is statically allocated at compile time for predictability. All buffers have bounded, compile-time defined sizes to prevent overflow issues. The TinyUSB core avoids heap allocation, resulting in **predictable memory usage** where consumption is fully deterministic.
Thread Safety
-------------
TinyUSB achieves thread safety through a deferred interrupt model:
- **ISR deferral**: USB interrupts are captured and deferred to task context
- **Single-threaded processing**: All USB protocol handling occurs in task context
- **Queue-based design**: Events are queued from ISR and processed in ``tud_task()``
- **RTOS integration**: Proper semaphore/mutex usage for shared resources
Portability
-----------
The stack is designed to work across diverse microcontroller families:
- **Hardware abstraction**: MCU-specific code isolated in portable drivers
- **OS abstraction**: RTOS dependencies isolated in OSAL layer
- **Modular design**: Features can be enabled/disabled at compile time
- **Standard compliance**: Strict adherence to USB specifications
Core Architecture
=================
Layer Structure
---------------
TinyUSB follows a layered architecture from hardware to application:
.. figure:: ../assets/stack.svg
:width: 500px
:align: left
:alt: stackup
.. raw:: html
<div class="clear-both"></div>
Component Overview
------------------
- **Application Layer**: Your main application code that uses TinyUSB APIs.
- **Class Drivers**: Implement specific USB device classes (CDC, HID, MSC, etc.) and handle class-specific requests.
- **Device/Host Core**: Implements USB protocol state machines, endpoint management, and core USB functionality.
- **OS Abstraction**: Provides threading primitives and synchronization for different RTOS environments.
- **Device/Host Controller Driver**: drivers that interface with MCU USB peripherals. Several MCUs may share a common driver.
Device Stack Architecture
=========================
This section is concerned with the **Device Stack**, i.e., the component of TinyUSB used in USB devices (that talk to a USB host).
Core Components
---------------
**Device Controller Driver (DCD)**:
- MCU-specific USB device peripheral driver
- Handles endpoint configuration and data transfers
- Abstracts hardware differences between MCU families
- Located in ``src/portable/VENDOR/USBIP/``
**USB Device Core (USBD)**:
- Implements USB device state machine
- Handles standard USB requests (Chapter 9)
- Manages device configuration and enumeration
- Located in ``src/device/``
**Class Drivers**:
- Implement USB class specifications
- Handle class-specific requests and data transfer
- Provide application APIs
- Located in ``src/class/*/``
Data Flow
---------
**Control Transfers (Setup Requests)**:
.. code-block:: none
USB Bus → DCD → USBD Core → Class Driver → Application
↓
Standard requests handled in core
↓
Class-specific requests → Class Driver
**Data Transfers**:
.. code-block:: none
Application → Class Driver → USBD Core → DCD → USB Bus
USB Bus → DCD → USBD Core → Class Driver → Application
Event Processing
----------------
TinyUSB uses a deferred interrupt model for thread safety:
1. **Interrupt Occurs**: USB hardware generates interrupt
2. **ISR Handler**: ``dcd_int_handler()`` captures event, minimal processing
3. **Event Queuing**: Events queued for later processing
4. **Task Processing**: ``tud_task()`` (called by application code) processes queued events
5. **Callback Execution**: Application callbacks executed in task context
.. code-block:: none
USB IRQ → ISR → Event Queue → tud_task() → Class Callbacks → Application
Host Stack Architecture
=======================
This section is concerned with the **Host Stack**, i.e., the component of TinyUSB used in USB hosts, managing connected USB devices.
Core Components
---------------
**Host Controller Driver (HCD)**:
- MCU-specific USB host peripheral driver
- Manages USB pipes and data transfers
- Handles host controller hardware
- Located in ``src/portable/VENDOR/FAMILY/``
**USB Host Core (USBH)**:
- Implements USB host functionality
- Manages device enumeration and configuration
- Handles pipe management and scheduling
- Located in ``src/host/``
**Hub Driver**:
- Manages USB hub devices
- Handles port management and device detection
- Supports multi-level hub topologies
- Located in ``src/host/``
Device Enumeration
------------------
The host stack follows USB enumeration process:
1. **Device Detection**: Hub or root hub detects device connection
2. **Reset and Address**: Reset device, assign unique address
3. **Descriptor Retrieval**: Get device, configuration, and class descriptors
4. **Driver Matching**: Find appropriate class driver for device
5. **Configuration**: Configure device and start communication
6. **Class Operation**: Normal class-specific communication
.. code-block:: none
Device Connect → Reset → Get Descriptors → Load Driver → Configure → Operate
Class Architecture
==================
Common Class Structure
----------------------
All USB classes follow a similar architecture:
**Device Classes**:
- ``*_device.c``: Device-side implementation
- ``*_device.h``: Device API definitions
- Implement class-specific descriptors
- Handle class requests and data transfer
**Host Classes**:
- ``*_host.c``: Host-side implementation
- ``*_host.h``: Host API definitions
- Manage connected devices of this class
- Provide application interface
Class Driver Interface
----------------------
See ``usbd.c``.
**Required Functions**:
- ``init()``: Initialize class driver
- ``reset()``: Reset class state
- ``open()``: Configure class endpoints
- ``control_xfer_cb()``: Handle control requests
- ``xfer_cb()``: Handle data transfer completion
**Optional Functions**:
- ``close()``: Clean up class resources
- ``deinit()``: Deinitialize class driver
- ``sof()``: Start-of-frame processing
- ``xfer_isr()``: Called from USB ISR context on transfer completion. Data will get queued for ``xfer_cb()`` only if this returns ``false``.
Descriptor Management
---------------------
Each class is responsible for:
- **Interface Descriptors**: Define class type and endpoints
- **Class-Specific Descriptors**: Additional class requirements
- **Endpoint Descriptors**: Define data transfer characteristics
Memory Management
=================
Static Allocation Model
-----------------------
TinyUSB uses only static memory allocation; it allocates fixed-size endpoint buffers for each configured endpoint, static buffers for class-specific data handling, a fixed buffer dedicated to control transfers, and static event queues for deferred interrupt processing.
Buffer Management
-----------------
**Endpoint Buffers**:
- Allocated per endpoint at compile time
- Size defined by ``CFG_TUD_*_EP_BUFSIZE`` macros
- Used for USB data transfers
**FIFO Buffers**:
- Ring buffers for streaming data
- Size defined by ``CFG_TUD_*_RX/TX_BUFSIZE`` macros
- Separate read/write pointers
Threading Model
===============
Task-Based Design
-----------------
TinyUSB uses a cooperative task model; it provides main tasks - ``tud_task()`` for device and ``tuh_task()`` for host operation. These tasks must be called regularly (typically less than 1ms intervals) to ensure all USB events are processed in task context, where application callbacks also execute.
RTOS Integration
----------------
**Bare Metal**:
- Application calls ``tud_task()`` in main loop
- No threading primitives needed
- Simplest integration method
**FreeRTOS**:
- USB task runs at high priority
- Semaphores used for synchronization
- Queue for inter-task communication
**Other RTOS**:
- Similar patterns with RTOS-specific primitives
- OSAL layer abstracts RTOS differences
Interrupt Handling
------------------
**Interrupt Service Routine**:
- Minimal processing in ISR
- Event capture and queuing only
- Quick return to avoid blocking
**Deferred Processing**:
- All complex processing in task context
- Thread-safe access to data structures
- Application callbacks in known context
Memory Usage Patterns
---------------------
**Flash Memory**:
- Core stack: 8-15KB depending on features
- Each class: 1-4KB additional
- Portable driver: 2-8KB depending on MCU
**RAM Usage**:
- Core stack: 1-2KB
- Endpoint buffers: User configurable
- Class buffers: Depends on configuration
third_party/tinyusb/docs/reference/boards.rst
Vendored
+379
View File
@@ -0,0 +1,379 @@
****************
Supported Boards
****************
The board support code is only used for self-contained examples and testing. It is not used when TinyUSB is part of a larger project.
It is responsible for getting the MCU started and the USB peripheral clocked with minimal of on-board devices
- One LED : for status
- One Button : to get input from user
- One UART : needed for logging with LOGGER=uart, maybe required for host/dual examples
Following boards are supported
Analog Devices
--------------
============= ================ ======== ================================================================================================================= ======
Board Name Family URL Note
============= ================ ======== ================================================================================================================= ======
apard32690 APARD32690-SL maxim https://www.analog.com/en/resources/evaluation-hardware-and-software/evaluation-boards-kits/ad-apard32690-sl.html
max32650evkit MAX32650 EVKIT maxim https://www.analog.com/en/resources/evaluation-hardware-and-software/evaluation-boards-kits/max32650-evkit.html
max32650fthr MAX32650 Feather maxim https://www.analog.com/en/resources/evaluation-hardware-and-software/evaluation-boards-kits/max32650fthr.html
max32651evkit MAX32651 EVKIT maxim https://www.analog.com/en/resources/evaluation-hardware-and-software/evaluation-boards-kits/max32651-evkit.html
max32666evkit MAX32666 EVKIT maxim https://www.analog.com/en/resources/evaluation-hardware-and-software/evaluation-boards-kits/max32666evkit.html
max32666fthr MAX32666 Feather maxim https://www.analog.com/en/resources/evaluation-hardware-and-software/evaluation-boards-kits/max32666fthr.html
max32690evkit MAX32690 EVKIT maxim https://www.analog.com/en/resources/evaluation-hardware-and-software/evaluation-boards-kits/max32690evkit.html
max78002evkit MAX78002 EVKIT maxim https://www.analog.com/en/resources/evaluation-hardware-and-software/evaluation-boards-kits/max78002evkit.html
============= ================ ======== ================================================================================================================= ======
Artery
------
========================= ============================= ============= ==================================================== ======
Board Name Family URL Note
========================= ============================= ============= ==================================================== ======
at_start_f402 AT-START-F402 at32f402_405 https://www.arterychip.com/en/product/AT32F402.jsp
at_start_f405 AT-START-F405 at32f402_405 https://www.arterychip.com/en/product/AT32F405.jsp
at32f403a_weact_blackpill WeAct BlackPill AT32F403ACGU7 at32f403a_407 https://github.com/WeActStudio/WeActStudio.BlackPill
at_start_f403a AT-START-F403a at32f403a_407 https://www.arterychip.com/en/product/AT32F403.jsp
at_start_f407 AT-START-F407 at32f403a_407 https://www.arterychip.com/en/product/AT32F407.jsp
at_start_f413 AT-START-F413 at32f413 https://www.arterychip.com/en/product/AT32F413.jsp
at_start_f415 AT-START-F415 at32f415 https://www.arterychip.com/en/product/AT32F415.jsp
at_start_f423 AT-START-F423 at32f423 https://www.arterychip.com/en/product/AT32F423.jsp
at_start_f425 AT-START-F425 at32f425 https://www.arterychip.com/en/product/AT32F425.jsp
at_start_f435 AT-START-F435 at32f435_437 https://www.arterychip.com/en/product/AT32F435.jsp
at_start_f437 AT-START-F437 at32f435_437 https://www.arterychip.com/en/product/AT32F437.jsp
at_start_f455 AT-START-F455 at32f45x https://www.arterychip.com/en/product/AT32F455.jsp
at_start_f456 AT-START-F456 at32f45x https://www.arterychip.com/en/product/AT32F456.jsp
at_start_f457 AT-START-F457 at32f45x https://www.arterychip.com/en/product/AT32F457.jsp
========================= ============================= ============= ==================================================== ======
Bridgetek
---------
========= ========= ======== ===================================== ======
Board Name Family URL Note
========= ========= ======== ===================================== ======
mm900evxb MM900EVxB ft9xx https://brtchip.com/product/mm900ev1b
========= ========= ======== ===================================== ======
Espressif
---------
========================= ============================== ========= ======================================================================================================== ======
Board Name Family URL Note
========================= ============================== ========= ======================================================================================================== ======
adafruit_feather_esp32_v2 Adafruit Feather ESP32 v2 espressif https://www.adafruit.com/product/5400
adafruit_feather_esp32c6 Adafruit Feather EPS32-C6 espressif https://www.adafruit.com/product/5933
adafruit_feather_esp32s2 Adafruit Feather ESP32S2 espressif https://www.adafruit.com/product/5000
adafruit_feather_esp32s3 Adafruit Feather ESP32S3 espressif https://www.adafruit.com/product/5323
adafruit_magtag_29gray Adafruit MagTag 2.9" Grayscale espressif https://www.adafruit.com/product/4800
adafruit_metro_esp32s2 Adafruit Metro ESP32-S2 espressif https://www.adafruit.com/product/4775
espressif_addax_1 Espresif Addax-1 espressif n/a
espressif_c3_devkitc Espresif C3 DevKitC espressif https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32c3/esp32-c3-devkitc-02/index.html
espressif_c6_devkitc Espresif C6 DevKitC espressif https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32c6/esp32-c6-devkitc-1/index.html
espressif_kaluga_1 Espresif Kaluga 1 espressif https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s2/esp32-s2-kaluga-1/index.html
espressif_p4_function_ev Espresif P4 Function EV espressif https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32p4/esp32-p4-function-ev-board/index.html
espressif_s2_devkitc Espresif S2 DevKitC espressif https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s2/esp32-s2-devkitc-1/index.html
espressif_s3_devkitc Espresif S3 DevKitC espressif https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s3/esp32-s3-devkitc-1/index.html
espressif_s3_devkitm Espresif S3 DevKitM espressif https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s3/esp32-s3-devkitm-1/index.html
espressif_saola_1 Espresif S2 Saola 1 espressif https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s2/esp32-s2-saola-1/index.html
========================= ============================== ========= ======================================================================================================== ======
GigaDevice
----------
================== ================== ========= ============================= ======
Board Name Family URL Note
================== ================== ========= ============================= ======
sipeed_longan_nano Sipeed Longan Nano gd32vf103 https://longan.sipeed.com/en/
================== ================== ========= ============================= ======
HPMicro
-------
=========== =========== ======== ========================================================================== ======
Board Name Family URL Note
=========== =========== ======== ========================================================================== ======
hpm6750evk2 HPM6750EVK2 hpmicro https://hpm-sdk.readthedocs.io/en/v1.6.0/boards/hpm6750evk2/README_en.html
=========== =========== ======== ========================================================================== ======
Infineon
--------
============= ================= ======== ============================================================================= ======
Board Name Family URL Note
============= ================= ======== ============================================================================= ======
xmc4500_relax XMC4500 relax kit xmc4000 https://www.infineon.com/cms/en/product/evaluation-boards/kit_xmc45_relax_v1/
xmc4700_relax XMC4700 relax kit xmc4000 https://www.infineon.com/cms/en/product/evaluation-boards/kit_xmc47_relax_v1/
============= ================= ======== ============================================================================= ======
Microchip
---------
========================= =================================== ========== ================================================================================= ======
Board Name Family URL Note
========================= =================================== ========== ================================================================================= ======
olimex_emz64 Olimex PIC32-EMZ64 pic32mz https://www.olimex.com/Products/PIC/Development/PIC32-EMZ64/open-source-hardware
olimex_hmz144 Olimex PIC32-HMZ144 pic32mz https://www.olimex.com/Products/PIC/Development/PIC32-HMZ144/open-source-hardware
cynthion_d11 Great Scott Gadgets Cynthion samd11 https://greatscottgadgets.com/cynthion/
samd11_xplained SAMD11 Xplained Pro samd11 https://www.microchip.com/en-us/development-tool/ATSAMD11-XPRO
atsamd21_xpro SAMD21 Xplained Pro samd2x_l2x https://www.microchip.com/DevelopmentTools/ProductDetails/ATSAMD21-XPRO
atsaml21_xpro SAML21 Xplained Pro samd2x_l2x https://www.microchip.com/en-us/development-tool/atsaml21-xpro-b
circuitplayground_express Adafruit Circuit Playground Express samd2x_l2x https://www.adafruit.com/product/3333
curiosity_nano SAMD21 Curiosty Nano samd2x_l2x https://www.microchip.com/en-us/development-tool/dm320119
cynthion_d21 Great Scott Gadgets Cynthion samd2x_l2x https://greatscottgadgets.com/cynthion/
feather_m0_express Adafruit Feather M0 Express samd2x_l2x https://www.adafruit.com/product/3403
itsybitsy_m0 Adafruit ItsyBitsy M0 samd2x_l2x https://www.adafruit.com/product/3727
metro_m0_express Adafruit Metro M0 Express samd2x_l2x https://www.adafruit.com/product/3505
qtpy Adafruit QT Py samd2x_l2x https://www.adafruit.com/product/4600
saml22_feather SAML22 Feather samd2x_l2x https://github.com/joeycastillo/Feather-Projects/tree/main/SAML22%20Feather
seeeduino_xiao Seeeduino XIAO samd2x_l2x https://wiki.seeedstudio.com/Seeeduino-XIAO/
sensorwatch_m0 SensorWatch samd2x_l2x https://github.com/joeycastillo/Sensor-Watch
sparkfun_samd21_mini_usb SparkFun SAMD21 Mini samd2x_l2x https://www.sparkfun.com/products/13664
trinket_m0 Adafruit Trinket M0 samd2x_l2x https://www.adafruit.com/product/3500
d5035_01 D5035-01 samd5x_e5x https://github.com/RudolphRiedel/USB_CAN-FD
feather_m4_express Adafruit Feather M4 Express samd5x_e5x https://www.adafruit.com/product/3857
itsybitsy_m4 Adafruit ItsyBitsy M4 samd5x_e5x https://www.adafruit.com/product/3800
metro_m4_express Adafruit Metro M4 Express samd5x_e5x https://www.adafruit.com/product/3382
pybadge Adafruit PyBadge samd5x_e5x https://www.adafruit.com/product/4200
pyportal Adafruit PyPortal samd5x_e5x https://www.adafruit.com/product/4116
same54_xplained SAME54 Xplained Pro samd5x_e5x https://www.microchip.com/DevelopmentTools/ProductDetails/ATSAME54-XPRO
same70_qmtech SAME70 QMTech same7x https://www.aliexpress.com/item/1005003173783268.html
same70_xplained SAME70 Xplained same7x https://www.microchip.com/en-us/development-tool/atsame70-xpld
samg55_xplained SAMG55 Xplained Pro samg https://www.microchip.com/DevelopmentTools/ProductDetails/ATSAMG55-XPRO
========================= =================================== ========== ================================================================================= ======
MindMotion
----------
===================== ====================================== ======== =============================================================================================== ======
Board Name Family URL Note
===================== ====================================== ======== =============================================================================================== ======
mm32f327x_mb39 MM32F3273G9P MB-039 mm32 https://www.mindmotion.com.cn/support/development_tools/evaluation_boards/evboard/mm32f3273g9p/
mm32f327x_pitaya_lite DshanMCU Pitaya Lite with MM32F3273G8P mm32 https://gitee.com/weidongshan/DshanMCU-Pitaya-c
===================== ====================================== ======== =============================================================================================== ======
NXP
---
================== ========================================= ============ ========================================================================================================================================================================= ======
Board Name Family URL Note
================== ========================================= ============ ========================================================================================================================================================================= ======
metro_m7_1011 Adafruit Metro M7 1011 imxrt https://www.adafruit.com/product/5600
mimxrt1010_evk i.MX RT1010 Evaluation Kit imxrt https://www.nxp.com/design/design-center/development-boards-and-designs/i-mx-evaluation-and-development-boards/i-mx-rt1010-evaluation-kit:MIMXRT1010-EVK
mimxrt1015_evk i.MX RT1015 Evaluation Kit imxrt https://www.nxp.com/design/design-center/development-boards-and-designs/MIMXRT1015-EVK
mimxrt1020_evk i.MX RT1020 Evaluation Kit imxrt https://www.nxp.com/design/design-center/development-boards-and-designs/MIMXRT1020-EVK
mimxrt1024_evk i.MX RT1024 Evaluation Kit imxrt https://www.nxp.com/design/design-center/development-boards-and-designs/i-mx-evaluation-and-development-boards/i-mx-rt1024-evaluation-kit:MIMXRT1024-EVK
mimxrt1050_evkb i.MX RT1050 Evaluation Kit revB imxrt https://www.nxp.com/part/IMXRT1050-EVKB
mimxrt1060_evk i.MX RT1060 Evaluation Kit revB imxrt https://www.nxp.com/design/design-center/development-boards-and-designs/MIMXRT1060-EVKB
mimxrt1064_evk i.MX RT1064 Evaluation Kit imxrt https://www.nxp.com/design/design-center/development-boards-and-designs/MIMXRT1064-EVK
mimxrt1170_evkb i.MX RT1070 Evaluation Kit imxrt https://www.nxp.com/design/design-center/development-boards-and-designs/i-mx-evaluation-and-development-boards/i-mx-rt1170-evaluation-kit:MIMXRT1170-EVKB
teensy_40 Teensy 4.0 imxrt https://www.pjrc.com/store/teensy40.html
teensy_41 Teensy 4.1 imxrt https://www.pjrc.com/store/teensy41.html
frdm_k64f Freedom K64F kinetis_k https://www.nxp.com/design/design-center/development-boards-and-designs/general-purpose-mcus/freedom-development-platform-for-kinetis-k64-k63-and-k24-mcus:FRDM-K64F
teensy_35 Teensy 3.5 kinetis_k https://www.pjrc.com/store/teensy35.html
frdm_k32l2a4s Freedom K32L2A4S kinetis_k32l https://www.nxp.com/design/design-center/development-boards-and-designs/FRDM-K32L2A4S
frdm_k32l2b Freedom K32L2B3 kinetis_k32l https://www.nxp.com/design/design-center/development-boards-and-designs/general-purpose-mcus/nxp-freedom-development-platform-for-k32-l2b-mcus:FRDM-K32L2B3
kuiic Kuiic kinetis_k32l https://github.com/nxf58843/kuiic
frdm_kl25z fomu kinetis_kl https://www.nxp.com/design/design-center/development-boards-and-designs/general-purpose-mcus/freedom-development-platform-for-kinetis-kl14-kl15-kl24-kl25-mcus:FRDM-KL25Z
lpcxpresso11u37 LPCXpresso11U37 lpc11 https://www.nxp.com/design/design-center/development-boards-and-designs/OM13074
lpcxpresso11u68 LPCXpresso11U68 lpc11 https://www.nxp.com/design/design-center/development-boards-and-designs/OM13058
lpcxpresso1347 LPCXpresso1347 lpc13 https://www.nxp.com/products/no-longer-manufactured/lpcxpresso-board-for-lpc1347:OM13045
lpcxpresso1549 LPCXpresso1549 lpc15 https://www.nxp.com/design/design-center/development-boards-and-designs/OM13056
lpcxpresso1769 LPCXpresso1769 lpc17 https://www.nxp.com/design/design-center/development-boards-and-designs/OM13000
mbed1768 mbed 1768 lpc17 https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/lpc1700-arm-cortex-m3/arm-mbed-lpc1768-board:OM11043
lpcxpresso18s37 LPCXpresso18s37 lpc18 https://www.nxp.com/design/design-center/software/development-software/mcuxpresso-software-and-tools-/lpcxpresso-boards/lpcxpresso18s37-development-board:OM13076
mcb1800 Keil MCB1800 lpc18 https://www.keil.com/arm/mcb1800/
ea4088_quickstart Embedded Artists LPC4088 QuickStart Board lpc40 https://www.embeddedartists.com/products/lpc4088-quickstart-board/
ea4357 Embedded Artists LPC4357 Development Kit lpc43 https://www.embeddedartists.com/products/lpc4357-developers-kit/
lpcxpresso43s67 LPCXpresso43S67 lpc43 https://www.nxp.com/design/design-center/software/development-software/mcuxpresso-software-and-tools-/lpcxpresso-boards/lpcxpresso43s67-development-board:OM13084
lpcxpresso51u68 LPCXpresso51u68 lpc51 https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/lpcxpresso51u68-for-the-lpc51u68-mcus:OM40005
lpcxpresso54114 LPCXpresso54114 lpc54 https://www.nxp.com/design/design-center/software/development-software/mcuxpresso-software-and-tools-/lpcxpresso-boards/lpcxpresso54114-board:OM13089
lpcxpresso54608 LPCXpresso54608 lpc54 https://www.nxp.com/design/design-center/software/development-software/mcuxpresso-software-and-tools-/lpcxpresso-development-board-for-lpc5460x-mcus:OM13092
lpcxpresso54628 LPCXpresso54628 lpc54 https://www.nxp.com/design/design-center/software/development-software/mcuxpresso-software-and-tools-/lpcxpresso-boards/lpcxpresso54628-development-board:OM13098
double_m33_express Double M33 Express lpc55 https://www.crowdsupply.com/steiert-solutions/double-m33-express
lpcxpresso55s28 LPCXpresso55s28 lpc55 https://www.nxp.com/design/design-center/software/development-software/mcuxpresso-software-and-tools-/lpcxpresso-boards/lpcxpresso55s28-development-board:LPC55S28-EVK
lpcxpresso55s69 LPCXpresso55s69 lpc55 https://www.nxp.com/design/design-center/software/development-software/mcuxpresso-software-and-tools-/lpcxpresso-boards/lpcxpresso55s69-development-board:LPC55S69-EVK
mcu_link MCU Link lpc55 https://www.nxp.com/design/design-center/software/development-software/mcuxpresso-software-and-tools-/mcu-link-debug-probe:MCU-LINK
frdm_mcxa153 Freedom MCXA153 mcx https://www.nxp.com/design/design-center/development-boards-and-designs/FRDM-MCXA153
frdm_mcxa156 Freedom MCXA156 mcx https://www.nxp.com/design/design-center/development-boards-and-designs/FRDM-MCXA156
frdm_mcxn947 Freedom MCXN947 mcx https://www.nxp.com/design/design-center/development-boards-and-designs/FRDM-MCXN947
mcxn947brk MCXN947 Breakout mcx n/a
frdm_rw612 FRDM-RW612 rw61x https://www.nxp.com/design/design-center/development-boards-and-designs/FRDM-RW612
================== ========================================= ============ ========================================================================================================================================================================= ======
Nordic Semiconductor
--------------------
=========================== ===================================== ======== ============================================================================== ======
Board Name Family URL Note
=========================== ===================================== ======== ============================================================================== ======
adafruit_clue Adafruit CLUE nrf https://www.adafruit.com/product/4500
arduino_nano33_ble Arduino Nano 33 BLE nrf https://store.arduino.cc/arduino-nano-33-ble
circuitplayground_bluefruit Adafruit Circuit Playground Bluefruit nrf https://www.adafruit.com/product/4333
feather_nrf52840_express Adafruit Feather nRF52840 Express nrf https://www.adafruit.com/product/4062
feather_nrf52840_sense Adafruit Feather nRF52840 Sense nrf https://www.adafruit.com/product/4516
itsybitsy_nrf52840 Adafruit ItsyBitsy nRF52840 Express nrf https://www.adafruit.com/product/4481
nrf52833dk Nordic nRF52833 DK nrf https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52833-DK
nrf52840dk Nordic nRF52840DK nrf https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK
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
------------
================================ ============================================ ============== ========================================================== ======
Board Name Family URL Note
================================ ============================================ ============== ========================================================== ======
raspberrypi_zero Raspberry Pi Zero broadcom_32bit https://www.raspberrypi.org/products/raspberry-pi-zero/
raspberrypi_cm4 Raspberry CM4 broadcom_64bit https://www.raspberrypi.org/products/compute-module-4
raspberrypi_zero2 Raspberry Zero2 broadcom_64bit https://www.raspberrypi.org/products/raspberry-pi-zero-2-w
adafruit_feather_rp2040_usb_host Adafruit Feather RP2040 with USB Type A Host rp2040 https://www.adafruit.com/product/5723
adafruit_fruit_jam Adafruit Fruit Jam - Mini RP2350 rp2040 https://www.adafruit.com/product/6200
adafruit_metro_rp2350 Adafruit Metro RP2350 rp2040 https://www.adafruit.com/product/6003
raspberry_pi_pico Pico rp2040 https://www.raspberrypi.com/products/raspberry-pi-pico/
raspberry_pi_pico2 Pico2 rp2040 https://www.raspberrypi.com/products/raspberry-pi-pico-2/
raspberry_pi_pico_w Pico rp2040 https://www.raspberrypi.com/products/raspberry-pi-pico/
================================ ============================================ ============== ========================================================== ======
Renesas
-------
============== =========================== ======== ================================================================================================================================================================ ======
Board Name Family URL Note
============== =========================== ======== ================================================================================================================================================================ ======
da14695_dk_usb DA14695-00HQDEVKT-U da1469x https://www.renesas.com/en/products/wireless-connectivity/bluetooth-low-energy/da14695-00hqdevkt-u-smartbond-da14695-bluetooth-low-energy-52-usb-development-kit
da1469x_dk_pro DA1469x Development Kit Pro da1469x https://lpccs-docs.renesas.com/um-b-090-da1469x_getting_started/DA1469x_The_hardware/DA1469x_The_hardware.html
portenta_c33 Arduino Portenta C33 ra https://www.arduino.cc/pro/hardware-product-portenta-c33/
ra2a1_ek RA2A1 EK ra https://www.renesas.com/en/products/microcontrollers-microprocessors/ra-cortex-m-mcus/ek-ra2a1-evaluation-kit-ra2a1-mcu-group
ra4m1_ek RA4M1 EK ra https://www.renesas.com/en/products/microcontrollers-microprocessors/ra-cortex-m-mcus/ek-ra4m1-evaluation-kit-ra4m1-mcu-group
ra4m3_ek RA4M3 EK ra https://www.renesas.com/en/products/microcontrollers-microprocessors/ra-cortex-m-mcus/ek-ra4m3-evaluation-kit-ra4m3-mcu-group
ra6m1_ek RA6M1 EK ra https://www.renesas.com/en/products/microcontrollers-microprocessors/ra-cortex-m-mcus/ek-ra6m1-evaluation-kit-ra6m1-mcu-group
ra6m5_ek RA6M5 EK ra https://www.renesas.com/en/products/microcontrollers-microprocessors/ra-cortex-m-mcus/ek-ra6m5-evaluation-kit-ra6m5-mcu-group
ra8m1_ek RA8M1 EK ra https://www.renesas.com/en/products/microcontrollers-microprocessors/ra-cortex-m-mcus/ek-ra8m1-evaluation-kit-ra8m1-mcu-group
uno_r4 Arduino UNO R4 ra https://store-usa.arduino.cc/pages/uno-r4
============== =========================== ======== ================================================================================================================================================================ ======
STMicroelectronics
------------------
=================== ================================= ========= ================================================================= ======
Board Name Family URL Note
=================== ================================= ========= ================================================================= ======
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
stm32f103_bluepill STM32 F103 Bluepill stm32f1 https://stm32-base.org/boards/STM32F103C8T6-Blue-Pill
stm32f103_mini_2 STM32 F103 Mini v2 stm32f1 https://stm32-base.org/boards/STM32F103RCT6-STM32-Mini-V2.0
stm32f103ze_iar IAR STM32 F103ze starter kit stm32f1 n/a
stm32f207nucleo STM32 F207 Nucleo stm32f2 https://www.st.com/en/evaluation-tools/nucleo-f207zg.html
stm32f303disco STM32 F303 Discovery stm32f3 https://www.st.com/en/evaluation-tools/stm32f3discovery.html
feather_stm32f405 Adafruit Feather STM32F405 stm32f4 https://www.adafruit.com/product/4382
pyboardv11 Pyboard v1.1 stm32f4 https://www.adafruit.com/product/2390
stm32f401blackpill STM32 F401 Blackpill stm32f4 https://stm32-base.org/boards/STM32F401CCU6-WeAct-Black-Pill-V1.2
stm32f407blackvet STM32 F407 Blackvet stm32f4 https://stm32-base.org/boards/STM32F407VET6-STM32-F4VE-V2.0
stm32f407disco STM32 F407 Discovery stm32f4 https://www.st.com/en/evaluation-tools/stm32f4discovery.html
stm32f411blackpill STM32 F411 Blackpill stm32f4 https://stm32-base.org/boards/STM32F411CEU6-WeAct-Black-Pill-V2.0
stm32f411disco STM32 F411 Discovery stm32f4 https://www.st.com/en/evaluation-tools/32f411ediscovery.html
stm32f412disco STM32 F412 Discovery stm32f4 https://www.st.com/en/evaluation-tools/32f412gdiscovery.html
stm32f412nucleo STM32 F412 Nucleo stm32f4 https://www.st.com/en/evaluation-tools/nucleo-f412zg.html
stm32f439nucleo STM32 F439 Nucleo stm32f4 https://www.st.com/en/evaluation-tools/nucleo-f439zi.html
stlinkv3mini Stlink-v3 mini stm32f7 https://www.st.com/en/development-tools/stlink-v3mini.html
stm32f723disco STM32 F723 Discovery stm32f7 https://www.st.com/en/evaluation-tools/32f723ediscovery.html
stm32f746disco STM32 F746 Discovery stm32f7 https://www.st.com/en/evaluation-tools/32f746gdiscovery.html
stm32f746nucleo STM32 F746 Nucleo stm32f7 https://www.st.com/en/evaluation-tools/nucleo-f746zg.html
stm32f767nucleo STM32 F767 Nucleo stm32f7 https://www.st.com/en/evaluation-tools/nucleo-f767zi.html
stm32f769disco STM32 F769 Discovery stm32f7 https://www.st.com/en/evaluation-tools/32f769idiscovery.html
stm32g0b1nucleo STM32 G0B1 Nucleo stm32g0 https://www.st.com/en/evaluation-tools/nucleo-g0b1re.html
b_g474e_dpow1 STM32 B-G474E-DPOW1 Discovery kit stm32g4 https://www.st.com/en/evaluation-tools/b-g474e-dpow1.html
stm32g474nucleo STM32 G474 Nucleo stm32g4 https://www.st.com/en/evaluation-tools/nucleo-g474re.html
stm32g491nucleo STM32 G491 Nucleo stm32g4 https://www.st.com/en/evaluation-tools/nucleo-g491re.html
stm32h503nucleo STM32 H503 Nucleo stm32h5 https://www.st.com/en/evaluation-tools/nucleo-h503rb.html
stm32h533nucleo STM32 H533 Nucleo stm32h5 https://www.st.com/en/evaluation-tools/nucleo-h533re.html
stm32h563nucleo STM32 H563 Nucleo stm32h5 https://www.st.com/en/evaluation-tools/nucleo-h563zi.html
stm32h573i_dk STM32 H573i Discovery stm32h5 https://www.st.com/en/evaluation-tools/stm32h573i-dk.html
daisyseed Daisy Seed stm32h7 https://electro-smith.com/products/daisy-seed
stm32h723nucleo STM32 H723 Nucleo stm32h7 https://www.st.com/en/evaluation-tools/nucleo-h723zg.html
stm32h743_weact STM32 H743 WeAct board stm32h7 https://github.com/WeActStudio/MiniSTM32H7xx
stm32h743eval STM32 H743 Eval stm32h7 https://www.st.com/en/evaluation-tools/stm32h743i-eval.html
stm32h743nucleo STM32 H743 Nucleo stm32h7 https://www.st.com/en/evaluation-tools/nucleo-h743zi.html
stm32h745disco STM32 H745 Discovery stm32h7 https://www.st.com/en/evaluation-tools/stm32h745i-disco.html
stm32h747disco STM32 H747 Discovery stm32h7 https://www.st.com/en/evaluation-tools/stm32h747i-disco.html
stm32h750_weact STM32 H750 WeAct stm32h7 https://www.adafruit.com/product/5032
stm32h750bdk STM32 H750b Discovery Kit stm32h7 https://www.st.com/en/evaluation-tools/stm32h750b-dk.html
waveshare_openh743i Waveshare Open H743i stm32h7 https://www.waveshare.com/openh743i-c-standard.htm
stm32h7s3nucleo STM32 H7S3L8 Nucleo stm32h7rs https://www.st.com/en/evaluation-tools/nucleo-h7s3l8.html
stm32l052dap52 STM32 L052 DAP stm32l0 n/a
stm32l0538disco STM32 L0538 Discovery stm32l0 https://www.st.com/en/evaluation-tools/32l0538discovery.html
stm32l412nucleo STM32 L412 Nucleo stm32l4 https://www.st.com/en/evaluation-tools/nucleo-l412kb.html
stm32l476disco STM32 L476 Disco stm32l4 https://www.st.com/en/evaluation-tools/32l476gdiscovery.html
stm32l496nucleo STM32 L496 Nucleo stm32l4 https://www.st.com/en/evaluation-tools/nucleo-l496ZG-P.html
stm32l4p5nucleo STM32 L4P5 Nucleo stm32l4 https://www.st.com/en/evaluation-tools/nucleo-l4p5zg.html
stm32l4r5nucleo STM32 L4R5 Nucleo stm32l4 https://www.st.com/en/evaluation-tools/nucleo-l4r5zi.html
stm32n6570dk STM32 N6570-DK stm32n6 https://www.st.com/en/evaluation-tools/stm32n6570-dk.html
stm32n657nucleo STM32 N657X0-Q Nucleo stm32n6 https://www.st.com/en/evaluation-tools/nucleo-n657x0-q.html
stm32u083cdk STM32U083C-DK Discovery Kit stm32u0 https://www.st.com/en/evaluation-tools/stm32u083c-dk.html
stm32u083nucleo NUCLEO-U083RC stm32u0 https://www.st.com/en/evaluation-tools/nucleo-u083rc.html
b_u585i_iot2a STM32 B-U585i IOT2A Discovery kit stm32u5 https://www.st.com/en/evaluation-tools/b-u585i-iot02a.html
stm32u545nucleo STM32 U545 Nucleo stm32u5 https://www.st.com/en/evaluation-tools/nucleo-u545re-q.html
stm32u575eval STM32 U575 Eval stm32u5 https://www.st.com/en/evaluation-tools/stm32u575i-ev.html
stm32u575nucleo STM32 U575 Nucleo stm32u5 https://www.st.com/en/evaluation-tools/nucleo-u575zi-q.html
stm32u5a5nucleo STM32 U5a5 Nucleo stm32u5 https://www.st.com/en/evaluation-tools/nucleo-u5a5zj-q.html
stm32wb55nucleo STM32 P-NUCLEO-WB55 stm32wb https://www.st.com/en/evaluation-tools/p-nucleo-wb55.html
stm32wba_nucleo STM32 NUCLEO-WBA65RI stm32wba https://www.st.com/en/evaluation-tools/nucleo-wba65ri.html
=================== ================================= ========= ================================================================= ======
Sunxi
-----
======= ================= ======== ========================================= ======
Board Name Family URL Note
======= ================= ======== ========================================= ======
f1c100s Lctech Pi F1C200s f1c100s https://linux-sunxi.org/Lctech_Pi_F1C200s
======= ================= ======== ========================================= ======
Texas Instruments
-----------------
================= ===================== ======== ========================================= ======
Board Name Family URL Note
================= ===================== ======== ========================================= ======
msp_exp430f5529lp MSP430F5529 LaunchPad msp430 https://www.ti.com/tool/MSP-EXP430F5529LP
msp_exp432e401y MSP432E401Y LaunchPad msp432e4 https://www.ti.com/tool/MSP-EXP432E401Y
ek_tm4c123gxl TM4C123G LaunchPad tm4c https://www.ti.com/tool/EK-TM4C123GXL
ek_tm4c1294xl TM4C1294 LaunchPad tm4c https://www.ti.com/tool/EK-TM4C1294XL
================= ===================== ======== ========================================= ======
Tomu
----
======= ====== ======== ========================= ======
Board Name Family URL Note
======= ====== ======== ========================= ======
fomu fomu fomu https://tomu.im/fomu.html
======= ====== ======== ========================= ======
WCH
---
================== ============================= ======== ===================================================================== ======
Board Name Family URL Note
================== ============================= ======== ===================================================================== ======
ch32f205r-r0 CH32F205r-r0 ch32f20x https://github.com/openwch/ch32f20x
ch32v103c_bluepill CH32V103C8T6-Bluepill ch32v10x https://stm32-base.org/boards/STM32F103C8T6-Blue-Pill
ch32v103r_r1_1v0 CH32V103R-R1-1v1 ch32v10x https://github.com/openwch/ch32v103/tree/main/SCHPCB/CH32V103R-R1-1v1
ch32v203c_r0_1v0 CH32V203C-R0-1v0 ch32v20x https://github.com/openwch/ch32v20x/tree/main/SCHPCB/CH32V203C-R0
ch32v203g_r0_1v0 CH32V203G-R0-1v0 ch32v20x https://github.com/openwch/ch32v20x/tree/main/SCHPCB/CH32V203C-R0
nanoch32v203 nanoCH32V203 ch32v20x https://github.com/wuxx/nanoCH32V203
ch32v307v_r1_1v0 CH32V307V-R1-1v0 ch32v30x https://github.com/openwch/ch32v307/tree/main/SCHPCB/CH32V307V-R1-1v0
nanoch32v305 nanoCH32V305 ch32v30x https://github.com/wuxx/nanoCH32V305
ch582m_evt CH582M-EVT evaluation board ch583 https://www.wch-ic.com/products/CH582.html
yd-ch582m yd-ch582m from vcc-gnd studio ch583 http://vcc-gnd.com/
================== ============================= ======== ===================================================================== ======
third_party/tinyusb/docs/reference/class_drivers.rst
Vendored
+316
View File
@@ -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
third_party/tinyusb/docs/reference/concurrency.rst
Vendored
+42
View File
@@ -0,0 +1,42 @@
***********
Concurrency
***********
The TinyUSB library is designed to operate on single-core MCUs with multi-threaded applications in mind. Interaction with interrupts is especially important to pay attention to.
It is compatible with optionally using an RTOS.
General
-------
When writing code, keep in mind that the OS (if using an RTOS) may swap out your code at any time. Also, your code can be preempted by an interrupt at any time.
Application Code
----------------
The USB core does not execute application callbacks while in an interrupt context. Calls to application code are from within the USB core task context. Note that the application core will call class drivers from within its own task.
Class Drivers
-------------
Class driver code should never be called from an interrupt context by the USB core, though the application is allowed to call class driver functions from interrupts. USB core functions may be called simultaneously by multiple tasks. Use care that proper locking is used to guard the USBD core functions from this case.
Class drivers are allowed to call ``usbd_*`` functions, but not ``dcd_*`` functions.
USB Core
--------
All functions that may be called from an (USB core) interrupt context have a ``bool in_isr`` parameter to remind the implementer that special care must be taken.
Interrupt handlers must not directly call class driver code, they must pass a message to the USB core's task.
``usbd_*`` functions may be called from interrupts without any notice. They may also be called simultaneously by multiple tasks.
Device Drivers
--------------
Much of the processing of the USB stack is done in an interrupt context, and care must be taken in order to ensure variables are handled in the appropriate ways by the compiler and optimizer.
In particular:
* Ensure that all memory-mapped registers (including packet memory) are marked as volatile. GCC's optimizer will even combine memory accesses (like two 16-bit to be a 32-bit) if you don't mark the pointers as volatile. On some architectures, this can use macros like _I , _O , or _IO.
* All defined global variables are marked as ``static``.
third_party/tinyusb/docs/reference/dependencies.rst
Vendored
+103
View File
@@ -0,0 +1,103 @@
************
Dependencies
************
MCU low-level peripheral drivers and external libraries for building TinyUSB examples
======================================== ================================================================ ======================================== ===================================================================================================================================================================================================================================================================================================================================================
Local Path Repo Commit Required by
======================================== ================================================================ ======================================== ===================================================================================================================================================================================================================================================================================================================================================
hw/mcu/allwinner https://github.com/hathach/allwinner_driver.git 8e5e89e8e132c0fd90e72d5422e5d3d68232b756 fc100s
hw/mcu/analog/msdk https://github.com/analogdevicesinc/msdk.git b20b398d3e5e2007594e54a74ba3d2a2e50ddd75 maxim
hw/mcu/artery/at32f402_405 https://github.com/ArteryTek/AT32F402_405_Firmware_Library.git 4424515c2663e82438654e0947695295df2abdfe at32f402_405
hw/mcu/artery/at32f403a_407 https://github.com/ArteryTek/AT32F403A_407_Firmware_Library.git f2cb360c3d28fada76b374308b8c4c61d37a090b at32f403a_407
hw/mcu/artery/at32f413 https://github.com/ArteryTek/AT32F413_Firmware_Library.git f6fe62dfec9fd40c5b63d92fc5ef2c2b5e77a450 at32f413
hw/mcu/artery/at32f415 https://github.com/ArteryTek/AT32F415_Firmware_Library.git 716f545aa1290ff144ccf023a8e797b951e1bc8e at32f415
hw/mcu/artery/at32f423 https://github.com/ArteryTek/AT32F423_Firmware_Library.git 2afa7f12852e57a9e8aab3a892c641e1a8635a18 at32f423
hw/mcu/artery/at32f425 https://github.com/ArteryTek/AT32F425_Firmware_Library.git 620233e1357d5c1b7e2bde6b9dd5196822b91817 at32f425
hw/mcu/artery/at32f435_437 https://github.com/ArteryTek/AT32F435_437_Firmware_Library.git 25439cc6650a8ae0345934e8707a5f38c7ae41f8 at32f435_437
hw/mcu/artery/at32f45x https://github.com/ArteryTek/AT32F45x_Firmware_Library.git 3d4a1b38be8ebac292e2350ca53bc4bfa4430233 at32f45x
hw/mcu/bridgetek/ft9xx/ft90x-sdk https://github.com/BRTSG-FOSS/ft90x-sdk.git 03f74eac84645178fdde7f2e5ca9acdcb7bd9dcd ft9xx
hw/mcu/broadcom https://github.com/adafruit/broadcom-peripherals.git 08370086080759ed54ac1136d62d2ad24c6fa267 broadcom_32bit broadcom_64bit
hw/mcu/gd/nuclei-sdk https://github.com/Nuclei-Software/nuclei-sdk.git 7eb7bfa9ea4fbeacfafe1d5f77d5a0e6ed3922e7 gd32vf103
hw/mcu/hpmicro/hpm_sdk https://github.com/hpmicro/hpm_sdk 8d2af741ecc4aaa82d7ee395dc1ce25d7070c3ff hpmicro
hw/mcu/infineon/mtb-xmclib-cat3 https://github.com/Infineon/mtb-xmclib-cat3.git daf5500d03cba23e68c2f241c30af79cd9d63880 xmc4000
hw/mcu/microchip https://github.com/hathach/microchip_driver.git 9e8b37e307d8404033bb881623a113931e1edf27 sam3x samd11 samd21 samd51 samd5x_e5x same5x same7x samd2x_l2x samg
hw/mcu/mindmotion/mm32sdk https://github.com/hathach/mm32sdk.git b93e856211060ae825216c6a1d6aa347ec758843 mm32
hw/mcu/nordic/nrfx https://github.com/NordicSemiconductor/nrfx.git 11f57e578c7feea13f21c79ea0efab2630ac68c7 nrf
hw/mcu/nuvoton https://github.com/majbthrd/nuc_driver.git 2204191ec76283371419fbcec207da02e1bc22fa nuc100_120 nuc121_125 nuc126 nuc505
hw/mcu/nxp/lpcopen https://github.com/hathach/nxp_lpcopen.git b41cf930e65c734d8ec6de04f1d57d46787c76ae lpc11 lpc13 lpc15 lpc17 lpc18 lpc40 lpc43
hw/mcu/nxp/mcux-devices-kinetis https://github.com/nxp-mcuxpresso/mcux-devices-kinetis 98a155e666c54f396e528ec3131f27a5d5b71f76 kinetis_k32l
hw/mcu/nxp/mcux-devices-lpc https://github.com/nxp-mcuxpresso/mcux-devices-lpc 8096b783ec09d0d1c8629025a5f9d8e7df26e520 lpc51 lpc55
hw/mcu/nxp/mcux-devices-mcx https://github.com/nxp-mcuxpresso/mcux-devices-mcx ada1c97c761123ec0c179bb9bb9f744bf9a11475 mcx
hw/mcu/nxp/mcux-devices-rt https://github.com/nxp-mcuxpresso/mcux-devices-rt dba2b523c9df61f3330bd186242f8210a8e47c45 imxrt
hw/mcu/nxp/mcux-sdk https://github.com/nxp-mcuxpresso/mcux-sdk a1bdae309a14ec95a4f64a96d3315a4f89c397c6 kinetis_k kinetis_kl lpc54 rw61x
hw/mcu/nxp/mcuxsdk-core https://github.com/nxp-mcuxpresso/mcuxsdk-core 0c5c6b16deb211110e06bde896cdff59ab213e16 imxrt kinetis_k32l lpc51 lpc55 mcx
hw/mcu/raspberry_pi/FreeRTOS-Kernel https://github.com/raspberrypi/FreeRTOS-Kernel.git 4f7299d6ea746b27a9dd19e87af568e34bd65b15 rp2040
hw/mcu/raspberry_pi/Pico-PIO-USB https://github.com/sekigon-gonnoc/Pico-PIO-USB.git 675543bcc9baa8170f868ab7ba316d418dbcf41f rp2040
hw/mcu/renesas/fsp https://github.com/renesas/fsp.git edcc97d684b6f716728a60d7a6fea049d9870bd6 ra
hw/mcu/renesas/rx https://github.com/kkitayam/rx_device.git 706b4e0cf485605c32351e2f90f5698267996023 rx
hw/mcu/silabs/cmsis-dfp-efm32gg12b https://github.com/cmsis-packs/cmsis-dfp-efm32gg12b.git f1c31b7887669cb230b3ea63f9b56769078960bc efm32
hw/mcu/sony/cxd56/spresense-exported-sdk https://github.com/sonydevworld/spresense-exported-sdk.git 2ec2a1538362696118dc3fdf56f33dacaf8f4067 spresense
hw/mcu/st/cmsis-device-u0 https://github.com/STMicroelectronics/cmsis-device-u0.git e3a627c6a5bc4eb2388e1885a95cc155e1672253 stm32u0
hw/mcu/st/cmsis-device-wba https://github.com/STMicroelectronics/cmsis-device-wba.git 647d8522e5fd15049e9a1cc30ed19d85e5911eaf stm32wba
hw/mcu/st/cmsis_device_c0 https://github.com/STMicroelectronics/cmsis_device_c0.git 517611273f835ffe95318947647bc1408f69120d stm32c0
hw/mcu/st/cmsis_device_f0 https://github.com/STMicroelectronics/cmsis_device_f0.git cbb5da5d48b4b5f2efacdc2f033be30f9d29889f stm32f0
hw/mcu/st/cmsis_device_f1 https://github.com/STMicroelectronics/cmsis_device_f1.git c8e9a4a4f16b6d2cb2a2083cbe5161025280fb22 stm32f1
hw/mcu/st/cmsis_device_f2 https://github.com/STMicroelectronics/cmsis_device_f2.git 49321f1e4d2bd3e65687b37f2652a28ea7983674 stm32f2
hw/mcu/st/cmsis_device_f3 https://github.com/STMicroelectronics/cmsis_device_f3.git 5558e64e3675a1e1fcb1c71f468c7c407c1b1134 stm32f3
hw/mcu/st/cmsis_device_f4 https://github.com/STMicroelectronics/cmsis_device_f4.git 3c77349ce04c8af401454cc51f85ea9a50e34fc1 stm32f4
hw/mcu/st/cmsis_device_f7 https://github.com/STMicroelectronics/cmsis_device_f7.git 2352e888e821aa0f4fe549bd5ea81d29c67a3222 stm32f7
hw/mcu/st/cmsis_device_g0 https://github.com/STMicroelectronics/cmsis_device_g0.git f484fe852535f913a02ee79787eafa74dd7f9488 stm32g0
hw/mcu/st/cmsis_device_g4 https://github.com/STMicroelectronics/cmsis_device_g4.git 7c39c32593b03764aaa57531588b8bf7cdd443a5 stm32g4
hw/mcu/st/cmsis_device_h5 https://github.com/STMicroelectronics/cmsis_device_h5.git 884b8dc78e41cbfca008363342b17f4a9e8641f7 stm32h5
hw/mcu/st/cmsis_device_h7 https://github.com/STMicroelectronics/cmsis_device_h7.git 45b818cab6ee2806e3a27c80e330957223424392 stm32h7
hw/mcu/st/cmsis_device_h7rs https://github.com/STMicroelectronics/cmsis_device_h7rs.git 57ea11f70ebf1850e1048989d665c9070f0bb863 stm32h7rs
hw/mcu/st/cmsis_device_l0 https://github.com/STMicroelectronics/cmsis_device_l0.git 7b7ae8cd71437331e1d7824f157d00c7bb4a5044 stm32l0
hw/mcu/st/cmsis_device_l1 https://github.com/STMicroelectronics/cmsis_device_l1.git a23ade4ccf14012085fedf862e33a536ab7ed8be stm32l1
hw/mcu/st/cmsis_device_l4 https://github.com/STMicroelectronics/cmsis_device_l4.git a2530753e86dd326a75467d28feb92e2ba7d0df2 stm32l4
hw/mcu/st/cmsis_device_l5 https://github.com/STMicroelectronics/cmsis_device_l5.git 7d9a51481f0e6c376e62c3c849e6caf652c66482 stm32l5
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/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
hw/mcu/st/stm32c5xx-dfp https://github.com/STMicroelectronics/stm32c5xx-dfp.git 6d0940882511d9430f83af9bd3da6bcb77f79239 stm32c5
hw/mcu/st/stm32c5xx-drivers https://github.com/STMicroelectronics/stm32c5xx-drivers.git 79b901285a7efeaf87c4c25db81d24cb5d8c9465 stm32c5
hw/mcu/st/stm32f0xx_hal_driver https://github.com/STMicroelectronics/stm32f0xx_hal_driver.git 94399697cb5eeaf8511b81b7f50dc62f0a5a3f6c stm32f0
hw/mcu/st/stm32f1xx_hal_driver https://github.com/STMicroelectronics/stm32f1xx_hal_driver.git 18074e3e5ecad0b380a5cf5a9131fe4b5ed1b2b7 stm32f1
hw/mcu/st/stm32f2xx_hal_driver https://github.com/STMicroelectronics/stm32f2xx_hal_driver.git ae7b47fe41cf75ccaf65cbf8ee8749b18ba0e0f3 stm32f2
hw/mcu/st/stm32f3xx_hal_driver https://github.com/STMicroelectronics/stm32f3xx_hal_driver.git e098c8c8ce6f426bcee7db3a37c0932ea881eb0b stm32f3
hw/mcu/st/stm32f4xx_hal_driver https://github.com/STMicroelectronics/stm32f4xx_hal_driver.git b6f0ed3829f3829eb358a2e7417d80bba1a42db7 stm32f4
hw/mcu/st/stm32f7xx_hal_driver https://github.com/STMicroelectronics/stm32f7xx_hal_driver.git e1446fa12ffda80ea1016faf349e45b2047fff12 stm32f7
hw/mcu/st/stm32g0xx_hal_driver https://github.com/STMicroelectronics/stm32g0xx_hal_driver.git a248a9e484d58943b46c68f6c49b4b276778bd59 stm32g0
hw/mcu/st/stm32g4xx_hal_driver https://github.com/STMicroelectronics/stm32g4xx_hal_driver.git 10138a41749ea62d53ecab65b2bc2a950acc04d2 stm32g4
hw/mcu/st/stm32h5xx_hal_driver https://github.com/STMicroelectronics/stm32h5xx_hal_driver.git 3c84eaa6000ab620be01afbcfba2735389afe09b stm32h5
hw/mcu/st/stm32h7rsxx_hal_driver https://github.com/STMicroelectronics/stm32h7rsxx-hal-driver.git 9e83b95ae0f70faa067eddce2da617d180937f9b stm32h7rs
hw/mcu/st/stm32h7xx_hal_driver https://github.com/STMicroelectronics/stm32h7xx_hal_driver.git dbfb749f229e1aa89e50b54229ca87766e180d2d stm32h7
hw/mcu/st/stm32l0xx_hal_driver https://github.com/STMicroelectronics/stm32l0xx_hal_driver.git 65da4cd8a10ad859ec8d9cd71f3f6c50735bd473 stm32l0
hw/mcu/st/stm32l1xx_hal_driver https://github.com/STMicroelectronics/stm32l1xx_hal_driver.git 54f0b7568ce2acb33d090c70c897ee32229c1d32 stm32l1
hw/mcu/st/stm32l4xx_hal_driver https://github.com/STMicroelectronics/stm32l4xx_hal_driver.git 3e039bbf62f54bbd834d578185521cff80596efe stm32l4
hw/mcu/st/stm32l5xx_hal_driver https://github.com/STMicroelectronics/stm32l5xx_hal_driver.git 3340b9a597bcf75cc173345a90a74aa2a4a37510 stm32l5
hw/mcu/st/stm32n6xx_hal_driver https://github.com/STMicroelectronics/stm32n6xx-hal-driver.git bc6c41f8f67d61b47af26695d0bf67762a000666 stm32n6
hw/mcu/st/stm32u0xx_hal_driver https://github.com/STMicroelectronics/stm32u0xx-hal-driver.git cbfb5ac654256445237fd32b3587ac6a238d24f1 stm32u0
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/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
hw/mcu/wch/ch583 https://github.com/openwch/ch583.git bd508ad7ceed48377619837051412a651952857f ch583
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 samd2x_l2x 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 stm32c5
lib/FreeRTOS-Kernel https://github.com/FreeRTOS/FreeRTOS-Kernel.git 9b777ae5c5b8e9e456065a00294d1e5f5f9facf5 all
lib/fatfs https://github.com/abbrev/fatfs.git 30ca13c62615df0d2e9104ab41256985b96590c1 all
lib/lwip https://github.com/lwip-tcpip/lwip.git 159e31b689577dbf69cf0683bbaffbd71fa5ee10 all
lib/sct_neopixel https://github.com/gsteiert/sct_neopixel.git e73e04ca63495672d955f9268e003cffe168fcd8 lpc55
lib/threadx https://github.com/eclipse-threadx/threadx.git 4b6e8100d932a3a67b34c6eb17f84f3bffb9e2ae all
tools/linkermap https://github.com/hathach/linkermap.git 8e1f440fa15c567aceb5aa0d14f6d18c329cc67f all
tools/uf2 https://github.com/microsoft/uf2.git c594542b2faa01cc33a2b97c9fbebc38549df80a all
======================================== ================================================================ ======================================== ===================================================================================================================================================================================================================================================================================================================================================
third_party/tinyusb/docs/reference/device_issues.rst
Vendored
+35
View File
@@ -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.
third_party/tinyusb/docs/reference/glossary.rst
Vendored
+98
View File
@@ -0,0 +1,98 @@
********
Glossary
********
.. glossary::
BSP
Board Support Package. A collection of board-specific code that provides hardware abstraction for a particular development board, including pin mappings, clock settings, linker scripts, and hardware initialization routines. Located in ``hw/bsp/FAMILY/boards/BOARD_NAME``.
Bulk Transfer
USB transfer type used for large amounts of data that doesn't require guaranteed timing. Used by mass storage devices and CDC class.
CDC
Communications Device Class. USB class for devices that communicate serial data, creating virtual serial ports.
Control Transfer
USB transfer type used for device configuration and control. All USB devices must support control transfers on endpoint 0.
DCD
Device Controller Driver. The hardware abstraction layer for USB device controllers in TinyUSB. See also HCD.
Descriptor
Data structures that describe USB device capabilities, configuration, and interfaces to the host.
Device Class
USB specification defining how devices of a particular type (e.g., storage, audio, HID) communicate with hosts.
DFU
Device Firmware Update. USB class that allows firmware updates over USB.
Endpoint
Communication channel between host and device. Each endpoint has a direction (IN/OUT) and transfer type.
Enumeration
Process where USB host discovers and configures a newly connected device.
HCD
Host Controller Driver. The hardware abstraction layer for USB host controllers in TinyUSB. See also DCD.
HID
Human Interface Device. USB class for input devices like keyboards, mice, and game controllers.
High Speed
USB 2.0 speed mode operating at 480 Mbps.
Full Speed
USB speed mode operating at 12 Mbps, supported by USB 1.1 and 2.0.
Low Speed
USB speed mode operating at 1.5 Mbps, typically used by simple input devices.
Interrupt Transfer
USB transfer type for small, time-sensitive data with guaranteed maximum latency.
Isochronous Transfer
USB transfer type for time-critical data like audio/video with guaranteed bandwidth but no error correction.
MSC
Mass Storage Class. USB class for storage devices like USB drives.
OSAL
Operating System Abstraction Layer. TinyUSB component that abstracts RTOS differences.
OTG
On-The-Go. USB specification allowing devices to act as both host and device.
Pipe
Host-side communication channel to a device endpoint.
Root Hub
The USB hub built into the host controller, where devices connect directly.
Stall
USB protocol mechanism where an endpoint responds with a STALL handshake to indicate an error condition or unsupported request. Used for error handling, not flow control.
Super Speed
USB 3.0 speed mode operating at 5 Gbps. Not supported by TinyUSB.
tud
TinyUSB Device. Function prefix for all device stack APIs (e.g., ``tud_task()``, ``tud_cdc_write()``).
tuh
TinyUSB Host. Function prefix for all host stack APIs (e.g., ``tuh_task()``, ``tuh_cdc_receive()``).
UAC
USB Audio Class. USB class for audio devices.
UVC
USB Video Class. USB class for video devices like cameras.
VID
Vendor Identifier. 16-bit number assigned by USB-IF to identify device manufacturers.
PID
Product Identifier. 16-bit number assigned by vendor to identify specific products.
USB-IF
USB Implementers Forum. Organization that maintains USB specifications and assigns VIDs.
third_party/tinyusb/docs/reference/index.rst
Vendored
+17
View File
@@ -0,0 +1,17 @@
*********
Reference
*********
Complete reference documentation for TinyUSB APIs, configuration, and supported hardware.
.. toctree::
:maxdepth: 2
architecture
usb_concepts
class_drivers
boards
dependencies
concurrency
device_issues
glossary
third_party/tinyusb/docs/reference/usb_concepts.rst
Vendored
+428
View File
@@ -0,0 +1,428 @@
************
USB Concepts
************
This document provides a brief introduction to USB protocol fundamentals that are essential for understanding TinyUSB development.
TinyUSB API Naming Conventions
===============================
TinyUSB uses consistent function prefixes to organize its API:
* **tusb_**: Core stack functions (initialization, interrupt handling)
* **tud_**: Device stack functions (e.g., ``tud_task()``, ``tud_cdc_write()``)
* **tuh_**: Host stack functions (e.g., ``tuh_task()``, ``tuh_cdc_receive()``)
* **tu_**: Internal utility functions (generally not used by applications)
This naming makes it easy to identify which part of the stack a function belongs to and ensures there are no naming conflicts when using both device and host stacks together.
USB Protocol Basics
====================
Universal Serial Bus (USB) is a standardized communication protocol designed for connecting devices to hosts (typically computers). Understanding these core concepts is essential for effective TinyUSB development.
Host and Device Roles
----------------------
**USB Host**: The controlling side of a USB connection (typically a computer). The host:
- Initiates all communication
- Provides power to devices
- Manages the USB bus
- Enumerates and configures devices
**TinyUSB Host Stack**: Enable with ``CFG_TUH_ENABLED=1`` in ``tusb_config.h``. Call ``tuh_task()`` regularly in your main loop. See the :doc:`../getting_started` Quick Start Examples for implementation details.
**USB Device**: The peripheral side (keyboard, mouse, storage device, etc.). Devices:
- Respond to host requests
- Cannot initiate communication
- Receive power from the host
- Must be enumerated by the host before use
**TinyUSB Device Stack**: Enable with ``CFG_TUD_ENABLED=1`` in ``tusb_config.h``. Call ``tud_task()`` regularly in your main loop. See the :doc:`../getting_started` Quick Start Examples for implementation details.
**OTG (On-The-Go)**: Some devices can switch between host and device roles dynamically. **TinyUSB Support**: Both stacks can be enabled simultaneously on OTG-capable hardware. See ``examples/dual/`` for dual-role implementations.
USB Transfers
=============
Every USB transfer consists of the host issuing a request, and the device replying to that request. The host is the bus master and initiates all communication.
Devices cannot initiate sending data; for unsolicited incoming data, polling is used by the host.
USB defines four transfer types, each intended for different use cases:
Control Transfers
-----------------
Used for device configuration and control commands.
**Characteristics**:
- Bidirectional (uses both IN and OUT)
- Guaranteed delivery with error detection
- Limited data size (8-64 bytes per packet)
- All devices must support control transfers on endpoint 0
**Usage**: Device enumeration, configuration changes, class-specific commands
**TinyUSB Context**: Handled automatically by the core stack for standard requests; class drivers handle class-specific requests. Endpoint 0 is managed by ``src/device/usbd.c`` and ``src/host/usbh.c``. Configure buffer size with ``CFG_TUD_ENDPOINT0_SIZE`` (typically 64 bytes).
Bulk Transfers
--------------
Used for large amounts of data that don't require guaranteed timing.
**Characteristics**:
- Unidirectional (separate IN and OUT endpoints)
- Guaranteed delivery with error detection
- Large packet sizes (up to 512 bytes for High Speed)
- Uses available bandwidth when no other transfers are active
**Usage**: File transfers, large data communication, CDC serial data
**TinyUSB Context**: Used by MSC (mass storage) and CDC classes for data transfer. Configure endpoint buffer sizes with ``CFG_TUD_MSC_EP_BUFSIZE`` and ``CFG_TUD_CDC_EP_BUFSIZE``. See ``src/class/msc/`` and ``src/class/cdc/`` for implementation details.
Interrupt Transfers
-------------------
Used for small, time-sensitive data with guaranteed maximum latency.
**Characteristics**:
- Unidirectional (separate IN and OUT endpoints)
- Guaranteed delivery with error detection
- Small packet sizes (up to 64 bytes for Full Speed)
- Regular polling interval (1ms to 255ms)
**Usage**: Keyboard/mouse input, sensor data, status updates
**TinyUSB Context**: Used by HID class for input reports. Configure with ``CFG_TUD_HID`` and ``CFG_TUD_HID_EP_BUFSIZE``. Send reports using ``tud_hid_report()`` or ``tud_hid_keyboard_report()``. See ``src/class/hid/`` and HID examples in ``examples/device/hid_*/``.
Isochronous Transfers
---------------------
Used for time-critical streaming data.
**Characteristics**:
- Unidirectional (separate IN and OUT endpoints)
- No error correction (speed over reliability)
- Guaranteed bandwidth
- Real-time delivery
**Usage**: Audio, video streaming
**TinyUSB Context**: Used by Audio class for streaming audio data. Configure with ``CFG_TUD_AUDIO`` and related audio configuration macros. See ``src/class/audio/`` and audio examples in ``examples/device/audio_*/`` for UAC2 implementation.
Endpoints and Addressing
=========================
Endpoint Basics
---------------
**Endpoint**: A communication channel between host and device.
- Each endpoint has a number (0-15) and direction
- Endpoint 0 is reserved for control transfers
- Other endpoints are assigned by device class requirements
**TinyUSB Endpoint Management**: Configure maximum endpoints with ``CFG_TUD_ENDPOINT_MAX``. Endpoints are automatically allocated by enabled classes. See your board's ``usb_descriptors.c`` for endpoint assignments.
**Direction**:
- **OUT**: Host to device (host sends data out)
- **IN**: Device to host (host reads data in)
- Note that in TinyUSB code, for ``tx``/``rx``, the device perspective is used typically: E.g., ``tud_cdc_tx_complete_cb()`` designates the callback executed once the device has completed sending data to the host (in device mode).
**Addressing**: Endpoints are addressed as EPx IN/OUT (e.g., EP1 IN, EP2 OUT)
Endpoint Configuration
----------------------
Each endpoint is configured with a specific **transfer type** (control, bulk, interrupt, or isochronous), a **direction** (IN, OUT, or bidirectional for control only), a **maximum packet size** that depends on USB speed and transfer type, and an **interval** for interrupt and isochronous endpoints.
**TinyUSB Configuration**: Endpoint characteristics are defined in descriptors (``usb_descriptors.c``) and automatically configured by the stack. Buffer sizes are set via ``CFG_TUD_*_EP_BUFSIZE`` macros.
Error Handling and Flow Control
-------------------------------
**Transfer Results**: USB transfers can complete with different results. An **ACK** indicates a successful transfer, while a **NAK** signals that the device is not ready (commonly used for flow control). A **STALL** response indicates an error condition or unsupported request, and **Timeout** occurs when a transfer fails to complete within the expected time frame.
**Flow Control in USB**: Unlike network protocols, USB doesn't use traditional congestion control. Instead, devices use NAK responses when not ready to receive data, applications implement buffering and proper timing strategies, and some classes (like CDC) support hardware flow control mechanisms such as RTS/CTS.
**TinyUSB Handling**: Transfer results are represented as ``xfer_result_t`` enum values. The stack automatically handles NAK responses and timing. STALL conditions indicate application-level errors that should be addressed in class drivers.
USB Device States
=================
A USB device progresses through several states:
1. **Attached**: Device is physically connected
2. **Powered**: Device receives power from host
3. **Default**: Device responds to address 0
4. **Address**: Device has been assigned a unique address
5. **Configured**: Device is ready for normal operation
6. **Suspended**: Device is in low-power state
**TinyUSB State Management**: State transitions are handled automatically by ``src/device/usbd.c``. You can implement ``tud_mount_cb()`` and ``tud_umount_cb()`` to respond to configuration changes, and ``tud_suspend_cb()``/``tud_resume_cb()`` for power management.
Device Enumeration Process
==========================
When a device is connected, the host follows this process:
1. **Detection**: Host detects device connection
2. **Reset**: Host resets the device
3. **Descriptor Requests**: Host requests device descriptors
4. **Address Assignment**: Host assigns unique address to device
5. **Configuration**: Host selects and configures device
6. **Class Loading**: Host loads appropriate drivers
7. **Normal Operation**: Device is ready for use
**TinyUSB Role**: The device stack handles steps 1-6 automatically; your application handles step 7.
USB Descriptors
===============
Descriptors are data structures that describe device capabilities:
Device Descriptor
-----------------
Describes the device (VID, PID, USB version, etc.)
Configuration Descriptor
------------------------
Describes device configuration (power requirements, interfaces, etc.)
Interface Descriptor
--------------------
Describes a functional interface (class, endpoints, etc.)
Endpoint Descriptor
-------------------
Describes endpoint characteristics (type, direction, size, etc.)
String Descriptors
------------------
Human-readable strings (manufacturer, product name, etc.)
**TinyUSB Implementation**: You provide descriptors in ``usb_descriptors.c`` via callback functions:
- ``tud_descriptor_device_cb()`` - Device descriptor
- ``tud_descriptor_configuration_cb()`` - Configuration descriptor
- ``tud_descriptor_string_cb()`` - String descriptors
The stack automatically handles descriptor requests during enumeration. See examples in ``examples/device/*/usb_descriptors.c`` for reference implementations.
USB Classes
===========
USB classes define standardized protocols for device types:
**Class Code**: Identifies the device type in descriptors
**Class Driver**: Software that implements the class protocol
**Class Requests**: Standardized commands for the class
**Common TinyUSB-Supported Classes**:
- **CDC (02h)**: Communication devices (virtual serial ports) - Enable with ``CFG_TUD_CDC``
- **HID (03h)**: Human interface devices (keyboards, mice) - Enable with ``CFG_TUD_HID``
- **MSC (08h)**: Mass storage devices (USB drives) - Enable with ``CFG_TUD_MSC``
- **Audio (01h)**: Audio devices (speakers, microphones) - Enable with ``CFG_TUD_AUDIO``
- **MIDI**: MIDI devices - Enable with ``CFG_TUD_MIDI``
- **DFU**: Device Firmware Update - Enable with ``CFG_TUD_DFU``
- **Vendor**: Custom vendor classes - Enable with ``CFG_TUD_VENDOR``
.. note::
**Vendor Class Buffer Configuration**: Unlike other USB classes, the vendor class supports setting buffer sizes to 0 in ``tusb_config.h`` (``CFG_TUD_VENDOR_RX_BUFSIZE = 0``) to disable internal buffering. When disabled, data goes directly to ``tud_vendor_rx_cb()`` and the ``tud_vendor_read()``/``tud_vendor_write()`` functions are not available - applications must handle data directly in callbacks.
See ``examples/device/*/tusb_config.h`` for configuration examples.
USB Speeds
==========
USB supports multiple speed modes:
**Low Speed (1.5 Mbps)**:
- Simple devices (mice, keyboards)
- Limited endpoint types and sizes
**Full Speed (12 Mbps)**:
- Most common for embedded devices
- All transfer types supported
- Maximum packet sizes: Control (64), Bulk (64), Interrupt (64)
**High Speed (480 Mbps)**:
- High-performance devices
- Larger packet sizes: Control (64), Bulk (512), Interrupt (1024)
- Requires more complex hardware
**Super Speed (5 Gbps)**:
- USB 3.0 and later
- Not supported by TinyUSB
**TinyUSB Speed Support**: Most TinyUSB ports support Full Speed and High Speed. Speed is typically auto-detected by hardware. Configure speed requirements in board configuration (``hw/bsp/FAMILY/boards/BOARD/board.mk``) and ensure your MCU supports the desired speed.
USB Controller Abstraction
===========================
USB controllers are hardware peripherals that handle the low-level USB protocol implementation. Understanding how they work helps explain TinyUSB's architecture and portability.
Controller Fundamentals
-----------------------
**What Controllers Do**:
- Handle USB signaling and protocol timing
- Manage endpoint buffers and data transfers
- Generate interrupts for USB events
- Implement USB electrical specifications
**Key Components**: USB controllers consist of several key components working together. The **Physical Layer** provides USB signal drivers and receivers for electrical interfacing. The **Protocol Engine** handles USB packets and ACK/NAK responses according to the USB specification. **Endpoint Buffers** provide hardware FIFOs or RAM for data storage during transfers. Finally, the **Interrupt Controller** generates events for software processing when USB activities occur.
Controller Architecture Types
-----------------------------
Different MCU vendors implement USB controllers with varying architectures.
To list a few common patterns:
**FIFO-Based Controllers** (e.g., STM32 OTG, NXP LPC):
- Shared or dedicated FIFOs for endpoint data
- Software manages FIFO allocation and data flow
- Common in higher-end MCUs with flexible configurations
**Buffer-Based Controllers** (e.g., STM32 FSDEV, Microchip SAMD, RP2040):
- Fixed packet memory areas for each endpoint
- Hardware automatically handles packet placement
- Simpler programming model, common in smaller MCUs
**Descriptor-Based Controllers** (e.g., NXP EHCI-style):
- Use descriptor chains to describe transfers
- Hardware processes transfer descriptors independently
- More complex but can handle larger transfers autonomously
TinyUSB Controller Abstraction
------------------------------
TinyUSB abstracts controller differences through the TinyUSB **Device Controller Driver (DCD)** layer.
These internal details don't matter to users of TinyUSB typically; however, when debugging, knowledge about internal details helps sometimes.
**Portable Interface** (``src/device/usbd.h``):
- Standardized function signatures for all controllers
- Common endpoint and transfer management APIs
- Unified interrupt and event handling
**Controller-Specific Drivers** (``src/portable/VENDOR/FAMILY/``):
- Implement the DCD interface for specific hardware
- Handle vendor-specific register layouts and behaviors
- Manage controller-specific quirks and workarounds
**Common DCD Functions**:
- ``dcd_init()`` - Initialize controller hardware
- ``dcd_edpt_open()`` - Configure endpoint with type and size
- ``dcd_edpt_xfer()`` - Start data transfer on endpoint
- ``dcd_int_handler()`` - Process USB interrupts
- ``dcd_connect()/dcd_disconnect()`` - Control USB bus connection
Host Controller Driver (HCD)
-----------------------------
TinyUSB also abstracts USB host controllers through the **Host Controller Driver (HCD)** layer for host mode applications.
**Portable Interface** (``src/host/usbh.h``):
- Standardized interface for all host controllers
- Common device enumeration and pipe management
- Unified transfer scheduling and completion handling
**Common HCD Functions**:
- ``hcd_init()`` - Initialize host controller hardware
- ``hcd_port_connect_status()`` - Check device connection status
- ``hcd_port_reset()`` - Reset connected device
- ``hcd_edpt_open()`` - Open communication pipe to device endpoint
- ``hcd_edpt_xfer()`` - Transfer data to/from connected device
**Host vs Device Architecture**: While DCD is reactive (responds to host requests), HCD is active (initiates all communication). Host controllers manage device enumeration, driver loading, and transfer scheduling to multiple connected devices.
TinyUSB Event System & Thread Safety
====================================
Deferred Interrupt Processing
-----------------------------
**Core Architectural Principle**: TinyUSB uses a deferred interrupt processing model where all USB hardware events are captured in interrupt service routines (ISRs) but processed later in non-interrupt context.
**Event Flow**:
1. **Hardware Event**: USB controller generates interrupt (e.g., data received, transfer complete)
2. **ISR Handling**: TinyUSB ISR captures the event and pushes it to a central event queue
3. **Deferred Processing**: Application calls ``tud_task()`` or ``tuh_task()`` to process queued events
4. **Class Driver Callbacks**: Events trigger appropriate class driver functions and user callbacks
**Buffer Integration**: The deferred processing model works seamlessly with TinyUSB's buffer/FIFO design. Since callbacks run in task context (not ISR), it's safe and straightforward to enqueue TX data directly in RX callbacks - for example, processing incoming CDC data and immediately sending a response.
Controller Event Flow
---------------------
**Typical USB Event Processing**:
1. **Hardware Event**: USB controller detects bus activity (setup packet, data transfer, etc.)
2. **Interrupt Generation**: Controller generates interrupt to CPU
3. **ISR Processing**: ``dcd_int_handler()`` reads controller status
4. **Event Queuing**: Events are queued for later processing (thread safety)
5. **Task Processing**: ``tud_task()`` processes queued events
6. **Class Notification**: Appropriate class drivers handle the event
7. **Application Callback**: User code responds to the event
USB Class Driver Architecture
==============================
TinyUSB implements USB classes through a standardized driver pattern that provides consistent integration with the core stack while allowing class-specific functionality.
Class Driver Pattern
---------------------
**Standardized Entry Points**: Each class driver implements these core functions:
- ``*_init()`` - Initialize class driver state and buffers
- ``*_reset()`` - Reset to initial state on USB bus reset
- ``*_open()`` - Parse and configure interfaces during enumeration
- ``*_control_xfer_cb()`` - Handle class-specific control requests
- ``*_xfer_cb()`` - Handle transfer completion callbacks
**Multi-Instance Support**: Classes support multiple instances using ``_n`` suffixed APIs:
.. code-block:: c
// Single instance (default instance 0)
tud_cdc_write(data, len);
// Multiple instances
tud_cdc_n_write(0, data, len); // Instance 0
tud_cdc_n_write(1, data, len); // Instance 1
**Integration with Core Stack**: Class drivers are automatically discovered and integrated through function pointers in driver tables. The core stack calls class drivers during enumeration, control requests, and data transfers without requiring explicit registration.
Class Driver Types
-------------------
TinyUSB classes have different architectural patterns based on their buffering capabilities and callback designs.
Most classes like CDC, MIDI, and HID always use internal buffers for data management. These classes provide notification-only callbacks such as ``tud_cdc_rx_cb(uint8_t itf)`` that signal when data is available, requiring applications to use class-specific APIs like ``tud_cdc_read()`` and ``tud_cdc_write()`` to access the data. HID is slightly different in that it provides direct buffer access in some callbacks (``tud_hid_set_report_cb()`` receives buffer and size parameters), but it still maintains internal endpoint buffering that cannot be disabled.
The **Vendor Class** is unique in that it supports both buffered and direct modes. When buffered, vendor class behaves like other classes with ``tud_vendor_read()`` and ``tud_vendor_write()`` APIs. However, when buffering is disabled by setting buffer size to 0, the vendor class provides direct buffer access through ``tud_vendor_rx_cb(itf, buffer, bufsize)`` callbacks, eliminating internal FIFO overhead and providing direct endpoint control.
**Block-Oriented Classes** like MSC operate differently by handling large data blocks through callback interfaces. The application implements storage access functions such as ``tud_msc_read10_cb()`` and ``tud_msc_write10_cb()``, while the TinyUSB stack manages the USB protocol aspects and the application manages the underlying storage.
Power Management
================
USB provides power to devices:
**Bus-Powered**: Device draws power from USB bus (up to 500mA)
**Self-Powered**: Device has its own power source
**Suspend/Resume**: Devices must enter low-power mode when bus is idle
**TinyUSB Power Management**:
- Implement ``tud_suspend_cb()`` and ``tud_resume_cb()`` for power management
- Configure power requirements in device descriptor (``bMaxPower`` field)
- Use ``tud_remote_wakeup()`` to wake the host from suspend (if supported)
- Enable remote wakeup with ``CFG_TUD_USBD_ENABLE_REMOTE_WAKEUP``
Next Steps
==========
- Start with :doc:`../getting_started` for basic setup
- Review ``examples/device/*/tusb_config.h`` for configuration examples
- Explore examples in ``examples/device/`` and ``examples/host/`` directories