Power Issues

   VBUS = 4.1 V, 300 mA      at t = 0 (just plugged in)
       -> normal. This is what attaching a device LOOKS like.

   VBUS = 4.1 V, 300 mA      at t = 2 seconds
       -> a fault. Something is loading the rail.

   300 mA, before SET_CONFIGURATION   -> a specification violation
   300 mA, after  SET_CONFIGURATION   -> legal

   A device may draw ONE UNIT LOAD -- 100 mA -- from the moment
   it attaches. It may draw its configured maximum, up to
   500 mA, only after the host has configured it.

// usb_power_monitor -- the same two numbers, read at two different times,
// and one of them is a healthy device while the other is a fault.
//
// IN-RUSH IS LEGAL. SAG IS NOT. THE DIFFERENCE IS A TIME WINDOW.
//
// When a device is plugged in, its bulk capacitance is empty. Connecting it
// to VBUS is connecting a 5 volt rail to a discharged capacitor, and the
// current that flows is limited only by the resistance of the path. The
// voltage at the port DROPS while that happens.
//
//     VBUS dips to 4.1 V, 300 mA flows      at t = 0
//         -> normal. This is what attaching a device LOOKS like.
//
//     VBUS dips to 4.1 V, 300 mA flows      at t = 2 seconds
//         -> a fault. Something is loading the rail.
//
// Identical readings. The only thing that distinguishes them is WHEN they
// were taken, relative to the attach event.
//
// This is why the specification bounds the device's bulk capacitance rather
// than bounding the current: you cannot limit the in-rush current directly
// without a soft-start circuit in every device, but you CAN bound how long
// it lasts, and a bounded duration is something a monitor can check.
//
// SO A MONITOR THAT DOES NOT KNOW ABOUT THE WINDOW HAS TWO FAILURE MODES
//
//     no window        every attach reports a sag and an over-current.
//                      One false alarm per plug-in event, for ever.
//
//     window too long  a real short circuit is invisible for as long as
//                      the window lasts, which is exactly when the
//                      damage happens.
//
// Both are the familiar pair: a checker nobody reads, or a checker that
// misses the thing it exists for (chapter 24.1).
//
// AND THE BUDGET DEPENDS ON THE ENUMERATION STATE
//
// A device may draw one unit load -- 100 mA -- from the moment it attaches.
// It may draw its configured maximum, up to 500 mA, only AFTER the host has
// sent SET_CONFIGURATION. Drawing 500 mA before that is a specification
// violation that works perfectly on every desktop and fails on a bus-powered
// hub, which is the most expensive category of bug there is:
//
//     it works on the developer's machine, always.
//
// OVER-CURRENT IS A PROTECTION ACTION, NOT AN ERROR
//
// A hub shutting off a port that exceeds its limit is the hub working. What
// is NOT normal is a port that shuts off, re-enables, and shuts off again --
// an oscillation, which means something downstream is latching up and
// recovering. So trips are counted and the OSCILLATION is the report.
module usb_power_monitor #(
  parameter integer V_MIN_MV   = 4400,  // the device's floor, in millivolts
  parameter integer I_UNCFG_MA = 100,   // one unit load, before configuration
  parameter integer I_CFG_MA   = 500,   // the configured maximum
  parameter integer I_LIMIT_MA = 900,   // the hub's port limit
  parameter integer INRUSH_CYC = 100,   // how long in-rush may last
  parameter integer OSC_MAX    = 3      // trips before it is an oscillation
) (
  input  wire        clk,
  input  wire        rst_n,

  input  wire        attach,
  input  wire        detach,
  input  wire        configured,   // SET_CONFIGURATION has been accepted
  input  wire        sample,       // vbus_mv and i_ma are valid this cycle
  input  wire [12:0] vbus_mv,
  input  wire [9:0]  i_ma,
  input  wire        eot,

  output wire [1:0]  phase,
  output wire [15:0] inrush_left,  // cycles of in-rush window remaining
  output wire        port_off,
  output wire        err_pulse,
  output wire [2:0]  err_code,

  output reg [31:0] n_sample,
  output reg [31:0] n_attach,
  output reg [31:0] n_sag,
  output reg [31:0] n_inrush_long,
  output reg [31:0] n_overcurrent,
  output reg [31:0] n_budget,
  output reg [31:0] n_osc,
  output reg [31:0] n_trip
);

  localparam [1:0] P_OFF    = 2'd0,  // nothing attached
                   P_INRUSH = 2'd1,  // attached, inside the window
                   P_ON     = 2'd2,  // attached, window expired, unconfigured
                   P_CFG    = 2'd3;  // configured

  localparam [2:0] E_NONE        = 3'd0,
                   E_SAG         = 3'd1,  // VBUS low OUTSIDE the window
                   E_INRUSH_LONG = 3'd2,  // still drawing when it expired
                   E_OVERCURRENT = 3'd3,  // past the port limit
                   E_BUDGET      = 3'd4,  // past the ENUMERATION-STATE budget
                   E_OSC         = 3'd5;  // trip / re-enable / trip

  reg [1:0]  ph_r;
  reg [15:0] win_r;
  reg [9:0]  ilast_r;
  reg [7:0]  trip_r;
  reg        off_r, osc_r;      // osc_r: reported once
  reg        er_r;
  reg [2:0]  ec_r;

  assign phase       = ph_r;
  assign inrush_left = win_r;
  assign port_off    = off_r;
  assign err_pulse   = er_r;
  assign err_code    = ec_r;

  reg [1:0]  ph_n;
  reg [15:0] win_n;
  reg [9:0]  ilast_n;
  reg [7:0]  trip_n;
  reg        off_n, osc_n, er_n;
  reg [2:0]  ec_n;
  reg        sag_n, il_n, oc_n, bud_n, oscc_n, trip_pulse, att_n;
  reg [9:0]  i_now;

  always @* begin
    ph_n    = ph_r;
    win_n   = win_r;
    ilast_n = ilast_r;
    trip_n  = trip_r;
    off_n   = off_r;
    osc_n   = osc_r;
    er_n    = 1'b0;
    ec_n    = E_NONE;
    sag_n = 1'b0; il_n = 1'b0; oc_n = 1'b0; bud_n = 1'b0;
    oscc_n = 1'b0; trip_pulse = 1'b0; att_n = 1'b0;

    // ---- The most recent measurement available AT THIS INSTANT. ----
    //
    // This cycle's, if there is one, otherwise the last one taken. The
    // window-close test below runs BEFORE the sample is registered, so
    // reading `ilast_r` there uses the measurement from one sample ago --
    // and a device that drops back under one unit load on the very last
    // sample of the window is then reported as an in-rush overrun. It is
    // off by exactly one measurement, which is invisible in every test
    // except one that lands the recovery on the final cycle.
    i_now = (sample && !off_r) ? i_ma : ilast_r;

    if (eot) begin
      // Nothing: the counters are the report.
    end else if (detach) begin
      // ---- Everything resets except the trip count. ----
      //
      // The trip count is what makes an oscillation visible, and an
      // oscillation is a sequence of attach/trip/detach cycles. Clearing it
      // on detach deletes the only evidence that the port is cycling --
      // each individual trip then looks like a one-off.
      ph_n  = P_OFF;
      win_n = 16'd0;
      off_n = 1'b0;
    end else if (attach) begin
      // ---- The window opens HERE, and only here. ----
      ph_n    = P_INRUSH;
      win_n   = INRUSH_CYC;
      off_n   = 1'b0;
      ilast_n = 10'd0;
      att_n   = 1'b1;
    end else begin
      if (configured && (ph_r == P_ON)) ph_n = P_CFG;

      // ---- The window runs on TIME, not on samples. ----
      //
      // Decremented per cycle rather than per measurement, because in-rush
      // is a physical duration. Tied to the sample rate instead, a monitor
      // that samples more slowly gets a longer window -- so the same device
      // passes on one analyser and fails on another, which is the kind of
      // discrepancy that gets blamed on the device for a week.
      if (ph_r == P_INRUSH) begin
        if (win_r != 16'd0) begin
          win_n = win_r - 16'd1;
          if (win_n == 16'd0) begin
            ph_n = P_ON;
            // ---- The window closed. Is it STILL drawing? ----
            //
            // If it is, the bulk capacitance is oversized or there is a
            // short, and the distinction from a legal in-rush is precisely
            // that this one did not finish in time.
            if (i_now > I_UNCFG_MA) begin
              er_n = 1'b1; ec_n = E_INRUSH_LONG;
              il_n = 1'b1;
            end
          end
        end
      end

      if (sample && !off_r) begin
        ilast_n = i_ma;

        if (i_ma > I_LIMIT_MA) begin
          // ---- The port limit is HARDWARE. It applies during in-rush too.
          //
          // The window excuses a device from the BUDGET, not from the
          // hub's protection circuit -- a dead short still trips the port
          // on the first microsecond, and a monitor that suppresses that
          // because "we are in the in-rush window" is suppressing the one
          // reading that means something is on fire.
          er_n  = 1'b1; ec_n = E_OVERCURRENT;
          oc_n  = 1'b1;
          off_n = 1'b1;
          ph_n  = P_OFF;
          win_n = 16'd0;
          trip_pulse = 1'b1;
          if (trip_r != 8'hFF) trip_n = trip_r + 8'd1;
          if ((trip_n >= OSC_MAX) && !osc_r) begin
            // Reported ONCE. A port that is cycling produces a trip every
            // few milliseconds, and one report per trip is chapter 25.3's
            // flood with a different name on it.
            ec_n   = E_OSC;
            oscc_n = 1'b1;
            osc_n  = 1'b1;
          end
        end else if (ph_r == P_INRUSH) begin
          // ---- INSIDE THE WINDOW: NOTHING IS REPORTED. ----
          //
          // Not "reported at a lower severity", not "reported and
          // filtered". A sagging rail and a large current during in-rush
          // are what a correct device looks like, and reporting them
          // produces one false alarm per plug-in event for ever.
        end else if (vbus_mv < V_MIN_MV) begin
          er_n  = 1'b1; ec_n = E_SAG;
          sag_n = 1'b1;
        end else if ((ph_r == P_CFG) ? (i_ma > I_CFG_MA)
                                     : (i_ma > I_UNCFG_MA)) begin
          // ---- The budget depends on the ENUMERATION STATE. ----
          //
          // 100 mA before SET_CONFIGURATION, the configured maximum after.
          // A device that ignores this works on every desktop and fails on
          // a bus-powered hub.
          er_n  = 1'b1; ec_n = E_BUDGET;
          bud_n = 1'b1;
        end
      end
    end
  end

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      ph_r    <= P_OFF;
      win_r   <= 16'd0;
      ilast_r <= 10'd0;
      trip_r  <= 8'd0;
      off_r   <= 1'b0;
      osc_r   <= 1'b0;
      er_r    <= 1'b0;
      ec_r    <= E_NONE;
      n_sample      <= 32'd0;
      n_attach      <= 32'd0;
      n_sag         <= 32'd0;
      n_inrush_long <= 32'd0;
      n_overcurrent <= 32'd0;
      n_budget      <= 32'd0;
      n_osc         <= 32'd0;
      n_trip        <= 32'd0;
    end else begin
      ph_r    <= ph_n;
      win_r   <= win_n;
      ilast_r <= ilast_n;
      trip_r  <= trip_n;
      off_r   <= off_n;
      osc_r   <= osc_n;
      er_r    <= er_n;
      ec_r    <= ec_n;

      // `!off_r` is part of the condition, not an oversight: a tripped
      // port has no voltage on it, so a measurement offered while it is off
      // is not a measurement of anything. Counting it inflates the
      // denominator of every rate computed from this block by however long
      // the port stayed off -- which is longest exactly when things are
      // going worst.
      if (sample && !eot && !detach && !attach && !off_r)
        n_sample <= n_sample + 32'd1;
      if (att_n)      n_attach      <= n_attach      + 32'd1;
      if (sag_n)      n_sag         <= n_sag         + 32'd1;
      if (il_n)       n_inrush_long <= n_inrush_long + 32'd1;
      if (oc_n)       n_overcurrent <= n_overcurrent + 32'd1;
      if (bud_n)      n_budget      <= n_budget      + 32'd1;
      if (oscc_n)     n_osc         <= n_osc         + 32'd1;
      if (trip_pulse) n_trip        <= n_trip        + 32'd1;
    end
  end
endmodule

// usb_power_monitor -- the same two numbers, read at two different times,
// and one of them is a healthy device while the other is a fault.
//
// IN-RUSH IS LEGAL. SAG IS NOT. THE DIFFERENCE IS A TIME WINDOW.
//
// When a device is plugged in, its bulk capacitance is empty. Connecting it
// to VBUS is connecting a 5 volt rail to a discharged capacitor, and the
// current that flows is limited only by the resistance of the path. The
// voltage at the port DROPS while that happens.
//
//     VBUS dips to 4.1 V, 300 mA flows      at t = 0
//         -> normal. This is what attaching a device LOOKS like.
//
//     VBUS dips to 4.1 V, 300 mA flows      at t = 2 seconds
//         -> a fault. Something is loading the rail.
//
// Identical readings. The only thing that distinguishes them is WHEN they
// were taken, relative to the attach event.
//
// This is why the specification bounds the device's bulk capacitance rather
// than bounding the current: you cannot limit the in-rush current directly
// without a soft-start circuit in every device, but you CAN bound how long
// it lasts, and a bounded duration is something a monitor can check.
//
// SO A MONITOR THAT DOES NOT KNOW ABOUT THE WINDOW HAS TWO FAILURE MODES
//
//     no window        every attach reports a sag and an over-current.
//                      One false alarm per plug-in event, for ever.
//
//     window too long  a real short circuit is invisible for as long as
//                      the window lasts, which is exactly when the
//                      damage happens.
//
// Both are the familiar pair: a checker nobody reads, or a checker that
// misses the thing it exists for (chapter 24.1).
//
// AND THE BUDGET DEPENDS ON THE ENUMERATION STATE
//
// A device may draw one unit load -- 100 mA -- from the moment it attaches.
// It may draw its configured maximum, up to 500 mA, only AFTER the host has
// sent SET_CONFIGURATION. Drawing 500 mA before that is a specification
// violation that works perfectly on every desktop and fails on a bus-powered
// hub, which is the most expensive category of bug there is:
//
//     it works on the developer's machine, always.
//
// OVER-CURRENT IS A PROTECTION ACTION, NOT AN ERROR
//
// A hub shutting off a port that exceeds its limit is the hub working. What
// is NOT normal is a port that shuts off, re-enables, and shuts off again --
// an oscillation, which means something downstream is latching up and
// recovering. So trips are counted and the OSCILLATION is the report.
package usb_power_pkg;
  // The phase is the whole argument of this block, so it gets a type: the
  // same measurement means different things in different phases, and a
  // two-bit output called `phase` is a number somebody has to look up.
  typedef enum logic [1:0] {
    P_OFF    = 2'd0,   // nothing attached
    P_INRUSH = 2'd1,   // attached, inside the window
    P_ON     = 2'd2,   // attached, window expired, unconfigured
    P_CFG    = 2'd3    // configured
  } phase_e;

  typedef enum logic [2:0] {
    E_NONE        = 3'd0,
    E_SAG         = 3'd1,   // VBUS low OUTSIDE the window
    E_INRUSH_LONG = 3'd2,   // still drawing when the window expired
    E_OVERCURRENT = 3'd3,   // past the port limit
    E_BUDGET      = 3'd4,   // past the ENUMERATION-STATE budget
    E_OSC         = 3'd5    // trip / re-enable / trip
  } pwr_err_e;
endpackage

module usb_power_monitor
  import usb_power_pkg::*;
 #(
  parameter int V_MIN_MV   = 4400,   // the device's floor, in millivolts
  parameter int I_UNCFG_MA = 100,    // one unit load, before configuration
  parameter int I_CFG_MA   = 500,    // the configured maximum
  parameter int I_LIMIT_MA = 900,    // the hub's port limit
  parameter int INRUSH_CYC = 100,    // how long in-rush may last
  parameter int OSC_MAX    = 3       // trips before it is an oscillation
) (
  input  logic        clk,
  input  logic        rst_n,

  input  logic        attach,
  input  logic        detach,
  input  logic        configured,   // SET_CONFIGURATION has been accepted
  input  logic        sample,       // vbus_mv and i_ma are valid this cycle
  input  logic [12:0] vbus_mv,
  input  logic [9:0]  i_ma,
  input  logic        eot,

  output phase_e      phase,
  output logic [15:0] inrush_left,  // cycles of in-rush window remaining
  output logic        port_off,
  output logic        err_pulse,
  output pwr_err_e    err_code,

  output logic [31:0] n_sample,
  output logic [31:0] n_attach,
  output logic [31:0] n_sag,
  output logic [31:0] n_inrush_long,
  output logic [31:0] n_overcurrent,
  output logic [31:0] n_budget,
  output logic [31:0] n_osc,
  output logic [31:0] n_trip
);

  phase_e     ph_r;
  logic [15:0] win_r;
  logic [9:0]  ilast_r;
  logic [7:0]  trip_r;
  logic        off_r, osc_r;    // osc_r: reported once
  logic        er_r;
  pwr_err_e    ec_r;

  assign phase       = ph_r;
  assign inrush_left = win_r;
  assign port_off    = off_r;
  assign err_pulse   = er_r;
  assign err_code    = ec_r;

  phase_e      ph_n;
  logic [15:0] win_n;
  logic [9:0]  ilast_n;
  logic [7:0]  trip_n;
  logic        off_n, osc_n, er_n;
  pwr_err_e    ec_n;
  logic        sag_n, il_n, oc_n, bud_n, oscc_n, trip_pulse, att_n;
  logic [9:0]  i_now;

  always_comb begin
    ph_n    = ph_r;
    win_n   = win_r;
    ilast_n = ilast_r;
    trip_n  = trip_r;
    off_n   = off_r;
    osc_n   = osc_r;
    er_n    = 1'b0;
    ec_n    = E_NONE;
    sag_n = 1'b0; il_n = 1'b0; oc_n = 1'b0; bud_n = 1'b0;
    oscc_n = 1'b0; trip_pulse = 1'b0; att_n = 1'b0;

    // ---- The most recent measurement available AT THIS INSTANT. ----
    //
    // This cycle's, if there is one, otherwise the last one taken. The
    // window-close test below runs BEFORE the sample is registered, so
    // reading `ilast_r` there uses the measurement from one sample ago --
    // and a device that drops back under one unit load on the very last
    // sample of the window is then reported as an in-rush overrun. It is
    // off by exactly one measurement, which is invisible in every test
    // except one that lands the recovery on the final cycle.
    i_now = (sample && !off_r) ? i_ma : ilast_r;

    if (eot) begin
      // Nothing: the counters are the report.
    end else if (detach) begin
      // ---- Everything resets except the trip count. ----
      //
      // The trip count is what makes an oscillation visible, and an
      // oscillation is a sequence of attach/trip/detach cycles. Clearing it
      // on detach deletes the only evidence that the port is cycling --
      // each individual trip then looks like a one-off.
      ph_n  = P_OFF;
      win_n = 16'd0;
      off_n = 1'b0;
    end else if (attach) begin
      // ---- The window opens HERE, and only here. ----
      ph_n    = P_INRUSH;
      win_n   = 16'(INRUSH_CYC);
      off_n   = 1'b0;
      ilast_n = 10'd0;
      att_n   = 1'b1;
    end else begin
      if (configured && (ph_r == P_ON)) ph_n = P_CFG;

      // ---- The window runs on TIME, not on samples. ----
      //
      // Decremented per cycle rather than per measurement, because in-rush
      // is a physical duration. Tied to the sample rate instead, a monitor
      // that samples more slowly gets a longer window -- so the same device
      // passes on one analyser and fails on another, which is the kind of
      // discrepancy that gets blamed on the device for a week.
      if (ph_r == P_INRUSH) begin
        if (win_r != 16'd0) begin
          win_n = win_r - 16'd1;
          if (win_n == 16'd0) begin
            ph_n = P_ON;
            // ---- The window closed. Is it STILL drawing? ----
            //
            // If it is, the bulk capacitance is oversized or there is a
            // short, and the distinction from a legal in-rush is precisely
            // that this one did not finish in time.
            if (i_now > I_UNCFG_MA) begin
              er_n = 1'b1; ec_n = E_INRUSH_LONG;
              il_n = 1'b1;
            end
          end
        end
      end

      if (sample && !off_r) begin
        ilast_n = i_ma;

        if (i_ma > I_LIMIT_MA) begin
          // ---- The port limit is HARDWARE. It applies during in-rush too.
          //
          // The window excuses a device from the BUDGET, not from the
          // hub's protection circuit -- a dead short still trips the port
          // on the first microsecond, and a monitor that suppresses that
          // because "we are in the in-rush window" is suppressing the one
          // reading that means something is on fire.
          er_n  = 1'b1; ec_n = E_OVERCURRENT;
          oc_n  = 1'b1;
          off_n = 1'b1;
          ph_n  = P_OFF;
          win_n = 16'd0;
          trip_pulse = 1'b1;
          if (trip_r != 8'hFF) trip_n = trip_r + 8'd1;
          if ((trip_n >= OSC_MAX) && !osc_r) begin
            // Reported ONCE. A port that is cycling produces a trip every
            // few milliseconds, and one report per trip is chapter 25.3's
            // flood with a different name on it.
            ec_n   = E_OSC;
            oscc_n = 1'b1;
            osc_n  = 1'b1;
          end
        end else if (ph_r == P_INRUSH) begin
          // ---- INSIDE THE WINDOW: NOTHING IS REPORTED. ----
          //
          // Not "reported at a lower severity", not "reported and
          // filtered". A sagging rail and a large current during in-rush
          // are what a correct device looks like, and reporting them
          // produces one false alarm per plug-in event for ever.
        end else if (vbus_mv < V_MIN_MV) begin
          er_n  = 1'b1; ec_n = E_SAG;
          sag_n = 1'b1;
        end else if (i_ma > ((ph_r == P_CFG) ? I_CFG_MA : I_UNCFG_MA)) begin
          // ---- The budget depends on the ENUMERATION STATE. ----
          //
          // 100 mA before SET_CONFIGURATION, the configured maximum after.
          // A device that ignores this works on every desktop and fails on
          // a bus-powered hub.
          er_n  = 1'b1; ec_n = E_BUDGET;
          bud_n = 1'b1;
        end
      end
    end
  end

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      ph_r    <= P_OFF;
      win_r   <= 16'd0;
      ilast_r <= 10'd0;
      trip_r  <= 8'd0;
      off_r   <= 1'b0;
      osc_r   <= 1'b0;
      er_r    <= 1'b0;
      ec_r    <= E_NONE;
      n_sample      <= 32'd0;
      n_attach      <= 32'd0;
      n_sag         <= 32'd0;
      n_inrush_long <= 32'd0;
      n_overcurrent <= 32'd0;
      n_budget      <= 32'd0;
      n_osc         <= 32'd0;
      n_trip        <= 32'd0;
    end else begin
      ph_r    <= ph_n;
      win_r   <= win_n;
      ilast_r <= ilast_n;
      trip_r  <= trip_n;
      off_r   <= off_n;
      osc_r   <= osc_n;
      er_r    <= er_n;
      ec_r    <= ec_n;

      // `!off_r` is part of the condition, not an oversight: a tripped
      // port has no voltage on it, so a measurement offered while it is off
      // is not a measurement of anything. Counting it inflates the
      // denominator of every rate computed from this block by however long
      // the port stayed off -- which is longest exactly when things are
      // going worst.
      if (sample && !eot && !detach && !attach && !off_r)
        n_sample <= n_sample + 32'd1;
      if (att_n)      n_attach      <= n_attach      + 32'd1;
      if (sag_n)      n_sag         <= n_sag         + 32'd1;
      if (il_n)       n_inrush_long <= n_inrush_long + 32'd1;
      if (oc_n)       n_overcurrent <= n_overcurrent + 32'd1;
      if (bud_n)      n_budget      <= n_budget      + 32'd1;
      if (oscc_n)     n_osc         <= n_osc         + 32'd1;
      if (trip_pulse) n_trip        <= n_trip        + 32'd1;
    end
  end
endmodule

-- usb_power_monitor -- the same two numbers, read at two different times,
-- and one of them is a healthy device while the other is a fault.
--
-- IN-RUSH IS LEGAL. SAG IS NOT. THE DIFFERENCE IS A TIME WINDOW.
--
-- When a device is plugged in, its bulk capacitance is empty. Connecting it
-- to VBUS is connecting a 5 volt rail to a discharged capacitor, and the
-- current that flows is limited only by the resistance of the path. The
-- voltage at the port DROPS while that happens.
--
--     VBUS dips to 4.1 V, 300 mA flows      at t = 0
--         -> normal. This is what attaching a device LOOKS like.
--
--     VBUS dips to 4.1 V, 300 mA flows      at t = 2 seconds
--         -> a fault. Something is loading the rail.
--
-- Identical readings. The only thing that distinguishes them is WHEN they
-- were taken, relative to the attach event.
--
-- This is why the specification bounds the device's bulk capacitance rather
-- than bounding the current: you cannot limit in-rush current directly
-- without a soft-start circuit in every device, but you CAN bound how long
-- it lasts, and a bounded duration is something a monitor can check.
--
-- SO A MONITOR THAT DOES NOT KNOW ABOUT THE WINDOW HAS TWO FAILURE MODES
--
--     no window        every attach reports a sag and an over-current.
--                      One false alarm per plug-in event, for ever.
--
--     window too long  a real short circuit is invisible for as long as the
--                      window lasts, which is exactly when the damage
--                      happens.
--
-- Both are the familiar pair: a checker nobody reads, or a checker that
-- misses the thing it exists for (chapter 24.1).
--
-- AND THE BUDGET DEPENDS ON THE ENUMERATION STATE
--
-- A device may draw one unit load -- 100 mA -- from the moment it attaches.
-- It may draw its configured maximum, up to 500 mA, only AFTER the host has
-- sent SET_CONFIGURATION. Drawing 500 mA before that is a violation that
-- works perfectly on every desktop and fails on a bus-powered hub, which is
-- the most expensive category of bug there is:
--
--     it works on the developer's machine, always.
--
-- OVER-CURRENT IS A PROTECTION ACTION, NOT AN ERROR
--
-- A hub shutting off a port that exceeds its limit is the hub working. What
-- is NOT normal is a port that shuts off, re-enables and shuts off again --
-- an oscillation, which means something downstream is latching up and
-- recovering. So trips are counted and the OSCILLATION is the report.
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

package usb_power_pkg is
  constant P_OFF    : std_logic_vector(1 downto 0) := "00";
  constant P_INRUSH : std_logic_vector(1 downto 0) := "01";
  constant P_ON     : std_logic_vector(1 downto 0) := "10";
  constant P_CFG    : std_logic_vector(1 downto 0) := "11";

  constant E_NONE        : std_logic_vector(2 downto 0) := "000";
  constant E_SAG         : std_logic_vector(2 downto 0) := "001";
  constant E_INRUSH_LONG : std_logic_vector(2 downto 0) := "010";
  constant E_OVERCURRENT : std_logic_vector(2 downto 0) := "011";
  constant E_BUDGET      : std_logic_vector(2 downto 0) := "100";
  constant E_OSC         : std_logic_vector(2 downto 0) := "101";
end package;

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

entity usb_power_monitor is
  generic (
    V_MIN_MV   : integer := 4400;   -- the device's floor, in millivolts
    I_UNCFG_MA : integer := 100;    -- one unit load, before configuration
    I_CFG_MA   : integer := 500;    -- the configured maximum
    I_LIMIT_MA : integer := 900;    -- the hub's port limit
    INRUSH_CYC : integer := 100;    -- how long in-rush may last
    OSC_MAX    : integer := 3       -- trips before it is an oscillation
  );
  port (
    clk        : in  std_logic;
    rst_n      : in  std_logic;

    attach     : in  std_logic;
    detach     : in  std_logic;
    configured : in  std_logic;     -- SET_CONFIGURATION has been accepted
    sample     : in  std_logic;     -- vbus_mv and i_ma are valid this cycle
    vbus_mv    : in  unsigned(12 downto 0);
    i_ma       : in  unsigned(9 downto 0);
    eot        : in  std_logic;

    phase       : out std_logic_vector(1 downto 0);
    inrush_left : out unsigned(15 downto 0);
    port_off    : out std_logic;
    err_pulse   : out std_logic;
    err_code    : out std_logic_vector(2 downto 0);

    n_sample      : out unsigned(31 downto 0);
    n_attach      : out unsigned(31 downto 0);
    n_sag         : out unsigned(31 downto 0);
    n_inrush_long : out unsigned(31 downto 0);
    n_overcurrent : out unsigned(31 downto 0);
    n_budget      : out unsigned(31 downto 0);
    n_osc         : out unsigned(31 downto 0);
    n_trip        : out unsigned(31 downto 0)
  );
end entity;

architecture rtl of usb_power_monitor is
  signal ph_r    : std_logic_vector(1 downto 0) := P_OFF;
  signal win_r   : unsigned(15 downto 0) := (others => '0');
  signal ilast_r : unsigned(9 downto 0)  := (others => '0');
  signal trip_r  : unsigned(7 downto 0)  := (others => '0');
  signal off_r   : std_logic := '0';
  signal osc_r   : std_logic := '0';      -- reported once
  signal er_r    : std_logic := '0';
  signal ec_r    : std_logic_vector(2 downto 0) := E_NONE;

  signal samp_c, att_c, sag_c, il_c : unsigned(31 downto 0)
    := (others => '0');
  signal oc_c, bud_c, osc_c, trip_c : unsigned(31 downto 0)
    := (others => '0');
begin
  phase       <= ph_r;
  inrush_left <= win_r;
  port_off    <= off_r;
  err_pulse   <= er_r;
  err_code    <= ec_r;

  n_sample      <= samp_c;
  n_attach      <= att_c;
  n_sag         <= sag_c;
  n_inrush_long <= il_c;
  n_overcurrent <= oc_c;
  n_budget      <= bud_c;
  n_osc         <= osc_c;
  n_trip        <= trip_c;

  process (clk, rst_n)
    variable ph_v    : std_logic_vector(1 downto 0);
    variable win_v   : unsigned(15 downto 0);
    variable ilast_v : unsigned(9 downto 0);
    variable trip_v  : unsigned(7 downto 0);
    variable off_v, osc_v, er_v : std_logic;
    variable ec_v    : std_logic_vector(2 downto 0);
    variable i_now   : unsigned(9 downto 0);
  begin
    if rst_n = '0' then
      ph_r    <= P_OFF;
      win_r   <= (others => '0');
      ilast_r <= (others => '0');
      trip_r  <= (others => '0');
      off_r   <= '0';
      osc_r   <= '0';
      er_r    <= '0';
      ec_r    <= E_NONE;
      samp_c  <= (others => '0');
      att_c   <= (others => '0');
      sag_c   <= (others => '0');
      il_c    <= (others => '0');
      oc_c    <= (others => '0');
      bud_c   <= (others => '0');
      osc_c   <= (others => '0');
      trip_c  <= (others => '0');
    elsif rising_edge(clk) then
      ph_v    := ph_r;
      win_v   := win_r;
      ilast_v := ilast_r;
      trip_v  := trip_r;
      off_v   := off_r;
      osc_v   := osc_r;
      er_v    := '0';
      ec_v    := E_NONE;

      -- ---- The most recent measurement available AT THIS INSTANT. ----
      --
      -- This cycle's, if there is one, otherwise the last one taken. The
      -- window-close test below runs BEFORE the sample is registered, so
      -- reading ilast_r there uses the measurement from one sample ago --
      -- and a device that drops back under one unit load on the very last
      -- sample of the window is then reported as an in-rush overrun. Off by
      -- exactly one measurement, and invisible in every test except one
      -- that lands the recovery on the final cycle.
      if sample = '1' and off_r = '0' then
        i_now := i_ma;
      else
        i_now := ilast_r;
      end if;

      if eot = '1' then
        -- Nothing: the counters are the report.
        null;
      elsif detach = '1' then
        -- ---- Everything resets except the trip count. ----
        --
        -- The trip count is what makes an oscillation visible, and an
        -- oscillation is a sequence of attach/trip/detach cycles. Clearing
        -- it on detach deletes the only evidence that the port is cycling;
        -- each individual trip then looks like a one-off.
        ph_v  := P_OFF;
        win_v := (others => '0');
        off_v := '0';
      elsif attach = '1' then
        -- ---- The window opens HERE, and only here. ----
        ph_v    := P_INRUSH;
        win_v   := to_unsigned(INRUSH_CYC, 16);
        off_v   := '0';
        ilast_v := (others => '0');
        att_c   <= att_c + 1;
      else
        if configured = '1' and ph_r = P_ON then
          ph_v := P_CFG;
        end if;

        -- ---- The window runs on TIME, not on samples. ----
        --
        -- Decremented per cycle rather than per measurement, because
        -- in-rush is a physical duration. Tied to the sample rate instead,
        -- a monitor that samples more slowly gets a longer window -- so the
        -- same device passes on one analyser and fails on another, which is
        -- the kind of discrepancy that gets blamed on the device for a week.
        if ph_r = P_INRUSH then
          if win_v /= x"0000" then
            win_v := win_v - 1;
            if win_v = x"0000" then
              ph_v := P_ON;
              -- ---- The window closed. Is it STILL drawing? ----
              --
              -- If it is, the bulk capacitance is oversized or there is a
              -- short, and the distinction from a legal in-rush is
              -- precisely that this one did not finish in time.
              if i_now > to_unsigned(I_UNCFG_MA, 10) then
                er_v := '1';
                ec_v := E_INRUSH_LONG;
                il_c <= il_c + 1;
              end if;
            end if;
          end if;
        end if;

        if sample = '1' and off_r = '0' then
          -- off_r is part of the condition, not an oversight: a tripped
          -- port has no voltage on it, so a measurement offered while it is
          -- off is not a measurement of anything. Counting it inflates the
          -- denominator of every rate computed from this block.
          samp_c  <= samp_c + 1;
          ilast_v := i_ma;

          if i_ma > to_unsigned(I_LIMIT_MA, 10) then
            -- ---- The port limit is HARDWARE. It applies during in-rush.
            --
            -- The window excuses a device from the BUDGET, not from the
            -- hub's protection circuit -- a dead short still trips the port
            -- on the first microsecond, and a monitor that suppresses that
            -- because "we are in the in-rush window" is suppressing the one
            -- reading that means something is on fire.
            er_v   := '1';
            ec_v   := E_OVERCURRENT;
            oc_c   <= oc_c + 1;
            off_v  := '1';
            ph_v   := P_OFF;
            win_v  := (others => '0');
            trip_c <= trip_c + 1;
            if trip_v /= x"FF" then trip_v := trip_v + 1; end if;
            if (trip_v >= to_unsigned(OSC_MAX, 8)) and osc_v = '0' then
              -- Reported ONCE. A port that is cycling produces a trip every
              -- few milliseconds, and one report per trip is chapter 25.3's
              -- flood with a different name on it.
              ec_v  := E_OSC;
              osc_c <= osc_c + 1;
              osc_v := '1';
            end if;
          elsif ph_r = P_INRUSH then
            -- ---- INSIDE THE WINDOW: NOTHING IS REPORTED. ----
            --
            -- Not "reported at a lower severity", not "reported and
            -- filtered". A sagging rail and a large current during in-rush
            -- are what a correct device looks like, and reporting them
            -- produces one false alarm per plug-in event for ever.
            null;
          elsif vbus_mv < to_unsigned(V_MIN_MV, 13) then
            er_v  := '1';
            ec_v  := E_SAG;
            sag_c <= sag_c + 1;
          elsif ((ph_r = P_CFG) and (i_ma > to_unsigned(I_CFG_MA, 10)))
             or ((ph_r /= P_CFG) and (i_ma > to_unsigned(I_UNCFG_MA, 10)))
          then
            -- ---- The budget depends on the ENUMERATION STATE. ----
            --
            -- 100 mA before SET_CONFIGURATION, the configured maximum
            -- after. A device that ignores this works on every desktop and
            -- fails on a bus-powered hub.
            er_v  := '1';
            ec_v  := E_BUDGET;
            bud_c <= bud_c + 1;
          end if;
        end if;
      end if;

      ph_r    <= ph_v;
      win_r   <= win_v;
      ilast_r <= ilast_v;
      trip_r  <= trip_v;
      off_r   <= off_v;
      osc_r   <= osc_v;
      er_r    <= er_v;
      ec_r    <= ec_v;
    end if;
  end process;
end architecture;

   for t in 0 .. INRUSH_CYC + 2:
       attach
       wait t cycles
       measure 4.1 V, 300 mA          <- the SAME reading every time
       require: silent    if t <  INRUSH_CYC
                reported  if t >= INRUSH_CYC

   result: silent 100, reported 3

`timescale 1ns/1ps
// Testbench for usb_power_monitor.
//
// The oracle is a shadow model written from the chapter's rules rather than
// from the RTL, re-derived every cycle and compared against every output.
//
// THE CENTRAL CLAIM IS ABOUT A BOUNDARY, SO THE BOUNDARY IS SWEPT
//
// "In-rush is legal and sag is not, and the difference is a time window" is
// a statement about ONE EDGE. Phase 1 drives an identical sagging
// measurement at every offset from 0 to INRUSH_CYC + 2 cycles after attach
// and requires that it is silent on one side of the edge and reported on
// the other -- with the edge in exactly the right place.
//
// A test that checks "inside the window" and "well outside the window"
// passes against a window of any length at all.
module tb_pm_v;

  localparam integer V_MIN_MV   = 4400;
  localparam integer I_UNCFG_MA = 100;
  localparam integer I_CFG_MA   = 500;
  localparam integer I_LIMIT_MA = 900;
  localparam integer INRUSH_CYC = 100;
  localparam integer OSC_MAX    = 3;

  localparam [1:0] P_OFF = 2'd0, P_INRUSH = 2'd1, P_ON = 2'd2, P_CFG = 2'd3;

  localparam [2:0] E_NONE = 3'd0, E_SAG = 3'd1, E_INRUSH_LONG = 3'd2,
                   E_OVERCURRENT = 3'd3, E_BUDGET = 3'd4, E_OSC = 3'd5;

  reg         clk = 1'b0, rst_n = 1'b0;
  reg         attach = 1'b0, detach = 1'b0, configured = 1'b0;
  reg         sample = 1'b0, eot = 1'b0;
  reg  [12:0] vbus_mv = 13'd5000;
  reg  [9:0]  i_ma = 10'd0;

  wire [1:0]  phase;
  wire [15:0] inrush_left;
  wire        port_off, err_pulse;
  wire [2:0]  err_code;
  wire [31:0] n_sample, n_attach, n_sag, n_inrush_long;
  wire [31:0] n_overcurrent, n_budget, n_osc, n_trip;

  usb_power_monitor #(
    .V_MIN_MV(V_MIN_MV), .I_UNCFG_MA(I_UNCFG_MA), .I_CFG_MA(I_CFG_MA),
    .I_LIMIT_MA(I_LIMIT_MA), .INRUSH_CYC(INRUSH_CYC), .OSC_MAX(OSC_MAX)
  ) dut (
    .clk(clk), .rst_n(rst_n),
    .attach(attach), .detach(detach), .configured(configured),
    .sample(sample), .vbus_mv(vbus_mv), .i_ma(i_ma), .eot(eot),
    .phase(phase), .inrush_left(inrush_left), .port_off(port_off),
    .err_pulse(err_pulse), .err_code(err_code),
    .n_sample(n_sample), .n_attach(n_attach), .n_sag(n_sag),
    .n_inrush_long(n_inrush_long), .n_overcurrent(n_overcurrent),
    .n_budget(n_budget), .n_osc(n_osc), .n_trip(n_trip)
  );

  always #5 clk = ~clk;

  // ---------------- the shadow model ----------------
  reg [1:0]  m_ph;
  reg [15:0] m_win;
  reg [9:0]  m_ilast;
  reg [7:0]  m_trip;
  reg        m_off, m_osc, m_er;
  reg [2:0]  m_ec;
  reg [31:0] c_samp, c_att, c_sag, c_il, c_oc, c_bud, c_osc, c_trip;

  integer errors = 0, checks = 0, steps = 0;
  integer k;

  // reach: phase (4) x vbus low? (2) x current band (4)
  reg [0:0] reach [0:31];
  integer   n_reach;

  task ck;
    input [255:0] nm;
    input [31:0]  got, exp;
    begin
      checks = checks + 1;
      if (got !== exp) begin
        errors = errors + 1;
        if (errors < 25)
          $display("FAIL t=%0t step=%0d %0s got=%0d exp=%0d",
                   $time, steps, nm, got, exp);
      end
    end
  endtask

  function [1:0] band; input [9:0] i;
    begin
      if      (i > I_LIMIT_MA) band = 2'd3;
      else if (i > I_CFG_MA)   band = 2'd2;
      else if (i > I_UNCFG_MA) band = 2'd1;
      else                     band = 2'd0;
    end
  endfunction

  reg [1:0] m_ph_pre;

  task model_step;
    reg [9:0] i_now;
    begin
      m_er = 1'b0; m_ec = E_NONE;
      // The most recent measurement available at this instant: this cycle's
      // if there is one, otherwise the last one taken.
      i_now = (sample && !m_off) ? i_ma : m_ilast;

      if (eot) begin
        // nothing
      end else if (detach) begin
        // The trip count SURVIVES a detach. It is the only evidence that
        // the port is cycling rather than failing once.
        m_ph  = P_OFF;
        m_win = 16'd0;
        m_off = 1'b0;
      end else if (attach) begin
        m_ph    = P_INRUSH;
        m_win   = INRUSH_CYC;
        m_off   = 1'b0;
        m_ilast = 10'd0;
        c_att   = c_att + 1;
      end else begin
        if (configured && (m_ph == P_ON)) m_ph = P_CFG;

        if (m_ph == P_INRUSH) begin
          if (m_win != 16'd0) begin
            m_win = m_win - 16'd1;
            if (m_win == 16'd0) begin
              m_ph = P_ON;
              if (i_now > I_UNCFG_MA) begin
                m_er = 1'b1; m_ec = E_INRUSH_LONG;
                c_il = c_il + 1;
              end
            end
          end
        end

        if (sample && !m_off) begin
          c_samp  = c_samp + 1;
          m_ilast = i_ma;

          if (i_ma > I_LIMIT_MA) begin
            // The port limit is hardware. It applies inside the window too:
            // a dead short trips on the first microsecond, and suppressing
            // that because "we are in the in-rush window" suppresses the one
            // reading that means something is on fire.
            m_er  = 1'b1; m_ec = E_OVERCURRENT;
            c_oc  = c_oc + 1;
            m_off = 1'b1;
            m_ph  = P_OFF;
            m_win = 16'd0;
            c_trip = c_trip + 1;
            if (m_trip != 8'hFF) m_trip = m_trip + 8'd1;
            if ((m_trip >= OSC_MAX) && !m_osc) begin
              m_ec  = E_OSC;
              c_osc = c_osc + 1;
              m_osc = 1'b1;
            end
          end else if (m_ph_pre == P_INRUSH) begin
            // INSIDE THE WINDOW: NOTHING IS REPORTED.
          end else if (vbus_mv < V_MIN_MV) begin
            m_er  = 1'b1; m_ec = E_SAG;
            c_sag = c_sag + 1;
          end else if ((m_ph_pre == P_CFG) ? (i_ma > I_CFG_MA)
                                           : (i_ma > I_UNCFG_MA)) begin
            m_er  = 1'b1; m_ec = E_BUDGET;
            c_bud = c_bud + 1;
          end
        end
      end
    end
  endtask

  task check_out;
    begin
      ck("phase",       {30'd0, phase},       {30'd0, m_ph});
      ck("inrush_left", {16'd0, inrush_left}, {16'd0, m_win});
      ck("port_off",    {31'd0, port_off},    {31'd0, m_off});
      ck("err_pulse",   {31'd0, err_pulse},   {31'd0, m_er});
      ck("err_code",    {29'd0, err_code},    {29'd0, m_ec});
      ck("n_sample",      n_sample,      c_samp);
      ck("n_attach",      n_attach,      c_att);
      ck("n_sag",         n_sag,         c_sag);
      ck("n_inrush_long", n_inrush_long, c_il);
      ck("n_overcurrent", n_overcurrent, c_oc);
      ck("n_budget",      n_budget,      c_bud);
      ck("n_osc",         n_osc,         c_osc);
      ck("n_trip",        n_trip,        c_trip);
      // ---- the structural invariant ----
      //
      // Every error is exactly one of five causes, so the per-cause counters
      // sum to the total. E_OSC is NOT added here: an oscillation is
      // reported INSTEAD of the over-current that triggered it, on the same
      // pulse, so counting both would double-count one event.
      ck("cause sum", n_sag + n_inrush_long + n_overcurrent + n_budget,
                      c_sag + c_il          + c_oc          + c_bud);
    end
  endtask

  task step;
    begin
      m_ph_pre = m_ph;
      if (sample && !eot && !detach && !attach && !m_off)
        reach[{m_ph, (vbus_mv < V_MIN_MV) ? 1'b1 : 1'b0, band(i_ma)}] = 1'b1;
      model_step;
      @(posedge clk);
      #1;
      steps = steps + 1;
      check_out;
    end
  endtask

  task meas; input [12:0] v; input [9:0] i;
    begin
      attach = 1'b0; detach = 1'b0; configured = 1'b0; eot = 1'b0;
      sample = 1'b1; vbus_mv = v; i_ma = i;
      step;
    end
  endtask

  task tick;
    begin
      attach = 1'b0; detach = 1'b0; configured = 1'b0; eot = 1'b0;
      sample = 1'b0;
      step;
    end
  endtask

  task do_attach;
    begin
      attach = 1'b1; detach = 1'b0; configured = 1'b0; sample = 1'b0;
      eot = 1'b0;
      step;
      attach = 1'b0;
    end
  endtask

  task do_detach;
    begin
      attach = 1'b0; detach = 1'b1; configured = 1'b0; sample = 1'b0;
      eot = 1'b0;
      step;
      detach = 1'b0;
    end
  endtask

  task do_configure;
    begin
      attach = 1'b0; detach = 1'b0; configured = 1'b1; sample = 1'b0;
      eot = 1'b0;
      step;
      configured = 1'b0;
    end
  endtask

  integer i, t, p, v, b, w;
  integer base_sag, base_il, base_oc, base_bud, base_osc, base_trip;
  integer n_edge_silent, n_edge_reported;

  initial begin
    for (k = 0; k < 32; k = k + 1) reach[k] = 1'b0;
    m_ph = P_OFF; m_win = 16'd0; m_ilast = 10'd0; m_trip = 8'd0;
    m_off = 1'b0; m_osc = 1'b0; m_er = 1'b0; m_ec = E_NONE;
    c_samp=0; c_att=0; c_sag=0; c_il=0; c_oc=0; c_bud=0; c_osc=0; c_trip=0;

    repeat (3) @(posedge clk);
    rst_n = 1'b1;
    @(negedge clk);

    // ================= PHASE 1 -- THE WINDOW EDGE, SWEPT =================
    //
    // The same sagging measurement -- 4.1 V, 300 mA -- taken at every offset
    // from 0 to INRUSH_CYC + 2 cycles after attach. Silent before the edge,
    // reported after it, and the edge exactly where the parameter says.
    //
    // Note that the current is 300 mA throughout, which is over the
    // unconfigured budget, so the post-window report could legitimately be
    // either SAG or BUDGET. The design checks voltage first and the model
    // agrees; what phase 1 proves is that SOMETHING is reported, and which
    // one is pinned by phase 2.
    n_edge_silent = 0; n_edge_reported = 0;
    for (t = 0; t <= INRUSH_CYC + 2; t = t + 1) begin
      do_detach;
      do_attach;
      base_sag = c_sag; base_bud = c_bud;
      for (i = 0; i < t; i = i + 1) tick;
      meas(13'd4100, 10'd300);
      if (t < INRUSH_CYC) begin
        if (c_sag != base_sag || c_bud != base_bud) begin
          errors = errors + 1;
          $display("FAIL reported INSIDE the window at t=%0d", t);
        end else n_edge_silent = n_edge_silent + 1;
      end else begin
        if (c_sag == base_sag && c_bud == base_bud) begin
          errors = errors + 1;
          $display("FAIL silent OUTSIDE the window at t=%0d", t);
        end else n_edge_reported = n_edge_reported + 1;
      end
    end
    if (n_edge_silent != INRUSH_CYC || n_edge_reported != 3) begin
      errors = errors + 1;
      $display("FAIL edge sweep: silent=%0d reported=%0d expected %0d and 3",
               n_edge_silent, n_edge_reported, INRUSH_CYC);
    end

    // ================= PHASE 2 -- a legal attach is COMPLETELY silent ====
    //
    // A sagging rail and 400 mA for the entire window. Zero reports. Not
    // one at a lower severity -- zero.
    do_detach;
    do_attach;
    base_sag = c_sag; base_bud = c_bud; base_oc = c_oc; base_il = c_il;
    for (i = 0; i < INRUSH_CYC - 1; i = i + 1) meas(13'd4150, 10'd400);
    // ...and it ends with the current back under one unit load, so the
    // window closes cleanly.
    meas(13'd4900, 10'd80);
    tick;
    if (c_sag != base_sag || c_bud != base_bud || c_oc != base_oc
        || c_il != base_il) begin
      errors = errors + 1;
      $display("FAIL a legal in-rush produced reports");
    end
    if (m_ph != P_ON) begin
      errors = errors + 1;
      $display("FAIL phase after the window is %0d, expected P_ON", m_ph);
    end

    // ================= PHASE 3 -- in-rush that never finishes ============
    do_detach;
    do_attach;
    base_il = c_il;
    for (i = 0; i < INRUSH_CYC + 1; i = i + 1) meas(13'd4150, 10'd400);
    if (c_il != base_il + 1) begin
      errors = errors + 1;
      $display("FAIL in-rush overrun reports %0d, expected 1", c_il - base_il);
    end

    // ================= PHASE 4 -- the budget follows the ENUMERATION =====
    //
    // 300 mA is a violation before SET_CONFIGURATION and legal after it.
    // Identical measurement, opposite verdict -- the same shape of argument
    // as the window, with enumeration state instead of time.
    do_detach;
    do_attach;
    for (i = 0; i < INRUSH_CYC; i = i + 1) tick;
    base_bud = c_bud;
    meas(13'd5000, 10'd300);              // unconfigured: a violation
    if (c_bud != base_bud + 1) begin
      errors = errors + 1;
      $display("FAIL 300 mA before configuration was not reported");
    end
    do_configure;
    base_bud = c_bud;
    meas(13'd5000, 10'd300);              // configured: legal
    if (c_bud != base_bud) begin
      errors = errors + 1;
      $display("FAIL 300 mA after configuration WAS reported");
    end
    meas(13'd5000, 10'd600);              // over the configured maximum
    if (c_bud != base_bud + 1) begin
      errors = errors + 1;
      $display("FAIL 600 mA after configuration was not reported");
    end
    // ...and the boundary itself: exactly I_CFG_MA is legal, one more is not
    base_bud = c_bud;
    meas(13'd5000, I_CFG_MA[9:0]);
    if (c_bud != base_bud) begin
      errors = errors + 1;
      $display("FAIL exactly I_CFG_MA was reported");
    end
    meas(13'd5000, I_CFG_MA[9:0] + 10'd1);
    if (c_bud != base_bud + 1) begin
      errors = errors + 1;
      $display("FAIL I_CFG_MA+1 was not reported");
    end

    // ================= PHASE 5 -- over-current, trips, oscillation =======
    //
    // Three trips. The first two are the hub working. The third is an
    // oscillation, reported ONCE.
    do_detach;
    base_oc = c_oc; base_osc = c_osc; base_trip = c_trip;
    for (i = 0; i < 6; i = i + 1) begin
      do_attach;
      meas(13'd5000, 10'd950);           // a dead short
      do_detach;
    end
    if (c_trip != base_trip + 6) begin
      errors = errors + 1;
      $display("FAIL trips %0d expected 6", c_trip - base_trip);
    end
    if (c_osc != base_osc + 1) begin
      errors = errors + 1;
      $display("FAIL oscillation reports %0d expected 1", c_osc - base_osc);
    end
    // ...and a tripped port stops being measurable until it is re-attached.
    do_attach;
    meas(13'd5000, 10'd950);
    base_sag = c_sag;
    meas(13'd4000, 10'd50);              // the port is off: no report
    if (c_sag != base_sag) begin
      errors = errors + 1;
      $display("FAIL a tripped port still reported a sag");
    end

    // ================= PHASE 6 -- the exhaustive situation sweep =========
    //
    // Every phase x (rail low or not) x current band. Phases are reached by
    // driving the design the way the design reaches them, never by forcing.
    for (p = 0; p < 4; p = p + 1)
      for (v = 0; v < 2; v = v + 1)
        for (b = 0; b < 4; b = b + 1) begin
          do_detach;
          if (p >= 1) begin
            do_attach;
            if (p >= 2) for (i = 0; i < INRUSH_CYC; i = i + 1) tick;
            if (p == 3) do_configure;
          end
          meas((v == 1) ? 13'd4100 : 13'd5000,
               (b == 0) ? 10'd50  : (b == 1) ? 10'd300 :
               (b == 2) ? 10'd700 : 10'd950);
        end

    // The random phase is switchable, because a mutation score is only
    // interesting once it is DECOMPOSED. Phase 6 alone reaches all 32
    // situations, so the exhaustiveness proof still holds without it.
`ifndef DIRECTED_ONLY
    // ================= PHASE 7 -- random =================================
    for (i = 0; i < 40000; i = i + 1) begin
      w = $unsigned($random) % 1000;
      if (w < 12)       do_attach;
      else if (w < 24)  do_detach;
      else if (w < 34)  do_configure;
      else if (w < 120) tick;
      else meas(13'd3800 + ($unsigned($random) % 1500),
                ($unsigned($random) % 1000));
    end

`endif

    // ================= the exhaustiveness proof ==========================
    n_reach = 0;
    for (k = 0; k < 32; k = k + 1) n_reach = n_reach + reach[k];
    if (n_reach != 32) begin
      errors = errors + 1;
      $display("FAIL situation reach %0d/32", n_reach);
      for (k = 0; k < 32; k = k + 1)
        if (!reach[k])
          $display("  unreached phase=%0d low=%0d band=%0d",
                   k >> 3, (k >> 2) & 1, k & 3);
    end

    $display("steps=%0d checks=%0d reach=%0d/32 errors=%0d",
             steps, checks, n_reach, errors);
    $display("window edge: silent=%0d reported=%0d",
             n_edge_silent, n_edge_reported);
    $display("samples=%0d attaches=%0d trips=%0d", n_sample, n_attach, n_trip);
    $display("sag=%0d inrush_long=%0d overcurrent=%0d budget=%0d osc=%0d",
             n_sag, n_inrush_long, n_overcurrent, n_budget, n_osc);
    $display("%0s: %0d errors in %0d checks",
             (errors == 0) ? "PASS" : "FAIL", errors, checks);
    $finish;
  end
endmodule

`timescale 1ns/1ps
// Testbench for usb_power_monitor.
//
// The oracle is a shadow model written from the chapter's rules rather than
// from the RTL, re-derived every cycle and compared against every output.
//
// THE CENTRAL CLAIM IS ABOUT A BOUNDARY, SO THE BOUNDARY IS SWEPT
//
// "In-rush is legal and sag is not, and the difference is a time window" is
// a statement about ONE EDGE. Phase 1 drives an identical sagging
// measurement at every offset from 0 to INRUSH_CYC + 2 cycles after attach
// and requires that it is silent on one side of the edge and reported on
// the other -- with the edge in exactly the right place.
//
// A test that checks "inside the window" and "well outside the window"
// passes against a window of any length at all.
module tb_pm_sv;
  import usb_power_pkg::*;

  localparam int V_MIN_MV   = 4400;
  localparam int I_UNCFG_MA = 100;
  localparam int I_CFG_MA   = 500;
  localparam int I_LIMIT_MA = 900;
  localparam int INRUSH_CYC = 100;
  localparam int OSC_MAX    = 3;

  logic       clk = 1'b0, rst_n = 1'b0;
  logic       attach = 1'b0, detach = 1'b0, configured = 1'b0;
  logic       sample = 1'b0, eot = 1'b0;
  logic [12:0] vbus_mv = 13'd5000;
  logic [9:0]  i_ma = 10'd0;

  phase_e      phase;
  logic [15:0] inrush_left;
  logic        port_off, err_pulse;
  pwr_err_e    err_code;
  logic [31:0] n_sample, n_attach, n_sag, n_inrush_long;
  logic [31:0] n_overcurrent, n_budget, n_osc, n_trip;

  usb_power_monitor #(
    .V_MIN_MV(V_MIN_MV), .I_UNCFG_MA(I_UNCFG_MA), .I_CFG_MA(I_CFG_MA),
    .I_LIMIT_MA(I_LIMIT_MA), .INRUSH_CYC(INRUSH_CYC), .OSC_MAX(OSC_MAX)
  ) dut (
    .clk(clk), .rst_n(rst_n),
    .attach(attach), .detach(detach), .configured(configured),
    .sample(sample), .vbus_mv(vbus_mv), .i_ma(i_ma), .eot(eot),
    .phase(phase), .inrush_left(inrush_left), .port_off(port_off),
    .err_pulse(err_pulse), .err_code(err_code),
    .n_sample(n_sample), .n_attach(n_attach), .n_sag(n_sag),
    .n_inrush_long(n_inrush_long), .n_overcurrent(n_overcurrent),
    .n_budget(n_budget), .n_osc(n_osc), .n_trip(n_trip)
  );

  always #5 clk = ~clk;

  // ---------------- the shadow model ----------------
  phase_e      m_ph;
  logic [15:0] m_win;
  logic [9:0]  m_ilast;
  logic [7:0]  m_trip;
  logic        m_off, m_osc, m_er;
  pwr_err_e    m_ec;
  int unsigned c_samp, c_att, c_sag, c_il, c_oc, c_bud, c_osc, c_trip;

  int errors = 0, checks = 0, steps = 0;
  int k;

  // reach: phase (4) x vbus low? (2) x current band (4)
  bit reach [32];
  int n_reach;

  task automatic ck(string nm, int unsigned got, int unsigned exp);
    checks++;
    if (got !== exp) begin
      errors++;
      if (errors < 25)
        $display("FAIL t=%0t step=%0d %0s got=%0d exp=%0d",
                 $time, steps, nm, got, exp);
    end
  endtask

  function automatic logic [1:0] band(input logic [9:0] i);
    begin
      if      (i > I_LIMIT_MA) band = 2'd3;
      else if (i > I_CFG_MA)   band = 2'd2;
      else if (i > I_UNCFG_MA) band = 2'd1;
      else                     band = 2'd0;
    end
  endfunction

  phase_e m_ph_pre;

  task automatic model_step;
    logic [9:0] i_now;
    begin
      m_er = 1'b0; m_ec = E_NONE;
      // The most recent measurement available at this instant: this cycle's
      // if there is one, otherwise the last one taken.
      i_now = (sample && !m_off) ? i_ma : m_ilast;

      if (eot) begin
        // nothing
      end else if (detach) begin
        // The trip count SURVIVES a detach. It is the only evidence that
        // the port is cycling rather than failing once.
        m_ph  = P_OFF;
        m_win = 16'd0;
        m_off = 1'b0;
      end else if (attach) begin
        m_ph    = P_INRUSH;
        m_win   = INRUSH_CYC;
        m_off   = 1'b0;
        m_ilast = 10'd0;
        c_att   = c_att + 1;
      end else begin
        if (configured && (m_ph == P_ON)) m_ph = P_CFG;

        if (m_ph == P_INRUSH) begin
          if (m_win != 16'd0) begin
            m_win = m_win - 16'd1;
            if (m_win == 16'd0) begin
              m_ph = P_ON;
              if (i_now > I_UNCFG_MA) begin
                m_er = 1'b1; m_ec = E_INRUSH_LONG;
                c_il = c_il + 1;
              end
            end
          end
        end

        if (sample && !m_off) begin
          c_samp  = c_samp + 1;
          m_ilast = i_ma;

          if (i_ma > I_LIMIT_MA) begin
            // The port limit is hardware. It applies inside the window too:
            // a dead short trips on the first microsecond, and suppressing
            // that because "we are in the in-rush window" suppresses the one
            // reading that means something is on fire.
            m_er  = 1'b1; m_ec = E_OVERCURRENT;
            c_oc  = c_oc + 1;
            m_off = 1'b1;
            m_ph  = P_OFF;
            m_win = 16'd0;
            c_trip = c_trip + 1;
            if (m_trip != 8'hFF) m_trip = m_trip + 8'd1;
            if ((m_trip >= OSC_MAX) && !m_osc) begin
              m_ec  = E_OSC;
              c_osc = c_osc + 1;
              m_osc = 1'b1;
            end
          end else if (m_ph_pre == P_INRUSH) begin
            // INSIDE THE WINDOW: NOTHING IS REPORTED.
          end else if (vbus_mv < V_MIN_MV) begin
            m_er  = 1'b1; m_ec = E_SAG;
            c_sag = c_sag + 1;
          end else if ((m_ph_pre == P_CFG) ? (i_ma > I_CFG_MA)
                                           : (i_ma > I_UNCFG_MA)) begin
            m_er  = 1'b1; m_ec = E_BUDGET;
            c_bud = c_bud + 1;
          end
        end
      end
    end
  endtask

  task automatic check_out;
    begin
      ck("phase",       phase,    m_ph);
      ck("inrush_left", inrush_left, m_win);
      ck("port_off",    port_off, m_off);
      ck("err_pulse",   err_pulse, m_er);
      ck("err_code",    err_code, m_ec);
      ck("n_sample",      n_sample,      c_samp);
      ck("n_attach",      n_attach,      c_att);
      ck("n_sag",         n_sag,         c_sag);
      ck("n_inrush_long", n_inrush_long, c_il);
      ck("n_overcurrent", n_overcurrent, c_oc);
      ck("n_budget",      n_budget,      c_bud);
      ck("n_osc",         n_osc,         c_osc);
      ck("n_trip",        n_trip,        c_trip);
      // ---- the structural invariant ----
      //
      // Every error is exactly one of five causes, so the per-cause counters
      // sum to the total. E_OSC is NOT added here: an oscillation is
      // reported INSTEAD of the over-current that triggered it, on the same
      // pulse, so counting both would double-count one event.
      ck("cause sum", n_sag + n_inrush_long + n_overcurrent + n_budget,
                      c_sag + c_il          + c_oc          + c_bud);
    end
  endtask

  task automatic step;
    begin
      m_ph_pre = m_ph;
      if (sample && !eot && !detach && !attach && !m_off)
        reach[int'(m_ph) * 8 + ((vbus_mv < V_MIN_MV) ? 4 : 0)
              + int'(band(i_ma))] = 1'b1;
      model_step;
      @(posedge clk);
      #1;
      steps = steps + 1;
      check_out;
    end
  endtask

  task automatic meas(logic [12:0] v, logic [9:0] i);
    begin
      attach = 1'b0; detach = 1'b0; configured = 1'b0; eot = 1'b0;
      sample = 1'b1; vbus_mv = v; i_ma = i;
      step;
    end
  endtask

  task automatic tick;
    begin
      attach = 1'b0; detach = 1'b0; configured = 1'b0; eot = 1'b0;
      sample = 1'b0;
      step;
    end
  endtask

  task automatic do_attach;
    begin
      attach = 1'b1; detach = 1'b0; configured = 1'b0; sample = 1'b0;
      eot = 1'b0;
      step;
      attach = 1'b0;
    end
  endtask

  task automatic do_detach;
    begin
      attach = 1'b0; detach = 1'b1; configured = 1'b0; sample = 1'b0;
      eot = 1'b0;
      step;
      detach = 1'b0;
    end
  endtask

  task automatic do_configure;
    begin
      attach = 1'b0; detach = 1'b0; configured = 1'b1; sample = 1'b0;
      eot = 1'b0;
      step;
      configured = 1'b0;
    end
  endtask

  int i, t, p, v, b, w;
  int base_sag, base_il, base_oc, base_bud, base_osc, base_trip;
  int n_edge_silent, n_edge_reported;

  initial begin
    foreach (reach[q]) reach[q] = 1'b0;
    m_ph = P_OFF; m_win = 16'd0; m_ilast = 10'd0; m_trip = 8'd0;
    m_off = 1'b0; m_osc = 1'b0; m_er = 1'b0; m_ec = E_NONE;
    c_samp=0; c_att=0; c_sag=0; c_il=0; c_oc=0; c_bud=0; c_osc=0; c_trip=0;

    repeat (3) @(posedge clk);
    rst_n = 1'b1;
    @(negedge clk);

    // ================= PHASE 1 -- THE WINDOW EDGE, SWEPT =================
    //
    // The same sagging measurement -- 4.1 V, 300 mA -- taken at every offset
    // from 0 to INRUSH_CYC + 2 cycles after attach. Silent before the edge,
    // reported after it, and the edge exactly where the parameter says.
    //
    // Note that the current is 300 mA throughout, which is over the
    // unconfigured budget, so the post-window report could legitimately be
    // either SAG or BUDGET. The design checks voltage first and the model
    // agrees; what phase 1 proves is that SOMETHING is reported, and which
    // one is pinned by phase 2.
    n_edge_silent = 0; n_edge_reported = 0;
    for (t = 0; t <= INRUSH_CYC + 2; t = t + 1) begin
      do_detach;
      do_attach;
      base_sag = c_sag; base_bud = c_bud;
      for (i = 0; i < t; i = i + 1) tick;
      meas(13'd4100, 10'd300);
      if (t < INRUSH_CYC) begin
        if (c_sag != base_sag || c_bud != base_bud) begin
          errors = errors + 1;
          $display("FAIL reported INSIDE the window at t=%0d", t);
        end else n_edge_silent = n_edge_silent + 1;
      end else begin
        if (c_sag == base_sag && c_bud == base_bud) begin
          errors = errors + 1;
          $display("FAIL silent OUTSIDE the window at t=%0d", t);
        end else n_edge_reported = n_edge_reported + 1;
      end
    end
    if (n_edge_silent != INRUSH_CYC || n_edge_reported != 3) begin
      errors = errors + 1;
      $display("FAIL edge sweep: silent=%0d reported=%0d expected %0d and 3",
               n_edge_silent, n_edge_reported, INRUSH_CYC);
    end

    // ================= PHASE 2 -- a legal attach is COMPLETELY silent ====
    //
    // A sagging rail and 400 mA for the entire window. Zero reports. Not
    // one at a lower severity -- zero.
    do_detach;
    do_attach;
    base_sag = c_sag; base_bud = c_bud; base_oc = c_oc; base_il = c_il;
    for (i = 0; i < INRUSH_CYC - 1; i = i + 1) meas(13'd4150, 10'd400);
    // ...and it ends with the current back under one unit load, so the
    // window closes cleanly.
    meas(13'd4900, 10'd80);
    tick;
    if (c_sag != base_sag || c_bud != base_bud || c_oc != base_oc
        || c_il != base_il) begin
      errors = errors + 1;
      $display("FAIL a legal in-rush produced reports");
    end
    if (m_ph != P_ON) begin
      errors = errors + 1;
      $display("FAIL phase after the window is %0d, expected P_ON", m_ph);
    end

    // ================= PHASE 3 -- in-rush that never finishes ============
    do_detach;
    do_attach;
    base_il = c_il;
    for (i = 0; i < INRUSH_CYC + 1; i = i + 1) meas(13'd4150, 10'd400);
    if (c_il != base_il + 1) begin
      errors = errors + 1;
      $display("FAIL in-rush overrun reports %0d, expected 1", c_il - base_il);
    end

    // ================= PHASE 4 -- the budget follows the ENUMERATION =====
    //
    // 300 mA is a violation before SET_CONFIGURATION and legal after it.
    // Identical measurement, opposite verdict -- the same shape of argument
    // as the window, with enumeration state instead of time.
    do_detach;
    do_attach;
    for (i = 0; i < INRUSH_CYC; i = i + 1) tick;
    base_bud = c_bud;
    meas(13'd5000, 10'd300);              // unconfigured: a violation
    if (c_bud != base_bud + 1) begin
      errors = errors + 1;
      $display("FAIL 300 mA before configuration was not reported");
    end
    do_configure;
    base_bud = c_bud;
    meas(13'd5000, 10'd300);              // configured: legal
    if (c_bud != base_bud) begin
      errors = errors + 1;
      $display("FAIL 300 mA after configuration WAS reported");
    end
    meas(13'd5000, 10'd600);              // over the configured maximum
    if (c_bud != base_bud + 1) begin
      errors = errors + 1;
      $display("FAIL 600 mA after configuration was not reported");
    end
    // ...and the boundary itself: exactly I_CFG_MA is legal, one more is not
    base_bud = c_bud;
    meas(13'd5000, 10'(I_CFG_MA));
    if (c_bud != base_bud) begin
      errors = errors + 1;
      $display("FAIL exactly I_CFG_MA was reported");
    end
    meas(13'd5000, 10'(I_CFG_MA) + 10'd1);
    if (c_bud != base_bud + 1) begin
      errors = errors + 1;
      $display("FAIL I_CFG_MA+1 was not reported");
    end

    // ================= PHASE 5 -- over-current, trips, oscillation =======
    //
    // Three trips. The first two are the hub working. The third is an
    // oscillation, reported ONCE.
    do_detach;
    base_oc = c_oc; base_osc = c_osc; base_trip = c_trip;
    for (i = 0; i < 6; i = i + 1) begin
      do_attach;
      meas(13'd5000, 10'd950);           // a dead short
      do_detach;
    end
    if (c_trip != base_trip + 6) begin
      errors = errors + 1;
      $display("FAIL trips %0d expected 6", c_trip - base_trip);
    end
    if (c_osc != base_osc + 1) begin
      errors = errors + 1;
      $display("FAIL oscillation reports %0d expected 1", c_osc - base_osc);
    end
    // ...and a tripped port stops being measurable until it is re-attached.
    do_attach;
    meas(13'd5000, 10'd950);
    base_sag = c_sag;
    meas(13'd4000, 10'd50);              // the port is off: no report
    if (c_sag != base_sag) begin
      errors = errors + 1;
      $display("FAIL a tripped port still reported a sag");
    end

    // ================= PHASE 6 -- the exhaustive situation sweep =========
    //
    // Every phase x (rail low or not) x current band. Phases are reached by
    // driving the design the way the design reaches them, never by forcing.
    for (p = 0; p < 4; p = p + 1)
      for (v = 0; v < 2; v = v + 1)
        for (b = 0; b < 4; b = b + 1) begin
          do_detach;
          if (p >= 1) begin
            do_attach;
            if (p >= 2) for (i = 0; i < INRUSH_CYC; i = i + 1) tick;
            if (p == 3) do_configure;
          end
          meas((v == 1) ? 13'd4100 : 13'd5000,
               (b == 0) ? 10'd50  : (b == 1) ? 10'd300 :
               (b == 2) ? 10'd700 : 10'd950);
        end

    // ================= PHASE 7 -- random =================================
    for (i = 0; i < 40000; i = i + 1) begin
      w = $unsigned($random) % 1000;
      if (w < 12)       do_attach;
      else if (w < 24)  do_detach;
      else if (w < 34)  do_configure;
      else if (w < 120) tick;
      else meas(13'd3800 + ($unsigned($random) % 1500),
                ($unsigned($random) % 1000));
    end

    // ================= the exhaustiveness proof ==========================
    n_reach = 0;
    for (k = 0; k < 32; k = k + 1) n_reach = n_reach + reach[k];
    if (n_reach != 32) begin
      errors = errors + 1;
      $display("FAIL situation reach %0d/32", n_reach);
      for (k = 0; k < 32; k = k + 1)
        if (!reach[k])
          $display("  unreached phase=%0d low=%0d band=%0d",
                   k / 8, (k / 4) % 2, k % 4);
    end

    $display("steps=%0d checks=%0d reach=%0d/32 errors=%0d",
             steps, checks, n_reach, errors);
    $display("window edge: silent=%0d reported=%0d",
             n_edge_silent, n_edge_reported);
    $display("samples=%0d attaches=%0d trips=%0d", n_sample, n_attach, n_trip);
    $display("sag=%0d inrush_long=%0d overcurrent=%0d budget=%0d osc=%0d",
             n_sag, n_inrush_long, n_overcurrent, n_budget, n_osc);
    $display("%0s: %0d errors in %0d checks",
             (errors == 0) ? "PASS" : "FAIL", errors, checks);
    $finish;
  end
endmodule