Enumeration Failures

    1  ATTACH        VBUS appears
    2  RESET         the host drives SE0
    3  GET_DESC_8    GET_DESCRIPTOR(Device, 8 bytes) at address 0
    4  RESET_2       the host resets again
    5  SET_ADDRESS   the device gets a unique address
    6  GET_DESC_DEV  the full device descriptor
    7  GET_DESC_C9   GET_DESCRIPTOR(Config, 9 bytes)
    8  GET_DESC_CFG  the full configuration descriptor
    9  SET_CONFIG    SET_CONFIGURATION
   10  ENUMERATED

   a STEP FAILURE   the device answered, and said no
                    -> firmware is running and has an opinion

   a TIMEOUT        the device did not answer at all
                    -> firmware is not running, or is stuck

   Nothing else in the tracker fires when NOTHING happens.

  usb_enum_tracker  #(N_STEP = 10, RETRY_MAX = 3, STEP_TO = 12)

  inputs                    outputs
  ------                    -------
  step_valid / step_id      cur_step   where it is NOW
  step_ok                   max_step   the furthest EVER -- the one
  bus_reset   a retry                  number that survives the retries
  detach      a new device  fail_step / fail_reason
  bus_idle                  retries_at_max
                            complete

  n_steps n_resets n_detach n_step_fail n_timeout
  n_skip n_regress n_exhausted n_badstep n_complete

// usb_enum_tracker -- why a failing enumeration tells you nothing, and the
// one change to the instrumentation that makes it tell you everything.
//
// ENUMERATION IS A SEQUENCE, AND THE FAILING STEP IS THE DIAGNOSIS
//
//   1  ATTACH        VBUS appears
//   2  RESET         the host drives SE0
//   3  GET_DESC_8    GET_DESCRIPTOR(Device, 8 bytes) at address 0
//   4  RESET_2       the host resets again
//   5  SET_ADDRESS   the device gets a unique address
//   6  GET_DESC_DEV  the full device descriptor
//   7  GET_DESC_C9   GET_DESCRIPTOR(Config, 9 bytes)
//   8  GET_DESC_CFG  the full configuration descriptor
//   9  SET_CONFIG    SET_CONFIGURATION
//  10  ENUMERATED
//
// Every one of those steps fails for a different reason, and knowing WHICH
// one is most of the debug. "The device does not enumerate" is not a bug
// report; "it never gets past SET_ADDRESS" is.
//
// AND HERE IS WHY THE OBVIOUS INSTRUMENTATION TELLS YOU NOTHING
//
// When enumeration fails, the host does not stop. It RESETS THE BUS and
// tries again, from step 1. It does that three times, and then it gives up
// and reports "device not recognised".
//
// So a tracker that records the CURRENT step -- which is the obvious thing
// to build, and what a state machine naturally gives you -- reads ATTACH at
// the end of every failed enumeration, no matter where the failure was. The
// state at the end is not the failure; it is the third retry's first step.
//
//     RECORD THE FURTHEST STEP EVER REACHED, AND DO NOT
//     LET A BUS RESET CLEAR IT.
//
// That one register is the difference between "the device does not work"
// and "it fails at step 6, three times, and step 6 is the full device
// descriptor". Those are the same bug and two completely different days.
//
// RETRIES ARE PER STEP, NOT GLOBAL
//
// A device that fails at step 5 three times has a different bug from one
// that fails at 5, then at 9, then at 5 again. The first is deterministic
// and cheap to find; the second is marginal, and probably timing or power.
// A single global retry counter loses that distinction entirely, and it is
// the distinction that decides which instrument you pick up next.
//
// A SKIPPED STEP IS AS DIAGNOSTIC AS A FAILED ONE
//
// The host does not skip steps by accident. If step 7 arrives when step 5
// was the last one seen, the host has abandoned something -- usually
// because a descriptor it read earlier told it not to bother. That is a
// finding, and it points at the descriptor rather than at the step that
// appears to be missing.
//
// AND A STEP THAT NEVER COMPLETES IS NOT A STEP THAT FAILED
//
// A failure is an answer. Silence is not. They have different causes --
// a STALL is firmware saying no, a timeout is firmware not running -- and
// nothing else in this block fires when nothing happens, which is the same
// argument the protocol checker of chapter 24.1 makes about its own
// timeout.
module usb_enum_tracker #(
  parameter integer N_STEP    = 10,  // steps in a complete enumeration
  parameter integer RETRY_MAX = 3,   // attempts at one step before giving up
  parameter integer STEP_TO   = 12   // idle cycles before a step is dead
) (
  input  wire       clk,
  input  wire       rst_n,

  input  wire       step_valid,  // a step completed, one way or the other
  input  wire [3:0] step_id,     // 1..N_STEP
  input  wire       step_ok,     // it succeeded
  input  wire       bus_reset,   // the host reset the bus: back to step 1
  input  wire       detach,      // VBUS gone: a different device next time
  input  wire       bus_idle,    // nothing is happening on the wire
  input  wire       eot,

  output wire [3:0] cur_step,    // where enumeration is NOW
  output wire [3:0] max_step,    // the furthest step EVER reached -- the
                                 // one number that survives the retries
  output wire [3:0] fail_step,   // where it went wrong
  output wire [2:0] fail_reason,
  output wire [3:0] retries_at_max,
  output wire [4:0] step_age,
  output wire       complete,
  output wire       event_pulse,

  output reg [31:0] n_steps,
  output reg [31:0] n_resets,
  output reg [31:0] n_detach,
  output reg [31:0] n_step_fail,
  output reg [31:0] n_timeout,
  output reg [31:0] n_skip,
  output reg [31:0] n_regress,
  output reg [31:0] n_exhausted,
  output reg [31:0] n_badstep,
  output reg [31:0] n_complete
);

  localparam [2:0] F_NONE      = 3'd0,
                   F_STEP_FAIL = 3'd1,  // the step returned an error
                   F_TIMEOUT   = 3'd2,  // the step never returned at all
                   F_SKIP      = 3'd3,  // the host jumped past a step
                   F_REGRESS   = 3'd4,  // a step went backwards, no reset
                   F_EXHAUSTED = 3'd5,  // RETRY_MAX attempts at one step
                   F_BADSTEP   = 3'd6;  // a step number the sequence has no
                                        // room for -- the decoder is wrong,
                                        // and letting it through corrupts
                                        // the diagnosis rather than adding
                                        // to it

  reg [3:0] cur_r, max_r, fail_r;
  reg [2:0] reason_r;
  reg [4:0] age_r;
  reg       done_r, ev_r;

  // Retries are counted PER STEP. One counter per step is N_STEP registers
  // and it is the whole difference between "fails at 5, three times" and
  // "fails three times, somewhere".
  reg [3:0] retry_r [1:N_STEP];

  assign cur_step       = cur_r;
  assign max_step       = max_r;
  assign fail_step      = fail_r;
  assign fail_reason    = reason_r;
  assign retries_at_max = (max_r == 4'd0) ? 4'd0 : retry_r[max_r];
  assign step_age       = age_r;
  assign complete       = done_r;
  assign event_pulse    = ev_r;

  integer i;
  reg [3:0] cur_n, max_n, fail_n;
  reg [2:0] reason_n;
  reg [4:0] age_n;
  reg       done_n, ev_n;
  reg       bump_r_n;      // this step's retry counter advances
  reg [3:0] bump_idx;

  always @* begin
    cur_n    = cur_r;
    max_n    = max_r;
    fail_n   = fail_r;
    reason_n = F_NONE;
    age_n    = age_r;
    // ---- `complete` is STICKY, not a pulse. ----
    //
    // A completed enumeration must stop the timeout below from firing, and
    // a one-cycle pulse cannot: the cycle after it, the tracker is sitting
    // at the last step with nothing outstanding and starts counting dead
    // air towards a step that does not exist.
    done_n   = done_r;
    ev_n     = 1'b0;
    bump_r_n = 1'b0;
    bump_idx = 4'd0;

    if (eot) begin
      age_n = 5'd0;
    end else if (detach) begin
      // ---- A DIFFERENT DEVICE. Everything goes, including the diagnosis.
      //
      // This is the one event that must clear max_step. Carrying a previous
      // device's furthest step into the next device's enumeration produces
      // a report that names a step the new device never attempted.
      cur_n    = 4'd0;
      max_n    = 4'd0;
      fail_n   = 4'd0;
      reason_n = F_NONE;
      age_n    = 5'd0;
      done_n   = 1'b0;
    end else if (bus_reset) begin
      // ---- A RETRY. The sequence restarts; the DIAGNOSIS does not. ----
      //
      // max_step deliberately survives. It is the only thing in this block
      // that does, and it is the reason the block exists.
      cur_n  = 4'd1;
      age_n  = 5'd0;
      done_n = 1'b0;
      // Step 1 HAS been reached -- the device is attached -- so the
      // high-water mark advances to it. Without this the mark can sit
      // behind the current step, which is not a state that means anything.
      if (max_r < 4'd1) max_n = 4'd1;
    end else if (step_valid) begin
      age_n = 5'd0;

      if ((step_id < 4'd1) || (step_id > N_STEP[3:0])) begin
        // ---- NOT A STEP AT ALL. ----
        //
        // The sequence has ten steps. A trace that reports an eleventh is a
        // decoder that is wrong, and the important thing is that it must
        // not ADVANCE anything: a bad step number accepted as progress
        // makes max_step name a step nobody ever attempted, which is worse
        // than no diagnosis because it is a confident one.
        ev_n     = 1'b1;
        reason_n = F_BADSTEP;
        fail_n   = step_id;
      end else if (step_id > cur_r + 4'd1) begin
        // ---- The host jumped past a step. ----
        //
        // Hosts do not do this by accident. Something the host read earlier
        // told it not to bother, so the finding is upstream of the step
        // that appears to be missing.
        ev_n     = 1'b1;
        reason_n = F_SKIP;
        fail_n   = step_id;
        cur_n    = step_id;
        if (step_id > max_r) max_n = step_id;
      end else if (step_id <= cur_r) begin
        // ---- Backwards, with no reset in between. ----
        ev_n     = 1'b1;
        reason_n = F_REGRESS;
        fail_n   = step_id;
        cur_n    = step_id;
      end else if (step_ok) begin
        cur_n = step_id;
        if (step_id > max_r) max_n = step_id;
        if (step_id == N_STEP[3:0]) begin
          done_n = 1'b1;
          ev_n   = 1'b1;
        end
      end else begin
        // ---- The step returned an error. ----
        //
        // The step is still the furthest REACHED -- it was attempted, and
        // naming it is the entire point -- so max_step advances even though
        // the step failed.
        ev_n     = 1'b1;
        reason_n = F_STEP_FAIL;
        fail_n   = step_id;
        if (step_id > max_r) max_n = step_id;
        bump_r_n = 1'b1;
        bump_idx = step_id;
        if (retry_r[step_id] + 4'd1 >= RETRY_MAX[3:0]) reason_n = F_EXHAUSTED;
      end
    end else if ((cur_r != 4'd0) && !done_r && (cur_r < N_STEP[3:0])) begin
      // ---- THE LIVENESS RULE. The step never returned at all. ----
      //
      // A failure is an answer; silence is not, and they have different
      // causes. Nothing else in this block fires when nothing happens.
      if (age_r >= STEP_TO[4:0] - 5'd1) begin
        ev_n     = 1'b1;
        reason_n = F_TIMEOUT;
        fail_n   = cur_r + 4'd1;   // the step that was awaited
        age_n    = 5'd0;
        bump_r_n = 1'b1;
        bump_idx = cur_r + 4'd1;
        if (bump_idx > max_r) max_n = bump_idx;
      end else if (bus_idle) begin
        age_n = age_r + 5'd1;
      end
    end
  end

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      cur_r       <= 4'd0;
      max_r       <= 4'd0;
      fail_r      <= 4'd0;
      reason_r    <= F_NONE;
      age_r       <= 5'd0;
      done_r      <= 1'b0;
      ev_r        <= 1'b0;
      for (i = 1; i <= N_STEP; i = i + 1) retry_r[i] <= 4'd0;
      n_steps     <= 32'd0;
      n_resets    <= 32'd0;
      n_detach    <= 32'd0;
      n_step_fail <= 32'd0;
      n_timeout   <= 32'd0;
      n_skip      <= 32'd0;
      n_regress   <= 32'd0;
      n_exhausted <= 32'd0;
      n_badstep   <= 32'd0;
      n_complete  <= 32'd0;
    end else begin
      cur_r    <= cur_n;
      max_r    <= max_n;
      fail_r   <= fail_n;
      reason_r <= reason_n;
      age_r    <= age_n;
      done_r   <= done_n;
      ev_r     <= ev_n;

      if (detach) begin
        for (i = 1; i <= N_STEP; i = i + 1) retry_r[i] <= 4'd0;
        n_detach <= n_detach + 32'd1;
      end else if (bump_r_n && (bump_idx >= 4'd1) && (bump_idx <= N_STEP[3:0])) begin
        if (retry_r[bump_idx] != 4'hF)
          retry_r[bump_idx] <= retry_r[bump_idx] + 4'd1;
      end

      if (step_valid && !detach && !bus_reset && !eot)
                        n_steps    <= n_steps + 32'd1;
      if (bus_reset && !detach && !eot)
                        n_resets   <= n_resets + 32'd1;
      // The RISING edge of a sticky flag, not the flag itself.
      if (done_n && !done_r) n_complete <= n_complete + 32'd1;

      // The per-cause counters are driven by the SAME pulse as the event,
      // so they sum to it by construction (chapter 23.4).
      if (ev_n) begin
        case (reason_n)
          F_STEP_FAIL: n_step_fail <= n_step_fail + 32'd1;
          F_TIMEOUT:   n_timeout   <= n_timeout   + 32'd1;
          F_SKIP:      n_skip      <= n_skip      + 32'd1;
          F_REGRESS:   n_regress   <= n_regress   + 32'd1;
          F_EXHAUSTED: n_exhausted <= n_exhausted + 32'd1;
          F_BADSTEP:   n_badstep   <= n_badstep   + 32'd1;
          default: ;
        endcase
      end
    end
  end
endmodule

// usb_enum_tracker -- why a failing enumeration tells you nothing, and the
// one change to the instrumentation that makes it tell you everything.
//
// ENUMERATION IS A SEQUENCE, AND THE FAILING STEP IS THE DIAGNOSIS
//
//   1  ATTACH        VBUS appears
//   2  RESET         the host drives SE0
//   3  GET_DESC_8    GET_DESCRIPTOR(Device, 8 bytes) at address 0
//   4  RESET_2       the host resets again
//   5  SET_ADDRESS   the device gets a unique address
//   6  GET_DESC_DEV  the full device descriptor
//   7  GET_DESC_C9   GET_DESCRIPTOR(Config, 9 bytes)
//   8  GET_DESC_CFG  the full configuration descriptor
//   9  SET_CONFIG    SET_CONFIGURATION
//  10  ENUMERATED
//
// Every one of those steps fails for a different reason, and knowing WHICH
// one is most of the debug. "The device does not enumerate" is not a bug
// report; "it never gets past SET_ADDRESS" is.
//
// AND HERE IS WHY THE OBVIOUS INSTRUMENTATION TELLS YOU NOTHING
//
// When enumeration fails, the host does not stop. It RESETS THE BUS and
// tries again, from step 1. It does that three times, and then it gives up
// and reports "device not recognised".
//
// So a tracker that records the CURRENT step -- which is the obvious thing
// to build, and what a state machine naturally gives you -- reads ATTACH at
// the end of every failed enumeration, no matter where the failure was. The
// state at the end is not the failure; it is the third retry's first step.
//
//     RECORD THE FURTHEST STEP EVER REACHED, AND DO NOT
//     LET A BUS RESET CLEAR IT.
//
// That one register is the difference between "the device does not work"
// and "it fails at step 6, three times, and step 6 is the full device
// descriptor". Those are the same bug and two completely different days.
//
// RETRIES ARE PER STEP, NOT GLOBAL
//
// A device that fails at step 5 three times has a different bug from one
// that fails at 5, then at 9, then at 5 again. The first is deterministic
// and cheap to find; the second is marginal, and probably timing or power.
// A single global retry counter loses that distinction entirely, and it is
// the distinction that decides which instrument you pick up next.
//
// A SKIPPED STEP IS AS DIAGNOSTIC AS A FAILED ONE
//
// The host does not skip steps by accident. If step 7 arrives when step 5
// was the last one seen, the host has abandoned something -- usually
// because a descriptor it read earlier told it not to bother. That is a
// finding, and it points at the descriptor rather than at the step that
// appears to be missing.
//
// AND A STEP THAT NEVER COMPLETES IS NOT A STEP THAT FAILED
//
// A failure is an answer. Silence is not. They have different causes --
// a STALL is firmware saying no, a timeout is firmware not running -- and
// nothing else in this block fires when nothing happens, which is the same
// argument the protocol checker of chapter 24.1 makes about its own
// timeout.
package usb_enum_pkg;
  // The reasons an enumeration stops making progress. They are separate
  // because they send you to different places: a STEP_FAIL is firmware
  // saying no, a TIMEOUT is firmware not running, a SKIP is the host having
  // read something earlier that told it not to bother, and a BADSTEP is the
  // decoder being wrong about the trace.
  typedef enum logic [2:0] {
    F_NONE      = 3'd0,
    F_STEP_FAIL = 3'd1,   // the step returned an error
    F_TIMEOUT   = 3'd2,   // the step never returned at all
    F_SKIP      = 3'd3,   // the host jumped past a step
    F_REGRESS   = 3'd4,   // a step went backwards, with no reset
    F_EXHAUSTED = 3'd5,   // RETRY_MAX attempts at one step
    F_BADSTEP   = 3'd6    // a step number the sequence has no room for
  } fail_e;
endpackage

module usb_enum_tracker
  import usb_enum_pkg::*;
 #(
  parameter int N_STEP    = 10,  // steps in a complete enumeration
  parameter int RETRY_MAX = 3,   // attempts at one step before giving up
  parameter int STEP_TO   = 12   // idle cycles before a step is dead
) (
  input  logic      clk,
  input  logic      rst_n,

  input  logic      step_valid,  // a step completed, one way or the other
  input  logic [3:0] step_id,     // 1..N_STEP
  input  logic      step_ok,     // it succeeded
  input  logic      bus_reset,   // the host reset the bus: back to step 1
  input  logic      detach,      // VBUS gone: a different device next time
  input  logic      bus_idle,    // nothing is happening on the wire
  input  logic      eot,

  output logic [3:0] cur_step,    // where enumeration is NOW
  output logic [3:0] max_step,    // the furthest step EVER reached -- the
                                 // one number that survives the retries
  output logic [3:0] fail_step,   // where it went wrong
  output fail_e      fail_reason,
  output logic [3:0] retries_at_max,
  output logic [4:0] step_age,
  output logic      complete,
  output logic      event_pulse,

  output logic [31:0] n_steps,
  output logic [31:0] n_resets,
  output logic [31:0] n_detach,
  output logic [31:0] n_step_fail,
  output logic [31:0] n_timeout,
  output logic [31:0] n_skip,
  output logic [31:0] n_regress,
  output logic [31:0] n_exhausted,
  output logic [31:0] n_badstep,
  output logic [31:0] n_complete
);

  logic [3:0] cur_r, max_r, fail_r;
  fail_e      reason_r;
  logic [4:0] age_r;
  logic       done_r, ev_r;

  // Retries are counted PER STEP. One counter per step is N_STEP registers
  // and it is the whole difference between "fails at 5, three times" and
  // "fails three times, somewhere".
  logic [3:0] retry_r [1:N_STEP];

  assign cur_step       = cur_r;
  assign max_step       = max_r;
  assign fail_step      = fail_r;
  assign fail_reason    = reason_r;
  assign retries_at_max = (max_r == 4'd0) ? 4'd0 : retry_r[max_r];
  assign step_age       = age_r;
  assign complete       = done_r;
  assign event_pulse    = ev_r;

  int         i;
  logic [3:0] cur_n, max_n, fail_n;
  fail_e      reason_n;
  logic [4:0] age_n;
  logic       done_n, ev_n;
  logic       bump_r_n;    // this step's retry counter advances
  logic [3:0] bump_idx;

  always_comb begin
    cur_n    = cur_r;
    max_n    = max_r;
    fail_n   = fail_r;
    reason_n = F_NONE;
    age_n    = age_r;
    // ---- `complete` is STICKY, not a pulse. ----
    //
    // A completed enumeration must stop the timeout below from firing, and
    // a one-cycle pulse cannot: the cycle after it, the tracker is sitting
    // at the last step with nothing outstanding and starts counting dead
    // air towards a step that does not exist.
    done_n   = done_r;
    ev_n     = 1'b0;
    bump_r_n = 1'b0;
    bump_idx = 4'd0;

    if (eot) begin
      age_n = 5'd0;
    end else if (detach) begin
      // ---- A DIFFERENT DEVICE. Everything goes, including the diagnosis.
      //
      // This is the one event that must clear max_step. Carrying a previous
      // device's furthest step into the next device's enumeration produces
      // a report that names a step the new device never attempted.
      cur_n    = 4'd0;
      max_n    = 4'd0;
      fail_n   = 4'd0;
      reason_n = F_NONE;
      age_n    = 5'd0;
      done_n   = 1'b0;
    end else if (bus_reset) begin
      // ---- A RETRY. The sequence restarts; the DIAGNOSIS does not. ----
      //
      // max_step deliberately survives. It is the only thing in this block
      // that does, and it is the reason the block exists.
      cur_n  = 4'd1;
      age_n  = 5'd0;
      done_n = 1'b0;
      // Step 1 HAS been reached -- the device is attached -- so the
      // high-water mark advances to it. Without this the mark can sit
      // behind the current step, which is not a state that means anything.
      if (max_r < 4'd1) max_n = 4'd1;
    end else if (step_valid) begin
      age_n = 5'd0;

      if ((step_id < 4'd1) || (step_id > 4'(N_STEP))) begin
        // ---- NOT A STEP AT ALL. ----
        //
        // The sequence has ten steps. A trace that reports an eleventh is a
        // decoder that is wrong, and the important thing is that it must
        // not ADVANCE anything: a bad step number accepted as progress
        // makes max_step name a step nobody ever attempted, which is worse
        // than no diagnosis because it is a confident one.
        ev_n     = 1'b1;
        reason_n = F_BADSTEP;
        fail_n   = step_id;
      end else if (step_id > cur_r + 4'd1) begin
        // ---- The host jumped past a step. ----
        //
        // Hosts do not do this by accident. Something the host read earlier
        // told it not to bother, so the finding is upstream of the step
        // that appears to be missing.
        ev_n     = 1'b1;
        reason_n = F_SKIP;
        fail_n   = step_id;
        cur_n    = step_id;
        if (step_id > max_r) max_n = step_id;
      end else if (step_id <= cur_r) begin
        // ---- Backwards, with no reset in between. ----
        ev_n     = 1'b1;
        reason_n = F_REGRESS;
        fail_n   = step_id;
        cur_n    = step_id;
      end else if (step_ok) begin
        cur_n = step_id;
        if (step_id > max_r) max_n = step_id;
        if (step_id == 4'(N_STEP)) begin
          done_n = 1'b1;
          ev_n   = 1'b1;
        end
      end else begin
        // ---- The step returned an error. ----
        //
        // The step is still the furthest REACHED -- it was attempted, and
        // naming it is the entire point -- so max_step advances even though
        // the step failed.
        ev_n     = 1'b1;
        reason_n = F_STEP_FAIL;
        fail_n   = step_id;
        if (step_id > max_r) max_n = step_id;
        bump_r_n = 1'b1;
        bump_idx = step_id;
        if (retry_r[step_id] + 4'd1 >= 4'(RETRY_MAX)) reason_n = F_EXHAUSTED;
      end
    end else if ((cur_r != 4'd0) && !done_r && (cur_r < 4'(N_STEP))) begin
      // ---- THE LIVENESS RULE. The step never returned at all. ----
      //
      // A failure is an answer; silence is not, and they have different
      // causes. Nothing else in this block fires when nothing happens.
      if (age_r >= 5'(STEP_TO) - 5'd1) begin
        ev_n     = 1'b1;
        reason_n = F_TIMEOUT;
        fail_n   = cur_r + 4'd1;   // the step that was awaited
        age_n    = 5'd0;
        bump_r_n = 1'b1;
        bump_idx = cur_r + 4'd1;
        if (bump_idx > max_r) max_n = bump_idx;
      end else if (bus_idle) begin
        age_n = age_r + 5'd1;
      end
    end
  end

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      cur_r       <= 4'd0;
      max_r       <= 4'd0;
      fail_r      <= 4'd0;
      reason_r    <= F_NONE;
      age_r       <= 5'd0;
      done_r      <= 1'b0;
      ev_r        <= 1'b0;
      for (i = 1; i <= N_STEP; i++) retry_r[i] <= 4'd0;
      n_steps     <= 32'd0;
      n_resets    <= 32'd0;
      n_detach    <= 32'd0;
      n_step_fail <= 32'd0;
      n_timeout   <= 32'd0;
      n_skip      <= 32'd0;
      n_regress   <= 32'd0;
      n_exhausted <= 32'd0;
      n_badstep   <= 32'd0;
      n_complete  <= 32'd0;
    end else begin
      cur_r    <= cur_n;
      max_r    <= max_n;
      fail_r   <= fail_n;
      reason_r <= reason_n;
      age_r    <= age_n;
      done_r   <= done_n;
      ev_r     <= ev_n;

      if (detach) begin
        for (i = 1; i <= N_STEP; i++) retry_r[i] <= 4'd0;
        n_detach <= n_detach + 32'd1;
      end else if (bump_r_n && (bump_idx >= 4'd1) && (bump_idx <= 4'(N_STEP))) begin
        if (retry_r[bump_idx] != 4'hF)
          retry_r[bump_idx] <= retry_r[bump_idx] + 4'd1;
      end

      if (step_valid && !detach && !bus_reset && !eot)
                        n_steps    <= n_steps + 32'd1;
      if (bus_reset && !detach && !eot)
                        n_resets   <= n_resets + 32'd1;
      // The RISING edge of a sticky flag, not the flag itself.
      if (done_n && !done_r) n_complete <= n_complete + 32'd1;

      // The per-cause counters are driven by the SAME pulse as the event,
      // so they sum to it by construction (chapter 23.4).
      if (ev_n) begin
        case (reason_n)
          F_STEP_FAIL: n_step_fail <= n_step_fail + 32'd1;
          F_TIMEOUT:   n_timeout   <= n_timeout   + 32'd1;
          F_SKIP:      n_skip      <= n_skip      + 32'd1;
          F_REGRESS:   n_regress   <= n_regress   + 32'd1;
          F_EXHAUSTED: n_exhausted <= n_exhausted + 32'd1;
          F_BADSTEP:   n_badstep   <= n_badstep   + 32'd1;
          default: ;
        endcase
      end
    end
  end
endmodule

-- usb_enum_tracker -- why a failing enumeration tells you nothing, and the
-- one change to the instrumentation that makes it tell you everything.
--
-- ENUMERATION IS A SEQUENCE, AND THE FAILING STEP IS THE DIAGNOSIS
--
--   1  ATTACH        VBUS appears
--   2  RESET         the host drives SE0
--   3  GET_DESC_8    GET_DESCRIPTOR(Device, 8 bytes) at address 0
--   4  RESET_2       the host resets again
--   5  SET_ADDRESS   the device gets a unique address
--   6  GET_DESC_DEV  the full device descriptor
--   7  GET_DESC_C9   GET_DESCRIPTOR(Config, 9 bytes)
--   8  GET_DESC_CFG  the full configuration descriptor
--   9  SET_CONFIG    SET_CONFIGURATION
--  10  ENUMERATED
--
-- Every one of those steps fails for a different reason, and knowing WHICH
-- one is most of the debug. "The device does not enumerate" is not a bug
-- report; "it never gets past SET_ADDRESS" is.
--
-- AND HERE IS WHY THE OBVIOUS INSTRUMENTATION TELLS YOU NOTHING
--
-- When enumeration fails, the host does not stop. It RESETS THE BUS and
-- tries again, from step 1. It does that three times, and then it gives up
-- and reports "device not recognised".
--
-- So a tracker that records the CURRENT step -- which is the obvious thing
-- to build, and what a state machine naturally gives you -- reads ATTACH at
-- the end of every failed enumeration, no matter where the failure was. The
-- state at the end is not the failure; it is the third retry's first step.
--
--     RECORD THE FURTHEST STEP EVER REACHED, AND DO NOT
--     LET A BUS RESET CLEAR IT.
--
-- That one register is the difference between "the device does not work"
-- and "it fails at step 6, three times, and step 6 is the full device
-- descriptor". Those are the same bug and two completely different days.
--
-- RETRIES ARE PER STEP, NOT GLOBAL
--
-- A device that fails at step 5 three times has a different bug from one
-- that fails at 5, then at 9, then at 5 again. The first is deterministic
-- and cheap to find; the second is marginal, and probably timing or power.
-- A single global retry counter loses that distinction entirely, and it is
-- the distinction that decides which instrument you pick up next.
--
-- A SKIPPED STEP IS AS DIAGNOSTIC AS A FAILED ONE
--
-- The host does not skip steps by accident. If step 7 arrives when step 5
-- was the last one seen, the host has abandoned something -- usually
-- because a descriptor it read earlier told it not to bother. That is a
-- finding, and it points at the descriptor rather than at the step that
-- appears to be missing.
--
-- AND A STEP THAT NEVER COMPLETES IS NOT A STEP THAT FAILED
--
-- A failure is an answer. Silence is not. They have different causes --
-- a STALL is firmware saying no, a timeout is firmware not running -- and
-- nothing else in this block fires when nothing happens, which is the same
-- argument the protocol checker of chapter 24.1 makes about its own
-- timeout.
library ieee;
use ieee.std_logic_1164.all;

package usb_enum_pkg is
  -- The reasons an enumeration stops making progress. They are separate
  -- because they send you to different places: a STEP_FAIL is firmware
  -- saying no, a TIMEOUT is firmware not running, a SKIP is the host having
  -- read something earlier that told it not to bother, and a BADSTEP is the
  -- decoder being wrong about the trace.
  type fail_t is (F_NONE, F_STEP_FAIL, F_TIMEOUT, F_SKIP, F_REGRESS,
                  F_EXHAUSTED, F_BADSTEP);
  function f_code (f : fail_t) return std_logic_vector;
end package usb_enum_pkg;

package body usb_enum_pkg is
  function f_code (f : fail_t) return std_logic_vector is
  begin
    case f is
      when F_NONE      => return "000";
      when F_STEP_FAIL => return "001";
      when F_TIMEOUT   => return "010";
      when F_SKIP      => return "011";
      when F_REGRESS   => return "100";
      when F_EXHAUSTED => return "101";
      when F_BADSTEP   => return "110";
    end case;
  end function;
end package body usb_enum_pkg;

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

entity usb_enum_tracker is
  generic (
    N_STEP    : integer := 10;  -- steps in a complete enumeration
    RETRY_MAX : integer := 3;   -- attempts at one step before giving up
    STEP_TO   : integer := 12   -- idle cycles before a step is dead
  );
  port (
    clk            : in  std_logic;
    rst_n          : in  std_logic;

    step_valid     : in  std_logic;                     -- a step completed
    step_id        : in  std_logic_vector(3 downto 0);  -- 1..N_STEP
    step_ok        : in  std_logic;                     -- it succeeded
    bus_reset      : in  std_logic;                     -- back to step 1
    detach         : in  std_logic;                     -- a different device
    bus_idle       : in  std_logic;
    eot            : in  std_logic;

    cur_step       : out std_logic_vector(3 downto 0);
    max_step       : out std_logic_vector(3 downto 0);  -- THE diagnosis
    fail_step      : out std_logic_vector(3 downto 0);
    fail_reason    : out std_logic_vector(2 downto 0);
    retries_at_max : out std_logic_vector(3 downto 0);
    step_age       : out std_logic_vector(4 downto 0);
    complete       : out std_logic;
    event_pulse    : out std_logic;

    n_steps        : out std_logic_vector(31 downto 0);
    n_resets       : out std_logic_vector(31 downto 0);
    n_detach       : out std_logic_vector(31 downto 0);
    n_step_fail    : out std_logic_vector(31 downto 0);
    n_timeout      : out std_logic_vector(31 downto 0);
    n_skip         : out std_logic_vector(31 downto 0);
    n_regress      : out std_logic_vector(31 downto 0);
    n_exhausted    : out std_logic_vector(31 downto 0);
    n_badstep      : out std_logic_vector(31 downto 0);
    n_complete     : out std_logic_vector(31 downto 0)
  );
end entity usb_enum_tracker;

architecture rtl of usb_enum_tracker is

  type retry_arr is array (1 to N_STEP) of unsigned(3 downto 0);

  signal cur_r, max_r, fail_r : unsigned(3 downto 0) := (others => '0');
  signal reason_r : fail_t := F_NONE;
  signal age_r    : unsigned(4 downto 0) := (others => '0');
  signal done_r, ev_r : std_logic := '0';

  -- Retries are counted PER STEP. One counter per step is N_STEP registers
  -- and it is the whole difference between "fails at 5, three times" and
  -- "fails three times, somewhere".
  signal retry_r : retry_arr := (others => (others => '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_st, c_rs, c_dt, c_sf, c_to : unsigned(31 downto 0) := (others => '0');
  signal c_sk, c_rg, c_ex, c_bs, c_cp : unsigned(31 downto 0) := (others => '0');

begin

  cur_step       <= std_logic_vector(cur_r);
  max_step       <= std_logic_vector(max_r);
  fail_step      <= std_logic_vector(fail_r);
  fail_reason    <= f_code(reason_r);
  retries_at_max <= (others => '0') when max_r = 0
                    else std_logic_vector(retry_r(to_integer(max_r)));
  step_age       <= std_logic_vector(age_r);
  complete       <= done_r;
  event_pulse    <= ev_r;

  n_steps     <= std_logic_vector(c_st);
  n_resets    <= std_logic_vector(c_rs);
  n_detach    <= std_logic_vector(c_dt);
  n_step_fail <= std_logic_vector(c_sf);
  n_timeout   <= std_logic_vector(c_to);
  n_skip      <= std_logic_vector(c_sk);
  n_regress   <= std_logic_vector(c_rg);
  n_exhausted <= std_logic_vector(c_ex);
  n_badstep   <= std_logic_vector(c_bs);
  n_complete  <= std_logic_vector(c_cp);

  process (clk, rst_n)
    variable ncur, nmax, nfail, bidx : unsigned(3 downto 0);
    variable nrsn : fail_t;
    variable nage : unsigned(4 downto 0);
    variable ndone, nev, nbump : std_logic;
    variable sid : unsigned(3 downto 0);
  begin
    if rst_n = '0' then
      cur_r    <= (others => '0');
      max_r    <= (others => '0');
      fail_r   <= (others => '0');
      reason_r <= F_NONE;
      age_r    <= (others => '0');
      done_r   <= '0';
      ev_r     <= '0';
      retry_r  <= (others => (others => '0'));
      c_st <= (others => '0'); c_rs <= (others => '0');
      c_dt <= (others => '0'); c_sf <= (others => '0');
      c_to <= (others => '0'); c_sk <= (others => '0');
      c_rg <= (others => '0'); c_ex <= (others => '0');
      c_bs <= (others => '0'); c_cp <= (others => '0');
    elsif rising_edge(clk) then
      sid   := unsigned(step_id);
      ncur  := cur_r; nmax := max_r; nfail := fail_r;
      nrsn  := F_NONE; nage := age_r;
      -- `complete` is STICKY, not a pulse: a completed enumeration must stop
      -- the timeout below from firing, and a one-cycle pulse cannot.
      ndone := done_r;
      nev   := '0'; nbump := '0'; bidx := (others => '0');

      if eot = '1' then
        nage := (others => '0');
      elsif detach = '1' then
        -- ---- A DIFFERENT DEVICE. Everything goes, including the diagnosis.
        --
        -- This is the one event that must clear max_step. Carrying a
        -- previous device's furthest step into the next device's
        -- enumeration produces a report that names a step the new device
        -- never attempted.
        ncur  := (others => '0'); nmax := (others => '0');
        nfail := (others => '0'); nrsn := F_NONE;
        nage  := (others => '0'); ndone := '0';
      elsif bus_reset = '1' then
        -- ---- A RETRY. The sequence restarts; the DIAGNOSIS does not. ----
        ncur  := to_unsigned(1, 4);
        nage  := (others => '0');
        ndone := '0';
        -- Step 1 HAS been reached -- the device is attached -- so the
        -- high-water mark advances to it.
        if max_r < 1 then nmax := to_unsigned(1, 4); end if;
      elsif step_valid = '1' then
        nage := (others => '0');
        if sid < 1 or sid > to_unsigned(N_STEP, 4) then
          -- ---- NOT A STEP AT ALL. ----
          --
          -- The sequence has N_STEP steps. A trace that reports one beyond
          -- them is a decoder that is wrong, and the important thing is
          -- that it must not ADVANCE anything: a bad step number accepted
          -- as progress makes max_step name a step nobody ever attempted,
          -- which is worse than no diagnosis because it is a confident one.
          nev := '1'; nrsn := F_BADSTEP; nfail := sid;
        elsif sid > cur_r + 1 then
          -- ---- The host jumped past a step. ----
          nev := '1'; nrsn := F_SKIP; nfail := sid; ncur := sid;
          if sid > max_r then nmax := sid; end if;
        elsif sid <= cur_r then
          -- ---- Backwards, with no reset in between. ----
          nev := '1'; nrsn := F_REGRESS; nfail := sid; ncur := sid;
        elsif step_ok = '1' then
          ncur := sid;
          if sid > max_r then nmax := sid; end if;
          if sid = to_unsigned(N_STEP, 4) then
            ndone := '1'; nev := '1';
          end if;
        else
          -- ---- The step returned an error. ----
          --
          -- The step is still the furthest REACHED -- it was attempted, and
          -- naming it is the entire point -- so max_step advances even
          -- though the step failed.
          nev := '1'; nrsn := F_STEP_FAIL; nfail := sid;
          if sid > max_r then nmax := sid; end if;
          nbump := '1'; bidx := sid;
          if retry_r(to_integer(sid)) + 1 >= to_unsigned(RETRY_MAX, 4) then
            nrsn := F_EXHAUSTED;
          end if;
        end if;
      elsif cur_r /= 0 and done_r = '0' and cur_r < to_unsigned(N_STEP, 4) then
        -- ---- THE LIVENESS RULE. The step never returned at all. ----
        --
        -- A failure is an answer; silence is not, and they have different
        -- causes. Nothing else in this block fires when nothing happens.
        if age_r >= to_unsigned(STEP_TO - 1, 5) then
          nev := '1'; nrsn := F_TIMEOUT; nfail := cur_r + 1;
          nage := (others => '0');
          nbump := '1'; bidx := cur_r + 1;
          if bidx > max_r then nmax := bidx; end if;
        elsif bus_idle = '1' then
          nage := age_r + 1;
        end if;
      end if;

      cur_r    <= ncur;
      max_r    <= nmax;
      fail_r   <= nfail;
      reason_r <= nrsn;
      age_r    <= nage;
      ev_r     <= nev;

      if detach = '1' then
        retry_r <= (others => (others => '0'));
        c_dt <= c_dt + 1;
      elsif nbump = '1' and bidx >= 1 and bidx <= to_unsigned(N_STEP, 4) then
        if retry_r(to_integer(bidx)) /= x"F" then
          retry_r(to_integer(bidx)) <= retry_r(to_integer(bidx)) + 1;
        end if;
      end if;

      if step_valid = '1' and detach = '0' and bus_reset = '0' and eot = '0' then
        c_st <= c_st + 1;
      end if;
      if bus_reset = '1' and detach = '0' and eot = '0' then
        c_rs <= c_rs + 1;
      end if;
      -- The RISING edge of a sticky flag, not the flag itself.
      if ndone = '1' and done_r = '0' then c_cp <= c_cp + 1; end if;
      done_r <= ndone;

      -- The per-cause counters are driven by the SAME pulse as the event,
      -- so they sum to it by construction (chapter 23.4).
      if nev = '1' then
        case nrsn is
          when F_STEP_FAIL => c_sf <= c_sf + 1;
          when F_TIMEOUT   => c_to <= c_to + 1;
          when F_SKIP      => c_sk <= c_sk + 1;
          when F_REGRESS   => c_rg <= c_rg + 1;
          when F_EXHAUSTED => c_ex <= c_ex + 1;
          when F_BADSTEP   => c_bs <= c_bs + 1;
          when others      => null;
        end case;
      end if;
    end if;
  end process;

end architecture rtl;

    for (s = 2; s <= N_STEP; s = s + 1) begin
      do_detach;
      for (k = 0; k < RETRY_MAX; k = k + 1) begin
        do_reset;
        for (a = 2; a < s; a = a + 1) ok_step(a[3:0]);
        bad_step(s[3:0]);
      end
      // The host gives up and resets once more before reporting.
      do_reset;
      check(cur_step === 4'd1,
            "the tracker is not sitting at step 1 after the final reset");
      check(max_step === s[3:0],
            "max_step is not the step that failed -- a tracker whose furthest step is cleared by a bus reset reports step 1 for every failure, and 'the device does not get past ATTACH' sends somebody to look at VBUS");
      check(retries_at_max === RETRY_MAX[3:0],
            "the retry count at the failing step is wrong -- retries are counted PER STEP, and 'fails at 5 three times' is a different bug from 'fails three times, somewhere'");
    end

      // ---- max_step is a HIGH-WATER MARK. It never goes backwards except
      // ---- on a detach, and that invariant is the whole block.
      check(m_max >= m_cur,
            "the furthest step reached is behind the current step, which is impossible");

// Testbench for usb_enum_tracker (Verilog-2005).
//
// THE TEST THAT DEFINES THE CHAPTER
//
// Enumeration fails at step 6 and the host retries the whole sequence three
// times. At the end:
//
//     cur_step  reads 1     -- the third retry's first step
//     max_step  reads 6     -- THE DIAGNOSIS
//
// The suite drives exactly that and checks both numbers, because the whole
// argument of the chapter is that one of them is useless and the other is
// the answer. A tracker whose max_step is cleared by a bus reset reports 1
// as well, and a report of "the device does not get past ATTACH" sends
// somebody to look at VBUS.
//
// WHAT IS EXHAUSTIVE HERE
//
//   1. Every step 1..N_STEP as the FAILING step, with the full retry-and-
//      reset sequence around it, checking max_step each time. Ten failures,
//      ten different diagnoses, and the tracker must produce the right one
//      for each.
//
//   2. Every current step 0..N_STEP crossed with all 16 combinations of
//      {step_valid, step_ok, bus_reset, detach} = 176 pairs, each state
//      reached by real steps.
`timescale 1ns/1ps
module tb_et_v;

  localparam integer N_STEP    = 10;
  localparam integer RETRY_MAX = 3;
  localparam integer STEP_TO   = 12;

  localparam [2:0] F_NONE=3'd0, F_STEP_FAIL=3'd1, F_TIMEOUT=3'd2,
                   F_SKIP=3'd3, F_REGRESS=3'd4, F_EXHAUSTED=3'd5,
                   F_BADSTEP=3'd6;

  reg clk = 1'b0, rst_n = 1'b0;
  reg step_valid = 1'b0, step_ok = 1'b0;
  reg bus_reset = 1'b0, detach = 1'b0, bus_idle = 1'b1, eot = 1'b0;
  reg [3:0] step_id = 4'd0;

  wire [3:0] cur_step, max_step, fail_step, retries_at_max;
  wire [2:0] fail_reason;
  wire [4:0] step_age;
  wire complete, event_pulse;
  wire [31:0] n_steps, n_resets, n_detach, n_step_fail, n_timeout,
              n_skip, n_regress, n_exhausted, n_badstep, n_complete;

  usb_enum_tracker #(.N_STEP(N_STEP), .RETRY_MAX(RETRY_MAX),
                     .STEP_TO(STEP_TO)) dut (
    .clk(clk), .rst_n(rst_n),
    .step_valid(step_valid), .step_id(step_id), .step_ok(step_ok),
    .bus_reset(bus_reset), .detach(detach), .bus_idle(bus_idle), .eot(eot),
    .cur_step(cur_step), .max_step(max_step), .fail_step(fail_step),
    .fail_reason(fail_reason), .retries_at_max(retries_at_max),
    .step_age(step_age), .complete(complete), .event_pulse(event_pulse),
    .n_steps(n_steps), .n_resets(n_resets), .n_detach(n_detach),
    .n_step_fail(n_step_fail), .n_timeout(n_timeout), .n_skip(n_skip),
    .n_regress(n_regress), .n_exhausted(n_exhausted),
    .n_badstep(n_badstep), .n_complete(n_complete)
  );

  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 | cur=%0d max=%0d fail=%0d(%0d) rty=%0d age=%0d",
                   $time, msg, cur_step, max_step, fail_step, fail_reason,
                   retries_at_max, step_age);
      end
    end
  endtask

  // ------------------------------------------------------------------
  // The shadow tracker.
  // ------------------------------------------------------------------
  reg [3:0] m_cur, m_max, m_fail;
  reg [2:0] m_rsn;
  reg [4:0] m_age;
  reg       m_done, m_ev;
  reg [3:0] m_retry [1:N_STEP];
  integer   m_st, m_rs, m_dt, m_sf, m_to, m_sk, m_rg, m_ex, m_bs, m_cp;

  integer seen [0:175];         // (N_STEP+1) x 16 input combinations
  integer n_seen, n_steps_t;

  task model_reset;
    integer j;
    begin
      m_cur = 4'd0; m_max = 4'd0; m_fail = 4'd0; m_rsn = F_NONE;
      m_age = 5'd0; m_done = 1'b0; m_ev = 1'b0;
      for (j = 1; j <= N_STEP; j = j + 1) m_retry[j] = 4'd0;
      m_st = 0; m_rs = 0; m_dt = 0; m_sf = 0; m_to = 0;
      m_sk = 0; m_rg = 0; m_ex = 0; m_bs = 0; m_cp = 0;
      for (j = 0; j < 176; j = j + 1) seen[j] = 0;
      n_seen = 0; n_steps_t = 0;
    end
  endtask

  integer idx;
  task step(input sv, input [3:0] sid, input sok,
            input brst, input det, input bidle, input eo);
    reg [3:0] ncur, nmax, nfail, bidx;
    reg [2:0] nrsn;
    reg [4:0] nage;
    reg ndone, nev, nbump;
    begin
      step_valid = sv; step_id = sid; step_ok = sok;
      bus_reset = brst; detach = det; bus_idle = bidle; eot = eo;
      #1;

      check(cur_step    === m_cur,  "cur_step disagrees with the shadow tracker");
      check(max_step    === m_max,  "max_step disagrees -- and max_step IS the diagnosis");
      check(fail_step   === m_fail, "fail_step disagrees");
      check(fail_reason === m_rsn,  "fail_reason disagrees");
      check(step_age    === m_age,  "step_age disagrees");
      check(complete    === m_done, "complete disagrees");
      check(event_pulse === m_ev,   "the event pulse disagrees");
      check(retries_at_max === ((m_max == 4'd0) ? 4'd0 : m_retry[m_max]),
            "retries_at_max disagrees -- retries are counted PER STEP, and a global counter cannot produce this number");

      // ---- max_step is a HIGH-WATER MARK. It never goes backwards except
      // ---- on a detach, and that invariant is the whole block.
      check(m_max >= m_cur,
            "the furthest step reached is behind the current step, which is impossible");
      check(max_step <= N_STEP[3:0],
            "max_step names a step that does not exist");
      check(step_age <= STEP_TO[4:0],
            "the step timer ran past its bound");
      check(!((m_cur == 4'd0) && (step_age != 5'd0)),
            "the step timer is running with no enumeration in progress");

      idx = m_cur * 16 + (sv ? 8 : 0) + (sok ? 4 : 0) + (brst ? 2 : 0) + (det ? 1 : 0);
      if (idx < 176) begin
        if (seen[idx] == 0) begin seen[idx] = 1; n_seen = n_seen + 1; end
      end
      n_steps_t = n_steps_t + 1;

      // ---- advance the shadow tracker ----
      ncur = m_cur; nmax = m_max; nfail = m_fail; nrsn = F_NONE;
      nage = m_age; ndone = m_done; nev = 1'b0; nbump = 1'b0; bidx = 4'd0;

      if (eo) begin
        nage = 5'd0;
      end else if (det) begin
        ncur = 4'd0; nmax = 4'd0; nfail = 4'd0; nrsn = F_NONE;
        nage = 5'd0; ndone = 1'b0;
      end else if (brst) begin
        ncur = 4'd1; nage = 5'd0; ndone = 1'b0;
        if (m_max < 4'd1) nmax = 4'd1;
      end else if (sv) begin
        nage = 5'd0;
        if ((sid < 4'd1) || (sid > N_STEP[3:0])) begin
          nev = 1'b1; nrsn = F_BADSTEP; nfail = sid;
        end else if (sid > m_cur + 4'd1) begin
          nev = 1'b1; nrsn = F_SKIP; nfail = sid; ncur = sid;
          if (sid > m_max) nmax = sid;
        end else if (sid <= m_cur) begin
          nev = 1'b1; nrsn = F_REGRESS; nfail = sid; ncur = sid;
        end else if (sok) begin
          ncur = sid;
          if (sid > m_max) nmax = sid;
          if (sid == N_STEP[3:0]) begin ndone = 1'b1; nev = 1'b1; end
        end else begin
          nev = 1'b1; nrsn = F_STEP_FAIL; nfail = sid;
          if (sid > m_max) nmax = sid;
          nbump = 1'b1; bidx = sid;
          if (m_retry[sid] + 4'd1 >= RETRY_MAX[3:0]) nrsn = F_EXHAUSTED;
        end
      end else if ((m_cur != 4'd0) && !m_done && (m_cur < N_STEP[3:0])) begin
        if (m_age >= STEP_TO[4:0] - 5'd1) begin
          nev = 1'b1; nrsn = F_TIMEOUT; nfail = m_cur + 4'd1; nage = 5'd0;
          nbump = 1'b1; bidx = m_cur + 4'd1;
          if (bidx > m_max) nmax = bidx;
        end else if (bidle) begin
          nage = m_age + 5'd1;
        end
      end

      m_cur = ncur; m_max = nmax; m_fail = nfail; m_rsn = nrsn;
      m_age = nage; m_ev = nev;
      if (det) begin
        for (idx = 1; idx <= N_STEP; idx = idx + 1) m_retry[idx] = 4'd0;
        m_dt = m_dt + 1;
      end else if (nbump && (bidx >= 4'd1) && (bidx <= N_STEP[3:0])) begin
        if (m_retry[bidx] != 4'hF) m_retry[bidx] = m_retry[bidx] + 4'd1;
      end
      if (ndone && !m_done) m_cp = m_cp + 1;
      m_done = ndone;

      if (sv && !det && !brst && !eo) m_st = m_st + 1;
      if (brst && !det && !eo)        m_rs = m_rs + 1;
      if (nev) begin
        case (nrsn)
          F_STEP_FAIL: m_sf = m_sf + 1;
          F_TIMEOUT:   m_to = m_to + 1;
          F_SKIP:      m_sk = m_sk + 1;
          F_REGRESS:   m_rg = m_rg + 1;
          F_EXHAUSTED: m_ex = m_ex + 1;
          F_BADSTEP:   m_bs = m_bs + 1;
          default: ;
        endcase
      end

      @(posedge clk); #1;
      step_valid = 1'b0; bus_reset = 1'b0; detach = 1'b0; eot = 1'b0;
    end
  endtask

  // A quiet bus. `bus_idle` must be HIGH here: the step timer counts DEAD
  // AIR, not elapsed time, so a "nop" that leaves the bus marked busy never
  // ages anything and the timeout phase below silently tests nothing.
  task nop(input integer n);
    integer j;
    begin
      for (j = 0; j < n; j = j + 1)
        step(1'b0,4'd0,1'b0, 1'b0,1'b0,1'b1,1'b0);
    end
  endtask

  task ok_step(input [3:0] s);
    begin step(1'b1,s,1'b1, 1'b0,1'b0,1'b0,1'b0); end
  endtask

  task bad_step(input [3:0] s);
    begin step(1'b1,s,1'b0, 1'b0,1'b0,1'b0,1'b0); end
  endtask

  task do_reset;
    begin step(1'b0,4'd0,1'b0, 1'b1,1'b0,1'b0,1'b0); end
  endtask

  // A new device. This is the ONLY thing that clears the diagnosis.
  task do_detach;
    begin
      step(1'b0,4'd0,1'b0, 1'b0,1'b1,1'b0,1'b0);
      nop(1);
      check(max_step === 4'd0,
            "a detach did not clear the furthest step -- the next device's report would name a step it never attempted");
      check(retries_at_max === 4'd0, "a detach did not clear the retry counts");
    end
  endtask

  integer k, s, cb, b_e, b_sf, b_c, a;

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

    // ---- Phase A: the state after reset ----
    check(cur_step === 4'd0 && max_step === 4'd0, "reset left a step recorded");
    check(complete === 1'b0, "reset reported a complete enumeration");

    // ---- Phase B: a clean enumeration, end to end. ----
    for (k = 0; k < 40; k = k + 1) begin
      do_detach;
      b_c = n_complete;
      do_reset;
      for (s = 2; s <= N_STEP; s = s + 1) ok_step(s[3:0]);
      check(complete === 1'b1, "a complete enumeration was not reported complete");
      check(max_step === N_STEP[3:0], "a complete enumeration did not reach the last step");
      check(n_complete == b_c + 1, "the completion was not counted");
      // ...and a completed enumeration must NOT then time out.
      b_e = n_timeout;
      nop(STEP_TO + 4);
      check(n_timeout == b_e,
            "a COMPLETED enumeration timed out -- `complete` must be a sticky state, because one cycle later the tracker is sitting at the last step counting dead air toward a step that does not exist");
    end

    // ---- Phase C: THE CHAPTER. Fail at every step, retry three times, and
    // ---- read the diagnosis off max_step.
    for (s = 2; s <= N_STEP; s = s + 1) begin
      do_detach;
      for (k = 0; k < RETRY_MAX; k = k + 1) begin
        do_reset;
        for (a = 2; a < s; a = a + 1) ok_step(a[3:0]);
        bad_step(s[3:0]);
      end
      // The host gives up and resets once more before reporting.
      do_reset;
      check(cur_step === 4'd1,
            "the tracker is not sitting at step 1 after the final reset");
      check(max_step === s[3:0],
            "max_step is not the step that failed -- a tracker whose furthest step is cleared by a bus reset reports step 1 for every failure, and 'the device does not get past ATTACH' sends somebody to look at VBUS");
      check(retries_at_max === RETRY_MAX[3:0],
            "the retry count at the failing step is wrong -- retries are counted PER STEP, and 'fails at 5 three times' is a different bug from 'fails three times, somewhere'");
      check(fail_step === s[3:0], "fail_step is not the failing step");
    end

    // ---- Phase D: retries are PER STEP. Fail at two different steps and
    // ---- check the counts are kept apart.
    do_detach;
    do_reset;
    ok_step(4'd2); ok_step(4'd3); ok_step(4'd4);
    bad_step(4'd5); bad_step(4'd5);
    do_reset;
    ok_step(4'd2); ok_step(4'd3); ok_step(4'd4); ok_step(4'd5);
    ok_step(4'd6); ok_step(4'd7); ok_step(4'd8);
    bad_step(4'd9);
    check(max_step === 4'd9, "max_step did not follow the furthest step");
    check(retries_at_max === 4'd1,
          "the retry count at step 9 has picked up step 5's failures -- a single global counter cannot tell a deterministic bug from a marginal one");

    // ---- Phase E: RETRY_MAX is reported as its own reason. ----
    do_detach;
    b_e = n_exhausted;
    for (k = 0; k < RETRY_MAX; k = k + 1) begin
      do_reset;
      ok_step(4'd2); ok_step(4'd3); ok_step(4'd4);
      bad_step(4'd5);
    end
    check(n_exhausted == b_e + 1,
          "the host ran out of retries at one step and it was not reported as exhaustion -- which is the difference between 'it sometimes fails' and 'the host has given up'");

    // ---- Phase F: a step that never answers is not a step that failed. --
    for (k = 0; k < 20; k = k + 1) begin
      do_detach;
      do_reset;
      ok_step(4'd2); ok_step(4'd3);
      b_e = n_timeout; b_sf = n_step_fail;
      nop(STEP_TO - 1);
      check(n_timeout == b_e, "the tracker gave up before its own bound");
      nop(3);
      check(n_timeout == b_e + 1,
            "a step that never returned at all was not reported -- a failure is an answer and silence is not, and they have different causes");
      check(n_step_fail == b_sf,
            "a timeout was classified as a step failure");
      check(max_step === 4'd4,
            "the awaited step was not recorded as the furthest reached -- it was attempted, and naming it is the point");
    end

    // ---- Phase G: a SKIPPED step. ----
    do_detach;
    do_reset;
    ok_step(4'd2); ok_step(4'd3);
    b_e = n_skip;
    ok_step(4'd7);
    check(n_skip == b_e + 1,
          "the host jumped past three steps and it was not reported -- hosts do not skip by accident, and the finding is upstream of the step that appears to be missing");

    // ---- Phase H: a REGRESSING step, with no reset in between. ----
    do_detach;
    do_reset;
    ok_step(4'd2); ok_step(4'd3); ok_step(4'd4);
    b_e = n_regress;
    ok_step(4'd3);
    check(n_regress == b_e + 1,
          "a step went backwards with no bus reset in between and it was not reported");

    // ---- Phase H2: a step number the sequence has no room for. ----
    do_detach;
    do_reset;
    ok_step(4'd2); ok_step(4'd3);
    b_e = n_badstep;
    step(1'b1, 4'd13, 1'b1, 1'b0, 1'b0, 1'b0, 1'b0);
    check(n_badstep == b_e + 1,
          "a step number outside the sequence was accepted -- a bad step number taken as progress makes max_step name a step nobody attempted, which is worse than no diagnosis because it is a confident one");
    check(max_step === 4'd3,
          "an out-of-range step number advanced the furthest step reached");
    step(1'b1, 4'd0, 1'b1, 1'b0, 1'b0, 1'b0, 1'b0);
    check(n_badstep == b_e + 2, "step number zero was accepted");

    // ---- Phase I: EXHAUSTIVE. Every current step x every input. ----
    for (s = 0; s <= N_STEP; s = s + 1) begin
      for (cb = 0; cb < 16; cb = cb + 1) begin
        do_detach;
        if (s > 0) begin
          do_reset;
          for (a = 2; a <= s; a = a + 1) ok_step(a[3:0]);
        end
        check(cur_step === s[3:0],
              "the sweep could not reach the step it meant to reach");
        step(cb[3], (s[3:0] + 4'd1), cb[2], cb[1], cb[0], 1'b1, 1'b0);
        step(cb[3], (s[3:0] + 4'd1), cb[2], cb[1], cb[0], 1'b1, 1'b0);
      end
    end

    // ---- Phase J: random ----
    for (k = 0; k < 30000; k = k + 1)
      step(($unsigned($random) % 100) < 36,
           ($unsigned($random) % 12),
           ($unsigned($random) % 100) < 62,
           ($unsigned($random) % 100) < 12,
           ($unsigned($random) % 1000) < 7,
           ($unsigned($random) % 100) < 70,
           1'b0);

    // ---- Phase K: and a clean enumeration afterwards. ----
    do_detach;
    b_c = n_complete;
    for (k = 0; k < 40; k = k + 1) begin
      do_detach;
      do_reset;
      for (s = 2; s <= N_STEP; s = s + 1) ok_step(s[3:0]);
      check(complete === 1'b1, "the tracker stopped recognising a complete enumeration");
    end
    check(n_complete == b_c + 40, "clean enumerations after the random phase were not counted");

    // ---- Final agreement ----
    check(n_steps     === m_st[31:0], "n_steps disagrees with the model");
    check(n_resets    === m_rs[31:0], "n_resets disagrees");
    check(n_detach    === m_dt[31:0], "n_detach disagrees");
    check(n_step_fail === m_sf[31:0], "n_step_fail disagrees");
    check(n_timeout   === m_to[31:0], "n_timeout disagrees");
    check(n_skip      === m_sk[31:0], "n_skip disagrees");
    check(n_regress   === m_rg[31:0], "n_regress disagrees");
    check(n_exhausted === m_ex[31:0], "n_exhausted disagrees");
    check(n_badstep   === m_bs[31:0], "n_badstep disagrees");
    check(n_complete  === m_cp[31:0], "n_complete disagrees");

    check(n_seen == 176, "not every current step was crossed with every input combination");
    check(n_step_fail > 32'd0, "no step ever failed");
    check(n_timeout   > 32'd0, "no step ever timed out");
    check(n_skip      > 32'd0, "no step was ever skipped");
    check(n_regress   > 32'd0, "no step ever went backwards");
    check(n_exhausted > 32'd0, "the retry limit was never reached");
    check(n_badstep   > 32'd0, "a step number outside the sequence was never seen");
    check(n_complete  > 32'd0, "enumeration never completed");
    check(n_detach    > 32'd0, "no device was ever detached");

    $display("REACH step-x-input=%0d/176 steps=%0d", n_seen, n_steps_t);
    $display("COUNTERS steps=%0d resets=%0d detach=%0d fail=%0d timeout=%0d skip=%0d regress=%0d exhausted=%0d complete=%0d",
             n_steps, n_resets, n_detach, n_step_fail, n_timeout, n_skip,
             n_regress, n_exhausted, n_complete);
    $display("         badstep=%0d", n_badstep);
    $display("%0s: %0d errors in %0d checks", (errors==0)?"PASS":"FAIL", errors, checks);
    $finish;
  end
endmodule

// Testbench for usb_enum_tracker (SystemVerilog).
//
// THE TEST THAT DEFINES THE CHAPTER
//
// Enumeration fails at step 6 and the host retries the whole sequence three
// times. At the end:
//
//     cur_step  reads 1     -- the third retry's first step
//     max_step  reads 6     -- THE DIAGNOSIS
//
// The suite drives exactly that and checks both numbers, because the whole
// argument of the chapter is that one of them is useless and the other is
// the answer. A tracker whose max_step is cleared by a bus reset reports 1
// as well, and a report of "the device does not get past ATTACH" sends
// somebody to look at VBUS.
//
// WHAT IS EXHAUSTIVE HERE
//
//   1. Every step 1..N_STEP as the FAILING step, with the full retry-and-
//      reset sequence around it, checking max_step each time. Ten failures,
//      ten different diagnoses, and the tracker must produce the right one
//      for each.
//
//   2. Every current step 0..N_STEP crossed with all 16 combinations of
//      {step_valid, step_ok, bus_reset, detach} = 176 pairs, each state
//      reached by real steps.
`timescale 1ns/1ps
module tb_et_sv;
  import usb_enum_pkg::*;

  localparam int N_STEP    = 10;
  localparam int RETRY_MAX = 3;
  localparam int STEP_TO   = 12;

  logic clk = 1'b0, rst_n = 1'b0;
  logic step_valid = 1'b0, step_ok = 1'b0;
  logic bus_reset = 1'b0, detach = 1'b0, bus_idle = 1'b1, eot = 1'b0;
  logic [3:0] step_id = 4'd0;

  logic [3:0] cur_step, max_step, fail_step, retries_at_max;
  fail_e      fail_reason;
  logic [4:0] step_age;
  logic complete, event_pulse;
  logic [31:0] n_steps, n_resets, n_detach, n_step_fail, n_timeout,
               n_skip, n_regress, n_exhausted, n_badstep, n_complete;

  usb_enum_tracker #(.N_STEP(N_STEP), .RETRY_MAX(RETRY_MAX),
                     .STEP_TO(STEP_TO)) 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 | cur=%0d max=%0d fail=%0d(%0d) rty=%0d age=%0d",
                   $time, msg, cur_step, max_step, fail_step, fail_reason,
                   retries_at_max, step_age);
      end
    end
  endtask

  // ------------------------------------------------------------------
  // The shadow tracker.
  // ------------------------------------------------------------------
  logic [3:0] m_cur, m_max, m_fail;
  fail_e      m_rsn;
  logic [4:0] m_age;
  logic       m_done, m_ev;
  logic [3:0] m_retry [1:N_STEP];
  int m_st, m_rs, m_dt, m_sf, m_to, m_sk, m_rg, m_ex, m_bs, m_cp;

  int seen [176];               // (N_STEP+1) x 16 input combinations
  int n_seen, n_steps_t;

  task automatic model_reset();
    int j;
    begin
      m_cur = 4'd0; m_max = 4'd0; m_fail = 4'd0; m_rsn = F_NONE;
      m_age = 5'd0; m_done = 1'b0; m_ev = 1'b0;
      for (j = 1; j <= N_STEP; j++) m_retry[j] = 4'd0;
      m_st = 0; m_rs = 0; m_dt = 0; m_sf = 0; m_to = 0;
      m_sk = 0; m_rg = 0; m_ex = 0; m_bs = 0; m_cp = 0;
      for (j = 0; j < 176; j++) seen[j] = 0;
      n_seen = 0; n_steps_t = 0;
    end
  endtask

  int idx;
  task automatic step(input logic sv, input logic [3:0] sid, input logic sok,
                      input logic brst, input logic det, input logic bidle,
                      input logic eo);
    logic [3:0] ncur, nmax, nfail, bidx;
    fail_e      nrsn;
    logic [4:0] nage;
    logic ndone, nev, nbump;
    begin
      step_valid = sv; step_id = sid; step_ok = sok;
      bus_reset = brst; detach = det; bus_idle = bidle; eot = eo;
      #1;

      check(cur_step    === m_cur,  "cur_step disagrees with the shadow tracker");
      check(max_step    === m_max,  "max_step disagrees -- and max_step IS the diagnosis");
      check(fail_step   === m_fail, "fail_step disagrees");
      check(fail_reason === m_rsn,  "fail_reason disagrees");
      check(step_age    === m_age,  "step_age disagrees");
      check(complete    === m_done, "complete disagrees");
      check(event_pulse === m_ev,   "the event pulse disagrees");
      check(retries_at_max === ((m_max == 4'd0) ? 4'd0 : m_retry[m_max]),
            "retries_at_max disagrees -- retries are counted PER STEP, and a global counter cannot produce this number");

      // ---- max_step is a HIGH-WATER MARK. It never goes backwards except
      // ---- on a detach, and that invariant is the whole block.
      check(m_max >= m_cur,
            "the furthest step reached is behind the current step, which is impossible");
      check(max_step <= 4'(N_STEP),
            "max_step names a step that does not exist");
      check(step_age <= 5'(STEP_TO),
            "the step timer ran past its bound");
      check(!((m_cur == 4'd0) && (step_age != 5'd0)),
            "the step timer is running with no enumeration in progress");

      idx = int'(m_cur) * 16 + (sv ? 8 : 0) + (sok ? 4 : 0) + (brst ? 2 : 0) + (det ? 1 : 0);
      if (idx < 176) begin
        if (seen[idx] == 0) begin seen[idx] = 1; n_seen = n_seen + 1; end
      end
      n_steps_t++;

      // ---- advance the shadow tracker ----
      ncur = m_cur; nmax = m_max; nfail = m_fail; nrsn = F_NONE;
      nage = m_age; ndone = m_done; nev = 1'b0; nbump = 1'b0; bidx = 4'd0;

      if (eo) begin
        nage = 5'd0;
      end else if (det) begin
        ncur = 4'd0; nmax = 4'd0; nfail = 4'd0; nrsn = F_NONE;
        nage = 5'd0; ndone = 1'b0;
      end else if (brst) begin
        ncur = 4'd1; nage = 5'd0; ndone = 1'b0;
        if (m_max < 4'd1) nmax = 4'd1;
      end else if (sv) begin
        nage = 5'd0;
        if ((sid < 4'd1) || (sid > 4'(N_STEP))) begin
          nev = 1'b1; nrsn = F_BADSTEP; nfail = sid;
        end else if (sid > m_cur + 4'd1) begin
          nev = 1'b1; nrsn = F_SKIP; nfail = sid; ncur = sid;
          if (sid > m_max) nmax = sid;
        end else if (sid <= m_cur) begin
          nev = 1'b1; nrsn = F_REGRESS; nfail = sid; ncur = sid;
        end else if (sok) begin
          ncur = sid;
          if (sid > m_max) nmax = sid;
          if (sid == 4'(N_STEP)) begin ndone = 1'b1; nev = 1'b1; end
        end else begin
          nev = 1'b1; nrsn = F_STEP_FAIL; nfail = sid;
          if (sid > m_max) nmax = sid;
          nbump = 1'b1; bidx = sid;
          if (m_retry[sid] + 4'd1 >= 4'(RETRY_MAX)) nrsn = F_EXHAUSTED;
        end
      end else if ((m_cur != 4'd0) && !m_done && (m_cur < 4'(N_STEP))) begin
        if (m_age >= 5'(STEP_TO) - 5'd1) begin
          nev = 1'b1; nrsn = F_TIMEOUT; nfail = m_cur + 4'd1; nage = 5'd0;
          nbump = 1'b1; bidx = m_cur + 4'd1;
          if (bidx > m_max) nmax = bidx;
        end else if (bidle) begin
          nage = m_age + 5'd1;
        end
      end

      m_cur = ncur; m_max = nmax; m_fail = nfail; m_rsn = nrsn;
      m_age = nage; m_ev = nev;
      if (det) begin
        for (idx = 1; idx <= N_STEP; idx++) m_retry[idx] = 4'd0;
        m_dt++;
      end else if (nbump && (bidx >= 4'd1) && (bidx <= 4'(N_STEP))) begin
        if (m_retry[bidx] != 4'hF) m_retry[bidx] = m_retry[bidx] + 4'd1;
      end
      if (ndone && !m_done) m_cp = m_cp + 1;
      m_done = ndone;

      if (sv && !det && !brst && !eo) m_st = m_st + 1;
      if (brst && !det && !eo)        m_rs = m_rs + 1;
      if (nev) begin
        case (nrsn)
          F_STEP_FAIL: m_sf = m_sf + 1;
          F_TIMEOUT:   m_to = m_to + 1;
          F_SKIP:      m_sk = m_sk + 1;
          F_REGRESS:   m_rg = m_rg + 1;
          F_EXHAUSTED: m_ex = m_ex + 1;
          F_BADSTEP:   m_bs = m_bs + 1;
          default: ;
        endcase
      end

      @(posedge clk); #1;
      step_valid = 1'b0; bus_reset = 1'b0; detach = 1'b0; eot = 1'b0;
    end
  endtask

  // A quiet bus. `bus_idle` must be HIGH here: the step timer counts DEAD
  // AIR, not elapsed time, so a "nop" that leaves the bus marked busy never
  // ages anything and the timeout phase below silently tests nothing.
  task automatic nop(input int n);
    repeat (n) step(1'b0,4'd0,1'b0, 1'b0,1'b0,1'b1,1'b0);
  endtask

  task automatic ok_step(input logic [3:0] s);
    step(1'b1,s,1'b1, 1'b0,1'b0,1'b0,1'b0);
  endtask

  task automatic bad_step(input logic [3:0] s);
    step(1'b1,s,1'b0, 1'b0,1'b0,1'b0,1'b0);
  endtask

  task automatic do_reset();
    step(1'b0,4'd0,1'b0, 1'b1,1'b0,1'b0,1'b0);
  endtask

  // A new device. This is the ONLY thing that clears the diagnosis.
  task automatic do_detach();
    begin
      step(1'b0,4'd0,1'b0, 1'b0,1'b1,1'b0,1'b0);
      nop(1);
      check(max_step === 4'd0,
            "a detach did not clear the furthest step -- the next device's report would name a step it never attempted");
      check(retries_at_max === 4'd0, "a detach did not clear the retry counts");
    end
  endtask

  int k, s, cb, b_e, b_sf, b_c, a;

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

    // ---- Phase A: the state after reset ----
    check(cur_step === 4'd0 && max_step === 4'd0, "reset left a step recorded");
    check(complete === 1'b0, "reset reported a complete enumeration");

    // ---- Phase B: a clean enumeration, end to end. ----
    for (k = 0; k < 40; k++) begin
      do_detach();
      b_c = n_complete;
      do_reset();
      for (s = 2; s <= N_STEP; s++) ok_step(4'(s));
      check(complete === 1'b1, "a complete enumeration was not reported complete");
      check(max_step === 4'(N_STEP), "a complete enumeration did not reach the last step");
      check(n_complete == b_c + 1, "the completion was not counted");
      // ...and a completed enumeration must NOT then time out.
      b_e = n_timeout;
      nop(STEP_TO + 4);
      check(n_timeout == b_e,
            "a COMPLETED enumeration timed out -- `complete` must be a sticky state, because one cycle later the tracker is sitting at the last step counting dead air toward a step that does not exist");
    end

    // ---- Phase C: THE CHAPTER. Fail at every step, retry three times, and
    // ---- read the diagnosis off max_step.
    for (s = 2; s <= N_STEP; s++) begin
      do_detach();
      for (k = 0; k < RETRY_MAX; k++) begin
        do_reset();
        for (a = 2; a < s; a++) ok_step(4'(a));
        bad_step(4'(s));
      end
      // The host gives up and resets once more before reporting.
      do_reset();
      check(cur_step === 4'd1,
            "the tracker is not sitting at step 1 after the final reset");
      check(max_step === 4'(s),
            "max_step is not the step that failed -- a tracker whose furthest step is cleared by a bus reset reports step 1 for every failure, and 'the device does not get past ATTACH' sends somebody to look at VBUS");
      check(retries_at_max === 4'(RETRY_MAX),
            "the retry count at the failing step is wrong -- retries are counted PER STEP, and 'fails at 5 three times' is a different bug from 'fails three times, somewhere'");
      check(fail_step === 4'(s), "fail_step is not the failing step");
    end

    // ---- Phase D: retries are PER STEP. Fail at two different steps and
    // ---- check the counts are kept apart.
    do_detach();
    do_reset();
    ok_step(4'd2); ok_step(4'd3); ok_step(4'd4);
    bad_step(4'd5); bad_step(4'd5);
    do_reset();
    ok_step(4'd2); ok_step(4'd3); ok_step(4'd4); ok_step(4'd5);
    ok_step(4'd6); ok_step(4'd7); ok_step(4'd8);
    bad_step(4'd9);
    check(max_step === 4'd9, "max_step did not follow the furthest step");
    check(retries_at_max === 4'd1,
          "the retry count at step 9 has picked up step 5's failures -- a single global counter cannot tell a deterministic bug from a marginal one");

    // ---- Phase E: RETRY_MAX is reported as its own reason. ----
    do_detach();
    b_e = n_exhausted;
    for (k = 0; k < RETRY_MAX; k++) begin
      do_reset();
      ok_step(4'd2); ok_step(4'd3); ok_step(4'd4);
      bad_step(4'd5);
    end
    check(n_exhausted == b_e + 1,
          "the host ran out of retries at one step and it was not reported as exhaustion -- which is the difference between 'it sometimes fails' and 'the host has given up'");

    // ---- Phase F: a step that never answers is not a step that failed. --
    for (k = 0; k < 20; k++) begin
      do_detach();
      do_reset();
      ok_step(4'd2); ok_step(4'd3);
      b_e = n_timeout; b_sf = n_step_fail;
      nop(STEP_TO - 1);
      check(n_timeout == b_e, "the tracker gave up before its own bound");
      nop(3);
      check(n_timeout == b_e + 1,
            "a step that never returned at all was not reported -- a failure is an answer and silence is not, and they have different causes");
      check(n_step_fail == b_sf,
            "a timeout was classified as a step failure");
      check(max_step === 4'd4,
            "the awaited step was not recorded as the furthest reached -- it was attempted, and naming it is the point");
    end

    // ---- Phase G: a SKIPPED step. ----
    do_detach();
    do_reset();
    ok_step(4'd2); ok_step(4'd3);
    b_e = n_skip;
    ok_step(4'd7);
    check(n_skip == b_e + 1,
          "the host jumped past three steps and it was not reported -- hosts do not skip by accident, and the finding is upstream of the step that appears to be missing");

    // ---- Phase H: a REGRESSING step, with no reset in between. ----
    do_detach();
    do_reset();
    ok_step(4'd2); ok_step(4'd3); ok_step(4'd4);
    b_e = n_regress;
    ok_step(4'd3);
    check(n_regress == b_e + 1,
          "a step went backwards with no bus reset in between and it was not reported");

    // ---- Phase H2: a step number the sequence has no room for. ----
    do_detach();
    do_reset();
    ok_step(4'd2); ok_step(4'd3);
    b_e = n_badstep;
    step(1'b1, 4'd13, 1'b1, 1'b0, 1'b0, 1'b0, 1'b0);
    check(n_badstep == b_e + 1,
          "a step number outside the sequence was accepted -- a bad step number taken as progress makes max_step name a step nobody attempted, which is worse than no diagnosis because it is a confident one");
    check(max_step === 4'd3,
          "an out-of-range step number advanced the furthest step reached");
    step(1'b1, 4'd0, 1'b1, 1'b0, 1'b0, 1'b0, 1'b0);
    check(n_badstep == b_e + 2, "step number zero was accepted");

    // ---- Phase I: EXHAUSTIVE. Every current step x every input. ----
    for (s = 0; s <= N_STEP; s++) begin
      for (cb = 0; cb < 16; cb++) begin
        do_detach();
        if (s > 0) begin
          do_reset();
          for (a = 2; a <= s; a++) ok_step(4'(a));
        end
        check(cur_step === 4'(s),
              "the sweep could not reach the step it meant to reach");
        step(1'(cb[3]), 4'(s + 1), 1'(cb[2]), 1'(cb[1]), 1'(cb[0]), 1'b1, 1'b0);
        step(1'(cb[3]), 4'(s + 1), 1'(cb[2]), 1'(cb[1]), 1'(cb[0]), 1'b1, 1'b0);
      end
    end

    // ---- Phase J: random ----
    for (k = 0; k < 30000; k++)
      step($urandom_range(0,99) < 36,
           4'($urandom_range(0,11)),
           $urandom_range(0,99) < 62,
           $urandom_range(0,99) < 12,
           $urandom_range(0,999) < 7,
           $urandom_range(0,99) < 70,
           1'b0);

    // ---- Phase K: and a clean enumeration afterwards. ----
    do_detach();
    b_c = n_complete;
    for (k = 0; k < 40; k++) begin
      do_detach();
      do_reset();
      for (s = 2; s <= N_STEP; s++) ok_step(4'(s));
      check(complete === 1'b1, "the tracker stopped recognising a complete enumeration");
    end
    check(n_complete == b_c + 40, "clean enumerations after the random phase were not counted");

    // ---- Final agreement ----
    check(n_steps     === 32'(m_st), "n_steps disagrees with the model");
    check(n_resets    === 32'(m_rs), "n_resets disagrees");
    check(n_detach    === 32'(m_dt), "n_detach disagrees");
    check(n_step_fail === 32'(m_sf), "n_step_fail disagrees");
    check(n_timeout   === 32'(m_to), "n_timeout disagrees");
    check(n_skip      === 32'(m_sk), "n_skip disagrees");
    check(n_regress   === 32'(m_rg), "n_regress disagrees");
    check(n_exhausted === 32'(m_ex), "n_exhausted disagrees");
    check(n_badstep   === 32'(m_bs), "n_badstep disagrees");
    check(n_complete  === 32'(m_cp), "n_complete disagrees");

    check(n_seen == 176, "not every current step was crossed with every input combination");
    check(n_step_fail > 32'd0, "no step ever failed");
    check(n_timeout   > 32'd0, "no step ever timed out");
    check(n_skip      > 32'd0, "no step was ever skipped");
    check(n_regress   > 32'd0, "no step ever went backwards");
    check(n_exhausted > 32'd0, "the retry limit was never reached");
    check(n_badstep   > 32'd0, "a step number outside the sequence was never seen");
    check(n_complete  > 32'd0, "enumeration never completed");
    check(n_detach    > 32'd0, "no device was ever detached");

    $display("REACH step-x-input=%0d/176 steps=%0d", n_seen, n_steps_t);
    $display("COUNTERS steps=%0d resets=%0d detach=%0d fail=%0d timeout=%0d skip=%0d regress=%0d exhausted=%0d complete=%0d",
             n_steps, n_resets, n_detach, n_step_fail, n_timeout, n_skip,
             n_regress, n_exhausted, n_complete);
    $display("         badstep=%0d", n_badstep);
    $display("%0s: %0d errors in %0d checks", (errors==0)?"PASS":"FAIL", errors, checks);
    $finish;
  end
endmodule