mirror of
https://github.com/hathach/tinyusb.git
synced 2025-12-01 12:24:17 +00:00
305 lines
7.0 KiB
ReStructuredText
305 lines
7.0 KiB
ReStructuredText
***************
|
|
Troubleshooting
|
|
***************
|
|
|
|
This guide helps you diagnose and fix common issues when developing with TinyUSB.
|
|
|
|
Build Issues
|
|
============
|
|
|
|
Toolchain Problems
|
|
------------------
|
|
|
|
**"arm-none-eabi-gcc: command not found"**
|
|
|
|
The ARM GCC toolchain is not installed or not in PATH.
|
|
|
|
*Solution*:
|
|
|
|
.. code-block:: bash
|
|
|
|
# Ubuntu/Debian
|
|
$ sudo apt-get update && sudo apt-get install gcc-arm-none-eabi
|
|
|
|
# macOS with Homebrew
|
|
$ brew install --cask gcc-arm-embedded
|
|
|
|
# Windows: Download from ARM website and add to PATH
|
|
|
|
**"make: command not found" or CMake errors**
|
|
|
|
Build tools are missing.
|
|
|
|
*Solution*:
|
|
|
|
.. code-block:: bash
|
|
|
|
# Ubuntu/Debian
|
|
$ sudo apt-get install build-essential cmake
|
|
|
|
# macOS
|
|
$ xcode-select --install
|
|
$ brew install cmake
|
|
|
|
Dependency Issues
|
|
-----------------
|
|
|
|
**"No rule to make target" or missing header files**
|
|
|
|
Dependencies for your MCU family are not downloaded.
|
|
|
|
*Solution*:
|
|
|
|
.. code-block:: bash
|
|
|
|
# Download dependencies for specific board or family
|
|
$ python tools/get_deps.py -b stm32h743eval # Replace with your board
|
|
$ python tools/get_deps.py stm32f4 # Replace with your family
|
|
|
|
# Or from example directory
|
|
cd examples/device/cdc_msc
|
|
make BOARD=your_board get-deps
|
|
|
|
**Board Not Found**
|
|
|
|
Invalid board name in build command.
|
|
|
|
*Diagnosis*:
|
|
|
|
.. code-block:: bash
|
|
|
|
# List available boards for a family
|
|
ls hw/bsp/stm32f4/boards/
|
|
|
|
*Solution*: Use exact board name from the listing.
|
|
|
|
Runtime Issues
|
|
==============
|
|
|
|
Device Mode Problems
|
|
--------------------
|
|
|
|
**Device not recognized by host**
|
|
|
|
The most common issue - host doesn't see your USB device.
|
|
|
|
*Diagnosis steps*:
|
|
|
|
1. Check USB cable (must support data, not just power)
|
|
2. Enable logging: build with ``LOG=2``
|
|
3. Use different USB ports/hosts
|
|
4. Check device manager (Windows) or ``dmesg`` (Linux)
|
|
|
|
*Common causes and solutions*:
|
|
|
|
- **Invalid descriptors**: Review ``usb_descriptors.c`` carefully
|
|
- **``tud_task()`` not called**: Ensure regular calls in main loop (< 1ms interval)
|
|
- **Wrong USB configuration**: Check ``tusb_config.h`` settings
|
|
- **Hardware issues**: Verify USB pins, crystal/clock configuration
|
|
|
|
**Enumeration starts but fails**
|
|
|
|
Device is detected but configuration fails.
|
|
|
|
*Diagnosis*:
|
|
|
|
.. code-block:: bash
|
|
|
|
# Build with logging enabled
|
|
make BOARD=your_board LOG=2 all
|
|
|
|
*Look for*:
|
|
|
|
- Setup request handling errors
|
|
- Endpoint configuration problems
|
|
- String descriptor issues
|
|
|
|
*Solutions*:
|
|
|
|
- Implement all required descriptors
|
|
- Check endpoint sizes match descriptors
|
|
- Ensure control endpoint (EP0) handling is correct
|
|
|
|
**Data transfer issues**
|
|
|
|
Device enumerates but data doesn't transfer correctly.
|
|
|
|
*Common causes*:
|
|
|
|
- Buffer overruns in class callbacks
|
|
- Incorrect endpoint usage (IN vs OUT)
|
|
- Flow control issues in CDC class
|
|
|
|
*Solutions*:
|
|
|
|
- Check buffer sizes in callbacks
|
|
- Verify endpoint directions in descriptors
|
|
- Implement proper flow control
|
|
|
|
Host Mode Problems
|
|
------------------
|
|
|
|
**No devices detected**
|
|
|
|
Host application doesn't see connected devices.
|
|
|
|
*Hardware checks*:
|
|
|
|
- Power supply adequate for host mode
|
|
- USB-A connector for host (not micro-USB)
|
|
- Board supports host mode on selected port
|
|
|
|
*Software checks*:
|
|
|
|
- ``tuh_task()`` called regularly
|
|
- Host stack enabled in ``tusb_config.h``
|
|
- Correct root hub port configuration
|
|
|
|
**Device enumeration fails**
|
|
|
|
Devices connect but enumeration fails.
|
|
|
|
*Diagnosis*:
|
|
|
|
.. code-block:: bash
|
|
|
|
# Enable host logging
|
|
make BOARD=your_board LOG=2 RHPORT_HOST=1 all
|
|
|
|
*Common issues*:
|
|
|
|
- Power supply insufficient during enumeration
|
|
- Timing issues with slow devices
|
|
- USB hub compatibility problems
|
|
|
|
**Class driver issues**
|
|
|
|
Device enumerates but class-specific communication fails.
|
|
|
|
*Troubleshooting*:
|
|
|
|
- Check device descriptors match expected class
|
|
- Verify interface/endpoint assignments
|
|
- Some devices need device-specific handling
|
|
|
|
Performance Issues
|
|
==================
|
|
|
|
Slow Transfer Speeds
|
|
--------------------
|
|
|
|
**Symptoms**: Lower than expected USB transfer rates
|
|
|
|
*Causes and solutions*: Improve **task scheduling** by calling ``tud_task()``/``tuh_task()`` more frequently to ensure timely USB event processing. Consider increasing **endpoint buffer sizes** for bulk transfers to reduce the frequency of small transfers. Enable **DMA usage** for USB transfers if your hardware supports it to offload CPU processing. Finally, use **High Speed** (480 Mbps) instead of Full Speed (12 Mbps) when possible to achieve better throughput.
|
|
|
|
High CPU Usage
|
|
--------------
|
|
|
|
**Symptoms**: MCU spending too much time in USB handling
|
|
|
|
*Solutions*:
|
|
|
|
- Use efficient logging (RTT/SWO instead of UART)
|
|
- Reduce log level in production builds
|
|
- Optimize descriptor parsing
|
|
- Use DMA for data transfers
|
|
|
|
Hardware-Specific Issues
|
|
========================
|
|
|
|
STM32 Issues
|
|
------------
|
|
|
|
**Clock configuration problems**:
|
|
|
|
- USB requires precise 48MHz clock
|
|
- HSE crystal must be configured correctly
|
|
- PLL settings affect USB timing
|
|
|
|
**Pin configuration**:
|
|
|
|
- USB pins need specific alternate function settings
|
|
- VBUS sensing configuration
|
|
- ID pin for OTG applications
|
|
|
|
RP2040 Issues
|
|
-------------
|
|
|
|
**PIO-USB for host mode**:
|
|
|
|
- Requires specific pin assignments
|
|
- CPU overclocking may be needed for reliable operation
|
|
- Timing-sensitive - avoid long interrupt disable periods
|
|
|
|
ESP32 Issues
|
|
------------
|
|
|
|
**USB peripheral differences**:
|
|
|
|
- ESP32-S2/S3/P4 have different USB capabilities
|
|
- DMA configuration varies between models
|
|
|
|
Advanced Debugging
|
|
==================
|
|
|
|
Using USB Analyzers
|
|
-------------------
|
|
|
|
For complex issues, hardware USB analyzers provide detailed protocol traces:
|
|
|
|
- **Wireshark** with USBPcap (Windows) or usbmon (Linux)
|
|
- **Hardware analyzers**: Total Phase Beagle, LeCroy USB analyzers
|
|
- **Logic analyzers**: For timing analysis of USB signals
|
|
|
|
Debugging with GDB
|
|
------------------
|
|
|
|
Debugging with traditional debuggers is limited due to the real time nature of USB.
|
|
However, especially for diagnosis of crashes, it can still be useful.
|
|
|
|
.. code-block:: bash
|
|
|
|
# Build with debug info
|
|
make BOARD=your_board DEBUG=1 all
|
|
|
|
# Use with debugger
|
|
arm-none-eabi-gdb build/your_app.elf
|
|
|
|
*Useful breakpoints*:
|
|
|
|
- ``dcd_int_handler()`` - USB interrupt entry
|
|
- ``tud_task()`` - Main device task
|
|
- Class-specific callbacks
|
|
|
|
Custom Logging
|
|
--------------
|
|
|
|
For production debugging, implement custom logging:
|
|
|
|
.. code-block:: c
|
|
|
|
// In tusb_config.h
|
|
#define CFG_TUSB_DEBUG_PRINTF my_printf
|
|
|
|
// Your implementation
|
|
void my_printf(const char* format, ...) {
|
|
// Send to RTT, SWO, or custom interface
|
|
}
|
|
|
|
Getting Help
|
|
============
|
|
|
|
When reporting issues:
|
|
|
|
1. **Minimal reproducible example**: Simplify to bare minimum
|
|
2. **Build information**: Board, toolchain version, build flags
|
|
3. **Logs**: Include output with ``LOG=2`` enabled
|
|
4. **Hardware details**: Board revision, USB connections, power supply
|
|
5. **Host environment**: OS version, USB port type
|
|
|
|
**Resources**:
|
|
|
|
- GitHub Discussions: https://github.com/hathach/tinyusb/discussions
|
|
- Issue Tracker: https://github.com/hathach/tinyusb/issues
|
|
- Documentation: https://docs.tinyusb.org
|