doc: update README for the proxy flash path and current state

Reflect what now works: per-FPGA registry, BSCAN proxy SPI bridge, and
flash detect/read/erase/program/verify (~100 KB/s). Switch the typical
flow to the proxy path, add the fpga/bscan/flash command rows, note
persistent history, the KU040 BSDL, the new modules + bscan_proxies/ in
the layout, and the quartiq MIT proxies in the license section.

README.md

@@ -1,9 +1,10 @@
 # bs_explorer — Boundary Scan Explorer
 
 Command-line tool to explore a JTAG chain, drive an FPGA's pins through
-boundary scan (BSDL), and — eventually — program SPI memories attached
+boundary scan (BSDL), and program the SPI configuration flash attached
-to the FPGA (Xilinx and others) by bit-banging SPI on I/O pins placed
+to an FPGA (Xilinx and others) over JTAG — fast, via a BSCAN proxy
-in EXTEST.
+bitstream loaded into the fabric (~100 KB/s), or slowly via EXTEST pin
+bit-bang for one-shot checks.
 
 Based on the [jtag-boundary-scanner](https://github.com/viveris/jtag-boundary-scanner)
 library by Viveris (LGPL).
@@ -12,14 +13,16 @@ library by Viveris (LGPL).
 
 - JTAG chain detection through FTDI / J-Link / Linux GPIO / Digilent SMT2 probes: OK
 - Automatic BSDL loading by IDCODE: OK
-- Pin control in SAMPLE / EXTEST: OK
+- Pin control in SAMPLE / EXTEST, incl. slow SPI bit-bang: OK
-- SPI bit-bang on 4 FPGA pins (MOSI/MISO/CS/CLK): OK (low-level primitive)
+- Per-FPGA registry (IDCODE → BSDL, IR opcodes, proxy, caveats): OK
-- SPI flash programming (JEDEC detect, erase, page program, verify): **planned**
+- BSCAN proxy SPI bridge (load proxy bitstream, talk SPI via `USER1`): OK
-- Multi-FPGA abstraction (per-target pin → flash mapping): **planned**
+- SPI flash detect / read / erase / program / verify: OK (~100 KB/s via the proxy)
 
-Only one BSDL is bundled so far: Xilinx Kintex UltraScale+ KU15P
+Bundled BSDLs: Xilinx Kintex UltraScale+ KU15P
-(`bsdl_files/xcku15p_ffve1517.bsd`). Add more by dropping `.bsd` files
+(`bsdl_files/xcku15p_ffve1517.bsd`) and Kintex UltraScale KU040
-in `bsdl_files/`.
+(`bsdl_files/xcku040_ffva1156.bsd`). Add more by dropping `.bsd` files
+in `bsdl_files/` (see [`doc/tutorial.md`](doc/tutorial.md) for adding a
+target).
 
 ## Dependencies
 
@@ -64,38 +67,38 @@ list of variables.
 ## REPL
 
 - `<Tab>` completes command names.
-- History handled by GNU readline (up/down arrows, Ctrl-R, …).
+- Persistent history (GNU readline) in `~/.bs_explorer_history`:
+  up/down arrows and Ctrl-R recall commands across sessions.
 - `help` or `?` lists commands; `help <cmd>` shows details.
 - `exit`, `quit`, or Ctrl-D to leave.
 
 ## Typical flow
 
 ```sh
-# 1. List probes, then open one by its index (the [N] in the list)
+# 1. List probes, open one by its index (the [N] in the list)
 bs_explorer> jtag_probes
   [0]  0x00000000  <probe description>
 bs_explorer> jtag_open 0                 # or the raw 0x id shown next to it
 
-# 2. Scan the chain and auto-load BSDL files
+# 2. Scan the chain and auto-load matching BSDLs
 bs_explorer> jtag_autoinit
 
-# 3. Switch device 0 to EXTEST (direct pin control)
+# 3. Load the BSCAN proxy into the fabric (fast SPI bridge)
-bs_explorer> jtag_mode 0 EXTEST
+bs_explorer> bscan_load_bitstream 0 bscan_proxies/bscan_spi_xcku040.bit
 
-# 4. Wire the 4 SPI pins onto the FPGA's BSDL pins
+# 4. Talk to the SPI flash through the proxy
-#    (exact names depend on the loaded BSDL)
+bs_explorer> flash_detect 0              # JEDEC ID -> chip name / size
-bs_explorer> jtag_spi_cs   0 <PIN_CS>   0
+bs_explorer> flash_read   0 0x0 256      # hex dump
-bs_explorer> jtag_spi_clk  0 <PIN_CLK>  0
+bs_explorer> flash_erase  0 0x10000 4096
-bs_explorer> jtag_spi_mosi 0 <PIN_MOSI> 0
+bs_explorer> flash_write  0 0x10000 image.bin
-bs_explorer> jtag_spi_miso 0 <PIN_MISO> 0
+bs_explorer> flash_verify 0 0x10000 image.bin
-
-# 5. Read the flash JEDEC ID (0x9F + 3 dummies)
-bs_explorer> jtag_spi_xfer 9F000000
 ```
 
-A minimal example script is provided in `scripts/example_script.txt`.
+The slow EXTEST path (bit-bang SPI on boundary-scan pins, `jtag_mode 0
-A full step-by-step walkthrough (probe detection → JEDEC ID → flashing
+EXTEST` + `jtag_spi_*`) is only useful for one-shot checks — see the
-via BSCAN proxy) lives in [`doc/tutorial.md`](doc/tutorial.md).
+tutorial. A minimal example script is in `scripts/example_script.txt`;
+the full walkthrough (probe → proxy → flash) lives in
+[`doc/tutorial.md`](doc/tutorial.md).
 
 ## Main commands
 
@@ -104,7 +107,10 @@ via BSCAN proxy) lives in [`doc/tutorial.md`](doc/tutorial.md).
 | Script control | `set`, `print`, `print_env_var`, `if`, `goto`, `call`, `return`, `rand`, `init_array`, `system`, `pause` |
 | Probe / chain | `jtag_probes`, `jtag_open`, `jtag_scan`, `jtag_autoinit`, `jtag_ndev`, `jtag_devices` |
 | BSDL / pins | `jtag_bsdl`, `jtag_pins`, `jtag_mode`, `jtag_pin_dir`, `jtag_pin_set`, `jtag_pin_get`, `jtag_push_pop` |
-| I²C / MDIO / SPI over BS pins | `jtag_i2c_scl`, `jtag_i2c_sda`, `jtag_i2c_rd`, `jtag_i2c_wr`, `jtag_mdio_mdc`, `jtag_mdio_io`, `jtag_mdio_rd`, `jtag_mdio_wr`, `jtag_spi_cs/mosi/miso/clk`, `jtag_spi_xfer` |
+| I²C / MDIO / SPI over BS pins (EXTEST) | `jtag_i2c_scl`, `jtag_i2c_sda`, `jtag_i2c_rd`, `jtag_i2c_wr`, `jtag_mdio_mdc`, `jtag_mdio_io`, `jtag_mdio_rd`, `jtag_mdio_wr`, `jtag_spi_cs/mosi/miso/clk`, `jtag_spi_xfer` |
+| FPGA registry | `fpga_list`, `fpga_info` |
+| BSCAN proxy | `bscan_load_bitstream`, `bscan_jedec`, `bscan_set_ir`, `bscan_shift_dr` |
+| SPI flash (via proxy) | `flash_detect`, `flash_read`, `flash_erase`, `flash_write`, `flash_verify` |
 | Misc | `help`, `?`, `version`, `exit` |
 
 Use `help <command>` for per-command help.
@@ -126,11 +132,13 @@ Use `help <command>` for per-command help.
 
 On 7-Series / UltraScale / UltraScale+, `CCLK` is not a regular I/O pin
 and goes through the `STARTUPE3` primitive, so it cannot be driven
-directly in EXTEST. Known workarounds:
+directly in EXTEST — the slow EXTEST SPI path therefore can't clock the
-- use the private `ISC_DISABLE` instruction;
+flash on these parts.
-- route the SPI clock through another user pin of the FPGA.
 
-To be handled when the FPGA abstraction layer is added.
+The **BSCAN proxy sidesteps this entirely**: it drives `CCLK` from the
+fabric internally, so flashing runs at full speed. Parts affected are
+flagged with the `CCLK_VIA_STARTUP` caveat in the registry (`fpga_info`
+shows it).
 
 ## Repository layout
 
@@ -139,13 +147,17 @@ bs/                  Application (readline REPL)
 modules/
 ├── jtag_core/       TAP state machine, IR/DR shifts
 ├── bsdl_parser/     .bsd loader
-├── bus_over_jtag/   SPI / I²C / MDIO / parallel mem bit-bang
+├── bus_over_jtag/   SPI / I²C / MDIO / parallel mem bit-bang (EXTEST)
 ├── drivers/         FTDI, J-Link, Linux GPIO, LPT, Digilent (optional)
-├── script/          Script engine (40+ commands)
+├── fpga/            Per-target registry (IDCODE, BSDL, IR opcodes, caveats)
+├── bscan_spi/       BSCAN proxy loader + fast SPI-over-USER1 bridge
+├── spi_flash/       SPI NOR chip database + read/erase/program/verify
+├── script/          Script engine
 ├── config/          Built-in config.script
 ├── os_interface/    Portable fs/network wrappers
 └── natsort/         Natural-order pin-name sorting
 bsdl_files/          BSDL files for target FPGAs
+bscan_proxies/       BSCAN proxy bitstreams (MIT, from quartiq)
 scripts/             Example scripts
 doc/                 Tutorial and longer-form docs
 libs/libftd2xx/      Vendored FTDI SDK
@@ -154,4 +166,6 @@ libs/libftd2xx/      Vendored FTDI SDK
 ## License
 
 `modules/jtag_core/` and the original Viveris files are under LGPL 2.1.
-See `LICENSE` and `modules/jtag_core/COPYING.LESSER`.
+See `LICENSE` and `modules/jtag_core/COPYING.LESSER`. The proxy
+bitstreams in `bscan_proxies/` are from quartiq (MIT) — see
+`bscan_proxies/LICENSE.quartiq`.