Endpoint Problems

   ACK     the transfer happened

   NAK     not ready YET -- try again.
           Flow control. The endpoint is WORKING.

   STALL   no, and the answer will stay no until the host
           sends CLEAR_FEATURE(ENDPOINT_HALT).

   NYET    (high speed) accepted, but do not send the next
           one immediately.

   healthy and busy    NAK NAK NAK NAK ACK NAK NAK ACK NAK ...
   wedged              NAK NAK NAK NAK NAK NAK NAK NAK NAK ...

   Same NAK rate over a long window. Same total.
   Completely different devices.

   ACK    -> run = 0     the endpoint answered
   NYET   -> run = 0     the endpoint answered (and asked to pause)
   NAK    -> run = run + 1
   STALL  -> run = 0     a different fault entirely; see section 5

   run >= NAK_RUN_MAX    -> WEDGED

   STALL seen            -> the DEVICE took the endpoint out of service
   token to halted ep    -> the HOST has not noticed

   Same two lines on a trace. Different team gets the bug.

   expected DATA0, got DATA1   ->  the sequence broke
   expected DATA1, got DATA0   ->  the sequence broke

   A one-bit field has exactly ONE wrong value.

   "the device re-sent a packet the host already took"
   "a packet was lost"

   ... produce the SAME symptom.

// usb_endpoint_health -- three things that look alike on a trace and mean
// completely different things.
//
//     ACK    the transfer happened
//     NAK    the endpoint is not ready YET. Flow control, working.
//     STALL  firmware is saying NO, and will keep saying no until
//            somebody explicitly clears it.
//
// A NAK IS NOT AN ERROR
//
// On a busy bus a bulk endpoint NAKs constantly -- that is what a bulk
// endpoint is FOR. Counting each NAK as an error produces thousands of
// entries per second and a log nobody reads, which is chapter 24.1's
// false-positive argument in its most concrete form.
//
// WHAT MATTERS IS THE RUN, NOT THE COUNT
//
// One NAK is nothing. A thousand CONSECUTIVE NAKs from one endpoint is an
// endpoint that has stopped working, and no individual NAK in that run is
// an error. So the measurement is a RUN LENGTH:
//
//     nak_run[ep]   consecutive NAKs since this endpoint last answered
//
// and it is reset by a successful transfer, not by time. An endpoint that
// NAKs a hundred times and then ACKs once is healthy and busy; one that
// NAKs a hundred times and never ACKs is wedged, and the two are
// indistinguishable by total count.
//
// ...AND THE RUN IS PER ENDPOINT
//
// A single global run counter is reset by any endpoint answering, so a
// wedged endpoint on a device with three healthy ones is invisible: the
// others keep clearing the counter. The wedged endpoint is exactly the one
// that never resets it, which is the whole signal, and a shared counter
// deletes it.
//
// A STALL IS STICKY
//
// A halted endpoint stays halted until the host sends
// CLEAR_FEATURE(ENDPOINT_HALT). It does not clear itself, it does not clear
// on the next successful transfer, and a monitor that clears it on an ACK
// hides the single most useful fact about a stalled endpoint: that firmware
// set it and nobody ever cleared it.
//
// AND POLLING A HALTED ENDPOINT IS THE HOST'S BUG
//
// A host that keeps issuing tokens to an endpoint that has STALLed is a
// host that has not noticed. That is worth counting SEPARATELY from the
// stall itself, because it points at the driver rather than at the device
// -- and on a trace the two look identical.
//
// THE DATA TOGGLE CATCHES LOSS AND DUPLICATION, AND CANNOT TELL THEM APART
//
// The toggle alternates on every successful transfer. A transfer arriving
// with the wrong toggle means the sequence broke -- but a one-bit field has
// only one wrong value, so "the packet was re-sent" and "a packet was lost"
// produce the SAME symptom.
//
//     A one-bit toggle detects that something went wrong.
//     It cannot tell you which of two opposite things it was.
//
// That is not a defect in this block; it is a property of a one-bit
// sequence number, and it is why chapter 24.3's scoreboard needs a real
// identity rather than a toggle.
module usb_endpoint_health #(
  parameter integer N_EP        = 4,   // endpoints watched
  parameter integer NAK_RUN_MAX = 16   // consecutive NAKs before "wedged"
) (
  input  wire       clk,
  input  wire       rst_n,

  input  wire       xact_valid,  // a transaction completed on this endpoint
  input  wire [1:0] ep,
  input  wire [1:0] resp,        // 0 ACK, 1 NAK, 2 STALL, 3 NYET
  input  wire       toggle,      // the DATA toggle this transfer carried
  input  wire       clear_halt,  // CLEAR_FEATURE(ENDPOINT_HALT) for `ep`
  input  wire       eot,

  output wire [N_EP-1:0] halted,
  output wire [7:0]      nak_run,     // the run on the endpoint named by `ep`
  output wire [7:0]      worst_run,
  output wire            exp_toggle,  // what `ep` should send next
  output wire            err_pulse,
  output wire [2:0]      err_code,
  output wire            stall_pulse, // a NEW halt, not an error in itself

  output reg [31:0] n_ack,
  output reg [31:0] n_nak,
  output reg [31:0] n_stall,
  output reg [31:0] n_nyet,
  output reg [31:0] n_wedged,
  output reg [31:0] n_polled_halted,
  output reg [31:0] n_toggle,
  output reg [31:0] n_clear_unhalted,
  output reg [31:0] n_clear
);

  localparam [1:0] R_ACK = 2'd0, R_NAK = 2'd1, R_STALL = 2'd2, R_NYET = 2'd3;

  localparam [2:0] H_NONE           = 3'd0,
                   H_WEDGED         = 3'd1,  // NAK_RUN_MAX consecutive NAKs
                   H_POLLED_HALTED  = 3'd2,  // a token to a halted endpoint
                   H_TOGGLE         = 3'd3,  // the toggle sequence broke
                   H_CLEAR_UNHALTED = 3'd4;  // CLEAR_FEATURE on a live one

  reg [N_EP-1:0] halt_r;
  reg [7:0]      run_r  [0:N_EP-1];
  reg            tog_r  [0:N_EP-1];
  reg            wed_r  [0:N_EP-1];   // already reported wedged: report ONCE
  reg [7:0]      worst_r;
  reg [2:0]      ec_r;
  reg            er_r, sp_r;

  assign halted      = halt_r;
  assign nak_run     = run_r[ep];
  assign worst_run   = worst_r;
  assign exp_toggle  = tog_r[ep];
  assign err_pulse   = er_r;
  assign err_code    = ec_r;
  assign stall_pulse = sp_r;

  integer i;
  reg [N_EP-1:0] halt_n;
  reg [7:0]      run_n  [0:N_EP-1];
  reg            tog_n  [0:N_EP-1];
  reg            wed_n  [0:N_EP-1];
  reg [7:0]      worst_n;
  reg [2:0]      ec_n;
  reg            er_n, sp_n;
  reg            ack_n, nak_n, stl_n, nyt_n, clr_n;

  always @* begin
    halt_n  = halt_r;
    worst_n = worst_r;
    ec_n    = H_NONE;
    er_n    = 1'b0;
    sp_n    = 1'b0;
    ack_n   = 1'b0; nak_n = 1'b0; stl_n = 1'b0; nyt_n = 1'b0; clr_n = 1'b0;
    for (i = 0; i < N_EP; i = i + 1) begin
      run_n[i] = run_r[i];
      tog_n[i] = tog_r[i];
      wed_n[i] = wed_r[i];
    end

    if (eot) begin
      // Nothing: the counters are the report.
    end else if (clear_halt) begin
      // ---- CLEAR_FEATURE(ENDPOINT_HALT). ----
      if (!halt_r[ep]) begin
        // Clearing a halt that was never set. Harmless on the wire, and a
        // useful signal: it means the driver believes the endpoint is
        // halted and the device does not, which is a disagreement worth
        // knowing about before it becomes a lockup.
        er_n = 1'b1; ec_n = H_CLEAR_UNHALTED;
      end
      halt_n[ep] = 1'b0;
      // A cleared endpoint restarts at DATA0. Chapter 21.1 makes the same
      // point about a bus reset: the toggle is part of the state that has
      // to be reset with everything else, and forgetting it costs exactly
      // one silently-dropped packet.
      tog_n[ep]  = 1'b0;
      run_n[ep]  = 8'd0;
      wed_n[ep]  = 1'b0;
      clr_n      = 1'b1;
    end else if (xact_valid) begin
      if (halt_r[ep]) begin
        // ---- The host is still polling a HALTED endpoint. ----
        //
        // Counted separately from the stall, because it points at the
        // driver rather than at the device -- and on a trace the two look
        // identical.
        er_n = 1'b1; ec_n = H_POLLED_HALTED;
      end else begin
        case (resp)
          R_ACK: begin
            ack_n = 1'b1;
            if (toggle != tog_r[ep]) begin
              // ---- The toggle sequence broke. ----
              //
              // Which direction it broke in is NOT recoverable from one
              // bit: a re-sent packet and a lost one produce the same
              // symptom. See the note in the header.
              er_n = 1'b1; ec_n = H_TOGGLE;
            end
            tog_n[ep] = ~tog_r[ep];
            // ---- A successful transfer resets the run. ----
            //
            // By the transfer, not by time. An endpoint that NAKs a hundred
            // times and then answers is healthy and busy.
            run_n[ep] = 8'd0;
            wed_n[ep] = 1'b0;
          end

          R_NAK: begin
            // NOT an error. This is flow control working, and counting each
            // one produces a log nobody reads.
            nak_n = 1'b1;
            if (run_r[ep] != 8'hFF) run_n[ep] = run_r[ep] + 8'd1;
            if (run_n[ep] > worst_r) worst_n = run_n[ep];
            if ((run_n[ep] >= NAK_RUN_MAX[7:0]) && !wed_r[ep]) begin
              // ---- The RUN is the error, not the NAK. ----
              //
              // Reported ONCE per wedge: an endpoint that is stuck produces
              // a NAK every microframe, and one report per NAK is the same
              // flood the individual-NAK counting produced.
              er_n = 1'b1; ec_n = H_WEDGED;
              wed_n[ep] = 1'b1;
            end
          end

          R_STALL: begin
            // ---- STICKY. Until CLEAR_FEATURE, and nothing else. ----
            stl_n      = 1'b1;
            sp_n       = 1'b1;
            halt_n[ep] = 1'b1;
            run_n[ep]  = 8'd0;
          end

          default: begin
            // NYET: accepted, but not ready for the next one. Like a NAK it
            // is not an error, and unlike a NAK it does not mean the
            // transfer failed -- so it resets the run.
            nyt_n     = 1'b1;
            run_n[ep] = 8'd0;
            wed_n[ep] = 1'b0;
          end
        endcase
      end
    end
  end

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      halt_r  <= {N_EP{1'b0}};
      worst_r <= 8'd0;
      ec_r    <= H_NONE;
      er_r    <= 1'b0;
      sp_r    <= 1'b0;
      for (i = 0; i < N_EP; i = i + 1) begin
        run_r[i] <= 8'd0;
        tog_r[i] <= 1'b0;
        wed_r[i] <= 1'b0;
      end
      n_ack            <= 32'd0;
      n_nak            <= 32'd0;
      n_stall          <= 32'd0;
      n_nyet           <= 32'd0;
      n_wedged         <= 32'd0;
      n_polled_halted  <= 32'd0;
      n_toggle         <= 32'd0;
      n_clear_unhalted <= 32'd0;
      n_clear          <= 32'd0;
    end else begin
      halt_r  <= halt_n;
      worst_r <= worst_n;
      ec_r    <= ec_n;
      er_r    <= er_n;
      sp_r    <= sp_n;
      for (i = 0; i < N_EP; i = i + 1) begin
        run_r[i] <= run_n[i];
        tog_r[i] <= tog_n[i];
        wed_r[i] <= wed_n[i];
      end

      if (ack_n) n_ack   <= n_ack   + 32'd1;
      if (nak_n) n_nak   <= n_nak   + 32'd1;
      if (stl_n) n_stall <= n_stall + 32'd1;
      if (nyt_n) n_nyet  <= n_nyet  + 32'd1;
      if (clr_n) n_clear <= n_clear + 32'd1;

      // The per-cause counters are driven by the SAME pulse as the error,
      // so they sum to it by construction (chapter 23.4).
      if (er_n) begin
        case (ec_n)
          H_WEDGED:         n_wedged         <= n_wedged         + 32'd1;
          H_POLLED_HALTED:  n_polled_halted  <= n_polled_halted  + 32'd1;
          H_TOGGLE:         n_toggle         <= n_toggle         + 32'd1;
          H_CLEAR_UNHALTED: n_clear_unhalted <= n_clear_unhalted + 32'd1;
          default: ;
        endcase
      end
    end
  end
endmodule

// usb_endpoint_health -- three things that look alike on a trace and mean
// completely different things.
//
//     ACK    the transfer happened
//     NAK    the endpoint is not ready YET. Flow control, working.
//     STALL  firmware is saying NO, and will keep saying no until
//            somebody explicitly clears it.
//
// A NAK IS NOT AN ERROR
//
// On a busy bus a bulk endpoint NAKs constantly -- that is what a bulk
// endpoint is FOR. Counting each NAK as an error produces thousands of
// entries per second and a log nobody reads, which is chapter 24.1's
// false-positive argument in its most concrete form.
//
// WHAT MATTERS IS THE RUN, NOT THE COUNT
//
// One NAK is nothing. A thousand CONSECUTIVE NAKs from one endpoint is an
// endpoint that has stopped working, and no individual NAK in that run is
// an error. So the measurement is a RUN LENGTH, reset by a successful
// transfer rather than by time. An endpoint that NAKs a hundred times and
// then ACKs once is healthy and busy; one that NAKs a hundred times and
// never ACKs is wedged, and the two are indistinguishable by total count.
//
// ...AND THE RUN IS PER ENDPOINT
//
// A single global run counter is reset by ANY endpoint answering, so a
// wedged endpoint on a device with three healthy ones is invisible: the
// others keep clearing the counter. The wedged endpoint is exactly the one
// that never resets it, which is the whole signal, and a shared counter
// deletes it.
//
// A STALL IS STICKY, AND POLLING A HALTED ENDPOINT IS THE HOST'S BUG
//
// A halted endpoint stays halted until CLEAR_FEATURE(ENDPOINT_HALT). It does
// not clear on the next successful transfer, and a host that keeps issuing
// tokens to it has not noticed -- which is worth counting SEPARATELY,
// because it points at the driver rather than at the device.
//
// THE TOGGLE CATCHES LOSS AND DUPLICATION AND CANNOT TELL THEM APART
//
// A one-bit sequence number has only one wrong value, so "re-sent" and
// "lost" produce the same symptom. That is a property of one bit, not a
// defect here, and it is why chapter 24.3's scoreboard needs a real
// identity.
package usb_eph_pkg;
  typedef enum logic [1:0] {
    R_ACK   = 2'd0,   // the transfer happened
    R_NAK   = 2'd1,   // not ready YET -- flow control, not an error
    R_STALL = 2'd2,   // firmware says no, until explicitly cleared
    R_NYET  = 2'd3    // accepted, but not ready for the next one
  } resp_e;

  typedef enum logic [2:0] {
    H_NONE           = 3'd0,
    H_WEDGED         = 3'd1,  // NAK_RUN_MAX consecutive NAKs
    H_POLLED_HALTED  = 3'd2,  // a token to a halted endpoint
    H_TOGGLE         = 3'd3,  // the toggle sequence broke
    H_CLEAR_UNHALTED = 3'd4   // CLEAR_FEATURE on a live one
  } health_e;
endpackage

module usb_endpoint_health
  import usb_eph_pkg::*;
 #(
  parameter int N_EP        = 4,
  parameter int NAK_RUN_MAX = 16
) (
  input  logic       clk,
  input  logic       rst_n,

  input  logic       xact_valid,
  input  logic [1:0] ep,
  input  resp_e      resp,
  input  logic       toggle,
  input  logic       clear_halt,
  input  logic       eot,

  output logic [N_EP-1:0] halted,
  output logic [7:0]      nak_run,
  output logic [7:0]      worst_run,
  output logic            exp_toggle,
  output logic            err_pulse,
  output health_e         err_code,
  output logic            stall_pulse,

  output logic [31:0] n_ack,
  output logic [31:0] n_nak,
  output logic [31:0] n_stall,
  output logic [31:0] n_nyet,
  output logic [31:0] n_wedged,
  output logic [31:0] n_polled_halted,
  output logic [31:0] n_toggle,
  output logic [31:0] n_clear_unhalted,
  output logic [31:0] n_clear
);

  logic [N_EP-1:0] halt_r;
  logic [7:0]      run_r [N_EP];
  logic            tog_r [N_EP];
  logic            wed_r [N_EP];   // already reported wedged: report ONCE
  logic [7:0]      worst_r;
  health_e         ec_r;
  logic            er_r, sp_r;

  assign halted      = halt_r;
  assign nak_run     = run_r[ep];
  assign worst_run   = worst_r;
  assign exp_toggle  = tog_r[ep];
  assign err_pulse   = er_r;
  assign err_code    = ec_r;
  assign stall_pulse = sp_r;

  logic [N_EP-1:0] halt_n;
  logic [7:0]      run_n [N_EP];
  logic            tog_n [N_EP];
  logic            wed_n [N_EP];
  logic [7:0]      worst_n;
  health_e         ec_n;
  logic            er_n, sp_n;
  logic            ack_n, nak_n, stl_n, nyt_n, clr_n;

  int i;
  always_comb begin
    halt_n  = halt_r;
    worst_n = worst_r;
    ec_n    = H_NONE;
    er_n    = 1'b0;
    sp_n    = 1'b0;
    ack_n   = 1'b0; nak_n = 1'b0; stl_n = 1'b0; nyt_n = 1'b0; clr_n = 1'b0;
    for (i = 0; i < N_EP; i++) begin
      run_n[i] = run_r[i];
      tog_n[i] = tog_r[i];
      wed_n[i] = wed_r[i];
    end

    if (eot) begin
      // Nothing: the counters are the report.
    end else if (clear_halt) begin
      // ---- CLEAR_FEATURE(ENDPOINT_HALT). ----
      if (!halt_r[ep]) begin
        // Clearing a halt that was never set: the driver believes the
        // endpoint is halted and the device does not. Harmless on the wire,
        // and a disagreement worth knowing about before it becomes a lockup.
        er_n = 1'b1; ec_n = H_CLEAR_UNHALTED;
      end
      halt_n[ep] = 1'b0;
      // A cleared endpoint restarts at DATA0. Chapter 21.1 makes the same
      // point about a bus reset: the toggle is part of the state that has
      // to be reset with everything else, and forgetting it costs exactly
      // one silently-dropped packet.
      tog_n[ep]  = 1'b0;
      run_n[ep]  = 8'd0;
      wed_n[ep]  = 1'b0;
      clr_n      = 1'b1;
    end else if (xact_valid) begin
      if (halt_r[ep]) begin
        // ---- The host is still polling a HALTED endpoint. ----
        er_n = 1'b1; ec_n = H_POLLED_HALTED;
      end else begin
        case (resp)
          R_ACK: begin
            ack_n = 1'b1;
            if (toggle != tog_r[ep]) begin
              // The sequence broke. WHICH WAY is not recoverable from one
              // bit -- see the note in the header.
              er_n = 1'b1; ec_n = H_TOGGLE;
            end
            tog_n[ep] = ~tog_r[ep];
            // ---- A successful transfer resets the run. By the transfer,
            // ---- not by time.
            run_n[ep] = 8'd0;
            wed_n[ep] = 1'b0;
          end

          R_NAK: begin
            // NOT an error. Flow control working.
            nak_n = 1'b1;
            if (run_r[ep] != 8'hFF) run_n[ep] = run_r[ep] + 8'd1;
            if (run_n[ep] > worst_r) worst_n = run_n[ep];
            if ((run_n[ep] >= 8'(NAK_RUN_MAX)) && !wed_r[ep]) begin
              // ---- The RUN is the error, not the NAK -- and it is
              // ---- reported ONCE. A stuck endpoint NAKs every
              // ---- microframe, and one report per NAK is the same flood
              // ---- that counting individual NAKs produced.
              er_n = 1'b1; ec_n = H_WEDGED;
              wed_n[ep] = 1'b1;
            end
          end

          R_STALL: begin
            // ---- STICKY. Until CLEAR_FEATURE, and nothing else. ----
            stl_n      = 1'b1;
            sp_n       = 1'b1;
            halt_n[ep] = 1'b1;
            run_n[ep]  = 8'd0;
          end

          R_NYET: begin
            // Accepted, but not ready for the next one. Like a NAK it is
            // not an error; unlike a NAK the transfer did happen, so it
            // resets the run.
            nyt_n     = 1'b1;
            run_n[ep] = 8'd0;
            wed_n[ep] = 1'b0;
          end
        endcase
      end
    end
  end

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      halt_r  <= '0;
      worst_r <= 8'd0;
      ec_r    <= H_NONE;
      er_r    <= 1'b0;
      sp_r    <= 1'b0;
      for (int j = 0; j < N_EP; j++) begin
        run_r[j] <= 8'd0;
        tog_r[j] <= 1'b0;
        wed_r[j] <= 1'b0;
      end
      n_ack            <= 32'd0;
      n_nak            <= 32'd0;
      n_stall          <= 32'd0;
      n_nyet           <= 32'd0;
      n_wedged         <= 32'd0;
      n_polled_halted  <= 32'd0;
      n_toggle         <= 32'd0;
      n_clear_unhalted <= 32'd0;
      n_clear          <= 32'd0;
    end else begin
      halt_r  <= halt_n;
      worst_r <= worst_n;
      ec_r    <= ec_n;
      er_r    <= er_n;
      sp_r    <= sp_n;
      for (int j = 0; j < N_EP; j++) begin
        run_r[j] <= run_n[j];
        tog_r[j] <= tog_n[j];
        wed_r[j] <= wed_n[j];
      end

      if (ack_n) n_ack   <= n_ack   + 32'd1;
      if (nak_n) n_nak   <= n_nak   + 32'd1;
      if (stl_n) n_stall <= n_stall + 32'd1;
      if (nyt_n) n_nyet  <= n_nyet  + 32'd1;
      if (clr_n) n_clear <= n_clear + 32'd1;

      // The per-cause counters are driven by the SAME pulse as the error,
      // so they sum to it by construction (chapter 23.4).
      if (er_n) begin
        case (ec_n)
          H_WEDGED:         n_wedged         <= n_wedged         + 32'd1;
          H_POLLED_HALTED:  n_polled_halted  <= n_polled_halted  + 32'd1;
          H_TOGGLE:         n_toggle         <= n_toggle         + 32'd1;
          H_CLEAR_UNHALTED: n_clear_unhalted <= n_clear_unhalted + 32'd1;
          default: ;
        endcase
      end
    end
  end
endmodule

-- usb_endpoint_health -- three things that look alike on a trace and mean
-- completely different things.
--
--     ACK    the transfer happened
--     NAK    the endpoint is not ready YET. Flow control, working.
--     STALL  firmware is saying NO, and will keep saying no until
--            somebody explicitly clears it.
--
-- A NAK IS NOT AN ERROR
--
-- On a busy bus a bulk endpoint NAKs constantly -- that is what a bulk
-- endpoint is FOR. Counting each NAK as an error produces thousands of
-- entries per second and a log nobody reads, which is chapter 24.1's
-- false-positive argument in its most concrete form.
--
-- WHAT MATTERS IS THE RUN, NOT THE COUNT
--
-- One NAK is nothing. A thousand CONSECUTIVE NAKs from one endpoint is an
-- endpoint that has stopped working, and no individual NAK in that run is
-- an error. So the measurement is a RUN LENGTH, reset by a successful
-- transfer rather than by time. An endpoint that NAKs a hundred times and
-- then ACKs once is healthy and busy; one that NAKs a hundred times and
-- never ACKs is wedged, and the two are indistinguishable by total count.
--
-- ...AND THE RUN IS PER ENDPOINT
--
-- A single global run counter is reset by ANY endpoint answering, so a
-- wedged endpoint on a device with three healthy ones is invisible: the
-- others keep clearing the counter. The wedged endpoint is exactly the one
-- that never resets it, which is the whole signal, and a shared counter
-- deletes it.
--
-- A STALL IS STICKY, AND POLLING A HALTED ENDPOINT IS THE HOST'S BUG
--
-- A halted endpoint stays halted until CLEAR_FEATURE(ENDPOINT_HALT). It does
-- not clear on the next successful transfer, and a host that keeps issuing
-- tokens to it has not noticed -- which is worth counting SEPARATELY,
-- because it points at the driver rather than at the device.
--
-- THE TOGGLE CATCHES LOSS AND DUPLICATION AND CANNOT TELL THEM APART
--
-- A one-bit sequence number has only one wrong value, so "re-sent" and
-- "lost" produce the same symptom. That is a property of one bit, not a
-- defect here, and it is why chapter 24.3's scoreboard needs a real
-- identity.
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

package usb_eph_pkg is
  -- Response encodings. Named constants rather than an enumerated type,
  -- because the port carries the two bits that appear on the analyser and
  -- an enumeration would hide which value is which.
  constant R_ACK   : std_logic_vector(1 downto 0) := "00";
  constant R_NAK   : std_logic_vector(1 downto 0) := "01";
  constant R_STALL : std_logic_vector(1 downto 0) := "10";
  constant R_NYET  : std_logic_vector(1 downto 0) := "11";

  constant H_NONE           : std_logic_vector(2 downto 0) := "000";
  constant H_WEDGED         : std_logic_vector(2 downto 0) := "001";
  constant H_POLLED_HALTED  : std_logic_vector(2 downto 0) := "010";
  constant H_TOGGLE         : std_logic_vector(2 downto 0) := "011";
  constant H_CLEAR_UNHALTED : std_logic_vector(2 downto 0) := "100";

  type run_array is array (natural range <>) of unsigned(7 downto 0);
end package;

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

entity usb_endpoint_health is
  generic (
    N_EP        : integer := 4;
    NAK_RUN_MAX : integer := 16
  );
  port (
    clk        : in  std_logic;
    rst_n      : in  std_logic;

    xact_valid : in  std_logic;
    ep         : in  std_logic_vector(1 downto 0);
    resp       : in  std_logic_vector(1 downto 0);
    toggle     : in  std_logic;
    clear_halt : in  std_logic;
    eot        : in  std_logic;

    halted      : out std_logic_vector(N_EP-1 downto 0);
    nak_run     : out std_logic_vector(7 downto 0);
    worst_run   : out std_logic_vector(7 downto 0);
    exp_toggle  : out std_logic;
    err_pulse   : out std_logic;
    err_code    : out std_logic_vector(2 downto 0);
    stall_pulse : out std_logic;

    n_ack            : out unsigned(31 downto 0);
    n_nak            : out unsigned(31 downto 0);
    n_stall          : out unsigned(31 downto 0);
    n_nyet           : out unsigned(31 downto 0);
    n_wedged         : out unsigned(31 downto 0);
    n_polled_halted  : out unsigned(31 downto 0);
    n_toggle         : out unsigned(31 downto 0);
    n_clear_unhalted : out unsigned(31 downto 0);
    n_clear          : out unsigned(31 downto 0)
  );
end entity;

architecture rtl of usb_endpoint_health is
  type bit_array is array (natural range <>) of std_logic;

  signal halt_r  : std_logic_vector(N_EP-1 downto 0);
  signal run_r   : run_array(0 to N_EP-1);
  signal tog_r   : bit_array(0 to N_EP-1);
  signal wed_r   : bit_array(0 to N_EP-1);  -- reported wedged: report ONCE
  signal worst_r : unsigned(7 downto 0);
  signal ec_r    : std_logic_vector(2 downto 0);
  signal er_r    : std_logic;
  signal sp_r    : std_logic;

  signal ack_c, nak_c, stl_c, nyt_c, clr_c : unsigned(31 downto 0);
  signal wedg_c, poll_c, tg_c, clru_c      : unsigned(31 downto 0);

  -- The endpoint index. Only two bits wide, so to_integer cannot overflow
  -- INTEGER here -- but the habit is worth keeping: converting a full
  -- 32-bit unsigned aborts the run rather than wrapping.
  signal epi : integer range 0 to N_EP-1;
begin
  epi <= to_integer(unsigned(ep));

  halted      <= halt_r;
  nak_run     <= std_logic_vector(run_r(epi));
  worst_run   <= std_logic_vector(worst_r);
  exp_toggle  <= tog_r(epi);
  err_pulse   <= er_r;
  err_code    <= ec_r;
  stall_pulse <= sp_r;

  n_ack            <= ack_c;
  n_nak            <= nak_c;
  n_stall          <= stl_c;
  n_nyet           <= nyt_c;
  n_wedged         <= wedg_c;
  n_polled_halted  <= poll_c;
  n_toggle         <= tg_c;
  n_clear_unhalted <= clru_c;
  n_clear          <= clr_c;

  process (clk, rst_n)
    variable e      : integer range 0 to N_EP-1;
    variable halt_v : std_logic_vector(N_EP-1 downto 0);
    variable run_v  : run_array(0 to N_EP-1);
    variable tog_v  : bit_array(0 to N_EP-1);
    variable wed_v  : bit_array(0 to N_EP-1);
    variable wrst_v : unsigned(7 downto 0);
    variable ec_v   : std_logic_vector(2 downto 0);
    variable er_v   : std_logic;
    variable sp_v   : std_logic;
  begin
    if rst_n = '0' then
      halt_r  <= (others => '0');
      run_r   <= (others => (others => '0'));
      tog_r   <= (others => '0');
      wed_r   <= (others => '0');
      worst_r <= (others => '0');
      ec_r    <= H_NONE;
      er_r    <= '0';
      sp_r    <= '0';
      ack_c   <= (others => '0');
      nak_c   <= (others => '0');
      stl_c   <= (others => '0');
      nyt_c   <= (others => '0');
      clr_c   <= (others => '0');
      wedg_c  <= (others => '0');
      poll_c  <= (others => '0');
      tg_c    <= (others => '0');
      clru_c  <= (others => '0');
    elsif rising_edge(clk) then
      e      := to_integer(unsigned(ep));
      halt_v := halt_r;
      run_v  := run_r;
      tog_v  := tog_r;
      wed_v  := wed_r;
      wrst_v := worst_r;
      ec_v   := H_NONE;
      er_v   := '0';
      sp_v   := '0';

      if eot = '1' then
        -- Nothing: the counters are the report.
        null;
      elsif clear_halt = '1' then
        -- ---- CLEAR_FEATURE(ENDPOINT_HALT). ----
        if halt_v(e) = '0' then
          -- Clearing a halt that was never set: the driver believes the
          -- endpoint is halted and the device does not. Harmless on the
          -- wire, and a disagreement worth knowing about before it becomes
          -- a lockup.
          er_v   := '1';
          ec_v   := H_CLEAR_UNHALTED;
          clru_c <= clru_c + 1;
        end if;
        halt_v(e) := '0';
        -- A cleared endpoint restarts at DATA0. Chapter 21.1 makes the same
        -- point about a bus reset: the toggle is part of the state that has
        -- to be reset with everything else, and forgetting it costs exactly
        -- one silently-dropped packet.
        tog_v(e)  := '0';
        run_v(e)  := (others => '0');
        wed_v(e)  := '0';
        clr_c     <= clr_c + 1;
      elsif xact_valid = '1' then
        if halt_v(e) = '1' then
          -- ---- The host is still polling a HALTED endpoint. ----
          er_v   := '1';
          ec_v   := H_POLLED_HALTED;
          poll_c <= poll_c + 1;
        else
          case resp is
            when R_ACK =>
              ack_c <= ack_c + 1;
              if toggle /= tog_v(e) then
                -- The sequence broke. WHICH WAY is not recoverable from one
                -- bit -- see the note in the header.
                er_v := '1';
                ec_v := H_TOGGLE;
                tg_c <= tg_c + 1;
              end if;
              tog_v(e) := not tog_v(e);
              -- ---- A successful transfer resets the run. By the transfer,
              -- ---- not by time.
              run_v(e) := (others => '0');
              wed_v(e) := '0';

            when R_NAK =>
              -- NOT an error. Flow control working.
              nak_c <= nak_c + 1;
              if run_v(e) /= x"FF" then
                run_v(e) := run_v(e) + 1;
              end if;
              if run_v(e) > wrst_v then
                wrst_v := run_v(e);
              end if;
              if (run_v(e) >= to_unsigned(NAK_RUN_MAX, 8)) and wed_v(e) = '0'
              then
                -- ---- The RUN is the error, not the NAK -- and it is
                -- ---- reported ONCE. A stuck endpoint NAKs every
                -- ---- microframe, and one report per NAK is the same flood
                -- ---- that counting individual NAKs produced.
                er_v     := '1';
                ec_v     := H_WEDGED;
                wedg_c   <= wedg_c + 1;
                wed_v(e) := '1';
              end if;

            when R_STALL =>
              -- ---- STICKY. Until CLEAR_FEATURE, and nothing else. ----
              stl_c     <= stl_c + 1;
              sp_v      := '1';
              halt_v(e) := '1';
              run_v(e)  := (others => '0');

            when others =>
              -- NYET: accepted, but not ready for the next one. Like a NAK
              -- it is not an error; unlike a NAK the transfer did happen,
              -- so it resets the run.
              nyt_c    <= nyt_c + 1;
              run_v(e) := (others => '0');
              wed_v(e) := '0';
          end case;
        end if;
      end if;

      halt_r  <= halt_v;
      run_r   <= run_v;
      tog_r   <= tog_v;
      wed_r   <= wed_v;
      worst_r <= wrst_v;
      ec_r    <= ec_v;
      er_r    <= er_v;
      sp_r    <= sp_v;
    end if;
  end process;
end architecture;

   endpoint        4   (0..3)
   halted          2   (before the transaction)
   response        4   (ACK / NAK / STALL / NYET)
   toggle matches  2   (yes / no)
                  ---
                   64  transaction situations

   CLEAR_FEATURE x endpoint x halted
                    8  clear situations
                  ---
                   72  and all 72 are REQUIRED

`timescale 1ns/1ps
// Testbench for usb_endpoint_health.
//
// The oracle is a SHADOW MODEL written from the chapter's rules rather than
// from the design's code: per-endpoint run lengths, a sticky halt, a
// report-once wedge latch, and an expected toggle. It is re-derived every
// cycle from the inputs and compared against every output, which is the only
// arrangement that catches a design that is self-consistently wrong.
//
// The exhaustive part is the SITUATION: every (endpoint, halted, response,
// toggle) combination, plus CLEAR_FEATURE against both a halted and an
// unhalted endpoint. 4x2x4x2 + 4x2 = 72, and all 72 are required to have
// been visited before the run is allowed to pass.
module tb_eh_v;

  localparam integer N_EP        = 4;
  localparam integer NAK_RUN_MAX = 16;

  localparam [1:0] R_ACK = 2'd0, R_NAK = 2'd1, R_STALL = 2'd2, R_NYET = 2'd3;

  localparam [2:0] H_NONE           = 3'd0,
                   H_WEDGED         = 3'd1,
                   H_POLLED_HALTED  = 3'd2,
                   H_TOGGLE         = 3'd3,
                   H_CLEAR_UNHALTED = 3'd4;

  reg        clk = 1'b0, rst_n = 1'b0;
  reg        xact_valid = 1'b0, toggle = 1'b0, clear_halt = 1'b0, eot = 1'b0;
  reg  [1:0] ep = 2'd0, resp = 2'd0;

  wire [N_EP-1:0] halted;
  wire [7:0]      nak_run, worst_run;
  wire            exp_toggle, err_pulse, stall_pulse;
  wire [2:0]      err_code;
  wire [31:0] n_ack, n_nak, n_stall, n_nyet, n_wedged,
              n_polled_halted, n_toggle, n_clear_unhalted, n_clear;

  usb_endpoint_health #(.N_EP(N_EP), .NAK_RUN_MAX(NAK_RUN_MAX)) dut (
    .clk(clk), .rst_n(rst_n),
    .xact_valid(xact_valid), .ep(ep), .resp(resp), .toggle(toggle),
    .clear_halt(clear_halt), .eot(eot),
    .halted(halted), .nak_run(nak_run), .worst_run(worst_run),
    .exp_toggle(exp_toggle), .err_pulse(err_pulse), .err_code(err_code),
    .stall_pulse(stall_pulse),
    .n_ack(n_ack), .n_nak(n_nak), .n_stall(n_stall), .n_nyet(n_nyet),
    .n_wedged(n_wedged), .n_polled_halted(n_polled_halted),
    .n_toggle(n_toggle), .n_clear_unhalted(n_clear_unhalted),
    .n_clear(n_clear)
  );

  always #5 clk = ~clk;

  // ---------------- the shadow model ----------------
  reg [N_EP-1:0] m_halt;
  reg [7:0]      m_run  [0:N_EP-1];
  reg            m_tog  [0:N_EP-1];
  reg            m_wed  [0:N_EP-1];
  reg [7:0]      m_worst;
  reg            m_err, m_stall_p;
  reg [2:0]      m_code;
  reg [31:0] m_ack, m_nak, m_stl, m_nyt, m_wedg, m_poll, m_tgerr, m_clru, m_clr;

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

  reg [0:0] reach [0:71];
  integer   n_reach;

  task mark; input integer idx; begin reach[idx] = 1'b1; end endtask

  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=%0d exp=%0d",
                   $time, steps, nm, got, exp);
      end
    end
  endtask

  reg m_halt_pre, m_tog_pre;

  // One modelled cycle. Mirrors the rules, not the RTL.
  task model_step;
    integer j;
    begin
      m_err = 1'b0; m_code = H_NONE; m_stall_p = 1'b0;

      if (eot) begin
        // no state change
      end else if (clear_halt) begin
        if (!m_halt[ep]) begin
          m_err = 1'b1; m_code = H_CLEAR_UNHALTED;
          m_clru = m_clru + 1;
        end
        m_halt[ep] = 1'b0;
        m_tog[ep]  = 1'b0;
        m_run[ep]  = 8'd0;
        m_wed[ep]  = 1'b0;
        m_clr = m_clr + 1;
      end else if (xact_valid) begin
        if (m_halt[ep]) begin
          m_err = 1'b1; m_code = H_POLLED_HALTED;
          m_poll = m_poll + 1;
        end else if (resp == R_ACK) begin
          m_ack = m_ack + 1;
          if (toggle != m_tog[ep]) begin
            m_err = 1'b1; m_code = H_TOGGLE;
            m_tgerr = m_tgerr + 1;
          end
          m_tog[ep] = ~m_tog[ep];
          m_run[ep] = 8'd0;
          m_wed[ep] = 1'b0;
        end else if (resp == R_NAK) begin
          m_nak = m_nak + 1;
          if (m_run[ep] != 8'hFF) m_run[ep] = m_run[ep] + 8'd1;
          if (m_run[ep] > m_worst) m_worst = m_run[ep];
          if ((m_run[ep] >= NAK_RUN_MAX) && !m_wed[ep]) begin
            m_err = 1'b1; m_code = H_WEDGED;
            m_wedg = m_wedg + 1;
            m_wed[ep] = 1'b1;
          end
        end else if (resp == R_STALL) begin
          m_stl = m_stl + 1;
          m_stall_p = 1'b1;
          m_halt[ep] = 1'b1;
          m_run[ep]  = 8'd0;
        end else begin
          m_nyt = m_nyt + 1;
          m_run[ep] = 8'd0;
          m_wed[ep] = 1'b0;
        end
      end

      // --- record the situation reached, for the exhaustiveness proof ---
      if (clear_halt)
        mark(64 + ep*2 + (m_halt_pre ? 1 : 0));
      else if (xact_valid)
        mark(ep*16 + (m_halt_pre ? 8 : 0) + resp*2 + (m_tog_pre ? 1 : 0));

      for (j = 0; j < N_EP; j = j + 1) ;
    end
  endtask

  task check_out;
    begin
      ck("halted",      {28'd0, halted},  {28'd0, m_halt});
      ck("nak_run",     {24'd0, nak_run}, {24'd0, m_run[ep]});
      ck("worst_run",   {24'd0, worst_run}, {24'd0, m_worst});
      ck("exp_toggle",  {31'd0, exp_toggle}, {31'd0, m_tog[ep]});
      ck("err_pulse",   {31'd0, err_pulse},  {31'd0, m_err});
      ck("err_code",    {29'd0, err_code},   {29'd0, m_code});
      ck("stall_pulse", {31'd0, stall_pulse},{31'd0, m_stall_p});
      ck("n_ack",   n_ack,   m_ack);
      ck("n_nak",   n_nak,   m_nak);
      ck("n_stall", n_stall, m_stl);
      ck("n_nyet",  n_nyet,  m_nyt);
      ck("n_wedged",         n_wedged,         m_wedg);
      ck("n_polled_halted",  n_polled_halted,  m_poll);
      ck("n_toggle",         n_toggle,         m_tgerr);
      ck("n_clear_unhalted", n_clear_unhalted, m_clru);
      ck("n_clear",          n_clear,          m_clr);
      // ---- the structural invariant ----
      // Every error is exactly one of the four causes, so the per-cause
      // counters sum to the total. Chapter 23.4's rule: a report that
      // cannot be decomposed cannot be trusted.
      ck("sum", n_wedged + n_polled_halted + n_toggle + n_clear_unhalted,
                m_wedg  + m_poll          + m_tgerr   + m_clru);
    end
  endtask

  task step;
    begin
      m_halt_pre = m_halt[ep];
      m_tog_pre  = (toggle == m_tog[ep]);
      // The caller has already driven the inputs, so the model is stepped
      // and the DUT clocked on the SAME edge. An extra @(negedge) here lets
      // the intervening posedge sample the inputs a second time -- every
      // transaction counted twice, and the shadow model is what says so.
      model_step;
      @(posedge clk);
      #1;
      steps = steps + 1;
      check_out;
    end
  endtask

  task xact; input [1:0] e; input [1:0] r; input tg;
    begin
      xact_valid = 1'b1; clear_halt = 1'b0; eot = 1'b0;
      ep = e; resp = r; toggle = tg;
      step;
    end
  endtask

  task clr; input [1:0] e;
    begin
      xact_valid = 1'b0; clear_halt = 1'b1; eot = 1'b0;
      ep = e;
      step;
    end
  endtask

  task nop;
    begin
      xact_valid = 1'b0; clear_halt = 1'b0; eot = 1'b0;
      step;
    end
  endtask

  // ---- OBSERVE an endpoint without driving it. ----
  //
  // `nak_run` and `exp_toggle` are indexed by the `ep` input, so pointing
  // `ep` at an endpoint during an idle cycle reads that endpoint's state and
  // changes nothing. A per-endpoint counter can only be proved per-endpoint
  // by looking at the endpoints that are NOT being driven -- see phase 4.
  task peek; input [1:0] e;
    begin
      xact_valid = 1'b0; clear_halt = 1'b0; eot = 1'b0;
      ep = e;
      step;
    end
  endtask

  integer i, e, r, t, h, w;
  integer base_wedged, base_poll, base_tg, base_clru;

  initial begin
    for (k = 0; k < 72; k = k + 1) reach[k] = 1'b0;
    m_halt = {N_EP{1'b0}};
    for (k = 0; k < N_EP; k = k + 1) begin
      m_run[k] = 8'd0; m_tog[k] = 1'b0; m_wed[k] = 1'b0;
    end
    m_worst = 8'd0; m_err = 1'b0; m_code = H_NONE; m_stall_p = 1'b0;
    m_ack=0; m_nak=0; m_stl=0; m_nyt=0;
    m_wedg=0; m_poll=0; m_tgerr=0; m_clru=0; m_clr=0;

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

    // ================= PHASE 1 -- the exhaustive situation sweep =========
    //
    // Every (endpoint, halted, response, toggle-matches) combination. The
    // halted axis is set up on the wire, by STALLing or clearing, because a
    // state forced into the design is a state the design never proved it can
    // reach (chapter 22.4).
    for (e = 0; e < N_EP; e = e + 1)
      for (h = 0; h < 2; h = h + 1)
        for (r = 0; r < 4; r = r + 1)
          for (t = 0; t < 2; t = t + 1) begin
            // bring endpoint e to the wanted halt state
            if (h == 1 && !m_halt[e[1:0]]) xact(e[1:0], R_STALL, 1'b0);
            if (h == 0 &&  m_halt[e[1:0]]) clr(e[1:0]);
            // t==1 means "the toggle matches what the model expects"
            xact(e[1:0], r[1:0], (t == 1) ? m_tog[e[1:0]] : ~m_tog[e[1:0]]);
            // leave the endpoint clean for the next combination
            if (m_halt[e[1:0]]) clr(e[1:0]);
          end

    // ================= PHASE 2 -- CLEAR against both halt states =========
    for (e = 0; e < N_EP; e = e + 1) begin
      clr(e[1:0]);                       // unhalted: must report
      xact(e[1:0], R_STALL, 1'b0);
      clr(e[1:0]);                       // halted: must NOT report
    end

    // ================= PHASE 3 -- the wedge boundary =====================
    //
    // NAK_RUN_MAX-1 NAKs must be silent; the NAK_RUN_MAX'th must fire; every
    // NAK after it must be silent again (report ONCE); and an ACK must
    // re-arm the latch so a second wedge is reported.
    for (e = 0; e < N_EP; e = e + 1) begin
      clr(e[1:0]);                        // known state, toggle at 0
      base_wedged = m_wedg;
      for (i = 0; i < NAK_RUN_MAX - 1; i = i + 1) xact(e[1:0], R_NAK, 1'b0);
      if (m_wedg != base_wedged) begin
        errors = errors + 1;
        $display("FAIL early wedge at ep=%0d", e);
      end
      xact(e[1:0], R_NAK, 1'b0);          // the threshold
      if (m_wedg != base_wedged + 1) begin
        errors = errors + 1;
        $display("FAIL threshold wedge ep=%0d", e);
      end
      repeat (40) xact(e[1:0], R_NAK, 1'b0);   // still ONE report
      if (m_wedg != base_wedged + 1) begin
        errors = errors + 1;
        $display("FAIL repeated wedge reports ep=%0d", e);
      end
      xact(e[1:0], R_ACK, m_tog[e[1:0]]); // answered: run resets, latch arms
      if (m_run[e[1:0]] != 0) begin
        errors = errors + 1;
        $display("FAIL run not reset by ACK ep=%0d", e);
      end
      repeat (NAK_RUN_MAX) xact(e[1:0], R_NAK, 1'b0);
      if (m_wedg != base_wedged + 2) begin
        errors = errors + 1;
        $display("FAIL wedge not re-armed ep=%0d", e);
      end
      // A NYET also clears the run -- accepted, just not ready for more.
      xact(e[1:0], R_NYET, 1'b0);
      if (m_run[e[1:0]] != 0) begin
        errors = errors + 1;
        $display("FAIL run not reset by NYET ep=%0d", e);
      end
    end

    // ================= PHASE 4 -- per-endpoint independence ==============
    //
    // The point of a PER-ENDPOINT run. Endpoint 0 NAKs forever while 1, 2
    // and 3 answer normally. A single shared counter is reset by every one
    // of those answers, so the wedged endpoint never reaches the threshold
    // and the one real fault on the bus is the one thing not reported.
    for (e = 0; e < N_EP; e = e + 1) clr(e[1:0]);
    base_wedged = m_wedg;
    for (i = 0; i < 3 * NAK_RUN_MAX; i = i + 1) begin
      xact(2'd0, R_NAK, 1'b0);
      // Read the three healthy endpoints BEFORE they answer. Without this,
      // a run counter shared across the whole device is invisible here: the
      // corruption lands on endpoints 1..3, and each one's own ACK wipes it
      // before anything looks. The wedge COUNT on endpoint 0 is unchanged,
      // so the phase written to catch a shared counter passes.
      peek(2'd1); peek(2'd2); peek(2'd3);
      xact(2'd1, R_ACK, m_tog[1]);
      xact(2'd2, R_ACK, m_tog[2]);
      xact(2'd3, R_NYET, 1'b0);
    end
    if (m_wedg != base_wedged + 1) begin
      errors = errors + 1;
      $display("FAIL interleaved wedge: got %0d expected %0d",
               m_wedg - base_wedged, 1);
    end

    // ================= PHASE 5 -- the toggle sequence ====================
    //
    // A long correct alternation must be silent; one wrong toggle must fire
    // exactly once; and the design must RESYNC afterwards rather than
    // reporting every subsequent transfer.
    for (e = 0; e < N_EP; e = e + 1) clr(e[1:0]);
    base_tg = m_tgerr;
    for (i = 0; i < 64; i = i + 1) xact(2'd1, R_ACK, m_tog[1]);
    if (m_tgerr != base_tg) begin
      errors = errors + 1;
      $display("FAIL toggle false positive on a correct sequence");
    end
    xact(2'd1, R_ACK, ~m_tog[1]);        // one break
    if (m_tgerr != base_tg + 1) begin
      errors = errors + 1;
      $display("FAIL toggle break not reported");
    end
    for (i = 0; i < 32; i = i + 1) xact(2'd1, R_ACK, m_tog[1]);
    if (m_tgerr != base_tg + 1) begin
      errors = errors + 1;
      $display("FAIL toggle did not resync (%0d extra)",
               m_tgerr - base_tg - 1);
    end

    // ================= PHASE 6 -- the halt is STICKY =====================
    //
    // A STALL, then a long run of successful-looking traffic. Nothing about
    // an ACK, a NYET or the passage of time clears a halt: only
    // CLEAR_FEATURE does, and until it arrives every poll is the host's bug.
    for (e = 0; e < N_EP; e = e + 1) clr(e[1:0]);
    base_poll = m_poll;
    xact(2'd2, R_STALL, 1'b0);
    for (i = 0; i < 50; i = i + 1) xact(2'd2, (i[1:0]), m_tog[2]);
    if (!m_halt[2]) begin
      errors = errors + 1;
      $display("FAIL halt did not stick");
    end
    if (m_poll != base_poll + 50) begin
      errors = errors + 1;
      $display("FAIL polled-halted count %0d expected 50",
               m_poll - base_poll);
    end
    clr(2'd2);
    if (m_halt[2]) begin
      errors = errors + 1;
      $display("FAIL CLEAR_FEATURE did not unhalt");
    end
    // ...and a cleared endpoint restarts at DATA0.
    if (m_tog[2] !== 1'b0) begin
      errors = errors + 1;
      $display("FAIL toggle not reset by CLEAR_FEATURE");
    end

    // The two random phases are switchable, because a mutation score is
    // only interesting once it is DECOMPOSED. A score that is identical
    // with and without them was earned entirely by directed stimulus, and
    // the random cycles -- however many there are -- bought nothing.
    // Phases 1 and 2 already visit all 72 situations, so the exhaustiveness
    // proof still holds with the random phases compiled out.
`ifndef DIRECTED_ONLY
    // ================= PHASE 7 -- random =================================
    //
    // The response is drawn ONCE into a variable. Written as a chain of
    // ternaries -- `($random%100 < 55) ? R_NAK : ($random%100 < 60) ? ...`
    // -- each arm draws a NEW number, so the branches are independent 55%
    // and 60% events rather than the nested distribution the code appears
    // to describe. It still runs, still passes, and quietly delivers a mix
    // nobody chose.
    //
    // The toggle is mostly CORRECT. A 50/50 toggle makes half of all ACKs a
    // sequence error, which is not a bus and, more to the point, makes a
    // dropped toggle check impossible to distinguish from a working one:
    // when the error is the common case, the check that finds it is no
    // longer doing any work.
    for (i = 0; i < 40000; i = i + 1) begin
      w = $unsigned($random) % 100;
      e = $unsigned($random) % N_EP;
      if (w < 14) begin
        clr(e[1:0]);
      end else if (w < 17) begin
        nop;
      end else begin
        r = $unsigned($random) % 100;
        t = ($unsigned($random) % 100) < 88;   // 12% break the sequence
        xact(e[1:0],
             (r < 50) ? R_NAK : (r < 53) ? R_STALL :
             (r < 63) ? R_NYET : R_ACK,
             (t == 1) ? m_tog[e[1:0]] : ~m_tog[e[1:0]]);
      end
    end

    // ================= PHASE 8 -- random, with a SICK endpoint ===========
    //
    // Phase 7 produced nine wedges and every one of them came from the
    // directed phases. With four endpoints and a 50% NAK rate, sixteen
    // consecutive NAKs on the SAME endpoint is a ~1-in-10^12 event: uniform
    // random stimulus does not produce a wedge, because a wedge is
    // SUSTAINED SILENCE and random traffic is the opposite of sustained.
    //
    // That is the same result as chapter 24.1's -- a liveness failure has
    // to be constructed -- and it is why the fix is not "more random
    // cycles". It is a stimulus that MODELS the fault: one endpoint at a
    // time is sick, answering only occasionally, while the others behave.
    // The sick one rotates, so every endpoint is both the fault and the
    // background noise.
    for (e = 0; e < N_EP; e = e + 1) clr(e[1:0]);
    for (i = 0; i < 20000; i = i + 1) begin
      if ((i % 201) == 0) h = $unsigned($random) % N_EP;  // rotate the sick one
      w = $unsigned($random) % 100;
      e = $unsigned($random) % N_EP;
      if (w < 3) begin
        clr(e[1:0]);
      end else if (e == h) begin
        // The sick endpoint: NAKs almost always, answers once in a while.
        r = $unsigned($random) % 100;
        xact(e[1:0], (r < 94) ? R_NAK : R_ACK, m_tog[e[1:0]]);
      end else begin
        r = $unsigned($random) % 100;
        t = ($unsigned($random) % 100) < 92;
        xact(e[1:0],
             (r < 20) ? R_NAK : (r < 22) ? R_STALL :
             (r < 32) ? R_NYET : R_ACK,
             (t == 1) ? m_tog[e[1:0]] : ~m_tog[e[1:0]]);
      end
    end

`endif

    // ================= the exhaustiveness proof ==========================
    n_reach = 0;
    for (k = 0; k < 72; k = k + 1) n_reach = n_reach + reach[k];
    if (n_reach != 72) begin
      errors = errors + 1;
      $display("FAIL situation reach %0d/72", n_reach);
      for (k = 0; k < 72; k = k + 1)
        if (!reach[k]) $display("  unreached situation %0d", k);
    end

    $display("steps=%0d checks=%0d reach=%0d/72 errors=%0d",
             steps, checks, n_reach, errors);
    $display("ack=%0d nak=%0d stall=%0d nyet=%0d clear=%0d",
             n_ack, n_nak, n_stall, n_nyet, n_clear);
    $display("wedged=%0d polled_halted=%0d toggle=%0d clear_unhalted=%0d",
             n_wedged, n_polled_halted, n_toggle, n_clear_unhalted);
    $display("%0s: %0d errors in %0d checks",
             (errors == 0) ? "PASS" : "FAIL", errors, checks);
    $finish;
  end
endmodule

`timescale 1ns/1ps
// Testbench for usb_endpoint_health (SystemVerilog).
//
// The oracle is a SHADOW MODEL written from the chapter's rules rather than
// from the design's code, and re-derived every cycle from the inputs. Every
// output is compared against it, which is the only arrangement that catches
// a design that is self-consistently wrong.
//
// The exhaustive part is the SITUATION: every (endpoint, halted, response,
// toggle-matches) combination plus CLEAR_FEATURE against both halt states.
// 4x2x4x2 + 4x2 = 72, and all 72 must have been visited before the run is
// allowed to pass.
module tb_eh_sv;
  import usb_eph_pkg::*;

  localparam int N_EP        = 4;
  localparam int NAK_RUN_MAX = 16;

  logic       clk = 1'b0, rst_n = 1'b0;
  logic       xact_valid = 1'b0, toggle = 1'b0, clear_halt = 1'b0, eot = 1'b0;
  logic [1:0] ep = 2'd0;
  resp_e      resp = R_ACK;

  logic [N_EP-1:0] halted;
  logic [7:0]      nak_run, worst_run;
  logic            exp_toggle, err_pulse, stall_pulse;
  health_e         err_code;
  logic [31:0] n_ack, n_nak, n_stall, n_nyet, n_wedged,
               n_polled_halted, n_toggle, n_clear_unhalted, n_clear;

  usb_endpoint_health #(.N_EP(N_EP), .NAK_RUN_MAX(NAK_RUN_MAX)) dut (
    .clk(clk), .rst_n(rst_n),
    .xact_valid(xact_valid), .ep(ep), .resp(resp), .toggle(toggle),
    .clear_halt(clear_halt), .eot(eot),
    .halted(halted), .nak_run(nak_run), .worst_run(worst_run),
    .exp_toggle(exp_toggle), .err_pulse(err_pulse), .err_code(err_code),
    .stall_pulse(stall_pulse),
    .n_ack(n_ack), .n_nak(n_nak), .n_stall(n_stall), .n_nyet(n_nyet),
    .n_wedged(n_wedged), .n_polled_halted(n_polled_halted),
    .n_toggle(n_toggle), .n_clear_unhalted(n_clear_unhalted),
    .n_clear(n_clear)
  );

  always #5 clk = ~clk;

  // ---------------- the shadow model ----------------
  //
  // Module scope, not a class. A class oracle is the UVM shape and the right
  // one on a commercial simulator; Icarus reaches its limits on class
  // properties quickly, and two of the ways it does so are worth knowing
  // because neither produces a usable message:
  //
  //   * an unpacked class array declared with a SIZE (`bit [7:0] run [N_EP]`)
  //     aborts the code generator in draw_class.c with no line number, while
  //     the identical descending RANGE (`run [N_EP-1:0]`) compiles;
  //   * a PACKED class property cannot be indexed inside a condition, though
  //     it can be indexed as an assignment target -- so the failure shows up
  //     on two lines out of six and reads like a typo.
  //
  // The UVM formulation of this same oracle is listed later in the chapter.
  // What matters for correctness is that the model is written from the
  // rules rather than from the RTL, and that is true either way.
  logic [N_EP-1:0] m_halt;
  logic [7:0]      m_run [N_EP];
  logic            m_tog [N_EP];
  logic            m_wed [N_EP];
  logic [7:0]      m_worst;
  logic            m_err, m_stall_p;
  health_e         m_code;
  int unsigned m_ack, m_nak, m_stl, m_nyt;
  int unsigned m_wedg, m_poll, m_tgerr, m_clru, m_clr;

  // One modelled cycle, derived from the chapter's rules rather than from
  // the RTL. Written independently is the whole point: an oracle copied
  // from the design agrees with the design's bugs.
  task automatic model_step;
    m_err = 1'b0; m_code = H_NONE; m_stall_p = 1'b0;

    if (eot) begin
      // no state change
    end else if (clear_halt) begin
      if (!m_halt[ep]) begin
        m_err = 1'b1; m_code = H_CLEAR_UNHALTED; m_clru++;
      end
      m_halt[ep] = 1'b0;
      m_tog[ep]  = 1'b0;
      m_run[ep]  = 8'd0;
      m_wed[ep]  = 1'b0;
      m_clr++;
    end else if (xact_valid) begin
      if (m_halt[ep]) begin
        m_err = 1'b1; m_code = H_POLLED_HALTED; m_poll++;
      end else if (resp == R_ACK) begin
        m_ack++;
        if (toggle != m_tog[ep]) begin
          m_err = 1'b1; m_code = H_TOGGLE; m_tgerr++;
        end
        m_tog[ep] = ~m_tog[ep];
        m_run[ep] = 8'd0;
        m_wed[ep] = 1'b0;
      end else if (resp == R_NAK) begin
        m_nak++;
        if (m_run[ep] != 8'hFF) m_run[ep] = m_run[ep] + 8'd1;
        if (m_run[ep] > m_worst) m_worst = m_run[ep];
        if ((m_run[ep] >= 8'(NAK_RUN_MAX)) && !m_wed[ep]) begin
          m_err = 1'b1; m_code = H_WEDGED; m_wedg++; m_wed[ep] = 1'b1;
        end
      end else if (resp == R_STALL) begin
        m_stl++; m_stall_p = 1'b1; m_halt[ep] = 1'b1; m_run[ep] = 8'd0;
      end else begin
        m_nyt++; m_run[ep] = 8'd0; m_wed[ep] = 1'b0;
      end
    end
  endtask

  int errors = 0, checks = 0, steps = 0;
  bit reach [72];
  int n_reach;
  bit m_halt_pre, m_tog_pre;

  task automatic ck(string nm, int unsigned got, int unsigned exp);
    checks++;
    if (got !== exp) begin
      errors++;
      if (errors < 25)
        $display("FAIL t=%0t step=%0d %0s got=%0d exp=%0d",
                 $time, steps, nm, got, exp);
    end
  endtask

  task automatic check_out;
    ck("halted",      halted,     m_halt);
    ck("nak_run",     nak_run,    m_run[ep]);
    ck("worst_run",   worst_run,  m_worst);
    ck("exp_toggle",  exp_toggle, m_tog[ep]);
    ck("err_pulse",   err_pulse,  m_err);
    ck("err_code",    err_code,   m_code);
    ck("stall_pulse", stall_pulse, m_stall_p);
    ck("n_ack",   n_ack,   m_ack);
    ck("n_nak",   n_nak,   m_nak);
    ck("n_stall", n_stall, m_stl);
    ck("n_nyet",  n_nyet,  m_nyt);
    ck("n_wedged",         n_wedged,         m_wedg);
    ck("n_polled_halted",  n_polled_halted,  m_poll);
    ck("n_toggle",         n_toggle,         m_tgerr);
    ck("n_clear_unhalted", n_clear_unhalted, m_clru);
    ck("n_clear",          n_clear,          m_clr);
    // Every error is exactly one of four causes, so the per-cause counters
    // sum to the total. A report that cannot be decomposed cannot be
    // trusted (chapter 23.4).
    ck("sum", n_wedged + n_polled_halted + n_toggle + n_clear_unhalted,
              m_wedg + m_poll        + m_tgerr + m_clru);
  endtask

  task automatic step_one;
    m_halt_pre = m_halt[ep];
    m_tog_pre  = (toggle == m_tog[ep]);
    // The caller has already driven the inputs, so the model is stepped and
    // the DUT clocked on the SAME edge. An extra @(negedge) here lets the
    // intervening posedge sample the inputs a second time -- every
    // transaction counted twice, and the shadow model is what says so.
    model_step;
    if (clear_halt)
      reach[64 + ep*2 + (m_halt_pre ? 1 : 0)] = 1'b1;
    else if (xact_valid)
      reach[ep*16 + (m_halt_pre ? 8 : 0) + int'(resp)*2 + (m_tog_pre ? 1 : 0)]
        = 1'b1;
    @(posedge clk);
    #1;
    steps++;
    check_out;
  endtask

  task automatic xact(bit [1:0] e, resp_e r, bit tg);
    xact_valid = 1'b1; clear_halt = 1'b0; eot = 1'b0;
    ep = e; resp = r; toggle = tg;
    step_one;
  endtask

  task automatic clr(bit [1:0] e);
    xact_valid = 1'b0; clear_halt = 1'b1; eot = 1'b0;
    ep = e;
    step_one;
  endtask

  task automatic nop;
    xact_valid = 1'b0; clear_halt = 1'b0; eot = 1'b0;
    step_one;
  endtask

  // ---- OBSERVE an endpoint without driving it. ----
  //
  // `nak_run` and `exp_toggle` are indexed by the `ep` input, so pointing
  // `ep` at an endpoint during an idle cycle reads that endpoint's state and
  // changes nothing. A per-endpoint counter can only be proved per-endpoint
  // by looking at the endpoints that are NOT being driven -- see phase 4.
  task automatic peek(bit [1:0] e);
    xact_valid = 1'b0; clear_halt = 1'b0; eot = 1'b0;
    ep = e;
    step_one;
  endtask

  int i, e, r, t, h, w;
  int base_wedged, base_poll, base_tg;

  initial begin
    foreach (reach[k]) reach[k] = 1'b0;
    m_halt = '0; m_worst = 8'd0; m_err = 1'b0; m_code = H_NONE;
    m_stall_p = 1'b0;
    for (int j = 0; j < N_EP; j++) begin
      m_run[j] = 8'd0; m_tog[j] = 1'b0; m_wed[j] = 1'b0;
    end
    m_ack = 0; m_nak = 0; m_stl = 0; m_nyt = 0;
    m_wedg = 0; m_poll = 0; m_tgerr = 0; m_clru = 0; m_clr = 0;

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

    // ================= PHASE 1 -- the exhaustive situation sweep =========
    //
    // The halted axis is set up ON THE WIRE, by STALLing or clearing,
    // because a state forced into the design is a state the design never
    // proved it can reach (chapter 22.4).
    for (e = 0; e < N_EP; e++)
      for (h = 0; h < 2; h++)
        for (r = 0; r < 4; r++)
          for (t = 0; t < 2; t++) begin
            if (h == 1 && !m_halt[e[1:0]]) xact(e[1:0], R_STALL, 1'b0);
            if (h == 0 &&  m_halt[e[1:0]]) clr(e[1:0]);
            xact(e[1:0], resp_e'(r[1:0]),
                 (t == 1) ? m_tog[e[1:0]] : ~m_tog[e[1:0]]);
            if (m_halt[e[1:0]]) clr(e[1:0]);
          end

    // ================= PHASE 2 -- CLEAR against both halt states =========
    for (e = 0; e < N_EP; e++) begin
      clr(e[1:0]);                       // unhalted: must report
      xact(e[1:0], R_STALL, 1'b0);
      clr(e[1:0]);                       // halted: must NOT report
    end

    // ================= PHASE 3 -- the wedge boundary =====================
    //
    // NAK_RUN_MAX-1 NAKs must be silent; the NAK_RUN_MAX'th must fire; every
    // NAK after it must be silent again (report ONCE); and an ACK must
    // re-arm the latch so a second wedge is reported.
    for (e = 0; e < N_EP; e++) begin
      clr(e[1:0]);
      base_wedged = m_wedg;
      for (i = 0; i < NAK_RUN_MAX - 1; i++) xact(e[1:0], R_NAK, 1'b0);
      if (m_wedg != base_wedged) begin
        errors++; $display("FAIL early wedge at ep=%0d", e);
      end
      xact(e[1:0], R_NAK, 1'b0);
      if (m_wedg != base_wedged + 1) begin
        errors++; $display("FAIL threshold wedge ep=%0d", e);
      end
      repeat (40) xact(e[1:0], R_NAK, 1'b0);
      if (m_wedg != base_wedged + 1) begin
        errors++; $display("FAIL repeated wedge reports ep=%0d", e);
      end
      xact(e[1:0], R_ACK, m_tog[e[1:0]]);
      if (m_run[e[1:0]] != 0) begin
        errors++; $display("FAIL run not reset by ACK ep=%0d", e);
      end
      repeat (NAK_RUN_MAX) xact(e[1:0], R_NAK, 1'b0);
      if (m_wedg != base_wedged + 2) begin
        errors++; $display("FAIL wedge not re-armed ep=%0d", e);
      end
      xact(e[1:0], R_NYET, 1'b0);
      if (m_run[e[1:0]] != 0) begin
        errors++; $display("FAIL run not reset by NYET ep=%0d", e);
      end
    end

    // ================= PHASE 4 -- per-endpoint independence ==============
    //
    // Endpoint 0 NAKs forever while 1, 2 and 3 answer normally. A single
    // shared counter is reset by every one of those answers, so the wedged
    // endpoint never reaches the threshold and the one real fault on the
    // bus is the one thing not reported.
    for (e = 0; e < N_EP; e++) clr(e[1:0]);
    base_wedged = m_wedg;
    for (i = 0; i < 3 * NAK_RUN_MAX; i++) begin
      xact(2'd0, R_NAK, 1'b0);
      // Read the three healthy endpoints BEFORE they answer. Without this,
      // a run counter shared across the whole device is invisible here: the
      // corruption lands on endpoints 1..3, and each one's own ACK wipes it
      // before anything looks. The wedge COUNT on endpoint 0 is unchanged,
      // so the phase written to catch a shared counter passes.
      peek(2'd1); peek(2'd2); peek(2'd3);
      xact(2'd1, R_ACK, m_tog[1]);
      xact(2'd2, R_ACK, m_tog[2]);
      xact(2'd3, R_NYET, 1'b0);
    end
    if (m_wedg != base_wedged + 1) begin
      errors++;
      $display("FAIL interleaved wedge: got %0d expected 1",
               m_wedg - base_wedged);
    end

    // ================= PHASE 5 -- the toggle sequence ====================
    for (e = 0; e < N_EP; e++) clr(e[1:0]);
    base_tg = m_tgerr;
    for (i = 0; i < 64; i++) xact(2'd1, R_ACK, m_tog[1]);
    if (m_tgerr != base_tg) begin
      errors++; $display("FAIL toggle false positive on a correct sequence");
    end
    xact(2'd1, R_ACK, ~m_tog[1]);
    if (m_tgerr != base_tg + 1) begin
      errors++; $display("FAIL toggle break not reported");
    end
    for (i = 0; i < 32; i++) xact(2'd1, R_ACK, m_tog[1]);
    if (m_tgerr != base_tg + 1) begin
      errors++;
      $display("FAIL toggle did not resync (%0d extra)",
               m_tgerr - base_tg - 1);
    end

    // ================= PHASE 6 -- the halt is STICKY =====================
    for (e = 0; e < N_EP; e++) clr(e[1:0]);
    base_poll = m_poll;
    xact(2'd2, R_STALL, 1'b0);
    for (i = 0; i < 50; i++) xact(2'd2, resp_e'(i[1:0]), m_tog[2]);
    if (!m_halt[2]) begin errors++; $display("FAIL halt did not stick"); end
    if (m_poll != base_poll + 50) begin
      errors++;
      $display("FAIL polled-halted count %0d expected 50",
               m_poll - base_poll);
    end
    clr(2'd2);
    if (m_halt[2]) begin
      errors++; $display("FAIL CLEAR_FEATURE did not unhalt");
    end
    if (m_tog[2] !== 1'b0) begin
      errors++; $display("FAIL toggle not reset by CLEAR_FEATURE");
    end

    // ================= PHASE 7 -- random =================================
    //
    // The response is drawn ONCE into a variable. Written as a chain of
    // ternaries each arm draws a NEW number, so the branches become
    // independent events rather than the nested distribution the code
    // appears to describe -- it still runs, still passes, and quietly
    // delivers a mix nobody chose.
    //
    // The toggle is mostly CORRECT: a 50/50 toggle makes half of all ACKs a
    // sequence error, and when the error is the common case the check that
    // finds it is no longer doing any work.
    for (i = 0; i < 40000; i++) begin
      w = $unsigned($random) % 100;
      e = $unsigned($random) % N_EP;
      if (w < 14) begin
        clr(e[1:0]);
      end else if (w < 17) begin
        nop;
      end else begin
        r = $unsigned($random) % 100;
        t = (($unsigned($random) % 100) < 88) ? 1 : 0;
        if (r < 50)      xact(e[1:0], R_NAK,
                              (t == 1) ? m_tog[e[1:0]] : ~m_tog[e[1:0]]);
        else if (r < 53) xact(e[1:0], R_STALL,
                              (t == 1) ? m_tog[e[1:0]] : ~m_tog[e[1:0]]);
        else if (r < 63) xact(e[1:0], R_NYET,
                              (t == 1) ? m_tog[e[1:0]] : ~m_tog[e[1:0]]);
        else             xact(e[1:0], R_ACK,
                              (t == 1) ? m_tog[e[1:0]] : ~m_tog[e[1:0]]);
      end
    end

    // ================= PHASE 8 -- random, with a SICK endpoint ===========
    //
    // Phase 7 produces wedges only where the directed phases put them. With
    // four endpoints and a 50% NAK rate, sixteen consecutive NAKs on the
    // SAME endpoint is a ~1-in-10^12 event: uniform random stimulus does
    // not produce a wedge, because a wedge is SUSTAINED SILENCE and random
    // traffic is the opposite of sustained. The fix is not more cycles; it
    // is a stimulus that MODELS the fault -- one endpoint at a time is
    // sick, answering only occasionally, and the sick one rotates.
    for (e = 0; e < N_EP; e++) clr(e[1:0]);
    for (i = 0; i < 20000; i++) begin
      if ((i % 201) == 0) h = $unsigned($random) % N_EP;
      w = $unsigned($random) % 100;
      e = $unsigned($random) % N_EP;
      if (w < 3) begin
        clr(e[1:0]);
      end else if (e == h) begin
        r = $unsigned($random) % 100;
        if (r < 94) xact(e[1:0], R_NAK, m_tog[e[1:0]]);
        else        xact(e[1:0], R_ACK, m_tog[e[1:0]]);
      end else begin
        r = $unsigned($random) % 100;
        t = (($unsigned($random) % 100) < 92) ? 1 : 0;
        if (r < 20)      xact(e[1:0], R_NAK,
                              (t == 1) ? m_tog[e[1:0]] : ~m_tog[e[1:0]]);
        else if (r < 22) xact(e[1:0], R_STALL,
                              (t == 1) ? m_tog[e[1:0]] : ~m_tog[e[1:0]]);
        else if (r < 32) xact(e[1:0], R_NYET,
                              (t == 1) ? m_tog[e[1:0]] : ~m_tog[e[1:0]]);
        else             xact(e[1:0], R_ACK,
                              (t == 1) ? m_tog[e[1:0]] : ~m_tog[e[1:0]]);
      end
    end

    // ================= the exhaustiveness proof ==========================
    n_reach = 0;
    foreach (reach[k]) n_reach += reach[k];
    if (n_reach != 72) begin
      errors++;
      $display("FAIL situation reach %0d/72", n_reach);
      foreach (reach[k]) if (!reach[k]) $display("  unreached situation %0d", k);
    end

    $display("steps=%0d checks=%0d reach=%0d/72 errors=%0d",
             steps, checks, n_reach, errors);
    $display("ack=%0d nak=%0d stall=%0d nyet=%0d clear=%0d",
             n_ack, n_nak, n_stall, n_nyet, n_clear);
    $display("wedged=%0d polled_halted=%0d toggle=%0d clear_unhalted=%0d",
             n_wedged, n_polled_halted, n_toggle, n_clear_unhalted);
    $display("%0s: %0d errors in %0d checks",
             (errors == 0) ? "PASS" : "FAIL", errors, checks);
    $finish;
  end
endmodule