hw: DSLogic JTAG diagnostics — BLOCKER-1 physical debug

[gHashTag]

Summary

BLOCKER-1: ESP32 XVC JTAG is broken (IDCODE returns 0x00001388 instead of 0x03631093). Need DSLogic logic analyzer capture to diagnose TCK/TMS/TDI/TDO signal integrity.

Hardware Setup

DSLogic Probe Wiring (JTAG header on QMTECH Wukong V1)

DSLogic CH	JTAG Pin	Signal	QMTECH Pin
CH0	Pin 5	TCK	T14
CH1	Pin 6	TMS	T15
CH2	Pin 4	TDI	U14
CH3	Pin 3	TDO	U15
GND	Pin 2	GND	—

DSView Settings

• Sample rate: 16 MS/s
• Threshold: 1.6V (3.3V CMOS)
• Protocol decoder: JTAG (TCK=CH0, TMS=CH1, TDI=CH2, TDO=CH3)

Steps

• 1. Wire DSLogic to JTAG header
• 2. Start DSView capture
• 3. Run openFPGALoader --cable xvc-client --ip 192.168.1.30 --detect
• 4. Capture trace → save as fpga/diagnostics/captures/jtag_xvc_detect.dsl
• 5. Analyze: where does XVC break? (TCK missing? TMS stuck? TDO floating?)
• 6. If XVC dead → switch to DLC-10: python3 tools/dlc10_jtag.py --detect
• 7. Verify IDCODE = 0x03631093 via DLC-10
• 8. Program: python3 tools/dlc10_jtag.py fpga/vsa/gf16_heartbeat_top.bit
• 9. Verify STATUS = 0x401079FC (DONE=1)

Expected Results

Cable	IDCODE	STATUS	Verdict
ESP32 XVC	0x00001388	—	BROKEN
DLC-10	0x03631093	0x401079FC	WORKING

Files

• tools/dlc10_jtag.py (commit f5ad8be0) — native DLC-10 driver
• tools/read_status.py — JTAG status register reader
• fpga/vsa/gf16_heartbeat_top.bit — synthesized bitstream
• fpga/diagnostics/ — (to be created) DSView configs + captures

References

• Issue [SEED-6] Ring-6: test blocks → Zig test blocks #14 (FPGA flash verification)
• Commit f5ad8be0 (DLC-10 driver + heartbeat verified on silicon)
• docs/fpga/clocking.md (pin mapping reference)

[gHashTag]

Update 2026-05-13: FGG676 proxy bitstream now builds in CI

Built spiOverJtag_xc7a100tfgg676.bit cleanly via GitHub Actions on the
gHashTag/openFPGALoader fork (workflow run 25753882084, commit f44f5af3).

XDC fix (spiOverJtag/constr_xc7a_fgg676.xdc): the prior pinout used
dedicated configuration bank pins (C8/B19/A18/B18/A19), which are
GT terminals in the FGG676 package — Vivado correctly rejected them
("is not a valid site or package pin name", "Setting property 'IOSTANDARD'
is not allowed for GT terminals"). Corrected to Bank 14 user IO sourced
from the official QMTech schematic
(QMTECH_XC7A75T_100T_200T-CORE-BOARD-V01-20210109.pdf):

PACKAGE_PIN P18 -> csn       (IO_L6P_T0_FCS_B_14)
PACKAGE_PIN R14 -> sdi_dq0   (IO_L1P_T0_D00_MOSI_14)
PACKAGE_PIN R15 -> sdo_dq1   (IO_L1N_T0_D01_DIN_14)
PACKAGE_PIN P14 -> wpn_dq2   (IO_L2P_T0_D02_14)
PACKAGE_PIN N14 -> hldn_dq3  (IO_L2N_T0_D03_14)

Bitstream artifact:

• size: 407,262 bytes
• sha256: bf5be125e9098d61b4855c599b19a5c90c360592991b7b9b7835af02e605cad2
• strings | grep 7a100t → 7a100tfgg676 ✓
• deployed to fpga/tools/bscan_spi_xc7a100t.bit in commit f8ddfde6 on
  feat/dlc10-rust, re-embedded into cli/dlc10 via include_bytes!.

Also fixed in this loop: the on-board SPI flash on the QMTech core board is
N25Q064A 3V (64 Mbit), JEDEC ID 20 BA 17, not MT25QL128 (20 BA 18) as
the SPEC previously stated.

Remaining BLOCKER-1 work (still on this issue):
tri fpga proxy-load now loads the correct FGG676 bitstream but
tri fpga proxy-status still reports STAT=0x00000000 (DONE=0, EOS=0,
INIT_B=0). The pre-existing Docker-Vivado bitstream also fails the same way,
so the remaining failure mode is in the JTAG transport layer
(cli/dlc10::program_sram_verbose), not in the bitstream content.
Diagnostic suggestions:

• compare against openFPGALoader -c dirtyJtag driving the same .bit
• check that the JTAG bitstream framing prepends JPROGRAM (instr 0x0B) +
  the standard 7-series JPROGRAM/CFG_IN sequence
• confirm CFG_IN IR is selected before the payload (instr 0x05 on XC7A100T)
• watch INIT_B rise/fall manually via tri fpga ir-probe vs raw shift

[gHashTag]

✅ BLOCKER-1 unblocked — JEDEC 20 BA 17 reads end-to-end

3-month FGG676 SPI flash blocker resolved in one session. Four root causes fixed:

1. program_sram_verbose (cdb820c3) — DLC10 FX2 firmware does NOT propagate TDO during Shift-IR. Replaced IR-capture INIT_B polling with 50 ms blind sleep + 12×cycle_tck(10_000) for erase margin. JSTART startup clocks: 24 → 2000.
2. read_cfg_reg_raw_n (cdb820c3) — old impl sent 5 Type-1 packets through 5 separate shift_dr_small calls; Update-DR/RTI between packets reset CFG_IN buffer. Rewrote as ONE unbroken TMS/TDI vector (TLR → RTI → CFG_IN IR → 160-bit packet DR → SELECT_IR → CFG_OUT IR → DR read). idcode-cfg returns 0x13631093.
3. JSTART pulse train (cdb820c3) — previous code issued JSTART then only 24 TCK pulses, far too few to walk the 7-series startup FSM through its 8-phase sequence when clocked from CCLK. Bumped to 2000 TCK pulses with cycle_tck(10_000) margin, plus a 50 ms blind sleep before STAT poll. With this alone (no Vivado bitstream changes), STAT went from 0x4000190C (EOS=0 forever) to 0x401079FC — DONE=1, EOS=1. Correction: the original write-up hypothesized that BITSTREAM.STARTUP.STARTUPCLK=JtagClk was required; we later verified that COR0 in the CI bitstream still has STARTUPCLK=Cclk (0x02003fe5, bits[27:26]=00) and the startup FSM completes anyway when given enough TCK pulses. Setting STARTUPCLK=JtagClk in the Vivado/openFPGALoader project would be a cleaner long-term property to add (separate follow-up), but it is not what unblocked us here.
4. spi_xfer_v2 (b802712e) — new spiOverJtag_core.v bridge uses an FSM IDLE → RECV_HEADER1 [→ RECV_HEADER2] → XFER → WAIT_END and requires start-bit + header byte(s) on the wire. Old spi_xfer sent raw bytes → csn never asserted → MISO floated FF FF FE. Ported Xilinx::spi_put_v2 from openFPGALoader src/xilinx.cpp:2278. Critical gotcha: real_len = max(tx.len(), rx_len) + 1, not tx.len() + 1.

$ tri fpga flash-id
JEDEC ID: 20 BA 17    # N25Q064A, 8 Mbit, matches QMTech XC7A100T-2FGG676I BOM ✓

Closes #592. This issue (#590) stays open as a tracking issue for any further physical-layer DLC10/JTAG diagnostics work.

Next: tri fpga program fpga/vsa/gf16_heartbeat_top.bit → power-cycle → LEDs from flash → BLOCKER-2.