Remote Wakeup

   #define USB_DEVICE_SELF_POWERED     0   /* (read only) */
   #define USB_DEVICE_REMOTE_WAKEUP    1   /* dev may initiate wakeup */

          // A bus reset outranks the wake event as well as an in-progress
          // drive. Gating only the drive was not enough: a reset arriving in
          // the SAME cycle as a wake event would still let the wakeup start,
          // and the device would come out of the reset already driving.
          if (wake_event && !bus_reset) begin

// usb_remote_wakeup -- the one exception to the single-master rule, and the
// two independent fences around it.
//
// Every chapter of this track has rested on one fact: THE HOST INITIATES
// EVERYTHING. Chapter 2.6 established it, chapter 18.3 built an entire
// polled reporting mechanism because of it, and chapter 19.3's suspend
// detector exists because a device cannot even be TOLD to sleep -- it has to
// work it out by measuring silence.
//
// Remote wakeup is the exception. A suspended device may drive the bus
// unasked, and the host will wake up.
//
// That is a large thing to allow on a single-master bus, and it is fenced
// accordingly. A wake event does nothing at all unless BOTH of these hold:
//
//   1. THE DEVICE IS ARMED. The host must have issued
//      SetFeature(DEVICE_REMOTE_WAKEUP) -- feature selector 1 in Linux's
//      ch9.h -- and a device that was never armed must stay silent no
//      matter what happens to it. This is not a formality: an unarmed
//      device that wakes the bus wakes a machine its owner deliberately
//      put to sleep, and does it from inside a closed bag.
//
//   2. THE BUS IS SUSPENDED. Driving K on a running bus is not a wakeup,
//      it is corruption -- it collides with whatever transaction the host
//      was conducting. There is nothing to wake, so there is nothing to do.
//
// The two refusals are DIFFERENT and both are counted, because "the device
// tried to wake the host and was not armed" and "the device tried to wake a
// bus that was already awake" are different bugs with different fixes.
//
// ARMING DOES NOT SURVIVE A BUS RESET
//
// A bus reset returns the device to its default state, and the arming goes
// with it. The host must re-issue SetFeature after every reset. A device
// that kept the bit across a reset would be armed without the current host
// ever having agreed to it -- and chapter 19.3 measured what arming costs:
// five times the suspended current, on every device that has it.
module usb_remote_wakeup #(
  parameter integer K_HOLD_TICKS = 5,   // how long this device drives K
  parameter integer K_MIN_TICKS  = 1,   // the specification's floor
  parameter integer K_MAX_TICKS  = 15   // the specification's ceiling
) (
  input  wire        clk,
  input  wire        rst_n,

  // --- the host, through a control transfer ---
  input  wire        set_feature_rw,    // SetFeature(DEVICE_REMOTE_WAKEUP)
  input  wire        clear_feature_rw,
  input  wire        bus_reset,

  // --- the device's own state ---
  input  wire        suspended,         // from chapter 19.3
  input  wire        wake_event,        // a keypress, a packet, a sensor

  output reg         rw_enabled,        // the armed bit -- GetStatus bit 1
  output wire        drive_k,           // the device driving the bus UNASKED
  output reg  [15:0] k_ticks,
  output wire        wakeup_active,
  output wire [1:0]  wake_outcome,      // what happened to this attempt

  output reg  [31:0] wakeups_issued,
  output reg  [31:0] refused_not_armed,
  output reg  [31:0] refused_not_suspended
);
  localparam [1:0] W_IDLE = 2'd0, W_DRIVE = 2'd1;

  reg [1:0] state;

  assign drive_k       = (state == W_DRIVE);
  assign wakeup_active = (state == W_DRIVE);

  // What this cycle's wake attempt came to. A combinational decode of the
  // same conditions the sequential block uses -- not a second opinion.
  // Verilog-2005 has no enumerated type, so the encoding is localparams:
  // chapters 19.2 and 19.3 both measured what happens when one language's
  // design exposes less than the others, and the answer both times was that
  // the tri-HDL comparison stopped measuring the designs.
  localparam [1:0] WK_ISSUED          = 2'd0,
                   WK_REFUSED_UNARMED = 2'd1,
                   WK_REFUSED_AWAKE   = 2'd2,
                   WK_NONE            = 2'd3;
  assign wake_outcome = (!wake_event || bus_reset) ? WK_NONE
                      : (state != W_IDLE)         ? WK_NONE
                      : (!rw_enabled)             ? WK_REFUSED_UNARMED
                      : (!suspended)              ? WK_REFUSED_AWAKE
                                                  : WK_ISSUED;

  // THE GATE is the pair of conditions below, tested SEPARATELY rather than
  // as one conjunction. A combined `rw_enabled && suspended` would be
  // shorter and would lose the thing that matters: "not armed" and "the bus
  // is awake" are different refusals with different fixes, and a design that
  // reports one number for both tells a debugger nothing.

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      rw_enabled            <= 1'b0;
      state                 <= W_IDLE;
      k_ticks               <= 16'd0;
      wakeups_issued        <= 32'd0;
      refused_not_armed     <= 32'd0;
      refused_not_suspended <= 32'd0;
    end else begin
      // ---- the armed bit ----
      if (bus_reset) begin
        // A reset returns the device to its default state, and the arming
        // goes with it. The host must arm again.
        rw_enabled <= 1'b0;
      end else if (clear_feature_rw) begin
        rw_enabled <= 1'b0;
      end else if (set_feature_rw) begin
        rw_enabled <= 1'b1;
      end

      // ---- the wakeup itself ----
      case (state)
        W_IDLE: begin
          // A bus reset outranks the wake event as well as an in-progress
          // drive. Gating only the drive was not enough: a reset arriving in
          // the SAME cycle as a wake event would still let the wakeup start,
          // and the device would come out of the reset already driving.
          if (wake_event && !bus_reset) begin
            if (!rw_enabled)
              // Not armed. The device stays silent, and the attempt is
              // RECORDED -- a device trying to wake a host it was never
              // permitted to wake is a defect, and an unrecorded refusal
              // looks exactly like an event that never happened.
              refused_not_armed <= refused_not_armed + 32'd1;
            else if (!suspended)
              // Armed, but the bus is awake. Nothing to wake.
              refused_not_suspended <= refused_not_suspended + 32'd1;
            else begin
              state          <= W_DRIVE;
              k_ticks        <= 16'd0;
              wakeups_issued <= wakeups_issued + 32'd1;
            end
          end
        end

        W_DRIVE: begin
          // A BUS RESET ABORTS THE DRIVE, immediately and unconditionally.
          // A reset is the host taking the bus back, and a device driving K
          // through one is fighting the host for the line. This is chapter
          // 18.2's precedence rule in its device-side form: physical
          // reality outranks anything the device was in the middle of.
          if (bus_reset) begin
            state   <= W_IDLE;
            k_ticks <= 16'd0;
          end
          // Otherwise the K is driven for its full duration. A wake event
          // that disappears mid-signal does NOT retract the wakeup: the
          // host has already begun responding, and a device that stopped
          // driving early would leave the resume half-finished.
          else if (k_ticks + 16'd1 >= K_HOLD_TICKS[15:0]) begin
            k_ticks <= k_ticks + 16'd1;
            state   <= W_IDLE;
          end else begin
            k_ticks <= k_ticks + 16'd1;
          end
        end

        default: state <= W_IDLE;
      endcase
    end
  end
endmodule

package usb_wakeup_pkg;
  // Why a wake attempt did or did not reach the bus. Three outcomes, and
  // collapsing the two refusals into one "refused" loses the only thing a
  // debugger needs: an unarmed device is a firmware bug, and a device
  // signalling on a running bus is a state-tracking bug.
  typedef enum logic [1:0] {
    WK_ISSUED,          // armed and suspended: the bus was driven
    WK_REFUSED_UNARMED, // the host never armed this device
    WK_REFUSED_AWAKE,   // armed, but there was nothing to wake
    WK_NONE             // no wake event this cycle
  } wake_outcome_e;
endpackage

// usb_remote_wakeup_sv -- the one exception to the single-master rule, and the
// two independent fences around it.
//
// Every chapter of this track has rested on one fact: THE HOST INITIATES
// EVERYTHING. Chapter 2.6 established it, chapter 18.3 built an entire
// polled reporting mechanism because of it, and chapter 19.3's suspend
// detector exists because a device cannot even be TOLD to sleep -- it has to
// work it out by measuring silence.
//
// Remote wakeup is the exception. A suspended device may drive the bus
// unasked, and the host will wake up.
//
// That is a large thing to allow on a single-master bus, and it is fenced
// accordingly. A wake event does nothing at all unless BOTH of these hold:
//
//   1. THE DEVICE IS ARMED. The host must have issued
//      SetFeature(DEVICE_REMOTE_WAKEUP) -- feature selector 1 in Linux's
//      ch9.h -- and a device that was never armed must stay silent no
//      matter what happens to it. This is not a formality: an unarmed
//      device that wakes the bus wakes a machine its owner deliberately
//      put to sleep, and does it from inside a closed bag.
//
//   2. THE BUS IS SUSPENDED. Driving K on a running bus is not a wakeup,
//      it is corruption -- it collides with whatever transaction the host
//      was conducting. There is nothing to wake, so there is nothing to do.
//
// The two refusals are DIFFERENT and both are counted, because "the device
// tried to wake the host and was not armed" and "the device tried to wake a
// bus that was already awake" are different bugs with different fixes.
//
// ARMING DOES NOT SURVIVE A BUS RESET
//
// A bus reset returns the device to its default state, and the arming goes
// with it. The host must re-issue SetFeature after every reset. A device
// that kept the bit across a reset would be armed without the current host
// ever having agreed to it -- and chapter 19.3 measured what arming costs:
// five times the suspended current, on every device that has it.
module usb_remote_wakeup_sv
  import usb_wakeup_pkg::*;
#(
  parameter int unsigned K_HOLD_TICKS = 5,  // how long this device drives K
  parameter int unsigned K_MIN_TICKS  = 1,  // the specification's floor
  parameter int unsigned K_MAX_TICKS  = 15  // the specification's ceiling
) (
  input  logic       clk,
  input  logic       rst_n,

  // --- the host, through a control transfer ---
  input  logic       set_feature_rw,    // SetFeature(DEVICE_REMOTE_WAKEUP)
  input  logic       clear_feature_rw,
  input  logic       bus_reset,

  // --- the device's own state ---
  input  logic       suspended,         // from chapter 19.3
  input  logic       wake_event,        // a keypress, a packet, a sensor

  output logic        rw_enabled,       // the armed bit -- GetStatus bit 1
  output logic        drive_k,          // the device driving the bus UNASKED
  output logic [15:0] k_ticks,
  output logic        wakeup_active,
  output wake_outcome_e wake_outcome,   // what happened to this attempt

  output logic [31:0] wakeups_issued,
  output logic [31:0] refused_not_armed,
  output logic [31:0] refused_not_suspended
);
  initial begin
    if (K_HOLD_TICKS < K_MIN_TICKS || K_HOLD_TICKS > K_MAX_TICKS)
      $fatal(1, "K_HOLD_TICKS=%0d is outside the permitted range %0d..%0d",
             K_HOLD_TICKS, K_MIN_TICKS, K_MAX_TICKS);
  end

  localparam logic [1:0] W_IDLE = 2'd0, W_DRIVE = 2'd1;

  logic [1:0] state;

  // What this cycle's wake attempt came to. A combinational decode of the
  // same conditions the sequential block uses -- not a second opinion.
  always_comb begin
    if      (!wake_event || bus_reset) wake_outcome = WK_NONE;
    else if (state != W_IDLE)          wake_outcome = WK_NONE;
    else if (!rw_enabled)              wake_outcome = WK_REFUSED_UNARMED;
    else if (!suspended)               wake_outcome = WK_REFUSED_AWAKE;
    else                               wake_outcome = WK_ISSUED;
  end

  assign drive_k       = (state == W_DRIVE);
  assign wakeup_active = (state == W_DRIVE);

  // THE GATE is the pair of conditions below, tested SEPARATELY rather than
  // as one conjunction. A combined `rw_enabled && suspended` would be
  // shorter and would lose the thing that matters: "not armed" and "the bus
  // is awake" are different refusals with different fixes, and a design that
  // reports one number for both tells a debugger nothing.

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      rw_enabled            <= 1'b0;
      state                 <= W_IDLE;
      k_ticks               <= 16'd0;
      wakeups_issued        <= '0;
      refused_not_armed     <= '0;
      refused_not_suspended <= '0;
    end else begin
      // ---- the armed bit ----
      if (bus_reset) begin
        // A reset returns the device to its default state, and the arming
        // goes with it. The host must arm again.
        rw_enabled <= 1'b0;
      end else if (clear_feature_rw) begin
        rw_enabled <= 1'b0;
      end else if (set_feature_rw) begin
        rw_enabled <= 1'b1;
      end

      // ---- the wakeup itself ----
      case (state)
        W_IDLE: begin
          // A bus reset outranks the wake event as well as an in-progress
          // drive. Gating only the drive was not enough: a reset arriving in
          // the SAME cycle as a wake event would still let the wakeup start,
          // and the device would come out of the reset already driving.
          if (wake_event && !bus_reset) begin
            if (!rw_enabled)
              // Not armed. The device stays silent, and the attempt is
              // RECORDED -- a device trying to wake a host it was never
              // permitted to wake is a defect, and an unrecorded refusal
              // looks exactly like an event that never happened.
              refused_not_armed <= refused_not_armed + 1;
            else if (!suspended)
              // Armed, but the bus is awake. Nothing to wake.
              refused_not_suspended <= refused_not_suspended + 1;
            else begin
              state          <= W_DRIVE;
              k_ticks        <= 16'd0;
              wakeups_issued <= wakeups_issued + 1;
            end
          end
        end

        W_DRIVE: begin
          // A BUS RESET ABORTS THE DRIVE, immediately and unconditionally.
          // A reset is the host taking the bus back, and a device driving K
          // through one is fighting the host for the line. This is chapter
          // 18.2's precedence rule in its device-side form: physical
          // reality outranks anything the device was in the middle of.
          if (bus_reset) begin
            state   <= W_IDLE;
            k_ticks <= 16'd0;
          end
          // Otherwise the K is driven for its full duration. A wake event
          // that disappears mid-signal does NOT retract the wakeup: the
          // host has already begun responding, and a device that stopped
          // driving early would leave the resume half-finished.
          else if (k_ticks + 16'd1 >= 16'(K_HOLD_TICKS)) begin
            k_ticks <= k_ticks + 16'd1;
            state   <= W_IDLE;
          end else begin
            k_ticks <= k_ticks + 16'd1;
          end
        end

        default: state <= W_IDLE;
      endcase
    end
  end
endmodule

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

package usb_wakeup_pkg is
  -- Why a wake attempt did or did not reach the bus. Three outcomes, and
  -- collapsing the two refusals into one "refused" loses the only thing a
  -- debugger needs: an unarmed device is a firmware bug, and a device
  -- signalling on a running bus is a state-tracking bug.
  type wake_outcome_t is (
    WK_ISSUED,          -- armed and suspended: the bus was driven
    WK_REFUSED_UNARMED, -- the host never armed this device
    WK_REFUSED_AWAKE,   -- armed, but there was nothing to wake
    WK_NONE             -- no wake event this cycle
  );
end package;

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

-- usb_remote_wakeup_vhdl -- the one exception to the single-master rule, and
-- the two independent fences around it.
--
-- Every chapter of this track has rested on one fact: THE HOST INITIATES
-- EVERYTHING. Chapter 2.6 established it, chapter 18.3 built an entire
-- polled reporting mechanism because of it, and chapter 19.3's suspend
-- detector exists because a device cannot even be TOLD to sleep.
--
-- Remote wakeup is the exception. A suspended device may drive the bus
-- unasked, and the host will wake up.
--
-- That is a large thing to allow on a single-master bus, and it is fenced
-- accordingly. A wake event does nothing at all unless BOTH of these hold:
--
--   1. THE DEVICE IS ARMED. The host must have issued
--      SetFeature(DEVICE_REMOTE_WAKEUP) -- feature selector 1 in Linux's
--      ch9.h -- and a device that was never armed must stay silent. An
--      unarmed device that wakes the bus wakes a machine its owner
--      deliberately put to sleep, from inside a closed bag.
--
--   2. THE BUS IS SUSPENDED. Driving K on a running bus is not a wakeup,
--      it is corruption -- it collides with whatever transaction the host
--      was conducting.
--
-- The two refusals are DIFFERENT and both are counted, because "not armed"
-- and "the bus was already awake" are different bugs with different fixes.
--
-- ARMING DOES NOT SURVIVE A BUS RESET, and a bus reset outranks both an
-- in-progress drive and a wake event arriving in the same cycle.
entity usb_remote_wakeup_vhdl is
  generic (
    K_HOLD_TICKS : positive := 5;   -- how long this device drives K
    K_MIN_TICKS  : positive := 1;   -- the specification's floor
    K_MAX_TICKS  : positive := 15   -- the specification's ceiling
  );
  port (
    clk                   : in  std_logic;
    rst_n                 : in  std_logic;

    set_feature_rw        : in  std_logic;
    clear_feature_rw      : in  std_logic;
    bus_reset             : in  std_logic;

    suspended             : in  std_logic;
    wake_event            : in  std_logic;

    rw_enabled            : out std_logic;
    drive_k               : out std_logic;
    k_ticks               : out unsigned(15 downto 0);
    wakeup_active         : out std_logic;
    wake_outcome          : out wake_outcome_t;

    wakeups_issued        : out unsigned(31 downto 0);
    refused_not_armed     : out unsigned(31 downto 0);
    refused_not_suspended : out unsigned(31 downto 0)
  );
end entity;

architecture rtl of usb_remote_wakeup_vhdl is
  type wk_state_t is (W_IDLE, W_DRIVE);

  signal st_r    : wk_state_t := W_IDLE;
  signal arm_r   : std_logic := '0';
  signal k_r     : unsigned(15 downto 0) := (others => '0');
  signal iss_r   : unsigned(31 downto 0) := (others => '0');
  signal rna_r   : unsigned(31 downto 0) := (others => '0');
  signal rns_r   : unsigned(31 downto 0) := (others => '0');
begin
  assert K_HOLD_TICKS >= K_MIN_TICKS and K_HOLD_TICKS <= K_MAX_TICKS
    report "K_HOLD_TICKS is outside the permitted range" severity failure;

  drive_k       <= '1' when st_r = W_DRIVE else '0';
  wakeup_active <= '1' when st_r = W_DRIVE else '0';
  rw_enabled    <= arm_r;
  k_ticks       <= k_r;

  wakeups_issued        <= iss_r;
  refused_not_armed     <= rna_r;
  refused_not_suspended <= rns_r;

  -- What this cycle's wake attempt came to. A combinational decode of the
  -- same conditions the sequential process uses -- not a second opinion.
  wake_outcome <= WK_NONE            when (wake_event = '0'
                                           or bus_reset = '1') else
                  WK_NONE            when st_r /= W_IDLE       else
                  WK_REFUSED_UNARMED when arm_r = '0'          else
                  WK_REFUSED_AWAKE   when suspended = '0'      else
                  WK_ISSUED;

  process (clk, rst_n)
  begin
    if rst_n = '0' then
      arm_r <= '0'; st_r <= W_IDLE; k_r <= (others => '0');
      iss_r <= (others => '0'); rna_r <= (others => '0');
      rns_r <= (others => '0');
    elsif rising_edge(clk) then
      -- ---- the armed bit ----
      if bus_reset = '1' then
        -- A reset returns the device to its default state, and the arming
        -- goes with it. The host must arm again.
        arm_r <= '0';
      elsif clear_feature_rw = '1' then
        arm_r <= '0';
      elsif set_feature_rw = '1' then
        arm_r <= '1';
      end if;

      -- ---- the wakeup itself ----
      case st_r is
        when W_IDLE =>
          -- A bus reset outranks the wake event as well as an in-progress
          -- drive. Gating only the drive is not enough: a reset arriving in
          -- the SAME cycle as a wake event would still let the wakeup start,
          -- and the device would come out of the reset already driving.
          if wake_event = '1' and bus_reset = '0' then
            if arm_r = '0' then
              -- Not armed. The device stays silent, and the attempt is
              -- RECORDED -- an unrecorded refusal looks exactly like an
              -- event that never happened.
              rna_r <= rna_r + 1;
            elsif suspended = '0' then
              -- Armed, but the bus is awake. Nothing to wake.
              rns_r <= rns_r + 1;
            else
              st_r  <= W_DRIVE;
              k_r   <= (others => '0');
              iss_r <= iss_r + 1;
            end if;
          end if;

        when W_DRIVE =>
          -- A BUS RESET ABORTS THE DRIVE, immediately and unconditionally.
          -- A reset is the host taking the bus back, and a device driving K
          -- through one is fighting the host for the line.
          if bus_reset = '1' then
            st_r <= W_IDLE; k_r <= (others => '0');
          -- Otherwise the K is driven for its full duration. A wake event
          -- that disappears mid-signal does NOT retract the wakeup: the
          -- host has already begun responding, and a device that stopped
          -- driving early would leave the resume half-finished.
          elsif k_r + 1 >= to_unsigned(K_HOLD_TICKS, 16) then
            k_r  <= k_r + 1;
            st_r <= W_IDLE;
          else
            k_r <= k_r + 1;
          end if;
      end case;
    end if;
  end process;
end architecture;

    // 12 distinct positions (armed or not, idle or partway through K) x all
    // 32 input combinations = 384 transitions: the entire one-step domain.
    for (pos=0; pos<12; pos=pos+1)
     for (ic=0; ic<32; ic=ic+1) begin
       goto(pos);
       tick(ic[0], ic[1], ic[2], ic[3], ic[4]);
       n_trans = n_trans + 1;
     end

    // Every interleaving of "the device has a reason to wake" and "the bus
    // is suspended" across a 6-tick window: 2^6 x 2^6 = 4096 scenarios.
    // These are the two conditions section 2's gate is built from, and the
    // whole point is that neither alone is sufficient.

      // 1. THE one that matters, stated precisely. A wakeup must never
      //    START unless the device was armed -- that is the property that
      //    stops a device waking a machine its owner put to sleep. Note it
      //    is about the START: a device that was legitimately armed and is
      //    then disarmed MID-SIGNAL keeps driving, because the host has
      //    already begun responding and a half-finished resume is worse
      //    than a completed one.

  exhaustive transition sweep: 384 of 384 transitions verified
  exhaustive wake/suspend interleaving sweep: 4096 of 4096 verified

  Verilog / SystemVerilog:
  REACH: transitions=384 interleavings=4096 issued=5597
         refused-unarmed=3397 refused-awake=4313 driving-ticks=21395
  [Verilog] usb_remote_wakeup: 0 errors — PASS

  VHDL:
  REACH: transitions=384 interleavings=4096 issued=5568
         refused-unarmed=3321 refused-awake=4345 driving-ticks=21316
  [VHDL] usb_remote_wakeup_vhdl: 0 errors — PASS

// The attack sequence. Its job is to try a wakeup at every point where the
// device is NOT entitled to one -- which is exactly what a firmware bug
// does by accident, and exactly what a malicious device would do on purpose.
class unarmed_wake_attack_seq extends uvm_sequence #(wakeup_item);
  `uvm_object_utils(unarmed_wake_attack_seq)

  task body();
    wakeup_item it;
    // Never arm. Then try to wake from every bus state there is.
    foreach_state: for (int s = 0; s < 4; s++) begin
      `uvm_do_with(it, { set_feature_rw == 0; clear_feature_rw == 0;
                         suspended == s[0]; bus_reset == s[1];
                         wake_event == 1; })
    end
  endtask
endclass

// The RACE sequence: a bus reset arriving in the same cycle as a wake
// event. Section 3 found this by hand; here it is deliberate.
class reset_wake_race_seq extends uvm_sequence #(wakeup_item);
  `uvm_object_utils(reset_wake_race_seq)
  rand int unsigned offset;      // where in the K the reset lands
  constraint c_off { offset inside {[0:K_HOLD_TICKS]}; }

  task body();
    wakeup_item it;
    `uvm_do_with(it, { set_feature_rw == 1; })                 // arm
    `uvm_do_with(it, { suspended == 1; wake_event == 1; })     // start a K
    repeat (offset)
      `uvm_do_with(it, { suspended == 1; wake_event == 0; })
    // THE race. offset == 0 is the same-cycle case that section 3's second
    // gap lived in; every other offset is the in-progress case of the first.
    `uvm_do_with(it, { bus_reset == 1; wake_event == 1; })
  endtask
endclass

class wakeup_scoreboard extends uvm_scoreboard;
  `uvm_component_utils(wakeup_scoreboard)
  local bit m_armed, m_was_driving;

  function void write(wakeup_txn t);
    // THE property, and the severity is deliberate: a device that wakes a
    // host it was never permitted to wake is not a protocol error with a
    // retry path. It is a machine coming out of a bag hot.
    if (!m_was_driving && t.drive_k && !m_armed)
      `uvm_fatal("WAKE/UNARMED",
        "a device that was never armed drove the bus")

    // A bus reset outranks everything the device was doing.
    if (t.bus_reset && t.drive_k)
      `uvm_error("WAKE/RESET",
        "the device kept driving K through a bus reset")

    // The two refusals stay distinguishable.
    if (t.wake_event && !t.drive_k) begin
      if (!m_armed && t.outcome != WK_REFUSED_UNARMED)
        `uvm_error("WAKE/REASON", "an unarmed refusal reported as something else")
      if (m_armed && !t.suspended && t.outcome != WK_REFUSED_AWAKE)
        `uvm_error("WAKE/REASON", "an awake-bus refusal reported as something else")
    end

    if (t.bus_reset || t.clear_feature_rw) m_armed = 0;
    else if (t.set_feature_rw)             m_armed = 1;
    m_was_driving = t.drive_k;
  endfunction
endclass

covergroup wakeup_cg with function sample(
    bit armed, bit suspended, bit wake, bit reset, bit driving);
  // The 2x2 that section 1 is entirely about. Three of these four must
  // produce nothing, and a run that misses any of them has not tested the
  // gate -- it has tested one side of it.
  x_fences : cross
    coverpoint armed     { bins no = {0}; bins yes = {1}; },
    coverpoint suspended { bins no = {0}; bins yes = {1}; }
    iff (wake);

  // Section 3's two gaps, as bins. cp_reset_start is the same-cycle race
  // and cp_reset_mid is the reset landing inside a drive.
  cp_reset_start : coverpoint {reset, wake, driving} { bins race = {3'b110}; }
  cp_reset_mid   : coverpoint {reset, driving}       { bins mid  = {2'b11}; }
endgroup

  // THE property: a wakeup never STARTS unarmed. On the edge, because that
  // is the only instant where "was it allowed to begin?" is meaningful.
  property p_no_unarmed_start;
    @(posedge clk) disable iff (!rst_n)
      $rose(drive_k) |-> $past(rw_enabled);
  endproperty
  a_no_unarmed_start : assert property (p_no_unarmed_start)
    else $fatal(1, "a device that was never armed drove the bus");

  // And never on a bus that is awake.
  property p_no_start_while_awake;
    @(posedge clk) disable iff (!rst_n)
      $rose(drive_k) |-> $past(suspended);
  endproperty
  a_no_start_while_awake : assert property (p_no_start_while_awake);

  // A bus reset outranks both the drive and the start. Mutations W4 and W5.
  property p_reset_wins;
    @(posedge clk) disable iff (!rst_n)
      bus_reset |=> !drive_k;
  endproperty
  a_reset_wins : assert property (p_reset_wins)
    else $error("a bus reset did not stop the device driving");

  // Arming does not survive a reset. Mutation W3.
  property p_reset_disarms;
    @(posedge clk) disable iff (!rst_n)
      bus_reset |=> !rw_enabled;
  endproperty
  a_reset_disarms : assert property (p_reset_disarms);