restructure: code+libs under src/, runtime resources under data/
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 <noreply@anthropic.com>
This commit is contained in:
84
README.md
84
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 <idx> <profile>` (`$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 <profile>
|
||||
@@ -103,7 +103,7 @@ bs_explorer> jtag_open 0 # or: jtag_open 0 <profile>
|
||||
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 <command>` 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 <idx> <profile>` 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`.
|
||||
|
||||
Reference in New Issue
Block a user