CRC Errors

   CRC5    x^5 + x^2 + 1                    poly 0x05
           covers the 11-bit TOKEN field:
           7-bit address + 4-bit endpoint.
           Sent by the HOST, on every single transaction.

   CRC16   x^16 + x^15 + x^2 + 1            poly 0x8005
           covers the DATA payload.
           Sent by whoever has the data, so either direction.

   Both:   initial value all ones
           result complemented

   scattered singles     . . X . . . . X . . . X . . . . X . .
                         marginal signal. Thermal noise, an eye
                         that is closing, a bad margin.

   runs                  . . . . X X X X X . . . . . . X X X X .
                         something PERIODIC. EMI from a switching
                         supply, a fan, a motor, a clock spur.

   CRC5  residual = 0x0C      for all 2048 token values
   CRC16 residual = 0x800D

   2048 tokens x 16 bit positions        =  32768 single-bit errors
   2048 tokens x C(16,2) = 120 pairs     = 245760 double-bit errors

   undetected: 0 and 0.

// usb_crc_analyzer -- the two real USB CRCs, and the reason the count of
// CRC failures is nearly useless while the DISTRIBUTION of them is the most
// direct evidence about the physical layer you will ever get.
//
// THE TWO POLYNOMIALS, AND WHAT EACH ONE COVERS
//
//     CRC5    x^5 + x^2 + 1                          poly 0x05
//             covers the 11-bit TOKEN field: 7-bit address + 4-bit
//             endpoint. Sent by the HOST, every single transaction.
//
//     CRC16   x^16 + x^15 + x^2 + 1                  poly 0x8005
//             covers the DATA payload. Sent by whoever has the data, so
//             either direction.
//
// Both are initialised to all ones and both have their result complemented,
// which is not decoration: it makes a codeword of all zeros -- the thing a
// dead receiver produces -- fail, and it makes leading zeros in the data
// change the result.
//
// THE FIELD NAMES THE DIRECTION
//
// This is the part that turns a CRC counter into a diagnosis. A token is
// ALWAYS host-to-device. So:
//
//     CRC5 failures        the DOWNSTREAM half is damaged. Always.
//     CRC16 on IN data     the UPSTREAM half is damaged.
//     CRC16 on OUT data    the DOWNSTREAM half is damaged.
//     both halves          common mode: power, ground, the connector,
//                          or the cable as a whole.
//
// A device that reports thousands of CRC16 failures on IN transfers and no
// CRC5 failures at all has a perfectly good downstream path -- which rules
// out half the usual suspects on the first reading of the counter.
//
// AND THE CLUSTERING NAMES THE MECHANISM
//
//     scattered single failures   marginal signal. Thermal noise,
//                                 an eye that is closing, a bad margin.
//
//     failures in RUNS            something periodic. EMI from a switching
//                                 supply, a fan, a motor, a clock spur.
//
// Same total. Completely different thing to go and look at. So this block
// counts a failure as BURST when the previous checked codeword also failed,
// and as ISOLATED otherwise -- a run of five failures is one isolated and
// four burst, and the ratio is the measurement.
//
// A RECEIVER CHECKS THE RESIDUAL, IT DOES NOT RECOMPUTE AND COMPARE
//
// Feeding the WHOLE codeword -- data and the received CRC together --
// through the same shift register leaves a CONSTANT, whatever the data was.
// It is one register instead of two and a comparison against a constant
// instead of against a computed value.
//
//     CRC5  residual = 5'h0C     for all 2048 token values
//     CRC16 residual = 16'h800D
//
// Those two constants are checked exhaustively by the testbench rather than
// quoted, because a wrong residual constant produces a checker that passes
// everything, and nothing else in the system will notice.
module usb_crc_analyzer #(
  parameter integer BURST_MIN = 2   // a run of this length is a burst
) (
  input  wire        clk,
  input  wire        rst_n,

  // ---- the token: 11 bits plus its CRC5, always host-to-device ----
  input  wire        tok_valid,
  input  wire [10:0] tok_data,     // {endpoint[3:0], address[6:0]}
  input  wire [4:0]  tok_crc5,     // as received

  // ---- the data packet: a byte stream plus its CRC16 ----
  input  wire        dat_start,    // begin a packet
  input  wire        dat_valid,    // one payload byte
  input  wire [7:0]  dat_byte,
  input  wire        dat_end,      // end of packet; dat_crc16 is valid now
  input  wire [15:0] dat_crc16,    // as received
  input  wire        dat_dir,      // 0 = OUT (downstream), 1 = IN (upstream)

  input  wire        eot,

  output wire [4:0]  crc5_gen,     // what the CRC5 SHOULD be
  output wire [4:0]  crc5_resid,   // the residual of the received codeword
  output wire        crc5_ok,
  output wire [15:0] crc16_gen,
  output wire [15:0] crc16_resid,
  output wire        crc16_ok,

  output wire        fail_pulse,
  output wire        fail_field,   // 0 = token (CRC5), 1 = data (CRC16)
  output wire [7:0]  fail_run,     // consecutive failures
  output wire [2:0]  verdict,
  output wire        bursty,

  output reg [31:0] n_tok,
  output reg [31:0] n_tok_fail,
  output reg [31:0] n_dat,
  output reg [31:0] n_dat_fail,
  output reg [31:0] n_down_fail,   // host -> device
  output reg [31:0] n_up_fail,     // device -> host
  output reg [31:0] n_burst,
  output reg [31:0] n_isolated
);

  localparam [4:0]  CRC5_INIT  = 5'h1F,  CRC5_POLY  = 5'h05;
  localparam [15:0] CRC16_INIT = 16'hFFFF, CRC16_POLY = 16'h8005;

  // The two residual constants. Named, so that the testbench can prove them
  // rather than the design asserting them.
  localparam [4:0]  CRC5_RESID  = 5'h0C;
  localparam [15:0] CRC16_RESID = 16'h800D;

  // ---- The burst threshold is derived once, at full width. ----
  //
  // Writing `run_r >= BURST_MIN[7:0] - 8'd1` inline works. What it hides is
  // that the expression TRUNCATES the parameter to eight bits: it is correct
  // here only because a run counter is eight bits, and it would be silently
  // wrong the moment either width changed without the other.
  //
  // Chapter 25.4's retry budget is the same trap with teeth -- there, a
  // two-bit comparison turned MAX_RETRY = 5 into 1 and no test written
  // against the default value noticed. The rule that comes out of it:
  // derive a width from what the value MEANS, never from what its default
  // happens to need.
  localparam [7:0] BURST_THRESH = BURST_MIN - 1;

  localparam [2:0] V_CLEAN  = 3'd0,  // nothing failed
                   V_DOWN   = 3'd1,  // host -> device is damaged
                   V_UP     = 3'd2,  // device -> host is damaged
                   V_COMMON = 3'd3;  // both: power, ground, the connector

  // ---- One bit into the CRC5 shift register. ----
  //
  // Data goes in LSB first, which is the order it is sent on the wire. Get
  // this backwards and every value is wrong, all 2048 of them, so the
  // spec's own worked example -- address 0x15, endpoint 0xE, CRC5 0x17 --
  // is the first thing the testbench checks.
  function [4:0] crc5_step;
    input [4:0] c;
    input       b;
    reg         x;
    begin
      x = b ^ c[4];
      crc5_step = {c[3:0], 1'b0};
      if (x) crc5_step = crc5_step ^ CRC5_POLY;
    end
  endfunction

  function [4:0] crc5_of;
    input [10:0] d;
    reg [4:0] c;
    integer   i;
    begin
      c = CRC5_INIT;
      for (i = 0; i < 11; i = i + 1) c = crc5_step(c, d[i]);
      crc5_of = ~c;
    end
  endfunction

  // ---- The RESIDUAL: the same register, fed the CRC as well. ----
  //
  // The received CRC goes in MSB first, because that is the order it
  // arrives in relative to the shift register's own direction.
  function [4:0] crc5_residual_of;
    input [10:0] d;
    input [4:0]  r;
    reg [4:0] c;
    integer   i;
    begin
      c = CRC5_INIT;
      for (i = 0; i < 11; i = i + 1) c = crc5_step(c, d[i]);
      for (i = 4; i >= 0; i = i - 1) c = crc5_step(c, r[i]);
      crc5_residual_of = c;
    end
  endfunction

  function [15:0] crc16_step;
    input [15:0] c;
    input        b;
    reg          x;
    begin
      x = b ^ c[15];
      crc16_step = {c[14:0], 1'b0};
      if (x) crc16_step = crc16_step ^ CRC16_POLY;
    end
  endfunction

  function [15:0] crc16_byte;
    input [15:0] c;
    input [7:0]  b;
    reg [15:0] t;
    integer    i;
    begin
      t = c;
      for (i = 0; i < 8; i = i + 1) t = crc16_step(t, b[i]);
      crc16_byte = t;
    end
  endfunction

  function [15:0] crc16_absorb16;
    input [15:0] c;
    input [15:0] r;
    reg [15:0] t;
    integer    i;
    begin
      t = c;
      for (i = 15; i >= 0; i = i - 1) t = crc16_step(t, r[i]);
      crc16_absorb16 = t;
    end
  endfunction

  // ---- The token check is purely combinational: 11 bits, one cycle. ----
  wire [4:0] t_gen   = crc5_of(tok_data);
  wire [4:0] t_resid = crc5_residual_of(tok_data, tok_crc5);
  wire       t_ok    = (t_resid == CRC5_RESID);

  assign crc5_gen   = t_gen;
  assign crc5_resid = t_resid;
  assign crc5_ok    = t_ok;

  // ---- The data check accumulates across the packet. ----
  reg [15:0] c16_r;
  wire [15:0] d_gen   = ~c16_r;
  wire [15:0] d_resid = crc16_absorb16(c16_r, dat_crc16);
  wire        d_ok    = (d_resid == CRC16_RESID);

  assign crc16_gen   = d_gen;
  assign crc16_resid = d_resid;
  assign crc16_ok    = d_ok;

  reg [7:0] run_r;
  reg       fp_r, ff_r;
  assign fail_pulse = fp_r;
  assign fail_field = ff_r;
  assign fail_run   = run_r;

  // ---- The verdict. ----
  //
  // A ratio, not a count. "Two thousand CRC errors" says nothing; "every
  // one of them upstream" says the downstream half is fine and halves the
  // search on the first reading.
  assign verdict = ((n_down_fail == 32'd0) && (n_up_fail == 32'd0)) ? V_CLEAN :
                   (n_down_fail > (n_up_fail   << 1))              ? V_DOWN  :
                   (n_up_fail   > (n_down_fail << 1))              ? V_UP    :
                                                                     V_COMMON;

  // Most failures arrived in runs -> something periodic. Scattered ->
  // marginal signal. Same total, different thing to go and look at.
  assign bursty = (n_burst > n_isolated);

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      c16_r      <= CRC16_INIT;
      run_r      <= 8'd0;
      fp_r       <= 1'b0;
      ff_r       <= 1'b0;
      n_tok      <= 32'd0;
      n_tok_fail <= 32'd0;
      n_dat      <= 32'd0;
      n_dat_fail <= 32'd0;
      n_down_fail<= 32'd0;
      n_up_fail  <= 32'd0;
      n_burst    <= 32'd0;
      n_isolated <= 32'd0;
    end else begin
      fp_r <= 1'b0;

      if (eot) begin
        // Nothing: the counters are the report.
      end else begin
        // ---- the data packet's shift register ----
        //
        // dat_start and dat_valid can be asserted together, so the reset to
        // CRC16_INIT has to happen before the byte is absorbed rather than
        // instead of it. Written the other way round, the first byte of
        // every packet is silently dropped and the CRC is wrong for every
        // packet in exactly the same way -- which looks like a polynomial
        // error and is not.
        if (dat_start && dat_valid)
          c16_r <= crc16_byte(CRC16_INIT, dat_byte);
        else if (dat_start)
          c16_r <= CRC16_INIT;
        else if (dat_valid)
          c16_r <= crc16_byte(c16_r, dat_byte);

        if (tok_valid) begin
          n_tok <= n_tok + 32'd1;
          if (!t_ok) begin
            fp_r       <= 1'b1;
            ff_r       <= 1'b0;
            n_tok_fail <= n_tok_fail + 32'd1;
            // A TOKEN is always host-to-device. There is no ambiguity to
            // resolve and no direction input to get wrong.
            n_down_fail<= n_down_fail + 32'd1;
            if (run_r >= BURST_THRESH) n_burst    <= n_burst    + 32'd1;
            else                       n_isolated <= n_isolated + 32'd1;
            if (run_r != 8'hFF) run_r <= run_r + 8'd1;
          end else begin
            run_r <= 8'd0;
          end
        end else if (dat_end) begin
          n_dat <= n_dat + 32'd1;
          if (!d_ok) begin
            fp_r       <= 1'b1;
            ff_r       <= 1'b1;
            n_dat_fail <= n_dat_fail + 32'd1;
            // Data goes in whichever direction the transfer does, so here
            // the direction has to be told to us.
            if (dat_dir) n_up_fail   <= n_up_fail   + 32'd1;
            else         n_down_fail <= n_down_fail + 32'd1;
            if (run_r >= BURST_THRESH) n_burst    <= n_burst    + 32'd1;
            else                       n_isolated <= n_isolated + 32'd1;
            if (run_r != 8'hFF) run_r <= run_r + 8'd1;
          end else begin
            run_r <= 8'd0;
          end
        end
      end
    end
  end
endmodule

// usb_crc_analyzer -- the two real USB CRCs, and the reason the count of
// CRC failures is nearly useless while the DISTRIBUTION of them is the most
// direct evidence about the physical layer you will ever get.
//
// THE TWO POLYNOMIALS, AND WHAT EACH ONE COVERS
//
//     CRC5    x^5 + x^2 + 1                          poly 0x05
//             covers the 11-bit TOKEN field: 7-bit address + 4-bit
//             endpoint. Sent by the HOST, every single transaction.
//
//     CRC16   x^16 + x^15 + x^2 + 1                  poly 0x8005
//             covers the DATA payload. Sent by whoever has the data, so
//             either direction.
//
// Both are initialised to all ones and both have their result complemented,
// which is not decoration: it makes a codeword of all zeros -- the thing a
// dead receiver produces -- fail, and it makes leading zeros in the data
// change the result.
//
// THE FIELD NAMES THE DIRECTION
//
// This is the part that turns a CRC counter into a diagnosis. A token is
// ALWAYS host-to-device. So:
//
//     CRC5 failures        the DOWNSTREAM half is damaged. Always.
//     CRC16 on IN data     the UPSTREAM half is damaged.
//     CRC16 on OUT data    the DOWNSTREAM half is damaged.
//     both halves          common mode: power, ground, the connector,
//                          or the cable as a whole.
//
// A device that reports thousands of CRC16 failures on IN transfers and no
// CRC5 failures at all has a perfectly good downstream path -- which rules
// out half the usual suspects on the first reading of the counter.
//
// AND THE CLUSTERING NAMES THE MECHANISM
//
//     scattered single failures   marginal signal. Thermal noise,
//                                 an eye that is closing, a bad margin.
//
//     failures in RUNS            something periodic. EMI from a switching
//                                 supply, a fan, a motor, a clock spur.
//
// Same total. Completely different thing to go and look at. So this block
// counts a failure as BURST when the previous checked codeword also failed,
// and as ISOLATED otherwise -- a run of five failures is one isolated and
// four burst, and the ratio is the measurement.
//
// A RECEIVER CHECKS THE RESIDUAL, IT DOES NOT RECOMPUTE AND COMPARE
//
// Feeding the WHOLE codeword -- data and the received CRC together --
// through the same shift register leaves a CONSTANT, whatever the data was.
// It is one register instead of two and a comparison against a constant
// instead of against a computed value.
//
//     CRC5  residual = 5'h0C     for all 2048 token values
//     CRC16 residual = 16'h800D
//
// Those two constants are checked exhaustively by the testbench rather than
// quoted, because a wrong residual constant produces a checker that passes
// everything, and nothing else in the system will notice.
package usb_crc_pkg;
  // The verdict is the whole point of the block, so it gets a type. A
  // three-bit output called `verdict` is a number somebody has to look up;
  // an enumeration prints V_UPSTREAM in the waveform viewer and in the log.
  typedef enum logic [2:0] {
    V_CLEAN  = 3'd0,   // nothing failed
    V_DOWN   = 3'd1,   // host -> device is damaged
    V_UP     = 3'd2,   // device -> host is damaged
    V_COMMON = 3'd3    // both: power, ground, the connector
  } verdict_e;

  typedef enum logic {
    F_TOKEN = 1'b0,    // CRC5 -- always host-to-device
    F_DATA  = 1'b1     // CRC16 -- whichever way the transfer went
  } field_e;
endpackage

module usb_crc_analyzer
  import usb_crc_pkg::*;
 #(
  parameter int BURST_MIN = 2       // a run of this length is a burst
) (
  input  logic       clk,
  input  logic       rst_n,

  // ---- the token: 11 bits plus its CRC5, always host-to-device ----
  input  logic       tok_valid,
  input  logic [10:0] tok_data,    // {endpoint[3:0], address[6:0]}
  input  logic [4:0]  tok_crc5,    // as received

  // ---- the data packet: a byte stream plus its CRC16 ----
  input  logic       dat_start,    // begin a packet
  input  logic       dat_valid,    // one payload byte
  input  logic [7:0] dat_byte,
  input  logic       dat_end,      // end of packet; dat_crc16 is valid now
  input  logic [15:0] dat_crc16,   // as received
  input  logic       dat_dir,      // 0 = OUT (downstream), 1 = IN (upstream)

  input  logic       eot,

  output logic [4:0]  crc5_gen,    // what the CRC5 SHOULD be
  output logic [4:0]  crc5_resid,  // the residual of the received codeword
  output logic        crc5_ok,
  output logic [15:0] crc16_gen,
  output logic [15:0] crc16_resid,
  output logic        crc16_ok,

  output logic        fail_pulse,
  output field_e      fail_field,
  output logic [7:0]  fail_run,    // consecutive failures
  output verdict_e    verdict,
  output logic        bursty,

  output logic [31:0] n_tok,
  output logic [31:0] n_tok_fail,
  output logic [31:0] n_dat,
  output logic [31:0] n_dat_fail,
  output logic [31:0] n_down_fail,   // host -> device
  output logic [31:0] n_up_fail,     // device -> host
  output logic [31:0] n_burst,
  output logic [31:0] n_isolated
);

  localparam [4:0]  CRC5_INIT  = 5'h1F,  CRC5_POLY  = 5'h05;
  localparam [15:0] CRC16_INIT = 16'hFFFF, CRC16_POLY = 16'h8005;

  // The two residual constants. Named, so that the testbench can prove them
  // rather than the design asserting them.
  localparam [4:0]  CRC5_RESID  = 5'h0C;
  localparam [15:0] CRC16_RESID = 16'h800D;

  // ---- The burst threshold is derived once, at full width. ----
  //
  // Writing `run_r >= BURST_MIN[7:0] - 8'd1` inline works. What it hides is
  // that the expression TRUNCATES the parameter to eight bits: it is correct
  // here only because a run counter is eight bits, and it would be silently
  // wrong the moment either width changed without the other.
  //
  // Chapter 25.4's retry budget is the same trap with teeth -- there, a
  // two-bit comparison turned MAX_RETRY = 5 into 1 and no test written
  // against the default value noticed. The rule that comes out of it:
  // derive a width from what the value MEANS, never from what its default
  // happens to need.
  localparam logic [7:0] BURST_THRESH = 8'(BURST_MIN - 1);

  // ---- One bit into the CRC5 shift register. ----
  //
  // Data goes in LSB first, which is the order it is sent on the wire. Get
  // this backwards and every value is wrong, all 2048 of them, so the
  // spec's own worked example -- address 0x15, endpoint 0xE, CRC5 0x17 --
  // is the first thing the testbench checks.
  function automatic logic [4:0] crc5_step(input logic [4:0] c,
                                          input logic       b);
    logic x;
    begin
      x = b ^ c[4];
      crc5_step = {c[3:0], 1'b0};
      if (x) crc5_step = crc5_step ^ CRC5_POLY;
    end
  endfunction

  function automatic logic [4:0] crc5_of(input logic [10:0] d);
    logic [4:0] c;
    int         i;
    begin
      c = CRC5_INIT;
      for (i = 0; i < 11; i = i + 1) c = crc5_step(c, d[i]);
      crc5_of = ~c;
    end
  endfunction

  // ---- The RESIDUAL: the same register, fed the CRC as well. ----
  //
  // The received CRC goes in MSB first, because that is the order it
  // arrives in relative to the shift register's own direction.
  function automatic logic [4:0] crc5_residual_of(input logic [10:0] d,
                                                 input logic [4:0]  r);
    logic [4:0] c;
    int         i;
    begin
      c = CRC5_INIT;
      for (i = 0; i < 11; i = i + 1) c = crc5_step(c, d[i]);
      for (i = 4; i >= 0; i = i - 1) c = crc5_step(c, r[i]);
      crc5_residual_of = c;
    end
  endfunction

  function automatic logic [15:0] crc16_step(input logic [15:0] c,
                                            input logic        b);
    logic x;
    begin
      x = b ^ c[15];
      crc16_step = {c[14:0], 1'b0};
      if (x) crc16_step = crc16_step ^ CRC16_POLY;
    end
  endfunction

  function automatic logic [15:0] crc16_byte(input logic [15:0] c,
                                            input logic [7:0]  b);
    logic [15:0] t;
    int          i;
    begin
      t = c;
      for (i = 0; i < 8; i = i + 1) t = crc16_step(t, b[i]);
      crc16_byte = t;
    end
  endfunction

  function automatic logic [15:0] crc16_absorb16(input logic [15:0] c,
                                                input logic [15:0] r);
    logic [15:0] t;
    int          i;
    begin
      t = c;
      for (i = 15; i >= 0; i = i - 1) t = crc16_step(t, r[i]);
      crc16_absorb16 = t;
    end
  endfunction

  // ---- The token check is purely combinational: 11 bits, one cycle. ----
  logic [4:0] t_gen; assign t_gen   = crc5_of(tok_data);
  logic [4:0] t_resid; assign t_resid = crc5_residual_of(tok_data, tok_crc5);
  logic t_ok; assign t_ok    = (t_resid == CRC5_RESID);

  assign crc5_gen   = t_gen;
  assign crc5_resid = t_resid;
  assign crc5_ok    = t_ok;

  // ---- The data check accumulates across the packet. ----
  logic [15:0] c16_r;
  logic [15:0] d_gen; assign d_gen   = ~c16_r;
  logic [15:0] d_resid; assign d_resid = crc16_absorb16(c16_r, dat_crc16);
  logic d_ok; assign d_ok    = (d_resid == CRC16_RESID);

  assign crc16_gen   = d_gen;
  assign crc16_resid = d_resid;
  assign crc16_ok    = d_ok;

  logic [7:0] run_r;
  logic       fp_r;
  field_e     ff_r;
  assign fail_pulse = fp_r;
  assign fail_field = ff_r;
  assign fail_run   = run_r;

  // ---- The verdict. ----
  //
  // A ratio, not a count. "Two thousand CRC errors" says nothing; "every
  // one of them upstream" says the downstream half is fine and halves the
  // search on the first reading.
  //
  // Written as a function rather than a chain of ternaries: a conditional
  // expression whose arms are enumeration literals needs an explicit cast
  // in SystemVerilog, and Icarus rejects it outright.
  function automatic verdict_e classify(input logic [31:0] dn,
                                        input logic [31:0] up);
    begin
      if ((dn == 32'd0) && (up == 32'd0)) classify = V_CLEAN;
      else if (dn > (up << 1))            classify = V_DOWN;
      else if (up > (dn << 1))            classify = V_UP;
      else                                classify = V_COMMON;
    end
  endfunction

  assign verdict = classify(n_down_fail, n_up_fail);

  // Most failures arrived in runs -> something periodic. Scattered ->
  // marginal signal. Same total, different thing to go and look at.
  assign bursty = (n_burst > n_isolated);

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      c16_r      <= CRC16_INIT;
      run_r      <= 8'd0;
      fp_r       <= 1'b0;
      ff_r       <= F_TOKEN;
      n_tok      <= 32'd0;
      n_tok_fail <= 32'd0;
      n_dat      <= 32'd0;
      n_dat_fail <= 32'd0;
      n_down_fail<= 32'd0;
      n_up_fail  <= 32'd0;
      n_burst    <= 32'd0;
      n_isolated <= 32'd0;
    end else begin
      fp_r <= 1'b0;

      if (eot) begin
        // Nothing: the counters are the report.
      end else begin
        // ---- the data packet's shift register ----
        //
        // dat_start and dat_valid can be asserted together, so the reset to
        // CRC16_INIT has to happen before the byte is absorbed rather than
        // instead of it. Written the other way round, the first byte of
        // every packet is silently dropped and the CRC is wrong for every
        // packet in exactly the same way -- which looks like a polynomial
        // error and is not.
        if (dat_start && dat_valid)
          c16_r <= crc16_byte(CRC16_INIT, dat_byte);
        else if (dat_start)
          c16_r <= CRC16_INIT;
        else if (dat_valid)
          c16_r <= crc16_byte(c16_r, dat_byte);

        if (tok_valid) begin
          n_tok <= n_tok + 32'd1;
          if (!t_ok) begin
            fp_r       <= 1'b1;
            ff_r       <= F_TOKEN;
            n_tok_fail <= n_tok_fail + 32'd1;
            // A TOKEN is always host-to-device. There is no ambiguity to
            // resolve and no direction input to get wrong.
            n_down_fail<= n_down_fail + 32'd1;
            if (run_r >= BURST_THRESH) n_burst    <= n_burst    + 32'd1;
            else                       n_isolated <= n_isolated + 32'd1;
            if (run_r != 8'hFF) run_r <= run_r + 8'd1;
          end else begin
            run_r <= 8'd0;
          end
        end else if (dat_end) begin
          n_dat <= n_dat + 32'd1;
          if (!d_ok) begin
            fp_r       <= 1'b1;
            ff_r       <= F_DATA;
            n_dat_fail <= n_dat_fail + 32'd1;
            // Data goes in whichever direction the transfer does, so here
            // the direction has to be told to us.
            if (dat_dir) n_up_fail   <= n_up_fail   + 32'd1;
            else         n_down_fail <= n_down_fail + 32'd1;
            if (run_r >= BURST_THRESH) n_burst    <= n_burst    + 32'd1;
            else                       n_isolated <= n_isolated + 32'd1;
            if (run_r != 8'hFF) run_r <= run_r + 8'd1;
          end else begin
            run_r <= 8'd0;
          end
        end
      end
    end
  end
endmodule

-- usb_crc_analyzer -- the two real USB CRCs, and the reason the count of
-- CRC failures is nearly useless while the DISTRIBUTION of them is the most
-- direct evidence about the physical layer you will ever get.
--
-- THE TWO POLYNOMIALS, AND WHAT EACH ONE COVERS
--
--     CRC5    x^5 + x^2 + 1                          poly 0x05
--             covers the 11-bit TOKEN field: 7-bit address + 4-bit
--             endpoint. Sent by the HOST, every single transaction.
--
--     CRC16   x^16 + x^15 + x^2 + 1                  poly 0x8005
--             covers the DATA payload. Sent by whoever has the data, so
--             either direction.
--
-- Both are initialised to all ones and both have their result complemented,
-- which is not decoration: it makes a codeword of all zeros -- the thing a
-- dead receiver produces -- fail, and it makes leading zeros in the data
-- change the result.
--
-- THE FIELD NAMES THE DIRECTION
--
-- A token is ALWAYS host-to-device. So:
--
--     CRC5 failures        the DOWNSTREAM half is damaged. Always.
--     CRC16 on IN data     the UPSTREAM half is damaged.
--     CRC16 on OUT data    the DOWNSTREAM half is damaged.
--     both halves          common mode: power, ground, the connector,
--                          or the cable as a whole.
--
-- A device reporting thousands of CRC16 failures on IN transfers and no
-- CRC5 failures at all has a perfectly good downstream path -- which rules
-- out half the usual suspects on the first reading of the counter.
--
-- AND THE CLUSTERING NAMES THE MECHANISM
--
--     scattered single failures   marginal signal. Thermal noise, an eye
--                                 that is closing, a bad margin.
--
--     failures in RUNS            something periodic. EMI from a switching
--                                 supply, a fan, a motor, a clock spur.
--
-- Same total, completely different thing to go and look at. So a failure is
-- counted BURST when the previous checked codeword also failed and ISOLATED
-- otherwise: a run of five is one isolated and four burst, and the ratio is
-- the measurement.
--
-- A RECEIVER CHECKS THE RESIDUAL, IT DOES NOT RECOMPUTE AND COMPARE
--
-- Feeding the WHOLE codeword -- data and the received CRC together --
-- through the same shift register leaves a CONSTANT, whatever the data was.
--
--     CRC5  residual = 0x0C     for all 2048 token values
--     CRC16 residual = 0x800D
--
-- Those constants are checked exhaustively by the testbench rather than
-- quoted, because a wrong residual constant produces a checker that passes
-- everything and nothing else in the system will notice.
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

package usb_crc_pkg is
  constant CRC5_INIT   : unsigned(4 downto 0)  := "11111";
  constant CRC5_POLY   : unsigned(4 downto 0)  := "00101";
  -- Named CRC5_RESIDUAL, not CRC5_RESID. VHDL identifiers are
  -- CASE-INSENSITIVE, so a constant called CRC5_RESID and the analyzer's
  -- output port called crc5_resid are the SAME NAME -- and inside the
  -- architecture the locally declared port wins. The error that produces
  -- points at the comparison, says "no matching operator =", and names two
  -- types neither of which is the one you declared.
  constant CRC5_RESIDUAL  : unsigned(4 downto 0)  := "01100";  -- 0x0C

  constant CRC16_INIT  : unsigned(15 downto 0) := x"FFFF";
  constant CRC16_POLY  : unsigned(15 downto 0) := x"8005";
  constant CRC16_RESIDUAL : unsigned(15 downto 0) := x"800D";

  constant V_CLEAN  : std_logic_vector(2 downto 0) := "000";
  constant V_DOWN   : std_logic_vector(2 downto 0) := "001";
  constant V_UP     : std_logic_vector(2 downto 0) := "010";
  constant V_COMMON : std_logic_vector(2 downto 0) := "011";

  -- One bit into the CRC5 shift register. Data goes in LSB first, which is
  -- the order it is sent on the wire; get this backwards and every one of
  -- the 2048 values is wrong.
  function crc5_step (c : unsigned(4 downto 0); b : std_logic)
    return unsigned;
  function crc5_of (d : unsigned(10 downto 0)) return unsigned;
  -- The RESIDUAL: the same register, fed the received CRC as well, MSB
  -- first -- the order it arrives in relative to the register's direction.
  function crc5_residual_of (d : unsigned(10 downto 0); r : unsigned(4 downto 0))
    return unsigned;

  function crc16_step (c : unsigned(15 downto 0); b : std_logic)
    return unsigned;
  function crc16_byte (c : unsigned(15 downto 0); b : std_logic_vector(7 downto 0))
    return unsigned;
  function crc16_absorb16 (c : unsigned(15 downto 0); r : unsigned(15 downto 0))
    return unsigned;
end package;

package body usb_crc_pkg is
  function crc5_step (c : unsigned(4 downto 0); b : std_logic)
    return unsigned is
    variable x : std_logic;
    variable t : unsigned(4 downto 0);
  begin
    x := b xor c(4);
    t := c(3 downto 0) & '0';
    if x = '1' then t := t xor CRC5_POLY; end if;
    return t;
  end function;

  function crc5_of (d : unsigned(10 downto 0)) return unsigned is
    variable c : unsigned(4 downto 0) := CRC5_INIT;
  begin
    for i in 0 to 10 loop
      c := crc5_step(c, d(i));
    end loop;
    return not c;
  end function;

  function crc5_residual_of (d : unsigned(10 downto 0); r : unsigned(4 downto 0))
    return unsigned is
    variable c : unsigned(4 downto 0) := CRC5_INIT;
  begin
    for i in 0 to 10 loop
      c := crc5_step(c, d(i));
    end loop;
    for i in 4 downto 0 loop
      c := crc5_step(c, r(i));
    end loop;
    return c;
  end function;

  function crc16_step (c : unsigned(15 downto 0); b : std_logic)
    return unsigned is
    variable x : std_logic;
    variable t : unsigned(15 downto 0);
  begin
    x := b xor c(15);
    t := c(14 downto 0) & '0';
    if x = '1' then t := t xor CRC16_POLY; end if;
    return t;
  end function;

  function crc16_byte (c : unsigned(15 downto 0); b : std_logic_vector(7 downto 0))
    return unsigned is
    variable t : unsigned(15 downto 0) := c;
  begin
    for i in 0 to 7 loop
      t := crc16_step(t, b(i));
    end loop;
    return t;
  end function;

  function crc16_absorb16 (c : unsigned(15 downto 0); r : unsigned(15 downto 0))
    return unsigned is
    variable t : unsigned(15 downto 0) := c;
  begin
    for i in 15 downto 0 loop
      t := crc16_step(t, r(i));
    end loop;
    return t;
  end function;
end package body;

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

entity usb_crc_analyzer is
  generic (
    BURST_MIN : integer := 2   -- a run of this length is a burst
  );
  port (
    clk       : in std_logic;
    rst_n     : in std_logic;

    tok_valid : in std_logic;
    tok_data  : in std_logic_vector(10 downto 0);
    tok_crc5  : in std_logic_vector(4 downto 0);

    dat_start : in std_logic;
    dat_valid : in std_logic;
    dat_byte  : in std_logic_vector(7 downto 0);
    dat_end   : in std_logic;
    dat_crc16 : in std_logic_vector(15 downto 0);
    dat_dir   : in std_logic;   -- 0 = OUT (downstream), 1 = IN (upstream)

    eot       : in std_logic;

    crc5_gen    : out std_logic_vector(4 downto 0);
    crc5_resid  : out std_logic_vector(4 downto 0);
    crc5_ok     : out std_logic;
    crc16_gen   : out std_logic_vector(15 downto 0);
    crc16_resid : out std_logic_vector(15 downto 0);
    crc16_ok    : out std_logic;

    fail_pulse  : out std_logic;
    fail_field  : out std_logic;   -- 0 = token (CRC5), 1 = data (CRC16)
    fail_run    : out std_logic_vector(7 downto 0);
    verdict     : out std_logic_vector(2 downto 0);
    bursty      : out std_logic;

    n_tok       : out unsigned(31 downto 0);
    n_tok_fail  : out unsigned(31 downto 0);
    n_dat       : out unsigned(31 downto 0);
    n_dat_fail  : out unsigned(31 downto 0);
    n_down_fail : out unsigned(31 downto 0);
    n_up_fail   : out unsigned(31 downto 0);
    n_burst     : out unsigned(31 downto 0);
    n_isolated  : out unsigned(31 downto 0)
  );
end entity;

architecture rtl of usb_crc_analyzer is
  constant BURST_THRESH : unsigned(7 downto 0) :=
    to_unsigned(BURST_MIN - 1, 8);

  signal c16_r  : unsigned(15 downto 0) := CRC16_INIT;
  signal run_r  : unsigned(7 downto 0)  := (others => '0');
  signal fp_r   : std_logic := '0';
  signal ff_r   : std_logic := '0';

  signal tok_c, tokf_c, dat_c, datf_c : unsigned(31 downto 0)
    := (others => '0');
  signal down_c, up_c, burst_c, iso_c : unsigned(31 downto 0)
    := (others => '0');

  -- Initialised at declaration. These feed concurrent comparisons that
  -- evaluate at time 0, before any driver has resolved them; left
  -- uninitialised they are all-U and numeric_std's "=" emits a metavalue
  -- warning on every single run. A warning that always fires is a warning
  -- nobody reads.
  signal t_gen, t_resid : unsigned(4 downto 0)  := (others => '0');
  signal t_ok           : std_logic := '0';
  signal d_resid        : unsigned(15 downto 0) := (others => '0');
  signal d_ok           : std_logic := '0';
begin
  -- ---- The token check is purely combinational: 11 bits, one cycle. ----
  t_gen   <= crc5_of(unsigned(tok_data));
  t_resid <= crc5_residual_of(unsigned(tok_data), unsigned(tok_crc5));
  t_ok    <= '1' when t_resid = CRC5_RESIDUAL else '0';

  crc5_gen   <= std_logic_vector(t_gen);
  crc5_resid <= std_logic_vector(t_resid);
  crc5_ok    <= t_ok;

  -- ---- The data check accumulates across the packet. ----
  d_resid <= crc16_absorb16(c16_r, unsigned(dat_crc16));
  d_ok    <= '1' when d_resid = CRC16_RESIDUAL else '0';

  crc16_gen   <= std_logic_vector(not c16_r);
  crc16_resid <= std_logic_vector(d_resid);
  crc16_ok    <= d_ok;

  fail_pulse <= fp_r;
  fail_field <= ff_r;
  fail_run   <= std_logic_vector(run_r);

  n_tok       <= tok_c;
  n_tok_fail  <= tokf_c;
  n_dat       <= dat_c;
  n_dat_fail  <= datf_c;
  n_down_fail <= down_c;
  n_up_fail   <= up_c;
  n_burst     <= burst_c;
  n_isolated  <= iso_c;

  -- ---- The verdict. ----
  --
  -- A ratio, not a count. "Two thousand CRC errors" says nothing; "every one
  -- of them upstream" says the downstream half is fine and halves the search
  -- on the first reading.
  verdict <= V_CLEAN  when (down_c = 0) and (up_c = 0) else
             V_DOWN   when down_c > (up_c sll 1) else
             V_UP     when up_c > (down_c sll 1) else
             V_COMMON;

  -- Most failures in runs -> something periodic. Scattered -> marginal
  -- signal. Same total, different thing to go and look at.
  bursty <= '1' when burst_c > iso_c else '0';

  process (clk, rst_n)
  begin
    if rst_n = '0' then
      c16_r   <= CRC16_INIT;
      run_r   <= (others => '0');
      fp_r    <= '0';
      ff_r    <= '0';
      tok_c   <= (others => '0');
      tokf_c  <= (others => '0');
      dat_c   <= (others => '0');
      datf_c  <= (others => '0');
      down_c  <= (others => '0');
      up_c    <= (others => '0');
      burst_c <= (others => '0');
      iso_c   <= (others => '0');
    elsif rising_edge(clk) then
      fp_r <= '0';

      if eot = '1' then
        -- Nothing: the counters are the report.
        null;
      else
        -- ---- the data packet's shift register ----
        --
        -- dat_start and dat_valid can be asserted together, so the reset to
        -- CRC16_INIT has to happen BEFORE the byte is absorbed rather than
        -- instead of it. Written the other way round, the first byte of
        -- every packet is silently dropped and the CRC is wrong for every
        -- packet in exactly the same way -- which looks like a polynomial
        -- error and is not.
        if dat_start = '1' and dat_valid = '1' then
          c16_r <= crc16_byte(CRC16_INIT, dat_byte);
        elsif dat_start = '1' then
          c16_r <= CRC16_INIT;
        elsif dat_valid = '1' then
          c16_r <= crc16_byte(c16_r, dat_byte);
        end if;

        if tok_valid = '1' then
          tok_c <= tok_c + 1;
          if t_ok = '0' then
            fp_r   <= '1';
            ff_r   <= '0';
            tokf_c <= tokf_c + 1;
            -- A TOKEN is always host-to-device. There is no ambiguity to
            -- resolve and no direction input to get wrong.
            down_c <= down_c + 1;
            if run_r >= BURST_THRESH then
              burst_c <= burst_c + 1;
            else
              iso_c <= iso_c + 1;
            end if;
            if run_r /= x"FF" then run_r <= run_r + 1; end if;
          else
            run_r <= (others => '0');
          end if;
        elsif dat_end = '1' then
          dat_c <= dat_c + 1;
          if d_ok = '0' then
            fp_r   <= '1';
            ff_r   <= '1';
            datf_c <= datf_c + 1;
            -- Data goes whichever way the transfer does, so here the
            -- direction has to be told to us.
            if dat_dir = '1' then
              up_c <= up_c + 1;
            else
              down_c <= down_c + 1;
            end if;
            if run_r >= BURST_THRESH then
              burst_c <= burst_c + 1;
            else
              iso_c <= iso_c + 1;
            end if;
            if run_r /= x"FF" then run_r <= run_r + 1; end if;
          else
            run_r <= (others => '0');
          end if;
        end if;
      end if;
    end if;
  end process;
end architecture;

`timescale 1ns/1ps
// Testbench for usb_crc_analyzer.
//
// THE ORACLE IS A BIT-SERIAL REFERENCE, WRITTEN INDEPENDENTLY
//
// A CRC is the one block where "the model agrees with the design" is worth
// almost nothing, because both were probably derived from the same
// half-remembered table. So the reference here is anchored to something
// outside both: the USB 2.0 specification's own worked example --
//
//     address 0x15, endpoint 0xE   ->   CRC5 = 0x17
//
// -- which is checked first, before anything else runs. If that one value
// is wrong, every other number in this file is a consistent lie.
//
// THE EXHAUSTIVE CLAIMS
//
//   1. all 2048 token values: the generated CRC5 matches the reference
//   2. all 2048 token values: the residual of the correct codeword is the
//      SAME CONSTANT (this is what makes residual checking legal at all)
//   3. all 2048 x 16 = 32768 single-bit errors are DETECTED
//   4. all 2048 x 120 = 245760 double-bit errors are DETECTED
//
// The last two are the properties the polynomial was chosen for, and they
// are the only ones that matter: a CRC that computes a repeatable value and
// detects nothing is a checksum with extra steps.
module tb_ca_v;

  localparam integer BURST_MIN = 2;

  localparam [4:0]  CRC5_RESID  = 5'h0C;
  localparam [15:0] CRC16_RESID = 16'h800D;

  localparam [2:0] V_CLEAN = 3'd0, V_DOWN = 3'd1, V_UP = 3'd2, V_COMMON = 3'd3;

  reg         clk = 1'b0, rst_n = 1'b0;
  reg         tok_valid = 1'b0;
  reg  [10:0] tok_data = 11'd0;
  reg  [4:0]  tok_crc5 = 5'd0;
  reg         dat_start = 1'b0, dat_valid = 1'b0, dat_end = 1'b0;
  reg  [7:0]  dat_byte = 8'd0;
  reg  [15:0] dat_crc16 = 16'd0;
  reg         dat_dir = 1'b0;
  reg         eot = 1'b0;

  wire [4:0]  crc5_gen, crc5_resid;
  wire        crc5_ok;
  wire [15:0] crc16_gen, crc16_resid;
  wire        crc16_ok;
  wire        fail_pulse, fail_field, bursty;
  wire [7:0]  fail_run;
  wire [2:0]  verdict;
  wire [31:0] n_tok, n_tok_fail, n_dat, n_dat_fail;
  wire [31:0] n_down_fail, n_up_fail, n_burst, n_isolated;

  usb_crc_analyzer #(.BURST_MIN(BURST_MIN)) dut (
    .clk(clk), .rst_n(rst_n),
    .tok_valid(tok_valid), .tok_data(tok_data), .tok_crc5(tok_crc5),
    .dat_start(dat_start), .dat_valid(dat_valid), .dat_byte(dat_byte),
    .dat_end(dat_end), .dat_crc16(dat_crc16), .dat_dir(dat_dir),
    .eot(eot),
    .crc5_gen(crc5_gen), .crc5_resid(crc5_resid), .crc5_ok(crc5_ok),
    .crc16_gen(crc16_gen), .crc16_resid(crc16_resid), .crc16_ok(crc16_ok),
    .fail_pulse(fail_pulse), .fail_field(fail_field), .fail_run(fail_run),
    .verdict(verdict), .bursty(bursty),
    .n_tok(n_tok), .n_tok_fail(n_tok_fail),
    .n_dat(n_dat), .n_dat_fail(n_dat_fail),
    .n_down_fail(n_down_fail), .n_up_fail(n_up_fail),
    .n_burst(n_burst), .n_isolated(n_isolated)
  );

  always #5 clk = ~clk;

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

  // ---- a shadow model of the CLASSIFICATION ----
  //
  // The phases below prove the CRC arithmetic exhaustively, which is the
  // hard part and not the whole part: the block also has to decide which
  // HALF of the link a failure belongs to and whether it arrived in a run.
  // Those two decisions were originally checked only by the six directed
  // assertions in phases 5 to 7 -- so the mutations that broke them scored
  // 3 and 2 against scores in the thousands for everything else.
  //
  // A mutation that survives on a handful of checks has not really been
  // killed; it has been cornered. So every event now predicts all of it.
  integer e_down, e_up, e_burst, e_iso, e_run, e_tokfail, e_datfail;

  task ck;
    input [255:0] nm;
    input [31:0]  got, exp;
    begin
      checks = checks + 1;
      if (got !== exp) begin
        errors = errors + 1;
        if (errors < 25)
          $display("FAIL t=%0t step=%0d %0s got=%0h exp=%0h",
                   $time, steps, nm, got, exp);
      end
    end
  endtask

  // ---------------- the independent bit-serial reference ----------------
  //
  // Written as a loop over single bits rather than as a table or an
  // unrolled XOR tree, because the loop IS the definition of the
  // polynomial division and the other two forms are optimisations of it
  // that have to be checked against something.
  function [4:0] ref_crc5;
    input [10:0] d;
    reg [4:0] c;
    reg       x;
    integer   i;
    begin
      c = 5'h1F;
      for (i = 0; i < 11; i = i + 1) begin
        x = d[i] ^ c[4];
        c = {c[3:0], 1'b0};
        if (x) c = c ^ 5'h05;
      end
      ref_crc5 = ~c;
    end
  endfunction

  function [4:0] ref_crc5_resid;
    input [10:0] d;
    input [4:0]  r;
    reg [4:0] c;
    reg       x;
    integer   i;
    begin
      c = 5'h1F;
      for (i = 0; i < 11; i = i + 1) begin
        x = d[i] ^ c[4];
        c = {c[3:0], 1'b0};
        if (x) c = c ^ 5'h05;
      end
      for (i = 4; i >= 0; i = i - 1) begin
        x = r[i] ^ c[4];
        c = {c[3:0], 1'b0};
        if (x) c = c ^ 5'h05;
      end
      ref_crc5_resid = c;
    end
  endfunction

  function [15:0] ref_crc16_byte;
    input [15:0] c0;
    input [7:0]  b;
    reg [15:0] c;
    reg        x;
    integer    i;
    begin
      c = c0;
      for (i = 0; i < 8; i = i + 1) begin
        x = b[i] ^ c[15];
        c = {c[14:0], 1'b0};
        if (x) c = c ^ 16'h8005;
      end
      ref_crc16_byte = c;
    end
  endfunction

  // Called on the cycle the design consumes an event. `ok` is computed from
  // the reference, never read back from the design.
  task classify; input ok; input is_data; input dir;
    begin
      if (!ok) begin
        if (is_data) begin
          e_datfail = e_datfail + 1;
          if (dir) e_up = e_up + 1; else e_down = e_down + 1;
        end else begin
          e_tokfail = e_tokfail + 1;
          // A token is ALWAYS host-to-device. The model asserts that as a
          // fact about the protocol rather than reading a direction input.
          e_down = e_down + 1;
        end
        if (e_run >= 1) e_burst = e_burst + 1;
        else            e_iso   = e_iso   + 1;
        if (e_run != 255) e_run = e_run + 1;
      end else begin
        e_run = 0;
      end
      ck("n_tok_fail",  n_tok_fail,  e_tokfail);
      ck("n_dat_fail",  n_dat_fail,  e_datfail);
      ck("n_down_fail", n_down_fail, e_down);
      ck("n_up_fail",   n_up_fail,   e_up);
      ck("n_burst",     n_burst,     e_burst);
      ck("n_isolated",  n_isolated,  e_iso);
      ck("fail_run",    {24'd0, fail_run}, e_run);
      // Every failure is exactly one of burst or isolated, and exactly one
      // of upstream or downstream. A report that cannot be decomposed
      // cannot be trusted (chapter 23.4).
      ck("burst+iso",   n_burst + n_isolated,  n_tok_fail + n_dat_fail);
      ck("up+down",     n_down_fail + n_up_fail, n_tok_fail + n_dat_fail);
    end
  endtask

  task clear_expect;
    begin
      e_down = 0; e_up = 0; e_burst = 0; e_iso = 0; e_run = 0;
      e_tokfail = 0; e_datfail = 0;
    end
  endtask

  // ---------------- drivers ----------------
  task tok; input [10:0] d; input [4:0] c;
    begin
      tok_valid = 1'b1; tok_data = d; tok_crc5 = c;
      dat_start = 1'b0; dat_valid = 1'b0; dat_end = 1'b0; eot = 1'b0;
      @(posedge clk); #1;
      steps = steps + 1;
      classify(ref_crc5_resid(d, c) == CRC5_RESID, 1'b0, 1'b0);
      tok_valid = 1'b0;
    end
  endtask

  task idle;
    begin
      tok_valid = 1'b0; dat_start = 1'b0; dat_valid = 1'b0; dat_end = 1'b0;
      eot = 1'b0;
      @(posedge clk); #1;
      steps = steps + 1;
    end
  endtask

  // A whole data packet: start, n bytes, end. The packet's CRC16 is passed
  // in rather than computed here, so a test can hand over a WRONG one.
  reg [7:0] pay [0:63];
  task datpkt; input integer n; input [15:0] c16; input dir;
    integer j;
    begin
      dat_dir = dir;
      tok_valid = 1'b0; eot = 1'b0;
      if (n == 0) begin
        // A zero-length packet is a real packet with a real CRC16. It is
        // also the one length nobody tests.
        dat_start = 1'b1; dat_valid = 1'b0; dat_end = 1'b0;
        @(posedge clk); #1; steps = steps + 1;
      end else begin
        for (j = 0; j < n; j = j + 1) begin
          dat_start = (j == 0);
          dat_valid = 1'b1;
          dat_byte  = pay[j];
          dat_end   = 1'b0;
          @(posedge clk); #1; steps = steps + 1;
        end
      end
      dat_start = 1'b0; dat_valid = 1'b0;
      dat_end   = 1'b1; dat_crc16 = c16;
      @(posedge clk); #1; steps = steps + 1;
      classify(c16 == pay_crc16(n), 1'b1, dir);
      dat_end = 1'b0;
    end
  endtask

  function [15:0] pay_crc16; input integer n;
    reg [15:0] c;
    integer j;
    begin
      c = 16'hFFFF;
      for (j = 0; j < n; j = j + 1) c = ref_crc16_byte(c, pay[j]);
      pay_crc16 = ~c;
    end
  endfunction

  integer i, j, bi, bj, n, w;
  integer n_single, n_double, n_miss_s, n_miss_d;
  integer base_burst, base_iso, base_tf, base_df, base_up, base_down;
  reg [15:0] cw, bad;
  reg [4:0]  g;
  reg [15:0] c16;
  reg [0:0]  seen_resid [0:31];
  integer    n_resid;

  initial begin
    for (i = 0; i < 32; i = i + 1) seen_resid[i] = 1'b0;
    clear_expect;

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

    // ================= PHASE 0 -- the specification's own example ========
    //
    // Before anything else. Address 0x15, endpoint 0xE, CRC5 = 0x17, from
    // the USB 2.0 specification. Every other number in this file depends on
    // this one being right, and nothing inside this testbench could tell
    // you if it were not.
    tok(11'h715, ref_crc5(11'h715));
    ck("spec example CRC5", {27'd0, crc5_gen}, 32'h17);
    ck("spec example ref",  {27'd0, ref_crc5(11'h715)}, 32'h17);
    ck("spec example ok",   {31'd0, crc5_ok}, 32'd1);

    // ================= PHASE 1 -- all 2048 tokens, generated and checked ==
    n_resid = 0;
    for (i = 0; i < 2048; i = i + 1) begin
      g = ref_crc5(i[10:0]);
      tok(i[10:0], g);
      ck("crc5_gen",   {27'd0, crc5_gen},   {27'd0, g});
      ck("crc5_ok",    {31'd0, crc5_ok},    32'd1);
      ck("crc5_resid", {27'd0, crc5_resid}, {27'd0, CRC5_RESID});
      // ...and record the residual actually observed, so that the claim
      // "it is a constant" is MEASURED rather than assumed.
      if (!seen_resid[crc5_resid]) begin
        seen_resid[crc5_resid] = 1'b1;
        n_resid = n_resid + 1;
      end
    end
    if (n_resid != 1) begin
      errors = errors + 1;
      $display("FAIL the CRC5 residual is not a constant: %0d values seen",
               n_resid);
    end

    // ================= PHASE 2 -- every single-bit error, all 2048 =======
    //
    // 2048 x 16 = 32768 injections. The polynomial detects all of them or
    // it is the wrong polynomial.
    n_single = 0; n_miss_s = 0;
    base_tf = n_tok_fail;
    for (i = 0; i < 2048; i = i + 1) begin
      // ---- A CORRECT codeword first, every time. ----
      //
      // Without this the phase drives tens of thousands of CONSECUTIVE
      // failures and never once follows a failure with a success -- which
      // is the only transition the run-reset logic has. The mutation that
      // deletes that reset scored 51 against scores in the millions, not
      // because the check was weak but because the stimulus never produced
      // the situation it checks.
      tok(i[10:0], ref_crc5(i[10:0]));
      cw = {5'd0, i[10:0]} | ({11'd0, ref_crc5(i[10:0])} << 11);
      for (bi = 0; bi < 16; bi = bi + 1) begin
        bad = cw ^ (16'd1 << bi);
        tok(bad[10:0], bad[15:11]);
        n_single = n_single + 1;
        checks   = checks + 1;
        if (crc5_ok) begin
          n_miss_s = n_miss_s + 1;
          if (n_miss_s < 5)
            $display("FAIL single-bit error UNDETECTED token=%0h bit=%0d",
                     i, bi);
        end
      end
    end
    if (n_miss_s != 0) errors = errors + 1;
    // Every one of them is also a reported downstream failure, because a
    // token is always host-to-device.
    ck("single-bit failures counted", n_tok_fail - base_tf, n_single);

    // ================= PHASE 3 -- every double-bit error, all 2048 =======
    //
    // 2048 x 120 = 245760 injections. This is the property that separates a
    // CRC from a parity bit.
    n_double = 0; n_miss_d = 0;
    for (i = 0; i < 2048; i = i + 1) begin
      // ...and again here, for the same reason.
      tok(i[10:0], ref_crc5(i[10:0]));
      cw = {5'd0, i[10:0]} | ({11'd0, ref_crc5(i[10:0])} << 11);
      for (bi = 0; bi < 16; bi = bi + 1)
        for (bj = bi + 1; bj < 16; bj = bj + 1) begin
          bad = cw ^ (16'd1 << bi) ^ (16'd1 << bj);
          tok(bad[10:0], bad[15:11]);
          n_double = n_double + 1;
          checks   = checks + 1;
          if (crc5_ok) begin
            n_miss_d = n_miss_d + 1;
            if (n_miss_d < 5)
              $display("FAIL double-bit error UNDETECTED token=%0h %0d,%0d",
                       i, bi, bj);
          end
        end
    end
    if (n_miss_d != 0) errors = errors + 1;

    // ================= PHASE 4 -- CRC16 over real packets ================
    //
    // Including the zero-length packet, which is a real packet with a real
    // CRC16 and the one length nobody tests.
    for (n = 0; n <= 16; n = n + 1) begin
      for (j = 0; j < n; j = j + 1) pay[j] = ($unsigned($random) % 256);
      c16 = pay_crc16(n);
      idle;
      datpkt(n, c16, 1'b0);
      ck("crc16_ok",    {31'd0, crc16_ok},    32'd1);
      ck("crc16_gen",   {16'd0, crc16_gen},   {16'd0, c16});
      ck("crc16_resid", {16'd0, crc16_resid}, {16'd0, CRC16_RESID});
    end

    // ================= PHASE 5 -- CRC16 single-bit detection =============
    //
    // Every bit of an 8-byte payload plus its 16-bit CRC: 80 positions,
    // over 64 different payloads. Not exhaustive over payloads -- 2^64 is
    // not a testbench -- but exhaustive over ERROR POSITION, which is the
    // axis the polynomial makes a promise about.
    base_df = n_dat_fail;
    n_single = 0;
    for (i = 0; i < 64; i = i + 1) begin
      for (j = 0; j < 8; j = j + 1) pay[j] = ($unsigned($random) % 256);
      c16 = pay_crc16(8);
      for (bi = 0; bi < 80; bi = bi + 1) begin
        // flip one bit: in the payload if bi < 64, in the CRC otherwise
        if (bi < 64) pay[bi/8] = pay[bi/8] ^ (8'd1 << (bi % 8));
        idle;
        datpkt(8, (bi >= 64) ? (c16 ^ (16'd1 << (bi - 64))) : c16, 1'b1);
        n_single = n_single + 1;
        checks   = checks + 1;
        if (crc16_ok) begin
          errors = errors + 1;
          if (errors < 25)
            $display("FAIL CRC16 single-bit error UNDETECTED payload=%0d bit=%0d",
                     i, bi);
        end
        if (bi < 64) pay[bi/8] = pay[bi/8] ^ (8'd1 << (bi % 8));
      end
    end
    ck("crc16 single-bit failures counted", n_dat_fail - base_df, n_single);
    // ...and every one of them was IN data, so every one is UPSTREAM. This
    // is the check that makes the verdict mean something: the direction is
    // not inferred from the failure, it is carried by the transaction.
    ck("all upstream", n_up_fail, n_single);

    // ================= PHASE 6 -- burst versus isolated ==================
    //
    // The measurement that separates marginal signal from interference. A
    // run of five failures is ONE isolated and FOUR burst; five failures
    // each separated by a good one are FIVE isolated.
    idle;
    tok(11'h123, ref_crc5(11'h123));     // a good one, to clear the run
    base_burst = n_burst; base_iso = n_isolated;
    for (i = 0; i < 5; i = i + 1) tok(11'h123, ref_crc5(11'h123) ^ 5'h01);
    if (n_burst - base_burst != 4 || n_isolated - base_iso != 1) begin
      errors = errors + 1;
      $display("FAIL run of 5: burst=%0d isolated=%0d expected 4 and 1",
               n_burst - base_burst, n_isolated - base_iso);
    end
    tok(11'h123, ref_crc5(11'h123));     // clear the run
    base_burst = n_burst; base_iso = n_isolated;
    for (i = 0; i < 5; i = i + 1) begin
      tok(11'h123, ref_crc5(11'h123) ^ 5'h01);
      tok(11'h123, ref_crc5(11'h123));
    end
    if (n_burst - base_burst != 0 || n_isolated - base_iso != 5) begin
      errors = errors + 1;
      $display("FAIL 5 separated: burst=%0d isolated=%0d expected 0 and 5",
               n_burst - base_burst, n_isolated - base_iso);
    end

    // ================= PHASE 7 -- the verdict ============================
    //
    // Three runs from a clean reset, each with the failures on one side of
    // the link, and the verdict has to name the right half.
    //
    // Reset between them, because a verdict is a RATIO over accumulated
    // counters: computed on top of the previous phase's totals it is a
    // ratio of the wrong things (chapter 25.4 phase 4, in a new costume).
    reset_dut;
    for (i = 0; i < 40; i = i + 1) tok(11'h055, ref_crc5(11'h055) ^ 5'h03);
    ck("verdict downstream", {29'd0, verdict}, {29'd0, V_DOWN});

    reset_dut;
    for (j = 0; j < 8; j = j + 1) pay[j] = j[7:0];
    c16 = pay_crc16(8);
    for (i = 0; i < 40; i = i + 1) begin
      idle;
      datpkt(8, c16 ^ 16'h0001, 1'b1);       // IN data, wrong CRC
    end
    ck("verdict upstream", {29'd0, verdict}, {29'd0, V_UP});

    reset_dut;
    for (i = 0; i < 20; i = i + 1) begin
      tok(11'h055, ref_crc5(11'h055) ^ 5'h03);
      idle;
      datpkt(8, c16 ^ 16'h0001, 1'b1);
    end
    ck("verdict common", {29'd0, verdict}, {29'd0, V_COMMON});

    reset_dut;
    for (i = 0; i < 20; i = i + 1) tok(11'h055, ref_crc5(11'h055));
    ck("verdict clean", {29'd0, verdict}, {29'd0, V_CLEAN});

    $display("steps=%0d checks=%0d errors=%0d", steps, checks, errors);
    $display("single-bit injections=%0d undetected=%0d", 2048*16, n_miss_s);
    $display("double-bit injections=%0d undetected=%0d", 2048*120, n_miss_d);
    $display("crc5 residual values observed=%0d (expected 1)", n_resid);
    $display("%0s: %0d errors in %0d checks",
             (errors == 0) ? "PASS" : "FAIL", errors, checks);
    $finish;
  end

  task reset_dut;
    begin
      tok_valid = 1'b0; dat_start = 1'b0; dat_valid = 1'b0; dat_end = 1'b0;
      rst_n = 1'b0;
      @(posedge clk); #1;
      rst_n = 1'b1;
      @(negedge clk);
      // The DUT's counters went to zero, so the expectations must too --
      // otherwise every check after the first reset fails for a reason that
      // has nothing to do with the design.
      clear_expect;
    end
  endtask
endmodule

`timescale 1ns/1ps
// Testbench for usb_crc_analyzer.
//
// THE ORACLE IS A BIT-SERIAL REFERENCE, WRITTEN INDEPENDENTLY
//
// A CRC is the one block where "the model agrees with the design" is worth
// almost nothing, because both were probably derived from the same
// half-remembered table. So the reference here is anchored to something
// outside both: the USB 2.0 specification's own worked example --
//
//     address 0x15, endpoint 0xE   ->   CRC5 = 0x17
//
// -- which is checked first, before anything else runs. If that one value
// is wrong, every other number in this file is a consistent lie.
//
// THE EXHAUSTIVE CLAIMS
//
//   1. all 2048 token values: the generated CRC5 matches the reference
//   2. all 2048 token values: the residual of the correct codeword is the
//      SAME CONSTANT (this is what makes residual checking legal at all)
//   3. all 2048 x 16 = 32768 single-bit errors are DETECTED
//   4. all 2048 x 120 = 245760 double-bit errors are DETECTED
//
// The last two are the properties the polynomial was chosen for, and they
// are the only ones that matter: a CRC that computes a repeatable value and
// detects nothing is a checksum with extra steps.
module tb_ca_sv;
  import usb_crc_pkg::*;

  localparam int BURST_MIN = 2;

  localparam [4:0]  CRC5_RESID  = 5'h0C;
  localparam [15:0] CRC16_RESID = 16'h800D;

  logic       clk = 1'b0, rst_n = 1'b0;
  logic       tok_valid = 1'b0;
  logic [10:0] tok_data = 11'd0;
  logic [4:0]  tok_crc5 = 5'd0;
  logic       dat_start = 1'b0, dat_valid = 1'b0, dat_end = 1'b0;
  logic [7:0]  dat_byte = 8'd0;
  logic [15:0] dat_crc16 = 16'd0;
  logic       dat_dir = 1'b0;
  logic       eot = 1'b0;

  logic [4:0]  crc5_gen, crc5_resid;
  logic        crc5_ok;
  logic [15:0] crc16_gen, crc16_resid;
  logic        crc16_ok;
  logic        fail_pulse, bursty;
  field_e      fail_field;
  logic [7:0]  fail_run;
  verdict_e    verdict;
  logic [31:0] n_tok, n_tok_fail, n_dat, n_dat_fail;
  logic [31:0] n_down_fail, n_up_fail, n_burst, n_isolated;

  usb_crc_analyzer #(.BURST_MIN(BURST_MIN)) dut (
    .clk(clk), .rst_n(rst_n),
    .tok_valid(tok_valid), .tok_data(tok_data), .tok_crc5(tok_crc5),
    .dat_start(dat_start), .dat_valid(dat_valid), .dat_byte(dat_byte),
    .dat_end(dat_end), .dat_crc16(dat_crc16), .dat_dir(dat_dir),
    .eot(eot),
    .crc5_gen(crc5_gen), .crc5_resid(crc5_resid), .crc5_ok(crc5_ok),
    .crc16_gen(crc16_gen), .crc16_resid(crc16_resid), .crc16_ok(crc16_ok),
    .fail_pulse(fail_pulse), .fail_field(fail_field), .fail_run(fail_run),
    .verdict(verdict), .bursty(bursty),
    .n_tok(n_tok), .n_tok_fail(n_tok_fail),
    .n_dat(n_dat), .n_dat_fail(n_dat_fail),
    .n_down_fail(n_down_fail), .n_up_fail(n_up_fail),
    .n_burst(n_burst), .n_isolated(n_isolated)
  );

  always #5 clk = ~clk;

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

  // ---- a shadow model of the CLASSIFICATION ----
  //
  // The phases below prove the CRC arithmetic exhaustively, which is the
  // hard part and not the whole part: the block also has to decide which
  // HALF of the link a failure belongs to and whether it arrived in a run.
  // Those two decisions were originally checked only by the six directed
  // assertions in phases 5 to 7 -- so the mutations that broke them scored
  // 3 and 2 against scores in the thousands for everything else.
  //
  // A mutation that survives on a handful of checks has not really been
  // killed; it has been cornered. So every event now predicts all of it.
  int e_down, e_up, e_burst, e_iso, e_run, e_tokfail, e_datfail;

  task ck;
    input [255:0] nm;
    input [31:0]  got, exp;
    begin
      checks = checks + 1;
      if (got !== exp) begin
        errors = errors + 1;
        if (errors < 25)
          $display("FAIL t=%0t step=%0d %0s got=%0h exp=%0h",
                   $time, steps, nm, got, exp);
      end
    end
  endtask

  // ---------------- the independent bit-serial reference ----------------
  //
  // Written as a loop over single bits rather than as a table or an
  // unrolled XOR tree, because the loop IS the definition of the
  // polynomial division and the other two forms are optimisations of it
  // that have to be checked against something.
  function automatic logic [4:0] ref_crc5(input logic [10:0] d);
    logic [4:0] c;
    logic       x;
    int         i;
    begin
      c = 5'h1F;
      for (i = 0; i < 11; i = i + 1) begin
        x = d[i] ^ c[4];
        c = {c[3:0], 1'b0};
        if (x) c = c ^ 5'h05;
      end
      ref_crc5 = ~c;
    end
  endfunction

  function automatic logic [4:0] ref_crc5_resid(input logic [10:0] d,
                                               input logic [4:0]  r);
    logic [4:0] c;
    logic       x;
    int         i;
    begin
      c = 5'h1F;
      for (i = 0; i < 11; i = i + 1) begin
        x = d[i] ^ c[4];
        c = {c[3:0], 1'b0};
        if (x) c = c ^ 5'h05;
      end
      for (i = 4; i >= 0; i = i - 1) begin
        x = r[i] ^ c[4];
        c = {c[3:0], 1'b0};
        if (x) c = c ^ 5'h05;
      end
      ref_crc5_resid = c;
    end
  endfunction

  function automatic logic [15:0] ref_crc16_byte(input logic [15:0] c0,
                                                input logic [7:0]  b);
    logic [15:0] c;
    logic        x;
    int          i;
    begin
      c = c0;
      for (i = 0; i < 8; i = i + 1) begin
        x = b[i] ^ c[15];
        c = {c[14:0], 1'b0};
        if (x) c = c ^ 16'h8005;
      end
      ref_crc16_byte = c;
    end
  endfunction

  // Called on the cycle the design consumes an event. `ok` is computed from
  // the reference, never read back from the design.
  task automatic classify(logic ok, logic is_data, logic dir);
    begin
      if (!ok) begin
        if (is_data) begin
          e_datfail = e_datfail + 1;
          if (dir) e_up = e_up + 1; else e_down = e_down + 1;
        end else begin
          e_tokfail = e_tokfail + 1;
          // A token is ALWAYS host-to-device. The model asserts that as a
          // fact about the protocol rather than reading a direction input.
          e_down = e_down + 1;
        end
        if (e_run >= 1) e_burst = e_burst + 1;
        else            e_iso   = e_iso   + 1;
        if (e_run != 255) e_run = e_run + 1;
      end else begin
        e_run = 0;
      end
      ck("n_tok_fail",  n_tok_fail,  e_tokfail);
      ck("n_dat_fail",  n_dat_fail,  e_datfail);
      ck("n_down_fail", n_down_fail, e_down);
      ck("n_up_fail",   n_up_fail,   e_up);
      ck("n_burst",     n_burst,     e_burst);
      ck("n_isolated",  n_isolated,  e_iso);
      ck("fail_run",    fail_run, e_run);
      // Every failure is exactly one of burst or isolated, and exactly one
      // of upstream or downstream. A report that cannot be decomposed
      // cannot be trusted (chapter 23.4).
      ck("burst+iso",   n_burst + n_isolated,  n_tok_fail + n_dat_fail);
      ck("up+down",     n_down_fail + n_up_fail, n_tok_fail + n_dat_fail);
    end
  endtask

  task automatic clear_expect;
    begin
      e_down = 0; e_up = 0; e_burst = 0; e_iso = 0; e_run = 0;
      e_tokfail = 0; e_datfail = 0;
    end
  endtask

  // ---------------- drivers ----------------
  task automatic tok(logic [10:0] d, logic [4:0] c);
    begin
      tok_valid = 1'b1; tok_data = d; tok_crc5 = c;
      dat_start = 1'b0; dat_valid = 1'b0; dat_end = 1'b0; eot = 1'b0;
      @(posedge clk); #1;
      steps = steps + 1;
      classify(ref_crc5_resid(d, c) == CRC5_RESID, 1'b0, 1'b0);
      tok_valid = 1'b0;
    end
  endtask

  task automatic idle;
    begin
      tok_valid = 1'b0; dat_start = 1'b0; dat_valid = 1'b0; dat_end = 1'b0;
      eot = 1'b0;
      @(posedge clk); #1;
      steps = steps + 1;
    end
  endtask

  // A whole data packet: start, n bytes, end. The packet's CRC16 is passed
  // in rather than computed here, so a test can hand over a WRONG one.
  logic [7:0] pay [0:63];
  task automatic datpkt(int n, logic [15:0] c16, logic dir);
    int j;
    begin
      dat_dir = dir;
      tok_valid = 1'b0; eot = 1'b0;
      if (n == 0) begin
        // A zero-length packet is a real packet with a real CRC16. It is
        // also the one length nobody tests.
        dat_start = 1'b1; dat_valid = 1'b0; dat_end = 1'b0;
        @(posedge clk); #1; steps = steps + 1;
      end else begin
        for (j = 0; j < n; j = j + 1) begin
          dat_start = (j == 0);
          dat_valid = 1'b1;
          dat_byte  = pay[j];
          dat_end   = 1'b0;
          @(posedge clk); #1; steps = steps + 1;
        end
      end
      dat_start = 1'b0; dat_valid = 1'b0;
      dat_end   = 1'b1; dat_crc16 = c16;
      @(posedge clk); #1; steps = steps + 1;
      classify(c16 == pay_crc16(n), 1'b1, dir);
      dat_end = 1'b0;
    end
  endtask

  function automatic logic [15:0] pay_crc16(input int n);
    logic [15:0] c;
    int j;
    begin
      c = 16'hFFFF;
      for (j = 0; j < n; j = j + 1) c = ref_crc16_byte(c, pay[j]);
      pay_crc16 = ~c;
    end
  endfunction

  int i, j, bi, bj, n, w;
  int n_single, n_double, n_miss_s, n_miss_d;
  int base_burst, base_iso, base_tf, base_df, base_up, base_down;
  logic [15:0] cw, bad;
  logic [4:0]  g;
  logic [15:0] c16;
  bit          seen_resid [32];
  int          n_resid;

  initial begin
    foreach (seen_resid[q]) seen_resid[q] = 1'b0;
    clear_expect;

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

    // ================= PHASE 0 -- the specification's own example ========
    //
    // Before anything else. Address 0x15, endpoint 0xE, CRC5 = 0x17, from
    // the USB 2.0 specification. Every other number in this file depends on
    // this one being right, and nothing inside this testbench could tell
    // you if it were not.
    tok(11'h715, ref_crc5(11'h715));
    ck("spec example CRC5", crc5_gen, 32'h17);
    ck("spec example ref",  ref_crc5(11'h715), 32'h17);
    ck("spec example ok",   crc5_ok, 32'd1);

    // ================= PHASE 1 -- all 2048 tokens, generated and checked ==
    n_resid = 0;
    for (i = 0; i < 2048; i = i + 1) begin
      g = ref_crc5(i[10:0]);
      tok(i[10:0], g);
      ck("crc5_gen",   crc5_gen, g);
      ck("crc5_ok",    crc5_ok, 32'd1);
      ck("crc5_resid", crc5_resid, CRC5_RESID);
      // ...and record the residual actually observed, so that the claim
      // "it is a constant" is MEASURED rather than assumed.
      if (!seen_resid[crc5_resid]) begin
        seen_resid[crc5_resid] = 1'b1;
        n_resid = n_resid + 1;
      end
    end
    if (n_resid != 1) begin
      errors = errors + 1;
      $display("FAIL the CRC5 residual is not a constant: %0d values seen",
               n_resid);
    end

    // ================= PHASE 2 -- every single-bit error, all 2048 =======
    //
    // 2048 x 16 = 32768 injections. The polynomial detects all of them or
    // it is the wrong polynomial.
    n_single = 0; n_miss_s = 0;
    base_tf = n_tok_fail;
    for (i = 0; i < 2048; i = i + 1) begin
      // ---- A CORRECT codeword first, every time. ----
      //
      // Without this the phase drives tens of thousands of CONSECUTIVE
      // failures and never once follows a failure with a success -- which
      // is the only transition the run-reset logic has. The mutation that
      // deletes that reset scored 51 against scores in the millions, not
      // because the check was weak but because the stimulus never produced
      // the situation it checks.
      tok(i[10:0], ref_crc5(i[10:0]));
      cw = {5'd0, i[10:0]} | ({11'd0, ref_crc5(i[10:0])} << 11);
      for (bi = 0; bi < 16; bi = bi + 1) begin
        bad = cw ^ (16'd1 << bi);
        tok(bad[10:0], bad[15:11]);
        n_single = n_single + 1;
        checks   = checks + 1;
        if (crc5_ok) begin
          n_miss_s = n_miss_s + 1;
          if (n_miss_s < 5)
            $display("FAIL single-bit error UNDETECTED token=%0h bit=%0d",
                     i, bi);
        end
      end
    end
    if (n_miss_s != 0) errors = errors + 1;
    // Every one of them is also a reported downstream failure, because a
    // token is always host-to-device.
    ck("single-bit failures counted", n_tok_fail - base_tf, n_single);

    // ================= PHASE 3 -- every double-bit error, all 2048 =======
    //
    // 2048 x 120 = 245760 injections. This is the property that separates a
    // CRC from a parity bit.
    n_double = 0; n_miss_d = 0;
    for (i = 0; i < 2048; i = i + 1) begin
      // ...and again here, for the same reason.
      tok(i[10:0], ref_crc5(i[10:0]));
      cw = {5'd0, i[10:0]} | ({11'd0, ref_crc5(i[10:0])} << 11);
      for (bi = 0; bi < 16; bi = bi + 1)
        for (bj = bi + 1; bj < 16; bj = bj + 1) begin
          bad = cw ^ (16'd1 << bi) ^ (16'd1 << bj);
          tok(bad[10:0], bad[15:11]);
          n_double = n_double + 1;
          checks   = checks + 1;
          if (crc5_ok) begin
            n_miss_d = n_miss_d + 1;
            if (n_miss_d < 5)
              $display("FAIL double-bit error UNDETECTED token=%0h %0d,%0d",
                       i, bi, bj);
          end
        end
    end
    if (n_miss_d != 0) errors = errors + 1;

    // ================= PHASE 4 -- CRC16 over real packets ================
    //
    // Including the zero-length packet, which is a real packet with a real
    // CRC16 and the one length nobody tests.
    for (n = 0; n <= 16; n = n + 1) begin
      for (j = 0; j < n; j = j + 1) pay[j] = ($unsigned($random) % 256);
      c16 = pay_crc16(n);
      idle;
      datpkt(n, c16, 1'b0);
      ck("crc16_ok",    crc16_ok, 32'd1);
      ck("crc16_gen",   crc16_gen, c16);
      ck("crc16_resid", crc16_resid, CRC16_RESID);
    end

    // ================= PHASE 5 -- CRC16 single-bit detection =============
    //
    // Every bit of an 8-byte payload plus its 16-bit CRC: 80 positions,
    // over 64 different payloads. Not exhaustive over payloads -- 2^64 is
    // not a testbench -- but exhaustive over ERROR POSITION, which is the
    // axis the polynomial makes a promise about.
    base_df = n_dat_fail;
    n_single = 0;
    for (i = 0; i < 64; i = i + 1) begin
      for (j = 0; j < 8; j = j + 1) pay[j] = ($unsigned($random) % 256);
      c16 = pay_crc16(8);
      for (bi = 0; bi < 80; bi = bi + 1) begin
        // flip one bit: in the payload if bi < 64, in the CRC otherwise
        if (bi < 64) pay[bi/8] = pay[bi/8] ^ (8'd1 << (bi % 8));
        idle;
        datpkt(8, (bi >= 64) ? (c16 ^ (16'd1 << (bi - 64))) : c16, 1'b1);
        n_single = n_single + 1;
        checks   = checks + 1;
        if (crc16_ok) begin
          errors = errors + 1;
          if (errors < 25)
            $display("FAIL CRC16 single-bit error UNDETECTED payload=%0d bit=%0d",
                     i, bi);
        end
        if (bi < 64) pay[bi/8] = pay[bi/8] ^ (8'd1 << (bi % 8));
      end
    end
    ck("crc16 single-bit failures counted", n_dat_fail - base_df, n_single);
    // ...and every one of them was IN data, so every one is UPSTREAM. This
    // is the check that makes the verdict mean something: the direction is
    // not inferred from the failure, it is carried by the transaction.
    ck("all upstream", n_up_fail, n_single);

    // ================= PHASE 6 -- burst versus isolated ==================
    //
    // The measurement that separates marginal signal from interference. A
    // run of five failures is ONE isolated and FOUR burst; five failures
    // each separated by a good one are FIVE isolated.
    idle;
    tok(11'h123, ref_crc5(11'h123));     // a good one, to clear the run
    base_burst = n_burst; base_iso = n_isolated;
    for (i = 0; i < 5; i = i + 1) tok(11'h123, ref_crc5(11'h123) ^ 5'h01);
    if (n_burst - base_burst != 4 || n_isolated - base_iso != 1) begin
      errors = errors + 1;
      $display("FAIL run of 5: burst=%0d isolated=%0d expected 4 and 1",
               n_burst - base_burst, n_isolated - base_iso);
    end
    tok(11'h123, ref_crc5(11'h123));     // clear the run
    base_burst = n_burst; base_iso = n_isolated;
    for (i = 0; i < 5; i = i + 1) begin
      tok(11'h123, ref_crc5(11'h123) ^ 5'h01);
      tok(11'h123, ref_crc5(11'h123));
    end
    if (n_burst - base_burst != 0 || n_isolated - base_iso != 5) begin
      errors = errors + 1;
      $display("FAIL 5 separated: burst=%0d isolated=%0d expected 0 and 5",
               n_burst - base_burst, n_isolated - base_iso);
    end

    // ================= PHASE 7 -- the verdict ============================
    //
    // Three runs from a clean reset, each with the failures on one side of
    // the link, and the verdict has to name the right half.
    //
    // Reset between them, because a verdict is a RATIO over accumulated
    // counters: computed on top of the previous phase's totals it is a
    // ratio of the wrong things (chapter 25.4 phase 4, in a new costume).
    reset_dut;
    for (i = 0; i < 40; i = i + 1) tok(11'h055, ref_crc5(11'h055) ^ 5'h03);
    ck("verdict downstream", verdict, V_DOWN);

    reset_dut;
    for (j = 0; j < 8; j = j + 1) pay[j] = j[7:0];
    c16 = pay_crc16(8);
    for (i = 0; i < 40; i = i + 1) begin
      idle;
      datpkt(8, c16 ^ 16'h0001, 1'b1);       // IN data, wrong CRC
    end
    ck("verdict upstream", verdict, V_UP);

    reset_dut;
    for (i = 0; i < 20; i = i + 1) begin
      tok(11'h055, ref_crc5(11'h055) ^ 5'h03);
      idle;
      datpkt(8, c16 ^ 16'h0001, 1'b1);
    end
    ck("verdict common", verdict, V_COMMON);

    reset_dut;
    for (i = 0; i < 20; i = i + 1) tok(11'h055, ref_crc5(11'h055));
    ck("verdict clean", verdict, V_CLEAN);

    $display("steps=%0d checks=%0d errors=%0d", steps, checks, errors);
    $display("single-bit injections=%0d undetected=%0d", 2048*16, n_miss_s);
    $display("double-bit injections=%0d undetected=%0d", 2048*120, n_miss_d);
    $display("crc5 residual values observed=%0d (expected 1)", n_resid);
    $display("%0s: %0d errors in %0d checks",
             (errors == 0) ? "PASS" : "FAIL", errors, checks);
    $finish;
  end

  task automatic reset_dut;
    begin
      tok_valid = 1'b0; dat_start = 1'b0; dat_valid = 1'b0; dat_end = 1'b0;
      rst_n = 1'b0;
      @(posedge clk); #1;
      rst_n = 1'b1;
      @(negedge clk);
      // The DUT's counters went to zero, so the expectations must too --
      // otherwise every check after the first reset fails for a reason that
      // has nothing to do with the design.
      clear_expect;
    end
  endtask
endmodule