doc: refresh README/tutorial/CLAUDE for profiles, clock, SVF
Bring the docs up to date and keep each in its lane: - README (overview): both programming paths (Xilinx proxy flash + SVF), probe profiles, neutral JTAG clock + per-device cap, runtime YAML registry, IGLOO2 bundled; run-from-repo-root fixed - tutorial (user view): probe profiles + jtag_close, the prog tag, a JTAG-clock section, a new "Programming via SVF" section, prog/max_tck in the add-a-target table, troubleshooting rows - CLAUDE.md (design): architecture tree lists the project modules + YAML data files; roadmap gains phases 5 (probes/JTAG-link) and 6 (SVF) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
74
README.md
74
README.md
@@ -1,10 +1,14 @@
|
||||
# bs_explorer — Boundary Scan Explorer
|
||||
|
||||
Command-line tool to explore a JTAG chain, drive an FPGA's pins through
|
||||
boundary scan (BSDL), and program the SPI configuration flash attached
|
||||
to an FPGA (Xilinx and others) over JTAG — fast, via a BSCAN proxy
|
||||
bitstream loaded into the fabric (~100 KB/s), or slowly via EXTEST pin
|
||||
bit-bang for one-shot checks.
|
||||
boundary scan (BSDL), and **program** parts over JTAG, from a host with
|
||||
an FTDI / Digilent / J-Link probe. Two programming paths:
|
||||
|
||||
- **Xilinx external SPI configuration flash** — fast, via a BSCAN proxy
|
||||
bitstream loaded into the fabric (~100 KB/s), or slowly via EXTEST pin
|
||||
bit-bang for one-shot checks;
|
||||
- **everything else** (Lattice, Microsemi, CPLDs, …) — by playing a
|
||||
vendor-exported **SVF** file (`svf_play`), one near-universal backend.
|
||||
|
||||
Based on the [jtag-boundary-scanner](https://github.com/viveris/jtag-boundary-scanner)
|
||||
library by Viveris (LGPL).
|
||||
@@ -14,15 +18,17 @@ 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, incl. slow SPI bit-bang: OK
|
||||
- Per-FPGA registry (IDCODE → BSDL, IR opcodes, proxy, caveats): OK
|
||||
- FPGA registry (runtime YAML: IDCODE → BSDL, IR opcodes, proxy, caveats, programming method): OK
|
||||
- Probe-config profiles (`probes.yaml`) + driver-neutral JTAG clock with per-device cap: OK
|
||||
- BSCAN proxy SPI bridge (load proxy bitstream, talk SPI via `USER1`): OK
|
||||
- SPI flash detect / read / erase / program / verify: OK (~100 KB/s via the proxy)
|
||||
- SVF player (`svf_play`) — program any device from a vendor-exported SVF: OK (single-device subset)
|
||||
|
||||
Bundled BSDLs: Xilinx Kintex UltraScale+ KU15P
|
||||
(`bsdl_files/xcku15p_ffve1517.bsd`) and Kintex UltraScale KU040
|
||||
(`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).
|
||||
(`xcku15p_ffve1517.bsd`), Kintex UltraScale KU040 (`xcku040_ffva1156.bsd`),
|
||||
and Microsemi IGLOO2 M2GL010T (`m2gl010t-fg484.bsd`). Add more by dropping
|
||||
`.bsd` files in `bsdl_files/` plus an entry in `fpga_registry.yaml` (see
|
||||
[`doc/tutorial.md`](doc/tutorial.md) for adding a target).
|
||||
|
||||
## Dependencies
|
||||
|
||||
@@ -56,15 +62,23 @@ cmake -DBS_ENABLE_DIGILENT=OFF ..
|
||||
|
||||
## Run
|
||||
|
||||
Run from the repository root so the runtime data files are found — they
|
||||
are looked up relative to the current directory:
|
||||
|
||||
```sh
|
||||
cd build
|
||||
./bs/bs
|
||||
./build/bs/bs
|
||||
```
|
||||
|
||||
At startup, `bs_explorer` looks for a `config.script` file in the
|
||||
current directory to override default settings (FTDI clock, TRST/SRST
|
||||
pin mapping, etc.). See `modules/config/config.script` for the full
|
||||
list of variables.
|
||||
`bs_explorer` reads, when present in that directory:
|
||||
|
||||
- `config.script` — overrides built-in probe variables (FTDI clock,
|
||||
TRST/SRST pin mapping, …); see `modules/config/config.script` for the
|
||||
full list. Loaded at startup.
|
||||
- `probes.yaml` — probe-config profiles, applied with
|
||||
`jtag_open <idx> <profile>` (`$BS_PROBES` overrides the path).
|
||||
- `fpga_registry.yaml` — the FPGA target registry
|
||||
(`$BS_FPGA_REGISTRY` overrides the path).
|
||||
- `bsdl_files/`, `bscan_proxies/` — BSDLs and proxy bitstreams.
|
||||
|
||||
## REPL
|
||||
|
||||
@@ -76,31 +90,39 @@ list of variables.
|
||||
|
||||
## Typical flow
|
||||
|
||||
**Xilinx external SPI flash — via the BSCAN proxy:**
|
||||
|
||||
```sh
|
||||
# 1. List probes, open one by its index (the [N] in the list)
|
||||
# 1. List probes, open one by its index ([N]). A probe that needs tweaks
|
||||
# (e.g. an embedded FlashPro) takes a profile from probes.yaml:
|
||||
bs_explorer> jtag_probes
|
||||
[0] 0x00000000 <probe description>
|
||||
bs_explorer> jtag_open 0 # or the raw 0x id shown next to it
|
||||
bs_explorer> jtag_profiles # available profiles
|
||||
bs_explorer> jtag_open 0 # or: jtag_open 0 <profile>
|
||||
|
||||
# 2. Scan the chain and auto-load matching BSDLs
|
||||
bs_explorer> jtag_autoinit
|
||||
bs_explorer> jtag_autoinit # fpga_info then shows the prog method
|
||||
|
||||
# 3. Load the BSCAN proxy into the fabric (fast SPI bridge)
|
||||
bs_explorer> bscan_load_bitstream 0 bscan_proxies/bscan_spi_xcku040.bit
|
||||
|
||||
# 4. Talk to the SPI flash through the proxy
|
||||
bs_explorer> flash_detect 0 # JEDEC ID -> chip name / size
|
||||
bs_explorer> flash_read 0 0x0 256 # hex dump
|
||||
bs_explorer> flash_erase 0 0x10000 4096
|
||||
bs_explorer> flash_write 0 0x10000 image.bin
|
||||
bs_explorer> flash_verify 0 0x10000 image.bin
|
||||
```
|
||||
|
||||
**Anything else (Lattice, Microsemi, …) — play a vendor-exported SVF:**
|
||||
|
||||
```sh
|
||||
bs_explorer> jtag_open 0 <profile> # e.g. flashpro for a Microsemi kit
|
||||
bs_explorer> jtag_autoinit # identify; prog method should be 'svf'
|
||||
bs_explorer> svf_play design.svf # exported from Libero / Diamond / Radiant
|
||||
```
|
||||
|
||||
The slow EXTEST path (bit-bang SPI on boundary-scan pins, `jtag_mode 0
|
||||
EXTEST` + `jtag_spi_*`) is only useful for one-shot checks — see the
|
||||
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).
|
||||
EXTEST` + `jtag_spi_*`) is only useful for one-shot checks. A minimal
|
||||
example script is in `scripts/example_script.txt`; the full walkthrough
|
||||
lives in [`doc/tutorial.md`](doc/tutorial.md).
|
||||
|
||||
## Main commands
|
||||
|
||||
@@ -159,6 +181,8 @@ modules/
|
||||
├── fpga/ Registry loader (parses fpga_registry.yaml at runtime)
|
||||
├── bscan/ JTAG TAP primitives + BSCAN proxy (bitstream, SPI-over-USER1)
|
||||
├── spi_flash/ SPI NOR chip database + read/erase/program/verify
|
||||
├── svf/ SVF player (program from a vendor-exported SVF)
|
||||
├── probes/ Probe-config profiles loader (probes.yaml)
|
||||
├── script/ Script engine
|
||||
├── config/ Built-in config.script
|
||||
├── os_interface/ Portable fs/network wrappers
|
||||
|
||||
Reference in New Issue
Block a user