WIP improved docs (feat. LLM)

1 files changed, 290 insertions, 0 deletions

diff --git a/docs/reference/usb_classes.rst b/docs/reference/usb_classes.rst
new file mode 100644
index 000000000..00a251ffb
--- /dev/null
+++ b/docs/reference/usb_classes.rst
@@ -0,0 +1,290 @@
+***********
+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
+--------------------------
+
+- **Buffer Sizes**: Match endpoint buffer sizes to expected data rates
+- **Transfer Types**: Use appropriate USB transfer types (bulk, interrupt, isochronous)
+- **CPU Usage**: Minimize processing in interrupt context
+- **Memory Usage**: Static allocation only, no dynamic memory
+
+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