Port Management

   detach   >   over-current   >   babble   >   host command

      change <= (change & ~(chg_clear ? chg_clear_mask : 5'd0)) | set_chg;

// usb_port_fsm -- the per-port state machine inside a hub's controller.
//
// Chapter 18.1 built the repeater and left `port_enabled` as an INPUT. This
// module is what drives it: one instance per downstream port.
//
// Three UNCOORDINATED sources move a port, and the whole difficulty of the
// block is that they can act in the same cycle:
//
//   1. the HOST, issuing port commands as control transfers to the hub
//      controller (SetPortFeature / ClearPortFeature);
//   2. the DEVICE below, attaching and detaching whenever it likes;
//   3. the HUB ITSELF, disabling a port for cause -- chapter 18.1's babble
//      isolation, and over-current.
//
// The host is the slowest of the three and the only one that can be wrong
// about the present, because its command was composed from a port status it
// read some time ago. So the precedence is NOT "host wins":
//
//      detach  >  over-current  >  babble  >  host command
//
// Physical reality outranks the hub's own faults, which outrank software.
//
// The other rule worth stating before the code: THERE IS NO ENABLE COMMAND.
// A port becomes Enabled only by completing a RESET. A host that wants a
// port enabled asks for a reset and waits; the enable is a side effect of
// the reset finishing, never something it can write directly.
module usb_port_fsm #(
  parameter integer RESET_CYCLES = 20      // duration of the drive-reset
) (
  input  wire       clk,
  input  wire       rst_n,

  // --- the host, through the hub controller (chapter 18.3) ---
  input  wire       cmd_valid,
  input  wire [2:0] cmd,
  // --- the device below ---
  input  wire       attached,              // physical presence detect
  // --- the hub itself ---
  input  wire       babble,                // 18.1: repeater isolated this port
  input  wire       overcurrent,

  output reg  [2:0] state,
  output wire       port_powered,
  output wire       port_enabled,          // --> chapter 18.1's repeater
  output wire       resetting,

  // --- sticky change bits, set by hardware, cleared by the host (18.3) ---
  input  wire       chg_clear,             // host acknowledges
  input  wire [4:0] chg_clear_mask,
  output reg  [4:0] change                 // {oc, reset, suspend, enable, connect}
);
  // Port states. USB 2.0 names them in section 11.5; these are the six that
  // carry distinct behaviour here.
  localparam [2:0] P_POWERED_OFF  = 3'd0,
                   P_DISCONNECTED = 3'd1,  // powered, nothing attached
                   P_DISABLED     = 3'd2,  // attached, not passing traffic
                   P_RESETTING    = 3'd3,
                   P_ENABLED      = 3'd4,
                   P_SUSPENDED    = 3'd5;

  localparam [2:0] CMD_NONE        = 3'd0,
                   CMD_SET_POWER   = 3'd1,
                   CMD_CLR_POWER   = 3'd2,
                   CMD_SET_RESET   = 3'd3,
                   CMD_SET_SUSPEND = 3'd4,
                   CMD_CLR_SUSPEND = 3'd5,  // resume
                   CMD_CLR_ENABLE  = 3'd6;  // disable, by request

  // change bit positions
  localparam integer C_CONNECT = 0, C_ENABLE = 1, C_SUSPEND = 2,
                     C_RESET   = 3, C_OC     = 4;

  assign port_powered = (state != P_POWERED_OFF);
  // ONLY the Enabled state passes traffic. Suspended does not, Resetting
  // does not -- a port being reset is emphatically not carrying packets.
  assign port_enabled = (state == P_ENABLED);
  assign resetting    = (state == P_RESETTING);

  reg [31:0] rst_cnt;

  // A command is only a command when it is valid. Decoding `cmd` without
  // qualifying it makes CMD_NONE (3'd0) indistinguishable from an idle bus.
  wire       c       = cmd_valid;
  wire       is_pwr_off = c && (cmd == CMD_CLR_POWER);
  wire       is_pwr_on  = c && (cmd == CMD_SET_POWER);
  wire       is_reset   = c && (cmd == CMD_SET_RESET);
  wire       is_susp    = c && (cmd == CMD_SET_SUSPEND);
  wire       is_resume  = c && (cmd == CMD_CLR_SUSPEND);
  wire       is_disable = c && (cmd == CMD_CLR_ENABLE);

  // A detach is only observable while the port is powered: with the port
  // powered off there is no pull-up to sense, so `attached` means nothing.
  wire       detached  = port_powered && !attached;

  // Connect-change is an EDGE, not a level. Setting it from `detached`
  // directly would re-set it every cycle the port sits empty, and the host
  // would never be able to clear it -- a change bit that cannot be cleared
  // is a change bit that reports nothing.
  reg        attached_q;
  wire       conn_changed = port_powered && (attached != attached_q);

  // The change register: set by hardware here, cleared by the host through
  // chg_clear/chg_clear_mask. Chapter 18.3 is about what happens when both
  // occur in the same cycle -- SET WINS, and that is built in below.
  reg [4:0] set_chg;

  always @* begin
    set_chg = 5'd0;
    if (state != P_POWERED_OFF) begin
      if (overcurrent)                       set_chg[C_OC]      = 1'b1;
      if (conn_changed)                      set_chg[C_CONNECT] = 1'b1;
      // a port leaving Enabled for a reason the host did not ask for
      if (state == P_ENABLED && babble && !overcurrent && !detached)
        set_chg[C_ENABLE] = 1'b1;
      if (state == P_RESETTING && rst_cnt == RESET_CYCLES-1 && !detached
          && !overcurrent)                   set_chg[C_RESET]   = 1'b1;
      if (state == P_SUSPENDED && is_resume && !detached && !overcurrent)
        set_chg[C_SUSPEND] = 1'b1;
    end
  end

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      state      <= P_POWERED_OFF;
      rst_cnt    <= 32'd0;
      change     <= 5'd0;
      attached_q <= 1'b0;
    end else begin
      // While the port is unpowered there is nothing to sense, so the
      // history resets: powering a port that already has a device attached
      // must report a connect change, because the host has not seen it yet.
      attached_q <= (state != P_POWERED_OFF) ? attached : 1'b0;
      // ---- change bits: SET beats CLEAR, always (chapter 18.3) ----
      // An event that arrives in the same cycle the host clears the bit must
      // survive. Clearing first and setting after would lose the event with
      // no trace; this ordering loses an acknowledgement instead, which the
      // host discovers on its next poll.
      change <= (change & ~(chg_clear ? chg_clear_mask : 5'd0)) | set_chg;

      // ---- the state, in strict precedence order ----
      if (detached) begin
        // Physical reality first. A device that is gone is gone, whatever
        // the host just asked for and whatever the repeater thinks.
        state   <= P_DISCONNECTED;
        rst_cnt <= 32'd0;
      end else if (overcurrent && state != P_POWERED_OFF) begin
        // The port is drawing more than it may. Removing power is not a
        // policy choice; it is the only way to stop it.
        state   <= P_POWERED_OFF;
        rst_cnt <= 32'd0;
      end else begin
        case (state)
          P_POWERED_OFF:
            if (is_pwr_on) state <= P_DISCONNECTED;

          P_DISCONNECTED: begin
            if (is_pwr_off)    state <= P_POWERED_OFF;
            else if (attached) state <= P_DISABLED;
          end

          P_DISABLED: begin
            if (is_pwr_off)     state <= P_POWERED_OFF;
            else if (is_reset) begin
              state   <= P_RESETTING;
              rst_cnt <= 32'd0;
            end
            // NOTE: no command moves a port from Disabled to Enabled. The
            // only route is through a reset.
          end

          P_RESETTING: begin
            if (is_pwr_off) begin
              state <= P_POWERED_OFF; rst_cnt <= 32'd0;
            end else if (rst_cnt == RESET_CYCLES-1) begin
              // Reset complete: THIS is where a port becomes enabled.
              state   <= P_ENABLED;
              rst_cnt <= 32'd0;
            end else begin
              rst_cnt <= rst_cnt + 32'd1;
            end
          end

          P_ENABLED: begin
            if (is_pwr_off)      state <= P_POWERED_OFF;
            // BABBLE OUTRANKS THE HOST'S COMMAND. If the repeater isolated
            // this port in the same cycle the host asked to suspend it, the
            // port goes to Disabled, not Suspended -- the host composed that
            // command from a status read before the fault existed.
            else if (babble)     state <= P_DISABLED;
            else if (is_disable) state <= P_DISABLED;
            else if (is_susp)    state <= P_SUSPENDED;
          end

          P_SUSPENDED: begin
            if (is_pwr_off)      state <= P_POWERED_OFF;
            else if (is_resume)  state <= P_ENABLED;
            else if (is_disable) state <= P_DISABLED;
          end

          default: state <= P_POWERED_OFF;
        endcase
      end
    end
  end
endmodule

package usb_port_pkg;
  // The six port states that carry distinct behaviour. USB 2.0 section 11.5
  // names more; these are the ones a repeater-facing FSM must distinguish.
  typedef enum logic [2:0] {
    P_POWERED_OFF,   // no power on the port; nothing can be sensed
    P_DISCONNECTED,  // powered, nothing attached
    P_DISABLED,      // attached, not passing traffic
    P_RESETTING,     // driving reset downstream
    P_ENABLED,       // the ONLY state that passes traffic
    P_SUSPENDED      // enabled but idled
  } port_state_e;

  // Port commands, as the hub controller decodes them from the host's
  // SetPortFeature / ClearPortFeature control transfers.
  typedef enum logic [2:0] {
    CMD_NONE,
    CMD_SET_POWER,
    CMD_CLR_POWER,
    CMD_SET_RESET,
    CMD_SET_SUSPEND,
    CMD_CLR_SUSPEND,   // resume
    CMD_CLR_ENABLE     // disable, by request
  } port_cmd_e;

  // Change-bit positions, shared with chapter 18.3's status-change endpoint.
  typedef enum int unsigned {
    CHG_CONNECT = 0, CHG_ENABLE = 1, CHG_SUSPEND = 2,
    CHG_RESET   = 3, CHG_OC     = 4
  } port_chg_e;
endpackage

// usb_port_fsm_sv -- the per-port state machine inside a hub's controller.
//
// Chapter 18.1 built the repeater and left `port_enabled` as an INPUT. This
// drives it: one instance per downstream port.
//
// Three UNCOORDINATED sources move a port and can act in the same cycle: the
// HOST issuing port commands, the DEVICE attaching and detaching, and the
// HUB ITSELF disabling a port for cause (18.1's babble, and over-current).
// The host is the slowest of the three and the only one that can be wrong
// about the present, because its command was composed from a status it read
// some time ago. So the precedence is NOT "host wins":
//
//      detach  >  over-current  >  babble  >  host command
//
// And: THERE IS NO ENABLE COMMAND. A port becomes Enabled only by completing
// a reset, or by resuming from Suspended.
module usb_port_fsm_sv
  import usb_port_pkg::*;
#(
  parameter int unsigned RESET_CYCLES = 20
) (
  input  logic        clk,
  input  logic        rst_n,
  input  logic        cmd_valid,
  input  port_cmd_e   cmd,
  input  logic        attached,
  input  logic        babble,
  input  logic        overcurrent,

  output port_state_e state,
  output logic        port_powered,
  output logic        port_enabled,
  output logic        resetting,

  input  logic        chg_clear,
  input  logic [4:0]  chg_clear_mask,
  output logic [4:0]  change
);
  initial if (RESET_CYCLES < 1)
    $fatal(1, "RESET_CYCLES=%0d: a reset with no duration is not a reset",
           RESET_CYCLES);

  assign port_powered = (state != P_POWERED_OFF);
  // ONLY Enabled passes traffic. Suspended does not; a port being reset
  // emphatically does not.
  assign port_enabled = (state == P_ENABLED);
  assign resetting    = (state == P_RESETTING);

  int unsigned rst_cnt;
  logic        attached_q;

  // A detach is only observable while powered: with no power there is no
  // pull-up to sense, so `attached` means nothing.
  wire detached     = port_powered && !attached;
  // Connect-change is an EDGE, not a level. Driving it from `detached`
  // would re-set it every cycle an empty port sat idle, and a change bit
  // the host can never clear reports nothing.
  wire conn_changed = port_powered && (attached != attached_q);

  logic [4:0] set_chg;
  always_comb begin
    set_chg = '0;
    if (state != P_POWERED_OFF) begin
      if (overcurrent)  set_chg[CHG_OC]      = 1'b1;
      if (conn_changed) set_chg[CHG_CONNECT] = 1'b1;
      if (state == P_ENABLED && babble && !overcurrent && !detached)
        set_chg[CHG_ENABLE] = 1'b1;
      if (state == P_RESETTING && rst_cnt == RESET_CYCLES-1
          && !detached && !overcurrent)
        set_chg[CHG_RESET] = 1'b1;
      if (state == P_SUSPENDED && cmd_valid && cmd == CMD_CLR_SUSPEND
          && !detached && !overcurrent)
        set_chg[CHG_SUSPEND] = 1'b1;
    end
  end

  wire is_pwr_off = cmd_valid && (cmd == CMD_CLR_POWER);

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      state <= P_POWERED_OFF; rst_cnt <= '0; change <= '0; attached_q <= 1'b0;
    end else begin
      attached_q <= (state != P_POWERED_OFF) ? attached : 1'b0;

      // SET beats CLEAR, always (chapter 18.3). An event arriving in the
      // same cycle the host clears the bit must survive: this ordering
      // loses an acknowledgement, which the host sees on its next poll,
      // rather than losing an event, which leaves no trace at all.
      change <= (change & ~(chg_clear ? chg_clear_mask : 5'd0)) | set_chg;

      if (detached) begin
        // Physical reality first, whatever the host just asked for.
        state <= P_DISCONNECTED; rst_cnt <= '0;
      end else if (overcurrent && state != P_POWERED_OFF) begin
        state <= P_POWERED_OFF; rst_cnt <= '0;
      end else if (is_pwr_off && state != P_POWERED_OFF) begin
        state <= P_POWERED_OFF; rst_cnt <= '0;
      end else begin
        case (state)
          P_POWERED_OFF:
            if (cmd_valid && cmd == CMD_SET_POWER) state <= P_DISCONNECTED;
          P_DISCONNECTED:
            if (attached) state <= P_DISABLED;
          P_DISABLED:
            // No command moves a port from Disabled to Enabled: the only
            // route is through a reset.
            if (cmd_valid && cmd == CMD_SET_RESET) begin
              state <= P_RESETTING; rst_cnt <= '0;
            end
          P_RESETTING:
            if (rst_cnt == RESET_CYCLES-1) begin
              state <= P_ENABLED; rst_cnt <= '0;   // THIS is where a port
            end else begin                          // becomes enabled
              rst_cnt <= rst_cnt + 1;
            end
          P_ENABLED:
            // BABBLE OUTRANKS THE HOST'S COMMAND: the host composed that
            // command from a status read taken before the fault existed.
            if (babble)                                    state <= P_DISABLED;
            else if (cmd_valid && cmd == CMD_CLR_ENABLE)   state <= P_DISABLED;
            else if (cmd_valid && cmd == CMD_SET_SUSPEND)  state <= P_SUSPENDED;
          P_SUSPENDED:
            if (cmd_valid && cmd == CMD_CLR_SUSPEND)       state <= P_ENABLED;
            else if (cmd_valid && cmd == CMD_CLR_ENABLE)   state <= P_DISABLED;
          default: state <= P_POWERED_OFF;
        endcase
      end
    end
  end
endmodule

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

package usb_port_pkg is
  -- The six port states that carry distinct behaviour. USB 2.0 section 11.5
  -- names more; these are the ones a repeater-facing FSM must distinguish.
  type port_state_t is (
    P_POWERED_OFF,   -- no power on the port; nothing can be sensed
    P_DISCONNECTED,  -- powered, nothing attached
    P_DISABLED,      -- attached, not passing traffic
    P_RESETTING,     -- driving reset downstream
    P_ENABLED,       -- the ONLY state that passes traffic
    P_SUSPENDED      -- enabled but idled
  );

  -- Port commands, as the hub controller decodes them from the host's
  -- SetPortFeature / ClearPortFeature control transfers.
  type port_cmd_t is (
    CMD_NONE, CMD_SET_POWER, CMD_CLR_POWER, CMD_SET_RESET,
    CMD_SET_SUSPEND, CMD_CLR_SUSPEND, CMD_CLR_ENABLE
  );

  -- Change-bit positions, shared with chapter 18.3's status-change endpoint.
  constant CHG_CONNECT : natural := 0;
  constant CHG_ENABLE  : natural := 1;
  constant CHG_SUSPEND : natural := 2;
  constant CHG_RESET   : natural := 3;
  constant CHG_OC      : natural := 4;
end package;

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

-- usb_port_fsm_vhdl -- the per-port state machine inside a hub's controller.
--
-- Chapter 18.1 built the repeater and left `port_enabled` as an INPUT. This
-- drives it: one instance per downstream port.
--
-- Three UNCOORDINATED sources move a port and can act in the same cycle: the
-- HOST issuing port commands, the DEVICE attaching and detaching, and the
-- HUB ITSELF disabling a port for cause (18.1's babble, and over-current).
-- The host is the slowest of the three and the only one that can be wrong
-- about the present, because its command was composed from a status it read
-- some time ago. So the precedence is NOT "host wins":
--
--      detach  >  over-current  >  babble  >  host command
--
-- And: THERE IS NO ENABLE COMMAND. A port becomes Enabled only by completing
-- a reset, or by resuming from Suspended.
entity usb_port_fsm_vhdl is
  generic ( RESET_CYCLES : positive := 20 );
  port (
    clk            : in  std_logic;
    rst_n          : in  std_logic;
    cmd_valid      : in  std_logic;
    cmd            : in  port_cmd_t;
    attached       : in  std_logic;
    babble         : in  std_logic;
    overcurrent    : in  std_logic;

    state          : out port_state_t;
    port_powered   : out std_logic;
    port_enabled   : out std_logic;
    resetting      : out std_logic;

    chg_clear      : in  std_logic;
    chg_clear_mask : in  std_logic_vector(4 downto 0);
    change         : out std_logic_vector(4 downto 0)
  );
end entity;

architecture rtl of usb_port_fsm_vhdl is
  signal st         : port_state_t := P_POWERED_OFF;
  signal rst_cnt    : natural range 0 to RESET_CYCLES := 0;
  signal attached_q : std_logic := '0';
  signal chg_r      : std_logic_vector(4 downto 0) := (others => '0');

  signal powered_i  : std_logic;
  signal detached   : std_logic;
  signal conn_chg   : std_logic;
  signal set_chg    : std_logic_vector(4 downto 0);
begin
  powered_i    <= '0' when st = P_POWERED_OFF else '1';
  port_powered <= powered_i;
  -- ONLY Enabled passes traffic. Suspended does not; a port being reset
  -- emphatically does not.
  port_enabled <= '1' when st = P_ENABLED   else '0';
  resetting    <= '1' when st = P_RESETTING else '0';
  state        <= st;
  change       <= chg_r;

  -- A detach is only observable while powered: with no power there is no
  -- pull-up to sense, so `attached` means nothing.
  detached <= '1' when (powered_i = '1' and attached = '0') else '0';
  -- Connect-change is an EDGE, not a level. Driving it from `detached`
  -- would re-set it every cycle an empty port sat idle, and a change bit
  -- the host can never clear reports nothing.
  conn_chg <= '1' when (powered_i = '1' and attached /= attached_q) else '0';

  process (st, rst_cnt, attached, babble, overcurrent, cmd, cmd_valid,
           detached, conn_chg)
    variable r : std_logic_vector(4 downto 0);
  begin
    r := (others => '0');
    if st /= P_POWERED_OFF then
      if overcurrent = '1' then r(CHG_OC)      := '1'; end if;
      if conn_chg    = '1' then r(CHG_CONNECT) := '1'; end if;
      if st = P_ENABLED and babble = '1' and overcurrent = '0'
         and detached = '0' then
        r(CHG_ENABLE) := '1';
      end if;
      if st = P_RESETTING and rst_cnt = RESET_CYCLES-1
         and detached = '0' and overcurrent = '0' then
        r(CHG_RESET) := '1';
      end if;
      if st = P_SUSPENDED and cmd_valid = '1' and cmd = CMD_CLR_SUSPEND
         and detached = '0' and overcurrent = '0' then
        r(CHG_SUSPEND) := '1';
      end if;
    end if;
    set_chg <= r;
  end process;

  process (clk, rst_n)
    variable clr : std_logic_vector(4 downto 0);
  begin
    if rst_n = '0' then
      st <= P_POWERED_OFF; rst_cnt <= 0; chg_r <= (others => '0');
      attached_q <= '0';
    elsif rising_edge(clk) then
      if st /= P_POWERED_OFF then attached_q <= attached;
      else                        attached_q <= '0'; end if;

      -- SET beats CLEAR, always (chapter 18.3). An event arriving in the
      -- same cycle the host clears the bit must survive: this ordering
      -- loses an acknowledgement, which the host sees on its next poll,
      -- rather than losing an event, which leaves no trace at all.
      if chg_clear = '1' then clr := chg_clear_mask;
      else                    clr := (others => '0'); end if;
      chg_r <= (chg_r and (not clr)) or set_chg;

      if detached = '1' then
        -- Physical reality first, whatever the host just asked for.
        st <= P_DISCONNECTED; rst_cnt <= 0;
      elsif overcurrent = '1' and st /= P_POWERED_OFF then
        st <= P_POWERED_OFF; rst_cnt <= 0;
      elsif cmd_valid = '1' and cmd = CMD_CLR_POWER and st /= P_POWERED_OFF then
        st <= P_POWERED_OFF; rst_cnt <= 0;
      else
        case st is
          when P_POWERED_OFF =>
            if cmd_valid = '1' and cmd = CMD_SET_POWER then
              st <= P_DISCONNECTED;
            end if;
          when P_DISCONNECTED =>
            if attached = '1' then st <= P_DISABLED; end if;
          when P_DISABLED =>
            -- No command moves a port from Disabled to Enabled: the only
            -- route is through a reset.
            if cmd_valid = '1' and cmd = CMD_SET_RESET then
              st <= P_RESETTING; rst_cnt <= 0;
            end if;
          when P_RESETTING =>
            if rst_cnt = RESET_CYCLES-1 then
              st <= P_ENABLED; rst_cnt <= 0;   -- THIS is where a port
            else                                -- becomes enabled
              rst_cnt <= rst_cnt + 1;
            end if;
          when P_ENABLED =>
            -- BABBLE OUTRANKS THE HOST'S COMMAND: the host composed that
            -- command from a status read taken before the fault existed.
            if babble = '1' then
              st <= P_DISABLED;
            elsif cmd_valid = '1' and cmd = CMD_CLR_ENABLE then
              st <= P_DISABLED;
            elsif cmd_valid = '1' and cmd = CMD_SET_SUSPEND then
              st <= P_SUSPENDED;
            end if;
          when P_SUSPENDED =>
            if cmd_valid = '1' and cmd = CMD_CLR_SUSPEND then
              st <= P_ENABLED;
            elsif cmd_valid = '1' and cmd = CMD_CLR_ENABLE then
              st <= P_DISABLED;
            end if;
        end case;
      end if;
    end if;
  end process;
end architecture;

    for (pos=0; pos<7; pos=pos+1)
     for (cs=0; cs<14; cs=cs+1)
      for (st=0; st<8; st=st+1) begin
        goto(POSN[pos]);
        n_exh = n_exh + 1;
        step(cs[0], cs[3:1], st[0], st[1], st[2], 0, 5'd0);
      end

  function [2:0] m_next(input [2:0] s, input [31:0] cnt, input cv,
                        input [2:0] c, input att, input bab, input oc);
    reg det;
    begin
      det = (s != P_OFF) && !att;
      if (det)                        m_next = P_DISC;
      else if (oc && (s != P_OFF))    m_next = P_OFF;
      else if (cv && c==C_PWR_OFF && s != P_OFF) m_next = P_OFF;
      else case (s)
        ...

      check(penabled === (state == P_EN),
            "port_enabled is asserted in the Enabled state and nowhere else");
      ...
      // A port may become Enabled only by COMPLETING A RESET or by RESUMING
      // from Suspended. There is no enable command, so a port must never
      // reach Enabled straight from Disabled, Disconnected or Powered-off.
      if (state == P_EN && prev_state != P_EN) begin
        n_enter_en = n_enter_en + 1;
        check(prev_state === P_RST || prev_state === P_SUSP,
              "a port entered Enabled other than by reset-complete or resume");
      end
      // A change bit never clears unless the host asked for it.
      check(((~change) & m_chg & ~(clr ? clrm : 5'd0)) === 5'd0,
            "a change bit cleared without the host clearing it");

  exhaustive transition sweep: 784 of 784 transitions verified

  Verilog / SystemVerilog:
  REACH: exhaustive=784 enabled-entries=1396 (reset=1088 resume=308) babble+cmd collisions=378
  [Verilog] usb_port_fsm: 0 errors — PASS

  VHDL:
  REACH: exhaustive=784 enabled-entries=1398 (reset=1091 resume=307) babble+cmd collisions=378
  [VHDL] usb_port_fsm_vhdl: 0 errors — PASS

      // A port may become Enabled ONLY by completing a reset.
      check(prev_state === P_RST, "a port entered Enabled from somewhere else");

    // This is the behaviour the chapter is about, and the sweep reaches it
    // exactly once: it needs Enabled, babble, cmd_valid, and specifically
    // CMD_SET_SUSPEND -- one point in 784. A claim this central cannot rest
    // on a single transition.
    for (pos=0; pos<50; pos=pos+1)
      for (i=0;i<7;i=i+1) begin
        goto(P_EN);
        step(1, i[2:0], 1, 1, 0, 0, 5'd0);
        // CLR_POWER is not a COMPETING command, it is a stronger one:
        // removing power takes the port past Disabled altogether. Babble
        // outranks every command that would leave the port powered.
        if (i == C_PWR_OFF)
          check(state===P_OFF, "a power-off command outranks babble");
        else
          check(state===P_DIS,
                "babble outranks every host command that leaves it powered");
      end

        step(sl(r2 < 0.3333), CMDS(integer(floor(r3*7.0))),
             sl(r4 < 0.75), sl(r5 < 0.0625), sl(r6 < 0.015625),
             sl(r7 < 0.125),                                   -- clear?
             std_logic_vector(to_unsigned(integer(floor(r7*32.0)), 5)));

// One agent per SOURCE, not per signal. The whole design problem is that
// these three are uncoordinated, so the environment must be able to make
// them collide without any of them knowing about the others.
class port_env extends uvm_env;
  `uvm_component_utils(port_env)
  host_cmd_agent   host;    // SetPortFeature / ClearPortFeature
  device_agent     device;  // attach / detach
  fault_agent      fault;   // babble (from 18.1) and over-current
  port_scoreboard  sb;
  port_coverage    cov;
endclass

class babble_vs_suspend_vseq extends uvm_sequence;
  `uvm_object_utils(babble_vs_suspend_vseq)
  port_vsequencer vsqr;

  task body();
    host_cmd_item   h;
    fault_item      f;
    // The SAME cycle. Section 14 measured what happens when this scenario
    // is left to chance: the mutation that inverts this precedence died by
    // THREE errors in a 26000-transition run.
    fork
      begin h = host_cmd_item::type_id::create("h");
            start_item(h, null, vsqr.host_sqr);
            h.cmd = CMD_SET_SUSPEND; h.valid = 1;
            finish_item(h, null); end
      begin f = fault_item::type_id::create("f");
            start_item(f, null, vsqr.fault_sqr);
            f.babble = 1;
            finish_item(f, null); end
    join
  endtask
endclass

class port_scoreboard extends uvm_scoreboard;
  `uvm_component_utils(port_scoreboard)
  local port_state_e m_state, m_prev;   // its OWN state (chapter 17.3)

  function void write(port_txn t);
    // A port may become Enabled only by completing a reset or by resuming.
    // The first version of this check named P_RESETTING alone and reported
    // 8 failures against a correct design -- every one of them a legal
    // resume. See section 12.
    if (t.state == P_ENABLED && m_prev != P_ENABLED)
      if (!(m_prev inside {P_RESETTING, P_SUSPENDED}))
        `uvm_error("PORT/ENTRY", $sformatf(
          "entered Enabled from %s; only reset-complete and resume are legal",
          m_prev.name()))

    // Exactly one state carries traffic.
    if (t.port_enabled !== (t.state == P_ENABLED))
      `uvm_error("PORT/EN", "port_enabled asserted outside the Enabled state")

    m_prev = m_state; m_state = t.state;
  endfunction
endclass

covergroup port_cg with function sample(
    port_state_e s, port_cmd_e c, bit cv, bit bab, bit oc, bit att);
  cp_state : coverpoint s;
  cp_cmd   : coverpoint c;
  cp_bab   : coverpoint bab { bins fault = {1}; }

  // THE cross that matters. Section 14: the one-step sweep reaches
  // Enabled x babble x SET_SUSPEND exactly ONCE in 784 transitions, and a
  // mutation inverting that precedence survived on a margin of three.
  // This cross makes the gap a coverage hole instead of a lucky catch.
  x_babble_vs_cmd : cross cp_state, cp_cmd, cp_bab {
    ignore_bins not_enabled = binsof(cp_state) intersect
      {P_POWERED_OFF, P_DISCONNECTED, P_DISABLED, P_RESETTING, P_SUSPENDED};
  }
endgroup

  // Exactly one state carries traffic.
  property p_enabled_only_in_enabled;
    @(posedge clk) disable iff (!rst_n)
      port_enabled == (state == P_ENABLED);
  endproperty
  a_enabled_only : assert property (p_enabled_only_in_enabled);

  // THE precedence: babble, with the port powered and staying powered,
  // always lands the port in Disabled -- whatever the host asked for.
  property p_babble_outranks_host;
    @(posedge clk) disable iff (!rst_n)
      (state == P_ENABLED && babble && !overcurrent && attached
       && !(cmd_valid && cmd == CMD_CLR_POWER)) |=> (state == P_DISABLED);
  endproperty
  a_babble_wins : assert property (p_babble_outranks_host)
    else $error("a host command overrode a babble fault");

  // There is no enable command: Enabled is reachable only from Resetting
  // or Suspended. Section 12 is why the second term is here.
  property p_enable_entry;
    @(posedge clk) disable iff (!rst_n)
      (state == P_ENABLED && $past(state) != P_ENABLED)
        |-> ($past(state) == P_RESETTING || $past(state) == P_SUSPENDED);
  endproperty
  a_enable_entry : assert property (p_enable_entry);

  // A change bit never clears unless the host cleared it.
  property p_change_sticky;
    @(posedge clk) disable iff (!rst_n)
      ($past(change) & ~change & ~($past(chg_clear) ? $past(chg_clear_mask) : '0))
        == '0;
  endproperty
  a_change_sticky : assert property (p_change_sticky);

  // A detach outranks everything except nothing: the port always lands in
  // Disconnected, whatever else arrived in the same cycle.
  property p_detach_wins;
    @(posedge clk) disable iff (!rst_n)
      (state != P_POWERED_OFF && !attached) |=> (state == P_DISCONNECTED);
  endproperty
  a_detach_wins : assert property (p_detach_wins);