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

2
CLAUDE.md
View File

@@ -56,7 +56,7 @@ Adding a feature usually means adding a new script command in
Move forward phase by phase: validate one with the user before starting
the next. Don't break the validated path
`jtag_open_probe → jtag_autoinit → jtag_set_mode 0 EXTEST` while
`jtag_open → jtag_autoinit → jtag_mode 0 EXTEST` while
refactoring.
## Key technical decisions

22
README.md
View File

@@ -71,25 +71,25 @@ list of variables.
```sh
# 1. List probes, then open one by its index (the [N] in the list)
bs_explorer> jtag_get_probes_list
bs_explorer> jtag_probes
[0] 0x00000000 <probe description>
bs_explorer> jtag_open_probe 0 # or the raw 0x id shown next to it
bs_explorer> jtag_open 0 # or the raw 0x id shown next to it
# 2. Scan the chain and auto-load BSDL files
bs_explorer> jtag_autoinit
# 3. Switch device 0 to EXTEST (direct pin control)
bs_explorer> jtag_set_mode 0 EXTEST
bs_explorer> jtag_mode 0 EXTEST
# 4. Wire the 4 SPI pins onto the FPGA's BSDL pins
# (exact names depend on the loaded BSDL)
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_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
# 5. Read the flash JEDEC ID (0x9F + 3 dummies)
bs_explorer> jtag_spi_rd_wr 9F000000
bs_explorer> jtag_spi_xfer 9F000000
```
A minimal example script is provided in `scripts/example_script.txt`.
@@ -101,9 +101,9 @@ via BSCAN proxy) lives in [`doc/tutorial.md`](doc/tutorial.md).
| Category | Commands |
|----------|----------|
| Script control | `set`, `print`, `print_env_var`, `if`, `goto`, `call`, `return`, `rand`, `init_array`, `system`, `pause` |
| Probe / chain | `jtag_get_probes_list`, `jtag_open_probe`, `jtag_init_scan`, `jtag_autoinit`, `jtag_get_nb_of_devices`, `jtag_get_devices_list` |
| BSDL / pins | `jtag_load_bsdl`, `jtag_get_pins_list`, `jtag_set_mode`, `jtag_set_pin_dir`, `jtag_set_pin_state`, `jtag_get_pin_state`, `jtag_push_pop` |
| I²C / MDIO / SPI over BS pins | `jtag_set_i2c_*_pin`, `jtag_i2c_rd`, `jtag_i2c_wr`, `jtag_set_mdio_*_pin`, `jtag_mdio_rd`, `jtag_mdio_wr`, `jtag_set_spi_*_pin`, `jtag_spi_rd_wr` |
| 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` |
| Misc | `help`, `?`, `version`, `exit` |
Use `help <command>` for per-command help.

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

6
modules/drivers/digilent_jtag/digilent_jtag_drv.c
View File

@@ -198,7 +198,7 @@ static int drv_Digilent_Detect(jtag_core *jc)
}
/* Release the enumeration table — required before EnumDevices can be
* called again (e.g. a second jtag_get_probes_list / open by index). */
* called again (e.g. a second jtag_probes / open by index). */
g_dj.FreeDvcEnum();
g_dj_num_probes = cdvc;
@@ -214,8 +214,8 @@ static int drv_Digilent_Init(jtag_core *jc, int sub_drv, char *params)
(void)params;
/* Lazy enumeration: jtag_open_probe can be called without going
* through jtag_get_probes_list first, so make sure Detect ran. */
/* Lazy enumeration: jtag_open can be called without going
* through jtag_probes first, so make sure Detect ran. */
if (g_dj_num_probes == 0) {
drv_Digilent_Detect(jc);
}

58
modules/script/script.c
View File

@@ -1736,7 +1736,7 @@ const char *cmd_print_probes_list_help[] = {
"Displays the list of detected probes.", // Explanations
""
};
/* Map the flat index shown by jtag_get_probes_list (0, 1, 2, ...) to the
/* Map the flat index shown by jtag_probes (0, 1, 2, ...) to the
* encoded (drv << 8 | probe) id, walking drivers/probes in the same order
* the list prints them. Returns -1 if the index is out of range. */
static int resolve_flat_probe_index(jtag_core *jc, int flat)
@@ -1776,7 +1776,7 @@ static int cmd_print_probes_list(script_ctx *ctx, char *line)
while (i < nb_of_probes)
{
jtagcore_get_probe_name(jc, PROBE_ID(j, i), probe_list);
// [flat index] is what to pass to jtag_open_probe; the
// [flat index] is what to pass to jtag_open; the
// 0x id after it is the raw form, also accepted.
ctx->script_printf(ctx, MSG_INFO_0, " [%d] 0x%.8X %s\n", flat, PROBE_ID(j, i), probe_list);
flat++;
@@ -1790,7 +1790,7 @@ static int cmd_print_probes_list(script_ctx *ctx, char *line)
const char *cmd_open_probe_help[] = {
"<probe>(int)", // Arguments "1<arg>(type) ..."
"Open a probe by its index from jtag_get_probes_list (0, 1, 2, ...).",
"Open a probe by its index from jtag_probes (0, 1, 2, ...).",
"A raw 0x-prefixed probe id (as printed after the index) also works.",
""
};
@@ -1812,12 +1812,12 @@ static int cmd_open_probe(script_ctx *ctx, char *line)
}
else
{
// Sequential index from jtag_get_probes_list.
// Sequential index from jtag_probes.
id = resolve_flat_probe_index(jc, (int)strtoul(probe_id, NULL, 10));
if (id < 0)
{
ctx->script_printf(ctx, MSG_ERROR,
"No probe at index %s. Run jtag_get_probes_list first.\n", probe_id);
"No probe at index %s. Run jtag_probes first.\n", probe_id);
return JTAG_CORE_BAD_PARAMETER;
}
}
@@ -2657,7 +2657,7 @@ static int cmd_spi_rd_wr(script_ctx *ctx, char *line)
jc = (jtag_core *)ctx->app_ctx;
// jtag_spi_rd_wr 00123344 1 (DATA LSBFirst)
// jtag_spi_xfer 00123344 1 (DATA LSBFirst)
i = get_param(ctx, line, 1, data_out_txt);
j = get_param(ctx, line, 2, lsbfirst);
@@ -2803,7 +2803,7 @@ static int cmd_fpga_list(script_ctx *ctx, char *line)
const char *cmd_fpga_info_help[] = {
"",
"Reports, for each device on the JTAG chain, whether its IDCODE",
"matches a known FPGA target. Requires jtag_init_scan or jtag_autoinit first.",
"matches a known FPGA target. Requires jtag_scan or jtag_autoinit first.",
""};
static int cmd_fpga_info(script_ctx *ctx, char *line)
{
@@ -2967,32 +2967,32 @@ cmd_list script_commands_list[] =
{"return", cmd_return, cmd_return_help},
{"rand", cmd_rand, cmd_rand_help},
{"init_array", cmd_initarray, cmd_initarray_help},
{"jtag_get_probes_list", cmd_print_probes_list, cmd_print_probes_list_help},
{"jtag_open_probe", cmd_open_probe, cmd_open_probe_help},
{"jtag_probes", cmd_print_probes_list, cmd_print_probes_list_help},
{"jtag_open", cmd_open_probe, cmd_open_probe_help},
{"jtag_autoinit", cmd_autoinit, cmd_autoinit_help},
{"jtag_init_scan", cmd_init_and_scan, cmd_init_and_scan_help},
{"jtag_get_nb_of_devices", cmd_print_nb_dev, cmd_print_nb_dev_help},
{"jtag_get_devices_list", cmd_print_devs_list, cmd_print_devs_list_help},
{"jtag_load_bsdl", cmd_load_bsdl, cmd_load_bsdl_help},
{"jtag_set_mode", cmd_set_scan_mode, cmd_set_scan_mode_help},
{"jtag_scan", cmd_init_and_scan, cmd_init_and_scan_help},
{"jtag_ndev", cmd_print_nb_dev, cmd_print_nb_dev_help},
{"jtag_devices", cmd_print_devs_list, cmd_print_devs_list_help},
{"jtag_bsdl", cmd_load_bsdl, cmd_load_bsdl_help},
{"jtag_mode", cmd_set_scan_mode, cmd_set_scan_mode_help},
{"jtag_push_pop", cmd_push_and_pop, cmd_push_and_pop_help},
{"jtag_get_pins_list", cmd_get_pins_list, cmd_get_pins_list_help},
{"jtag_set_pin_dir", cmd_set_pin_mode, cmd_set_pin_mode_help},
{"jtag_set_pin_state", cmd_set_pin_state, cmd_set_pin_state_help},
{"jtag_get_pin_state", cmd_get_pin_state, cmd_get_pin_state_help},
{"jtag_set_i2c_scl_pin", cmd_set_i2c_scl_pin, cmd_set_i2c_scl_help},
{"jtag_set_i2c_sda_pin", cmd_set_i2c_sda_pin, cmd_set_i2c_sda_help},
{"jtag_pins", cmd_get_pins_list, cmd_get_pins_list_help},
{"jtag_pin_dir", cmd_set_pin_mode, cmd_set_pin_mode_help},
{"jtag_pin_set", cmd_set_pin_state, cmd_set_pin_state_help},
{"jtag_pin_get", cmd_get_pin_state, cmd_get_pin_state_help},
{"jtag_i2c_scl", cmd_set_i2c_scl_pin, cmd_set_i2c_scl_help},
{"jtag_i2c_sda", cmd_set_i2c_sda_pin, cmd_set_i2c_sda_help},
{"jtag_i2c_rd", cmd_do_i2c_rd, cmd_do_i2c_wr_help},
{"jtag_i2c_wr", cmd_do_i2c_wr, cmd_do_i2c_rd_help},
{"jtag_set_mdio_mdc_pin", cmd_set_mdio_mdc_pin, cmd_set_mdio_mdc_pin_help},
{"jtag_set_mdio_mdio_pin", cmd_set_mdio_mdio_pin, cmd_set_mdio_mdio_pin_help},
{"jtag_mdio_mdc", cmd_set_mdio_mdc_pin, cmd_set_mdio_mdc_pin_help},
{"jtag_mdio_io", cmd_set_mdio_mdio_pin, cmd_set_mdio_mdio_pin_help},
{"jtag_mdio_rd", cmd_do_mdio_rd, cmd_do_mdio_rd_help},
{"jtag_mdio_wr", cmd_do_mdio_wr, cmd_do_mdio_wr_help},
{"jtag_set_spi_cs_pin", cmd_set_spi_cs_pin, cmd_set_spi_cs_pin_help},
{"jtag_set_spi_mosi_pin", cmd_set_spi_mosi_pin, cmd_set_spi_mosi_pin_help},
{"jtag_set_spi_miso_pin", cmd_set_spi_miso_pin, cmd_set_spi_miso_pin_help},
{"jtag_set_spi_clk_pin", cmd_set_spi_clk_pin, cmd_set_spi_clk_pin_help},
{"jtag_spi_rd_wr", cmd_spi_rd_wr, cmd_spi_rd_wr_help},
{"jtag_spi_cs", cmd_set_spi_cs_pin, cmd_set_spi_cs_pin_help},
{"jtag_spi_mosi", cmd_set_spi_mosi_pin, cmd_set_spi_mosi_pin_help},
{"jtag_spi_miso", cmd_set_spi_miso_pin, cmd_set_spi_miso_pin_help},
{"jtag_spi_clk", cmd_set_spi_clk_pin, cmd_set_spi_clk_pin_help},
{"jtag_spi_xfer", cmd_spi_rd_wr, cmd_spi_rd_wr_help},
{"fpga_list", cmd_fpga_list, cmd_fpga_list_help},
{"fpga_info", cmd_fpga_info, cmd_fpga_info_help},
{"bscan_set_ir", cmd_bscan_set_ir, cmd_bscan_set_ir_help},
@@ -3041,7 +3041,7 @@ int jtagcore_savePinsStateScript(jtag_core *jc, int device, char *script_path)
{
state = jtagcore_get_pin_state(jc, device, i, JTAG_CORE_OE);
fprintf(f, "print Pin %s direction : %d\n", pin_name, state);
fprintf(f, "jtag_set_pin_dir %d %s %d\n", device, pin_name, state);
fprintf(f, "jtag_pin_dir %d %s %d\n", device, pin_name, state);
}
// output data
@@ -3049,7 +3049,7 @@ int jtagcore_savePinsStateScript(jtag_core *jc, int device, char *script_path)
{
state = jtagcore_get_pin_state(jc, device, i, JTAG_CORE_OUTPUT);
fprintf(f, "print Pin %s state : %d\n", pin_name, state);
fprintf(f, "jtag_set_pin_state %d %s %d\n", device, pin_name, state);
fprintf(f, "jtag_pin_set %d %s %d\n", device, pin_name, state);
}
// input data

4
scripts/example_script.txt
View File

@@ -1,4 +1,4 @@
jtag_open_probe 1
jtag_open 0
jtag_autoinit
jtag_set_mode 0 EXTEST
jtag_mode 0 EXTEST