Anatomy of a Read Transaction

// spi_read_path.sv — the slave-side read datapath.
//
// A write ends inside the device (Chapter 5.1). A read must come back out,
// and that creates an obligation a write never has: the FIRST data bit must
// already be on MISO before the first launch edge of the data phase. There is
// no edge before it on which to place it.
//
// The dummy phase (Chapter 4.5) exists to buy the time this module needs
// between "the address is known" and "the first bit is on the pin".
module spi_read_path #(
    parameter int WIDTH = 8
) (
    input  logic             clk,
    input  logic             rst_n,
    input  logic             data_phase,   // level, from the phase sequencer
    input  logic             launch_stb,   // one pulse per launch edge
    input  logic [WIDTH-1:0] fetch_data,   // byte presented by the memory
    output logic             fetch_req,    // pulse: hand me the next byte
    output logic             miso,
    output logic             miso_oe       // output enable for the pad
);
    localparam int CW = (WIDTH > 1) ? $clog2(WIDTH) : 1;

    logic [WIDTH-1:0] shreg;
    logic [CW-1:0]    bit_cnt;
    logic             data_phase_q;

    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            shreg        <= '0;
            bit_cnt      <= '0;
            fetch_req    <= 1'b0;
            data_phase_q <= 1'b0;
        end else begin
            data_phase_q <= data_phase;
            fetch_req    <= 1'b0;          // a strobe, not a level

            if (!data_phase) begin
                // Outside the data phase nothing is shifted and nothing is
                // driven. Holding the counter cleared means the first launch
                // edge after entry is bit 0 of a fresh word.
                bit_cnt <= '0;
            end else if (!data_phase_q) begin
                // ENTERING the data phase: the first byte must be loaded NOW,
                // because the next launch edge will already be shifting it.
                shreg     <= fetch_data;
                bit_cnt   <= '0;
                fetch_req <= 1'b1;          // prefetch the byte after this one
            end else if (launch_stb) begin
                if (bit_cnt == CW'(WIDTH - 1)) begin
                    // Last bit of this word has just left; the next word must
                    // already be available on fetch_data.
                    shreg     <= fetch_data;
                    bit_cnt   <= '0;
                    fetch_req <= 1'b1;
                end else begin
                    shreg   <= {shreg[WIDTH-2:0], 1'b0};
                    bit_cnt <= bit_cnt + 1'b1;
                end
            end
        end
    end

    assign miso = shreg[WIDTH-1];            // MSB-first (Chapter 4.3)
    // The slave drives MISO ONLY in the data phase. Everything earlier belongs
    // to the master's half of the exchange, and on a multi-slave bus driving
    // early is contention rather than merely wrong data.
    assign miso_oe = data_phase;
endmodule

// spi_read_path_tb.sv — first-bit timing, multi-byte streaming, and the
// output enable staying confined to the data phase.
`timescale 1ns/1ps
module spi_read_path_tb;
    logic clk = 0, rst_n = 0;
    always #5 clk = ~clk;

    localparam int W = 8;
    logic data_phase = 0, launch = 0;
    logic [W-1:0] fetch_data = 8'h00;
    logic fetch_req, miso, miso_oe;

    spi_read_path #(.WIDTH(W)) dut (
        .clk, .rst_n, .data_phase, .launch_stb(launch),
        .fetch_data, .fetch_req, .miso, .miso_oe);

    int errors = 0, fetches = 0;
    task automatic chk(input string what, input int got, input int exp);
        if (got !== exp) begin $display("FAIL %s: got 0x%0h exp 0x%0h", what, got, exp); errors++; end
    endtask

    // A tiny memory model: hand over the next byte whenever asked.
    logic [W-1:0] mem [4] = '{8'hA5, 8'h3C, 8'h81, 8'h00};
    int mem_idx = 0;
    always @(posedge clk) begin
        if (rst_n && fetch_req) begin
            fetches++;
            mem_idx <= (mem_idx + 1) % 4;
        end
    end
    always_comb fetch_data = mem[mem_idx];

    // Collect MISO as it is launched.
    logic [W-1:0] got_byte;
    task automatic shift_bits(input int n);
        for (int i = 0; i < n; i++) begin
            got_byte = {got_byte[W-2:0], miso};   // sample BEFORE the launch edge
            @(negedge clk); launch = 1; @(negedge clk); launch = 0; @(negedge clk);
        end
    endtask

    initial begin
        repeat (3) @(negedge clk); rst_n = 1; @(negedge clk);
        chk("idle: miso_oe low", miso_oe, 0);

        // --- Enter the data phase. The first bit must be valid IMMEDIATELY,
        //     before any launch edge occurs. ---
        data_phase = 1; @(negedge clk); @(negedge clk);
        chk("data phase: miso_oe high", miso_oe, 1);
        chk("first bit already valid",  miso,    1'b1);   // 0xA5 MSB = 1

        got_byte = '0;
        shift_bits(W);
        chk("byte 0 streamed", got_byte, 8'hA5);

        got_byte = '0;
        shift_bits(W);
        chk("byte 1 streamed", got_byte, 8'h3C);

        got_byte = '0;
        shift_bits(W);
        chk("byte 2 streamed", got_byte, 8'h81);

        // --- Leaving the data phase must release the pad ---
        data_phase = 0; @(negedge clk); @(negedge clk);
        chk("released: miso_oe low", miso_oe, 0);

        // --- Re-entering starts a fresh word, not mid-byte ---
        mem_idx = 0; @(negedge clk);
        data_phase = 1; @(negedge clk); @(negedge clk);
        chk("re-entry: first bit valid again", miso, 1'b1);
        got_byte = '0;
        shift_bits(W);
        chk("re-entry byte", got_byte, 8'hA5);
        data_phase = 0; @(negedge clk);

        if (errors == 0)
            $display("PASS: the first data bit is valid on entry to the data phase, bytes stream back to back, and MISO is driven only while the data phase is active");
        else
            $display("FAILED with %0d error(s)", errors);
        $finish;
    end

    initial begin #500000; $display("FAIL: watchdog timeout"); $finish; end
endmodule

// spi_read_path.v — the same slave-side read datapath in Verilog-2001.
module spi_read_path #(
    parameter WIDTH = 8
) (
    input  wire             clk,
    input  wire             rst_n,
    input  wire             data_phase,
    input  wire             launch_stb,
    input  wire [WIDTH-1:0] fetch_data,
    output reg              fetch_req,
    output wire             miso,
    output wire             miso_oe
);
    function integer clogb2;
        input integer value;
        integer v;
        begin
            v = value - 1;
            for (clogb2 = 0; v > 0; clogb2 = clogb2 + 1) v = v >> 1;
        end
    endfunction

    localparam CW = (WIDTH > 1) ? clogb2(WIDTH) : 1;

    reg [WIDTH-1:0] shreg;
    reg [CW-1:0]    bit_cnt;
    reg             data_phase_q;

    always @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            shreg        <= {WIDTH{1'b0}};
            bit_cnt      <= {CW{1'b0}};
            fetch_req    <= 1'b0;
            data_phase_q <= 1'b0;
        end else begin
            data_phase_q <= data_phase;
            fetch_req    <= 1'b0;

            if (!data_phase) begin
                bit_cnt <= {CW{1'b0}};
            end else if (!data_phase_q) begin
                // ENTERING the data phase: load now, because the next launch
                // edge will already be shifting this word.
                shreg     <= fetch_data;
                bit_cnt   <= {CW{1'b0}};
                fetch_req <= 1'b1;
            end else if (launch_stb) begin
                if (bit_cnt == (WIDTH - 1)) begin
                    shreg     <= fetch_data;
                    bit_cnt   <= {CW{1'b0}};
                    fetch_req <= 1'b1;
                end else begin
                    shreg   <= {shreg[WIDTH-2:0], 1'b0};
                    bit_cnt <= bit_cnt + 1'b1;
                end
            end
        end
    end

    assign miso    = shreg[WIDTH-1];
    assign miso_oe = data_phase;
endmodule

// spi_read_path_tb.v — the same checks in Verilog-2001.
`timescale 1ns/1ps
module spi_read_path_tb;
    reg clk = 0, rst_n = 0;
    always #5 clk = ~clk;

    parameter W = 8;
    reg  data_phase = 0, launch = 0;
    wire [W-1:0] fetch_data;
    wire fetch_req, miso, miso_oe;

    spi_read_path #(.WIDTH(W)) dut (
        .clk(clk), .rst_n(rst_n), .data_phase(data_phase), .launch_stb(launch),
        .fetch_data(fetch_data), .fetch_req(fetch_req), .miso(miso), .miso_oe(miso_oe));

    integer errors = 0, fetches = 0, mem_idx = 0, i;
    reg [W-1:0] mem [0:3];
    reg [W-1:0] got_byte;

    initial begin
        mem[0] = 8'hA5; mem[1] = 8'h3C; mem[2] = 8'h81; mem[3] = 8'h00;
    end

    assign fetch_data = mem[mem_idx];

    task chk;
        input [80*8-1:0] what;
        input [31:0] got, exp;
        begin
            if (got !== exp) begin
                $display("FAIL %0s: got 0x%0h exp 0x%0h", what, got, exp);
                errors = errors + 1;
            end
        end
    endtask

    always @(posedge clk) if (rst_n && fetch_req) begin
        fetches = fetches + 1;
        mem_idx = (mem_idx + 1) % 4;
    end

    task shift_bits;
        input integer n;
        integer k;
        begin
            for (k = 0; k < n; k = k + 1) begin
                got_byte = {got_byte[W-2:0], miso};
                @(negedge clk); launch = 1; @(negedge clk); launch = 0; @(negedge clk);
            end
        end
    endtask

    initial begin
        repeat (3) @(negedge clk); rst_n = 1; @(negedge clk);
        chk("idle: miso_oe low", miso_oe, 0);

        data_phase = 1; @(negedge clk); @(negedge clk);
        chk("data phase: miso_oe high", miso_oe, 1);
        chk("first bit already valid",  miso,    1'b1);

        got_byte = 0; shift_bits(W); chk("byte 0 streamed", got_byte, 8'hA5);
        got_byte = 0; shift_bits(W); chk("byte 1 streamed", got_byte, 8'h3C);
        got_byte = 0; shift_bits(W); chk("byte 2 streamed", got_byte, 8'h81);

        data_phase = 0; @(negedge clk); @(negedge clk);
        chk("released: miso_oe low", miso_oe, 0);

        mem_idx = 0; @(negedge clk);
        data_phase = 1; @(negedge clk); @(negedge clk);
        chk("re-entry: first bit valid again", miso, 1'b1);
        got_byte = 0; shift_bits(W);
        chk("re-entry byte", got_byte, 8'hA5);
        data_phase = 0; @(negedge clk);

        if (errors == 0)
            $display("PASS: the first data bit is valid on entry to the data phase, bytes stream back to back, and MISO is driven only while the data phase is active");
        else
            $display("FAILED with %0d error(s)", errors);
        $finish;
    end

    initial begin #500000; $display("FAIL: watchdog timeout"); $finish; end
endmodule

-- spi_read_path.vhd — the same slave-side read datapath in VHDL.
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

entity spi_read_path is
    generic (
        WIDTH : positive := 8
    );
    port (
        clk        : in  std_logic;
        rst_n      : in  std_logic;
        data_phase : in  std_logic;                                 -- level
        launch_stb : in  std_logic;                                 -- one pulse per launch edge
        fetch_data : in  std_logic_vector(WIDTH - 1 downto 0);
        fetch_req  : out std_logic;                                 -- pulse
        miso       : out std_logic;
        miso_oe    : out std_logic
    );
end entity spi_read_path;

architecture rtl of spi_read_path is
    signal shreg        : std_logic_vector(WIDTH - 1 downto 0);
    signal bit_cnt      : integer range 0 to WIDTH - 1;
    signal data_phase_q : std_logic;
begin

    process (clk, rst_n) is
    begin
        if rst_n = '0' then
            shreg        <= (others => '0');
            bit_cnt      <= 0;
            fetch_req    <= '0';
            data_phase_q <= '0';
        elsif rising_edge(clk) then
            data_phase_q <= data_phase;
            fetch_req    <= '0';

            if data_phase = '0' then
                bit_cnt <= 0;
            elsif data_phase_q = '0' then
                -- ENTERING the data phase: load now, because the next launch
                -- edge will already be shifting this word.
                shreg     <= fetch_data;
                bit_cnt   <= 0;
                fetch_req <= '1';
            elsif launch_stb = '1' then
                if bit_cnt = WIDTH - 1 then
                    shreg     <= fetch_data;
                    bit_cnt   <= 0;
                    fetch_req <= '1';
                else
                    shreg   <= shreg(WIDTH - 2 downto 0) & '0';
                    bit_cnt <= bit_cnt + 1;
                end if;
            end if;
        end if;
    end process;

    miso    <= shreg(WIDTH - 1);
    -- Driven ONLY in the data phase: driving early is contention, not merely
    -- wrong data.
    miso_oe <= data_phase;

end architecture rtl;

-- spi_read_path_tb.vhd — the same checks in VHDL.
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

entity spi_read_path_tb is
end entity spi_read_path_tb;

architecture tb of spi_read_path_tb is
    constant W : positive := 8;

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

    signal fetch_data : std_logic_vector(W - 1 downto 0);
    signal fetch_req  : std_logic;
    signal miso       : std_logic;
    signal miso_oe    : std_logic;

    signal errors   : natural := 0;
    signal mem_idx  : natural := 0;
    signal mem_rst  : std_logic := '0';   -- stim requests; memproc owns mem_idx
    signal got_byte : std_logic_vector(W - 1 downto 0) := (others => '0');

    type mem_t is array (0 to 3) of std_logic_vector(W - 1 downto 0);
    constant MEM : mem_t := (x"A5", x"3C", x"81", x"00");
begin

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

    fetch_data <= MEM(mem_idx);

    dut : entity work.spi_read_path
        generic map (WIDTH => W)
        port map (clk => clk, rst_n => rst_n, data_phase => data_phase,
                  launch_stb => launch, fetch_data => fetch_data,
                  fetch_req => fetch_req, miso => miso, miso_oe => miso_oe);

    -- Tiny memory model: advance on every fetch request.
    memproc : process (clk) is
    begin
        if rising_edge(clk) then
            if mem_rst = '1' then
                mem_idx <= 0;
            elsif rst_n = '1' and fetch_req = '1' then
                mem_idx <= (mem_idx + 1) mod 4;
            end if;
        end if;
    end process;

    stim : process is
        procedure chk_v (what : string; got, exp : std_logic_vector) is
        begin
            if got /= exp then
                report "FAIL " & what & ": got 0x" & to_hstring(got)
                    & " exp 0x" & to_hstring(exp) severity error;
                errors <= errors + 1;
            end if;
        end procedure;

        procedure chk_b (what : string; got, exp : std_logic) is
        begin
            if got /= exp then
                report "FAIL " & what severity error;
                errors <= errors + 1;
            end if;
        end procedure;

        procedure shift_bits (n : positive) is
        begin
            for k in 0 to n - 1 loop
                got_byte <= got_byte(W - 2 downto 0) & miso;
                wait until falling_edge(clk); launch <= '1';
                wait until falling_edge(clk); launch <= '0';
                wait until falling_edge(clk);
            end loop;
        end procedure;
    begin
        for i in 0 to 2 loop
            wait until falling_edge(clk);
        end loop;
        rst_n <= '1';
        wait until falling_edge(clk);
        chk_b("idle: miso_oe low", miso_oe, '0');

        data_phase <= '1';
        wait until falling_edge(clk);
        wait until falling_edge(clk);
        chk_b("data phase: miso_oe high", miso_oe, '1');
        chk_b("first bit already valid",  miso,    '1');

        got_byte <= (others => '0'); wait until falling_edge(clk);
        shift_bits(W); chk_v("byte 0 streamed", got_byte, x"A5");

        got_byte <= (others => '0'); wait until falling_edge(clk);
        shift_bits(W); chk_v("byte 1 streamed", got_byte, x"3C");

        got_byte <= (others => '0'); wait until falling_edge(clk);
        shift_bits(W); chk_v("byte 2 streamed", got_byte, x"81");

        data_phase <= '0';
        wait until falling_edge(clk);
        wait until falling_edge(clk);
        chk_b("released: miso_oe low", miso_oe, '0');

        mem_rst <= '1';
        wait until falling_edge(clk);
        mem_rst <= '0';
        wait until falling_edge(clk);
        data_phase <= '1';
        wait until falling_edge(clk);
        wait until falling_edge(clk);
        chk_b("re-entry: first bit valid again", miso, '1');
        got_byte <= (others => '0'); wait until falling_edge(clk);
        shift_bits(W);
        chk_v("re-entry byte", got_byte, x"A5");
        data_phase <= '0';
        wait until falling_edge(clk);

        if errors = 0 then
            report "PASS: the first data bit is valid on entry to the data phase, "
                 & "bytes stream back to back, and MISO is driven only while the "
                 & "data phase is active" severity note;
        else
            report "FAILED with " & integer'image(errors) & " error(s)" severity error;
        end if;
        halt <= true;
        wait;
    end process;

    watchdog : process is
    begin
        wait for 500 us;
        if not halt then
            report "FAIL: watchdog timeout" severity failure;
        end if;
        wait;
    end process;

end architecture tb;

   // A write item can be a byte queue. A read item cannot: the same frame
   // carries master-driven bytes and device-driven bytes, and the boundary
   // between them is a DEVICE fact (Chapter 4.1 §7) rather than an
   // observable one. The item therefore records both streams plus the
   // configuration that says where to split them.
   class spi_read_item extends uvm_sequence_item;
       `uvm_object_utils(spi_read_item)

       // --- what the master sent ---
       rand bit [7:0]       opcode;
       rand bit [7:0]       addr_bytes[];
       rand int unsigned    dummy_cycles;

       // --- what the device returned (filled by the monitor) ---
       bit [7:0]            rx_data[$];

       // --- what the monitor needs in order to split the frame at all ---
       int unsigned         cmd_len;
       int unsigned         addr_len;

       // The full MOSI and MISO streams, kept UNSPLIT. Keeping the raw
       // streams alongside the interpretation means a scoreboard can be
       // re-run against a corrected configuration without recapturing.
       bit [7:0]            mosi_raw[$];
       bit [7:0]            miso_raw[$];

       constraint c_addr  { addr_bytes.size() inside {0, 1, 2, 3, 4}; }
       constraint c_dummy { dummy_cycles inside {[0:32]}; }
   endclass

   // 1. Never drive outside the data phase. On a multi-slave bus this is
   //    contention with another device; on a shared-line bus, with the master.
   a_no_early_drive : assert property (
       @(posedge clk) disable iff (!rst_n) miso_oe |-> data_phase)
       else $error("slave drove MISO outside the data phase");

   // 2. The first bit must be valid on entry, BEFORE any launch edge.
   //    This is §5 as a checkable statement.
   property p_first_bit_ready;
       @(posedge clk) disable iff (!rst_n)
           $rose(data_phase) |-> ##1 (miso === fetch_data_at_entry[WIDTH-1]);
   endproperty

   // 3. Prefetch must lead by a full word, or a streaming read will stall.
   //    Catches a design that requests the next byte too late.
   property p_prefetch_leads;
       @(posedge clk) disable iff (!rst_n || !data_phase)
           fetch_req |-> ##[1:$] (bit_cnt == 0);
   endproperty

   // 4. Release on frame close. A slave still driving when the next device
   //    is selected produces contention the NEXT transaction will suffer.
   a_release_on_close : assert property (
       @(posedge clk) disable iff (!rst_n) $fell(data_phase) |=> !miso_oe)
       else $error("slave still driving MISO after the data phase ended");

   covergroup spi_read_cg @(posedge cs_rose);
       cp_data_bytes : coverpoint rx_byte_count {
           bins none    = {0};        // a read aborted before any data
           bins one     = {1};        // no byte boundary exercised at all
           bins two     = {2};        // the first reload -- where prefetch bugs live
           bins burst   = {[3:255]};
           bins long    = {[256:$]};
       }

       // §5: a burst is where prefetch matters. A single-byte read never
       // exercises the reload path, so it can pass with prefetch broken.
       cp_abort_in_data : coverpoint aborted_mid_byte {
           bins clean_boundary = {0};
           bins mid_byte       = {1};   // CS rose part-way through a word
       }

       x_bytes_abort : cross cp_data_bytes, cp_abort_in_data;
   endgroup