bscan: rename from bscan_spi, add TAP primitives for the SVF player

The module outgrew its "SPI bridge" name — it's mostly generic
single-device JTAG TAP primitives now. Rename modules/bscan_spi ->
modules/bscan (dir, files, library target, includes, doc paths);
bscan_* function names and bscan_spi_xfer() kept.

Add the two primitives the SVF player needs beyond shift_dr:
- bscan_shift_ir: general IR scan with TDO capture (bscan_set_ir is
  opcode-only, no readback)
- bscan_tap_reset: force Test-Logic-Reset, land in Run-Test/Idle

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

modules/bscan/bscan.h

@@ -0,0 +1,69 @@
+#ifndef _BSCAN_H
+#define _BSCAN_H
+
+/*
+ * Single-device JTAG primitives and BSCAN-proxy operations.
+ *
+ * Provides:
+ *   - low-level JTAG TAP primitives (set_ir, shift_ir, shift_dr,
+ *     idle_cycles, tap_reset) that operate directly on jc->io_functions,
+ *     leaving jtag_core untouched. These are the building blocks the SVF
+ *     player and the proxy paths share;
+ *   - bitstream loading via CFG_IN to install a BSCAN proxy in the FPGA
+ *     fabric (Xilinx);
+ *   - a fast SPI transfer routine via USER1 once the proxy is loaded.
+ *
+ * (Was modules/bscan_spi/ — renamed once it grew past the SPI bridge
+ * into general TAP primitives.)
+ *
+ * Current assumption: single device on the JTAG chain. Multi-device
+ * support requires knowing the IR length of bypassed devices; defer.
+ */
+
+#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);
+
+/* Like bscan_shift_dr but through Shift-IR — a general IR scan with TDO
+ * capture (bscan_set_ir is opcode-only). Single-device chain; buffers
+ * LSB-first per byte. Both ends in Run-Test/Idle. */
+int bscan_shift_ir(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);
+
+/* One CS-framed SPI transaction through the BSCAN proxy (USER1 DR):
+ * clock out `txlen` MOSI bytes (e.g. command + address + write data),
+ * then read `rxlen` MISO bytes into `rx`. Either length may be 0.
+ * Bytes are MSB-first on the wire; bit-order juggling is internal.
+ * Follows the quartiq/OpenOCD jtagspi proxy framing. Single-device
+ * chain only. Requires a proxy bitstream already loaded (USER1 live). */
+int bscan_spi_xfer(jtag_core *jc, const fpga_target *t,
+                   const uint8_t *tx, size_t txlen,
+                   uint8_t *rx, size_t rxlen);
+
+#endif