#!/usr/bin/env python3
"""Offline helper for the SPI master benchmark.

This script documents the fixed transfer schedule used by the directed
testbench scenarios. It is not imported by the Verilog testbench at runtime.
"""


def transfer_trace(tx_byte: int, rx_byte: int) -> list[tuple[int, str, int, int]]:
    trace = [(0, "accept", tx_byte >> 7 & 1, None)]
    cycle = 0
    for bit in range(7, -1, -1):
        cycle += 1
        trace.append((cycle, f"sample_bit_{bit}", (tx_byte >> bit) & 1, (rx_byte >> bit) & 1))
        if bit != 0:
            cycle += 1
            trace.append((cycle, f"shift_bit_{bit-1}", (tx_byte >> (bit - 1)) & 1, None))
    cycle += 1
    trace.append((cycle, "done", None, None))
    return trace


def main() -> None:
    scenarios = [
        ("primary", 0xA6, 0x5C),
        ("back_to_back_1", 0x3C, 0xC3),
        ("back_to_back_2", 0x81, 0x7E),
    ]

    for name, tx_byte, rx_byte in scenarios:
        print(f"{name}: tx=0x{tx_byte:02X} rx=0x{rx_byte:02X}")
        for cycle, event, mosi, miso in transfer_trace(tx_byte, rx_byte):
            if event == "done":
                print(f"  cycle {cycle:2d}: done")
            elif miso is None:
                print(f"  cycle {cycle:2d}: {event:12s} mosi={mosi}")
            else:
                print(f"  cycle {cycle:2d}: {event:12s} mosi={mosi} sample_miso={miso}")
        print()


if __name__ == "__main__":
    main()