From 27836d63bbabee22b10329ca1b18776618b04e8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois?= Date: Sun, 24 May 2026 01:28:20 +0200 Subject: [PATCH] doc: design note for a standalone embedded port (Arduino GIGA R1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Captures feasibility and shape of an MCU-based programmer: the MCU is the JTAG master (GPIO/SPI-assisted driver behind the existing drv_TX_TMS/drv_TXRX_DATA seam), jtag_core/registry/SVF-player/flash logic reused as-is, REPL/os_interface/BSDL-parse dropped or replaced, and the one real rework — stream payloads from SD/USB in chunks instead of one big malloc. SVF-from-SD is the ideal fit for small Lattice/IGLOO2. --- CLAUDE.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 8d88369..044e981 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -183,6 +183,51 @@ a registry entry. one-time NVCM) with minimal JTAG — out of scope for this JTAG-centric tool. +## Embedded port (design note) + +Not yet implemented — captured for a possible standalone programmer. +No hard blocker: standalone JTAG programmers are all MCU-based. The +architecture has the right seam (the driver function-pointer table). + +**Reference target: Arduino GIGA R1 WiFi** — STM32H747XI (Cortex-M7 +@ 480 MHz + M4 @ 240 MHz, 1 MB RAM, 2 MB flash), WiFi/BT, Arduino/Mbed +OS. The comfortable high end. ESP32 is a lighter alternative (WiFi +on-die, ~520 KB RAM); avoid bare AVR (RAM too small). + +**The seam — the MCU *is* the JTAG master.** Replace `modules/drivers/` +with a GPIO bit-bang (or SPI-assisted: MOSI=TDI, MISO=TDO, SCK=TCK, +TMS bit-banged between scans → multi-MHz) driver behind +`drv_TX_TMS` / `drv_TXRX_DATA`. Everything above that — `jtag_core`, the +`bscan_set_ir`/`bscan_shift_dr` primitives, the `fpga_target` registry, +the SVF player and the flash logic — is portable C, reused as-is. + +**Dropped / replaced on the MCU:** +- readline REPL → command interface over WiFi (HTTP/telnet) or USB-CDC; +- `os_interface` (host fs/net) → Mbed OS filesystem + network (real + implementations, little rework); +- runtime BSDL parsing → pre-baked tables (the registry already does + this); `bsdl_parser` can be left out; +- `libftd2xx` / Digilent dlopen → gone (the MCU is the probe). + +**The one real rework: stream, don't `malloc`.** `bscan_shift_dr` +currently allocates the whole shift buffer (`malloc(nbits)` — ~19 MB for +a Xilinx proxy). On an MCU the payload (proxy `.bit`, flash image, SVF) +lives on **SD or a USB stick** and must be **shifted in chunks**; WiFi +fetches the file / triggers the job. With an SD/USB source this is +natural (read a block, shift, repeat). 1 MB RAM relaxes buffer sizes but +does not remove the need (a 32 MB image never fits). + +**Ideal fit: an SVF player streamed from SD** — a classic embedded +programmer design, and it matches the small-Lattice/IGLOO2-in-a-PSU use +case (small config, modest `SDR` vectors). Big Xilinx external-flash +images (huge SVF vectors) stay on the host or a large MCU. + +**Hardware notes:** +- the GIGA R1 has **no onboard microSD** — add it via the GIGA Display + Shield, an SPI SD module, or its USB-A host port (USB mass storage); +- 3.3 V GPIO → **level-shift** for 1.8 V JTAG targets (e.g. KCU105), + same as on the host side. + ## External references - **BSCAN proxy bitstreams**: `quartiq/bscan_spi_bitstreams` (MIT).