Bus Power

   /* SuperSpeed power is in 8 mA units; others are in 2 mA units */
   unsigned mul = (udev->speed >= USB_SPEED_SUPER ? 8 : 2);
   return c->desc.bMaxPower * mul;

// usb_bus_power_negotiate -- what a bus-powered device may draw, and when.
//
// Module 18 asked what a HUB can supply. This asks what a DEVICE may take,
// and the two are different questions with different answers at different
// times.
//
// The rule that surprises people is that a device's allowance CHANGES
// during enumeration, and it changes exactly once:
//
//   BEFORE SetConfiguration   one unit load. Always. However much the
//                             device declared it wants, however much the
//                             port has spare. The host has not yet agreed
//                             to anything, and a device that helped itself
//                             to 500 mA while merely attached could brown
//                             out a port before anyone had read a
//                             descriptor from it.
//
//   AFTER SetConfiguration    bMaxPower, scaled -- and only if the host
//                             accepted the configuration. If the port
//                             cannot supply it, SetConfiguration FAILS and
//                             the device stays at one unit load, addressed
//                             and enumerated and unusable.
//
// bMaxPower is stored in UNITS, not milliamps, and the unit depends on the
// speed: SuperSpeed counts in 8 mA, everything else in 2 mA. Linux:
//
//     /* SuperSpeed power is in 8 mA units; others are in 2 mA units */
//     unsigned mul = (udev->speed >= USB_SPEED_SUPER ? 8 : 2);
//     return c->desc.bMaxPower * mul;
//
// An 8-bit field times 2 is 510 mA, which is why a USB 2.0 device can ask
// for the full 500 mA in one byte and not a milliamp more.
module usb_bus_power_negotiate #(
  parameter integer UNIT_LOAD_HS = 100,   // one unit load, USB 2.0, mA
  parameter integer UNIT_LOAD_SS = 150    // one unit load, SuperSpeed, mA
) (
  input  wire        clk,
  input  wire        rst_n,

  input  wire        vbus_present,
  input  wire        superspeed,       // scales BOTH the unit load and bMaxPower
  input  wire [7:0]  b_max_power,      // the descriptor field, in UNITS
  input  wire [15:0] port_offers_mA,   // what the hub said this port supplies

  input  wire        set_config,       // host issues SetConfiguration
  input  wire        set_config_zero,  // SetConfiguration(0) -- deconfigure
  input  wire        detach,

  output wire [15:0] unit_load_mA,
  output wire [15:0] requested_mA,     // bMaxPower scaled into milliamps
  output wire        request_fits,     // the port can supply the request
  output reg         configured,
  output wire [15:0] allowance_mA,     // what the device may draw RIGHT NOW
  output reg         config_refused,   // sticky: a SetConfiguration failed
  output reg  [31:0] refusal_count
);
  // The unit load is a property of the SPEED, not of the request. A
  // SuperSpeed device gets a bigger floor as well as a bigger ceiling.
  assign unit_load_mA = superspeed ? UNIT_LOAD_SS[15:0] : UNIT_LOAD_HS[15:0];

  // bMaxPower is in units. Widened to 16 bits BEFORE the multiply so the
  // product cannot wrap: 255 * 8 is 2040, which does not fit 8 bits and
  // does fit 16.
  assign requested_mA = superspeed ? ({8'd0, b_max_power} << 3)   // x8
                                   : ({8'd0, b_max_power} << 1);  // x2

  // Inclusive, as everywhere else in this track: a request that exactly
  // consumes what the port offers is legal.
  assign request_fits = (requested_mA <= port_offers_mA);

  // THE POINT OF THE MODULE. Before configuration the device is entitled to
  // one unit load and nothing else, whatever it declared. After a SUCCESSFUL
  // SetConfiguration it is entitled to what it declared.
  assign allowance_mA = configured ? requested_mA : unit_load_mA;

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      configured     <= 1'b0;
      config_refused <= 1'b0;
      refusal_count  <= 32'd0;
    end else if (detach || !vbus_present) begin
      // Losing VBUS is not a state transition to negotiate, it is the end
      // of the conversation. A device that stayed "configured" across a
      // detach would resume drawing its full allowance on the next attach
      // before the host had agreed to anything.
      configured     <= 1'b0;
      config_refused <= 1'b0;
    end else if (set_config_zero) begin
      // SetConfiguration(0) returns the device to the Address state, and
      // with it to one unit load.
      configured     <= 1'b0;
    end else if (set_config) begin
      if (request_fits) begin
        configured     <= 1'b1;
        config_refused <= 1'b0;
      end else begin
        // The request does not fit. The device is NOT configured, and it
        // stays at one unit load -- enumerated, addressed, visible in the
        // device list, and unusable. This is what "the device is detected
        // but doesn't work" looks like from inside the hardware.
        configured     <= 1'b0;
        config_refused <= 1'b1;
        refusal_count  <= refusal_count + 32'd1;
      end
    end
  end
endmodule

package usb_devpower_pkg;
  // What a device is entitled to draw, as a named state rather than a flag.
  // The distinction is not cosmetic: the two states differ by up to a factor
  // of five, and "configured" is the only word that licenses the larger one.
  typedef enum logic [1:0] {
    PWR_UNPOWERED,     // no VBUS -- the device may draw nothing at all
    PWR_ONE_UNIT,      // attached or addressed: ONE unit load, no more
    PWR_CONFIGURED     // SetConfiguration succeeded: bMaxPower, scaled
  } dev_power_e;
endpackage

// usb_bus_power_negotiate_sv -- what a bus-powered device may draw, and when.
//
// Module 18 asked what a HUB can supply. This asks what a DEVICE may take,
// and the two are different questions with different answers at different
// times.
//
// The rule that surprises people is that a device's allowance CHANGES
// during enumeration, and it changes exactly once:
//
//   BEFORE SetConfiguration   one unit load. Always. However much the
//                             device declared it wants, however much the
//                             port has spare. The host has not yet agreed
//                             to anything, and a device that helped itself
//                             to 500 mA while merely attached could brown
//                             out a port before anyone had read a
//                             descriptor from it.
//
//   AFTER SetConfiguration    bMaxPower, scaled -- and only if the host
//                             accepted the configuration. If the port
//                             cannot supply it, SetConfiguration FAILS and
//                             the device stays at one unit load, addressed
//                             and enumerated and unusable.
//
// bMaxPower is stored in UNITS, not milliamps, and the unit depends on the
// speed: SuperSpeed counts in 8 mA, everything else in 2 mA. Linux:
//
//     /* SuperSpeed power is in 8 mA units; others are in 2 mA units */
//     unsigned mul = (udev->speed >= USB_SPEED_SUPER ? 8 : 2);
//     return c->desc.bMaxPower * mul;
module usb_bus_power_negotiate_sv
  import usb_devpower_pkg::*;
#(
  parameter int unsigned UNIT_LOAD_HS = 100,
  parameter int unsigned UNIT_LOAD_SS = 150
) (
  input  logic        clk,
  input  logic        rst_n,

  input  logic        vbus_present,
  input  logic        superspeed,
  input  logic [7:0]  b_max_power,
  input  logic [15:0] port_offers_mA,

  input  logic        set_config,
  input  logic        set_config_zero,
  input  logic        detach,

  output logic [15:0] unit_load_mA,
  output logic [15:0] requested_mA,
  output logic        request_fits,
  output logic        configured,
  output logic [15:0] allowance_mA,
  output dev_power_e  power_state,
  output logic        config_refused,
  output logic [31:0] refusal_count
);
  initial begin
    if (UNIT_LOAD_HS < 1 || UNIT_LOAD_SS < 1)
      $fatal(1, "a unit load of zero entitles a device to nothing");
    // 255 units x 8 mA is 2040, which must fit the arithmetic below.
    if (UNIT_LOAD_SS > 2040)
      $fatal(1, "UNIT_LOAD_SS=%0d exceeds what bMaxPower can express",
             UNIT_LOAD_SS);
  end

  // The unit load is a property of the SPEED, not of the request. A
  // SuperSpeed device gets a bigger floor as well as a bigger ceiling.
  assign unit_load_mA = superspeed ? 16'(UNIT_LOAD_SS) : 16'(UNIT_LOAD_HS);

  // bMaxPower is in units. Widened to 16 bits BEFORE the multiply so the
  // product cannot wrap: 255 * 8 is 2040, which does not fit 8 bits and
  // does fit 16.
  assign requested_mA = superspeed ? (16'(b_max_power) << 3)
                                   : (16'(b_max_power) << 1);

  // Inclusive, as everywhere else in this track: a request that exactly
  // consumes what the port offers is legal.
  assign request_fits = (requested_mA <= port_offers_mA);

  // THE POINT OF THE MODULE. Before configuration the device is entitled to
  // one unit load and nothing else, whatever it declared.
  assign allowance_mA = configured ? requested_mA : unit_load_mA;

  // The same fact as a named state. `configured` is a bit a reader must
  // interpret; PWR_ONE_UNIT says what the device may actually do.
  always_comb begin
    if      (!vbus_present) power_state = PWR_UNPOWERED;
    else if (configured)    power_state = PWR_CONFIGURED;
    else                    power_state = PWR_ONE_UNIT;
  end

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      configured <= 1'b0; config_refused <= 1'b0; refusal_count <= '0;
    end else if (detach || !vbus_present) begin
      // Losing VBUS is not a state transition to negotiate, it is the end
      // of the conversation. A device that stayed "configured" across a
      // detach would resume drawing its full allowance on the next attach
      // before the host had agreed to anything.
      configured <= 1'b0; config_refused <= 1'b0;
    end else if (set_config_zero) begin
      // SetConfiguration(0) returns the device to the Address state, and
      // with it to one unit load.
      configured <= 1'b0;
    end else if (set_config) begin
      if (request_fits) begin
        configured <= 1'b1; config_refused <= 1'b0;
      end else begin
        // The request does not fit. The device is NOT configured, and it
        // stays at one unit load -- enumerated, addressed, visible in the
        // device list, and unusable. This is what "the device is detected
        // but doesn't work" looks like from inside the hardware.
        configured <= 1'b0; config_refused <= 1'b1;
        refusal_count <= refusal_count + 1;
      end
    end
  end
endmodule

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

package usb_devpower_pkg is
  -- What a device is entitled to draw, as a named state rather than a flag.
  -- The distinction is not cosmetic: the two states differ by up to a factor
  -- of five, and "configured" is the only word that licenses the larger one.
  type dev_power_t is (
    PWR_UNPOWERED,     -- no VBUS -- the device may draw nothing at all
    PWR_ONE_UNIT,      -- attached or addressed: ONE unit load, no more
    PWR_CONFIGURED     -- SetConfiguration succeeded: bMaxPower, scaled
  );
end package;

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

-- usb_bus_power_negotiate_vhdl -- what a device may draw, and when.
--
-- Module 18 asked what a HUB can supply. This asks what a DEVICE may take,
-- and the two are different questions with different answers at different
-- times.
--
-- The rule that surprises people is that a device's allowance CHANGES
-- during enumeration, and it changes exactly once:
--
--   BEFORE SetConfiguration   one unit load. Always. However much the
--                             device declared it wants, however much the
--                             port has spare. The host has not yet agreed
--                             to anything, and a device that helped itself
--                             to 500 mA while merely attached could brown
--                             out a port before anyone had read a
--                             descriptor from it.
--
--   AFTER SetConfiguration    bMaxPower, scaled -- and only if the host
--                             accepted the configuration. If the port
--                             cannot supply it, SetConfiguration FAILS and
--                             the device stays at one unit load, addressed
--                             and enumerated and unusable.
--
-- bMaxPower is stored in UNITS, not milliamps, and the unit depends on the
-- speed: SuperSpeed counts in 8 mA, everything else in 2 mA. Linux:
--
--     /* SuperSpeed power is in 8 mA units; others are in 2 mA units */
--     unsigned mul = (udev->speed >= USB_SPEED_SUPER ? 8 : 2);
--     return c->desc.bMaxPower * mul;
entity usb_bus_power_negotiate_vhdl is
  generic (
    UNIT_LOAD_HS : positive := 100;
    UNIT_LOAD_SS : positive := 150
  );
  port (
    clk             : in  std_logic;
    rst_n           : in  std_logic;

    vbus_present    : in  std_logic;
    superspeed      : in  std_logic;
    b_max_power     : in  unsigned(7 downto 0);
    port_offers_mA  : in  unsigned(15 downto 0);

    set_config      : in  std_logic;
    set_config_zero : in  std_logic;
    detach          : in  std_logic;

    unit_load_mA    : out unsigned(15 downto 0);
    requested_mA    : out unsigned(15 downto 0);
    request_fits    : out std_logic;
    configured      : out std_logic;
    allowance_mA    : out unsigned(15 downto 0);
    power_state     : out dev_power_t;
    config_refused  : out std_logic;
    refusal_count   : out unsigned(31 downto 0)
  );
end entity;

architecture rtl of usb_bus_power_negotiate_vhdl is
  signal ul_i    : unsigned(15 downto 0);
  signal req_i   : unsigned(15 downto 0);
  signal fits_i  : std_logic;
  signal cfg_r   : std_logic := '0';
  signal ref_r   : std_logic := '0';
  signal cnt_r   : unsigned(31 downto 0) := (others => '0');
begin
  assert UNIT_LOAD_SS <= 2040
    report "UNIT_LOAD_SS exceeds what bMaxPower can express"
    severity failure;

  -- The unit load is a property of the SPEED, not of the request. A
  -- SuperSpeed device gets a bigger floor as well as a bigger ceiling.
  ul_i <= to_unsigned(UNIT_LOAD_SS, 16) when superspeed = '1'
          else to_unsigned(UNIT_LOAD_HS, 16);

  -- bMaxPower is in units. Resized to 16 bits BEFORE the shift so the
  -- product cannot wrap: 255 * 8 is 2040, which does not fit 8 bits and
  -- does fit 16. Written as a shift rather than a multiply because
  -- numeric_std's "unsigned * natural" returns a result as wide as both
  -- operands together, which is a runtime length error rather than a
  -- truncation (chapter 18.4 section 9).
  req_i <= shift_left(resize(b_max_power, 16), 3) when superspeed = '1'
           else shift_left(resize(b_max_power, 16), 1);

  -- Inclusive, as everywhere else in this track: a request that exactly
  -- consumes what the port offers is legal.
  fits_i <= '1' when req_i <= port_offers_mA else '0';

  unit_load_mA   <= ul_i;
  requested_mA   <= req_i;
  request_fits   <= fits_i;
  configured     <= cfg_r;
  config_refused <= ref_r;
  refusal_count  <= cnt_r;

  -- THE POINT OF THE MODULE. Before configuration the device is entitled to
  -- one unit load and nothing else, whatever it declared.
  allowance_mA <= req_i when cfg_r = '1' else ul_i;

  -- The same fact as a named state. `configured` is a bit a reader must
  -- interpret; PWR_ONE_UNIT says what the device may actually do.
  power_state <= PWR_UNPOWERED  when vbus_present = '0' else
                 PWR_CONFIGURED when cfg_r = '1'        else
                 PWR_ONE_UNIT;

  process (clk, rst_n)
  begin
    if rst_n = '0' then
      cfg_r <= '0'; ref_r <= '0'; cnt_r <= (others => '0');
    elsif rising_edge(clk) then
      if detach = '1' or vbus_present = '0' then
        -- Losing VBUS is not a state transition to negotiate, it is the end
        -- of the conversation. A device that stayed "configured" across a
        -- detach would resume drawing its full allowance on the next attach
        -- before the host had agreed to anything.
        cfg_r <= '0'; ref_r <= '0';
      elsif set_config_zero = '1' then
        -- SetConfiguration(0) returns the device to the Address state, and
        -- with it to one unit load.
        cfg_r <= '0';
      elsif set_config = '1' then
        if fits_i = '1' then
          cfg_r <= '1'; ref_r <= '0';
        else
          -- The request does not fit. The device is NOT configured, and it
          -- stays at one unit load -- enumerated, addressed, visible in the
          -- device list, and unusable. This is what "the device is detected
          -- but doesn't work" looks like from inside the hardware.
          cfg_r <= '0'; ref_r <= '1';
          cnt_r <= cnt_r + 1;
        end if;
      end if;
    end if;
  end process;
end architecture;

    for (s=0; s<2; s=s+1)
     for (p=0; p<256; p=p+1)
      for (o=0; o<11; o=o+1) begin
        hard_reset;
        ss=s[0]; bmp=p[7:0]; #1;
        offers = offer_of(o, requested_mA); #1;
        check_comb;                       // unconfigured allowance
        if (offers == requested_mA) n_exact = n_exact + 1;
        step(1, 0, 0, 1);                 // the host tries SetConfiguration
        n_exh = n_exh + 1;
      end

      // ---- SAFETY PROPERTIES, independent of the model ----
      // 1. THE one that matters: a configured device never has an allowance
      //    larger than its port offered it.
      if (configured)
        check(allowance_mA <= offers,
              "a configured device may draw more than its port supplies");
      // 2. An unconfigured device draws exactly one unit load, never more.
      if (!configured)
        check(allowance_mA === e_ul,
              "an unconfigured device's allowance is not one unit load");
      // 3. Being configured implies the request fitted.
      check(!configured || request_fits,
            "the device is configured with a request that does not fit");

  exhaustive bus-power sweep: 5632 of 5632 scenarios verified

  REACH: exhaustive=5632 configured=2860 refused=2772 offer-exactly-request=522
  [Verilog] usb_bus_power_negotiate: 0 errors — PASS
  [SystemVerilog] usb_bus_power_negotiate_sv: 0 errors — PASS
  [VHDL] usb_bus_power_negotiate_vhdl: 0 errors — PASS

  // Offer modes 8, 9 and 10 are computed FROM the request: exactly the
  // request, one milliamp under, one over. Without them the sweep lands on
  // the inclusive boundary only where a fixed offer happens to equal
  // bMaxPower x 2 -- eight times in 4096 points, which is not enough to
  // distinguish an inclusive bound from an exclusive one.
  function [15:0] offer_of(input integer mode, input [15:0] req);
    begin
      case (mode)
        8:       offer_of = req;
        9:       offer_of = (req == 16'd0) ? 16'd0 : (req - 16'd1);
        10:      offer_of = req + 16'd1;
        default: offer_of = OFF[mode];
      endcase
    end
  endfunction

class enum_power_item extends uvm_sequence_item;
  `uvm_object_utils(enum_power_item)
  rand bit [7:0]  b_max_power;
  rand bit        superspeed;
  rand bit [15:0] port_offers_mA;

  // Bias HARD toward the boundary. Section 11 measured what uniform
  // stimulus does here: the inclusive bound is reached by coincidence,
  // eight times in four thousand.
  constraint c_boundary {
    port_offers_mA dist {
      (superspeed ? b_max_power*8 : b_max_power*2)       := 10,  // exactly
      (superspeed ? b_max_power*8 : b_max_power*2) - 1   := 5,   // just under
      (superspeed ? b_max_power*8 : b_max_power*2) + 1   := 5,   // just over
      [0:2040]                                            := 3   // anywhere
    };
  }
endclass

// The whole enumeration, as a sequence. The POINT is the window between
// attach and SetConfiguration, where the device is entitled to one unit
// load and a badly-behaved device would take more.
class enumerate_seq extends uvm_sequence #(enum_power_item);
  `uvm_object_utils(enumerate_seq)
  rand int unsigned descriptor_delay;
  constraint c_delay { descriptor_delay inside {[1:20]}; }

  task body();
    enum_power_item it;
    `uvm_do_with(it, { })                 // attach: VBUS appears
    repeat (descriptor_delay) @(posedge cfg.vif.clk);   // host reads descriptors
    // THE window. Everything above happens while the device is entitled to
    // exactly one unit load, and the scoreboard checks that continuously.
    `uvm_do_with(it, { })                 // SetConfiguration
  endtask
endclass

class bus_power_scoreboard extends uvm_scoreboard;
  `uvm_component_utils(bus_power_scoreboard)
  local bit m_configured;   // its OWN copy (chapter 17.3)

  function void write(power_txn t);
    int unsigned unit_load = t.superspeed ? 150 : 100;
    int unsigned request   = t.b_max_power * (t.superspeed ? 8 : 2);

    // THE property, and it is about a WINDOW rather than an instant: from
    // attach until SetConfiguration succeeds, the allowance is one unit
    // load. A device that exceeded it even for one cycle could brown out a
    // port before the host knew what was attached.
    if (!m_configured && t.allowance_mA != unit_load)
      `uvm_error("PWR/FLOOR", $sformatf(
        "unconfigured device allowed %0d mA; one unit load is %0d",
        t.allowance_mA, unit_load))

    // A configured device never exceeds what its port offered.
    if (m_configured && t.allowance_mA > t.port_offers_mA)
      `uvm_error("PWR/OVER", $sformatf(
        "configured at %0d mA from a port offering %0d",
        t.allowance_mA, t.port_offers_mA))

    if (t.set_config) m_configured = (request <= t.port_offers_mA);
    if (t.set_config_zero || !t.vbus_present) m_configured = 0;
  endfunction
endclass

covergroup bus_power_cg with function sample(
    int unsigned request, int unsigned offer, bit ss, bit configured);
  cp_speed : coverpoint ss;
  // The bin section 11 is about. Without deriving the offer from the
  // request, this bin reads 8 out of 4096.
  cp_rel : coverpoint (request == offer ? 0 : request < offer ? 1 : 2) {
    bins exactly_fits = {0};
    bins fits         = {1};
    bins too_big      = {2};
  }
  x_speed_rel : cross cp_speed, cp_rel;
endgroup

  // THE property: an unconfigured device draws exactly one unit load.
  property p_unconfigured_floor;
    @(posedge clk) disable iff (!rst_n)
      (!configured) |-> (allowance_mA == unit_load_mA);
  endproperty
  a_unconfigured_floor : assert property (p_unconfigured_floor)
    else $error("an unconfigured device's allowance is not one unit load");

  // A configured device never exceeds what its port offered.
  property p_within_offer;
    @(posedge clk) disable iff (!rst_n)
      configured |-> (allowance_mA <= port_offers_mA);
  endproperty
  a_within_offer : assert property (p_within_offer);

  // Configuration only ever follows a request that fitted. Mutation B4.
  property p_config_implies_fit;
    @(posedge clk) disable iff (!rst_n)
      ($rose(configured)) |-> $past(request_fits);
  endproperty
  a_config_implies_fit : assert property (p_config_implies_fit);

  // Losing VBUS deconfigures, next cycle, unconditionally. Mutation B5.
  property p_vbus_deconfigures;
    @(posedge clk) disable iff (!rst_n)
      (!vbus_present) |=> (!configured);
  endproperty
  a_vbus_deconfigures : assert property (p_vbus_deconfigures);