phase 2.5: add bscan_spi/ — BSCAN proxy infrastructure

Low-level JTAG primitives operating directly on jc->io_functions
(single-device chain assumed), independent of jtag_core:
- bscan_set_ir
- bscan_shift_dr (TDI/TDO, LSB-first packing)
- bscan_idle_cycles

High-level operations driven by an fpga_target descriptor:
- bscan_load_bitstream: JPROGRAM -> CFG_IN -> shift (bit-reversed for
  Xilinx) -> JSTART -> idle -> BYPASS
- bscan_load_bitstream_file: parses the Xilinx .bit container header
  (sections a/b/c/d/e), falls back to raw .bin

bscan_spi_xfer is stubbed: the quartiq jtagspi protocol details will
be wired once we have a proxy .bit to validate against (OpenOCD
src/flash/nor/jtagspi.c is the host-side reference).

Three new script commands:
- bscan_set_ir <opcode_hex> <ir_length>
- bscan_shift_dr <nbits>  (writes zeros, prints captured TDO)
- bscan_load_bitstream <device> <path>

The sanity check for a healthy primitive on KU15P:
  jtag_init_scan; bscan_set_ir 9 6; bscan_shift_dr 32  ->  04 A5 60 93

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

modules/bscan_spi/bscan_spi.h

@@ -0,0 +1,59 @@
+#ifndef _BSCAN_SPI_H
+#define _BSCAN_SPI_H
+
+/*
+ * BSCAN-proxy SPI bridge (Phase 2.5).
+ *
+ * Provides:
+ *   - low-level JTAG primitives (set_ir, shift_dr, idle_cycles) that
+ *     operate directly on jc->io_functions, leaving jtag_core untouched;
+ *   - bitstream loading via CFG_IN to install a BSCAN proxy in the FPGA
+ *     fabric;
+ *   - a fast SPI transfer routine via USER1 once the proxy is loaded.
+ *
+ * Current assumption: single device on the JTAG chain. Multi-device
+ * support requires knowing the IR length of bypassed devices; defer.
+ *
+ * The SPI transfer entry point is wired against the quartiq jtagspi
+ * proxy convention but the protocol header still needs to be confirmed
+ * against an actual proxy bitstream (see openocd src/flash/nor/jtagspi.c).
+ */
+
+#include <stddef.h>
+#include <stdint.h>
+
+#include "jtag_core/jtag_core.h"
+#include "fpga/fpga.h"
+
+/* --- Low-level primitives (single-device chain) -------------------- */
+
+/* Shift `opcode` into IR. `ir_length` is the IR width in bits. */
+int bscan_set_ir(jtag_core *jc, unsigned int opcode, int ir_length);
+
+/* Shift `nbits` through DR. `tdi` may be NULL (shifts zeros).
+ * `tdo` may be NULL (write only). Both buffers are LSB-first per byte. */
+int bscan_shift_dr(jtag_core *jc, const uint8_t *tdi, uint8_t *tdo, int nbits);
+
+/* Emit `ncycles` TCK cycles while staying in Run-Test/Idle. */
+int bscan_idle_cycles(jtag_core *jc, int ncycles);
+
+/* --- High-level operations ---------------------------------------- */
+
+/* Load a raw bitstream payload (no .bit container header) into the
+ * FPGA via JPROGRAM -> CFG_IN -> shift -> JSTART. Bit-reverses each
+ * byte before shifting (Xilinx convention). */
+int bscan_load_bitstream(jtag_core *jc, const fpga_target *t,
+                         const uint8_t *data, size_t nbytes);
+
+/* Convenience wrapper: read a file and load it. Detects the Xilinx
+ * .bit header and skips it; otherwise treats the file as raw payload. */
+int bscan_load_bitstream_file(jtag_core *jc, const fpga_target *t,
+                              const char *path);
+
+/* Transfer `nbytes` of SPI data through the BSCAN proxy (USER1 DR).
+ * Placeholder: protocol details deferred until an actual proxy
+ * bitstream is available for testing. */
+int bscan_spi_xfer(jtag_core *jc, const fpga_target *t,
+                   const uint8_t *tx, uint8_t *rx, size_t nbytes);
+
+#endif