electronics/bs_explorer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

script: shorten jtag_* command names

Browse Source 
Drop the get_/set_/_pin/_list noise from the JTAG commands (e.g.
jtag_get_probes_list -> jtag_probes, jtag_set_spi_cs_pin -> jtag_spi_cs,
jtag_spi_rd_wr -> jtag_spi_xfer). jtag_open_probe -> jtag_open (not
jtag_probe, which would clash with jtag_probes under tab-completion).

Hard rename, no aliases. Updates the state-dump emitter, help text,
example script and docs accordingly.
This commit is contained in:
Foué
2026-05-23 16:33:23 +02:00
parent d82a1e0739
commit 952c010c63
6 changed files with 62 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
doc/tutorial.md
View File

@@ -50,7 +50,7 @@ Ctrl-D or `exit` quits.
## 1. Detect and open the probe
```
bs_explorer> jtag_get_probes_list
bs_explorer> jtag_probes
[0] 0x00000000 Digilent USB Device 210308AB06A6
[1] 0x00000300 Digilent: JtagSmt2NC
```
@@ -58,14 +58,14 @@ bs_explorer> jtag_get_probes_list
Open a probe by the index in brackets:
```
bs_explorer> jtag_open_probe 1
bs_explorer> jtag_open 1
```
The `0x…` value next to each index is the raw probe id and is also
accepted (`jtag_open_probe 0x300`) — handy in scripts where you'd
rather pin the exact backend than rely on enumeration order.
accepted (`jtag_open 0x300`) — handy in scripts where you'd rather pin
the exact backend than rely on enumeration order.
If `jtag_open_probe` fails: check `lsusb` for the probe VID:PID, make
If `jtag_open` fails: check `lsusb` for the probe VID:PID, make
sure the user has access to the USB device (udev rule or group), and
confirm no other process holds the probe (e.g. `openocd`).
@@ -113,8 +113,8 @@ the BSDL state (so `jtag_core` doesn't fight us on IR caching) and
shift IDCODE manually:
```
bs_explorer> jtag_open_probe 0 # index from jtag_get_probes_list
bs_explorer> jtag_init_scan # detects devices, does NOT load BSDL
bs_explorer> jtag_open 0 # index from jtag_probes
bs_explorer> jtag_scan # detects devices, does NOT load BSDL
bs_explorer> bscan_set_ir 9 6 # IDCODE opcode (KU15P: 0x09, IR=6 bits)
bs_explorer> bscan_shift_dr 32
DR = 04 A5 60 93 # bytes printed MSB-first
@@ -135,14 +135,14 @@ BSDL pin names:
```
bs_explorer> jtag_autoinit
bs_explorer> jtag_set_mode 0 EXTEST
bs_explorer> jtag_set_spi_cs_pin 0 <PIN_CS> 0
bs_explorer> jtag_set_spi_clk_pin 0 <PIN_CLK> 0
bs_explorer> jtag_set_spi_mosi_pin 0 <PIN_MOSI> 0
bs_explorer> jtag_set_spi_miso_pin 0 <PIN_MISO> 0
bs_explorer> jtag_mode 0 EXTEST
bs_explorer> jtag_spi_cs 0 <PIN_CS> 0
bs_explorer> jtag_spi_clk 0 <PIN_CLK> 0
bs_explorer> jtag_spi_mosi 0 <PIN_MOSI> 0
bs_explorer> jtag_spi_miso 0 <PIN_MISO> 0
```
Pin names depend on the board: dump `jtag_get_pins_list 0` to discover
Pin names depend on the board: dump `jtag_pins 0` to discover
them. On Xilinx FPGAs, the SPI flash is typically wired to the
configuration bank (e.g. `D00_MOSI_0`, `D01_DIN_0`, `FCS_B_0`) —
**except** `CCLK`, which goes through the `STARTUPE3` primitive and is
@@ -151,7 +151,7 @@ not drivable in EXTEST (the `CCLK_VIA_STARTUP` quirk on the target).
Send the JEDEC ID command (`0x9F` + 3 dummy bytes):
```
bs_explorer> jtag_spi_rd_wr 9F000000
bs_explorer> jtag_spi_xfer 9F000000
SPI TX: 9F 00 00 00
SPI RX: FF XX YY ZZ # XX YY ZZ identifies the flash vendor/part
```
@@ -223,13 +223,13 @@ end-to-end.
| Symptom | Likely cause |
|---------|--------------|
| `jtag_get_probes_list` returns nothing | FTDI not enumerated. Check `lsusb`, udev permissions, conflicting process. |
| `jtag_probes` returns nothing | FTDI not enumerated. Check `lsusb`, udev permissions, conflicting process. |
| `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 the part to `fpga_registry[]`. |
| `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_rd_wr` is hopelessly slow | That's expected via EXTEST — switch to BSCAN proxy (Phase 2.5). |
| `jtag_spi_xfer` is hopelessly slow | That's expected via EXTEST — switch to BSCAN proxy (Phase 2.5). |
## Where to go from here