From d1bdce91dc7d590bf57c7a55662cc5ac3c5e2d15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois?= Date: Sun, 24 May 2026 15:03:25 +0200 Subject: [PATCH] restructure: code+libs under src/, runtime resources under data/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Separate the two concerns the repo root was mixing: - src/ — bs/, modules/, libs/ (code + vendored libs) - data/ — fpga_registry.yaml, probes.yaml, bsdl_files/, bscan_proxies/, scripts/ (everything the tool reads at runtime, CWD-relative) - doc/ — kept at the root CMake: repoint DIR_MODULES/DIR_LIBS and add_subdirectory at src/; emit the binary at the build/ root (build/bs) via CMAKE_RUNTIME_OUTPUT_DIRECTORY instead of the nested build/src/bs/. The jtag_core ../../libs path still resolves since modules and libs moved together. Runtime default paths now point under data/ (fpga.c, probes.c, script.c bsdl_files lookup, init.c config.script). Docs (README/tutorial/CLAUDE) updated for the new layout, src/ module paths, and ./build/bs. Validated on the IGLOO2/FlashPro: profiles, autoinit, and svf_play all work run from the repo root. Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 103 +++++++++--------- CMakeLists.txt | 12 +- README.md | 84 +++++++------- .../bscan_proxies}/LICENSE.quartiq | 0 .../bscan_proxies}/README.md | 2 +- .../bscan_proxies}/bscan_spi_xcku040.bit | Bin .../bsdl_files}/m2gl010t-fg484.bsd | 0 .../bsdl_files}/xcku040_ffva1156.bsd | 0 .../bsdl_files}/xcku15p_ffve1517.bsd | 0 fpga_registry.yaml => data/fpga_registry.yaml | 0 probes.yaml => data/probes.yaml | 0 {scripts => data/scripts}/example_script.txt | 0 doc/tutorial.md | 54 ++++----- {bs => src/bs}/CMakeLists.txt | 0 {bs => src/bs}/init.c | 4 +- {bs => src/bs}/init.h | 0 {bs => src/bs}/main.c | 0 {libs => src/libs}/libftd2xx/WinTypes.h | 0 {libs => src/libs}/libftd2xx/ftd2xx.h | 0 {libs => src/libs}/libftd2xx/libftd2xx.a | Bin {modules => src/modules}/bscan/CMakeLists.txt | 0 {modules => src/modules}/bscan/bscan.c | 0 {modules => src/modules}/bscan/bscan.h | 0 .../modules}/bsdl_parser/CMakeLists.txt | 0 .../modules}/bsdl_parser/bsdl_loader.c | 0 .../modules}/bsdl_parser/bsdl_loader.h | 0 .../modules}/bsdl_parser/bsdl_strings.c | 0 .../modules}/bsdl_parser/bsdl_strings.h | 0 .../modules}/bus_over_jtag/CMakeLists.txt | 0 .../modules}/bus_over_jtag/i2c_over_jtag.c | 0 .../modules}/bus_over_jtag/mdio_over_jtag.c | 0 .../modules}/bus_over_jtag/memory_over_jtag.c | 0 .../modules}/bus_over_jtag/spi_over_jtag.c | 0 {modules => src/modules}/config/bs_defines.h | 0 {modules => src/modules}/config/config.script | 0 .../modules}/config/config_script.h | 0 {modules => src/modules}/config/version.h | 0 .../modules}/drivers/CMakeLists.txt | 0 .../drivers/digilent_jtag/digilent_jtag_drv.c | 0 .../drivers/digilent_jtag/digilent_jtag_drv.h | 0 .../modules}/drivers/drivers_list.c | 0 .../modules}/drivers/drivers_list.h | 0 {modules => src/modules}/drivers/drv_loader.c | 0 {modules => src/modules}/drivers/drv_loader.h | 0 .../drivers/ftdi_jtag/ftdi_jtag_drv.c | 0 .../drivers/ftdi_jtag/ftdi_jtag_drv.h | 0 .../drivers/jlink_jtag/jlink_jtag_drv.c | 0 .../drivers/jlink_jtag/jlink_jtag_drv.h | 0 .../linux_gpio_jtag/linux_gpio_jtag_drv.c | 0 .../linux_gpio_jtag/linux_gpio_jtag_drv.h | 0 .../modules}/drivers/lpt_jtag/lpt_jtag_drv.c | 0 .../modules}/drivers/lpt_jtag/lpt_jtag_drv.h | 0 {modules => src/modules}/fpga/CMakeLists.txt | 0 {modules => src/modules}/fpga/fpga.c | 2 +- {modules => src/modules}/fpga/fpga.h | 0 .../modules}/jtag_core/CMakeLists.txt | 0 .../modules}/jtag_core/COPYING.LESSER | 0 {modules => src/modules}/jtag_core/dbg_logs.c | 0 {modules => src/modules}/jtag_core/dbg_logs.h | 0 .../modules}/jtag_core/jtag_core.c | 0 .../modules}/jtag_core/jtag_core.h | 0 .../modules}/natsort/CMakeLists.txt | 0 {modules => src/modules}/natsort/strnatcmp.c | 0 {modules => src/modules}/natsort/strnatcmp.h | 0 .../modules}/os_interface/CMakeLists.txt | 0 {modules => src/modules}/os_interface/fs.c | 0 .../modules}/os_interface/network.c | 0 .../modules}/os_interface/network.h | 0 .../modules}/os_interface/os_interface.c | 0 .../modules}/os_interface/os_interface.h | 0 .../modules}/probes/CMakeLists.txt | 0 {modules => src/modules}/probes/probes.c | 2 +- {modules => src/modules}/probes/probes.h | 0 .../modules}/script/CMakeLists.txt | 0 {modules => src/modules}/script/env.c | 0 {modules => src/modules}/script/env.h | 0 {modules => src/modules}/script/script.c | 4 +- {modules => src/modules}/script/script.h | 0 .../modules}/spi_flash/CMakeLists.txt | 0 .../modules}/spi_flash/spi_flash.c | 0 .../modules}/spi_flash/spi_flash.h | 0 {modules => src/modules}/svf/CMakeLists.txt | 0 {modules => src/modules}/svf/svf.c | 0 {modules => src/modules}/svf/svf.h | 0 84 files changed, 138 insertions(+), 129 deletions(-) rename {bscan_proxies => data/bscan_proxies}/LICENSE.quartiq (100%) rename {bscan_proxies => data/bscan_proxies}/README.md (90%) rename {bscan_proxies => data/bscan_proxies}/bscan_spi_xcku040.bit (100%) rename {bsdl_files => data/bsdl_files}/m2gl010t-fg484.bsd (100%) rename {bsdl_files => data/bsdl_files}/xcku040_ffva1156.bsd (100%) rename {bsdl_files => data/bsdl_files}/xcku15p_ffve1517.bsd (100%) rename fpga_registry.yaml => data/fpga_registry.yaml (100%) rename probes.yaml => data/probes.yaml (100%) rename {scripts => data/scripts}/example_script.txt (100%) rename {bs => src/bs}/CMakeLists.txt (100%) rename {bs => src/bs}/init.c (95%) rename {bs => src/bs}/init.h (100%) rename {bs => src/bs}/main.c (100%) rename {libs => src/libs}/libftd2xx/WinTypes.h (100%) rename {libs => src/libs}/libftd2xx/ftd2xx.h (100%) rename {libs => src/libs}/libftd2xx/libftd2xx.a (100%) rename {modules => src/modules}/bscan/CMakeLists.txt (100%) rename {modules => src/modules}/bscan/bscan.c (100%) rename {modules => src/modules}/bscan/bscan.h (100%) rename {modules => src/modules}/bsdl_parser/CMakeLists.txt (100%) rename {modules => src/modules}/bsdl_parser/bsdl_loader.c (100%) rename {modules => src/modules}/bsdl_parser/bsdl_loader.h (100%) rename {modules => src/modules}/bsdl_parser/bsdl_strings.c (100%) rename {modules => src/modules}/bsdl_parser/bsdl_strings.h (100%) rename {modules => src/modules}/bus_over_jtag/CMakeLists.txt (100%) rename {modules => src/modules}/bus_over_jtag/i2c_over_jtag.c (100%) rename {modules => src/modules}/bus_over_jtag/mdio_over_jtag.c (100%) rename {modules => src/modules}/bus_over_jtag/memory_over_jtag.c (100%) rename {modules => src/modules}/bus_over_jtag/spi_over_jtag.c (100%) rename {modules => src/modules}/config/bs_defines.h (100%) rename {modules => src/modules}/config/config.script (100%) rename {modules => src/modules}/config/config_script.h (100%) rename {modules => src/modules}/config/version.h (100%) rename {modules => src/modules}/drivers/CMakeLists.txt (100%) rename {modules => src/modules}/drivers/digilent_jtag/digilent_jtag_drv.c (100%) rename {modules => src/modules}/drivers/digilent_jtag/digilent_jtag_drv.h (100%) rename {modules => src/modules}/drivers/drivers_list.c (100%) rename {modules => src/modules}/drivers/drivers_list.h (100%) rename {modules => src/modules}/drivers/drv_loader.c (100%) rename {modules => src/modules}/drivers/drv_loader.h (100%) rename {modules => src/modules}/drivers/ftdi_jtag/ftdi_jtag_drv.c (100%) rename {modules => src/modules}/drivers/ftdi_jtag/ftdi_jtag_drv.h (100%) rename {modules => src/modules}/drivers/jlink_jtag/jlink_jtag_drv.c (100%) rename {modules => src/modules}/drivers/jlink_jtag/jlink_jtag_drv.h (100%) rename {modules => src/modules}/drivers/linux_gpio_jtag/linux_gpio_jtag_drv.c (100%) rename {modules => src/modules}/drivers/linux_gpio_jtag/linux_gpio_jtag_drv.h (100%) rename {modules => src/modules}/drivers/lpt_jtag/lpt_jtag_drv.c (100%) rename {modules => src/modules}/drivers/lpt_jtag/lpt_jtag_drv.h (100%) rename {modules => src/modules}/fpga/CMakeLists.txt (100%) rename {modules => src/modules}/fpga/fpga.c (99%) rename {modules => src/modules}/fpga/fpga.h (100%) rename {modules => src/modules}/jtag_core/CMakeLists.txt (100%) rename {modules => src/modules}/jtag_core/COPYING.LESSER (100%) rename {modules => src/modules}/jtag_core/dbg_logs.c (100%) rename {modules => src/modules}/jtag_core/dbg_logs.h (100%) rename {modules => src/modules}/jtag_core/jtag_core.c (100%) rename {modules => src/modules}/jtag_core/jtag_core.h (100%) rename {modules => src/modules}/natsort/CMakeLists.txt (100%) rename {modules => src/modules}/natsort/strnatcmp.c (100%) rename {modules => src/modules}/natsort/strnatcmp.h (100%) rename {modules => src/modules}/os_interface/CMakeLists.txt (100%) rename {modules => src/modules}/os_interface/fs.c (100%) rename {modules => src/modules}/os_interface/network.c (100%) rename {modules => src/modules}/os_interface/network.h (100%) rename {modules => src/modules}/os_interface/os_interface.c (100%) rename {modules => src/modules}/os_interface/os_interface.h (100%) rename {modules => src/modules}/probes/CMakeLists.txt (100%) rename {modules => src/modules}/probes/probes.c (99%) rename {modules => src/modules}/probes/probes.h (100%) rename {modules => src/modules}/script/CMakeLists.txt (100%) rename {modules => src/modules}/script/env.c (100%) rename {modules => src/modules}/script/env.h (100%) rename {modules => src/modules}/script/script.c (96%) rename {modules => src/modules}/script/script.h (100%) rename {modules => src/modules}/spi_flash/CMakeLists.txt (100%) rename {modules => src/modules}/spi_flash/spi_flash.c (100%) rename {modules => src/modules}/spi_flash/spi_flash.h (100%) rename {modules => src/modules}/svf/CMakeLists.txt (100%) rename {modules => src/modules}/svf/svf.c (100%) rename {modules => src/modules}/svf/svf.h (100%) diff --git a/CLAUDE.md b/CLAUDE.md index a50e03c..36e9aae 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -17,55 +17,58 @@ on a host with an FTDI/Digilent/J-Link probe — Xilinx external SPI configuration flash via a BSCAN proxy (started with the KU15P), and other families (Lattice, Microsemi, …) by playing a vendor-exported SVF. -The Viveris library itself lives unchanged in `modules/`. Everything -new is in `bs/` (the REPL) and the project modules (`fpga/`, `bscan/`, +The Viveris library itself lives unchanged in `src/modules/`. Everything +new is in `src/bs/` (the REPL) and the project modules (`fpga/`, `bscan/`, `spi_flash/`, `svf/`, `probes/`) sitting alongside the Viveris ones. ## Architecture ``` -bs/ Application (readline REPL, no business logic) -modules/ - — Viveris's library (LGPL, unchanged) — -├── jtag_core/ TAP state machine, IR/DR shifts -├── bsdl_parser/ .bsd loader -├── bus_over_jtag/ SPI/I²C/MDIO/parallel mem bit-bang over EXTEST -├── drivers/ FTDI, J-Link, Linux GPIO, LPT, Digilent (optional, dlopen) -├── script/ Script engine (the real UI) -├── config/ Built-in config.script -├── os_interface/ Portable fs/network wrappers -├── natsort/ Natural pin-name sorting - — new (this project) — -├── fpga/ Registry loader (parses fpga_registry.yaml, libyaml) -├── bscan/ JTAG TAP primitives (set_ir/shift_ir/shift_dr/tap_reset/ -│ idle_cycles) + BSCAN proxy (bitstream load, SPI-over-USER1) -├── spi_flash/ SPI NOR chip DB + read/erase/program/verify over a callback -├── svf/ SVF player (svf_play): SIR/SDR/RUNTEST/STATE, masked compare -└── probes/ Probe-config profiles loader (parses probes.yaml, libyaml) -fpga_registry.yaml FPGA registry (IDCODE → BSDL, IR opcodes, proxy, caveats, prog, max_tck) -probes.yaml Probe-config profiles (defaults + per-probe overrides) -bsdl_files/ BSDL files for target FPGAs -bscan_proxies/ BSCAN proxy bitstreams (MIT, from quartiq) -scripts/ Example scripts -doc/ Tutorial and longer-form docs (doc/tutorial.md is the end-to-end walkthrough) -libs/libftd2xx/ Vendored FTDI SDK +src/ — code + libs — +├── bs/ Application (readline REPL, no business logic) +├── libs/libftd2xx/ Vendored FTDI SDK +└── modules/ + — Viveris's library (LGPL, unchanged) — + ├── jtag_core/ TAP state machine, IR/DR shifts + ├── bsdl_parser/ .bsd loader + ├── bus_over_jtag/ SPI/I²C/MDIO/parallel mem bit-bang over EXTEST + ├── drivers/ FTDI, J-Link, Linux GPIO, LPT, Digilent (optional, dlopen) + ├── script/ Script engine (the real UI) + ├── config/ Built-in config.script + ├── os_interface/ Portable fs/network wrappers + └── natsort/ Natural pin-name sorting + — new (this project) — + ├── fpga/ Registry loader (parses data/fpga_registry.yaml, libyaml) + ├── bscan/ JTAG TAP primitives (set_ir/shift_ir/shift_dr/tap_reset/ + │ idle_cycles) + BSCAN proxy (bitstream load, SPI-over-USER1) + ├── spi_flash/ SPI NOR chip DB + read/erase/program/verify over a callback + ├── svf/ SVF player (svf_play): SIR/SDR/RUNTEST/STATE, masked compare + └── probes/ Probe-config profiles loader (parses data/probes.yaml, libyaml) +data/ — runtime resources, looked up CWD-relative — +├── fpga_registry.yaml FPGA registry (IDCODE → BSDL, IR opcodes, proxy, caveats, prog, max_tck) +├── probes.yaml Probe-config profiles (defaults + per-probe overrides) +├── bsdl_files/ BSDL files for target FPGAs +├── bscan_proxies/ BSCAN proxy bitstreams (MIT, from quartiq) +└── scripts/ Example scripts +doc/ Tutorial and longer-form docs (doc/tutorial.md is the end-to-end walkthrough) +CMakeLists.txt Top-level build (binary lands at build/bs) ``` User interacts with the project through the script engine commands (`jtag_*`, `set`, `if`, …), exposed via the REPL or piped script files. Adding a feature usually means adding a new script command in -`modules/script/script.c` and the supporting C in a new module. +`src/modules/script/script.c` and the supporting C in a new module. ## Roadmap | Phase | Module | Status | Summary | |-------|--------|--------|---------| | 1 | `bs/` cleanup, REPL polish, README | **done** (commit `7cb3627`) | Fix format-strings, delete dead code, tab-completion, banner | -| 2 | `fpga/` | **done** (commit `545fe09`) | Per-target descriptor (IDCODE, BSDL, IR codes, proxy path, caveats). Now a **runtime YAML** registry (`fpga_registry.yaml`, libyaml), later gaining `prog` method + `max_tck_khz`. | +| 2 | `fpga/` | **done** (commit `545fe09`) | Per-target descriptor (IDCODE, BSDL, IR codes, proxy path, caveats). Now a **runtime YAML** registry (`data/fpga_registry.yaml`, libyaml), later gaining `prog` method + `max_tck_khz`. | | 2.5 | `bscan/` | **done** (commit `dec0d14`) | Load BSCAN proxy bitstream via `CFG_IN`, expose fast `bscan_spi_xfer()` via `USER1`. Required for realistic flashing speeds. | | 3 | `spi_flash/` | **done** (commit `c4afe87`) | Chip DB (JEDEC ID → page/sector/cmd set) + generic `read/erase/program/verify` over an `xfer` callback. detect+read validated on KCU105; erase/program implemented but not yet hardware-tested. | | 4 | script commands | **done** (commit `d6f843e`) | `flash_detect`, `flash_read` (+file), `flash_erase`, `flash_write`, `flash_verify`. Full set validated on KCU105 (save/erase/write-random/verify/restore round-trip). ~100 KB/s write once the proxy is loaded. | -| 5 | `probes/` + JTAG-link | **done** | `probes.yaml` probe-config profiles (`jtag_open `, `jtag_profiles`, `jtag_close`); driver-neutral `JTAG_TCK_FREQ_KHZ`/`JTAG_RTCK`; device `max_tck_khz` clock cap resolved at `jtag_autoinit`; `prog` method tag. See the config-strategy design note. Validated on the IGLOO2 (FlashPro). | +| 5 | `probes/` + JTAG-link | **done** | `data/probes.yaml` probe-config profiles (`jtag_open `, `jtag_profiles`, `jtag_close`); driver-neutral `JTAG_TCK_FREQ_KHZ`/`JTAG_RTCK`; device `max_tck_khz` clock cap resolved at `jtag_autoinit`; `prog` method tag. See the config-strategy design note. Validated on the IGLOO2 (FlashPro). | | 6 | `svf/` | **done** (subset, commit `c77d86e`) | SVF player + `svf_play`: SIR/SDR with masked TDO compare, RUNTEST, STATE — single-device. Validated on the IGLOO2 IDCODE; a real Libero SVF and a generic `program` dispatch off the `prog` tag are still TODO. | Move forward phase by phase: validate one with the user before starting @@ -103,12 +106,12 @@ derived from the BSDL alone: - `proxy_bitstream_path` — path to the BSCAN proxy `.bit` for this part - `caveats` — flags for known hardware gotchas (e.g. CCLK via STARTUPE3) -Registry is a **runtime YAML file** (`fpga_registry.yaml` at the repo +Registry is a **runtime YAML file** (`data/fpga_registry.yaml` at the repo root), parsed via libyaml — no longer a compile-time array. It is looked -up CWD-relative (like `bsdl_files/`), overridable with +up CWD-relative (like `data/bsdl_files/`), overridable with `$BS_FPGA_REGISTRY`, and loaded lazily on first access. Adding a part = -one YAML entry + its `.bsd` in `bsdl_files/` + (optionally) its proxy -`.bit` in `bscan_proxies/` — no rebuild. The `family` field accepts +one YAML entry + its `.bsd` in `data/bsdl_files/` + (optionally) its proxy +`.bit` in `data/bscan_proxies/` — no rebuild. The `family` field accepts `xilinx_*`, `microsemi_igloo2/smartfusion2`, `lattice_machxo2/3` (enum in `fpga.h`). @@ -122,7 +125,7 @@ toggles but the level-shifters/buffers stay disabled, so TDO floats high ("all ones" symptom). Standard FTDI driver path is dead on these boards. -Workaround: `modules/drivers/digilent_jtag/` wraps libdjtg/libdmgr +Workaround: `src/modules/drivers/digilent_jtag/` wraps libdjtg/libdmgr (Digilent Adept Runtime), loaded via `dlopen` at runtime — no Digilent binary or header in the repo. Because it's dlopen'd (degrades to "no probe" if the libs are absent), it costs nothing to build in: @@ -130,10 +133,10 @@ probe" if the libs are absent), it costs nothing to build in: disable with `-DBS_ENABLE_DIGILENT=OFF`. Adept Runtime is only needed at runtime to actually drive such a probe. -### Probe config profiles (probes.yaml) +### Probe config profiles (data/probes.yaml) -Probe wiring/electrical settings live in `probes.yaml` (parsed by -`modules/probes/`, libyaml), layered on top of the built-in +Probe wiring/electrical settings live in `data/probes.yaml` (parsed by +`src/modules/probes/`, libyaml), layered on top of the built-in `config.script` defaults: a `defaults:` map applied on every `jtag_open` (so opening without a profile is deterministic) plus named `profiles:` selected with `jtag_open ` (`jtag_profiles` lists them). @@ -166,9 +169,9 @@ driver-neutral terms that get resolved per session.** | Layer | What it owns | Where it lives | Applied | |-------|-------------|----------------|---------| -| **Probe (sonde)** | driver + interface, pin map, buffer-enable, TRST/SRST pins, level-shift, *max TCK the adapter supports* | `probes.yaml` (done) | at `jtag_open` | +| **Probe (sonde)** | driver + interface, pin map, buffer-enable, TRST/SRST pins, level-shift, *max TCK the adapter supports* | `data/probes.yaml` (done) | at `jtag_open` | | **JTAG link** | TCK freq, RTCK, reset behaviour, chain layout — **driver-neutral names**, resolved to effective values | *missing today* | open, then refined after detect | -| **Device** | IDCODE/BSDL/IR/proxy/caveats, programming method, *max TCK the part/board tolerates* | `fpga_registry.yaml` (done) | after IDCODE match | +| **Device** | IDCODE/BSDL/IR/proxy/caveats, programming method, *max TCK the part/board tolerates* | `data/fpga_registry.yaml` (done) | after IDCODE match | ### The smell that motivated this @@ -192,7 +195,7 @@ fact bounded by both the probe and the board/device. method) is known — using the `jtag_close`→reopen seam if a re-init is needed. This also dissolves the chicken-and-egg: a conservative link default gets you to detection, then the device refines it. -- `probes.yaml` gains an optional `max_tck_khz`; `fpga_registry.yaml` +- `data/probes.yaml` gains an optional `max_tck_khz`; `data/fpga_registry.yaml` gains optional `max_tck_khz` + a `prog` method tag (`proxy_spi`/`svf`). ### Phasing @@ -200,7 +203,7 @@ fact bounded by both the probe and the board/device. - **A (done)** — one canonical `JTAG_TCK_FREQ_KHZ` (kHz): mirrored to `PROBE_FTDI_TCK_FREQ_KHZ` at `jtag_open` for the Viveris FTDI driver, read directly by our Digilent driver; unset → each driver's own default - (FTDI 1000, Digilent 4000). Set it via `set`, a `probes.yaml` profile, + (FTDI 1000, Digilent 4000). Set it via `set`, a `data/probes.yaml` profile, or `defaults:`. (FTDI path hardware-validated; Digilent path untested.) - **B (done)** — registry `max_tck_khz` caps the clock: `jtag_autoinit`, after identifying the chain, clamps `JTAG_TCK_FREQ_KHZ` to the smallest @@ -217,8 +220,8 @@ fact bounded by both the probe and the board/device. specific pin/polarity/timing vars with no clean neutral form yet. The actual `program` dispatch command lands with the SVF player. -What exists already: the **probe layer** (`probes.yaml`) and the -**device layer** (`fpga_registry.yaml`). The new work is the **JTAG-link +What exists already: the **probe layer** (`data/probes.yaml`) and the +**device layer** (`data/fpga_registry.yaml`). The new work is the **JTAG-link layer** in the middle. ## Programming backends: beyond Xilinx external flash (design note) @@ -256,7 +259,7 @@ progress and partial ops. The equivalent SVF ("indirect flash") is huge ### The SVF player (the real work) -**Status: initial implementation in `modules/svf/` + the `svf_play ` +**Status: initial implementation in `src/modules/svf/` + the `svf_play ` command.** Supports the single-device subset: `SIR`/`SDR` with `TDI`/`TDO`/`MASK`/`SMASK` and the masked TDO compare, `RUNTEST` (TCK/SCK + SEC), `STATE` (RESET/IDLE), `ENDIR`/`ENDDR` (IDLE only), @@ -306,7 +309,7 @@ architecture has the right seam (the driver function-pointer table). 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/` +**The seam — the MCU *is* the JTAG master.** Replace `src/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 @@ -350,8 +353,8 @@ images (huge SVF vectors) stay on the host or a large MCU. Defines the proxy protocol (header with bit count + CS state, then payload). Don't reinvent — match what OpenOCD does so we share the same bitstreams. -- **Viveris library docs**: `modules/jtag_core/` headers are well - commented. `modules/config/config.script` documents every runtime +- **Viveris library docs**: `src/modules/jtag_core/` headers are well + commented. `src/modules/config/config.script` documents every runtime variable. ## Build & test @@ -362,9 +365,9 @@ mkdir build && cd build && cmake .. && make ``` Build needs **libyaml** (pkg-config `yaml-0.1`; Arch `libyaml`, Debian -`libyaml-dev`) — the FPGA registry is parsed from `fpga_registry.yaml` +`libyaml-dev`) — the FPGA registry is parsed from `data/fpga_registry.yaml` at runtime. Run `bs` from the repo root so it finds that file (and -`bsdl_files/`, `bscan_proxies/`), or point `$BS_FPGA_REGISTRY` at it. +`data/bsdl_files/`, `data/bscan_proxies/`), or point `$BS_FPGA_REGISTRY` at it. The Digilent SMT2 backend is built by default on UNIX (disable with `-DBS_ENABLE_DIGILENT=OFF`). To actually use such a probe, install the diff --git a/CMakeLists.txt b/CMakeLists.txt index 1b0f2fb..e1e0a91 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -2,6 +2,10 @@ cmake_minimum_required(VERSION 3.10) project(BoundaryScanExplorer) +# Put the built executable at the build/ root (build/bs), not nested under +# build/src/bs/ where the source tree would otherwise mirror it. +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}) + # Digilent JTAG-SMT* backend. The driver dlopen's libdjtg/libdmgr at # runtime and degrades to "no probe" if they're absent, so building it # in costs nothing — default ON. Needs , so UNIX only. @@ -16,8 +20,8 @@ option(BS_ENABLE_DIGILENT # script and jtag_core must be the last linked archive for the application to compile set(BS_MODULES script jtag_core) -set(DIR_MODULES ${CMAKE_SOURCE_DIR}/modules) -set(DIR_LIBS ${CMAKE_SOURCE_DIR}/libs) +set(DIR_MODULES ${CMAKE_SOURCE_DIR}/src/modules) +set(DIR_LIBS ${CMAKE_SOURCE_DIR}/src/libs) # We dive into submodules file(GLOB MODULES_DIRS RELATIVE ${DIR_MODULES} ${DIR_MODULES}/*) @@ -32,10 +36,10 @@ foreach(module ${MODULES_DIRS}) list(APPEND BS_MODULES ${module}) endif() # We'll compile the module - add_subdirectory(modules/${module}) + add_subdirectory(src/modules/${module}) else() message(STATUS "Ignored : ${module}") endif() endforeach() -add_subdirectory(bs) +add_subdirectory(src/bs) diff --git a/README.md b/README.md index 69686a4..5280eb6 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ library by Viveris (LGPL). - Automatic BSDL loading by IDCODE: OK - Pin control in SAMPLE / EXTEST, incl. slow SPI bit-bang: 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 +- Probe-config profiles (`data/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) @@ -27,7 +27,7 @@ library by Viveris (LGPL). Bundled BSDLs: Xilinx Kintex UltraScale+ KU15P (`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 +`.bsd` files in `data/bsdl_files/` plus an entry in `data/fpga_registry.yaml` (see [`doc/tutorial.md`](doc/tutorial.md) for adding a target). ## Dependencies @@ -36,7 +36,7 @@ and Microsemi IGLOO2 M2GL010T (`m2gl010t-fg484.bsd`). Add more by dropping - `readline` (Arch: `readline`, Debian/Ubuntu: `libreadline-dev`) - `libyaml` for the FPGA registry, found via pkg-config `yaml-0.1` (Arch: `libyaml`, Debian/Ubuntu: `libyaml-dev`) -- `libftd2xx` for FTDI probes (vendored in `libs/libftd2xx/`) +- `libftd2xx` for FTDI probes (vendored in `src/libs/libftd2xx/`) - *To drive a Digilent SMT2/SMT2-NC probe:* the Digilent [Adept Runtime](https://digilent.com/shop/software/digilent-adept/) installed system-wide (provides `libdjtg.so` + `libdmgr.so`). @@ -52,7 +52,7 @@ cmake .. make ``` -The binary is produced at `build/bs/bs`. +The binary is produced at `build/bs`. The Digilent SMT2 backend is built by default on Linux. To leave it out: @@ -66,19 +66,19 @@ Run from the repository root so the runtime data files are found — they are looked up relative to the current directory: ```sh -./build/bs/bs +./build/bs ``` `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 +- `data/config.script` — overrides built-in probe variables (FTDI clock, + TRST/SRST pin mapping, …); see `src/modules/config/config.script` for the full list. Loaded at startup. -- `probes.yaml` — probe-config profiles, applied with +- `data/probes.yaml` — probe-config profiles, applied with `jtag_open ` (`$BS_PROBES` overrides the path). -- `fpga_registry.yaml` — the FPGA target registry +- `data/fpga_registry.yaml` — the FPGA target registry (`$BS_FPGA_REGISTRY` overrides the path). -- `bsdl_files/`, `bscan_proxies/` — BSDLs and proxy bitstreams. +- `data/bsdl_files/`, `data/bscan_proxies/` — BSDLs and proxy bitstreams. ## REPL @@ -94,7 +94,7 @@ are looked up relative to the current directory: ```sh # 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: +# (e.g. an embedded FlashPro) takes a profile from data/probes.yaml: bs_explorer> jtag_probes bs_explorer> jtag_profiles # available profiles bs_explorer> jtag_open 0 # or: jtag_open 0 @@ -103,7 +103,7 @@ bs_explorer> jtag_open 0 # or: jtag_open 0 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 +bs_explorer> bscan_load_bitstream 0 data/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 @@ -121,7 +121,7 @@ bs_explorer> svf_play design.svf # exported from Libero / Diamond / Radi The slow EXTEST path (bit-bang SPI on boundary-scan pins, `jtag_mode 0 EXTEST` + `jtag_spi_*`) is only useful for one-shot checks. A minimal -example script is in `scripts/example_script.txt`; the full walkthrough +example script is in `data/scripts/example_script.txt`; the full walkthrough lives in [`doc/tutorial.md`](doc/tutorial.md). ## Main commands @@ -143,10 +143,10 @@ Use `help ` for per-command help. ## Supported probes - **FTDI** MPSSE (FT2232D/H, FT4232H, …) — see the `PROBE_FTDI_*` block - in `modules/config/config.script` for pin mapping and TCK frequency. + in `src/modules/config/config.script` for pin mapping and TCK frequency. Boards that wire the FT4232H differently (e.g. the embedded FlashPro on Microsemi eval kits, which needs ADBUS4 left high-Z) are handled by a - **probe profile** in `probes.yaml`: `jtag_profiles` lists them, + **probe profile** in `data/probes.yaml`: `jtag_profiles` lists them, `jtag_open ` applies one (e.g. `jtag_open 0 flashpro`). - **SEGGER J-Link** - **Linux GPIO** (sysfs; deprecated on recent kernels, libgpiod migration TBD) @@ -172,33 +172,35 @@ shows it). ## Repository layout ``` -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 (EXTEST) -├── drivers/ FTDI, J-Link, Linux GPIO, LPT, Digilent (optional) -├── 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 -└── natsort/ Natural-order pin-name sorting -fpga_registry.yaml FPGA registry (IDCODE → BSDL, IR opcodes, proxy, caveats) -probes.yaml Probe-config profiles (defaults + per-probe overrides) -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 +src/ — code + libs — +├── bs/ Application (readline REPL) +├── libs/libftd2xx/ Vendored FTDI SDK +└── modules/ + ├── jtag_core/ TAP state machine, IR/DR shifts + ├── bsdl_parser/ .bsd loader + ├── bus_over_jtag/ SPI / I²C / MDIO / parallel mem bit-bang (EXTEST) + ├── drivers/ FTDI, J-Link, Linux GPIO, LPT, Digilent (optional) + ├── fpga/ Registry loader (parses data/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 (data/probes.yaml) + ├── script/ Script engine + ├── config/ Built-in config.script + ├── os_interface/ Portable fs/network wrappers + └── natsort/ Natural-order pin-name sorting +data/ — runtime resources, looked up from the CWD — +├── fpga_registry.yaml FPGA registry (IDCODE → BSDL, IR opcodes, proxy, caveats) +├── probes.yaml Probe-config profiles (defaults + per-probe overrides) +├── bsdl_files/ BSDL files for target FPGAs +├── bscan_proxies/ BSCAN proxy bitstreams (MIT, from quartiq) +└── scripts/ Example scripts +doc/ Tutorial and longer-form docs ``` ## License -`modules/jtag_core/` and the original Viveris files are under LGPL 2.1. -See `LICENSE` and `modules/jtag_core/COPYING.LESSER`. The proxy -bitstreams in `bscan_proxies/` are from quartiq (MIT) — see -`bscan_proxies/LICENSE.quartiq`. +`src/modules/jtag_core/` and the original Viveris files are under LGPL 2.1. +See `LICENSE` and `src/modules/jtag_core/COPYING.LESSER`. The proxy +bitstreams in `data/bscan_proxies/` are from quartiq (MIT) — see +`data/bscan_proxies/LICENSE.quartiq`. diff --git a/bscan_proxies/LICENSE.quartiq b/data/bscan_proxies/LICENSE.quartiq similarity index 100% rename from bscan_proxies/LICENSE.quartiq rename to data/bscan_proxies/LICENSE.quartiq diff --git a/bscan_proxies/README.md b/data/bscan_proxies/README.md similarity index 90% rename from bscan_proxies/README.md rename to data/bscan_proxies/README.md index 141aad1..2466127 100644 --- a/bscan_proxies/README.md +++ b/data/bscan_proxies/README.md @@ -7,7 +7,7 @@ enabling fast SPI flashing — see `doc/tutorial.md`, Phase 2.5. These `.bit` files are **not** built here. They come from [quartiq/bscan_spi_bitstreams](https://github.com/quartiq/bscan_spi_bitstreams), © QUARTIQ GmbH, MIT-licensed — see `LICENSE.quartiq`. The host-side -framing in `modules/bscan/` matches OpenOCD's `jtagspi` so the same +framing in `src/modules/bscan/` matches OpenOCD's `jtagspi` so the same bitstreams work. | File | Part | Used by | diff --git a/bscan_proxies/bscan_spi_xcku040.bit b/data/bscan_proxies/bscan_spi_xcku040.bit similarity index 100% rename from bscan_proxies/bscan_spi_xcku040.bit rename to data/bscan_proxies/bscan_spi_xcku040.bit diff --git a/bsdl_files/m2gl010t-fg484.bsd b/data/bsdl_files/m2gl010t-fg484.bsd similarity index 100% rename from bsdl_files/m2gl010t-fg484.bsd rename to data/bsdl_files/m2gl010t-fg484.bsd diff --git a/bsdl_files/xcku040_ffva1156.bsd b/data/bsdl_files/xcku040_ffva1156.bsd similarity index 100% rename from bsdl_files/xcku040_ffva1156.bsd rename to data/bsdl_files/xcku040_ffva1156.bsd diff --git a/bsdl_files/xcku15p_ffve1517.bsd b/data/bsdl_files/xcku15p_ffve1517.bsd similarity index 100% rename from bsdl_files/xcku15p_ffve1517.bsd rename to data/bsdl_files/xcku15p_ffve1517.bsd diff --git a/fpga_registry.yaml b/data/fpga_registry.yaml similarity index 100% rename from fpga_registry.yaml rename to data/fpga_registry.yaml diff --git a/probes.yaml b/data/probes.yaml similarity index 100% rename from probes.yaml rename to data/probes.yaml diff --git a/scripts/example_script.txt b/data/scripts/example_script.txt similarity index 100% rename from scripts/example_script.txt rename to data/scripts/example_script.txt diff --git a/doc/tutorial.md b/doc/tutorial.md index e0dea4c..1db6437 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -9,17 +9,17 @@ paths and the tutorial covers both: - **any other part** (Lattice, Microsemi, …), by playing a vendor-exported **SVF** — shown on a Microsemi IGLOO2 M2GL010T. -The early steps are identical for any device in `fpga_registry.yaml`; +The early steps are identical for any device in `data/fpga_registry.yaml`; only the IDCODE and BSDL filename change. ## Prerequisites - A JTAG probe physically wired to the target's TCK/TDI/TDO/TMS/TRST. - `libftd2xx` reachable at runtime (already vendored under - `libs/libftd2xx/`). -- The target's BSDL in `bsdl_files/` (KU15P: `xcku15p_ffve1517.bsd` is + `src/libs/libftd2xx/`). +- The target's BSDL in `data/bsdl_files/` (KU15P: `xcku15p_ffve1517.bsd` is bundled). -- An entry for the target in `fpga_registry.yaml` (KU15P is bundled). +- An entry for the target in `data/fpga_registry.yaml` (KU15P is bundled). See [Adding a new FPGA](#6-add-a-new-fpga-target) below. - For SPI flashing, eventually: a BSCAN proxy bitstream — see the [Phase 2.5 caveat](#phase-25-spi-through-the-bscan-proxy-bridge-bitstream) at the end. @@ -34,8 +34,8 @@ README and the `Digilent SMT2` block in `CLAUDE.md` for the why. ```sh mkdir build && cd build && cmake .. && make && cd .. -./build/bs/bs # run from the repo root: probes.yaml, fpga_registry.yaml, - # bsdl_files/ and bscan_proxies/ are looked up in the CWD +./build/bs # run from the repo root: data/probes.yaml, data/fpga_registry.yaml, + # data/bsdl_files/ and data/bscan_proxies/ are looked up in the CWD ``` You should see: @@ -81,12 +81,12 @@ confirm no other process holds the probe (e.g. `openocd`). Some probes need pin tweaks the built-in defaults don't cover — e.g. the embedded **FlashPro** on Microsemi eval kits (an FT4232H whose JTAG sits on channel A = index 0 and needs `ADBUS4` left high-Z, or the chain stays -silent). `probes.yaml` captures these as named profiles; apply one when +silent). `data/probes.yaml` captures these as named profiles; apply one when opening: ``` bs_explorer> jtag_profiles -2 probe profile(s) in probes.yaml: +2 probe profile(s) in data/probes.yaml: flashpro ft2232h bs_explorer> jtag_open 0 flashpro @@ -102,7 +102,7 @@ probes in turn: `jtag_close`, then `jtag_open` the next one and ## 2. Scan the JTAG chain The fastest path is `jtag_autoinit`: it scans the chain *and* -auto-loads every BSDL in `bsdl_files/` whose IDCODE matches a device. +auto-loads every BSDL in `data/bsdl_files/` whose IDCODE matches a device. ``` bs_explorer> jtag_autoinit @@ -122,7 +122,7 @@ mis-wired. Power-cycle and re-check the harness before going further. ## 3. Identify the FPGA against the registry `fpga_info` walks the chain and matches each IDCODE against the -registry in `fpga_registry.yaml`: +registry in `data/fpga_registry.yaml`: ``` bs_explorer> fpga_info @@ -216,7 +216,7 @@ way; you'd be there for weeks. ## 6. Add a new FPGA target -The registry — `fpga_registry.yaml` at the repo root — holds the +The registry — `data/fpga_registry.yaml` at the repo root — holds the per-part facts that can't be derived from the BSDL alone (or are tedious to). It's parsed at runtime, so adding a part is **editing YAML, no rebuild**. The XCKU040 entry already there was added exactly with the @@ -224,7 +224,7 @@ steps below — use it as your template. ### a. Drop the BSDL -Put the part's `.bsd` in `bsdl_files/`. Source: Xilinx/AMD device page +Put the part's `.bsd` in `data/bsdl_files/`. Source: Xilinx/AMD device page under "Design Files / BSDL", Intel in the Quartus install, Lattice per part, Microsemi/Microchip via Libero. `jtag_autoinit` will then auto-load it by IDCODE. @@ -235,7 +235,7 @@ Everything you need is in the file: ```sh grep -iE "INSTRUCTION_LENGTH|IDCODE_REGISTER|\b(USER1|CFG_IN|JPROGRAM|JSTART|JSHUTDOWN|ISC_DISABLE)\b" \ - bsdl_files/xcku040_ffva1156.bsd + data/bsdl_files/xcku040_ffva1156.bsd ``` For the XCKU040 this yields IR length 6, and the private opcodes @@ -247,7 +247,7 @@ masks them off. ### c. Add a YAML entry -Append a list item under `fpgas:` in `fpga_registry.yaml`: +Append a list item under `fpgas:` in `data/fpga_registry.yaml`: | Key | What it is | XCKU040 | |-----|-----------|---------| @@ -255,15 +255,15 @@ Append a list item under `fpgas:` in `fpga_registry.yaml`: | `idcode` | IDCODE pattern (version nibble as 0) | `0x03822093` | | `idcode_mask` | bits that must match; `0x0FFFFFFF` ignores the Xilinx revision nibble (default `0xFFFFFFFF`) | `0x0FFFFFFF` | | `family` | `xilinx_7/us/usp`, `microsemi_igloo2/smartfusion2`, `lattice_machxo2/3` | `xilinx_us` | -| `bsdl` | basename in `bsdl_files/` | `xcku040_ffva1156.bsd` | +| `bsdl` | basename in `data/bsdl_files/` | `xcku040_ffva1156.bsd` | | `ir_length` | IR width in bits | `6` | | `ir_cfg_in` / `ir_user1` / `ir_jprogram` / `ir_jstart` / `ir_jshutdown` / `ir_isc_disable` | private IR opcodes (omit = 0/N/A) | from the BSDL | -| `proxy_bitstream` | BSCAN proxy `.bit` in `bscan_proxies/` (omit if none) | `bscan_spi_xcku040.bit` | +| `proxy_bitstream` | BSCAN proxy `.bit` in `data/bscan_proxies/` (omit if none) | `bscan_spi_xcku040.bit` | | `caveats` | space/comma-separated flag names (omit if none) | `cclk_via_startup` | | `max_tck_khz` | max safe JTAG TCK in kHz; `jtag_autoinit` clamps + re-opens if exceeded (omit = unspecified) | — | | `prog` | programming backend `proxy_spi`/`svf`/`none` (omit → inferred: a proxy ⇒ `proxy_spi`, Microsemi/Lattice ⇒ `svf`) | `proxy_spi` | -The resulting entry (verbatim from `fpga_registry.yaml`): +The resulting entry (verbatim from `data/fpga_registry.yaml`): ```yaml - name: "Xilinx Kintex UltraScale XCKU040" @@ -318,7 +318,7 @@ The registry is loaded at runtime, so just (re)start bs_explorer from the repo root and check: ```sh -./build/bs/bs +./build/bs bs_explorer> fpga_list # your part should appear, with its source file bs_explorer> jtag_autoinit bs_explorer> fpga_info # should show your part, family, and any caveats @@ -339,10 +339,10 @@ internally — so the `STARTUPE3`/CCLK problem of EXTEST disappears. ### Get the bridge bitstream Pre-built proxies live in `quartiq/bscan_spi_bitstreams` (MIT). Drop -the one for your part in `bscan_proxies/`: +the one for your part in `data/bscan_proxies/`: ```sh -curl -L -o bscan_proxies/bscan_spi_xcku040.bit \ +curl -L -o data/bscan_proxies/bscan_spi_xcku040.bit \ https://raw.githubusercontent.com/quartiq/bscan_spi_bitstreams/master/bscan_spi_xcku040.bit ``` @@ -367,9 +367,9 @@ PATH=$PATH:/opt/Xilinx/Vivado/2022.2/bin \ The XCKU15P first has to be **added to the generator's device table** (a Migen platform entry) — it's not just a command-line part flag. -Once built, drop `bscan_spi_xcku15p.bit` into `bscan_proxies/` (it's -MIT, like the KU040 — keep `bscan_proxies/LICENSE.quartiq`) and set the -`proxy_bitstream` field on the KU15P entry in `fpga_registry.yaml` +Once built, drop `bscan_spi_xcku15p.bit` into `data/bscan_proxies/` (it's +MIT, like the KU040 — keep `data/bscan_proxies/LICENSE.quartiq`) and set the +`proxy_bitstream` field on the KU15P entry in `data/fpga_registry.yaml` (currently omitted). ### Load the bridge and talk SPI @@ -377,7 +377,7 @@ MIT, like the KU040 — keep `bscan_proxies/LICENSE.quartiq`) and set the ``` bs_explorer> jtag_open 1 bs_explorer> jtag_autoinit -bs_explorer> bscan_load_bitstream 0 bscan_proxies/bscan_spi_xcku040.bit +bs_explorer> bscan_load_bitstream 0 data/bscan_proxies/bscan_spi_xcku040.bit bs_explorer> bscan_jedec 0 JEDEC ID: 20 BB 19 (manufacturer 0x20, device 0xBB19) ``` @@ -414,7 +414,7 @@ read-latency skew. ### The transfer primitive `bscan_spi_xfer(jc, t, tx, txlen, rx, rxlen)` in -`modules/bscan/bscan.c` performs one CS-framed transaction: +`src/modules/bscan/bscan.c` performs one CS-framed transaction: clock out `txlen` MOSI bytes, then read `rxlen` MISO bytes. It builds the quartiq/OpenOCD jtagspi DR frame (`marker | bit-count | MOSI | latency-skip | MISO`) and matches @@ -484,7 +484,7 @@ small IGLOO2 parts). `bs_explorer` only *plays* it, which is fully open. | `jtag_autoinit` finds 0 devices | TDI/TDO swap, TRST held low, voltage mismatch, or chain broken. | | All IDCODEs read `0xFFFFFFFF` | TDO floats high — broken TDO link, wrong voltage reference, or a Digilent SMT2 module being driven via raw FTDI MPSSE (use the Digilent backend instead). | | All IDCODEs read `0x00000000` | TDO tied low or no clock reaching the target. | -| `fpga_info` says "not in registry" | Add an entry to `fpga_registry.yaml`. | +| `fpga_info` says "not in registry" | Add an entry to `data/fpga_registry.yaml`. | | `bscan_shift_dr 32` doesn't return the expected IDCODE | Wrong IR opcode/length, wrong device index, or a multi-device chain (current primitives assume single device). | | `jtag_spi_xfer` is hopelessly slow | That's expected via EXTEST — switch to BSCAN proxy (Phase 2.5). | | Detected fine, then reads turn to garbage / `0x00000000` mid-session | Target board lost power — JTAG floats (the USB probe stays enumerated regardless). Re-power the board. | @@ -498,4 +498,4 @@ small IGLOO2 parts). `bs_explorer` only *plays* it, which is fully open. technical decisions (machine-independent). - `README.md` is the user-facing summary. - The original Viveris library and its docs live untouched under - `modules/jtag_core/`, `modules/bsdl_parser/`, `modules/bus_over_jtag/`. + `src/modules/jtag_core/`, `src/modules/bsdl_parser/`, `src/modules/bus_over_jtag/`. diff --git a/bs/CMakeLists.txt b/src/bs/CMakeLists.txt similarity index 100% rename from bs/CMakeLists.txt rename to src/bs/CMakeLists.txt diff --git a/bs/init.c b/src/bs/init.c similarity index 95% rename from bs/init.c rename to src/bs/init.c index dcb1069..e5c1787 100644 --- a/bs/init.c +++ b/src/bs/init.c @@ -64,10 +64,10 @@ void bsexp_init(jtag_core **jc, script_ctx **sctx) execute_ram_script(*sctx, config_script, config_script_len); /* User override is optional — silence the engine's "not found" message. */ { - FILE *f = fopen("config.script", "r"); + FILE *f = fopen("data/config.script", "r"); if (f) { fclose(f); - execute_file_script(*sctx, "config.script"); + execute_file_script(*sctx, "data/config.script"); } } diff --git a/bs/init.h b/src/bs/init.h similarity index 100% rename from bs/init.h rename to src/bs/init.h diff --git a/bs/main.c b/src/bs/main.c similarity index 100% rename from bs/main.c rename to src/bs/main.c diff --git a/libs/libftd2xx/WinTypes.h b/src/libs/libftd2xx/WinTypes.h similarity index 100% rename from libs/libftd2xx/WinTypes.h rename to src/libs/libftd2xx/WinTypes.h diff --git a/libs/libftd2xx/ftd2xx.h b/src/libs/libftd2xx/ftd2xx.h similarity index 100% rename from libs/libftd2xx/ftd2xx.h rename to src/libs/libftd2xx/ftd2xx.h diff --git a/libs/libftd2xx/libftd2xx.a b/src/libs/libftd2xx/libftd2xx.a similarity index 100% rename from libs/libftd2xx/libftd2xx.a rename to src/libs/libftd2xx/libftd2xx.a diff --git a/modules/bscan/CMakeLists.txt b/src/modules/bscan/CMakeLists.txt similarity index 100% rename from modules/bscan/CMakeLists.txt rename to src/modules/bscan/CMakeLists.txt diff --git a/modules/bscan/bscan.c b/src/modules/bscan/bscan.c similarity index 100% rename from modules/bscan/bscan.c rename to src/modules/bscan/bscan.c diff --git a/modules/bscan/bscan.h b/src/modules/bscan/bscan.h similarity index 100% rename from modules/bscan/bscan.h rename to src/modules/bscan/bscan.h diff --git a/modules/bsdl_parser/CMakeLists.txt b/src/modules/bsdl_parser/CMakeLists.txt similarity index 100% rename from modules/bsdl_parser/CMakeLists.txt rename to src/modules/bsdl_parser/CMakeLists.txt diff --git a/modules/bsdl_parser/bsdl_loader.c b/src/modules/bsdl_parser/bsdl_loader.c similarity index 100% rename from modules/bsdl_parser/bsdl_loader.c rename to src/modules/bsdl_parser/bsdl_loader.c diff --git a/modules/bsdl_parser/bsdl_loader.h b/src/modules/bsdl_parser/bsdl_loader.h similarity index 100% rename from modules/bsdl_parser/bsdl_loader.h rename to src/modules/bsdl_parser/bsdl_loader.h diff --git a/modules/bsdl_parser/bsdl_strings.c b/src/modules/bsdl_parser/bsdl_strings.c similarity index 100% rename from modules/bsdl_parser/bsdl_strings.c rename to src/modules/bsdl_parser/bsdl_strings.c diff --git a/modules/bsdl_parser/bsdl_strings.h b/src/modules/bsdl_parser/bsdl_strings.h similarity index 100% rename from modules/bsdl_parser/bsdl_strings.h rename to src/modules/bsdl_parser/bsdl_strings.h diff --git a/modules/bus_over_jtag/CMakeLists.txt b/src/modules/bus_over_jtag/CMakeLists.txt similarity index 100% rename from modules/bus_over_jtag/CMakeLists.txt rename to src/modules/bus_over_jtag/CMakeLists.txt diff --git a/modules/bus_over_jtag/i2c_over_jtag.c b/src/modules/bus_over_jtag/i2c_over_jtag.c similarity index 100% rename from modules/bus_over_jtag/i2c_over_jtag.c rename to src/modules/bus_over_jtag/i2c_over_jtag.c diff --git a/modules/bus_over_jtag/mdio_over_jtag.c b/src/modules/bus_over_jtag/mdio_over_jtag.c similarity index 100% rename from modules/bus_over_jtag/mdio_over_jtag.c rename to src/modules/bus_over_jtag/mdio_over_jtag.c diff --git a/modules/bus_over_jtag/memory_over_jtag.c b/src/modules/bus_over_jtag/memory_over_jtag.c similarity index 100% rename from modules/bus_over_jtag/memory_over_jtag.c rename to src/modules/bus_over_jtag/memory_over_jtag.c diff --git a/modules/bus_over_jtag/spi_over_jtag.c b/src/modules/bus_over_jtag/spi_over_jtag.c similarity index 100% rename from modules/bus_over_jtag/spi_over_jtag.c rename to src/modules/bus_over_jtag/spi_over_jtag.c diff --git a/modules/config/bs_defines.h b/src/modules/config/bs_defines.h similarity index 100% rename from modules/config/bs_defines.h rename to src/modules/config/bs_defines.h diff --git a/modules/config/config.script b/src/modules/config/config.script similarity index 100% rename from modules/config/config.script rename to src/modules/config/config.script diff --git a/modules/config/config_script.h b/src/modules/config/config_script.h similarity index 100% rename from modules/config/config_script.h rename to src/modules/config/config_script.h diff --git a/modules/config/version.h b/src/modules/config/version.h similarity index 100% rename from modules/config/version.h rename to src/modules/config/version.h diff --git a/modules/drivers/CMakeLists.txt b/src/modules/drivers/CMakeLists.txt similarity index 100% rename from modules/drivers/CMakeLists.txt rename to src/modules/drivers/CMakeLists.txt diff --git a/modules/drivers/digilent_jtag/digilent_jtag_drv.c b/src/modules/drivers/digilent_jtag/digilent_jtag_drv.c similarity index 100% rename from modules/drivers/digilent_jtag/digilent_jtag_drv.c rename to src/modules/drivers/digilent_jtag/digilent_jtag_drv.c diff --git a/modules/drivers/digilent_jtag/digilent_jtag_drv.h b/src/modules/drivers/digilent_jtag/digilent_jtag_drv.h similarity index 100% rename from modules/drivers/digilent_jtag/digilent_jtag_drv.h rename to src/modules/drivers/digilent_jtag/digilent_jtag_drv.h diff --git a/modules/drivers/drivers_list.c b/src/modules/drivers/drivers_list.c similarity index 100% rename from modules/drivers/drivers_list.c rename to src/modules/drivers/drivers_list.c diff --git a/modules/drivers/drivers_list.h b/src/modules/drivers/drivers_list.h similarity index 100% rename from modules/drivers/drivers_list.h rename to src/modules/drivers/drivers_list.h diff --git a/modules/drivers/drv_loader.c b/src/modules/drivers/drv_loader.c similarity index 100% rename from modules/drivers/drv_loader.c rename to src/modules/drivers/drv_loader.c diff --git a/modules/drivers/drv_loader.h b/src/modules/drivers/drv_loader.h similarity index 100% rename from modules/drivers/drv_loader.h rename to src/modules/drivers/drv_loader.h diff --git a/modules/drivers/ftdi_jtag/ftdi_jtag_drv.c b/src/modules/drivers/ftdi_jtag/ftdi_jtag_drv.c similarity index 100% rename from modules/drivers/ftdi_jtag/ftdi_jtag_drv.c rename to src/modules/drivers/ftdi_jtag/ftdi_jtag_drv.c diff --git a/modules/drivers/ftdi_jtag/ftdi_jtag_drv.h b/src/modules/drivers/ftdi_jtag/ftdi_jtag_drv.h similarity index 100% rename from modules/drivers/ftdi_jtag/ftdi_jtag_drv.h rename to src/modules/drivers/ftdi_jtag/ftdi_jtag_drv.h diff --git a/modules/drivers/jlink_jtag/jlink_jtag_drv.c b/src/modules/drivers/jlink_jtag/jlink_jtag_drv.c similarity index 100% rename from modules/drivers/jlink_jtag/jlink_jtag_drv.c rename to src/modules/drivers/jlink_jtag/jlink_jtag_drv.c diff --git a/modules/drivers/jlink_jtag/jlink_jtag_drv.h b/src/modules/drivers/jlink_jtag/jlink_jtag_drv.h similarity index 100% rename from modules/drivers/jlink_jtag/jlink_jtag_drv.h rename to src/modules/drivers/jlink_jtag/jlink_jtag_drv.h diff --git a/modules/drivers/linux_gpio_jtag/linux_gpio_jtag_drv.c b/src/modules/drivers/linux_gpio_jtag/linux_gpio_jtag_drv.c similarity index 100% rename from modules/drivers/linux_gpio_jtag/linux_gpio_jtag_drv.c rename to src/modules/drivers/linux_gpio_jtag/linux_gpio_jtag_drv.c diff --git a/modules/drivers/linux_gpio_jtag/linux_gpio_jtag_drv.h b/src/modules/drivers/linux_gpio_jtag/linux_gpio_jtag_drv.h similarity index 100% rename from modules/drivers/linux_gpio_jtag/linux_gpio_jtag_drv.h rename to src/modules/drivers/linux_gpio_jtag/linux_gpio_jtag_drv.h diff --git a/modules/drivers/lpt_jtag/lpt_jtag_drv.c b/src/modules/drivers/lpt_jtag/lpt_jtag_drv.c similarity index 100% rename from modules/drivers/lpt_jtag/lpt_jtag_drv.c rename to src/modules/drivers/lpt_jtag/lpt_jtag_drv.c diff --git a/modules/drivers/lpt_jtag/lpt_jtag_drv.h b/src/modules/drivers/lpt_jtag/lpt_jtag_drv.h similarity index 100% rename from modules/drivers/lpt_jtag/lpt_jtag_drv.h rename to src/modules/drivers/lpt_jtag/lpt_jtag_drv.h diff --git a/modules/fpga/CMakeLists.txt b/src/modules/fpga/CMakeLists.txt similarity index 100% rename from modules/fpga/CMakeLists.txt rename to src/modules/fpga/CMakeLists.txt diff --git a/modules/fpga/fpga.c b/src/modules/fpga/fpga.c similarity index 99% rename from modules/fpga/fpga.c rename to src/modules/fpga/fpga.c index aa6f26d..f0fa5eb 100644 --- a/modules/fpga/fpga.c +++ b/src/modules/fpga/fpga.c @@ -19,7 +19,7 @@ * The schema is one flat mapping per entry; see fpga_registry.yaml. */ -#define DEFAULT_REGISTRY_FILE "fpga_registry.yaml" +#define DEFAULT_REGISTRY_FILE "data/fpga_registry.yaml" static fpga_target *g_registry = NULL; static int g_count = 0; diff --git a/modules/fpga/fpga.h b/src/modules/fpga/fpga.h similarity index 100% rename from modules/fpga/fpga.h rename to src/modules/fpga/fpga.h diff --git a/modules/jtag_core/CMakeLists.txt b/src/modules/jtag_core/CMakeLists.txt similarity index 100% rename from modules/jtag_core/CMakeLists.txt rename to src/modules/jtag_core/CMakeLists.txt diff --git a/modules/jtag_core/COPYING.LESSER b/src/modules/jtag_core/COPYING.LESSER similarity index 100% rename from modules/jtag_core/COPYING.LESSER rename to src/modules/jtag_core/COPYING.LESSER diff --git a/modules/jtag_core/dbg_logs.c b/src/modules/jtag_core/dbg_logs.c similarity index 100% rename from modules/jtag_core/dbg_logs.c rename to src/modules/jtag_core/dbg_logs.c diff --git a/modules/jtag_core/dbg_logs.h b/src/modules/jtag_core/dbg_logs.h similarity index 100% rename from modules/jtag_core/dbg_logs.h rename to src/modules/jtag_core/dbg_logs.h diff --git a/modules/jtag_core/jtag_core.c b/src/modules/jtag_core/jtag_core.c similarity index 100% rename from modules/jtag_core/jtag_core.c rename to src/modules/jtag_core/jtag_core.c diff --git a/modules/jtag_core/jtag_core.h b/src/modules/jtag_core/jtag_core.h similarity index 100% rename from modules/jtag_core/jtag_core.h rename to src/modules/jtag_core/jtag_core.h diff --git a/modules/natsort/CMakeLists.txt b/src/modules/natsort/CMakeLists.txt similarity index 100% rename from modules/natsort/CMakeLists.txt rename to src/modules/natsort/CMakeLists.txt diff --git a/modules/natsort/strnatcmp.c b/src/modules/natsort/strnatcmp.c similarity index 100% rename from modules/natsort/strnatcmp.c rename to src/modules/natsort/strnatcmp.c diff --git a/modules/natsort/strnatcmp.h b/src/modules/natsort/strnatcmp.h similarity index 100% rename from modules/natsort/strnatcmp.h rename to src/modules/natsort/strnatcmp.h diff --git a/modules/os_interface/CMakeLists.txt b/src/modules/os_interface/CMakeLists.txt similarity index 100% rename from modules/os_interface/CMakeLists.txt rename to src/modules/os_interface/CMakeLists.txt diff --git a/modules/os_interface/fs.c b/src/modules/os_interface/fs.c similarity index 100% rename from modules/os_interface/fs.c rename to src/modules/os_interface/fs.c diff --git a/modules/os_interface/network.c b/src/modules/os_interface/network.c similarity index 100% rename from modules/os_interface/network.c rename to src/modules/os_interface/network.c diff --git a/modules/os_interface/network.h b/src/modules/os_interface/network.h similarity index 100% rename from modules/os_interface/network.h rename to src/modules/os_interface/network.h diff --git a/modules/os_interface/os_interface.c b/src/modules/os_interface/os_interface.c similarity index 100% rename from modules/os_interface/os_interface.c rename to src/modules/os_interface/os_interface.c diff --git a/modules/os_interface/os_interface.h b/src/modules/os_interface/os_interface.h similarity index 100% rename from modules/os_interface/os_interface.h rename to src/modules/os_interface/os_interface.h diff --git a/modules/probes/CMakeLists.txt b/src/modules/probes/CMakeLists.txt similarity index 100% rename from modules/probes/CMakeLists.txt rename to src/modules/probes/CMakeLists.txt diff --git a/modules/probes/probes.c b/src/modules/probes/probes.c similarity index 99% rename from modules/probes/probes.c rename to src/modules/probes/probes.c index 316044a..2a6018e 100644 --- a/modules/probes/probes.c +++ b/src/modules/probes/probes.c @@ -21,7 +21,7 @@ * Parsed once and cached. See probes.h for semantics. */ -#define DEFAULT_PROBES_FILE "probes.yaml" +#define DEFAULT_PROBES_FILE "data/probes.yaml" typedef struct { char *key; char *val; } kv; typedef struct { char *name; kv *vars; int nvars; } profile; diff --git a/modules/probes/probes.h b/src/modules/probes/probes.h similarity index 100% rename from modules/probes/probes.h rename to src/modules/probes/probes.h diff --git a/modules/script/CMakeLists.txt b/src/modules/script/CMakeLists.txt similarity index 100% rename from modules/script/CMakeLists.txt rename to src/modules/script/CMakeLists.txt diff --git a/modules/script/env.c b/src/modules/script/env.c similarity index 100% rename from modules/script/env.c rename to src/modules/script/env.c diff --git a/modules/script/env.h b/src/modules/script/env.h similarity index 100% rename from modules/script/env.h rename to src/modules/script/env.h diff --git a/modules/script/script.c b/src/modules/script/script.c similarity index 96% rename from modules/script/script.c rename to src/modules/script/script.c index fc14baf..54e0244 100644 --- a/modules/script/script.c +++ b/src/modules/script/script.c @@ -1514,7 +1514,7 @@ static int autoinit_run(script_ctx *ctx) genos_getcurrentdirectory(szExecPath, MAX_PATH); strncpy(scanfolder, szExecPath, sizeof(scanfolder)); - genos_strndstcat(scanfolder, DIR_SEPARATOR "bsdl_files" DIR_SEPARATOR, sizeof(scanfolder) - 1); + genos_strndstcat(scanfolder, DIR_SEPARATOR "data" DIR_SEPARATOR "bsdl_files" DIR_SEPARATOR, sizeof(scanfolder) - 1); scanfolder[sizeof(scanfolder) - 1] = '\0'; h_file_find = genos_find_first_file(scanfolder, "*.*", &fileinfo); @@ -1525,7 +1525,7 @@ static int autoinit_run(script_ctx *ctx) do { strcpy(filename, szExecPath); - genos_strndstcat(filename, DIR_SEPARATOR "bsdl_files" DIR_SEPARATOR, sizeof(filename)); + genos_strndstcat(filename, DIR_SEPARATOR "data" DIR_SEPARATOR "bsdl_files" DIR_SEPARATOR, sizeof(filename)); genos_strndstcat(filename, fileinfo.filename, sizeof(filename)); filename[sizeof(filename) - 1] = '\0'; diff --git a/modules/script/script.h b/src/modules/script/script.h similarity index 100% rename from modules/script/script.h rename to src/modules/script/script.h diff --git a/modules/spi_flash/CMakeLists.txt b/src/modules/spi_flash/CMakeLists.txt similarity index 100% rename from modules/spi_flash/CMakeLists.txt rename to src/modules/spi_flash/CMakeLists.txt diff --git a/modules/spi_flash/spi_flash.c b/src/modules/spi_flash/spi_flash.c similarity index 100% rename from modules/spi_flash/spi_flash.c rename to src/modules/spi_flash/spi_flash.c diff --git a/modules/spi_flash/spi_flash.h b/src/modules/spi_flash/spi_flash.h similarity index 100% rename from modules/spi_flash/spi_flash.h rename to src/modules/spi_flash/spi_flash.h diff --git a/modules/svf/CMakeLists.txt b/src/modules/svf/CMakeLists.txt similarity index 100% rename from modules/svf/CMakeLists.txt rename to src/modules/svf/CMakeLists.txt diff --git a/modules/svf/svf.c b/src/modules/svf/svf.c similarity index 100% rename from modules/svf/svf.c rename to src/modules/svf/svf.c diff --git a/modules/svf/svf.h b/src/modules/svf/svf.h similarity index 100% rename from modules/svf/svf.h rename to src/modules/svf/svf.h