Agent Handbook

Shared TinyUSB Ground Rules

  • Keep TinyUSB memory-safe: avoid dynamic allocation, defer ISR work to task context, and follow C99 with two-space indentation/no tabs.
  • Match file organization: core stack under src, MCU/BSP support in hw/{mcu,bsp}, examples under examples/{device,host,dual}, docs in docs, tests under test/{unit-test,fuzz,hil}.
  • Use descriptive snake_case for helpers, reserve tud_/tuh_ for public APIs, TU_ for macros, and keep headers self-contained with #if CFG_TUSB_MCU guards where needed.
  • Prefer .clang-format for C/C++ formatting, run pre-commit run --all-files before submitting, and document board/HIL coverage when applicable.
  • Commit in imperative mood, keep changes scoped, and supply PRs with linked issues plus test/build evidence.

Build and Test Cheatsheet

  • Fetch dependencies once with python3 tools/get_deps.py [FAMILY]; assets land in lib/ and hw/mcu/.
  • CMake (preferred): cmake -G Ninja -DBOARD=<board> -DCMAKE_BUILD_TYPE={MinSizeRel|Debug} inside an example build/ dir, then ninja or cmake --build ..
  • Make (alt): make BOARD=<board> [DEBUG=1] [LOG=2 LOGGER=rtt] all from the example root; add uf2, flash-openocd, or flash-jlink targets as needed.
  • Bulk builds: python3 tools/build.py -b <board> to sweep all examples; expect occasional non-critical objcopy warnings.
  • Unit tests: cd test/unit-test && ceedling test:all (or a specific test_<module>), honor Unity/CMock fixtures under test/support.
  • Docs: pip install -r docs/requirements.txt then sphinx-build -b html . _build from docs/.

Validation Checklist

  1. pre-commit run --all-files after edits (install with pip install pre-commit && pre-commit install).
  2. Build at least one representative example (e.g., examples/device/cdc_msc) via CMake+Ninja or Make.
  3. Run unit tests relevant to touched modules; add fuzz/HIL coverage when modifying parsers or protocol state machines.

Copilot Agent Notes (.github/copilot-instructions.md)

  • Treat this handbook as authoritative before searching or executing speculative shell commands; unexpected conflicts justify additional probing.
  • Respect build timing guidance: allow ≥5 minutes for single example builds and ≥30 minutes for bulk runs; never cancel dependency fetches or builds mid-flight.
  • Support optional switches: -DRHPORT_DEVICE[_SPEED], logging toggles (LOG=2, LOGGER=rtt), and board selection helpers from tools/get_deps.py.
  • Flashing shortcuts: ninja <target>-jlink|openocd|uf2 or make BOARD=<board> flash-{jlink,openocd}; list Ninja targets with ninja -t targets.
  • Keep Ceedling installed (sudo gem install ceedling) and available for per-test or full suite runs triggered from test/unit-test.

Claude Agent Notes (CLAUDE.md)

  • Default to CMake+Ninja for builds, but align with Make workflows when users rely on legacy scripts; provide DEBUG/LOG/LOGGER knobs consistently.
  • Highlight dependency helpers (tools/get_deps.py rp2040) and reference core locations: src/, hw/, examples/, test/.
  • Run clang-format on all touched files to ensure consistent formatting.
  • Use TU_ASSERT for all fallible calls to enforce runtime checks.
  • Ensure header comments retain the MIT license notice.
  • Add descriptive comments for non-trivial code paths to aid maintainability.
  • Release flow primer: bump tools/make_release.py version, run the script (updates src/tusb_option.h, repository.yml, library.json), refresh docs/info/changelog.rst, then tag.
  • Testing reminders: Ceedling full or targeted runs, specify board/OS context, and ensure logging of manual hardware outcomes when available.