Add RTT console/capture tooling (tools/rtt.py), rtt skill, and HIL harness support (#3853)

2026-08-28T07:16:02Z

Promote SEGGER RTT from an inline debugging technique to a standalone skill backed by one stdlib-only implementation in tools/rtt.py: a CLI and importable module for console/capture over J-Link (RTTTelnetPort) and OpenOCD (rtt server) probes, with probe selection by serial or VID:PID, control-block address via --elf or --addr, bidirectional console, post-mortem ring dump, and --reset-before-attach for boot-time capture. The HIL harness reads a board's console over RTT when its probe has no VCOM ("logger": "rtt" plus a LOGGER=rtt variant define), covering device_info, pool-check aliveness, and CI wiring. Validated on 22 boards across both backends; 26 unit tests run in pre-commit.

skill(read-doc): search the Calibre database instead of the filesystem

2026-08-18T09:58:58Z

Finding documents by walking the library tree misses anything the filename does not carry - Calibre stores only a truncated title and the author there, so the tags, series, publisher and description that hold most part numbers and errata IDs are invisible to it. A zero-result tree search then reads as "the document does not exist" rather than as a bad search; that happened here, and led to a confident claim that a fully populated 14,000-file library was empty. search.py queries metadata.db, ANDs its keywords across every metadata field (including the stored filename), and prints the best matches first with the exact path to read. Matching is NFKC + casefold, so a typed ASCII apostrophe or mu reaches the titles that store the typographic ones. Every printed path is checked on disk. Calibre renames / (<id>) when metadata is edited and leaves the old directory behind, so a miss retries by the stable book id before reporting MISSING - which distinguishes "the file is not here right now" from "no such document". The gate tests for metadata.db rather than the directory, since an unmounted or half-synced mountpoint is still a directory. Consumers that prescribed their own tree search - driver-reviewer, port-dev, the driver-review workflow, and the calibre-library references in CLAUDE.md, usbtest, etm-trace and target-debug - now point at the skill, which owns the library's location. </article> <article> <h1>skills, docs: rewrite USB recovery from the live incidents</h1> <p>2026-08-18T05:19:09Z</p> Two things the rig taught us that the old guidance got wrong. A usbfs ioctl wedged in D state cannot be freed on a running kernel. It holds the device lock, so usb_disconnect() blocks behind it; reboot(2) walks device_shutdown() and takes the same lock, so every userspace reboot stalls too. Only sysrq b (emergency_restart, which skips device_shutdown) or hypervisor action clears it -- all cited to the kernel source. The recovery ladder is generic across rigs now (ci.lan, hifiphile, a bench PC) and ends at hypervisor escalation only where host access exists. Two claims are corrected outright: JLinkExe is NOT convoy-safe, and a park-flash cannot free a device-lock owner. The hil skill's banner list is what an operator agent matches a report against, so it enumerates the banners that actually exist, including the D-state note -- which is explicitly NOT a wedge, since a healthy in-flight testusb is uninterruptible for most of every case and a concurrent CI battery would otherwise turn a clean run red. </article> <article> <h1>hil: split hil_test.py into hil_lock/hil_flash, add pool_check, update rig probes (#3794)</h1> <p>2026-07-29T10:29:59Z</p> test/hil: add board-pool health check, split hil_test into focused modules (#3794) Add test/hil/hil_pool_check.py: per-board rig health scan — probe presence, light-example flash (dfu_runtime; device_info + serial check for host-only boards), uid re-enumeration, safe recovery (probe authorized-toggle, board reset), verified board_test re-park, USB topology report, and a markdown summary table. Missing firmware is built on the spot (tools/build.py, idf.py for espressif, one get_deps retry); row statuses: ok, flash-failed, failed, locked. Board locks are always respected, never bypassed. Refactor hil_test.py into hil_lock.py (flock protocol, controller permits, hold/release/status CLI; replaces board_lock.py) and hil_flash.py (flashers, find_firmware, run_cmd). Update WCH probe uids and the board roster in tinyusb.json; add the hil-pool-check skill. </article> <article> <h1>target-debug: list etm-trace as the instruction-level channel</h1> <p>2026-07-24T08:56:14Z</p> Fifth capture view alongside usbmon/kernel/target/wire: exact execution history via J-Trace, existing only where the trace header is wired - confirm with the user before reaching for it. </article> <article> <h1>docs: address Codex/Copilot review on #3786</h1> <p>2026-07-24T08:14:02Z</p> - target-debug: fault frame lives on PSP when EXC_RETURN bit2 set (FreeRTOS tasks) — decode LR before choosing $msp/$psp (Codex; valid, our verify happened to fault on MSP) - esp-target-debug: show the Xtensa gdb for S3 in the attach recipe; clarify adapter serial = USB-SJ iSerial (colon MAC, hardware-verified) vs the CP2102N flasher uids in tinyusb.json (Codex; second half of the finding had the identifiers inverted) - esp plan: align serial form with the verified command; record the real console-gate outcome (UART0, USB-SJ console untested) (Copilot) - target-debug plan: Task 4 now consistently $JB/ARMv7-M matching the executed JLinkExe path (Copilot) - drop IDE-local .idea files swept in by the rename commit (Copilot) </article> <article> <h1>docs(skills): tighten esp-target-debug/target-debug; agent routes backends by board family</h1> <p>2026-07-24T07:55:59Z</p> - esp-target-debug: de-narrated (~1000 -> 847 words) — session-diary phrasing ('this unit', dates, 'we measured') replaced with durable reference facts; restructured per-board (P4 vs S3 notes); new Scripted-session gotchas section consolidates telnet-halt pattern, ESP_ONLYCPU, and ROM-frame guidance; UART-reset recipe stated once - target-debug: fix run-on seam from the -singlerun insertion - target-debugger agent: charter now resolves the board family FIRST and routes Espressif boards to esp-target-debug as primary playbook; skills table re-aligned - retrieval regression: 4/4 (agent routing, S3 keep-alive quirk, OpenOCD RTT on ST-Link, ROM-frame guidance) </article> <article> <h1>docs(skills): esp-target-debug — Espressif built-in USB-JTAG backend, rig-verified</h1> <p>2026-07-24T07:55:59Z</p> P4 (hand-wired USB-SJ breakout, GPIO24/25 from header J1): - COEXISTENCE verified: 303a:1001 + cafe:4008 enumerated simultaneously; gdb attach/halt/bt during live CDC traffic; symbolized app backtrace (tud_task_ext <- usb_device_task <- vPortTaskWrapper) - set ESP_RTOS FreeRTOS before board cfg -> full dual-core task list; without it, bare 'Remote target' - attach-may-reset nuance flagged (post-mortem autopsy caution) - console = UART0 (CP2102 flasher tty) on stock builds; D+/D- swap symptom documented (low-speed + error -71 vs full-speed) S3 (same-port PHY swap): - boundary captured live in dmesg: same hub port flips 303a:1001 -> cafe:4008 as the app boots; openocd 'esp_usb_jtag: could not find or open device!' verbatim - attach/halt/symbol resolution verified via board_test (usb_new_phy absent from ELF when CFG_TUD/TUH=0); app-context keep-alive quirk (~4 s unattended drop, -71 half-dead, UART esptool reset recovers); cpu1 OCD_ID=0 -> ESP_ONLYCPU=1; telnet-halt + gdb-read scripted pattern; RTC_CNTL PHY-mux reference (0x60008120) + esptool read_mem/write_mem - target-debug pointer + target-debugger agent table row </article> <article> <h1>docs(target-debug): DWT data trace (verified both probe families); reorder to table; SWO enable chain</h1> <p>2026-07-24T07:55:59Z</p> - DWT data trace: FUNCTION 0b0011 (ARMv7-M ARM Table C1-21) streams value + accessor-PC packets per access, no halt, no code. Verified on stm32f407disco (J-Link SWORead: 451 KB, value = uptime ms, PC = tusb_time_millis_api) and stm32h743nucleo (OpenOCD/ST-Link tpiu capture: 607 KB, same decode). Caveat recorded: R/W-only trace floods on polled variables. - SWO enable chain documented: tools own TRCENA/ITM/TPIU; vendor part bites — H7 needs DBGMCU trace clocks, PB3 manually muxed to AF0, native stlink-dap (hla tpiu silently no-ops), the cfg's stm32h7x.swo object (the .tpiu object is the parallel port), traceclk = c_ck 400 MHz (wrong guesses: ratio-garbage or silence). - Sections reordered to match the intrusiveness table (least->most intrusive); cross-references fixed; table gains the data-trace row. </article> <article> <h1>docs(skills): formatting feedback — agent skill table, probe bullets, aligned columns</h1> <p>2026-07-24T07:55:59Z</p> - target-debugger: skill list is now a table referencing skills by name only (path pattern stated once). - target-debug: probe-mapping run-on paragraph split into bullets; drop the GDB Ninth-Edition caveat (calibre now holds the Tenth-Edition PDF, id 2264). - Align markdown table columns across target-debug, usb-sniffer, usbmon, hil, usbtest and the agent (7 tables); tables with paragraph-length cells left unpadded (usbmon symptom map, usbtest case map). </article> </main></body></html>

tinyusb.git/.claude/skills/target-debug/SKILL.md, branch codex/class-reference-docs

Add RTT console/capture tooling (tools/rtt.py), rtt skill, and HIL harness support (#3853)

skill(read-doc): search the Calibre database instead of the filesystem