# Building a BSCAN SPI proxy bitstream for a Xilinx FPGA

The fast SPI-flash path in `bs_explorer` ([tutorial.md, Phase 2.5](tutorial.md#phase-25-spi-through-the-bscan-proxy-bridge-bitstream))
loads a tiny "BSCAN proxy" bitstream into the FPGA fabric so SPI can run
through the JTAG `USER1` instruction at fabric speed. Pre-built proxies
for many parts ship in [quartiq/bscan_spi_bitstreams](https://github.com/quartiq/bscan_spi_bitstreams)
(MIT) — that repo also contains the **generator** (Migen + Vivado) used
to make them.

For parts the generator doesn't already know — **all of UltraScale+**
(XCKU15P, XCKU3P, XCKU11P, XCZU…, Virtex US+), plus any 7-Series /
UltraScale part missing from its table — you have to add a platform
entry and build the `.bit` yourself. This document walks through that,
using the **Kintex UltraScale+ XCKU15P** as the worked example.

The same recipe applies to any other Xilinx part: only the device
string, package pin LOCs and I/O standard change.

## What you end up doing

1. install Vivado and the quartiq generator's Python deps;
2. add a Migen **platform entry** for your part (the generator picks
   parts out of a hard-coded table — it is *not* just a CLI flag);
3. run the generator, which calls Vivado to synth / place / route into a
   `.bit`;
4. drop the `.bit` into `data/bscan_proxies/` and reference it from
   `data/targets.yaml`;
5. smoke-test on the board.

## Prerequisites

- **Vivado** matching your part's family. UltraScale+ needs Vivado
  2019.2 or newer (2022.2 is what quartiq's README pins). The free
  WebPACK / Standard edition covers the smaller US+ devices like the
  XCKU3P / XCKU11P; larger parts (KU15P included) may need a paid
  Vivado licence. ISE 14.7 only for Spartan-6 and earlier.
- **Python ≥ 3.8** with `venv`, and the Migen revision pinned in the
  generator's `requirements.txt`.
- Roughly 30–80 GB of disk for Vivado, plus a few GB scratch per
  synthesis run.

Confirm Vivado is reachable from your shell:

```sh
source /opt/Xilinx/Vivado/2022.2/settings64.sh
vivado -version       # should print the version
```

## 1. Clone quartiq and install its Python deps

```sh
git clone https://github.com/quartiq/bscan_spi_bitstreams
cd bscan_spi_bitstreams
python3 -m venv --system-site-packages .venv
./.venv/bin/pip install -r requirements.txt
```

`--system-site-packages` lets the venv see a system-wide Migen if one
is installed; drop the flag for a fully isolated venv.

## 2. Add your part to the generator's table

Open `xilinx_bscan_spi.py`. Near the bottom you'll find a table of
`Platform` subclasses, one per supported part, each setting at least:

- `device` — the full Vivado part string, e.g.
  `"xcku15p-ffve1517-2-e"`. Speed grade and temp range matter — copy
  them from your board's schematic or the Vivado project that targets
  the same silicon.
- `toolchain` — `"vivado"` for 7-Series and newer, `"ise"` for older.
- The SPI-flash pin **locations** for the part's *configuration bank*
  (typically `D00_MOSI_0`, `D01_DIN_0`, `FCS_B_0`). **CCLK is not
  declared here** — it is driven inside the FPGA via `STARTUPE3` for
  UltraScale/+ and `STARTUPE2` for 7-Series, which the generator
  already instantiates. (This is exactly what dissolves the
  `cclk_via_startup` caveat described in `CLAUDE.md`.)
- The I/O standard for those pins (`LVCMOS18` for 1.8 V banks like the
  KCU105/KU15P config bank, `LVCMOS25`/`LVCMOS33` otherwise). Wrong
  voltage ⇒ Vivado DRC errors, or worse, damaged I/O on the flash.

Pick the closest existing entry as a template. For the KU15P, the
KU040 entry is the right neighbour: same toolchain (`vivado`), same
`STARTUPE3`, same bank-0 pinout shape. Duplicate it, change:

- the **device string** to your part + package + speed grade;
- the **pin LOCs** if the package differs (e.g. `FFVE1517` vs
  `FFVA1156`);
- the **class name**, and add it to the dispatch dictionary at the
  bottom of the file so a CLI key resolves to your new class.

Cross-check the four pin LOCs against the part's *Package Pin* table
in the Xilinx/AMD datasheet — these pads are board-independent (they
are the hard-wired configuration-bank pins), but the package suffix
changes them.

## 3. Run the generator

```sh
source /opt/Xilinx/Vivado/2022.2/settings64.sh
./.venv/bin/python3 xilinx_bscan_spi.py xcku15p
```

The argument is the **key you added to the dispatch dictionary** in
step 2 — not the raw Vivado part string. The script writes a Migen
build tree, calls Vivado, and on success drops
`bscan_spi_xcku15p.bit` (a few KB — just a `BSCANE2`, a `STARTUPE3`
and a small FSM) in the current directory.

Expect 1–3 minutes on a modern host. A failed run leaves its logs
under `build_xcku15p/`; common culprits:

| Vivado error | Fix |
|--------------|-----|
| `[Place 30-574]` pin LOC not on package | wrong package suffix in `device`, or copied LOCs from a different package |
| `[Drc NSTD-1]` unconstrained I/O | missing I/O standard on a pin → fix the platform entry |
| `Part xcku15p-… is not installed` | install the device support pack in Vivado, or pick a part covered by your licence |
| Vivado not found | forgot to `source settings64.sh` before launching the generator |

## 4. Drop it into bs_explorer

```sh
cp bscan_spi_xcku15p.bit /path/to/bs_explorer/data/bscan_proxies/
```

The directory's `LICENSE.quartiq` (MIT) covers your build too — leave
it in place. Point the registry entry at the new file (this is the
KU15P entry that currently has `proxy_bitstream` omitted in
`data/targets.yaml`):

```yaml
  - name:            "Xilinx Kintex UltraScale+ XCKU15P"
    idcode:          0x04A56093
    idcode_mask:     0x0FFFFFFF
    family:          xilinx_usp
    bsdl:            xcku15p_ffve1517.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_xcku15p.bit   # <-- the file you just built
    caveats:         cclk_via_startup
    prog:            proxy_spi
```

No rebuild — the registry is loaded at runtime.

## 5. Smoke-test on the board

```
bs_explorer> jtag_open 1
bs_explorer> jtag_autoinit
bs_explorer> bscan_load_bitstream 0 data/bscan_proxies/bscan_spi_xcku15p.bit
bs_explorer> bscan_jedec 0
JEDEC ID: 20 BB 19            # or whatever flash your board carries
```

A plausible JEDEC ID — manufacturer byte matching the flash on the
schematic (`0x20` Micron, `0xEF` Winbond, `0xC2` Macronix, `0x01`
Cypress/Infineon, `0x9D` ISSI, …) — confirms the proxy is wired right:
`STARTUPE3` is driving `CCLK`, the `BSCANE2` capture is on `USER1`,
and the four pin LOCs match the physical flash. A `00 00 00` or
`FF FF FF` reply almost always means one of the LOCs is wrong —
re-check the package's configuration-bank pinout.

## Upstreaming (optional)

If your new part is broadly useful — any stock dev-board MPSoC, common
KU/VU/ZU device — the quartiq project takes PRs against
`xilinx_bscan_spi.py`. Once merged, future users get a pre-built
`.bit` and skip this whole document.