MOSI Capture and Bit Counting

   if (cap_stb) sr <= {sr[MAX_W-2:0], mosi_q};

   counter reset by the assert          counter that just rolls over
   ---------------------------------    ------------------------------------
   the pin defines word boundaries      the counter defines word boundaries
   a lost edge shifts the rest of       a lost edge shifts the rest of the
     the transaction                      transaction, identically
   the NEXT transaction is correct      the next transaction is also correct,
                                          because the assert happens to reset
                                          it anyway in most designs
   the authority is external and        the authority is internal and cannot
     cannot be wrong about framing        notice that it is wrong

   POLARITY mismatch    DETECTABLE FROM A LEVEL
                        SCLK is not at the configured idle level when chip
                        select asserts. Caught before a single bit has moved.

   PHASE mismatch       DETECTABLE FROM A MOTION, and NOT from the edge count
                        A mismatched pair still exchanges a whole number of
                        frames. What gives it away is that MOSI is changing at
                        the instant the slave samples it.

   BIT-ORDER mismatch   NOT DETECTABLE AT ALL
                        Both orders produce a well-formed word of the right
                        length at the right time. There is no observation the
                        slave can make that distinguishes them.

   rx_data          the completed word, right-aligned in MAX_W bits
   rx_valid_stb     one cycle, WITH valid data on rx_data
   bit_idx          the position within the word in progress
   words_in_txn     how many complete words this transaction has produced
   rx_partial_sr    the word IN PROGRESS, right-aligned as far as it has got

// spi_slave_rx.sv
//
// Chapter 14.3 -- capturing MOSI, and counting bits that cannot be recounted.
//
// The capture itself is one line. Everything interesting is about the COUNTER,
// and about what the slave can and cannot detect when the counter is wrong.
//
// THE COUNTER IS CLEARED BY THE TRANSACTION, AND BY THE WORD BOUNDARY IT
// DERIVES FROM IT -- AND BY NOTHING ELSE.
//
// Chapter 14.2 established that chip select is the only framing SPI has, so the
// bit position within a transaction is (edges since assert) / 2. This block
// counts captures rather than edges, which is the same number divided by two,
// and it takes its zero from `txn_start_stb`. A counter that rolled over on
// `len` without any reference to the select pin would be asserting that its own
// arithmetic defines the word boundary -- and if it were ever wrong it would
// stay wrong for the rest of the assertion, because there is nothing in the data
// stream to resynchronise against.
//
// WHAT THE SLAVE CAN DETECT, AND WHAT IT CANNOT. This is the taxonomy worth
// carrying out of the chapter, because the three mismatches look identical from
// the system side and need completely different responses:
//
//   POLARITY mismatch   DETECTABLE FROM A LEVEL. SCLK is not at the configured idle
//                       level when chip select asserts (Chapter 14.6).
//   PHASE mismatch      DETECTABLE FROM A MOTION, and NOT from the edge count: a
//                       mismatched pair still exchanges a whole number of frames.
//                       What gives it away is that MOSI is changing at the instant
//                       the slave samples it (Chapter 14.6).
//   BIT-ORDER mismatch  NOT DETECTABLE AT ALL. Both orders produce a well-formed
//                       word of the right length at the right time. There is no
//                       observation the slave can make that distinguishes them, so
//                       it must be configured correctly and there is nothing to
//                       report.
//
// A SLIP IS ALSO NOT DETECTABLE FROM THE DATA. If an edge is lost -- the failure
// Chapter 14.1's precondition exists to prevent -- every subsequent word in the
// transaction is shifted by one bit. The words are still the right length and
// still arrive at the right times, because their boundaries come from a counter
// that is itself wrong. Only the edge count of Chapter 14.2 reveals it, and only
// at the END of the transaction. That asymmetry is why the edge count is
// published at all.
//
// BIT ORDER IS THE SAME TRANSFORM THE MASTER USES. Reversing the low `len` bits
// is its own inverse (Chapter 13.8), so the slave applies exactly the function
// the master applies, on the boundary rather than in the shift path. There is no
// second implementation to keep in step.

module spi_slave_rx #(
    parameter int MAX_W = 32,
    parameter int LEN_W = 6,
    parameter int CNT_W = 12
) (
    input  wire              clk,
    input  wire              rst_n,

    // --- from 14.2 ---------------------------------------------------------
    input  wire              txn_active,
    input  wire              txn_start_stb,

    // --- the capture strobe, from the mode logic of 14.6 -------------------
    input  wire              cap_stb,
    input  wire              mosi_q,       // delay-matched, from 14.1

    // --- configuration -----------------------------------------------------
    input  wire [LEN_W-1:0]  len,
    input  wire              lsb_first,

    // --- the received words ------------------------------------------------
    output wire [MAX_W-1:0]  rx_data,
    output reg               rx_valid_stb,  // one cycle, WITH valid data
    output wire [LEN_W-1:0]  bit_idx,       // captures into the current word
    output wire [CNT_W-1:0]  words_in_txn,
    // The word IN PROGRESS, right-aligned as far as it has got. Published because
    // Chapter 14.7 has to be able to report a partial, and the only alternative is
    // for 14.7 to duplicate the shift register -- two copies of the same state,
    // which is one more than can be kept correct.
    output wire [MAX_W-1:0]  rx_partial_sr
);

    reg [MAX_W-1:0] rx_sr;
    reg [MAX_W-1:0] rx_hold;
    reg [LEN_W-1:0] bits;
    reg [CNT_W-1:0] words;

    assign bit_idx       = bits;
    assign words_in_txn  = words;
    assign rx_partial_sr = rx_sr;

    // A fixed full-width reversal: pure wiring, no logic.
    function automatic [MAX_W-1:0] rev_all(input [MAX_W-1:0] x);
        integer b;
        begin
            rev_all = {MAX_W{1'b0}};
            for (b = 0; b < MAX_W; b = b + 1)
                rev_all[b] = x[MAX_W-1-b];
        end
    endfunction

    // Reverse the low `len` bits, zero above -- its own inverse, and the same
    // function the master applies (Chapter 13.8).
    wire [MAX_W-1:0] rx_rev = rev_all(rx_hold) >> (MAX_W - len);

    assign rx_data = lsb_first ? rx_rev : rx_hold;

    // The word completes on the capture that brings the count to len-1, so this
    // is the LAST capture of the word rather than the cycle after it.
    wire last_cap = cap_stb & txn_active & (bits == (len - 1'b1));

    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            rx_sr        <= {MAX_W{1'b0}};
            rx_hold      <= {MAX_W{1'b0}};
            bits         <= {LEN_W{1'b0}};
            words        <= {CNT_W{1'b0}};
            rx_valid_stb <= 1'b0;
        end else begin
            // Delayed by one cycle, deliberately: the final bit reaches `rx_sr`
            // on the same edge that sees the last capture, so on that cycle the
            // word is one bit short. Pulsing valid there means "good next
            // cycle", which every consumer gets wrong once (Chapter 13.6).
            rx_valid_stb <= last_cap;

            if (txn_start_stb) begin
                // The transaction's zero. Chapter 14.2's rule, applied here.
                rx_sr <= {MAX_W{1'b0}};
                bits  <= {LEN_W{1'b0}};
                words <= {CNT_W{1'b0}};
            end else if (cap_stb && txn_active) begin
                // Bits arrive at the bottom and walk up, so after `len` captures
                // the word is already right-aligned with zeros above -- no
                // alignment shift on this side, the same asymmetry as the
                // master's datapath.
                rx_sr <= {rx_sr[MAX_W-2:0], mosi_q};

                if (bits == (len - 1'b1)) begin
                    // The completed word is copied out and the shift register is
                    // CLEARED, not merely overwritten. A frame narrower than the
                    // datapath does not overwrite the bits above it, and a
                    // transaction of several narrow words would otherwise carry
                    // the previous word's bits in the positions above the
                    // current one.
                    rx_hold <= {rx_sr[MAX_W-2:0], mosi_q};
                    rx_sr   <= {MAX_W{1'b0}};
                    bits    <= {LEN_W{1'b0}};
                    words   <= words + 1'b1;
                end else begin
                    bits <= bits + 1'b1;
                end
            end
        end
    end

`ifdef SPI_CHECKS
    always_ff @(posedge clk) if (rst_n) begin
        if (cap_stb && !txn_active && txn_active !== 1'bx)
            $fatal(1, "a capture strobe arrived with no transaction open");
        if (bits >= len && len != {LEN_W{1'b0}})
            $fatal(1, "the bit index reached the frame width");
    end
`endif

endmodule

// spi_slave_rx.v
//
// Chapter 14.3 -- capturing MOSI, and counting bits that cannot be recounted.
//
// The capture itself is one line. Everything interesting is about the COUNTER,
// and about what the slave can and cannot detect when the counter is wrong.
//
// THE COUNTER IS CLEARED BY THE TRANSACTION, AND BY THE WORD BOUNDARY IT
// DERIVES FROM IT -- AND BY NOTHING ELSE.
//
// Chapter 14.2 established that chip select is the only framing SPI has, so the
// bit position within a transaction is (edges since assert) / 2. This block
// counts captures rather than edges, which is the same number divided by two,
// and it takes its zero from `txn_start_stb`. A counter that rolled over on
// `len` without any reference to the select pin would be asserting that its own
// arithmetic defines the word boundary -- and if it were ever wrong it would
// stay wrong for the rest of the assertion, because there is nothing in the data
// stream to resynchronise against.
//
// WHAT THE SLAVE CAN DETECT, AND WHAT IT CANNOT. This is the taxonomy worth
// carrying out of the chapter, because the three mismatches look identical from
// the system side and need completely different responses:
//
//   POLARITY mismatch   DETECTABLE FROM A LEVEL. SCLK is not at the configured idle
//                       level when chip select asserts (Chapter 14.6).
//   PHASE mismatch      DETECTABLE FROM A MOTION, and NOT from the edge count: a
//                       mismatched pair still exchanges a whole number of frames.
//                       What gives it away is that MOSI is changing at the instant
//                       the slave samples it (Chapter 14.6).
//   BIT-ORDER mismatch  NOT DETECTABLE AT ALL. Both orders produce a well-formed
//                       word of the right length at the right time. There is no
//                       observation the slave can make that distinguishes them, so
//                       it must be configured correctly and there is nothing to
//                       report.
//
// A SLIP IS ALSO NOT DETECTABLE FROM THE DATA. If an edge is lost -- the failure
// Chapter 14.1's precondition exists to prevent -- every subsequent word in the
// transaction is shifted by one bit. The words are still the right length and
// still arrive at the right times, because their boundaries come from a counter
// that is itself wrong. Only the edge count of Chapter 14.2 reveals it, and only
// at the END of the transaction. That asymmetry is why the edge count is
// published at all.
//
// BIT ORDER IS THE SAME TRANSFORM THE MASTER USES. Reversing the low `len` bits
// is its own inverse (Chapter 13.8), so the slave applies exactly the function
// the master applies, on the boundary rather than in the shift path. There is no
// second implementation to keep in step.

module spi_slave_rx #(
    parameter MAX_W = 32,
    parameter LEN_W = 6,
    parameter CNT_W = 12
) (
    input  wire              clk,
    input  wire              rst_n,

    // --- from 14.2 ---------------------------------------------------------
    input  wire              txn_active,
    input  wire              txn_start_stb,

    // --- the capture strobe, from the mode logic of 14.6 -------------------
    input  wire              cap_stb,
    input  wire              mosi_q,       // delay-matched, from 14.1

    // --- configuration -----------------------------------------------------
    input  wire [LEN_W-1:0]  len,
    input  wire              lsb_first,

    // --- the received words ------------------------------------------------
    output wire [MAX_W-1:0]  rx_data,
    output reg               rx_valid_stb,  // one cycle, WITH valid data
    output wire [LEN_W-1:0]  bit_idx,       // captures into the current word
    output wire [CNT_W-1:0]  words_in_txn,
    // The word IN PROGRESS, right-aligned as far as it has got. Published because
    // Chapter 14.7 has to be able to report a partial, and the only alternative is
    // for 14.7 to duplicate the shift register -- two copies of the same state,
    // which is one more than can be kept correct.
    output wire [MAX_W-1:0]  rx_partial_sr
);

    reg [MAX_W-1:0] rx_sr;
    reg [MAX_W-1:0] rx_hold;
    reg [LEN_W-1:0] bits;
    reg [CNT_W-1:0] words;

    assign bit_idx       = bits;
    assign words_in_txn  = words;
    assign rx_partial_sr = rx_sr;

    // A fixed full-width reversal: pure wiring, no logic.
        function [MAX_W-1:0] rev_all;
        input [MAX_W-1:0] x;
        integer b;
        begin
            rev_all = {MAX_W{1'b0}};
            for (b = 0; b < MAX_W; b = b + 1)
                rev_all[b] = x[MAX_W-1-b];
        end
    endfunction

    // Reverse the low `len` bits, zero above -- its own inverse, and the same
    // function the master applies (Chapter 13.8).
    wire [MAX_W-1:0] rx_rev = rev_all(rx_hold) >> (MAX_W - len);

    assign rx_data = lsb_first ? rx_rev : rx_hold;

    // The word completes on the capture that brings the count to len-1, so this
    // is the LAST capture of the word rather than the cycle after it.
    wire last_cap = cap_stb & txn_active & (bits == (len - 1'b1));

    always @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            rx_sr        <= {MAX_W{1'b0}};
            rx_hold      <= {MAX_W{1'b0}};
            bits         <= {LEN_W{1'b0}};
            words        <= {CNT_W{1'b0}};
            rx_valid_stb <= 1'b0;
        end else begin
            // Delayed by one cycle, deliberately: the final bit reaches `rx_sr`
            // on the same edge that sees the last capture, so on that cycle the
            // word is one bit short. Pulsing valid there means "good next
            // cycle", which every consumer gets wrong once (Chapter 13.6).
            rx_valid_stb <= last_cap;

            if (txn_start_stb) begin
                // The transaction's zero. Chapter 14.2's rule, applied here.
                rx_sr <= {MAX_W{1'b0}};
                bits  <= {LEN_W{1'b0}};
                words <= {CNT_W{1'b0}};
            end else if (cap_stb && txn_active) begin
                // Bits arrive at the bottom and walk up, so after `len` captures
                // the word is already right-aligned with zeros above -- no
                // alignment shift on this side, the same asymmetry as the
                // master's datapath.
                rx_sr <= {rx_sr[MAX_W-2:0], mosi_q};

                if (bits == (len - 1'b1)) begin
                    // The completed word is copied out and the shift register is
                    // CLEARED, not merely overwritten. A frame narrower than the
                    // datapath does not overwrite the bits above it, and a
                    // transaction of several narrow words would otherwise carry
                    // the previous word's bits in the positions above the
                    // current one.
                    rx_hold <= {rx_sr[MAX_W-2:0], mosi_q};
                    rx_sr   <= {MAX_W{1'b0}};
                    bits    <= {LEN_W{1'b0}};
                    words   <= words + 1'b1;
                end else begin
                    bits <= bits + 1'b1;
                end
            end
        end
    end

`ifdef SPI_CHECKS
    always @(posedge clk) if (rst_n) begin
        if (cap_stb && !txn_active && txn_active !== 1'bx)
            $fatal(1, "a capture strobe arrived with no transaction open");
        if (bits >= len && len != {LEN_W{1'b0}})
            $fatal(1, "the bit index reached the frame width");
    end
`endif

endmodule

-- spi_slave_rx.vhd
--
-- Chapter 14.3 -- capturing MOSI, and counting bits that cannot be recounted.
--
-- The capture itself is one line. Everything interesting is about the COUNTER,
-- and about what the slave can and cannot detect when the counter is wrong.
--
-- THE COUNTER IS CLEARED BY THE TRANSACTION, AND BY THE WORD BOUNDARY IT DERIVES
-- FROM IT -- AND BY NOTHING ELSE.
--
-- Chapter 14.2 established that chip select is the only framing SPI has, so the
-- bit position within a transaction is (edges since assert) / 2. This block counts
-- captures, which is the same number divided by two, and takes its zero from
-- `txn_start_stb`. A counter that rolled over on `len` without any reference to
-- the select pin would be asserting that its own arithmetic defines the word
-- boundary -- and if it were ever wrong it would stay wrong for the rest of the
-- assertion, because there is nothing in the data stream to resynchronise against.
--
-- WHAT THE SLAVE CAN DETECT, AND WHAT IT CANNOT. The three mismatches look
-- identical from the system side and need completely different responses:
--
--   POLARITY mismatch   DETECTABLE FROM A LEVEL. SCLK is not at the configured idle
--                       level when chip select asserts (Chapter 14.6).
--   PHASE mismatch      DETECTABLE FROM A MOTION, and NOT from the edge count: a
--                       mismatched pair still exchanges a whole number of frames.
--                       What gives it away is that MOSI is changing at the instant
--                       the slave samples it (Chapter 14.6).
--   BIT-ORDER mismatch  NOT DETECTABLE AT ALL. Both orders produce a well-formed
--                       word of the right length at the right time. There is no
--                       observation the slave can make that distinguishes them, so
--                       it must be configured correctly and there is nothing to
--                       report.
--
-- A SLIP IS ALSO NOT DETECTABLE FROM THE DATA. If an edge is lost -- the failure
-- Chapter 14.1's precondition exists to prevent -- every subsequent word in the
-- transaction is shifted by one bit. The words are still the right length and
-- still arrive at the right times, because their boundaries come from a counter
-- that is itself wrong. Only the edge count of Chapter 14.2 reveals it, and only
-- at the END of the transaction. That asymmetry is why the edge count is published.
--
-- BIT ORDER IS THE SAME TRANSFORM THE MASTER USES. Reversing the low `len` bits is
-- its own inverse (Chapter 13.8), so the slave applies exactly the function the
-- master applies, on the boundary rather than in the shift path.

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

entity spi_slave_rx is
    generic (
        MAX_W : positive := 32;
        LEN_W : positive := 6;
        CNT_W : positive := 12
    );
    port (
        clk           : in  std_logic;
        rst_n         : in  std_logic;

        -- from 14.2
        txn_active    : in  std_logic;
        txn_start_stb : in  std_logic;

        -- the capture strobe, from the mode logic of 14.6
        cap_stb       : in  std_logic;
        mosi_q        : in  std_logic;   -- delay-matched, from 14.1

        -- configuration
        len           : in  unsigned(LEN_W - 1 downto 0);
        lsb_first     : in  std_logic;

        -- the received words
        rx_data       : out std_logic_vector(MAX_W - 1 downto 0);
        rx_valid_stb  : out std_logic;   -- one cycle, WITH valid data
        bit_idx       : out unsigned(LEN_W - 1 downto 0);
        words_in_txn  : out unsigned(CNT_W - 1 downto 0);
        -- The word IN PROGRESS, right-aligned as far as it has got. Published
        -- because Chapter 14.7 has to be able to report a partial, and the only
        -- alternative is for 14.7 to duplicate the shift register -- two copies of
        -- the same state, which is one more than can be kept correct.
        rx_partial_sr : out std_logic_vector(MAX_W - 1 downto 0)
    );
end entity;

architecture rtl of spi_slave_rx is

    signal rx_sr   : std_logic_vector(MAX_W - 1 downto 0) := (others => '0');
    signal rx_hold : std_logic_vector(MAX_W - 1 downto 0) := (others => '0');
    signal bits    : unsigned(LEN_W - 1 downto 0) := (others => '0');
    signal words   : unsigned(CNT_W - 1 downto 0) := (others => '0');
    signal valid_r : std_logic := '0';

    signal last_cap : std_logic;

    -- A fixed full-width reversal: pure wiring, no logic.
    function rev_all(x : std_logic_vector(MAX_W - 1 downto 0))
        return std_logic_vector is
        variable r : std_logic_vector(MAX_W - 1 downto 0);
    begin
        for b in 0 to MAX_W - 1 loop
            r(b) := x(MAX_W - 1 - b);
        end loop;
        return r;
    end function;

    signal n_bits : natural;
    signal rx_rev : std_logic_vector(MAX_W - 1 downto 0);

begin

    bit_idx       <= bits;
    words_in_txn  <= words;
    rx_partial_sr <= rx_sr;
    rx_valid_stb <= valid_r;

    -- Clamped so the shift amount stays in range while an illegal width is being
    -- presented: an out-of-range shift is an undefined result, not an error, and
    -- an undefined value propagating into a data path turns a configuration
    -- mistake into an intermittent corruption.
    n_bits <= 1 when len = 0
              else MAX_W when to_integer(len) > MAX_W
              else to_integer(len);

    -- Reverse the low `len` bits, zero above -- its own inverse, and the same
    -- function the master applies (Chapter 13.8).
    rx_rev  <= std_logic_vector(shift_right(unsigned(rev_all(rx_hold)),
                                           MAX_W - n_bits));
    rx_data <= rx_rev when lsb_first = '1' else rx_hold;

    -- The word completes on the capture that brings the count to len-1, so this
    -- is the LAST capture of the word rather than the cycle after it.
    last_cap <= '1' when (cap_stb = '1' and txn_active = '1' and
                          bits = (len - 1)) else '0';

    capture : process (clk, rst_n)
    begin
        if rst_n = '0' then
            rx_sr   <= (others => '0');
            rx_hold <= (others => '0');
            bits    <= (others => '0');
            words   <= (others => '0');
            valid_r <= '0';
        elsif rising_edge(clk) then
            -- Delayed by one cycle, deliberately: the final bit reaches `rx_sr` on
            -- the same edge that sees the last capture, so on that cycle the word
            -- is one bit short. Pulsing valid there means "good next cycle", which
            -- every consumer gets wrong once (Chapter 13.6).
            valid_r <= last_cap;

            if txn_start_stb = '1' then
                -- The transaction's zero. Chapter 14.2's rule, applied here.
                rx_sr <= (others => '0');
                bits  <= (others => '0');
                words <= (others => '0');
            elsif cap_stb = '1' and txn_active = '1' then
                -- Bits arrive at the bottom and walk up, so after `len` captures
                -- the word is already right-aligned with zeros above -- no
                -- alignment shift on this side, the same asymmetry as the
                -- master's datapath.
                if bits = (len - 1) then
                    -- The completed word is copied out and the shift register is
                    -- CLEARED, not merely overwritten. A frame narrower than the
                    -- datapath does not overwrite the bits above it, and a
                    -- transaction of several narrow words would otherwise carry
                    -- the previous word's bits in the positions above this one.
                    rx_hold <= rx_sr(MAX_W - 2 downto 0) & mosi_q;
                    rx_sr   <= (others => '0');
                    bits    <= (others => '0');
                    words   <= words + 1;
                else
                    rx_sr <= rx_sr(MAX_W - 2 downto 0) & mosi_q;
                    bits  <= bits + 1;
                end if;
            end if;
        end if;
    end process;

    check : process (clk)
    begin
        if rising_edge(clk) and rst_n = '1' then
            assert not (cap_stb = '1' and txn_active = '0')
                report "a capture strobe arrived with no transaction open"
                severity failure;
            assert not (bits >= len and len /= 0)
                report "the bit index reached the frame width" severity failure;
        end if;
    end process;

end architecture;

// spi_slave_rx_tb.sv
//
// The real front end of 14.1 and the real transaction detector of 14.2 sit in
// front of the block under test, so every capture is a recovered one and the word
// boundaries come from the select pin exactly as they will in the finished slave.
//
// Two properties get most of the attention because both are invisible to the
// obvious test:
//
//   NARROW WORDS IN SEQUENCE. A five-bit word followed by another five-bit word
//   must not carry the first word's bits in the positions above the second's. A
//   suite whose words are all as wide as the datapath cannot fail this, and a
//   suite whose narrow words are all identical cannot either.
//
//   THE WORD COUNT MUST AGREE WITH THE EDGE COUNT. Chapter 14.2 counts edges and
//   this block counts captures; they are the same number divided by two. If they
//   ever disagree, one of them has invented a boundary -- which is the failure
//   14.2's rule exists to prevent, and the only place it can be observed is here,
//   where both numbers exist at once.

`timescale 1ns/1ps

module spi_slave_rx_tb;

    localparam int MAX_W = 32;
    localparam int LEN_W = 6;
    localparam int CNT_W = 12;

    logic clk = 1'b0;
    logic rst_n = 1'b0;
    always #5 clk = ~clk;

    // --- 14.1 ---------------------------------------------------------------
    logic cpol     = 1'b0;
    logic sclk_pin = 1'b0;
    logic cs_n_pin = 1'b1;
    logic mosi_pin = 1'b0;

    wire        sclk_q, cs_active, mosi_q;
    wire        edge_a_stb, edge_b_stb;
    wire        cs_assert_stb, cs_deassert_stb;
    wire [11:0] min_half;
    wire        ratio_err;

    spi_slave_frontend #(.SYNC_N(2), .HALF_MIN(3), .CNT_W(12)) u_fe (
        .clk(clk), .rst_n(rst_n), .cpol(cpol),
        .sclk_pin(sclk_pin), .cs_n_pin(cs_n_pin), .mosi_pin(mosi_pin),
        .sclk_q(sclk_q), .cs_active(cs_active), .mosi_q(mosi_q),
        .edge_a_stb(edge_a_stb), .edge_b_stb(edge_b_stb),
        .cs_assert_stb(cs_assert_stb), .cs_deassert_stb(cs_deassert_stb),
        .min_half(min_half), .ratio_err(ratio_err), .clr_flags(1'b0)
    );

    // --- 14.2 ---------------------------------------------------------------
    logic [LEN_W-1:0] len       = 6'd8;
    logic             lsb_first = 1'b0;
    logic             cpha_now  = 1'b0;

    wire             txn_active, txn_start_stb, txn_end_stb;
    wire [CNT_W-1:0] edges_in_txn, frames_in_txn;
    wire             txn_clean, txn_trunc, txn_empty, txn_report_stb;
    wire [2:0]       cs_state;

    spi_slave_cs #(.LEN_W(LEN_W), .CNT_W(CNT_W)) u_cs (
        .clk(clk), .rst_n(rst_n),
        .cs_assert_stb(cs_assert_stb), .cs_deassert_stb(cs_deassert_stb),
        .edge_a_stb(edge_a_stb), .edge_b_stb(edge_b_stb), .len(len),
        .txn_active(txn_active), .txn_start_stb(txn_start_stb),
        .txn_end_stb(txn_end_stb),
        .edges_in_txn(edges_in_txn), .frames_in_txn(frames_in_txn),
        .txn_clean(txn_clean), .txn_trunc(txn_trunc), .txn_empty(txn_empty),
        .txn_report_stb(txn_report_stb), .state_id(cs_state)
    );

    // The mode logic is Chapter 14.6; here the phase simply selects which
    // recovered edge is the capture.
    wire cap_stb = txn_active & (cpha_now ? edge_b_stb : edge_a_stb);

    // --- 14.3, the block under test ----------------------------------------
    wire [MAX_W-1:0] rx_data;
    wire             rx_valid_stb;
    wire [LEN_W-1:0] bit_idx;
    wire [CNT_W-1:0] words_in_txn;
    wire [MAX_W-1:0] rx_partial_sr;

    spi_slave_rx #(.MAX_W(MAX_W), .LEN_W(LEN_W), .CNT_W(CNT_W)) dut (
        .clk(clk), .rst_n(rst_n),
        .txn_active(txn_active), .txn_start_stb(txn_start_stb),
        .cap_stb(cap_stb), .mosi_q(mosi_q),
        .len(len), .lsb_first(lsb_first),
        .rx_data(rx_data), .rx_valid_stb(rx_valid_stb),
        .bit_idx(bit_idx), .words_in_txn(words_in_txn),
        .rx_partial_sr(rx_partial_sr)
    );

    // --- the expectation ----------------------------------------------------
    integer seed;
    logic [MAX_W-1:0] exp_q [0:63];
    integer exp_w, got_w;
    integer word_bad, upper_bad, valid_at_wrong_time;
    integer n_valid;

    always_ff @(posedge clk) begin
        if (rst_n) begin
            if (txn_start_stb) begin
                got_w <= 0;
            end
            if (rx_valid_stb) begin
                n_valid <= n_valid + 1;
                if (got_w < exp_w) begin
                    if (rx_data !== exp_q[got_w]) word_bad <= word_bad + 1;
                    // Nothing above the frame width, ever. This is the property
                    // a narrow word following another narrow word breaks.
                    if (len < MAX_W && (rx_data >> len) != {MAX_W{1'b0}})
                        upper_bad <= upper_bad + 1;
                end else begin
                    valid_at_wrong_time <= valid_at_wrong_time + 1;
                end
                got_w <= got_w + 1;
            end
        end
    end

    integer errors = 0;

    task automatic adv(input integer n);
        begin repeat (n) @(negedge clk); end
    endtask

    task automatic clear_exp;
        begin
            exp_w = 0; got_w = 0;
        end
    endtask

    // Drives a whole transaction of `nwords` words of `nbits` bits, in the given
    // mode, with the bit order the SLAVE is configured for -- so what goes on the
    // wire is the order that configuration implies, and the received word must
    // come back equal to the value sent.
    task automatic drive_txn(input integer half, input bit pol, input bit pha,
                             input integer nbits, input integer nwords,
                             input bit lsb);
        integer w, i, seedl;
        logic [MAX_W-1:0] word;
        logic             b;
        begin
            cpol      = pol;
            cpha_now  = pha;
            len       = nbits[LEN_W-1:0];
            lsb_first = lsb;
            sclk_pin  = pol;
            cs_n_pin  = 1'b1;
            adv(8);
            clear_exp();

            cs_n_pin = 1'b0;
            adv(4);

            for (w = 0; w < nwords; w = w + 1) begin
                seed = (seed * 32'h0019_660D) + 32'h3C6E_F35F;
                word = seed & ((nbits >= 32) ? 32'hFFFF_FFFF
                                             : ((32'h1 << nbits) - 1));
                exp_q[exp_w] = word;
                exp_w = exp_w + 1;

                for (i = 0; i < nbits; i = i + 1) begin
                    // The wire carries the configured order: bit i of the word
                    // first when LSB-first, bit nbits-1-i first otherwise.
                    b = lsb ? word[i] : word[nbits-1-i];

                    if (!pha) begin
                        // Capture is on the leading edge, so the bit must be on
                        // the wire before it -- driven at CS assert for the first
                        // bit and on the trailing edge for the rest.
                        mosi_pin = b;
                        adv(2);
                        sclk_pin = ~pol;      // leading: captured here
                        adv(half);
                        sclk_pin = pol;       // trailing
                        adv(half - 2 < 1 ? 1 : half - 2);
                    end else begin
                        sclk_pin = ~pol;      // leading: launch
                        mosi_pin = b;
                        adv(half);
                        sclk_pin = pol;       // trailing: captured here
                        adv(half);
                    end
                end
            end

            adv(4);
            cs_n_pin = 1'b1;
            adv(8);
            sclk_pin = pol;
            adv(8);
        end
    endtask

    integer h, p, o, nb, nw, k;

    initial begin
        exp_w = 0; got_w = 0; n_valid = 0;
        word_bad = 0; upper_bad = 0; valid_at_wrong_time = 0;
        seed = 32'h0C4F_7E21;

        adv(3);
        rst_n = 1'b1;
        adv(2);

        // 1. ONE BYTE, MSB-first, mode 0. The simplest thing that can work.
        drive_txn(4, 1'b0, 1'b0, 8, 1, 1'b0);
        if (got_w != 1) begin
            $display("  FAIL: one byte produced %0d received words", got_w);
            errors = errors + 1;
        end
        $display("  one byte, mode 0, MSB-first: received %02h and expected %02h",
                 rx_data[7:0], exp_q[0][7:0]);

        // 2. SEVERAL WORDS IN ONE TRANSACTION, in order. The word boundary comes
        //    from a counter whose zero is the select pin, so a transaction of
        //    four words must produce four words and the fourth must not be the
        //    first one's bits shifted.
        drive_txn(4, 1'b0, 1'b0, 8, 4, 1'b0);
        if (got_w != 4) begin
            $display("  FAIL: four bytes produced %0d received words", got_w);
            errors = errors + 1;
        end
        if (words_in_txn != 4 || frames_in_txn != 4) begin
            $display("  FAIL: the capture counter says %0d words and the edge counter says %0d frames",
                     words_in_txn, frames_in_txn);
            errors = errors + 1;
        end
        $display("  four bytes in one transaction: four words received in order, and the capture and edge counters agree");

        // 3. NARROW WORDS IN SEQUENCE. Five-bit words, one after another, with
        //    different values -- the case where a receive register that is not
        //    cleared at the word boundary carries the previous word's bits above
        //    the current one.
        drive_txn(4, 1'b0, 1'b0, 5, 6, 1'b0);
        if (got_w != 6) begin
            $display("  FAIL: six five-bit words produced %0d", got_w);
            errors = errors + 1;
        end
        $display("  six five-bit words in one transaction: each right-aligned with nothing above bit 4");

        // 4. BOTH BIT ORDERS. The wire carries a different sequence in each, so
        //    a slave that ignored the setting would return the bit-reverse.
        drive_txn(4, 1'b0, 1'b0, 8, 3, 1'b0);
        drive_txn(4, 1'b0, 1'b0, 8, 3, 1'b1);
        $display("  both bit orders returned the value that was sent, which a slave ignoring the setting could not do");

        // 5. THE SWEEP. Widths from 1 to 32, both orders, both phases, several
        //    ratios, multi-word transactions.
        for (o = 0; o <= 1; o = o + 1)
            for (p = 0; p <= 1; p = p + 1)
                for (h = 2; h <= 6; h = h + 2) begin
                    drive_txn(h, 1'b0, p[0], 1,  3, o[0]);
                    drive_txn(h, 1'b0, p[0], 2,  3, o[0]);
                    drive_txn(h, 1'b0, p[0], 5,  3, o[0]);
                    drive_txn(h, 1'b0, p[0], 8,  3, o[0]);
                    drive_txn(h, 1'b0, p[0], 13, 2, o[0]);
                    drive_txn(h, 1'b0, p[0], 32, 2, o[0]);
                end
        $display("  %0d words swept: widths 1, 2, 5, 8, 13 and 32, both bit orders, both phases, three ratios",
                 n_valid);

        // 6. A TRANSACTION THAT ENDS MID-WORD. The completed words must be
        //    unaffected and the partial count must be readable -- the policy for
        //    what to DO with it is Chapter 14.7's.
        len = 6'd8; lsb_first = 1'b0; cpha_now = 1'b0;
        adv(2);
        clear_exp();
        // The bits driven below are k[0] for k = 0..10, so the first eight --
        // 0 1 0 1 0 1 0 1 read MSB-first -- are 0x55. Registering it matters:
        // an unexpected word and a missing word are different failures, and a
        // monitor that cannot tell them apart reports the wrong one.
        exp_q[0] = 32'h55;
        exp_w    = 1;
        cpol = 1'b0; sclk_pin = 1'b0; cs_n_pin = 1'b1; adv(8);
        cs_n_pin = 1'b0; adv(4);
        // one complete byte, then three bits of a second
        for (k = 0; k < 11; k = k + 1) begin
            mosi_pin = k[0];
            adv(2);
            sclk_pin = 1'b1; adv(4);
            sclk_pin = 1'b0; adv(2);
        end
        adv(4);
        if (bit_idx != 3) begin
            $display("  FAIL: after 11 bits the partial count was %0d, expected 3",
                     bit_idx);
            errors = errors + 1;
        end
        if (words_in_txn != 1) begin
            $display("  FAIL: after 11 bits %0d words completed, expected 1",
                     words_in_txn);
            errors = errors + 1;
        end
        cs_n_pin = 1'b1; adv(8); sclk_pin = 1'b0; adv(8);
        if (!txn_trunc) begin
            $display("  FAIL: a transaction ending mid-word was not reported truncated");
            errors = errors + 1;
        end
        $display("  a transaction of 11 bits at eight bits per word: one complete word, a partial count of 3, and the transaction reported truncated");

        // 7. THE CONTINUOUS PROPERTIES.
        if (word_bad != 0) begin
            $display("  FAIL: %0d of %0d received words were wrong",
                     word_bad, n_valid);
            errors = errors + 1;
        end
        if (upper_bad != 0) begin
            $display("  FAIL: %0d words carried bits above the frame width",
                     upper_bad);
            errors = errors + 1;
        end
        if (valid_at_wrong_time != 0) begin
            $display("  FAIL: %0d words arrived that nothing was sent for",
                     valid_at_wrong_time);
            errors = errors + 1;
        end
        $display("  %0d received words, none wrong, none carrying bits above its width, and none unaccounted for",
                 n_valid);

        if (errors == 0)
            $display("PASS: MOSI is captured on the mode's capture edge and assembled into words whose boundaries come from a counter cleared by the select pin, so nothing the slave counts can redefine where a word ends -- all %0d words across widths of 1, 2, 5, 8, 13 and 32 bits, both bit orders, both phases and three frequency ratios came back exactly as sent, every one right-aligned with nothing above its width even when narrow words of differing values followed one another, the capture counter and the edge counter of Chapter 14.2 agree on every transaction, and a transaction ending mid-word leaves its completed words intact with a readable partial count and is reported as truncated", n_valid);
        else
            $display("FAIL: %0d error(s)", errors);
        $finish;
    end

endmodule

// spi_slave_rx_tb.v
//
// The real front end of 14.1 and the real transaction detector of 14.2 sit in
// front of the block under test, so every capture is a recovered one and the word
// boundaries come from the select pin exactly as they will in the finished slave.
//
// Two properties get most of the attention because both are invisible to the
// obvious test:
//
//   NARROW WORDS IN SEQUENCE. A five-bit word followed by another five-bit word
//   must not carry the first word's bits in the positions above the second's. A
//   suite whose words are all as wide as the datapath cannot fail this, and a
//   suite whose narrow words are all identical cannot either.
//
//   THE WORD COUNT MUST AGREE WITH THE EDGE COUNT. Chapter 14.2 counts edges and
//   this block counts captures; they are the same number divided by two. If they
//   ever disagree, one of them has invented a boundary -- which is the failure
//   14.2's rule exists to prevent, and the only place it can be observed is here,
//   where both numbers exist at once.

`timescale 1ns/1ps

module spi_slave_rx_tb;

    localparam MAX_W = 32;
    localparam LEN_W = 6;
    localparam CNT_W = 12;

    reg clk;
    reg rst_n;
    always #5 clk = ~clk;

    // --- 14.1 ---------------------------------------------------------------
    reg cpol;
    reg sclk_pin;
    reg cs_n_pin;
    reg mosi_pin;

    wire        sclk_q, cs_active, mosi_q;
    wire        edge_a_stb, edge_b_stb;
    wire        cs_assert_stb, cs_deassert_stb;
    wire [11:0] min_half;
    wire        ratio_err;

    spi_slave_frontend #(.SYNC_N(2), .HALF_MIN(3), .CNT_W(12)) u_fe (
        .clk(clk), .rst_n(rst_n), .cpol(cpol),
        .sclk_pin(sclk_pin), .cs_n_pin(cs_n_pin), .mosi_pin(mosi_pin),
        .sclk_q(sclk_q), .cs_active(cs_active), .mosi_q(mosi_q),
        .edge_a_stb(edge_a_stb), .edge_b_stb(edge_b_stb),
        .cs_assert_stb(cs_assert_stb), .cs_deassert_stb(cs_deassert_stb),
        .min_half(min_half), .ratio_err(ratio_err), .clr_flags(1'b0)
    );

    // --- 14.2 ---------------------------------------------------------------
    reg [LEN_W-1:0] len;
    reg             lsb_first;
    reg             cpha_now;

    wire             txn_active, txn_start_stb, txn_end_stb;
    wire [CNT_W-1:0] edges_in_txn, frames_in_txn;
    wire             txn_clean, txn_trunc, txn_empty, txn_report_stb;
    wire [2:0]       cs_state;

    spi_slave_cs #(.LEN_W(LEN_W), .CNT_W(CNT_W)) u_cs (
        .clk(clk), .rst_n(rst_n),
        .cs_assert_stb(cs_assert_stb), .cs_deassert_stb(cs_deassert_stb),
        .edge_a_stb(edge_a_stb), .edge_b_stb(edge_b_stb), .len(len),
        .txn_active(txn_active), .txn_start_stb(txn_start_stb),
        .txn_end_stb(txn_end_stb),
        .edges_in_txn(edges_in_txn), .frames_in_txn(frames_in_txn),
        .txn_clean(txn_clean), .txn_trunc(txn_trunc), .txn_empty(txn_empty),
        .txn_report_stb(txn_report_stb), .state_id(cs_state)
    );

    // The mode logic is Chapter 14.6; here the phase simply selects which
    // recovered edge is the capture.
    wire cap_stb = txn_active & (cpha_now ? edge_b_stb : edge_a_stb);

    // --- 14.3, the block under test ----------------------------------------
    wire [MAX_W-1:0] rx_data;
    wire             rx_valid_stb;
    wire [LEN_W-1:0] bit_idx;
    wire [CNT_W-1:0] words_in_txn;
    wire [MAX_W-1:0] rx_partial_sr;

    spi_slave_rx #(.MAX_W(MAX_W), .LEN_W(LEN_W), .CNT_W(CNT_W)) dut (
        .clk(clk), .rst_n(rst_n),
        .txn_active(txn_active), .txn_start_stb(txn_start_stb),
        .cap_stb(cap_stb), .mosi_q(mosi_q),
        .len(len), .lsb_first(lsb_first),
        .rx_data(rx_data), .rx_valid_stb(rx_valid_stb),
        .bit_idx(bit_idx), .words_in_txn(words_in_txn),
        .rx_partial_sr(rx_partial_sr)
    );

    // --- the expectation ----------------------------------------------------
    integer seed;
    reg [MAX_W-1:0] exp_q [0:63];
    integer exp_w, got_w;
    integer word_bad, upper_bad, valid_at_wrong_time;
    integer n_valid;

    always @(posedge clk) begin
        if (rst_n) begin
            if (txn_start_stb) begin
                got_w <= 0;
            end
            if (rx_valid_stb) begin
                n_valid <= n_valid + 1;
                if (got_w < exp_w) begin
                    if (rx_data !== exp_q[got_w]) word_bad <= word_bad + 1;
                    // Nothing above the frame width, ever. This is the property
                    // a narrow word following another narrow word breaks.
                    if (len < MAX_W && (rx_data >> len) != {MAX_W{1'b0}})
                        upper_bad <= upper_bad + 1;
                end else begin
                    valid_at_wrong_time <= valid_at_wrong_time + 1;
                end
                got_w <= got_w + 1;
            end
        end
    end

    integer errors;

        task adv;
        input integer n;
        begin repeat (n) @(negedge clk); end
    endtask

    task clear_exp;
        begin
            exp_w = 0; got_w = 0;
        end
    endtask

    // Drives a whole transaction of `nwords` words of `nbits` bits, in the given
    // mode, with the bit order the SLAVE is configured for -- so what goes on the
    // wire is the order that configuration implies, and the received word must
    // come back equal to the value sent.
        task drive_txn;
        input integer half;
        input pol;
        input pha;
        input integer nbits;
        input integer nwords;
        input lsb;
        integer w, i, seedl;
        reg [MAX_W-1:0] word;
        reg             b;
        begin
            cpol      = pol;
            cpha_now  = pha;
            len       = nbits[LEN_W-1:0];
            lsb_first = lsb;
            sclk_pin  = pol;
            cs_n_pin  = 1'b1;
            adv(8);
            clear_exp();

            cs_n_pin = 1'b0;
            adv(4);

            for (w = 0; w < nwords; w = w + 1) begin
                seed = (seed * 32'h0019_660D) + 32'h3C6E_F35F;
                word = seed & ((nbits >= 32) ? 32'hFFFF_FFFF
                                             : ((32'h1 << nbits) - 1));
                exp_q[exp_w] = word;
                exp_w = exp_w + 1;

                for (i = 0; i < nbits; i = i + 1) begin
                    // The wire carries the configured order: bit i of the word
                    // first when LSB-first, bit nbits-1-i first otherwise.
                    b = lsb ? word[i] : word[nbits-1-i];

                    if (!pha) begin
                        // Capture is on the leading edge, so the bit must be on
                        // the wire before it -- driven at CS assert for the first
                        // bit and on the trailing edge for the rest.
                        mosi_pin = b;
                        adv(2);
                        sclk_pin = ~pol;      // leading: captured here
                        adv(half);
                        sclk_pin = pol;       // trailing
                        adv(half - 2 < 1 ? 1 : half - 2);
                    end else begin
                        sclk_pin = ~pol;      // leading: launch
                        mosi_pin = b;
                        adv(half);
                        sclk_pin = pol;       // trailing: captured here
                        adv(half);
                    end
                end
            end

            adv(4);
            cs_n_pin = 1'b1;
            adv(8);
            sclk_pin = pol;
            adv(8);
        end
    endtask

    integer h, p, o, nb, nw, k;

    initial begin
        exp_w = 0; got_w = 0; n_valid = 0;
        word_bad = 0; upper_bad = 0; valid_at_wrong_time = 0;
        seed = 32'h0C4F_7E21;

        adv(3);
        rst_n = 1'b1;
        adv(2);

        // 1. ONE BYTE, MSB-first, mode 0. The simplest thing that can work.
        drive_txn(4, 1'b0, 1'b0, 8, 1, 1'b0);
        if (got_w != 1) begin
            $display("  FAIL: one byte produced %0d received words", got_w);
            errors = errors + 1;
        end
        $display("  one byte, mode 0, MSB-first: received %02h and expected %02h",
                 rx_data[7:0], exp_q[0][7:0]);

        // 2. SEVERAL WORDS IN ONE TRANSACTION, in order. The word boundary comes
        //    from a counter whose zero is the select pin, so a transaction of
        //    four words must produce four words and the fourth must not be the
        //    first one's bits shifted.
        drive_txn(4, 1'b0, 1'b0, 8, 4, 1'b0);
        if (got_w != 4) begin
            $display("  FAIL: four bytes produced %0d received words", got_w);
            errors = errors + 1;
        end
        if (words_in_txn != 4 || frames_in_txn != 4) begin
            $display("  FAIL: the capture counter says %0d words and the edge counter says %0d frames",
                     words_in_txn, frames_in_txn);
            errors = errors + 1;
        end
        $display("  four bytes in one transaction: four words received in order, and the capture and edge counters agree");

        // 3. NARROW WORDS IN SEQUENCE. Five-bit words, one after another, with
        //    different values -- the case where a receive register that is not
        //    cleared at the word boundary carries the previous word's bits above
        //    the current one.
        drive_txn(4, 1'b0, 1'b0, 5, 6, 1'b0);
        if (got_w != 6) begin
            $display("  FAIL: six five-bit words produced %0d", got_w);
            errors = errors + 1;
        end
        $display("  six five-bit words in one transaction: each right-aligned with nothing above bit 4");

        // 4. BOTH BIT ORDERS. The wire carries a different sequence in each, so
        //    a slave that ignored the setting would return the bit-reverse.
        drive_txn(4, 1'b0, 1'b0, 8, 3, 1'b0);
        drive_txn(4, 1'b0, 1'b0, 8, 3, 1'b1);
        $display("  both bit orders returned the value that was sent, which a slave ignoring the setting could not do");

        // 5. THE SWEEP. Widths from 1 to 32, both orders, both phases, several
        //    ratios, multi-word transactions.
        for (o = 0; o <= 1; o = o + 1)
            for (p = 0; p <= 1; p = p + 1)
                for (h = 2; h <= 6; h = h + 2) begin
                    drive_txn(h, 1'b0, p[0], 1,  3, o[0]);
                    drive_txn(h, 1'b0, p[0], 2,  3, o[0]);
                    drive_txn(h, 1'b0, p[0], 5,  3, o[0]);
                    drive_txn(h, 1'b0, p[0], 8,  3, o[0]);
                    drive_txn(h, 1'b0, p[0], 13, 2, o[0]);
                    drive_txn(h, 1'b0, p[0], 32, 2, o[0]);
                end
        $display("  %0d words swept: widths 1, 2, 5, 8, 13 and 32, both bit orders, both phases, three ratios",
                 n_valid);

        // 6. A TRANSACTION THAT ENDS MID-WORD. The completed words must be
        //    unaffected and the partial count must be readable -- the policy for
        //    what to DO with it is Chapter 14.7's.
        len = 6'd8; lsb_first = 1'b0; cpha_now = 1'b0;
        adv(2);
        clear_exp();
        // The bits driven below are k[0] for k = 0..10, so the first eight --
        // 0 1 0 1 0 1 0 1 read MSB-first -- are 0x55. Registering it matters:
        // an unexpected word and a missing word are different failures, and a
        // monitor that cannot tell them apart reports the wrong one.
        exp_q[0] = 32'h55;
        exp_w    = 1;
        cpol = 1'b0; sclk_pin = 1'b0; cs_n_pin = 1'b1; adv(8);
        cs_n_pin = 1'b0; adv(4);
        // one complete byte, then three bits of a second
        for (k = 0; k < 11; k = k + 1) begin
            mosi_pin = k[0];
            adv(2);
            sclk_pin = 1'b1; adv(4);
            sclk_pin = 1'b0; adv(2);
        end
        adv(4);
        if (bit_idx != 3) begin
            $display("  FAIL: after 11 bits the partial count was %0d, expected 3",
                     bit_idx);
            errors = errors + 1;
        end
        if (words_in_txn != 1) begin
            $display("  FAIL: after 11 bits %0d words completed, expected 1",
                     words_in_txn);
            errors = errors + 1;
        end
        cs_n_pin = 1'b1; adv(8); sclk_pin = 1'b0; adv(8);
        if (!txn_trunc) begin
            $display("  FAIL: a transaction ending mid-word was not reported truncated");
            errors = errors + 1;
        end
        $display("  a transaction of 11 bits at eight bits per word: one complete word, a partial count of 3, and the transaction reported truncated");

        // 7. THE CONTINUOUS PROPERTIES.
        if (word_bad != 0) begin
            $display("  FAIL: %0d of %0d received words were wrong",
                     word_bad, n_valid);
            errors = errors + 1;
        end
        if (upper_bad != 0) begin
            $display("  FAIL: %0d words carried bits above the frame width",
                     upper_bad);
            errors = errors + 1;
        end
        if (valid_at_wrong_time != 0) begin
            $display("  FAIL: %0d words arrived that nothing was sent for",
                     valid_at_wrong_time);
            errors = errors + 1;
        end
        $display("  %0d received words, none wrong, none carrying bits above its width, and none unaccounted for",
                 n_valid);

        if (errors == 0)
            $display("PASS: MOSI is captured on the mode's capture edge and assembled into words whose boundaries come from a counter cleared by the select pin, so nothing the slave counts can redefine where a word ends -- all %0d words across widths of 1, 2, 5, 8, 13 and 32 bits, both bit orders, both phases and three frequency ratios came back exactly as sent, every one right-aligned with nothing above its width even when narrow words of differing values followed one another, the capture counter and the edge counter of Chapter 14.2 agree on every transaction, and a transaction ending mid-word leaves its completed words intact with a readable partial count and is reported as truncated", n_valid);
        else
            $display("FAIL: %0d error(s)", errors);
        $finish;
    end


    initial begin
        clk = 1'b0;
        rst_n = 1'b0;
        cpol = 1'b0;
        sclk_pin = 1'b0;
        cs_n_pin = 1'b1;
        mosi_pin = 1'b0;
        len = 6'd8;
        lsb_first = 1'b0;
        cpha_now = 1'b0;
        errors = 0;
    end

endmodule

-- spi_slave_rx_tb.vhd
--
-- The real front end of 14.1 and the real transaction detector of 14.2 sit in
-- front of the block under test, so every capture is a recovered one and the word
-- boundaries come from the select pin exactly as they will in the finished slave.
--
-- Two properties get most of the attention because both are invisible to the
-- obvious test:
--
--   NARROW WORDS IN SEQUENCE. A five-bit word followed by another five-bit word
--   must not carry the first word's bits in the positions above the second's. A
--   suite whose words are all as wide as the datapath cannot fail this, and one
--   whose narrow words are all identical cannot either.
--
--   THE WORD COUNT MUST AGREE WITH THE EDGE COUNT. Chapter 14.2 counts edges and
--   this block counts captures; they are the same number divided by two. If they
--   ever disagree, one of them has invented a boundary -- and the only place that
--   can be observed is here, where both numbers exist at once.

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

entity spi_slave_rx_tb is
end entity;

architecture sim of spi_slave_rx_tb is

    constant MAX_W : positive := 32;
    constant LEN_W : positive := 6;
    constant CNT_W : positive := 12;

    type word_array is array (0 to 63) of std_logic_vector(MAX_W - 1 downto 0);

    signal clk   : std_logic := '0';
    signal rst_n : std_logic := '0';
    signal halt  : boolean   := false;

    signal cpol     : std_logic := '0';
    signal sclk_pin : std_logic := '0';
    signal cs_n_pin : std_logic := '1';
    signal mosi_pin : std_logic := '0';

    signal sclk_q, cs_active, mosi_q : std_logic;
    signal edge_a_stb, edge_b_stb    : std_logic;
    signal cs_assert_stb, cs_deassert_stb : std_logic;
    signal min_half  : unsigned(11 downto 0);
    signal ratio_err : std_logic;

    signal len       : unsigned(LEN_W - 1 downto 0) := to_unsigned(8, LEN_W);
    signal lsb_first : std_logic := '0';
    signal cpha_now  : std_logic := '0';

    signal txn_active, txn_start_stb, txn_end_stb : std_logic;
    signal edges_in_txn, frames_in_txn : unsigned(CNT_W - 1 downto 0);
    signal txn_clean, txn_trunc, txn_empty, txn_report_stb : std_logic;
    signal cs_state : unsigned(2 downto 0);

    signal cap_stb : std_logic;

    signal rx_data      : std_logic_vector(MAX_W - 1 downto 0);
    signal rx_valid_stb : std_logic;
    signal bit_idx      : unsigned(LEN_W - 1 downto 0);
    signal words_in_txn : unsigned(CNT_W - 1 downto 0);
    signal rx_partial_sr : std_logic_vector(MAX_W - 1 downto 0);

    signal exp_q : word_array := (others => (others => '0'));
    signal exp_w : natural := 0;
    signal got_w : natural := 0;
    signal word_bad, upper_bad, valid_at_wrong_time, n_valid : natural := 0;

    signal errors : natural := 0;

    function hex8(v : std_logic_vector) return string is
        constant DIGITS : string(1 to 16) := "0123456789abcdef";
        variable u : unsigned(MAX_W - 1 downto 0);
        variable r : string(1 to 8);
    begin
        u := unsigned(v);
        for k in 8 downto 1 loop
            r(k) := DIGITS(to_integer(u(3 downto 0)) + 1);
            u := shift_right(u, 4);
        end loop;
        return r;
    end function;

begin

    clk <= not clk after 5 ns when not halt else '0';

    u_fe : entity work.spi_slave_frontend
        generic map (SYNC_N => 2, HALF_MIN => 3, CNT_W => 12)
        port map (clk => clk, rst_n => rst_n, cpol => cpol,
                  sclk_pin => sclk_pin, cs_n_pin => cs_n_pin,
                  mosi_pin => mosi_pin,
                  sclk_q => sclk_q, cs_active => cs_active, mosi_q => mosi_q,
                  edge_a_stb => edge_a_stb, edge_b_stb => edge_b_stb,
                  cs_assert_stb => cs_assert_stb,
                  cs_deassert_stb => cs_deassert_stb,
                  min_half => min_half, ratio_err => ratio_err,
                  clr_flags => '0');

    u_cs : entity work.spi_slave_cs
        generic map (LEN_W => LEN_W, CNT_W => CNT_W)
        port map (clk => clk, rst_n => rst_n,
                  cs_assert_stb => cs_assert_stb,
                  cs_deassert_stb => cs_deassert_stb,
                  edge_a_stb => edge_a_stb, edge_b_stb => edge_b_stb,
                  len => len,
                  txn_active => txn_active, txn_start_stb => txn_start_stb,
                  txn_end_stb => txn_end_stb,
                  edges_in_txn => edges_in_txn, frames_in_txn => frames_in_txn,
                  txn_clean => txn_clean, txn_trunc => txn_trunc,
                  txn_empty => txn_empty,
                  txn_report_stb => txn_report_stb, state_id => cs_state);

    -- The mode logic is Chapter 14.6; here the phase simply selects which
    -- recovered edge is the capture.
    cap_stb <= txn_active and edge_b_stb when cpha_now = '1'
               else txn_active and edge_a_stb;

    dut : entity work.spi_slave_rx
        generic map (MAX_W => MAX_W, LEN_W => LEN_W, CNT_W => CNT_W)
        port map (clk => clk, rst_n => rst_n,
                  txn_active => txn_active, txn_start_stb => txn_start_stb,
                  cap_stb => cap_stb, mosi_q => mosi_q,
                  len => len, lsb_first => lsb_first,
                  rx_data => rx_data, rx_valid_stb => rx_valid_stb,
                  bit_idx => bit_idx, words_in_txn => words_in_txn,
                  rx_partial_sr => rx_partial_sr);

    monitor : process (clk)
        variable above : std_logic_vector(MAX_W - 1 downto 0);
    begin
        if rising_edge(clk) then
            if rst_n = '1' then
                if txn_start_stb = '1' then
                    got_w <= 0;
                end if;
                if rx_valid_stb = '1' then
                    n_valid <= n_valid + 1;
                    if got_w < exp_w then
                        if rx_data /= exp_q(got_w) then
                            word_bad <= word_bad + 1;
                        end if;
                        -- Nothing above the frame width, ever. This is the
                        -- property a narrow word following another breaks.
                        if to_integer(len) < MAX_W then
                            above := std_logic_vector(
                                        shift_right(unsigned(rx_data),
                                                    to_integer(len)));
                            if above /= (above'range => '0') then
                                upper_bad <= upper_bad + 1;
                            end if;
                        end if;
                    else
                        valid_at_wrong_time <= valid_at_wrong_time + 1;
                    end if;
                    got_w <= got_w + 1;
                end if;
            end if;
        end if;
    end process;

    stim : process
        variable errs : natural := 0;
        variable seed : unsigned(31 downto 0) := x"0C4F7E21";
        variable word : std_logic_vector(MAX_W - 1 downto 0);
        variable b    : std_logic;
        variable mask : unsigned(MAX_W - 1 downto 0);

        procedure adv(n : natural) is
        begin
            for k in 1 to n loop wait until falling_edge(clk); end loop;
        end procedure;

        -- Only `exp_w` is cleared here. `got_w` belongs to the monitor process
        -- and is cleared there on the transaction start: VHDL resolves multiple
        -- drivers rather than letting the last writer win, so a signal written
        -- from both processes has no defined value at all.
        procedure clear_exp is
        begin
            exp_w <= 0;
        end procedure;

        -- Drives a whole transaction of `nwords` words of `nbits` bits, in the
        -- given mode, with the bit order the SLAVE is configured for -- so what
        -- goes on the wire is the order that configuration implies.
        procedure drive_txn(half : natural; pol : std_logic; pha : std_logic;
                            nbits : natural; nwords : natural;
                            lsb : std_logic) is
            variable n_exp : natural := 0;
        begin
            cpol      <= pol;
            cpha_now  <= pha;
            len       <= to_unsigned(nbits, LEN_W);
            lsb_first <= lsb;
            sclk_pin  <= pol;
            cs_n_pin  <= '1';
            adv(8);
            clear_exp;
            n_exp := 0;

            cs_n_pin <= '0';
            adv(4);

            for w in 0 to nwords - 1 loop
                seed := resize(seed * x"0019660D", 32) + x"3C6EF35F";
                mask := (others => '0');
                for k in 0 to MAX_W - 1 loop
                    if k < nbits then mask(k) := '1'; end if;
                end loop;
                word := std_logic_vector(seed and mask);
                exp_q(n_exp) <= word;
                n_exp := n_exp + 1;
                exp_w <= n_exp;

                for i in 0 to nbits - 1 loop
                    if lsb = '1' then
                        b := word(i);
                    else
                        b := word(nbits - 1 - i);
                    end if;

                    if pha = '0' then
                        -- Capture is on the leading edge, so the bit must be on
                        -- the wire before it.
                        mosi_pin <= b;
                        adv(2);
                        sclk_pin <= not pol;      -- leading: captured here
                        adv(half);
                        sclk_pin <= pol;          -- trailing
                        if half > 2 then adv(half - 2); else adv(1); end if;
                    else
                        sclk_pin <= not pol;      -- leading: launch
                        mosi_pin <= b;
                        adv(half);
                        sclk_pin <= pol;          -- trailing: captured here
                        adv(half);
                    end if;
                end loop;
            end loop;

            adv(4);
            cs_n_pin <= '1';
            adv(8);
            sclk_pin <= pol;
            adv(8);
        end procedure;

        variable pha_v, lsb_v : std_logic;
    begin
        adv(3);
        rst_n <= '1';
        adv(2);

        -- 1. ONE BYTE, MSB-first, mode 0.
        drive_txn(4, '0', '0', 8, 1, '0');
        if got_w /= 1 then
            report "  FAIL: one byte produced " & integer'image(got_w) &
                   " received words";
            errs := errs + 1;
        end if;
        report "  one byte, mode 0, MSB-first: received " & hex8(rx_data) &
               " and expected " & hex8(exp_q(0));

        -- 2. SEVERAL WORDS IN ONE TRANSACTION, in order.
        drive_txn(4, '0', '0', 8, 4, '0');
        if got_w /= 4 then
            report "  FAIL: four bytes produced " & integer'image(got_w) &
                   " received words";
            errs := errs + 1;
        end if;
        if to_integer(words_in_txn) /= 4 or to_integer(frames_in_txn) /= 4 then
            report "  FAIL: the capture counter says " &
                   integer'image(to_integer(words_in_txn)) &
                   " words and the edge counter says " &
                   integer'image(to_integer(frames_in_txn)) & " frames";
            errs := errs + 1;
        end if;
        report "  four bytes in one transaction: four words received in order, and the capture and edge counters agree";

        -- 3. NARROW WORDS IN SEQUENCE.
        drive_txn(4, '0', '0', 5, 6, '0');
        if got_w /= 6 then
            report "  FAIL: six five-bit words produced " &
                   integer'image(got_w);
            errs := errs + 1;
        end if;
        report "  six five-bit words in one transaction: each right-aligned with nothing above bit 4";

        -- 4. BOTH BIT ORDERS.
        drive_txn(4, '0', '0', 8, 3, '0');
        drive_txn(4, '0', '0', 8, 3, '1');
        report "  both bit orders returned the value that was sent, which a slave ignoring the setting could not do";

        -- 5. THE SWEEP.
        for o in 0 to 1 loop
            if o = 1 then lsb_v := '1'; else lsb_v := '0'; end if;
            for p in 0 to 1 loop
                if p = 1 then pha_v := '1'; else pha_v := '0'; end if;
                for h in 1 to 3 loop
                    drive_txn(h * 2, '0', pha_v, 1,  3, lsb_v);
                    drive_txn(h * 2, '0', pha_v, 2,  3, lsb_v);
                    drive_txn(h * 2, '0', pha_v, 5,  3, lsb_v);
                    drive_txn(h * 2, '0', pha_v, 8,  3, lsb_v);
                    drive_txn(h * 2, '0', pha_v, 13, 2, lsb_v);
                    drive_txn(h * 2, '0', pha_v, 32, 2, lsb_v);
                end loop;
            end loop;
        end loop;
        report "  " & integer'image(n_valid) &
               " words swept: widths 1, 2, 5, 8, 13 and 32, both bit orders, both phases, three ratios";

        -- 6. A TRANSACTION THAT ENDS MID-WORD.
        len <= to_unsigned(8, LEN_W);
        lsb_first <= '0';
        cpha_now  <= '0';
        adv(2);
        clear_exp;
        -- The bits driven below are k mod 2 for k = 0..10, so the first eight --
        -- 0 1 0 1 0 1 0 1 read MSB-first -- are 0x55. Registering it matters: an
        -- unexpected word and a missing word are different failures.
        exp_q(0) <= x"00000055";
        exp_w    <= 1;
        cpol <= '0'; sclk_pin <= '0'; cs_n_pin <= '1'; adv(8);
        cs_n_pin <= '0'; adv(4);
        for k in 0 to 10 loop
            if (k mod 2) = 0 then mosi_pin <= '0'; else mosi_pin <= '1'; end if;
            adv(2);
            sclk_pin <= '1'; adv(4);
            sclk_pin <= '0'; adv(2);
        end loop;
        adv(4);
        if to_integer(bit_idx) /= 3 then
            report "  FAIL: after 11 bits the partial count was " &
                   integer'image(to_integer(bit_idx)) & ", expected 3";
            errs := errs + 1;
        end if;
        if to_integer(words_in_txn) /= 1 then
            report "  FAIL: after 11 bits " &
                   integer'image(to_integer(words_in_txn)) &
                   " words completed, expected 1";
            errs := errs + 1;
        end if;
        cs_n_pin <= '1'; adv(8); sclk_pin <= '0'; adv(8);
        if txn_trunc /= '1' then
            report "  FAIL: a transaction ending mid-word was not reported truncated";
            errs := errs + 1;
        end if;
        report "  a transaction of 11 bits at eight bits per word: one complete word, a partial count of 3, and the transaction reported truncated";

        -- 7. THE CONTINUOUS PROPERTIES.
        if word_bad /= 0 then
            report "  FAIL: " & integer'image(word_bad) & " of " &
                   integer'image(n_valid) & " received words were wrong";
            errs := errs + 1;
        end if;
        if upper_bad /= 0 then
            report "  FAIL: " & integer'image(upper_bad) &
                   " words carried bits above the frame width";
            errs := errs + 1;
        end if;
        if valid_at_wrong_time /= 0 then
            report "  FAIL: " & integer'image(valid_at_wrong_time) &
                   " words arrived that nothing was sent for";
            errs := errs + 1;
        end if;
        report "  " & integer'image(n_valid) &
               " received words, none wrong, none carrying bits above its width, and none unaccounted for";

        errors <= errs;
        if errs = 0 then
            report "PASS: MOSI is captured on the mode's capture edge and assembled into words whose boundaries come from a counter cleared by the select pin, so nothing the slave counts can redefine where a word ends -- all " & integer'image(n_valid) & " words across widths of 1, 2, 5, 8, 13 and 32 bits, both bit orders, both phases and three frequency ratios came back exactly as sent, every one right-aligned with nothing above its width even when narrow words of differing values followed one another, the capture counter and the edge counter of Chapter 14.2 agree on every transaction, and a transaction ending mid-word leaves its completed words intact with a readable partial count and is reported as truncated";
        else
            report "FAIL: " & integer'image(errs) & " error(s)" severity error;
        end if;
        halt <= true;
        wait;
    end process;

end architecture;

// Properties for the receive path.

property p_valid_only_in_txn;
    // A word can only be published inside a transaction. A strobe outside one
    // means the counter is being advanced by something other than the capture
    // strobe -- which is the failure mode of a counter that rolls over freely.
    @(posedge clk) disable iff (!rst_n)
        rx_valid_stb |-> txn_active;
endproperty

property p_bit_idx_in_range;
    // The position within the word is always a legal position. An index that
    // reaches len means the boundary comparison is off by one, and the symptom
    // is words of len+1 bits that look like a shift.
    @(posedge clk) disable iff (!rst_n)
        txn_active |-> (bit_idx < len);
endproperty

property p_counter_zeroed_at_start;
    // The zero comes from the pin. This is section 1's rule, checkable in one
    // line, and it is the property that makes the next transaction correct
    // after this one has slipped.
    @(posedge clk) disable iff (!rst_n)
        txn_start_stb |=> (bit_idx == 0);
endproperty

property p_valid_follows_final_capture;
    // The strobe is exactly one cycle after the capture that completed the
    // word -- not the same cycle. This is the off-by-one in section 7, stated
    // as a property rather than left to a code review.
    @(posedge clk) disable iff (!rst_n)
        (cap_stb && bit_idx == len - 1) |=> rx_valid_stb;
endproperty

property p_no_valid_without_final_capture;
    // And the converse, which is what catches a strobe generated from a level
    // rather than from the capture.
    @(posedge clk) disable iff (!rst_n)
        rx_valid_stb |-> $past(cap_stb);
endproperty

property p_partial_tracks_sr;
    // The published in-progress word changes only on a capture. A partial that
    // moves on any other cycle means 14.7 is reading a register that something
    // else writes.
    @(posedge clk) disable iff (!rst_n)
        !cap_stb |=> $stable(rx_partial_sr);
endproperty

// Coverage. The two axes are WIDTH and ORDER, and they must be crossed, because
// the reversal is a function of the width and the alignment is a function of
// both.

covergroup cg_rx @(posedge clk iff rx_valid_stb);
    option.per_instance = 1;

    // Widths chosen at the boundaries rather than spread evenly: 1 is where a
    // word boundary happens every capture, MAX_W is where the reversal touches
    // every bit and the right-alignment is a no-op.
    width: coverpoint len {
        bins one     = {1};
        bins narrow  = {[2:7]};
        bins byte_w  = {8};
        bins odd     = {5, 9, 13, 17};   // widths that are not powers of two
        bins wide    = {[18:31]};
        bins full    = {32};
    }

    order: coverpoint lsb_first { bins msb = {0}; bins lsb = {1}; }

    // How many words this transaction has produced by the time this one
    // arrives. The first word of a transaction and the fifth exercise
    // different paths through the counter's reset.
    position: coverpoint words_in_txn {
        bins first  = {1};
        bins second = {2};
        bins middle = {[3:7]};
        bins many   = {[8:$]};
    }

    x_width_order: cross width, order;
    x_width_pos:   cross width, position;

endgroup