USB 3.x vs USB 2.0 Differences

   "Is this a SuperSpeed device?"

  usb3_capability_resolve

  what the device CLAIMS            what the LINK did
  ----------------------            -----------------
  dev_ss_capable                    port_ss_capable
  bos_present                       ss_link_up
  unit_loads_req  [2:0]             usb2_speed  [1:0]
  self_powered

  outputs
  -------
  ss_capable_reported    <- the claim.  Gates nothing.
  ss_operating           <- the truth.  Gates everything below.

  op_mode          [2:0]   NONE / LOW / FULL / HIGH / SUPER
  credit_flow              0 = host polls,  1 = credits
  async_notify             0 = NAK,         1 = NRDY / ERDY
  burst_allowed
  streams_allowed
  link_pm_u1u2             0 = bus suspend, 1 = U1 / U2

  unit_load_ma     [7:0]   100 or 150
  unit_loads_grant [2:0]   after BOTH ceilings are applied
  max_power_ma     [9:0]   grant x unit load, up to 900
  power_capped

  n_superspeed     [31:0]
  n_fallback       [31:0]  <- the diagnostic that earns its area
  n_capped         [31:0]
  n_unconfigured   [31:0]

  2 (dev_ss_capable)  x  2 (bos_present)  x  2 (port_ss_capable)
    x  2 (ss_link_up)  x  4 (usb2_speed)  x  8 (unit_loads_req)
    x  2 (self_powered)

    =  1024 points, ALL of them reachable

// usb3_capability_resolve -- which mechanism applies at which speed, and the
// one question software keeps answering with the wrong input.
//
// USB 3 did not replace USB 2. It added a second, parallel bus in the same
// cable (Chapter 20.2), and a device can end up operating on either one. Every
// mechanism the two buses define differs:
//
//              USB 2                    SuperSpeed
//   flow       host POLLS the device    device is GIVEN CREDITS
//   busy       device answers NAK       device sends NRDY, later ERDY
//   unit load  100 mA                   150 mA
//   bursting   no                       yes, up to bMaxBurst packets
//   streams    no                       yes, for bulk endpoints
//   idle       bus-wide SUSPEND         per-link U1 / U2
//
// THE QUESTION, AND THE WRONG INPUT
//
// "Is this a SuperSpeed device?" is not a question about the device. It is a
// question about THE LINK THAT WAS ACTUALLY ESTABLISHED.
//
// A SuperSpeed-capable device plugged into a USB 2 hub, or into a USB 3 port
// with a broken SuperSpeed pair, or into a cable missing the SuperSpeed
// wires, IS A USB 2 DEVICE. It reports SuperSpeed capability in its BOS
// descriptor, it is physically capable of SuperSpeed, and none of that is
// relevant: the link trained at high speed, so high-speed rules apply.
//
// So this module produces TWO separate outputs that are easy to conflate and
// must never be:
//
//   ss_capable_reported   what the descriptors CLAIM. Read from the device.
//   ss_operating          what is ACTUALLY running. Requires the device to be
//                         capable, the port to be capable, AND the SuperSpeed
//                         link to have trained (Chapter 20.3).
//
// Every mechanism selection below is gated on ss_operating. A design that
// gates any of them on ss_capable_reported enables SuperSpeed behaviour on a
// USB 2 link -- which is the failure Chapter 20.2 warned about, arriving from
// the software side instead of the hardware side.
module usb3_capability_resolve (
  input  wire        clk,
  input  wire        rst_n,

  // what the device claims
  input  wire        dev_ss_capable,   // the device's hardware supports SS
  input  wire        bos_present,      // and it published a BOS descriptor
  input  wire [2:0]  unit_loads_req,   // bMaxPower, in unit loads (0..7)
  input  wire        self_powered,     // it has its own supply

  // what the link actually did
  input  wire        port_ss_capable,  // the port/hub offers a SS pair
  input  wire        ss_link_up,       // and the SS link TRAINED (ch 20.3)
  input  wire [1:0]  usb2_speed,       // the USB 2 link that did come up

  output wire        ss_capable_reported,
  output wire        ss_operating,

  output wire [2:0]  op_mode,
  output wire        credit_flow,      // 0 = host polls, 1 = credits
  output wire        async_notify,     // 0 = NAK, 1 = NRDY/ERDY
  output wire        burst_allowed,
  output wire        streams_allowed,
  output wire        link_pm_u1u2,     // 0 = bus suspend only, 1 = U1/U2

  output wire [7:0]  unit_load_ma,     // 100 or 150
  output wire [2:0]  unit_loads_grant,
  output wire [9:0]  max_power_ma,
  output wire        power_capped,

  output reg  [31:0] n_superspeed,
  output reg  [31:0] n_fallback,       // SS-capable but NOT operating at SS
  output reg  [31:0] n_capped,
  output reg  [31:0] n_unconfigured
);
  localparam [1:0] SP_NONE = 2'd0, SP_LOW = 2'd1, SP_FULL = 2'd2, SP_HIGH = 2'd3;

  localparam [2:0] OP_NONE  = 3'd0,
                   OP_LOW   = 3'd1,
                   OP_FULL  = 3'd2,
                   OP_HIGH  = 3'd3,
                   OP_SUPER = 3'd4;

  // ---- The two capability answers, and they are NOT the same question ----

  // What software can read out of the descriptors. Useful for logging and for
  // telling a user "this device would be faster in a USB 3 port". Useful for
  // NOTHING ELSE.
  assign ss_capable_reported = dev_ss_capable && bos_present;

  // What is actually running. All three terms are required: a capable device,
  // a capable port, and a link that trained. Drop any one of them and the
  // module starts enabling SuperSpeed mechanisms on a USB 2 link.
  assign ss_operating = dev_ss_capable && port_ss_capable && ss_link_up;

  // ---- Operating mode: SuperSpeed if it trained, otherwise whatever USB 2
  // ---- actually negotiated. NOT "high speed because it is a USB 3 device".
  assign op_mode = ss_operating          ? OP_SUPER
                 : (usb2_speed == SP_HIGH) ? OP_HIGH
                 : (usb2_speed == SP_FULL) ? OP_FULL
                 : (usb2_speed == SP_LOW)  ? OP_LOW
                                           : OP_NONE;

  // ---- Every mechanism, gated on ss_operating and never on the claim ----
  assign credit_flow     = ss_operating;
  assign async_notify    = ss_operating;
  assign burst_allowed   = ss_operating;
  assign streams_allowed = ss_operating;
  assign link_pm_u1u2    = ss_operating;

  // ---- Power: the unit load is 150 mA on SuperSpeed, 100 mA on USB 2 ----
  assign unit_load_ma = ss_operating ? 8'd150 : 8'd100;

  // Two independent ceilings apply, and the lower one wins.
  //
  //   a SELF-POWERED device may draw at most ONE unit load from the bus --
  //   it has its own supply and the bus budget is for everyone else
  //
  //   a BUS-POWERED device may draw 6 unit loads on SuperSpeed, 5 on USB 2
  wire [2:0] mode_ceiling = ss_operating ? 3'd6 : 3'd5;
  wire [2:0] ceiling      = self_powered ? 3'd1 : mode_ceiling;

  assign unit_loads_grant = (unit_loads_req > ceiling) ? ceiling
                                                      : unit_loads_req;
  assign power_capped     = (unit_loads_req > ceiling);

  // 6 unit loads x 150 mA = 900 mA, which is why this is 10 bits wide.
  assign max_power_ma = {7'd0, unit_loads_grant} * {2'd0, unit_load_ma};

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      n_superspeed   <= 32'd0;
      n_fallback     <= 32'd0;
      n_capped       <= 32'd0;
      n_unconfigured <= 32'd0;
    end else begin
      if (ss_operating) n_superspeed <= n_superspeed + 32'd1;
      // THE diagnostic worth having in real silicon: a device that could have
      // run at SuperSpeed and did not. Every one of these is a cable, a hub,
      // or a training failure, and without this counter it is invisible --
      // the device works, just at a twentieth of the speed.
      if (ss_capable_reported && !ss_operating)
        n_fallback <= n_fallback + 32'd1;
      if (power_capped)        n_capped       <= n_capped + 32'd1;
      if (op_mode == OP_NONE)  n_unconfigured <= n_unconfigured + 32'd1;
    end
  end
endmodule

// usb3_capability_resolve -- which mechanism applies at which speed, and the
// one question software keeps answering with the wrong input.
//
// USB 3 did not replace USB 2. It added a second, parallel bus in the same
// cable (Chapter 20.2), and a device can end up operating on either one.
//
//              USB 2                    SuperSpeed
//   flow       host POLLS the device    device is GIVEN CREDITS
//   busy       device answers NAK       device sends NRDY, later ERDY
//   unit load  100 mA                   150 mA
//   bursting   no                       yes, up to bMaxBurst packets
//   streams    no                       yes, for bulk endpoints
//   idle       bus-wide SUSPEND         per-link U1 / U2
//
// The SystemVerilog build separates the two capability answers into an enum
// and a bit, which makes the distinction visible at every call site: you
// cannot pass an op_mode_e where a "did it train" bit is wanted.
package usb3_cap_pkg;
  // The USB 2 speed that was negotiated on the D+/D- pair.
  typedef enum logic [1:0] {
    SP_NONE = 2'd0,   // nothing came up on USB 2 either
    SP_LOW  = 2'd1,
    SP_FULL = 2'd2,
    SP_HIGH = 2'd3
  } usb2_speed_e;

  // What is ACTUALLY running. OP_SUPER is reachable only through a trained
  // SuperSpeed link -- never through a descriptor.
  typedef enum logic [2:0] {
    OP_NONE  = 3'd0,
    OP_LOW   = 3'd1,
    OP_FULL  = 3'd2,
    OP_HIGH  = 3'd3,
    OP_SUPER = 3'd4
  } op_mode_e;

  // The two ceilings on bus current, in unit loads.
  parameter int unsigned UL_CEIL_SS   = 6;  // bus-powered, SuperSpeed
  parameter int unsigned UL_CEIL_USB2 = 5;  // bus-powered, USB 2
  parameter int unsigned UL_CEIL_SELF = 1;  // self-powered, either bus

  parameter int unsigned UL_MA_SS   = 150;
  parameter int unsigned UL_MA_USB2 = 100;
endpackage

// THE QUESTION, AND THE WRONG INPUT
//
// "Is this a SuperSpeed device?" is not a question about the device. It is a
// question about THE LINK THAT WAS ACTUALLY ESTABLISHED.
//
// A SuperSpeed-capable device plugged into a USB 2 hub, or into a USB 3 port
// with a broken SuperSpeed pair, or through a cable missing the SuperSpeed
// wires, IS A USB 2 DEVICE. It reports SuperSpeed capability in its BOS
// descriptor, it is physically capable of SuperSpeed, and none of that is
// relevant: the link trained at high speed, so high-speed rules apply.
//
// Hence two outputs that are easy to conflate and must never be:
//
//   ss_capable_reported   what the descriptors CLAIM. Read from the device.
//   ss_operating          what is ACTUALLY running. Requires a capable
//                         device, a capable port, AND a trained link.
module usb3_capability_resolve
  import usb3_cap_pkg::*;
(
  input  logic        clk,
  input  logic        rst_n,

  // what the device claims
  input  logic        dev_ss_capable,
  input  logic        bos_present,
  input  logic [2:0]  unit_loads_req,
  input  logic        self_powered,

  // what the link actually did
  input  logic        port_ss_capable,
  input  logic        ss_link_up,
  input  usb2_speed_e usb2_speed,

  output logic        ss_capable_reported,
  output logic        ss_operating,

  output op_mode_e    op_mode,
  output logic        credit_flow,
  output logic        async_notify,
  output logic        burst_allowed,
  output logic        streams_allowed,
  output logic        link_pm_u1u2,

  output logic [7:0]  unit_load_ma,
  output logic [2:0]  unit_loads_grant,
  output logic [9:0]  max_power_ma,
  output logic        power_capped,

  output logic [31:0] n_superspeed,
  output logic [31:0] n_fallback,
  output logic [31:0] n_capped,
  output logic [31:0] n_unconfigured
);
  op_mode_e  op_mode_c;
  logic [2:0] ceiling;

  // ---- The two capability answers, and they are NOT the same question ----

  // What software can read out of the descriptors. Useful for logging and for
  // telling a user "this device would be faster in a USB 3 port". Useful for
  // NOTHING ELSE.
  assign ss_capable_reported = dev_ss_capable && bos_present;

  // What is actually running. All three terms are required.
  assign ss_operating = dev_ss_capable && port_ss_capable && ss_link_up;

  // ---- Operating mode: SuperSpeed if it trained, otherwise whatever USB 2
  // ---- actually negotiated. NOT "high speed because it is a USB 3 device".
  always_comb begin
    if (ss_operating) op_mode_c = OP_SUPER;
    else begin
      case (usb2_speed)
        SP_HIGH: op_mode_c = OP_HIGH;
        SP_FULL: op_mode_c = OP_FULL;
        SP_LOW:  op_mode_c = OP_LOW;
        default: op_mode_c = OP_NONE;
      endcase
    end
  end
  assign op_mode = op_mode_c;

  // ---- Every mechanism, gated on ss_operating and never on the claim ----
  assign credit_flow     = ss_operating;
  assign async_notify    = ss_operating;
  assign burst_allowed   = ss_operating;
  assign streams_allowed = ss_operating;
  assign link_pm_u1u2    = ss_operating;

  // ---- Power: the unit load is 150 mA on SuperSpeed, 100 mA on USB 2 ----
  assign unit_load_ma = ss_operating ? 8'(UL_MA_SS) : 8'(UL_MA_USB2);

  // Two independent ceilings apply and the LOWER one wins:
  //   a SELF-POWERED device may draw at most ONE unit load from the bus
  //   a BUS-POWERED device may draw 6 unit loads on SS, 5 on USB 2
  always_comb begin
    ceiling = ss_operating ? 3'(UL_CEIL_SS) : 3'(UL_CEIL_USB2);
    if (self_powered && 3'(UL_CEIL_SELF) < ceiling)
      ceiling = 3'(UL_CEIL_SELF);
  end

  assign unit_loads_grant = (unit_loads_req > ceiling) ? ceiling
                                                      : unit_loads_req;
  assign power_capped     = (unit_loads_req > ceiling);

  // 6 unit loads x 150 mA = 900 mA, which is why this is 10 bits wide.
  assign max_power_ma = 10'(unit_loads_grant) * 10'(unit_load_ma);

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      n_superspeed   <= '0;
      n_fallback     <= '0;
      n_capped       <= '0;
      n_unconfigured <= '0;
    end else begin
      if (ss_operating) n_superspeed <= n_superspeed + 1;
      // THE diagnostic worth having in real silicon: a device that could have
      // run at SuperSpeed and did not. Every one of these is a cable, a hub
      // or a training failure, and without this counter it is invisible --
      // the device works, just at a twentieth of the speed.
      if (ss_capable_reported && !ss_operating) n_fallback <= n_fallback + 1;
      if (power_capped)            n_capped       <= n_capped + 1;
      if (op_mode_c == OP_NONE)    n_unconfigured <= n_unconfigured + 1;
    end
  end
endmodule

-- usb3_capability_resolve -- which mechanism applies at which speed, and the
-- one question software keeps answering with the wrong input.
--
-- USB 3 did not replace USB 2. It added a second, parallel bus in the same
-- cable (Chapter 20.2), and a device can end up operating on either one.
--
--              USB 2                    SuperSpeed
--   flow       host POLLS the device    device is GIVEN CREDITS
--   busy       device answers NAK       device sends NRDY, later ERDY
--   unit load  100 mA                   150 mA
--   bursting   no                       yes, up to bMaxBurst packets
--   streams    no                       yes, for bulk endpoints
--   idle       bus-wide SUSPEND         per-link U1 / U2
--
-- VHDL's type system is the reason this version is worth reading alongside
-- the other two: op_mode_t is an enumerated type whose OP_SUPER value cannot
-- be produced by accident, and the two capability answers are separate
-- signals of separate meaning rather than two bits that look alike.
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

package usb3_cap_pkg is
  -- The USB 2 speed that was negotiated on the D+/D- pair.
  type usb2_speed_t is (SP_NONE, SP_LOW, SP_FULL, SP_HIGH);

  -- What is ACTUALLY running. OP_SUPER is reachable only through a trained
  -- SuperSpeed link -- never through a descriptor.
  type op_mode_t is (OP_NONE, OP_LOW, OP_FULL, OP_HIGH, OP_SUPER);

  -- The two ceilings on bus current, in unit loads.
  constant UL_CEIL_SS   : natural := 6;  -- bus-powered, SuperSpeed
  constant UL_CEIL_USB2 : natural := 5;  -- bus-powered, USB 2
  constant UL_CEIL_SELF : natural := 1;  -- self-powered, either bus

  constant UL_MA_SS   : natural := 150;
  constant UL_MA_USB2 : natural := 100;

  function speed_decode(s : std_logic_vector(1 downto 0)) return usb2_speed_t;
  function mode_code(m : op_mode_t) return std_logic_vector;
end package;

package body usb3_cap_pkg is
  function speed_decode(s : std_logic_vector(1 downto 0)) return usb2_speed_t is
  begin
    case s is
      when "00"   => return SP_NONE;
      when "01"   => return SP_LOW;
      when "10"   => return SP_FULL;
      when others => return SP_HIGH;
    end case;
  end function;

  function mode_code(m : op_mode_t) return std_logic_vector is
  begin
    return std_logic_vector(to_unsigned(op_mode_t'pos(m), 3));
  end function;
end package body;

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

-- THE QUESTION, AND THE WRONG INPUT
--
-- "Is this a SuperSpeed device?" is not a question about the device. It is a
-- question about THE LINK THAT WAS ACTUALLY ESTABLISHED.
--
-- A SuperSpeed-capable device plugged into a USB 2 hub, or into a USB 3 port
-- with a broken SuperSpeed pair, or through a cable missing the SuperSpeed
-- wires, IS A USB 2 DEVICE. It reports SuperSpeed capability in its BOS
-- descriptor, it is physically capable of SuperSpeed, and none of that is
-- relevant: the link trained at high speed, so high-speed rules apply.
--
-- Hence two outputs that are easy to conflate and must never be:
--
--   ss_capable_reported   what the descriptors CLAIM. Read from the device.
--   ss_operating          what is ACTUALLY running. Requires a capable
--                         device, a capable port, AND a trained link.
entity usb3_capability_resolve is
  port (
    clk                 : in  std_logic;
    rst_n               : in  std_logic;

    -- what the device claims
    dev_ss_capable      : in  std_logic;
    bos_present         : in  std_logic;
    unit_loads_req      : in  std_logic_vector(2 downto 0);
    self_powered        : in  std_logic;

    -- what the link actually did
    port_ss_capable     : in  std_logic;
    ss_link_up          : in  std_logic;
    usb2_speed          : in  std_logic_vector(1 downto 0);

    ss_capable_reported : out std_logic;
    ss_operating        : out std_logic;

    op_mode             : out std_logic_vector(2 downto 0);
    credit_flow         : out std_logic;
    async_notify        : out std_logic;
    burst_allowed       : out std_logic;
    streams_allowed     : out std_logic;
    link_pm_u1u2        : out std_logic;

    unit_load_ma        : out std_logic_vector(7 downto 0);
    unit_loads_grant    : out std_logic_vector(2 downto 0);
    max_power_ma        : out std_logic_vector(9 downto 0);
    power_capped        : out std_logic;

    n_superspeed        : out std_logic_vector(31 downto 0);
    n_fallback          : out std_logic_vector(31 downto 0);
    n_capped            : out std_logic_vector(31 downto 0);
    n_unconfigured      : out std_logic_vector(31 downto 0)
  );
end entity;

architecture rtl of usb3_capability_resolve is
  signal rep    : std_logic;
  signal oper   : std_logic;
  signal mode   : op_mode_t;
  signal ul_ma  : natural range 0 to 255;
  signal ceil_u : natural range 0 to 7;
  signal grant  : natural range 0 to 7;
  signal capped : std_logic;

  signal ss_r, fb_r, cap_r, unc_r : unsigned(31 downto 0) := (others => '0');
begin
  -- ---- The two capability answers, and they are NOT the same question ----

  -- What software can read out of the descriptors. Useful for logging and for
  -- telling a user "this device would be faster in a USB 3 port". Useful for
  -- NOTHING ELSE.
  rep <= dev_ss_capable and bos_present;

  -- What is actually running. All three terms are required.
  oper <= dev_ss_capable and port_ss_capable and ss_link_up;

  ss_capable_reported <= rep;
  ss_operating        <= oper;

  -- ---- Operating mode: SuperSpeed if it trained, otherwise whatever USB 2
  -- ---- actually negotiated. NOT "high speed because it is a USB 3 device".
  mode_sel : process (oper, usb2_speed)
  begin
    if oper = '1' then
      mode <= OP_SUPER;
    else
      case speed_decode(usb2_speed) is
        when SP_HIGH => mode <= OP_HIGH;
        when SP_FULL => mode <= OP_FULL;
        when SP_LOW  => mode <= OP_LOW;
        when SP_NONE => mode <= OP_NONE;
      end case;
    end if;
  end process;

  op_mode <= mode_code(mode);

  -- ---- Every mechanism, gated on ss_operating and never on the claim ----
  credit_flow     <= oper;
  async_notify    <= oper;
  burst_allowed   <= oper;
  streams_allowed <= oper;
  link_pm_u1u2    <= oper;

  -- ---- Power: the unit load is 150 mA on SuperSpeed, 100 mA on USB 2 ----
  ul_ma <= UL_MA_SS when oper = '1' else UL_MA_USB2;

  -- Two independent ceilings apply and the LOWER one wins:
  --   a SELF-POWERED device may draw at most ONE unit load from the bus
  --   a BUS-POWERED device may draw 6 unit loads on SS, 5 on USB 2
  ceiling_sel : process (oper, self_powered)
    variable c : natural range 0 to 7;
  begin
    if oper = '1' then
      c := UL_CEIL_SS;
    else
      c := UL_CEIL_USB2;
    end if;
    if self_powered = '1' and UL_CEIL_SELF < c then
      c := UL_CEIL_SELF;
    end if;
    ceil_u <= c;
  end process;

  grant_sel : process (unit_loads_req, ceil_u)
    variable req : natural range 0 to 7;
  begin
    req := to_integer(unsigned(unit_loads_req));
    if req > ceil_u then
      grant  <= ceil_u;
      capped <= '1';
    else
      grant  <= req;
      capped <= '0';
    end if;
  end process;

  unit_loads_grant <= std_logic_vector(to_unsigned(grant, 3));
  unit_load_ma     <= std_logic_vector(to_unsigned(ul_ma, 8));
  power_capped     <= capped;

  -- 6 unit loads x 150 mA = 900 mA, which is why this is 10 bits wide. The
  -- multiply is done in the integer domain deliberately: an unsigned * natural
  -- in VHDL returns a vector as wide as the two operands combined, which is a
  -- runtime length error waiting to happen on an output port.
  max_power_ma <= std_logic_vector(to_unsigned(grant * ul_ma, 10));

  counters : process (clk, rst_n)
  begin
    if rst_n = '0' then
      ss_r  <= (others => '0');
      fb_r  <= (others => '0');
      cap_r <= (others => '0');
      unc_r <= (others => '0');
    elsif rising_edge(clk) then
      if oper = '1' then
        ss_r <= ss_r + 1;
      end if;
      -- THE diagnostic worth having in real silicon: a device that could have
      -- run at SuperSpeed and did not. Every one of these is a cable, a hub
      -- or a training failure, and without this counter it is invisible --
      -- the device works, just at a twentieth of the speed.
      if rep = '1' and oper = '0' then
        fb_r <= fb_r + 1;
      end if;
      if capped = '1' then
        cap_r <= cap_r + 1;
      end if;
      if mode = OP_NONE then
        unc_r <= unc_r + 1;
      end if;
    end if;
  end process;

  n_superspeed   <= std_logic_vector(ss_r);
  n_fallback     <= std_logic_vector(fb_r);
  n_capped       <= std_logic_vector(cap_r);
  n_unconfigured <= std_logic_vector(unc_r);
end architecture;

-- WRONG: unsigned * natural in VHDL returns a vector as WIDE AS THE TWO
-- OPERANDS COMBINED, so this is a 3 + 8 = 11-bit result assigned to a
-- 10-bit port, and nvc raises a length error at RUNTIME, not at analysis.
max_power_ma <= std_logic_vector(unsigned(unit_loads_grant) * ul_ma);

-- RIGHT: do the arithmetic in the integer domain and size the result once.
max_power_ma <= std_logic_vector(to_unsigned(grant * ul_ma, 10));

`timescale 1ns/1ps
module tb_cr_v;
  reg clk=0, rst_n=0;
  reg dss=0, bos=0, sp=0, pss=0, slu=0;
  reg [2:0] ulr=0;
  reg [1:0] u2s=0;
  wire ss_capable_reported, ss_operating;
  wire [2:0] op_mode;
  wire credit_flow, async_notify, burst_allowed, streams_allowed, link_pm_u1u2;
  wire [7:0] unit_load_ma;
  wire [2:0] unit_loads_grant;
  wire [9:0] max_power_ma;
  wire power_capped;
  wire [31:0] n_superspeed, n_fallback, n_capped, n_unconfigured;
  always #5 clk=~clk;

  usb3_capability_resolve dut (
    .clk(clk), .rst_n(rst_n), .dev_ss_capable(dss), .bos_present(bos),
    .unit_loads_req(ulr), .self_powered(sp), .port_ss_capable(pss),
    .ss_link_up(slu), .usb2_speed(u2s),
    .ss_capable_reported(ss_capable_reported), .ss_operating(ss_operating),
    .op_mode(op_mode), .credit_flow(credit_flow), .async_notify(async_notify),
    .burst_allowed(burst_allowed), .streams_allowed(streams_allowed),
    .link_pm_u1u2(link_pm_u1u2), .unit_load_ma(unit_load_ma),
    .unit_loads_grant(unit_loads_grant), .max_power_ma(max_power_ma),
    .power_capped(power_capped), .n_superspeed(n_superspeed),
    .n_fallback(n_fallback), .n_capped(n_capped),
    .n_unconfigured(n_unconfigured));

  localparam [1:0] SP_NONE=0, SP_LOW=1, SP_FULL=2, SP_HIGH=3;
  localparam [2:0] OP_NONE=0, OP_LOW=1, OP_FULL=2, OP_HIGH=3, OP_SUPER=4;

  integer errors=0, i, a, b, c, d, e, f, g;
  integer n_exh=0;
  integer n_op [0:4];
  integer n_ss=0, n_fb=0, n_cap=0, n_selfcap=0, n_claim_only=0;
  integer m_ss, m_fb, m_cap, m_unc;

  task check(input cond, input [639:0] msg);
    begin if (!cond) begin errors=errors+1;
      if (errors <= 25)
        $display("  FAIL: %0s (dss=%b bos=%b pss=%b slu=%b u2s=%0d ulr=%0d sp=%b | op=%0d ssop=%b grant=%0d ul=%0d pwr=%0d, t=%0t)",
                 msg, dss, bos, pss, slu, u2s, ulr, sp, op_mode, ss_operating,
                 unit_loads_grant, unit_load_ma, max_power_ma, $time);
    end end
  endtask

  task check_comb;
    reg e_rep, e_op;
    integer e_mode, e_ul, e_ceil, e_grant, e_pwr;
    reg e_cap;
    begin
      // The reference model is deliberately built the other way round: it
      // computes the ceiling with an explicit min() over both limits rather
      // than a nested ternary, and derives the mode with a case.
      e_rep = dss && bos;
      e_op  = dss && pss && slu;

      case (u2s)
        SP_HIGH: e_mode = OP_HIGH;
        SP_FULL: e_mode = OP_FULL;
        SP_LOW:  e_mode = OP_LOW;
        default: e_mode = OP_NONE;
      endcase
      if (e_op) e_mode = OP_SUPER;

      e_ul = e_op ? 150 : 100;

      // both ceilings, lowest wins
      e_ceil = e_op ? 6 : 5;
      if (sp && 1 < e_ceil) e_ceil = 1;

      e_grant = (ulr > e_ceil) ? e_ceil : ulr;
      e_cap   = (ulr > e_ceil);
      e_pwr   = e_grant * e_ul;

      check(ss_capable_reported === e_rep,
            "ss_capable_reported is the DESCRIPTOR claim");
      check(ss_operating === e_op,
            "ss_operating needs device AND port AND a trained link");
      check(op_mode === e_mode[2:0], "op_mode matches the model");
      check(unit_load_ma === e_ul[7:0], "unit load is 150 on SS, 100 on USB 2");
      check(unit_loads_grant === e_grant[2:0], "unit loads granted match");
      check(power_capped === e_cap, "power_capped matches the model");
      check(max_power_ma === e_pwr[9:0], "max_power_ma matches the model");

      // Every mechanism follows ss_operating, none follows the claim.
      check(credit_flow     === e_op, "credit flow follows ss_operating");
      check(async_notify    === e_op, "ERDY/NRDY follows ss_operating");
      check(burst_allowed   === e_op, "bursting follows ss_operating");
      check(streams_allowed === e_op, "streams follow ss_operating");
      check(link_pm_u1u2    === e_op, "U1/U2 follows ss_operating");

      // ---- SAFETY PROPERTIES, independent of the model ----
      // 1. THE property. Not one mechanism may be enabled by the claim alone.
      if (ss_capable_reported && !ss_operating) begin
        check(!credit_flow && !async_notify && !burst_allowed
              && !streams_allowed && !link_pm_u1u2,
              "a SuperSpeed mechanism was enabled on a USB 2 link");
        check(unit_load_ma === 8'd100,
              "a 150 mA unit load was granted on a USB 2 link");
        check(op_mode !== OP_SUPER,
              "op_mode says SuperSpeed but the link never trained");
      end
      // 2. SuperSpeed operation is impossible without all three terms.
      check(!ss_operating || (dss && pss && slu),
            "ss_operating asserted with a term missing");
      // 3. A self-powered device never draws more than one unit load.
      if (sp)
        check(unit_loads_grant <= 3'd1,
              "a self-powered device was granted more than one unit load");
      // 4. The grant never exceeds the request -- a cap only ever reduces.
      check(unit_loads_grant <= ulr,
            "more unit loads were granted than were requested");
      // 5. The USB 2 ceiling is 5 unit loads (500 mA), never 6.
      if (!ss_operating)
        check(unit_loads_grant <= 3'd5,
              "more than 500 mA granted on a USB 2 link");
      // 6. Power is exactly grant x unit load -- no rounding, no slack.
      check(max_power_ma === (unit_loads_grant * unit_load_ma),
            "max_power_ma is not grant x unit load");
      // 7. An unconfigured port grants nothing and runs nothing.
      if (op_mode === OP_NONE)
        check(!credit_flow && !burst_allowed && !streams_allowed,
              "mechanisms enabled on a port with no link at all");

      if (e_mode >= 0 && e_mode <= 4) n_op[e_mode] = n_op[e_mode] + 1;
      if (e_op) n_ss = n_ss + 1;
      if (e_rep && !e_op) n_fb = n_fb + 1;
      if (e_cap) n_cap = n_cap + 1;
      if (sp && e_cap) n_selfcap = n_selfcap + 1;
      if (e_rep && !e_op && (u2s != SP_NONE)) n_claim_only = n_claim_only + 1;
    end
  endtask

  task step;
    begin
      #1;
      check_comb;
      if (ss_operating) m_ss = m_ss + 1;
      if (ss_capable_reported && !ss_operating) m_fb = m_fb + 1;
      if (power_capped) m_cap = m_cap + 1;
      if (op_mode === OP_NONE) m_unc = m_unc + 1;
      @(posedge clk); #1;
      check(n_superspeed   === m_ss[31:0],  "n_superspeed matches the model");
      check(n_fallback     === m_fb[31:0],  "n_fallback matches the model");
      check(n_capped       === m_cap[31:0], "n_capped matches the model");
      check(n_unconfigured === m_unc[31:0], "n_unconfigured matches the model");
    end
  endtask

  task hard_reset;
    begin
      rst_n=0; dss=0; bos=0; sp=0; pss=0; slu=0; ulr=0; u2s=0;
      @(posedge clk); #1; @(posedge clk); #1; rst_n=1; #1;
      m_ss=0; m_fb=0; m_cap=0; m_unc=0;
    end
  endtask

  initial begin
    for (i=0;i<5;i=i+1) n_op[i]=0;
    hard_reset;
    check(op_mode === OP_NONE, "nothing connected, no operating mode");
    check(!ss_operating, "and nothing is running at SuperSpeed");

    // ===== A. EXHAUSTIVE over the whole resolution =====
    // dev_ss_capable x bos_present x port_ss_capable x ss_link_up
    //   x usb2_speed(4) x unit_loads_req(8) x self_powered
    // = 2 x 2 x 2 x 2 x 4 x 8 x 2 = 1024 points, the complete input space.
    for (a=0;a<2;a=a+1)
     for (b=0;b<2;b=b+1)
      for (c=0;c<2;c=c+1)
       for (d=0;d<2;d=d+1)
        for (e=0;e<4;e=e+1)
         for (f=0;f<8;f=f+1)
          for (g=0;g<2;g=g+1) begin
            dss=a[0]; bos=b[0]; pss=c[0]; slu=d[0];
            u2s=e[1:0]; ulr=f[2:0]; sp=g[0];
            step;
            n_exh = n_exh + 1;
          end
    $display("  exhaustive capability-resolution sweep: %0d of %0d points verified",
             n_exh, 2*2*2*2*4*8*2);

    // ===== B. directed: the scenarios that get argued about =====
    hard_reset;

    // 1. A SuperSpeed device in a SuperSpeed port. Everything on.
    dss=1; bos=1; pss=1; slu=1; u2s=SP_HIGH; ulr=6; sp=0; step;
    check(op_mode === OP_SUPER, "a trained SS link operates at SuperSpeed");
    check(credit_flow && async_notify && burst_allowed && streams_allowed,
          "and every SuperSpeed mechanism is available");
    check(unit_load_ma === 8'd150, "the unit load is 150 mA");
    check(unit_loads_grant === 3'd6, "6 unit loads are allowed");
    check(max_power_ma === 10'd900, "which is 900 mA");
    check(!power_capped, "and nothing was capped");

    // 2. THE case. The SAME device, behind a USB 2 hub. It is a USB 2 device.
    dss=1; bos=1; pss=0; slu=0; u2s=SP_HIGH; ulr=6; sp=0; step;
    check(ss_capable_reported,
          "the descriptors still claim SuperSpeed capability");
    check(!ss_operating, "but nothing SuperSpeed is running");
    check(op_mode === OP_HIGH, "it is a HIGH SPEED device now");
    check(!credit_flow, "the host must POLL it");
    check(!async_notify, "it answers NAK, not NRDY/ERDY");
    check(!burst_allowed && !streams_allowed, "no bursting, no streams");
    check(!link_pm_u1u2, "and idle means bus suspend, not U1/U2");
    check(unit_load_ma === 8'd100, "its unit load is 100 mA");
    check(unit_loads_grant === 3'd5, "capped at 5 unit loads");
    check(max_power_ma === 10'd500, "so 500 mA, not 900");
    check(power_capped, "and the request WAS capped");

    // 3. A SuperSpeed port, a capable device, but training FAILED.
    //    Identical outcome to case 2 -- which is the point.
    dss=1; bos=1; pss=1; slu=0; u2s=SP_HIGH; ulr=6; sp=0; step;
    check(!ss_operating,
          "a capable device in a capable port still is not SuperSpeed if training failed");
    check(op_mode === OP_HIGH, "it fell back to high speed");
    check(unit_load_ma === 8'd100, "with a USB 2 unit load");

    // 4. A device that claims SuperSpeed with NO BOS descriptor.
    dss=1; bos=0; pss=1; slu=1; u2s=SP_HIGH; ulr=2; sp=0; step;
    check(!ss_capable_reported,
          "with no BOS descriptor there is no reported capability");
    check(ss_operating,
          "yet the link trained, so SuperSpeed IS operating -- the link decides");

    // 5. A self-powered SuperSpeed device asking for 6 unit loads.
    dss=1; bos=1; pss=1; slu=1; u2s=SP_HIGH; ulr=6; sp=1; step;
    check(unit_loads_grant === 3'd1,
          "a self-powered device gets ONE unit load whatever it asks for");
    check(max_power_ma === 10'd150, "which is 150 mA on SuperSpeed");
    check(power_capped, "and the request was capped");

    // 6. A low-speed device: no SuperSpeed anything, 100 mA unit load.
    dss=0; bos=0; pss=1; slu=0; u2s=SP_LOW; ulr=1; sp=0; step;
    check(op_mode === OP_LOW, "a low speed device operates at low speed");
    check(unit_load_ma === 8'd100, "with a 100 mA unit load");
    check(max_power_ma === 10'd100, "and 100 mA total");

    // 7. Nothing plugged in at all.
    dss=1; bos=1; pss=1; slu=0; u2s=SP_NONE; ulr=4; sp=0; step;
    check(op_mode === OP_NONE, "no link of either kind means no mode");
    check(!credit_flow && !burst_allowed, "and no mechanisms at all");

    // ===== C. randomised =====
    for (i=0;i<40000;i=i+1) begin
      dss={$random}%2; bos={$random}%2; pss={$random}%2; slu={$random}%2;
      u2s={$random}%4; ulr={$random}%8; sp=({$random}%4)==0;
      step;
    end

    for (i=0;i<5;i=i+1)
      check(n_op[i] > 0, "every operating mode was reached");
    check(n_ss > 1000, "SuperSpeed operation was reached often");
    check(n_fb > 1000, "the SS-capable-but-not-operating case was reached often");
    check(n_selfcap > 100, "self-powered devices were capped");
    check(n_claim_only > 1000,
          "the claim-without-operation case was reached with a live USB 2 link");

    $display("");
    $display("  REACH: exhaustive=%0d | modes: none=%0d low=%0d full=%0d high=%0d super=%0d",
             n_exh, n_op[0], n_op[1], n_op[2], n_op[3], n_op[4]);
    $display("  CASES: ss-operating=%0d fallback=%0d capped=%0d self-capped=%0d claim-only-live=%0d",
             n_ss, n_fb, n_cap, n_selfcap, n_claim_only);
    $display("  COUNTERS: superspeed=%0d fallback=%0d capped=%0d unconfigured=%0d",
             n_superspeed, n_fallback, n_capped, n_unconfigured);
    $display("  [Verilog] usb3_capability_resolve: %0d errors", errors);
    $display("  [Verilog] %0s", errors==0 ? "PASS" : "FAIL");
    $display("");
    $finish;
  end
endmodule

`timescale 1ns/1ps
module tb_cr_sv;
  import usb3_cap_pkg::*;

  logic clk=0, rst_n=0;
  logic dss=0, bos=0, sp=0, pss=0, slu=0;
  logic [2:0] ulr=0;
  usb2_speed_e u2s = SP_NONE;
  logic ss_capable_reported, ss_operating;
  op_mode_e op_mode;
  logic credit_flow, async_notify, burst_allowed, streams_allowed, link_pm_u1u2;
  logic [7:0] unit_load_ma;
  logic [2:0] unit_loads_grant;
  logic [9:0] max_power_ma;
  logic power_capped;
  logic [31:0] n_superspeed, n_fallback, n_capped, n_unconfigured;
  always #5 clk=~clk;

  usb3_capability_resolve dut (
    .clk, .rst_n, .dev_ss_capable(dss), .bos_present(bos),
    .unit_loads_req(ulr), .self_powered(sp), .port_ss_capable(pss),
    .ss_link_up(slu), .usb2_speed(u2s), .ss_capable_reported, .ss_operating,
    .op_mode, .credit_flow, .async_notify, .burst_allowed, .streams_allowed,
    .link_pm_u1u2, .unit_load_ma, .unit_loads_grant, .max_power_ma,
    .power_capped, .n_superspeed, .n_fallback, .n_capped, .n_unconfigured);

  int errors=0, i, a, b, c, d, e, f, g;
  int n_exh=0;
  int n_op [5];
  int n_ss=0, n_fb=0, n_cap=0, n_selfcap=0, n_claim_only=0;
  int m_ss, m_fb, m_cap, m_unc;

  // Icarus seeds $random and $urandom IDENTICALLY, so an unseeded
  // SystemVerilog run replays the Verilog run's stimulus exactly and the two
  // columns stop being independent evidence. Seeding one of them explicitly
  // is what makes the randomised phases three separate samples.
  int urandom_seed = 20251;

  // Icarus will not call .name() on a net, so the enum output is copied into
  // a variable of the same type before being printed.
  task automatic check(input bit cond, input string msg);
    op_mode_e om_v;
    if (!cond) begin
      errors++;
      om_v = op_mode;
      if (errors <= 25)
        $display("  FAIL: %0s (dss=%b bos=%b pss=%b slu=%b u2s=%s ulr=%0d sp=%b | op=%s ssop=%b grant=%0d ul=%0d pwr=%0d, t=%0t)",
                 msg, dss, bos, pss, slu, u2s.name(), ulr, sp, om_v.name(),
                 ss_operating, unit_loads_grant, unit_load_ma, max_power_ma,
                 $time);
    end
  endtask

  task automatic check_comb;
    bit e_rep, e_op, e_cap;
    op_mode_e e_mode;
    int e_ul, e_ceil, e_grant, e_pwr;
    begin
      // The reference model is deliberately built the other way round: it
      // computes the ceiling with an explicit min over both limits rather
      // than the design's conditional narrowing.
      e_rep = dss && bos;
      e_op  = dss && pss && slu;

      case (u2s)
        SP_HIGH: e_mode = OP_HIGH;
        SP_FULL: e_mode = OP_FULL;
        SP_LOW:  e_mode = OP_LOW;
        default: e_mode = OP_NONE;
      endcase
      if (e_op) e_mode = OP_SUPER;

      e_ul = e_op ? int'(UL_MA_SS) : int'(UL_MA_USB2);

      e_ceil = e_op ? int'(UL_CEIL_SS) : int'(UL_CEIL_USB2);
      if (sp && int'(UL_CEIL_SELF) < e_ceil) e_ceil = int'(UL_CEIL_SELF);

      e_grant = (int'(ulr) > e_ceil) ? e_ceil : int'(ulr);
      e_cap   = (int'(ulr) > e_ceil);
      e_pwr   = e_grant * e_ul;

      check(ss_capable_reported === e_rep,
            "ss_capable_reported is the DESCRIPTOR claim");
      check(ss_operating === e_op,
            "ss_operating needs device AND port AND a trained link");
      check(op_mode === e_mode, "op_mode matches the model");
      check(unit_load_ma === 8'(e_ul), "unit load is 150 on SS, 100 on USB 2");
      check(unit_loads_grant === 3'(e_grant), "unit loads granted match");
      check(power_capped === e_cap, "power_capped matches the model");
      check(max_power_ma === 10'(e_pwr), "max_power_ma matches the model");

      // Every mechanism follows ss_operating, none follows the claim.
      check(credit_flow     === e_op, "credit flow follows ss_operating");
      check(async_notify    === e_op, "ERDY/NRDY follows ss_operating");
      check(burst_allowed   === e_op, "bursting follows ss_operating");
      check(streams_allowed === e_op, "streams follow ss_operating");
      check(link_pm_u1u2    === e_op, "U1/U2 follows ss_operating");

      // ---- SAFETY PROPERTIES, independent of the model ----
      // 1. THE property. Not one mechanism may be enabled by the claim alone.
      if (ss_capable_reported && !ss_operating) begin
        check(!credit_flow && !async_notify && !burst_allowed
              && !streams_allowed && !link_pm_u1u2,
              "a SuperSpeed mechanism was enabled on a USB 2 link");
        check(unit_load_ma === 8'd100,
              "a 150 mA unit load was granted on a USB 2 link");
        check(op_mode !== OP_SUPER,
              "op_mode says SuperSpeed but the link never trained");
      end
      // 2. SuperSpeed operation is impossible without all three terms.
      check(!ss_operating || (dss && pss && slu),
            "ss_operating asserted with a term missing");
      // 3. A self-powered device never draws more than one unit load.
      if (sp)
        check(unit_loads_grant <= 3'd1,
              "a self-powered device was granted more than one unit load");
      // 4. The grant never exceeds the request -- a cap only ever reduces.
      check(unit_loads_grant <= ulr,
            "more unit loads were granted than were requested");
      // 5. The USB 2 ceiling is 5 unit loads (500 mA), never 6.
      if (!ss_operating)
        check(unit_loads_grant <= 3'd5,
              "more than 500 mA granted on a USB 2 link");
      // 6. Power is exactly grant x unit load -- no rounding, no slack.
      check(max_power_ma === 10'(unit_loads_grant) * 10'(unit_load_ma),
            "max_power_ma is not grant x unit load");
      // 7. An unconfigured port grants nothing and runs nothing.
      if (op_mode === OP_NONE)
        check(!credit_flow && !burst_allowed && !streams_allowed,
              "mechanisms enabled on a port with no link at all");

      n_op[int'(e_mode)] = n_op[int'(e_mode)] + 1;
      if (e_op) n_ss++;
      if (e_rep && !e_op) n_fb++;
      if (e_cap) n_cap++;
      if (sp && e_cap) n_selfcap++;
      if (e_rep && !e_op && (u2s != SP_NONE)) n_claim_only++;
    end
  endtask

  task automatic step;
    begin
      #1;
      check_comb;
      if (ss_operating) m_ss++;
      if (ss_capable_reported && !ss_operating) m_fb++;
      if (power_capped) m_cap++;
      if (op_mode === OP_NONE) m_unc++;
      @(posedge clk); #1;
      check(n_superspeed   === 32'(m_ss),  "n_superspeed matches the model");
      check(n_fallback     === 32'(m_fb),  "n_fallback matches the model");
      check(n_capped       === 32'(m_cap), "n_capped matches the model");
      check(n_unconfigured === 32'(m_unc), "n_unconfigured matches the model");
    end
  endtask

  task automatic hard_reset;
    begin
      rst_n=0; dss=0; bos=0; sp=0; pss=0; slu=0; ulr=0; u2s=SP_NONE;
      @(posedge clk); #1; @(posedge clk); #1; rst_n=1; #1;
      m_ss=0; m_fb=0; m_cap=0; m_unc=0;
    end
  endtask

  initial begin
    void'($urandom(urandom_seed));
    foreach (n_op[i]) n_op[i]=0;
    hard_reset;
    check(op_mode === OP_NONE, "nothing connected, no operating mode");
    check(!ss_operating, "and nothing is running at SuperSpeed");

    // ===== A. EXHAUSTIVE over the whole resolution =====
    // dev_ss_capable x bos_present x port_ss_capable x ss_link_up
    //   x usb2_speed(4) x unit_loads_req(8) x self_powered
    // = 2 x 2 x 2 x 2 x 4 x 8 x 2 = 1024 points, the complete input space.
    for (a=0;a<2;a++)
     for (b=0;b<2;b++)
      for (c=0;c<2;c++)
       for (d=0;d<2;d++)
        for (e=0;e<4;e++)
         for (f=0;f<8;f++)
          for (g=0;g<2;g++) begin
            dss=a[0]; bos=b[0]; pss=c[0]; slu=d[0];
            u2s=usb2_speed_e'(e[1:0]); ulr=f[2:0]; sp=g[0];
            step;
            n_exh++;
          end
    $display("  exhaustive capability-resolution sweep: %0d of %0d points verified",
             n_exh, 2*2*2*2*4*8*2);

    // ===== B. directed: the scenarios that get argued about =====
    hard_reset;

    // 1. A SuperSpeed device in a SuperSpeed port. Everything on.
    dss=1; bos=1; pss=1; slu=1; u2s=SP_HIGH; ulr=6; sp=0; step;
    check(op_mode === OP_SUPER, "a trained SS link operates at SuperSpeed");
    check(credit_flow && async_notify && burst_allowed && streams_allowed,
          "and every SuperSpeed mechanism is available");
    check(unit_load_ma === 8'd150, "the unit load is 150 mA");
    check(unit_loads_grant === 3'd6, "6 unit loads are allowed");
    check(max_power_ma === 10'd900, "which is 900 mA");
    check(!power_capped, "and nothing was capped");

    // 2. THE case. The SAME device, behind a USB 2 hub. It is a USB 2 device.
    dss=1; bos=1; pss=0; slu=0; u2s=SP_HIGH; ulr=6; sp=0; step;
    check(ss_capable_reported,
          "the descriptors still claim SuperSpeed capability");
    check(!ss_operating, "but nothing SuperSpeed is running");
    check(op_mode === OP_HIGH, "it is a HIGH SPEED device now");
    check(!credit_flow, "the host must POLL it");
    check(!async_notify, "it answers NAK, not NRDY/ERDY");
    check(!burst_allowed && !streams_allowed, "no bursting, no streams");
    check(!link_pm_u1u2, "and idle means bus suspend, not U1/U2");
    check(unit_load_ma === 8'd100, "its unit load is 100 mA");
    check(unit_loads_grant === 3'd5, "capped at 5 unit loads");
    check(max_power_ma === 10'd500, "so 500 mA, not 900");
    check(power_capped, "and the request WAS capped");

    // 3. A SuperSpeed port, a capable device, but training FAILED.
    //    Identical outcome to case 2 -- which is the point.
    dss=1; bos=1; pss=1; slu=0; u2s=SP_HIGH; ulr=6; sp=0; step;
    check(!ss_operating,
          "a capable device in a capable port still is not SuperSpeed if training failed");
    check(op_mode === OP_HIGH, "it fell back to high speed");
    check(unit_load_ma === 8'd100, "with a USB 2 unit load");

    // 4. A device that claims SuperSpeed with NO BOS descriptor.
    dss=1; bos=0; pss=1; slu=1; u2s=SP_HIGH; ulr=2; sp=0; step;
    check(!ss_capable_reported,
          "with no BOS descriptor there is no reported capability");
    check(ss_operating,
          "yet the link trained, so SuperSpeed IS operating -- the link decides");

    // 5. A self-powered SuperSpeed device asking for 6 unit loads.
    dss=1; bos=1; pss=1; slu=1; u2s=SP_HIGH; ulr=6; sp=1; step;
    check(unit_loads_grant === 3'd1,
          "a self-powered device gets ONE unit load whatever it asks for");
    check(max_power_ma === 10'd150, "which is 150 mA on SuperSpeed");
    check(power_capped, "and the request was capped");

    // 6. A low-speed device: no SuperSpeed anything, 100 mA unit load.
    dss=0; bos=0; pss=1; slu=0; u2s=SP_LOW; ulr=1; sp=0; step;
    check(op_mode === OP_LOW, "a low speed device operates at low speed");
    check(unit_load_ma === 8'd100, "with a 100 mA unit load");
    check(max_power_ma === 10'd100, "and 100 mA total");

    // 7. Nothing plugged in at all.
    dss=1; bos=1; pss=1; slu=0; u2s=SP_NONE; ulr=4; sp=0; step;
    check(op_mode === OP_NONE, "no link of either kind means no mode");
    check(!credit_flow && !burst_allowed, "and no mechanisms at all");

    // ===== C. randomised =====
    for (i=0;i<40000;i++) begin
      dss=$urandom%2; bos=$urandom%2; pss=$urandom%2; slu=$urandom%2;
      u2s=usb2_speed_e'($urandom%4); ulr=$urandom%8; sp=($urandom%4)==0;
      step;
    end

    foreach (n_op[i]) check(n_op[i] > 0, "every operating mode was reached");
    check(n_ss > 1000, "SuperSpeed operation was reached often");
    check(n_fb > 1000, "the SS-capable-but-not-operating case was reached often");
    check(n_selfcap > 100, "self-powered devices were capped");
    check(n_claim_only > 1000,
          "the claim-without-operation case was reached with a live USB 2 link");

    $display("");
    $display("  REACH: exhaustive=%0d | modes: none=%0d low=%0d full=%0d high=%0d super=%0d",
             n_exh, n_op[0], n_op[1], n_op[2], n_op[3], n_op[4]);
    $display("  CASES: ss-operating=%0d fallback=%0d capped=%0d self-capped=%0d claim-only-live=%0d",
             n_ss, n_fb, n_cap, n_selfcap, n_claim_only);
    $display("  COUNTERS: superspeed=%0d fallback=%0d capped=%0d unconfigured=%0d",
             n_superspeed, n_fallback, n_capped, n_unconfigured);
    $display("  [SystemVerilog] usb3_capability_resolve: %0d errors", errors);
    $display("  [SystemVerilog] %0s", errors==0 ? "PASS" : "FAIL");
    $display("");
    $finish;
  end
endmodule

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;
use ieee.math_real.all;
use work.usb3_cap_pkg.all;

entity tb_cr_vhdl is
end entity;

architecture sim of tb_cr_vhdl is
  signal clk   : std_logic := '0';
  signal rst_n : std_logic := '0';
  signal dss, bos, sp, pss, slu : std_logic := '0';
  signal ulr : std_logic_vector(2 downto 0) := (others => '0');
  signal u2s : std_logic_vector(1 downto 0) := (others => '0');

  signal ss_capable_reported, ss_operating : std_logic;
  signal op_mode : std_logic_vector(2 downto 0);
  signal credit_flow, async_notify, burst_allowed : std_logic;
  signal streams_allowed, link_pm_u1u2 : std_logic;
  signal unit_load_ma     : std_logic_vector(7 downto 0);
  signal unit_loads_grant : std_logic_vector(2 downto 0);
  signal max_power_ma     : std_logic_vector(9 downto 0);
  signal power_capped     : std_logic;
  signal n_superspeed, n_fallback, n_capped, n_unconfigured
       : std_logic_vector(31 downto 0);

  signal running : boolean := true;

  type cnt5_t is array (0 to 4) of integer;
begin
  clk <= not clk after 5 ns when running else '0';

  dut : entity work.usb3_capability_resolve
    port map (clk => clk, rst_n => rst_n, dev_ss_capable => dss,
              bos_present => bos, unit_loads_req => ulr, self_powered => sp,
              port_ss_capable => pss, ss_link_up => slu, usb2_speed => u2s,
              ss_capable_reported => ss_capable_reported,
              ss_operating => ss_operating, op_mode => op_mode,
              credit_flow => credit_flow, async_notify => async_notify,
              burst_allowed => burst_allowed,
              streams_allowed => streams_allowed,
              link_pm_u1u2 => link_pm_u1u2, unit_load_ma => unit_load_ma,
              unit_loads_grant => unit_loads_grant,
              max_power_ma => max_power_ma, power_capped => power_capped,
              n_superspeed => n_superspeed, n_fallback => n_fallback,
              n_capped => n_capped, n_unconfigured => n_unconfigured);

  stim : process
    variable seed1 : positive := 7717;
    variable seed2 : positive := 2293;
    variable r1    : real;

    -- VHDL-2008 requires a shared variable to have a protected type, so the
    -- bookkeeping lives inside the single stimulus process instead.
    variable errors : integer := 0;
    variable n_op   : cnt5_t  := (others => 0);
    variable n_exh  : integer := 0;
    variable n_ss, n_fb, n_cap, n_selfcap, n_claim_only : integer := 0;
    variable m_ss, m_fb, m_cap, m_unc : integer := 0;

    procedure check(cond : boolean; msg : string) is
    begin
      if not cond then
        errors := errors + 1;
        if errors <= 25 then
          report "  FAIL: " & msg
               & " (dss=" & std_logic'image(dss)(2)
               & " bos=" & std_logic'image(bos)(2)
               & " pss=" & std_logic'image(pss)(2)
               & " slu=" & std_logic'image(slu)(2)
               & " u2s=" & integer'image(to_integer(unsigned(u2s)))
               & " ulr=" & integer'image(to_integer(unsigned(ulr)))
               & " sp=" & std_logic'image(sp)(2)
               & " | op=" & integer'image(to_integer(unsigned(op_mode)))
               & " ssop=" & std_logic'image(ss_operating)(2)
               & " grant=" & integer'image(to_integer(unsigned(unit_loads_grant)))
               & " ul=" & integer'image(to_integer(unsigned(unit_load_ma)))
               & " pwr=" & integer'image(to_integer(unsigned(max_power_ma)))
               & ")" severity note;
        end if;
      end if;
    end procedure;

    procedure rnd(variable v : out integer; m : integer) is
    begin
      uniform(seed1, seed2, r1);
      v := integer(floor(r1 * real(m)));
    end procedure;

    procedure check_comb is
      variable e_rep, e_op, e_cap : boolean;
      variable e_mode  : op_mode_t;
      variable e_ul, e_ceil, e_grant, e_pwr, req : integer;
    begin
      -- The reference model is deliberately built the other way round: it
      -- computes the ceiling with an explicit min over both limits rather
      -- than the design's conditional narrowing.
      e_rep := (dss = '1') and (bos = '1');
      e_op  := (dss = '1') and (pss = '1') and (slu = '1');

      case speed_decode(u2s) is
        when SP_HIGH => e_mode := OP_HIGH;
        when SP_FULL => e_mode := OP_FULL;
        when SP_LOW  => e_mode := OP_LOW;
        when SP_NONE => e_mode := OP_NONE;
      end case;
      if e_op then
        e_mode := OP_SUPER;
      end if;

      if e_op then e_ul := UL_MA_SS; else e_ul := UL_MA_USB2; end if;

      if e_op then e_ceil := UL_CEIL_SS; else e_ceil := UL_CEIL_USB2; end if;
      if (sp = '1') and UL_CEIL_SELF < e_ceil then
        e_ceil := UL_CEIL_SELF;
      end if;

      req := to_integer(unsigned(ulr));
      if req > e_ceil then
        e_grant := e_ceil; e_cap := true;
      else
        e_grant := req;    e_cap := false;
      end if;
      e_pwr := e_grant * e_ul;

      check((ss_capable_reported = '1') = e_rep,
            "ss_capable_reported is the DESCRIPTOR claim");
      check((ss_operating = '1') = e_op,
            "ss_operating needs device AND port AND a trained link");
      check(op_mode = mode_code(e_mode), "op_mode matches the model");
      check(unit_load_ma = std_logic_vector(to_unsigned(e_ul, 8)),
            "unit load is 150 on SS, 100 on USB 2");
      check(unit_loads_grant = std_logic_vector(to_unsigned(e_grant, 3)),
            "unit loads granted match");
      check((power_capped = '1') = e_cap, "power_capped matches the model");
      check(max_power_ma = std_logic_vector(to_unsigned(e_pwr, 10)),
            "max_power_ma matches the model");

      -- Every mechanism follows ss_operating, none follows the claim.
      check((credit_flow = '1') = e_op,     "credit flow follows ss_operating");
      check((async_notify = '1') = e_op,    "ERDY/NRDY follows ss_operating");
      check((burst_allowed = '1') = e_op,   "bursting follows ss_operating");
      check((streams_allowed = '1') = e_op, "streams follow ss_operating");
      check((link_pm_u1u2 = '1') = e_op,    "U1/U2 follows ss_operating");

      -- ---- SAFETY PROPERTIES, independent of the model ----
      -- 1. THE property. Not one mechanism may be enabled by the claim alone.
      if ss_capable_reported = '1' and ss_operating = '0' then
        check(credit_flow = '0' and async_notify = '0' and burst_allowed = '0'
              and streams_allowed = '0' and link_pm_u1u2 = '0',
              "a SuperSpeed mechanism was enabled on a USB 2 link");
        check(unit_load_ma = std_logic_vector(to_unsigned(100, 8)),
              "a 150 mA unit load was granted on a USB 2 link");
        check(op_mode /= mode_code(OP_SUPER),
              "op_mode says SuperSpeed but the link never trained");
      end if;
      -- 2. SuperSpeed operation is impossible without all three terms.
      check(ss_operating = '0'
            or (dss = '1' and pss = '1' and slu = '1'),
            "ss_operating asserted with a term missing");
      -- 3. A self-powered device never draws more than one unit load.
      if sp = '1' then
        check(to_integer(unsigned(unit_loads_grant)) <= 1,
              "a self-powered device was granted more than one unit load");
      end if;
      -- 4. The grant never exceeds the request -- a cap only ever reduces.
      check(to_integer(unsigned(unit_loads_grant))
            <= to_integer(unsigned(ulr)),
            "more unit loads were granted than were requested");
      -- 5. The USB 2 ceiling is 5 unit loads (500 mA), never 6.
      if ss_operating = '0' then
        check(to_integer(unsigned(unit_loads_grant)) <= 5,
              "more than 500 mA granted on a USB 2 link");
      end if;
      -- 6. Power is exactly grant x unit load -- no rounding, no slack.
      check(to_integer(unsigned(max_power_ma))
            = to_integer(unsigned(unit_loads_grant))
              * to_integer(unsigned(unit_load_ma)),
            "max_power_ma is not grant x unit load");
      -- 7. An unconfigured port grants nothing and runs nothing.
      if op_mode = mode_code(OP_NONE) then
        check(credit_flow = '0' and burst_allowed = '0'
              and streams_allowed = '0',
              "mechanisms enabled on a port with no link at all");
      end if;

      n_op(op_mode_t'pos(e_mode)) := n_op(op_mode_t'pos(e_mode)) + 1;
      if e_op then n_ss := n_ss + 1; end if;
      if e_rep and not e_op then n_fb := n_fb + 1; end if;
      if e_cap then n_cap := n_cap + 1; end if;
      if sp = '1' and e_cap then n_selfcap := n_selfcap + 1; end if;
      if e_rep and not e_op and speed_decode(u2s) /= SP_NONE then
        n_claim_only := n_claim_only + 1;
      end if;
    end procedure;

    procedure step is
    begin
      wait for 1 ns;
      check_comb;
      if ss_operating = '1' then m_ss := m_ss + 1; end if;
      if ss_capable_reported = '1' and ss_operating = '0' then
        m_fb := m_fb + 1;
      end if;
      if power_capped = '1' then m_cap := m_cap + 1; end if;
      if op_mode = mode_code(OP_NONE) then m_unc := m_unc + 1; end if;
      wait until rising_edge(clk);
      wait for 1 ns;
      check(n_superspeed = std_logic_vector(to_unsigned(m_ss, 32)),
            "n_superspeed matches the model");
      check(n_fallback = std_logic_vector(to_unsigned(m_fb, 32)),
            "n_fallback matches the model");
      check(n_capped = std_logic_vector(to_unsigned(m_cap, 32)),
            "n_capped matches the model");
      check(n_unconfigured = std_logic_vector(to_unsigned(m_unc, 32)),
            "n_unconfigured matches the model");
    end procedure;

    procedure hard_reset is
    begin
      rst_n <= '0'; dss <= '0'; bos <= '0'; sp <= '0'; pss <= '0';
      slu <= '0'; ulr <= (others => '0'); u2s <= (others => '0');
      wait until rising_edge(clk); wait for 1 ns;
      wait until rising_edge(clk); wait for 1 ns;
      rst_n <= '1'; wait for 1 ns;
      m_ss := 0; m_fb := 0; m_cap := 0; m_unc := 0;
    end procedure;

    variable iv : integer;
  begin
    hard_reset;
    check(op_mode = mode_code(OP_NONE), "nothing connected, no operating mode");
    check(ss_operating = '0', "and nothing is running at SuperSpeed");

    -- ===== A. EXHAUSTIVE over the whole resolution =====
    -- dev_ss_capable x bos_present x port_ss_capable x ss_link_up
    --   x usb2_speed(4) x unit_loads_req(8) x self_powered
    -- = 2 x 2 x 2 x 2 x 4 x 8 x 2 = 1024 points, the complete input space.
    for a in 0 to 1 loop
      for b in 0 to 1 loop
        for c in 0 to 1 loop
          for d in 0 to 1 loop
            for e in 0 to 3 loop
              for f in 0 to 7 loop
                for g in 0 to 1 loop
                  if a = 1 then dss <= '1'; else dss <= '0'; end if;
                  if b = 1 then bos <= '1'; else bos <= '0'; end if;
                  if c = 1 then pss <= '1'; else pss <= '0'; end if;
                  if d = 1 then slu <= '1'; else slu <= '0'; end if;
                  u2s <= std_logic_vector(to_unsigned(e, 2));
                  ulr <= std_logic_vector(to_unsigned(f, 3));
                  if g = 1 then sp <= '1'; else sp <= '0'; end if;
                  step;
                  n_exh := n_exh + 1;
                end loop;
              end loop;
            end loop;
          end loop;
        end loop;
      end loop;
    end loop;
    report "  exhaustive capability-resolution sweep: " & integer'image(n_exh)
         & " of 1024 points verified" severity note;

    -- ===== B. directed: the scenarios that get argued about =====
    hard_reset;

    -- 1. A SuperSpeed device in a SuperSpeed port. Everything on.
    dss <= '1'; bos <= '1'; pss <= '1'; slu <= '1'; u2s <= "11";
    ulr <= "110"; sp <= '0'; step;
    check(op_mode = mode_code(OP_SUPER),
          "a trained SS link operates at SuperSpeed");
    check(credit_flow = '1' and async_notify = '1' and burst_allowed = '1'
          and streams_allowed = '1',
          "and every SuperSpeed mechanism is available");
    check(to_integer(unsigned(unit_load_ma)) = 150, "the unit load is 150 mA");
    check(to_integer(unsigned(unit_loads_grant)) = 6,
          "6 unit loads are allowed");
    check(to_integer(unsigned(max_power_ma)) = 900, "which is 900 mA");
    check(power_capped = '0', "and nothing was capped");

    -- 2. THE case. The SAME device, behind a USB 2 hub. It is a USB 2 device.
    dss <= '1'; bos <= '1'; pss <= '0'; slu <= '0'; u2s <= "11";
    ulr <= "110"; sp <= '0'; step;
    check(ss_capable_reported = '1',
          "the descriptors still claim SuperSpeed capability");
    check(ss_operating = '0', "but nothing SuperSpeed is running");
    check(op_mode = mode_code(OP_HIGH), "it is a HIGH SPEED device now");
    check(credit_flow = '0', "the host must POLL it");
    check(async_notify = '0', "it answers NAK, not NRDY/ERDY");
    check(burst_allowed = '0' and streams_allowed = '0',
          "no bursting, no streams");
    check(link_pm_u1u2 = '0',
          "and idle means bus suspend, not U1/U2");
    check(to_integer(unsigned(unit_load_ma)) = 100,
          "its unit load is 100 mA");
    check(to_integer(unsigned(unit_loads_grant)) = 5,
          "capped at 5 unit loads");
    check(to_integer(unsigned(max_power_ma)) = 500, "so 500 mA, not 900");
    check(power_capped = '1', "and the request WAS capped");

    -- 3. A SuperSpeed port, a capable device, but training FAILED.
    --    Identical outcome to case 2 -- which is the point.
    dss <= '1'; bos <= '1'; pss <= '1'; slu <= '0'; u2s <= "11";
    ulr <= "110"; sp <= '0'; step;
    check(ss_operating = '0',
          "a capable device in a capable port still is not SuperSpeed if training failed");
    check(op_mode = mode_code(OP_HIGH), "it fell back to high speed");
    check(to_integer(unsigned(unit_load_ma)) = 100,
          "with a USB 2 unit load");

    -- 4. A device that claims SuperSpeed with NO BOS descriptor.
    dss <= '1'; bos <= '0'; pss <= '1'; slu <= '1'; u2s <= "11";
    ulr <= "010"; sp <= '0'; step;
    check(ss_capable_reported = '0',
          "with no BOS descriptor there is no reported capability");
    check(ss_operating = '1',
          "yet the link trained, so SuperSpeed IS operating -- the link decides");

    -- 5. A self-powered SuperSpeed device asking for 6 unit loads.
    dss <= '1'; bos <= '1'; pss <= '1'; slu <= '1'; u2s <= "11";
    ulr <= "110"; sp <= '1'; step;
    check(to_integer(unsigned(unit_loads_grant)) = 1,
          "a self-powered device gets ONE unit load whatever it asks for");
    check(to_integer(unsigned(max_power_ma)) = 150,
          "which is 150 mA on SuperSpeed");
    check(power_capped = '1', "and the request was capped");

    -- 6. A low-speed device: no SuperSpeed anything, 100 mA unit load.
    dss <= '0'; bos <= '0'; pss <= '1'; slu <= '0'; u2s <= "01";
    ulr <= "001"; sp <= '0'; step;
    check(op_mode = mode_code(OP_LOW),
          "a low speed device operates at low speed");
    check(to_integer(unsigned(unit_load_ma)) = 100,
          "with a 100 mA unit load");
    check(to_integer(unsigned(max_power_ma)) = 100, "and 100 mA total");

    -- 7. Nothing plugged in at all.
    dss <= '1'; bos <= '1'; pss <= '1'; slu <= '0'; u2s <= "00";
    ulr <= "100"; sp <= '0'; step;
    check(op_mode = mode_code(OP_NONE), "no link of either kind means no mode");
    check(credit_flow = '0' and burst_allowed = '0',
          "and no mechanisms at all");

    -- ===== C. randomised =====
    -- ieee.math_real.uniform is a genuinely different generator from either
    -- Verilog builtin, which is what makes this column independent evidence.
    for i in 0 to 39999 loop
      rnd(iv, 2); if iv = 1 then dss <= '1'; else dss <= '0'; end if;
      rnd(iv, 2); if iv = 1 then bos <= '1'; else bos <= '0'; end if;
      rnd(iv, 2); if iv = 1 then pss <= '1'; else pss <= '0'; end if;
      rnd(iv, 2); if iv = 1 then slu <= '1'; else slu <= '0'; end if;
      rnd(iv, 4); u2s <= std_logic_vector(to_unsigned(iv, 2));
      rnd(iv, 8); ulr <= std_logic_vector(to_unsigned(iv, 3));
      rnd(iv, 4); if iv = 0 then sp <= '1'; else sp <= '0'; end if;
      step;
    end loop;

    for i in 0 to 4 loop
      check(n_op(i) > 0, "every operating mode was reached");
    end loop;
    check(n_ss > 1000, "SuperSpeed operation was reached often");
    check(n_fb > 1000,
          "the SS-capable-but-not-operating case was reached often");
    check(n_selfcap > 100, "self-powered devices were capped");
    check(n_claim_only > 1000,
          "the claim-without-operation case was reached with a live USB 2 link");

    report "  REACH: exhaustive=" & integer'image(n_exh)
         & " | modes: none=" & integer'image(n_op(0))
         & " low=" & integer'image(n_op(1))
         & " full=" & integer'image(n_op(2))
         & " high=" & integer'image(n_op(3))
         & " super=" & integer'image(n_op(4)) severity note;
    report "  CASES: ss-operating=" & integer'image(n_ss)
         & " fallback=" & integer'image(n_fb)
         & " capped=" & integer'image(n_cap)
         & " self-capped=" & integer'image(n_selfcap)
         & " claim-only-live=" & integer'image(n_claim_only) severity note;
    report "  COUNTERS: superspeed="
         & integer'image(to_integer(unsigned(n_superspeed)))
         & " fallback=" & integer'image(to_integer(unsigned(n_fallback)))
         & " capped=" & integer'image(to_integer(unsigned(n_capped)))
         & " unconfigured="
         & integer'image(to_integer(unsigned(n_unconfigured))) severity note;
    report "  [VHDL] usb3_capability_resolve: " & integer'image(errors)
         & " errors" severity note;
    if errors = 0 then
      report "  [VHDL] PASS" severity note;
    else
      report "  [VHDL] FAIL" severity failure;
    end if;
    running <= false;
    wait;
  end process;
end architecture;