USB Flash Drives

    CBW    31 bytes OUT   "here is a command, and here is how many bytes
                           I expect to move, in this direction"

    DATA   0..N bytes     the payload, if there is one

    CSW    13 bytes IN    "it worked / it did not, and I moved this many
                           fewer bytes than you asked for"

// =====================================================================
//  msc_bot_fsm -- Bulk-Only Transport, the protocol every USB flash
//  drive on earth actually speaks.
//
//  CLASSIFICATION: simplified synthesisable teaching RTL.
//  This is NOT a mass-storage device. There is no SCSI command decoder,
//  no media, no FIFO and no error recovery beyond what the transport
//  itself defines. It is the TRANSPORT: the wrapper around every
//  command, and the arithmetic that decides what the host is told.
//
//  WHY THIS MECHANISM IS WORTH RTL
//  -------------------------------
//  A flash drive is three bulk transfers in a loop:
//
//      CBW   31 bytes OUT   "here is a command, and here is how many
//                            bytes I expect to move, in this direction"
//      DATA  0..N bytes     the payload, if any
//      CSW   13 bytes IN    "it worked / it did not, and I moved this
//                            many fewer bytes than you asked for"
//
//  The interesting part is the third line. The host states an
//  expectation in the CBW -- dCBWDataTransferLength and the direction
//  bit -- BEFORE the device has looked at the command. The device then
//  discovers what it actually wants to do. Those two can disagree, in
//  both length and direction, and the transport has to resolve every
//  combination without ever leaving the host and device out of step.
//
//  The BOT specification enumerates exactly THIRTEEN cases of that
//  disagreement. They are not a style guide; they are the contract, and
//  an implementation that gets case 7 wrong works perfectly against
//  every well-behaved host until somebody issues a command whose real
//  length exceeds what the host allocated -- and then the two ends
//  disagree about how many bytes are on the wire, which no amount of
//  retrying fixes.
//
//  That is why this is the mechanism worth building: it is a small,
//  completely enumerable decision table where a single wrong cell is
//  invisible in normal use and unrecoverable when it fires.
// =====================================================================
module msc_bot_fsm (
  input  wire        clk,
  input  wire        rst_n,

  // ---- the Command Block Wrapper, 31 bytes OUT ----
  input  wire        cbw_valid,
  input  wire [31:0] cbw_tag,       // dCBWTag: MUST come back in the CSW
  input  wire [31:0] cbw_len,       // dCBWDataTransferLength: the host's expectation
  input  wire        cbw_dir_in,    // bmCBWFlags bit 7: 1 = device-to-host
  input  wire        cbw_sig_ok,    // dCBWSignature == 'USBC'
  input  wire        cbw_cb_ok,     // bCBWCBLength in 1..16

  // ---- what the command layer says it will actually do ----
  //
  // Available only AFTER the CBW has been parsed, which is exactly why
  // the disagreement below is possible at all.
  input  wire        dev_none,      // this command moves no data
  input  wire        dev_dir_in,    // direction the device wants
  input  wire [31:0] dev_len,       // bytes the device will actually move
  input  wire        dev_fail,      // the command itself failed

  // ---- the Command Status Wrapper, 13 bytes IN ----
  output wire        csw_valid,
  output wire [31:0] csw_tag,       // echoed, always
  output wire [31:0] csw_residue,   // dCSWDataResidue = expected - actual
  output wire [1:0]  csw_status,    // 00 pass, 01 fail, 10 phase error

  // ---- what the endpoints are told to do ----
  output wire        stall_in,
  output wire        stall_out,
  output wire        need_reset,    // invalid CBW: wait for Reset Recovery

  output wire [2:0]  state,
  output wire [31:0] n_cbw,
  output wire [31:0] n_pass,
  output wire [31:0] n_fail,
  output wire [31:0] n_phase,
  output wire [31:0] n_stall,
  output wire [31:0] n_invalid
);

  localparam [1:0] ST_PASS  = 2'd0,
                   ST_FAIL  = 2'd1,
                   ST_PHASE = 2'd2;

  localparam [2:0] S_IDLE = 3'd0,   // waiting for a CBW
                   S_DATA = 3'd1,   // moving the data phase
                   S_CSW  = 3'd2,   // presenting the status
                   S_WEDGE = 3'd3;  // invalid CBW: both endpoints stalled

  // -------------------------------------------------------------------
  //  The host's stated expectation, as the spec's three kinds.
  // -------------------------------------------------------------------
  wire h_none = (cbw_len == 32'd0);
  wire h_in   = !h_none &&  cbw_dir_in;
  wire h_out  = !h_none && !cbw_dir_in;

  // The device's intent. dev_dir_in and dev_len are IGNORED when the
  // command moves no data -- a device that let a stale length leak into
  // a no-data command would report a residue for bytes that were never
  // going to move.
  wire d_none = dev_none;
  wire d_in   = !d_none &&  dev_dir_in;
  wire d_out  = !d_none && !dev_dir_in;
  // dev_len is read only through d_in / d_out below, both of which are
  // false when the command moves no data -- so no zeroing guard is needed
  // here, and adding one would be dead code. The bench asserts that
  // invariant rather than the design defending against it.
  wire [31:0] d_len = dev_len;

  // -------------------------------------------------------------------
  //  THE THIRTEEN CASES.
  //
  //  Direction disagreement is always fatal: cases 8 and 13. So is the
  //  host under-allocating, cases 2, 3, 7 and 12 -- there is no way to
  //  move more bytes than the host set aside, and no way to tell it so
  //  except by declaring the phase lost.
  //
  //  Everything else is survivable, and the residue carries the
  //  shortfall.
  // -------------------------------------------------------------------
  wire dir_clash = (h_in && d_out) || (h_out && d_in);          // 8, 13
  wire host_short = (h_none && !d_none)                         // 2, 3
                 || (h_in  && d_in  && (cbw_len < d_len))       // 7
                 || (h_out && d_out && (cbw_len < d_len));      // 12

  wire phase_err = dir_clash || host_short;

  // Bytes the transport will actually move.
  //
  // NO CLAMP TO cbw_len IS NEEDED, and that is worth stating because the
  // clamp is the obvious thing to write. Every situation in which the
  // device wants more bytes than the host allocated is ALREADY a phase
  // error: same-direction under-allocation is caught by host_short
  // (cases 7 and 12) and opposite-direction by dir_clash (cases 8 and 13).
  // So on any path that reaches this expression, d_len <= cbw_len holds.
  //
  // A clamp here would be unreachable code -- it was in the first version
  // of this file, and the mutation that broke it scored exactly ZERO,
  // which is how it was found. The invariant is asserted in the bench
  // instead, where a violation would be visible.
  //
  // There is no phase-error guard here either, for the same reason: both
  // consumers below (`residue` and the two short-data tests) already
  // exclude the phase-error case themselves. Guarding it a second time
  // scored zero as well. Two dead guards, both found by mutations that
  // refused to die, and both deleted rather than explained away.
  wire [31:0] moved = d_none ? 32'd0 : d_len;

  // dCSWDataResidue. On a phase error the field is defined but
  // meaningless to the host, which is about to reset the interface
  // anyway; it is reported as the full expectation so a trace reads
  // sensibly.
  wire [31:0] residue = phase_err ? cbw_len : (cbw_len - moved);

  // Cases 4 and 9: the host allocated a data phase and the device has
  // nothing to put in it. The transport must terminate that phase
  // rather than leave the host waiting, and a STALL is how BOT says so.
  wire short_in  = h_in  && !phase_err && (moved < cbw_len);
  wire short_out = h_out && !phase_err && (moved < cbw_len);

  // -------------------------------------------------------------------
  //  CBW validity. A CBW that is not 31 bytes, lacks the signature, or
  //  carries an out-of-range command length is not a CBW at all: the
  //  device stalls BOTH endpoints and waits for Reset Recovery. It must
  //  NOT answer with a CSW, because a CSW would imply it understood a
  //  command it did not.
  // -------------------------------------------------------------------
  wire cbw_ok = cbw_sig_ok && cbw_cb_ok;

  reg [2:0]  st;
  reg [31:0] tag_r, res_r;
  reg [1:0]  sts_r;
  reg        csw_r, sin_r, sout_r, wedge_r;

  reg [31:0] cbw_c, pass_c, fail_c, phase_c, stall_c, inval_c;

  assign state       = st;
  assign csw_valid   = csw_r;
  assign csw_tag     = tag_r;
  assign csw_residue = res_r;
  assign csw_status  = sts_r;
  assign stall_in    = sin_r;
  assign stall_out   = sout_r;
  assign need_reset  = wedge_r;
  assign n_cbw       = cbw_c;
  assign n_pass      = pass_c;
  assign n_fail      = fail_c;
  assign n_phase     = phase_c;
  assign n_stall     = stall_c;
  assign n_invalid   = inval_c;

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      st      <= S_IDLE;
      tag_r   <= 32'd0;
      res_r   <= 32'd0;
      sts_r   <= ST_PASS;
      csw_r   <= 1'b0;
      sin_r   <= 1'b0;
      sout_r  <= 1'b0;
      wedge_r <= 1'b0;
      cbw_c   <= 32'd0;
      pass_c  <= 32'd0;
      fail_c  <= 32'd0;
      phase_c <= 32'd0;
      stall_c <= 32'd0;
      inval_c <= 32'd0;
    end else begin
      csw_r  <= 1'b0;
      sin_r  <= 1'b0;
      sout_r <= 1'b0;

      case (st)
        S_IDLE: begin
          if (cbw_valid) begin
            cbw_c <= cbw_c + 32'd1;
            if (!cbw_ok) begin
              // Not a CBW. Stall both ways and wedge until Reset
              // Recovery -- answering anything else would be inventing
              // a reply to a command that was never received.
              st      <= S_WEDGE;
              wedge_r <= 1'b1;
              sin_r   <= 1'b1;
              sout_r  <= 1'b1;
              inval_c <= inval_c + 32'd1;
            end else begin
              // THE TAG IS CAPTURED HERE, from the CBW, and echoed
              // unchanged. A device that regenerates it, or echoes the
              // previous one, breaks every host's command queue.
              tag_r <= cbw_tag;
              res_r <= residue;
              sts_r <= phase_err ? ST_PHASE : (dev_fail ? ST_FAIL : ST_PASS);

              if (phase_err) begin
                phase_c <= phase_c + 32'd1;
                // A phase error stalls the direction the host was
                // waiting on, so the host stops waiting and comes to
                // read the CSW.
                if (h_in)  sin_r  <= 1'b1;
                if (h_out) sout_r <= 1'b1;
                if (h_in || h_out) stall_c <= stall_c + 32'd1;
                st <= S_CSW;
              end else begin
                if (dev_fail) fail_c <= fail_c + 32'd1;
                else          pass_c <= pass_c + 32'd1;
                // Cases 4 and 9: terminate a data phase the device
                // cannot fill.
                if (short_in)  begin sin_r  <= 1'b1; stall_c <= stall_c + 32'd1; end
                if (short_out) begin sout_r <= 1'b1; stall_c <= stall_c + 32'd1; end
                st <= (h_none && d_none) ? S_CSW : S_DATA;
              end
            end
          end
        end

        // The data phase itself is not modelled byte by byte; what the
        // transport owes the host is the LENGTH decision above, and that
        // is already fixed.
        S_DATA: st <= S_CSW;

        S_CSW: begin
          csw_r <= 1'b1;
          st    <= S_IDLE;
        end

        // Wedged. Only a reset gets out, which is what Reset Recovery
        // means: the host has to clear both stalls and start again.
        S_WEDGE: begin
          sin_r  <= 1'b1;
          sout_r <= 1'b1;
        end

        default: st <= S_IDLE;
      endcase
    end
  end

endmodule

// =====================================================================
//  Testbench for msc_bot_fsm.
//
//  THE MODEL IS THE SPEC'S TABLE, NOT THE DESIGN'S BOOLEANS.
//
//  The design decides with two expressions -- `dir_clash` and
//  `host_short` -- and derives everything from them. The model does the
//  opposite: it classifies the situation into one of the thirteen NAMED
//  cases the Bulk-Only Transport specification enumerates, and then
//  looks the answer up in a table written straight from that document.
//
//  Two different derivations of the same contract. A boolean the design
//  got subtly wrong cannot be got wrong the same way by a lookup keyed
//  on a case number, which is the entire reason for writing it this way
//  rather than more carefully.
//
//  Every valid-gated output is captured at a DEFINED instant. The stall
//  decision is only meaningful in the cycle the CBW is consumed; reading
//  it later reads a scheduling artefact.
// =====================================================================
`timescale 1ns/1ps
module tb_bt_v;

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

  reg         cbw_valid = 1'b0;
  reg  [31:0] cbw_tag = 32'd0, cbw_len = 32'd0;
  reg         cbw_dir_in = 1'b0, cbw_sig_ok = 1'b1, cbw_cb_ok = 1'b1;
  reg         dev_none = 1'b0, dev_dir_in = 1'b0, dev_fail = 1'b0;
  reg  [31:0] dev_len = 32'd0;

  wire        csw_valid, stall_in, stall_out, need_reset;
  wire [31:0] csw_tag, csw_residue;
  wire [1:0]  csw_status;
  wire [2:0]  state;
  wire [31:0] n_cbw, n_pass, n_fail, n_phase, n_stall, n_invalid;

  msc_bot_fsm dut (
    .clk(clk), .rst_n(rst_n),
    .cbw_valid(cbw_valid), .cbw_tag(cbw_tag), .cbw_len(cbw_len),
    .cbw_dir_in(cbw_dir_in), .cbw_sig_ok(cbw_sig_ok), .cbw_cb_ok(cbw_cb_ok),
    .dev_none(dev_none), .dev_dir_in(dev_dir_in), .dev_len(dev_len),
    .dev_fail(dev_fail),
    .csw_valid(csw_valid), .csw_tag(csw_tag), .csw_residue(csw_residue),
    .csw_status(csw_status),
    .stall_in(stall_in), .stall_out(stall_out), .need_reset(need_reset),
    .state(state),
    .n_cbw(n_cbw), .n_pass(n_pass), .n_fail(n_fail), .n_phase(n_phase),
    .n_stall(n_stall), .n_invalid(n_invalid)
  );

  localparam [1:0] ST_PASS = 2'd0, ST_FAIL = 2'd1, ST_PHASE = 2'd2;

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

  // ---- cumulative across resets ----
  //
  // Every reset_dut zeroes the DUT's own counters, so a summary that read
  // them directly would report only whatever happened after the last one.
  // Per-step checks still use the DUT counters; these are for the totals.
  integer c_cbw = 0, c_pass = 0, c_fail = 0, c_phase = 0,
          c_stall = 0, c_invalid = 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 ----
  reg        obs_sin, obs_sout, obs_wedge, obs_csw;
  reg [31:0] obs_tag, obs_res;
  reg [1:0]  obs_sts;

  // ---- how many times each of the thirteen cases was exercised ----
  integer case_hits [1:13];

  // -------------------------------------------------------------------
  //  THE MODEL: classify into the spec's thirteen cases.
  //
  //  h: 0 = Hn (no data), 1 = Hi (device-to-host), 2 = Ho (host-to-device)
  //  d: 0 = Dn (no data), 1 = Di (device-to-host), 2 = Do (host-to-device)
  // -------------------------------------------------------------------
  function [4:0] spec_case(input [1:0] h, input [1:0] d,
                           input [31:0] hl, input [31:0] dl);
    begin
      if      (h == 2'd0 && d == 2'd0)                spec_case = 5'd1;
      else if (h == 2'd0 && d == 2'd1)                spec_case = 5'd2;
      else if (h == 2'd0 && d == 2'd2)                spec_case = 5'd3;
      else if (h == 2'd1 && d == 2'd0)                spec_case = 5'd4;
      else if (h == 2'd1 && d == 2'd1 && hl >  dl)    spec_case = 5'd5;
      else if (h == 2'd1 && d == 2'd1 && hl == dl)    spec_case = 5'd6;
      else if (h == 2'd1 && d == 2'd1 && hl <  dl)    spec_case = 5'd7;
      else if (h == 2'd1 && d == 2'd2)                spec_case = 5'd8;
      else if (h == 2'd2 && d == 2'd0)                spec_case = 5'd9;
      else if (h == 2'd2 && d == 2'd2 && hl >  dl)    spec_case = 5'd10;
      else if (h == 2'd2 && d == 2'd2 && hl == dl)    spec_case = 5'd11;
      else if (h == 2'd2 && d == 2'd2 && hl <  dl)    spec_case = 5'd12;
      else                                            spec_case = 5'd13;
    end
  endfunction

  // Which cases are a phase error, straight from the specification.
  // Written as a set membership rather than as a condition, so it cannot
  // share an algebraic mistake with the design.
  function is_phase(input [4:0] c);
    begin
      is_phase = (c == 5'd2)  || (c == 5'd3)  || (c == 5'd7) ||
                 (c == 5'd8)  || (c == 5'd12) || (c == 5'd13);
    end
  endfunction

  // -------------------------------------------------------------------
  //  Drive one CBW and check everything the transport owes the host.
  // -------------------------------------------------------------------
  task run_cbw(input [31:0] tag, input [31:0] hlen, input hdir,
               input dnone, input ddir, input [31:0] dlen,
               input dfail, input sig_ok, input cb_ok);
    reg [1:0]  h, d;
    reg [4:0]  c;
    reg        e_phase, e_sin, e_sout;
    reg [31:0] e_moved, e_res;
    reg [1:0]  e_sts;
    reg [31:0] p0, f0, ph0, i0;
    integer    g;
    begin
      // classify, from the inputs only
      h = (hlen == 32'd0) ? 2'd0 : (hdir ? 2'd1 : 2'd2);
      d = dnone           ? 2'd0 : (ddir ? 2'd1 : 2'd2);
      c = spec_case(h, d, hlen, dnone ? 32'd0 : dlen);
      e_phase = is_phase(c);

      // the expected answer, from the case number
      e_moved = e_phase ? 32'd0
              : (d == 2'd0) ? 32'd0
              : ((dlen > hlen) ? hlen : dlen);
      e_res   = e_phase ? hlen : (hlen - e_moved);
      e_sts   = e_phase ? ST_PHASE : (dfail ? ST_FAIL : ST_PASS);
      // A short or absent data phase must be terminated on the side the
      // host is waiting on; a phase error stalls that side too.
      e_sin   = e_phase ? (h == 2'd1) : ((h == 2'd1) && (e_moved < hlen));
      e_sout  = e_phase ? (h == 2'd2) : ((h == 2'd2) && (e_moved < hlen));

      p0 = n_pass; f0 = n_fail; ph0 = n_phase; i0 = n_invalid;

      cbw_valid  = 1'b1;  cbw_tag = tag; cbw_len = hlen; cbw_dir_in = hdir;
      cbw_sig_ok = sig_ok; cbw_cb_ok = cb_ok;
      dev_none   = dnone; dev_dir_in = ddir; dev_len = dlen; dev_fail = dfail;

      @(posedge clk); #1;
      // ---- captured at the instant the CBW is consumed ----
      obs_sin   = stall_in;
      obs_sout  = stall_out;
      obs_wedge = need_reset;
      cbw_valid = 1'b0;

      if (!(sig_ok && cb_ok)) begin
        // ---- PROPERTY 1: an invalid CBW is not answered ----
        //
        // The device must stall both endpoints and wait for Reset
        // Recovery. Replying with a CSW would tell the host the command
        // was understood, and the host would believe it.
        ck(obs_sin && obs_sout,
           "an invalid CBW did not stall both endpoints");
        ck(obs_wedge, "an invalid CBW did not request reset recovery");
        ck(n_invalid == i0 + 32'd1, "an invalid CBW was not counted");
        c_cbw = c_cbw + 1; c_invalid = c_invalid + 1;
        // and no CSW, ever -- checked over a bounded window
        obs_csw = 1'b0;
        for (g = 0; g < 8; g = g + 1) begin
          @(posedge clk); #1;
          if (csw_valid) obs_csw = 1'b1;
        end
        ck(!obs_csw, "an invalid CBW was answered with a CSW");
        ck(n_pass == p0 && n_fail == f0 && n_phase == ph0,
           "an invalid CBW moved a status counter");
        // reset out of the wedge, which is what Reset Recovery does
        rst_n = 1'b0; @(posedge clk); @(posedge clk); rst_n = 1'b1;
        @(posedge clk); #1;
        steps = steps + 1;
      end else begin
        case_hits[c] = case_hits[c] + 1;
        c_cbw = c_cbw + 1;
        if (e_sts == ST_PHASE) c_phase = c_phase + 1;
        else if (e_sts == ST_FAIL) c_fail = c_fail + 1;
        else c_pass = c_pass + 1;
        if (e_sin)  c_stall = c_stall + 1;
        if (e_sout) c_stall = c_stall + 1;

        // ---- PROPERTY 2a: the invariants the design RELIES on ----
        //
        // The design carries no clamp and no zeroing guard, because two
        // invariants make both unnecessary. Relying on an invariant is
        // fine; relying on one nobody checks is not, so they are checked
        // here -- and a violation would be a bench bug before it was a
        // design bug.
        if (!e_phase && d != 2'd0)
          ck(dlen <= hlen,
             "INVARIANT: a non-phase-error transfer wants more than the host allocated");
        if (dnone)
          ck(e_moved == 32'd0,
             "INVARIANT: a no-data command moved a non-zero number of bytes");

        // ---- PROPERTY 2: the stall decision matches the case ----
        ck(obs_sin  === e_sin,  "stall_in disagrees with the spec case");
        ck(obs_sout === e_sout, "stall_out disagrees with the spec case");
        ck(!obs_wedge, "a valid CBW requested reset recovery");

        // ---- wait, bounded, for the CSW ----
        obs_csw = 1'b0;
        for (g = 0; g < 8 && !obs_csw; g = g + 1) begin
          @(posedge clk); #1;
          if (csw_valid) begin
            obs_csw = 1'b1;
            obs_tag = csw_tag;
            obs_res = csw_residue;
            obs_sts = csw_status;
          end
        end
        // ---- PROPERTY 3: exactly one CSW per valid CBW ----
        //
        // Silence would hang the host forever: it is waiting on an IN
        // endpoint that will never produce anything.
        ck(obs_csw, "a valid CBW produced no CSW");

        if (obs_csw) begin
          // ---- PROPERTY 4: THE TAG IS ECHOED UNCHANGED ----
          //
          // dCSWTag must equal dCBWTag. A device that regenerates it, or
          // returns the previous one, breaks every host that has more
          // than one command in flight -- and the corruption is silent,
          // because both values are plausible 32-bit numbers.
          ck(obs_tag === tag, "dCSWTag does not echo dCBWTag");
          // ---- PROPERTY 5: the status matches the case ----
          ck(obs_sts === e_sts, "csw_status disagrees with the spec case");
          // ---- PROPERTY 6: the residue is expected minus actual ----
          ck(obs_res === e_res, "dCSWDataResidue disagrees with the spec case");
          // ---- PROPERTY 7: a residue never exceeds the expectation ----
          //
          // A residue larger than dCBWDataTransferLength is arithmetically
          // impossible and would be read by the host as an enormous
          // negative transfer.
          ck(obs_res <= hlen, "the residue exceeds what the host asked for");
        end

        // ---- PROPERTY 8: exactly one status counter moved ----
        if (e_sts == ST_PHASE)
          ck(n_phase == ph0 + 32'd1 && n_pass == p0 && n_fail == f0,
             "counters wrong for a phase error");
        else if (e_sts == ST_FAIL)
          ck(n_fail == f0 + 32'd1 && n_pass == p0 && n_phase == ph0,
             "counters wrong for a failed command");
        else
          ck(n_pass == p0 + 32'd1 && n_fail == f0 && n_phase == ph0,
             "counters wrong for a passing command");

        ck(state === 3'd0, "the transport did not return to IDLE after a CSW");
        steps = steps + 1;
      end
    end
  endtask

  task reset_dut;
    begin
      rst_n = 1'b0; cbw_valid = 1'b0;
      @(posedge clk); @(posedge clk);
      rst_n = 1'b1;
      @(posedge clk); #1;
    end
  endtask

  // ---- exhaustive reach ----
  //
  // hlen(3) x hdir(2) x dkind(3) x dlen(3) x dfail(2) = 108, every
  // combination an independent input. dlen and ddir are deliberately
  // swept even when the device declares no data, because IGNORING them
  // in that case is itself a property -- a device that let a stale
  // length leak into a no-data command would report a residue for bytes
  // that were never going to move.
  reg reach [0:107];
  integer nr, ri;

  integer hi_, hd, dk, dl_, df, k, idx;
  integer HLEN [0:2];
  integer DLEN [0:2];

  initial begin
    for (ri = 0; ri < 108; ri = ri + 1) reach[ri] = 1'b0;
    for (k = 1; k <= 13; k = k + 1) case_hits[k] = 0;
    HLEN[0] = 0; HLEN[1] = 8; HLEN[2] = 16;
    DLEN[0] = 0; DLEN[1] = 8; DLEN[2] = 16;
    seed = 32'd29001;

    reset_dut;

    // =============================================================
    //  PHASE 1 (DIRECTED, EXHAUSTIVE) -- the whole decision space.
    // =============================================================
    for (hi_ = 0; hi_ < 3; hi_ = hi_ + 1)
    for (hd  = 0; hd  < 2; hd  = hd + 1)
    for (dk  = 0; dk  < 3; dk  = dk + 1)
    for (dl_ = 0; dl_ < 3; dl_ = dl_ + 1)
    for (df  = 0; df  < 2; df  = df + 1) begin
      run_cbw(32'hA5A5_0000 + steps[31:0], HLEN[hi_][31:0], hd[0],
              (dk == 0), (dk == 1), DLEN[dl_][31:0], df[0], 1'b1, 1'b1);
      idx = ((((hi_ * 2 + hd) * 3 + dk) * 3 + dl_) * 2 + df);
      reach[idx] = 1'b1;
    end

    // =============================================================
    //  PHASE 2 (DIRECTED) -- every one of the thirteen cases, by name.
    //
    //  Phase 1 already reaches them all. This phase exists so the
    //  chapter can state that each NAMED case was exercised, and so a
    //  reader can find the one line that produces case 7.
    // =============================================================
    reset_dut;
    run_cbw(32'h0000_0001, 32'd0,  1'b0, 1'b1, 1'b0, 32'd0,  1'b0, 1'b1, 1'b1); // 1  Hn = Dn
    run_cbw(32'h0000_0002, 32'd0,  1'b0, 1'b0, 1'b1, 32'd8,  1'b0, 1'b1, 1'b1); // 2  Hn < Di
    run_cbw(32'h0000_0003, 32'd0,  1'b0, 1'b0, 1'b0, 32'd8,  1'b0, 1'b1, 1'b1); // 3  Hn < Do
    run_cbw(32'h0000_0004, 32'd16, 1'b1, 1'b1, 1'b0, 32'd0,  1'b0, 1'b1, 1'b1); // 4  Hi > Dn
    run_cbw(32'h0000_0005, 32'd16, 1'b1, 1'b0, 1'b1, 32'd8,  1'b0, 1'b1, 1'b1); // 5  Hi > Di
    run_cbw(32'h0000_0006, 32'd8,  1'b1, 1'b0, 1'b1, 32'd8,  1'b0, 1'b1, 1'b1); // 6  Hi = Di
    run_cbw(32'h0000_0007, 32'd8,  1'b1, 1'b0, 1'b1, 32'd16, 1'b0, 1'b1, 1'b1); // 7  Hi < Di
    run_cbw(32'h0000_0008, 32'd8,  1'b1, 1'b0, 1'b0, 32'd8,  1'b0, 1'b1, 1'b1); // 8  Hi <> Do
    run_cbw(32'h0000_0009, 32'd16, 1'b0, 1'b1, 1'b0, 32'd0,  1'b0, 1'b1, 1'b1); // 9  Ho > Dn
    run_cbw(32'h0000_000A, 32'd16, 1'b0, 1'b0, 1'b0, 32'd8,  1'b0, 1'b1, 1'b1); // 10 Ho > Do
    run_cbw(32'h0000_000B, 32'd8,  1'b0, 1'b0, 1'b0, 32'd8,  1'b0, 1'b1, 1'b1); // 11 Ho = Do
    run_cbw(32'h0000_000C, 32'd8,  1'b0, 1'b0, 1'b0, 32'd16, 1'b0, 1'b1, 1'b1); // 12 Ho < Do
    run_cbw(32'h0000_000D, 32'd8,  1'b0, 1'b0, 1'b1, 32'd8,  1'b0, 1'b1, 1'b1); // 13 Ho <> Di

    // =============================================================
    //  PHASE 3 (DIRECTED) -- the tag, over many distinct values.
    //
    //  The tag is the one field with no arithmetic in it, which makes it
    //  the easiest to get wrong in a way nothing else notices. Sixty-four
    //  distinct tags, including the ends of the range and values that a
    //  truncating implementation would alias together.
    // =============================================================
    reset_dut;
    for (k = 0; k < 64; k = k + 1) begin : tags
      reg [31:0] t;
      case (k % 4)
        0: t = 32'h0000_0000 + k;
        1: t = 32'hFFFF_FFFF - k;
        2: t = 32'h0000_FFFF + (k << 16);
        default: t = {k[7:0], ~k[7:0], k[7:0], ~k[7:0]};
      endcase
      run_cbw(t, 32'd8, 1'b1, 1'b0, 1'b1, 32'd8, 1'b0, 1'b1, 1'b1);
      ck(obs_tag === t, "a distinct tag was not echoed exactly");
    end

    // =============================================================
    //  PHASE 4 (DIRECTED, EXHAUSTIVE) -- CBW validity.
    //
    //  Signature and command length, all four combinations. Three of
    //  them are not a CBW at all, and the device must wedge rather than
    //  guess.
    // =============================================================
    //  Swept across every host length and direction as well, because the
    //  wedge must happen REGARDLESS of what the rest of the CBW claimed --
    //  the device has not understood the command and must not act on any
    //  part of it. 4 validity combinations x 3 lengths x 2 directions = 24,
    //  of which 18 are invalid.
    //
    //  The first version tested the four validity combinations once each,
    //  which gave the mutation that answers an invalid CBW a domain of
    //  three and a score of nine. Widening a property costs nothing and
    //  turns an uninformative number into one that means something.
    reset_dut;
    for (k = 0; k < 4; k = k + 1)
    for (hi_ = 0; hi_ < 3; hi_ = hi_ + 1)
    for (hd = 0; hd < 2; hd = hd + 1)
      run_cbw(32'hDEAD_0000 + k * 8 + hi_ * 2 + hd, HLEN[hi_][31:0], hd[0],
              1'b0, 1'b1, 32'd8, 1'b0, k[1], k[0]);

    // =============================================================
    //  PHASE 5 (RANDOM)
    // =============================================================
`ifndef DIRECTED_ONLY
    reset_dut;
    for (k = 0; k < 600; k = k + 1)
      run_cbw(urand(0), (urand(0) % 3) * 8, (urand(0) % 2),
              (urand(0) % 3) == 0, (urand(0) % 2), (urand(0) % 3) * 8,
              (urand(0) % 4) == 0, 1'b1, 1'b1);
`endif

    nr = 0; for (ri = 0; ri < 108; ri = ri + 1) if (reach[ri]) nr = nr + 1;

    $display("steps=%0d checks=%0d reach=%0d/108 errors=%0d",
             steps, checks, nr, errors);
    $display("[bot] cbws=%0d pass=%0d fail=%0d phase_error=%0d stalls=%0d invalid=%0d",
             c_cbw, c_pass, c_fail, c_phase, c_stall, c_invalid);
    $display("--- the thirteen Bulk-Only Transport cases, times exercised ---");
    $display("    case:  1    2    3    4    5    6    7    8    9   10   11   12   13");
    $write("    hits:");
    for (k = 1; k <= 13; k = k + 1) $write("%5d", case_hits[k]);
    $display("");
    for (k = 1; k <= 13; k = k + 1)
      ck(case_hits[k] > 0, "a Bulk-Only Transport case was never exercised");
    if (nr != 108) 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

// =====================================================================
//  msc_bot_fsm -- SystemVerilog.
//
//  Same hardware contract as the Verilog file: same ports, same widths,
//  same reset values, same cycle-by-cycle behaviour. The status and state
//  encodings become named types, and every continuous assignment is
//  written as `logic` + `assign` on separate lines.
//
//  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. Earlier in this track the mechanical
//  translation of five such lines produced 29,580 phantom failures
//  against a design that was entirely correct.
//
//  msc_bot_fsm -- Bulk-Only Transport, the protocol every USB flash
//  drive on earth actually speaks.
//
//  CLASSIFICATION: simplified synthesisable teaching RTL.
//  This is NOT a mass-storage device. There is no SCSI command decoder,
//  no media, no FIFO and no error recovery beyond what the transport
//  itself defines. It is the TRANSPORT: the wrapper around every
//  command, and the arithmetic that decides what the host is told.
//
//  WHY THIS MECHANISM IS WORTH RTL
//  -------------------------------
//  A flash drive is three bulk transfers in a loop:
//
//      CBW   31 bytes OUT   "here is a command, and here is how many
//                            bytes I expect to move, in this direction"
//      DATA  0..N bytes     the payload, if any
//      CSW   13 bytes IN    "it worked / it did not, and I moved this
//                            many fewer bytes than you asked for"
//
//  The interesting part is the third line. The host states an
//  expectation in the CBW -- dCBWDataTransferLength and the direction
//  bit -- BEFORE the device has looked at the command. The device then
//  discovers what it actually wants to do. Those two can disagree, in
//  both length and direction, and the transport has to resolve every
//  combination without ever leaving the host and device out of step.
//
//  The BOT specification enumerates exactly THIRTEEN cases of that
//  disagreement. They are not a style guide; they are the contract, and
//  an implementation that gets case 7 wrong works perfectly against
//  every well-behaved host until somebody issues a command whose real
//  length exceeds what the host allocated -- and then the two ends
//  disagree about how many bytes are on the wire, which no amount of
//  retrying fixes.
//
//  That is why this is the mechanism worth building: it is a small,
//  completely enumerable decision table where a single wrong cell is
//  invisible in normal use and unrecoverable when it fires.
// =====================================================================
module msc_bot_fsm (
  input  logic        clk,
  input  logic        rst_n,

  // ---- the Command Block Wrapper, 31 bytes OUT ----
  input  logic        cbw_valid,
  input  logic [31:0] cbw_tag,       // dCBWTag: MUST come back in the CSW
  input  logic [31:0] cbw_len,       // dCBWDataTransferLength: the host's expectation
  input  logic        cbw_dir_in,    // bmCBWFlags bit 7: 1 = device-to-host
  input  logic        cbw_sig_ok,    // dCBWSignature == 'USBC'
  input  logic        cbw_cb_ok,     // bCBWCBLength in 1..16

  // ---- what the command layer says it will actually do ----
  //
  // Available only AFTER the CBW has been parsed, which is exactly why
  // the disagreement below is possible at all.
  input  logic        dev_none,      // this command moves no data
  input  logic        dev_dir_in,    // direction the device wants
  input  logic [31:0] dev_len,       // bytes the device will actually move
  input  logic        dev_fail,      // the command itself failed

  // ---- the Command Status Wrapper, 13 bytes IN ----
  output logic        csw_valid,
  output logic [31:0] csw_tag,       // echoed, always
  output logic [31:0] csw_residue,   // dCSWDataResidue = expected - actual
  output logic [1:0]  csw_status,    // 00 pass, 01 fail, 10 phase error

  // ---- what the endpoints are told to do ----
  output logic        stall_in,
  output logic        stall_out,
  output logic        need_reset,    // invalid CBW: wait for Reset Recovery

  output logic [2:0]  state,
  output logic [31:0] n_cbw,
  output logic [31:0] n_pass,
  output logic [31:0] n_fail,
  output logic [31:0] n_phase,
  output logic [31:0] n_stall,
  output logic [31:0] n_invalid
);

  localparam [1:0] ST_PASS  = 2'd0,
                   ST_FAIL  = 2'd1,
                   ST_PHASE = 2'd2;

  localparam [2:0] S_IDLE = 3'd0,   // waiting for a CBW
                   S_DATA = 3'd1,   // moving the data phase
                   S_CSW  = 3'd2,   // presenting the status
                   S_WEDGE = 3'd3;  // invalid CBW: both endpoints stalled

  // -------------------------------------------------------------------
  //  The host's stated expectation, as the spec's three kinds.
  // -------------------------------------------------------------------
  logic h_none;
  assign h_none = (cbw_len == 32'd0);
  logic h_in;
  assign h_in = !h_none &&  cbw_dir_in;
  logic h_out;
  assign h_out = !h_none && !cbw_dir_in;

  // The device's intent. dev_dir_in and dev_len are IGNORED when the
  // command moves no data -- a device that let a stale length leak into
  // a no-data command would report a residue for bytes that were never
  // going to move.
  logic d_none;
  assign d_none = dev_none;
  logic d_in;
  assign d_in = !d_none &&  dev_dir_in;
  logic d_out;
  assign d_out = !d_none && !dev_dir_in;
  // dev_len is read only through d_in / d_out below, both of which are
  // false when the command moves no data -- so no zeroing guard is needed
  // here, and adding one would be dead code. The bench asserts that
  // invariant rather than the design defending against it.
  logic [31:0] d_len;
  assign d_len = dev_len;

  // -------------------------------------------------------------------
  //  THE THIRTEEN CASES.
  //
  //  Direction disagreement is always fatal: cases 8 and 13. So is the
  //  host under-allocating, cases 2, 3, 7 and 12 -- there is no way to
  //  move more bytes than the host set aside, and no way to tell it so
  //  except by declaring the phase lost.
  //
  //  Everything else is survivable, and the residue carries the
  //  shortfall.
  // -------------------------------------------------------------------
  logic dir_clash;
  assign dir_clash = (h_in && d_out) || (h_out && d_in);      // 8, 13
  logic host_short;
  assign host_short = (h_none && !d_none)                       // 2, 3
                   || (h_in  && d_in  && (cbw_len < d_len))     // 7
                   || (h_out && d_out && (cbw_len < d_len));    // 12

  logic phase_err;
  assign phase_err = dir_clash || host_short;

  // Bytes the transport will actually move.
  //
  // NO CLAMP TO cbw_len IS NEEDED, and that is worth stating because the
  // clamp is the obvious thing to write. Every situation in which the
  // device wants more bytes than the host allocated is ALREADY a phase
  // error: same-direction under-allocation is caught by host_short
  // (cases 7 and 12) and opposite-direction by dir_clash (cases 8 and 13).
  // So on any path that reaches this expression, d_len <= cbw_len holds.
  //
  // A clamp here would be unreachable code -- it was in the first version
  // of this file, and the mutation that broke it scored exactly ZERO,
  // which is how it was found. The invariant is asserted in the bench
  // instead, where a violation would be visible.
  //
  // There is no phase-error guard here either, for the same reason: both
  // consumers below (`residue` and the two short-data tests) already
  // exclude the phase-error case themselves. Guarding it a second time
  // scored zero as well. Two dead guards, both found by mutations that
  // refused to die, and both deleted rather than explained away.
  logic [31:0] moved;
  assign moved = d_none ? 32'd0 : d_len;

  // dCSWDataResidue. On a phase error the field is defined but
  // meaningless to the host, which is about to reset the interface
  // anyway; it is reported as the full expectation so a trace reads
  // sensibly.
  logic [31:0] residue;
  assign residue = phase_err ? cbw_len : (cbw_len - moved);

  // Cases 4 and 9: the host allocated a data phase and the device has
  // nothing to put in it. The transport must terminate that phase
  // rather than leave the host waiting, and a STALL is how BOT says so.
  logic short_in;
  assign short_in = h_in  && !phase_err && (moved < cbw_len);
  logic short_out;
  assign short_out = h_out && !phase_err && (moved < cbw_len);

  // -------------------------------------------------------------------
  //  CBW validity. A CBW that is not 31 bytes, lacks the signature, or
  //  carries an out-of-range command length is not a CBW at all: the
  //  device stalls BOTH endpoints and waits for Reset Recovery. It must
  //  NOT answer with a CSW, because a CSW would imply it understood a
  //  command it did not.
  // -------------------------------------------------------------------
  logic cbw_ok;
  assign cbw_ok = cbw_sig_ok && cbw_cb_ok;

  logic [2:0]  st;
  logic [31:0] tag_r, res_r;
  logic [1:0]  sts_r;
  logic        csw_r, sin_r, sout_r, wedge_r;

  logic [31:0] cbw_c, pass_c, fail_c, phase_c, stall_c, inval_c;

  assign state       = st;
  assign csw_valid   = csw_r;
  assign csw_tag     = tag_r;
  assign csw_residue = res_r;
  assign csw_status  = sts_r;
  assign stall_in    = sin_r;
  assign stall_out   = sout_r;
  assign need_reset  = wedge_r;
  assign n_cbw       = cbw_c;
  assign n_pass      = pass_c;
  assign n_fail      = fail_c;
  assign n_phase     = phase_c;
  assign n_stall     = stall_c;
  assign n_invalid   = inval_c;

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      st      <= S_IDLE;
      tag_r   <= 32'd0;
      res_r   <= 32'd0;
      sts_r   <= ST_PASS;
      csw_r   <= 1'b0;
      sin_r   <= 1'b0;
      sout_r  <= 1'b0;
      wedge_r <= 1'b0;
      cbw_c   <= 32'd0;
      pass_c  <= 32'd0;
      fail_c  <= 32'd0;
      phase_c <= 32'd0;
      stall_c <= 32'd0;
      inval_c <= 32'd0;
    end else begin
      csw_r  <= 1'b0;
      sin_r  <= 1'b0;
      sout_r <= 1'b0;

      case (st)
        S_IDLE: begin
          if (cbw_valid) begin
            cbw_c <= cbw_c + 32'd1;
            if (!cbw_ok) begin
              // Not a CBW. Stall both ways and wedge until Reset
              // Recovery -- answering anything else would be inventing
              // a reply to a command that was never received.
              st      <= S_WEDGE;
              wedge_r <= 1'b1;
              sin_r   <= 1'b1;
              sout_r  <= 1'b1;
              inval_c <= inval_c + 32'd1;
            end else begin
              // THE TAG IS CAPTURED HERE, from the CBW, and echoed
              // unchanged. A device that regenerates it, or echoes the
              // previous one, breaks every host's command queue.
              tag_r <= cbw_tag;
              res_r <= residue;
              sts_r <= phase_err ? ST_PHASE : (dev_fail ? ST_FAIL : ST_PASS);

              if (phase_err) begin
                phase_c <= phase_c + 32'd1;
                // A phase error stalls the direction the host was
                // waiting on, so the host stops waiting and comes to
                // read the CSW.
                if (h_in)  sin_r  <= 1'b1;
                if (h_out) sout_r <= 1'b1;
                if (h_in || h_out) stall_c <= stall_c + 32'd1;
                st <= S_CSW;
              end else begin
                if (dev_fail) fail_c <= fail_c + 32'd1;
                else          pass_c <= pass_c + 32'd1;
                // Cases 4 and 9: terminate a data phase the device
                // cannot fill.
                if (short_in)  begin sin_r  <= 1'b1; stall_c <= stall_c + 32'd1; end
                if (short_out) begin sout_r <= 1'b1; stall_c <= stall_c + 32'd1; end
                st <= (h_none && d_none) ? S_CSW : S_DATA;
              end
            end
          end
        end

        // The data phase itself is not modelled byte by byte; what the
        // transport owes the host is the LENGTH decision above, and that
        // is already fixed.
        S_DATA: st <= S_CSW;

        S_CSW: begin
          csw_r <= 1'b1;
          st    <= S_IDLE;
        end

        // Wedged. Only a reset gets out, which is what Reset Recovery
        // means: the host has to clear both stalls and start again.
        S_WEDGE: begin
          sin_r  <= 1'b1;
          sout_r <= 1'b1;
        end

        default: st <= S_IDLE;
      endcase
    end
  end

endmodule

// =====================================================================
//  Testbench for msc_bot_fsm -- 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 MODEL IS THE SPEC'S TABLE, NOT THE DESIGN'S BOOLEANS.
//
//  The design decides with two expressions -- `dir_clash` and
//  `host_short` -- and derives everything from them. The model does the
//  opposite: it classifies the situation into one of the thirteen NAMED
//  cases the Bulk-Only Transport specification enumerates, and then
//  looks the answer up in a table written straight from that document.
//
//  Two different derivations of the same contract. A boolean the design
//  got subtly wrong cannot be got wrong the same way by a lookup keyed
//  on a case number, which is the entire reason for writing it this way
//  rather than more carefully.
//
//  Every valid-gated output is captured at a DEFINED instant. The stall
//  decision is only meaningful in the cycle the CBW is consumed; reading
//  it later reads a scheduling artefact.
// =====================================================================
`timescale 1ns/1ps
module tb_bt_sv;

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

  logic         cbw_valid = 1'b0;
  logic [31:0] cbw_tag = 32'd0, cbw_len = 32'd0;
  logic         cbw_dir_in = 1'b0, cbw_sig_ok = 1'b1, cbw_cb_ok = 1'b1;
  logic         dev_none = 1'b0, dev_dir_in = 1'b0, dev_fail = 1'b0;
  logic [31:0] dev_len = 32'd0;

  logic        csw_valid, stall_in, stall_out, need_reset;
  logic [31:0] csw_tag, csw_residue;
  logic [1:0]  csw_status;
  logic [2:0]  state;
  logic [31:0] n_cbw, n_pass, n_fail, n_phase, n_stall, n_invalid;

  msc_bot_fsm dut (
    .clk(clk), .rst_n(rst_n),
    .cbw_valid(cbw_valid), .cbw_tag(cbw_tag), .cbw_len(cbw_len),
    .cbw_dir_in(cbw_dir_in), .cbw_sig_ok(cbw_sig_ok), .cbw_cb_ok(cbw_cb_ok),
    .dev_none(dev_none), .dev_dir_in(dev_dir_in), .dev_len(dev_len),
    .dev_fail(dev_fail),
    .csw_valid(csw_valid), .csw_tag(csw_tag), .csw_residue(csw_residue),
    .csw_status(csw_status),
    .stall_in(stall_in), .stall_out(stall_out), .need_reset(need_reset),
    .state(state),
    .n_cbw(n_cbw), .n_pass(n_pass), .n_fail(n_fail), .n_phase(n_phase),
    .n_stall(n_stall), .n_invalid(n_invalid)
  );

  localparam [1:0] ST_PASS = 2'd0, ST_FAIL = 2'd1, ST_PHASE = 2'd2;

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

  // ---- cumulative across resets ----
  //
  // Every reset_dut zeroes the DUT's own counters, so a summary that read
  // them directly would report only whatever happened after the last one.
  // Per-step checks still use the DUT counters; these are for the totals.
  int c_cbw = 0, c_pass = 0, c_fail = 0, c_phase = 0,
          c_stall = 0, c_invalid = 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 ----
  logic        obs_sin, obs_sout, obs_wedge, obs_csw;
  logic [31:0] obs_tag, obs_res;
  logic [1:0]  obs_sts;

  // ---- how many times each of the thirteen cases was exercised ----
  int case_hits [1:13];

  // -------------------------------------------------------------------
  //  THE MODEL: classify into the spec's thirteen cases.
  //
  //  h: 0 = Hn (no data), 1 = Hi (device-to-host), 2 = Ho (host-to-device)
  //  d: 0 = Dn (no data), 1 = Di (device-to-host), 2 = Do (host-to-device)
  // -------------------------------------------------------------------
  function automatic logic [4:0] spec_case(input [1:0] h, input [1:0] d,
                           input [31:0] hl, input [31:0] dl);
    begin
      if      (h == 2'd0 && d == 2'd0)                spec_case = 5'd1;
      else if (h == 2'd0 && d == 2'd1)                spec_case = 5'd2;
      else if (h == 2'd0 && d == 2'd2)                spec_case = 5'd3;
      else if (h == 2'd1 && d == 2'd0)                spec_case = 5'd4;
      else if (h == 2'd1 && d == 2'd1 && hl >  dl)    spec_case = 5'd5;
      else if (h == 2'd1 && d == 2'd1 && hl == dl)    spec_case = 5'd6;
      else if (h == 2'd1 && d == 2'd1 && hl <  dl)    spec_case = 5'd7;
      else if (h == 2'd1 && d == 2'd2)                spec_case = 5'd8;
      else if (h == 2'd2 && d == 2'd0)                spec_case = 5'd9;
      else if (h == 2'd2 && d == 2'd2 && hl >  dl)    spec_case = 5'd10;
      else if (h == 2'd2 && d == 2'd2 && hl == dl)    spec_case = 5'd11;
      else if (h == 2'd2 && d == 2'd2 && hl <  dl)    spec_case = 5'd12;
      else                                            spec_case = 5'd13;
    end
  endfunction

  // Which cases are a phase error, straight from the specification.
  // Written as a set membership rather than as a condition, so it cannot
  // share an algebraic mistake with the design.
  function automatic logic is_phase(input [4:0] c);
    begin
      is_phase = (c == 5'd2)  || (c == 5'd3)  || (c == 5'd7) ||
                 (c == 5'd8)  || (c == 5'd12) || (c == 5'd13);
    end
  endfunction

  // -------------------------------------------------------------------
  //  Drive one CBW and check everything the transport owes the host.
  // -------------------------------------------------------------------
  task automatic run_cbw(input [31:0] tag, input [31:0] hlen, input hdir,
               input dnone, input ddir, input [31:0] dlen,
               input dfail, input sig_ok, input cb_ok);
    logic [1:0]  h, d;
    logic [4:0]  c;
    logic        e_phase, e_sin, e_sout;
    logic [31:0] e_moved, e_res;
    logic [1:0]  e_sts;
    logic [31:0] p0, f0, ph0, i0;
    int    g;
    begin
      // classify, from the inputs only
      h = (hlen == 32'd0) ? 2'd0 : (hdir ? 2'd1 : 2'd2);
      d = dnone           ? 2'd0 : (ddir ? 2'd1 : 2'd2);
      c = spec_case(h, d, hlen, dnone ? 32'd0 : dlen);
      e_phase = is_phase(c);

      // the expected answer, from the case number
      e_moved = e_phase ? 32'd0
              : (d == 2'd0) ? 32'd0
              : ((dlen > hlen) ? hlen : dlen);
      e_res   = e_phase ? hlen : (hlen - e_moved);
      e_sts   = e_phase ? ST_PHASE : (dfail ? ST_FAIL : ST_PASS);
      // A short or absent data phase must be terminated on the side the
      // host is waiting on; a phase error stalls that side too.
      e_sin   = e_phase ? (h == 2'd1) : ((h == 2'd1) && (e_moved < hlen));
      e_sout  = e_phase ? (h == 2'd2) : ((h == 2'd2) && (e_moved < hlen));

      p0 = n_pass; f0 = n_fail; ph0 = n_phase; i0 = n_invalid;

      cbw_valid  = 1'b1;  cbw_tag = tag; cbw_len = hlen; cbw_dir_in = hdir;
      cbw_sig_ok = sig_ok; cbw_cb_ok = cb_ok;
      dev_none   = dnone; dev_dir_in = ddir; dev_len = dlen; dev_fail = dfail;

      @(posedge clk); #1;
      // ---- captured at the instant the CBW is consumed ----
      obs_sin   = stall_in;
      obs_sout  = stall_out;
      obs_wedge = need_reset;
      cbw_valid = 1'b0;

      if (!(sig_ok && cb_ok)) begin
        // ---- PROPERTY 1: an invalid CBW is not answered ----
        //
        // The device must stall both endpoints and wait for Reset
        // Recovery. Replying with a CSW would tell the host the command
        // was understood, and the host would believe it.
        ck(obs_sin && obs_sout,
           "an invalid CBW did not stall both endpoints");
        ck(obs_wedge, "an invalid CBW did not request reset recovery");
        ck(n_invalid == i0 + 32'd1, "an invalid CBW was not counted");
        c_cbw = c_cbw + 1; c_invalid = c_invalid + 1;
        // and no CSW, ever -- checked over a bounded window
        obs_csw = 1'b0;
        for (g = 0; g < 8; g = g + 1) begin
          @(posedge clk); #1;
          if (csw_valid) obs_csw = 1'b1;
        end
        ck(!obs_csw, "an invalid CBW was answered with a CSW");
        ck(n_pass == p0 && n_fail == f0 && n_phase == ph0,
           "an invalid CBW moved a status counter");
        // reset out of the wedge, which is what Reset Recovery does
        rst_n = 1'b0; @(posedge clk); @(posedge clk); rst_n = 1'b1;
        @(posedge clk); #1;
        steps = steps + 1;
      end else begin
        case_hits[c] = case_hits[c] + 1;
        c_cbw = c_cbw + 1;
        if (e_sts == ST_PHASE) c_phase = c_phase + 1;
        else if (e_sts == ST_FAIL) c_fail = c_fail + 1;
        else c_pass = c_pass + 1;
        if (e_sin)  c_stall = c_stall + 1;
        if (e_sout) c_stall = c_stall + 1;

        // ---- PROPERTY 2a: the invariants the design RELIES on ----
        //
        // The design carries no clamp and no zeroing guard, because two
        // invariants make both unnecessary. Relying on an invariant is
        // fine; relying on one nobody checks is not, so they are checked
        // here -- and a violation would be a bench bug before it was a
        // design bug.
        if (!e_phase && d != 2'd0)
          ck(dlen <= hlen,
             "INVARIANT: a non-phase-error transfer wants more than the host allocated");
        if (dnone)
          ck(e_moved == 32'd0,
             "INVARIANT: a no-data command moved a non-zero number of bytes");

        // ---- PROPERTY 2: the stall decision matches the case ----
        ck(obs_sin  === e_sin,  "stall_in disagrees with the spec case");
        ck(obs_sout === e_sout, "stall_out disagrees with the spec case");
        ck(!obs_wedge, "a valid CBW requested reset recovery");

        // ---- wait, bounded, for the CSW ----
        obs_csw = 1'b0;
        for (g = 0; g < 8 && !obs_csw; g = g + 1) begin
          @(posedge clk); #1;
          if (csw_valid) begin
            obs_csw = 1'b1;
            obs_tag = csw_tag;
            obs_res = csw_residue;
            obs_sts = csw_status;
          end
        end
        // ---- PROPERTY 3: exactly one CSW per valid CBW ----
        //
        // Silence would hang the host forever: it is waiting on an IN
        // endpoint that will never produce anything.
        ck(obs_csw, "a valid CBW produced no CSW");

        if (obs_csw) begin
          // ---- PROPERTY 4: THE TAG IS ECHOED UNCHANGED ----
          //
          // dCSWTag must equal dCBWTag. A device that regenerates it, or
          // returns the previous one, breaks every host that has more
          // than one command in flight -- and the corruption is silent,
          // because both values are plausible 32-bit numbers.
          ck(obs_tag === tag, "dCSWTag does not echo dCBWTag");
          // ---- PROPERTY 5: the status matches the case ----
          ck(obs_sts === e_sts, "csw_status disagrees with the spec case");
          // ---- PROPERTY 6: the residue is expected minus actual ----
          ck(obs_res === e_res, "dCSWDataResidue disagrees with the spec case");
          // ---- PROPERTY 7: a residue never exceeds the expectation ----
          //
          // A residue larger than dCBWDataTransferLength is arithmetically
          // impossible and would be read by the host as an enormous
          // negative transfer.
          ck(obs_res <= hlen, "the residue exceeds what the host asked for");
        end

        // ---- PROPERTY 8: exactly one status counter moved ----
        if (e_sts == ST_PHASE)
          ck(n_phase == ph0 + 32'd1 && n_pass == p0 && n_fail == f0,
             "counters wrong for a phase error");
        else if (e_sts == ST_FAIL)
          ck(n_fail == f0 + 32'd1 && n_pass == p0 && n_phase == ph0,
             "counters wrong for a failed command");
        else
          ck(n_pass == p0 + 32'd1 && n_fail == f0 && n_phase == ph0,
             "counters wrong for a passing command");

        ck(state === 3'd0, "the transport did not return to IDLE after a CSW");
        steps = steps + 1;
      end
    end
  endtask

  task automatic reset_dut;
    begin
      rst_n = 1'b0; cbw_valid = 1'b0;
      @(posedge clk); @(posedge clk);
      rst_n = 1'b1;
      @(posedge clk); #1;
    end
  endtask

  // ---- exhaustive reach ----
  //
  // hlen(3) x hdir(2) x dkind(3) x dlen(3) x dfail(2) = 108, every
  // combination an independent input. dlen and ddir are deliberately
  // swept even when the device declares no data, because IGNORING them
  // in that case is itself a property -- a device that let a stale
  // length leak into a no-data command would report a residue for bytes
  // that were never going to move.
  logic reach [0:107];
  int nr, ri;

  int hi_, hd, dk, dl_, df, k, idx;
  int HLEN [0:2];
  int DLEN [0:2];

  initial begin
    for (ri = 0; ri < 108; ri = ri + 1) reach[ri] = 1'b0;
    for (k = 1; k <= 13; k = k + 1) case_hits[k] = 0;
    HLEN[0] = 0; HLEN[1] = 8; HLEN[2] = 16;
    DLEN[0] = 0; DLEN[1] = 8; DLEN[2] = 16;
    seed = 32'd29001;

    reset_dut;

    // =============================================================
    //  PHASE 1 (DIRECTED, EXHAUSTIVE) -- the whole decision space.
    // =============================================================
    for (hi_ = 0; hi_ < 3; hi_ = hi_ + 1)
    for (hd  = 0; hd  < 2; hd  = hd + 1)
    for (dk  = 0; dk  < 3; dk  = dk + 1)
    for (dl_ = 0; dl_ < 3; dl_ = dl_ + 1)
    for (df  = 0; df  < 2; df  = df + 1) begin
      run_cbw(32'hA5A5_0000 + steps[31:0], HLEN[hi_][31:0], hd[0],
              (dk == 0), (dk == 1), DLEN[dl_][31:0], df[0], 1'b1, 1'b1);
      idx = ((((hi_ * 2 + hd) * 3 + dk) * 3 + dl_) * 2 + df);
      reach[idx] = 1'b1;
    end

    // =============================================================
    //  PHASE 2 (DIRECTED) -- every one of the thirteen cases, by name.
    //
    //  Phase 1 already reaches them all. This phase exists so the
    //  chapter can state that each NAMED case was exercised, and so a
    //  reader can find the one line that produces case 7.
    // =============================================================
    reset_dut;
    run_cbw(32'h0000_0001, 32'd0,  1'b0, 1'b1, 1'b0, 32'd0,  1'b0, 1'b1, 1'b1); // 1  Hn = Dn
    run_cbw(32'h0000_0002, 32'd0,  1'b0, 1'b0, 1'b1, 32'd8,  1'b0, 1'b1, 1'b1); // 2  Hn < Di
    run_cbw(32'h0000_0003, 32'd0,  1'b0, 1'b0, 1'b0, 32'd8,  1'b0, 1'b1, 1'b1); // 3  Hn < Do
    run_cbw(32'h0000_0004, 32'd16, 1'b1, 1'b1, 1'b0, 32'd0,  1'b0, 1'b1, 1'b1); // 4  Hi > Dn
    run_cbw(32'h0000_0005, 32'd16, 1'b1, 1'b0, 1'b1, 32'd8,  1'b0, 1'b1, 1'b1); // 5  Hi > Di
    run_cbw(32'h0000_0006, 32'd8,  1'b1, 1'b0, 1'b1, 32'd8,  1'b0, 1'b1, 1'b1); // 6  Hi = Di
    run_cbw(32'h0000_0007, 32'd8,  1'b1, 1'b0, 1'b1, 32'd16, 1'b0, 1'b1, 1'b1); // 7  Hi < Di
    run_cbw(32'h0000_0008, 32'd8,  1'b1, 1'b0, 1'b0, 32'd8,  1'b0, 1'b1, 1'b1); // 8  Hi <> Do
    run_cbw(32'h0000_0009, 32'd16, 1'b0, 1'b1, 1'b0, 32'd0,  1'b0, 1'b1, 1'b1); // 9  Ho > Dn
    run_cbw(32'h0000_000A, 32'd16, 1'b0, 1'b0, 1'b0, 32'd8,  1'b0, 1'b1, 1'b1); // 10 Ho > Do
    run_cbw(32'h0000_000B, 32'd8,  1'b0, 1'b0, 1'b0, 32'd8,  1'b0, 1'b1, 1'b1); // 11 Ho = Do
    run_cbw(32'h0000_000C, 32'd8,  1'b0, 1'b0, 1'b0, 32'd16, 1'b0, 1'b1, 1'b1); // 12 Ho < Do
    run_cbw(32'h0000_000D, 32'd8,  1'b0, 1'b0, 1'b1, 32'd8,  1'b0, 1'b1, 1'b1); // 13 Ho <> Di

    // =============================================================
    //  PHASE 3 (DIRECTED) -- the tag, over many distinct values.
    //
    //  The tag is the one field with no arithmetic in it, which makes it
    //  the easiest to get wrong in a way nothing else notices. Sixty-four
    //  distinct tags, including the ends of the range and values that a
    //  truncating implementation would alias together.
    // =============================================================
    reset_dut;
    for (k = 0; k < 64; k = k + 1) begin : tags
      logic [31:0] t;
      case (k % 4)
        0: t = 32'h0000_0000 + k;
        1: t = 32'hFFFF_FFFF - k;
        2: t = 32'h0000_FFFF + (k << 16);
        default: t = {k[7:0], ~k[7:0], k[7:0], ~k[7:0]};
      endcase
      run_cbw(t, 32'd8, 1'b1, 1'b0, 1'b1, 32'd8, 1'b0, 1'b1, 1'b1);
      ck(obs_tag === t, "a distinct tag was not echoed exactly");
    end

    // =============================================================
    //  PHASE 4 (DIRECTED, EXHAUSTIVE) -- CBW validity.
    //
    //  Signature and command length, all four combinations. Three of
    //  them are not a CBW at all, and the device must wedge rather than
    //  guess.
    // =============================================================
    //  Swept across every host length and direction as well, because the
    //  wedge must happen REGARDLESS of what the rest of the CBW claimed --
    //  the device has not understood the command and must not act on any
    //  part of it. 4 validity combinations x 3 lengths x 2 directions = 24,
    //  of which 18 are invalid.
    //
    //  The first version tested the four validity combinations once each,
    //  which gave the mutation that answers an invalid CBW a domain of
    //  three and a score of nine. Widening a property costs nothing and
    //  turns an uninformative number into one that means something.
    reset_dut;
    for (k = 0; k < 4; k = k + 1)
    for (hi_ = 0; hi_ < 3; hi_ = hi_ + 1)
    for (hd = 0; hd < 2; hd = hd + 1)
      run_cbw(32'hDEAD_0000 + k * 8 + hi_ * 2 + hd, HLEN[hi_][31:0], hd[0],
              1'b0, 1'b1, 32'd8, 1'b0, k[1], k[0]);

    // =============================================================
    //  PHASE 5 (RANDOM)
    // =============================================================
`ifndef DIRECTED_ONLY
    reset_dut;
    for (k = 0; k < 600; k = k + 1)
      run_cbw(urand(), (urand() % 3) * 8, (urand() % 2),
              (urand() % 3) == 0, (urand() % 2), (urand() % 3) * 8,
              (urand() % 4) == 0, 1'b1, 1'b1);
`endif

    nr = 0; for (ri = 0; ri < 108; ri = ri + 1) if (reach[ri]) nr = nr + 1;

    $display("steps=%0d checks=%0d reach=%0d/108 errors=%0d",
             steps, checks, nr, errors);
    $display("[bot] cbws=%0d pass=%0d fail=%0d phase_error=%0d stalls=%0d invalid=%0d",
             c_cbw, c_pass, c_fail, c_phase, c_stall, c_invalid);
    $display("--- the thirteen Bulk-Only Transport cases, times exercised ---");
    $display("    case:  1    2    3    4    5    6    7    8    9   10   11   12   13");
    $write("    hits:");
    for (k = 1; k <= 13; k = k + 1) $write("%5d", case_hits[k]);
    $display("");
    for (k = 1; k <= 13; k = k + 1)
      ck(case_hits[k] > 0, "a Bulk-Only Transport case was never exercised");
    if (nr != 108) 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

-- =====================================================================
--  msc_bot_fsm -- Bulk-Only Transport, VHDL-2008.
--
--  CLASSIFICATION: simplified synthesisable teaching RTL.
--  Same hardware contract as the Verilog and SystemVerilog files: same
--  ports, same widths, same reset values, same cycle-by-cycle behaviour.
--
--  This is NOT a mass-storage device. There is no SCSI decoder, no media
--  and no FIFO. It is the TRANSPORT: the wrapper around every command,
--  and the arithmetic that decides what the host is told.
--
--  A flash drive is three bulk transfers in a loop -- CBW out, data,
--  CSW in -- and the interesting part is the third. The host states an
--  expectation in the CBW BEFORE the device has looked at the command;
--  the device then discovers what it actually wants to do. Those two can
--  disagree in length and in direction, and the specification enumerates
--  exactly THIRTEEN cases of that disagreement.
--
--  Getting one cell of that table wrong is invisible against every
--  well-behaved host and unrecoverable when it fires, because the two
--  ends then disagree about how many bytes are on the wire and no amount
--  of retrying fixes it.
-- =====================================================================
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

entity msc_bot_fsm is
  port (
    clk   : in std_logic;
    rst_n : in std_logic;

    -- the Command Block Wrapper, 31 bytes OUT
    cbw_valid  : in std_logic;
    cbw_tag    : in std_logic_vector(31 downto 0);  -- MUST come back in the CSW
    cbw_len    : in std_logic_vector(31 downto 0);  -- the host's expectation
    cbw_dir_in : in std_logic;                      -- 1 = device-to-host
    cbw_sig_ok : in std_logic;                      -- dCBWSignature == 'USBC'
    cbw_cb_ok  : in std_logic;                      -- bCBWCBLength in 1..16

    -- what the command layer says it will actually do, available only
    -- AFTER the CBW has been parsed -- which is why disagreement is
    -- possible at all
    dev_none   : in std_logic;
    dev_dir_in : in std_logic;
    dev_len    : in std_logic_vector(31 downto 0);
    dev_fail   : in std_logic;

    -- the Command Status Wrapper, 13 bytes IN
    csw_valid   : out std_logic;
    csw_tag     : out std_logic_vector(31 downto 0);
    csw_residue : out std_logic_vector(31 downto 0);
    csw_status  : out std_logic_vector(1 downto 0);

    stall_in   : out std_logic;
    stall_out  : out std_logic;
    need_reset : out std_logic;

    state     : out std_logic_vector(2 downto 0);
    n_cbw     : out std_logic_vector(31 downto 0);
    n_pass    : out std_logic_vector(31 downto 0);
    n_fail    : out std_logic_vector(31 downto 0);
    n_phase   : out std_logic_vector(31 downto 0);
    n_stall   : out std_logic_vector(31 downto 0);
    n_invalid : out std_logic_vector(31 downto 0)
  );
end entity;

architecture rtl of msc_bot_fsm is

  constant ST_PASS  : std_logic_vector(1 downto 0) := "00";
  constant ST_FAIL  : std_logic_vector(1 downto 0) := "01";
  constant ST_PHASE : std_logic_vector(1 downto 0) := "10";

  type bot_state_t is (S_IDLE, S_DATA, S_CSW, S_WEDGE);

  -- Exported as a 3-bit code so all three languages present one identical
  -- observable contract to their benches.
  function st_code (s : bot_state_t) return std_logic_vector is
  begin
    case s is
      when S_IDLE  => return "000";
      when S_DATA  => return "001";
      when S_CSW   => return "010";
      when S_WEDGE => return "011";
    end case;
  end function;

  signal st : bot_state_t := S_IDLE;

  -- the host's stated expectation, as the spec's three kinds
  signal h_none, h_in, h_out : std_logic;
  -- the device's intent
  signal d_none, d_in, d_out : std_logic;
  signal d_len : unsigned(31 downto 0);

  signal dir_clash, host_short, phase_err : std_logic;
  signal moved, residue : unsigned(31 downto 0);
  signal short_in, short_out : std_logic;
  signal cbw_ok : std_logic;

  signal tag_r : std_logic_vector(31 downto 0) := (others => '0');
  signal res_r : unsigned(31 downto 0) := (others => '0');
  signal sts_r : std_logic_vector(1 downto 0) := ST_PASS;
  signal csw_r, sin_r, sout_r, wedge_r : std_logic := '0';

  signal cbw_c, pass_c, fail_c, phase_c, stall_c, inval_c
         : unsigned(31 downto 0) := (others => '0');

  -- How many stalls this CBW raises, computed combinationally so the
  -- counter takes one write rather than one per direction.
  signal n_stall_now : unsigned(31 downto 0);

begin

  h_none <= '1' when unsigned(cbw_len) = 0 else '0';
  h_in   <= '1' when (h_none = '0' and cbw_dir_in = '1') else '0';
  h_out  <= '1' when (h_none = '0' and cbw_dir_in = '0') else '0';

  d_none <= dev_none;
  d_in   <= '1' when (d_none = '0' and dev_dir_in = '1') else '0';
  d_out  <= '1' when (d_none = '0' and dev_dir_in = '0') else '0';
  -- dev_len is read only through d_in / d_out below, both false when the
  -- command moves no data, so no zeroing guard is needed here.
  d_len  <= unsigned(dev_len);

  -- -------------------------------------------------------------------
  --  THE THIRTEEN CASES. Direction disagreement is always fatal (8, 13);
  --  so is the host under-allocating (2, 3, 7, 12) -- there is no way to
  --  move more bytes than the host set aside and no way to say so except
  --  by declaring the phase lost. Everything else is survivable and the
  --  residue carries the shortfall.
  -- -------------------------------------------------------------------
  dir_clash <= '1' when ((h_in = '1' and d_out = '1') or
                         (h_out = '1' and d_in = '1')) else '0';        -- 8, 13
  host_short <= '1' when ((h_none = '1' and d_none = '0') or            -- 2, 3
                          (h_in = '1' and d_in = '1' and unsigned(cbw_len) < d_len) or   -- 7
                          (h_out = '1' and d_out = '1' and unsigned(cbw_len) < d_len))   -- 12
                else '0';
  phase_err <= dir_clash or host_short;

  -- No clamp to cbw_len, and no phase-error guard. Every case where the
  -- device wants more than the host allocated is ALREADY a phase error,
  -- and both consumers below exclude the phase-error case themselves.
  -- Both guards were present in the first version of this design and both
  -- were found to be unreachable by mutations that scored exactly zero.
  moved <= (others => '0') when d_none = '1' else d_len;

  residue <= unsigned(cbw_len) when phase_err = '1'
             else unsigned(cbw_len) - moved;

  -- Cases 4 and 9: the host allocated a data phase the device cannot
  -- fill. The transport must terminate it rather than leave the host
  -- waiting, and a STALL is how BOT says so.
  short_in  <= '1' when (h_in = '1' and phase_err = '0' and moved < unsigned(cbw_len))
               else '0';
  short_out <= '1' when (h_out = '1' and phase_err = '0' and moved < unsigned(cbw_len))
               else '0';

  cbw_ok <= cbw_sig_ok and cbw_cb_ok;

  stalls : process (all)
    variable c : unsigned(31 downto 0);
  begin
    c := (others => '0');
    if phase_err = '1' then
      if h_in = '1' or h_out = '1' then c := to_unsigned(1, 32); end if;
    else
      if short_in  = '1' then c := c + 1; end if;
      if short_out = '1' then c := c + 1; end if;
    end if;
    n_stall_now <= c;
  end process;

  state       <= st_code(st);
  csw_valid   <= csw_r;
  csw_tag     <= tag_r;
  csw_residue <= std_logic_vector(res_r);
  csw_status  <= sts_r;
  stall_in    <= sin_r;
  stall_out   <= sout_r;
  need_reset  <= wedge_r;
  n_cbw       <= std_logic_vector(cbw_c);
  n_pass      <= std_logic_vector(pass_c);
  n_fail      <= std_logic_vector(fail_c);
  n_phase     <= std_logic_vector(phase_c);
  n_stall     <= std_logic_vector(stall_c);
  n_invalid   <= std_logic_vector(inval_c);

  process (clk, rst_n)
  begin
    if rst_n = '0' then
      st      <= S_IDLE;
      tag_r   <= (others => '0');
      res_r   <= (others => '0');
      sts_r   <= ST_PASS;
      csw_r   <= '0';
      sin_r   <= '0';
      sout_r  <= '0';
      wedge_r <= '0';
      cbw_c   <= (others => '0');
      pass_c  <= (others => '0');
      fail_c  <= (others => '0');
      phase_c <= (others => '0');
      stall_c <= (others => '0');
      inval_c <= (others => '0');
    elsif rising_edge(clk) then
      csw_r  <= '0';
      sin_r  <= '0';
      sout_r <= '0';

      case st is

        when S_IDLE =>
          if cbw_valid = '1' then
            cbw_c <= cbw_c + 1;
            if cbw_ok = '0' then
              -- Not a CBW. Stall both ways and wedge until Reset Recovery;
              -- answering anything else would invent a reply to a command
              -- that was never received.
              st      <= S_WEDGE;
              wedge_r <= '1';
              sin_r   <= '1';
              sout_r  <= '1';
              inval_c <= inval_c + 1;
            else
              -- THE TAG IS CAPTURED HERE and echoed unchanged. A device
              -- that regenerates it, or echoes the previous one, breaks
              -- every host with more than one command in flight.
              tag_r <= cbw_tag;
              res_r <= residue;
              if phase_err = '1' then
                sts_r   <= ST_PHASE;
                phase_c <= phase_c + 1;
                if h_in = '1'  then sin_r  <= '1'; end if;
                if h_out = '1' then sout_r <= '1'; end if;
                stall_c <= stall_c + n_stall_now;
                st <= S_CSW;
              else
                if dev_fail = '1' then
                  sts_r  <= ST_FAIL;
                  fail_c <= fail_c + 1;
                else
                  sts_r  <= ST_PASS;
                  pass_c <= pass_c + 1;
                end if;
                if short_in  = '1' then sin_r  <= '1'; end if;
                if short_out = '1' then sout_r <= '1'; end if;
                stall_c <= stall_c + n_stall_now;
                if h_none = '1' and d_none = '1' then
                  st <= S_CSW;
                else
                  st <= S_DATA;
                end if;
              end if;
            end if;
          end if;

        -- The data phase is not modelled byte by byte; what the transport
        -- owes the host is the LENGTH decision above, already fixed.
        when S_DATA =>
          st <= S_CSW;

        when S_CSW =>
          csw_r <= '1';
          st    <= S_IDLE;

        -- Wedged. Only a reset gets out, which is what Reset Recovery
        -- means: the host clears both stalls and starts again.
        when S_WEDGE =>
          sin_r  <= '1';
          sout_r <= '1';

      end case;
    end if;
  end process;

end architecture;