From 952c010c63a8cf09ade101355abaeda366ca2640 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois?= Date: Sat, 23 May 2026 16:33:23 +0200 Subject: [PATCH] script: shorten jtag_* command names 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. --- CLAUDE.md | 2 +- README.md | 22 +++---- doc/tutorial.md | 32 +++++----- .../drivers/digilent_jtag/digilent_jtag_drv.c | 6 +- modules/script/script.c | 58 +++++++++---------- scripts/example_script.txt | 4 +- 6 files changed, 62 insertions(+), 62 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b13b2bd..0354caa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 diff --git a/README.md b/README.md index ebf4017..2a2a1df 100644 --- a/README.md +++ b/README.md @@ -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 -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 0 -bs_explorer> jtag_set_spi_clk_pin 0 0 -bs_explorer> jtag_set_spi_mosi_pin 0 0 -bs_explorer> jtag_set_spi_miso_pin 0 0 +bs_explorer> jtag_spi_cs 0 0 +bs_explorer> jtag_spi_clk 0 0 +bs_explorer> jtag_spi_mosi 0 0 +bs_explorer> jtag_spi_miso 0 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 ` for per-command help. diff --git a/doc/tutorial.md b/doc/tutorial.md index 8d1cf6b..7d5e6ea 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -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 0 -bs_explorer> jtag_set_spi_clk_pin 0 0 -bs_explorer> jtag_set_spi_mosi_pin 0 0 -bs_explorer> jtag_set_spi_miso_pin 0 0 +bs_explorer> jtag_mode 0 EXTEST +bs_explorer> jtag_spi_cs 0 0 +bs_explorer> jtag_spi_clk 0 0 +bs_explorer> jtag_spi_mosi 0 0 +bs_explorer> jtag_spi_miso 0 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 diff --git a/modules/drivers/digilent_jtag/digilent_jtag_drv.c b/modules/drivers/digilent_jtag/digilent_jtag_drv.c index 4fd14e7..651f795 100644 --- a/modules/drivers/digilent_jtag/digilent_jtag_drv.c +++ b/modules/drivers/digilent_jtag/digilent_jtag_drv.c @@ -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); } diff --git a/modules/script/script.c b/modules/script/script.c index 3013d1e..0ea5711 100644 --- a/modules/script/script.c +++ b/modules/script/script.c @@ -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[] = { "(int)", // Arguments "1(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 diff --git a/scripts/example_script.txt b/scripts/example_script.txt index 2d8f69b..d121dd9 100644 --- a/scripts/example_script.txt +++ b/scripts/example_script.txt @@ -1,4 +1,4 @@ -jtag_open_probe 1 +jtag_open 0 jtag_autoinit -jtag_set_mode 0 EXTEST +jtag_mode 0 EXTEST