Input and Output Delay Constraints

   * `set_input_delay` still applies -- it is about the PORT -- but the slack it
     produces depends on logic that has nothing to do with the board;
   * a tool asked to pull the register into the pad cannot, because there is logic
     between the pad and the register;
   * and a report showing the path failing does not say whether the fault is the
     board's arrival time or somebody's combinational logic.

   LEAD  >= SYNC_N + 3     chip select to the first SCLK edge   (was SYNC_N + 2, 14.4)
   HALF  >= SYNC_N + 2     one SCLK half-period                 (was SYNC_N + 1)
   GAP   >= SYNC_N + 2     chip select high between transactions (was SYNC_N + 1, 14.5)

   NOT CHECKED, and not checkable:
     whether set_input_delay on the three inputs describes the board
     whether set_output_delay on MISO describes it
     whether SCLK is declared as DATA rather than as a clock
     whether the pad registers were actually placed in the pads

# spi_slave.xdc -- Xilinx Vivado
#
# The system clock. This is the ONLY clock in the design, which is the whole point
# of Architecture B (Chapter 15.3): SCLK is data.
create_clock -period 10.000 -name sys_clk [get_ports clk]

# ---------------------------------------------------------------------------
# SCLK, CS# and MOSI are INPUTS, not clocks. There is deliberately NO
# create_clock on sclk_pin -- a design review that finds one has found the
# problem, because it means somebody has told the tool to build a clock tree for
# a signal the RTL samples as data.
# ---------------------------------------------------------------------------
#
# The numbers: the master launches SCLK and MOSI from its own clock, and they
# arrive here after the master's clock-to-out plus the board delay. A 10 MHz
# master with a 3 ns output delay and a 1 ns trace gives a 4 ns arrival, with a
# minimum of 1 ns if the master is fast and the trace short.
#
# These are stated relative to sys_clk because the design samples them with
# sys_clk. That is not a fiction -- it is exactly what the pad register does.
set_input_delay -clock sys_clk -max 4.000 [get_ports {sclk_pin cs_n_pin mosi_pin}]
set_input_delay -clock sys_clk -min 1.000 [get_ports {sclk_pin cs_n_pin mosi_pin}]

# MISO is driven from a registered value AND a registered enable (see the RTL).
# The master samples it on its own edge, so the requirement is that it is valid
# early enough for the master's setup plus the return trace.
set_output_delay -clock sys_clk -max 5.000 [get_ports miso_pad]
set_output_delay -clock sys_clk -min 0.500 [get_ports miso_pad]

# ---------------------------------------------------------------------------
# The synchroniser chains. ASYNC_REG does two jobs and both matter:
#   1. it stops the tool retiming or SRL-inferring the chain, whose DEPTH the
#      design's correctness depends on (Chapter 14.1);
#   2. it tells timing analysis that the first flop's input is an asynchronous
#      arrival rather than a path to report as failing forever.
#
# Applied to the CELLS rather than to a hierarchy, so that a refactor that moves
# them does not silently drop the attribute.
# ---------------------------------------------------------------------------
set_property ASYNC_REG TRUE [get_cells -hierarchical -filter {NAME =~ *sync_sr_reg*}]
set_property SHREG_EXTRACT NO [get_cells -hierarchical -filter {NAME =~ *sync_sr_reg*}]

# Ask for the pad registers. This is a REQUEST: the tool honours it when nothing
# sits between the pin and the flop, and WARNS when something does (Chapter 15.8).
# The warning is in a log of ten thousand lines, so the mechanism is the structure
# and this only makes the tool's refusal visible.
set_property IOB TRUE [get_ports {sclk_pin cs_n_pin mosi_pin miso_pad}]

# The one path that crosses domains in an Architecture A design (Chapter 15.2).
# Not needed in Architecture B, which has one domain -- and the fact that this
# list is SHORT is the reason to prefer a FIFO over an ad-hoc crossing: two
# exceptions can be reviewed.
# set_max_delay -datapath_only 10.000 -from [get_cells u_a/word_src_reg*] \
#                                     -to   [get_cells u_a/rx_data_reg*]

# spi_slave.sdc -- Intel Quartus Prime
#
# Same three claims in a different dialect. The differences are mechanical; the
# one that is NOT mechanical is the synchroniser identification, which Quartus
# needs in order to exempt the chain from its own CDC analysis.

create_clock -period 10.000 -name sys_clk [get_ports clk]

# SCLK, CS# and MOSI as inputs. Again: no create_clock on sclk_pin.
set_input_delay -clock sys_clk -max 4.000 [get_ports {sclk_pin cs_n_pin mosi_pin}]
set_input_delay -clock sys_clk -min 1.000 [get_ports {sclk_pin cs_n_pin mosi_pin}]

set_output_delay -clock sys_clk -max 5.000 [get_ports miso_pad]
set_output_delay -clock sys_clk -min 0.500 [get_ports miso_pad]

# Quartus's equivalent of ASYNC_REG is an assignment rather than an SDC property,
# so it lives in the QSF -- which is worth knowing, because a team that puts
# everything in the SDC will find the chain retimed and the attribute absent.
#
#   set_instance_assignment -name SYNCHRONIZER_IDENTIFICATION \
#       "FORCED IF ASYNCHRONOUS" -to "*sync_sr[0]"
#
# And shift-register inference is disabled per-entity in the QSF too:
#   set_instance_assignment -name AUTO_SHIFT_REGISTER_RECOGNITION OFF \
#       -to "spi_slave_frontend"

# The Architecture A crossing, if present.
# set_max_skew -from [get_registers {*word_src*}] -to [get_registers {*rx_data*}] 2.0
# set_net_delay -from [get_registers {*word_src*}] -to [get_registers {*rx_data*}] -max 8.0

# spi_slave_generic.sdc
#
# The portable subset, and it is worth knowing how small it is: the CLOCK and the
# DELAYS are portable, and everything that protects a synchroniser is not.
#
# That asymmetry is the practical reason a CDC review cannot be replaced by a
# constraints review -- half of what protects the crossings lives in
# vendor-specific attributes, in a different file, in a different language.

create_clock -period 10.000 -name sys_clk [get_ports clk]

set_input_delay  -clock sys_clk -max 4.000 [get_ports sclk_pin]
set_input_delay  -clock sys_clk -min 1.000 [get_ports sclk_pin]
set_input_delay  -clock sys_clk -max 4.000 [get_ports cs_n_pin]
set_input_delay  -clock sys_clk -min 1.000 [get_ports cs_n_pin]
set_input_delay  -clock sys_clk -max 4.000 [get_ports mosi_pin]
set_input_delay  -clock sys_clk -min 1.000 [get_ports mosi_pin]

set_output_delay -clock sys_clk -max 5.000 [get_ports miso_pad]
set_output_delay -clock sys_clk -min 0.500 [get_ports miso_pad]

# A false path is the WRONG exception for a data crossing, and it appears here as
# a warning rather than as advice. `set_false_path` tells the tool the path does
# not matter; a data crossing's path DOES matter -- its skew has to be bounded, or
# Chapter 15.5's incoherence follows. The right exception is a bounded one:
# set_max_delay -datapath_only, or set_net_delay, or the vendor's skew constraint.
#
#   set_false_path -from [get_clocks sclk_dom] -to [get_clocks sys_clk]   # NO

// spi_io_shell.sv
//
// Chapter 15.7 -- the module a constraints file is written about.
//
// Modules 13, 14 and the first half of 15 have deferred the constraints file three
// times, and the reason is that it cannot be written from inside the RTL. It is
// about the BOARD: how long after the master's clock edge its data is valid at this
// device's pin, and how long after this device's clock edge its data is valid at the
// master's. Neither number is in any HDL file, and no simulation contains either.
//
// So this file is small on purpose. It is the SHELL -- the pad registers and nothing
// else -- and it exists to give the constraints file something with named ports and
// a known latency to be written against.
//
// WHAT THE SHELL IS FOR, BEYOND TIDINESS.
//
// A constraint is a claim about a PATH, and the path runs from a pin to a register.
// If the first register on that path is three levels down inside a hierarchy, behind
// a synchroniser that someone may deepen and a mux someone may add, then:
//
//   * `set_input_delay` still applies -- it is about the port -- but the slack it
//     produces depends on logic that has nothing to do with the board;
//   * a tool asked to pull the register into the pad (`IOB = TRUE`) cannot, because
//     there is logic between the pad and the register;
//   * and a report that shows the path failing does not say whether the fault is the
//     board's arrival time or somebody's combinational logic.
//
// Putting exactly one register between each pin and everything else makes the path a
// constraints file talks about the same path the tool reports on.
//
// THE LATENCY IS THE NUMBER THE CONSTRAINTS ASSUME, AND IT IS CHECKABLE.
//
// This shell adds ONE cycle to every input before the rest of the design sees it. So
// the slave's recovered-edge latency becomes SYNC_N + 1 rather than SYNC_N, and
// every derived number in Module 14 moves by one:
//
//     LEAD  >= SYNC_N + 3     (was SYNC_N + 2, Chapter 14.4)
//     HALF  >= SYNC_N + 2     (was SYNC_N + 1)
//     GAP   >= SYNC_N + 2     (was SYNC_N + 1)
//
// That is the thing worth taking from this file: ADDING A PAD REGISTER CHANGES A
// DATASHEET. It is the right thing to do for timing closure and it is not free, and
// a team that adds it late discovers the cost as a customer's master no longer
// working. The testbench measures the latency so that the number in the constraints
// file and the number in the datasheet are the same number.
//
// WHAT IS DELIBERATELY NOT HERE. No logic. Not an edge detector, not a synchroniser,
// not a polarity comparison. Anything that is not a register belongs behind the
// shell, because anything that is not a register is what stops the register reaching
// the pad.

module spi_io_shell #(
    // The output enable is registered too, and its reset value matters more than any
    // other bit in the design: a shell that comes up driving makes every other
    // device on the MISO net unreadable (Chapter 14.5).
    parameter bit OE_RESET = 1'b0
) (
    input  wire  clk,
    input  wire  rst_n,

    // --- the pins ---------------------------------------------------------
    input  wire  sclk_pin,
    input  wire  cs_n_pin,
    input  wire  mosi_pin,
    output wire  miso_pad,

    // --- the core side: one cycle later, and nothing else different -------
    output reg   sclk_i,
    output reg   cs_n_i,
    output reg   mosi_i,
    input  wire  miso_o,
    input  wire  miso_oe
);

    // Input pad registers. One flop, no logic, no reset -- and the missing reset is
    // deliberate rather than an omission worth flagging: resetting an input pad
    // register adds a mux in front of it on some devices, which is exactly the logic
    // that stops it being placed in the pad. The values are meaningless until the
    // core's own reset has released anyway, and the core resets its synchronisers.
    //
    // The exception is CS, which is reset to DESELECTED. A slave that wakes up
    // believing it is selected is worse than one that wakes up believing it is not,
    // and one mux is a fair price for that (Chapter 14.8).
    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            sclk_i <= 1'b0;
            cs_n_i <= 1'b1;        // deselected
            mosi_i <= 1'b0;
        end else begin
            sclk_i <= sclk_pin;
            cs_n_i <= cs_n_pin;
            mosi_i <= mosi_pin;
        end
    end

    // Output pad registers. Both the value AND the enable are registered, and they
    // must be registered TOGETHER -- a design that registers the value and drives
    // the enable combinationally has a pad whose turn-on time depends on fabric
    // logic, which is the one thing `set_output_delay` cannot describe.
    reg miso_r, oe_r;

    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            miso_r <= 1'b0;
            oe_r   <= OE_RESET;    // released, unless a design asks otherwise
        end else begin
            miso_r <= miso_o;
            oe_r   <= miso_oe;
        end
    end

    // The tri-state, at the top of the shell and driving a port directly, which is
    // what makes an OBUFT inferrable (Chapter 14.5).
    assign miso_pad = oe_r ? miso_r : 1'bz;

endmodule

// spi_io_shell.v
//
// Chapter 15.7 -- the module a constraints file is written about.
//
// Modules 13, 14 and the first half of 15 have deferred the constraints file three
// times, and the reason is that it cannot be written from inside the RTL. It is
// about the BOARD: how long after the master's clock edge its data is valid at this
// device's pin, and how long after this device's clock edge its data is valid at the
// master's. Neither number is in any HDL file, and no simulation contains either.
//
// So this file is small on purpose. It is the SHELL -- the pad registers and nothing
// else -- and it exists to give the constraints file something with named ports and
// a known latency to be written against.
//
// WHAT THE SHELL IS FOR, BEYOND TIDINESS.
//
// A constraint is a claim about a PATH, and the path runs from a pin to a register.
// If the first register on that path is three levels down inside a hierarchy, behind
// a synchroniser that someone may deepen and a mux someone may add, then:
//
//   * `set_input_delay` still applies -- it is about the port -- but the slack it
//     produces depends on logic that has nothing to do with the board;
//   * a tool asked to pull the register into the pad (`IOB = TRUE`) cannot, because
//     there is logic between the pad and the register;
//   * and a report that shows the path failing does not say whether the fault is the
//     board's arrival time or somebody's combinational logic.
//
// Putting exactly one register between each pin and everything else makes the path a
// constraints file talks about the same path the tool reports on.
//
// THE LATENCY IS THE NUMBER THE CONSTRAINTS ASSUME, AND IT IS CHECKABLE.
//
// This shell adds ONE cycle to every input before the rest of the design sees it. So
// the slave's recovered-edge latency becomes SYNC_N + 1 rather than SYNC_N, and
// every derived number in Module 14 moves by one:
//
//     LEAD  >= SYNC_N + 3     (was SYNC_N + 2, Chapter 14.4)
//     HALF  >= SYNC_N + 2     (was SYNC_N + 1)
//     GAP   >= SYNC_N + 2     (was SYNC_N + 1)
//
// That is the thing worth taking from this file: ADDING A PAD REGISTER CHANGES A
// DATASHEET. It is the right thing to do for timing closure and it is not free, and
// a team that adds it late discovers the cost as a customer's master no longer
// working. The testbench measures the latency so that the number in the constraints
// file and the number in the datasheet are the same number.
//
// WHAT IS DELIBERATELY NOT HERE. No logic. Not an edge detector, not a synchroniser,
// not a polarity comparison. Anything that is not a register belongs behind the
// shell, because anything that is not a register is what stops the register reaching
// the pad.

module spi_io_shell #(
    // The output enable is registered too, and its reset value matters more than any
    // other bit in the design: a shell that comes up driving makes every other
    // device on the MISO net unreadable (Chapter 14.5).
    parameter OE_RESET = 1'b0
) (
    input  wire  clk,
    input  wire  rst_n,

    // --- the pins ---------------------------------------------------------
    input  wire  sclk_pin,
    input  wire  cs_n_pin,
    input  wire  mosi_pin,
    output wire  miso_pad,

    // --- the core side: one cycle later, and nothing else different -------
    output reg   sclk_i,
    output reg   cs_n_i,
    output reg   mosi_i,
    input  wire  miso_o,
    input  wire  miso_oe
);

    // Input pad registers. One flop, no logic, no reset -- and the missing reset is
    // deliberate rather than an omission worth flagging: resetting an input pad
    // register adds a mux in front of it on some devices, which is exactly the logic
    // that stops it being placed in the pad. The values are meaningless until the
    // core's own reset has released anyway, and the core resets its synchronisers.
    //
    // The exception is CS, which is reset to DESELECTED. A slave that wakes up
    // believing it is selected is worse than one that wakes up believing it is not,
    // and one mux is a fair price for that (Chapter 14.8).
    always @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            sclk_i <= 1'b0;
            cs_n_i <= 1'b1;        // deselected
            mosi_i <= 1'b0;
        end else begin
            sclk_i <= sclk_pin;
            cs_n_i <= cs_n_pin;
            mosi_i <= mosi_pin;
        end
    end

    // Output pad registers. Both the value AND the enable are registered, and they
    // must be registered TOGETHER -- a design that registers the value and drives
    // the enable combinationally has a pad whose turn-on time depends on fabric
    // logic, which is the one thing `set_output_delay` cannot describe.
    reg miso_r, oe_r;

    always @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            miso_r <= 1'b0;
            oe_r   <= OE_RESET;    // released, unless a design asks otherwise
        end else begin
            miso_r <= miso_o;
            oe_r   <= miso_oe;
        end
    end

    // The tri-state, at the top of the shell and driving a port directly, which is
    // what makes an OBUFT inferrable (Chapter 14.5).
    assign miso_pad = oe_r ? miso_r : 1'bz;

endmodule

-- spi_io_shell.vhd
--
-- Chapter 15.7 -- the module a constraints file is written about.
--
-- Modules 13, 14 and the first half of 15 have deferred the constraints file three
-- times, and the reason is that it cannot be written from inside the RTL. It is
-- about the BOARD: how long after the master's clock edge its data is valid at this
-- device's pin, and how long after this device's clock edge its data is valid at the
-- master's. Neither number is in any HDL file, and no simulation contains either.
--
-- So this file is small on purpose. It is the SHELL -- the pad registers and nothing
-- else -- and it exists to give the constraints file something with named ports and
-- a known latency to be written against.
--
-- WHAT THE SHELL IS FOR, BEYOND TIDINESS.
--
-- A constraint is a claim about a PATH, and the path runs from a pin to a register.
-- If the first register on that path is three levels down inside a hierarchy, behind
-- a synchroniser that someone may deepen and a mux someone may add, then:
--
--   * `set_input_delay` still applies -- it is about the port -- but the slack it
--     produces depends on logic that has nothing to do with the board;
--   * a tool asked to pull the register into the pad (`IOB = TRUE`) cannot, because
--     there is logic between the pad and the register;
--   * and a report that shows the path failing does not say whether the fault is the
--     board's arrival time or somebody's combinational logic.
--
-- Putting exactly one register between each pin and everything else makes the path a
-- constraints file talks about the same path the tool reports on.
--
-- THE LATENCY IS THE NUMBER THE CONSTRAINTS ASSUME, AND IT IS CHECKABLE.
--
-- This shell adds ONE cycle to every input before the rest of the design sees it. So
-- the slave's recovered-edge latency becomes SYNC_N + 1 rather than SYNC_N, and
-- every derived number in Module 14 moves by one:
--
--     LEAD  >= SYNC_N + 3     (was SYNC_N + 2, Chapter 14.4)
--     HALF  >= SYNC_N + 2     (was SYNC_N + 1)
--     GAP   >= SYNC_N + 2     (was SYNC_N + 1)
--
-- That is the thing worth taking from this file: ADDING A PAD REGISTER CHANGES A
-- DATASHEET. It is the right thing to do for timing closure and it is not free, and
-- a team that adds it late discovers the cost as a customer's master no longer
-- working. The testbench measures the latency so that the number in the constraints
-- file and the number in the datasheet are the same number.
--
-- WHAT IS DELIBERATELY NOT HERE. No logic. Not an edge detector, not a synchroniser,
-- not a polarity comparison. Anything that is not a register belongs behind the
-- shell, because anything that is not a register is what stops the register reaching
-- the pad.

library ieee;
use ieee.std_logic_1164.all;

entity spi_io_shell is
    generic (
        -- The output enable is registered too, and its reset value matters more than
        -- any other bit in the design: a shell that comes up driving makes every
        -- other device on the MISO net unreadable (Chapter 14.5).
        OE_RESET : std_logic := '0'
    );
    port (
        clk      : in  std_logic;
        rst_n    : in  std_logic;

        -- the pins
        sclk_pin : in  std_logic;
        cs_n_pin : in  std_logic;
        mosi_pin : in  std_logic;
        miso_pad : out std_logic;

        -- the core side: one cycle later, and nothing else different
        sclk_i   : out std_logic;
        cs_n_i   : out std_logic;
        mosi_i   : out std_logic;
        miso_o   : in  std_logic;
        miso_oe  : in  std_logic
    );
end entity;

architecture rtl of spi_io_shell is
    signal sclk_r : std_logic := '0';
    signal cs_n_r : std_logic := '1';
    signal mosi_r : std_logic := '0';
    signal miso_r : std_logic := '0';
    signal oe_r   : std_logic := '0';
begin

    sclk_i <= sclk_r;
    cs_n_i <= cs_n_r;
    mosi_i <= mosi_r;

    -- Input pad registers. One flop, no logic, and no reset except on CS -- the
    -- missing resets are deliberate rather than an omission: resetting an input pad
    -- register adds a mux in front of it on some devices, which is exactly the logic
    -- that stops it being placed in the pad. CS is the exception, reset to
    -- DESELECTED, because a slave that wakes up believing it is selected is worse
    -- than one that wakes up believing it is not (Chapter 14.8).
    inreg : process (clk, rst_n)
    begin
        if rst_n = '0' then
            sclk_r <= '0';
            cs_n_r <= '1';        -- deselected
            mosi_r <= '0';
        elsif rising_edge(clk) then
            sclk_r <= sclk_pin;
            cs_n_r <= cs_n_pin;
            mosi_r <= mosi_pin;
        end if;
    end process;

    -- Output pad registers. The value AND the enable, registered TOGETHER -- a
    -- design that registers the value and drives the enable combinationally has a
    -- pad whose turn-on time depends on fabric logic, which is the one thing
    -- `set_output_delay` cannot describe.
    outreg : process (clk, rst_n)
    begin
        if rst_n = '0' then
            miso_r <= '0';
            oe_r   <= OE_RESET;   -- released, unless a design asks otherwise
        elsif rising_edge(clk) then
            miso_r <= miso_o;
            oe_r   <= miso_oe;
        end if;
    end process;

    -- The tri-state, at the top of the shell and driving a port directly, which is
    -- what makes an OBUFT inferrable (Chapter 14.5).
    miso_pad <= miso_r when oe_r = '1' else 'Z';

end architecture;

// spi_io_shell_tb.sv
//
// A constraints file cannot be simulated. That is the chapter's premise and it is
// not a limitation of this bench -- `set_input_delay` describes a board, and no
// board is present. So this bench checks the two things about the shell that a
// constraints file ASSUMES and that simulation can settle:
//
//   1  THE LATENCY IS EXACTLY ONE CYCLE, on every input, and the same one cycle on
//      every input. A constraints file written against a one-cycle shell and a
//      design whose SCLK path is one cycle and whose MOSI path is two is a design
//      whose delay-matching is broken (Chapter 14.1) in a place no timing report
//      will mention, because both paths pass.
//
//   2  THE OUTPUT ENABLE COMES UP RELEASED, and is registered alongside the value
//      rather than ahead of it. Both halves matter: the first is the obligation of
//      Chapter 14.5, and the second is what makes `set_output_delay` describe the
//      real turn-on time rather than a fabric path.
//
// And then it states the thing it cannot check, in the run's own log, so that a
// green regression is not mistaken for a constrained design.

`timescale 1ns/1ps

module spi_io_shell_tb;

    reg clk   = 1'b0;
    reg rst_n = 1'b1;
    always #5 clk = ~clk;

    reg sclk_pin = 1'b0;
    reg cs_n_pin = 1'b1;
    reg mosi_pin = 1'b0;
    reg miso_o   = 1'b0;
    reg miso_oe  = 1'b0;

    wire sclk_i, cs_n_i, mosi_i, miso_pad;

    spi_io_shell #(.OE_RESET(1'b0)) dut (
        .clk(clk), .rst_n(rst_n),
        .sclk_pin(sclk_pin), .cs_n_pin(cs_n_pin), .mosi_pin(mosi_pin),
        .miso_pad(miso_pad),
        .sclk_i(sclk_i), .cs_n_i(cs_n_i), .mosi_i(mosi_i),
        .miso_o(miso_o), .miso_oe(miso_oe)
    );

    integer errors = 0;

    initial begin
        #200_000;
        $display("FAIL: the simulation did not finish within its time limit");
        $finish;
    end

    // Measures how many clock edges pass between a pin changing and the core-side
    // copy following it. The answer must be 1 and must be the same for all three.
    task automatic measure(input integer which, output integer cycles);
        integer n;
        begin
            cycles = -1;
            @(negedge clk);
            case (which)
                0: sclk_pin = ~sclk_pin;
                1: cs_n_pin = ~cs_n_pin;
                2: mosi_pin = ~mosi_pin;
            endcase
            for (n = 1; n <= 8 && cycles < 0; n = n + 1) begin
                @(posedge clk);
                #1;
                case (which)
                    0: if (sclk_i === sclk_pin) cycles = n;
                    1: if (cs_n_i === cs_n_pin) cycles = n;
                    2: if (mosi_i === mosi_pin) cycles = n;
                endcase
            end
        end
    endtask

    integer c_sclk, c_cs, c_mosi, k;
    reg [2:0] pat;

    initial begin
        // Power-on: reset released, then asserted, then released -- the model
        // Chapter 15.2 established, so that an asynchronous reset actually fires.
        rst_n = 1'b1;
        repeat (2) @(posedge clk);
        rst_n = 1'b0;

        // 1. THE ENABLE COMES UP RELEASED, checked WHILE reset is asserted, which is
        //    the only time it can be checked at all. A slave driving a shared bus
        //    during reset makes every other device on the net unreadable, and after
        //    reset has gone the evidence has gone with it.
        #1;
        if (miso_pad !== 1'bz) begin
            $display("  FAIL: the shell drives MISO during reset (pad reads %b) -- every other device on the net is unreadable while this one is held in reset",
                     miso_pad);
            errors = errors + 1;
        end
        $display("  during reset the MISO pad reads high-impedance, so a device held in reset does not make the net unusable for everything else");

        repeat (4) @(posedge clk);
        rst_n = 1'b1;
        repeat (4) @(posedge clk);

        // 2. CS COMES UP DESELECTED. The one input pad register that carries a reset
        //    value, and the reason it earns the mux that a reset costs.
        if (cs_n_i !== 1'b1) begin
            $display("  FAIL: the shell's chip select came out of reset asserted");
            errors = errors + 1;
        end
        $display("  chip select comes out of reset DESELECTED, which is the one input worth spending a reset mux on: a slave that wakes up believing it is selected is worse than one that wakes up believing it is not");

        // 3. EVERY INPUT IS EXACTLY ONE CYCLE, AND THE SAME ONE CYCLE. Measured
        //    rather than assumed, because delay-matching is a lint property and no
        //    timing report will mention an asymmetry here.
        measure(0, c_sclk);
        measure(1, c_cs);
        measure(2, c_mosi);

        $display("  pad-to-core latency:  sclk %0d cycle(s)   cs_n %0d   mosi %0d",
                 c_sclk, c_cs, c_mosi);

        if (c_sclk != 1 || c_cs != 1 || c_mosi != 1) begin
            $display("  FAIL: the shell's latency must be exactly one cycle on every input, got %0d, %0d and %0d",
                     c_sclk, c_cs, c_mosi);
            errors = errors + 1;
        end
        if (!(c_sclk == c_cs && c_cs == c_mosi)) begin
            $display("  FAIL: the three inputs have different latencies, which breaks Chapter 14.1's delay matching in a place no timing report will mention");
            errors = errors + 1;
        end

        // 4. THE OUTPUT VALUE AND ITS ENABLE ARE REGISTERED TOGETHER. Driving the
        //    enable a cycle ahead of the value would put a known-wrong bit on the
        //    bus for one cycle; driving it a cycle behind would release the bus late.
        //    Both are checked by asserting they change on the same edge.
        @(negedge clk);
        miso_o  = 1'b1;
        miso_oe = 1'b1;
        @(posedge clk); #1;
        if (miso_pad !== 1'b1) begin
            $display("  FAIL: the value and the enable did not take effect together; the pad reads %b one cycle after both were asserted",
                     miso_pad);
            errors = errors + 1;
        end
        @(negedge clk);
        miso_oe = 1'b0;
        @(posedge clk); #1;
        if (miso_pad !== 1'bz) begin
            $display("  FAIL: the pad did not release one cycle after the enable was dropped");
            errors = errors + 1;
        end
        $display("  the value and the enable are registered together, so the pad turns on and off one cycle after both -- which is what lets an output delay constraint describe a flop's clock-to-out rather than a fabric path");

        // 5. AND THE SHELL IS TRANSPARENT: whatever goes in comes out, once. Checked
        //    over a pattern rather than a single bit, because a shell that inverted
        //    or held a value would pass every test above.
        pat = 3'b000;
        for (k = 0; k < 8; k = k + 1) begin
            @(negedge clk);
            sclk_pin = k[0];
            cs_n_pin = k[1];
            mosi_pin = k[2];
            @(posedge clk); #1;
            if (sclk_i !== k[0] || cs_n_i !== k[1] || mosi_i !== k[2]) begin
                $display("  FAIL: at pattern %0d the core side read %b%b%b, expected %b%b%b",
                         k, mosi_i, cs_n_i, sclk_i, k[2], k[1], k[0]);
                errors = errors + 1;
            end
        end
        $display("  all eight input combinations pass through unchanged after exactly one cycle, so the shell adds latency and nothing else");

        // 6. THE THING THIS BENCH CANNOT CHECK, printed in the log on purpose.
        $display("  NOT CHECKED HERE, and not checkable: whether `set_input_delay` on the three inputs and `set_output_delay` on MISO describe the board, whether SCLK is correctly declared as DATA rather than as a clock, and whether the pad registers were actually placed in the pads. Those are a constraints file and a place-and-route report, and a green run of this bench is evidence about the RTL only");

        // 7. AND THE NUMBER THIS SHELL CHANGES. Adding it moves every requirement
        //    Module 14 derived by one cycle, which is a datasheet change rather than
        //    an implementation detail.
        $display("  the shell adds one cycle, so Chapter 14.4's lead requirement becomes SYNC_N + 3, the half-period SYNC_N + 2 and Chapter 14.5's gap SYNC_N + 2 -- adding a pad register is the right thing for timing closure and it changes the numbers a master must respect, which is why it belongs in the datasheet and not only in the constraints file");

        if (errors == 0)
            $display("PASS: the shell is one register per pin and no logic, and that is the whole design -- because anything that is not a register is what stops a register being placed in the pad, and a constraint is a claim about the path from a pin to its first register. Measured: every input follows its pin after exactly ONE cycle and all three follow after the SAME one cycle, which is Chapter 14.1's delay-matching obligation made checkable rather than left to a lint rule that no timing report enforces; the MISO pad reads high-impedance throughout reset, so a device held in reset does not make the net unusable for everything else; chip select comes out of reset deselected, which is the one input worth the mux a reset costs; the output value and its enable are registered together, so the pad's turn-on is a flop's clock-to-out and an output delay constraint can describe it; and all eight input combinations pass through unchanged, so the shell adds latency and nothing else. What this bench cannot check is everything the chapter is actually about -- whether the delays describe the board, whether SCLK is declared as data, and whether the registers reached the pads -- and the shell's one cycle moves Module 14's lead, half-period and gap requirements each by one, which makes adding it a datasheet change rather than an implementation detail");
        else
            $display("FAIL: %0d error(s)", errors);
        $finish;
    end

endmodule

// spi_io_shell_tb.v
//
// A constraints file cannot be simulated. That is the chapter's premise and it is
// not a limitation of this bench -- `set_input_delay` describes a board, and no
// board is present. So this bench checks the two things about the shell that a
// constraints file ASSUMES and that simulation can settle:
//
//   1  THE LATENCY IS EXACTLY ONE CYCLE, on every input, and the same one cycle on
//      every input. A constraints file written against a one-cycle shell and a
//      design whose SCLK path is one cycle and whose MOSI path is two is a design
//      whose delay-matching is broken (Chapter 14.1) in a place no timing report
//      will mention, because both paths pass.
//
//   2  THE OUTPUT ENABLE COMES UP RELEASED, and is registered alongside the value
//      rather than ahead of it. Both halves matter: the first is the obligation of
//      Chapter 14.5, and the second is what makes `set_output_delay` describe the
//      real turn-on time rather than a fabric path.
//
// And then it states the thing it cannot check, in the run's own log, so that a
// green regression is not mistaken for a constrained design.

`timescale 1ns/1ps

module spi_io_shell_tb;

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

    reg sclk_pin;
    reg cs_n_pin;
    reg mosi_pin;
    reg miso_o;
    reg miso_oe;

    wire sclk_i, cs_n_i, mosi_i, miso_pad;

    spi_io_shell #(.OE_RESET(1'b0)) dut (
        .clk(clk), .rst_n(rst_n),
        .sclk_pin(sclk_pin), .cs_n_pin(cs_n_pin), .mosi_pin(mosi_pin),
        .miso_pad(miso_pad),
        .sclk_i(sclk_i), .cs_n_i(cs_n_i), .mosi_i(mosi_i),
        .miso_o(miso_o), .miso_oe(miso_oe)
    );

    integer errors;

    initial begin
        #200_000;
        $display("FAIL: the simulation did not finish within its time limit");
        $finish;
    end

    // Measures how many clock edges pass between a pin changing and the core-side
    // copy following it. The answer must be 1 and must be the same for all three.
        task measure;
        input integer which;
        output integer cycles;
        integer n;
        begin
            cycles = -1;
            @(negedge clk);
            case (which)
                0: sclk_pin = ~sclk_pin;
                1: cs_n_pin = ~cs_n_pin;
                2: mosi_pin = ~mosi_pin;
            endcase
            for (n = 1; n <= 8 && cycles < 0; n = n + 1) begin
                @(posedge clk);
                #1;
                case (which)
                    0: if (sclk_i === sclk_pin) cycles = n;
                    1: if (cs_n_i === cs_n_pin) cycles = n;
                    2: if (mosi_i === mosi_pin) cycles = n;
                endcase
            end
        end
    endtask

    integer c_sclk, c_cs, c_mosi, k;
    reg [2:0] pat;

    initial begin
        // Power-on: reset released, then asserted, then released -- the model
        // Chapter 15.2 established, so that an asynchronous reset actually fires.
        rst_n = 1'b1;
        repeat (2) @(posedge clk);
        rst_n = 1'b0;

        // 1. THE ENABLE COMES UP RELEASED, checked WHILE reset is asserted, which is
        //    the only time it can be checked at all. A slave driving a shared bus
        //    during reset makes every other device on the net unreadable, and after
        //    reset has gone the evidence has gone with it.
        #1;
        if (miso_pad !== 1'bz) begin
            $display("  FAIL: the shell drives MISO during reset (pad reads %b) -- every other device on the net is unreadable while this one is held in reset",
                     miso_pad);
            errors = errors + 1;
        end
        $display("  during reset the MISO pad reads high-impedance, so a device held in reset does not make the net unusable for everything else");

        repeat (4) @(posedge clk);
        rst_n = 1'b1;
        repeat (4) @(posedge clk);

        // 2. CS COMES UP DESELECTED. The one input pad register that carries a reset
        //    value, and the reason it earns the mux that a reset costs.
        if (cs_n_i !== 1'b1) begin
            $display("  FAIL: the shell's chip select came out of reset asserted");
            errors = errors + 1;
        end
        $display("  chip select comes out of reset DESELECTED, which is the one input worth spending a reset mux on: a slave that wakes up believing it is selected is worse than one that wakes up believing it is not");

        // 3. EVERY INPUT IS EXACTLY ONE CYCLE, AND THE SAME ONE CYCLE. Measured
        //    rather than assumed, because delay-matching is a lint property and no
        //    timing report will mention an asymmetry here.
        measure(0, c_sclk);
        measure(1, c_cs);
        measure(2, c_mosi);

        $display("  pad-to-core latency:  sclk %0d cycle(s)   cs_n %0d   mosi %0d",
                 c_sclk, c_cs, c_mosi);

        if (c_sclk != 1 || c_cs != 1 || c_mosi != 1) begin
            $display("  FAIL: the shell's latency must be exactly one cycle on every input, got %0d, %0d and %0d",
                     c_sclk, c_cs, c_mosi);
            errors = errors + 1;
        end
        if (!(c_sclk == c_cs && c_cs == c_mosi)) begin
            $display("  FAIL: the three inputs have different latencies, which breaks Chapter 14.1's delay matching in a place no timing report will mention");
            errors = errors + 1;
        end

        // 4. THE OUTPUT VALUE AND ITS ENABLE ARE REGISTERED TOGETHER. Driving the
        //    enable a cycle ahead of the value would put a known-wrong bit on the
        //    bus for one cycle; driving it a cycle behind would release the bus late.
        //    Both are checked by asserting they change on the same edge.
        @(negedge clk);
        miso_o  = 1'b1;
        miso_oe = 1'b1;
        @(posedge clk); #1;
        if (miso_pad !== 1'b1) begin
            $display("  FAIL: the value and the enable did not take effect together; the pad reads %b one cycle after both were asserted",
                     miso_pad);
            errors = errors + 1;
        end
        @(negedge clk);
        miso_oe = 1'b0;
        @(posedge clk); #1;
        if (miso_pad !== 1'bz) begin
            $display("  FAIL: the pad did not release one cycle after the enable was dropped");
            errors = errors + 1;
        end
        $display("  the value and the enable are registered together, so the pad turns on and off one cycle after both -- which is what lets an output delay constraint describe a flop's clock-to-out rather than a fabric path");

        // 5. AND THE SHELL IS TRANSPARENT: whatever goes in comes out, once. Checked
        //    over a pattern rather than a single bit, because a shell that inverted
        //    or held a value would pass every test above.
        pat = 3'b000;
        for (k = 0; k < 8; k = k + 1) begin
            @(negedge clk);
            sclk_pin = k[0];
            cs_n_pin = k[1];
            mosi_pin = k[2];
            @(posedge clk); #1;
            if (sclk_i !== k[0] || cs_n_i !== k[1] || mosi_i !== k[2]) begin
                $display("  FAIL: at pattern %0d the core side read %b%b%b, expected %b%b%b",
                         k, mosi_i, cs_n_i, sclk_i, k[2], k[1], k[0]);
                errors = errors + 1;
            end
        end
        $display("  all eight input combinations pass through unchanged after exactly one cycle, so the shell adds latency and nothing else");

        // 6. THE THING THIS BENCH CANNOT CHECK, printed in the log on purpose.
        $display("  NOT CHECKED HERE, and not checkable: whether `set_input_delay` on the three inputs and `set_output_delay` on MISO describe the board, whether SCLK is correctly declared as DATA rather than as a clock, and whether the pad registers were actually placed in the pads. Those are a constraints file and a place-and-route report, and a green run of this bench is evidence about the RTL only");

        // 7. AND THE NUMBER THIS SHELL CHANGES. Adding it moves every requirement
        //    Module 14 derived by one cycle, which is a datasheet change rather than
        //    an implementation detail.
        $display("  the shell adds one cycle, so Chapter 14.4's lead requirement becomes SYNC_N + 3, the half-period SYNC_N + 2 and Chapter 14.5's gap SYNC_N + 2 -- adding a pad register is the right thing for timing closure and it changes the numbers a master must respect, which is why it belongs in the datasheet and not only in the constraints file");

        if (errors == 0)
            $display("PASS: the shell is one register per pin and no logic, and that is the whole design -- because anything that is not a register is what stops a register being placed in the pad, and a constraint is a claim about the path from a pin to its first register. Measured: every input follows its pin after exactly ONE cycle and all three follow after the SAME one cycle, which is Chapter 14.1's delay-matching obligation made checkable rather than left to a lint rule that no timing report enforces; the MISO pad reads high-impedance throughout reset, so a device held in reset does not make the net unusable for everything else; chip select comes out of reset deselected, which is the one input worth the mux a reset costs; the output value and its enable are registered together, so the pad's turn-on is a flop's clock-to-out and an output delay constraint can describe it; and all eight input combinations pass through unchanged, so the shell adds latency and nothing else. What this bench cannot check is everything the chapter is actually about -- whether the delays describe the board, whether SCLK is declared as data, and whether the registers reached the pads -- and the shell's one cycle moves Module 14's lead, half-period and gap requirements each by one, which makes adding it a datasheet change rather than an implementation detail");
        else
            $display("FAIL: %0d error(s)", errors);
        $finish;
    end


    initial begin
        clk = 1'b0;
        rst_n = 1'b1;
        sclk_pin = 1'b0;
        cs_n_pin = 1'b1;
        mosi_pin = 1'b0;
        miso_o = 1'b0;
        miso_oe = 1'b0;
        errors = 0;
    end

endmodule

-- spi_io_shell_tb.vhd
--
-- A constraints file cannot be simulated. That is the chapter's premise and it is
-- not a limitation of this bench -- `set_input_delay` describes a board, and no
-- board is present. So this bench checks the two things about the shell that a
-- constraints file ASSUMES and that simulation can settle:
--
--   1  THE LATENCY IS EXACTLY ONE CYCLE, on every input, and the same one cycle on
--      every input. A constraints file written against a one-cycle shell and a
--      design whose SCLK path is one cycle and whose MOSI path is two is a design
--      whose delay-matching is broken (Chapter 14.1) in a place no timing report
--      will mention, because both paths pass.
--
--   2  THE OUTPUT ENABLE COMES UP RELEASED, and is registered alongside the value
--      rather than ahead of it. Both halves matter: the first is the obligation of
--      Chapter 14.5, and the second is what makes `set_output_delay` describe the
--      real turn-on time rather than a fabric path.
--
-- And then it states the thing it cannot check, in the run's own log, so that a
-- green regression is not mistaken for a constrained design.

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

entity spi_io_shell_tb is
end entity;

architecture sim of spi_io_shell_tb is

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

    signal sclk_pin : std_logic := '0';
    signal cs_n_pin : std_logic := '1';
    signal mosi_pin : std_logic := '0';
    signal miso_o   : std_logic := '0';
    signal miso_oe  : std_logic := '0';

    signal sclk_i, cs_n_i, mosi_i, miso_pad : std_logic;

begin

    clkgen : process
    begin
        while not halt loop
            clk <= '0'; wait for 5 ns; clk <= '1'; wait for 5 ns;
        end loop;
        wait;
    end process;

    dut : entity work.spi_io_shell
        generic map (OE_RESET => '0')
        port map (clk => clk, rst_n => rst_n,
                  sclk_pin => sclk_pin, cs_n_pin => cs_n_pin, mosi_pin => mosi_pin,
                  miso_pad => miso_pad,
                  sclk_i => sclk_i, cs_n_i => cs_n_i, mosi_i => mosi_i,
                  miso_o => miso_o, miso_oe => miso_oe);

    watchdog : process
    begin
        wait for 200 us;
        if not halt then
            report "FAIL: the simulation did not finish within its time limit"
                severity failure;
        end if;
        wait;
    end process;

    stim : process
        variable errs : natural := 0;
        variable c_sclk, c_cs, c_mosi : integer;

        -- Measures how many clock edges pass between a pin changing and the core-side
        -- copy following it. The answer must be 1, and the same 1 for all three.
        procedure measure(which : natural; cycles : out integer) is
            variable n : integer := -1;
            variable target : std_logic;
        begin
            n := -1;
            wait until falling_edge(clk);
            case which is
                when 0 => sclk_pin <= not sclk_pin; target := not sclk_pin;
                when 1 => cs_n_pin <= not cs_n_pin; target := not cs_n_pin;
                when others => mosi_pin <= not mosi_pin; target := not mosi_pin;
            end case;
            for i in 1 to 8 loop
                wait until rising_edge(clk);
                wait for 1 ns;
                if n < 0 then
                    case which is
                        when 0 => if sclk_i = sclk_pin then n := i; end if;
                        when 1 => if cs_n_i = cs_n_pin then n := i; end if;
                        when others => if mosi_i = mosi_pin then n := i; end if;
                    end case;
                end if;
            end loop;
            cycles := n;
        end procedure;
    begin
        -- Power-on: reset released, then asserted, then released -- the model
        -- Chapter 15.2 established, so an asynchronous reset actually fires.
        rst_n <= '1';
        for i in 1 to 2 loop wait until rising_edge(clk); end loop;
        rst_n <= '0';

        -- 1. THE ENABLE COMES UP RELEASED, checked WHILE reset is asserted, which is
        --    the only time it can be checked at all.
        wait for 1 ns;
        if miso_pad /= 'Z' then
            report "  FAIL: the shell drives MISO during reset -- every other device on the net is unreadable while this one is held in reset";
            errs := errs + 1;
        end if;
        report "  during reset the MISO pad reads high-impedance, so a device held in reset does not make the net unusable for everything else";

        for i in 1 to 4 loop wait until rising_edge(clk); end loop;
        rst_n <= '1';
        for i in 1 to 4 loop wait until rising_edge(clk); end loop;

        -- 2. CS COMES UP DESELECTED.
        if cs_n_i /= '1' then
            report "  FAIL: the shell's chip select came out of reset asserted";
            errs := errs + 1;
        end if;
        report "  chip select comes out of reset DESELECTED, which is the one input worth spending a reset mux on: a slave that wakes up believing it is selected is worse than one that wakes up believing it is not";

        -- 3. EVERY INPUT IS EXACTLY ONE CYCLE, AND THE SAME ONE CYCLE.
        measure(0, c_sclk);
        measure(1, c_cs);
        measure(2, c_mosi);

        report "  pad-to-core latency:  sclk " & integer'image(c_sclk) &
               " cycle(s)   cs_n " & integer'image(c_cs) &
               "   mosi " & integer'image(c_mosi);

        if c_sclk /= 1 or c_cs /= 1 or c_mosi /= 1 then
            report "  FAIL: the shell's latency must be exactly one cycle on every input";
            errs := errs + 1;
        end if;
        if not (c_sclk = c_cs and c_cs = c_mosi) then
            report "  FAIL: the three inputs have different latencies, which breaks Chapter 14.1's delay matching in a place no timing report will mention";
            errs := errs + 1;
        end if;

        -- 4. THE OUTPUT VALUE AND ITS ENABLE ARE REGISTERED TOGETHER.
        wait until falling_edge(clk);
        miso_o  <= '1';
        miso_oe <= '1';
        wait until rising_edge(clk);
        wait for 1 ns;
        if miso_pad /= '1' then
            report "  FAIL: the value and the enable did not take effect together";
            errs := errs + 1;
        end if;
        wait until falling_edge(clk);
        miso_oe <= '0';
        wait until rising_edge(clk);
        wait for 1 ns;
        if miso_pad /= 'Z' then
            report "  FAIL: the pad did not release one cycle after the enable was dropped";
            errs := errs + 1;
        end if;
        report "  the value and the enable are registered together, so the pad turns on and off one cycle after both -- which is what lets an output delay constraint describe a flop's clock-to-out rather than a fabric path";

        -- 5. AND THE SHELL IS TRANSPARENT over every input combination.
        for k in 0 to 7 loop
            wait until falling_edge(clk);
            sclk_pin <= '1' when (k mod 2) = 1 else '0';
            cs_n_pin <= '1' when ((k / 2) mod 2) = 1 else '0';
            mosi_pin <= '1' when (k / 4) = 1 else '0';
            wait until rising_edge(clk);
            wait for 1 ns;
            if sclk_i /= sclk_pin or cs_n_i /= cs_n_pin or mosi_i /= mosi_pin then
                report "  FAIL: at pattern " & integer'image(k) &
                       " the core side did not match the pins";
                errs := errs + 1;
            end if;
        end loop;
        report "  all eight input combinations pass through unchanged after exactly one cycle, so the shell adds latency and nothing else";

        -- 6. THE THING THIS BENCH CANNOT CHECK, printed in the log on purpose.
        report "  NOT CHECKED HERE, and not checkable: whether `set_input_delay` on the three inputs and `set_output_delay` on MISO describe the board, whether SCLK is correctly declared as DATA rather than as a clock, and whether the pad registers were actually placed in the pads. Those are a constraints file and a place-and-route report, and a green run of this bench is evidence about the RTL only";

        -- 7. AND THE NUMBER THIS SHELL CHANGES.
        report "  the shell adds one cycle, so Chapter 14.4's lead requirement becomes SYNC_N + 3, the half-period SYNC_N + 2 and Chapter 14.5's gap SYNC_N + 2 -- adding a pad register is the right thing for timing closure and it changes the numbers a master must respect, which is why it belongs in the datasheet and not only in the constraints file";

        if errs = 0 then
            report "PASS: the shell is one register per pin and no logic, and that is the whole design -- because anything that is not a register is what stops a register being placed in the pad, and a constraint is a claim about the path from a pin to its first register. Measured: every input follows its pin after exactly ONE cycle and all three follow after the SAME one cycle, which is Chapter 14.1's delay-matching obligation made checkable rather than left to a lint rule that no timing report enforces; the MISO pad reads high-impedance throughout reset, so a device held in reset does not make the net unusable for everything else; chip select comes out of reset deselected, which is the one input worth the mux a reset costs; the output value and its enable are registered together, so the pad's turn-on is a flop's clock-to-out and an output delay constraint can describe it; and all eight input combinations pass through unchanged, so the shell adds latency and nothing else. What this bench cannot check is everything the chapter is actually about -- whether the delays describe the board, whether SCLK is declared as data, and whether the registers reached the pads -- and the shell's one cycle moves Module 14's lead, half-period and gap requirements each by one, which makes adding it a datasheet change rather than an implementation detail";
        else
            report "FAIL: " & integer'image(errs) & " error(s)" severity error;
        end if;

        halt <= true;
        wait;
    end process;

end architecture;

// Properties for an I/O shell. Short, because the shell is short -- and the
// shortage is the point: everything interesting about a constraints file is
// outside the RTL.

property p_input_latency_exactly_one;
    // The claim a constraints file makes about the path from the pin.
    @(posedge clk) disable iff (!rst_n)
        1 |=> (sclk_i == $past(sclk_pin));
endproperty

property p_all_inputs_same_latency;
    // Chapter 14.1's delay matching, as a property rather than a lint rule. No
    // timing report will mention an asymmetry here, because both paths pass.
    @(posedge clk) disable iff (!rst_n)
        1 |=> ((sclk_i == $past(sclk_pin)) &&
               (cs_n_i == $past(cs_n_pin)) &&
               (mosi_i == $past(mosi_pin)));
endproperty

property p_released_during_reset;
    // Deliberately NOT inside a disable iff: this property is about the reset state
    // itself, so disabling it during reset would remove its only content.
    @(posedge clk)
        !rst_n |-> (miso_pad === 1'bz);
endproperty

property p_value_and_enable_together;
    // What makes set_output_delay describe a flop's clock-to-out rather than a
    // fabric path. A design that registers one and not the other has a pad whose
    // turn-on depends on logic the constraint cannot see.
    @(posedge clk) disable iff (!rst_n)
        1 |=> (miso_pad === ($past(miso_oe) ? $past(miso_o) : 1'bz));
endproperty

property p_cs_comes_up_deselected;
    // The one input worth spending a reset mux on.
    @(posedge clk)
        $rose(rst_n) |-> cs_n_i;
endproperty

// Coverage. There is little to cover in the shell itself, and the honest coverage
// model says so -- the axes that matter are in the constraints and in the
// place-and-route report, neither of which a covergroup can reach.

covergroup cg_shell @(posedge clk);
    option.per_instance = 1;

    // Every combination of the three inputs, because a shell that held or inverted
    // one would pass a single-bit test.
    combo: coverpoint {mosi_pin, cs_n_pin, sclk_pin} { bins all[] = {[0:7]}; }

    // The output's three states. `released` during reset is the one that matters and
    // the one a bench structure usually cannot reach.
    pad: coverpoint pad_state {
        bins driving_0 = {0};
        bins driving_1 = {1};
        bins released  = {2};
    }

    // Whether reset was asserted while the pad was observed -- which is how the
    // released-during-reset bin gets reached at all.
    in_reset: coverpoint rst_asserted { bins yes = {1}; bins no = {0}; }

    x_pad_reset: cross pad, in_reset;

endgroup