CS Glitches and False Selection

   pulse shorter than the threshold  →  rejected, and reported
   pulse longer than the threshold   →  ACCEPTED as a real transition
   pulse near the threshold          →  depends on sampling phase

// spi_cs_filter.sv — rejecting chip-select glitches.
//
// Chapter 5.2 §7 established that a synchroniser resolves METASTABILITY and
// does not decide whether a pulse was intended -- and that adding stages adds
// latency without adding rejection. This is the separate mechanism it
// promised: a candidate transition is accepted only after FILTER_N
// consecutive samples agree with it.
//
// The honest limitation is stated by the design rather than hidden: a glitch
// LONGER than FILTER_N samples is accepted as a real transition. A filter has
// a threshold, not judgement, and the threshold is the whole specification.
module spi_cs_filter #(
    parameter int FILTER_N = 3       // consecutive agreeing samples required
) (
    input  logic clk,
    input  logic rst_n,
    input  logic cs_n_raw,           // straight from the pin
    output logic cs_n_clean,         // safe to derive frame edges from
    output logic glitch_seen         // pulse: a candidate reverted before acceptance
);
    localparam int CW = (FILTER_N > 1) ? $clog2(FILTER_N) : 1;

    // Metastability first, filtering second. The order matters: filtering a
    // possibly-metastable sample would be counting undefined values.
    logic [1:0]    sync;
    logic [CW-1:0] agree_cnt;
    logic          synced;

    assign synced = sync[1];

    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            sync        <= 2'b11;        // idle high: deselected is the safe state
            cs_n_clean  <= 1'b1;
            agree_cnt   <= '0;
            glitch_seen <= 1'b0;
        end else begin
            sync        <= {sync[0], cs_n_raw};
            glitch_seen <= 1'b0;

            if (synced != cs_n_clean) begin
                // A candidate transition is in progress.
                if (agree_cnt == CW'(FILTER_N - 1)) begin
                    cs_n_clean <= synced;     // accepted
                    agree_cnt  <= '0;
                end else begin
                    agree_cnt <= agree_cnt + 1'b1;
                end
            end else begin
                // The input agrees with the accepted value. If a candidate was
                // part-way through, it reverted -- that is a glitch.
                if (agree_cnt != '0) glitch_seen <= 1'b1;
                agree_cnt <= '0;
            end
        end
    end
endmodule

// spi_cs_filter_tb.sv — a real edge is accepted, a short glitch is rejected
// and reported, and a long glitch is accepted (a filter has a threshold).
`timescale 1ns/1ps
module spi_cs_filter_tb;
    logic clk = 0, rst_n = 0;
    always #5 clk = ~clk;

    localparam int FN = 3;
    logic cs_n_raw = 1;
    logic cs_n_clean, glitch_seen;

    spi_cs_filter #(.FILTER_N(FN)) dut (
        .clk, .rst_n, .cs_n_raw, .cs_n_clean, .glitch_seen);

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

    always @(posedge clk) if (rst_n && glitch_seen) glitches++;

    // Hold the raw input at a value for n clock cycles.
    task automatic hold(input logic v, input int n);
        cs_n_raw = v;
        repeat (n) @(negedge clk);
    endtask

    int g0;
    initial begin
        repeat (3) @(negedge clk); rst_n = 1; @(negedge clk);
        chk("reset: deselected", cs_n_clean, 1);

        // --- a REAL assertion: held well past the threshold ---
        g0 = glitches;
        hold(1'b0, 12);
        chk("real edge accepted",    cs_n_clean, 0);
        chk("no glitch reported",    glitches - g0, 0);

        // --- a REAL deassertion ---
        hold(1'b1, 12);
        chk("real release accepted", cs_n_clean, 1);

        // --- a SHORT glitch: 2 samples, below the 3-sample threshold ---
        g0 = glitches;
        hold(1'b0, 2);
        hold(1'b1, 12);
        chk("short glitch rejected", cs_n_clean, 1);
        chk("glitch reported",       glitches - g0, 1);

        // --- an even shorter glitch: 1 sample ---
        g0 = glitches;
        hold(1'b0, 1);
        hold(1'b1, 12);
        chk("1-sample glitch rejected", cs_n_clean, 1);
        chk("glitch reported",          glitches - g0, 1);

        // --- a LONG glitch: 8 samples, well past the threshold. This is
        //     ACCEPTED, and that is the honest limit of a filter. ---
        g0 = glitches;
        hold(1'b0, 8);
        chk("long glitch accepted as real", cs_n_clean, 0);
        hold(1'b1, 12);
        chk("and released again",           cs_n_clean, 1);

        // --- repeated short glitches must never accumulate into acceptance.
        //     They are separated by more than the synchroniser latency so
        //     each is independently observable; glitches closer together
        //     than that merge into a single report, which is a property of
        //     the synchroniser rather than of the filter. ---
        g0 = glitches;
        for (int i = 0; i < 6; i++) begin
            hold(1'b0, 2);
            hold(1'b1, 6);
        end
        chk("repeated short glitches never accepted", cs_n_clean, 1);
        if (glitches - g0 < 6) begin
            $display("FAIL: expected at least 6 glitch reports, got %0d", glitches - g0);
            errors++;
        end

        if (errors == 0)
            $display("PASS: transitions held for at least %0d samples are accepted, shorter ones are rejected and reported, and repeated short glitches never accumulate", FN);
        else
            $display("FAILED with %0d error(s)", errors);
        $finish;
    end

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

// spi_cs_filter.v — the same glitch filter in Verilog-2001.
module spi_cs_filter #(
    parameter FILTER_N = 3          // consecutive agreeing samples required
) (
    input  wire clk,
    input  wire rst_n,
    input  wire cs_n_raw,           // straight from the pin
    output reg  cs_n_clean,         // safe to derive frame edges from
    output reg  glitch_seen         // pulse: a candidate reverted
);
    function integer clogb2;
        input integer value;
        integer v;
        begin
            v = value - 1;
            for (clogb2 = 0; v > 0; clogb2 = clogb2 + 1) v = v >> 1;
        end
    endfunction

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

    // Metastability first, filtering second: filtering a possibly-metastable
    // sample would be counting undefined values.
    reg [1:0]    sync;
    reg [CW-1:0] agree_cnt;
    wire         synced = sync[1];

    always @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            sync        <= 2'b11;       // idle high: deselected is safe
            cs_n_clean  <= 1'b1;
            agree_cnt   <= {CW{1'b0}};
            glitch_seen <= 1'b0;
        end else begin
            sync        <= {sync[0], cs_n_raw};
            glitch_seen <= 1'b0;

            if (synced != cs_n_clean) begin
                if (agree_cnt == (FILTER_N - 1)) begin
                    cs_n_clean <= synced;       // accepted
                    agree_cnt  <= {CW{1'b0}};
                end else begin
                    agree_cnt <= agree_cnt + 1'b1;
                end
            end else begin
                // A candidate part-way through has reverted: a glitch.
                if (agree_cnt != {CW{1'b0}}) glitch_seen <= 1'b1;
                agree_cnt <= {CW{1'b0}};
            end
        end
    end
endmodule

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

    parameter FN = 3;
    reg cs_n_raw = 1;
    wire cs_n_clean, glitch_seen;

    spi_cs_filter #(.FILTER_N(FN)) dut (
        .clk(clk), .rst_n(rst_n), .cs_n_raw(cs_n_raw),
        .cs_n_clean(cs_n_clean), .glitch_seen(glitch_seen));

    integer errors = 0, glitches = 0, g0 = 0, i;

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

    always @(posedge clk) if (rst_n && glitch_seen) glitches = glitches + 1;

    task hold;
        input v;
        input integer n;
        begin
            cs_n_raw = v;
            repeat (n) @(negedge clk);
        end
    endtask

    initial begin
        repeat (3) @(negedge clk); rst_n = 1; @(negedge clk);
        chk("reset: deselected", cs_n_clean, 1);

        g0 = glitches;
        hold(1'b0, 12);
        chk("real edge accepted", cs_n_clean, 0);
        chk("no glitch reported", glitches - g0, 0);

        hold(1'b1, 12);
        chk("real release accepted", cs_n_clean, 1);

        g0 = glitches;
        hold(1'b0, 2);
        hold(1'b1, 12);
        chk("short glitch rejected", cs_n_clean, 1);
        chk("glitch reported",       glitches - g0, 1);

        g0 = glitches;
        hold(1'b0, 1);
        hold(1'b1, 12);
        chk("1-sample glitch rejected", cs_n_clean, 1);
        chk("glitch reported",          glitches - g0, 1);

        // A glitch longer than the threshold IS accepted: a filter has a
        // threshold, not judgement.
        g0 = glitches;
        hold(1'b0, 8);
        chk("long glitch accepted as real", cs_n_clean, 0);
        hold(1'b1, 12);
        chk("and released again",           cs_n_clean, 1);

        g0 = glitches;
        for (i = 0; i < 6; i = i + 1) begin
            hold(1'b0, 2);
            hold(1'b1, 6);
        end
        chk("repeated short glitches never accepted", cs_n_clean, 1);
        if (glitches - g0 < 6) begin
            $display("FAIL: expected at least 6 glitch reports, got %0d", glitches - g0);
            errors = errors + 1;
        end

        if (errors == 0)
            $display("PASS: transitions held for at least %0d samples are accepted, shorter ones are rejected and reported, and repeated short glitches never accumulate", FN);
        else
            $display("FAILED with %0d error(s)", errors);
        $finish;
    end

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

-- spi_cs_filter.vhd — the same glitch filter in VHDL.
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

entity spi_cs_filter is
    generic (
        FILTER_N : positive := 3        -- consecutive agreeing samples required
    );
    port (
        clk         : in  std_logic;
        rst_n       : in  std_logic;
        cs_n_raw    : in  std_logic;    -- straight from the pin
        cs_n_clean  : out std_logic;    -- safe to derive frame edges from
        glitch_seen : out std_logic     -- pulse: a candidate reverted
    );
end entity spi_cs_filter;

architecture rtl of spi_cs_filter is
    -- Metastability first, filtering second: filtering a possibly-metastable
    -- sample would be counting undefined values.
    signal sync       : std_logic_vector(1 downto 0);
    signal agree_cnt  : integer range 0 to FILTER_N - 1;
    signal clean_r    : std_logic;
    signal synced     : std_logic;
begin

    synced     <= sync(1);
    cs_n_clean <= clean_r;

    process (clk, rst_n) is
    begin
        if rst_n = '0' then
            sync        <= (others => '1');   -- idle high: deselected is safe
            clean_r     <= '1';
            agree_cnt   <= 0;
            glitch_seen <= '0';
        elsif rising_edge(clk) then
            sync        <= sync(0) & cs_n_raw;
            glitch_seen <= '0';

            if synced /= clean_r then
                if agree_cnt = FILTER_N - 1 then
                    clean_r   <= synced;      -- accepted
                    agree_cnt <= 0;
                else
                    agree_cnt <= agree_cnt + 1;
                end if;
            else
                -- A candidate part-way through has reverted: a glitch.
                if agree_cnt /= 0 then
                    glitch_seen <= '1';
                end if;
                agree_cnt <= 0;
            end if;
        end if;
    end process;

end architecture rtl;

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

entity spi_cs_filter_tb is
end entity spi_cs_filter_tb;

architecture tb of spi_cs_filter_tb is
    constant FN : positive := 3;

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

    signal errors   : natural := 0;
    signal glitches : natural := 0;
begin

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

    dut : entity work.spi_cs_filter
        generic map (FILTER_N => FN)
        port map (clk => clk, rst_n => rst_n, cs_n_raw => cs_n_raw,
                  cs_n_clean => cs_n_clean, glitch_seen => glitch_seen);

    counter : process (clk) is
    begin
        if rising_edge(clk) and rst_n = '1' and glitch_seen = '1' then
            glitches <= glitches + 1;
        end if;
    end process;

    stim : process is
        variable g0 : natural;

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

        procedure chk_n (what : string; g, e : natural) is
        begin
            if g /= e then
                report "FAIL " & what & ": got " & integer'image(g)
                    & " exp " & integer'image(e) severity error;
                errors <= errors + 1;
            end if;
        end procedure;

        procedure hold (v : std_logic; n : positive) is
        begin
            cs_n_raw <= v;
            for i in 1 to n loop
                wait until falling_edge(clk);
            end loop;
        end procedure;
    begin
        for i in 0 to 2 loop wait until falling_edge(clk); end loop;
        rst_n <= '1';
        wait until falling_edge(clk);
        chk_b("reset: deselected", cs_n_clean, '1');

        g0 := glitches;
        hold('0', 12);
        chk_b("real edge accepted", cs_n_clean, '0');
        chk_n("no glitch reported", glitches - g0, 0);

        hold('1', 12);
        chk_b("real release accepted", cs_n_clean, '1');

        g0 := glitches;
        hold('0', 2);
        hold('1', 12);
        chk_b("short glitch rejected", cs_n_clean, '1');
        chk_n("glitch reported",       glitches - g0, 1);

        g0 := glitches;
        hold('0', 1);
        hold('1', 12);
        chk_b("1-sample glitch rejected", cs_n_clean, '1');
        chk_n("glitch reported",          glitches - g0, 1);

        -- A glitch longer than the threshold IS accepted.
        hold('0', 8);
        chk_b("long glitch accepted as real", cs_n_clean, '0');
        hold('1', 12);
        chk_b("and released again",           cs_n_clean, '1');

        g0 := glitches;
        for i in 0 to 5 loop
            hold('0', 2);
            hold('1', 6);
        end loop;
        chk_b("repeated short glitches never accepted", cs_n_clean, '1');
        if glitches - g0 < 6 then
            report "FAIL: expected at least 6 glitch reports" severity error;
            errors <= errors + 1;
        end if;

        if errors = 0 then
            report "PASS: transitions held for at least " & integer'image(FN)
                 & " samples are accepted, shorter ones are rejected and reported, "
                 & "and repeated short glitches never accumulate" severity note;
        else
            report "FAILED with " & integer'image(errors) & " error(s)" severity error;
        end if;
        halt <= true;
        wait;
    end process;

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

end architecture tb;

   // 1. A pulse shorter than the threshold never reaches the output.
   //    Expressed on the SYNCHRONISED input, because that is what the
   //    filter actually sees.
   property p_short_rejected;
       @(posedge clk) disable iff (!rst_n)
           ($changed(synced) ##1 $changed(synced)[->1] within
            ($stable(synced)[*0:FILTER_N-1]))
           |-> $stable(cs_n_clean);
   endproperty

   // 2. A glitch is REPORTED when rejected. Silent rejection is worse than
   //    no filter: the board has a noise problem that nothing surfaces.
   a_glitch_reported : assert property (
       @(posedge clk) disable iff (!rst_n)
           (agree_cnt != 0 && synced == cs_n_clean) |=> glitch_seen)
       else $error("a rejected candidate was not reported");

   // 3. The output changes only after the full threshold. Catches an
   //    off-by-one that accepts one sample early.
   a_threshold_respected : assert property (
       @(posedge clk) disable iff (!rst_n)
           $changed(cs_n_clean) |-> ($past(agree_cnt) == FILTER_N - 1))
       else $error("output changed before the threshold was met");

   // 4. Out of reset, deselected. A filter resetting to "selected" opens a
   //    frame the master never started.
   a_reset_idle : assert property (
       @(posedge clk) $rose(rst_n) |-> cs_n_clean)
       else $error("filter output asserted out of reset");

   covergroup spi_cs_glitch_cg @(posedge clk);
       cp_pulse_width : coverpoint pulse_samples iff (pulse_ended) {
           bins sub_threshold = {[1:FILTER_N-1]};   // rejected
           bins at_threshold  = {FILTER_N};         // the grey band
           bins over          = {[FILTER_N+1:$]};   // ACCEPTED -- by design
       }

       // Where the glitch landed relative to a real transaction. A glitch
       // during another device's frame is the contention case (Chapter 8.5);
       // one on an idle bus is comparatively harmless.
       cp_context : coverpoint glitch_context {
           bins bus_idle        = {CTX_IDLE};
           bins other_selected  = {CTX_OTHER_ACTIVE};   // the dangerous one
           bins self_selected   = {CTX_SELF_ACTIVE};
       }

       x_width_context : cross cp_pulse_width, cp_context;
   endgroup