The Transfer-Types Question

   The one question that generates the table:

     reservation?  --no-->  BULK      (retry freely, no deadline)
          |
         yes
          |
     big enough to fill a frame?
          |                    |
         yes                   no
          |                    |
     ISOCHRONOUS           INTERRUPT
     (no room to retry)    (small enough that a retry fits)

   CONTROL is the special case: its own separate 10%, so that a
   full periodic schedule can never stop the host talking.

// =====================================================================
//  usb_xfer_admit -- "Which transfer type, and why?" answered in hardware.
//
//  The four types are easy to list and the trade is easy to state
//  backwards. What candidates say: "isochronous is fast but unreliable."
//  What is actually true:
//
//      Guaranteed bandwidth and guaranteed delivery are the SAME
//      resource spent two different ways.
//
//  An isochronous endpoint is promised a slot in every frame. A retry
//  needs a slot. Every slot is already allocated -- that is what the
//  promise means -- so there is nowhere to put the retry. Isochronous
//  is not unreliable because somebody skimped on error handling; it is
//  unreliable BECAUSE it is guaranteed.
//
//  Bulk is the mirror image: no reservation at all, therefore retries
//  are free, therefore delivery is certain and timing is not.
//
//  This module is the host's admission control: it decides whether a new
//  endpoint can be accepted into the schedule, and it is the place where
//  the trade becomes arithmetic.
// =====================================================================
module usb_xfer_admit #(
  // A USB 2.0 full-speed frame is 1500 bytes at 12 Mbit/s. The
  // specification reserves at most 90% for periodic traffic and at least
  // 10% for control, and the two limits are separate rules.
  parameter integer FRAME_BYTES   = 1500,
  parameter integer PERIODIC_MAX  = 1350,   // 90% of the frame
  parameter integer CONTROL_MIN   = 150,    // 10%, reserved for control
  parameter integer N_EP          = 8
) (
  input  wire        clk,
  input  wire        rst_n,

  // ---- a request to admit an endpoint into the schedule ----
  input  wire        req_valid,
  input  wire [1:0]  req_type,     // X_CTRL / X_ISO / X_INT / X_BULK
  input  wire [10:0] req_maxp,     // bytes per transaction
  input  wire [7:0]  req_interval, // frames between polls (periodic only)

  // ---- withdraw a previously admitted endpoint ----
  input  wire        rel_valid,
  input  wire [3:0]  rel_slot,

  // ---- the decision, one cycle later ----
  output wire        adm_done,
  output wire        adm_ok,
  output wire [2:0]  adm_reason,
  output wire [3:0]  adm_slot,

  // ---- the schedule as it stands ----
  output wire [15:0] used_periodic,
  output wire [15:0] used_control,
  output wire [15:0] n_admitted,

  // ---- observability ----
  output wire [31:0] n_req,
  output wire [31:0] n_reject_bw,
  output wire [31:0] n_reject_interval,
  output wire [31:0] n_reject_maxp,
  output wire [31:0] n_reject_full,
  output wire [31:0] n_overcommit     // must always read 0
);

  localparam [1:0] X_CTRL = 2'd0, X_ISO = 2'd1, X_INT = 2'd2, X_BULK = 2'd3;

  localparam [2:0] R_OK        = 3'd0,
                   R_BW        = 3'd1,   // no periodic bandwidth left
                   R_INTERVAL  = 3'd2,   // interval not a legal value
                   R_MAXP      = 3'd3,   // packet too large for the type
                   R_FULL      = 3'd4,   // no free slot
                   R_CTRL_ROOM = 3'd5;   // would eat the control reservation

  // ---- the largest packet each type may use at full speed ----
  //
  // These are not stylistic limits. Isochronous gets the biggest packet
  // because it is the type that cannot retry, so a lost packet must cost
  // as little as possible in transactions -- one big one beats eight small
  // ones when none of them can be repeated.
  function [10:0] max_packet;
    input [1:0] t;
    begin
      case (t)
        X_CTRL: max_packet = 11'd64;
        X_ISO:  max_packet = 11'd1023;
        X_INT:  max_packet = 11'd64;
        default: max_packet = 11'd64;      // bulk
      endcase
    end
  endfunction

  // ---- a periodic endpoint's cost, per frame ----
  //
  // maxp bytes every `interval` frames is maxp/interval bytes per frame on
  // average -- but the schedule must survive the WORST frame, not the
  // average one, so the cost charged is the full maxp. Charging the average
  // is how a schedule that passes admission control then misses deadlines.
  function [15:0] frame_cost;
    input [10:0] mp;
    begin
      // Bytes on the wire are more than the payload: token, data PID, CRC
      // and inter-packet gap. 13 bytes of overhead per transaction at full
      // speed is the conventional figure and it is not negligible for small
      // packets -- an 8-byte interrupt endpoint costs 21, not 8.
      frame_cost = {5'd0, mp} + 16'd13;
    end
  endfunction

  // ---- a legal interval is a power of two, in frames ----
  function is_pow2;
    input [7:0] v;
    begin
      is_pow2 = (v != 8'd0) && ((v & (v - 8'd1)) == 8'd0);
    end
  endfunction

  reg [15:0] per_r;      // periodic bytes committed per frame
  reg [15:0] ctl_r;      // control bytes committed per frame
  reg [15:0] cnt_r;      // how many endpoints are admitted

  reg [10:0] slot_mp   [0:N_EP-1];
  reg [1:0]  slot_type [0:N_EP-1];
  // A packed vector rather than an array of regs, so that a same-cycle
  // release can be MASKED OUT of it combinationally. See used_now below.
  reg [N_EP-1:0] used_r;

  reg        done_r;
  reg        ok_r;
  reg [2:0]  why_r;
  reg [3:0]  slot_r;

  reg [31:0] req_c, bw_c, iv_c, mp_c, full_c, over_c;

  assign adm_done          = done_r;
  assign adm_ok            = ok_r;
  assign adm_reason        = why_r;
  assign adm_slot          = slot_r;
  assign used_periodic     = per_r;
  assign used_control      = ctl_r;
  assign n_admitted        = cnt_r;
  assign n_req             = req_c;
  assign n_reject_bw       = bw_c;
  assign n_reject_interval = iv_c;
  assign n_reject_maxp     = mp_c;
  assign n_reject_full     = full_c;
  assign n_overcommit      = over_c;

  // =================================================================
  //  THE POST-RELEASE VIEW.
  //
  //  A release written "before" the request in source order is NOT applied
  //  before it in hardware: every read below sees the registered value, so
  //  a driver that closes one endpoint and opens another in the same cycle
  //  would be refused for want of a slot it just freed.
  //
  //  Being refused is not a functional failure -- the driver retries and
  //  succeeds -- which is exactly why this is worth getting right. The
  //  symptom is a bandwidth limit that appears only under load, and it is
  //  unreproducible because it depends on whether two operations happened
  //  to land in one cycle.
  //
  //  So the post-release state is computed explicitly and everything that
  //  decides the request reads THAT.
  // =================================================================
  wire rel_hit = rel_valid && (rel_slot < N_EP) && used_r[rel_slot];

  wire [15:0] rel_cost = frame_cost(slot_mp[rel_slot]);
  wire        rel_per  = rel_hit && ((slot_type[rel_slot] == X_ISO) ||
                                     (slot_type[rel_slot] == X_INT));
  wire        rel_ctl  = rel_hit && (slot_type[rel_slot] == X_CTRL);

  wire [N_EP-1:0] used_now = rel_hit ? (used_r & ~({{(N_EP-1){1'b0}}, 1'b1} << rel_slot))
                                     : used_r;
  wire [15:0]     per_now  = rel_per ? (per_r - rel_cost) : per_r;
  wire [15:0]     ctl_now  = rel_ctl ? (ctl_r - rel_cost) : ctl_r;

  // ---- the first free slot, in the POST-RELEASE view ----
  integer j;
  reg [3:0]  free_slot;
  reg        have_free;

  always @* begin
    free_slot = 4'd0;
    have_free = 1'b0;
    for (j = N_EP - 1; j >= 0; j = j - 1)
      if (!used_now[j]) begin
        free_slot = j[3:0];
        have_free = 1'b1;
      end
  end

  wire is_periodic = (req_type == X_ISO) || (req_type == X_INT);
  wire [15:0] cost = frame_cost(req_maxp);

  integer k;

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      per_r  <= 16'd0;
      ctl_r  <= 16'd0;
      cnt_r  <= 16'd0;
      done_r <= 1'b0;
      ok_r   <= 1'b0;
      why_r  <= R_OK;
      slot_r <= 4'd0;
      req_c  <= 32'd0;
      bw_c   <= 32'd0;
      iv_c   <= 32'd0;
      mp_c   <= 32'd0;
      full_c <= 32'd0;
      over_c <= 32'd0;
      used_r <= {N_EP{1'b0}};
      for (k = 0; k < N_EP; k = k + 1) begin
        slot_mp[k]   <= 11'd0;
        slot_type[k] <= X_CTRL;
      end
    end else begin
      done_r <= 1'b0;
      ok_r   <= 1'b0;
      why_r  <= R_OK;

      // ---- release first, so a slot freed this cycle is available ----
      //
      // Applied before the request below, which means a driver that closes
      // one endpoint and opens another in the same cycle succeeds. Ordering
      // it the other way rejects the request and the driver retries -- which
      // works, and looks like a bandwidth bug under load.
      if (rel_hit) begin
        cnt_r <= cnt_r - 16'd1;
        if      (rel_per) per_r <= per_now;
        else if (rel_ctl) ctl_r <= ctl_now;
      end
      used_r <= used_now;

      if (req_valid) begin
        req_c  <= req_c + 32'd1;
        done_r <= 1'b1;
        slot_r <= free_slot;

        // ---- the checks, in the order that makes the reason useful ----
        //
        // Cheapest and most specific first. A request that is wrong in two
        // ways should report the one the driver can act on.
        if (req_maxp > max_packet(req_type)) begin
          ok_r  <= 1'b0;
          why_r <= R_MAXP;
          mp_c  <= mp_c + 32'd1;

        end else if (is_periodic && !is_pow2(req_interval)) begin
          // A periodic interval must be a power of two so the host can
          // place the endpoint in a binary tree of frames. 3 frames is not
          // schedulable however much bandwidth is free.
          ok_r  <= 1'b0;
          why_r <= R_INTERVAL;
          iv_c  <= iv_c + 32'd1;

        end else if (!have_free) begin
          ok_r   <= 1'b0;
          why_r  <= R_FULL;
          full_c <= full_c + 32'd1;

        end else if (is_periodic && ((per_now + cost) > PERIODIC_MAX)) begin
          // The 90% rule. This is the one that makes isochronous what it
          // is: once the periodic budget is spoken for, nothing more gets
          // in -- and nothing already in can be retried either.
          ok_r  <= 1'b0;
          why_r <= R_BW;
          bw_c  <= bw_c + 32'd1;

        end else if ((req_type == X_CTRL) &&
                     ((ctl_now + cost) > CONTROL_MIN)) begin
          // The 10% rule, and it is a SEPARATE limit rather than the
          // remainder of the periodic one. Control traffic has its own
          // reservation precisely so that a fully committed periodic
          // schedule cannot stop the host talking to its devices.
          ok_r  <= 1'b0;
          why_r <= R_CTRL_ROOM;
          bw_c  <= bw_c + 32'd1;

        end else begin
          ok_r  <= 1'b1;
          why_r <= R_OK;
          used_r               <= used_now | ({{(N_EP-1){1'b0}}, 1'b1} << free_slot);
          slot_mp[free_slot]   <= req_maxp;
          slot_type[free_slot] <= req_type;
          cnt_r <= rel_hit ? cnt_r : (cnt_r + 16'd1);
          if (is_periodic)              per_r <= per_now + cost;
          else if (req_type == X_CTRL)  ctl_r <= ctl_now + cost;
          // Bulk is charged NOTHING. It has no reservation, which is
          // exactly why it can retry: it uses whatever the frame has left
          // after everything with a promise has been served.
        end
      end

      // ---- the self-check that makes the whole thing measurable ----
      //
      // The periodic commitment must never exceed its ceiling, and the
      // control commitment must never exceed its reservation. Unreachable
      // on a correct design, counted so a run can publish zero.
      if ((per_r > PERIODIC_MAX) || (ctl_r > CONTROL_MIN))
        over_c <= over_c + 32'd1;
    end
  end

endmodule

// =====================================================================
//  usb_xfer_admit -- SystemVerilog.
//
//  The transfer types and the rejection reasons become named enumerations,
//  which matters here for a specific reason: this module's job is to REPORT
//  WHY, and a rejection reason that arrives as the integer 5 is a reason
//  nobody reads. `R_CTRL_ROOM` in a waveform is a diagnosis.
//
//  The four types are easy to list and the trade is easy to state
//  backwards. What candidates say: "isochronous is fast but unreliable."
//  What is actually true:
//
//      Guaranteed bandwidth and guaranteed delivery are the SAME
//      resource spent two different ways.
//
//  An isochronous endpoint is promised a slot in every frame. A retry
//  needs a slot. Every slot is already allocated -- that is what the
//  promise means -- so there is nowhere to put the retry. Isochronous
//  is not unreliable because somebody skimped on error handling; it is
//  unreliable BECAUSE it is guaranteed.
//
//  Bulk is the mirror image: no reservation at all, therefore retries
//  are free, therefore delivery is certain and timing is not.
//
//  This module is the host's admission control: it decides whether a new
//  endpoint can be accepted into the schedule, and it is the place where
//  the trade becomes arithmetic.
// =====================================================================
module usb_xfer_admit #(
  // A USB 2.0 full-speed frame is 1500 bytes at 12 Mbit/s. The
  // specification reserves at most 90% for periodic traffic and at least
  // 10% for control, and the two limits are separate rules.
  parameter int FRAME_BYTES   = 1500,
  parameter int PERIODIC_MAX  = 1350,   // 90% of the frame
  parameter int CONTROL_MIN   = 150,    // 10%, reserved for control
  parameter int N_EP          = 8
) (
  input  logic       clk,
  input  logic       rst_n,

  // ---- a request to admit an endpoint into the schedule ----
  input  logic       req_valid,
  input  logic [1:0] req_type,     // X_CTRL / X_ISO / X_INT / X_BULK
  input  logic [10:0]req_maxp,     // bytes per transaction
  input  logic [7:0] req_interval, // frames between polls (periodic only)

  // ---- withdraw a previously admitted endpoint ----
  input  logic       rel_valid,
  input  logic [3:0] rel_slot,

  // ---- the decision, one cycle later ----
  output logic       adm_done,
  output logic       adm_ok,
  output logic [2:0] adm_reason,
  output logic [3:0] adm_slot,

  // ---- the schedule as it stands ----
  output logic [15:0]used_periodic,
  output logic [15:0]used_control,
  output logic [15:0]n_admitted,

  // ---- observability ----
  output logic [31:0]n_req,
  output logic [31:0]n_reject_bw,
  output logic [31:0]n_reject_interval,
  output logic [31:0]n_reject_maxp,
  output logic [31:0]n_reject_full,
  output logic [31:0]n_overcommit     // must always read 0
);

  typedef enum logic [1:0] { X_CTRL = 2'd0, X_ISO = 2'd1,
                             X_INT  = 2'd2, X_BULK = 2'd3 } xfer_e;

  // A rejection reason that arrives as the integer 5 is a reason nobody
  // reads. This is the output the driver author actually consumes.
  typedef enum logic [2:0] {
    R_OK        = 3'd0,
    R_BW        = 3'd1,   // no periodic bandwidth left
    R_INTERVAL  = 3'd2,   // interval not a legal value
    R_MAXP      = 3'd3,   // packet too large for the type
    R_FULL      = 3'd4,   // no free slot
    R_CTRL_ROOM = 3'd5    // would eat the control reservation
  } reason_e;

  // ---- the largest packet each type may use at full speed ----
  //
  // These are not stylistic limits. Isochronous gets the biggest packet
  // because it is the type that cannot retry, so a lost packet must cost
  // as little as possible in transactions -- one big one beats eight small
  // ones when none of them can be repeated.
  function automatic logic [10:0] max_packet(logic [1:0] t);
    begin
      case (t)
        X_CTRL: max_packet = 11'd64;
        X_ISO:  max_packet = 11'd1023;
        X_INT:  max_packet = 11'd64;
        default: max_packet = 11'd64;      // bulk
      endcase
    end
  endfunction

  // ---- a periodic endpoint's cost, per frame ----
  //
  // maxp bytes every `interval` frames is maxp/interval bytes per frame on
  // average -- but the schedule must survive the WORST frame, not the
  // average one, so the cost charged is the full maxp. Charging the average
  // is how a schedule that passes admission control then misses deadlines.
  function automatic logic [15:0] frame_cost(logic [10:0] mp);
    begin
      // Bytes on the wire are more than the payload: token, data PID, CRC
      // and inter-packet gap. 13 bytes of overhead per transaction at full
      // speed is the conventional figure and it is not negligible for small
      // packets -- an 8-byte interrupt endpoint costs 21, not 8.
      frame_cost = {5'd0, mp} + 16'd13;
    end
  endfunction

  // ---- a legal interval is a power of two, in frames ----
  function automatic logic is_pow2(logic [7:0] v);
    begin
      is_pow2 = (v != 8'd0) && ((v & (v - 8'd1)) == 8'd0);
    end
  endfunction

  logic [15:0] per_r;      // periodic bytes committed per frame
  logic [15:0] ctl_r;      // control bytes committed per frame
  logic [15:0] cnt_r;      // how many endpoints are admitted

  logic [10:0] slot_mp   [N_EP];
  xfer_e       slot_type [N_EP];
  // A packed vector rather than an array of regs, so that a same-cycle
  // release can be MASKED OUT of it combinationally. See used_now below.
  logic [N_EP-1:0] used_r;

  logic      done_r;
  logic      ok_r;
  reason_e   why_r;
  logic [3:0] slot_r;

  logic [31:0] req_c, bw_c, iv_c, mp_c, full_c, over_c;

  assign adm_done          = done_r;
  assign adm_ok            = ok_r;
  assign adm_reason        = why_r;
  assign adm_slot          = slot_r;
  assign used_periodic     = per_r;
  assign used_control      = ctl_r;
  assign n_admitted        = cnt_r;
  assign n_req             = req_c;
  assign n_reject_bw       = bw_c;
  assign n_reject_interval = iv_c;
  assign n_reject_maxp     = mp_c;
  assign n_reject_full     = full_c;
  assign n_overcommit      = over_c;

  // =================================================================
  //  THE POST-RELEASE VIEW.
  //
  //  A release written "before" the request in source order is NOT applied
  //  before it in hardware: every read below sees the registered value, so
  //  a driver that closes one endpoint and opens another in the same cycle
  //  would be refused for want of a slot it just freed.
  //
  //  Being refused is not a functional failure -- the driver retries and
  //  succeeds -- which is exactly why this is worth getting right. The
  //  symptom is a bandwidth limit that appears only under load, and it is
  //  unreproducible because it depends on whether two operations happened
  //  to land in one cycle.
  //
  //  So the post-release state is computed explicitly and everything that
  //  decides the request reads THAT.
  // =================================================================
  wire rel_hit = rel_valid && (rel_slot < N_EP) && used_r[rel_slot];

  wire [15:0] rel_cost = frame_cost(slot_mp[rel_slot]);
  wire        rel_per  = rel_hit && ((slot_type[rel_slot] == X_ISO) ||
                                     (slot_type[rel_slot] == X_INT));
  wire        rel_ctl  = rel_hit && (slot_type[rel_slot] == X_CTRL);

  wire [N_EP-1:0] used_now = rel_hit ? (used_r & ~({{(N_EP-1){1'b0}}, 1'b1} << rel_slot))
                                     : used_r;
  wire [15:0]     per_now  = rel_per ? (per_r - rel_cost) : per_r;
  wire [15:0]     ctl_now  = rel_ctl ? (ctl_r - rel_cost) : ctl_r;

  // ---- the first free slot, in the POST-RELEASE view ----
  logic [3:0] free_slot;
  logic       have_free;

  always_comb begin
    free_slot = 4'd0;
    have_free = 1'b0;
    for (int j = N_EP - 1; j >= 0; j--)
      if (!used_now[j]) begin
        free_slot = j[3:0];
        have_free = 1'b1;
      end
  end

  wire is_periodic = (req_type == X_ISO) || (req_type == X_INT);
  wire [15:0] cost = frame_cost(req_maxp);


  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      per_r  <= 16'd0;
      ctl_r  <= 16'd0;
      cnt_r  <= 16'd0;
      done_r <= 1'b0;
      ok_r   <= 1'b0;
      why_r  <= R_OK;
      slot_r <= 4'd0;
      req_c  <= 32'd0;
      bw_c   <= 32'd0;
      iv_c   <= 32'd0;
      mp_c   <= 32'd0;
      full_c <= 32'd0;
      over_c <= 32'd0;
      used_r <= {N_EP{1'b0}};
      for (int k = 0; k < N_EP; k++) begin
        slot_mp[k]   <= 11'd0;
        slot_type[k] <= X_CTRL;
      end
    end else begin
      done_r <= 1'b0;
      ok_r   <= 1'b0;
      why_r  <= R_OK;

      // ---- release first, so a slot freed this cycle is available ----
      //
      // Applied before the request below, which means a driver that closes
      // one endpoint and opens another in the same cycle succeeds. Ordering
      // it the other way rejects the request and the driver retries -- which
      // works, and looks like a bandwidth bug under load.
      if (rel_hit) begin
        cnt_r <= cnt_r - 16'd1;
        if      (rel_per) per_r <= per_now;
        else if (rel_ctl) ctl_r <= ctl_now;
      end
      used_r <= used_now;

      if (req_valid) begin
        req_c  <= req_c + 32'd1;
        done_r <= 1'b1;
        slot_r <= free_slot;

        // ---- the checks, in the order that makes the reason useful ----
        //
        // Cheapest and most specific first. A request that is wrong in two
        // ways should report the one the driver can act on.
        if (req_maxp > max_packet(req_type)) begin
          ok_r  <= 1'b0;
          why_r <= R_MAXP;
          mp_c  <= mp_c + 32'd1;

        end else if (is_periodic && !is_pow2(req_interval)) begin
          // A periodic interval must be a power of two so the host can
          // place the endpoint in a binary tree of frames. 3 frames is not
          // schedulable however much bandwidth is free.
          ok_r  <= 1'b0;
          why_r <= R_INTERVAL;
          iv_c  <= iv_c + 32'd1;

        end else if (!have_free) begin
          ok_r   <= 1'b0;
          why_r  <= R_FULL;
          full_c <= full_c + 32'd1;

        end else if (is_periodic && ((per_now + cost) > PERIODIC_MAX)) begin
          // The 90% rule. This is the one that makes isochronous what it
          // is: once the periodic budget is spoken for, nothing more gets
          // in -- and nothing already in can be retried either.
          ok_r  <= 1'b0;
          why_r <= R_BW;
          bw_c  <= bw_c + 32'd1;

        end else if ((req_type == X_CTRL) &&
                     ((ctl_now + cost) > CONTROL_MIN)) begin
          // The 10% rule, and it is a SEPARATE limit rather than the
          // remainder of the periodic one. Control traffic has its own
          // reservation precisely so that a fully committed periodic
          // schedule cannot stop the host talking to its devices.
          ok_r  <= 1'b0;
          why_r <= R_CTRL_ROOM;
          bw_c  <= bw_c + 32'd1;

        end else begin
          ok_r  <= 1'b1;
          why_r <= R_OK;
          used_r               <= used_now | ({{(N_EP-1){1'b0}}, 1'b1} << free_slot);
          slot_mp[free_slot]   <= req_maxp;
          slot_type[free_slot] <= xfer_e'(req_type);
          cnt_r <= rel_hit ? cnt_r : (cnt_r + 16'd1);
          if (is_periodic)              per_r <= per_now + cost;
          else if (req_type == X_CTRL)  ctl_r <= ctl_now + cost;
          // Bulk is charged NOTHING. It has no reservation, which is
          // exactly why it can retry: it uses whatever the frame has left
          // after everything with a promise has been served.
        end
      end

      // ---- the self-check that makes the whole thing measurable ----
      //
      // The periodic commitment must never exceed its ceiling, and the
      // control commitment must never exceed its reservation. Unreachable
      // on a correct design, counted so a run can publish zero.
      if ((per_r > PERIODIC_MAX) || (ctl_r > CONTROL_MIN))
        over_c <= over_c + 32'd1;
    end
  end

endmodule

-- =====================================================================
--  usb_xfer_admit -- VHDL-2008.
--
--  The transfer types and the rejection reasons are enumerations of
--  genuinely distinct types, so the compiler refuses to confuse a reason
--  with a type. That matters here because this module's whole output is a
--  DIAGNOSIS: "refused" is useless, "refused because the control
--  reservation is full" tells a driver author what to change.
--
--  Constants are prefixed because VHDL identifiers are case-insensitive:
--  a package constant and a same-named port are one name and the port
--  wins, silently.
-- =====================================================================
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

package xt_pkg is
  type xfer_t is (XT_CTRL, XT_ISO, XT_INT, XT_BULK);

  type reason_t is (RS_OK,
                    RS_BW,         -- no periodic bandwidth left
                    RS_INTERVAL,   -- interval not a legal value
                    RS_MAXP,       -- packet too large for the type
                    RS_FULL,       -- no free slot
                    RS_CTRL_ROOM); -- would eat the control reservation

  function xfer_of(v : std_logic_vector(1 downto 0)) return xfer_t;
  function code_of(r : reason_t) return std_logic_vector;
  function is_periodic_t(t : xfer_t) return boolean;

  -- A transaction costs more than its payload: token, data PID, CRC and
  -- inter-packet gap. 13 bytes at full speed is the conventional figure,
  -- and it is not negligible for small packets -- an 8-byte interrupt
  -- endpoint costs 21, not 8.
  constant TXN_OVERHEAD : natural := 13;

  type mp_array is array (natural range <>) of unsigned(10 downto 0);
  type ty_array is array (natural range <>) of xfer_t;
end package;

package body xt_pkg is
  function xfer_of(v : std_logic_vector(1 downto 0)) return xfer_t is
  begin
    case v is
      when "00"   => return XT_CTRL;
      when "01"   => return XT_ISO;
      when "10"   => return XT_INT;
      when others => return XT_BULK;
    end case;
  end function;

  function code_of(r : reason_t) return std_logic_vector is
  begin
    case r is
      when RS_OK        => return "000";
      when RS_BW        => return "001";
      when RS_INTERVAL  => return "010";
      when RS_MAXP      => return "011";
      when RS_FULL      => return "100";
      when RS_CTRL_ROOM => return "101";
    end case;
  end function;

  function is_periodic_t(t : xfer_t) return boolean is
  begin
    return t = XT_ISO or t = XT_INT;
  end function;
end package body;

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

entity usb_xfer_admit is
  generic (
    FRAME_BYTES  : natural := 1500;
    PERIODIC_MAX : natural := 1350;   -- 90% of the frame
    CONTROL_MIN  : natural := 150;    -- 10%, reserved for control
    N_EP         : natural := 8
  );
  port (
    clk          : in  std_logic;
    rst_n        : in  std_logic;

    req_valid    : in  std_logic;
    req_type     : in  std_logic_vector(1 downto 0);
    req_maxp     : in  std_logic_vector(10 downto 0);
    req_interval : in  std_logic_vector(7 downto 0);

    rel_valid    : in  std_logic;
    rel_slot     : in  std_logic_vector(3 downto 0);

    adm_done     : out std_logic;
    adm_ok       : out std_logic;
    adm_reason   : out std_logic_vector(2 downto 0);
    adm_slot     : out std_logic_vector(3 downto 0);

    used_periodic : out std_logic_vector(15 downto 0);
    used_control  : out std_logic_vector(15 downto 0);
    n_admitted    : out std_logic_vector(15 downto 0);

    n_req             : out std_logic_vector(31 downto 0);
    n_reject_bw       : out std_logic_vector(31 downto 0);
    n_reject_interval : out std_logic_vector(31 downto 0);
    n_reject_maxp     : out std_logic_vector(31 downto 0);
    n_reject_full     : out std_logic_vector(31 downto 0);
    n_overcommit      : out std_logic_vector(31 downto 0)
  );
end entity;

architecture rtl of usb_xfer_admit is
  signal per_r, ctl_r, cnt_r : unsigned(15 downto 0) := (others => '0');
  signal used_r  : std_logic_vector(N_EP-1 downto 0) := (others => '0');
  signal slot_mp : mp_array(0 to N_EP-1) := (others => (others => '0'));
  signal slot_ty : ty_array(0 to N_EP-1) := (others => XT_CTRL);

  signal done_r : std_logic := '0';
  signal ok_r   : std_logic := '0';
  signal why_r  : reason_t  := RS_OK;
  signal slot_r : unsigned(3 downto 0) := (others => '0');

  signal req_c, bw_c, iv_c, mp_c, full_c, over_c : unsigned(31 downto 0)
    := (others => '0');

  -- ---- the largest packet each type may use at full speed ----
  --
  -- Isochronous gets the biggest packet because it is the type that cannot
  -- retry: a lost packet must cost as few transactions as possible, and one
  -- big one beats eight small ones when none of them can be repeated.
  -- A case over all four types rather than "ISO or not", so that the
  -- per-type limits can be changed independently. Collapsing it to a single
  -- comparison also collapses three mutations into one: a mutation of the
  -- control limit then silently changes interrupt and bulk too, and the
  -- VHDL column reads 116236 against Verilog's 64357.
  function max_packet(t : xfer_t) return unsigned is
  begin
    case t is
      when XT_CTRL => return to_unsigned(64, 11);
      when XT_ISO  => return to_unsigned(1023, 11);
      when XT_INT  => return to_unsigned(64, 11);
      when XT_BULK => return to_unsigned(64, 11);
    end case;
  end function;

  -- The cost charged is the FULL packet, not maxp/interval. The schedule
  -- must survive the worst frame, not the average one; charging the average
  -- is how a schedule passes admission control and then misses deadlines.
  function frame_cost(mp : unsigned(10 downto 0)) return unsigned is
  begin
    return resize(mp, 16) + to_unsigned(TXN_OVERHEAD, 16);
  end function;

  -- A legal periodic interval is a power of two, in frames, so the host can
  -- place the endpoint in a binary tree of frames. 3 frames is not
  -- schedulable however much bandwidth is free.
  function is_pow2(v : unsigned(7 downto 0)) return boolean is
  begin
    return v /= 0 and (v and (v - 1)) = 0;
  end function;
begin

  adm_done      <= done_r;
  adm_ok        <= ok_r;
  adm_reason    <= code_of(why_r);
  adm_slot      <= std_logic_vector(slot_r);
  used_periodic <= std_logic_vector(per_r);
  used_control  <= std_logic_vector(ctl_r);
  n_admitted    <= std_logic_vector(cnt_r);

  n_req             <= std_logic_vector(req_c);
  n_reject_bw       <= std_logic_vector(bw_c);
  n_reject_interval <= std_logic_vector(iv_c);
  n_reject_maxp     <= std_logic_vector(mp_c);
  n_reject_full     <= std_logic_vector(full_c);
  n_overcommit      <= std_logic_vector(over_c);

  main : process(clk, rst_n)
    -- The POST-RELEASE view. A release written before the request in source
    -- order is not applied before it in hardware: every read sees the
    -- registered value, so a driver that closes one endpoint and opens
    -- another in one cycle would be refused for a slot it just freed.
    --
    -- Being refused is not a functional failure -- the driver retries -- which
    -- is why it is worth getting right: the symptom is a bandwidth limit that
    -- appears only under load and cannot be reproduced.
    variable rs_i     : natural;
    variable rel_hit  : boolean;
    variable rel_cost : unsigned(15 downto 0);
    variable used_now : std_logic_vector(N_EP-1 downto 0);
    variable per_now, ctl_now : unsigned(15 downto 0);
    variable free_slot : natural;
    variable have_free : boolean;
    variable t         : xfer_t;
    variable cost      : unsigned(15 downto 0);
    variable per_req   : boolean;
  begin
    if rst_n = '0' then
      per_r  <= (others => '0');
      ctl_r  <= (others => '0');
      cnt_r  <= (others => '0');
      used_r <= (others => '0');
      done_r <= '0';
      ok_r   <= '0';
      why_r  <= RS_OK;
      slot_r <= (others => '0');
      req_c  <= (others => '0');
      bw_c   <= (others => '0');
      iv_c   <= (others => '0');
      mp_c   <= (others => '0');
      full_c <= (others => '0');
      over_c <= (others => '0');
      slot_mp <= (others => (others => '0'));
      slot_ty <= (others => XT_CTRL);

    elsif rising_edge(clk) then
      done_r <= '0';
      ok_r   <= '0';
      why_r  <= RS_OK;

      -- ---- the post-release view, computed before anything decides ----
      rs_i     := to_integer(unsigned(rel_slot));
      rel_hit  := rel_valid = '1' and rs_i < N_EP and used_r(rs_i) = '1';
      used_now := used_r;
      per_now  := per_r;
      ctl_now  := ctl_r;
      if rel_hit then
        rel_cost    := frame_cost(slot_mp(rs_i));
        used_now(rs_i) := '0';
        if is_periodic_t(slot_ty(rs_i)) then
          per_now := per_now - rel_cost;
        elsif slot_ty(rs_i) = XT_CTRL then
          ctl_now := ctl_now - rel_cost;
        end if;
        cnt_r <= cnt_r - 1;
      end if;
      per_r  <= per_now;
      ctl_r  <= ctl_now;
      used_r <= used_now;

      -- ---- the first free slot, in the post-release view ----
      free_slot := 0;
      have_free := false;
      for j in N_EP-1 downto 0 loop
        if used_now(j) = '0' then
          free_slot := j;
          have_free := true;
        end if;
      end loop;

      if req_valid = '1' then
        t       := xfer_of(req_type);
        cost    := frame_cost(unsigned(req_maxp));
        per_req := is_periodic_t(t);

        req_c  <= req_c + 1;
        done_r <= '1';
        slot_r <= to_unsigned(free_slot, 4);

        -- ---- the checks, cheapest and most specific first ----
        --
        -- A request that is wrong in two ways should report the one the
        -- driver can act on.
        if unsigned(req_maxp) > max_packet(t) then
          ok_r  <= '0';
          why_r <= RS_MAXP;
          mp_c  <= mp_c + 1;

        elsif per_req and not is_pow2(unsigned(req_interval)) then
          ok_r  <= '0';
          why_r <= RS_INTERVAL;
          iv_c  <= iv_c + 1;

        elsif not have_free then
          ok_r   <= '0';
          why_r  <= RS_FULL;
          full_c <= full_c + 1;

        elsif per_req and (per_now + cost) > to_unsigned(PERIODIC_MAX, 16) then
          -- The 90% rule, and the reason isochronous is what it is: once the
          -- periodic budget is spoken for nothing more gets in -- and nothing
          -- already in can be retried either.
          ok_r  <= '0';
          why_r <= RS_BW;
          bw_c  <= bw_c + 1;

        elsif t = XT_CTRL and (ctl_now + cost) > to_unsigned(CONTROL_MIN, 16) then
          -- The 10% rule, a SEPARATE limit rather than the remainder of the
          -- periodic one: control has its own reservation precisely so that a
          -- fully committed periodic schedule cannot stop the host talking to
          -- its devices.
          ok_r  <= '0';
          why_r <= RS_CTRL_ROOM;
          bw_c  <= bw_c + 1;

        else
          ok_r  <= '1';
          why_r <= RS_OK;
          used_now(free_slot) := '1';
          used_r              <= used_now;
          slot_mp(free_slot)  <= unsigned(req_maxp);
          slot_ty(free_slot)  <= t;
          if rel_hit then cnt_r <= cnt_r;
          else            cnt_r <= cnt_r + 1;
          end if;
          if per_req then
            per_r <= per_now + cost;
          elsif t = XT_CTRL then
            ctl_r <= ctl_now + cost;
          end if;
          -- Bulk is charged NOTHING. It has no reservation, which is exactly
          -- why it can retry: it uses whatever the frame has left after
          -- everything with a promise has been served.
        end if;
      end if;

      -- ---- the self-check that makes the whole thing measurable ----
      if per_r > to_unsigned(PERIODIC_MAX, 16)
         or ctl_r > to_unsigned(CONTROL_MIN, 16) then
        over_c <= over_c + 1;
      end if;
    end if;
  end process;

end architecture;

   Design:  per_r <= per_r + cost          (incremental)
            per_r <= per_r - released_cost

   Shadow:  sum over every admitted slot     (re-summed)

   A release that subtracts the wrong amount leaves the
   design's total SELF-CONSISTENT and wrong. A model that
   re-sums cannot make that mistake, so the two disagree
   the moment the arithmetic drifts.

// =====================================================================
//  Testbench for usb_xfer_admit.
//
//  The shadow model is written from the RULES rather than from the
//  design's control flow: it recomputes, from scratch, what the total
//  periodic and control commitment OUGHT to be given the set of
//  endpoints currently admitted -- by summing over the slots rather than
//  by tracking increments.
//
//  That distinction matters. The design maintains running totals, so a
//  release that subtracts the wrong amount leaves a total that is
//  self-consistent and wrong. A model that re-sums cannot make that
//  mistake, so the two disagree the moment the design's arithmetic drifts.
// =====================================================================
`timescale 1ns/1ps
module tb_xt_v;

  localparam integer FRAME_BYTES  = 1500;
  localparam integer PERIODIC_MAX = 1350;
  localparam integer CONTROL_MIN  = 150;
  localparam integer N_EP         = 8;

  localparam [1:0] X_CTRL = 2'd0, X_ISO = 2'd1, X_INT = 2'd2, X_BULK = 2'd3;
  localparam [2:0] R_OK = 3'd0, R_BW = 3'd1, R_INTERVAL = 3'd2,
                   R_MAXP = 3'd3, R_FULL = 3'd4, R_CTRL_ROOM = 3'd5;

  reg         clk = 1'b0, rst_n = 1'b0;
  reg         req_valid = 1'b0;
  reg  [1:0]  req_type = X_BULK;
  reg  [10:0] req_maxp = 11'd0;
  reg  [7:0]  req_interval = 8'd1;
  reg         rel_valid = 1'b0;
  reg  [3:0]  rel_slot = 4'd0;

  wire        adm_done, adm_ok;
  wire [2:0]  adm_reason;
  wire [3:0]  adm_slot;
  wire [15:0] used_periodic, used_control, n_admitted;
  wire [31:0] n_req, n_reject_bw, n_reject_interval, n_reject_maxp,
              n_reject_full, n_overcommit;

  usb_xfer_admit #(.FRAME_BYTES(FRAME_BYTES), .PERIODIC_MAX(PERIODIC_MAX),
                   .CONTROL_MIN(CONTROL_MIN), .N_EP(N_EP)) dut (
    .clk(clk), .rst_n(rst_n),
    .req_valid(req_valid), .req_type(req_type),
    .req_maxp(req_maxp), .req_interval(req_interval),
    .rel_valid(rel_valid), .rel_slot(rel_slot),
    .adm_done(adm_done), .adm_ok(adm_ok),
    .adm_reason(adm_reason), .adm_slot(adm_slot),
    .used_periodic(used_periodic), .used_control(used_control),
    .n_admitted(n_admitted),
    .n_req(n_req), .n_reject_bw(n_reject_bw),
    .n_reject_interval(n_reject_interval), .n_reject_maxp(n_reject_maxp),
    .n_reject_full(n_reject_full), .n_overcommit(n_overcommit)
  );

  always #5 clk = ~clk;

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

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

  // ---- the shadow: a SET of admitted endpoints, re-summed each time ----
  reg        s_used [0:N_EP-1];
  reg [10:0] s_mp   [0:N_EP-1];
  reg [1:0]  s_ty   [0:N_EP-1];
  reg [31:0] x_req, x_bw, x_iv, x_mp, x_full;

  integer n_over = 0;      // the headline: any overcommitted cycle
  // Run-wide totals: the DUT's counters are cleared by every reset, so a
  // summary printed from them describes the last window, not the run.
  integer g_req = 0, g_bw = 0, g_iv = 0, g_mp = 0, g_full = 0, g_ok = 0;

  reg reach [0:143];
  integer ri, n_reach;

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

  function [15:0] fcost;
    input [10:0] mp;
    begin fcost = {5'd0, mp} + 16'd13; end
  endfunction

  function [10:0] maxp_of;
    input [1:0] t;
    begin
      if (t == X_ISO) maxp_of = 11'd1023;
      else            maxp_of = 11'd64;
    end
  endfunction

  function pow2;
    input [7:0] v;
    begin pow2 = (v != 8'd0) && ((v & (v - 8'd1)) == 8'd0); end
  endfunction

  // ---- re-sum the whole schedule from the admitted set ----
  //
  // Never incremental. A design that subtracts the wrong amount on release
  // stays self-consistent; a model that re-sums does not.
  function [15:0] sum_periodic;
    input dummy;
    integer a;
    begin
      sum_periodic = 16'd0;
      for (a = 0; a < N_EP; a = a + 1)
        if (s_used[a] && ((s_ty[a] == X_ISO) || (s_ty[a] == X_INT)))
          sum_periodic = sum_periodic + fcost(s_mp[a]);
    end
  endfunction

  function [15:0] sum_control;
    input dummy;
    integer a;
    begin
      sum_control = 16'd0;
      for (a = 0; a < N_EP; a = a + 1)
        if (s_used[a] && (s_ty[a] == X_CTRL))
          sum_control = sum_control + fcost(s_mp[a]);
    end
  endfunction

  function [15:0] count_used;
    input dummy;
    integer a;
    begin
      count_used = 16'd0;
      for (a = 0; a < N_EP; a = a + 1) if (s_used[a]) count_used = count_used + 16'd1;
    end
  endfunction

  function [3:0] first_free;
    input dummy;
    integer a;
    begin
      first_free = 4'd0;
      for (a = N_EP - 1; a >= 0; a = a - 1) if (!s_used[a]) first_free = a[3:0];
    end
  endfunction

  function have_free_f;
    input dummy;
    integer a;
    begin
      have_free_f = 1'b0;
      for (a = 0; a < N_EP; a = a + 1) if (!s_used[a]) have_free_f = 1'b1;
    end
  endfunction

  // ---------------------------------------------------------------
  //  One cycle: a release and/or a request, then check the decision.
  // ---------------------------------------------------------------
  task step(input rv, input [3:0] rs,
            input qv, input [1:0] qt, input [10:0] qm, input [7:0] qi);
    reg        e_ok;
    reg [2:0]  e_why;
    reg [3:0]  e_slot;
    reg        e_per;
    reg [15:0] e_cost;
    begin
      rel_valid = rv;  rel_slot = rs;
      req_valid = qv;  req_type = qt;  req_maxp = qm;  req_interval = qi;

      // ---- release first, exactly as the design orders it ----
      if (rv && (rs < N_EP) && s_used[rs]) s_used[rs] = 1'b0;

      e_per  = (qt == X_ISO) || (qt == X_INT);
      e_cost = fcost(qm);
      e_ok   = 1'b0;
      e_why  = R_OK;
      e_slot = first_free(0);

      if (qv) begin
        x_req = x_req + 1;  g_req = g_req + 1;
        if (qm > maxp_of(qt)) begin
          e_why = R_MAXP;  x_mp = x_mp + 1;  g_mp = g_mp + 1;
        end else if (e_per && !pow2(qi)) begin
          e_why = R_INTERVAL;  x_iv = x_iv + 1;  g_iv = g_iv + 1;
        end else if (!have_free_f(0)) begin
          e_why = R_FULL;  x_full = x_full + 1;  g_full = g_full + 1;
        end else if (e_per && ((sum_periodic(0) + e_cost) > PERIODIC_MAX)) begin
          e_why = R_BW;  x_bw = x_bw + 1;  g_bw = g_bw + 1;
        end else if ((qt == X_CTRL) && ((sum_control(0) + e_cost) > CONTROL_MIN)) begin
          e_why = R_CTRL_ROOM;  x_bw = x_bw + 1;  g_bw = g_bw + 1;
        end else begin
          e_ok = 1'b1;  e_why = R_OK;  g_ok = g_ok + 1;
          s_used[e_slot] = 1'b1;
          s_mp[e_slot]   = qm;
          s_ty[e_slot]   = qt;
        end
      end

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

      // ---- PROPERTY 1: the decision and its reason ----
      ck(adm_done === qv, "adm_done disagrees with whether a request was made");
      if (qv) begin
        ck(adm_ok     === e_ok,   "admission decision disagrees");
        ck(adm_reason === e_why,  "rejection reason disagrees");
        if (e_ok) ck(adm_slot === e_slot, "admitted into the wrong slot");
      end

      // ---- PROPERTY 2: the schedule totals, RE-SUMMED ----
      ck(used_periodic === sum_periodic(0), "periodic commitment disagrees");
      ck(used_control  === sum_control(0),  "control commitment disagrees");
      ck(n_admitted    === count_used(0),   "admitted count disagrees");

      // ---- PROPERTY 3: the ceilings are never exceeded ----
      if (used_periodic > PERIODIC_MAX) n_over = n_over + 1;
      if (used_control  > CONTROL_MIN)  n_over = n_over + 1;
      ck(used_periodic <= PERIODIC_MAX, "periodic budget overcommitted");
      ck(used_control  <= CONTROL_MIN,  "control reservation overcommitted");
      ck(n_overcommit === 32'd0, "the design detected its own overcommitment");
      ck(n_over == 0, "the schedule was overcommitted");

      // ---- PROPERTY 4: the counters agree ----
      ck(n_req             === x_req,  "request count disagrees");
      ck(n_reject_bw       === x_bw,   "bandwidth-rejection count disagrees");
      ck(n_reject_interval === x_iv,   "interval-rejection count disagrees");
      ck(n_reject_maxp     === x_mp,   "maxp-rejection count disagrees");
      ck(n_reject_full     === x_full, "slot-full-rejection count disagrees");
    end
  endtask

  task reset_dut;
    integer a;
    begin
      rst_n = 1'b0;
      req_valid = 0; rel_valid = 0;
      @(posedge clk); @(posedge clk);
      rst_n = 1'b1;
      for (a = 0; a < N_EP; a = a + 1) begin
        s_used[a] = 1'b0; s_mp[a] = 11'd0; s_ty[a] = X_CTRL;
      end
      x_req = 0; x_bw = 0; x_iv = 0; x_mp = 0; x_full = 0;
      @(posedge clk); #1;
    end
  endtask

  integer ti, mi, ii, k, a3;
  integer expect_n;
  reg [10:0] mps [0:5];
  reg [7:0]  ivs [0:5];

  initial begin
    for (ri = 0; ri < 144; ri = ri + 1) reach[ri] = 1'b0;
    // Boundary values on purpose: 64 and 65 straddle the control/bulk
    // limit, 1023 and 1024 straddle the isochronous one.
    mps[0] = 11'd8;   mps[1] = 11'd64;   mps[2] = 11'd65;
    mps[3] = 11'd512; mps[4] = 11'd1023; mps[5] = 11'd1024;
    // 1,2,4,8 are legal; 3 and 255 are not powers of two.
    ivs[0] = 8'd1; ivs[1] = 8'd2; ivs[2] = 8'd3;
    ivs[3] = 8'd4; ivs[4] = 8'd8; ivs[5] = 8'd255;
    seed = 32'd27005;

    // =============================================================
    //  PHASE 1 (DIRECTED, EXHAUSTIVE) -- every type against every
    //  packet size against every interval. 4 x 6 x 6 = 144.
    // =============================================================
    for (ti = 0; ti < 4; ti = ti + 1)
    for (mi = 0; mi < 6; mi = mi + 1)
    for (ii = 0; ii < 6; ii = ii + 1) begin
      reset_dut;
      step(1'b0, 4'd0, 1'b1, ti[1:0], mps[mi], ivs[ii]);
      ri = (ti * 36) + (mi * 6) + ii;
      reach[ri] = 1'b1;
    end

    // =============================================================
    //  PHASE 2 (DIRECTED) -- fill the periodic budget exactly, then
    //  ask for one more byte.
    //
    //  This is the trade made arithmetic: the last endpoint that fits
    //  is admitted, the next is refused, and NOTHING already admitted
    //  can be retried -- because every slot is spoken for. That is
    //  what "guaranteed bandwidth" costs.
    // =============================================================
    reset_dut;
    // 1023 + 13 = 1036 per iso endpoint; the ceiling is 1350
    step(1'b0, 4'd0, 1'b1, X_ISO, 11'd1023, 8'd1);
    ck(adm_ok === 1'b1, "the first isochronous endpoint was refused");
    // a second one would be 2072 > 1350
    step(1'b0, 4'd0, 1'b1, X_ISO, 11'd1023, 8'd1);
    ck(adm_ok === 1'b0, "a second full-size isochronous endpoint was admitted");
    ck(adm_reason === R_BW, "the refusal was not attributed to bandwidth");
    // but a small interrupt endpoint still fits: 1036 + 8 + 13 = 1057
    step(1'b0, 4'd0, 1'b1, X_INT, 11'd8, 8'd8);
    ck(adm_ok === 1'b1, "a small interrupt endpoint did not fit in the remainder");
    // and bulk ALWAYS fits, because it is charged nothing at all
    for (k = 0; k < 5; k = k + 1) begin
      step(1'b0, 4'd0, 1'b1, X_BULK, 11'd64, 8'd0);
      ck(adm_ok === 1'b1, "a bulk endpoint was refused for bandwidth");
      ck(used_periodic === 16'd1057, "bulk was charged periodic bandwidth");
    end

    // =============================================================
    //  PHASE 3 (DIRECTED) -- the control reservation is SEPARATE.
    //
    //  A fully committed periodic schedule must not stop the host
    //  talking to its devices, which is why control has its own 10%
    //  rather than sharing the periodic remainder.
    // =============================================================
    reset_dut;
    step(1'b0, 4'd0, 1'b1, X_ISO, 11'd1023, 8'd1);    // 1036 periodic
    step(1'b0, 4'd0, 1'b1, X_CTRL, 11'd64, 8'd0);     // 77 control
    ck(adm_ok === 1'b1, "control was refused while its reservation was free");
    ck(used_control === 16'd77, "control was charged to the wrong budget");
    step(1'b0, 4'd0, 1'b1, X_CTRL, 11'd64, 8'd0);     // 154 > 150
    ck(adm_ok === 1'b0, "control exceeded its own reservation");
    ck(adm_reason === R_CTRL_ROOM, "the refusal was not attributed to control room");

    // =============================================================
    //  PHASE 4 (DIRECTED, EXHAUSTIVE) -- release returns EXACTLY
    //  what was charged, from every slot.
    // =============================================================
    for (k = 0; k < N_EP; k = k + 1) begin
      reset_dut;
      // fill every slot with a small interrupt endpoint
      for (a3 = 0; a3 < N_EP; a3 = a3 + 1)
        step(1'b0, 4'd0, 1'b1, X_INT, 11'd8, 8'd4);
      ck(used_periodic === 16'd168, "eight 8-byte interrupt endpoints cost the wrong amount");
      // the ninth is refused for want of a slot, not bandwidth
      step(1'b0, 4'd0, 1'b1, X_INT, 11'd8, 8'd4);
      ck(adm_ok === 1'b0, "a ninth endpoint was admitted into eight slots");
      ck(adm_reason === R_FULL, "the refusal was not attributed to slots");
      // release slot k and the commitment drops by exactly one endpoint
      step(1'b1, k[3:0], 1'b0, X_BULK, 11'd0, 8'd0);
      ck(used_periodic === 16'd147, "release returned the wrong amount");
      // and a release in the SAME cycle as a request frees the slot for it
      step(1'b1, 4'd0, 1'b1, X_INT, 11'd8, 8'd4);
    end

    // =============================================================
    //  PHASE 4b (DIRECTED, EXHAUSTIVE) -- walk the periodic budget from
    //  empty to refusal, for every packet size.
    //
    //  The trade this chapter is about is arithmetic, so it deserves
    //  arithmetic stimulus: admit identical isochronous endpoints one at a
    //  time until the budget refuses one, checking at every step that the
    //  commitment is exactly the re-summed total and that the refusal
    //  arrives at precisely the right count.
    //
    //  This is what catches a cost function that forgets the
    //  per-transaction overhead, or charges the average instead of the
    //  worst frame: both are off by a few bytes per endpoint and both show
    //  up as the budget refusing one endpoint too late.
    // =============================================================
    for (mi = 0; mi < 6; mi = mi + 1) begin
      if (mps[mi] <= 11'd1023) begin
        reset_dut;
        expect_n = 0;
        // how many of this size fit: floor(PERIODIC_MAX / (maxp + 13)),
        // capped by the number of slots
        while (((expect_n + 1) * (mps[mi] + 13) <= PERIODIC_MAX)
               && (expect_n < N_EP))
          expect_n = expect_n + 1;

        for (k = 0; k < expect_n; k = k + 1) begin
          step(1'b0, 4'd0, 1'b1, X_ISO, mps[mi], 8'd1);
          ck(adm_ok === 1'b1, "an endpoint that fits the budget was refused");
          ck(used_periodic === ((k + 1) * (mps[mi] + 13)),
             "the running commitment is not the sum of the admitted costs");
        end
        // the next one must be refused -- for bandwidth if the budget is
        // what binds, for slots if we ran out of those first
        step(1'b0, 4'd0, 1'b1, X_ISO, mps[mi], 8'd1);
        ck(adm_ok === 1'b0, "one endpoint too many was admitted");
        if (expect_n < N_EP)
          ck(adm_reason === R_BW, "the refusal was not attributed to bandwidth");
        else
          ck(adm_reason === R_FULL, "the refusal was not attributed to slots");
        ck(used_periodic === (expect_n * (mps[mi] + 13)),
           "a refused endpoint changed the commitment");
      end
    end

    // =============================================================
    //  PHASE 5 (RANDOM) -- a driver opening and closing endpoints.
    // =============================================================
`ifndef DIRECTED_ONLY
    reset_dut;
    for (k = 0; k < 20000; k = k + 1) begin
      step((urand(0) % 4) == 0, urand(0) % 16,
           (urand(0) % 2) == 0, urand(0) % 4,
           mps[urand(0) % 6], ivs[urand(0) % 6]);
      if ((k % 256) == 255) reset_dut;
    end
`endif

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

    $display("steps=%0d checks=%0d reach=%0d/144 errors=%0d",
             steps, checks, n_reach, errors);
    $display("[sched] requests=%0d admitted=%0d bw=%0d interval=%0d maxp=%0d full=%0d",
             g_req, g_ok, g_bw, g_iv, g_mp, g_full);
    $display("[the whole point] overcommitted cycles = %0d", n_over);
    if (n_reach != 144) begin
      $display("FAIL: exhaustive sweep incomplete"); errors = errors + 1;
    end
    if (errors == 0) $display("PASS: 0 errors in %0d checks", checks);
    else             $display("FAIL: %0d errors in %0d checks", errors, checks);
    $finish;
  end

endmodule

// =====================================================================
//  Testbench for usb_xfer_admit.
//
//  The shadow model is written from the RULES rather than from the
//  design's control flow: it recomputes, from scratch, what the total
//  periodic and control commitment OUGHT to be given the set of
//  endpoints currently admitted -- by summing over the slots rather than
//  by tracking increments.
//
//  That distinction matters. The design maintains running totals, so a
//  release that subtracts the wrong amount leaves a total that is
//  self-consistent and wrong. A model that re-sums cannot make that
//  mistake, so the two disagree the moment the design's arithmetic drifts.
// =====================================================================
`timescale 1ns/1ps
module tb_xt_sv;

  localparam integer FRAME_BYTES  = 1500;
  localparam integer PERIODIC_MAX = 1350;
  localparam integer CONTROL_MIN  = 150;
  localparam integer N_EP         = 8;

  localparam [1:0] X_CTRL = 2'd0, X_ISO = 2'd1, X_INT = 2'd2, X_BULK = 2'd3;
  localparam [2:0] R_OK = 3'd0, R_BW = 3'd1, R_INTERVAL = 3'd2,
                   R_MAXP = 3'd3, R_FULL = 3'd4, R_CTRL_ROOM = 3'd5;

  logic       clk = 1'b0, rst_n = 1'b0;
  logic       req_valid = 1'b0;
  logic [1:0] req_type = X_BULK;
  logic [10:0] req_maxp = 11'd0;
  logic [7:0] req_interval = 8'd1;
  logic       rel_valid = 1'b0;
  logic [3:0] rel_slot = 4'd0;

  logic       adm_done, adm_ok;
  logic [2:0] adm_reason;
  logic [3:0] adm_slot;
  logic [15:0] used_periodic, used_control, n_admitted;
  logic [31:0] n_req, n_reject_bw, n_reject_interval, n_reject_maxp,
               n_reject_full, n_overcommit;

  usb_xfer_admit #(.FRAME_BYTES(FRAME_BYTES), .PERIODIC_MAX(PERIODIC_MAX),
                   .CONTROL_MIN(CONTROL_MIN), .N_EP(N_EP)) dut (
    .clk(clk), .rst_n(rst_n),
    .req_valid(req_valid), .req_type(req_type),
    .req_maxp(req_maxp), .req_interval(req_interval),
    .rel_valid(rel_valid), .rel_slot(rel_slot),
    .adm_done(adm_done), .adm_ok(adm_ok),
    .adm_reason(adm_reason), .adm_slot(adm_slot),
    .used_periodic(used_periodic), .used_control(used_control),
    .n_admitted(n_admitted),
    .n_req(n_req), .n_reject_bw(n_reject_bw),
    .n_reject_interval(n_reject_interval), .n_reject_maxp(n_reject_maxp),
    .n_reject_full(n_reject_full), .n_overcommit(n_overcommit)
  );

  always #5 clk = ~clk;

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

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

  // ---- the shadow: a SET of admitted endpoints, re-summed each time ----
  logic      s_used [0:N_EP-1];
  logic [10:0] s_mp   [0:N_EP-1];
  logic [1:0] s_ty   [0:N_EP-1];
  logic [31:0] x_req, x_bw, x_iv, x_mp, x_full;

  integer n_over = 0;      // the headline: any overcommitted cycle
  // Run-wide totals: the DUT's counters are cleared by every reset, so a
  // summary printed from them describes the last window, not the run.
  integer g_req = 0, g_bw = 0, g_iv = 0, g_mp = 0, g_full = 0, g_ok = 0;

  logic reach [0:143];
  integer ri, n_reach;

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

  function automatic logic [15:0] fcost(logic [10:0] mp);
    return {5'd0, mp} + 16'd13;
  endfunction

  function automatic logic [10:0] maxp_of(logic [1:0] t);
    if (t == X_ISO) return 11'd1023;
    return 11'd64;
  endfunction

  function automatic logic pow2(logic [7:0] v);
    return (v != 8'd0) && ((v & (v - 8'd1)) == 8'd0);
  endfunction

  // ---- re-sum the whole schedule from the admitted set ----
  //
  // Never incremental. A design that subtracts the wrong amount on release
  // stays self-consistent; a model that re-sums does not.
  function automatic logic [15:0] sum_periodic(bit dummy);
    integer a;
    begin
      sum_periodic = 16'd0;
      for (a = 0; a < N_EP; a = a + 1)
        if (s_used[a] && ((s_ty[a] == X_ISO) || (s_ty[a] == X_INT)))
          sum_periodic = sum_periodic + fcost(s_mp[a]);
    end
  endfunction

  function automatic logic [15:0] sum_control(bit dummy);
    integer a;
    begin
      sum_control = 16'd0;
      for (a = 0; a < N_EP; a = a + 1)
        if (s_used[a] && (s_ty[a] == X_CTRL))
          sum_control = sum_control + fcost(s_mp[a]);
    end
  endfunction

  function automatic logic [15:0] count_used(bit dummy);
    integer a;
    begin
      count_used = 16'd0;
      for (a = 0; a < N_EP; a = a + 1) if (s_used[a]) count_used = count_used + 16'd1;
    end
  endfunction

  function automatic logic [3:0] first_free(bit dummy);
    integer a;
    begin
      first_free = 4'd0;
      for (a = N_EP - 1; a >= 0; a = a - 1) if (!s_used[a]) first_free = a[3:0];
    end
  endfunction

  function automatic logic have_free_f(bit dummy);
    integer a;
    begin
      have_free_f = 1'b0;
      for (a = 0; a < N_EP; a = a + 1) if (!s_used[a]) have_free_f = 1'b1;
    end
  endfunction

  // ---------------------------------------------------------------
  //  One cycle: a release and/or a request, then check the decision.
  // ---------------------------------------------------------------
  task step(input logic rv, input logic [3:0] rs,
            input logic qv, input logic [1:0] qt,
            input logic [10:0] qm, input logic [7:0] qi);
    logic      e_ok;
    logic [2:0] e_why;
    logic [3:0] e_slot;
    logic      e_per;
    logic [15:0] e_cost;
    begin
      rel_valid = rv;  rel_slot = rs;
      req_valid = qv;  req_type = qt;  req_maxp = qm;  req_interval = qi;

      // ---- release first, exactly as the design orders it ----
      if (rv && (rs < N_EP) && s_used[rs]) s_used[rs] = 1'b0;

      e_per  = (qt == X_ISO) || (qt == X_INT);
      e_cost = fcost(qm);
      e_ok   = 1'b0;
      e_why  = R_OK;
      e_slot = first_free(0);

      if (qv) begin
        x_req = x_req + 1;  g_req = g_req + 1;
        if (qm > maxp_of(qt)) begin
          e_why = R_MAXP;  x_mp = x_mp + 1;  g_mp = g_mp + 1;
        end else if (e_per && !pow2(qi)) begin
          e_why = R_INTERVAL;  x_iv = x_iv + 1;  g_iv = g_iv + 1;
        end else if (!have_free_f(0)) begin
          e_why = R_FULL;  x_full = x_full + 1;  g_full = g_full + 1;
        end else if (e_per && ((sum_periodic(0) + e_cost) > PERIODIC_MAX)) begin
          e_why = R_BW;  x_bw = x_bw + 1;  g_bw = g_bw + 1;
        end else if ((qt == X_CTRL) && ((sum_control(0) + e_cost) > CONTROL_MIN)) begin
          e_why = R_CTRL_ROOM;  x_bw = x_bw + 1;  g_bw = g_bw + 1;
        end else begin
          e_ok = 1'b1;  e_why = R_OK;  g_ok = g_ok + 1;
          s_used[e_slot] = 1'b1;
          s_mp[e_slot]   = qm;
          s_ty[e_slot]   = qt;
        end
      end

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

      // ---- PROPERTY 1: the decision and its reason ----
      ck(adm_done === qv, "adm_done disagrees with whether a request was made");
      if (qv) begin
        ck(adm_ok     === e_ok,   "admission decision disagrees");
        ck(adm_reason === e_why,  "rejection reason disagrees");
        if (e_ok) ck(adm_slot === e_slot, "admitted into the wrong slot");
      end

      // ---- PROPERTY 2: the schedule totals, RE-SUMMED ----
      ck(used_periodic === sum_periodic(0), "periodic commitment disagrees");
      ck(used_control  === sum_control(0),  "control commitment disagrees");
      ck(n_admitted    === count_used(0),   "admitted count disagrees");

      // ---- PROPERTY 3: the ceilings are never exceeded ----
      if (used_periodic > PERIODIC_MAX) n_over = n_over + 1;
      if (used_control  > CONTROL_MIN)  n_over = n_over + 1;
      ck(used_periodic <= PERIODIC_MAX, "periodic budget overcommitted");
      ck(used_control  <= CONTROL_MIN,  "control reservation overcommitted");
      ck(n_overcommit === 32'd0, "the design detected its own overcommitment");
      ck(n_over == 0, "the schedule was overcommitted");

      // ---- PROPERTY 4: the counters agree ----
      ck(n_req             === x_req,  "request count disagrees");
      ck(n_reject_bw       === x_bw,   "bandwidth-rejection count disagrees");
      ck(n_reject_interval === x_iv,   "interval-rejection count disagrees");
      ck(n_reject_maxp     === x_mp,   "maxp-rejection count disagrees");
      ck(n_reject_full     === x_full, "slot-full-rejection count disagrees");
    end
  endtask

  task reset_dut;
    integer a;
    begin
      rst_n = 1'b0;
      req_valid = 0; rel_valid = 0;
      @(posedge clk); @(posedge clk);
      rst_n = 1'b1;
      for (a = 0; a < N_EP; a = a + 1) begin
        s_used[a] = 1'b0; s_mp[a] = 11'd0; s_ty[a] = X_CTRL;
      end
      x_req = 0; x_bw = 0; x_iv = 0; x_mp = 0; x_full = 0;
      @(posedge clk); #1;
    end
  endtask

  integer ti, mi, ii, k, a3;
  integer expect_n;
  logic [10:0] mps [0:5];
  logic [7:0] ivs [0:5];

  initial begin
    for (ri = 0; ri < 144; ri = ri + 1) reach[ri] = 1'b0;
    // Boundary values on purpose: 64 and 65 straddle the control/bulk
    // limit, 1023 and 1024 straddle the isochronous one.
    mps[0] = 11'd8;   mps[1] = 11'd64;   mps[2] = 11'd65;
    mps[3] = 11'd512; mps[4] = 11'd1023; mps[5] = 11'd1024;
    // 1,2,4,8 are legal; 3 and 255 are not powers of two.
    ivs[0] = 8'd1; ivs[1] = 8'd2; ivs[2] = 8'd3;
    ivs[3] = 8'd4; ivs[4] = 8'd8; ivs[5] = 8'd255;
    seed = 32'd27005;

    // =============================================================
    //  PHASE 1 (DIRECTED, EXHAUSTIVE) -- every type against every
    //  packet size against every interval. 4 x 6 x 6 = 144.
    // =============================================================
    for (ti = 0; ti < 4; ti = ti + 1)
    for (mi = 0; mi < 6; mi = mi + 1)
    for (ii = 0; ii < 6; ii = ii + 1) begin
      reset_dut;
      step(1'b0, 4'd0, 1'b1, ti[1:0], mps[mi], ivs[ii]);
      ri = (ti * 36) + (mi * 6) + ii;
      reach[ri] = 1'b1;
    end

    // =============================================================
    //  PHASE 2 (DIRECTED) -- fill the periodic budget exactly, then
    //  ask for one more byte.
    //
    //  This is the trade made arithmetic: the last endpoint that fits
    //  is admitted, the next is refused, and NOTHING already admitted
    //  can be retried -- because every slot is spoken for. That is
    //  what "guaranteed bandwidth" costs.
    // =============================================================
    reset_dut;
    // 1023 + 13 = 1036 per iso endpoint; the ceiling is 1350
    step(1'b0, 4'd0, 1'b1, X_ISO, 11'd1023, 8'd1);
    ck(adm_ok === 1'b1, "the first isochronous endpoint was refused");
    // a second one would be 2072 > 1350
    step(1'b0, 4'd0, 1'b1, X_ISO, 11'd1023, 8'd1);
    ck(adm_ok === 1'b0, "a second full-size isochronous endpoint was admitted");
    ck(adm_reason === R_BW, "the refusal was not attributed to bandwidth");
    // but a small interrupt endpoint still fits: 1036 + 8 + 13 = 1057
    step(1'b0, 4'd0, 1'b1, X_INT, 11'd8, 8'd8);
    ck(adm_ok === 1'b1, "a small interrupt endpoint did not fit in the remainder");
    // and bulk ALWAYS fits, because it is charged nothing at all
    for (k = 0; k < 5; k = k + 1) begin
      step(1'b0, 4'd0, 1'b1, X_BULK, 11'd64, 8'd0);
      ck(adm_ok === 1'b1, "a bulk endpoint was refused for bandwidth");
      ck(used_periodic === 16'd1057, "bulk was charged periodic bandwidth");
    end

    // =============================================================
    //  PHASE 3 (DIRECTED) -- the control reservation is SEPARATE.
    //
    //  A fully committed periodic schedule must not stop the host
    //  talking to its devices, which is why control has its own 10%
    //  rather than sharing the periodic remainder.
    // =============================================================
    reset_dut;
    step(1'b0, 4'd0, 1'b1, X_ISO, 11'd1023, 8'd1);    // 1036 periodic
    step(1'b0, 4'd0, 1'b1, X_CTRL, 11'd64, 8'd0);     // 77 control
    ck(adm_ok === 1'b1, "control was refused while its reservation was free");
    ck(used_control === 16'd77, "control was charged to the wrong budget");
    step(1'b0, 4'd0, 1'b1, X_CTRL, 11'd64, 8'd0);     // 154 > 150
    ck(adm_ok === 1'b0, "control exceeded its own reservation");
    ck(adm_reason === R_CTRL_ROOM, "the refusal was not attributed to control room");

    // =============================================================
    //  PHASE 4 (DIRECTED, EXHAUSTIVE) -- release returns EXACTLY
    //  what was charged, from every slot.
    // =============================================================
    for (k = 0; k < N_EP; k = k + 1) begin
      reset_dut;
      // fill every slot with a small interrupt endpoint
      for (a3 = 0; a3 < N_EP; a3 = a3 + 1)
        step(1'b0, 4'd0, 1'b1, X_INT, 11'd8, 8'd4);
      ck(used_periodic === 16'd168, "eight 8-byte interrupt endpoints cost the wrong amount");
      // the ninth is refused for want of a slot, not bandwidth
      step(1'b0, 4'd0, 1'b1, X_INT, 11'd8, 8'd4);
      ck(adm_ok === 1'b0, "a ninth endpoint was admitted into eight slots");
      ck(adm_reason === R_FULL, "the refusal was not attributed to slots");
      // release slot k and the commitment drops by exactly one endpoint
      step(1'b1, k[3:0], 1'b0, X_BULK, 11'd0, 8'd0);
      ck(used_periodic === 16'd147, "release returned the wrong amount");
      // and a release in the SAME cycle as a request frees the slot for it
      step(1'b1, 4'd0, 1'b1, X_INT, 11'd8, 8'd4);
    end

    // =============================================================
    //  PHASE 4b (DIRECTED, EXHAUSTIVE) -- walk the periodic budget from
    //  empty to refusal, for every packet size.
    //
    //  The trade this chapter is about is arithmetic, so it deserves
    //  arithmetic stimulus: admit identical isochronous endpoints one at a
    //  time until the budget refuses one, checking at every step that the
    //  commitment is exactly the re-summed total and that the refusal
    //  arrives at precisely the right count.
    //
    //  This is what catches a cost function that forgets the
    //  per-transaction overhead, or charges the average instead of the
    //  worst frame: both are off by a few bytes per endpoint and both show
    //  up as the budget refusing one endpoint too late.
    // =============================================================
    for (mi = 0; mi < 6; mi = mi + 1) begin
      if (mps[mi] <= 11'd1023) begin
        reset_dut;
        expect_n = 0;
        // how many of this size fit: floor(PERIODIC_MAX / (maxp + 13)),
        // capped by the number of slots
        while (((expect_n + 1) * (mps[mi] + 13) <= PERIODIC_MAX)
               && (expect_n < N_EP))
          expect_n = expect_n + 1;

        for (k = 0; k < expect_n; k = k + 1) begin
          step(1'b0, 4'd0, 1'b1, X_ISO, mps[mi], 8'd1);
          ck(adm_ok === 1'b1, "an endpoint that fits the budget was refused");
          ck(used_periodic === ((k + 1) * (mps[mi] + 13)),
             "the running commitment is not the sum of the admitted costs");
        end
        // the next one must be refused -- for bandwidth if the budget is
        // what binds, for slots if we ran out of those first
        step(1'b0, 4'd0, 1'b1, X_ISO, mps[mi], 8'd1);
        ck(adm_ok === 1'b0, "one endpoint too many was admitted");
        if (expect_n < N_EP)
          ck(adm_reason === R_BW, "the refusal was not attributed to bandwidth");
        else
          ck(adm_reason === R_FULL, "the refusal was not attributed to slots");
        ck(used_periodic === (expect_n * (mps[mi] + 13)),
           "a refused endpoint changed the commitment");
      end
    end

    // =============================================================
    //  PHASE 5 (RANDOM) -- a driver opening and closing endpoints.
    // =============================================================
`ifndef DIRECTED_ONLY
    reset_dut;
    for (k = 0; k < 20000; k = k + 1) begin
      step((urand(0) % 4) == 0, urand(0) % 16,
           (urand(0) % 2) == 0, urand(0) % 4,
           mps[urand(0) % 6], ivs[urand(0) % 6]);
      if ((k % 256) == 255) reset_dut;
    end
`endif

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

    $display("steps=%0d checks=%0d reach=%0d/144 errors=%0d",
             steps, checks, n_reach, errors);
    $display("[sched] requests=%0d admitted=%0d bw=%0d interval=%0d maxp=%0d full=%0d",
             g_req, g_ok, g_bw, g_iv, g_mp, g_full);
    $display("[the whole point] overcommitted cycles = %0d", n_over);
    if (n_reach != 144) begin
      $display("FAIL: exhaustive sweep incomplete"); errors = errors + 1;
    end
    if (errors == 0) $display("PASS: 0 errors in %0d checks", checks);
    else             $display("FAIL: %0d errors in %0d checks", errors, checks);
    $finish;
  end

endmodule