Hub Power Management

   a bus-powered hub may draw            500 mA   from its upstream port
   it must run its own controller from   that same 500 mA
   it must then supply                     4 ports
   at a full load each that would need  2000 mA

   remaining = hdev->bus_mA - hub->descriptor->bHubContrCurrent;
   hub->mA_per_port = unit_load;      /* 7.2.1 */

   available = upstream_mA − bHubContrCurrent

   "insufficient power available to use all downstream ports"

// usb_hub_power_budget -- who gets how much current, and who is refused.
//
// Chapter 18.2 gave every port a PORT_POWER command and an over-current
// input and treated both as inputs to a state machine. They are not inputs;
// they are a resource with a budget, and the budget does not balance.
//
// The arithmetic that does not work:
//
//   a bus-powered hub may draw            500 mA from its upstream port
//   it must run its own controller from   that same 500 mA
//   it must then supply                   4 downstream ports
//   at a full load each that would need   2000 mA
//
// The resolution is that a bus-powered hub does NOT offer a full load. It
// offers ONE UNIT LOAD -- 100 mA -- to each port, and a device needing more
// is refused. Linux writes exactly this, with a specification reference
// attached to the line:
//
//     remaining = hdev->bus_mA - hub->descriptor->bHubContrCurrent;
//     hub->mA_per_port = unit_load;   /* 7.2.1 */
//
// A SELF-powered hub has its own supply and offers a full load per port.
// This is the entire practical difference between the two kinds of hub, and
// it is why a bus-powered hub cannot run a bus-powered hard drive.
module usb_hub_power_budget #(
  parameter integer NPORTS     = 4,
  parameter integer UNIT_LOAD  = 100,   // one unit load, mA (USB 2.0)
  parameter integer FULL_LOAD  = 500,   // five unit loads, mA
  parameter integer SELF_SUPPLY = 2500  // what a self-powered hub can source
) (
  input  wire                  clk,
  input  wire                  rst_n,

  input  wire                  self_powered,
  input  wire [15:0]           upstream_mA,     // what the hub may draw
  input  wire [15:0]           contr_current,   // bHubContrCurrent
  input  wire [NPORTS*16-1:0]  req_mA_flat,     // per-port request
  input  wire [NPORTS-1:0]     req_valid,
  input  wire [NPORTS-1:0]     overcurrent,

  output wire [15:0]           mA_per_port,     // what a port is OFFERED
  output wire [15:0]           available,       // what the hub can source
  output wire                  limited_power,   // ports get less than a full load
  output reg  [NPORTS-1:0]     grant,
  output reg  [15:0]           total_granted,
  output wire                  insufficient,    // cannot supply every port
  output reg                   ever_insufficient
);
  // A self-powered hub offers a FULL load; a bus-powered hub offers ONE
  // unit load. There is no arithmetic here to get wrong -- the number is
  // fixed by the specification, not derived from what happens to be spare.
  assign mA_per_port   = self_powered ? FULL_LOAD[15:0] : UNIT_LOAD[15:0];
  assign limited_power = !self_powered;

  // SATURATING subtraction. A hub whose controller is declared to draw more
  // than its upstream port supplies is a malformed descriptor, and the
  // wrapped answer -- an enormous budget -- is the single worst response
  // available: it would grant every port and brown out the whole tree.
  wire [15:0] bus_avail = (upstream_mA > contr_current)
                        ? (upstream_mA - contr_current) : 16'd0;
  assign available = self_powered ? SELF_SUPPLY[15:0] : bus_avail;

  // Linux warns "insufficient power available to use all downstream ports"
  // on exactly this condition. It is a WARNING, not a refusal: the hub
  // still works, it simply cannot power every port at once.
  assign insufficient = (available < (NPORTS * mA_per_port));

  // Allocation, in port order. A fixed order rather than a policy, because
  // the host -- not the hub -- decides which devices matter, and a hub that
  // reordered would make the host's decisions non-reproducible.
  integer i;
  reg [15:0] req_i;
  reg [16:0] running;          // 17 bits: the sum must not wrap mid-loop
  always @* begin
    grant   = {NPORTS{1'b0}};
    running = 17'd0;
    for (i = 0; i < NPORTS; i = i + 1) begin
      req_i = req_mA_flat[i*16 +: 16];
      // Three independent reasons to refuse, and they are not the same:
      //   * the port is in over-current -- it gets nothing, whatever it asked
      //   * the request exceeds what a port is OFFERED (the unit-load rule)
      //   * the request exceeds what the hub has LEFT (the budget)
      if (req_valid[i] && !overcurrent[i]
          && (req_i <= mA_per_port)
          && ((running + {1'b0, req_i}) <= {1'b0, available})) begin
        grant[i] = 1'b1;
        running  = running + {1'b0, req_i};
      end
    end
    total_granted = running[15:0];
  end

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n)           ever_insufficient <= 1'b0;
    else if (insufficient) ever_insufficient <= 1'b1;
  end
endmodule

package usb_power_pkg;
  // Where a hub's downstream current comes from. This is not a status bit:
  // it decides what every port is OFFERED, and those two answers differ by
  // a factor of five.
  typedef enum logic {
    PWR_BUS,    // drawn from the upstream port -- one unit load per port
    PWR_SELF    // the hub has its own supply   -- a full load per port
  } power_src_e;
endpackage

// usb_hub_power_budget_sv -- who gets how much current, and who is refused.
//
// Chapter 18.2 gave every port a PORT_POWER command and an over-current
// input and treated both as inputs to a state machine. They are not inputs;
// they are a resource with a budget, and the budget does not balance.
//
// The arithmetic that does not work:
//
//   a bus-powered hub may draw            500 mA from its upstream port
//   it must run its own controller from   that same 500 mA
//   it must then supply                   4 downstream ports
//   at a full load each that would need   2000 mA
//
// The resolution is that a bus-powered hub does NOT offer a full load. It
// offers ONE UNIT LOAD -- 100 mA -- to each port, and a device needing more
// is refused. Linux writes exactly this, with a specification reference
// attached to the line:
//
//     remaining = hdev->bus_mA - hub->descriptor->bHubContrCurrent;
//     hub->mA_per_port = unit_load;   /* 7.2.1 */
module usb_hub_power_budget_sv
  import usb_power_pkg::*;
#(
  parameter int unsigned NPORTS      = 4,
  parameter int unsigned UNIT_LOAD   = 100,
  parameter int unsigned FULL_LOAD   = 500,
  parameter int unsigned SELF_SUPPLY = 2500
) (
  input  logic                 clk,
  input  logic                 rst_n,

  input  power_src_e           power_src,
  input  logic [15:0]          upstream_mA,
  input  logic [15:0]          contr_current,
  input  logic [NPORTS*16-1:0] req_mA_flat,
  input  logic [NPORTS-1:0]    req_valid,
  input  logic [NPORTS-1:0]    overcurrent,

  output logic [15:0]          mA_per_port,
  output logic [15:0]          available,
  output logic                 limited_power,
  output logic [NPORTS-1:0]    grant,
  output logic [15:0]          total_granted,
  output logic                 insufficient,
  output logic                 ever_insufficient
);
  initial begin
    if (UNIT_LOAD > FULL_LOAD)
      $fatal(1, "UNIT_LOAD=%0d exceeds FULL_LOAD=%0d: a unit load is a fraction of a full one",
             UNIT_LOAD, FULL_LOAD);
    if (NPORTS < 1)
      $fatal(1, "NPORTS=%0d: a hub with no downstream ports is not a hub",
             NPORTS);
  end

  wire self_powered = (power_src == PWR_SELF);

  // A self-powered hub offers a FULL load; a bus-powered hub offers ONE
  // unit load. There is no arithmetic here to get wrong -- the number is
  // fixed by the specification, not derived from what happens to be spare.
  assign mA_per_port   = self_powered ? 16'(FULL_LOAD) : 16'(UNIT_LOAD);
  assign limited_power = !self_powered;

  // SATURATING subtraction. A hub whose controller is declared to draw more
  // than its upstream port supplies is a malformed descriptor, and the
  // wrapped answer -- an enormous budget -- is the single worst response
  // available: it would grant every port and brown out the whole tree.
  wire [15:0] bus_avail = (upstream_mA > contr_current)
                        ? (upstream_mA - contr_current) : 16'd0;
  assign available = self_powered ? 16'(SELF_SUPPLY) : bus_avail;

  // Linux warns "insufficient power available to use all downstream ports"
  // on exactly this condition. It is a WARNING, not a refusal: the hub
  // still works, it simply cannot power every port at once.
  assign insufficient = (available < 16'(NPORTS * mA_per_port));

  // Declared at module scope rather than inside the process: `running` is
  // 17 bits so the running sum cannot wrap mid-loop, and its low half is
  // the reported total.
  logic [15:0] req_i;
  logic [16:0] running;
  // Allocation, in port order. A fixed order rather than a policy, because
  // the host -- not the hub -- decides which devices matter, and a hub that
  // reordered would make the host's decisions non-reproducible.
  always_comb begin
    grant   = '0;
    running = '0;
    for (int i = 0; i < int'(NPORTS); i++) begin
      req_i = req_mA_flat[i*16 +: 16];
      // Three independent reasons to refuse, and they are not the same:
      //   * the port is in over-current -- it gets nothing, whatever it asked
      //   * the request exceeds what a port is OFFERED (the unit-load rule)
      //   * the request exceeds what the hub has LEFT (the budget)
      if (req_valid[i] && !overcurrent[i]
          && (req_i <= mA_per_port)
          && ((running + 17'(req_i)) <= 17'(available))) begin
        grant[i] = 1'b1;
        running  = running + 17'(req_i);
      end
    end
  end
  // Continuous, so the 17-bit running sum is narrowed in one place and the
  // process has no part-select in it.
  assign total_granted = running[15:0];

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n)            ever_insufficient <= 1'b0;
    else if (insufficient) ever_insufficient <= 1'b1;
  end
endmodule

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

package usb_power_pkg is
  -- Where a hub's downstream current comes from. This is not a status bit:
  -- it decides what every port is OFFERED, and those two answers differ by
  -- a factor of five.
  type power_src_t is (
    PWR_BUS,    -- drawn from the upstream port -- one unit load per port
    PWR_SELF    -- the hub has its own supply   -- a full load per port
  );

  -- An UNCONSTRAINED array of per-port requests. The Verilog and
  -- SystemVerilog flatten this into one wide vector and slice it back out
  -- with a part-select, because neither has an array port that carries its
  -- own element width. Here the port is what it actually is.
  type ma_array_t is array (natural range <>) of unsigned(15 downto 0);
end package;

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

-- usb_hub_power_budget_vhdl -- who gets how much current, and who is refused.
--
-- Chapter 18.2 gave every port a PORT_POWER command and an over-current
-- input and treated both as inputs to a state machine. They are not inputs;
-- they are a resource with a budget, and the budget does not balance.
--
-- The arithmetic that does not work:
--
--   a bus-powered hub may draw            500 mA from its upstream port
--   it must run its own controller from   that same 500 mA
--   it must then supply                   4 downstream ports
--   at a full load each that would need   2000 mA
--
-- The resolution is that a bus-powered hub does NOT offer a full load. It
-- offers ONE UNIT LOAD -- 100 mA -- to each port, and a device needing more
-- is refused. Linux writes exactly this, with a specification reference
-- attached to the line:
--
--     remaining = hdev->bus_mA - hub->descriptor->bHubContrCurrent;
--     hub->mA_per_port = unit_load;   /* 7.2.1 */
entity usb_hub_power_budget_vhdl is
  generic (
    NPORTS      : positive := 4;
    UNIT_LOAD   : positive := 100;
    FULL_LOAD   : positive := 500;
    SELF_SUPPLY : positive := 2500
  );
  port (
    clk               : in  std_logic;
    rst_n             : in  std_logic;

    power_src         : in  power_src_t;
    upstream_mA       : in  unsigned(15 downto 0);
    contr_current     : in  unsigned(15 downto 0);
    req_mA            : in  ma_array_t(0 to NPORTS-1);
    req_valid         : in  std_logic_vector(NPORTS-1 downto 0);
    overcurrent       : in  std_logic_vector(NPORTS-1 downto 0);

    mA_per_port       : out unsigned(15 downto 0);
    available         : out unsigned(15 downto 0);
    limited_power     : out std_logic;
    grant             : out std_logic_vector(NPORTS-1 downto 0);
    total_granted     : out unsigned(15 downto 0);
    insufficient      : out std_logic;
    ever_insufficient : out std_logic
  );
end entity;

architecture rtl of usb_hub_power_budget_vhdl is
  signal self_powered : boolean;
  signal mpp_i        : unsigned(15 downto 0);
  signal avail_i      : unsigned(15 downto 0);
  signal insuf_i      : std_logic;
  signal ever_r       : std_logic := '0';
begin
  assert UNIT_LOAD <= FULL_LOAD
    report "a unit load is a fraction of a full load, not more than one"
    severity failure;

  self_powered <= power_src = PWR_SELF;

  -- A self-powered hub offers a FULL load; a bus-powered hub offers ONE
  -- unit load. There is no arithmetic here to get wrong -- the number is
  -- fixed by the specification, not derived from what happens to be spare.
  mpp_i <= to_unsigned(FULL_LOAD, 16) when self_powered
           else to_unsigned(UNIT_LOAD, 16);
  mA_per_port   <= mpp_i;
  limited_power <= '0' when self_powered else '1';

  -- SATURATING subtraction. A hub whose controller is declared to draw more
  -- than its upstream port supplies is a malformed descriptor, and the
  -- wrapped answer -- an enormous budget -- is the single worst response
  -- available: it would grant every port and brown out the whole tree.
  avail_i <= to_unsigned(SELF_SUPPLY, 16) when self_powered else
             (upstream_mA - contr_current) when upstream_mA > contr_current
             else to_unsigned(0, 16);
  available <= avail_i;

  -- Linux warns "insufficient power available to use all downstream ports"
  -- on exactly this condition. It is a WARNING, not a refusal: the hub
  -- still works, it simply cannot power every port at once.
  insuf_i <= '1' when avail_i < resize(mpp_i * NPORTS, 16) else '0';
  insufficient <= insuf_i;

  -- Allocation, in port order. A fixed order rather than a policy, because
  -- the host -- not the hub -- decides which devices matter, and a hub that
  -- reordered would make the host's decisions non-reproducible.
  process (req_mA, req_valid, overcurrent, mpp_i, avail_i)
    variable running : unsigned(16 downto 0);  -- 17 bits: no mid-loop wrap
    variable g       : std_logic_vector(NPORTS-1 downto 0);
  begin
    g       := (others => '0');
    running := (others => '0');
    for i in 0 to NPORTS-1 loop
      -- Three independent reasons to refuse, and they are not the same:
      --   * the port is in over-current -- it gets nothing, whatever it asked
      --   * the request exceeds what a port is OFFERED (the unit-load rule)
      --   * the request exceeds what the hub has LEFT (the budget)
      if req_valid(i) = '1' and overcurrent(i) = '0'
         and req_mA(i) <= mpp_i
         and (running + ('0' & req_mA(i))) <= ('0' & avail_i) then
        g(i)    := '1';
        running := running + ('0' & req_mA(i));
      end if;
    end loop;
    grant         <= g;
    total_granted <= running(15 downto 0);
  end process;

  process (clk, rst_n)
  begin
    if rst_n = '0' then
      ever_r <= '0';
    elsif rising_edge(clk) then
      if insuf_i = '1' then ever_r <= '1'; end if;
    end if;
  end process;
  ever_insufficient <= ever_r;
end architecture;

    for (sp=0; sp<2; sp=sp+1)
     for (r=0; r<256; r=r+1)
      for (oc=0; oc<16; oc=oc+1)
       for (bg=0; bg<5; bg=bg+1) begin
        apply(r[7:0], {N{1'b1}}, oc[N-1:0], sp[0], UPS[bg], CCR[bg]);
        n_exh = n_exh + 1;
        ...
       end

      // ---- SAFETY PROPERTIES, independent of the model ----
      // 1. THE one that matters: never promise more than you have.
      check(total_granted <= available,
            "the hub granted more current than it can source");
      // 2. No granted port was offered more than the per-port limit.
      for (j = 0; j < N; j = j + 1)
        if (grant[j])
          check(req_flat[j*16 +: 16] <= mA_per_port,
                "a port was granted more than a port is offered");
      // 3. A port in over-current is never granted anything.
      check((grant & overcurrent) === {N{1'b0}},
            "an over-current port was granted power");
      // 4. A bus-powered hub never offers a full load.
      check(self_powered || (mA_per_port <= UL),
            "a bus-powered hub offered more than one unit load");
      // 5. Nothing is granted to a port that did not ask.
      check((grant & ~req_valid) === {N{1'b0}},
            "a port that did not request power was granted some");

  exhaustive power-budget sweep: 40960 of 40960 points verified

  REACH: exhaustive=40960 grants-in-sweep=59008 budget-exactly-spent=2048
  [Verilog] usb_hub_power_budget: 0 errors — PASS
  [SystemVerilog] usb_hub_power_budget_sv: 0 errors — PASS
  [VHDL] usb_hub_power_budget_vhdl: 0 errors — PASS

  // available = 0, 100, 200, 300, 400. Chosen to ALIGN with the sums the
  // request alphabet can actually produce (multiples of 100 under the
  // bus-powered per-port cap), so the inclusive bound -- running + req
  // exactly equal to the budget -- is reached constantly rather than once.

    apply(8'b00000011, 4'b0001, 4'b0000, 1'b0, 16'd500, 16'd100);
    check(mA_per_port === 16'd100, "a bus-powered hub offers ONE unit load");
    check(!grant[0], "so a 500 mA device is refused outright");
    check(insufficient, "and the hub warns it cannot supply every port");  // WRONG

    // 500 upstream less 100 for the controller leaves 400, which is EXACTLY
    // four unit loads -- so this hub is not short of power at all. The
    // device is refused by the PER-PORT offer, not by the budget, and those
    // are different refusals. The first version of this check asserted
    // `insufficient` here and was simply wrong about which rule applies.
    check(!insufficient, "this hub CAN supply every port -- 400 = 4 x 100");

    // a hub that genuinely cannot: a hungrier controller
    apply(8'b01010101, 4'b1111, 4'b0000, 1'b0, 16'd500, 16'd200);
    check(available === 16'd300, "500 upstream less 200 for the controller");
    check(insufficient, "300 mA cannot supply four ports at 100 mA each");
    check(grant === 4'b0111, "so the fourth port gets nothing");

class power_request_item extends uvm_sequence_item;
  `uvm_object_utils(power_request_item)
  rand bit [15:0] req_mA [4];
  rand bit [3:0]  req_valid;
  rand bit [3:0]  overcurrent;
  rand bit [15:0] upstream_mA, contr_current;
  rand power_src_e power_src;

  // Requests are drawn from the alphabet devices actually declare, not
  // uniformly over 16 bits -- a random 16-bit request is refused by the
  // per-port rule before the budget is ever consulted.
  constraint c_realistic {
    foreach (req_mA[i]) req_mA[i] inside {0, 100, 200, 500};
    contr_current inside {[0:300]};
    upstream_mA   inside {100, 200, 300, 400, 500};
  }

  // THE constraint section 12 is about: make the total land ON the budget,
  // not merely near it. A sweep that never lands exactly on the boundary
  // cannot tell an inclusive bound from an exclusive one.
  constraint c_on_the_boundary {
    solve upstream_mA, contr_current before req_mA;
    (upstream_mA > contr_current) ->
      (req_mA.sum() with (int'(item)) == int'(upstream_mA - contr_current));
  }
endclass

class power_scoreboard extends uvm_scoreboard;
  `uvm_component_utils(power_scoreboard)

  // Its OWN recomputation of the offer and the budget (17.3).
  function void write(power_txn t);
    int unsigned m_mpp   = (t.power_src == PWR_SELF) ? FULL_LOAD : UNIT_LOAD;
    int unsigned m_avail = (t.power_src == PWR_SELF) ? SELF_SUPPLY
                         : (t.upstream_mA > t.contr_current
                            ? t.upstream_mA - t.contr_current : 0);
    int unsigned total = 0;

    foreach (t.grant[i]) if (t.grant[i]) total += t.req_mA[i];

    // THE property. Not "the grant matched" -- this one has physical
    // consequences, and it is the reason the block exists.
    if (total > m_avail)
      `uvm_error("PWR/OVER", $sformatf(
        "granted %0d mA from a %0d mA budget", total, m_avail))

    // The unit-load rule, per port.
    foreach (t.grant[i])
      if (t.grant[i] && t.req_mA[i] > m_mpp)
        `uvm_error("PWR/OFFER", $sformatf(
          "port %0d granted %0d mA where a port is offered %0d",
          i, t.req_mA[i], m_mpp))

    // Over-current outranks everything.
    foreach (t.grant[i])
      if (t.grant[i] && t.overcurrent[i])
        `uvm_error("PWR/OC", $sformatf(
          "port %0d granted power while in over-current", i))
  endfunction
endclass

covergroup power_cg with function sample(
    power_src_e src, int unsigned avail, int unsigned total, bit oc_any);
  cp_src   : coverpoint src;
  cp_oc    : coverpoint oc_any { bins fault = {1}; }
  // The bin section 12's sweep did not have: the budget SPENT EXACTLY.
  // With the original fixed supply this bin would have read 1.
  cp_exact : coverpoint (total == avail && avail != 0) { bins spent = {1}; }
  // And the budget actually binding, rather than the per-port rule.
  cp_bound : coverpoint (total == avail) iff (avail != 0);
  x_src_exact : cross cp_src, cp_exact;
endgroup

  // THE property: never promise more current than you can source.
  property p_never_over_budget;
    @(posedge clk) disable iff (!rst_n)
      total_granted <= available;
  endproperty
  a_never_over_budget : assert property (p_never_over_budget)
    else $error("the hub granted more current than it can source");

  // A bus-powered hub never offers more than one unit load. Section 1.
  property p_unit_load_when_bus_powered;
    @(posedge clk) disable iff (!rst_n)
      (power_src == PWR_BUS) |-> (mA_per_port == UNIT_LOAD);
  endproperty
  a_unit_load : assert property (p_unit_load_when_bus_powered);

  // Over-current outranks every other consideration. Mutation P4.
  property p_overcurrent_blocks;
    @(posedge clk) disable iff (!rst_n)
      (grant & overcurrent) == '0;
  endproperty
  a_overcurrent_blocks : assert property (p_overcurrent_blocks);

  // The budget saturates rather than wrapping. Mutation P2, stated as the
  // consequence rather than the mechanism: a deficit yields nothing.
  property p_saturating_budget;
    @(posedge clk) disable iff (!rst_n)
      (power_src == PWR_BUS && contr_current >= upstream_mA)
        |-> (available == '0);
  endproperty
  a_saturating_budget : assert property (p_saturating_budget);