bs_explorer/doc/tutorial.md

# Tutorial — from probe detection to SPI flash

This walks through the full `bs_explorer` flow on a Xilinx Kintex
UltraScale+ KU15P board connected via an FTDI MPSSE probe. The
commands are identical for any FPGA registered in `modules/fpga/`; 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
  bundled).
- An entry for the target in `modules/fpga/fpga.c` (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.

If your board uses a Digilent JTAG-SMT2 / SMT2-NC module (KCU105,
ZCU102, …), you need the optional Digilent backend: install the Adept
Runtime system-wide and configure with `cmake -DBS_ENABLE_DIGILENT=ON
..`. Plain MPSSE does not work on those modules — see the README and
the `Digilent SMT2` block in `CLAUDE.md` for the why.

## Build & launch

```sh
mkdir build && cd build
cmake .. && make
./bs/bs
```

You should see:

```
  Boundary Scan Explorer  v2.6.7.1
  Based on Viveris jtag-boundary-scanner

  3 probe driver(s) available.
  Type 'help' or '?' to list commands, 'exit' or Ctrl-D to quit.
  <Tab> completes commands.

bs_explorer>
```

`<Tab>` completes commands; `help <cmd>` shows per-command help;
Ctrl-D or `exit` quits.

## 1. Detect and open the probe

```
bs_explorer> jtag_probes
  [0]  0x00000000  Digilent USB Device 210308AB06A6
  [1]  0x00000300  Digilent: JtagSmt2NC
```

Open a probe by the index in brackets:

```
bs_explorer> jtag_open 1
```

The `0x…` value next to each index is the raw probe id and is also
accepted (`jtag_open 0x300`) — handy in scripts where you'd rather pin
the exact backend than rely on enumeration order.

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`).

## 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.

```
bs_explorer> jtag_autoinit
```

Expected output for a single-FPGA board:

```
1 device(s) found
Device 0 (04A56093 - XCKU15P_FFVE1517) - BSDL Loaded : ...xcku15p_ffve1517.bsd
```

If the device count is 0 or the IDCODE is `0xFFFFFFFF`/`0x00000000`:
TDI/TDO are likely swapped, TRST not released, or the probe is
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
compile-time registry in `modules/fpga/fpga.c`:

```
bs_explorer> fpga_info
Device 0  IDCODE 0x04A56093  -> Xilinx Kintex UltraScale+ XCKU15P [Xilinx UltraScale+]
           caveat: CCLK routed via STARTUP primitive (not drivable in EXTEST)
```

If you get `not in registry`, add an entry — see
[Adding a new FPGA](#6-add-a-new-fpga-target).

`fpga_list` prints the whole registry without needing a probe.

## 4. (Optional) Sanity-check the low-level JTAG primitives

Before doing anything fancy, you can verify that `bscan_set_ir` and
`bscan_shift_dr` actually move bits correctly on your hardware. Drop
the BSDL state (so `jtag_core` doesn't fight us on IR caching) and
shift IDCODE manually:

```
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
```

Match → primitives are healthy. Mismatch → wiring or clock issue, fix
that before moving on. The opcode and IR length come from the
`fpga_target` (and ultimately the BSDL `INSTRUCTION_OPCODE` block).

## 5. Read the SPI flash JEDEC ID via EXTEST (validation only)

This is the *slow* path — useful to confirm the SPI pins are wired
correctly to the flash, **not** a viable way to flash megabytes. See
[Phase 2.5](#phase-25-spi-through-the-bscan-proxy-bridge-bitstream) for the production path.

Put the FPGA in EXTEST, then map the four SPI signals onto the FPGA's
BSDL pin names:

```
bs_explorer> jtag_autoinit
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_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
not drivable in EXTEST (the `CCLK_VIA_STARTUP` caveat on the target).

Send the JEDEC ID command (`0x9F` + 3 dummy bytes):

```
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
```

This takes several seconds even for 4 bytes — that's the
~30 bytes/sec EXTEST ceiling. Don't try to read the whole flash this
way; you'd be there for weeks.

## 6. Add a new FPGA target

The registry in `modules/fpga/fpga.c` holds the per-part facts that
can't be derived from the BSDL alone (or are tedious to). The XCKU040
entry already there was added exactly with the steps below — use it as
your template.

### a. Drop the BSDL

Put the part's `.bsd` in `bsdl_files/`. Source: Xilinx/AMD device page
under "Design Files / BSDL", Intel in the Quartus install, Lattice per
part. `jtag_autoinit` will then auto-load it by IDCODE.

### b. Pull the facts out of the BSDL

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
```

For the XCKU040 this yields IR length 6, and the private opcodes
`USER1=000010` (0x02), `CFG_IN=000101` (0x05), `JPROGRAM=001011`
(0x0B), `JSTART=001100` (0x0C), etc. The `IDCODE_REGISTER` string is
`XXXX...0010 0000 1001 0011` — the top four bits are the silicon
**revision** and read as `X` (don't-care), which is why the registry
masks them off.

### c. Fill in an `fpga_target`

| Field | What it is | XCKU040 |
|-------|-----------|---------|
| `name` | human-readable label | "Xilinx Kintex UltraScale XCKU040" |
| `idcode` | IDCODE pattern (version nibble as 0) | `0x03822093` |
| `idcode_mask` | bits that must match; `0x0FFFFFFF` ignores the Xilinx revision nibble | `0x0FFFFFFF` |
| `family` | `FPGA_FAMILY_XILINX_7/US/USP` | `FPGA_FAMILY_XILINX_US` |
| `bsdl_filename` | basename in `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 (0 = N/A) | from the BSDL |
| `proxy_bitstream` | BSCAN proxy `.bit` in `bscan_proxies/`, or `NULL` | `"bscan_spi_xcku040.bit"` |
| `caveats` | bit-flags for hardware gotchas (see below) | `FPGA_CAVEAT_CCLK_VIA_STARTUP` |

The resulting entry (verbatim from `fpga.c`):

```c
{
    .name             = "Xilinx Kintex UltraScale XCKU040",
    .idcode           = 0x03822093,
    .idcode_mask      = 0x0FFFFFFF,
    .family           = FPGA_FAMILY_XILINX_US,
    .bsdl_filename    = "xcku040_ffva1156.bsd",
    .ir_length        = 6,
    .ir_cfg_in        = 0x05,
    .ir_user1         = 0x02,
    .ir_jprogram      = 0x0B,
    .ir_jstart        = 0x0C,
    .ir_jshutdown     = 0x0D,
    .ir_isc_disable   = 0x16,
    .proxy_bitstream  = "bscan_spi_xcku040.bit",
    .caveats          = FPGA_CAVEAT_CCLK_VIA_STARTUP,
},
```

### What `caveats` means

`caveats` is a bit-field of `FPGA_CAVEAT_*` flags (in `fpga.h`) marking
**known hardware gotchas that change how the tool must drive the
part**. It is *not* a free-text note — each flag is something the code
(or you) can branch on. Set it to `0` when the part has none you know
of. `fpga_info` prints any flag that is set, as a human-readable line.

Currently one flag exists:

- `FPGA_CAVEAT_CCLK_VIA_STARTUP` — on Xilinx 7-Series / UltraScale /
  UltraScale+, the SPI configuration clock **CCLK is not a normal I/O
  pin**: it is routed through the `STARTUP`/`STARTUPE3` primitive and
  therefore **cannot be toggled in EXTEST** boundary scan. Practical
  effect: the slow EXTEST SPI bit-bang can't clock the flash on these
  parts — you must use the BSCAN proxy (Phase 2.5), where CCLK is driven
  by the fabric internally and the problem disappears. Set this flag for
  any 7-Series/US/US+ part.

To introduce a *new* caveat: add a `#define FPGA_CAVEAT_xxx (1u << n)`
in `fpga.h`, OR it into the relevant entries, and (if it should be
visible) print it in `cmd_fpga_info` in `script.c`.

### d. Rebuild and verify

The registry is compile-time — no runtime registration:

```sh
cd build && make
./bs/bs
bs_explorer> jtag_autoinit
bs_explorer> fpga_info        # should show your part, family, and any caveats
```

## Phase 2.5: SPI through the BSCAN proxy (bridge bitstream)

Talking to the SPI flash via EXTEST is fine for a JEDEC ID but useless
for real flashing (~30 B/s, days to weeks for a config part). The
production path loads a tiny **BSCAN proxy** bitstream into the FPGA
fabric, then runs SPI through the `USER1` instruction at fabric speed
(~50–200 KB/s). The proxy uses a `BSCANE2` primitive to bridge the
`USER1` DR shift to the flash pins, and drives `CCLK` from the fabric
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/`:

```sh
curl -L -o bscan_proxies/bscan_spi_xcku040.bit \
  https://raw.githubusercontent.com/quartiq/bscan_spi_bitstreams/master/bscan_spi_xcku040.bit
```

The registry entry for the part points at this file via its
`proxy_bitstream` field (e.g. the XCKU040 entry → `bscan_spi_xcku040.bit`).

### Load the bridge and talk SPI

```
bs_explorer> jtag_open 1
bs_explorer> jtag_autoinit
bs_explorer> bscan_load_bitstream 0 bscan_proxies/bscan_spi_xcku040.bit
bs_explorer> bscan_jedec 0
JEDEC ID: 20 BB 19  (manufacturer 0x20, device 0xBB19)
```

(Validated on a KCU105: `0x20` = Micron, `0xBB19` = MT25QU256, the
board's 1.8 V 256 Mbit config flash. Other boards will show different
device bytes.)

`bscan_load_bitstream` runs JPROGRAM → CFG_IN → shift → JSTART, which
**reconfigures the FPGA fabric**: the design currently running on the
part is wiped and replaced by the proxy. This is undone by a
power-cycle (the configuration flash reloads the original design at the
next boot), but be aware the board stops doing whatever it was doing.

`bscan_jedec` issues the SPI **Read Identification** command (`0x9F`,
also called RDID) and reads back 3 bytes — the chip's *JEDEC ID*. JEDEC
is the standards body (JESD216 / JEP106) that defines this identifier;
every serial flash answers `0x9F` the same way:

- **byte 0** — manufacturer, a code assigned by JEDEC (`0x20` Micron,
  `0xEF` Winbond, `0xC2` Macronix, `0x01` Cypress/Infineon, `0x9D`
  ISSI, …);
- **bytes 1–2** — device ID (memory type + capacity), vendor-specific.

So the JEDEC ID is how you discover *which* flash is wired up without
prior knowledge — Phase 3 will use it to look the part up in a chip
database and pull its page/sector sizes and command set.

A sane answer here (manufacturer `0x20` = Micron, the KCU105's config
flash) also confirms the whole proxy path end to end: the
`bscan_spi_xfer()` framing, the MSB-first bit order, and the TDO
read-latency skew.

### The transfer primitive

`bscan_spi_xfer(jc, t, tx, txlen, rx, rxlen)` in
`modules/bscan_spi/bscan_spi.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
OpenOCD's `src/flash/nor/jtagspi.c` so the same bitstreams work. Generic
flash `read`/`erase`/`program`/`verify` (Phase 3) will be built on top
of this primitive.

## Troubleshooting cheat sheet

| Symptom | Likely cause |
|---------|--------------|
| `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_xfer` is hopelessly slow | That's expected via EXTEST — switch to BSCAN proxy (Phase 2.5). |

## Where to go from here

- `help` in the REPL lists all commands; `help <cmd>` gives details.
- `CLAUDE.md` at the repo root captures the architecture, roadmap and
  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/`.