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

docs: address Codex/Copilot review on #3786

2026-07-24T08:14:02Z

- 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)

docs(skills): tighten esp-target-debug/target-debug; agent routes backends by board family

2026-07-24T07:55:59Z

- 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)

docs(skills): esp-target-debug — Espressif built-in USB-JTAG backend, rig-verified

2026-07-24T07:55:59Z

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