USB VIP Usage

   A VIP at 100% has exercised every bin IT declares:

     the bins ITS authors thought of
     for the specification revision THEY targeted
     with the configurations THEY support

   It says nothing about the model in chapter 24.4, and in
   particular nothing about the combinations your device
   supports and its authors had never heard of.

  usb_vip_adapter  #(QD = 8, QW = 3, SKEW_MAX = 4)

  the VIP's decoded view     the design's decoded view
  ----------------------     -------------------------
  vip_valid / vip_pid        dut_valid / dut_pid
  vip_view                   dut_view

  strict   1: a disagreement FAILS
           0: it is MASKED -- and COUNTED

  outputs   agree_pulse / dis_pulse / masked_pulse
            dis_code  PID / VIEW / SKEW / UNPAIRED
            skew      how far apart the two sides are

  n_agree n_pid_dis n_view_dis n_skew n_masked n_unpaired

// usb_vip_adapter -- integrating verification IP you did not write, and the
// one job the adapter must not do.
//
// A VIP IS A SECOND IMPLEMENTATION OF THE SPECIFICATION
//
// That is the whole value of it. Two independent readings of the same
// document, watching the same wires, and where they disagree ONE OF THEM IS
// WRONG. Neither can tell you which, because each is reasoning from its own
// model -- and that is fine, because "these two disagree, here, on this
// packet" is already the most useful thing anybody will learn that day.
//
// THE JOB THE ADAPTER MUST NOT DO
//
// An adapter sits between the VIP and the design because their interfaces
// never match exactly: different field widths, different event granularity,
// a cycle of pipelining here, a differently-named signal there. Writing that
// translation is legitimate work.
//
// What is not legitimate is the step that always follows:
//
//     "the VIP flags this as an error but our device is
//      allowed to do it, so the adapter filters it out"
//
// That sentence is sometimes true. It is a specification argument, and it
// has to be WON -- written down, cited, and reviewed -- not implemented in a
// shim by whoever was unblocking the regression that afternoon. Once it is
// in the shim, the disagreement is invisible, and so is every future
// disagreement of the same shape.
//
//     AN ADAPTER MAKES A DISAGREEMENT VISIBLE.
//     IT DOES NOT RESOLVE ONE.
//
// So this block compares the two views and reports the difference. It has a
// permissive mode -- because sometimes you genuinely must get through the
// afternoon -- and in permissive mode it COUNTS what it masked. A permissive
// run cannot come back clean; it comes back with a number.
//
// A VIP'S COVERAGE IS THE VIP'S MODEL'S COVERAGE
//
// This is worth saying plainly because VIP coverage reports are quoted as if
// they were project coverage. A VIP at 100% has exercised every bin IT
// declares, which are the bins ITS authors thought of, for the specification
// revision THEY targeted. It says nothing about the bins in chapter 24.4's
// model, and in particular it says nothing about the combinations your
// device supports and the VIP's authors had never heard of.
//
// THE TWO SIDES DO NOT SPEAK AT THE SAME TIME
//
// A behavioural VIP reports a packet when it has decoded it; a pipelined
// design reports the same packet some cycles later. So the adapter aligns
// them with a small queue on each side rather than comparing cycle by cycle.
//
// And the alignment window is BOUNDED. When one side runs SKEW_MAX events
// ahead of the other, they are not skewed any more -- they have lost
// alignment, and every comparison after that point is between unrelated
// events. Widening the window is the reflex and it is wrong: it converts a
// loud failure into a quiet stream of nonsense comparisons.
module usb_vip_adapter #(
  parameter integer QD       = 8,   // alignment queue depth
  parameter integer QW       = 3,   // log2(QD)
  parameter integer SKEW_MAX = 4    // events one side may run ahead
) (
  input  wire       clk,
  input  wire       rst_n,

  // ---- the VIP's decoded view of the bus ----
  input  wire       vip_valid,
  input  wire [3:0] vip_pid,
  input  wire [1:0] vip_view,

  // ---- the design's decoded view of the SAME bus ----
  input  wire       dut_valid,
  input  wire [3:0] dut_pid,
  input  wire [1:0] dut_view,

  input  wire       strict,     // 1: a disagreement fails. 0: it is COUNTED.
  input  wire       eot,

  output wire [QW:0] vip_depth,
  output wire [QW:0] dut_depth,
  output wire [QW:0] skew,
  output wire        agree_pulse,
  output wire        dis_pulse,
  output wire [2:0]  dis_code,
  output wire        masked_pulse,

  output reg [31:0] n_agree,
  output reg [31:0] n_pid_dis,
  output reg [31:0] n_view_dis,
  output reg [31:0] n_skew,
  output reg [31:0] n_masked,
  output reg [31:0] n_unpaired
);

  localparam [2:0] D_NONE     = 3'd0,
                   D_PID      = 3'd1,  // the two sides decoded a different PID
                   D_VIEW     = 3'd2,  // same PID, different interpretation
                   D_SKEW     = 3'd3,  // alignment lost
                   D_UNPAIRED = 3'd4;  // an event only one side ever saw

  reg [3:0] vp_pid [0:QD-1];
  reg [1:0] vp_vw  [0:QD-1];
  reg [3:0] dt_pid [0:QD-1];
  reg [1:0] dt_vw  [0:QD-1];
  reg [QW:0] vp_n, dt_n;

  reg [2:0] code_r;
  reg       agr_r, dis_r, msk_r;

  assign vip_depth    = vp_n;
  assign dut_depth    = dt_n;
  // Only one queue can be non-empty after a comparison, so the skew is
  // simply whichever one still holds events.
  assign skew         = (vp_n > dt_n) ? vp_n : dt_n;
  assign agree_pulse  = agr_r;
  assign dis_pulse    = dis_r;
  assign dis_code     = code_r;
  assign masked_pulse = msk_r;

  integer i;
  reg [3:0] nvp_pid [0:QD-1];
  reg [1:0] nvp_vw  [0:QD-1];
  reg [3:0] ndt_pid [0:QD-1];
  reg [1:0] ndt_vw  [0:QD-1];
  reg [QW:0] nvp_n, ndt_n;
  reg [2:0]  ncode;
  reg        nagr, ndis, nmsk, nunp;
  reg        differ;

  always @* begin
    for (i = 0; i < QD; i = i + 1) begin
      nvp_pid[i] = vp_pid[i]; nvp_vw[i] = vp_vw[i];
      ndt_pid[i] = dt_pid[i]; ndt_vw[i] = dt_vw[i];
    end
    nvp_n = vp_n; ndt_n = dt_n;
    ncode = D_NONE;
    nagr = 1'b0; ndis = 1'b0; nmsk = 1'b0; nunp = 1'b0;
    differ = 1'b0;

    if (eot) begin
      // ---- THE DRAIN. An event only one side ever reported. ----
      //
      // Not "skew that had not settled": the run is over. One of the two
      // implementations saw something the other never did, which is exactly
      // the class of finding a second implementation exists to produce.
      if (vp_n != 0) begin
        for (i = 0; i < QD - 1; i = i + 1) begin
          nvp_pid[i] = nvp_pid[i+1]; nvp_vw[i] = nvp_vw[i+1];
        end
        nvp_n = vp_n - 1'b1;
        ndis  = 1'b1; ncode = D_UNPAIRED; nunp = 1'b1;
      end else if (dt_n != 0) begin
        for (i = 0; i < QD - 1; i = i + 1) begin
          ndt_pid[i] = ndt_pid[i+1]; ndt_vw[i] = ndt_vw[i+1];
        end
        ndt_n = dt_n - 1'b1;
        ndis  = 1'b1; ncode = D_UNPAIRED; nunp = 1'b1;
      end
    end else begin
      // ---- 1. Both sides have an event: compare the OLDEST pair. ----
      if ((vp_n != 0) && (dt_n != 0)) begin
        if (vp_pid[0] !== dt_pid[0]) begin
          differ = 1'b1; ncode = D_PID;
        end else if (vp_vw[0] !== dt_vw[0]) begin
          // ---- Same PID, different INTERPRETATION. ----
          //
          // This is the disagreement worth having a VIP for. Both sides
          // agree on what arrived and disagree on what it MEANS -- which is
          // always a specification reading, and is the case an adapter is
          // most often asked to paper over.
          differ = 1'b1; ncode = D_VIEW;
        end else begin
          nagr = 1'b1;
        end

        if (differ) begin
          if (strict) begin
            ndis = 1'b1;
          end else begin
            // ---- PERMISSIVE. Masked, and COUNTED. ----
            //
            // The count is the point. A permissive run does not come back
            // clean; it comes back with a number, and the number is how
            // many specification arguments nobody has had yet.
            nmsk = 1'b1;
          end
        end

        for (i = 0; i < QD - 1; i = i + 1) begin
          nvp_pid[i] = nvp_pid[i+1]; nvp_vw[i] = nvp_vw[i+1];
          ndt_pid[i] = ndt_pid[i+1]; ndt_vw[i] = ndt_vw[i+1];
        end
        nvp_n = nvp_n - 1'b1;
        ndt_n = ndt_n - 1'b1;
      end

      // ---- 2. Enqueue whatever arrived this cycle. ----
      if (vip_valid && (nvp_n < QD[QW:0])) begin
        nvp_pid[nvp_n] = vip_pid;
        nvp_vw[nvp_n]  = vip_view;
        nvp_n = nvp_n + 1'b1;
      end
      if (dut_valid && (ndt_n < QD[QW:0])) begin
        ndt_pid[ndt_n] = dut_pid;
        ndt_vw[ndt_n]  = dut_view;
        ndt_n = ndt_n + 1'b1;
      end

      // ---- 3. THE ALIGNMENT BOUND. ----
      //
      // One side running SKEW_MAX events ahead of the other is not skew any
      // more: alignment is lost, and every comparison after this point is
      // between unrelated events. The queues are flushed so that the loss
      // is reported ONCE rather than as a stream of nonsense PID
      // disagreements.
      //
      // Widening SKEW_MAX is the reflex and it is the wrong move: it
      // converts a loud failure into a quiet stream of garbage.
      if ((nvp_n > SKEW_MAX[QW:0]) || (ndt_n > SKEW_MAX[QW:0])) begin
        nvp_n = {(QW+1){1'b0}};
        ndt_n = {(QW+1){1'b0}};
        ndis  = 1'b1;
        nmsk  = 1'b0;
        ncode = D_SKEW;
        nagr  = 1'b0;
      end
    end
  end

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      for (i = 0; i < QD; i = i + 1) begin
        vp_pid[i] <= 4'd0; vp_vw[i] <= 2'd0;
        dt_pid[i] <= 4'd0; dt_vw[i] <= 2'd0;
      end
      vp_n       <= {(QW+1){1'b0}};
      dt_n       <= {(QW+1){1'b0}};
      code_r     <= D_NONE;
      agr_r      <= 1'b0;
      dis_r      <= 1'b0;
      msk_r      <= 1'b0;
      n_agree    <= 32'd0;
      n_pid_dis  <= 32'd0;
      n_view_dis <= 32'd0;
      n_skew     <= 32'd0;
      n_masked   <= 32'd0;
      n_unpaired <= 32'd0;
    end else begin
      for (i = 0; i < QD; i = i + 1) begin
        vp_pid[i] <= nvp_pid[i]; vp_vw[i] <= nvp_vw[i];
        dt_pid[i] <= ndt_pid[i]; dt_vw[i] <= ndt_vw[i];
      end
      vp_n   <= nvp_n;
      dt_n   <= ndt_n;
      code_r <= ncode;
      agr_r  <= nagr;
      dis_r  <= ndis;
      msk_r  <= nmsk;

      if (nagr) n_agree <= n_agree + 32'd1;
      if (nmsk) n_masked <= n_masked + 32'd1;

      // A masked disagreement still increments its CAUSE counter. The
      // permissive switch decides whether the run fails; it does not decide
      // whether the disagreement happened.
      if (ndis || nmsk) begin
        case (ncode)
          D_PID:      n_pid_dis  <= n_pid_dis  + 32'd1;
          D_VIEW:     n_view_dis <= n_view_dis + 32'd1;
          D_SKEW:     n_skew     <= n_skew     + 32'd1;
          D_UNPAIRED: n_unpaired <= n_unpaired + 32'd1;
          default: ;
        endcase
      end
    end
  end
endmodule

// usb_vip_adapter -- integrating verification IP you did not write, and the
// one job the adapter must not do.
//
// A VIP IS A SECOND IMPLEMENTATION OF THE SPECIFICATION
//
// That is the whole value of it. Two independent readings of the same
// document, watching the same wires, and where they disagree ONE OF THEM IS
// WRONG. Neither can tell you which, because each is reasoning from its own
// model -- and that is fine, because "these two disagree, here, on this
// packet" is already the most useful thing anybody will learn that day.
//
// THE JOB THE ADAPTER MUST NOT DO
//
// An adapter sits between the VIP and the design because their interfaces
// never match exactly: different field widths, different event granularity,
// a cycle of pipelining here, a differently-named signal there. Writing that
// translation is legitimate work.
//
// What is not legitimate is the step that always follows:
//
//     "the VIP flags this as an error but our device is
//      allowed to do it, so the adapter filters it out"
//
// That sentence is sometimes true. It is a specification argument, and it
// has to be WON -- written down, cited, and reviewed -- not implemented in a
// shim by whoever was unblocking the regression that afternoon. Once it is
// in the shim, the disagreement is invisible, and so is every future
// disagreement of the same shape.
//
//     AN ADAPTER MAKES A DISAGREEMENT VISIBLE.
//     IT DOES NOT RESOLVE ONE.
//
// So this block compares the two views and reports the difference. It has a
// permissive mode -- because sometimes you genuinely must get through the
// afternoon -- and in permissive mode it COUNTS what it masked. A permissive
// run cannot come back clean; it comes back with a number.
//
// A VIP'S COVERAGE IS THE VIP'S MODEL'S COVERAGE
//
// This is worth saying plainly because VIP coverage reports are quoted as if
// they were project coverage. A VIP at 100% has exercised every bin IT
// declares, which are the bins ITS authors thought of, for the specification
// revision THEY targeted. It says nothing about the bins in chapter 24.4's
// model, and in particular it says nothing about the combinations your
// device supports and the VIP's authors had never heard of.
//
// THE TWO SIDES DO NOT SPEAK AT THE SAME TIME
//
// A behavioural VIP reports a packet when it has decoded it; a pipelined
// design reports the same packet some cycles later. So the adapter aligns
// them with a small queue on each side rather than comparing cycle by cycle.
//
// And the alignment window is BOUNDED. When one side runs SKEW_MAX events
// ahead of the other, they are not skewed any more -- they have lost
// alignment, and every comparison after that point is between unrelated
// events. Widening the window is the reflex and it is wrong: it converts a
// loud failure into a quiet stream of nonsense comparisons.
package usb_vip_pkg;
  // The four ways two independent readings of the same bus can differ.
  // D_VIEW is the one worth owning a VIP for: both sides agree on what
  // arrived and disagree on what it MEANS, which is always a specification
  // reading rather than a decode bug.
  typedef enum logic [2:0] {
    D_NONE     = 3'd0,
    D_PID      = 3'd1,   // the two sides decoded a different PID
    D_VIEW     = 3'd2,   // same PID, different interpretation
    D_SKEW     = 3'd3,   // alignment lost
    D_UNPAIRED = 3'd4    // an event only one side ever saw
  } dis_e;
endpackage

module usb_vip_adapter
  import usb_vip_pkg::*;
 #(
  parameter int QD       = 8,   // alignment queue depth
  parameter int QW       = 3,   // log2(QD)
  parameter int SKEW_MAX = 4    // events one side may run ahead
) (
  input  logic      clk,
  input  logic      rst_n,

  // ---- the VIP's decoded view of the bus ----
  input  logic      vip_valid,
  input  logic [3:0] vip_pid,
  input  logic [1:0] vip_view,

  // ---- the design's decoded view of the SAME bus ----
  input  logic      dut_valid,
  input  logic [3:0] dut_pid,
  input  logic [1:0] dut_view,

  input  logic      strict,     // 1: a disagreement fails. 0: it is COUNTED.
  input  logic      eot,

  output logic [QW:0] vip_depth,
  output logic [QW:0] dut_depth,
  output logic [QW:0] skew,
  output logic       agree_pulse,
  output logic       dis_pulse,
  output dis_e        dis_code,
  output logic       masked_pulse,

  output logic [31:0] n_agree,
  output logic [31:0] n_pid_dis,
  output logic [31:0] n_view_dis,
  output logic [31:0] n_skew,
  output logic [31:0] n_masked,
  output logic [31:0] n_unpaired
);

  logic [3:0] vp_pid [QD];
  logic [1:0] vp_vw  [QD];
  logic [3:0] dt_pid [QD];
  logic [1:0] dt_vw  [QD];
  logic [QW:0] vp_n, dt_n;

  dis_e code_r;
  logic agr_r, dis_r, msk_r;

  assign vip_depth    = vp_n;
  assign dut_depth    = dt_n;
  // Only one queue can be non-empty after a comparison, so the skew is
  // simply whichever one still holds events.
  assign skew         = (vp_n > dt_n) ? vp_n : dt_n;
  assign agree_pulse  = agr_r;
  assign dis_pulse    = dis_r;
  assign dis_code     = code_r;
  assign masked_pulse = msk_r;

  int          i;
  logic [3:0]  nvp_pid [QD];
  logic [1:0]  nvp_vw  [QD];
  logic [3:0]  ndt_pid [QD];
  logic [1:0]  ndt_vw  [QD];
  logic [QW:0] nvp_n, ndt_n;
  dis_e        ncode;
  logic        nagr, ndis, nmsk, nunp;
  logic        differ;

  always_comb begin
    for (i = 0; i < QD; i++) begin
      nvp_pid[i] = vp_pid[i]; nvp_vw[i] = vp_vw[i];
      ndt_pid[i] = dt_pid[i]; ndt_vw[i] = dt_vw[i];
    end
    nvp_n = vp_n; ndt_n = dt_n;
    ncode = D_NONE;
    nagr = 1'b0; ndis = 1'b0; nmsk = 1'b0; nunp = 1'b0;
    differ = 1'b0;

    if (eot) begin
      // ---- THE DRAIN. An event only one side ever reported. ----
      //
      // Not "skew that had not settled": the run is over. One of the two
      // implementations saw something the other never did, which is exactly
      // the class of finding a second implementation exists to produce.
      if (vp_n != 0) begin
        for (i = 0; i < QD - 1; i++) begin
          nvp_pid[i] = nvp_pid[i+1]; nvp_vw[i] = nvp_vw[i+1];
        end
        nvp_n = vp_n - 1'b1;
        ndis  = 1'b1; ncode = D_UNPAIRED; nunp = 1'b1;
      end else if (dt_n != 0) begin
        for (i = 0; i < QD - 1; i++) begin
          ndt_pid[i] = ndt_pid[i+1]; ndt_vw[i] = ndt_vw[i+1];
        end
        ndt_n = dt_n - 1'b1;
        ndis  = 1'b1; ncode = D_UNPAIRED; nunp = 1'b1;
      end
    end else begin
      // ---- 1. Both sides have an event: compare the OLDEST pair. ----
      if ((vp_n != 0) && (dt_n != 0)) begin
        if (vp_pid[0] !== dt_pid[0]) begin
          differ = 1'b1; ncode = D_PID;
        end else if (vp_vw[0] !== dt_vw[0]) begin
          // ---- Same PID, different INTERPRETATION. ----
          //
          // This is the disagreement worth having a VIP for. Both sides
          // agree on what arrived and disagree on what it MEANS -- which is
          // always a specification reading, and is the case an adapter is
          // most often asked to paper over.
          differ = 1'b1; ncode = D_VIEW;
        end else begin
          nagr = 1'b1;
        end

        if (differ) begin
          if (strict) begin
            ndis = 1'b1;
          end else begin
            // ---- PERMISSIVE. Masked, and COUNTED. ----
            //
            // The count is the point. A permissive run does not come back
            // clean; it comes back with a number, and the number is how
            // many specification arguments nobody has had yet.
            nmsk = 1'b1;
          end
        end

        for (i = 0; i < QD - 1; i++) begin
          nvp_pid[i] = nvp_pid[i+1]; nvp_vw[i] = nvp_vw[i+1];
          ndt_pid[i] = ndt_pid[i+1]; ndt_vw[i] = ndt_vw[i+1];
        end
        nvp_n = nvp_n - 1'b1;
        ndt_n = ndt_n - 1'b1;
      end

      // ---- 2. Enqueue whatever arrived this cycle. ----
      if (vip_valid && (nvp_n < (QW+1)'(QD))) begin
        nvp_pid[nvp_n] = vip_pid;
        nvp_vw[nvp_n]  = vip_view;
        nvp_n = nvp_n + 1'b1;
      end
      if (dut_valid && (ndt_n < (QW+1)'(QD))) begin
        ndt_pid[ndt_n] = dut_pid;
        ndt_vw[ndt_n]  = dut_view;
        ndt_n = ndt_n + 1'b1;
      end

      // ---- 3. THE ALIGNMENT BOUND. ----
      //
      // One side running SKEW_MAX events ahead of the other is not skew any
      // more: alignment is lost, and every comparison after this point is
      // between unrelated events. The queues are flushed so that the loss
      // is reported ONCE rather than as a stream of nonsense PID
      // disagreements.
      //
      // Widening SKEW_MAX is the reflex and it is the wrong move: it
      // converts a loud failure into a quiet stream of garbage.
      if ((nvp_n > (QW+1)'(SKEW_MAX)) || (ndt_n > (QW+1)'(SKEW_MAX))) begin
        nvp_n = '0;
        ndt_n = '0;
        ndis  = 1'b1;
        nmsk  = 1'b0;
        ncode = D_SKEW;
        nagr  = 1'b0;
      end
    end
  end

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      for (i = 0; i < QD; i++) begin
        vp_pid[i] <= 4'd0; vp_vw[i] <= 2'd0;
        dt_pid[i] <= 4'd0; dt_vw[i] <= 2'd0;
      end
      vp_n       <= '0;
      dt_n       <= '0;
      code_r     <= D_NONE;
      agr_r      <= 1'b0;
      dis_r      <= 1'b0;
      msk_r      <= 1'b0;
      n_agree    <= 32'd0;
      n_pid_dis  <= 32'd0;
      n_view_dis <= 32'd0;
      n_skew     <= 32'd0;
      n_masked   <= 32'd0;
      n_unpaired <= 32'd0;
    end else begin
      for (i = 0; i < QD; i++) begin
        vp_pid[i] <= nvp_pid[i]; vp_vw[i] <= nvp_vw[i];
        dt_pid[i] <= ndt_pid[i]; dt_vw[i] <= ndt_vw[i];
      end
      vp_n   <= nvp_n;
      dt_n   <= ndt_n;
      code_r <= ncode;
      agr_r  <= nagr;
      dis_r  <= ndis;
      msk_r  <= nmsk;

      if (nagr) n_agree <= n_agree + 32'd1;
      if (nmsk) n_masked <= n_masked + 32'd1;

      // A masked disagreement still increments its CAUSE counter. The
      // permissive switch decides whether the run fails; it does not decide
      // whether the disagreement happened.
      if (ndis || nmsk) begin
        case (ncode)
          D_PID:      n_pid_dis  <= n_pid_dis  + 32'd1;
          D_VIEW:     n_view_dis <= n_view_dis + 32'd1;
          D_SKEW:     n_skew     <= n_skew     + 32'd1;
          D_UNPAIRED: n_unpaired <= n_unpaired + 32'd1;
          default: ;
        endcase
      end
    end
  end
endmodule

-- usb_vip_adapter -- integrating verification IP you did not write, and the
-- one job the adapter must not do.
--
-- A VIP IS A SECOND IMPLEMENTATION OF THE SPECIFICATION
--
-- That is the whole value of it. Two independent readings of the same
-- document, watching the same wires, and where they disagree ONE OF THEM IS
-- WRONG. Neither can tell you which, because each is reasoning from its own
-- model -- and that is fine, because "these two disagree, here, on this
-- packet" is already the most useful thing anybody will learn that day.
--
-- THE JOB THE ADAPTER MUST NOT DO
--
-- An adapter sits between the VIP and the design because their interfaces
-- never match exactly: different field widths, different event granularity,
-- a cycle of pipelining here, a differently-named signal there. Writing that
-- translation is legitimate work.
--
-- What is not legitimate is the step that always follows:
--
--     "the VIP flags this as an error but our device is
--      allowed to do it, so the adapter filters it out"
--
-- That sentence is sometimes true. It is a specification argument, and it
-- has to be WON -- written down, cited, and reviewed -- not implemented in a
-- shim by whoever was unblocking the regression that afternoon. Once it is
-- in the shim, the disagreement is invisible, and so is every future
-- disagreement of the same shape.
--
--     AN ADAPTER MAKES A DISAGREEMENT VISIBLE.
--     IT DOES NOT RESOLVE ONE.
--
-- So this block compares the two views and reports the difference. It has a
-- permissive mode -- because sometimes you genuinely must get through the
-- afternoon -- and in permissive mode it COUNTS what it masked. A permissive
-- run cannot come back clean; it comes back with a number.
--
-- A VIP'S COVERAGE IS THE VIP'S MODEL'S COVERAGE
--
-- This is worth saying plainly because VIP coverage reports are quoted as if
-- they were project coverage. A VIP at 100% has exercised every bin IT
-- declares, which are the bins ITS authors thought of, for the specification
-- revision THEY targeted. It says nothing about the bins in chapter 24.4's
-- model, and in particular it says nothing about the combinations your
-- device supports and the VIP's authors had never heard of.
--
-- THE TWO SIDES DO NOT SPEAK AT THE SAME TIME
--
-- A behavioural VIP reports a packet when it has decoded it; a pipelined
-- design reports the same packet some cycles later. So the adapter aligns
-- them with a small queue on each side rather than comparing cycle by cycle.
--
-- And the alignment window is BOUNDED. When one side runs SKEW_MAX events
-- ahead of the other, they are not skewed any more -- they have lost
-- alignment, and every comparison after that point is between unrelated
-- events. Widening the window is the reflex and it is wrong: it converts a
-- loud failure into a quiet stream of nonsense comparisons.
library ieee;
use ieee.std_logic_1164.all;

package usb_vip_pkg is
  -- The four ways two independent readings of the same bus can differ.
  -- D_VIEW is the one worth owning a VIP for: both sides agree on what
  -- arrived and disagree on what it MEANS, which is always a specification
  -- reading rather than a decode bug.
  type dis_t is (D_NONE, D_PID, D_VIEW, D_SKEW, D_UNPAIRED);
  function d_code (d : dis_t) return std_logic_vector;
end package usb_vip_pkg;

package body usb_vip_pkg is
  function d_code (d : dis_t) return std_logic_vector is
  begin
    case d is
      when D_NONE     => return "000";
      when D_PID      => return "001";
      when D_VIEW     => return "010";
      when D_SKEW     => return "011";
      when D_UNPAIRED => return "100";
    end case;
  end function;
end package body usb_vip_pkg;

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

entity usb_vip_adapter is
  generic (
    QD       : integer := 8;   -- alignment queue depth
    QW       : integer := 3;   -- log2(QD)
    SKEW_MAX : integer := 4    -- events one side may run ahead
  );
  port (
    clk          : in  std_logic;
    rst_n        : in  std_logic;

    -- ---- the VIP's decoded view of the bus ----
    vip_valid    : in  std_logic;
    vip_pid      : in  std_logic_vector(3 downto 0);
    vip_view     : in  std_logic_vector(1 downto 0);

    -- ---- the design's decoded view of the SAME bus ----
    dut_valid    : in  std_logic;
    dut_pid      : in  std_logic_vector(3 downto 0);
    dut_view     : in  std_logic_vector(1 downto 0);

    strict       : in  std_logic;   -- 1: fails. 0: the disagreement is COUNTED.
    eot          : in  std_logic;

    vip_depth    : out std_logic_vector(QW downto 0);
    dut_depth    : out std_logic_vector(QW downto 0);
    skew         : out std_logic_vector(QW downto 0);
    agree_pulse  : out std_logic;
    dis_pulse    : out std_logic;
    dis_code     : out std_logic_vector(2 downto 0);
    masked_pulse : out std_logic;

    n_agree      : out std_logic_vector(31 downto 0);
    n_pid_dis    : out std_logic_vector(31 downto 0);
    n_view_dis   : out std_logic_vector(31 downto 0);
    n_skew       : out std_logic_vector(31 downto 0);
    n_masked     : out std_logic_vector(31 downto 0);
    n_unpaired   : out std_logic_vector(31 downto 0)
  );
end entity usb_vip_adapter;

architecture rtl of usb_vip_adapter is

  type pid_arr is array (0 to QD-1) of std_logic_vector(3 downto 0);
  type vw_arr  is array (0 to QD-1) of std_logic_vector(1 downto 0);

  signal vp_pid : pid_arr := (others => (others => '0'));
  signal vp_vw  : vw_arr  := (others => (others => '0'));
  signal dt_pid : pid_arr := (others => (others => '0'));
  signal dt_vw  : vw_arr  := (others => (others => '0'));
  signal vp_n, dt_n : unsigned(QW downto 0) := (others => '0');

  signal code_r : dis_t := D_NONE;
  signal agr_r, dis_r, msk_r : std_logic := '0';

  -- Accumulators are held as unsigned rather than as range-constrained
  -- integers: a constrained integer aborts simulation on overflow, which
  -- turns a mutation into a crash instead of a measured kill.
  signal c_ag, c_pd, c_vd : unsigned(31 downto 0) := (others => '0');
  signal c_sk, c_mk, c_up : unsigned(31 downto 0) := (others => '0');

begin

  vip_depth <= std_logic_vector(vp_n);
  dut_depth <= std_logic_vector(dt_n);
  -- Only one queue can be non-empty after a comparison, so the skew is
  -- simply whichever one still holds events.
  skew <= std_logic_vector(vp_n) when vp_n > dt_n else std_logic_vector(dt_n);
  agree_pulse  <= agr_r;
  dis_pulse    <= dis_r;
  dis_code     <= d_code(code_r);
  masked_pulse <= msk_r;

  n_agree    <= std_logic_vector(c_ag);
  n_pid_dis  <= std_logic_vector(c_pd);
  n_view_dis <= std_logic_vector(c_vd);
  n_skew     <= std_logic_vector(c_sk);
  n_masked   <= std_logic_vector(c_mk);
  n_unpaired <= std_logic_vector(c_up);

  process (clk, rst_n)
    variable nvp_pid, ndt_pid : pid_arr;
    variable nvp_vw,  ndt_vw  : vw_arr;
    variable nvp_n, ndt_n : unsigned(QW downto 0);
    variable ncode : dis_t;
    variable nagr, ndis, nmsk, dif : std_logic;
  begin
    if rst_n = '0' then
      vp_pid <= (others => (others => '0'));
      vp_vw  <= (others => (others => '0'));
      dt_pid <= (others => (others => '0'));
      dt_vw  <= (others => (others => '0'));
      vp_n   <= (others => '0');
      dt_n   <= (others => '0');
      code_r <= D_NONE;
      agr_r  <= '0'; dis_r <= '0'; msk_r <= '0';
      c_ag <= (others => '0'); c_pd <= (others => '0');
      c_vd <= (others => '0'); c_sk <= (others => '0');
      c_mk <= (others => '0'); c_up <= (others => '0');
    elsif rising_edge(clk) then
      nvp_pid := vp_pid; nvp_vw := vp_vw;
      ndt_pid := dt_pid; ndt_vw := dt_vw;
      nvp_n := vp_n; ndt_n := dt_n;
      ncode := D_NONE;
      nagr := '0'; ndis := '0'; nmsk := '0'; dif := '0';

      if eot = '1' then
        -- ---- THE DRAIN. An event only one side ever reported. ----
        --
        -- Not "skew that had not settled": the run is over. One of the two
        -- implementations saw something the other never did, which is
        -- exactly the class of finding a second implementation exists to
        -- produce.
        if nvp_n /= 0 then
          for k in 0 to QD - 2 loop
            nvp_pid(k) := nvp_pid(k+1); nvp_vw(k) := nvp_vw(k+1);
          end loop;
          nvp_n := nvp_n - 1;
          ndis := '1'; ncode := D_UNPAIRED;
        elsif ndt_n /= 0 then
          for k in 0 to QD - 2 loop
            ndt_pid(k) := ndt_pid(k+1); ndt_vw(k) := ndt_vw(k+1);
          end loop;
          ndt_n := ndt_n - 1;
          ndis := '1'; ncode := D_UNPAIRED;
        end if;
      else
        -- ---- 1. Both sides have an event: compare the OLDEST pair. ----
        if nvp_n /= 0 and ndt_n /= 0 then
          if vp_pid(0) /= dt_pid(0) then
            dif := '1'; ncode := D_PID;
          elsif vp_vw(0) /= dt_vw(0) then
            -- ---- Same PID, different INTERPRETATION. ----
            --
            -- This is the disagreement worth having a VIP for. Both sides
            -- agree on what arrived and disagree on what it MEANS -- which
            -- is always a specification reading, and is the case an adapter
            -- is most often asked to paper over.
            dif := '1'; ncode := D_VIEW;
          else
            nagr := '1';
          end if;

          if dif = '1' then
            if strict = '1' then
              ndis := '1';
            else
              -- ---- PERMISSIVE. Masked, and COUNTED. ----
              --
              -- The count is the point. A permissive run does not come back
              -- clean; it comes back with a number, and the number is how
              -- many specification arguments nobody has had yet.
              nmsk := '1';
            end if;
          end if;

          for k in 0 to QD - 2 loop
            nvp_pid(k) := nvp_pid(k+1); nvp_vw(k) := nvp_vw(k+1);
            ndt_pid(k) := ndt_pid(k+1); ndt_vw(k) := ndt_vw(k+1);
          end loop;
          nvp_n := nvp_n - 1;
          ndt_n := ndt_n - 1;
        end if;

        -- ---- 2. Enqueue whatever arrived this cycle. ----
        if vip_valid = '1' and nvp_n < to_unsigned(QD, QW+1) then
          nvp_pid(to_integer(nvp_n)) := vip_pid;
          nvp_vw(to_integer(nvp_n))  := vip_view;
          nvp_n := nvp_n + 1;
        end if;
        if dut_valid = '1' and ndt_n < to_unsigned(QD, QW+1) then
          ndt_pid(to_integer(ndt_n)) := dut_pid;
          ndt_vw(to_integer(ndt_n))  := dut_view;
          ndt_n := ndt_n + 1;
        end if;

        -- ---- 3. THE ALIGNMENT BOUND. ----
        --
        -- One side running SKEW_MAX events ahead of the other is not skew
        -- any more: alignment is lost, and every comparison after this
        -- point is between unrelated events. The queues are flushed so that
        -- the loss is reported ONCE rather than as a stream of nonsense PID
        -- disagreements.
        --
        -- Widening SKEW_MAX is the reflex and it is the wrong move: it
        -- converts a loud failure into a quiet stream of garbage.
        if nvp_n > to_unsigned(SKEW_MAX, QW+1)
           or ndt_n > to_unsigned(SKEW_MAX, QW+1) then
          nvp_n := (others => '0');
          ndt_n := (others => '0');
          ndis  := '1';
          nmsk  := '0';
          ncode := D_SKEW;
          nagr  := '0';
        end if;
      end if;

      vp_pid <= nvp_pid; vp_vw <= nvp_vw;
      dt_pid <= ndt_pid; dt_vw <= ndt_vw;
      vp_n   <= nvp_n;
      dt_n   <= ndt_n;
      code_r <= ncode;
      agr_r  <= nagr;
      dis_r  <= ndis;
      msk_r  <= nmsk;

      if nagr = '1' then c_ag <= c_ag + 1; end if;
      if nmsk = '1' then c_mk <= c_mk + 1; end if;

      -- A masked disagreement still increments its CAUSE counter. The
      -- permissive switch decides whether the run fails; it does not decide
      -- whether the disagreement happened.
      if ndis = '1' or nmsk = '1' then
        case ncode is
          when D_PID      => c_pd <= c_pd + 1;
          when D_VIEW     => c_vd <= c_vd + 1;
          when D_SKEW     => c_sk <= c_sk + 1;
          when D_UNPAIRED => c_up <= c_up + 1;
          when others     => null;
        end case;
      end if;
    end if;
  end process;

end architecture rtl;

   1.  ALL 256 (vip_pid, dut_pid) pairs, views agreeing.
       Agreement on exactly the 16 diagonal pairs and
       disagreement on the other 240 -- which is a far
       stronger statement than "it noticed the one we
       injected".

   2.  ALL 16 (vip_view, dut_view) pairs, PIDs agreeing:
       both sides saw the same packet and read it
       differently.

   3.  Every alignment skew 0..SKEW_MAX x all 16
       combinations of {vip_valid, dut_valid, strict, eot}
       = 80 pairs.

      // strict: it fails
      b_pd = n_pid_dis; b_mk = n_masked;
      pair(4'h1, 2'd0, 4'h2, 2'd0, 1'b1);
      check(n_pid_dis == b_pd + 1, "a strict disagreement was not counted");
      check(n_masked == b_mk, "a strict disagreement was masked");

      // permissive: it is masked -- and STILL COUNTED
      b_pd = n_pid_dis; b_mk = n_masked;
      pair(4'h1, 2'd0, 4'h2, 2'd0, 1'b0);
      check(n_masked == b_mk + 1,
            "a permissive run came back clean -- masking without counting is the shim that makes a disagreement invisible, and every future disagreement of the same shape with it");
      check(n_pid_dis == b_pd + 1,
            "the permissive switch decided whether the disagreement HAPPENED, rather than whether the run fails");

// Testbench for usb_vip_adapter (Verilog-2005).
//
// WHAT IS EXHAUSTIVE HERE
//
//   1. ALL 256 (vip_pid, dut_pid) PAIRS, with the two views agreeing. The
//      adapter must agree on exactly the 16 diagonal pairs and disagree on
//      the other 240 -- which is a stronger statement than "it noticed the
//      disagreement we injected".
//
//   2. ALL 16 (vip_view, dut_view) pairs with the PIDs agreeing, for the
//      case that matters most: both sides saw the same packet and read it
//      differently.
//
//   3. Every alignment skew from 0 to SKEW_MAX crossed with all sixteen
//      combinations of {vip_valid, dut_valid, strict, eot} = 80 pairs.
//
// AND THE PROPERTY THE CHAPTER EXISTS FOR
//
// PERMISSIVE MODE STILL COUNTS. The same disagreement is driven twice, once
// strict and once permissive, and the checks are:
//
//     strict      dis_pulse fires        cause counter +1
//     permissive  masked_pulse fires     cause counter +1  AND  n_masked +1
//
// The cause counter increments in BOTH. The permissive switch decides
// whether the run fails; it does not decide whether the disagreement
// happened, and an adapter that forgets that is the shim this chapter is
// about.
`timescale 1ns/1ps
module tb_va_v;

  localparam integer QD       = 8;
  localparam integer QW       = 3;
  localparam integer SKEW_MAX = 4;

  localparam [2:0] D_NONE=3'd0, D_PID=3'd1, D_VIEW=3'd2, D_SKEW=3'd3,
                   D_UNPAIRED=3'd4;

  reg clk = 1'b0, rst_n = 1'b0;
  reg vip_valid = 1'b0, dut_valid = 1'b0, strict = 1'b1, eot = 1'b0;
  reg [3:0] vip_pid = 4'd0, dut_pid = 4'd0;
  reg [1:0] vip_view = 2'd0, dut_view = 2'd0;

  wire [QW:0] vip_depth, dut_depth, skew;
  wire [2:0]  dis_code;
  wire agree_pulse, dis_pulse, masked_pulse;
  wire [31:0] n_agree, n_pid_dis, n_view_dis, n_skew, n_masked, n_unpaired;

  usb_vip_adapter #(.QD(QD), .QW(QW), .SKEW_MAX(SKEW_MAX)) dut (
    .clk(clk), .rst_n(rst_n),
    .vip_valid(vip_valid), .vip_pid(vip_pid), .vip_view(vip_view),
    .dut_valid(dut_valid), .dut_pid(dut_pid), .dut_view(dut_view),
    .strict(strict), .eot(eot),
    .vip_depth(vip_depth), .dut_depth(dut_depth), .skew(skew),
    .agree_pulse(agree_pulse), .dis_pulse(dis_pulse),
    .dis_code(dis_code), .masked_pulse(masked_pulse),
    .n_agree(n_agree), .n_pid_dis(n_pid_dis), .n_view_dis(n_view_dis),
    .n_skew(n_skew), .n_masked(n_masked), .n_unpaired(n_unpaired)
  );

  always #5 clk = ~clk;

  integer errors = 0, checks = 0;
  task check(input cond, input [1023:0] msg);
    begin
      checks = checks + 1;
      if (!cond) begin
        errors = errors + 1;
        if (errors <= 25)
          $display("FAIL @%0t: %0s | vd=%0d dd=%0d sk=%0d a=%b d=%b(%0d) m=%b",
                   $time, msg, vip_depth, dut_depth, skew, agree_pulse,
                   dis_pulse, dis_code, masked_pulse);
      end
    end
  endtask

  // ------------------------------------------------------------------
  // The shadow adapter. Its own queues.
  // ------------------------------------------------------------------
  reg [3:0] mvp_pid [0:QD-1];
  reg [1:0] mvp_vw  [0:QD-1];
  reg [3:0] mdt_pid [0:QD-1];
  reg [1:0] mdt_vw  [0:QD-1];
  reg [QW:0] mvp_n, mdt_n;
  reg [2:0]  m_code;
  reg        m_agr, m_dis, m_msk;
  integer    m_ag, m_pd, m_vd, m_sk, m_mk, m_up;

  integer seen [0:79];          // (SKEW_MAX+1) x 16 input combinations
  integer n_seen, n_steps;

  task model_reset;
    integer j;
    begin
      for (j = 0; j < QD; j = j + 1) begin
        mvp_pid[j] = 4'd0; mvp_vw[j] = 2'd0;
        mdt_pid[j] = 4'd0; mdt_vw[j] = 2'd0;
      end
      mvp_n = 0; mdt_n = 0; m_code = D_NONE;
      m_agr = 1'b0; m_dis = 1'b0; m_msk = 1'b0;
      m_ag = 0; m_pd = 0; m_vd = 0; m_sk = 0; m_mk = 0; m_up = 0;
      for (j = 0; j < 80; j = j + 1) seen[j] = 0;
      n_seen = 0; n_steps = 0;
    end
  endtask

  integer q, idx;
  task step(input vv, input [3:0] vp, input [1:0] vw,
            input dv, input [3:0] dp, input [1:0] dw,
            input st, input eo);
    reg [2:0] ncode;
    reg nagr, ndis, nmsk, dif;
    reg [QW:0] msk_now;
    begin
      vip_valid = vv; vip_pid = vp; vip_view = vw;
      dut_valid = dv; dut_pid = dp; dut_view = dw;
      strict = st; eot = eo;
      #1;

      check(vip_depth === mvp_n, "vip_depth disagrees with the shadow adapter");
      check(dut_depth === mdt_n, "dut_depth disagrees");
      check(skew === ((mvp_n > mdt_n) ? mvp_n : mdt_n), "skew disagrees");
      check(agree_pulse  === m_agr, "the agree pulse disagrees");
      check(dis_pulse    === m_dis, "the disagreement pulse disagrees");
      check(dis_code     === m_code, "dis_code disagrees");
      check(masked_pulse === m_msk, "the masked pulse disagrees");
      check(!(agree_pulse && dis_pulse),
            "a comparison was reported as both agreement and disagreement");
      check(!(dis_pulse && masked_pulse),
            "a disagreement was reported as both failed and masked");
      check(skew <= SKEW_MAX[QW:0] + 1,
            "the alignment queues grew past the bound -- every comparison after that point is between unrelated events");

      msk_now = (mvp_n > mdt_n) ? mvp_n : mdt_n;
      idx = msk_now * 16 + (vv ? 8 : 0) + (dv ? 4 : 0) + (st ? 2 : 0) + (eo ? 1 : 0);
      if (idx < 80) begin
        if (seen[idx] == 0) begin seen[idx] = 1; n_seen = n_seen + 1; end
      end
      n_steps = n_steps + 1;

      // ---- advance the shadow adapter ----
      ncode = D_NONE; nagr = 1'b0; ndis = 1'b0; nmsk = 1'b0; dif = 1'b0;

      if (eo) begin
        if (mvp_n != 0) begin
          for (q = 0; q < QD - 1; q = q + 1) begin
            mvp_pid[q] = mvp_pid[q+1]; mvp_vw[q] = mvp_vw[q+1];
          end
          mvp_n = mvp_n - 1'b1;
          ndis = 1'b1; ncode = D_UNPAIRED;
        end else if (mdt_n != 0) begin
          for (q = 0; q < QD - 1; q = q + 1) begin
            mdt_pid[q] = mdt_pid[q+1]; mdt_vw[q] = mdt_vw[q+1];
          end
          mdt_n = mdt_n - 1'b1;
          ndis = 1'b1; ncode = D_UNPAIRED;
        end
      end else begin
        if ((mvp_n != 0) && (mdt_n != 0)) begin
          if (mvp_pid[0] !== mdt_pid[0]) begin dif = 1'b1; ncode = D_PID; end
          else if (mvp_vw[0] !== mdt_vw[0]) begin dif = 1'b1; ncode = D_VIEW; end
          else nagr = 1'b1;
          if (dif) begin
            if (st) ndis = 1'b1; else nmsk = 1'b1;
          end
          for (q = 0; q < QD - 1; q = q + 1) begin
            mvp_pid[q] = mvp_pid[q+1]; mvp_vw[q] = mvp_vw[q+1];
            mdt_pid[q] = mdt_pid[q+1]; mdt_vw[q] = mdt_vw[q+1];
          end
          mvp_n = mvp_n - 1'b1;
          mdt_n = mdt_n - 1'b1;
        end
        if (vv && (mvp_n < QD[QW:0])) begin
          mvp_pid[mvp_n] = vp; mvp_vw[mvp_n] = vw; mvp_n = mvp_n + 1'b1;
        end
        if (dv && (mdt_n < QD[QW:0])) begin
          mdt_pid[mdt_n] = dp; mdt_vw[mdt_n] = dw; mdt_n = mdt_n + 1'b1;
        end
        if ((mvp_n > SKEW_MAX[QW:0]) || (mdt_n > SKEW_MAX[QW:0])) begin
          mvp_n = 0; mdt_n = 0;
          ndis = 1'b1; nmsk = 1'b0; ncode = D_SKEW; nagr = 1'b0;
        end
      end

      m_code = ncode; m_agr = nagr; m_dis = ndis; m_msk = nmsk;
      if (nagr) m_ag = m_ag + 1;
      if (nmsk) m_mk = m_mk + 1;
      if (ndis || nmsk) begin
        case (ncode)
          D_PID:      m_pd = m_pd + 1;
          D_VIEW:     m_vd = m_vd + 1;
          D_SKEW:     m_sk = m_sk + 1;
          D_UNPAIRED: m_up = m_up + 1;
          default: ;
        endcase
      end

      @(posedge clk); #1;
      vip_valid = 1'b0; dut_valid = 1'b0; eot = 1'b0;
    end
  endtask

  task nop(input integer n);
    integer j;
    begin
      for (j = 0; j < n; j = j + 1)
        step(1'b0,4'd0,2'd0, 1'b0,4'd0,2'd0, strict, 1'b0);
    end
  endtask

  // Feed both sides one event each and let the comparison happen.
  task pair(input [3:0] vp, input [1:0] vw, input [3:0] dp, input [1:0] dw,
            input st);
    begin
      step(1'b1,vp,vw, 1'b1,dp,dw, st, 1'b0);
      step(1'b0,4'd0,2'd0, 1'b0,4'd0,2'd0, st, 1'b0);
    end
  endtask

  // Drain the alignment queues the way the design provides for.
  task drain;
    integer j;
    begin
      for (j = 0; j < 2*QD + 2; j = j + 1)
        step(1'b0,4'd0,2'd0, 1'b0,4'd0,2'd0, strict, 1'b1);
      check(vip_depth === 4'd0 && dut_depth === 4'd0,
            "the drain did not empty the alignment queues");
      nop(1);
    end
  endtask

  integer a, b, k, b_ag, b_pd, b_vd, b_mk, b_up, b_sk, sk2, cb;

  initial begin
    model_reset;
    repeat (3) @(posedge clk);
    rst_n = 1'b1;
    @(posedge clk); #1;

    // ---- Phase A: the state after reset ----
    check(vip_depth === 4'd0 && dut_depth === 4'd0, "reset left events queued");
    check(agree_pulse === 1'b0 && dis_pulse === 1'b0,
          "reset asserted a comparison result");

    // ---- Phase B: ALL 256 PID PAIRS. Agreement on exactly the diagonal. --
    for (a = 0; a < 16; a = a + 1) begin
      for (b = 0; b < 16; b = b + 1) begin
        b_ag = n_agree; b_pd = n_pid_dis;
        pair(a[3:0], 2'd1, b[3:0], 2'd1, 1'b1);
        if (a == b) begin
          check(n_agree == b_ag + 1,
                "the two sides reported the same PID and the adapter did not agree");
          check(n_pid_dis == b_pd,
                "identical PIDs were reported as a disagreement");
        end else begin
          check(n_pid_dis == b_pd + 1,
                "the two sides decoded DIFFERENT PIDs and the adapter did not say so -- an adapter that resolves a disagreement has deleted the only finding a second implementation can produce");
          check(n_agree == b_ag,
                "a PID disagreement was counted as agreement");
        end
      end
    end

    // ---- Phase C: ALL 16 VIEW PAIRS, with the PIDs agreeing. ----
    //
    // Both sides saw the same packet and read it differently. This is the
    // disagreement worth owning a VIP for, and the one an adapter is most
    // often asked to paper over.
    for (a = 0; a < 4; a = a + 1) begin
      for (b = 0; b < 4; b = b + 1) begin
        b_ag = n_agree; b_vd = n_view_dis;
        pair(4'hC, a[1:0], 4'hC, b[1:0], 1'b1);
        if (a == b) begin
          check(n_agree == b_ag + 1, "identical views were not agreed");
          check(n_view_dis == b_vd, "identical views were reported as a disagreement");
        end else begin
          check(n_view_dis == b_vd + 1,
                "both sides saw the same packet and read it differently, and the adapter said nothing");
          check(n_agree == b_ag, "a view disagreement was counted as agreement");
        end
      end
    end

    // ---- Phase D: PERMISSIVE STILL COUNTS. ----
    for (k = 0; k < 30; k = k + 1) begin
      // strict: it fails
      b_pd = n_pid_dis; b_mk = n_masked;
      pair(4'h1, 2'd0, 4'h2, 2'd0, 1'b1);
      check(n_pid_dis == b_pd + 1, "a strict disagreement was not counted");
      check(n_masked == b_mk, "a strict disagreement was masked");

      // permissive: it is masked -- and STILL COUNTED
      b_pd = n_pid_dis; b_mk = n_masked;
      pair(4'h1, 2'd0, 4'h2, 2'd0, 1'b0);
      check(n_masked == b_mk + 1,
            "a permissive run came back clean -- masking without counting is the shim that makes a disagreement invisible, and every future disagreement of the same shape with it");
      check(n_pid_dis == b_pd + 1,
            "the permissive switch decided whether the disagreement HAPPENED, rather than whether the run fails");
    end

    // ---- Phase E: THE ALIGNMENT BOUND, both edges. ----
    drain;
    // exactly SKEW_MAX ahead: still aligned, no failure
    b_sk = n_skew;
    for (k = 0; k < SKEW_MAX; k = k + 1)
      step(1'b1, 4'h5, 2'd0, 1'b0, 4'd0, 2'd0, 1'b1, 1'b0);
    check(skew === SKEW_MAX[QW:0],
          "the queue did not reach the alignment bound");
    check(n_skew == b_sk,
          "alignment was declared lost AT the bound rather than past it");
    // one more: alignment is lost
    step(1'b1, 4'h5, 2'd0, 1'b0, 4'd0, 2'd0, 1'b1, 1'b0);
    nop(1);
    check(n_skew == b_sk + 1,
          "one side ran more than SKEW_MAX events ahead and the adapter carried on comparing unrelated events");
    check(skew === 4'd0,
          "the queues were not flushed after alignment was lost, so the loss will be reported again on every subsequent event");

    // ---- Phase F: UNPAIRED at end of test. ----
    drain;
    for (k = 1; k <= SKEW_MAX; k = k + 1) begin
      b_up = n_unpaired;
      for (a = 0; a < k; a = a + 1)
        step(1'b1, 4'h7, 2'd0, 1'b0, 4'd0, 2'd0, 1'b1, 1'b0);
      drain;
      check(n_unpaired == b_up + k,
            "an event that only one side ever reported was not named at end of test -- that is exactly the class of finding a second implementation exists to produce");
    end

    // ---- Phase G: EXHAUSTIVE. Every skew x every input combination. ----
    for (sk2 = 0; sk2 <= SKEW_MAX; sk2 = sk2 + 1) begin
      for (cb = 0; cb < 16; cb = cb + 1) begin
        drain;
        for (a = 0; a < sk2; a = a + 1)
          step(1'b1, 4'h9, 2'd0, 1'b0, 4'd0, 2'd0, 1'b1, 1'b0);
        check(skew === sk2[QW:0],
              "the sweep could not reach the skew it meant to reach");
        step(cb[3], 4'h9, 2'd0, cb[2], 4'h9, 2'd0, cb[1], cb[0]);
        step(cb[3], 4'h9, 2'd0, cb[2], 4'h9, 2'd0, cb[1], cb[0]);
      end
    end

    // ---- Phase H: random ----
    for (k = 0; k < 32000; k = k + 1)
      step(($unsigned($random) % 100) < 42, $random, $random,
           ($unsigned($random) % 100) < 42, $random, $random,
           ($unsigned($random) % 100) < 70,
           ($unsigned($random) % 1000) < 8);

    // ---- Phase I: clean agreement afterwards, so the adapter is shown to
    // ---- still work rather than merely to have stopped.
    drain;
    b_ag = n_agree;
    for (k = 0; k < 200; k = k + 1) pair(4'hE, 2'd2, 4'hE, 2'd2, 1'b1);
    check(n_agree == b_ag + 200,
          "the adapter stopped agreeing on identical views after the random phase");

    // ---- Final agreement ----
    check(n_agree    === m_ag[31:0], "n_agree disagrees with the model");
    check(n_pid_dis  === m_pd[31:0], "n_pid_dis disagrees");
    check(n_view_dis === m_vd[31:0], "n_view_dis disagrees");
    check(n_skew     === m_sk[31:0], "n_skew disagrees");
    check(n_masked   === m_mk[31:0], "n_masked disagrees");
    check(n_unpaired === m_up[31:0], "n_unpaired disagrees");

    check(n_seen == 80, "not every alignment skew was crossed with every input combination");
    check(n_agree    > 32'd0, "the two sides never agreed about anything");
    check(n_pid_dis  > 32'd0, "a PID disagreement was never seen");
    check(n_view_dis > 32'd0, "a view disagreement was never seen");
    check(n_skew     > 32'd0, "alignment was never lost");
    check(n_masked   > 32'd0, "permissive mode was never exercised");
    check(n_unpaired > 32'd0, "an unpaired event was never seen");

    $display("REACH skew-x-input=%0d/80 steps=%0d", n_seen, n_steps);
    $display("COUNTERS agree=%0d pid-dis=%0d view-dis=%0d skew=%0d masked=%0d unpaired=%0d",
             n_agree, n_pid_dis, n_view_dis, n_skew, n_masked, n_unpaired);
    $display("%0s: %0d errors in %0d checks", (errors==0)?"PASS":"FAIL", errors, checks);
    $finish;
  end
endmodule

// Testbench for usb_vip_adapter (SystemVerilog).
//
// WHAT IS EXHAUSTIVE HERE
//
//   1. ALL 256 (vip_pid, dut_pid) PAIRS, with the two views agreeing. The
//      adapter must agree on exactly the 16 diagonal pairs and disagree on
//      the other 240 -- which is a stronger statement than "it noticed the
//      disagreement we injected".
//
//   2. ALL 16 (vip_view, dut_view) pairs with the PIDs agreeing, for the
//      case that matters most: both sides saw the same packet and read it
//      differently.
//
//   3. Every alignment skew from 0 to SKEW_MAX crossed with all sixteen
//      combinations of {vip_valid, dut_valid, strict, eot} = 80 pairs.
//
// AND THE PROPERTY THE CHAPTER EXISTS FOR
//
// PERMISSIVE MODE STILL COUNTS. The same disagreement is driven twice, once
// strict and once permissive, and the checks are:
//
//     strict      dis_pulse fires        cause counter +1
//     permissive  masked_pulse fires     cause counter +1  AND  n_masked +1
//
// The cause counter increments in BOTH. The permissive switch decides
// whether the run fails; it does not decide whether the disagreement
// happened, and an adapter that forgets that is the shim this chapter is
// about.
`timescale 1ns/1ps
module tb_va_sv;
  import usb_vip_pkg::*;

  localparam int QD       = 8;
  localparam int QW       = 3;
  localparam int SKEW_MAX = 4;

  logic clk = 1'b0, rst_n = 1'b0;
  logic vip_valid = 1'b0, dut_valid = 1'b0, strict = 1'b1, eot = 1'b0;
  logic [3:0] vip_pid = '0, dut_pid = '0;
  logic [1:0] vip_view = '0, dut_view = '0;

  logic [QW:0] vip_depth, dut_depth, skew;
  dis_e        dis_code;
  logic agree_pulse, dis_pulse, masked_pulse;
  logic [31:0] n_agree, n_pid_dis, n_view_dis, n_skew, n_masked, n_unpaired;

  usb_vip_adapter #(.QD(QD), .QW(QW), .SKEW_MAX(SKEW_MAX)) dut (.*);

  always #5 clk = ~clk;

  int errors = 0, checks = 0;
  task automatic check(input logic cond, input string msg);
    begin
      checks++;
      if (!cond) begin
        errors++;
        if (errors <= 25)
          $display("FAIL @%0t: %0s | vd=%0d dd=%0d sk=%0d a=%b d=%b(%0d) m=%b",
                   $time, msg, vip_depth, dut_depth, skew, agree_pulse,
                   dis_pulse, dis_code, masked_pulse);
      end
    end
  endtask

  // ------------------------------------------------------------------
  // The shadow adapter. Its own queues.
  // ------------------------------------------------------------------
  logic [3:0] mvp_pid [QD];
  logic [1:0] mvp_vw  [QD];
  logic [3:0] mdt_pid [QD];
  logic [1:0] mdt_vw  [QD];
  logic [QW:0] mvp_n, mdt_n;
  dis_e        m_code;
  logic        m_agr, m_dis, m_msk;
  int          m_ag, m_pd, m_vd, m_sk, m_mk, m_up;

  int seen [80];                // (SKEW_MAX+1) x 16 input combinations
  int n_seen, n_steps;

  task automatic model_reset();
    int j;
    begin
      for (j = 0; j < QD; j++) begin
        mvp_pid[j] = 4'd0; mvp_vw[j] = 2'd0;
        mdt_pid[j] = 4'd0; mdt_vw[j] = 2'd0;
      end
      mvp_n = 0; mdt_n = 0; m_code = D_NONE;
      m_agr = 1'b0; m_dis = 1'b0; m_msk = 1'b0;
      m_ag = 0; m_pd = 0; m_vd = 0; m_sk = 0; m_mk = 0; m_up = 0;
      for (j = 0; j < 80; j++) seen[j] = 0;
      n_seen = 0; n_steps = 0;
    end
  endtask

  int q, idx;
  task automatic step(input logic vv, input logic [3:0] vp, input logic [1:0] vw,
                      input logic dv, input logic [3:0] dp, input logic [1:0] dw,
                      input logic st, input logic eo);
    dis_e ncode;
    logic nagr, ndis, nmsk, dif;
    logic [QW:0] msk_now;
    begin
      vip_valid = vv; vip_pid = vp; vip_view = vw;
      dut_valid = dv; dut_pid = dp; dut_view = dw;
      strict = st; eot = eo;
      #1;

      check(vip_depth === mvp_n, "vip_depth disagrees with the shadow adapter");
      check(dut_depth === mdt_n, "dut_depth disagrees");
      check(skew === ((mvp_n > mdt_n) ? mvp_n : mdt_n), "skew disagrees");
      check(agree_pulse  === m_agr, "the agree pulse disagrees");
      check(dis_pulse    === m_dis, "the disagreement pulse disagrees");
      check(dis_code     === m_code, "dis_code disagrees");
      check(masked_pulse === m_msk, "the masked pulse disagrees");
      check(!(agree_pulse && dis_pulse),
            "a comparison was reported as both agreement and disagreement");
      check(!(dis_pulse && masked_pulse),
            "a disagreement was reported as both failed and masked");
      check(skew <= (QW+1)'(SKEW_MAX) + 1,
            "the alignment queues grew past the bound -- every comparison after that point is between unrelated events");

      msk_now = (mvp_n > mdt_n) ? mvp_n : mdt_n;
      idx = int'(msk_now) * 16 + (vv ? 8 : 0) + (dv ? 4 : 0) + (st ? 2 : 0) + (eo ? 1 : 0);
      if (idx < 80) begin
        if (seen[idx] == 0) begin seen[idx] = 1; n_seen = n_seen + 1; end
      end
      n_steps++;

      // ---- advance the shadow adapter ----
      ncode = D_NONE; nagr = 1'b0; ndis = 1'b0; nmsk = 1'b0; dif = 1'b0;

      if (eo) begin
        if (mvp_n != 0) begin
          for (q = 0; q < QD - 1; q++) begin
            mvp_pid[q] = mvp_pid[q+1]; mvp_vw[q] = mvp_vw[q+1];
          end
          mvp_n = mvp_n - 1'b1;
          ndis = 1'b1; ncode = D_UNPAIRED;
        end else if (mdt_n != 0) begin
          for (q = 0; q < QD - 1; q++) begin
            mdt_pid[q] = mdt_pid[q+1]; mdt_vw[q] = mdt_vw[q+1];
          end
          mdt_n = mdt_n - 1'b1;
          ndis = 1'b1; ncode = D_UNPAIRED;
        end
      end else begin
        if ((mvp_n != 0) && (mdt_n != 0)) begin
          if (mvp_pid[0] !== mdt_pid[0]) begin dif = 1'b1; ncode = D_PID; end
          else if (mvp_vw[0] !== mdt_vw[0]) begin dif = 1'b1; ncode = D_VIEW; end
          else nagr = 1'b1;
          if (dif) begin
            if (st) ndis = 1'b1; else nmsk = 1'b1;
          end
          for (q = 0; q < QD - 1; q++) begin
            mvp_pid[q] = mvp_pid[q+1]; mvp_vw[q] = mvp_vw[q+1];
            mdt_pid[q] = mdt_pid[q+1]; mdt_vw[q] = mdt_vw[q+1];
          end
          mvp_n = mvp_n - 1'b1;
          mdt_n = mdt_n - 1'b1;
        end
        if (vv && (mvp_n < (QW+1)'(QD))) begin
          mvp_pid[mvp_n] = vp; mvp_vw[mvp_n] = vw; mvp_n = mvp_n + 1'b1;
        end
        if (dv && (mdt_n < (QW+1)'(QD))) begin
          mdt_pid[mdt_n] = dp; mdt_vw[mdt_n] = dw; mdt_n = mdt_n + 1'b1;
        end
        if ((mvp_n > (QW+1)'(SKEW_MAX)) || (mdt_n > (QW+1)'(SKEW_MAX))) begin
          mvp_n = 0; mdt_n = 0;
          ndis = 1'b1; nmsk = 1'b0; ncode = D_SKEW; nagr = 1'b0;
        end
      end

      m_code = ncode; m_agr = nagr; m_dis = ndis; m_msk = nmsk;
      if (nagr) m_ag = m_ag + 1;
      if (nmsk) m_mk = m_mk + 1;
      if (ndis || nmsk) begin
        case (ncode)
          D_PID:      m_pd = m_pd + 1;
          D_VIEW:     m_vd = m_vd + 1;
          D_SKEW:     m_sk = m_sk + 1;
          D_UNPAIRED: m_up = m_up + 1;
          default: ;
        endcase
      end

      @(posedge clk); #1;
      vip_valid = 1'b0; dut_valid = 1'b0; eot = 1'b0;
    end
  endtask

  task automatic nop(input int n);
    repeat (n) step(1'b0,4'd0,2'd0, 1'b0,4'd0,2'd0, strict, 1'b0);
  endtask

  // Feed both sides one event each and let the comparison happen.
  task automatic pair(input logic [3:0] vp, input logic [1:0] vw,
                      input logic [3:0] dp, input logic [1:0] dw,
                      input logic st);
    begin
      step(1'b1,vp,vw, 1'b1,dp,dw, st, 1'b0);
      step(1'b0,4'd0,2'd0, 1'b0,4'd0,2'd0, st, 1'b0);
    end
  endtask

  // Drain the alignment queues the way the design provides for.
  task automatic drain();
    repeat (2*QD + 2) step(1'b0,4'd0,2'd0, 1'b0,4'd0,2'd0, strict, 1'b1);
    check(vip_depth === '0 && dut_depth === '0,
          "the drain did not empty the alignment queues");
    nop(1);
  endtask

  int a, b, k, b_ag, b_pd, b_vd, b_mk, b_up, b_sk, sk2, cb;

  initial begin
    model_reset();
    repeat (3) @(posedge clk);
    rst_n = 1'b1;
    @(posedge clk); #1;

    // ---- Phase A: the state after reset ----
    check(vip_depth === 4'd0 && dut_depth === 4'd0, "reset left events queued");
    check(agree_pulse === 1'b0 && dis_pulse === 1'b0,
          "reset asserted a comparison result");

    // ---- Phase B: ALL 256 PID PAIRS. Agreement on exactly the diagonal. --
    for (a = 0; a < 16; a++) begin
      for (b = 0; b < 16; b++) begin
        b_ag = n_agree; b_pd = n_pid_dis;
        pair(4'(a), 2'd1, 4'(b), 2'd1, 1'b1);
        if (a == b) begin
          check(n_agree == b_ag + 1,
                "the two sides reported the same PID and the adapter did not agree");
          check(n_pid_dis == b_pd,
                "identical PIDs were reported as a disagreement");
        end else begin
          check(n_pid_dis == b_pd + 1,
                "the two sides decoded DIFFERENT PIDs and the adapter did not say so -- an adapter that resolves a disagreement has deleted the only finding a second implementation can produce");
          check(n_agree == b_ag,
                "a PID disagreement was counted as agreement");
        end
      end
    end

    // ---- Phase C: ALL 16 VIEW PAIRS, with the PIDs agreeing. ----
    //
    // Both sides saw the same packet and read it differently. This is the
    // disagreement worth owning a VIP for, and the one an adapter is most
    // often asked to paper over.
    for (a = 0; a < 4; a++) begin
      for (b = 0; b < 4; b++) begin
        b_ag = n_agree; b_vd = n_view_dis;
        pair(4'hC, 2'(a), 4'hC, 2'(b), 1'b1);
        if (a == b) begin
          check(n_agree == b_ag + 1, "identical views were not agreed");
          check(n_view_dis == b_vd, "identical views were reported as a disagreement");
        end else begin
          check(n_view_dis == b_vd + 1,
                "both sides saw the same packet and read it differently, and the adapter said nothing");
          check(n_agree == b_ag, "a view disagreement was counted as agreement");
        end
      end
    end

    // ---- Phase D: PERMISSIVE STILL COUNTS. ----
    for (k = 0; k < 30; k++) begin
      // strict: it fails
      b_pd = n_pid_dis; b_mk = n_masked;
      pair(4'h1, 2'd0, 4'h2, 2'd0, 1'b1);
      check(n_pid_dis == b_pd + 1, "a strict disagreement was not counted");
      check(n_masked == b_mk, "a strict disagreement was masked");

      // permissive: it is masked -- and STILL COUNTED
      b_pd = n_pid_dis; b_mk = n_masked;
      pair(4'h1, 2'd0, 4'h2, 2'd0, 1'b0);
      check(n_masked == b_mk + 1,
            "a permissive run came back clean -- masking without counting is the shim that makes a disagreement invisible, and every future disagreement of the same shape with it");
      check(n_pid_dis == b_pd + 1,
            "the permissive switch decided whether the disagreement HAPPENED, rather than whether the run fails");
    end

    // ---- Phase E: THE ALIGNMENT BOUND, both edges. ----
    drain();
    // exactly SKEW_MAX ahead: still aligned, no failure
    b_sk = n_skew;
    for (k = 0; k < SKEW_MAX; k++)
      step(1'b1, 4'h5, 2'd0, 1'b0, 4'd0, 2'd0, 1'b1, 1'b0);
    check(skew === (QW+1)'(SKEW_MAX),
          "the queue did not reach the alignment bound");
    check(n_skew == b_sk,
          "alignment was declared lost AT the bound rather than past it");
    // one more: alignment is lost
    step(1'b1, 4'h5, 2'd0, 1'b0, 4'd0, 2'd0, 1'b1, 1'b0);
    nop(1);
    check(n_skew == b_sk + 1,
          "one side ran more than SKEW_MAX events ahead and the adapter carried on comparing unrelated events");
    check(skew === '0,
          "the queues were not flushed after alignment was lost, so the loss will be reported again on every subsequent event");

    // ---- Phase F: UNPAIRED at end of test. ----
    drain();
    for (k = 1; k <= SKEW_MAX; k++) begin
      b_up = n_unpaired;
      for (a = 0; a < k; a++)
        step(1'b1, 4'h7, 2'd0, 1'b0, 4'd0, 2'd0, 1'b1, 1'b0);
      drain();
      check(n_unpaired == b_up + k,
            "an event that only one side ever reported was not named at end of test -- that is exactly the class of finding a second implementation exists to produce");
    end

    // ---- Phase G: EXHAUSTIVE. Every skew x every input combination. ----
    for (sk2 = 0; sk2 <= SKEW_MAX; sk2++) begin
      for (cb = 0; cb < 16; cb++) begin
        drain();
        for (a = 0; a < sk2; a++)
          step(1'b1, 4'h9, 2'd0, 1'b0, 4'd0, 2'd0, 1'b1, 1'b0);
        check(skew === (QW+1)'(sk2),
              "the sweep could not reach the skew it meant to reach");
        step(1'(cb[3]), 4'h9, 2'd0, 1'(cb[2]), 4'h9, 2'd0, 1'(cb[1]), 1'(cb[0]));
        step(1'(cb[3]), 4'h9, 2'd0, 1'(cb[2]), 4'h9, 2'd0, 1'(cb[1]), 1'(cb[0]));
      end
    end

    // ---- Phase H: random ----
    for (k = 0; k < 32000; k++)
      step($urandom_range(0,99) < 42, 4'($urandom()), 2'($urandom()),
           $urandom_range(0,99) < 42, 4'($urandom()), 2'($urandom()),
           $urandom_range(0,99) < 70,
           $urandom_range(0,999) < 8);

    // ---- Phase I: clean agreement afterwards, so the adapter is shown to
    // ---- still work rather than merely to have stopped.
    drain();
    b_ag = n_agree;
    for (k = 0; k < 200; k++) pair(4'hE, 2'd2, 4'hE, 2'd2, 1'b1);
    check(n_agree == b_ag + 200,
          "the adapter stopped agreeing on identical views after the random phase");

    // ---- Final agreement ----
    check(n_agree    === 32'(m_ag), "n_agree disagrees with the model");
    check(n_pid_dis  === 32'(m_pd), "n_pid_dis disagrees");
    check(n_view_dis === 32'(m_vd), "n_view_dis disagrees");
    check(n_skew     === 32'(m_sk), "n_skew disagrees");
    check(n_masked   === 32'(m_mk), "n_masked disagrees");
    check(n_unpaired === 32'(m_up), "n_unpaired disagrees");

    check(n_seen == 80, "not every alignment skew was crossed with every input combination");
    check(n_agree    > 32'd0, "the two sides never agreed about anything");
    check(n_pid_dis  > 32'd0, "a PID disagreement was never seen");
    check(n_view_dis > 32'd0, "a view disagreement was never seen");
    check(n_skew     > 32'd0, "alignment was never lost");
    check(n_masked   > 32'd0, "permissive mode was never exercised");
    check(n_unpaired > 32'd0, "an unpaired event was never seen");

    $display("REACH skew-x-input=%0d/80 steps=%0d", n_seen, n_steps);
    $display("COUNTERS agree=%0d pid-dis=%0d view-dis=%0d skew=%0d masked=%0d unpaired=%0d",
             n_agree, n_pid_dis, n_view_dis, n_skew, n_masked, n_unpaired);
    $display("%0s: %0d errors in %0d checks", (errors==0)?"PASS":"FAIL", errors, checks);
    $finish;
  end
endmodule