MISO Output Enable and Release

   ASSERT LATE     the master reads nothing for a while. Recoverable: it reads
                   the wrong first bit, which Chapter 14.4 measures and reports.

   RELEASE LATE    two devices drive the same wire. Not recoverable by anyone:
                   the contending value is neither slave's, both output stages
                   source current into each other, and on a long enough bus it
                   is a reliability problem as well as a data one.

   oe <= cs_active          // cs_active is already SYNC_N behind the pin

   GAP >= (this slave's release latency) - (the next device's assert latency)

   GAP >= SYNC_N + 1

   invisible to the slave          visible to
   ----------------------------    ------------------------------------
   a lost SCLK edge (14.1)         nothing in simulation; a board, via
                                     the measured ratio
   a late first bit (14.4)         a pin-level observer; the slave sees
                                     only the interval, which cancels
   bus contention (14.5)           a bus-level observer only

// spi_slave_oe.sv
//
// Chapter 14.5 -- driving MISO only while selected, and releasing it in time.
//
// MISO is the one pin a slave drives, and on a bus with more than one slave it is
// shared. So there are two obligations, and they are not symmetric:
//
//   ASSERT LATE and the master reads nothing for a while. Recoverable: it reads
//   the wrong first bit, which Chapter 14.4 measures and reports.
//
//   RELEASE LATE and two devices drive the same wire. Not recoverable by anyone:
//   the contending value is neither slave's, both output stages source current
//   into each other, and on a long enough bus it is a reliability problem as well
//   as a data one.
//
// So the release is the side that gets the attention.
//
// THE ENABLE IS A REGISTER, AND IT IS DERIVED FROM THE SYNCHRONISED SELECT.
//
//     oe <= cs_active          // cs_active is already SYNC_N behind the pin
//
// which means the pin-to-release latency is SYNC_N + 1 system clocks. That is not
// a design choice that could be made differently: the pin is the only information
// the slave has, and it arrives through the synchroniser.
//
// What IS a choice is the alternative someone will propose -- deriving the enable
// combinationally from the chip-select pin to release faster. Do not:
//
//   * a glitch on the select line then DRIVES THE BUS, which is the failure the
//     enable exists to prevent;
//   * the enable is an output-stage control, so a combinational path from an
//     asynchronous input to it is a path from a pin to a pin with no flop in it,
//     which static timing analysis has nothing to say about;
//   * and it buys SYNC_N cycles on a release that the master's inter-transaction
//     gap already covers, if the gap is specified -- which is what §4 is about.
//
// THE THIRD REQUIREMENT ON THE MASTER, AND WHY IT DEPENDS ON THE NEIGHBOUR.
//
// Chapter 14.4 produced two requirements from the synchroniser depth: a lead of
// SYNC_N + 2 and a half-period of SYNC_N + 1. This is the third, and it is the
// only one of the three that is not a property of this slave alone:
//
//     GAP >= (this slave's release latency) - (the next device's assert latency)
//
// Two identical oversampling slaves never contend, at any gap, because the one
// being selected is as slow to start driving as the one being deselected is to
// stop. Put this slave next to a device that drives immediately -- an ASIC with no
// oversampling, or anything clocked on SCLK -- and the subtraction stops being
// free: the requirement becomes GAP >= SYNC_N + 1.
//
// That is why a datasheet specifies a minimum CS-high time rather than leaving it
// to the master's judgement. The master cannot compute it, because it depends on
// two devices it does not know the internals of.
//
// AND THE SLAVE CANNOT DETECT CONTENTION. It is driving; what it reads back is its
// own value fighting someone else's, and a CMOS output stage wins or loses by
// drive strength rather than by arbitration. Only a bus-level observer sees it --
// which is the third thing in this module that is invisible from inside the slave,
// after the late first bit (14.4) and the lost edge (14.1). What the slave CAN
// measure is its own CS-high time, so a back-to-back pair of transactions to THIS
// device is checkable; a neighbour's is not.

module spi_slave_oe #(
    parameter int GAP_MIN = 3,    // recovered cycles of CS-high this slave needs
    parameter int CNT_W   = 8
) (
    input  wire              clk,
    input  wire              rst_n,

    // --- from the front end of 14.1 --------------------------------------
    input  wire              cs_active,
    input  wire              cs_assert_stb,
    input  wire              cs_deassert_stb,

    // --- from 14.4 --------------------------------------------------------
    input  wire              miso_val,

    // --- the pin ----------------------------------------------------------
    output wire              oe,
    output wire              miso_pad,     // driven, or released to high impedance

    // --- status -----------------------------------------------------------
    output reg  [CNT_W-1:0]  gap_seen,     // this slave's own CS-high time
    output reg               gap_short,    // sticky: below GAP_MIN
    output reg  [CNT_W-1:0]  rel_cycles,   // measured release latency
    input  wire              clr_flags
);

    reg oe_r;
    reg cs_active_d;

    assign oe = oe_r;

    // The tri-state. One expression, and the only place in the slave where a pin
    // is not unconditionally driven.
    assign miso_pad = oe_r ? miso_val : 1'bz;

    reg [CNT_W-1:0] since_release;   // cycles since `oe` dropped
    reg [CNT_W-1:0] since_deassert;  // cycles since the select was seen to rise
    reg             armed;           // a release has happened and not been measured

    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            // Reset releases the pin, asynchronously. A slave held in reset while
            // still driving a shared bus is the same failure as a master holding
            // a select line low in reset (Chapter 13.10), from the other side --
            // and here the consequence is that no other device on the bus can be
            // used at all until this one comes out of reset.
            oe_r           <= 1'b0;
            cs_active_d    <= 1'b0;
            since_release  <= {CNT_W{1'b0}};
            since_deassert <= {CNT_W{1'b1}};
            armed          <= 1'b0;
            gap_seen       <= {CNT_W{1'b1}};
            gap_short      <= 1'b0;
            rel_cycles     <= {CNT_W{1'b0}};
        end else begin
            // THE enable. One register, fed by the synchronised select and by
            // nothing else -- no combinational term, no bypass, no fast path.
            oe_r        <= cs_active;
            cs_active_d <= cs_active;

            if (clr_flags)
                gap_short <= 1'b0;

            // --- the measured release latency ------------------------------
            // Counted from the synchronised select falling to the enable
            // dropping. In a correct design it is the constant 1, and publishing
            // it means a reviewer reads the number rather than deriving it from
            // the synchroniser depth -- and a gate-level run that changes it says
            // so instead of failing somewhere else.
            if (cs_active_d && !cs_active) begin
                since_release <= {{(CNT_W-1){1'b0}}, 1'b1};
                armed         <= 1'b1;
            end else if (armed && !oe_r) begin
                rel_cycles <= since_release;
                armed      <= 1'b0;
            end else if (since_release != {CNT_W{1'b1}}) begin
                since_release <= since_release + 1'b1;
            end

            // --- this slave's own CS-high time -----------------------------
            // Measured in recovered cycles, so the synchroniser latency is at
            // both ends and cancels. It says nothing about a NEIGHBOUR's gap,
            // which is the case that actually causes contention -- and that
            // asymmetry is the point of the header.
            if (cs_deassert_stb) begin
                since_deassert <= {{(CNT_W-1){1'b0}}, 1'b1};
            end else if (cs_assert_stb) begin
                if (since_deassert != {CNT_W{1'b1}}) begin
                    gap_seen <= since_deassert;
                    if (since_deassert < GAP_MIN)
                        gap_short <= 1'b1;
                end
            end else if (since_deassert != {CNT_W{1'b1}}) begin
                since_deassert <= since_deassert + 1'b1;
            end
        end
    end

endmodule

// spi_slave_oe.v
//
// Chapter 14.5 -- driving MISO only while selected, and releasing it in time.
//
// MISO is the one pin a slave drives, and on a bus with more than one slave it is
// shared. So there are two obligations, and they are not symmetric:
//
//   ASSERT LATE and the master reads nothing for a while. Recoverable: it reads
//   the wrong first bit, which Chapter 14.4 measures and reports.
//
//   RELEASE LATE and two devices drive the same wire. Not recoverable by anyone:
//   the contending value is neither slave's, both output stages source current
//   into each other, and on a long enough bus it is a reliability problem as well
//   as a data one.
//
// So the release is the side that gets the attention.
//
// THE ENABLE IS A REGISTER, AND IT IS DERIVED FROM THE SYNCHRONISED SELECT.
//
//     oe <= cs_active          // cs_active is already SYNC_N behind the pin
//
// which means the pin-to-release latency is SYNC_N + 1 system clocks. That is not
// a design choice that could be made differently: the pin is the only information
// the slave has, and it arrives through the synchroniser.
//
// What IS a choice is the alternative someone will propose -- deriving the enable
// combinationally from the chip-select pin to release faster. Do not:
//
//   * a glitch on the select line then DRIVES THE BUS, which is the failure the
//     enable exists to prevent;
//   * the enable is an output-stage control, so a combinational path from an
//     asynchronous input to it is a path from a pin to a pin with no flop in it,
//     which static timing analysis has nothing to say about;
//   * and it buys SYNC_N cycles on a release that the master's inter-transaction
//     gap already covers, if the gap is specified -- which is what §4 is about.
//
// THE THIRD REQUIREMENT ON THE MASTER, AND WHY IT DEPENDS ON THE NEIGHBOUR.
//
// Chapter 14.4 produced two requirements from the synchroniser depth: a lead of
// SYNC_N + 2 and a half-period of SYNC_N + 1. This is the third, and it is the
// only one of the three that is not a property of this slave alone:
//
//     GAP >= (this slave's release latency) - (the next device's assert latency)
//
// Two identical oversampling slaves never contend, at any gap, because the one
// being selected is as slow to start driving as the one being deselected is to
// stop. Put this slave next to a device that drives immediately -- an ASIC with no
// oversampling, or anything clocked on SCLK -- and the subtraction stops being
// free: the requirement becomes GAP >= SYNC_N + 1.
//
// That is why a datasheet specifies a minimum CS-high time rather than leaving it
// to the master's judgement. The master cannot compute it, because it depends on
// two devices it does not know the internals of.
//
// AND THE SLAVE CANNOT DETECT CONTENTION. It is driving; what it reads back is its
// own value fighting someone else's, and a CMOS output stage wins or loses by
// drive strength rather than by arbitration. Only a bus-level observer sees it --
// which is the third thing in this module that is invisible from inside the slave,
// after the late first bit (14.4) and the lost edge (14.1). What the slave CAN
// measure is its own CS-high time, so a back-to-back pair of transactions to THIS
// device is checkable; a neighbour's is not.

module spi_slave_oe #(
    parameter GAP_MIN = 3,    // recovered cycles of CS-high this slave needs
    parameter CNT_W   = 8
) (
    input  wire              clk,
    input  wire              rst_n,

    // --- from the front end of 14.1 --------------------------------------
    input  wire              cs_active,
    input  wire              cs_assert_stb,
    input  wire              cs_deassert_stb,

    // --- from 14.4 --------------------------------------------------------
    input  wire              miso_val,

    // --- the pin ----------------------------------------------------------
    output wire              oe,
    output wire              miso_pad,     // driven, or released to high impedance

    // --- status -----------------------------------------------------------
    output reg  [CNT_W-1:0]  gap_seen,     // this slave's own CS-high time
    output reg               gap_short,    // sticky: below GAP_MIN
    output reg  [CNT_W-1:0]  rel_cycles,   // measured release latency
    input  wire              clr_flags
);

    reg oe_r;
    reg cs_active_d;

    assign oe = oe_r;

    // The tri-state. One expression, and the only place in the slave where a pin
    // is not unconditionally driven.
    assign miso_pad = oe_r ? miso_val : 1'bz;

    reg [CNT_W-1:0] since_release;   // cycles since `oe` dropped
    reg [CNT_W-1:0] since_deassert;  // cycles since the select was seen to rise
    reg             armed;           // a release has happened and not been measured

    always @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            // Reset releases the pin, asynchronously. A slave held in reset while
            // still driving a shared bus is the same failure as a master holding
            // a select line low in reset (Chapter 13.10), from the other side --
            // and here the consequence is that no other device on the bus can be
            // used at all until this one comes out of reset.
            oe_r           <= 1'b0;
            cs_active_d    <= 1'b0;
            since_release  <= {CNT_W{1'b0}};
            since_deassert <= {CNT_W{1'b1}};
            armed          <= 1'b0;
            gap_seen       <= {CNT_W{1'b1}};
            gap_short      <= 1'b0;
            rel_cycles     <= {CNT_W{1'b0}};
        end else begin
            // THE enable. One register, fed by the synchronised select and by
            // nothing else -- no combinational term, no bypass, no fast path.
            oe_r        <= cs_active;
            cs_active_d <= cs_active;

            if (clr_flags)
                gap_short <= 1'b0;

            // --- the measured release latency ------------------------------
            // Counted from the synchronised select falling to the enable
            // dropping. In a correct design it is the constant 1, and publishing
            // it means a reviewer reads the number rather than deriving it from
            // the synchroniser depth -- and a gate-level run that changes it says
            // so instead of failing somewhere else.
            if (cs_active_d && !cs_active) begin
                since_release <= {{(CNT_W-1){1'b0}}, 1'b1};
                armed         <= 1'b1;
            end else if (armed && !oe_r) begin
                rel_cycles <= since_release;
                armed      <= 1'b0;
            end else if (since_release != {CNT_W{1'b1}}) begin
                since_release <= since_release + 1'b1;
            end

            // --- this slave's own CS-high time -----------------------------
            // Measured in recovered cycles, so the synchroniser latency is at
            // both ends and cancels. It says nothing about a NEIGHBOUR's gap,
            // which is the case that actually causes contention -- and that
            // asymmetry is the point of the header.
            if (cs_deassert_stb) begin
                since_deassert <= {{(CNT_W-1){1'b0}}, 1'b1};
            end else if (cs_assert_stb) begin
                if (since_deassert != {CNT_W{1'b1}}) begin
                    gap_seen <= since_deassert;
                    if (since_deassert < GAP_MIN)
                        gap_short <= 1'b1;
                end
            end else if (since_deassert != {CNT_W{1'b1}}) begin
                since_deassert <= since_deassert + 1'b1;
            end
        end
    end

endmodule

-- spi_slave_oe.vhd
--
-- Chapter 14.5 -- driving MISO only while selected, and releasing it in time.
--
-- MISO is the one pin a slave drives, and on a bus with more than one slave it is
-- shared. So there are two obligations, and they are not symmetric:
--
--   ASSERT LATE and the master reads nothing for a while. Recoverable: it reads the
--   wrong first bit, which Chapter 14.4 measures and reports.
--
--   RELEASE LATE and two devices drive the same wire. Not recoverable by anyone:
--   the contending value is neither slave's, both output stages source current into
--   each other, and on a long enough bus it is a reliability problem as well as a
--   data one.
--
-- So the release is the side that gets the attention.
--
-- THE ENABLE IS A REGISTER, AND IT IS DERIVED FROM THE SYNCHRONISED SELECT.
--
--     oe <= cs_active          -- cs_active is already SYNC_N behind the pin
--
-- which means the pin-to-release latency is SYNC_N + 1 system clocks. That is not a
-- design choice that could be made differently: the pin is the only information the
-- slave has, and it arrives through the synchroniser.
--
-- What IS a choice is the alternative someone will propose -- deriving the enable
-- combinationally from the chip-select pin to release faster. Do not:
--
--   * a glitch on the select line then DRIVES THE BUS, which is the failure the
--     enable exists to prevent;
--   * the enable is an output-stage control, so a combinational path from an
--     asynchronous input to it is a path from a pin to a pin with no flop in it,
--     which static timing analysis has nothing to say about;
--   * and it buys SYNC_N cycles on a release that the master's inter-transaction
--     gap already covers, if the gap is specified.
--
-- THE THIRD REQUIREMENT ON THE MASTER, AND WHY IT DEPENDS ON THE NEIGHBOUR.
--
-- Chapter 14.4 produced two requirements from the synchroniser depth: a lead of
-- SYNC_N + 2 and a half-period of SYNC_N + 1. This is the third, and it is the only
-- one of the three that is not a property of this slave alone:
--
--     GAP >= (this slave's release latency) - (the next device's assert latency)
--
-- Two identical oversampling slaves never contend, at any gap, because the one being
-- selected is as slow to start driving as the one being deselected is to stop. Put
-- this slave next to a device that drives immediately -- an ASIC with no
-- oversampling, or anything clocked on SCLK -- and the subtraction stops being free:
-- the requirement becomes GAP >= SYNC_N + 1.
--
-- That is why a datasheet specifies a minimum CS-high time rather than leaving it to
-- the master's judgement. The master cannot compute it, because it depends on two
-- devices it does not know the internals of.
--
-- AND THE SLAVE CANNOT DETECT CONTENTION. It is driving; what it reads back is its
-- own value fighting someone else's, and a CMOS output stage wins or loses by drive
-- strength rather than by arbitration. Only a bus-level observer sees it -- the third
-- thing in this module invisible from inside the slave, after the late first bit
-- (14.4) and the lost edge (14.1). What the slave CAN measure is its own CS-high
-- time, so a back-to-back pair of transactions to THIS device is checkable; a
-- neighbour's is not.

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

entity spi_slave_oe is
    generic (
        GAP_MIN : positive := 3;   -- recovered cycles of CS-high this slave needs
        CNT_W   : positive := 8
    );
    port (
        clk             : in  std_logic;
        rst_n           : in  std_logic;

        -- from the front end of 14.1
        cs_active       : in  std_logic;
        cs_assert_stb   : in  std_logic;
        cs_deassert_stb : in  std_logic;

        -- from 14.4
        miso_val        : in  std_logic;

        -- the pin
        oe              : out std_logic;
        miso_pad        : out std_logic;   -- driven, or released to high impedance

        -- status
        gap_seen        : out unsigned(CNT_W - 1 downto 0);
        gap_short       : out std_logic;
        rel_cycles      : out unsigned(CNT_W - 1 downto 0);
        clr_flags       : in  std_logic
    );
end entity;

architecture rtl of spi_slave_oe is

    signal oe_r        : std_logic := '0';
    signal cs_active_d : std_logic := '0';

    signal since_release  : unsigned(CNT_W - 1 downto 0) := (others => '0');
    signal since_deassert : unsigned(CNT_W - 1 downto 0) := (others => '1');
    signal armed          : std_logic := '0';
    signal gap_seen_r     : unsigned(CNT_W - 1 downto 0) := (others => '1');
    signal gap_short_r    : std_logic := '0';
    signal rel_cycles_r   : unsigned(CNT_W - 1 downto 0) := (others => '0');

    constant ALL_ONES : unsigned(CNT_W - 1 downto 0) := (others => '1');

begin

    oe         <= oe_r;
    gap_seen   <= gap_seen_r;
    gap_short  <= gap_short_r;
    rel_cycles <= rel_cycles_r;

    -- The tri-state. One expression, and the only place in the slave where a pin is
    -- not unconditionally driven.
    miso_pad <= miso_val when oe_r = '1' else 'Z';

    enable : process (clk, rst_n)
    begin
        if rst_n = '0' then
            -- Reset releases the pin, asynchronously. A slave held in reset while
            -- still driving a shared bus is the same failure as a master holding a
            -- select line low in reset (Chapter 13.10), from the other side -- and
            -- here the consequence is that no other device on the bus can be used
            -- at all until this one comes out of reset.
            oe_r           <= '0';
            cs_active_d    <= '0';
            since_release  <= (others => '0');
            since_deassert <= (others => '1');
            armed          <= '0';
            gap_seen_r     <= (others => '1');
            gap_short_r    <= '0';
            rel_cycles_r   <= (others => '0');
        elsif rising_edge(clk) then
            -- THE enable. One register, fed by the synchronised select and by
            -- nothing else -- no combinational term, no bypass, no fast path.
            oe_r        <= cs_active;
            cs_active_d <= cs_active;

            if clr_flags = '1' then
                gap_short_r <= '0';
            end if;

            -- the measured release latency: from the synchronised select falling to
            -- the enable dropping. In a correct design it is the constant 1, and
            -- publishing it means a reviewer reads the number rather than deriving
            -- it -- and a gate-level run that changes it says so.
            if cs_active_d = '1' and cs_active = '0' then
                since_release <= to_unsigned(1, CNT_W);
                armed         <= '1';
            elsif armed = '1' and oe_r = '0' then
                rel_cycles_r <= since_release;
                armed        <= '0';
            elsif since_release /= ALL_ONES then
                since_release <= since_release + 1;
            end if;

            -- this slave's own CS-high time, in recovered cycles so the latency is
            -- at both ends and cancels. It says nothing about a NEIGHBOUR's gap,
            -- which is the case that actually causes contention.
            if cs_deassert_stb = '1' then
                since_deassert <= to_unsigned(1, CNT_W);
            elsif cs_assert_stb = '1' then
                if since_deassert /= ALL_ONES then
                    gap_seen_r <= since_deassert;
                    if to_integer(since_deassert) < GAP_MIN then
                        gap_short_r <= '1';
                    end if;
                end if;
            elsif since_deassert /= ALL_ONES then
                since_deassert <= since_deassert + 1;
            end if;
        end if;
    end process;

end architecture;

// spi_slave_oe_tb.sv
//
// This testbench builds a BUS, not a block. Two devices share one MISO net, and
// what is measured is whether the net ever carries a contending value -- which is
// the only place the failure exists, because neither device can see it.
//
// Two neighbours are used, and the difference between them is the chapter's whole
// argument:
//
//   an IDENTICAL oversampling slave, which is as slow to start driving as this one
//   is to stop, so the two never contend at any inter-transaction gap;
//
//   a FAST peer that drives the instant its select pin falls -- an ASIC with no
//   oversampling, or anything clocked on SCLK -- against which the gap requirement
//   stops being free and has to be measured.
//
// The gap sweep then calibrates the number: it finds the shortest gap at which the
// net is clean, and requires it to equal the release latency the slave publishes.

`timescale 1ns/1ps

module spi_slave_oe_tb;

    localparam int SYNC_N  = 2;
    localparam int GAP_MIN = 3;
    localparam int CNT_W   = 8;

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

    // --- the shared bus -----------------------------------------------------
    wire miso_bus;

    // --- device A: the slave under test -------------------------------------
    logic cs_a_pin   = 1'b1;
    logic sclk_pin   = 1'b0;
    logic mosi_pin   = 1'b0;
    logic clr_flags  = 1'b0;
    logic miso_val_a = 1'b1;     // a constant 1, so contention with a 0 is visible

    wire        sclk_q_a, cs_active_a, mosi_q_a;
    wire        edge_a_a, edge_b_a, cs_as_a, cs_de_a;
    wire [11:0] min_half_a;
    wire        ratio_err_a;

    spi_slave_frontend #(.SYNC_N(SYNC_N), .HALF_MIN(3), .CNT_W(12)) u_fe_a (
        .clk(clk), .rst_n(rst_n), .cpol(1'b0),
        .sclk_pin(sclk_pin), .cs_n_pin(cs_a_pin), .mosi_pin(mosi_pin),
        .sclk_q(sclk_q_a), .cs_active(cs_active_a), .mosi_q(mosi_q_a),
        .edge_a_stb(edge_a_a), .edge_b_stb(edge_b_a),
        .cs_assert_stb(cs_as_a), .cs_deassert_stb(cs_de_a),
        .min_half(min_half_a), .ratio_err(ratio_err_a), .clr_flags(1'b0)
    );

    wire             oe_a;
    wire [CNT_W-1:0] gap_seen, rel_cycles;
    wire             gap_short;

    spi_slave_oe #(.GAP_MIN(GAP_MIN), .CNT_W(CNT_W)) dut (
        .clk(clk), .rst_n(rst_n),
        .cs_active(cs_active_a), .cs_assert_stb(cs_as_a),
        .cs_deassert_stb(cs_de_a),
        .miso_val(miso_val_a),
        .oe(oe_a), .miso_pad(miso_bus),
        .gap_seen(gap_seen), .gap_short(gap_short), .rel_cycles(rel_cycles),
        .clr_flags(clr_flags)
    );

    // --- device B, in two flavours ------------------------------------------
    logic cs_b_pin    = 1'b1;
    logic b_is_fast   = 1'b0;   // 0 = an identical slave, 1 = a zero-latency peer
    logic miso_val_b  = 1'b0;   // a constant 0: contention with A's 1 gives X

    // B as an identical oversampling slave.
    wire        cs_active_b, sclk_q_b, mosi_q_b;
    wire        edge_a_b, edge_b_b, cs_as_b, cs_de_b;
    wire [11:0] min_half_b;
    wire        ratio_err_b;

    spi_slave_frontend #(.SYNC_N(SYNC_N), .HALF_MIN(3), .CNT_W(12)) u_fe_b (
        .clk(clk), .rst_n(rst_n), .cpol(1'b0),
        .sclk_pin(sclk_pin), .cs_n_pin(cs_b_pin), .mosi_pin(mosi_pin),
        .sclk_q(sclk_q_b), .cs_active(cs_active_b), .mosi_q(mosi_q_b),
        .edge_a_stb(edge_a_b), .edge_b_stb(edge_b_b),
        .cs_assert_stb(cs_as_b), .cs_deassert_stb(cs_de_b),
        .min_half(min_half_b), .ratio_err(ratio_err_b), .clr_flags(1'b0)
    );

    wire             oe_b_slow;
    wire [CNT_W-1:0] gap_seen_b, rel_cycles_b;
    wire             gap_short_b;
    wire             pad_b_slow;

    spi_slave_oe #(.GAP_MIN(GAP_MIN), .CNT_W(CNT_W)) u_b_slow (
        .clk(clk), .rst_n(rst_n),
        .cs_active(cs_active_b), .cs_assert_stb(cs_as_b),
        .cs_deassert_stb(cs_de_b),
        .miso_val(miso_val_b),
        .oe(oe_b_slow), .miso_pad(pad_b_slow),
        .gap_seen(gap_seen_b), .gap_short(gap_short_b),
        .rel_cycles(rel_cycles_b), .clr_flags(1'b0)
    );

    // B as a FAST peer: it drives the instant its select pin falls, with no
    // synchroniser at all. This is not a straw man -- a device clocked on SCLK, or
    // one built in a technology where the select pin reaches the output enable
    // through combinational logic, behaves exactly like this.
    wire pad_b_fast = (cs_b_pin == 1'b0) ? miso_val_b : 1'bz;

    // Only one flavour drives at a time.
    assign miso_bus = b_is_fast ? pad_b_fast : pad_b_slow;

    // --- the bus monitor ----------------------------------------------------
    integer contentions, driven_cycles, z_cycles;
    integer a_driving_deselected;

    always_ff @(posedge clk) begin
        if (rst_n) begin
            if (miso_bus === 1'bx) contentions   <= contentions + 1;
            else if (miso_bus === 1'bz) z_cycles <= z_cycles + 1;
            else driven_cycles <= driven_cycles + 1;
            if (oe_a && cs_a_pin) a_driving_deselected <= a_driving_deselected + 1;
        end
    end

    integer errors = 0;

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

    task automatic clear_bus_stats;
        begin
            contentions = 0; driven_cycles = 0; z_cycles = 0;
        end
    endtask

    // A transaction to A followed, after `gap` cycles of both selects high, by a
    // transaction to B. `gap` is the master's t_CSD in system clocks.
    task automatic a_then_b(input integer gap, input integer nbits,
                            input integer half);
        integer i;
        begin
            cs_a_pin = 1'b1; cs_b_pin = 1'b1; sclk_pin = 1'b0;
            adv(10);
            cs_a_pin = 1'b0;
            adv(4);
            for (i = 0; i < nbits * 2; i = i + 1) begin
                sclk_pin = (i % 2 == 0) ? 1'b1 : 1'b0;
                adv(half);
            end
            adv(4);
            cs_a_pin = 1'b1;
            adv(gap);
            cs_b_pin = 1'b0;
            adv(4);
            for (i = 0; i < nbits * 2; i = i + 1) begin
                sclk_pin = (i % 2 == 0) ? 1'b1 : 1'b0;
                adv(half);
            end
            adv(4);
            cs_b_pin = 1'b1;
            adv(10);
        end
    endtask

    integer gap, k, boundary, found;

    initial begin
        clear_bus_stats();
        a_driving_deselected = 0;

        adv(3);
        // 1. RESET RELEASES THE PIN. Checked before reset is removed, because a
        //    slave that drives a shared bus while held in reset makes every other
        //    device on that bus unusable.
        if (oe_a !== 1'b0) begin
            $display("  FAIL: the enable was asserted while in reset");
            errors = errors + 1;
        end
        if (miso_bus !== 1'bz) begin
            $display("  FAIL: the bus was driven while both devices were in reset");
            errors = errors + 1;
        end
        $display("  in reset: the enable is low and the shared bus is released");
        rst_n = 1'b1;
        adv(4);

        // 2. DESELECTED MEANS RELEASED, and the latency is published rather than
        //    implied.
        if (oe_a !== 1'b0) begin
            $display("  FAIL: deselected, the enable is still asserted");
            errors = errors + 1;
        end
        cs_a_pin = 1'b0;
        adv(6);
        if (oe_a !== 1'b1) begin
            $display("  FAIL: selected, the enable never asserted");
            errors = errors + 1;
        end
        cs_a_pin = 1'b1;
        adv(6);
        if (oe_a !== 1'b0) begin
            $display("  FAIL: deselected again, the enable did not drop");
            errors = errors + 1;
        end
        if (rel_cycles != 1) begin
            $display("  FAIL: the published release latency is %0d, expected 1 cycle past the synchroniser",
                     rel_cycles);
            errors = errors + 1;
        end
        $display("  the enable follows the synchronised select and publishes a release latency of %0d cycle past it, so the pin-to-release time is %0d system clocks",
                 rel_cycles, SYNC_N + rel_cycles);

        // 3. TWO IDENTICAL SLAVES NEVER CONTEND, at any gap. The one being
        //    selected is as slow to start as the one being deselected is to stop,
        //    so the subtraction in the header comes out negative.
        b_is_fast = 1'b0;
        clear_bus_stats();
        for (gap = 0; gap <= 6; gap = gap + 1)
            a_then_b(gap, 4, 4);
        if (contentions != 0) begin
            $display("  FAIL: two identical slaves contended on %0d cycles",
                     contentions);
            errors = errors + 1;
        end
        if (driven_cycles == 0) begin
            $display("  FAIL: the bus was never driven -- the monitor proves nothing");
            errors = errors + 1;
        end
        $display("  two identical oversampling slaves, gaps from 0 to 6: %0d cycles driven, %0d released, and no contending cycle at any gap",
                 driven_cycles, z_cycles);

        // 4. A FAST PEER. Now the gap matters, and the boundary is the number.
        b_is_fast = 1'b1;
        boundary  = 99;
        found     = 0;
        for (gap = 0; gap <= 6; gap = gap + 1) begin
            clear_bus_stats();
            a_then_b(gap, 4, 4);
            $display("    gap=%0d: %0d contending cycles", gap, contentions);
            if (contentions == 0 && gap < boundary) boundary = gap;
            if (contentions != 0) found = 1;
        end
        if (!found) begin
            $display("  FAIL: a zero-latency peer never contended -- the experiment proves nothing");
            errors = errors + 1;
        end
        if (boundary != SYNC_N + 1) begin
            $display("  FAIL: the bus became clean at a gap of %0d, expected %0d",
                     boundary, SYNC_N + 1);
            errors = errors + 1;
        end
        $display("  a zero-latency peer contends for every gap below %0d and never at or above it, which is exactly this slave's pin-to-release time",
                 boundary);

        // 5. THE SLAVE'S OWN CS-HIGH TIME is measurable, and a neighbour's is not.
        b_is_fast = 1'b0;
        clr_flags = 1'b1; adv(1); clr_flags = 1'b0;
        // Two transactions to THIS slave, with a generous gap.
        cs_a_pin = 1'b1; adv(10);
        cs_a_pin = 1'b0; adv(8); cs_a_pin = 1'b1; adv(10);
        cs_a_pin = 1'b0; adv(8); cs_a_pin = 1'b1; adv(10);
        if (gap_short) begin
            $display("  FAIL: a generous CS-high time was reported as short");
            errors = errors + 1;
        end
        clr_flags = 1'b1; adv(1); clr_flags = 1'b0;
        // And again with a gap below the requirement.
        cs_a_pin = 1'b0; adv(8); cs_a_pin = 1'b1; adv(1);
        cs_a_pin = 1'b0; adv(8); cs_a_pin = 1'b1; adv(10);
        if (!gap_short) begin
            $display("  FAIL: a one-cycle CS-high time was not reported");
            errors = errors + 1;
        end
        $display("  a generous CS-high time to this slave is accepted and a one-cycle one is reported, with the measured value published as %0d cycles",
                 gap_seen);

        // 6. THE RELEASE LATENCY IS VISIBLE AS DRIVEN-WHILE-DESELECTED CYCLES, and
        //    it is non-zero BY DESIGN. Reporting zero here would mean the enable
        //    had a combinational path from the pin, which is the thing the chapter
        //    says not to build.
        if (a_driving_deselected == 0) begin
            $display("  FAIL: the enable never outlived the select pin -- that implies a combinational path from the pin to the output enable");
            errors = errors + 1;
        end
        $display("  the enable outlived the deselected pin on %0d cycles across the run, which is the registered release the chapter argues for rather than a fault",
                 a_driving_deselected);

        if (errors == 0)
            $display("PASS: the output enable is a single register fed by the synchronised select and by nothing else, so the pin-to-release latency is SYNC_N plus one system clocks and the enable is published rather than implied -- reset releases the shared bus asynchronously, two identical oversampling slaves never contend at any inter-transaction gap because the device being selected is as slow to start driving as the one being deselected is to stop, and a zero-latency neighbour contends for every gap below %0d and never at or above it, which is precisely this slave's release time and therefore the minimum CS-high time it requires of a master it shares a bus with -- the slave's own CS-high time is measurable and reported while a neighbour's is not, and the enable outliving the deselected pin is the registered behaviour the chapter argues for rather than a fault, because the alternative is a combinational path from an asynchronous pin to an output stage that no timing tool can constrain",
                     SYNC_N + 1);
        else
            $display("FAIL: %0d error(s)", errors);
        $finish;
    end

endmodule

// spi_slave_oe_tb.v
//
// This testbench builds a BUS, not a block. Two devices share one MISO net, and
// what is measured is whether the net ever carries a contending value -- which is
// the only place the failure exists, because neither device can see it.
//
// Two neighbours are used, and the difference between them is the chapter's whole
// argument:
//
//   an IDENTICAL oversampling slave, which is as slow to start driving as this one
//   is to stop, so the two never contend at any inter-transaction gap;
//
//   a FAST peer that drives the instant its select pin falls -- an ASIC with no
//   oversampling, or anything clocked on SCLK -- against which the gap requirement
//   stops being free and has to be measured.
//
// The gap sweep then calibrates the number: it finds the shortest gap at which the
// net is clean, and requires it to equal the release latency the slave publishes.

`timescale 1ns/1ps

module spi_slave_oe_tb;

    localparam SYNC_N  = 2;
    localparam GAP_MIN = 3;
    localparam CNT_W   = 8;

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

    // --- the shared bus -----------------------------------------------------
    wire miso_bus;

    // --- device A: the slave under test -------------------------------------
    reg cs_a_pin;
    reg sclk_pin;
    reg mosi_pin;
    reg clr_flags;
    reg miso_val_a;   // a constant 1, so contention with a 0 is visible

    wire        sclk_q_a, cs_active_a, mosi_q_a;
    wire        edge_a_a, edge_b_a, cs_as_a, cs_de_a;
    wire [11:0] min_half_a;
    wire        ratio_err_a;

    spi_slave_frontend #(.SYNC_N(SYNC_N), .HALF_MIN(3), .CNT_W(12)) u_fe_a (
        .clk(clk), .rst_n(rst_n), .cpol(1'b0),
        .sclk_pin(sclk_pin), .cs_n_pin(cs_a_pin), .mosi_pin(mosi_pin),
        .sclk_q(sclk_q_a), .cs_active(cs_active_a), .mosi_q(mosi_q_a),
        .edge_a_stb(edge_a_a), .edge_b_stb(edge_b_a),
        .cs_assert_stb(cs_as_a), .cs_deassert_stb(cs_de_a),
        .min_half(min_half_a), .ratio_err(ratio_err_a), .clr_flags(1'b0)
    );

    wire             oe_a;
    wire [CNT_W-1:0] gap_seen, rel_cycles;
    wire             gap_short;

    spi_slave_oe #(.GAP_MIN(GAP_MIN), .CNT_W(CNT_W)) dut (
        .clk(clk), .rst_n(rst_n),
        .cs_active(cs_active_a), .cs_assert_stb(cs_as_a),
        .cs_deassert_stb(cs_de_a),
        .miso_val(miso_val_a),
        .oe(oe_a), .miso_pad(miso_bus),
        .gap_seen(gap_seen), .gap_short(gap_short), .rel_cycles(rel_cycles),
        .clr_flags(clr_flags)
    );

    // --- device B, in two flavours ------------------------------------------
    reg cs_b_pin;
    reg b_is_fast;   // 0 = an identical slave, 1 = a zero-latency peer
    reg miso_val_b;   // a constant 0: contention with A's 1 gives X

    // B as an identical oversampling slave.
    wire        cs_active_b, sclk_q_b, mosi_q_b;
    wire        edge_a_b, edge_b_b, cs_as_b, cs_de_b;
    wire [11:0] min_half_b;
    wire        ratio_err_b;

    spi_slave_frontend #(.SYNC_N(SYNC_N), .HALF_MIN(3), .CNT_W(12)) u_fe_b (
        .clk(clk), .rst_n(rst_n), .cpol(1'b0),
        .sclk_pin(sclk_pin), .cs_n_pin(cs_b_pin), .mosi_pin(mosi_pin),
        .sclk_q(sclk_q_b), .cs_active(cs_active_b), .mosi_q(mosi_q_b),
        .edge_a_stb(edge_a_b), .edge_b_stb(edge_b_b),
        .cs_assert_stb(cs_as_b), .cs_deassert_stb(cs_de_b),
        .min_half(min_half_b), .ratio_err(ratio_err_b), .clr_flags(1'b0)
    );

    wire             oe_b_slow;
    wire [CNT_W-1:0] gap_seen_b, rel_cycles_b;
    wire             gap_short_b;
    wire             pad_b_slow;

    spi_slave_oe #(.GAP_MIN(GAP_MIN), .CNT_W(CNT_W)) u_b_slow (
        .clk(clk), .rst_n(rst_n),
        .cs_active(cs_active_b), .cs_assert_stb(cs_as_b),
        .cs_deassert_stb(cs_de_b),
        .miso_val(miso_val_b),
        .oe(oe_b_slow), .miso_pad(pad_b_slow),
        .gap_seen(gap_seen_b), .gap_short(gap_short_b),
        .rel_cycles(rel_cycles_b), .clr_flags(1'b0)
    );

    // B as a FAST peer: it drives the instant its select pin falls, with no
    // synchroniser at all. This is not a straw man -- a device clocked on SCLK, or
    // one built in a technology where the select pin reaches the output enable
    // through combinational logic, behaves exactly like this.
    wire pad_b_fast = (cs_b_pin == 1'b0) ? miso_val_b : 1'bz;

    // Only one flavour drives at a time.
    assign miso_bus = b_is_fast ? pad_b_fast : pad_b_slow;

    // --- the bus monitor ----------------------------------------------------
    integer contentions, driven_cycles, z_cycles;
    integer a_driving_deselected;

    always @(posedge clk) begin
        if (rst_n) begin
            if (miso_bus === 1'bx) contentions   <= contentions + 1;
            else if (miso_bus === 1'bz) z_cycles <= z_cycles + 1;
            else driven_cycles <= driven_cycles + 1;
            if (oe_a && cs_a_pin) a_driving_deselected <= a_driving_deselected + 1;
        end
    end

    integer errors;

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

    task clear_bus_stats;
        begin
            contentions = 0; driven_cycles = 0; z_cycles = 0;
        end
    endtask

    // A transaction to A followed, after `gap` cycles of both selects high, by a
    // transaction to B. `gap` is the master's t_CSD in system clocks.
        task a_then_b;
        input integer gap;
        input integer nbits;
        input integer half;
        integer i;
        begin
            cs_a_pin = 1'b1; cs_b_pin = 1'b1; sclk_pin = 1'b0;
            adv(10);
            cs_a_pin = 1'b0;
            adv(4);
            for (i = 0; i < nbits * 2; i = i + 1) begin
                sclk_pin = (i % 2 == 0) ? 1'b1 : 1'b0;
                adv(half);
            end
            adv(4);
            cs_a_pin = 1'b1;
            adv(gap);
            cs_b_pin = 1'b0;
            adv(4);
            for (i = 0; i < nbits * 2; i = i + 1) begin
                sclk_pin = (i % 2 == 0) ? 1'b1 : 1'b0;
                adv(half);
            end
            adv(4);
            cs_b_pin = 1'b1;
            adv(10);
        end
    endtask

    integer gap, k, boundary, found;

    initial begin
        clear_bus_stats();
        a_driving_deselected = 0;

        adv(3);
        // 1. RESET RELEASES THE PIN. Checked before reset is removed, because a
        //    slave that drives a shared bus while held in reset makes every other
        //    device on that bus unusable.
        if (oe_a !== 1'b0) begin
            $display("  FAIL: the enable was asserted while in reset");
            errors = errors + 1;
        end
        if (miso_bus !== 1'bz) begin
            $display("  FAIL: the bus was driven while both devices were in reset");
            errors = errors + 1;
        end
        $display("  in reset: the enable is low and the shared bus is released");
        rst_n = 1'b1;
        adv(4);

        // 2. DESELECTED MEANS RELEASED, and the latency is published rather than
        //    implied.
        if (oe_a !== 1'b0) begin
            $display("  FAIL: deselected, the enable is still asserted");
            errors = errors + 1;
        end
        cs_a_pin = 1'b0;
        adv(6);
        if (oe_a !== 1'b1) begin
            $display("  FAIL: selected, the enable never asserted");
            errors = errors + 1;
        end
        cs_a_pin = 1'b1;
        adv(6);
        if (oe_a !== 1'b0) begin
            $display("  FAIL: deselected again, the enable did not drop");
            errors = errors + 1;
        end
        if (rel_cycles != 1) begin
            $display("  FAIL: the published release latency is %0d, expected 1 cycle past the synchroniser",
                     rel_cycles);
            errors = errors + 1;
        end
        $display("  the enable follows the synchronised select and publishes a release latency of %0d cycle past it, so the pin-to-release time is %0d system clocks",
                 rel_cycles, SYNC_N + rel_cycles);

        // 3. TWO IDENTICAL SLAVES NEVER CONTEND, at any gap. The one being
        //    selected is as slow to start as the one being deselected is to stop,
        //    so the subtraction in the header comes out negative.
        b_is_fast = 1'b0;
        clear_bus_stats();
        for (gap = 0; gap <= 6; gap = gap + 1)
            a_then_b(gap, 4, 4);
        if (contentions != 0) begin
            $display("  FAIL: two identical slaves contended on %0d cycles",
                     contentions);
            errors = errors + 1;
        end
        if (driven_cycles == 0) begin
            $display("  FAIL: the bus was never driven -- the monitor proves nothing");
            errors = errors + 1;
        end
        $display("  two identical oversampling slaves, gaps from 0 to 6: %0d cycles driven, %0d released, and no contending cycle at any gap",
                 driven_cycles, z_cycles);

        // 4. A FAST PEER. Now the gap matters, and the boundary is the number.
        b_is_fast = 1'b1;
        boundary  = 99;
        found     = 0;
        for (gap = 0; gap <= 6; gap = gap + 1) begin
            clear_bus_stats();
            a_then_b(gap, 4, 4);
            $display("    gap=%0d: %0d contending cycles", gap, contentions);
            if (contentions == 0 && gap < boundary) boundary = gap;
            if (contentions != 0) found = 1;
        end
        if (!found) begin
            $display("  FAIL: a zero-latency peer never contended -- the experiment proves nothing");
            errors = errors + 1;
        end
        if (boundary != SYNC_N + 1) begin
            $display("  FAIL: the bus became clean at a gap of %0d, expected %0d",
                     boundary, SYNC_N + 1);
            errors = errors + 1;
        end
        $display("  a zero-latency peer contends for every gap below %0d and never at or above it, which is exactly this slave's pin-to-release time",
                 boundary);

        // 5. THE SLAVE'S OWN CS-HIGH TIME is measurable, and a neighbour's is not.
        b_is_fast = 1'b0;
        clr_flags = 1'b1; adv(1); clr_flags = 1'b0;
        // Two transactions to THIS slave, with a generous gap.
        cs_a_pin = 1'b1; adv(10);
        cs_a_pin = 1'b0; adv(8); cs_a_pin = 1'b1; adv(10);
        cs_a_pin = 1'b0; adv(8); cs_a_pin = 1'b1; adv(10);
        if (gap_short) begin
            $display("  FAIL: a generous CS-high time was reported as short");
            errors = errors + 1;
        end
        clr_flags = 1'b1; adv(1); clr_flags = 1'b0;
        // And again with a gap below the requirement.
        cs_a_pin = 1'b0; adv(8); cs_a_pin = 1'b1; adv(1);
        cs_a_pin = 1'b0; adv(8); cs_a_pin = 1'b1; adv(10);
        if (!gap_short) begin
            $display("  FAIL: a one-cycle CS-high time was not reported");
            errors = errors + 1;
        end
        $display("  a generous CS-high time to this slave is accepted and a one-cycle one is reported, with the measured value published as %0d cycles",
                 gap_seen);

        // 6. THE RELEASE LATENCY IS VISIBLE AS DRIVEN-WHILE-DESELECTED CYCLES, and
        //    it is non-zero BY DESIGN. Reporting zero here would mean the enable
        //    had a combinational path from the pin, which is the thing the chapter
        //    says not to build.
        if (a_driving_deselected == 0) begin
            $display("  FAIL: the enable never outlived the select pin -- that implies a combinational path from the pin to the output enable");
            errors = errors + 1;
        end
        $display("  the enable outlived the deselected pin on %0d cycles across the run, which is the registered release the chapter argues for rather than a fault",
                 a_driving_deselected);

        if (errors == 0)
            $display("PASS: the output enable is a single register fed by the synchronised select and by nothing else, so the pin-to-release latency is SYNC_N plus one system clocks and the enable is published rather than implied -- reset releases the shared bus asynchronously, two identical oversampling slaves never contend at any inter-transaction gap because the device being selected is as slow to start driving as the one being deselected is to stop, and a zero-latency neighbour contends for every gap below %0d and never at or above it, which is precisely this slave's release time and therefore the minimum CS-high time it requires of a master it shares a bus with -- the slave's own CS-high time is measurable and reported while a neighbour's is not, and the enable outliving the deselected pin is the registered behaviour the chapter argues for rather than a fault, because the alternative is a combinational path from an asynchronous pin to an output stage that no timing tool can constrain",
                     SYNC_N + 1);
        else
            $display("FAIL: %0d error(s)", errors);
        $finish;
    end


    initial begin
        clk = 1'b0;
        rst_n = 1'b0;
        cs_a_pin = 1'b1;
        sclk_pin = 1'b0;
        mosi_pin = 1'b0;
        clr_flags = 1'b0;
        miso_val_a = 1'b1;
        cs_b_pin = 1'b1;
        b_is_fast = 1'b0;
        miso_val_b = 1'b0;
        errors = 0;
    end

endmodule

-- spi_slave_oe_tb.vhd
--
-- This testbench builds a BUS, not a block. Two devices share one MISO net, and what
-- is measured is whether the net ever carries a contending value -- which is the only
-- place the failure exists, because neither device can see it.
--
-- Two neighbours are used, and the difference between them is the chapter's whole
-- argument:
--
--   an IDENTICAL oversampling slave, which is as slow to start driving as this one is
--   to stop, so the two never contend at any inter-transaction gap;
--
--   a FAST peer that drives the instant its select pin falls -- an ASIC with no
--   oversampling, or anything clocked on SCLK -- against which the gap requirement
--   stops being free and has to be measured.
--
-- The gap sweep then calibrates the number: it finds the shortest gap at which the
-- net is clean, and requires it to equal the release latency the slave publishes.

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

entity spi_slave_oe_tb is
end entity;

architecture sim of spi_slave_oe_tb is

    constant SYNC_N  : positive := 2;
    constant GAP_MIN : positive := 3;
    constant CNT_W   : positive := 8;

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

    -- the shared bus
    signal miso_bus : std_logic;

    -- device A: the slave under test
    signal cs_a_pin   : std_logic := '1';
    signal sclk_pin   : std_logic := '0';
    signal mosi_pin   : std_logic := '0';
    signal clr_flags  : std_logic := '0';
    signal miso_val_a : std_logic := '1';   -- a constant 1, so a 0 contends visibly

    signal sclk_q_a, cs_active_a, mosi_q_a : std_logic;
    signal edge_a_a, edge_b_a, cs_as_a, cs_de_a : std_logic;
    signal min_half_a : unsigned(11 downto 0);
    signal ratio_err_a : std_logic;

    signal oe_a : std_logic;
    signal gap_seen, rel_cycles : unsigned(CNT_W - 1 downto 0);
    signal gap_short : std_logic;

    -- device B, in two flavours
    signal cs_b_pin   : std_logic := '1';
    signal b_is_fast  : boolean   := false;
    signal miso_val_b : std_logic := '0';   -- a constant 0: contention gives X

    signal sclk_q_b, cs_active_b, mosi_q_b : std_logic;
    signal edge_a_b, edge_b_b, cs_as_b, cs_de_b : std_logic;
    signal min_half_b : unsigned(11 downto 0);
    signal ratio_err_b : std_logic;
    signal oe_b_slow : std_logic;
    signal gap_seen_b, rel_cycles_b : unsigned(CNT_W - 1 downto 0);
    signal gap_short_b : std_logic;
    signal pad_b_slow  : std_logic;
    signal pad_b_fast  : std_logic;

    signal contentions, driven_cycles, z_cycles : natural := 0;
    signal a_driving_deselected : natural := 0;
    signal clr_stats : std_logic := '0';

    signal errors : natural := 0;

begin

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

    u_fe_a : entity work.spi_slave_frontend
        generic map (SYNC_N => SYNC_N, HALF_MIN => 3, CNT_W => 12)
        port map (clk => clk, rst_n => rst_n, cpol => '0',
                  sclk_pin => sclk_pin, cs_n_pin => cs_a_pin,
                  mosi_pin => mosi_pin,
                  sclk_q => sclk_q_a, cs_active => cs_active_a,
                  mosi_q => mosi_q_a,
                  edge_a_stb => edge_a_a, edge_b_stb => edge_b_a,
                  cs_assert_stb => cs_as_a, cs_deassert_stb => cs_de_a,
                  min_half => min_half_a, ratio_err => ratio_err_a,
                  clr_flags => '0');

    dut : entity work.spi_slave_oe
        generic map (GAP_MIN => GAP_MIN, CNT_W => CNT_W)
        port map (clk => clk, rst_n => rst_n,
                  cs_active => cs_active_a, cs_assert_stb => cs_as_a,
                  cs_deassert_stb => cs_de_a,
                  miso_val => miso_val_a,
                  oe => oe_a, miso_pad => miso_bus,
                  gap_seen => gap_seen, gap_short => gap_short,
                  rel_cycles => rel_cycles, clr_flags => clr_flags);

    u_fe_b : entity work.spi_slave_frontend
        generic map (SYNC_N => SYNC_N, HALF_MIN => 3, CNT_W => 12)
        port map (clk => clk, rst_n => rst_n, cpol => '0',
                  sclk_pin => sclk_pin, cs_n_pin => cs_b_pin,
                  mosi_pin => mosi_pin,
                  sclk_q => sclk_q_b, cs_active => cs_active_b,
                  mosi_q => mosi_q_b,
                  edge_a_stb => edge_a_b, edge_b_stb => edge_b_b,
                  cs_assert_stb => cs_as_b, cs_deassert_stb => cs_de_b,
                  min_half => min_half_b, ratio_err => ratio_err_b,
                  clr_flags => '0');

    u_b_slow : entity work.spi_slave_oe
        generic map (GAP_MIN => GAP_MIN, CNT_W => CNT_W)
        port map (clk => clk, rst_n => rst_n,
                  cs_active => cs_active_b, cs_assert_stb => cs_as_b,
                  cs_deassert_stb => cs_de_b,
                  miso_val => miso_val_b,
                  oe => oe_b_slow, miso_pad => pad_b_slow,
                  gap_seen => gap_seen_b, gap_short => gap_short_b,
                  rel_cycles => rel_cycles_b, clr_flags => '0');

    -- B as a FAST peer: it drives the instant its select pin falls, with no
    -- synchroniser at all. Not a straw man -- a device clocked on SCLK, or one where
    -- the select pin reaches the output enable combinationally, behaves like this.
    -- Only one flavour drives at a time, and the net is resolved so a genuine
    -- conflict shows as 'X'.
    --
    -- Written as a flat selection rather than a nested conditional expression:
    -- VHDL's `when ... else` is not an expression, so it cannot appear inside one.
    pad_b_fast <= miso_val_b when (b_is_fast and cs_b_pin = '0') else 'Z';
    miso_bus   <= pad_b_fast when b_is_fast else pad_b_slow;

    monitor : process (clk)
    begin
        if rising_edge(clk) then
            if clr_stats = '1' then
                contentions   <= 0;
                driven_cycles <= 0;
                z_cycles      <= 0;
            elsif rst_n = '1' then
                if miso_bus = 'X' then
                    contentions <= contentions + 1;
                elsif miso_bus = 'Z' then
                    z_cycles <= z_cycles + 1;
                else
                    driven_cycles <= driven_cycles + 1;
                end if;
                if oe_a = '1' and cs_a_pin = '1' then
                    a_driving_deselected <= a_driving_deselected + 1;
                end if;
            end if;
        end if;
    end process;

    stim : process
        variable errs : natural := 0;
        variable boundary : integer;
        variable found : boolean;

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

        procedure clear_bus_stats is
        begin
            clr_stats <= '1';
            wait until falling_edge(clk);
            clr_stats <= '0';
        end procedure;

        -- A transaction to A followed, after `gap` cycles of both selects high, by a
        -- transaction to B. `gap` is the master's t_CSD in system clocks.
        procedure a_then_b(gap : natural; nbits : natural; half : natural) is
        begin
            cs_a_pin <= '1'; cs_b_pin <= '1'; sclk_pin <= '0';
            adv(10);
            cs_a_pin <= '0';
            adv(4);
            for i in 0 to nbits * 2 - 1 loop
                if (i mod 2) = 0 then sclk_pin <= '1'; else sclk_pin <= '0'; end if;
                adv(half);
            end loop;
            adv(4);
            cs_a_pin <= '1';
            if gap > 0 then adv(gap); end if;
            cs_b_pin <= '0';
            adv(4);
            for i in 0 to nbits * 2 - 1 loop
                if (i mod 2) = 0 then sclk_pin <= '1'; else sclk_pin <= '0'; end if;
                adv(half);
            end loop;
            adv(4);
            cs_b_pin <= '1';
            adv(10);
        end procedure;
    begin
        adv(3);
        -- 1. RESET RELEASES THE PIN.
        if oe_a /= '0' then
            report "  FAIL: the enable was asserted while in reset";
            errs := errs + 1;
        end if;
        if miso_bus /= 'Z' then
            report "  FAIL: the bus was driven while both devices were in reset";
            errs := errs + 1;
        end if;
        report "  in reset: the enable is low and the shared bus is released";
        rst_n <= '1';
        adv(4);

        -- 2. DESELECTED MEANS RELEASED, and the latency is published.
        if oe_a /= '0' then
            report "  FAIL: deselected, the enable is still asserted";
            errs := errs + 1;
        end if;
        cs_a_pin <= '0';
        adv(6);
        if oe_a /= '1' then
            report "  FAIL: selected, the enable never asserted";
            errs := errs + 1;
        end if;
        cs_a_pin <= '1';
        adv(6);
        if oe_a /= '0' then
            report "  FAIL: deselected again, the enable did not drop";
            errs := errs + 1;
        end if;
        if to_integer(rel_cycles) /= 1 then
            report "  FAIL: the published release latency is " &
                   integer'image(to_integer(rel_cycles)) & ", expected 1";
            errs := errs + 1;
        end if;
        report "  the enable follows the synchronised select and publishes a release latency of " &
               integer'image(to_integer(rel_cycles)) &
               " cycle past it, so the pin-to-release time is " &
               integer'image(SYNC_N + to_integer(rel_cycles)) & " system clocks";

        -- 3. TWO IDENTICAL SLAVES NEVER CONTEND, at any gap.
        b_is_fast <= false;
        clear_bus_stats;
        for gap in 0 to 6 loop
            a_then_b(gap, 4, 4);
        end loop;
        if contentions /= 0 then
            report "  FAIL: two identical slaves contended on " &
                   integer'image(contentions) & " cycles";
            errs := errs + 1;
        end if;
        if driven_cycles = 0 then
            report "  FAIL: the bus was never driven -- the monitor proves nothing";
            errs := errs + 1;
        end if;
        report "  two identical oversampling slaves, gaps from 0 to 6: " &
               integer'image(driven_cycles) & " cycles driven, " &
               integer'image(z_cycles) &
               " released, and no contending cycle at any gap";

        -- 4. A FAST PEER. Now the gap matters, and the boundary is the number.
        b_is_fast <= true;
        boundary  := 99;
        found     := false;
        for gap in 0 to 6 loop
            clear_bus_stats;
            a_then_b(gap, 4, 4);
            report "    gap=" & integer'image(gap) & ": " &
                   integer'image(contentions) & " contending cycles";
            if contentions = 0 and gap < boundary then boundary := gap; end if;
            if contentions /= 0 then found := true; end if;
        end loop;
        if not found then
            report "  FAIL: a zero-latency peer never contended -- the experiment proves nothing";
            errs := errs + 1;
        end if;
        if boundary /= SYNC_N + 1 then
            report "  FAIL: the bus became clean at a gap of " &
                   integer'image(boundary) & ", expected " &
                   integer'image(SYNC_N + 1);
            errs := errs + 1;
        end if;
        report "  a zero-latency peer contends for every gap below " &
               integer'image(boundary) &
               " and never at or above it, which is exactly this slave's pin-to-release time";

        -- 5. THE SLAVE'S OWN CS-HIGH TIME is measurable, and a neighbour's is not.
        b_is_fast <= false;
        clr_flags <= '1'; adv(1); clr_flags <= '0';
        cs_a_pin <= '1'; adv(10);
        cs_a_pin <= '0'; adv(8); cs_a_pin <= '1'; adv(10);
        cs_a_pin <= '0'; adv(8); cs_a_pin <= '1'; adv(10);
        if gap_short = '1' then
            report "  FAIL: a generous CS-high time was reported as short";
            errs := errs + 1;
        end if;
        clr_flags <= '1'; adv(1); clr_flags <= '0';
        cs_a_pin <= '0'; adv(8); cs_a_pin <= '1'; adv(1);
        cs_a_pin <= '0'; adv(8); cs_a_pin <= '1'; adv(10);
        if gap_short /= '1' then
            report "  FAIL: a one-cycle CS-high time was not reported";
            errs := errs + 1;
        end if;
        report "  a generous CS-high time to this slave is accepted and a one-cycle one is reported, with the measured value published as " &
               integer'image(to_integer(gap_seen)) & " cycles";

        -- 6. THE RELEASE LATENCY IS VISIBLE AS DRIVEN-WHILE-DESELECTED CYCLES, and
        --    it is non-zero BY DESIGN.
        if a_driving_deselected = 0 then
            report "  FAIL: the enable never outlived the select pin -- that implies a combinational path from the pin to the output enable";
            errs := errs + 1;
        end if;
        report "  the enable outlived the deselected pin on " &
               integer'image(a_driving_deselected) &
               " cycles across the run, which is the registered release the chapter argues for rather than a fault";

        errors <= errs;
        if errs = 0 then
            report "PASS: the output enable is a single register fed by the synchronised select and by nothing else, so the pin-to-release latency is SYNC_N plus one system clocks and the enable is published rather than implied -- reset releases the shared bus asynchronously, two identical oversampling slaves never contend at any inter-transaction gap because the device being selected is as slow to start driving as the one being deselected is to stop, and a zero-latency neighbour contends for every gap below " & integer'image(SYNC_N + 1) & " and never at or above it, which is precisely this slave's release time and therefore the minimum CS-high time it requires of a master it shares a bus with -- the slave's own CS-high time is measurable and reported while a neighbour's is not, and the enable outliving the deselected pin is the registered behaviour the chapter argues for rather than a fault, because the alternative is a combinational path from an asynchronous pin to an output stage that no timing tool can constrain";
        else
            report "FAIL: " & integer'image(errs) & " error(s)" severity error;
        end if;
        halt <= true;
        wait;
    end process;

end architecture;

// Properties for the output stage. The first is the one that matters, and it is
// about a wire rather than about a block -- which is why it needs the second
// driver that test 3 and 4 provide.

property p_never_drive_while_deselected;
    // The core obligation. Note it is stated against the REGISTERED enable and
    // the synchronised select, because those are the only two things that exist
    // in the same time frame.
    @(posedge clk) disable iff (!rst_n)
        !cs_active |=> !oe;
endproperty

property p_released_in_reset;
    // Not inside a disable iff, deliberately: this property is about the reset
    // state itself, so disabling it during reset would remove its only content.
    @(posedge clk)
        !rst_n |-> !oe;
endproperty

property p_pad_z_when_disabled;
    // The pad is high-impedance exactly when the enable is low. A four-state
    // comparison, because === is the only operator that distinguishes z from x.
    @(posedge clk) disable iff (!rst_n)
        !oe |-> (miso_pad === 1'bz);
endproperty

property p_pad_driven_when_enabled;
    // And the converse: enabled means driving a real value, never x. An x here
    // means miso_val is undefined, which is a transmit-path fault surfacing on
    // the one pin where it becomes a board problem.
    @(posedge clk) disable iff (!rst_n)
        oe |-> (miso_pad === 1'b0 || miso_pad === 1'b1);
endproperty

property p_gap_measured_at_assert;
    // The measurement is taken at the assert and held, not continuously
    // updated -- a continuously updated value reports the current idle time
    // rather than the gap that preceded the last transaction.
    @(posedge clk) disable iff (!rst_n)
        (!cs_assert_stb && !clr_flags) |=> $stable(gap_seen);
endproperty

// Coverage. The axis is the GAP, and the second axis is the peer -- because the
// requirement is a function of the neighbour and a suite with one peer type has
// tested one of the two answers.

covergroup cg_oe @(posedge clk iff cs_assert_stb);
    option.per_instance = 1;

    gap: coverpoint gap_seen {
        bins one     = {1};
        bins below   = {2};                   // below SYNC_N + 1 at SYNC_N = 2
        bins exact   = {3};                   // exactly SYNC_N + 1
        bins margin  = {4, 5};
        bins roomy   = {[6:$]};
    }

    // The peer's assert latency is what makes the requirement bite, so it is a
    // first-class coverage axis rather than a testbench detail.
    peer: coverpoint peer_assert_latency {
        bins immediate   = {0};               // an ASIC, or SCLK-clocked
        bins one_cycle   = {1};
        bins matched     = {[2:3]};           // another oversampling slave
        bins slower      = {[4:$]};
    }

    // Whether contention actually occurred, observed on the wire by the bench.
    // Crossed with the gap, this is the calibration: the boundary must fall at
    // exactly one place.
    contended: coverpoint saw_both_driving { bins no = {0}; bins yes = {1}; }

    x_gap_peer:      cross gap, peer;
    x_gap_contended: cross gap, contended;

endgroup