{"owner":"hathach","repo":"tinyusb","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# TinyUSB Agent Instructions\n\nTinyUSB is a cross-platform USB Host/Device stack for embedded systems: memory-safe (no dynamic allocation) and thread-safe (ISR events deferred to task context).\n\nReference these instructions first; fall back to search/bash only when reality diverges.\n\n## Behavioral Guidelines\n\nBias toward caution over speed. For trivial tasks, use judgment.\n\n- **Think first** — state assumptions; ask if unclear; present alternatives instead of picking silently.\n- **Simplicity** — no features, abstractions, flexibility, or error handling beyond what was asked. If 200 lines could be 50, rewrite.\n- **Surgical changes** — touch only what the task requires; match existing style; don't refactor working code; mention unrelated dead code rather than deleting it. Remove only orphans *your* changes created.\n- **Goal-driven** — turn tasks into verifiable goals (\"write failing test, make it pass\"). For multi-step work, state a brief `step → verify` plan.\n- **Worktrees** — default to a git worktree for any branch or multi-step work; never switch the shared primary checkout's branch. Sessions run concurrently: switching the primary checkout mid-flight disrupts other sessions and can silently point a review, build, or commit at the wrong diff. Only trivial one-shot fixes may skip this. Standard location: `.worktrees/<branch-name>` at the repo root (gitignored), e.g. `git worktree add .worktrees/my-branch -b my-branch`. In a new worktree, symlink the dependency dirs (`lib/*`, `hw/mcu/*`, `tools/linkermap` — the keys of `deps_all` in `tools/get_deps.py`) to the primary checkout instead of re-cloning them; only if the branch needs a different dep revision, replace that one symlink with a real dir and run `get_deps.py` for it.\n\n## Ground Rules\n\n- **Language/style:** C99, 2-space indent (no tabs), snake_case helpers, `UPPER_CASE` macros. Public APIs use `tud_`/`tuh_`; macros use `TU_`. Headers self-contained with `#if CFG_TUSB_MCU` guards.\n- **Safety:** no dynamic allocation; defer ISR work to task context; use `TU_ASSERT()` for error checks; always check return values; include order: C stdlib → tusb common → drivers → classes.\n- **Layout:** `src/` core, `hw/{mcu,bsp}/` MCU+BSP, `examples/{device,host,dual}/`, `test/{unit-test,fuzz,hil}/`, `docs/`, `tools/`.\n- **Commits/PRs:** imperative mood, scoped changes, link issues, include test/build evidence. After opening a PR, drive it to green: address automated review comments (Copilot/Codex/Claude) and fix failing CI, pushing follow-ups until checks pass and threads resolve. Useful: `gh pr checks <num> --watch`, `gh pr view <num> --comments`.\n- **Formatting/lint:** `clang-format` (`.clang-format`), `codespell` (`.codespellrc`); run `pre-commit run --all-files` before submitting.\n\n## Bootstrap\n\n```bash\nsudo apt-get install -y gcc-arm-none-eabi          # ARM toolchain (2-5 min, one-time)\npython3 tools/get_deps.py [FAMILY|-b BOARD]        # fetch deps into lib/, hw/mcu/ (<1 s)\n. $HOME/code/esp-idf/export.sh                     # Espressif only: before any build/flash/monitor\n```\n\n## Build\n\nSingle example (CMake+Ninja, recommended, 1-3 s):\n```bash\ncd examples/device/cdc_msc && mkdir -p build && cd build\ncmake -DBOARD=raspberry_pi_pico -G Ninja -DCMAKE_BUILD_TYPE=MinSizeRel .. && cmake --build .\n```\n\nAll examples for a board (15-20 s; some objcopy failures are non-critical). The build dir **must** be `cmake-build-<board>` — HIL tests expect that exact name:\n```bash\ncd examples\ncmake -B cmake-build-raspberry_pi_pico -DBOARD=raspberry_pi_pico -G Ninja -DCMAKE_BUILD_TYPE=MinSizeRel . && cmake --build cmake-build-raspberry_pi_pico\n```\n\n- **Make:** `cd examples/device/cdc_msc && make BOARD=raspberry_pi_pico all`\n- **Espressif** (ESP-IDF examples only, e.g. `cdc_msc_freertos`): after `export.sh`, `cd examples/device/cdc_msc_freertos && idf.py -DBOARD=espressif_s3_devkitc build`\n- **Options** (CMake `-D…` / Make `…=…`): `CMAKE_BUILD_TYPE=Debug`/`DEBUG=1`; `LOG=2` (`LOGGER=rtt` for RTT); `RHPORT_DEVICE=1`; `RHPORT_DEVICE_SPEED=OPT_MODE_FULL_SPEED`\n\n## Flash\n\n```bash\nninja cdc_msc-jlink       # CMake; Make: make BOARD=<board> flash-jlink\nninja cdc_msc-openocd     # CMake; Make: make BOARD=<board> flash-openocd\nninja cdc_msc-uf2         # CMake; Make: make BOARD=<board> all uf2\nninja -t targets          # list CMake targets\n```\nEspressif (after `export.sh`): `idf.py -DBOARD=<board> flash` / `… monitor`.\n\n## GDB Debugging\n\nLook up `JLINK_DEVICE` / `OPENOCD_OPTION` in `hw/bsp/*/boards/*/board.cmake` (CMake) or `board.mk` (Make).\n\nTerminal 1 — start a gdbserver:\n```bash\nJLinkGDBServer -device stm32h743xi -if SWD -speed 4000 -port 2331 -nogui   # JLink → :2331\nopenocd -f interface/stlink.cfg -f target/stm32h7x.cfg                     # OpenOCD → :3333\nopenocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c \"adapter speed 5000\"   # rp2040/rp2350\n```\nTerminal 2 — connect (`<port>`: 2331 JLink, 3333 OpenOCD):\n```bash\narm-none-eabi-gdb build/your_app.elf\n(gdb) target remote :<port>    # then: monitor reset halt → load → continue\n```\n**RTT:** build `LOG=2 LOGGER=rtt`, run JLinkGDBServer with `-RTTTelnetPort 19021`, then `JLinkRTTClient` (`timeout 20s JLinkRTTClient > rtt.log` for non-interactive capture).\n\n## Testing\n\n**Unit (Ceedling, Unity+CMock, ~4 s):**\n```bash\nsudo gem install ceedling\ncd test/unit-test && ceedling test:all        # or ceedling test:test_fifo\n```\n\n**HIL (2-5 min):** invoke the `hil` skill (`.claude/skills/hil/SKILL.md`) — local vs remote mode, config selection, SSH copy steps, debugging. Requires pre-built examples (Build → \"All examples for a board\").\n\n## Documentation\n\nSphinx docs in `docs/` (`.rst`, or `.md` via MyST). Use the `build-doc` skill (`.claude/skills/build-doc/SKILL.md`) to build/preview locally and regenerate auto-generated files (`tools/gen_doc.py` + `tools/gen_presets.py`) after adding a board or dependency.\n\n## Code Size Metrics\n\nVerify size impact before committing with the `code-size` skill (`.claude/skills/code-size/SKILL.md`) — it wraps `tools/metrics_compare_base.py` for the base-vs-branch worktree + build + compare. Scopes: single example (`-e device/cdc_msc -b <board>`, add `--bloaty`), all examples on a board (`-b <board>`), or all arm-gcc CI families (`--ci`). Reports land in `cmake-metrics/<board>/metrics_compare.md` (and `_combined/` for `--ci`).\n\n## Static Analysis (PVS-Studio)\n\nUse the `pvs` skill (`.claude/skills/pvs/SKILL.md`) — it builds the examples with an exported `compile_commands.json` and runs SAST + MISRA C:2023/C++:2008 for a board, emitting readable + SARIF output (~10-30 s). The examples build exports `compile_commands.json` by default.\n\n## Validation After Changes\n\n1. `pre-commit run --all-files` — format, spell, unit tests (10-15 s).\n2. Build at least one board's full example set (Build → \"All examples for a board\") for modules you touched.\n3. Run relevant unit tests; add fuzz/HIL coverage for parsers or protocol state machines.\n\n**Boards good for local testing:**\n- `stm32f407disco` — no external SDK\n- `raspberry_pi_pico` — Pico SDK required\n- Others: see `hw/bsp/FAMILY/boards/`\n\nDevice examples need real hardware to validate runtime behavior; must at least build.\n\n## Release\n\nCutting a release — version bump, regenerated files, the per-release changelog, validation, and the maintainer's commit/tag/GitHub-release — is handled by the `make-release` skill (`.claude/skills/make-release/SKILL.md`).\n\n## References\n\n- MCU reference manuals, datasheets, schematics: before answering register/bitfield/pinout/errata/timing questions from memory or the web — or changing a specific dcd/hcd driver — use the `read-doc` skill (`.claude/skills/read-doc/SKILL.md`) to cross-check against docs in `$HOME/Documents/calibre-library`; tell the user if the needed document is missing (skill no-ops if the library is absent).\n- Supported MCUs/boards: `hw/bsp/` and `docs/reference/boards.rst`.\n- USB classes: `src/class/{cdc,hid,msc,audio,…}/` — each has `*_device.c` and `*_host.c`.\n- Key files: `src/tusb.h`, `src/tusb_config.h`, `tools/get_deps.py`, `tools/build.py`, `test/unit-test/project.yml`.\n\n## Common Build Issues\n\n- Missing compiler → install `gcc-arm-none-eabi`.\n- Missing deps → `python3 tools/get_deps.py FAMILY`.\n- Unknown board → check `hw/bsp/FAMILY/boards/`.\n- `objcopy` errors in full builds are often non-critical; retry the single example.\n"},"files":{"CLAUDE.md":"# TinyUSB Agent Instructions\n\nTinyUSB is a cross-platform USB Host/Device stack for embedded systems: memory-safe (no dynamic allocation) and thread-safe (ISR events deferred to task context).\n\nReference these instructions first; fall back to search/bash only when reality diverges.\n\n## Behavioral Guidelines\n\nBias toward caution over speed. For trivial tasks, use judgment.\n\n- **Think first** — state assumptions; ask if unclear; present alternatives instead of picking silently.\n- **Simplicity** — no features, abstractions, flexibility, or error handling beyond what was asked. If 200 lines could be 50, rewrite.\n- **Surgical changes** — touch only what the task requires; match existing style; don't refactor working code; mention unrelated dead code rather than deleting it. Remove only orphans *your* changes created.\n- **Goal-driven** — turn tasks into verifiable goals (\"write failing test, make it pass\"). For multi-step work, state a brief `step → verify` plan.\n- **Worktrees** — default to a git worktree for any branch or multi-step work; never switch the shared primary checkout's branch. Sessions run concurrently: switching the primary checkout mid-flight disrupts other sessions and can silently point a review, build, or commit at the wrong diff. Only trivial one-shot fixes may skip this. Standard location: `.worktrees/<branch-name>` at the repo root (gitignored), e.g. `git worktree add .worktrees/my-branch -b my-branch`. In a new worktree, symlink the dependency dirs (`lib/*`, `hw/mcu/*`, `tools/linkermap` — the keys of `deps_all` in `tools/get_deps.py`) to the primary checkout instead of re-cloning them; only if the branch needs a different dep revision, replace that one symlink with a real dir and run `get_deps.py` for it.\n\n## Ground Rules\n\n- **Language/style:** C99, 2-space indent (no tabs), snake_case helpers, `UPPER_CASE` macros. Public APIs use `tud_`/`tuh_`; macros use `TU_`. Headers self-contained with `#if CFG_TUSB_MCU` guards.\n- **Safety:** no dynamic allocation; defer ISR work to task context; use `TU_ASSERT()` for error checks; always check return values; include order: C stdlib → tusb common → drivers → classes.\n- **Layout:** `src/` core, `hw/{mcu,bsp}/` MCU+BSP, `examples/{device,host,dual}/`, `test/{unit-test,fuzz,hil}/`, `docs/`, `tools/`.\n- **Commits/PRs:** imperative mood, scoped changes, link issues, include test/build evidence. After opening a PR, drive it to green: address automated review comments (Copilot/Codex/Claude) and fix failing CI, pushing follow-ups until checks pass and threads resolve. Useful: `gh pr checks <num> --watch`, `gh pr view <num> --comments`.\n- **Formatting/lint:** `clang-format` (`.clang-format`), `codespell` (`.codespellrc`); run `pre-commit run --all-files` before submitting.\n\n## Bootstrap\n\n```bash\nsudo apt-get install -y gcc-arm-none-eabi          # ARM toolchain (2-5 min, one-time)\npython3 tools/get_deps.py [FAMILY|-b BOARD]        # fetch deps into lib/, hw/mcu/ (<1 s)\n. $HOME/code/esp-idf/export.sh                     # Espressif only: before any build/flash/monitor\n```\n\n## Build\n\nSingle example (CMake+Ninja, recommended, 1-3 s):\n```bash\ncd examples/device/cdc_msc && mkdir -p build && cd build\ncmake -DBOARD=raspberry_pi_pico -G Ninja -DCMAKE_BUILD_TYPE=MinSizeRel .. && cmake --build .\n```\n\nAll examples for a board (15-20 s; some objcopy failures are non-critical). The build dir **must** be `cmake-build-<board>` — HIL tests expect that exact name:\n```bash\ncd examples\ncmake -B cmake-build-raspberry_pi_pico -DBOARD=raspberry_pi_pico -G Ninja -DCMAKE_BUILD_TYPE=MinSizeRel . && cmake --build cmake-build-raspberry_pi_pico\n```\n\n- **Make:** `cd examples/device/cdc_msc && make BOARD=raspberry_pi_pico all`\n- **Espressif** (ESP-IDF examples only, e.g. `cdc_msc_freertos`): after `export.sh`, `cd examples/device/cdc_msc_freertos && idf.py -DBOARD=espressif_s3_devkitc build`\n- **Options** (CMake `-D…` / Make `…=…`): `CMAKE_BUILD_TYPE=Debug`/`DEBUG=1`; `LOG=2` (`LOGGER=rtt` for RTT); `RHPORT_DEVICE=1`; `RHPORT_DEVICE_SPEED=OPT_MODE_FULL_SPEED`\n\n## Flash\n\n```bash\nninja cdc_msc-jlink       # CMake; Make: make BOARD=<board> flash-jlink\nninja cdc_msc-openocd     # CMake; Make: make BOARD=<board> flash-openocd\nninja cdc_msc-uf2         # CMake; Make: make BOARD=<board> all uf2\nninja -t targets          # list CMake targets\n```\nEspressif (after `export.sh`): `idf.py -DBOARD=<board> flash` / `… monitor`.\n\n## GDB Debugging\n\nLook up `JLINK_DEVICE` / `OPENOCD_OPTION` in `hw/bsp/*/boards/*/board.cmake` (CMake) or `board.mk` (Make).\n\nTerminal 1 — start a gdbserver:\n```bash\nJLinkGDBServer -device stm32h743xi -if SWD -speed 4000 -port 2331 -nogui   # JLink → :2331\nopenocd -f interface/stlink.cfg -f target/stm32h7x.cfg                     # OpenOCD → :3333\nopenocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c \"adapter speed 5000\"   # rp2040/rp2350\n```\nTerminal 2 — connect (`<port>`: 2331 JLink, 3333 OpenOCD):\n```bash\narm-none-eabi-gdb build/your_app.elf\n(gdb) target remote :<port>    # then: monitor reset halt → load → continue\n```\n**RTT:** build `LOG=2 LOGGER=rtt`, run JLinkGDBServer with `-RTTTelnetPort 19021`, then `JLinkRTTClient` (`timeout 20s JLinkRTTClient > rtt.log` for non-interactive capture).\n\n## Testing\n\n**Unit (Ceedling, Unity+CMock, ~4 s):**\n```bash\nsudo gem install ceedling\ncd test/unit-test && ceedling test:all        # or ceedling test:test_fifo\n```\n\n**HIL (2-5 min):** invoke the `hil` skill (`.claude/skills/hil/SKILL.md`) — local vs remote mode, config selection, SSH copy steps, debugging. Requires pre-built examples (Build → \"All examples for a board\").\n\n## Documentation\n\nSphinx docs in `docs/` (`.rst`, or `.md` via MyST). Use the `build-doc` skill (`.claude/skills/build-doc/SKILL.md`) to build/preview locally and regenerate auto-generated files (`tools/gen_doc.py` + `tools/gen_presets.py`) after adding a board or dependency.\n\n## Code Size Metrics\n\nVerify size impact before committing with the `code-size` skill (`.claude/skills/code-size/SKILL.md`) — it wraps `tools/metrics_compare_base.py` for the base-vs-branch worktree + build + compare. Scopes: single example (`-e device/cdc_msc -b <board>`, add `--bloaty`), all examples on a board (`-b <board>`), or all arm-gcc CI families (`--ci`). Reports land in `cmake-metrics/<board>/metrics_compare.md` (and `_combined/` for `--ci`).\n\n## Static Analysis (PVS-Studio)\n\nUse the `pvs` skill (`.claude/skills/pvs/SKILL.md`) — it builds the examples with an exported `compile_commands.json` and runs SAST + MISRA C:2023/C++:2008 for a board, emitting readable + SARIF output (~10-30 s). The examples build exports `compile_commands.json` by default.\n\n## Validation After Changes\n\n1. `pre-commit run --all-files` — format, spell, unit tests (10-15 s).\n2. Build at least one board's full example set (Build → \"All examples for a board\") for modules you touched.\n3. Run relevant unit tests; add fuzz/HIL coverage for parsers or protocol state machines.\n\n**Boards good for local testing:**\n- `stm32f407disco` — no external SDK\n- `raspberry_pi_pico` — Pico SDK required\n- Others: see `hw/bsp/FAMILY/boards/`\n\nDevice examples need real hardware to validate runtime behavior; must at least build.\n\n## Release\n\nCutting a release — version bump, regenerated files, the per-release changelog, validation, and the maintainer's commit/tag/GitHub-release — is handled by the `make-release` skill (`.claude/skills/make-release/SKILL.md`).\n\n## References\n\n- MCU reference manuals, datasheets, schematics: before answering register/bitfield/pinout/errata/timing questions from memory or the web — or changing a specific dcd/hcd driver — use the `read-doc` skill (`.claude/skills/read-doc/SKILL.md`) to cross-check against docs in `$HOME/Documents/calibre-library`; tell the user if the needed document is missing (skill no-ops if the library is absent).\n- Supported MCUs/boards: `hw/bsp/` and `docs/reference/boards.rst`.\n- USB classes: `src/class/{cdc,hid,msc,audio,…}/` — each has `*_device.c` and `*_host.c`.\n- Key files: `src/tusb.h`, `src/tusb_config.h`, `tools/get_deps.py`, `tools/build.py`, `test/unit-test/project.yml`.\n\n## Common Build Issues\n\n- Missing compiler → install `gcc-arm-none-eabi`.\n- Missing deps → `python3 tools/get_deps.py FAMILY`.\n- Unknown board → check `hw/bsp/FAMILY/boards/`.\n- `objcopy` errors in full builds are often non-critical; retry the single example.\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# TinyUSB Agent Instructions\n\nTinyUSB is a cross-platform USB Host/Device stack for embedded systems: memory-safe (no dynamic allocation) and thread-safe (ISR events deferred to task context).\n\nReference these instructions first; fall back to search/bash only when reality diverges.\n\n## Behavioral Guidelines\n\nBias toward caution over speed. For trivial tasks, use judgment.\n\n- **Think first** — state assumptions; ask if unclear; present alternatives instead of picking silently.\n- **Simplicity** — no features, abstractions, flexibility, or error handling beyond what was asked. If 200 lines could be 50, rewrite.\n- **Surgical changes** — touch only what the task requires; match existing style; don't refactor working code; mention unrelated dead code rather than deleting it. Remove only orphans *your* changes created.\n- **Goal-driven** — turn tasks into verifiable goals (\"write failing test, make it pass\"). For multi-step work, state a brief `step → verify` plan.\n- **Worktrees** — default to a git worktree for any branch or multi-step work; never switch the shared primary checkout's branch. Sessions run concurrently: switching the primary checkout mid-flight disrupts other sessions and can silently point a review, build, or commit at the wrong diff. Only trivial one-shot fixes may skip this. Standard location: `.worktrees/<branch-name>` at the repo root (gitignored), e.g. `git worktree add .worktrees/my-branch -b my-branch`. In a new worktree, symlink the dependency dirs (`lib/*`, `hw/mcu/*`, `tools/linkermap` — the keys of `deps_all` in `tools/get_deps.py`) to the primary checkout instead of re-cloning them; only if the branch needs a different dep revision, replace that one symlink with a real dir and run `get_deps.py` for it.\n\n## Ground Rules\n\n- **Language/style:** C99, 2-space indent (no tabs), snake_case helpers, `UPPER_CASE` macros. Public APIs use `tud_`/`tuh_`; macros use `TU_`. Headers self-contained with `#if CFG_TUSB_MCU` guards.\n- **Safety:** no dynamic allocation; defer ISR work to task context; use `TU_ASSERT()` for error checks; always check return values; include order: C stdlib → tusb common → drivers → classes.\n- **Layout:** `src/` core, `hw/{mcu,bsp}/` MCU+BSP, `examples/{device,host,dual}/`, `test/{unit-test,fuzz,hil}/`, `docs/`, `tools/`.\n- **Commits/PRs:** imperative mood, scoped changes, link issues, include test/build evidence. After opening a PR, drive it to green: address automated review comments (Copilot/Codex/Claude) and fix failing CI, pushing follow-ups until checks pass and threads resolve. Useful: `gh pr checks <num> --watch`, `gh pr view <num> --comments`.\n- **Formatting/lint:** `clang-format` (`.clang-format`), `codespell` (`.codespellrc`); run `pre-commit run --all-files` before submitting.\n\n## Bootstrap\n\n```bash\nsudo apt-get install -y gcc-arm-none-eabi          # ARM toolchain (2-5 min, one-time)\npython3 tools/get_deps.py [FAMILY|-b BOARD]        # fetch deps into lib/, hw/mcu/ (<1 s)\n. $HOME/code/esp-idf/export.sh                     # Espressif only: before any build/flash/monitor\n```\n\n## Build\n\nSingle example (CMake+Ninja, recommended, 1-3 s):\n```bash\ncd examples/device/cdc_msc && mkdir -p build && cd build\ncmake -DBOARD=raspberry_pi_pico -G Ninja -DCMAKE_BUILD_TYPE=MinSizeRel .. && cmake --build .\n```\n\nAll examples for a board (15-20 s; some objcopy failures are non-critical). The build dir **must** be `cmake-build-<board>` — HIL tests expect that exact name:\n```bash\ncd examples\ncmake -B cmake-build-raspberry_pi_pico -DBOARD=raspberry_pi_pico -G Ninja -DCMAKE_BUILD_TYPE=MinSizeRel . && cmake --build cmake-build-raspberry_pi_pico\n```\n\n- **Make:** `cd examples/device/cdc_msc && make BOARD=raspberry_pi_pico all`\n- **Espressif** (ESP-IDF examples only, e.g. `cdc_msc_freertos`): after `export.sh`, `cd examples/device/cdc_msc_freertos && idf.py -DBOARD=espressif_s3_devkitc build`\n- **Options** (CMake `-D…` / Make `…=…`): `CMAKE_BUILD_TYPE=Debug`/`DEBUG=1`; `LOG=2` (`LOGGER=rtt` for RTT); `RHPORT_DEVICE=1`; `RHPORT_DEVICE_SPEED=OPT_MODE_FULL_SPEED`\n\n## Flash\n\n```bash\nninja cdc_msc-jlink       # CMake; Make: make BOARD=<board> flash-jlink\nninja cdc_msc-openocd     # CMake; Make: make BOARD=<board> flash-openocd\nninja cdc_msc-uf2         # CMake; Make: make BOARD=<board> all uf2\nninja -t targets          # list CMake targets\n```\nEspressif (after `export.sh`): `idf.py -DBOARD=<board> flash` / `… monitor`.\n\n## GDB Debugging\n\nLook up `JLINK_DEVICE` / `OPENOCD_OPTION` in `hw/bsp/*/boards/*/board.cmake` (CMake) or `board.mk` (Make).\n\nTerminal 1 — start a gdbserver:\n```bash\nJLinkGDBServer -device stm32h743xi -if SWD -speed 4000 -port 2331 -nogui   # JLink → :2331\nopenocd -f interface/stlink.cfg -f target/stm32h7x.cfg                     # OpenOCD → :3333\nopenocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c \"adapter speed 5000\"   # rp2040/rp2350\n```\nTerminal 2 — connect (`<port>`: 2331 JLink, 3333 OpenOCD):\n```bash\narm-none-eabi-gdb build/your_app.elf\n(gdb) target remote :<port>    # then: monitor reset halt → load → continue\n```\n**RTT:** build `LOG=2 LOGGER=rtt`, run JLinkGDBServer with `-RTTTelnetPort 19021`, then `JLinkRTTClient` (`timeout 20s JLinkRTTClient > rtt.log` for non-interactive capture).\n\n## Testing\n\n**Unit (Ceedling, Unity+CMock, ~4 s):**\n```bash\nsudo gem install ceedling\ncd test/unit-test && ceedling test:all        # or ceedling test:test_fifo\n```\n\n**HIL (2-5 min):** invoke the `hil` skill (`.claude/skills/hil/SKILL.md`) — local vs remote mode, config selection, SSH copy steps, debugging. Requires pre-built examples (Build → \"All examples for a board\").\n\n## Documentation\n\nSphinx docs in `docs/` (`.rst`, or `.md` via MyST). Use the `build-doc` skill (`.claude/skills/build-doc/SKILL.md`) to build/preview locally and regenerate auto-generated files (`tools/gen_doc.py` + `tools/gen_presets.py`) after adding a board or dependency.\n\n## Code Size Metrics\n\nVerify size impact before committing with the `code-size` skill (`.claude/skills/code-size/SKILL.md`) — it wraps `tools/metrics_compare_base.py` for the base-vs-branch worktree + build + compare. Scopes: single example (`-e device/cdc_msc -b <board>`, add `--bloaty`), all examples on a board (`-b <board>`), or all arm-gcc CI families (`--ci`). Reports land in `cmake-metrics/<board>/metrics_compare.md` (and `_combined/` for `--ci`).\n\n## Static Analysis (PVS-Studio)\n\nUse the `pvs` skill (`.claude/skills/pvs/SKILL.md`) — it builds the examples with an exported `compile_commands.json` and runs SAST + MISRA C:2023/C++:2008 for a board, emitting readable + SARIF output (~10-30 s). The examples build exports `compile_commands.json` by default.\n\n## Validation After Changes\n\n1. `pre-commit run --all-files` — format, spell, unit tests (10-15 s).\n2. Build at least one board's full example set (Build → \"All examples for a board\") for modules you touched.\n3. Run relevant unit tests; add fuzz/HIL coverage for parsers or protocol state machines.\n\n**Boards good for local testing:**\n- `stm32f407disco` — no external SDK\n- `raspberry_pi_pico` — Pico SDK required\n- Others: see `hw/bsp/FAMILY/boards/`\n\nDevice examples need real hardware to validate runtime behavior; must at least build.\n\n## Release\n\nCutting a release — version bump, regenerated files, the per-release changelog, validation, and the maintainer's commit/tag/GitHub-release — is handled by the `make-release` skill (`.claude/skills/make-release/SKILL.md`).\n\n## References\n\n- MCU reference manuals, datasheets, schematics: before answering register/bitfield/pinout/errata/timing questions from memory or the web — or changing a specific dcd/hcd driver — use the `read-doc` skill (`.claude/skills/read-doc/SKILL.md`) to cross-check against docs in `$HOME/Documents/calibre-library`; tell the user if the needed document is missing (skill no-ops if the library is absent).\n- Supported MCUs/boards: `hw/bsp/` and `docs/reference/boards.rst`.\n- USB classes: `src/class/{cdc,hid,msc,audio,…}/` — each has `*_device.c` and `*_host.c`.\n- Key files: `src/tusb.h`, `src/tusb_config.h`, `tools/get_deps.py`, `tools/build.py`, `test/unit-test/project.yml`.\n\n## Common Build Issues\n\n- Missing compiler → install `gcc-arm-none-eabi`.\n- Missing deps → `python3 tools/get_deps.py FAMILY`.\n- Unknown board → check `hw/bsp/FAMILY/boards/`.\n- `objcopy` errors in full builds are often non-critical; retry the single example.\n","category":"root","tokens":2094}]}