#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