Merge pull request #3851 from hathach/etmtrace-rp2350
rp2350: ETM trace board pico2_etm_trace
diff --git a/.claude/skills/etm-trace/boards.md b/.claude/skills/etm-trace/boards.md
index 044d4e0..f54e1d7 100644
--- a/.claude/skills/etm-trace/boards.md
+++ b/.claude/skills/etm-trace/boards.md
@@ -26,7 +26,7 @@
| mimxrt1170_evkb | 996 MHz | 50 MHz (root/2) | 1 | 0 | weld 0 Ω R1881-R1886; JP4 shorted; J58 (populated) | re-weld R1884 (D3 open; D1/D2 meter-verified good) → width 4 |
| ra6m5_ek (M33) | 200 MHz | 25 MHz (TRCLK/4 /2) | 4 | 0 (unset) | J9 closed; native J20 trace | — |
| ra8m1_ek (M85) | 480 MHz | 60 MHz (TRCLK/4 /2) | 4 | 0 (unset) | J9 closed + Table 7 jumpers | — |
-| raspberry_pi_pico2 (RP2350 M33) | 48 MHz | 24 MHz (clk_sys/2) | 4 | 0 (unset) | fly-wire GPIO1-5 → MIPI20 (map in jdebug) | 72-80 MHz per seating (re-qualify); >80 needs V3 probe + trace board |
+| pico2_etm_trace (RP2350 M33) | 150 MHz | 75 MHz (clk_sys/2) | 4 | +1 ns | Pico 2 on the trace-carrier PCB (MIPI-20) | — |
| same54_xplained (E54 M4F) | 120 MHz | 60 MHz (CPU/2) | 4 | 0 (unset) | none — populated 20-pin ETM header | — |
| same70_xplained (E70 M7) | 300 MHz | 37.5 MHz (PCK3/2) | 1 | 0 (unset) | solder 20-pin header on J403 (bottom) | width 4 blocked: D1 (J403.16) dead at speed — probe-channel crosscheck pending |
| SEGGER H7/F407 ref | demo defaults | demo | 4 | demo | probe-powered: add `--power` | — |
@@ -105,42 +105,68 @@
the decoder at t≈0.05 s every run. Runs both chip maxima (120 MHz TRCLK,
60 MHz pin) clean. `ReadIntoTraceCache 0x0 0x10000` in the download hook
covers runtime chip-ROM execution. ISR entry: `tusb_int_handler`.
-- **raspberry_pi_pico2** (RP2350): TRACECLK is a fixed clk_sys/2, no divider
- (DDR data, like every ARM TPIU pin port). **Measured cliff on this rig:**
- 80 MHz core (40 MHz TRACECLK) traces idle code but dies under dense data;
- 88 MHz+ dies instantly at any width/global-timing/TIF/pad setting. Cause
- not pinned down: the same V2 probe samples 66 MHz TRACECLK (132 Msample/s)
- on metro_m7_1011, so it is NOT a plain probe sample-rate ceiling. The
- cliff at >40 MHz TRACECLK (84+ MHz core) survived a full sweep - global
- AND per-pin `--trace-timing`, pad drive 2/4/8/12 mA + slew, width 4/2/1,
- TIF 1-25 MHz, newer J-Link library - all flat, so it is V3-probe / real-
- trace-board territory (SEGGER's Pico 2 KB requires J-Trace PRO **V3.0+**
- and recommends a proper trace board; community reports fly-wires fail at
- 75 MHz for everyone, PCBs work). Separately, fly-wire seating quality
- sets the width-4 DENSE-data ceiling (48-72 MHz observed across seatings):
- after ANY rewiring re-qualify with idle blinky at the target clock, then
- cdc_msc x3. Random unknown-packet deaths KB into a clean stream = one
- marginal wire; `--trace-width` 1 vs 2 vs 4 bisects which (width 1 =
- CLK+D0 only; D1 = GPIO3->MIPI20 pin 16 has gone marginal twice on this
- rig). Width-1 is a full-quality fallback: complete cdc_msc profiles at up
- to 80 MHz core even when width 4 is broken.
- **Never set a custom JLinkScript** — it
- replaces J-Link's built-in RP2350 device script, which both declares the
- trace component map (funnel/TPIU/ETM are not in the ROM table → "Required
- trace components for pin trace not found", 0 fetches) and re-arms the whole
- chip-side path via `OnTraceStart` at every resume. Firmware therefore does
- no trace setup; TRACE_ETM builds only (a) pin clk_sys to 48 MHz from crt0
- (board.cmake) — the fly-wire ceiling: 96/150 MHz kill the stream in the
- startup burst at any sample timing (and at 150 MHz the saturated probe
- stops answering halts, "CPU could not be halted"); any post-arm clock
- change steps TRACECLK mid-stream and kills the decoder — and (b)
- clear TIMER0/1 DBGPAUSE (family.c): debug sessions leave cores
- halted-at-reset and the default DBGPAUSE freezes the µs timer, so every
- `sleep_ms()` spins forever (looks like a dead board; watchdog-scratch
- breadcrumbs survive warm resets but not POR when diagnosing). UART console
- is TX-only (GPIO1 = TRACECLK). Empty reset/download hooks: the bootrom
- must run the IMAGE_DEF. If the chip ends up wedged/un-attachable:
- J-Link `erase` + reset drops it into BOOTSEL (2e8a:000f) for picotool.
+- **pico2_etm_trace** (Pico 2 / RP2350 on the carrier; board `raspberry_pi_pico2`
+ is the bare module and has no trace wiring): rig = **pico2 trace motherboard PCB**
+ (~/code/pcb/pico2_trace_motherboard: MIPI-20, 27 Ohm source-terminated,
+ GND-guarded). TRACECLK is a fixed clk_sys/2 (DDR), so the board traces at
+ the rp2350 pico-sdk default 150 MHz -> 75 MHz TRACECLK width 4, validated
+ 2026-08-26: cdc_msc enumeration burst 3/3, zero overflow, **data sampling
+ +1 ns** (committed in the reference; idle eye -1000..+2000 ps, +3000 dead;
+ TD aliases modulo the 6.67 ns UI); soak: cdc_msc_throughput under a live
+ host CDC+MSC bulk pump, 3/3 x 15 s, zero overflow, 53.7M fetches (DCD hot
+ path at 9% load). `TRACE_ETM` is set by the board's own board.cmake - no
+ build flag needed.
+ **Other rates need a hand-built clock**: pass `SYS_CLK_KHZ` *together with*
+ `PLL_SYS_VCO_FREQ_HZ`/`POSTDIV1`/`POSTDIV2` from the SDK's
+ `scripts/vcocalc.py` as compile definitions (a bare `-DSYS_CLK_KHZ=` only
+ sets a CMake cache var and is silently ignored - the BSP no longer carries
+ a PLL table). Measured: 180000 = 90 MHz TRACECLK, loaded eye
+ +4000..+5000 ps (3/3); 240000 = **the J-Trace PRO V2 ceiling** (120 MHz
+ TRACECLK, TD +3500) — **⚠ 240 MHz was measured with the core regulator
+ raised to 1.15 V, which nothing does automatically any more: add
+ `SYS_CLK_VREG_VOLTAGE_AUTO_ADJUST=1` and
+ `SYS_CLK_VREG_VOLTAGE_MIN=VREG_VOLTAGE_1_15` yourself, or the chip runs
+ 60% over its 150 MHz rating at stock 1.10 V.** >=125 MHz
+ TRACECLK is a hard probe wall at every sample delay/width (the V2 AT its
+ documented limit: Arm spec 100 MHz in-spec, SEGGER's tuned-V2 best is
+ 120; the 150 MHz on current product pages is V3/V4). **Firmware needs
+ almost no trace code**: J-Link's built-in RP2350 device script declares
+ the off-ROM-table trace components (funnel/TPIU/ETM) and re-arms the
+ whole chip-side path via OnTraceStart at every resume — **never set a
+ custom JLinkScript** (it replaces the built-in script: "Required trace
+ components for pin trace not found", 0 fetches). What TRACE_ETM (set by
+ this board's board.cmake) does in firmware: (a) clears TIMER0/1 DBGPAUSE
+ — J-Link does NOT clear it, and with the reset default the us-timer
+ freezes while a core is debug-halted, so sleep_ms() spins forever after
+ any debugger session (measured: DBGPAUSE reads 0x7 and TIMERAWL stands
+ still until the clear); (b) compile-time pin-conflict checks — #error if
+ the UART console lands on a trace pin GP1-5, #pragma message if the
+ default I2C does. The console itself is full-duplex on GP12/13 (the
+ carrier routes it off GP0/1; the old TX-only fallback is gone with the
+ fly-wire rig). PCB A/B validation did remove the 12 mA fast-slew trace
+ pads (default pads pass 3/3 with a wider idle eye) — do not re-add
+ without fresh PCB evidence. A runtime clk_sys switch **silently
+ truncates the capture at the switch** (no decoder error — profile just
+ ends; verified 3/3 with a board_init-time 120->156 step), so nothing may
+ re-switch the clock at runtime.
+ **This is the only trace-capable board in the rp2040 family** - it owns the
+ sole ozone reference, so `--board <any other rp2040/rp2350 board>` exits
+ with "cannot resolve J-Link device" (the script's board.cmake fallback
+ cannot help: this family sets `JLINK_DEVICE` in family.cmake). Capture with
+ `--board pico2_etm_trace`.
+ **Arm-phase flake**: an occasional instant unknown-packet death at
+ offset ~0x10-0x6C right at trace start — just re-run; only mid-stream
+ deaths indicate a real problem. **Loose MIPI-20 cable symptom ladder**:
+ flash "Failed to perform RAMCode-sided Prepare()" / "Download failed"
+ first, then "Target voltage too low" (VTref lost) — reseat the cable at
+ both ends before debugging software. Empty reset/download hooks in the
+ reference: the bootrom must run the IMAGE_DEF (setting SP/PC from the
+ vector table bypasses it and the pico-sdk runtime never comes up). If
+ the chip ends up wedged/un-attachable: J-Link `erase` + reset drops it
+ into BOOTSEL (2e8a:000f) for picotool. *Historical*: bring-up used a
+ fly-wire rig (same GPIO1-5 -> MIPI20 map) whose wire SI capped TRACECLK
+ at 24-40 MHz and motivated the removed workarounds; it is retired —
+ details in git history (the 48/80 MHz PLL rows left with it).
- **same54_xplained**: the CM4 trace unit is clocked from **GCLK channel 47
(GCLK_CM4_TRACE)** — with it disabled the pins mux fine, TPIU/ETM arm
fine, and the port stays perfectly silent (zero fetches, no errors);
diff --git a/.idea/cmake.xml b/.idea/cmake.xml
index 23e8af7..f5f1fda 100644
--- a/.idea/cmake.xml
+++ b/.idea/cmake.xml
@@ -9,6 +9,8 @@
<configuration PROFILE_NAME="raspberry_pi_pico-pio_host" ENABLED="false" CONFIG_NAME="Debug" GENERATION_OPTIONS="-DBOARD=raspberry_pi_pico -DLOG=1 -DCFLAGS_CLI="-DCFG_TUH_RPI_PIO_USB=1"" />
<configuration PROFILE_NAME="raspberry_pi_pico2" ENABLED="false" CONFIG_NAME="Debug" GENERATION_OPTIONS="-DBOARD=raspberry_pi_pico2 -DLOG=1" />
<configuration PROFILE_NAME="raspberry_pi_pico2-pio_host" ENABLED="false" CONFIG_NAME="Debug" GENERATION_OPTIONS="-DBOARD=raspberry_pi_pico2 -DLOG=1 -DCFLAGS_CLI="-DCFG_TUH_RPI_PIO_USB=1"" />
+ <configuration PROFILE_NAME="pico2_etm_trace" ENABLED="false" CONFIG_NAME="Debug" GENERATION_OPTIONS="-DBOARD=pico2_etm_trace -DLOG=1" />
+ <configuration PROFILE_NAME="pico2_etm_trace-pio_host" ENABLED="false" CONFIG_NAME="Debug" GENERATION_OPTIONS="-DBOARD=pico2_etm_trace -DLOG=1 -DCFLAGS_CLI="-DCFG_TUH_RPI_PIO_USB=1"" />
<configuration PROFILE_NAME="feather_rp2040" ENABLED="false" CONFIG_NAME="Debug" GENERATION_OPTIONS="-DBOARD=pico_sdk -DPICO_BOARD=adafruit_feather_rp2040 -DLOG=1" />
<configuration PROFILE_NAME="feather_rp2040_max3421" ENABLED="false" CONFIG_NAME="Debug" GENERATION_OPTIONS="-DBOARD=feather_rp2040_max3421 -DLOG=1" />
<configuration PROFILE_NAME="metro_rp2040" ENABLED="false" CONFIG_NAME="Debug" GENERATION_OPTIONS="-DBOARD=pico_sdk -DPICO_BOARD=adafruit_metro_rp2040 -DLOG=1 -DMAX3421_HOST=1" />
diff --git a/docs/reference/boards.rst b/docs/reference/boards.rst
index 8b0f798..794c4fa 100644
--- a/docs/reference/boards.rst
+++ b/docs/reference/boards.rst
@@ -236,19 +236,20 @@
Raspberry Pi
------------
-================================ ============================================ ============== ========================================================== ======
-Board Name Family URL Note
-================================ ============================================ ============== ========================================================== ======
+================================ ============================================ ============== ================================================================ ======
+Board Name Family URL Note
+================================ ============================================ ============== ================================================================ ======
raspberrypi_zero Raspberry Pi Zero broadcom_32bit https://www.raspberrypi.org/products/raspberry-pi-zero/
raspberrypi_cm4 Raspberry CM4 broadcom_64bit https://www.raspberrypi.org/products/compute-module-4
raspberrypi_zero2 Raspberry Zero2 broadcom_64bit https://www.raspberrypi.org/products/raspberry-pi-zero-2-w
adafruit_feather_rp2040_usb_host Adafruit Feather RP2040 with USB Type A Host rp2040 https://www.adafruit.com/product/5723
adafruit_fruit_jam Adafruit Fruit Jam - Mini RP2350 rp2040 https://www.adafruit.com/product/6200
adafruit_metro_rp2350 Adafruit Metro RP2350 rp2040 https://www.adafruit.com/product/6003
+pico2_etm_trace Pico 2 ETM Trace Carrier rp2040 https://github.com/hathach/pcb/tree/main/pico2_trace_motherboard
raspberry_pi_pico Pico rp2040 https://www.raspberrypi.com/products/raspberry-pi-pico/
raspberry_pi_pico2 Pico2 rp2040 https://www.raspberrypi.com/products/raspberry-pi-pico-2/
raspberry_pi_pico_w Pico rp2040 https://www.raspberrypi.com/products/raspberry-pi-pico/
-================================ ============================================ ============== ========================================================== ======
+================================ ============================================ ============== ================================================================ ======
Renesas
-------
diff --git a/docs/superpowers/followup/pr3851-msc-host-tur-retry.md b/docs/superpowers/followup/pr3851-msc-host-tur-retry.md
new file mode 100644
index 0000000..462b90f
--- /dev/null
+++ b/docs/superpowers/followup/pr3851-msc-host-tur-retry.md
@@ -0,0 +1,149 @@
+# MSC host: bound the Test Unit Ready retry loop and act on sense data
+
+> Split out of PR #3851 (`etmtrace-rp2350`, rp2350 ETM trace + stock clocks):
+> a host-stack MSC bug with no relation to that branch's scope.
+
+**Goal:** stop `msch_open`'s enumeration retry from spinning forever when a
+device answers Test Unit Ready with CHECK CONDITION, and use the sense data the
+driver already fetches to decide whether to keep waiting, give up, or report.
+
+---
+
+## What is already established
+
+### The loop is unbounded, and the source says so
+
+`src/class/msc/msc_host.c:445-472` is a two-function cycle with no counter:
+
+```c
+static bool config_test_unit_ready_complete(...) {
+ if (csw->status == 0) {
+ ... tuh_msc_read_capacity(...); // ready -> proceed to mount
+ } else {
+ // Note: During enumeration, some device fails Test Unit Ready and require a few retries
+ // with Request Sense to start working !!
+ // TODO limit number of retries <-- :459, pre-existing
+ TU_LOG_DRV("SCSI Request Sense\r\n");
+ TU_ASSERT(tuh_msc_request_sense(dev_addr, cbw->lun, enum_buf,
+ config_request_sense_complete, 0));
+ }
+ return true;
+}
+
+static bool config_request_sense_complete(...) {
+ TU_ASSERT(csw->status == 0);
+ TU_ASSERT(tuh_msc_test_unit_ready(dev_addr, cbw->lun,
+ config_test_unit_ready_complete, 0)); // :472
+ return true;
+}
+```
+
+Two defects, independent of each other:
+
+1. **No bound.** TUR fail -> Request Sense -> TUR -> ... forever. `tuh_msc_mount_cb()`
+ is never called and the application is never told anything; the device sits
+ enumerated-but-unmounted indefinitely.
+2. **Sense data is fetched and discarded.** `config_request_sense_complete`
+ checks only the CSW status. `enum_buf` holds a `scsi_sense_fixed_resp_t`
+ whose `sense_key` / ASC / ASCQ distinguish "Not Ready — becoming ready"
+ (retry is correct) from "Not Ready — medium not present" (a card reader with
+ no card; retrying can never succeed) from a hard error. The driver cannot
+ currently tell these apart because it never looks.
+
+### Measured on hardware (2026-08-25)
+
+Rig: `raspberry_pi_pico` (RP2040) + Pico-PIO-USB host on GP20/21, probe
+`E6614103E719612F`, console over the probe's CDC. Build:
+`-DCFG_TUH_RPI_PIO_USB=1 -DLOG=2`.
+
+- `examples/host/msc_file_explorer` never mounts. Debug log over ~25 s:
+ **1× `SCSI Test Unit Ready`, 350× `SCSI Request Sense`**, zero
+ `SCSI Read Capacity`, zero mount callbacks. `dd` reports
+ `no MSC device mounted`.
+- **The transfers themselves all succeed** — every CBW/CSW pair logs `OK`
+ (`Queue EP 02 with 31 bytes ... OK`, `Queue EP 81 with 13 bytes ... OK`), so
+ this is a SCSI-state-machine problem, not a bulk-transfer or PIO-USB timing
+ problem.
+- Reproduced with **two different drives** (`24a9:1802` "STORAGE DEVICE" and the
+ drive swapped in after it), so it is not one device's quirk.
+- Control transfers on the same target are fine: `examples/host/device_info`
+ reads full descriptors from the same drive on the same board
+ (`bcdUSB 0210`, `bMaxPacketSize0 64`, i.e. full-speed).
+- **The very same drive mounts and sustains I/O on RP2350**
+ (`pico2_etm_trace` carrier): `msc_file_explorer` + `dd` returns
+ `dd: 524288 bytes in 8448 ms = 62 KB/s`. Confirmed by the maintainer at the
+ bench, so the device is healthy and the "not ready" answer is provoked by
+ something specific to the RP2040 setup.
+- **Bumping Pico-PIO-USB does not fix it.** Retested with upstream HEAD
+ `5a37a66` (10 commits ahead of the pinned `675543b`, including
+ `512d3a2` "Place calc_usb_crc16 in RAM like calc_usb_crc5 and the CRC
+ tables", which looked like a promising RP2040 timing fix, and `cbf055d`
+ transaction-length clamp) via `-DPICO_PIO_USB_PATH=<clone>`: identical
+ failure, no mount.
+- Clock is **not** a factor: identical failure at 120 MHz, 133 MHz and
+ 156 MHz on RP2040 (and on RP2350 all of 120/125/126/138/150/156/162/174/186/240 MHz
+ behave identically).
+
+### What is NOT established
+
+- The actual sense key/ASC/ASCQ the failing drives return — the driver never
+ logs it. **Task 1 below exists to capture it**, and its answer decides whether
+ a bounded retry is sufficient or a "medium not present" path is also needed.
+- **Why the RP2040 setup provokes the not-ready state.** Leading suspect is
+ VBUS quality rather than firmware: the RP2350 carrier feeds J5 through a
+ proper load switch, while the RP2040 rig is a bare Pico whose GP22 "VBUS
+ enable" drives nothing (no load switch on a bare Pico), so the drive is fed
+ directly off the VBUS pin through hookup wire. A bus-powered drive that
+ cannot spin up answers exactly this "not ready" forever. Measure VBUS at the
+ device under load, or retest with a powered hub / self-powered device,
+ BEFORE attributing the stall to the host stack.
+- The actual sense key (Task 1) — still the gate for any policy change.
+
+---
+
+## What remains
+
+### Task 1: Log the sense response (diagnostic, ship-able on its own)
+
+**Files:** `src/class/msc/msc_host.c` (`config_request_sense_complete`, ~:467)
+
+Add a `TU_LOG_DRV` of `sense_key`, `add_sense_code`, `add_sense_qualifier` from
+the fixed-format response in `usbh_get_enum_buf()`. `scsi_sense_fixed_resp_t` is
+already declared in `src/class/msc/msc.h`.
+
+Verify on the rig above: rebuild `msc_file_explorer` with `-DLOG=2`, flash, read
+the probe CDC, and record the triple. Expected candidates:
+`0x02/0x04/0x01` (becoming ready) or `0x02/0x3A/0x00` (medium not present).
+
+### Task 2: Bound the retry
+
+**Files:** `src/class/msc/msc_host.c`, `msch_interface_t` (add a retry counter),
+`src/class/msc/msc_host.h` (a `CFG_TUH_MSC_TUR_RETRY_COUNT`-style knob with a
+sane default; follow the existing `CFG_TUH_MSC_*` naming in
+`src/tusb_option.h`).
+
+On exhaustion, stop the cycle and surface the failure rather than silently
+looping — the application currently has no way to learn the device is stuck.
+
+### Task 3: Decide behaviour per sense key
+
+Gated on Task 1's measurement. At minimum: keep retrying on "becoming ready",
+stop immediately on "medium not present". Do not invent policy for sense keys
+that were not observed.
+
+### Task 4: Regression coverage
+
+`test/unit-test/` has no MSC host suite today; adding one means mocking
+`tuh_msc_*` completions. Confirm with the maintainer whether a unit test or a
+HIL case on a known not-ready device (an empty card reader is the cheap
+reproducer) is the wanted evidence before building either.
+
+---
+
+## Why it was split out
+
+Found while sweeping PIO-USB clocks on the `etmtrace-rp2350` branch, which
+touches only rp2040/rp2350 clock pinning and ETM trace config. This bug is in
+the class-driver layer, affects every MCU running the MSC host, and predates
+that branch (the `// TODO limit number of retries` is already in master). It
+deserves its own PR and its own hardware evidence.
diff --git a/hw/bsp/BoardPresets.json b/hw/bsp/BoardPresets.json
index a480efc..280d6d5 100644
--- a/hw/bsp/BoardPresets.json
+++ b/hw/bsp/BoardPresets.json
@@ -507,6 +507,10 @@
"inherits": "default"
},
{
+ "name": "pico2_etm_trace",
+ "inherits": "default"
+ },
+ {
"name": "pico_sdk",
"inherits": "default"
},
@@ -1641,6 +1645,11 @@
"configurePreset": "nutiny_sdk_nuc505"
},
{
+ "name": "pico2_etm_trace",
+ "description": "Build preset for the pico2_etm_trace board",
+ "configurePreset": "pico2_etm_trace"
+ },
+ {
"name": "pico_sdk",
"description": "Build preset for the pico_sdk board",
"configurePreset": "pico_sdk"
@@ -3901,6 +3910,19 @@
]
},
{
+ "name": "pico2_etm_trace",
+ "steps": [
+ {
+ "type": "configure",
+ "name": "pico2_etm_trace"
+ },
+ {
+ "type": "build",
+ "name": "pico2_etm_trace"
+ }
+ ]
+ },
+ {
"name": "pico_sdk",
"steps": [
{
diff --git a/hw/bsp/rp2040/boards/pico2_etm_trace/board.cmake b/hw/bsp/rp2040/boards/pico2_etm_trace/board.cmake
new file mode 100644
index 0000000..53f9132
--- /dev/null
+++ b/hw/bsp/rp2040/boards/pico2_etm_trace/board.cmake
@@ -0,0 +1,35 @@
+set(PICO_PLATFORM rp2350-arm-s)
+set(PICO_BOARD pico2)
+
+# ETM trace is wired on this carrier only (GP1-5 -> MIPI-20), so the trace
+# build flag lives here rather than being a global -D anyone can pass: on a
+# board whose PIO-USB D+ sits on GP1 (e.g. adafruit_fruit_jam) it would fight
+# the trace clock.
+set(TRACE_ETM 1)
+
+# Point the pico-sdk's own defaults at the carrier's wiring: pico2.h guards
+# every PICO_DEFAULT_* with #ifndef, so these win. Without them anything that
+# talks to the SDK directly instead of the TinyUSB BSP (e.g. stdio_init_all()
+# in examples/device/cdc_uac2) would mux GP0/GP1 for UART - and GP1 is
+# TRACECLK, so it would silently kill the trace clock mid-capture.
+add_compile_definitions(
+ PICO_DEFAULT_UART_TX_PIN=12
+ PICO_DEFAULT_UART_RX_PIN=13
+ PICO_DEFAULT_LED_PIN=10
+ PICO_DEFAULT_I2C=0 # STEMMA-QT / Qwiic port on GP8/9;
+ PICO_DEFAULT_I2C_SDA_PIN=8 # the sdk default GP4/5 is TRACEDATA2/3
+ PICO_DEFAULT_I2C_SCL_PIN=9
+)
+
+# the carrier's MIPI-20 is driven by a J-Trace; uncomment (or pass
+# -DJLINK_OPTION=...) to pin one probe by USB nickname/serial when several
+# J-Links are attached during hardware validation
+#set(JLINK_OPTION "-USB jtrace")
+
+# Clock: the rp2350 pico-sdk default, 150 MHz -> 75 MHz TRACECLK (clk_sys/2),
+# validated on the trace motherboard: cdc_msc enumeration burst 3/3, zero
+# overflow, +1 ns data sampling (idle eye -1000..+2000 ps; committed in the
+# ozone reference). Nothing may switch clk_sys at runtime - that truncates a
+# capture at the switch. Other validated rates (156000, 180000, and 240000 =
+# the J-Trace PRO V2 ceiling) need PLL_SYS_* from the SDK's vcocalc.py; see
+# the etm-trace skill's boards.md.
diff --git a/hw/bsp/rp2040/boards/pico2_etm_trace/board.h b/hw/bsp/rp2040/boards/pico2_etm_trace/board.h
new file mode 100644
index 0000000..863d0e6
--- /dev/null
+++ b/hw/bsp/rp2040/boards/pico2_etm_trace/board.h
@@ -0,0 +1,80 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2025 Ha Thach (tinyusb.org)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * This file is part of the TinyUSB stack.
+ */
+
+/* metadata:
+ name: Pico 2 ETM Trace Carrier
+ url: https://github.com/hathach/pcb/tree/main/pico2_trace_motherboard
+*/
+
+// Raspberry Pi Pico 2 seated on the "pico2 trace motherboard" carrier: a
+// MIPI-20 Cortex Debug+ETM adapter (SWD + 4-bit trace) plus a TinyUSB test
+// bench. Same RP2350 module as raspberry_pi_pico2, different pin map: the
+// carrier keeps GP1-5 free for TRACECLK/TRACEDATA0-3 and moves the console,
+// LED, button and USB control pins out of the way.
+//
+// Carrier pin map (only the pins the BSP uses are defined below):
+// 0 GND guard (JP2) 1 TRACECLK
+// 2-5 TRACEDATA0-3 6 GND guard (JP3)
+// 8/9 I2C0 SDA/SCL (STEMMA-QT) 10 user LED
+// 11 device D+ pull-up enable 12/13 UART0 TX/RX (console)
+// 14 user button (to GND, unused - BSP uses BOOTSEL)
+// 15 host VBUS fault
+// 16 native VBUS-detect tap 17 host VBUS enable
+// 18/19 PIO-USB device D+/D- (J9) 20/21 PIO-USB host D+/D- (J5)
+// 26 VBUS current sense (ADC) 27 J9 device VBUS-detect
+
+#ifndef TUSB_BOARD_H
+#define TUSB_BOARD_H
+
+#ifdef __cplusplus
+ extern "C" {
+#endif
+
+//--------------------------------------------------------------------+
+// LED, UART (button: the family BSP uses BOOTSEL, like every rp2040 board)
+//--------------------------------------------------------------------+
+#define LED_PIN 10
+#define LED_STATE_ON 1
+
+// console is on GP12/13, NOT the pico default GP0/1: GP1 is TRACECLK, so the
+// console stays full-duplex while tracing
+#define UART_DEV 0 // uart0 (index, see uart_get_instance)
+#define UART_TX_PIN 12
+#define UART_RX_PIN 13
+
+//--------------------------------------------------------------------+
+// PIO_USB
+//--------------------------------------------------------------------+
+// host port J5 (USB-A): D+ = GP20, D- = GP21, load switch enable = GP17
+#define PICO_DEFAULT_PIO_USB_DP_PIN 20
+#define PICO_DEFAULT_PIO_USB_VBUSEN_PIN 17
+#define PICO_DEFAULT_PIO_USB_VBUSEN_STATE 1
+
+#ifdef __cplusplus
+ }
+#endif
+
+#endif
diff --git a/hw/bsp/rp2040/boards/pico2_etm_trace/ozone/rp2350.jdebug b/hw/bsp/rp2040/boards/pico2_etm_trace/ozone/rp2350.jdebug
new file mode 100644
index 0000000..fd5d589
--- /dev/null
+++ b/hw/bsp/rp2040/boards/pico2_etm_trace/ozone/rp2350.jdebug
@@ -0,0 +1,79 @@
+/*********************************************************************
+*
+* OnProjectLoad
+*
+* Function description
+* Project load routine. Required.
+*
+* Notes
+* Board pico2_etm_trace = a Pico 2 seated on the pico2 trace motherboard
+* carrier (MIPI-20, source-terminated), GPIO1-5 to the MIPI20:
+* TRACECLK=GPIO1->12, D0=GPIO2->14, D1=GPIO3->16, D2=GPIO4->18,
+* D3=GPIO5->20. Firmware needs NO trace-specific code: J-Link's
+* built-in RP2350 device script declares the off-ROM-table trace
+* components (funnel/TPIU/ETM) and re-arms the whole chip-side path
+* via OnTraceStart at every resume - do NOT set a custom JLinkScript
+* here (it replaces that built-in script and J-Link then fails with
+* "Required trace components for pin trace not found"). TRACE_ETM (set
+* by this board's own board.cmake) clears TIMER0/1 DBGPAUSE - J-Link
+* does not, and the reset default freezes the us-timer while a core is
+* debug-halted - and adds compile-time checks that no console/I2C pin
+* lands on the trace pins GP1-5; the console is full-duplex on GP12/13.
+* clk_sys is the rp2350 pico-sdk default
+* 150 MHz (75 MHz TRACECLK) and nothing may re-switch it at runtime:
+* a mid-stream step silently truncates the capture.
+*
+**********************************************************************
+*/
+void OnProjectLoad (void) {
+ Project.SetTraceSource ("Trace Pins");
+ Project.SetTracePortWidth (4);
+ Project.SetSWO (0);
+ // +1 ns data sampling: at 75 MHz TRACECLK (DDR) on the trace motherboard
+ // the idle eye spans -1000..+2000 ps and cdc_msc passes 3/3 at +1000
+ // (+3000 dead; TD aliases modulo the 6.67 ns UI)
+ Project.SetTraceTiming (1000, 1000, 1000, 1000);
+ Edit.SysVar (VAR_TRACE_CORE_CLOCK, 150000000);
+ Project.AddSvdFile ("$(InstallDir)/Config/CPU/Cortex-M33F.svd");
+
+ Project.SetDevice ("RP2350_M33_0");
+ Project.SetHostIF ("USB", "");
+ Project.SetTargetIF ("SWD");
+ Project.SetTIFSpeed ("25 MHz");
+
+ File.Open ("../../../../../../examples/cmake-build-pico2_etm_trace/device/cdc_msc/cdc_msc.elf");
+}
+
+/*********************************************************************
+*
+* AfterTargetReset
+*
+* Function description
+* Event handler routine.
+* - Sets the PC register to program reset value.
+* - Sets the SP register to program reset value on Cortex-M.
+*
+**********************************************************************
+*/
+void AfterTargetReset (void) {
+ // intentionally empty: the RP2350 bootrom must run to validate the
+ // IMAGE_DEF and hand over to the app - setting SP/PC from the vector
+ // table bypasses it and the pico-sdk runtime never comes up
+}
+
+/*********************************************************************
+*
+* AfterTargetDownload
+*
+* Function description
+* Event handler routine.
+* - Sets the PC register to program reset value.
+* - Sets the SP register to program reset value on Cortex-M.
+*
+**********************************************************************
+*/
+void AfterTargetDownload (void) {
+ // intentionally empty: the RP2350 bootrom must run to validate the
+ // IMAGE_DEF and hand over to the app - setting SP/PC from the vector
+ // table bypasses it and the pico-sdk runtime never comes up
+}
diff --git a/hw/bsp/rp2040/boards/raspberry_pi_pico2/board.cmake b/hw/bsp/rp2040/boards/raspberry_pi_pico2/board.cmake
index 08384b0..0a7dd4d 100644
--- a/hw/bsp/rp2040/boards/raspberry_pi_pico2/board.cmake
+++ b/hw/bsp/rp2040/boards/raspberry_pi_pico2/board.cmake
@@ -1,17 +1,3 @@
set(PICO_PLATFORM rp2350-arm-s)
set(PICO_BOARD pico2)
#set(OPENOCD_SERIAL E6614103E77C5A24)
-
-if (TRACE_ETM STREQUAL "1")
- # TRACECLK is clk_sys/2 and must stay constant once trace is armed (a step
- # desyncs the decoder), so the trace clock is pinned from crt0 onwards.
- # 48 MHz (24 MHz TRACECLK) holds full-width trace on a typical fly-wire
- # seating; a fresh, tight seating supports up to 72-80 MHz (re-qualify per
- # the etm-trace skill), and >80 MHz needs a V3 probe + real trace board.
- add_compile_definitions(
- SYS_CLK_KHZ=48000
- PLL_SYS_VCO_FREQ_HZ=1440000000
- PLL_SYS_POSTDIV1=6
- PLL_SYS_POSTDIV2=5
- )
-endif ()
diff --git a/hw/bsp/rp2040/boards/raspberry_pi_pico2/ozone/rp2350.jdebug b/hw/bsp/rp2040/boards/raspberry_pi_pico2/ozone/rp2350.jdebug
deleted file mode 100644
index ff48eb6..0000000
--- a/hw/bsp/rp2040/boards/raspberry_pi_pico2/ozone/rp2350.jdebug
+++ /dev/null
@@ -1,70 +0,0 @@
-/*********************************************************************
-*
-* OnProjectLoad
-*
-* Function description
-* Project load routine. Required.
-*
-* Notes
-* Pico 2 has no trace connector - fly-wire GPIO1-5 to the MIPI20:
-* TRACECLK=GPIO1->12, D0=GPIO2->14, D1=GPIO3->16, D2=GPIO4->18,
-* D3=GPIO5->20 (SEGGER validates this board the same way). Firmware must
-* be built with TRACE_ETM=1: it pins clk_sys to 48 MHz (board.cmake) so
-* the 4-bit port never saturates and the clock never steps mid-stream,
-* and keeps the us-timer free of TIMER DBGPAUSE (family.c). The whole
-* chip-side trace path (ETM/funnel/TPIU/pin mux) is armed by J-Link's
-* built-in RP2350 script at every resume - do NOT set a custom
-* JLinkScript here: it would replace that script and J-Link then fails
-* with "Required trace components for pin trace not found".
-* GPIO1 is the default UART0 RX: console TX still works, RX is lost.
-*
-**********************************************************************
-*/
-void OnProjectLoad (void) {
- Project.SetTraceSource ("Trace Pins");
- Project.SetTracePortWidth (4);
- Project.SetSWO (0);
- Edit.SysVar (VAR_TRACE_CORE_CLOCK, 48000000);
- Project.AddSvdFile ("$(InstallDir)/Config/CPU/Cortex-M33F.svd");
-
- Project.SetDevice ("RP2350_M33_0");
- Project.SetHostIF ("USB", "");
- Project.SetTargetIF ("SWD");
- Project.SetTIFSpeed ("25 MHz");
-
- File.Open ("../../../../../../examples/cmake-build-raspberry_pi_pico2/device/cdc_msc/cdc_msc.elf");
-}
-
-/*********************************************************************
-*
-* AfterTargetReset
-*
-* Function description
-* Event handler routine.
-* - Sets the PC register to program reset value.
-* - Sets the SP register to program reset value on Cortex-M.
-*
-**********************************************************************
-*/
-void AfterTargetReset (void) {
- // intentionally empty: the RP2350 bootrom must run to validate the
- // IMAGE_DEF and hand over to the app - setting SP/PC from the vector
- // table bypasses it and the pico-sdk runtime never comes up
-}
-
-/*********************************************************************
-*
-* AfterTargetDownload
-*
-* Function description
-* Event handler routine.
-* - Sets the PC register to program reset value.
-* - Sets the SP register to program reset value on Cortex-M.
-*
-**********************************************************************
-*/
-void AfterTargetDownload (void) {
- // intentionally empty: the RP2350 bootrom must run to validate the
- // IMAGE_DEF and hand over to the app - setting SP/PC from the vector
- // table bypasses it and the pico-sdk runtime never comes up
-}
diff --git a/hw/bsp/rp2040/family.c b/hw/bsp/rp2040/family.c
index e12f51b..9de1658 100644
--- a/hw/bsp/rp2040/family.c
+++ b/hw/bsp/rp2040/family.c
@@ -158,15 +158,34 @@
}
#endif
-//--------------------------------------------------------------------+
-//
-//--------------------------------------------------------------------+
#if defined(TRACE_ETM) && defined(PICO_RP2350) && PICO_RP2350 == 1
-// J-Link's built-in RP2350 device script re-arms the whole chip-side trace
-// path (ETM/funnel/TPIU/pins) via OnTraceStart at every resume, so firmware
-// must NOT touch it - it only keeps the us-timer running while cores sit
-// debug-halted (default TIMER DBGPAUSE freezes it, and sleep_ms() then spins
-// forever after any debugger session).
+// ETM trace owns GP1-5 (GP1 = TRACECLK, GP2-5 = TRACEDATA0-3): muxing any of
+// them away - even briefly - gaps the trace clock/data and desyncs the probe.
+#define TRACE_PIN_CONFLICT(pin) ((pin) >= 1 && (pin) <= 5)
+// board_init() muxes UART_TX_PIN/UART_RX_PIN, which are defined whenever UART_DEV is
+#ifdef UART_DEV
+ #if TRACE_PIN_CONFLICT(UART_TX_PIN) || TRACE_PIN_CONFLICT(UART_RX_PIN)
+ #error "TRACE_ETM: UART TX/RX sits on a trace pin (GP1-5) - route the console elsewhere (pico2_etm_trace uses GP12/13)"
+ #endif
+#endif
+// stdio_init_all() muxes the sdk defaults even when the BSP console is elsewhere
+#if defined(LIB_PICO_STDIO_UART) && defined(PICO_DEFAULT_UART_TX_PIN) && \
+ (TRACE_PIN_CONFLICT(PICO_DEFAULT_UART_TX_PIN) || TRACE_PIN_CONFLICT(PICO_DEFAULT_UART_RX_PIN))
+ #error "TRACE_ETM: pico-sdk default UART (stdio_init_all) sits on a trace pin (GP1-5)"
+#endif
+#if defined(PICO_DEFAULT_I2C_SDA_PIN) && (TRACE_PIN_CONFLICT(PICO_DEFAULT_I2C_SDA_PIN) || TRACE_PIN_CONFLICT(PICO_DEFAULT_I2C_SCL_PIN))
+ // #pragma message, not #warning: examples build with -Werror, and this is
+ // only a hazard if the app actually uses i2c_default
+ #pragma message("TRACE_ETM: default I2C SDA/SCL sits on a trace pin (GP1-5) - using i2c_default will corrupt the trace stream (pico2_etm_trace routes I2C to GP8/9)")
+#endif
+
+// A debugger session leaves a core halted (Ozone captures halt at the end,
+// openocd halts both cores to flash), and TIMER's reset default pauses the
+// us-timer whenever EITHER core is debug-halted - J-Link's RP2350 script does
+// NOT clear it (verified: DBGPAUSE still reads 0x7, TIMERAWL frozen while
+// halted). tusb_time_millis_api()/sleep_ms() then spin forever and the board
+// looks dead, so free the timer for trace builds, which always run under a
+// probe.
static void trace_etm_init(void) {
*(volatile uint32_t*) 0x400B002Cu = 0; // TIMER0 DBGPAUSE
*(volatile uint32_t*) 0x400B802Cu = 0; // TIMER1 DBGPAUSE
@@ -177,20 +196,15 @@
void board_init(void)
{
+ trace_etm_init();
+
#if (CFG_TUH_ENABLED && CFG_TUH_RPI_PIO_USB) || (CFG_TUD_ENABLED && CFG_TUD_RPI_PIO_USB)
- // Set the system clock to a multiple of 12mhz for bit-banging USB with pico-usb
- #if defined(PICO_RP2350) && PICO_RP2350 == 1
- #ifdef TRACE_ETM
- #error "TRACE_ETM pins clk_sys to 48 MHz (board.cmake) - too slow for PIO-USB, and a runtime clock switch desyncs the trace stream"
- #endif
- set_sys_clock_khz(156000, true); // rp2350 default is 150Mhz
- #else
+ // rp2350 runs the pico-sdk stock 150 MHz (a runtime switch also truncates ETM
+ // capture). rp2040 keeps 120 MHz: soak-tested — the stock 125 MHz collapses
+ // PIO-USB bulk-OUT (device NAKs ~600:1, wire-measured, zero CRC errors).
+ #if !(defined(PICO_RP2350) && PICO_RP2350 == 1)
set_sys_clock_khz(120000, true); // rp2040 default is 125Mhz
#endif
- // set_sys_clock_khz(180000, true);
- // set_sys_clock_khz(192000, true);
- // set_sys_clock_khz(240000, true);
- // set_sys_clock_khz(264000, true);
#ifdef PICO_DEFAULT_PIO_USB_VBUSEN_PIN
gpio_init(PICO_DEFAULT_PIO_USB_VBUSEN_PIN);
@@ -217,17 +231,9 @@
#ifdef UART_DEV
uart_inst = uart_get_instance(UART_DEV);
-#if defined(TRACE_ETM) && defined(PICO_RP2350) && PICO_RP2350 == 1
- // GPIO1 (default UART RX) is TRACECLK: TX-only console, and never touch
- // GPIO1 - even a brief re-mux gaps the trace clock and desyncs the probe
- bi_decl(bi_1pin_with_name(UART_TX_PIN, "UART TX"));
- stdio_uart_init_full(uart_inst, CFG_BOARD_UART_BAUDRATE, UART_TX_PIN, -1);
-#else
bi_decl(bi_2pins_with_func(UART_TX_PIN, UART_RX_PIN, GPIO_FUNC_UART));
stdio_uart_init_full(uart_inst, CFG_BOARD_UART_BAUDRATE, UART_TX_PIN, UART_RX_PIN);
#endif
-#endif
- trace_etm_init();
#if defined(LOGGER_RTT)
stdio_rtt_init();
diff --git a/tools/build.py b/tools/build.py
index 0bb366e..aa8868c 100755
--- a/tools/build.py
+++ b/tools/build.py
@@ -34,6 +34,7 @@
'adafruit_fruit_jam',
'adafruit_metro_rp2350',
'feather_rp2040_max3421',
+ 'pico2_etm_trace',
'pico_sdk',
'raspberry_pi_pico_w',
],
