|
| 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=raspberry_pi_pico -DCMAKE_BUILD_TYPE=MinSizeRel .. |
| 22 | +cmake --build . -j4 |
| 23 | +``` |
| 24 | +-- takes 1-2 seconds. NEVER CANCEL. Set timeout to 5+ minutes. |
| 25 | + |
| 26 | +**CMake with Ninja (Alternative)** |
| 27 | +```bash |
| 28 | +cd examples/device/cdc_msc |
| 29 | +mkdir build && cd build |
| 30 | +cmake -G Ninja -DBOARD=raspberry_pi_pico .. |
| 31 | +ninja |
| 32 | +``` |
| 33 | + |
| 34 | +**Option 2: Individual Example with Make** |
| 35 | +```bash |
| 36 | +cd examples/device/cdc_msc |
| 37 | +make BOARD=raspberry_pi_pico all |
| 38 | +``` |
| 39 | +-- takes 2-3 seconds. NEVER CANCEL. Set timeout to 5+ minutes. |
| 40 | + |
| 41 | +**Option 3: All Examples for a Board** |
| 42 | +```bash |
| 43 | +python3 tools/build.py -b BOARD_NAME |
| 44 | +``` |
| 45 | +-- takes 15-20 seconds, may have some objcopy failures that are non-critical. NEVER CANCEL. Set timeout to 30+ minutes. |
| 46 | + |
| 47 | +### Build Options |
| 48 | +- **Debug build**: |
| 49 | + - CMake: `-DCMAKE_BUILD_TYPE=Debug` |
| 50 | + - Make: `DEBUG=1` |
| 51 | +- **With logging**: |
| 52 | + - CMake: `-DLOG=2` |
| 53 | + - Make: `LOG=2` |
| 54 | +- **With RTT logger**: |
| 55 | + - CMake: `-DLOG=2 -DLOGGER=rtt` |
| 56 | + - Make: `LOG=2 LOGGER=rtt` |
| 57 | +- **RootHub port selection**: |
| 58 | + - CMake: `-DRHPORT_DEVICE=1` |
| 59 | + - Make: `RHPORT_DEVICE=1` |
| 60 | +- **Port speed**: |
| 61 | + - CMake: `-DRHPORT_DEVICE_SPEED=OPT_MODE_FULL_SPEED` |
| 62 | + - Make: `RHPORT_DEVICE_SPEED=OPT_MODE_FULL_SPEED` |
| 63 | + |
| 64 | +### Flashing and Deploymen |
| 65 | +- **Flash with JLink**:1 |
| 66 | + - CMake: `ninja cdc_msc-jlink` |
| 67 | + - Make: `make BOARD=raspberry_pi_pico flash-jlink` |
| 68 | +- **Flash with OpenOCD**: |
| 69 | + - CMake: `ninja cdc_msc-openocd` |
| 70 | + - Make: `make BOARD=raspberry_pi_pico flash-openocd` |
| 71 | +- **Generate UF2**: |
| 72 | + - CMake: `ninja cdc_msc-uf2` |
| 73 | + - Make: `make BOARD=raspberry_pi_pico all uf2` |
| 74 | +- **List all targets** (CMake/Ninja): `ninja -t targets` |
| 75 | + |
| 76 | +### Unit Testing |
| 77 | +- Install Ceedling: `sudo gem install ceedling` |
| 78 | +- Run all unit tests: `cd test/unit-test && ceedling` or `cd test/unit-test && ceedling test:all` -- takes 4 seconds. NEVER CANCEL. Set timeout to 10+ minutes. |
| 79 | +- Run specific test: `cd test/unit-test && ceedling test:test_fifo` |
| 80 | +- Tests use Unity framework with CMock for mocking |
| 81 | + |
| 82 | +### Documentation |
| 83 | +- Install requirements: `pip install -r docs/requirements.txt` |
| 84 | +- Build docs: `cd docs && sphinx-build -b html . _build` -- takes 2-3 seconds. NEVER CANCEL. Set timeout to 10+ minutes. |
| 85 | + |
| 86 | +### Code Quality and Validation |
| 87 | +- Format code: `clang-format -i path/to/file.c` (uses `.clang-format` config) |
| 88 | +- Check spelling: `pip install codespell && codespell` (uses `.codespellrc` config) |
| 89 | +- Pre-commit hooks validate unit tests and code quality automatically |
| 90 | + |
| 91 | +## Validation |
| 92 | + |
| 93 | +### ALWAYS Run These After Making Changes |
| 94 | +1. **Pre-commit validation** (RECOMMENDED): `pre-commit run --all-files` |
| 95 | + - Install pre-commit: `pip install pre-commit && pre-commit install` |
| 96 | + - Runs all quality checks, unit tests, spell checking, and formatting |
| 97 | + - Takes 10-15 seconds. NEVER CANCEL. Set timeout to 15+ minutes. |
| 98 | +2. **Build validation**: Build at least one example that exercises your changes |
| 99 | + ```bash |
| 100 | + cd examples/device/cdc_msc |
| 101 | + make BOARD=raspberry_pi_pico all |
| 102 | + ``` |
| 103 | + |
| 104 | +### Manual Testing Scenarios |
| 105 | +- **Device examples**: Cannot be fully tested without real hardware, but must build successfully |
| 106 | +- **Unit tests**: Exercise core stack functionality - ALL tests must pass |
| 107 | +- **Build system**: Must be able to build examples for multiple board families |
| 108 | + |
| 109 | +### Board Selection for Testing |
| 110 | +- **STM32F4**: `stm32f407disco` - no external SDK required, good for testing |
| 111 | +- **RP2040**: `raspberry_pi_pico` - requires Pico SDK, commonly used |
| 112 | +- **Other families**: Check `hw/bsp/FAMILY/boards/` for available boards |
| 113 | + |
| 114 | +## Common Tasks and Time Expectations |
| 115 | + |
| 116 | +### Repository Structure Quick Reference |
| 117 | +``` |
| 118 | +├── src/ # Core TinyUSB stack |
| 119 | +│ ├── class/ # USB device classes (CDC, HID, MSC, Audio, etc.) |
| 120 | +│ ├── portable/ # MCU-specific drivers (organized by vendor) |
| 121 | +│ ├── device/ # USB device stack core |
| 122 | +│ ├── host/ # USB host stack core |
| 123 | +│ └── common/ # Shared utilities (FIFO, etc.) |
| 124 | +├── examples/ # Example applications |
| 125 | +│ ├── device/ # Device examples (cdc_msc, hid_generic, etc.) |
| 126 | +│ ├── host/ # Host examples |
| 127 | +│ └── dual/ # Dual-role examples |
| 128 | +├── hw/bsp/ # Board Support Packages |
| 129 | +│ └── FAMILY/boards/ # Board-specific configurations |
| 130 | +├── test/unit-test/ # Unit tests using Ceedling |
| 131 | +├── tools/ # Build and utility scripts |
| 132 | +└── docs/ # Sphinx documentation |
| 133 | +``` |
| 134 | + |
| 135 | +### Build Time Reference |
| 136 | +- **Dependency fetch**: <1 second |
| 137 | +- **Single example build**: 1-3 seconds |
| 138 | +- **Unit tests**: ~4 seconds |
| 139 | +- **Documentation build**: ~2.5 seconds |
| 140 | +- **Full board examples**: 15-20 seconds |
| 141 | +- **Toolchain installation**: 2-5 minutes (one-time) |
| 142 | + |
| 143 | +### Key Files to Know |
| 144 | +- `tools/get_deps.py`: Manages dependencies for MCU families |
| 145 | +- `tools/build.py`: Builds multiple examples, supports make/cmake |
| 146 | +- `src/tusb.h`: Main TinyUSB header file |
| 147 | +- `src/tusb_config.h`: Configuration template |
| 148 | +- `examples/device/cdc_msc/`: Most commonly used example for testing |
| 149 | +- `test/unit-test/project.yml`: Ceedling test configuration |
| 150 | + |
| 151 | +### Debugging Build Issues |
| 152 | +- **Missing compiler**: Install `gcc-arm-none-eabi` package |
| 153 | +- **Missing dependencies**: Run `python3 tools/get_deps.py FAMILY` |
| 154 | +- **Board not found**: Check `hw/bsp/FAMILY/boards/` for valid board names |
| 155 | +- **objcopy errors**: Often non-critical in full builds, try individual example builds |
| 156 | + |
| 157 | +### Working with USB Device Classes |
| 158 | +- **CDC (Serial)**: `src/class/cdc/` - Virtual serial port |
| 159 | +- **HID**: `src/class/hid/` - Human Interface Device (keyboard, mouse, etc.) |
| 160 | +- **MSC**: `src/class/msc/` - Mass Storage Class (USB drive) |
| 161 | +- **Audio**: `src/class/audio/` - USB Audio Class |
| 162 | +- Each class has device (`*_device.c`) and host (`*_host.c`) implementations |
| 163 | + |
| 164 | +### MCU Family Support |
| 165 | +- **STM32**: Largest support (F0, F1, F2, F3, F4, F7, G0, G4, H7, L4, U5, etc.) |
| 166 | +- **Raspberry Pi**: RP2040, RP2350 with PIO-USB host support |
| 167 | +- **NXP**: iMXRT, Kinetis, LPC families |
| 168 | +- **Microchip**: SAM D/E/G/L families |
| 169 | +- Check `hw/bsp/` for complete list and `docs/reference/boards.rst` for details |
| 170 | + |
| 171 | +## Code Style Guidelines |
| 172 | + |
| 173 | +### General Coding Standards |
| 174 | +- Use C99 standard |
| 175 | +- Memory-safe: no dynamic allocation |
| 176 | +- Thread-safe: defer all interrupt events to non-ISR task functions |
| 177 | +- 2-space indentation, no tabs |
| 178 | +- Use snake_case for variables/functions |
| 179 | +- Use UPPER_CASE for macros and constants |
| 180 | +- Follow existing variable naming patterns in files you're modifying |
| 181 | +- Include proper header comments with MIT license |
| 182 | +- Add descriptive comments for non-obvious functions |
| 183 | + |
| 184 | +### Best Practices |
| 185 | +- When including headers, group in order: C stdlib, tusb common, drivers, classes |
| 186 | +- Always check return values from functions that can fail |
| 187 | +- Use TU_ASSERT() for error checking with return statements |
| 188 | +- Follow the existing code patterns in the files you're modifying |
| 189 | + |
| 190 | +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