USB vs PCIe

// =====================================================================
//  OUTSTANDING TRANSACTIONS -- THE MECHANISM PCIe NEEDS AND USB DOES NOT.
//
//  CLASSIFICATION: simplified synthesisable teaching RTL.
//  Two modules. Neither is a controller: there is no TLP encoder, no
//  link layer, no credits, no USB packet engine and no scheduler. Each
//  is the part that answers one question.
//
//      "This response just arrived. Which request was it for?"
//
//  USB answers it by CONSTRUCTION. The host issues one transaction to an
//  endpoint and waits for it. The response is the next thing on the wire,
//  so there is nothing to match -- and USB packets carry no transaction
//  identifier at all, because none is needed.
//
//  PCIe answers it with a TAG. A requester may have many non-posted
//  requests in flight at once; completions travel independently, come
//  back OUT OF ORDER, and may arrive split into several pieces. So every
//  request carries a tag, and the requester must track each one until the
//  last byte of its completion has arrived.
//
//  The difference is not bandwidth, it is CONCURRENCY:
//
//      USB:  one outstanding transaction, so throughput is bounded by
//            1 / latency, whatever the wire can carry.
//      PCIe: N outstanding transactions, so throughput is bounded by
//            min(1, N / latency) -- and with enough tags, not by latency
//            at all.
//
//  That is a formula, so the chapter measures it. Section 5's table is
//  throughput against tag count and latency, and the USB case is exactly
//  its first row.
//
//  What the tags cost is a class of bug that cannot exist on USB: a tag
//  reused before its completion arrives silently attributes one
//  transaction's data to another.
// =====================================================================

// ---------------------------------------------------------------------
//  pcie_tag_tracker -- many in flight, matched by tag.
//
//  `tag_limit` is an INPUT rather than a parameter so the testbench can
//  sweep how many tags the requester is allowed to use without
//  re-elaborating. That is what makes the throughput curve in section 5
//  a single exhaustive sweep instead of eight separate runs -- and it is
//  also how the USB case is reached: tag_limit = 1.
// ---------------------------------------------------------------------
module pcie_tag_tracker #(
  parameter integer N_TAG   = 8,
  // Bytes are tracked so a SPLIT completion can be modelled: a single
  // read may be answered by several completions, and the tag is not free
  // until the last byte arrives.
  parameter integer MAX_BYTES = 256
) (
  input  wire       clk,
  input  wire       rst_n,

  // How many tags the requester may use, 1..N_TAG. Zero is treated as
  // one: a requester that can have nothing outstanding cannot make
  // progress, and silently deadlocking is worse than clamping.
  input  wire [$clog2(N_TAG+1)-1:0] tag_limit,

  // ---- a request ----
  input  wire        req_valid,
  // POSTED requests (writes) expect no completion and consume no tag.
  // That is why a PCIe write is fast and a PCIe read is not: the write is
  // finished when it is sent, and the read is not finished until it comes
  // back.
  input  wire        req_posted,
  input  wire [15:0] req_bytes,

  output wire        req_ready,   // a tag was available
  output wire [$clog2(N_TAG)-1:0] req_tag,
  output wire        req_stall,   // no tag available: this is back-pressure

  // ---- a completion, arriving whenever the fabric feels like it ----
  input  wire        cpl_valid,
  input  wire [$clog2(N_TAG)-1:0] cpl_tag,
  input  wire [15:0] cpl_bytes,

  output wire        cpl_retire,  // this completion finished its request

  // ---- observability ----
  output wire [31:0] n_alloc,
  output wire [31:0] n_posted,
  output wire [31:0] n_stall,
  output wire [31:0] n_retire,
  output wire [31:0] n_partial,     // a completion that did not finish a tag
  output wire [31:0] n_bad_tag,     // a completion for a tag nobody owns
  output wire [31:0] n_over,        // more bytes returned than requested
  output wire [31:0] n_outstanding  // how many tags are in flight NOW
);

  localparam integer TW = $clog2(N_TAG);
  localparam integer LW = $clog2(N_TAG+1);

  reg         t_busy [0:N_TAG-1];
  reg [15:0]  t_rem  [0:N_TAG-1];

  integer i;

  // Clamp to at least one usable tag. A requester allowed zero
  // outstanding transactions can never make progress, and a design that
  // deadlocks silently is harder to debug than one that refuses to.
  wire [LW-1:0] lim = (tag_limit == 0) ? {{(LW-1){1'b0}}, 1'b1} : tag_limit;

  // -------------------------------------------------------------------
  //  ALLOCATE -- the lowest free tag strictly below the limit.
  //
  //  Walking downwards so the lowest index wins. Real requesters often
  //  allocate round-robin to spread wear on completion buffers; lowest-
  //  free is chosen here because it is deterministic, which is what makes
  //  the tag-reuse property checkable at all.
  // -------------------------------------------------------------------
  reg          free_any;
  reg [TW-1:0] free_tag;
  always @(*) begin
    free_any = 1'b0;
    free_tag = {TW{1'b0}};
    for (i = N_TAG - 1; i >= 0; i = i - 1) begin
      if (!t_busy[i] && (i < lim)) begin
        free_any = 1'b1;
        free_tag = i[TW-1:0];
      end
    end
  end

  // A posted request needs no tag, so it is never stalled by tag
  // exhaustion. This asymmetry is the whole reason PCIe separates the two
  // classes.
  assign req_ready = req_valid && (req_posted || free_any);
  assign req_tag   = free_tag;
  assign req_stall = req_valid && !req_posted && !free_any;

  // -------------------------------------------------------------------
  //  COMPLETE -- match by tag, subtract bytes, free on the last one.
  // -------------------------------------------------------------------
  wire          cpl_known = cpl_valid && t_busy[cpl_tag];
  wire [15:0]   rem_now   = t_rem[cpl_tag];
  // More bytes than were asked for. On a real link this is a malformed
  // completion; here it is flagged rather than allowed to wrap the
  // counter, because a wrapped counter would keep the tag outstanding
  // forever and turn a protocol error into a hang.
  wire          cpl_overrun = cpl_known && (cpl_bytes > rem_now);
  wire          cpl_last    = cpl_known && (cpl_bytes >= rem_now);

  assign cpl_retire = cpl_last;

  reg [31:0] alloc_c, posted_c, stall_c, retire_c, partial_c, bad_c, over_c;
  assign n_alloc   = alloc_c;
  assign n_posted  = posted_c;
  assign n_stall   = stall_c;
  assign n_retire  = retire_c;
  assign n_partial = partial_c;
  assign n_bad_tag = bad_c;
  assign n_over    = over_c;

  // Combinational, so it reports the tracker as it stands rather than as
  // it stood a cycle ago.
  reg [31:0] out_now;
  always @(*) begin
    out_now = 32'd0;
    for (i = 0; i < N_TAG; i = i + 1) if (t_busy[i]) out_now = out_now + 32'd1;
  end
  assign n_outstanding = out_now;

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      for (i = 0; i < N_TAG; i = i + 1) begin
        t_busy[i] <= 1'b0;
        t_rem[i]  <= 16'd0;
      end
      alloc_c   <= 32'd0;
      posted_c  <= 32'd0;
      stall_c   <= 32'd0;
      retire_c  <= 32'd0;
      partial_c <= 32'd0;
      bad_c     <= 32'd0;
      over_c    <= 32'd0;
    end else begin
      // ---- completions, then requests ----
      //
      // The order of these two blocks is immaterial to correctness, and it
      // is worth saying why rather than implying otherwise. `free_any` and
      // `free_tag` are combinational over the REGISTERED t_busy, so they
      // describe the table as it stood at the START of this cycle. A tag
      // retired by a completion in this cycle therefore becomes
      // allocatable in the NEXT one -- not this one.
      //
      // That is ONE CYCLE OF TURNAROUND per tag, and it is a real cost with
      // a visible consequence: saturating a fabric of latency L needs L+1
      // tags, not L. Section 5's table shows exactly that boundary.
      //
      // The two blocks cannot collide, because an index being retired is
      // busy and is therefore never the index free_any selects.
      if (cpl_valid) begin
        if (!t_busy[cpl_tag]) begin
          // A completion for a tag nobody owns. Either the fabric
          // invented it or this requester retired the tag early -- and
          // the second is exactly what a tag-reuse bug looks like from
          // here.
          bad_c <= bad_c + 32'd1;
        end else begin
          if (cpl_bytes >= rem_now) begin
            t_busy[cpl_tag] <= 1'b0;
            t_rem[cpl_tag]  <= 16'd0;
            retire_c <= retire_c + 32'd1;
            if (cpl_bytes > rem_now) over_c <= over_c + 32'd1;
          end else begin
            // A split completion: the request is not finished, so the tag
            // stays outstanding. Freeing it here would allow the tag to be
            // reused while the rest of the data was still in flight.
            t_rem[cpl_tag] <= rem_now - cpl_bytes;
            partial_c <= partial_c + 32'd1;
          end
        end
      end

      // ---- then the request ----
      if (req_valid) begin
        if (req_posted) begin
          posted_c <= posted_c + 32'd1;
        end else if (free_any) begin
          // free_tag was chosen from the table as it stood at the start of
          // the cycle, so it is not an index any completion is retiring
          // right now.
          t_busy[free_tag] <= 1'b1;
          t_rem[free_tag]  <= req_bytes;
          alloc_c <= alloc_c + 32'd1;
        end else begin
          stall_c <= stall_c + 32'd1;
        end
      end
    end
  end

endmodule


// ---------------------------------------------------------------------
//  usb_xact_slot -- one in flight, matched by nothing.
//
//  The same question, answered by construction. A USB host issues one
//  transaction to an endpoint and waits for the response; the response is
//  the next thing on the wire. So:
//
//    * There is no tag. There is no field in any USB packet that
//      identifies which transaction a response belongs to, because the
//      question never arises.
//
//    * There is no reordering. One outstanding transaction cannot be
//      overtaken.
//
//    * There is no split-completion reassembly. A transaction's data
//      arrives in one transaction.
//
//    * And there is no tag-reuse bug to have.
//
//  What it costs is in the port list too, by omission: there is no way to
//  have a second transaction outstanding, so throughput is 1 / latency
//  and no amount of link bandwidth changes that. Section 5 measures it.
// ---------------------------------------------------------------------
module usb_xact_slot #(
  parameter integer N_EP = 4
) (
  input  wire       clk,
  input  wire       rst_n,

  // ---- issue a transaction to an endpoint ----
  input  wire       iss_valid,
  input  wire [$clog2(N_EP)-1:0] iss_ep,

  output wire       iss_ready,   // that endpoint was idle
  output wire       iss_busy,    // that endpoint already has one in flight

  // ---- the response, which can only belong to that endpoint's ----
  input  wire       rsp_valid,
  input  wire [$clog2(N_EP)-1:0] rsp_ep,

  output wire       rsp_match,   // there was a transaction to answer
  output wire       rsp_spurious,// there was not

  output wire [31:0] n_issued,
  output wire [31:0] n_refused,
  output wire [31:0] n_answered,
  output wire [31:0] n_spurious,
  output wire [31:0] n_outstanding
);

  localparam integer EW = $clog2(N_EP);

  // One bit per endpoint. That is the entire mechanism -- compare it with
  // the tag array above, which needs a byte counter per entry because a
  // completion can be partial.
  reg  ep_busy [0:N_EP-1];

  integer i;

  assign iss_ready = iss_valid && !ep_busy[iss_ep];
  assign iss_busy  = iss_valid &&  ep_busy[iss_ep];

  // A response with nothing outstanding on that endpoint. On a real bus
  // this is a device talking when it was not asked, which USB treats as a
  // protocol error -- and which is detectable precisely because there is
  // only ever one thing it could have been answering.
  assign rsp_match    = rsp_valid &&  ep_busy[rsp_ep];
  assign rsp_spurious = rsp_valid && !ep_busy[rsp_ep];

  reg [31:0] iss_c, ref_c, ans_c, spur_c;
  assign n_issued   = iss_c;
  assign n_refused  = ref_c;
  assign n_answered = ans_c;
  assign n_spurious = spur_c;

  reg [31:0] out_now;
  always @(*) begin
    out_now = 32'd0;
    for (i = 0; i < N_EP; i = i + 1) if (ep_busy[i]) out_now = out_now + 32'd1;
  end
  assign n_outstanding = out_now;

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      for (i = 0; i < N_EP; i = i + 1) ep_busy[i] <= 1'b0;
      iss_c  <= 32'd0;
      ref_c  <= 32'd0;
      ans_c  <= 32'd0;
      spur_c <= 32'd0;
    end else begin
      // Responses first, for the same reason as the tracker: an endpoint
      // answered this cycle can be reissued in this cycle.
      if (rsp_valid) begin
        if (ep_busy[rsp_ep]) begin
          ep_busy[rsp_ep] <= 1'b0;
          ans_c <= ans_c + 32'd1;
        end else begin
          spur_c <= spur_c + 32'd1;
        end
      end

      if (iss_valid) begin
        if (!ep_busy[iss_ep]) begin
          ep_busy[iss_ep] <= 1'b1;
          iss_c <= iss_c + 32'd1;
        end else begin
          ref_c <= ref_c + 32'd1;
        end
      end
    end
  end

endmodule

    cycles(tags = 1, L)  ==  K * (L + 1)          K = 24

    cycles(tags >= L + 1, L)  ==  K + L

    cycles(tags <= L, L)  >   K + L

    a PCIe write is fast because it is over when it leaves
    a PCIe read is slow because it is not over until it returns

// =====================================================================
//  Testbench for pcie_tag_tracker and usb_xact_slot.
//
//  THE HEADLINE IS A THROUGHPUT SURFACE, NOT A PASS/FAIL.
//
//  Both designs answer "which request was this response for?". The
//  interesting question is what each one's answer COSTS, and the cost is
//  concurrency: how many transactions can be in flight at once.
//
//  So the bench contains a FABRIC MODEL with a settable latency, issues
//  requests as fast as the tracker will take them, and measures how many
//  cycles it takes to retire a fixed number. Sweeping (tag_limit,
//  latency) gives a surface, and the tag_limit = 1 row of that surface IS
//  the USB behaviour -- because a USB host has exactly one transaction
//  outstanding per endpoint, by construction.
//
//  THE SHADOW MODEL IS FORMULATED IN THE OPPOSITE DIRECTION. The tracker
//  allocates by walking its tags DOWNWARDS so the lowest free index wins;
//  the model walks UPWARDS and stops at the first free one. Same answer,
//  different derivation.
// =====================================================================
`timescale 1ns/1ps
module tb_tg_v;

  localparam integer N_TAG = 8;
  localparam integer N_EP  = 4;
  localparam integer MAXF  = 64;   // fabric depth: in-flight completions

  reg clk = 1'b0, rst_n = 1'b0;
  always #5 clk = ~clk;

  // ---- PCIe side ----
  reg  [3:0]  tag_limit = 4'd8;
  reg         req_valid = 1'b0, req_posted = 1'b0;
  reg  [15:0] req_bytes = 16'd0;
  wire        req_ready, req_stall;
  wire [2:0]  req_tag;
  reg         cpl_valid = 1'b0;
  reg  [2:0]  cpl_tag = 3'd0;
  reg  [15:0] cpl_bytes = 16'd0;
  wire        cpl_retire;
  wire [31:0] n_alloc, n_posted, n_stall, n_retire, n_partial,
              n_bad_tag, n_over, n_outstanding;

  pcie_tag_tracker #(.N_TAG(N_TAG)) dut (
    .clk(clk), .rst_n(rst_n), .tag_limit(tag_limit),
    .req_valid(req_valid), .req_posted(req_posted), .req_bytes(req_bytes),
    .req_ready(req_ready), .req_tag(req_tag), .req_stall(req_stall),
    .cpl_valid(cpl_valid), .cpl_tag(cpl_tag), .cpl_bytes(cpl_bytes),
    .cpl_retire(cpl_retire),
    .n_alloc(n_alloc), .n_posted(n_posted), .n_stall(n_stall),
    .n_retire(n_retire), .n_partial(n_partial), .n_bad_tag(n_bad_tag),
    .n_over(n_over), .n_outstanding(n_outstanding)
  );

  // ---- USB side ----
  reg        iss_valid = 1'b0;
  reg  [1:0] iss_ep = 2'd0;
  wire       iss_ready, iss_busy;
  reg        rsp_valid = 1'b0;
  reg  [1:0] rsp_ep = 2'd0;
  wire       rsp_match, rsp_spurious;
  wire [31:0] u_n_issued, u_n_refused, u_n_answered, u_n_spurious, u_n_out;

  usb_xact_slot #(.N_EP(N_EP)) udut (
    .clk(clk), .rst_n(rst_n),
    .iss_valid(iss_valid), .iss_ep(iss_ep),
    .iss_ready(iss_ready), .iss_busy(iss_busy),
    .rsp_valid(rsp_valid), .rsp_ep(rsp_ep),
    .rsp_match(rsp_match), .rsp_spurious(rsp_spurious),
    .n_issued(u_n_issued), .n_refused(u_n_refused),
    .n_answered(u_n_answered), .n_spurious(u_n_spurious),
    .n_outstanding(u_n_out)
  );

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

  // ---- cumulative across resets ----
  //
  // The DUTs' own counters are zeroed by every reset_all, so reading them in
  // the final summary would report only whatever happened after the last
  // one. Per-step checks still use the DUT counters directly; these are for
  // the totals.
  integer c_alloc = 0, c_posted = 0, c_stall = 0, c_retire = 0,
          c_partial = 0, c_bad = 0, c_over = 0;
  integer c_iss = 0, c_ref = 0, c_ans = 0, c_spur = 0;

  // $random is SIGNED: mask the sign bit before any modulo.
  function [31:0] urand;
    input dummy;
    begin urand = $random(seed) & 32'h3FFF_FFFF; end
  endfunction

  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

  // ---- what the design said, sampled at a DEFINED instant ----
  //
  // cpl_retire is only meaningful while cpl_valid is asserted. A check
  // placed after do_cpl returns reads it after the deassert, where the
  // answer is a delta-cycle artefact -- which produced 4 failures against a
  // design that was entirely correct. Capture once, assert on the capture.
  reg obs_retire;

  // ---- the shadow tracker, maintained by the bench ----
  reg        m_busy [0:N_TAG-1];
  reg [15:0] m_rem  [0:N_TAG-1];
  reg        um_busy [0:N_EP-1];

  // Upward-and-stop, the opposite of the design's downward walk.
  function m_free_any(input [3:0] lim);
    integer j; reg f;
    begin
      f = 1'b0;
      for (j = 0; j < N_TAG; j = j + 1)
        if (!m_busy[j] && (j < lim) && !f) f = 1'b1;
      m_free_any = f;
    end
  endfunction

  function [2:0] m_free_tag(input [3:0] lim);
    integer j; reg f; reg [2:0] t;
    begin
      f = 1'b0; t = 3'd0;
      for (j = 0; j < N_TAG; j = j + 1)
        if (!m_busy[j] && (j < lim) && !f) begin t = j[2:0]; f = 1'b1; end
      m_free_tag = t;
    end
  endfunction

  function [31:0] m_out;
    input dummy;
    integer j; reg [31:0] c;
    begin
      c = 32'd0;
      for (j = 0; j < N_TAG; j = j + 1) if (m_busy[j]) c = c + 32'd1;
      m_out = c;
    end
  endfunction

  function [31:0] um_out;
    input dummy;
    integer j; reg [31:0] c;
    begin
      c = 32'd0;
      for (j = 0; j < N_EP; j = j + 1) if (um_busy[j]) c = c + 32'd1;
      um_out = c;
    end
  endfunction

  // ---- the fabric: completions in flight, each with a due cycle ----
  //
  // A model of the thing PCIe has and USB does not: a transport that holds
  // several requests at once and returns them WHENEVER, not in order.
  reg        f_act   [0:MAXF-1];
  reg [2:0]  f_tag   [0:MAXF-1];
  reg [15:0] f_bytes [0:MAXF-1];
  integer    f_due   [0:MAXF-1];
  integer    now_c;

  task fabric_clear;
    integer j;
    begin
      for (j = 0; j < MAXF; j = j + 1) f_act[j] = 1'b0;
      now_c = 0;
    end
  endtask

  task fabric_push(input [2:0] t, input [15:0] b, input integer due);
    integer j; reg placed;
    begin
      placed = 1'b0;
      for (j = 0; j < MAXF; j = j + 1)
        if (!f_act[j] && !placed) begin
          f_act[j] = 1'b1; f_tag[j] = t; f_bytes[j] = b; f_due[j] = due;
          placed = 1'b1;
        end
      // A full fabric would silently drop a completion and the tag would
      // stay outstanding forever, which reads as a design hang. Bound it.
      ck(placed, "TEST BUG: the fabric model overflowed");
    end
  endtask

  // Pick the earliest-due active completion at or before `now`. Only ONE
  // per cycle, because completions are serialised on a real link.
  task fabric_pop(input integer now, output found, output [2:0] t,
                  output [15:0] b);
    integer j, best, bestdue;
    begin
      best = -1; bestdue = 0; found = 1'b0; t = 3'd0; b = 16'd0;
      for (j = 0; j < MAXF; j = j + 1)
        if (f_act[j] && (f_due[j] <= now))
          if ((best < 0) || (f_due[j] < bestdue)) begin
            best = j; bestdue = f_due[j];
          end
      if (best >= 0) begin
        found = 1'b1; t = f_tag[best]; b = f_bytes[best];
        f_act[best] = 1'b0;
      end
    end
  endtask

  // ---------------------------------------------------------------
  //  THE MEASUREMENT.
  //
  //  Issue K non-posted requests as fast as the tracker accepts them,
  //  against a fabric of fixed latency, and count the cycles until the
  //  last one retires. Everything about the result is decided by how many
  //  tags the requester is allowed to hold.
  // ---------------------------------------------------------------
  integer K_XACT = 24;

  task measure(input integer lim, input integer lat, output integer cycles);
    integer issued, retired, guard;
    reg      pop_found;
    reg [2:0] pop_tag;
    reg [15:0] pop_bytes;
    reg [2:0]  got_tag;
    reg        pre_free;
    reg [2:0]  pre_tag;
    integer j;
    begin
      // reset both the DUT and the model
      rst_n = 1'b0;
      req_valid = 1'b0; cpl_valid = 1'b0; req_posted = 1'b0;
      @(posedge clk); @(posedge clk);
      rst_n = 1'b1;
      @(posedge clk); #1;
      for (j = 0; j < N_TAG; j = j + 1) begin m_busy[j] = 1'b0; m_rem[j] = 16'd0; end
      fabric_clear;

      tag_limit = lim[3:0];
      issued = 0; retired = 0; guard = 0;

      // Every wait loop is bounded. An unbounded one turns a design hang
      // into a test that never finishes, which is strictly worse.
      while ((retired < K_XACT) && (guard < 20000)) begin
        // present at most one due completion
        fabric_pop(now_c, pop_found, pop_tag, pop_bytes);
        cpl_valid = pop_found;
        cpl_tag   = pop_tag;
        cpl_bytes = pop_bytes;

        // offer a request whenever there are any left
        req_valid  = (issued < K_XACT);
        req_posted = 1'b0;
        req_bytes  = 16'd64;

        #1;
        got_tag = req_tag;

        // The allocation decision is taken from the table as it stood at the
        // START of this cycle, because the design's free_any is
        // combinational over the REGISTERED tag array. A tag retired by the
        // completion being presented right now is not allocatable until next
        // cycle -- one cycle of turnaround per tag, which is why saturating
        // a fabric of latency L needs L+1 tags.
        //
        // Applying the completion to the model first, and only then judging
        // the allocation, made the model one cycle ahead of the design. The
        // sweep then hung at every point where latency was less than the tag
        // limit, and reported 20000 -- the guard value -- for 54 of its 64
        // cells. Ordering, not arithmetic.
        pre_free = m_free_any(lim[3:0]);
        pre_tag  = m_free_tag(lim[3:0]);

        // ---- PROPERTY 1: the tracker and the model pick the same tag ----
        if (req_valid && pre_free) begin
          ck(req_ready === 1'b1, "a request was refused while a tag was free");
          ck(got_tag === pre_tag, "the tracker allocated a different tag than the model");
        end else if (req_valid) begin
          // ---- PROPERTY 2: no free tag means a stall, not a silent drop ----
          ck(req_stall === 1'b1, "the tracker neither accepted nor stalled a request");
          ck(req_ready === 1'b0, "the tracker accepted a request with no tag free");
        end

        // ---- now advance the model, completions first, exactly as the
        //      design's clocked process does ----
        if (cpl_valid && m_busy[pop_tag]) begin
          if (pop_bytes >= m_rem[pop_tag]) begin
            m_busy[pop_tag] = 1'b0; m_rem[pop_tag] = 16'd0;
            retired = retired + 1;
          end else begin
            m_rem[pop_tag] = m_rem[pop_tag] - pop_bytes;
          end
        end
        if (req_valid && pre_free) begin
          m_busy[pre_tag] = 1'b1;
          m_rem[pre_tag]  = 16'd64;
          fabric_push(pre_tag, 16'd64, now_c + lat);
          issued = issued + 1;
        end

        @(posedge clk); #1;

        // ---- PROPERTY 3: outstanding count is exact, every cycle ----
        //
        // Checked AFTER the edge. Before it, the design's combinational
        // count still describes the previous cycle while the model has
        // already advanced -- comparing across that boundary produced 1122
        // failures against a design and a model that agreed perfectly.
        ck(n_outstanding === m_out(0),
           "the tracker and the model disagree about how many tags are in flight");

        now_c = now_c + 1;
        guard = guard + 1;
        steps = steps + 1;
      end
      req_valid = 1'b0; cpl_valid = 1'b0;
      ck(retired == K_XACT, "the measurement did not retire every transaction");
      cycles = now_c;
    end
  endtask

  // ---------------------------------------------------------------
  //  Single-step helpers for the directed phases.
  // ---------------------------------------------------------------
  task do_req(input posted, input [15:0] bytes, output [2:0] tg,
              output accepted);
    begin
      req_valid = 1'b1; req_posted = posted; req_bytes = bytes;
      #1;
      tg = req_tag;
      accepted = req_ready;
      if (!posted) begin
        if (m_free_any(tag_limit)) begin
          ck(req_ready === 1'b1, "a request was refused while a tag was free");
          ck(req_tag === m_free_tag(tag_limit), "wrong tag allocated");
        end else begin
          ck(req_stall === 1'b1, "no stall was raised with every tag busy");
        end
      end else begin
        // ---- PROPERTY 4: a posted request never consumes a tag ----
        //
        // This is why a PCIe write is fast and a PCIe read is not: the
        // write is finished when it is sent.
        ck(req_ready === 1'b1, "a posted request was refused");
        ck(req_stall === 1'b0, "a posted request was stalled by tag exhaustion");
      end
      @(posedge clk); #1;
      req_valid = 1'b0;
      if (!posted && accepted) begin
        m_busy[tg] = 1'b1; m_rem[tg] = bytes;
        c_alloc = c_alloc + 1;
      end
      if (posted)                 c_posted = c_posted + 1;
      if (!posted && !accepted)   c_stall  = c_stall + 1;
      ck(n_outstanding === m_out(0), "outstanding count wrong after a request");
      steps = steps + 1;
    end
  endtask

  task do_cpl(input [2:0] t, input [15:0] bytes);
    reg e_known, e_last, e_over;
    reg [31:0] r0, p0, b0, o0;
    begin
      e_known = m_busy[t];
      e_last  = e_known && (bytes >= m_rem[t]);
      e_over  = e_known && (bytes >  m_rem[t]);
      r0 = n_retire; p0 = n_partial; b0 = n_bad_tag; o0 = n_over;

      cpl_valid = 1'b1; cpl_tag = t; cpl_bytes = bytes;
      #1;
      obs_retire = cpl_retire;
      // ---- PROPERTY 5: retire means the LAST byte arrived ----
      //
      // A tag freed on a partial completion could be reused while the rest
      // of the data was still in flight, and the next transaction would
      // then collect it.
      ck(cpl_retire === e_last,
         "retire does not mean the request was completely satisfied");
      @(posedge clk); #1;
      cpl_valid = 1'b0;

      if (!e_known)      c_bad     = c_bad + 1;
      else if (e_last)   c_retire  = c_retire + 1;
      else               c_partial = c_partial + 1;
      if (e_over)        c_over    = c_over + 1;

      if (!e_known) begin
        // ---- PROPERTY 6: a completion for a free tag is reported ----
        ck(n_bad_tag == b0 + 32'd1, "a completion for an unowned tag was not reported");
        ck(n_retire == r0, "an unowned completion retired something");
      end else if (e_last) begin
        m_busy[t] = 1'b0; m_rem[t] = 16'd0;
        ck(n_retire == r0 + 32'd1, "a finishing completion did not retire");
        ck(n_over == o0 + (e_over ? 32'd1 : 32'd0), "overrun miscounted");
      end else begin
        m_rem[t] = m_rem[t] - bytes;
        // ---- PROPERTY 7: a partial completion keeps the tag ----
        ck(n_partial == p0 + 32'd1, "a partial completion was not counted");
        ck(n_retire == r0, "a partial completion retired the tag");
      end
      ck(n_outstanding === m_out(0), "outstanding count wrong after a completion");
      steps = steps + 1;
    end
  endtask

  task reset_all;
    integer j;
    begin
      rst_n = 1'b0;
      req_valid = 1'b0; cpl_valid = 1'b0; req_posted = 1'b0;
      iss_valid = 1'b0; rsp_valid = 1'b0;
      @(posedge clk); @(posedge clk);
      rst_n = 1'b1;
      @(posedge clk); #1;
      for (j = 0; j < N_TAG; j = j + 1) begin m_busy[j] = 1'b0; m_rem[j] = 16'd0; end
      for (j = 0; j < N_EP;  j = j + 1) um_busy[j] = 1'b0;
      tag_limit = 4'd8;
    end
  endtask

  // ---- the USB side ----
  task do_iss(input [1:0] ep);
    reg e_busy;
    reg [31:0] i0, f0;
    begin
      e_busy = um_busy[ep];
      i0 = u_n_issued; f0 = u_n_refused;
      iss_valid = 1'b1; iss_ep = ep;
      #1;
      // ---- PROPERTY 8: one outstanding transaction per endpoint ----
      //
      // The entire mechanism. There is no second slot to have, which is
      // why no USB packet carries a transaction identifier.
      ck(iss_ready === !e_busy, "the slot accepted a second transaction on one endpoint");
      ck(iss_busy  ===  e_busy, "busy was not reported for an occupied endpoint");
      ck(!(iss_ready && iss_busy), "ready and busy were both asserted");
      @(posedge clk); #1;
      iss_valid = 1'b0;
      if (!e_busy) begin
        um_busy[ep] = 1'b1;
        c_iss = c_iss + 1;
        ck(u_n_issued == i0 + 32'd1, "an accepted transaction was not counted");
      end else begin
        c_ref = c_ref + 1;
        ck(u_n_refused == f0 + 32'd1, "a refused transaction was not counted");
      end
      ck(u_n_out === um_out(0), "usb outstanding count wrong after an issue");
      steps = steps + 1;
    end
  endtask

  task do_rsp(input [1:0] ep);
    reg e_busy;
    reg [31:0] a0, s0;
    begin
      e_busy = um_busy[ep];
      a0 = u_n_answered; s0 = u_n_spurious;
      rsp_valid = 1'b1; rsp_ep = ep;
      #1;
      // ---- PROPERTY 9: a response with nothing outstanding is spurious ----
      //
      // Detectable precisely BECAUSE there is only one thing it could have
      // been answering. With N tags in flight the same question needs a
      // tag field to answer at all.
      ck(rsp_match    ===  e_busy, "a response was not matched to its transaction");
      ck(rsp_spurious === !e_busy, "an unsolicited response was not flagged");
      @(posedge clk); #1;
      rsp_valid = 1'b0;
      if (e_busy) begin
        um_busy[ep] = 1'b0;
        c_ans = c_ans + 1;
        ck(u_n_answered == a0 + 32'd1, "an answered transaction was not counted");
      end else begin
        c_spur = c_spur + 1;
        ck(u_n_spurious == s0 + 32'd1, "a spurious response was not counted");
      end
      ck(u_n_out === um_out(0), "usb outstanding count wrong after a response");
      steps = steps + 1;
    end
  endtask

  // ---- results ----
  integer thr_cyc [0:8][0:8];   // cycles for (limit, latency)
  integer lim, lat, k, j, c;
  reg [2:0] tg;
  reg acc;
  reg [31:0] snap;

  // exhaustive reach over (tag_limit 1..8) x (latency 1..8) = 64
  reg reach [0:63];
  integer nr, ri;
  // and over the directed tracker state space, below
  reg reach_t [0:255];
  integer nrt;

  initial begin
    for (ri = 0; ri < 64;  ri = ri + 1) reach[ri]   = 1'b0;
    for (ri = 0; ri < 256; ri = ri + 1) reach_t[ri] = 1'b0;
    seed = 32'd28004;

    reset_all;

    // =============================================================
    //  PHASE 1 (DIRECTED, EXHAUSTIVE) -- THE THROUGHPUT SURFACE.
    //
    //  Every tag limit from 1 to 8 against every fabric latency from 1 to
    //  8: 64 points, all reachable, both dimensions independent inputs.
    //
    //  The tag_limit = 1 row is the USB case. A USB host has exactly one
    //  transaction outstanding per endpoint, so whatever that row says
    //  about throughput is what USB can do regardless of link speed.
    // =============================================================
    for (lim = 1; lim <= 8; lim = lim + 1)
    for (lat = 1; lat <= 8; lat = lat + 1) begin
      measure(lim, lat, c);
      thr_cyc[lim][lat] = c;
      reach[(lim - 1) * 8 + (lat - 1)] = 1'b1;
    end

    // ---- PROPERTY 10: more tags never make it slower ----
    //
    // Monotonicity in the tag count. Stated as a property rather than
    // eyeballed off the table, because a tracker that leaked tags would
    // produce a table that still looked plausible.
    for (lat = 1; lat <= 8; lat = lat + 1)
      for (lim = 2; lim <= 8; lim = lim + 1)
        ck(thr_cyc[lim][lat] <= thr_cyc[lim-1][lat],
           "adding a tag made the transfer slower");

    // ---- PROPERTY 11: more latency never makes it faster ----
    for (lim = 1; lim <= 8; lim = lim + 1)
      for (lat = 2; lat <= 8; lat = lat + 1)
        ck(thr_cyc[lim][lat] >= thr_cyc[lim][lat-1],
           "adding latency made the transfer faster");

    // ---- PROPERTY 12: one tag costs the full latency, EXACTLY ----
    //
    // THE USB RESULT, as a closed form rather than an observation. With one
    // outstanding transaction nothing overlaps, so each takes (latency + 1)
    // cycles -- latency to come back, one to issue the next -- and the total
    // is exactly K*(latency+1). No amount of link bandwidth changes it.
    //
    // Asserted with == rather than >=. An inequality would also pass for a
    // design that was slower still, and the point of a closed form is that
    // it pins the number from both sides.
    for (lat = 1; lat <= 8; lat = lat + 1)
      ck(thr_cyc[1][lat] == K_XACT * (lat + 1),
         "one outstanding transaction did not cost exactly latency+1 cycles each");

    // ---- PROPERTY 13: latency+1 tags saturate the link, EXACTLY ----
    //
    // The other closed form, and the one that answers "how many tags do I
    // need?". With L+1 tags the requester issues one per cycle and the only
    // cost left is draining the last one, so the total is exactly K + L.
    //
    // It is latency+1 and not latency because of the one-cycle tag
    // turnaround: free_any reads the REGISTERED tag array, so a tag retired
    // this cycle is allocatable next cycle. That single cycle is the
    // difference between needing L tags and needing L+1.
    for (lat = 1; lat <= 8; lat = lat + 1)
      for (lim = lat + 1; lim <= 8; lim = lim + 1)
        ck(thr_cyc[lim][lat] == K_XACT + lat,
           "latency+1 tags did not saturate the link");

    // ---- PROPERTY 14: fewer than latency+1 tags CANNOT saturate ----
    //
    // The negative half, without which the property above would be
    // satisfied by a design that was always saturated regardless of tags --
    // and the whole chapter would have no result.
    for (lat = 2; lat <= 8; lat = lat + 1)
      for (lim = 1; lim <= lat; lim = lim + 1)
        ck(thr_cyc[lim][lat] > K_XACT + lat,
           "fewer tags than latency+1 saturated the link anyway");

    // =============================================================
    //  PHASE 2 (DIRECTED) -- COMPLETIONS OUT OF ORDER.
    //
    //  The case USB cannot produce. Four tags are allocated in order and
    //  completed in REVERSE, and every one must retire correctly.
    // =============================================================
    reset_all;
    do_req(1'b0, 16'd64, tg, acc); ck(tg === 3'd0, "first tag should be 0");
    do_req(1'b0, 16'd64, tg, acc); ck(tg === 3'd1, "second tag should be 1");
    do_req(1'b0, 16'd64, tg, acc); ck(tg === 3'd2, "third tag should be 2");
    do_req(1'b0, 16'd64, tg, acc); ck(tg === 3'd3, "fourth tag should be 3");
    ck(n_outstanding === 32'd4, "four requests should leave four tags in flight");
    do_cpl(3'd3, 16'd64);
    do_cpl(3'd1, 16'd64);
    do_cpl(3'd2, 16'd64);
    do_cpl(3'd0, 16'd64);
    ck(n_outstanding === 32'd0, "completing every tag should empty the tracker");
    ck(n_retire === 32'd4, "four completions should retire four requests");
    ck(n_bad_tag === 32'd0, "out-of-order completion reported a bad tag");

    // =============================================================
    //  PHASE 3 (DIRECTED, EXHAUSTIVE over every completion order)
    //
    //  Three tags, all 3! = 6 completion orders. Out-of-order is not one
    //  case, it is every permutation, and a tracker that happened to work
    //  for reverse order is not thereby correct for the rest.
    // =============================================================
    for (k = 0; k < 6; k = k + 1) begin : perm
      integer a, b2, c2, t0;
      reset_all;
      do_req(1'b0, 16'd64, tg, acc);
      do_req(1'b0, 16'd64, tg, acc);
      do_req(1'b0, 16'd64, tg, acc);
      // the six orderings of {0,1,2}
      case (k)
        0: begin a = 0; b2 = 1; c2 = 2; end
        1: begin a = 0; b2 = 2; c2 = 1; end
        2: begin a = 1; b2 = 0; c2 = 2; end
        3: begin a = 1; b2 = 2; c2 = 0; end
        4: begin a = 2; b2 = 0; c2 = 1; end
        default: begin a = 2; b2 = 1; c2 = 0; end
      endcase
      do_cpl(a[2:0],  16'd64);
      do_cpl(b2[2:0], 16'd64);
      do_cpl(c2[2:0], 16'd64);
      ck(n_outstanding === 32'd0, "some completion order left a tag outstanding");
      ck(n_retire === 32'd3, "some completion order lost a retirement");
      ck(n_bad_tag === 32'd0, "some completion order was mistaken for a bad tag");
    end

    // =============================================================
    //  PHASE 4 (DIRECTED, EXHAUSTIVE over split shapes) -- SPLIT
    //  COMPLETIONS.
    //
    //  One request may be answered by several completions. The tag must
    //  stay outstanding until the LAST byte arrives -- freeing it early is
    //  the tag-reuse bug, and it would attribute the remaining data to
    //  whatever transaction took the tag next.
    //
    //  Every split of 256 bytes into equal pieces of 256, 128, 64, 32 and
    //  16 is swept, which is every shape a power-of-two payload can take.
    // =============================================================
    for (k = 0; k < 5; k = k + 1) begin : splits
      integer piece, pieces, n;
      reset_all;
      piece  = 256 >> k;
      pieces = 256 / piece;
      do_req(1'b0, 16'd256, tg, acc);
      for (n = 0; n < pieces; n = n + 1) begin
        do_cpl(tg, piece[15:0]);
        if (n < pieces - 1) begin
          // ---- PROPERTY 13: a partially completed tag stays busy ----
          ck(n_outstanding === 32'd1,
             "a tag was freed before its last completion arrived");
          ck(obs_retire === 1'b0, "a partial completion claimed to retire");
        end
      end
      ck(n_outstanding === 32'd0, "the tag was not freed by its last completion");
      ck(n_partial === (pieces - 1),
         "the number of partial completions does not match the split");
    end

    // =============================================================
    //  PHASE 5 (DIRECTED) -- TAG EXHAUSTION IS BACK-PRESSURE.
    //
    //  With two tags, a third request must STALL rather than be dropped or
    //  accepted. That stall is why PCIe read throughput depends on tag
    //  count, and it is the mechanism phase 1 measures.
    // =============================================================
    reset_all;
    tag_limit = 4'd2;
    do_req(1'b0, 16'd64, tg, acc); ck(acc === 1'b1, "first of two tags refused");
    do_req(1'b0, 16'd64, tg, acc); ck(acc === 1'b1, "second of two tags refused");
    snap = n_stall;
    do_req(1'b0, 16'd64, tg, acc);
    ck(acc === 1'b0, "a third request was accepted with only two tags");
    ck(n_stall == snap + 32'd1, "tag exhaustion did not raise a stall");
    ck(n_outstanding === 32'd2, "a stalled request consumed a tag anyway");
    // ---- PROPERTY 14: a POSTED request is never stalled ----
    //
    // Even with every tag busy. A write needs no completion, so tag
    // exhaustion cannot block it -- which is exactly why mixing posted and
    // non-posted traffic changes a PCIe link's behaviour so much.
    snap = n_posted;
    do_req(1'b1, 16'd64, tg, acc);
    ck(acc === 1'b1, "a posted request was blocked by tag exhaustion");
    ck(n_posted == snap + 32'd1, "a posted request was not counted");
    ck(n_outstanding === 32'd2, "a posted request consumed a tag");
    // and freeing one tag lets the next non-posted request through
    do_cpl(3'd0, 16'd64);
    do_req(1'b0, 16'd64, tg, acc);
    ck(acc === 1'b1, "freeing a tag did not admit the next request");
    ck(tg === 3'd0, "the freed tag was not the one reused");

    // =============================================================
    //  PHASE 5b (DIRECTED, EXHAUSTIVE over every tag limit)
    //
    //  The posted-request guarantee is only OBSERVABLE when no tag is free,
    //  because with a tag free a posted request would be accepted either way.
    //  So the table is filled to capacity at each of the eight limits and the
    //  guarantee is checked there.
    //
    //  That is the difference between a property being stated and being
    //  tested: phase 5 demonstrated it once, which gave the mutation that
    //  breaks it a domain of one.
    // =============================================================
    for (k = 1; k <= 8; k = k + 1) begin : postedsweep
      integer b;
      reg [31:0] psnap, osnap2;
      reset_all;
      tag_limit = k[3:0];
      for (b = 0; b < k; b = b + 1) begin
        do_req(1'b0, 16'd64, tg, acc);
        ck(acc === 1'b1, "a request was refused below the tag limit");
      end
      ck(n_outstanding === k, "filling to the limit did not use every tag");

      // a non-posted request must now stall
      do_req(1'b0, 16'd64, tg, acc);
      ck(acc === 1'b0, "a request was accepted above the tag limit");

      // ---- and a POSTED request must NOT ----
      //
      // This is why a PCIe write never blocks on read credit: it needs no
      // completion, so tag exhaustion cannot apply to it. A design that made
      // writes wait for tags would serialise a workload PCIe is specifically
      // built to overlap.
      psnap = n_posted; osnap2 = n_outstanding;
      do_req(1'b1, 16'd64, tg, acc);
      ck(acc === 1'b1, "a posted request was blocked by tag exhaustion");
      ck(n_posted == psnap + 32'd1, "a posted request was not counted");
      ck(n_outstanding === osnap2, "a posted request consumed a tag");
    end

    // =============================================================
    //  PHASE 6 (DIRECTED) -- MALFORMED COMPLETIONS.
    //
    //  A completion for a tag nobody owns, and a completion carrying more
    //  bytes than were asked for. Both are protocol errors and both must
    //  be REPORTED rather than absorbed -- an absorbed overrun would wrap
    //  the byte counter and leave the tag outstanding forever, turning a
    //  protocol error into a hang.
    // =============================================================
    reset_all;
    snap = n_bad_tag;
    do_cpl(3'd5, 16'd64);        // nobody owns tag 5
    ck(n_bad_tag == snap + 32'd1, "a completion for a free tag was accepted");
    ck(n_outstanding === 32'd0, "an unowned completion changed the tracker state");

    do_req(1'b0, 16'd64, tg, acc);
    snap = n_over;
    do_cpl(tg, 16'd128);         // twice what was asked for
    ck(n_over == snap + 32'd1, "an over-long completion was not reported");
    ck(n_outstanding === 32'd0, "an over-long completion left the tag outstanding");

    // =============================================================
    //  PHASE 6b (DIRECTED, EXHAUSTIVE over overrun shapes)
    //
    //  A completion carrying more bytes than were requested, for every
    //  request size and both interesting overrun amounts: one byte too many,
    //  and twice as many as asked for. Eight cases rather than the single
    //  one phase 6 had, because a mutation that stops reporting overruns
    //  should not be able to score 2.
    //
    //  In every case the tag must still RETIRE. Absorbing the overrun by
    //  wrapping the byte counter would leave the tag outstanding forever and
    //  turn a protocol error into a hang, which is strictly worse.
    // =============================================================
    for (k = 0; k < 8; k = k + 1) begin : overruns
      integer want, extra;
      reg [31:0] osnap;
      reset_all;
      want  = 16 << (k % 4);
      extra = (k < 4) ? 1 : want;      // one byte too many, or double
      do_req(1'b0, want[15:0], tg, acc);
      osnap = n_over;
      do_cpl(tg, (want + extra));
      ck(n_over == osnap + 32'd1, "an over-long completion was not reported");
      ck(n_outstanding === 32'd0,
         "an over-long completion left the tag outstanding");
      ck(n_retire > 32'd0, "an over-long completion did not retire the tag");
    end

    // =============================================================
    //  PHASE 7 (DIRECTED, EXHAUSTIVE over the tracker's busy-mask)
    //
    //  Every one of the 2**8 = 256 combinations of which tags are busy,
    //  reached by allocating and completing rather than by forcing state.
    //  For each, the allocation decision is checked against the model.
    // =============================================================
    for (k = 0; k < 256; k = k + 1) begin : masks
      integer b;
      reset_all;
      // allocate all eight, then complete the ones the mask says are free
      for (b = 0; b < 8; b = b + 1) do_req(1'b0, 16'd64, tg, acc);
      ck(n_outstanding === 32'd8, "eight requests did not fill eight tags");
      for (b = 0; b < 8; b = b + 1)
        if (!k[b]) do_cpl(b[2:0], 16'd64);
      // ---- a POSTED request, against every table state ----
      //
      // It must be accepted and must consume no tag, whatever else is in
      // flight -- including when every tag is busy. Swept here rather than
      // demonstrated once, because a property exercised a single time has a
      // mutation domain of one and tells you almost nothing.
      snap = n_outstanding;
      do_req(1'b1, 16'd64, tg, acc);
      ck(acc === 1'b1, "a posted request was refused");
      ck(n_outstanding === snap, "a posted request consumed a tag");

      // ---- a completion for a tag NOBODY OWNS, against every state ----
      //
      // Whichever tag is free, a completion for it is a protocol error and
      // must be reported rather than absorbed. With a full table this case
      // does not exist, so it is skipped rather than faked.
      if (m_free_any(4'd8)) begin : badcpl
        reg [2:0] ft;
        reg [31:0] bsnap, osnap;
        ft = m_free_tag(4'd8);
        bsnap = n_bad_tag; osnap = n_outstanding;
        do_cpl(ft, 16'd64);
        ck(n_bad_tag == bsnap + 32'd1,
           "a completion for an unowned tag was not reported");
        ck(n_outstanding === osnap,
           "a completion for an unowned tag changed the tracker state");
      end

      // Now exactly the tags set in k are busy. The next allocation must
      // pick the lowest free one, which the model computes independently.
      if (m_free_any(4'd8)) begin
        do_req(1'b0, 16'd64, tg, acc);
        ck(acc === 1'b1, "a request was refused with a free tag");
      end else begin
        do_req(1'b0, 16'd64, tg, acc);
        ck(acc === 1'b0, "a request was accepted with every tag busy");
      end
      reach_t[k] = 1'b1;
    end

    // =============================================================
    //  PHASE 8 (DIRECTED) -- THE USB SLOT.
    //
    //  One outstanding transaction per endpoint. The endpoints are
    //  independent, a second issue to a busy endpoint is refused, and a
    //  response with nothing outstanding is flagged.
    // =============================================================
    reset_all;
    for (k = 0; k < 4; k = k + 1) begin
      do_iss(k[1:0]);
      ck(u_n_out === (k + 1), "each endpoint should hold one transaction");
    end
    // every endpoint busy: a second issue to each must be refused
    for (k = 0; k < 4; k = k + 1) do_iss(k[1:0]);
    ck(u_n_refused === 32'd4, "four second-issues should all be refused");
    ck(u_n_out === 32'd4, "a refused issue changed the outstanding count");
    // answer them all
    for (k = 0; k < 4; k = k + 1) do_rsp(k[1:0]);
    ck(u_n_out === 32'd0, "answering every endpoint should empty the slots");
    // an unsolicited response
    snap = u_n_spurious;
    do_rsp(2'd2);
    ck(u_n_spurious == snap + 32'd1, "an unsolicited response was not flagged");

    // =============================================================
    //  PHASE 9 (DIRECTED, EXHAUSTIVE over the endpoint busy-mask)
    //
    //  All 2**4 = 16 combinations of which endpoints are busy, crossed
    //  with an issue and a response to each of the 4 endpoints. 16 x 4 x 2
    //  decisions, every one checked against the model.
    // =============================================================
    for (k = 0; k < 16; k = k + 1) begin : epmask
      integer b;
      reset_all;
      for (b = 0; b < 4; b = b + 1) if (k[b]) do_iss(b[1:0]);
      for (b = 0; b < 4; b = b + 1) do_iss(b[1:0]);
      reset_all;
      for (b = 0; b < 4; b = b + 1) if (k[b]) do_iss(b[1:0]);
      for (b = 0; b < 4; b = b + 1) do_rsp(b[1:0]);
    end

    // =============================================================
    //  PHASE 10 (RANDOM) -- mixed traffic with a reordering fabric.
    // =============================================================
`ifndef DIRECTED_ONLY
    reset_all;
    fabric_clear;
    for (k = 0; k < 800; k = k + 1) begin : rnd
      reg pf; reg [2:0] pt; reg [15:0] pb;
      // a due completion, if any
      fabric_pop(now_c, pf, pt, pb);
      if (pf) do_cpl(pt, pb);
      // a request, sometimes posted
      if ((urand(0) % 3) != 0) begin
        if ((urand(0) % 5) == 0) begin
          do_req(1'b1, 16'd64, tg, acc);
        end else begin
          do_req(1'b0, 16'd64, tg, acc);
          // A random latency, so completions come back out of order --
          // which is the property the whole tracker exists for.
          if (acc) fabric_push(tg, 16'd64, now_c + 1 + (urand(0) % 9));
        end
      end
      // and some USB traffic on the side
      if ((urand(0) % 2) == 0) do_iss((urand(0) % 4));
      else                     do_rsp((urand(0) % 4));
      now_c = now_c + 1;
    end
    // drain whatever is still in flight, bounded
    for (k = 0; k < 400; k = k + 1) begin : drain
      reg pf2; reg [2:0] pt2; reg [15:0] pb2;
      fabric_pop(now_c + 100, pf2, pt2, pb2);
      if (pf2) do_cpl(pt2, pb2);
      now_c = now_c + 1;
    end
`endif

    nr = 0;  for (ri = 0; ri < 64;  ri = ri + 1) if (reach[ri])   nr  = nr + 1;
    nrt = 0; for (ri = 0; ri < 256; ri = ri + 1) if (reach_t[ri]) nrt = nrt + 1;

    $display("steps=%0d checks=%0d reach_thr=%0d/64 reach_tag=%0d/256 errors=%0d",
             steps, checks, nr, nrt, errors);
    $display("[pcie] alloc=%0d posted=%0d stalls=%0d retire=%0d partial=%0d bad_tag=%0d over=%0d",
             c_alloc, c_posted, c_stall, c_retire, c_partial, c_bad, c_over);
    $display("[usb]  issued=%0d refused=%0d answered=%0d spurious=%0d",
             c_iss, c_ref, c_ans, c_spur);
    $display("--- cycles to move %0d transactions, by tags outstanding x latency ---", K_XACT);
    $display("    tags      L=1     L=2     L=3     L=4     L=5     L=6     L=7     L=8");
    for (lim = 1; lim <= 8; lim = lim + 1)
      $display("    %4d %8d%8d%8d%8d%8d%8d%8d%8d", lim,
               thr_cyc[lim][1], thr_cyc[lim][2], thr_cyc[lim][3], thr_cyc[lim][4],
               thr_cyc[lim][5], thr_cyc[lim][6], thr_cyc[lim][7], thr_cyc[lim][8]);
    $display("    (row tags=1 IS the USB case: one transaction outstanding)");
    if (nr != 64 || nrt != 256) 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

// =====================================================================
//  OUTSTANDING TRANSACTIONS -- SystemVerilog.
//
//  Same hardware contract as the Verilog file: same ports, same widths,
//  same reset values, same cycle-by-cycle behaviour. What changes is
//  `always_comb` / `always_ff`, loop variables declared in the loop, and
//  every continuous assignment written as `logic` + `assign` on separate
//  lines rather than as an initialised declaration.
//
//  THAT LAST POINT IS NOT COSMETIC. `logic x = expr;` is a one-shot
//  VARIABLE INITIALISER in SystemVerilog -- evaluated once at time zero and
//  never again -- while the Verilog `wire x = expr;` it came from is a
//  continuous assignment. Translating the five such lines in the previous
//  chapter mechanically produced 29,580 phantom failures against a design
//  that was entirely correct, and the symptom was structural: nothing ever
//  matched, anywhere.
//
//  OUTSTANDING TRANSACTIONS -- THE MECHANISM PCIe NEEDS AND USB DOES NOT.
//
//  CLASSIFICATION: simplified synthesisable teaching RTL.
//  Two modules. Neither is a controller: there is no TLP encoder, no
//  link layer, no credits, no USB packet engine and no scheduler. Each
//  is the part that answers one question.
//
//      "This response just arrived. Which request was it for?"
//
//  USB answers it by CONSTRUCTION. The host issues one transaction to an
//  endpoint and waits for it. The response is the next thing on the wire,
//  so there is nothing to match -- and USB packets carry no transaction
//  identifier at all, because none is needed.
//
//  PCIe answers it with a TAG. A requester may have many non-posted
//  requests in flight at once; completions travel independently, come
//  back OUT OF ORDER, and may arrive split into several pieces. So every
//  request carries a tag, and the requester must track each one until the
//  last byte of its completion has arrived.
//
//  The difference is not bandwidth, it is CONCURRENCY:
//
//      USB:  one outstanding transaction, so throughput is bounded by
//            1 / latency, whatever the wire can carry.
//      PCIe: N outstanding transactions, so throughput is bounded by
//            min(1, N / latency) -- and with enough tags, not by latency
//            at all.
//
//  That is a formula, so the chapter measures it. Section 5's table is
//  throughput against tag count and latency, and the USB case is exactly
//  its first row.
//
//  What the tags cost is a class of bug that cannot exist on USB: a tag
//  reused before its completion arrives silently attributes one
//  transaction's data to another.
// =====================================================================

// ---------------------------------------------------------------------
//  pcie_tag_tracker -- many in flight, matched by tag.
//
//  `tag_limit` is an INPUT rather than a parameter so the testbench can
//  sweep how many tags the requester is allowed to use without
//  re-elaborating. That is what makes the throughput curve in section 5
//  a single exhaustive sweep instead of eight separate runs -- and it is
//  also how the USB case is reached: tag_limit = 1.
// ---------------------------------------------------------------------
module pcie_tag_tracker #(
  parameter int N_TAG   = 8,
  // Bytes are tracked so a SPLIT completion can be modelled: a single
  // read may be answered by several completions, and the tag is not free
  // until the last byte arrives.
  parameter int MAX_BYTES = 256
) (
  input  logic       clk,
  input  logic       rst_n,

  // How many tags the requester may use, 1..N_TAG. Zero is treated as
  // one: a requester that can have nothing outstanding cannot make
  // progress, and silently deadlocking is worse than clamping.
  input  logic [$clog2(N_TAG+1)-1:0] tag_limit,

  // ---- a request ----
  input  logic        req_valid,
  // POSTED requests (writes) expect no completion and consume no tag.
  // That is why a PCIe write is fast and a PCIe read is not: the write is
  // finished when it is sent, and the read is not finished until it comes
  // back.
  input  logic        req_posted,
  input  logic [15:0] req_bytes,

  output logic        req_ready,   // a tag was available
  output logic [$clog2(N_TAG)-1:0] req_tag,
  output logic        req_stall,   // no tag available: this is back-pressure

  // ---- a completion, arriving whenever the fabric feels like it ----
  input  logic        cpl_valid,
  input  logic [$clog2(N_TAG)-1:0] cpl_tag,
  input  logic [15:0] cpl_bytes,

  output logic        cpl_retire,  // this completion finished its request

  // ---- observability ----
  output logic [31:0] n_alloc,
  output logic [31:0] n_posted,
  output logic [31:0] n_stall,
  output logic [31:0] n_retire,
  output logic [31:0] n_partial,     // a completion that did not finish a tag
  output logic [31:0] n_bad_tag,     // a completion for a tag nobody owns
  output logic [31:0] n_over,        // more bytes returned than requested
  output logic [31:0] n_outstanding  // how many tags are in flight NOW
);

  localparam int TW = $clog2(N_TAG);
  localparam int LW = $clog2(N_TAG+1);

  logic         t_busy [N_TAG];
  logic [15:0]  t_rem  [N_TAG];


  // Clamp to at least one usable tag. A requester allowed zero
  // outstanding transactions can never make progress, and a design that
  // deadlocks silently is harder to debug than one that refuses to.
  logic [LW-1:0] lim;
  assign lim = (tag_limit == 0) ? {{(LW-1){1'b0}}, 1'b1} : tag_limit;

  // -------------------------------------------------------------------
  //  ALLOCATE -- the lowest free tag strictly below the limit.
  //
  //  Walking downwards so the lowest index wins. Real requesters often
  //  allocate round-robin to spread wear on completion buffers; lowest-
  //  free is chosen here because it is deterministic, which is what makes
  //  the tag-reuse property checkable at all.
  // -------------------------------------------------------------------
  logic          free_any;
  logic [TW-1:0] free_tag;
  always_comb begin
    free_any = 1'b0;
    free_tag = '0;
    for (int i = N_TAG - 1; i >= 0; i--) begin
      if (!t_busy[i] && (i < lim)) begin
        free_any = 1'b1;
        free_tag = TW'(i);
      end
    end
  end

  // A posted request needs no tag, so it is never stalled by tag
  // exhaustion. This asymmetry is the whole reason PCIe separates the two
  // classes.
  assign req_ready = req_valid && (req_posted || free_any);
  assign req_tag   = free_tag;
  assign req_stall = req_valid && !req_posted && !free_any;

  // -------------------------------------------------------------------
  //  COMPLETE -- match by tag, subtract bytes, free on the last one.
  // -------------------------------------------------------------------
  logic cpl_known;
  assign cpl_known = cpl_valid && t_busy[cpl_tag];
  logic [15:0] rem_now;
  assign rem_now = t_rem[cpl_tag];
  // More bytes than were asked for. On a real link this is a malformed
  // completion; here it is flagged rather than allowed to wrap the
  // counter, because a wrapped counter would keep the tag outstanding
  // forever and turn a protocol error into a hang.
  logic cpl_overrun;
  assign cpl_overrun = cpl_known && (cpl_bytes > rem_now);
  logic cpl_last;
  assign cpl_last = cpl_known && (cpl_bytes >= rem_now);

  assign cpl_retire = cpl_last;

  logic [31:0] alloc_c, posted_c, stall_c, retire_c, partial_c, bad_c, over_c;
  assign n_alloc   = alloc_c;
  assign n_posted  = posted_c;
  assign n_stall   = stall_c;
  assign n_retire  = retire_c;
  assign n_partial = partial_c;
  assign n_bad_tag = bad_c;
  assign n_over    = over_c;

  // Combinational, so it reports the tracker as it stands rather than as
  // it stood a cycle ago.
  logic [31:0] out_now;
  always_comb begin
    out_now = 32'd0;
    for (int i = 0; i < N_TAG; i++) if (t_busy[i]) out_now = out_now + 32'd1;
  end
  assign n_outstanding = out_now;

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      for (int i = 0; i < N_TAG; i++) begin
        t_busy[i] <= 1'b0;
        t_rem[i]  <= 16'd0;
      end
      alloc_c   <= 32'd0;
      posted_c  <= 32'd0;
      stall_c   <= 32'd0;
      retire_c  <= 32'd0;
      partial_c <= 32'd0;
      bad_c     <= 32'd0;
      over_c    <= 32'd0;
    end else begin
      // ---- completions, then requests ----
      //
      // The order of these two blocks is immaterial to correctness, and it
      // is worth saying why rather than implying otherwise. `free_any` and
      // `free_tag` are combinational over the REGISTERED t_busy, so they
      // describe the table as it stood at the START of this cycle. A tag
      // retired by a completion in this cycle therefore becomes
      // allocatable in the NEXT one -- not this one.
      //
      // That is ONE CYCLE OF TURNAROUND per tag, and it is a real cost with
      // a visible consequence: saturating a fabric of latency L needs L+1
      // tags, not L. Section 5's table shows exactly that boundary.
      //
      // The two blocks cannot collide, because an index being retired is
      // busy and is therefore never the index free_any selects.
      if (cpl_valid) begin
        if (!t_busy[cpl_tag]) begin
          // A completion for a tag nobody owns. Either the fabric
          // invented it or this requester retired the tag early -- and
          // the second is exactly what a tag-reuse bug looks like from
          // here.
          bad_c <= bad_c + 32'd1;
        end else begin
          if (cpl_bytes >= rem_now) begin
            t_busy[cpl_tag] <= 1'b0;
            t_rem[cpl_tag]  <= 16'd0;
            retire_c <= retire_c + 32'd1;
            if (cpl_bytes > rem_now) over_c <= over_c + 32'd1;
          end else begin
            // A split completion: the request is not finished, so the tag
            // stays outstanding. Freeing it here would allow the tag to be
            // reused while the rest of the data was still in flight.
            t_rem[cpl_tag] <= rem_now - cpl_bytes;
            partial_c <= partial_c + 32'd1;
          end
        end
      end

      // ---- then the request ----
      if (req_valid) begin
        if (req_posted) begin
          posted_c <= posted_c + 32'd1;
        end else if (free_any) begin
          // free_tag was chosen from the table as it stood at the start of
          // the cycle, so it is not an index any completion is retiring
          // right now.
          t_busy[free_tag] <= 1'b1;
          t_rem[free_tag]  <= req_bytes;
          alloc_c <= alloc_c + 32'd1;
        end else begin
          stall_c <= stall_c + 32'd1;
        end
      end
    end
  end

endmodule


// ---------------------------------------------------------------------
//  usb_xact_slot -- one in flight, matched by nothing.
//
//  The same question, answered by construction. A USB host issues one
//  transaction to an endpoint and waits for the response; the response is
//  the next thing on the wire. So:
//
//    * There is no tag. There is no field in any USB packet that
//      identifies which transaction a response belongs to, because the
//      question never arises.
//
//    * There is no reordering. One outstanding transaction cannot be
//      overtaken.
//
//    * There is no split-completion reassembly. A transaction's data
//      arrives in one transaction.
//
//    * And there is no tag-reuse bug to have.
//
//  What it costs is in the port list too, by omission: there is no way to
//  have a second transaction outstanding, so throughput is 1 / latency
//  and no amount of link bandwidth changes that. Section 5 measures it.
// ---------------------------------------------------------------------
module usb_xact_slot #(
  parameter int N_EP = 4
) (
  input  logic       clk,
  input  logic       rst_n,

  // ---- issue a transaction to an endpoint ----
  input  logic       iss_valid,
  input  logic [$clog2(N_EP)-1:0] iss_ep,

  output logic       iss_ready,   // that endpoint was idle
  output logic       iss_busy,    // that endpoint already has one in flight

  // ---- the response, which can only belong to that endpoint's ----
  input  logic       rsp_valid,
  input  logic [$clog2(N_EP)-1:0] rsp_ep,

  output logic       rsp_match,   // there was a transaction to answer
  output logic       rsp_spurious,// there was not

  output logic [31:0] n_issued,
  output logic [31:0] n_refused,
  output logic [31:0] n_answered,
  output logic [31:0] n_spurious,
  output logic [31:0] n_outstanding
);

  localparam int EW = $clog2(N_EP);

  // One bit per endpoint. That is the entire mechanism -- compare it with
  // the tag array above, which needs a byte counter per entry because a
  // completion can be partial.
  logic  ep_busy [N_EP];


  assign iss_ready = iss_valid && !ep_busy[iss_ep];
  assign iss_busy  = iss_valid &&  ep_busy[iss_ep];

  // A response with nothing outstanding on that endpoint. On a real bus
  // this is a device talking when it was not asked, which USB treats as a
  // protocol error -- and which is detectable precisely because there is
  // only ever one thing it could have been answering.
  assign rsp_match    = rsp_valid &&  ep_busy[rsp_ep];
  assign rsp_spurious = rsp_valid && !ep_busy[rsp_ep];

  logic [31:0] iss_c, ref_c, ans_c, spur_c;
  assign n_issued   = iss_c;
  assign n_refused  = ref_c;
  assign n_answered = ans_c;
  assign n_spurious = spur_c;

  logic [31:0] out_now;
  always_comb begin
    out_now = 32'd0;
    for (int i = 0; i < N_EP; i++) if (ep_busy[i]) out_now = out_now + 32'd1;
  end
  assign n_outstanding = out_now;

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      for (int i = 0; i < N_EP; i++) ep_busy[i] <= 1'b0;
      iss_c  <= 32'd0;
      ref_c  <= 32'd0;
      ans_c  <= 32'd0;
      spur_c <= 32'd0;
    end else begin
      // Responses first, for the same reason as the tracker: an endpoint
      // answered this cycle can be reissued in this cycle.
      if (rsp_valid) begin
        if (ep_busy[rsp_ep]) begin
          ep_busy[rsp_ep] <= 1'b0;
          ans_c <= ans_c + 32'd1;
        end else begin
          spur_c <= spur_c + 32'd1;
        end
      end

      if (iss_valid) begin
        if (!ep_busy[iss_ep]) begin
          ep_busy[iss_ep] <= 1'b1;
          iss_c <= iss_c + 32'd1;
        end else begin
          ref_c <= ref_c + 32'd1;
        end
      end
    end
  end

endmodule

// =====================================================================
//  Testbench for pcie_tag_tracker and usb_xact_slot -- SystemVerilog.
//
//  SAME SEED AND SAME PHASE ORDER AS THE VERILOG BENCH, deliberately.
//  Icarus seeds $random identically, so both drive identical stimulus and
//  any difference between the two mutation columns is a real difference
//  between the two DESIGNS. The independent-stimulus role is VHDL's.
//
//  THE HEADLINE IS A THROUGHPUT SURFACE, NOT A PASS/FAIL.
//
//  Both designs answer "which request was this response for?". The
//  interesting question is what each one's answer COSTS, and the cost is
//  concurrency: how many transactions can be in flight at once.
//
//  So the bench contains a FABRIC MODEL with a settable latency, issues
//  requests as fast as the tracker will take them, and measures how many
//  cycles it takes to retire a fixed number. Sweeping (tag_limit,
//  latency) gives a surface, and the tag_limit = 1 row of that surface IS
//  the USB behaviour -- because a USB host has exactly one transaction
//  outstanding per endpoint, by construction.
//
//  THE SHADOW MODEL IS FORMULATED IN THE OPPOSITE DIRECTION. The tracker
//  allocates by walking its tags DOWNWARDS so the lowest free index wins;
//  the model walks UPWARDS and stops at the first free one. Same answer,
//  different derivation.
// =====================================================================
`timescale 1ns/1ps
module tb_tg_sv;

  localparam int N_TAG = 8;
  localparam int N_EP  = 4;
  localparam int MAXF  = 64;   // fabric depth: in-flight completions

  logic clk = 1'b0, rst_n = 1'b0;
  always #5 clk = ~clk;

  // ---- PCIe side ----
  logic [3:0]  tag_limit = 4'd8;
  logic         req_valid = 1'b0, req_posted = 1'b0;
  logic [15:0] req_bytes = 16'd0;
  logic        req_ready, req_stall;
  logic [2:0]  req_tag;
  logic         cpl_valid = 1'b0;
  logic [2:0]  cpl_tag = 3'd0;
  logic [15:0] cpl_bytes = 16'd0;
  logic        cpl_retire;
  logic [31:0] n_alloc, n_posted, n_stall, n_retire, n_partial,
              n_bad_tag, n_over, n_outstanding;

  pcie_tag_tracker #(.N_TAG(N_TAG)) dut (
    .clk(clk), .rst_n(rst_n), .tag_limit(tag_limit),
    .req_valid(req_valid), .req_posted(req_posted), .req_bytes(req_bytes),
    .req_ready(req_ready), .req_tag(req_tag), .req_stall(req_stall),
    .cpl_valid(cpl_valid), .cpl_tag(cpl_tag), .cpl_bytes(cpl_bytes),
    .cpl_retire(cpl_retire),
    .n_alloc(n_alloc), .n_posted(n_posted), .n_stall(n_stall),
    .n_retire(n_retire), .n_partial(n_partial), .n_bad_tag(n_bad_tag),
    .n_over(n_over), .n_outstanding(n_outstanding)
  );

  // ---- USB side ----
  logic        iss_valid = 1'b0;
  logic [1:0] iss_ep = 2'd0;
  logic       iss_ready, iss_busy;
  logic        rsp_valid = 1'b0;
  logic [1:0] rsp_ep = 2'd0;
  logic       rsp_match, rsp_spurious;
  logic [31:0] u_n_issued, u_n_refused, u_n_answered, u_n_spurious, u_n_out;

  usb_xact_slot #(.N_EP(N_EP)) udut (
    .clk(clk), .rst_n(rst_n),
    .iss_valid(iss_valid), .iss_ep(iss_ep),
    .iss_ready(iss_ready), .iss_busy(iss_busy),
    .rsp_valid(rsp_valid), .rsp_ep(rsp_ep),
    .rsp_match(rsp_match), .rsp_spurious(rsp_spurious),
    .n_issued(u_n_issued), .n_refused(u_n_refused),
    .n_answered(u_n_answered), .n_spurious(u_n_spurious),
    .n_outstanding(u_n_out)
  );

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

  // ---- cumulative across resets ----
  //
  // The DUTs' own counters are zeroed by every reset_all, so reading them in
  // the final summary would report only whatever happened after the last
  // one. Per-step checks still use the DUT counters directly; these are for
  // the totals.
  int c_alloc = 0, c_posted = 0, c_stall = 0, c_retire = 0,
          c_partial = 0, c_bad = 0, c_over = 0;
  int c_iss = 0, c_ref = 0, c_ans = 0, c_spur = 0;

  // $random is SIGNED: mask the sign bit before any modulo.
  function automatic logic [31:0] urand();
    return $random(seed) & 32'h3FFF_FFFF;
  endfunction

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

  // ---- what the design said, sampled at a DEFINED instant ----
  //
  // cpl_retire is only meaningful while cpl_valid is asserted. A check
  // placed after do_cpl returns reads it after the deassert, where the
  // answer is a delta-cycle artefact -- which produced 4 failures against a
  // design that was entirely correct. Capture once, assert on the capture.
  logic obs_retire;

  // ---- the shadow tracker, maintained by the bench ----
  logic        m_busy [0:N_TAG-1];
  logic [15:0] m_rem  [0:N_TAG-1];
  logic        um_busy [0:N_EP-1];

  // Upward-and-stop, the opposite of the design's downward walk.
  function automatic logic m_free_any(input [3:0] lim);
    int j; logic f;
    begin
      f = 1'b0;
      for (j = 0; j < N_TAG; j = j + 1)
        if (!m_busy[j] && (j < lim) && !f) f = 1'b1;
      m_free_any = f;
    end
  endfunction

  function automatic logic [2:0] m_free_tag(input [3:0] lim);
    int j; logic f; logic [2:0] t;
    begin
      f = 1'b0; t = 3'd0;
      for (j = 0; j < N_TAG; j = j + 1)
        if (!m_busy[j] && (j < lim) && !f) begin t = j[2:0]; f = 1'b1; end
      m_free_tag = t;
    end
  endfunction

  function automatic logic [31:0] m_out(input logic dummy);
    int j; logic [31:0] c;
    begin
      c = 32'd0;
      for (j = 0; j < N_TAG; j = j + 1) if (m_busy[j]) c = c + 32'd1;
      m_out = c;
    end
  endfunction

  function automatic logic [31:0] um_out(input logic dummy);
    int j; logic [31:0] c;
    begin
      c = 32'd0;
      for (j = 0; j < N_EP; j = j + 1) if (um_busy[j]) c = c + 32'd1;
      um_out = c;
    end
  endfunction

  // ---- the fabric: completions in flight, each with a due cycle ----
  //
  // A model of the thing PCIe has and USB does not: a transport that holds
  // several requests at once and returns them WHENEVER, not in order.
  logic        f_act   [0:MAXF-1];
  logic [2:0]  f_tag   [0:MAXF-1];
  logic [15:0] f_bytes [0:MAXF-1];
  integer    f_due   [0:MAXF-1];
  int    now_c;

  task automatic fabric_clear;
    int j;
    begin
      for (j = 0; j < MAXF; j = j + 1) f_act[j] = 1'b0;
      now_c = 0;
    end
  endtask

  task automatic fabric_push(input [2:0] t, input [15:0] b, input integer due);
    int j; logic placed;
    begin
      placed = 1'b0;
      for (j = 0; j < MAXF; j = j + 1)
        if (!f_act[j] && !placed) begin
          f_act[j] = 1'b1; f_tag[j] = t; f_bytes[j] = b; f_due[j] = due;
          placed = 1'b1;
        end
      // A full fabric would silently drop a completion and the tag would
      // stay outstanding forever, which reads as a design hang. Bound it.
      ck(placed, "TEST BUG: the fabric model overflowed");
    end
  endtask

  // Pick the earliest-due active completion at or before `now`. Only ONE
  // per cycle, because completions are serialised on a real link.
  task automatic fabric_pop(input integer now, output found, output [2:0] t,
                  output [15:0] b);
    int j, best, bestdue;
    begin
      best = -1; bestdue = 0; found = 1'b0; t = 3'd0; b = 16'd0;
      for (j = 0; j < MAXF; j = j + 1)
        if (f_act[j] && (f_due[j] <= now))
          if ((best < 0) || (f_due[j] < bestdue)) begin
            best = j; bestdue = f_due[j];
          end
      if (best >= 0) begin
        found = 1'b1; t = f_tag[best]; b = f_bytes[best];
        f_act[best] = 1'b0;
      end
    end
  endtask

  // ---------------------------------------------------------------
  //  THE MEASUREMENT.
  //
  //  Issue K non-posted requests as fast as the tracker accepts them,
  //  against a fabric of fixed latency, and count the cycles until the
  //  last one retires. Everything about the result is decided by how many
  //  tags the requester is allowed to hold.
  // ---------------------------------------------------------------
  int K_XACT = 24;

  task automatic measure(input integer lim, input integer lat, output integer cycles);
    int issued, retired, guard;
    logic      pop_found;
    logic [2:0] pop_tag;
    logic [15:0] pop_bytes;
    logic [2:0]  got_tag;
    logic        pre_free;
    logic [2:0]  pre_tag;
    int j;
    begin
      // reset both the DUT and the model
      rst_n = 1'b0;
      req_valid = 1'b0; cpl_valid = 1'b0; req_posted = 1'b0;
      @(posedge clk); @(posedge clk);
      rst_n = 1'b1;
      @(posedge clk); #1;
      for (j = 0; j < N_TAG; j = j + 1) begin m_busy[j] = 1'b0; m_rem[j] = 16'd0; end
      fabric_clear;

      tag_limit = lim[3:0];
      issued = 0; retired = 0; guard = 0;

      // Every wait loop is bounded. An unbounded one turns a design hang
      // into a test that never finishes, which is strictly worse.
      while ((retired < K_XACT) && (guard < 20000)) begin
        // present at most one due completion
        fabric_pop(now_c, pop_found, pop_tag, pop_bytes);
        cpl_valid = pop_found;
        cpl_tag   = pop_tag;
        cpl_bytes = pop_bytes;

        // offer a request whenever there are any left
        req_valid  = (issued < K_XACT);
        req_posted = 1'b0;
        req_bytes  = 16'd64;

        #1;
        got_tag = req_tag;

        // The allocation decision is taken from the table as it stood at the
        // START of this cycle, because the design's free_any is
        // combinational over the REGISTERED tag array. A tag retired by the
        // completion being presented right now is not allocatable until next
        // cycle -- one cycle of turnaround per tag, which is why saturating
        // a fabric of latency L needs L+1 tags.
        //
        // Applying the completion to the model first, and only then judging
        // the allocation, made the model one cycle ahead of the design. The
        // sweep then hung at every point where latency was less than the tag
        // limit, and reported 20000 -- the guard value -- for 54 of its 64
        // cells. Ordering, not arithmetic.
        pre_free = m_free_any(lim[3:0]);
        pre_tag  = m_free_tag(lim[3:0]);

        // ---- PROPERTY 1: the tracker and the model pick the same tag ----
        if (req_valid && pre_free) begin
          ck(req_ready === 1'b1, "a request was refused while a tag was free");
          ck(got_tag === pre_tag, "the tracker allocated a different tag than the model");
        end else if (req_valid) begin
          // ---- PROPERTY 2: no free tag means a stall, not a silent drop ----
          ck(req_stall === 1'b1, "the tracker neither accepted nor stalled a request");
          ck(req_ready === 1'b0, "the tracker accepted a request with no tag free");
        end

        // ---- now advance the model, completions first, exactly as the
        //      design's clocked process does ----
        if (cpl_valid && m_busy[pop_tag]) begin
          if (pop_bytes >= m_rem[pop_tag]) begin
            m_busy[pop_tag] = 1'b0; m_rem[pop_tag] = 16'd0;
            retired = retired + 1;
          end else begin
            m_rem[pop_tag] = m_rem[pop_tag] - pop_bytes;
          end
        end
        if (req_valid && pre_free) begin
          m_busy[pre_tag] = 1'b1;
          m_rem[pre_tag]  = 16'd64;
          fabric_push(pre_tag, 16'd64, now_c + lat);
          issued = issued + 1;
        end

        @(posedge clk); #1;

        // ---- PROPERTY 3: outstanding count is exact, every cycle ----
        //
        // Checked AFTER the edge. Before it, the design's combinational
        // count still describes the previous cycle while the model has
        // already advanced -- comparing across that boundary produced 1122
        // failures against a design and a model that agreed perfectly.
        ck(n_outstanding === m_out(0),
           "the tracker and the model disagree about how many tags are in flight");

        now_c = now_c + 1;
        guard = guard + 1;
        steps = steps + 1;
      end
      req_valid = 1'b0; cpl_valid = 1'b0;
      ck(retired == K_XACT, "the measurement did not retire every transaction");
      cycles = now_c;
    end
  endtask

  // ---------------------------------------------------------------
  //  Single-step helpers for the directed phases.
  // ---------------------------------------------------------------
  task automatic do_req(input posted, input [15:0] bytes, output [2:0] tg,
              output accepted);
    begin
      req_valid = 1'b1; req_posted = posted; req_bytes = bytes;
      #1;
      tg = req_tag;
      accepted = req_ready;
      if (!posted) begin
        if (m_free_any(tag_limit)) begin
          ck(req_ready === 1'b1, "a request was refused while a tag was free");
          ck(req_tag === m_free_tag(tag_limit), "wrong tag allocated");
        end else begin
          ck(req_stall === 1'b1, "no stall was raised with every tag busy");
        end
      end else begin
        // ---- PROPERTY 4: a posted request never consumes a tag ----
        //
        // This is why a PCIe write is fast and a PCIe read is not: the
        // write is finished when it is sent.
        ck(req_ready === 1'b1, "a posted request was refused");
        ck(req_stall === 1'b0, "a posted request was stalled by tag exhaustion");
      end
      @(posedge clk); #1;
      req_valid = 1'b0;
      if (!posted && accepted) begin
        m_busy[tg] = 1'b1; m_rem[tg] = bytes;
        c_alloc = c_alloc + 1;
      end
      if (posted)                 c_posted = c_posted + 1;
      if (!posted && !accepted)   c_stall  = c_stall + 1;
      ck(n_outstanding === m_out(0), "outstanding count wrong after a request");
      steps = steps + 1;
    end
  endtask

  task automatic do_cpl(input [2:0] t, input [15:0] bytes);
    logic e_known, e_last, e_over;
    logic [31:0] r0, p0, b0, o0;
    begin
      e_known = m_busy[t];
      e_last  = e_known && (bytes >= m_rem[t]);
      e_over  = e_known && (bytes >  m_rem[t]);
      r0 = n_retire; p0 = n_partial; b0 = n_bad_tag; o0 = n_over;

      cpl_valid = 1'b1; cpl_tag = t; cpl_bytes = bytes;
      #1;
      obs_retire = cpl_retire;
      // ---- PROPERTY 5: retire means the LAST byte arrived ----
      //
      // A tag freed on a partial completion could be reused while the rest
      // of the data was still in flight, and the next transaction would
      // then collect it.
      ck(cpl_retire === e_last,
         "retire does not mean the request was completely satisfied");
      @(posedge clk); #1;
      cpl_valid = 1'b0;

      if (!e_known)      c_bad     = c_bad + 1;
      else if (e_last)   c_retire  = c_retire + 1;
      else               c_partial = c_partial + 1;
      if (e_over)        c_over    = c_over + 1;

      if (!e_known) begin
        // ---- PROPERTY 6: a completion for a free tag is reported ----
        ck(n_bad_tag == b0 + 32'd1, "a completion for an unowned tag was not reported");
        ck(n_retire == r0, "an unowned completion retired something");
      end else if (e_last) begin
        m_busy[t] = 1'b0; m_rem[t] = 16'd0;
        ck(n_retire == r0 + 32'd1, "a finishing completion did not retire");
        ck(n_over == o0 + (e_over ? 32'd1 : 32'd0), "overrun miscounted");
      end else begin
        m_rem[t] = m_rem[t] - bytes;
        // ---- PROPERTY 7: a partial completion keeps the tag ----
        ck(n_partial == p0 + 32'd1, "a partial completion was not counted");
        ck(n_retire == r0, "a partial completion retired the tag");
      end
      ck(n_outstanding === m_out(0), "outstanding count wrong after a completion");
      steps = steps + 1;
    end
  endtask

  task automatic reset_all;
    int j;
    begin
      rst_n = 1'b0;
      req_valid = 1'b0; cpl_valid = 1'b0; req_posted = 1'b0;
      iss_valid = 1'b0; rsp_valid = 1'b0;
      @(posedge clk); @(posedge clk);
      rst_n = 1'b1;
      @(posedge clk); #1;
      for (j = 0; j < N_TAG; j = j + 1) begin m_busy[j] = 1'b0; m_rem[j] = 16'd0; end
      for (j = 0; j < N_EP;  j = j + 1) um_busy[j] = 1'b0;
      tag_limit = 4'd8;
    end
  endtask

  // ---- the USB side ----
  task automatic do_iss(input [1:0] ep);
    logic e_busy;
    logic [31:0] i0, f0;
    begin
      e_busy = um_busy[ep];
      i0 = u_n_issued; f0 = u_n_refused;
      iss_valid = 1'b1; iss_ep = ep;
      #1;
      // ---- PROPERTY 8: one outstanding transaction per endpoint ----
      //
      // The entire mechanism. There is no second slot to have, which is
      // why no USB packet carries a transaction identifier.
      ck(iss_ready === !e_busy, "the slot accepted a second transaction on one endpoint");
      ck(iss_busy  ===  e_busy, "busy was not reported for an occupied endpoint");
      ck(!(iss_ready && iss_busy), "ready and busy were both asserted");
      @(posedge clk); #1;
      iss_valid = 1'b0;
      if (!e_busy) begin
        um_busy[ep] = 1'b1;
        c_iss = c_iss + 1;
        ck(u_n_issued == i0 + 32'd1, "an accepted transaction was not counted");
      end else begin
        c_ref = c_ref + 1;
        ck(u_n_refused == f0 + 32'd1, "a refused transaction was not counted");
      end
      ck(u_n_out === um_out(0), "usb outstanding count wrong after an issue");
      steps = steps + 1;
    end
  endtask

  task automatic do_rsp(input [1:0] ep);
    logic e_busy;
    logic [31:0] a0, s0;
    begin
      e_busy = um_busy[ep];
      a0 = u_n_answered; s0 = u_n_spurious;
      rsp_valid = 1'b1; rsp_ep = ep;
      #1;
      // ---- PROPERTY 9: a response with nothing outstanding is spurious ----
      //
      // Detectable precisely BECAUSE there is only one thing it could have
      // been answering. With N tags in flight the same question needs a
      // tag field to answer at all.
      ck(rsp_match    ===  e_busy, "a response was not matched to its transaction");
      ck(rsp_spurious === !e_busy, "an unsolicited response was not flagged");
      @(posedge clk); #1;
      rsp_valid = 1'b0;
      if (e_busy) begin
        um_busy[ep] = 1'b0;
        c_ans = c_ans + 1;
        ck(u_n_answered == a0 + 32'd1, "an answered transaction was not counted");
      end else begin
        c_spur = c_spur + 1;
        ck(u_n_spurious == s0 + 32'd1, "a spurious response was not counted");
      end
      ck(u_n_out === um_out(0), "usb outstanding count wrong after a response");
      steps = steps + 1;
    end
  endtask

  // ---- results ----
  integer thr_cyc [0:8][0:8];   // cycles for (limit, latency)
  int lim, lat, k, j, c;
  logic [2:0] tg;
  logic acc;
  logic [31:0] snap;

  // exhaustive reach over (tag_limit 1..8) x (latency 1..8) = 64
  logic reach [0:63];
  int nr, ri;
  // and over the directed tracker state space, below
  logic reach_t [0:255];
  int nrt;

  initial begin
    for (ri = 0; ri < 64;  ri = ri + 1) reach[ri]   = 1'b0;
    for (ri = 0; ri < 256; ri = ri + 1) reach_t[ri] = 1'b0;
    seed = 32'd28004;

    reset_all;

    // =============================================================
    //  PHASE 1 (DIRECTED, EXHAUSTIVE) -- THE THROUGHPUT SURFACE.
    //
    //  Every tag limit from 1 to 8 against every fabric latency from 1 to
    //  8: 64 points, all reachable, both dimensions independent inputs.
    //
    //  The tag_limit = 1 row is the USB case. A USB host has exactly one
    //  transaction outstanding per endpoint, so whatever that row says
    //  about throughput is what USB can do regardless of link speed.
    // =============================================================
    for (lim = 1; lim <= 8; lim = lim + 1)
    for (lat = 1; lat <= 8; lat = lat + 1) begin
      measure(lim, lat, c);
      thr_cyc[lim][lat] = c;
      reach[(lim - 1) * 8 + (lat - 1)] = 1'b1;
    end

    // ---- PROPERTY 10: more tags never make it slower ----
    //
    // Monotonicity in the tag count. Stated as a property rather than
    // eyeballed off the table, because a tracker that leaked tags would
    // produce a table that still looked plausible.
    for (lat = 1; lat <= 8; lat = lat + 1)
      for (lim = 2; lim <= 8; lim = lim + 1)
        ck(thr_cyc[lim][lat] <= thr_cyc[lim-1][lat],
           "adding a tag made the transfer slower");

    // ---- PROPERTY 11: more latency never makes it faster ----
    for (lim = 1; lim <= 8; lim = lim + 1)
      for (lat = 2; lat <= 8; lat = lat + 1)
        ck(thr_cyc[lim][lat] >= thr_cyc[lim][lat-1],
           "adding latency made the transfer faster");

    // ---- PROPERTY 12: one tag costs the full latency, EXACTLY ----
    //
    // THE USB RESULT, as a closed form rather than an observation. With one
    // outstanding transaction nothing overlaps, so each takes (latency + 1)
    // cycles -- latency to come back, one to issue the next -- and the total
    // is exactly K*(latency+1). No amount of link bandwidth changes it.
    //
    // Asserted with == rather than >=. An inequality would also pass for a
    // design that was slower still, and the point of a closed form is that
    // it pins the number from both sides.
    for (lat = 1; lat <= 8; lat = lat + 1)
      ck(thr_cyc[1][lat] == K_XACT * (lat + 1),
         "one outstanding transaction did not cost exactly latency+1 cycles each");

    // ---- PROPERTY 13: latency+1 tags saturate the link, EXACTLY ----
    //
    // The other closed form, and the one that answers "how many tags do I
    // need?". With L+1 tags the requester issues one per cycle and the only
    // cost left is draining the last one, so the total is exactly K + L.
    //
    // It is latency+1 and not latency because of the one-cycle tag
    // turnaround: free_any reads the REGISTERED tag array, so a tag retired
    // this cycle is allocatable next cycle. That single cycle is the
    // difference between needing L tags and needing L+1.
    for (lat = 1; lat <= 8; lat = lat + 1)
      for (lim = lat + 1; lim <= 8; lim = lim + 1)
        ck(thr_cyc[lim][lat] == K_XACT + lat,
           "latency+1 tags did not saturate the link");

    // ---- PROPERTY 14: fewer than latency+1 tags CANNOT saturate ----
    //
    // The negative half, without which the property above would be
    // satisfied by a design that was always saturated regardless of tags --
    // and the whole chapter would have no result.
    for (lat = 2; lat <= 8; lat = lat + 1)
      for (lim = 1; lim <= lat; lim = lim + 1)
        ck(thr_cyc[lim][lat] > K_XACT + lat,
           "fewer tags than latency+1 saturated the link anyway");

    // =============================================================
    //  PHASE 2 (DIRECTED) -- COMPLETIONS OUT OF ORDER.
    //
    //  The case USB cannot produce. Four tags are allocated in order and
    //  completed in REVERSE, and every one must retire correctly.
    // =============================================================
    reset_all;
    do_req(1'b0, 16'd64, tg, acc); ck(tg === 3'd0, "first tag should be 0");
    do_req(1'b0, 16'd64, tg, acc); ck(tg === 3'd1, "second tag should be 1");
    do_req(1'b0, 16'd64, tg, acc); ck(tg === 3'd2, "third tag should be 2");
    do_req(1'b0, 16'd64, tg, acc); ck(tg === 3'd3, "fourth tag should be 3");
    ck(n_outstanding === 32'd4, "four requests should leave four tags in flight");
    do_cpl(3'd3, 16'd64);
    do_cpl(3'd1, 16'd64);
    do_cpl(3'd2, 16'd64);
    do_cpl(3'd0, 16'd64);
    ck(n_outstanding === 32'd0, "completing every tag should empty the tracker");
    ck(n_retire === 32'd4, "four completions should retire four requests");
    ck(n_bad_tag === 32'd0, "out-of-order completion reported a bad tag");

    // =============================================================
    //  PHASE 3 (DIRECTED, EXHAUSTIVE over every completion order)
    //
    //  Three tags, all 3! = 6 completion orders. Out-of-order is not one
    //  case, it is every permutation, and a tracker that happened to work
    //  for reverse order is not thereby correct for the rest.
    // =============================================================
    for (k = 0; k < 6; k = k + 1) begin : perm
      int a, b2, c2, t0;
      reset_all;
      do_req(1'b0, 16'd64, tg, acc);
      do_req(1'b0, 16'd64, tg, acc);
      do_req(1'b0, 16'd64, tg, acc);
      // the six orderings of {0,1,2}
      case (k)
        0: begin a = 0; b2 = 1; c2 = 2; end
        1: begin a = 0; b2 = 2; c2 = 1; end
        2: begin a = 1; b2 = 0; c2 = 2; end
        3: begin a = 1; b2 = 2; c2 = 0; end
        4: begin a = 2; b2 = 0; c2 = 1; end
        default: begin a = 2; b2 = 1; c2 = 0; end
      endcase
      do_cpl(a[2:0],  16'd64);
      do_cpl(b2[2:0], 16'd64);
      do_cpl(c2[2:0], 16'd64);
      ck(n_outstanding === 32'd0, "some completion order left a tag outstanding");
      ck(n_retire === 32'd3, "some completion order lost a retirement");
      ck(n_bad_tag === 32'd0, "some completion order was mistaken for a bad tag");
    end

    // =============================================================
    //  PHASE 4 (DIRECTED, EXHAUSTIVE over split shapes) -- SPLIT
    //  COMPLETIONS.
    //
    //  One request may be answered by several completions. The tag must
    //  stay outstanding until the LAST byte arrives -- freeing it early is
    //  the tag-reuse bug, and it would attribute the remaining data to
    //  whatever transaction took the tag next.
    //
    //  Every split of 256 bytes into equal pieces of 256, 128, 64, 32 and
    //  16 is swept, which is every shape a power-of-two payload can take.
    // =============================================================
    for (k = 0; k < 5; k = k + 1) begin : splits
      int piece, pieces, n;
      reset_all;
      piece  = 256 >> k;
      pieces = 256 / piece;
      do_req(1'b0, 16'd256, tg, acc);
      for (n = 0; n < pieces; n = n + 1) begin
        do_cpl(tg, piece[15:0]);
        if (n < pieces - 1) begin
          // ---- PROPERTY 13: a partially completed tag stays busy ----
          ck(n_outstanding === 32'd1,
             "a tag was freed before its last completion arrived");
          ck(obs_retire === 1'b0, "a partial completion claimed to retire");
        end
      end
      ck(n_outstanding === 32'd0, "the tag was not freed by its last completion");
      ck(n_partial === (pieces - 1),
         "the number of partial completions does not match the split");
    end

    // =============================================================
    //  PHASE 5 (DIRECTED) -- TAG EXHAUSTION IS BACK-PRESSURE.
    //
    //  With two tags, a third request must STALL rather than be dropped or
    //  accepted. That stall is why PCIe read throughput depends on tag
    //  count, and it is the mechanism phase 1 measures.
    // =============================================================
    reset_all;
    tag_limit = 4'd2;
    do_req(1'b0, 16'd64, tg, acc); ck(acc === 1'b1, "first of two tags refused");
    do_req(1'b0, 16'd64, tg, acc); ck(acc === 1'b1, "second of two tags refused");
    snap = n_stall;
    do_req(1'b0, 16'd64, tg, acc);
    ck(acc === 1'b0, "a third request was accepted with only two tags");
    ck(n_stall == snap + 32'd1, "tag exhaustion did not raise a stall");
    ck(n_outstanding === 32'd2, "a stalled request consumed a tag anyway");
    // ---- PROPERTY 14: a POSTED request is never stalled ----
    //
    // Even with every tag busy. A write needs no completion, so tag
    // exhaustion cannot block it -- which is exactly why mixing posted and
    // non-posted traffic changes a PCIe link's behaviour so much.
    snap = n_posted;
    do_req(1'b1, 16'd64, tg, acc);
    ck(acc === 1'b1, "a posted request was blocked by tag exhaustion");
    ck(n_posted == snap + 32'd1, "a posted request was not counted");
    ck(n_outstanding === 32'd2, "a posted request consumed a tag");
    // and freeing one tag lets the next non-posted request through
    do_cpl(3'd0, 16'd64);
    do_req(1'b0, 16'd64, tg, acc);
    ck(acc === 1'b1, "freeing a tag did not admit the next request");
    ck(tg === 3'd0, "the freed tag was not the one reused");

    // =============================================================
    //  PHASE 5b (DIRECTED, EXHAUSTIVE over every tag limit)
    //
    //  The posted-request guarantee is only OBSERVABLE when no tag is free,
    //  because with a tag free a posted request would be accepted either way.
    //  So the table is filled to capacity at each of the eight limits and the
    //  guarantee is checked there.
    //
    //  That is the difference between a property being stated and being
    //  tested: phase 5 demonstrated it once, which gave the mutation that
    //  breaks it a domain of one.
    // =============================================================
    for (k = 1; k <= 8; k = k + 1) begin : postedsweep
      int b;
      logic [31:0] psnap, osnap2;
      reset_all;
      tag_limit = k[3:0];
      for (b = 0; b < k; b = b + 1) begin
        do_req(1'b0, 16'd64, tg, acc);
        ck(acc === 1'b1, "a request was refused below the tag limit");
      end
      ck(n_outstanding === k, "filling to the limit did not use every tag");

      // a non-posted request must now stall
      do_req(1'b0, 16'd64, tg, acc);
      ck(acc === 1'b0, "a request was accepted above the tag limit");

      // ---- and a POSTED request must NOT ----
      //
      // This is why a PCIe write never blocks on read credit: it needs no
      // completion, so tag exhaustion cannot apply to it. A design that made
      // writes wait for tags would serialise a workload PCIe is specifically
      // built to overlap.
      psnap = n_posted; osnap2 = n_outstanding;
      do_req(1'b1, 16'd64, tg, acc);
      ck(acc === 1'b1, "a posted request was blocked by tag exhaustion");
      ck(n_posted == psnap + 32'd1, "a posted request was not counted");
      ck(n_outstanding === osnap2, "a posted request consumed a tag");
    end

    // =============================================================
    //  PHASE 6 (DIRECTED) -- MALFORMED COMPLETIONS.
    //
    //  A completion for a tag nobody owns, and a completion carrying more
    //  bytes than were asked for. Both are protocol errors and both must
    //  be REPORTED rather than absorbed -- an absorbed overrun would wrap
    //  the byte counter and leave the tag outstanding forever, turning a
    //  protocol error into a hang.
    // =============================================================
    reset_all;
    snap = n_bad_tag;
    do_cpl(3'd5, 16'd64);        // nobody owns tag 5
    ck(n_bad_tag == snap + 32'd1, "a completion for a free tag was accepted");
    ck(n_outstanding === 32'd0, "an unowned completion changed the tracker state");

    do_req(1'b0, 16'd64, tg, acc);
    snap = n_over;
    do_cpl(tg, 16'd128);         // twice what was asked for
    ck(n_over == snap + 32'd1, "an over-long completion was not reported");
    ck(n_outstanding === 32'd0, "an over-long completion left the tag outstanding");

    // =============================================================
    //  PHASE 6b (DIRECTED, EXHAUSTIVE over overrun shapes)
    //
    //  A completion carrying more bytes than were requested, for every
    //  request size and both interesting overrun amounts: one byte too many,
    //  and twice as many as asked for. Eight cases rather than the single
    //  one phase 6 had, because a mutation that stops reporting overruns
    //  should not be able to score 2.
    //
    //  In every case the tag must still RETIRE. Absorbing the overrun by
    //  wrapping the byte counter would leave the tag outstanding forever and
    //  turn a protocol error into a hang, which is strictly worse.
    // =============================================================
    for (k = 0; k < 8; k = k + 1) begin : overruns
      int want, extra;
      logic [31:0] osnap;
      reset_all;
      want  = 16 << (k % 4);
      extra = (k < 4) ? 1 : want;      // one byte too many, or double
      do_req(1'b0, want[15:0], tg, acc);
      osnap = n_over;
      do_cpl(tg, (want + extra));
      ck(n_over == osnap + 32'd1, "an over-long completion was not reported");
      ck(n_outstanding === 32'd0,
         "an over-long completion left the tag outstanding");
      ck(n_retire > 32'd0, "an over-long completion did not retire the tag");
    end

    // =============================================================
    //  PHASE 7 (DIRECTED, EXHAUSTIVE over the tracker's busy-mask)
    //
    //  Every one of the 2**8 = 256 combinations of which tags are busy,
    //  reached by allocating and completing rather than by forcing state.
    //  For each, the allocation decision is checked against the model.
    // =============================================================
    for (k = 0; k < 256; k = k + 1) begin : masks
      int b;
      reset_all;
      // allocate all eight, then complete the ones the mask says are free
      for (b = 0; b < 8; b = b + 1) do_req(1'b0, 16'd64, tg, acc);
      ck(n_outstanding === 32'd8, "eight requests did not fill eight tags");
      for (b = 0; b < 8; b = b + 1)
        if (!k[b]) do_cpl(b[2:0], 16'd64);
      // ---- a POSTED request, against every table state ----
      //
      // It must be accepted and must consume no tag, whatever else is in
      // flight -- including when every tag is busy. Swept here rather than
      // demonstrated once, because a property exercised a single time has a
      // mutation domain of one and tells you almost nothing.
      snap = n_outstanding;
      do_req(1'b1, 16'd64, tg, acc);
      ck(acc === 1'b1, "a posted request was refused");
      ck(n_outstanding === snap, "a posted request consumed a tag");

      // ---- a completion for a tag NOBODY OWNS, against every state ----
      //
      // Whichever tag is free, a completion for it is a protocol error and
      // must be reported rather than absorbed. With a full table this case
      // does not exist, so it is skipped rather than faked.
      if (m_free_any(4'd8)) begin : badcpl
        logic [2:0] ft;
        logic [31:0] bsnap, osnap;
        ft = m_free_tag(4'd8);
        bsnap = n_bad_tag; osnap = n_outstanding;
        do_cpl(ft, 16'd64);
        ck(n_bad_tag == bsnap + 32'd1,
           "a completion for an unowned tag was not reported");
        ck(n_outstanding === osnap,
           "a completion for an unowned tag changed the tracker state");
      end

      // Now exactly the tags set in k are busy. The next allocation must
      // pick the lowest free one, which the model computes independently.
      if (m_free_any(4'd8)) begin
        do_req(1'b0, 16'd64, tg, acc);
        ck(acc === 1'b1, "a request was refused with a free tag");
      end else begin
        do_req(1'b0, 16'd64, tg, acc);
        ck(acc === 1'b0, "a request was accepted with every tag busy");
      end
      reach_t[k] = 1'b1;
    end

    // =============================================================
    //  PHASE 8 (DIRECTED) -- THE USB SLOT.
    //
    //  One outstanding transaction per endpoint. The endpoints are
    //  independent, a second issue to a busy endpoint is refused, and a
    //  response with nothing outstanding is flagged.
    // =============================================================
    reset_all;
    for (k = 0; k < 4; k = k + 1) begin
      do_iss(k[1:0]);
      ck(u_n_out === (k + 1), "each endpoint should hold one transaction");
    end
    // every endpoint busy: a second issue to each must be refused
    for (k = 0; k < 4; k = k + 1) do_iss(k[1:0]);
    ck(u_n_refused === 32'd4, "four second-issues should all be refused");
    ck(u_n_out === 32'd4, "a refused issue changed the outstanding count");
    // answer them all
    for (k = 0; k < 4; k = k + 1) do_rsp(k[1:0]);
    ck(u_n_out === 32'd0, "answering every endpoint should empty the slots");
    // an unsolicited response
    snap = u_n_spurious;
    do_rsp(2'd2);
    ck(u_n_spurious == snap + 32'd1, "an unsolicited response was not flagged");

    // =============================================================
    //  PHASE 9 (DIRECTED, EXHAUSTIVE over the endpoint busy-mask)
    //
    //  All 2**4 = 16 combinations of which endpoints are busy, crossed
    //  with an issue and a response to each of the 4 endpoints. 16 x 4 x 2
    //  decisions, every one checked against the model.
    // =============================================================
    for (k = 0; k < 16; k = k + 1) begin : epmask
      int b;
      reset_all;
      for (b = 0; b < 4; b = b + 1) if (k[b]) do_iss(b[1:0]);
      for (b = 0; b < 4; b = b + 1) do_iss(b[1:0]);
      reset_all;
      for (b = 0; b < 4; b = b + 1) if (k[b]) do_iss(b[1:0]);
      for (b = 0; b < 4; b = b + 1) do_rsp(b[1:0]);
    end

    // =============================================================
    //  PHASE 10 (RANDOM) -- mixed traffic with a reordering fabric.
    // =============================================================
`ifndef DIRECTED_ONLY
    reset_all;
    fabric_clear;
    for (k = 0; k < 800; k = k + 1) begin : rnd
      logic pf; reg [2:0] pt; reg [15:0] pb;
      // a due completion, if any
      fabric_pop(now_c, pf, pt, pb);
      if (pf) do_cpl(pt, pb);
      // a request, sometimes posted
      if ((urand() % 3) != 0) begin
        if ((urand() % 5) == 0) begin
          do_req(1'b1, 16'd64, tg, acc);
        end else begin
          do_req(1'b0, 16'd64, tg, acc);
          // A random latency, so completions come back out of order --
          // which is the property the whole tracker exists for.
          if (acc) fabric_push(tg, 16'd64, now_c + 1 + (urand() % 9));
        end
      end
      // and some USB traffic on the side
      if ((urand() % 2) == 0) do_iss((urand() % 4));
      else                     do_rsp((urand() % 4));
      now_c = now_c + 1;
    end
    // drain whatever is still in flight, bounded
    for (k = 0; k < 400; k = k + 1) begin : drain
      logic pf2; reg [2:0] pt2; reg [15:0] pb2;
      fabric_pop(now_c + 100, pf2, pt2, pb2);
      if (pf2) do_cpl(pt2, pb2);
      now_c = now_c + 1;
    end
`endif

    nr = 0;  for (ri = 0; ri < 64;  ri = ri + 1) if (reach[ri])   nr  = nr + 1;
    nrt = 0; for (ri = 0; ri < 256; ri = ri + 1) if (reach_t[ri]) nrt = nrt + 1;

    $display("steps=%0d checks=%0d reach_thr=%0d/64 reach_tag=%0d/256 errors=%0d",
             steps, checks, nr, nrt, errors);
    $display("[pcie] alloc=%0d posted=%0d stalls=%0d retire=%0d partial=%0d bad_tag=%0d over=%0d",
             c_alloc, c_posted, c_stall, c_retire, c_partial, c_bad, c_over);
    $display("[usb]  issued=%0d refused=%0d answered=%0d spurious=%0d",
             c_iss, c_ref, c_ans, c_spur);
    $display("--- cycles to move %0d transactions, by tags outstanding x latency ---", K_XACT);
    $display("    tags      L=1     L=2     L=3     L=4     L=5     L=6     L=7     L=8");
    for (lim = 1; lim <= 8; lim = lim + 1)
      $display("    %4d %8d%8d%8d%8d%8d%8d%8d%8d", lim,
               thr_cyc[lim][1], thr_cyc[lim][2], thr_cyc[lim][3], thr_cyc[lim][4],
               thr_cyc[lim][5], thr_cyc[lim][6], thr_cyc[lim][7], thr_cyc[lim][8]);
    $display("    (row tags=1 IS the USB case: one transaction outstanding)");
    if (nr != 64 || nrt != 256) 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