Downstream Device Discovery

// usb_hub_status_change -- the hub's status-change endpoint.
//
// A hub cannot interrupt the host. Chapter 2.6's single-master model means
// the hub only ever ANSWERS, so every event chapter 18.2 recorded on a port
// waits in a register until the host asks for it.
//
// The asking is an interrupt IN transfer to this endpoint, and the answer is
// a BITMAP: bit 0 is the hub itself, bits N..1 are the downstream ports. One
// bit per port, regardless of how many things happened on it -- the bitmap
// says WHERE to look, never WHAT happened. The host follows up with a
// GetPortStatus control transfer to each port whose bit was set.
//
// Two things make this harder than a register read:
//
//  1. NOTHING TO REPORT IS NOT ZERO. If no bit is set the hub must NAK the
//     transfer, not return a bitmap of zeros. A zero DATA packet is a
//     successful transfer that consumed a data toggle and told the host
//     nothing; a NAK is the hub saying "ask again later", which is what an
//     interrupt endpoint with no news is supposed to say.
//
//  2. THE HOST CLEARS WHAT IT READ, NOT WHAT IS THERE. Between the poll and
//     the clear, other ports keep setting bits. A host that cleared the
//     whole bitmap would discard events it never saw -- a device that
//     attached in that window would simply never be enumerated, and nothing
//     anywhere would record that it had been lost. So the clear is MASKED by
//     the snapshot the host actually received, and any event arriving after
//     that snapshot survives into the next poll.
module usb_hub_status_change #(
  parameter integer NPORTS = 4
) (
  input  wire              clk,
  input  wire              rst_n,

  // --- from chapter 18.2, one per port: "this port has something to report"
  input  wire [NPORTS-1:0] port_change,
  input  wire              hub_change,      // over-current on the hub itself

  // --- the host polling the status-change endpoint ---
  input  wire              poll_req,
  output wire [NPORTS:0]   bitmap,          // {ports, hub} -- bit 0 is the hub
  output wire              report_valid,    // 1 = DATA returned, 0 = NAK

  // --- the host acknowledging what it read ---
  input  wire              clear_valid,
  input  wire [NPORTS:0]   clear_mask,

  output wire [NPORTS:0]   pending,
  output reg  [NPORTS:0]   snapshot,        // the last bitmap actually sent
  output reg               snapshot_valid,
  output reg  [31:0]       nak_count,       // polls answered with no news
  output wire [NPORTS:0]   late_event,      // set AFTER the current snapshot
  output reg  [31:0]       late_count       // how often that window was hit
);
  localparam integer W = NPORTS + 1;

  reg [W-1:0] pending_r;
  reg [W-1:0] src_q;                        // previous level of the sources

  wire [W-1:0] src = {port_change, hub_change};

  // EDGE, not level -- chapter 18.2 learned this the expensive way. A level
  // would re-set the bit every cycle the port still had news, so a clear
  // could never take effect and the host would poll forever.
  wire [W-1:0] set_evt = src & ~src_q;

  assign pending      = pending_r;
  assign bitmap       = pending_r;
  // NOTHING TO REPORT IS NOT ZERO: with no bits set the endpoint NAKs.
  assign report_valid = (pending_r != {W{1'b0}});

  // The clear is MASKED BY THE SNAPSHOT. A bit the host did not see in the
  // bitmap it was given cannot be cleared by this acknowledgement, however
  // the host addressed it -- which is what makes an event arriving between
  // the poll and the clear survive.
  wire [W-1:0] eff_clear = (clear_valid && snapshot_valid)
                         ? (clear_mask & snapshot)
                         : {W{1'b0}};

  // Events arriving AFTER the snapshot the host is holding. These are the
  // ones the snapshot mask exists to protect: the host cannot have seen
  // them, so its acknowledgement must not be able to clear them. An output,
  // because a window this narrow is otherwise invisible -- and because the
  // testbench needs to prove the window was actually entered.
  assign late_event = set_evt & ~snapshot & {W{snapshot_valid}};

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      pending_r      <= {W{1'b0}};
      src_q          <= {W{1'b0}};
      snapshot       <= {W{1'b0}};
      snapshot_valid <= 1'b0;
      nak_count      <= 32'd0;
      late_count     <= 32'd0;
    end else begin
      src_q <= src;

      // SET BEATS CLEAR, as in chapter 18.2 and for the same reason: an
      // event arriving in the same cycle as the acknowledgement must
      // survive. Losing an ack costs one more poll; losing an event costs
      // a device that is never enumerated.
      pending_r <= (pending_r & ~eff_clear) | set_evt;

      if (|late_event) late_count <= late_count + 32'd1;

      if (poll_req) begin
        if (pending_r != {W{1'b0}}) begin
          // The host is handed THIS bitmap, so this is what it may clear.
          snapshot       <= pending_r;
          snapshot_valid <= 1'b1;
        end else begin
          nak_count      <= nak_count + 32'd1;
        end
      end
    end
  end
endmodule

package usb_status_pkg;
  // What the endpoint answers a poll with. NAK is a first-class response,
  // not the absence of one: an interrupt endpoint with no news says "ask
  // again later", and that is different from successfully reporting zero.
  typedef enum logic [1:0] {
    RESP_NAK,      // nothing pending -- the transfer does not complete
    RESP_DATA      // a bitmap is returned
  } poll_resp_e;
endpackage

// usb_hub_status_change_sv -- the hub's status-change endpoint.
//
// A hub cannot interrupt the host. Chapter 2.6's single-master model means
// the hub only ever ANSWERS, so every event chapter 18.2 recorded on a port
// waits in a register until the host asks for it.
//
// The asking is an interrupt IN transfer to this endpoint, and the answer is
// a BITMAP: bit 0 is the hub itself, bits N..1 are the downstream ports. One
// bit per port, regardless of how many things happened on it -- the bitmap
// says WHERE to look, never WHAT happened.
//
// Two things make this harder than a register read:
//
//  1. NOTHING TO REPORT IS NOT ZERO -- see poll_resp_e above.
//  2. THE HOST CLEARS WHAT IT READ, NOT WHAT IS THERE. Between the poll and
//     the clear, other ports keep setting bits. A host that cleared the
//     whole bitmap would discard events it never saw, and a device that
//     attached in that window would never be enumerated with nothing
//     anywhere recording the loss. So the clear is MASKED by the snapshot
//     the host actually received.
module usb_hub_status_change_sv
  import usb_status_pkg::*;
#(
  parameter int unsigned NPORTS = 4
) (
  input  logic              clk,
  input  logic              rst_n,
  input  logic [NPORTS-1:0] port_change,
  input  logic              hub_change,

  input  logic              poll_req,
  output logic [NPORTS:0]   bitmap,
  output logic              report_valid,
  output poll_resp_e        poll_resp,

  input  logic              clear_valid,
  input  logic [NPORTS:0]   clear_mask,

  output logic [NPORTS:0]   pending,
  output logic [NPORTS:0]   snapshot,
  output logic              snapshot_valid,
  output logic [31:0]       nak_count,
  output logic [NPORTS:0]   late_event,
  output logic [31:0]       late_count
);
  localparam int unsigned W = NPORTS + 1;

  initial begin
    if (NPORTS < 1)
      $fatal(1, "NPORTS=%0d: a hub with no downstream ports is not a hub",
             NPORTS);
    if (NPORTS > 31)
      $fatal(1, "NPORTS=%0d: the status-change bitmap would not fit",
             NPORTS);
  end

  logic [W-1:0] pending_r, src_q;
  wire  [W-1:0] src = {port_change, hub_change};

  // EDGE, not level -- chapter 18.2 learned this the expensive way. A level
  // would re-set the bit every cycle the port still had news, so a clear
  // could never take effect and the host would poll forever.
  wire  [W-1:0] set_evt = src & ~src_q;

  assign pending      = pending_r;
  assign bitmap       = pending_r;
  assign report_valid = (pending_r != '0);
  // Written as a branch rather than a ternary: a conditional expression
  // yielding an enum needs an explicit cast in some tools.
  always_comb begin
    if (pending_r != '0) poll_resp = RESP_DATA;
    else                 poll_resp = RESP_NAK;
  end

  // The clear is MASKED BY THE SNAPSHOT. A bit the host did not see in the
  // bitmap it was given cannot be cleared by this acknowledgement, however
  // the host addressed it.
  wire [W-1:0] eff_clear = (clear_valid && snapshot_valid)
                         ? (clear_mask & snapshot) : '0;

  // Events arriving AFTER the snapshot the host is holding -- the ones the
  // snapshot mask exists to protect. An output, because a window this
  // narrow is otherwise invisible.
  assign late_event = set_evt & ~snapshot & {W{snapshot_valid}};

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      pending_r <= '0; src_q <= '0; snapshot <= '0; snapshot_valid <= 1'b0;
      nak_count <= '0; late_count <= '0;
    end else begin
      src_q <= src;
      // SET BEATS CLEAR, as in chapter 18.2 and for the same reason: losing
      // an acknowledgement costs one more poll; losing an event costs a
      // device that is never enumerated.
      pending_r <= (pending_r & ~eff_clear) | set_evt;

      if (|late_event) late_count <= late_count + 1;

      if (poll_req) begin
        if (pending_r != '0) begin
          snapshot       <= pending_r;   // what the host may now clear
          snapshot_valid <= 1'b1;
        end else begin
          nak_count      <= nak_count + 1;
        end
      end
    end
  end
endmodule

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

package usb_status_pkg is
  -- What the endpoint answers a poll with. NAK is a first-class response,
  -- not the absence of one: an interrupt endpoint with no news says "ask
  -- again later", and that is different from successfully reporting zero.
  type poll_resp_t is (RESP_NAK, RESP_DATA);
end package;

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

-- usb_hub_status_change_vhdl -- the hub's status-change endpoint.
--
-- A hub cannot interrupt the host. Chapter 2.6's single-master model means
-- the hub only ever ANSWERS, so every event chapter 18.2 recorded on a port
-- waits in a register until the host asks for it.
--
-- The asking is an interrupt IN transfer to this endpoint, and the answer is
-- a BITMAP: bit 0 is the hub itself, bits N..1 are the downstream ports. One
-- bit per port, regardless of how many things happened on it -- the bitmap
-- says WHERE to look, never WHAT happened.
--
-- Two things make this harder than a register read:
--
--  1. NOTHING TO REPORT IS NOT ZERO -- see poll_resp_t above.
--  2. THE HOST CLEARS WHAT IT READ, NOT WHAT IS THERE. Between the poll and
--     the clear, other ports keep setting bits. A host that cleared the
--     whole bitmap would discard events it never saw, and a device that
--     attached in that window would never be enumerated with nothing
--     anywhere recording the loss. So the clear is MASKED by the snapshot
--     the host actually received.
entity usb_hub_status_change_vhdl is
  generic ( NPORTS : positive := 4 );
  port (
    clk            : in  std_logic;
    rst_n          : in  std_logic;
    port_change    : in  std_logic_vector(NPORTS-1 downto 0);
    hub_change     : in  std_logic;

    poll_req       : in  std_logic;
    bitmap         : out std_logic_vector(NPORTS downto 0);
    report_valid   : out std_logic;
    poll_resp      : out poll_resp_t;

    clear_valid    : in  std_logic;
    clear_mask     : in  std_logic_vector(NPORTS downto 0);

    pending        : out std_logic_vector(NPORTS downto 0);
    snapshot       : out std_logic_vector(NPORTS downto 0);
    snapshot_valid : out std_logic;
    nak_count      : out unsigned(31 downto 0);
    late_event     : out std_logic_vector(NPORTS downto 0);
    late_count     : out unsigned(31 downto 0)
  );
end entity;

architecture rtl of usb_hub_status_change_vhdl is
  constant W    : positive := NPORTS + 1;
  constant ZERO : std_logic_vector(W-1 downto 0) := (others => '0');

  signal pending_r : std_logic_vector(W-1 downto 0) := (others => '0');
  signal src_q     : std_logic_vector(W-1 downto 0) := (others => '0');
  signal snap_r    : std_logic_vector(W-1 downto 0) := (others => '0');
  signal snapv_r   : std_logic := '0';
  signal nak_r     : unsigned(31 downto 0) := (others => '0');
  signal late_r    : unsigned(31 downto 0) := (others => '0');

  signal src, set_evt, eff_clear, late_i : std_logic_vector(W-1 downto 0);
begin
  assert NPORTS >= 1
    report "a hub with no downstream ports is not a hub" severity failure;
  assert NPORTS <= 31
    report "the status-change bitmap would not fit" severity failure;

  src <= port_change & hub_change;

  -- EDGE, not level -- chapter 18.2 learned this the expensive way. A level
  -- would re-set the bit every cycle the port still had news, so a clear
  -- could never take effect and the host would poll forever.
  set_evt <= src and (not src_q);

  pending        <= pending_r;
  bitmap         <= pending_r;
  snapshot       <= snap_r;
  snapshot_valid <= snapv_r;
  nak_count      <= nak_r;
  late_count     <= late_r;

  report_valid <= '1' when pending_r /= ZERO else '0';
  poll_resp    <= RESP_DATA when pending_r /= ZERO else RESP_NAK;

  -- The clear is MASKED BY THE SNAPSHOT. A bit the host did not see in the
  -- bitmap it was given cannot be cleared by this acknowledgement.
  eff_clear <= (clear_mask and snap_r)
               when (clear_valid = '1' and snapv_r = '1') else ZERO;

  -- Events arriving AFTER the snapshot the host is holding -- the ones the
  -- snapshot mask exists to protect. An output, because a window this
  -- narrow is otherwise invisible.
  late_i     <= set_evt and (not snap_r) when snapv_r = '1' else ZERO;
  late_event <= late_i;

  process (clk, rst_n)
  begin
    if rst_n = '0' then
      pending_r <= (others => '0'); src_q <= (others => '0');
      snap_r <= (others => '0'); snapv_r <= '0';
      nak_r <= (others => '0'); late_r <= (others => '0');
    elsif rising_edge(clk) then
      src_q <= src;
      -- SET BEATS CLEAR, as in chapter 18.2 and for the same reason: losing
      -- an acknowledgement costs one more poll; losing an event costs a
      -- device that is never enumerated.
      pending_r <= (pending_r and (not eff_clear)) or set_evt;

      if late_i /= ZERO then late_r <= late_r + 1; end if;

      if poll_req = '1' then
        if pending_r /= ZERO then
          snap_r  <= pending_r;    -- what the host may now clear
          snapv_r <= '1';
        else
          nak_r   <= nak_r + 1;
        end if;
      end if;
    end if;
  end process;
end architecture;

    // 32 pending patterns x 32 clear masks x 32 new-event patterns = 32768
    // points -- the entire interaction this chapter is about.
    for (a=0; a<32; a=a+1)
     for (b=0; b<32; b=b+1)
      for (c=0; c<32; c=c+1) begin
        hard_reset;
        // raise the sources to create `a` as edges
        step(a[4:1], a[0], 0, 0, 5'd0);
        // poll: the host receives this bitmap and may clear only these bits
        step(a[4:1], a[0], 1, 0, 5'd0);
        // NOW: new events on other bits arrive in the SAME cycle as the
        // host's acknowledgement of what it read a cycle ago.
        step(a[4:1] | c[4:1], a[0] | c[0], 0, 1, b[4:0]);
        n_exh = n_exh + 1;
      end

      // --- THE INVARIANT, independent of the model ---
      // An event bit is never removed from pending unless the host cleared a
      // bit it had ACTUALLY BEEN SHOWN. This is the whole chapter.
      check(((~pending) & m_pend & ~eff) === {W{1'b0}},
            "a pending event vanished without an acknowledged clear");
      // A bit the host was never shown can never be cleared by an ack.
      check((eff & ~snap_before) === {W{1'b0}},
            "a clear reached a bit that was not in the snapshot it acknowledged");

      // The clear refers to the bitmap the host was handed EARLIER, so it
      // is governed by the snapshot as it stands BEFORE this edge. A poll
      // arriving in the same cycle installs a new snapshot, and that new
      // one governs the NEXT acknowledgement, not this one.
      snap_before = m_snap;
      eff = (clr && m_snapv) ? (cm & snap_before) : {W{1'b0}};

  exhaustive snapshot/clear/late sweep: 32768 of 32768 points verified

  Verilog / SystemVerilog:
  REACH: exhaustive=32768 polls=46173 naks=1065 late-event cycles=32008
  [Verilog] usb_hub_status_change: 0 errors — PASS

  VHDL:
  REACH: exhaustive=32768 polls=45943 naks=1068 late-event cycles=31966
  [VHDL] usb_hub_status_change_vhdl: 0 errors — PASS

// The host's side of section 3, as a sequence. The GAP between the poll and
// the clear is the point: it is randomised, because a window that is always
// the same length is a window whose corner cases never appear.
class host_poll_seq extends uvm_sequence #(host_txn);
  `uvm_object_utils(host_poll_seq)
  rand int unsigned gap;
  constraint c_gap { gap inside {[0:8]}; }

  task body();
    host_txn poll, clr;
    `uvm_do_with(poll, { kind == POLL; })
    if (poll.rsp == RESP_NAK) return;   // nothing to acknowledge

    repeat (gap) #10ns;                 // the host thinks; ports keep firing

    // Clear ONLY what the poll returned. A sequence that cleared '1 here
    // would be modelling the buggy host of section 3 -- which is exactly
    // what bad_host_seq below does deliberately.
    `uvm_do_with(clr, { kind == CLEAR; mask == poll.bitmap; })
  endtask
endclass

// The buggy host, kept as a NEGATIVE test: the DUT must survive it.
class bad_host_seq extends uvm_sequence #(host_txn);
  `uvm_object_utils(bad_host_seq)
  task body();
    host_txn poll, clr;
    `uvm_do_with(poll, { kind == POLL; })
    if (poll.rsp == RESP_NAK) return;
    repeat (4) #10ns;
    `uvm_do_with(clr, { kind == CLEAR; mask == '1; })   // blanket clear
  endtask
endclass

class discovery_scoreboard extends uvm_scoreboard;
  `uvm_component_utils(discovery_scoreboard)

  // Its OWN model of what has been reported and acknowledged (17.3).
  local bit [31:0] m_pending, m_snapshot;
  local bit        m_snap_valid;

  // Every event that ever occurred, and every event the host was told about.
  local int unsigned events_raised [int];
  local int unsigned events_reported [int];

  function void write_port_event(int port);
    events_raised[port]++;
  endfunction

  function void write_poll(bit [31:0] bmp);
    foreach (bmp[i]) if (bmp[i]) events_reported[i]++;
    m_snapshot = bmp; m_snap_valid = 1;
  endfunction

  // THE property: no event is ever lost. Not "the bitmap matched" -- that
  // is checkable cycle by cycle and misses the failure entirely, because
  // the bitmap is correct at every instant while the EVENT disappears.
  function void check_phase(uvm_phase phase);
    foreach (events_raised[p])
      if (events_reported.exists(p) == 0 || events_reported[p] == 0)
        `uvm_error("DISC/LOST", $sformatf(
          "port %0d raised %0d event(s) and the host was never told about any",
          p, events_raised[p]))
  endfunction
endclass

covergroup discovery_cg with function sample(
    int unsigned gap, bit late_during_gap, bit blanket);
  // How long the host took between reading and acknowledging.
  cp_gap : coverpoint gap { bins none = {0}; bins short = {[1:3]};
                            bins long = {[4:8]}; }
  // Did a port fire inside that window? This is the bin that matters:
  // without it, a run can pass with the race never once occurring.
  cp_late : coverpoint late_during_gap { bins raced = {1}; }
  cp_blanket : coverpoint blanket { bins buggy_host = {1}; }
  x_race : cross cp_gap, cp_late, cp_blanket;
endgroup

  // Nothing to report is a NAK, not a zero bitmap.
  property p_nak_when_empty;
    @(posedge clk) disable iff (!rst_n)
      (pending == '0) |-> !report_valid;
  endproperty
  a_nak_when_empty : assert property (p_nak_when_empty);

  // THE property: a clear never reaches a bit outside the snapshot the host
  // was handed. Section 3 in one line.
  property p_clear_within_snapshot;
    @(posedge clk) disable iff (!rst_n)
      (clear_valid && snapshot_valid)
        |=> ((~pending & $past(pending) & ~$past(snapshot)) == '0);
  endproperty
  a_clear_within_snapshot : assert property (p_clear_within_snapshot)
    else $error("an event the host never saw was cleared");

  // An event arriving in the same cycle as its own clear survives it.
  property p_set_beats_clear;
    @(posedge clk) disable iff (!rst_n)
      ($rose(port_change[0]) && clear_valid) |=> pending[1];
  endproperty
  a_set_beats_clear : assert property (p_set_beats_clear);

  // A NAKed poll installs no snapshot.
  property p_nak_takes_no_snapshot;
    @(posedge clk) disable iff (!rst_n)
      (poll_req && pending == '0) |=> $stable(snapshot);
  endproperty
  a_nak_no_snapshot : assert property (p_nak_takes_no_snapshot);