|
| 1 | +# TinyUSB |
| 2 | +TinyUSB is an open-source cross-platform USB Host/Device stack for embedded systems, designed to be memory-safe with no dynamic allocation and thread-safe with all interrupt events deferred to non-ISR task functions. |
| 3 | + |
| 4 | +Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. |
| 5 | + |
| 6 | +## Working Effectively |
| 7 | + |
| 8 | +### Bootstrap and Build Setup |
| 9 | +- Install ARM GCC toolchain: `sudo apt-get update && sudo apt-get install -y gcc-arm-none-eabi` |
| 10 | +- Fetch core dependencies: `python3 tools/get_deps.py` -- takes <1 second. NEVER CANCEL. |
| 11 | +- For specific board families: `python3 tools/get_deps.py FAMILY_NAME` (e.g., rp2040, stm32f4) |
| 12 | +- Dependencies are cached in `lib/` and `hw/mcu/` directories |
| 13 | + |
| 14 | +### Build Examples |
| 15 | +Choose ONE of these approaches: |
| 16 | + |
| 17 | +**Option 1: Individual Example with CMake (RECOMMENDED)** |
| 18 | +```bash |
| 19 | +cd examples/device/cdc_msc |
| 20 | +mkdir -p build && cd build |
| 21 | +cmake -DBOARD=stm32f407disco -DCMAKE_BUILD_TYPE=MinSizeRel .. |
| 22 | +cmake --build . -j4 |
| 23 | +``` |
| 24 | +-- takes 1-2 seconds. NEVER CANCEL. Set timeout to 5+ minutes. |
| 25 | + |
| 26 | +**Option 2: Individual Example with Make** |
| 27 | +```bash |
| 28 | +cd examples/device/cdc_msc |
| 29 | +make BOARD=stm32f407disco all |
| 30 | +``` |
| 31 | +-- takes 2-3 seconds. NEVER CANCEL. Set timeout to 5+ minutes. |
| 32 | + |
| 33 | +**Option 3: All Examples for a Board** |
| 34 | +```bash |
| 35 | +python3 tools/build.py -b BOARD_NAME |
| 36 | +``` |
| 37 | +-- takes 15-20 seconds, may have some objcopy failures that are non-critical. NEVER CANCEL. Set timeout to 30+ minutes. |
| 38 | + |
| 39 | +### Unit Testing |
| 40 | +- Install Ceedling: `sudo gem install ceedling` |
| 41 | +- Run all unit tests: `cd test/unit-test && ceedling` -- takes 4 seconds. NEVER CANCEL. Set timeout to 10+ minutes. |
| 42 | +- Tests use Unity framework with CMock for mocking |
| 43 | + |
| 44 | +### Documentation |
| 45 | +- Install requirements: `pip install -r docs/requirements.txt` |
| 46 | +- Build docs: `cd docs && sphinx-build -b html . _build` -- takes 2-3 seconds. NEVER CANCEL. Set timeout to 10+ minutes. |
| 47 | + |
| 48 | +### Code Quality and Validation |
| 49 | +- Format code: `clang-format -i path/to/file.c` (uses `.clang-format` config) |
| 50 | +- Check spelling: `pip install codespell && codespell` (uses `.codespellrc` config) |
| 51 | +- Pre-commit hooks validate unit tests and code quality automatically |
| 52 | + |
| 53 | +## Validation |
| 54 | + |
| 55 | +### ALWAYS Run These After Making Changes |
| 56 | +1. **Pre-commit validation** (RECOMMENDED): `pre-commit run --all-files` |
| 57 | + - Install pre-commit: `pip install pre-commit && pre-commit install` |
| 58 | + - Runs all quality checks, unit tests, spell checking, and formatting |
| 59 | + - Takes 10-15 seconds. NEVER CANCEL. Set timeout to 15+ minutes. |
| 60 | +2. **Build validation**: Build at least one example that exercises your changes |
| 61 | + ```bash |
| 62 | + cd examples/device/cdc_msc |
| 63 | + make BOARD=stm32f407disco all |
| 64 | + ``` |
| 65 | + |
| 66 | +### Manual Testing Scenarios |
| 67 | +- **Device examples**: Cannot be fully tested without real hardware, but must build successfully |
| 68 | +- **Unit tests**: Exercise core stack functionality - ALL tests must pass |
| 69 | +- **Build system**: Must be able to build examples for multiple board families |
| 70 | + |
| 71 | +### Board Selection for Testing |
| 72 | +- **STM32F4**: `stm32f407disco` - no external SDK required, good for testing |
| 73 | +- **RP2040**: `pico_sdk` - requires Pico SDK, commonly used |
| 74 | +- **Other families**: Check `hw/bsp/FAMILY/boards/` for available boards |
| 75 | + |
| 76 | +## Common Tasks and Time Expectations |
| 77 | + |
| 78 | +### Repository Structure Quick Reference |
| 79 | +``` |
| 80 | +├── src/ # Core TinyUSB stack |
| 81 | +│ ├── class/ # USB device classes (CDC, HID, MSC, Audio, etc.) |
| 82 | +│ ├── portable/ # MCU-specific drivers (organized by vendor) |
| 83 | +│ ├── device/ # USB device stack core |
| 84 | +│ ├── host/ # USB host stack core |
| 85 | +│ └── common/ # Shared utilities (FIFO, etc.) |
| 86 | +├── examples/ # Example applications |
| 87 | +│ ├── device/ # Device examples (cdc_msc, hid_generic, etc.) |
| 88 | +│ ├── host/ # Host examples |
| 89 | +│ └── dual/ # Dual-role examples |
| 90 | +├── hw/bsp/ # Board Support Packages |
| 91 | +│ └── FAMILY/boards/ # Board-specific configurations |
| 92 | +├── test/unit-test/ # Unit tests using Ceedling |
| 93 | +├── tools/ # Build and utility scripts |
| 94 | +└── docs/ # Sphinx documentation |
| 95 | +``` |
| 96 | + |
| 97 | +### Build Time Reference |
| 98 | +- **Dependency fetch**: <1 second |
| 99 | +- **Single example build**: 1-3 seconds |
| 100 | +- **Unit tests**: ~4 seconds |
| 101 | +- **Documentation build**: ~2.5 seconds |
| 102 | +- **Full board examples**: 15-20 seconds |
| 103 | +- **Toolchain installation**: 2-5 minutes (one-time) |
| 104 | + |
| 105 | +### Key Files to Know |
| 106 | +- `tools/get_deps.py`: Manages dependencies for MCU families |
| 107 | +- `tools/build.py`: Builds multiple examples, supports make/cmake |
| 108 | +- `src/tusb.h`: Main TinyUSB header file |
| 109 | +- `src/tusb_config.h`: Configuration template |
| 110 | +- `examples/device/cdc_msc/`: Most commonly used example for testing |
| 111 | +- `test/unit-test/project.yml`: Ceedling test configuration |
| 112 | + |
| 113 | +### Debugging Build Issues |
| 114 | +- **Missing compiler**: Install `gcc-arm-none-eabi` package |
| 115 | +- **Missing dependencies**: Run `python3 tools/get_deps.py FAMILY` |
| 116 | +- **Board not found**: Check `hw/bsp/FAMILY/boards/` for valid board names |
| 117 | +- **objcopy errors**: Often non-critical in full builds, try individual example builds |
| 118 | + |
| 119 | +### Working with USB Device Classes |
| 120 | +- **CDC (Serial)**: `src/class/cdc/` - Virtual serial port |
| 121 | +- **HID**: `src/class/hid/` - Human Interface Device (keyboard, mouse, etc.) |
| 122 | +- **MSC**: `src/class/msc/` - Mass Storage Class (USB drive) |
| 123 | +- **Audio**: `src/class/audio/` - USB Audio Class |
| 124 | +- Each class has device (`*_device.c`) and host (`*_host.c`) implementations |
| 125 | + |
| 126 | +### MCU Family Support |
| 127 | +- **STM32**: Largest support (F0, F1, F2, F3, F4, F7, G0, G4, H7, L4, U5, etc.) |
| 128 | +- **Raspberry Pi**: RP2040, RP2350 with PIO-USB host support |
| 129 | +- **NXP**: iMXRT, Kinetis, LPC families |
| 130 | +- **Microchip**: SAM D/E/G/L families |
| 131 | +- Check `hw/bsp/` for complete list and `docs/reference/boards.rst` for details |
| 132 | + |
| 133 | +Remember: TinyUSB is designed for embedded systems - builds are fast, tests are focused, and the codebase is optimized for resource-constrained environments. |
0 commit comments