Senior Silicon Debug

   Reasoning FROM the symptom:

     CRC errors -> "probably signal integrity"
                -> reflow the board, swap the cable, scope D+/D-
                -> two days, no change, and the shortlist never shrank

   Reasoning FROM exclusion:

     one CLEAN packet from the device
       -> a marginal PHY does not selectively corrupt
       -> signal integrity is OUT
     a TIMEOUT
       -> a device that talks too much does not go silent
       -> unsolicited traffic is OUT
     a STALL
       -> a considered response means packets arrive intact both ways
       -> the hub is OUT

   Three events. Three classes gone. Nothing was guessed.

// =====================================================================
//  usb_trace_triage -- "Walk a bring-up debug session" in hardware.
//
//  An analyser trace of a failing USB bring-up contains millions of
//  packets and one interesting moment. The skill the question tests is
//  not reading packets; it is NARROWING -- and the discipline that makes
//  narrowing work is counter-intuitive:
//
//      Narrow by what the evidence EXCLUDES, not by what it suggests.
//
//  A trace that shows CRC errors SUGGESTS signal integrity. What it
//  EXCLUDES is nothing at all, because a CRC error is also what a device
//  driving the bus at the wrong time looks like, and what a hub with a
//  failing repeater looks like, and what a host with a marginal
//  turnaround timeout looks like.
//
//  So this module does not classify failures. It maintains, for each
//  candidate fault class, the evidence that would RULE IT OUT -- and
//  reports which classes remain possible. A class is eliminated when
//  something in the trace is inconsistent with it, never when something
//  merely looks like something else.
//
//  The output is therefore not a diagnosis. It is a SHORTLIST, and the
//  most valuable field on it is how many classes are still alive.
// =====================================================================
module usb_trace_triage (
  input  wire        clk,
  input  wire        rst_n,

  // ---- one trace event per cycle ----
  input  wire        ev_valid,
  input  wire [2:0]  ev_kind,

  // ---- attributes of the event, as an analyser would report them ----
  input  wire        ev_from_device,   // the device transmitted it
  input  wire        ev_crc_bad,
  input  wire [6:0]  ev_addr,
  input  wire        ev_addr_is_zero,
  input  wire        ev_after_reset,   // within the post-reset window
  input  wire        ev_toggle,

  // ---- which fault classes are STILL POSSIBLE ----
  //
  // All start possible. Each is cleared by evidence that CONTRADICTS it.
  output wire        c_signal,      // signal integrity / marginal PHY
  output wire        c_addr_early,  // SET_ADDRESS applied too early
  output wire        c_toggle,      // data toggle desynchronised
  output wire        c_unsolicited, // device transmits without a token
  output wire        c_hub,         // hub repeater or translator fault
  output wire        c_power,       // brown-out / insufficient current

  // ---- the shortlist, and the number that matters ----
  output wire [2:0]  n_alive,
  output wire        conclusive,    // exactly one class remains

  // ---- observability ----
  output wire [31:0] n_events,
  output wire [31:0] n_crc_bad,
  output wire [31:0] n_dev_tx,
  output wire [31:0] n_eliminations
);

  localparam [2:0] E_SOF     = 3'd0,
                   E_TOKEN   = 3'd1,
                   E_DATA    = 3'd2,
                   E_ACK     = 3'd3,
                   E_NAK     = 3'd4,
                   E_STALL   = 3'd5,
                   E_TIMEOUT = 3'd6,
                   E_RESET   = 3'd7;

  // Each bit is "this class is still possible". They start SET.
  reg c_sig_r, c_addr_r, c_tog_r, c_unsol_r, c_hub_r, c_pwr_r;

  reg [31:0] ev_c, crc_c, devtx_c, elim_c;

  // toggle history, for the one class that needs a sequence rather than
  // a single event
  reg        last_tog;
  reg        have_tog;

  assign c_signal      = c_sig_r;
  assign c_addr_early  = c_addr_r;
  assign c_toggle      = c_tog_r;
  assign c_unsolicited = c_unsol_r;
  assign c_hub         = c_hub_r;
  assign c_power       = c_pwr_r;

  assign n_events       = ev_c;
  assign n_crc_bad      = crc_c;
  assign n_dev_tx       = devtx_c;
  assign n_eliminations = elim_c;

  // ---- the shortlist size ----
  wire [2:0] alive = {2'd0, c_sig_r}   + {2'd0, c_addr_r} + {2'd0, c_tog_r}
                   + {2'd0, c_unsol_r} + {2'd0, c_hub_r}  + {2'd0, c_pwr_r};

  assign n_alive = alive;

  // ---- CONCLUSIVE means exactly one class survives ----
  //
  // Not "one class looks likely". A trace that eliminates five of six is
  // a diagnosis; a trace that makes one of six look probable is a guess,
  // and the whole point of this module is that it refuses to report the
  // second as though it were the first.
  assign conclusive = (alive == 3'd1);

  // =================================================================
  //  THE ELIMINATION RULES.
  //
  //  Each is a statement of the form "if X is in the trace then class Y
  //  is impossible". Note that NONE of them says "X means Y" -- that is
  //  the direction that produces wrong diagnoses, and the direction
  //  every one of these deliberately avoids.
  // =================================================================

  // A CLEAN packet from the device rules out signal integrity as the
  // WHOLE story: a marginal PHY does not selectively corrupt.
  wire e_sig   = ev_valid && ev_from_device && !ev_crc_bad;

  // Any successful transaction at a NON-ZERO address rules out the
  // address applying early: the device is reachable where the host
  // thinks it is.
  wire e_addr  = ev_valid && (ev_kind == E_ACK) && !ev_addr_is_zero;

  // Two consecutive DATA packets with DIFFERENT toggles rule out a
  // desynchronised toggle.
  wire e_tog   = ev_valid && (ev_kind == E_DATA) && have_tog
                 && (ev_toggle != last_tog);

  // A TIMEOUT rules out unsolicited transmission as the cause: a device
  // that talks too much does not produce silence.
  wire e_unsol = ev_valid && (ev_kind == E_TIMEOUT);

  // A STALL rules out a hub fault: a stall is a considered response from
  // a device whose packets are therefore arriving intact in both
  // directions.
  wire e_hub   = ev_valid && (ev_kind == E_STALL);

  // Activity outside the post-reset window rules out brown-out: a device
  // that resets under load does not keep running.
  wire e_pwr   = ev_valid && !ev_after_reset && (ev_kind != E_RESET);

  wire [2:0] elim_now = {2'd0, (e_sig   && c_sig_r)}
                      + {2'd0, (e_addr  && c_addr_r)}
                      + {2'd0, (e_tog   && c_tog_r)}
                      + {2'd0, (e_unsol && c_unsol_r)}
                      + {2'd0, (e_hub   && c_hub_r)}
                      + {2'd0, (e_pwr   && c_pwr_r)};

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      // Everything starts possible. A triage tool that begins with a
      // favourite has already made the mistake it exists to prevent.
      c_sig_r   <= 1'b1;
      c_addr_r  <= 1'b1;
      c_tog_r   <= 1'b1;
      c_unsol_r <= 1'b1;
      c_hub_r   <= 1'b1;
      c_pwr_r   <= 1'b1;
      ev_c      <= 32'd0;
      crc_c     <= 32'd0;
      devtx_c   <= 32'd0;
      elim_c    <= 32'd0;
      last_tog  <= 1'b0;
      have_tog  <= 1'b0;
    end else begin
      if (ev_valid) begin
        ev_c <= ev_c + 32'd1;
        if (ev_crc_bad)     crc_c   <= crc_c + 32'd1;
        if (ev_from_device) devtx_c <= devtx_c + 32'd1;

        // ---- elimination is MONOTONIC ----
        //
        // A class, once ruled out, stays ruled out. Evidence does not
        // expire, and a later event that merely looks consistent with a
        // class cannot revive it -- which is what stops this from
        // oscillating and what makes the shortlist mean something.
        if (e_sig)   c_sig_r   <= 1'b0;
        if (e_addr)  c_addr_r  <= 1'b0;
        if (e_tog)   c_tog_r   <= 1'b0;
        if (e_unsol) c_unsol_r <= 1'b0;
        if (e_hub)   c_hub_r   <= 1'b0;
        if (e_pwr)   c_pwr_r   <= 1'b0;

        // One add of the combinational count, not six increments of one
        // register: six non-blocking assignments to elim_c would be six
        // writes and only the last would take effect.
        if (elim_now != 3'd0) elim_c <= elim_c + {29'd0, elim_now};

        // toggle history advances on every DATA packet
        if (ev_kind == E_DATA) begin
          last_tog <= ev_toggle;
          have_tog <= 1'b1;
        end
      end
    end
  end

endmodule

// =====================================================================
//  usb_trace_triage -- SystemVerilog.
//
//  The event kinds and the fault classes become named enumerations, which
//  matters here more than usual: the output of this module is a SHORTLIST
//  of hypotheses, and a shortlist printed as `3'b101` is not a shortlist
//  anybody can act on.
//
//  Originally: "Walk a bring-up debug session" in hardware.
//
//  An analyser trace of a failing USB bring-up contains millions of
//  packets and one interesting moment. The skill the question tests is
//  not reading packets; it is NARROWING -- and the discipline that makes
//  narrowing work is counter-intuitive:
//
//      Narrow by what the evidence EXCLUDES, not by what it suggests.
//
//  A trace that shows CRC errors SUGGESTS signal integrity. What it
//  EXCLUDES is nothing at all, because a CRC error is also what a device
//  driving the bus at the wrong time looks like, and what a hub with a
//  failing repeater looks like, and what a host with a marginal
//  turnaround timeout looks like.
//
//  So this module does not classify failures. It maintains, for each
//  candidate fault class, the evidence that would RULE IT OUT -- and
//  reports which classes remain possible. A class is eliminated when
//  something in the trace is inconsistent with it, never when something
//  merely looks like something else.
//
//  The output is therefore not a diagnosis. It is a SHORTLIST, and the
//  most valuable field on it is how many classes are still alive.
// =====================================================================
module usb_trace_triage (
  input  logic       clk,
  input  logic       rst_n,

  // ---- one trace event per cycle ----
  input  logic       ev_valid,
  input  logic [2:0] ev_kind,

  // ---- attributes of the event, as an analyser would report them ----
  input  logic       ev_from_device,   // the device transmitted it
  input  logic       ev_crc_bad,
  input  logic [6:0] ev_addr,
  input  logic       ev_addr_is_zero,
  input  logic       ev_after_reset,   // within the post-reset window
  input  logic       ev_toggle,

  // ---- which fault classes are STILL POSSIBLE ----
  //
  // All start possible. Each is cleared by evidence that CONTRADICTS it.
  output logic       c_signal,      // signal integrity / marginal PHY
  output logic       c_addr_early,  // SET_ADDRESS applied too early
  output logic       c_toggle,      // data toggle desynchronised
  output logic       c_unsolicited, // device transmits without a token
  output logic       c_hub,         // hub repeater or translator fault
  output logic       c_power,       // brown-out / insufficient current

  // ---- the shortlist, and the number that matters ----
  output logic [2:0] n_alive,
  output logic       conclusive,    // exactly one class remains

  // ---- observability ----
  output logic [31:0]n_events,
  output logic [31:0]n_crc_bad,
  output logic [31:0]n_dev_tx,
  output logic [31:0]n_eliminations
);

  // A shortlist printed as 3'b101 is not a shortlist anybody can act on.
  typedef enum logic [2:0] {
    E_SOF     = 3'd0,
    E_TOKEN   = 3'd1,
    E_DATA    = 3'd2,
    E_ACK     = 3'd3,
    E_NAK     = 3'd4,
    E_STALL   = 3'd5,
    E_TIMEOUT = 3'd6,
    E_RESET   = 3'd7
  } ev_e;

  // Each bit is "this class is still possible". They start SET.
  logic c_sig_r, c_addr_r, c_tog_r, c_unsol_r, c_hub_r, c_pwr_r;

  logic [31:0] ev_c, crc_c, devtx_c, elim_c;

  // toggle history, for the one class that needs a sequence rather than
  // a single event
  logic      last_tog;
  logic      have_tog;

  assign c_signal      = c_sig_r;
  assign c_addr_early  = c_addr_r;
  assign c_toggle      = c_tog_r;
  assign c_unsolicited = c_unsol_r;
  assign c_hub         = c_hub_r;
  assign c_power       = c_pwr_r;

  assign n_events       = ev_c;
  assign n_crc_bad      = crc_c;
  assign n_dev_tx       = devtx_c;
  assign n_eliminations = elim_c;

  // ---- the shortlist size ----
  wire [2:0] alive = {2'd0, c_sig_r}   + {2'd0, c_addr_r} + {2'd0, c_tog_r}
                   + {2'd0, c_unsol_r} + {2'd0, c_hub_r}  + {2'd0, c_pwr_r};

  assign n_alive = alive;

  // ---- CONCLUSIVE means exactly one class survives ----
  //
  // Not "one class looks likely". A trace that eliminates five of six is
  // a diagnosis; a trace that makes one of six look probable is a guess,
  // and the whole point of this module is that it refuses to report the
  // second as though it were the first.
  assign conclusive = (alive == 3'd1);

  // =================================================================
  //  THE ELIMINATION RULES.
  //
  //  Each is a statement of the form "if X is in the trace then class Y
  //  is impossible". Note that NONE of them says "X means Y" -- that is
  //  the direction that produces wrong diagnoses, and the direction
  //  every one of these deliberately avoids.
  // =================================================================

  // A CLEAN packet from the device rules out signal integrity as the
  // WHOLE story: a marginal PHY does not selectively corrupt.
  wire e_sig   = ev_valid && ev_from_device && !ev_crc_bad;

  // Any successful transaction at a NON-ZERO address rules out the
  // address applying early: the device is reachable where the host
  // thinks it is.
  wire e_addr  = ev_valid && (ev_kind == E_ACK) && !ev_addr_is_zero;

  // Two consecutive DATA packets with DIFFERENT toggles rule out a
  // desynchronised toggle.
  wire e_tog   = ev_valid && (ev_kind == E_DATA) && have_tog
                 && (ev_toggle != last_tog);

  // A TIMEOUT rules out unsolicited transmission as the cause: a device
  // that talks too much does not produce silence.
  wire e_unsol = ev_valid && (ev_kind == E_TIMEOUT);

  // A STALL rules out a hub fault: a stall is a considered response from
  // a device whose packets are therefore arriving intact in both
  // directions.
  wire e_hub   = ev_valid && (ev_kind == E_STALL);

  // Activity outside the post-reset window rules out brown-out: a device
  // that resets under load does not keep running.
  wire e_pwr   = ev_valid && !ev_after_reset && (ev_kind != E_RESET);

  wire [2:0] elim_now = {2'd0, (e_sig   && c_sig_r)}
                      + {2'd0, (e_addr  && c_addr_r)}
                      + {2'd0, (e_tog   && c_tog_r)}
                      + {2'd0, (e_unsol && c_unsol_r)}
                      + {2'd0, (e_hub   && c_hub_r)}
                      + {2'd0, (e_pwr   && c_pwr_r)};

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      // Everything starts possible. A triage tool that begins with a
      // favourite has already made the mistake it exists to prevent.
      c_sig_r   <= 1'b1;
      c_addr_r  <= 1'b1;
      c_tog_r   <= 1'b1;
      c_unsol_r <= 1'b1;
      c_hub_r   <= 1'b1;
      c_pwr_r   <= 1'b1;
      ev_c      <= 32'd0;
      crc_c     <= 32'd0;
      devtx_c   <= 32'd0;
      elim_c    <= 32'd0;
      last_tog  <= 1'b0;
      have_tog  <= 1'b0;
    end else begin
      if (ev_valid) begin
        ev_c <= ev_c + 32'd1;
        if (ev_crc_bad)     crc_c   <= crc_c + 32'd1;
        if (ev_from_device) devtx_c <= devtx_c + 32'd1;

        // ---- elimination is MONOTONIC ----
        //
        // A class, once ruled out, stays ruled out. Evidence does not
        // expire, and a later event that merely looks consistent with a
        // class cannot revive it -- which is what stops this from
        // oscillating and what makes the shortlist mean something.
        if (e_sig)   c_sig_r   <= 1'b0;
        if (e_addr)  c_addr_r  <= 1'b0;
        if (e_tog)   c_tog_r   <= 1'b0;
        if (e_unsol) c_unsol_r <= 1'b0;
        if (e_hub)   c_hub_r   <= 1'b0;
        if (e_pwr)   c_pwr_r   <= 1'b0;

        // One add of the combinational count, not six increments of one
        // register: six non-blocking assignments to elim_c would be six
        // writes and only the last would take effect.
        if (elim_now != 3'd0) elim_c <= elim_c + {29'd0, elim_now};

        // toggle history advances on every DATA packet
        if (ev_kind == E_DATA) begin
          last_tog <= ev_toggle;
          have_tog <= 1'b1;
        end
      end
    end
  end

endmodule

-- =====================================================================
--  usb_trace_triage -- VHDL-2008.
--
--  An analyser trace of a failing USB bring-up contains millions of
--  packets and one interesting moment. The skill the interview tests is
--  not reading packets; it is NARROWING -- and the discipline that makes
--  narrowing work is counter-intuitive:
--
--      Narrow by what the evidence EXCLUDES, not by what it suggests.
--
--  A trace full of CRC errors SUGGESTS signal integrity. It EXCLUDES
--  nothing, because a CRC error is also what a device driving the bus at
--  the wrong time looks like, and what a failing hub repeater looks like,
--  and what a marginal host turnaround looks like.
--
--  So this entity does not classify. For each candidate fault class it
--  maintains the evidence that would RULE IT OUT, and reports which
--  classes remain possible. The output is a SHORTLIST, and its most
--  valuable field is how many classes are still alive.
-- =====================================================================
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

package td_pkg is
  type ev_t is (EV_SOF, EV_TOKEN, EV_DATA, EV_ACK,
                EV_NAK, EV_STALL, EV_TIMEOUT, EV_RESET);

  function ev_of(v : std_logic_vector(2 downto 0)) return ev_t;
end package;

package body td_pkg is
  function ev_of(v : std_logic_vector(2 downto 0)) return ev_t is
  begin
    case v is
      when "000"  => return EV_SOF;
      when "001"  => return EV_TOKEN;
      when "010"  => return EV_DATA;
      when "011"  => return EV_ACK;
      when "100"  => return EV_NAK;
      when "101"  => return EV_STALL;
      when "110"  => return EV_TIMEOUT;
      when others => return EV_RESET;
    end case;
  end function;
end package body;

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

entity usb_trace_triage is
  port (
    clk             : in  std_logic;
    rst_n           : in  std_logic;

    ev_valid        : in  std_logic;
    ev_kind         : in  std_logic_vector(2 downto 0);

    ev_from_device  : in  std_logic;
    ev_crc_bad      : in  std_logic;
    ev_addr         : in  std_logic_vector(6 downto 0);
    ev_addr_is_zero : in  std_logic;
    ev_after_reset  : in  std_logic;
    ev_toggle       : in  std_logic;

    -- which fault classes are STILL POSSIBLE. All start possible; each is
    -- cleared only by evidence that CONTRADICTS it.
    c_signal        : out std_logic;
    c_addr_early    : out std_logic;
    c_toggle        : out std_logic;
    c_unsolicited   : out std_logic;
    c_hub           : out std_logic;
    c_power         : out std_logic;

    n_alive         : out std_logic_vector(2 downto 0);
    conclusive      : out std_logic;

    n_events        : out std_logic_vector(31 downto 0);
    n_crc_bad       : out std_logic_vector(31 downto 0);
    n_dev_tx        : out std_logic_vector(31 downto 0);
    n_eliminations  : out std_logic_vector(31 downto 0)
  );
end entity;

architecture rtl of usb_trace_triage is
  signal c_sig_r, c_addr_r, c_tog_r : std_logic := '1';
  signal c_unsol_r, c_hub_r, c_pwr_r : std_logic := '1';

  signal ev_c, crc_c, devtx_c, elim_c : unsigned(31 downto 0)
    := (others => '0');

  signal last_tog, have_tog : std_logic := '0';

  signal e_sig, e_addr, e_tog, e_unsol, e_hub, e_pwr : std_logic;
  signal alive, elim_now : natural range 0 to 6;

  signal kind : ev_t;

  function b2n(b : std_logic) return natural is
  begin
    if b = '1' then return 1; else return 0; end if;
  end function;
begin

  kind <= ev_of(ev_kind);

  c_signal      <= c_sig_r;
  c_addr_early  <= c_addr_r;
  c_toggle      <= c_tog_r;
  c_unsolicited <= c_unsol_r;
  c_hub         <= c_hub_r;
  c_power       <= c_pwr_r;

  n_events       <= std_logic_vector(ev_c);
  n_crc_bad      <= std_logic_vector(crc_c);
  n_dev_tx       <= std_logic_vector(devtx_c);
  n_eliminations <= std_logic_vector(elim_c);

  alive   <= b2n(c_sig_r) + b2n(c_addr_r) + b2n(c_tog_r)
           + b2n(c_unsol_r) + b2n(c_hub_r) + b2n(c_pwr_r);
  n_alive <= std_logic_vector(to_unsigned(alive, 3));

  -- ---- CONCLUSIVE means exactly ONE class survives ----
  --
  -- Not "one class looks likely". A trace that eliminates five of six is a
  -- diagnosis; one that makes a class look probable is a guess, and this
  -- entity refuses to report the second as though it were the first.
  --
  -- Nor is an EMPTY shortlist conclusive: a trace that contradicts every
  -- hypothesis is informative -- the fault is outside the model -- but it
  -- is not a diagnosis.
  conclusive <= '1' when alive = 1 else '0';

  -- =================================================================
  --  THE ELIMINATION RULES.
  --
  --  Each has the form "if X is in the trace then class Y is impossible".
  --  None says "X means Y" -- that is the direction that produces wrong
  --  diagnoses, and every one of these deliberately avoids it.
  -- =================================================================

  -- A CLEAN packet from the device rules out signal integrity as the whole
  -- story: a marginal PHY does not selectively corrupt.
  e_sig <= '1' when (ev_valid = '1' and ev_from_device = '1'
                     and ev_crc_bad = '0') else '0';

  -- Any successful transaction at a NON-ZERO address rules out the address
  -- applying early: the device is reachable where the host thinks it is.
  e_addr <= '1' when (ev_valid = '1' and kind = EV_ACK
                      and ev_addr_is_zero = '0') else '0';

  -- Two consecutive DATA packets with DIFFERENT toggles rule out a
  -- desynchronised toggle. The have_tog term matters: a single DATA packet
  -- is not evidence about a sequence.
  e_tog <= '1' when (ev_valid = '1' and kind = EV_DATA and have_tog = '1'
                     and ev_toggle /= last_tog) else '0';

  -- A TIMEOUT rules out unsolicited transmission: a device that talks too
  -- much does not produce silence.
  e_unsol <= '1' when (ev_valid = '1' and kind = EV_TIMEOUT) else '0';

  -- A STALL rules out a hub fault: a stall is a considered response from a
  -- device whose packets are therefore arriving intact in both directions.
  e_hub <= '1' when (ev_valid = '1' and kind = EV_STALL) else '0';

  -- Activity outside the post-reset window rules out brown-out: a device
  -- that resets under load does not keep running.
  e_pwr <= '1' when (ev_valid = '1' and ev_after_reset = '0'
                     and kind /= EV_RESET) else '0';

  elim_now <= b2n(e_sig   and c_sig_r)   + b2n(e_addr  and c_addr_r)
            + b2n(e_tog   and c_tog_r)   + b2n(e_unsol and c_unsol_r)
            + b2n(e_hub   and c_hub_r)   + b2n(e_pwr   and c_pwr_r);

  main : process(clk, rst_n)
  begin
    if rst_n = '0' then
      -- Everything starts possible. A triage tool that begins with a
      -- favourite has already made the mistake it exists to prevent.
      c_sig_r   <= '1';
      c_addr_r  <= '1';
      c_tog_r   <= '1';
      c_unsol_r <= '1';
      c_hub_r   <= '1';
      c_pwr_r   <= '1';
      ev_c      <= (others => '0');
      crc_c     <= (others => '0');
      devtx_c   <= (others => '0');
      elim_c    <= (others => '0');
      last_tog  <= '0';
      have_tog  <= '0';

    elsif rising_edge(clk) then
      if ev_valid = '1' then
        ev_c <= ev_c + 1;
        if ev_crc_bad = '1'     then crc_c   <= crc_c + 1; end if;
        if ev_from_device = '1' then devtx_c <= devtx_c + 1; end if;

        -- ---- elimination is MONOTONIC ----
        --
        -- A class, once ruled out, stays ruled out. Evidence does not
        -- expire, and a later event that merely looks consistent with a
        -- class cannot revive it -- which is what stops the shortlist
        -- oscillating and what makes its size mean something.
        if e_sig   = '1' then c_sig_r   <= '0'; end if;
        if e_addr  = '1' then c_addr_r  <= '0'; end if;
        if e_tog   = '1' then c_tog_r   <= '0'; end if;
        if e_unsol = '1' then c_unsol_r <= '0'; end if;
        if e_hub   = '1' then c_hub_r   <= '0'; end if;
        if e_pwr   = '1' then c_pwr_r   <= '0'; end if;

        -- One add of the combinational count. Six increments of one signal
        -- would be six assignments and only the last would take effect.
        if elim_now /= 0 then
          elim_c <= elim_c + to_unsigned(elim_now, 32);
        end if;

        if kind = EV_DATA then
          last_tog <= ev_toggle;
          have_tog <= '1';
        end if;
      end if;
    end if;
  end process;

end architecture;

   NO FALSE ELIMINATION -- a class must never be ruled out by
                           evidence that does not contradict it.

   NO FALSE SURVIVAL    -- a class must be ruled out the moment
                           something does.

   The first is the dangerous one. A tool that eliminates the
   REAL fault does not merely fail to help -- it actively
   misdirects, and it does so with the authority of a
   shortlist.

// =====================================================================
//  Testbench for usb_trace_triage.
//
//  The property that matters is NOT "does it find the right fault". It is
//  the two-sided one that a triage tool lives or dies by:
//
//    NO FALSE ELIMINATION -- a class is never ruled out by evidence that
//                            does not actually contradict it.
//    NO FALSE SURVIVAL    -- a class IS ruled out the moment something
//                            contradicts it.
//
//  The first is the dangerous direction. A tool that eliminates the real
//  fault sends the whole team to look somewhere else, and it does so with
//  the authority of a shortlist.
//
//  So the shadow recomputes all six elimination conditions from the event
//  attributes, independently, and compares the full set every cycle --
//  not just the class that changed.
// =====================================================================
`timescale 1ns/1ps
module tb_td_v;

  localparam [2:0] E_SOF = 3'd0, E_TOKEN = 3'd1, E_DATA = 3'd2, E_ACK = 3'd3,
                   E_NAK = 3'd4, E_STALL = 3'd5, E_TIMEOUT = 3'd6,
                   E_RESET = 3'd7;

  reg        clk = 1'b0, rst_n = 1'b0;
  reg        ev_valid = 1'b0;
  reg [2:0]  ev_kind = E_SOF;
  reg        ev_from_device = 1'b0;
  reg        ev_crc_bad = 1'b0;
  reg [6:0]  ev_addr = 7'd0;
  reg        ev_addr_is_zero = 1'b1;
  reg        ev_after_reset = 1'b1;
  reg        ev_toggle = 1'b0;

  wire       c_signal, c_addr_early, c_toggle, c_unsolicited, c_hub, c_power;
  wire [2:0] n_alive;
  wire       conclusive;
  wire [31:0] n_events, n_crc_bad, n_dev_tx, n_eliminations;

  usb_trace_triage dut (
    .clk(clk), .rst_n(rst_n),
    .ev_valid(ev_valid), .ev_kind(ev_kind),
    .ev_from_device(ev_from_device), .ev_crc_bad(ev_crc_bad),
    .ev_addr(ev_addr), .ev_addr_is_zero(ev_addr_is_zero),
    .ev_after_reset(ev_after_reset), .ev_toggle(ev_toggle),
    .c_signal(c_signal), .c_addr_early(c_addr_early), .c_toggle(c_toggle),
    .c_unsolicited(c_unsolicited), .c_hub(c_hub), .c_power(c_power),
    .n_alive(n_alive), .conclusive(conclusive),
    .n_events(n_events), .n_crc_bad(n_crc_bad),
    .n_dev_tx(n_dev_tx), .n_eliminations(n_eliminations)
  );

  always #5 clk = ~clk;

  integer errors = 0, checks = 0, steps = 0;
  integer seed;

  function [31:0] urand;
    input dummy;
    begin urand = $random(seed) & 32'h3FFF_FFFF; end
  endfunction

  // ---- the shadow: six independent booleans ----
  reg s_sig, s_addr, s_tog, s_unsol, s_hub, s_pwr;
  reg s_last_tog, s_have_tog;
  reg [31:0] x_ev, x_crc, x_dev, x_elim;

  // ---- the two headline counters ----
  // Run-wide totals: the DUT's counters are cleared by every reset, and
  // the random phase resets every 16 events.
  integer g_ev = 0, g_crc = 0, g_dev = 0, g_elim = 0;

  integer n_false_elim = 0;   // a class cleared without contradiction
  integer n_false_surv = 0;   // a class survived a contradiction

  // ---- exhaustive reach over (kind, from_dev, crc, addr0, after_reset) --
  // The event TOGGLE is a sixth dimension, not a constant. Without it the
  // first DATA packet of every scenario carries toggle 0, which equals the
  // reset value of the history -- so a rule that wrongly ignores "is there
  // any history" never fires, and mutation I6 scored 0 directed.
  reg reach [0:255];
  integer ri, n_reach;

  task ck(input cond, input [255:0] what);
    begin
      checks = checks + 1;
      if (!cond) begin
        errors = errors + 1;
        if (errors <= 20)
          $display("  ERROR @%0t step=%0d: %0s", $time, steps, what);
      end
    end
  endtask

  // ---------------------------------------------------------------
  //  One trace event.
  // ---------------------------------------------------------------
  task ev(input v, input [2:0] k, input fd, input cb,
          input az, input ar, input tg);
    reg p_sig, p_addr, p_tog, p_unsol, p_hub, p_pwr;
    reg q_sig, q_addr, q_tog, q_unsol, q_hub, q_pwr;
    reg [2:0] e_alive;
    begin
      ev_valid = v;  ev_kind = k;  ev_from_device = fd;
      ev_crc_bad = cb;  ev_addr_is_zero = az;
      ev_after_reset = ar;  ev_toggle = tg;
      ev_addr = az ? 7'd0 : 7'd42;

      // remember the state BEFORE this event, for the monotonicity check
      p_sig = s_sig; p_addr = s_addr; p_tog = s_tog;
      p_unsol = s_unsol; p_hub = s_hub; p_pwr = s_pwr;

      // ---- the six elimination conditions, recomputed independently ----
      q_sig   = v && fd && !cb;
      q_addr  = v && (k == E_ACK) && !az;
      q_tog   = v && (k == E_DATA) && s_have_tog && (tg != s_last_tog);
      q_unsol = v && (k == E_TIMEOUT);
      q_hub   = v && (k == E_STALL);
      q_pwr   = v && !ar && (k != E_RESET);

      if (v) begin
        x_ev = x_ev + 1;  g_ev = g_ev + 1;
        if (cb) begin x_crc = x_crc + 1; g_crc = g_crc + 1; end
        if (fd) begin x_dev = x_dev + 1; g_dev = g_dev + 1; end
        x_elim = x_elim
               + ((q_sig   && s_sig)   ? 1 : 0)
               + ((q_addr  && s_addr)  ? 1 : 0)
               + ((q_tog   && s_tog)   ? 1 : 0)
               + ((q_unsol && s_unsol) ? 1 : 0)
               + ((q_hub   && s_hub)   ? 1 : 0)
               + ((q_pwr   && s_pwr)   ? 1 : 0);
        g_elim = g_elim
               + ((q_sig   && s_sig)   ? 1 : 0)
               + ((q_addr  && s_addr)  ? 1 : 0)
               + ((q_tog   && s_tog)   ? 1 : 0)
               + ((q_unsol && s_unsol) ? 1 : 0)
               + ((q_hub   && s_hub)   ? 1 : 0)
               + ((q_pwr   && s_pwr)   ? 1 : 0);
        if (q_sig)   s_sig   = 1'b0;
        if (q_addr)  s_addr  = 1'b0;
        if (q_tog)   s_tog   = 1'b0;
        if (q_unsol) s_unsol = 1'b0;
        if (q_hub)   s_hub   = 1'b0;
        if (q_pwr)   s_pwr   = 1'b0;
        if (k == E_DATA) begin
          s_last_tog = tg;
          s_have_tog = 1'b1;
        end
      end

      @(posedge clk);
      #1;
      steps = steps + 1;
      ev_valid = 1'b0;

      // ---- PROPERTY 1: every class matches the shadow ----
      //
      // All six compared every cycle, not just the one that changed. A
      // class cleared as a side effect of another's evidence would
      // otherwise go unnoticed.
      ck(c_signal      === s_sig,   "c_signal disagrees");
      ck(c_addr_early  === s_addr,  "c_addr_early disagrees");
      ck(c_toggle      === s_tog,   "c_toggle disagrees");
      ck(c_unsolicited === s_unsol, "c_unsolicited disagrees");
      ck(c_hub         === s_hub,   "c_hub disagrees");
      ck(c_power       === s_pwr,   "c_power disagrees");

      // ---- PROPERTY 2: NO FALSE ELIMINATION ----
      //
      // The dangerous direction. A class may only go from possible to
      // impossible if its OWN condition held this cycle.
      if (p_sig   && !c_signal      && !q_sig)   n_false_elim = n_false_elim + 1;
      if (p_addr  && !c_addr_early  && !q_addr)  n_false_elim = n_false_elim + 1;
      if (p_tog   && !c_toggle      && !q_tog)   n_false_elim = n_false_elim + 1;
      if (p_unsol && !c_unsolicited && !q_unsol) n_false_elim = n_false_elim + 1;
      if (p_hub   && !c_hub         && !q_hub)   n_false_elim = n_false_elim + 1;
      if (p_pwr   && !c_power       && !q_pwr)   n_false_elim = n_false_elim + 1;
      ck(n_false_elim == 0,
         "a fault class was eliminated by evidence that does not contradict it");

      // ---- PROPERTY 3: NO FALSE SURVIVAL ----
      if (q_sig   && c_signal)      n_false_surv = n_false_surv + 1;
      if (q_addr  && c_addr_early)  n_false_surv = n_false_surv + 1;
      if (q_tog   && c_toggle)      n_false_surv = n_false_surv + 1;
      if (q_unsol && c_unsolicited) n_false_surv = n_false_surv + 1;
      if (q_hub   && c_hub)         n_false_surv = n_false_surv + 1;
      if (q_pwr   && c_power)       n_false_surv = n_false_surv + 1;
      ck(n_false_surv == 0,
         "a fault class survived evidence that contradicts it");

      // ---- PROPERTY 4: elimination is MONOTONIC ----
      //
      // Evidence does not expire. A class that was ruled out stays ruled
      // out, and no later event can revive it.
      ck(!(!p_sig   && c_signal),      "c_signal came back from the dead");
      ck(!(!p_addr  && c_addr_early),  "c_addr_early came back from the dead");
      ck(!(!p_tog   && c_toggle),      "c_toggle came back from the dead");
      ck(!(!p_unsol && c_unsolicited), "c_unsolicited came back from the dead");
      ck(!(!p_hub   && c_hub),         "c_hub came back from the dead");
      ck(!(!p_pwr   && c_power),       "c_power came back from the dead");

      // ---- PROPERTY 5: the shortlist size and the verdict ----
      e_alive = {2'd0, s_sig}   + {2'd0, s_addr} + {2'd0, s_tog}
              + {2'd0, s_unsol} + {2'd0, s_hub}  + {2'd0, s_pwr};
      ck(n_alive === e_alive, "the shortlist size disagrees");
      ck(conclusive === (e_alive == 3'd1), "conclusive disagrees");

      // ---- PROPERTY 6: zero survivors is NOT conclusive ----
      //
      // A trace that contradicts every hypothesis is informative -- the
      // fault is outside the model -- but it is not a diagnosis, and
      // reporting it as one would be the worst possible outcome.
      ck(!(conclusive && (e_alive == 3'd0)),
         "an empty shortlist was reported as conclusive");

      // ---- PROPERTY 7: the counters agree ----
      ck(n_events       === x_ev,   "event count disagrees");
      ck(n_crc_bad      === x_crc,  "CRC-error count disagrees");
      ck(n_dev_tx       === x_dev,  "device-transmission count disagrees");
      ck(n_eliminations === x_elim, "elimination count disagrees");
    end
  endtask

  task reset_dut;
    begin
      rst_n = 1'b0;
      ev_valid = 0;
      @(posedge clk); @(posedge clk);
      rst_n = 1'b1;
      // everything starts possible
      s_sig = 1'b1; s_addr = 1'b1; s_tog = 1'b1;
      s_unsol = 1'b1; s_hub = 1'b1; s_pwr = 1'b1;
      s_last_tog = 1'b0; s_have_tog = 1'b0;
      x_ev = 0; x_crc = 0; x_dev = 0; x_elim = 0;
      @(posedge clk); #1;
    end
  endtask

  integer ki, fi, ci, ai, ri2, tgi, k;

  initial begin
    for (ri = 0; ri < 256; ri = ri + 1) reach[ri] = 1'b0;
    seed = 32'd27009;

    // =============================================================
    //  PHASE 1 (DIRECTED, EXHAUSTIVE) -- every event attribute
    //  combination, against a freshly reset shortlist.
    //  8 kinds x from_device x crc x addr0 x after_reset x toggle = 256.
    // =============================================================
    for (ki = 0; ki < 8; ki = ki + 1)
    for (fi = 0; fi < 2; fi = fi + 1)
    for (ci = 0; ci < 2; ci = ci + 1)
    for (ai = 0; ai < 2; ai = ai + 1)
    for (ri2 = 0; ri2 < 2; ri2 = ri2 + 1)
    for (tgi = 0; tgi < 2; tgi = tgi + 1) begin
      reset_dut;
      ck(n_alive === 3'd6, "the shortlist did not start with all six classes");
      ck(conclusive === 1'b0, "a fresh shortlist was reported as conclusive");
      ev(1'b1, ki[2:0], fi[0], ci[0], ai[0], ri2[0], tgi[0]);
      ev(1'b0, E_SOF, 1'b0, 1'b0, 1'b1, 1'b1, 1'b0);

      ri = (ki << 5) | (fi << 4) | (ci << 3) | (ai << 2) | (ri2 << 1) | tgi;
      reach[ri] = 1'b1;
    end

    // =============================================================
    //  PHASE 2 (DIRECTED) -- THE POINT OF THE CHAPTER.
    //
    //  A real debug session, narrowed one piece of evidence at a time,
    //  with the shortlist size checked after each step. The fault is a
    //  device that applies SET_ADDRESS too early, and the trace looks
    //  at first exactly like signal integrity.
    // =============================================================
    reset_dut;
    ck(n_alive === 3'd6, "the session did not start with six classes");

    // (1) The trace is full of CRC errors. This SUGGESTS signal integrity
    //     and EXCLUDES nothing -- the shortlist must not move at all.
    //
    //     The toggle is held CONSTANT here on purpose. Alternating it
    //     would eliminate the toggle class as a side effect, and the
    //     first version of this phase did exactly that and then asserted
    //     that nothing had been eliminated. The assertion was right and
    //     the stimulus was wrong.
    for (k = 0; k < 8; k = k + 1)
      ev(1'b1, E_DATA, 1'b1, 1'b1, 1'b1, 1'b1, 1'b0);
    ck(n_alive === 3'd6,
       "CRC errors narrowed the shortlist, but they contradict nothing");

    // (2) One clean packet from the device, same toggle. Signal integrity
    //     cannot be the whole story: a marginal PHY does not selectively
    //     corrupt.
    ev(1'b1, E_DATA, 1'b1, 1'b0, 1'b1, 1'b1, 1'b0);
    ck(c_signal === 1'b0, "a clean device packet did not rule out signal integrity");
    ck(n_alive  === 3'd5, "the shortlist did not shrink to five");

    // (3) Now a DATA packet with the OTHER toggle: the two alternate, so a
    //     desynchronised toggle is ruled out.
    ev(1'b1, E_DATA, 1'b0, 1'b1, 1'b1, 1'b1, 1'b1);
    ck(c_toggle === 1'b0, "alternating toggles did not rule out desynchronisation");
    ck(n_alive  === 3'd4, "the shortlist did not shrink to four");

    // (4) A timeout: the device went silent, so it is not talking too
    //     much. Unsolicited transmission is out.
    ev(1'b1, E_TIMEOUT, 1'b0, 1'b0, 1'b1, 1'b1, 1'b0);
    ck(c_unsolicited === 1'b0, "a timeout did not rule out unsolicited traffic");

    // (5) A STALL: a considered response, so packets arrive intact both
    //     ways. A hub fault is out.
    ev(1'b1, E_STALL, 1'b1, 1'b0, 1'b1, 1'b1, 1'b0);
    ck(c_hub === 1'b0, "a STALL did not rule out a hub fault");

    // (6) Activity outside the post-reset window: the device is not
    //     browning out. Power is out.
    ev(1'b1, E_TOKEN, 1'b0, 1'b0, 1'b1, 1'b0, 1'b0);
    ck(c_power === 1'b0, "activity outside the reset window did not rule out power");

    // ---- and now exactly one class remains ----
    ck(n_alive     === 3'd1, "the session did not narrow to a single class");
    ck(c_addr_early === 1'b1, "the surviving class is not the one the evidence leaves");
    ck(conclusive  === 1'b1, "a single surviving class was not reported as conclusive");

    // (7) The confirming evidence: an ACK at a non-zero address would
    //     rule the last class out too -- and then NOTHING survives,
    //     which must NOT be reported as a diagnosis.
    ev(1'b1, E_ACK, 1'b0, 1'b0, 1'b0, 1'b1, 1'b0);
    ck(c_addr_early === 1'b0, "an ACK at a non-zero address did not rule out the last class");
    ck(n_alive     === 3'd0, "the shortlist did not empty");
    ck(conclusive  === 1'b0, "an empty shortlist was reported as conclusive");

    // =============================================================
    //  PHASE 3 (DIRECTED, EXHAUSTIVE) -- each class eliminated last.
    //
    //  Six orderings, each ending with a different survivor, so the
    //  "exactly one remains" state is reached for every class rather
    //  than for one convenient one.
    // =============================================================
    for (k = 0; k < 6; k = k + 1) begin
      reset_dut;
      // eliminate all but class k
      if (k != 0) ev(1'b1, E_DATA,    1'b1, 1'b0, 1'b1, 1'b1, 1'b0);
      if (k != 1) ev(1'b1, E_ACK,     1'b0, 1'b0, 1'b0, 1'b1, 1'b0);
      if (k != 2) begin
        ev(1'b1, E_DATA, 1'b0, 1'b1, 1'b1, 1'b1, 1'b0);
        ev(1'b1, E_DATA, 1'b0, 1'b1, 1'b1, 1'b1, 1'b1);
      end
      if (k != 3) ev(1'b1, E_TIMEOUT, 1'b0, 1'b0, 1'b1, 1'b1, 1'b0);
      if (k != 4) ev(1'b1, E_STALL,   1'b0, 1'b0, 1'b1, 1'b1, 1'b0);
      if (k != 5) ev(1'b1, E_TOKEN,   1'b0, 1'b0, 1'b1, 1'b0, 1'b0);
      ck(n_alive    === 3'd1, "the ordering did not leave exactly one class");
      ck(conclusive === 1'b1, "a single survivor was not conclusive");
    end

    // =============================================================
    //  PHASE 3b (DIRECTED, EXHAUSTIVE) -- drive the shortlist to EMPTY
    //  by six different routes.
    //
    //  An empty shortlist means the trace contradicts every hypothesis in
    //  the model -- which is informative (the fault is outside the model)
    //  and is NOT a diagnosis. Reporting it as conclusive would be the
    //  worst possible outcome, so it is checked on every route rather than
    //  on one convenient one. Checked once, it killed its mutation 3 times.
    // =============================================================
    for (k = 0; k < 6; k = k + 1) begin
      reset_dut;
      // the six eliminations, rotated so a different one lands last
      for (ki = 0; ki < 6; ki = ki + 1) begin
        ri2 = (ki + k) % 6;
        if (ri2 == 0) ev(1'b1, E_DATA,    1'b1, 1'b0, 1'b1, 1'b1, 1'b0);
        if (ri2 == 1) ev(1'b1, E_ACK,     1'b0, 1'b0, 1'b0, 1'b1, 1'b0);
        if (ri2 == 2) begin
          ev(1'b1, E_DATA, 1'b0, 1'b1, 1'b1, 1'b1, 1'b0);
          ev(1'b1, E_DATA, 1'b0, 1'b1, 1'b1, 1'b1, 1'b1);
        end
        if (ri2 == 3) ev(1'b1, E_TIMEOUT, 1'b0, 1'b0, 1'b1, 1'b1, 1'b0);
        if (ri2 == 4) ev(1'b1, E_STALL,   1'b0, 1'b0, 1'b1, 1'b1, 1'b0);
        if (ri2 == 5) ev(1'b1, E_TOKEN,   1'b0, 1'b0, 1'b1, 1'b0, 1'b0);
        // after every step: a shortlist of one is conclusive, none is not
        ck(conclusive === (n_alive === 3'd1),
           "conclusive does not mean exactly one survivor");
        ck(!(conclusive && (n_alive === 3'd0)),
           "an empty shortlist was reported as conclusive");
      end
      ck(n_alive    === 3'd0, "the six eliminations did not empty the shortlist");
      ck(conclusive === 1'b0, "an empty shortlist was reported as conclusive");
      // and further events must not revive anything
      ev(1'b1, E_SOF, 1'b0, 1'b0, 1'b1, 1'b1, 1'b0);
      ck(n_alive    === 3'd0, "a later event revived an eliminated class");
      ck(conclusive === 1'b0, "an empty shortlist became conclusive");
    end

    // =============================================================
    //  PHASE 4 (RANDOM) -- arbitrary traces.
    // =============================================================
`ifndef DIRECTED_ONLY
    for (k = 0; k < 24000; k = k + 1) begin
      if ((k % 16) == 0) reset_dut;
      ev((urand(0) % 4) != 0, urand(0) % 8, (urand(0) % 2) == 0,
         (urand(0) % 3) == 0, (urand(0) % 2) == 0, (urand(0) % 4) != 0,
         (urand(0) % 2) == 0);
    end
`endif

    n_reach = 0;
    for (ri = 0; ri < 256; ri = ri + 1) if (reach[ri]) n_reach = n_reach + 1;

    $display("steps=%0d checks=%0d reach=%0d/256 errors=%0d",
             steps, checks, n_reach, errors);
    $display("[trace] events=%0d crc_bad=%0d dev_tx=%0d eliminations=%0d",
             g_ev, g_crc, g_dev, g_elim);
    $display("[the whole point] false eliminations = %0d, false survivals = %0d",
             n_false_elim, n_false_surv);
    if (n_reach != 256) begin
      $display("FAIL: exhaustive sweep incomplete"); errors = errors + 1;
    end
    if (errors == 0) $display("PASS: 0 errors in %0d checks", checks);
    else             $display("FAIL: %0d errors in %0d checks", errors, checks);
    $finish;
  end

endmodule

// =====================================================================
//  Testbench for usb_trace_triage.
//
//  The property that matters is NOT "does it find the right fault". It is
//  the two-sided one that a triage tool lives or dies by:
//
//    NO FALSE ELIMINATION -- a class is never ruled out by evidence that
//                            does not actually contradict it.
//    NO FALSE SURVIVAL    -- a class IS ruled out the moment something
//                            contradicts it.
//
//  The first is the dangerous direction. A tool that eliminates the real
//  fault sends the whole team to look somewhere else, and it does so with
//  the authority of a shortlist.
//
//  So the shadow recomputes all six elimination conditions from the event
//  attributes, independently, and compares the full set every cycle --
//  not just the class that changed.
// =====================================================================
`timescale 1ns/1ps
module tb_td_sv;

  localparam [2:0] E_SOF = 3'd0, E_TOKEN = 3'd1, E_DATA = 3'd2, E_ACK = 3'd3,
                   E_NAK = 3'd4, E_STALL = 3'd5, E_TIMEOUT = 3'd6,
                   E_RESET = 3'd7;

  logic      clk = 1'b0, rst_n = 1'b0;
  logic      ev_valid = 1'b0;
  logic [2:0] ev_kind = E_SOF;
  logic      ev_from_device = 1'b0;
  logic      ev_crc_bad = 1'b0;
  logic [6:0] ev_addr = 7'd0;
  logic      ev_addr_is_zero = 1'b1;
  logic      ev_after_reset = 1'b1;
  logic      ev_toggle = 1'b0;

  logic      c_signal, c_addr_early, c_toggle, c_unsolicited, c_hub, c_power;
  logic [2:0] n_alive;
  logic      conclusive;
  logic [31:0] n_events, n_crc_bad, n_dev_tx, n_eliminations;

  usb_trace_triage dut (
    .clk(clk), .rst_n(rst_n),
    .ev_valid(ev_valid), .ev_kind(ev_kind),
    .ev_from_device(ev_from_device), .ev_crc_bad(ev_crc_bad),
    .ev_addr(ev_addr), .ev_addr_is_zero(ev_addr_is_zero),
    .ev_after_reset(ev_after_reset), .ev_toggle(ev_toggle),
    .c_signal(c_signal), .c_addr_early(c_addr_early), .c_toggle(c_toggle),
    .c_unsolicited(c_unsolicited), .c_hub(c_hub), .c_power(c_power),
    .n_alive(n_alive), .conclusive(conclusive),
    .n_events(n_events), .n_crc_bad(n_crc_bad),
    .n_dev_tx(n_dev_tx), .n_eliminations(n_eliminations)
  );

  always #5 clk = ~clk;

  integer errors = 0, checks = 0, steps = 0;
  integer seed;

  function automatic logic [31:0] urand(bit dummy);
    return $random(seed) & 32'h3FFF_FFFF;
  endfunction

  // ---- the shadow: six independent booleans ----
  logic s_sig, s_addr, s_tog, s_unsol, s_hub, s_pwr;
  logic s_last_tog, s_have_tog;
  logic [31:0] x_ev, x_crc, x_dev, x_elim;

  // ---- the two headline counters ----
  // Run-wide totals: the DUT's counters are cleared by every reset, and
  // the random phase resets every 16 events.
  integer g_ev = 0, g_crc = 0, g_dev = 0, g_elim = 0;

  integer n_false_elim = 0;   // a class cleared without contradiction
  integer n_false_surv = 0;   // a class survived a contradiction

  // ---- exhaustive reach over (kind, from_dev, crc, addr0, after_reset) --
  // The event TOGGLE is a sixth dimension, not a constant. Without it the
  // first DATA packet of every scenario carries toggle 0, which equals the
  // reset value of the history -- so a rule that wrongly ignores "is there
  // any history" never fires, and mutation I6 scored 0 directed.
  logic reach [0:255];
  integer ri, n_reach;

  task ck(input logic cond, input logic [255:0] what);
    begin
      checks = checks + 1;
      if (!cond) begin
        errors = errors + 1;
        if (errors <= 20)
          $display("  ERROR @%0t step=%0d: %0s", $time, steps, what);
      end
    end
  endtask

  // ---------------------------------------------------------------
  //  One trace event.
  // ---------------------------------------------------------------
  task ev(input logic v, input logic [2:0] k, input logic fd, input logic cb,
          input logic az, input logic ar, input logic tg);
    logic p_sig, p_addr, p_tog, p_unsol, p_hub, p_pwr;
    logic q_sig, q_addr, q_tog, q_unsol, q_hub, q_pwr;
    logic [2:0] e_alive;
    begin
      ev_valid = v;  ev_kind = k;  ev_from_device = fd;
      ev_crc_bad = cb;  ev_addr_is_zero = az;
      ev_after_reset = ar;  ev_toggle = tg;
      ev_addr = az ? 7'd0 : 7'd42;

      // remember the state BEFORE this event, for the monotonicity check
      p_sig = s_sig; p_addr = s_addr; p_tog = s_tog;
      p_unsol = s_unsol; p_hub = s_hub; p_pwr = s_pwr;

      // ---- the six elimination conditions, recomputed independently ----
      q_sig   = v && fd && !cb;
      q_addr  = v && (k == E_ACK) && !az;
      q_tog   = v && (k == E_DATA) && s_have_tog && (tg != s_last_tog);
      q_unsol = v && (k == E_TIMEOUT);
      q_hub   = v && (k == E_STALL);
      q_pwr   = v && !ar && (k != E_RESET);

      if (v) begin
        x_ev = x_ev + 1;  g_ev = g_ev + 1;
        if (cb) begin x_crc = x_crc + 1; g_crc = g_crc + 1; end
        if (fd) begin x_dev = x_dev + 1; g_dev = g_dev + 1; end
        x_elim = x_elim
               + ((q_sig   && s_sig)   ? 1 : 0)
               + ((q_addr  && s_addr)  ? 1 : 0)
               + ((q_tog   && s_tog)   ? 1 : 0)
               + ((q_unsol && s_unsol) ? 1 : 0)
               + ((q_hub   && s_hub)   ? 1 : 0)
               + ((q_pwr   && s_pwr)   ? 1 : 0);
        g_elim = g_elim
               + ((q_sig   && s_sig)   ? 1 : 0)
               + ((q_addr  && s_addr)  ? 1 : 0)
               + ((q_tog   && s_tog)   ? 1 : 0)
               + ((q_unsol && s_unsol) ? 1 : 0)
               + ((q_hub   && s_hub)   ? 1 : 0)
               + ((q_pwr   && s_pwr)   ? 1 : 0);
        if (q_sig)   s_sig   = 1'b0;
        if (q_addr)  s_addr  = 1'b0;
        if (q_tog)   s_tog   = 1'b0;
        if (q_unsol) s_unsol = 1'b0;
        if (q_hub)   s_hub   = 1'b0;
        if (q_pwr)   s_pwr   = 1'b0;
        if (k == E_DATA) begin
          s_last_tog = tg;
          s_have_tog = 1'b1;
        end
      end

      @(posedge clk);
      #1;
      steps = steps + 1;
      ev_valid = 1'b0;

      // ---- PROPERTY 1: every class matches the shadow ----
      //
      // All six compared every cycle, not just the one that changed. A
      // class cleared as a side effect of another's evidence would
      // otherwise go unnoticed.
      ck(c_signal      === s_sig,   "c_signal disagrees");
      ck(c_addr_early  === s_addr,  "c_addr_early disagrees");
      ck(c_toggle      === s_tog,   "c_toggle disagrees");
      ck(c_unsolicited === s_unsol, "c_unsolicited disagrees");
      ck(c_hub         === s_hub,   "c_hub disagrees");
      ck(c_power       === s_pwr,   "c_power disagrees");

      // ---- PROPERTY 2: NO FALSE ELIMINATION ----
      //
      // The dangerous direction. A class may only go from possible to
      // impossible if its OWN condition held this cycle.
      if (p_sig   && !c_signal      && !q_sig)   n_false_elim = n_false_elim + 1;
      if (p_addr  && !c_addr_early  && !q_addr)  n_false_elim = n_false_elim + 1;
      if (p_tog   && !c_toggle      && !q_tog)   n_false_elim = n_false_elim + 1;
      if (p_unsol && !c_unsolicited && !q_unsol) n_false_elim = n_false_elim + 1;
      if (p_hub   && !c_hub         && !q_hub)   n_false_elim = n_false_elim + 1;
      if (p_pwr   && !c_power       && !q_pwr)   n_false_elim = n_false_elim + 1;
      ck(n_false_elim == 0,
         "a fault class was eliminated by evidence that does not contradict it");

      // ---- PROPERTY 3: NO FALSE SURVIVAL ----
      if (q_sig   && c_signal)      n_false_surv = n_false_surv + 1;
      if (q_addr  && c_addr_early)  n_false_surv = n_false_surv + 1;
      if (q_tog   && c_toggle)      n_false_surv = n_false_surv + 1;
      if (q_unsol && c_unsolicited) n_false_surv = n_false_surv + 1;
      if (q_hub   && c_hub)         n_false_surv = n_false_surv + 1;
      if (q_pwr   && c_power)       n_false_surv = n_false_surv + 1;
      ck(n_false_surv == 0,
         "a fault class survived evidence that contradicts it");

      // ---- PROPERTY 4: elimination is MONOTONIC ----
      //
      // Evidence does not expire. A class that was ruled out stays ruled
      // out, and no later event can revive it.
      ck(!(!p_sig   && c_signal),      "c_signal came back from the dead");
      ck(!(!p_addr  && c_addr_early),  "c_addr_early came back from the dead");
      ck(!(!p_tog   && c_toggle),      "c_toggle came back from the dead");
      ck(!(!p_unsol && c_unsolicited), "c_unsolicited came back from the dead");
      ck(!(!p_hub   && c_hub),         "c_hub came back from the dead");
      ck(!(!p_pwr   && c_power),       "c_power came back from the dead");

      // ---- PROPERTY 5: the shortlist size and the verdict ----
      e_alive = {2'd0, s_sig}   + {2'd0, s_addr} + {2'd0, s_tog}
              + {2'd0, s_unsol} + {2'd0, s_hub}  + {2'd0, s_pwr};
      ck(n_alive === e_alive, "the shortlist size disagrees");
      ck(conclusive === (e_alive == 3'd1), "conclusive disagrees");

      // ---- PROPERTY 6: zero survivors is NOT conclusive ----
      //
      // A trace that contradicts every hypothesis is informative -- the
      // fault is outside the model -- but it is not a diagnosis, and
      // reporting it as one would be the worst possible outcome.
      ck(!(conclusive && (e_alive == 3'd0)),
         "an empty shortlist was reported as conclusive");

      // ---- PROPERTY 7: the counters agree ----
      ck(n_events       === x_ev,   "event count disagrees");
      ck(n_crc_bad      === x_crc,  "CRC-error count disagrees");
      ck(n_dev_tx       === x_dev,  "device-transmission count disagrees");
      ck(n_eliminations === x_elim, "elimination count disagrees");
    end
  endtask

  task reset_dut;
    begin
      rst_n = 1'b0;
      ev_valid = 0;
      @(posedge clk); @(posedge clk);
      rst_n = 1'b1;
      // everything starts possible
      s_sig = 1'b1; s_addr = 1'b1; s_tog = 1'b1;
      s_unsol = 1'b1; s_hub = 1'b1; s_pwr = 1'b1;
      s_last_tog = 1'b0; s_have_tog = 1'b0;
      x_ev = 0; x_crc = 0; x_dev = 0; x_elim = 0;
      @(posedge clk); #1;
    end
  endtask

  integer ki, fi, ci, ai, ri2, tgi, k;

  initial begin
    for (ri = 0; ri < 256; ri = ri + 1) reach[ri] = 1'b0;
    seed = 32'd27009;

    // =============================================================
    //  PHASE 1 (DIRECTED, EXHAUSTIVE) -- every event attribute
    //  combination, against a freshly reset shortlist.
    //  8 kinds x from_device x crc x addr0 x after_reset x toggle = 256.
    // =============================================================
    for (ki = 0; ki < 8; ki = ki + 1)
    for (fi = 0; fi < 2; fi = fi + 1)
    for (ci = 0; ci < 2; ci = ci + 1)
    for (ai = 0; ai < 2; ai = ai + 1)
    for (ri2 = 0; ri2 < 2; ri2 = ri2 + 1)
    for (tgi = 0; tgi < 2; tgi = tgi + 1) begin
      reset_dut;
      ck(n_alive === 3'd6, "the shortlist did not start with all six classes");
      ck(conclusive === 1'b0, "a fresh shortlist was reported as conclusive");
      ev(1'b1, ki[2:0], fi[0], ci[0], ai[0], ri2[0], tgi[0]);
      ev(1'b0, E_SOF, 1'b0, 1'b0, 1'b1, 1'b1, 1'b0);

      ri = (ki << 5) | (fi << 4) | (ci << 3) | (ai << 2) | (ri2 << 1) | tgi;
      reach[ri] = 1'b1;
    end

    // =============================================================
    //  PHASE 2 (DIRECTED) -- THE POINT OF THE CHAPTER.
    //
    //  A real debug session, narrowed one piece of evidence at a time,
    //  with the shortlist size checked after each step. The fault is a
    //  device that applies SET_ADDRESS too early, and the trace looks
    //  at first exactly like signal integrity.
    // =============================================================
    reset_dut;
    ck(n_alive === 3'd6, "the session did not start with six classes");

    // (1) The trace is full of CRC errors. This SUGGESTS signal integrity
    //     and EXCLUDES nothing -- the shortlist must not move at all.
    //
    //     The toggle is held CONSTANT here on purpose. Alternating it
    //     would eliminate the toggle class as a side effect, and the
    //     first version of this phase did exactly that and then asserted
    //     that nothing had been eliminated. The assertion was right and
    //     the stimulus was wrong.
    for (k = 0; k < 8; k = k + 1)
      ev(1'b1, E_DATA, 1'b1, 1'b1, 1'b1, 1'b1, 1'b0);
    ck(n_alive === 3'd6,
       "CRC errors narrowed the shortlist, but they contradict nothing");

    // (2) One clean packet from the device, same toggle. Signal integrity
    //     cannot be the whole story: a marginal PHY does not selectively
    //     corrupt.
    ev(1'b1, E_DATA, 1'b1, 1'b0, 1'b1, 1'b1, 1'b0);
    ck(c_signal === 1'b0, "a clean device packet did not rule out signal integrity");
    ck(n_alive  === 3'd5, "the shortlist did not shrink to five");

    // (3) Now a DATA packet with the OTHER toggle: the two alternate, so a
    //     desynchronised toggle is ruled out.
    ev(1'b1, E_DATA, 1'b0, 1'b1, 1'b1, 1'b1, 1'b1);
    ck(c_toggle === 1'b0, "alternating toggles did not rule out desynchronisation");
    ck(n_alive  === 3'd4, "the shortlist did not shrink to four");

    // (4) A timeout: the device went silent, so it is not talking too
    //     much. Unsolicited transmission is out.
    ev(1'b1, E_TIMEOUT, 1'b0, 1'b0, 1'b1, 1'b1, 1'b0);
    ck(c_unsolicited === 1'b0, "a timeout did not rule out unsolicited traffic");

    // (5) A STALL: a considered response, so packets arrive intact both
    //     ways. A hub fault is out.
    ev(1'b1, E_STALL, 1'b1, 1'b0, 1'b1, 1'b1, 1'b0);
    ck(c_hub === 1'b0, "a STALL did not rule out a hub fault");

    // (6) Activity outside the post-reset window: the device is not
    //     browning out. Power is out.
    ev(1'b1, E_TOKEN, 1'b0, 1'b0, 1'b1, 1'b0, 1'b0);
    ck(c_power === 1'b0, "activity outside the reset window did not rule out power");

    // ---- and now exactly one class remains ----
    ck(n_alive     === 3'd1, "the session did not narrow to a single class");
    ck(c_addr_early === 1'b1, "the surviving class is not the one the evidence leaves");
    ck(conclusive  === 1'b1, "a single surviving class was not reported as conclusive");

    // (7) The confirming evidence: an ACK at a non-zero address would
    //     rule the last class out too -- and then NOTHING survives,
    //     which must NOT be reported as a diagnosis.
    ev(1'b1, E_ACK, 1'b0, 1'b0, 1'b0, 1'b1, 1'b0);
    ck(c_addr_early === 1'b0, "an ACK at a non-zero address did not rule out the last class");
    ck(n_alive     === 3'd0, "the shortlist did not empty");
    ck(conclusive  === 1'b0, "an empty shortlist was reported as conclusive");

    // =============================================================
    //  PHASE 3 (DIRECTED, EXHAUSTIVE) -- each class eliminated last.
    //
    //  Six orderings, each ending with a different survivor, so the
    //  "exactly one remains" state is reached for every class rather
    //  than for one convenient one.
    // =============================================================
    for (k = 0; k < 6; k = k + 1) begin
      reset_dut;
      // eliminate all but class k
      if (k != 0) ev(1'b1, E_DATA,    1'b1, 1'b0, 1'b1, 1'b1, 1'b0);
      if (k != 1) ev(1'b1, E_ACK,     1'b0, 1'b0, 1'b0, 1'b1, 1'b0);
      if (k != 2) begin
        ev(1'b1, E_DATA, 1'b0, 1'b1, 1'b1, 1'b1, 1'b0);
        ev(1'b1, E_DATA, 1'b0, 1'b1, 1'b1, 1'b1, 1'b1);
      end
      if (k != 3) ev(1'b1, E_TIMEOUT, 1'b0, 1'b0, 1'b1, 1'b1, 1'b0);
      if (k != 4) ev(1'b1, E_STALL,   1'b0, 1'b0, 1'b1, 1'b1, 1'b0);
      if (k != 5) ev(1'b1, E_TOKEN,   1'b0, 1'b0, 1'b1, 1'b0, 1'b0);
      ck(n_alive    === 3'd1, "the ordering did not leave exactly one class");
      ck(conclusive === 1'b1, "a single survivor was not conclusive");
    end

    // =============================================================
    //  PHASE 3b (DIRECTED, EXHAUSTIVE) -- drive the shortlist to EMPTY
    //  by six different routes.
    //
    //  An empty shortlist means the trace contradicts every hypothesis in
    //  the model -- which is informative (the fault is outside the model)
    //  and is NOT a diagnosis. Reporting it as conclusive would be the
    //  worst possible outcome, so it is checked on every route rather than
    //  on one convenient one. Checked once, it killed its mutation 3 times.
    // =============================================================
    for (k = 0; k < 6; k = k + 1) begin
      reset_dut;
      // the six eliminations, rotated so a different one lands last
      for (ki = 0; ki < 6; ki = ki + 1) begin
        ri2 = (ki + k) % 6;
        if (ri2 == 0) ev(1'b1, E_DATA,    1'b1, 1'b0, 1'b1, 1'b1, 1'b0);
        if (ri2 == 1) ev(1'b1, E_ACK,     1'b0, 1'b0, 1'b0, 1'b1, 1'b0);
        if (ri2 == 2) begin
          ev(1'b1, E_DATA, 1'b0, 1'b1, 1'b1, 1'b1, 1'b0);
          ev(1'b1, E_DATA, 1'b0, 1'b1, 1'b1, 1'b1, 1'b1);
        end
        if (ri2 == 3) ev(1'b1, E_TIMEOUT, 1'b0, 1'b0, 1'b1, 1'b1, 1'b0);
        if (ri2 == 4) ev(1'b1, E_STALL,   1'b0, 1'b0, 1'b1, 1'b1, 1'b0);
        if (ri2 == 5) ev(1'b1, E_TOKEN,   1'b0, 1'b0, 1'b1, 1'b0, 1'b0);
        // after every step: a shortlist of one is conclusive, none is not
        ck(conclusive === (n_alive === 3'd1),
           "conclusive does not mean exactly one survivor");
        ck(!(conclusive && (n_alive === 3'd0)),
           "an empty shortlist was reported as conclusive");
      end
      ck(n_alive    === 3'd0, "the six eliminations did not empty the shortlist");
      ck(conclusive === 1'b0, "an empty shortlist was reported as conclusive");
      // and further events must not revive anything
      ev(1'b1, E_SOF, 1'b0, 1'b0, 1'b1, 1'b1, 1'b0);
      ck(n_alive    === 3'd0, "a later event revived an eliminated class");
      ck(conclusive === 1'b0, "an empty shortlist became conclusive");
    end

    // =============================================================
    //  PHASE 4 (RANDOM) -- arbitrary traces.
    // =============================================================
`ifndef DIRECTED_ONLY
    for (k = 0; k < 24000; k = k + 1) begin
      if ((k % 16) == 0) reset_dut;
      ev((urand(0) % 4) != 0, urand(0) % 8, (urand(0) % 2) == 0,
         (urand(0) % 3) == 0, (urand(0) % 2) == 0, (urand(0) % 4) != 0,
         (urand(0) % 2) == 0);
    end
`endif

    n_reach = 0;
    for (ri = 0; ri < 256; ri = ri + 1) if (reach[ri]) n_reach = n_reach + 1;

    $display("steps=%0d checks=%0d reach=%0d/256 errors=%0d",
             steps, checks, n_reach, errors);
    $display("[trace] events=%0d crc_bad=%0d dev_tx=%0d eliminations=%0d",
             g_ev, g_crc, g_dev, g_elim);
    $display("[the whole point] false eliminations = %0d, false survivals = %0d",
             n_false_elim, n_false_surv);
    if (n_reach != 256) begin
      $display("FAIL: exhaustive sweep incomplete"); errors = errors + 1;
    end
    if (errors == 0) $display("PASS: 0 errors in %0d checks", checks);
    else             $display("FAIL: %0d errors in %0d checks", errors, checks);
    $finish;
  end

endmodule