|
| 1 | +# TinyUSB Development Guide |
| 2 | + |
| 3 | +## Build Commands |
| 4 | + |
| 5 | +### CMake Build System (Preferred) |
| 6 | +CMake with Ninja is the preferred build method for TinyUSB development. |
| 7 | + |
| 8 | +- Build example with Ninja: |
| 9 | + ```bash |
| 10 | + cd examples/device/cdc_msc |
| 11 | + mkdir build && cd build |
| 12 | + cmake -G Ninja -DBOARD=raspberry_pi_pico .. |
| 13 | + ninja |
| 14 | + ``` |
| 15 | +- Debug build: `cmake -G Ninja -DBOARD=raspberry_pi_pico -DCMAKE_BUILD_TYPE=Debug ..` |
| 16 | +- With logging: `cmake -G Ninja -DBOARD=raspberry_pi_pico -DLOG=2 ..` |
| 17 | +- With RTT logger: `cmake -G Ninja -DBOARD=raspberry_pi_pico -DLOG=2 -DLOGGER=rtt ..` |
| 18 | +- Flash with JLink: `ninja cdc_msc-jlink` |
| 19 | +- Flash with OpenOCD: `ninja cdc_msc-openocd` |
| 20 | +- Generate UF2: `ninja cdc_msc-uf2` |
| 21 | +- List all targets: `ninja -t targets` |
| 22 | + |
| 23 | +### Make Build System (Alternative) |
| 24 | +- Build example: `cd examples/device/cdc_msc && make BOARD=raspberry_pi_pico all` |
| 25 | +- For specific example: `cd examples/{device|host|dual}/{example_name} && make BOARD=raspberry_pi_pico all` |
| 26 | +- Flash with JLink: `make BOARD=raspberry_pi_pico flash-jlink` |
| 27 | +- Flash with OpenOCD: `make BOARD=raspberry_pi_pico flash-openocd` |
| 28 | +- Debug build: `make BOARD=raspberry_pi_pico DEBUG=1 all` |
| 29 | +- With logging: `make BOARD=raspberry_pi_pico LOG=2 all` |
| 30 | +- With RTT logger: `make BOARD=raspberry_pi_pico LOG=2 LOGGER=rtt all` |
| 31 | +- Generate UF2: `make BOARD=raspberry_pi_pico all uf2` |
| 32 | + |
| 33 | +### Additional Options |
| 34 | +- Select RootHub port: `RHPORT_DEVICE=1` (make) or `-DRHPORT_DEVICE=1` (cmake) |
| 35 | +- Set port speed: `RHPORT_DEVICE_SPEED=OPT_MODE_FULL_SPEED` (make) or `-DRHPORT_DEVICE_SPEED=OPT_MODE_FULL_SPEED` (cmake) |
| 36 | + |
| 37 | +### Dependencies |
| 38 | +- Get dependencies: `python tools/get_deps.py rp2040` |
| 39 | +- Or from example: `cd examples/device/cdc_msc && make BOARD=raspberry_pi_pico get-deps` |
| 40 | + |
| 41 | +### Testing |
| 42 | +- Run unit tests: `cd test/unit-test && ceedling test:all` |
| 43 | +- Run specific test: `cd test/unit-test && ceedling test:test_fifo` |
| 44 | + |
| 45 | +### Pre-commit Hooks |
| 46 | +Before building, it's recommended to run pre-commit to ensure code quality: |
| 47 | +- Run pre-commit on all files: `pre-commit run --all-files` |
| 48 | +- Run pre-commit on staged files: `pre-commit run` |
| 49 | +- Install pre-commit hook: `pre-commit install` |
| 50 | + |
| 51 | +## Code Style Guidelines |
| 52 | +- Use C99 standard |
| 53 | +- Memory-safe: no dynamic allocation |
| 54 | +- Thread-safe: defer all interrupt events to non-ISR task functions |
| 55 | +- 2-space indentation, no tabs |
| 56 | +- Use snake_case for variables/functions |
| 57 | +- Use UPPER_CASE for macros and constants |
| 58 | +- Follow existing variable naming patterns in files you're modifying |
| 59 | +- Include proper header comments with MIT license |
| 60 | +- Add descriptive comments for non-obvious functions |
| 61 | +- When including headers, group in order: C stdlib, tusb common, drivers, classes |
| 62 | +- Always check return values from functions that can fail |
| 63 | +- Use TU_ASSERT() for error checking with return statements |
| 64 | + |
| 65 | +## Project Structure |
| 66 | +- src/: Core TinyUSB stack code |
| 67 | +- hw/: Board support packages and MCU drivers |
| 68 | +- examples/: Reference examples for device/host/dual |
| 69 | +- test/: Unit tests and hardware integration tests |
0 commit comments