diff options
| -rw-r--r-- | docs/explanation/index.rst | 11 | ||||
| -rw-r--r-- | docs/faq.rst | 2 | ||||
| -rw-r--r-- | docs/getting_started.rst (renamed from docs/tutorials/getting_started.rst) | 11 | ||||
| -rw-r--r-- | docs/index.rst | 12 | ||||
| -rw-r--r-- | docs/reference/architecture.rst (renamed from docs/explanation/architecture.rst) | 5 | ||||
| -rw-r--r-- | docs/reference/configuration.rst | 307 | ||||
| -rw-r--r-- | docs/reference/index.rst | 5 | ||||
| -rw-r--r-- | docs/reference/usb_classes.rst | 287 | ||||
| -rw-r--r-- | docs/reference/usb_concepts.rst (renamed from docs/explanation/usb_concepts.rst) | 15 | ||||
| -rw-r--r-- | docs/tutorials/index.rst | 10 |
10 files changed, 22 insertions, 643 deletions
diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst deleted file mode 100644 index 695efd9e0..000000000 --- a/docs/explanation/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -*********** -Explanation -*********** - -Deep understanding of TinyUSB's design, architecture, and concepts. - -.. toctree:: - :maxdepth: 2 - - architecture - usb_concepts
\ No newline at end of file diff --git a/docs/faq.rst b/docs/faq.rst index 505833316..ade51a379 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -38,7 +38,7 @@ Run ``python tools/get_deps.py FAMILY`` where FAMILY is your MCU family (e.g., s **Q: Can I use my own build system instead of Make/CMake?** -Yes, just add all ``.c`` files from ``src/`` to your project and configure include paths. See :doc:`tutorials/getting_started` for details. +Yes, just add all ``.c`` files from ``src/`` to your project and configure include paths. See :doc:`getting_started` for details. **Q: Error: "tusb_config.h: No such file or directory"** diff --git a/docs/tutorials/getting_started.rst b/docs/getting_started.rst index 35a9aa9bf..5e8ebd040 100644 --- a/docs/tutorials/getting_started.rst +++ b/docs/getting_started.rst @@ -13,11 +13,11 @@ To incorporate TinyUSB into your project: * Add all the ``.c`` files in the ``tinyusb/src`` folder to your project * Add ``your_project/tinyusb/src`` to your include path. Also ensure that your include path contains the configuration file ``tusb_config.h``. * Ensure all required macros are properly defined in ``tusb_config.h``. The configuration file from the demo applications provides a good starting point, but you'll need to add additional macros such as ``CFG_TUSB_MCU`` and ``CFG_TUSB_OS``. These are typically passed by make/cmake to maintain unique configurations for different boards. -* If you're using the device stack, ensure you have created or modified USB descriptors to meet your specific requirements. Ultimately you need to implement all **tud descriptor** callbacks for the stack to work. +* If you're using the **device stack**, you need to implement all **tud descriptor** callbacks for the stack to work. * Add a ``tusb_init(rhport, role)`` call to your reset initialization code. * Call ``tusb_int_handler(rhport, in_isr)`` from your USB IRQ handler * Implement all enabled classes' callbacks. -* If you're not using an RTOS, you must call the ``tud_task()``/``tuh_task()`` functions continuously or periodically. These task functions handle all callbacks and core functionality. +* If you're not using an RTOS, you must call the ``tud_task()``/``tuh_task()`` functions periodically. These task functions handle all callbacks and core functionality. .. note:: TinyUSB uses consistent naming prefixes: ``tud_`` for device stack functions and ``tuh_`` for host stack functions. See the :doc:`../reference/glossary` for more details. @@ -29,6 +29,7 @@ To incorporate TinyUSB into your project: .role = TUSB_ROLE_DEVICE, .speed = TUSB_SPEED_AUTO }; + // tud descriptor omitted here tusb_init(0, &dev_init); // initialize device stack on roothub port 0 tusb_rhport_init_t host_init = { @@ -67,7 +68,7 @@ Some ports require additional port-specific SDKs (e.g., for RP2040) or binaries Dependencies ^^^^^^^^^^^^ -TinyUSB separates example applications from board-specific hardware configurations. Example applications live in ``examples/device``, ``examples/host``, and ``examples/dual`` directories, while Board Support Package (BSP) configurations are stored in ``hw/bsp/FAMILY/boards/BOARD_NAME``. The BSP provides hardware abstraction including pin mappings, clock settings, linker scripts, and hardware initialization routines. For example, raspberry_pi_pico is located in ``hw/bsp/rp2040/boards/raspberry_pi_pico`` where ``FAMILY=rp2040`` and ``BOARD=raspberry_pi_pico``. When you build an example with ``BOARD=raspberry_pi_pico``, the build system automatically finds and uses the corresponding BSP. +TinyUSB separates example applications from board-specific hardware configurations (Board Support Packages, BSP). Example applications live in ``examples/device``, ``examples/host``, and ``examples/dual`` directories, while BSP configurations are stored in ``hw/bsp/FAMILY/boards/BOARD_NAME``. The BSP provides hardware abstraction including pin mappings, clock settings, linker scripts, and hardware initialization routines. For example, raspberry_pi_pico is located in ``hw/bsp/rp2040/boards/raspberry_pi_pico`` where ``FAMILY=rp2040`` and ``BOARD=raspberry_pi_pico``. When you build an example with ``BOARD=raspberry_pi_pico``, the build system automatically finds and uses the corresponding BSP. Before building, you must first download dependencies including MCU low-level peripheral drivers and external libraries such as FreeRTOS (required by some examples). You can do this in either of two ways: @@ -352,5 +353,5 @@ The ``cdc_msc_hid`` example creates a USB host that can connect to USB devices w Next Steps ^^^^^^^^^^ -* Check :doc:`../reference/boards` for board-specific information -* Explore more :doc:`../examples` for advanced use cases +* Check :doc:`reference/boards` for board-specific information +* Explore more examples in ``examples/device/`` and ``examples/host/`` directories diff --git a/docs/index.rst b/docs/index.rst index 3a70f2471..ac10dbfd7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,10 +18,8 @@ TinyUSB provides a complete USB stack implementation supporting both device and **Quick Navigation:** -* New to TinyUSB? Start with :doc:`tutorials/getting_started` -* Need to solve a specific problem? Check :doc:`guides/index` -* Looking for API details? See :doc:`reference/index` -* Want to understand the design? Read :doc:`explanation/architecture` +* New to TinyUSB? Start with :doc:`getting_started` and :doc:`reference/glossary` +* Want to understand the design? Read :doc:`reference/architecture` and :doc:`reference/usb_concepts` * Having issues? Check :doc:`faq` and :doc:`troubleshooting` Documentation Structure @@ -31,12 +29,10 @@ Documentation Structure :maxdepth: 2 :caption: Information - explanation/index - tutorials/index - guides/index - reference/index + getting_started faq troubleshooting + reference/index .. toctree:: :maxdepth: 1 diff --git a/docs/explanation/architecture.rst b/docs/reference/architecture.rst index aa0c76128..ab451a91a 100644 --- a/docs/explanation/architecture.rst +++ b/docs/reference/architecture.rst @@ -239,11 +239,6 @@ Buffer Management - Size defined by ``CFG_TUD_*_RX/TX_BUFSIZE`` macros - Separate read/write pointers -**DMA Considerations**: -- Buffers must be DMA-accessible on some MCUs -- Alignment requirements vary by hardware -- Cache coherency handled in portable drivers - Threading Model =============== diff --git a/docs/reference/configuration.rst b/docs/reference/configuration.rst deleted file mode 100644 index fa0a874f5..000000000 --- a/docs/reference/configuration.rst +++ /dev/null @@ -1,307 +0,0 @@ -************* -Configuration -************* - -TinyUSB behavior is controlled through compile-time configuration in ``tusb_config.h``. This reference covers all available configuration options. - -Basic Configuration -=================== - -Required Settings ------------------ - -.. code-block:: c - - // Target MCU family - REQUIRED - #define CFG_TUSB_MCU OPT_MCU_STM32F4 - - // OS abstraction layer - REQUIRED - #define CFG_TUSB_OS OPT_OS_NONE - - // Enable device or host stack - #define CFG_TUD_ENABLED 1 // Device stack - #define CFG_TUH_ENABLED 1 // Host stack - -Debug and Logging ------------------ - -.. code-block:: c - - // Debug level (0=off, 1=error, 2=warning, 3=info) - #define CFG_TUSB_DEBUG 2 - - // Memory alignment for buffers (usually 4) - #define CFG_TUSB_MEM_ALIGN __attribute__ ((aligned(4))) - -Device Stack Configuration -========================== - -Endpoint Configuration ----------------------- - -.. code-block:: c - - // Control endpoint buffer size - #define CFG_TUD_ENDPOINT0_SIZE 64 - - // Number of endpoints (excluding EP0) - #define CFG_TUD_ENDPOINT_MAX 16 - -Device Classes --------------- - -**CDC (Communication Device Class)**: - -.. code-block:: c - - #define CFG_TUD_CDC 1 // Number of CDC interfaces - #define CFG_TUD_CDC_EP_BUFSIZE 512 // CDC endpoint buffer size - #define CFG_TUD_CDC_RX_BUFSIZE 256 // CDC RX FIFO size - #define CFG_TUD_CDC_TX_BUFSIZE 256 // CDC TX FIFO size - -**HID (Human Interface Device)**: - -.. code-block:: c - - #define CFG_TUD_HID 1 // Number of HID interfaces - #define CFG_TUD_HID_EP_BUFSIZE 16 // HID endpoint buffer size - -**MSC (Mass Storage Class)**: - -.. code-block:: c - - #define CFG_TUD_MSC 1 // Number of MSC interfaces - #define CFG_TUD_MSC_EP_BUFSIZE 512 // MSC endpoint buffer size - -**Audio Class**: - -.. code-block:: c - - #define CFG_TUD_AUDIO 1 // Number of audio interfaces - #define CFG_TUD_AUDIO_FUNC_1_DESC_LEN 220 - #define CFG_TUD_AUDIO_FUNC_1_N_AS_INT 1 - #define CFG_TUD_AUDIO_FUNC_1_CTRL_BUF_SZ 64 - #define CFG_TUD_AUDIO_ENABLE_EP_IN 1 - #define CFG_TUD_AUDIO_FUNC_1_N_BYTES_PER_SAMPLE_TX 2 - #define CFG_TUD_AUDIO_FUNC_1_N_CHANNELS_TX 2 - -**MIDI**: - -.. code-block:: c - - #define CFG_TUD_MIDI 1 // Number of MIDI interfaces - #define CFG_TUD_MIDI_RX_BUFSIZE 128 // MIDI RX buffer size - #define CFG_TUD_MIDI_TX_BUFSIZE 128 // MIDI TX buffer size - -**DFU (Device Firmware Update)**: - -.. code-block:: c - - #define CFG_TUD_DFU 1 // Enable DFU mode - #define CFG_TUD_DFU_XFER_BUFSIZE 512 // DFU transfer buffer size - -**Vendor Class**: - -.. code-block:: c - - #define CFG_TUD_VENDOR 1 // Number of vendor interfaces - #define CFG_TUD_VENDOR_EPSIZE 64 // Vendor endpoint size - #define CFG_TUD_VENDOR_RX_BUFSIZE 64 // RX buffer size (0 = no buffering) - #define CFG_TUD_VENDOR_TX_BUFSIZE 64 // TX buffer size (0 = no buffering) - -.. note:: - Unlike other classes, vendor class supports setting buffer sizes to 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. - -Host Stack Configuration -======================== - -Port and Hub Configuration --------------------------- - -.. code-block:: c - - // Number of host root hub ports - #define CFG_TUH_HUB 1 - - // Number of connected devices (including hub) - #define CFG_TUH_DEVICE_MAX 5 - - // Control transfer buffer size - #define CFG_TUH_ENUMERATION_BUFSIZE 512 - -Host Classes ------------- - -**CDC Host**: - -.. code-block:: c - - #define CFG_TUH_CDC 2 // Number of CDC host instances - #define CFG_TUH_CDC_FTDI 1 // FTDI serial support - #define CFG_TUH_CDC_CP210X 1 // CP210x serial support - #define CFG_TUH_CDC_CH34X 1 // CH34x serial support - -**HID Host**: - -.. code-block:: c - - #define CFG_TUH_HID 4 // Number of HID instances - #define CFG_TUH_HID_EPIN_BUFSIZE 64 // HID endpoint buffer size - #define CFG_TUH_HID_EPOUT_BUFSIZE 64 - -**MSC Host**: - -.. code-block:: c - - #define CFG_TUH_MSC 1 // Number of MSC instances - #define CFG_TUH_MSC_MAXLUN 4 // Max LUNs per device - -Advanced Configuration -====================== - -Memory Management ------------------ - -.. code-block:: c - - // Enable stack protection - #define CFG_TUSB_DEBUG_PRINTF printf - - // Custom memory allocation (if needed) - #define CFG_TUSB_MEM_SECTION __attribute__((section(".usb_ram"))) - -RTOS Configuration ------------------- - -TinyUSB supports multiple operating systems through its OSAL (Operating System Abstraction Layer). Choose the appropriate configuration based on your target environment. - -**FreeRTOS Integration**: - -When using FreeRTOS, configure the task queue sizes to handle USB events efficiently: - -.. code-block:: c - - #define CFG_TUSB_OS OPT_OS_FREERTOS - #define CFG_TUD_TASK_QUEUE_SZ 16 // Device task queue size - #define CFG_TUH_TASK_QUEUE_SZ 16 // Host task queue size - -**RT-Thread Integration**: - -RT-Thread requires only the OS selection, as it uses the RTOS's built-in primitives: - -.. code-block:: c - - #define CFG_TUSB_OS OPT_OS_RTTHREAD - -Low Power Configuration ------------------------ - -.. code-block:: c - - // Enable remote wakeup - #define CFG_TUD_USBD_ENABLE_REMOTE_WAKEUP 1 - - // Suspend/resume callbacks - // Implement tud_suspend_cb() and tud_resume_cb() - -MCU-Specific Options -==================== - -The ``CFG_TUSB_MCU`` option selects the target microcontroller family: - -.. code-block:: c - - // STM32 families - #define CFG_TUSB_MCU OPT_MCU_STM32F0 - #define CFG_TUSB_MCU OPT_MCU_STM32F1 - #define CFG_TUSB_MCU OPT_MCU_STM32F4 - #define CFG_TUSB_MCU OPT_MCU_STM32F7 - #define CFG_TUSB_MCU OPT_MCU_STM32H7 - - // NXP families - #define CFG_TUSB_MCU OPT_MCU_LPC18XX - #define CFG_TUSB_MCU OPT_MCU_LPC40XX - #define CFG_TUSB_MCU OPT_MCU_LPC43XX - #define CFG_TUSB_MCU OPT_MCU_KINETIS_KL - #define CFG_TUSB_MCU OPT_MCU_IMXRT - - // Other vendors - #define CFG_TUSB_MCU OPT_MCU_RP2040 - #define CFG_TUSB_MCU OPT_MCU_ESP32S2 - #define CFG_TUSB_MCU OPT_MCU_ESP32S3 - #define CFG_TUSB_MCU OPT_MCU_SAMD21 - #define CFG_TUSB_MCU OPT_MCU_SAMD51 - #define CFG_TUSB_MCU OPT_MCU_NRF5X - -Configuration Examples -====================== - -Minimal Device (CDC only) --------------------------- - -.. code-block:: c - - #define CFG_TUSB_MCU OPT_MCU_STM32F4 - #define CFG_TUSB_OS OPT_OS_NONE - #define CFG_TUSB_DEBUG 0 - - #define CFG_TUD_ENABLED 1 - #define CFG_TUD_ENDPOINT0_SIZE 64 - - #define CFG_TUD_CDC 1 - #define CFG_TUD_CDC_EP_BUFSIZE 512 - #define CFG_TUD_CDC_RX_BUFSIZE 512 - #define CFG_TUD_CDC_TX_BUFSIZE 512 - - // Disable other classes - #define CFG_TUD_HID 0 - #define CFG_TUD_MSC 0 - #define CFG_TUD_MIDI 0 - #define CFG_TUD_AUDIO 0 - #define CFG_TUD_VENDOR 0 - -Full-Featured Host ------------------- - -.. code-block:: c - - #define CFG_TUSB_MCU OPT_MCU_STM32F4 - #define CFG_TUSB_OS OPT_OS_FREERTOS - #define CFG_TUSB_DEBUG 2 - - #define CFG_TUH_ENABLED 1 - #define CFG_TUH_HUB 1 - #define CFG_TUH_DEVICE_MAX 8 - #define CFG_TUH_ENUMERATION_BUFSIZE 512 - - #define CFG_TUH_CDC 2 - #define CFG_TUH_HID 4 - #define CFG_TUH_MSC 2 - #define CFG_TUH_VENDOR 2 - -Validation -========== - -Use these checks to validate your configuration: - -.. code-block:: c - - // In your main.c, add compile-time checks - #if !defined(CFG_TUSB_MCU) || (CFG_TUSB_MCU == OPT_MCU_NONE) - #error "CFG_TUSB_MCU must be defined" - #endif - - #if CFG_TUD_ENABLED && !defined(CFG_TUD_ENDPOINT0_SIZE) - #error "CFG_TUD_ENDPOINT0_SIZE must be defined for device stack" - #endif - -Common Configuration Issues -=========================== - -1. **Endpoint buffer size too small**: Causes transfer failures -2. **Missing CFG_TUSB_MCU**: Build will fail -3. **Incorrect OS setting**: RTOS functions won't work properly -4. **Insufficient endpoint count**: Device enumeration will fail -5. **Buffer size mismatches**: Data corruption or transfer failures - -For configuration examples specific to your board, check ``examples/device/*/tusb_config.h``.
\ No newline at end of file diff --git a/docs/reference/index.rst b/docs/reference/index.rst index cb35dd1b9..d3c96eeee 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -7,9 +7,8 @@ Complete reference documentation for TinyUSB APIs, configuration, and supported .. toctree:: :maxdepth: 2 - api/index - configuration - usb_classes + architecture + usb_concepts boards dependencies concurrency diff --git a/docs/reference/usb_classes.rst b/docs/reference/usb_classes.rst deleted file mode 100644 index 387587b48..000000000 --- a/docs/reference/usb_classes.rst +++ /dev/null @@ -1,287 +0,0 @@ -*********** -USB Classes -*********** - -TinyUSB supports multiple USB device and host classes. This reference describes the features, capabilities, and requirements for each class. - -Device Classes -============== - -CDC (Communication Device Class) --------------------------------- - -Implements USB CDC specification for serial communication. - -**Supported Features:** -- CDC-ACM (Abstract Control Model) for virtual serial ports -- Data terminal ready (DTR) and request to send (RTS) control lines -- Line coding configuration (baud rate, parity, stop bits) -- Break signal support - -**Configuration:** -- ``CFG_TUD_CDC``: Number of CDC interfaces (1-4) -- ``CFG_TUD_CDC_EP_BUFSIZE``: Endpoint buffer size (typically 512) -- ``CFG_TUD_CDC_RX_BUFSIZE``: Receive FIFO size -- ``CFG_TUD_CDC_TX_BUFSIZE``: Transmit FIFO size - -**Key Functions:** -- ``tud_cdc_available()``: Check bytes available to read -- ``tud_cdc_read()``: Read data from host -- ``tud_cdc_write()``: Write data to host -- ``tud_cdc_write_flush()``: Flush transmit buffer - -**Callbacks:** -- ``tud_cdc_line_coding_cb()``: Line coding changed -- ``tud_cdc_line_state_cb()``: DTR/RTS state changed - -HID (Human Interface Device) ----------------------------- - -Implements USB HID specification for input devices. - -**Supported Features:** -- Boot protocol (keyboard/mouse) -- Report protocol with custom descriptors -- Input, output, and feature reports -- Multiple HID interfaces - -**Configuration:** -- ``CFG_TUD_HID``: Number of HID interfaces -- ``CFG_TUD_HID_EP_BUFSIZE``: Endpoint buffer size - -**Key Functions:** -- ``tud_hid_ready()``: Check if ready to send report -- ``tud_hid_report()``: Send HID report -- ``tud_hid_keyboard_report()``: Send keyboard report -- ``tud_hid_mouse_report()``: Send mouse report - -**Callbacks:** -- ``tud_hid_descriptor_report_cb()``: Provide report descriptor -- ``tud_hid_get_report_cb()``: Handle get report request -- ``tud_hid_set_report_cb()``: Handle set report request - -MSC (Mass Storage Class) ------------------------- - -Implements USB mass storage for file systems. - -**Supported Features:** -- SCSI transparent command set -- Multiple logical units (LUNs) -- Read/write operations -- Inquiry and capacity commands - -**Configuration:** -- ``CFG_TUD_MSC``: Number of MSC interfaces -- ``CFG_TUD_MSC_EP_BUFSIZE``: Endpoint buffer size - -**Key Functions:** -- Storage operations handled via callbacks - -**Required Callbacks:** -- ``tud_msc_inquiry_cb()``: Device inquiry information -- ``tud_msc_test_unit_ready_cb()``: Test if LUN is ready -- ``tud_msc_capacity_cb()``: Get LUN capacity -- ``tud_msc_start_stop_cb()``: Start/stop LUN -- ``tud_msc_read10_cb()``: Read data from LUN -- ``tud_msc_write10_cb()``: Write data to LUN - -Audio Class ------------ - -Implements USB Audio Class 2.0 specification. - -**Supported Features:** -- Audio streaming (input/output) -- Multiple sampling rates -- Volume and mute controls -- Feedback endpoints for asynchronous mode - -**Configuration:** -- ``CFG_TUD_AUDIO``: Number of audio functions -- Multiple configuration options for channels, sample rates, bit depth - -**Key Functions:** -- ``tud_audio_read()``: Read audio data -- ``tud_audio_write()``: Write audio data -- ``tud_audio_clear_ep_out_ff()``: Clear output FIFO - -MIDI ----- - -Implements USB MIDI specification. - -**Supported Features:** -- MIDI 1.0 message format -- Multiple virtual MIDI cables -- Standard MIDI messages - -**Configuration:** -- ``CFG_TUD_MIDI``: Number of MIDI interfaces -- ``CFG_TUD_MIDI_RX_BUFSIZE``: Receive buffer size -- ``CFG_TUD_MIDI_TX_BUFSIZE``: Transmit buffer size - -**Key Functions:** -- ``tud_midi_available()``: Check available MIDI messages -- ``tud_midi_read()``: Read MIDI packet -- ``tud_midi_write()``: Send MIDI packet - -DFU (Device Firmware Update) ----------------------------- - -Implements USB DFU specification for firmware updates. - -**Supported Modes:** -- DFU Mode: Device enters DFU for firmware update -- DFU Runtime: Request transition to DFU mode - -**Configuration:** -- ``CFG_TUD_DFU``: Enable DFU mode -- ``CFG_TUD_DFU_RUNTIME``: Enable DFU runtime - -**Key Functions:** -- Firmware update operations handled via callbacks - -**Required Callbacks:** -- ``tud_dfu_download_cb()``: Receive firmware data -- ``tud_dfu_manifest_cb()``: Complete firmware update - -Vendor Class ------------- - -Custom vendor-specific USB class implementation. - -**Features:** -- Configurable endpoints -- Custom protocol implementation -- WebUSB support -- Microsoft OS descriptors - -**Configuration:** -- ``CFG_TUD_VENDOR``: Number of vendor interfaces -- ``CFG_TUD_VENDOR_EPSIZE``: Endpoint size - -**Key Functions:** -- ``tud_vendor_available()``: Check available data -- ``tud_vendor_read()``: Read vendor data -- ``tud_vendor_write()``: Write vendor data - -Host Classes -============ - -CDC Host --------- - -Connect to CDC devices (virtual serial ports). - -**Supported Devices:** -- CDC-ACM devices -- FTDI USB-to-serial converters -- CP210x USB-to-serial converters -- CH34x USB-to-serial converters - -**Configuration:** -- ``CFG_TUH_CDC``: Number of CDC host instances -- ``CFG_TUH_CDC_FTDI``: Enable FTDI support -- ``CFG_TUH_CDC_CP210X``: Enable CP210x support - -**Key Functions:** -- ``tuh_cdc_available()``: Check available data -- ``tuh_cdc_read()``: Read from CDC device -- ``tuh_cdc_write()``: Write to CDC device -- ``tuh_cdc_set_baudrate()``: Configure serial settings - -HID Host --------- - -Connect to HID devices (keyboards, mice, etc.). - -**Supported Devices:** -- Boot keyboards and mice -- Generic HID devices with report descriptors -- Composite HID devices - -**Configuration:** -- ``CFG_TUH_HID``: Number of HID host instances -- ``CFG_TUH_HID_EPIN_BUFSIZE``: Input endpoint buffer size - -**Key Functions:** -- ``tuh_hid_receive_report()``: Start receiving reports -- ``tuh_hid_send_report()``: Send report to device -- ``tuh_hid_parse_report_descriptor()``: Parse HID descriptors - -MSC Host --------- - -Connect to mass storage devices (USB drives). - -**Supported Features:** -- SCSI transparent command set -- FAT file system support (with FatFS integration) -- Multiple LUNs per device - -**Configuration:** -- ``CFG_TUH_MSC``: Number of MSC host instances -- ``CFG_TUH_MSC_MAXLUN``: Maximum LUNs per device - -**Key Functions:** -- ``tuh_msc_ready()``: Check if device is ready -- ``tuh_msc_read10()``: Read sectors from device -- ``tuh_msc_write10()``: Write sectors to device - -Hub ---- - -Support for USB hubs to connect multiple devices. - -**Features:** -- Multi-level hub support -- Port power management -- Device connect/disconnect detection - -**Configuration:** -- ``CFG_TUH_HUB``: Number of hub instances -- ``CFG_TUH_DEVICE_MAX``: Total connected devices - -Class Implementation Guidelines -=============================== - -Descriptor Requirements ------------------------ - -Each USB class requires specific descriptors: - -1. **Interface Descriptor**: Defines the class type -2. **Endpoint Descriptors**: Define communication endpoints -3. **Class-Specific Descriptors**: Additional class requirements -4. **String Descriptors**: Human-readable device information - -Callback Implementation ------------------------ - -Most classes require callback functions: - -- **Mandatory callbacks**: Must be implemented for class to function -- **Optional callbacks**: Provide additional functionality -- **Event callbacks**: Called when specific events occur - -Performance Considerations --------------------------- - -When implementing USB classes, match **buffer sizes** to expected data rates to avoid bottlenecks. Choose appropriate **transfer types** based on your application's requirements. Keep **callback processing** lightweight for optimal performance. Avoid **memory allocations in critical paths** where possible to maintain consistent performance. - -Testing and Validation ----------------------- - -- **USB-IF Compliance**: Ensure descriptors meet USB standards -- **Host Compatibility**: Test with multiple operating systems -- **Performance Testing**: Verify transfer rates and latency -- **Error Handling**: Test disconnect/reconnect scenarios - -Class-Specific Resources -======================== - -- **USB-IF Specifications**: Official USB class specifications -- **Example Code**: Reference implementations in ``examples/`` directory -- **Test Applications**: Host-side test applications for validation -- **Debugging Tools**: USB protocol analyzers and debugging utilities
\ No newline at end of file diff --git a/docs/explanation/usb_concepts.rst b/docs/reference/usb_concepts.rst index e3d400921..86ae97007 100644 --- a/docs/explanation/usb_concepts.rst +++ b/docs/reference/usb_concepts.rst @@ -30,7 +30,7 @@ Host and Device Roles - 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:`../tutorials/getting_started` Quick Start Examples for implementation details. +**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 @@ -38,7 +38,7 @@ Host and Device Roles - 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:`../tutorials/getting_started` Quick Start Examples for implementation details. +**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. @@ -226,7 +226,10 @@ USB classes define standardized protocols for device types: - **DFU**: Device Firmware Update - Enable with ``CFG_TUD_DFU`` - **Vendor**: Custom vendor classes - Enable with ``CFG_TUD_VENDOR`` -See :doc:`../reference/usb_classes` for detailed class information and :doc:`../reference/configuration` for configuration options. +.. 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 ========== @@ -420,6 +423,6 @@ USB provides power to devices: Next Steps ========== -- Start with :doc:`../tutorials/getting_started` for basic setup -- Review :doc:`../reference/configuration` for configuration options -- Explore :doc:`../examples` for advanced use cases +- 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 diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst deleted file mode 100644 index dc362d717..000000000 --- a/docs/tutorials/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -********* -Tutorials -********* - -Step-by-step learning guides for TinyUSB development. - -.. toctree:: - :maxdepth: 2 - - getting_started
\ No newline at end of file |