target-debug replaced usb-target-debug in the debug-skill overhaul; update
the cross-skill table and PC-sampling pointer. Add the consent gate: the
J-Trace is a single probe moved between boards, so captures on a board the
user did not just ask about need explicit confirmation that it is wired.
J403 (bottom-side Cortex Debug+ETM footprint, header required):
TRACECLK=PD8 peripheral D, TRACED0-3=PD4-7 peripheral C. TRACE_ETM builds
hold the KSZ8081 PHY in reset (PD4-7 are its RMII receive outputs and it
drives against the trace stream), clock the TPIU from PCK3 (MCK/2) and
mux the pins; the ozone reference starts PCK3 in the post-reset/download
hooks - TPIU programming while PCK3 is stopped is silently lost. Width-1
validated at the stock 300 MHz core; width 4 blocked on a dead D1 line
(suspect probe channel, h743eval crosscheck pending).
J-Link's built-in RP2350 script owns the whole chip-side path (component
map is not ROM-table-discoverable; a custom JLinkScript replaces the
built-in one and kills pin trace), re-arming at every resume - firmware
does no trace setup. TRACE_ETM builds pin clk_sys to 48 MHz from crt0
(fly-wire seating-proof; the port is DDR at clk_sys/2 and the J-Trace PRO
V2 cliff sits just above 40 MHz TRACECLK - SEGGER requires V3.0+ for this
chip), clear TIMER0/1 DBGPAUSE (default freezes the us-timer while any
core is debug-halted and sleep_ms spins forever), and run the UART console
TX-only (GPIO1 = default UART0 RX = TRACECLK).
Generic TRCKCR setup gated on DHCSR.C_DEBUGEN (a standalone-boot TRCKCR
write wedges the chip un-attachable until power-cycle), two-step write per
the hardware manual. ra6m5_ek: div-4 (25 MHz pin) - div-2 is dead on this
board at every width/timing; J9 must be closed. ra8m1_ek: chip-max
120 MHz TRCLK / 60 MHz pin via the committed JLinkScript whose empty
OnTraceStart defers the trace clock to firmware (J-Link's from-reset
enable steps the clock mid-stream at the FSP MOCO-to-PLL switch);
ReadIntoTraceCache covers runtime ROM execution. J9 closed on both EKs -
open = SWD contention up to apparent bricks.
300 MHz core, 50 MHz TRACECLK, width 2: SB11/SB12 stub TRACED2/3 onto Zio
CN8 and kill width 4 under IRQ-heavy USB traffic (removal = width-4 TODO
at 600 MHz). Session note: --attach while a host actively polls the
device wedges its USB session.
metro_m7_1011 (custom ETM-header rework): 500 MHz core, 66 MHz TRACECLK
width 4, +50 ps; trace_etm_init ungates the 132 MHz trace root that
BOARD_BootClockRUN leaves gated. mimxrt1170_evkb: 996 MHz CM7 at width 1,
CSTRACE pinned to 50 MHz (stock 132 corrupts - the Ethernet PHY loads the
CLK net) and the CM7 platform trace-funnel port enabled in firmware:
J-Link does not program that funnel and everything reads register-perfect
yet silent without it. FlexSPI boot needs the committed SP/PC hooks; D1-D3
stay dead pending the R1882-R1884 continuity check (width-4 TODO).
H5 hangs its debug AP if trace CoreSight is touched unclocked (recover =
power-cycle): the reference's AfterTargetConnect clocks the DBGMCU trace
domain but defers IOEN to firmware, or the mid-boot clock switch desyncs
the decoder. Stock solder bridges make the CN5 path marginal: validated
config is 100 MHz core, width 1, +5 ns (board.h selects the reduced clock
for TRACE_ETM builds); width 4 / 250 MHz retest waits on SB removal.
nrf52840dk: 16 MHz TRACECLK (hardware cap) width 4, P25 soldered, SW7=Alt;
no family code needed (J-Link arms TRACECONFIG). nrf5340dk: TRACE_ETM
builds force the TAD port to 16 MHz (SystemInit's 64 MHz is marginal),
+3 ns sample timing; the interface MCU's UART1 flow control drives the
trace pins - SB27/SB28 must be cut (P0.10/P0.11 = TRACEDATA1/0).
BSP mux + board.h are register-proven; the module routes TRACECLK to the
header only with SJ1's 0-ohm resistor moved to pads 2-3 (Lauterbach doc
confirms), so hardware validation waits on that rework.
60 MHz TRACECLK (CCLK/2) width 4 with J5 DBG_EN fitted; board.h drops the
trace-line pull-ups and the ozone reference points at the device example.
A badly-mated ribbon reads register-perfect yet silent - re-seat first.
120 MHz TRACECLK width 4 over the fully-wired J7 (rev B schematic,
TRACE_5V on pin 11). FS enumeration finishes in <100 ms - ISR analysis
needs a short no-eviction window (--duration-ms 150).
Headless instruction-trace capture on any TRACE_ETM-capable board via
Ozone's automation socket (port 19201, xvfb): etm_capture.py generates a
throwaway project from the board's committed ozone reference (device, TIF,
width, timing, hooks, JLinkScript inheritance), drives the session, and
exports profile/coverage; etm_profile.py renders hot functions, coverage,
per-line/instruction counters and ISR timing from the itrace stream.
SKILL.md carries rig discipline, capture recipes, a new-board bring-up
ladder and troubleshooting; boards.md is the per-board reference (config
table + caveats) for all validated boards.
- 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)
Spec (brainstormed): own-skill backend decision, PHY-conflict map, six
verification gates, external-JTAG TODO. Plan executed same-day: all gates
run on the rig; apptrace resolved per its own gate rule as (untested).
- 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.
- 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).
- Vector catch + Cortex-M fault autopsy, verified with a deliberate bad-load
on stm32f407disco: CFSR=0x8200 (BFARVALID|PRECISERR), BFAR = exact bad
address, stacked pc addr2lined to the faulting line; gotchas recorded
(stale FPB comparators fire phantom SIGTRAPs — scrub first; arm DEMCR
after reset; loads precise / stores imprecise; ARMv6-M has no CFSR/BFAR)
- SWO exception trace + hw PC sampling gate PASSED on F407: 680 KB of
packets in 3 s (0x17 PC samples in flash range, 0x0E SysTick enter/exit);
JLinkSWOViewerCL decodes stimulus only — raw SWORead is the recipe;
SWOStart needs an explicit speed headless
- verifybin 'Verify successful.'; FreeRTOS -rtos plugin lists all 6
cdc_msc_freertos tasks after a run->stop cycle (plain attach = 0xDEAD
placeholder); semihosting anti-note; monitor-mode pointer (untested)
- Intrusiveness table gains the new rows; agent playbook bullet updated;
retrieval gate 5/5 with a fresh reader; executed plan committed
LOGGER=rtt builds of any rp2040 example fail with -Werror=missing-prototypes
(stdio_rtt_init has no prototype and is only called from family.c).
Found by building cdc_msc -DLOG=2 -DLOGGER=rtt for raspberry_pi_pico.
Rename usb-target-debug -> target-debug, usb-debug -> usb-kernel-debug,
usb-recover -> usb-kernel-recover (script filenames unchanged), and make all
debug skills/agents decide tool applicability by which end of the link runs
Linux: TinyUSB may run the device or host stack, and its peer may be a Linux
PC, another TinyUSB board, or a Linux gadget (e.g. Raspberry Pi UDC).
- usbmon: exists only when a Linux PC is the link's host
- usb-kernel-debug: either Linux end; allowlist gains dwc3/libcomposite/udc_core
for the gadget side of a Linux peer
- usb-sniffer: the only full-visibility capture when TinyUSB is the host
- target-debug: covers dcd_* and hcd_*/tuh_ debugging; channel choice by topology
- update target-debugger/hil-operator agents, pre-pr, hil-validate.js, and the
USB_RECOVER path constant in test/hil/usbtest.py
- CLAUDE.md: fold the dcd/hcd datasheet cross-check rule into the read-doc line
* docs: add read-doc skill for on-demand datasheet lookup
Search and read MCU datasheets, reference manuals, errata, and the USB
spec from a local Calibre library ($HOME/Documents/calibre-library)
instead of answering register/bitfield/pinout questions from model
memory. Gated on the library's existence, so it no-ops for contributors
who don't have it.
* docs: reference read-doc skill and tighten CLAUDE.md
Point the datasheet/reference entry at the new read-doc skill, and trim
sections that only duplicate a skill already owning the detail:
PVS-Studio and Code Size collapse to pointers; GDB/Build/Flash command
blocks condensed to essentials. 213 -> 129 lines; behavioral guidelines
and the validation checklist unchanged.
* docs: tighten skill redundancy; rename AGENTS.md refs to CLAUDE.md
code-size: fold the step list into a sentence and drop invocation
examples the argument tables already cover. hil: merge the duplicated
self-lock bullets and compress the hifiphile note. usbmon: compress the
group-membership setup paragraph. All commands, flags, lock rules, and
report paths preserved. usb-target-debug and the pvs script only get
stale AGENTS.md references renamed to CLAUDE.md (now the real file);
run_pvs.sh no longer cites a --dump-files mention that CLAUDE.md dropped.
* docs: fix review findings — restore Espressif cd step, ELF placeholder, code-size comment
Codex/Copilot/Claude review of #3778: the condensed Espressif bullet
lost its cd (idf.py resolves the project from CWD, so the command failed
from repo root); the GDB example now uses the build/your_app.elf
placeholder that docs/troubleshooting.rst established; the code-size
invocation comment no longer references --combined, which the shown
command doesn't use.
