DDR Monitors

   cycle    command        what the monitor can say
   -----    -------        ------------------------
     4      ACT b3 r500    a row is opening -- no transaction yet
     9      RD  b3 c16     a read begins; row is 500 (from the model)
    14      (data)         the burst returns
    16      (data end)     TRANSACTION COMPLETE: read, b3, r500, c16

   monitor's view of bank state   =   the DUT's view of bank state

   "is this access legal?"  ->  the DUT's own opinion of its own legality

// ---------------------------------------------------------------------
// ddr_txn -- one completed or abandoned DDR access, as reconstructed
// from the interface.
//
// CLASSIFICATION: educational, SIMULATION-ONLY.
//
// WHY EVERY DERIVED FIELD CARRIES A RESOLUTION FLAG: §6 and 7.4's
// principle -- reporting a confident wrong row is worse than
// reporting "unknown". A consumer must be able to tell a row the
// monitor KNOWS from a row it GUESSED, and the only way is a flag
// beside the value.
//
// WHAT IT DOES NOT MODEL:
//   - the device, the real command encoding, or any timing value
//   - the data's correctness. That is 27.4's comparison, not this
//     object's business; the txn carries the payload it observed.
//
// WHAT IT WOULD MISS:
//   - any field the interface does not carry and the model cannot
//     derive. A resolved field is exactly as good as the
//     reconstruction behind it.
// ---------------------------------------------------------------------
typedef enum int { TXN_READ = 0, TXN_WRITE = 1 } txn_dir_e;

typedef enum int {
  TXN_COMPLETE  = 0,   // data phase observed end to end
  TXN_ABANDONED = 1,   // precharge, reset, or illegal command intervened
  TXN_PENDING   = 2    // still in the queue -- never published in this state
} txn_outcome_e;

typedef enum int {
  RES_KNOWN   = 0,     // the model observed the establishing event
  RES_UNKNOWN = 1,     // §6: nothing observed since attach
  RES_CONFIG  = 2      // §8: supplied by the test, not independent
} resolution_e;

class ddr_txn extends uvm_sequence_item;
  `uvm_object_utils(ddr_txn)

  // ── Directly observed. These came off the pins.
  txn_dir_e     dir;
  int unsigned  bank;
  int unsigned  col;
  int unsigned  cmd_cycle;      // when the column command was seen
  int unsigned  data_cycle;     // when the burst completed
  logic [63:0]  data[$];

  // ── Derived. The row is the field the interface never transmitted
  //    (§2), so it always carries its resolution.
  int unsigned  row;
  resolution_e  row_res;

  // ── Derived from mode state, which §7 says a late attach may never
  //    learn. Its resolution is therefore often RES_CONFIG.
  int unsigned  burst_len;
  resolution_e  burst_res;

  txn_outcome_e outcome;
  string        abandon_reason;  // non-empty only when ABANDONED

  function new(string name = "ddr_txn");
    super.new(name);
    row_res   = RES_UNKNOWN;
    burst_res = RES_UNKNOWN;
    outcome   = TXN_PENDING;
  endfunction

  // A transaction is well formed when its flags and fields agree.
  // Returns "" when valid, else the first problem.
  function string validate();
    if (outcome == TXN_PENDING)
      // §14 never publishes a pending transaction: a consumer
      // receiving one would treat an incomplete access as an access.
      return "published while still pending";
    if (outcome == TXN_ABANDONED && abandon_reason == "")
      return "abandoned with no reason";
    if (outcome == TXN_COMPLETE && abandon_reason != "")
      return "complete but carries an abandon reason";
    if (outcome == TXN_COMPLETE && data_cycle < cmd_cycle)
      // Data cannot precede its command. A monitor reporting this has
      // mis-framed the data phase, which §3 says presents as a
      // missing transaction rather than a wrong one.
      return "data_cycle precedes cmd_cycle";
    if (row_res == RES_KNOWN && outcome == TXN_ABANDONED
        && abandon_reason == "bank was unknown")
      return "row claimed known while abandoned for unknown bank";
    return "";
  endfunction

  // §6: a consumer that needs a trustworthy address must be able to
  // ask. This is deliberately NOT the same as "row_res == RES_KNOWN",
  // because a config-supplied burst length also weakens the claim.
  function bit fully_independent();
    return (row_res == RES_KNOWN) && (burst_res == RES_KNOWN);
  endfunction

  function string convert2string();
    return $sformatf(
      "%s b%0d r%0d(%s) c%0d bl%0d(%s) cmd@%0d data@%0d %s%s",
      dir.name(), bank, row, row_res.name(), col, burst_len,
      burst_res.name(), cmd_cycle, data_cycle, outcome.name(),
      (abandon_reason != "") ? {" -- ", abandon_reason} : "");
  endfunction
endclass

// ---------------------------------------------------------------------
// ddr_passive_monitor -- reconstructs bank state, composes multi-
// command transactions, and publishes them with their resolutions.
//
// CLASSIFICATION: educational, SIMULATION-ONLY.
//
// COLLISION NOTE: 7.4's cmd_monitor_model owns bank-state
// reconstruction and the three-valued known/unknown treatment. This
// class uses that idea and owns what 7.4 does not -- the UVM
// packaging, the transaction composition of §2, and the pin-only
// interface discipline of §8.
//
// THE INTERFACE IS PINS ONLY, AND THAT IS THE POINT (§8, §9). There
// is deliberately no handle to the DUT here. A monitor that can see
// dut.bank_open agrees with the design by construction and reports
// success forever.
//
// WHAT IT DOES NOT MODEL:
//   - the device, the array, or electrical behaviour (Module 22)
//   - the protocol's real encoding; cmd_code is ILLUSTRATIVE
//
// WHAT IT WOULD MISS:
//   - everything in §10, and its own divergence -- hence §15.
// ---------------------------------------------------------------------
typedef enum int { BK_UNKNOWN = 0, BK_CLOSED = 1, BK_OPEN = 2 } bank_state_e;

class ddr_passive_monitor extends uvm_monitor;
  `uvm_component_utils(ddr_passive_monitor)

  uvm_analysis_port #(ddr_txn) ap;

  // ── Reconstructions (§3). Sized at build from configuration.
  protected int           m_banks;
  protected bank_state_e  m_bank[$];
  protected int unsigned  m_row[$];
  protected int unsigned  m_last_act_cycle[$];
  protected int unsigned  m_burst_len;
  protected resolution_e  m_burst_res;

  // ── Partial transactions (§2). A DDR transaction is emitted late.
  protected ddr_txn       m_pending[$];
  protected int           m_max_pending;

  // ── Accounting.
  protected int m_published;
  protected int m_abandoned;
  protected int m_dropped_overflow;
  protected int m_rejected_malformed;
  protected int unsigned m_cycle;

  function new(string name, uvm_component parent);
    super.new(name, parent);
    ap = new("ap", this);
    m_banks       = 16;          // ILLUSTRATIVE
    m_max_pending = 8;           // ILLUSTRATIVE
    m_burst_res   = RES_UNKNOWN; // §7: not learned until observed
  endfunction

  function void configure(int banks, int max_pending);
    if (banks < 2) begin
      // Fewer than two banks makes bank state meaningless and would
      // make §15's cross-check trivially true.
      `uvm_fatal("MON", $sformatf("banks must be at least 2, got %0d", banks))
    end
    if (max_pending < 1)
      `uvm_fatal("MON", "max_pending must be at least 1")
    m_banks       = banks;
    m_max_pending = max_pending;
  endfunction

  function void build_phase(uvm_phase phase);
    super.build_phase(phase);
    m_bank.delete(); m_row.delete(); m_last_act_cycle.delete();
    for (int b = 0; b < m_banks; b++) begin
      // §6: UNKNOWN, not CLOSED. Defaulting to closed would
      // manufacture a violation for every access to a bank this
      // monitor has not yet seen activated.
      m_bank.push_back(BK_UNKNOWN);
      m_row.push_back(0);
      m_last_act_cycle.push_back(0);
    end
  endfunction

  // §8's remaining hole, made explicit rather than hidden. A test
  // supplying the burst length marks it RES_CONFIG, so every
  // transaction records that this field is not independent evidence.
  function void supply_burst_len_from_config(int bl);
    if (bl < 1) begin
      `uvm_error("MON", "configured burst length must be positive")
      return;
    end
    m_burst_len = bl;
    m_burst_res = RES_CONFIG;
    `uvm_info("MON", $sformatf(
      "burst length %0d taken from configuration -- transactions will be marked RES_CONFIG", bl),
      UVM_LOW)
  endfunction

  // ── Observed events. A real monitor samples these from a virtual
  //    interface; they are methods here so the class is testable
  //    without one.

  function void observe_activate(int bank, int unsigned row);
    if (!bank_ok(bank)) return;
    m_bank[bank]           = BK_OPEN;
    m_row[bank]            = row;
    m_last_act_cycle[bank] = m_cycle;
  endfunction

  function void observe_precharge(int bank);
    if (!bank_ok(bank)) return;
    m_bank[bank] = BK_CLOSED;
    abandon_for_bank(bank, "precharge before data returned");
  endfunction

  // §7: the full resynchronisation. Every bank becomes known at once.
  function void observe_precharge_all();
    for (int b = 0; b < m_banks; b++) begin
      m_bank[b] = BK_CLOSED;
      abandon_for_bank(b, "precharge-all before data returned");
    end
  endfunction

  function void observe_mode_write(int bl);
    if (bl < 1) begin
      `uvm_error("MON", "observed mode write with a non-positive burst length")
      return;
    end
    m_burst_len = bl;
    // Observed, therefore independent -- unlike the configured path.
    m_burst_res = RES_KNOWN;
  endfunction

  // A column command starts a transaction. Its row comes from the
  // model (§2), never from the bus.
  function void observe_column(txn_dir_e dir, int bank, int unsigned col);
    ddr_txn t;
    if (!bank_ok(bank)) return;
    if (m_pending.size() >= m_max_pending) begin
      // §2: the queue has a depth and it can be exceeded. Dropping
      // silently would lose an access; this reports and counts.
      m_dropped_overflow++;
      `uvm_error("MON", $sformatf(
        "pending queue full (%0d) -- access to bank %0d dropped", m_max_pending, bank))
      return;
    end
    t = ddr_txn::type_id::create("txn");
    t.dir       = dir;
    t.bank      = bank;
    t.col       = col;
    t.cmd_cycle = m_cycle;
    t.row       = m_row[bank];
    t.burst_len = m_burst_len;
    t.burst_res = m_burst_res;
    case (m_bank[bank])
      BK_OPEN    : t.row_res = RES_KNOWN;
      BK_CLOSED  : begin
                     // An access to a bank the model believes closed
                     // is a legality finding, published as abandoned
                     // rather than dropped -- §2.
                     t.row_res        = RES_KNOWN;
                     t.outcome        = TXN_ABANDONED;
                     t.abandon_reason = "access to a bank believed closed";
                     publish(t);
                     return;
                   end
      // §6: not judgeable. Neither a violation nor a trustworthy row.
      default    : t.row_res = RES_UNKNOWN;
    endcase
    m_pending.push_back(t);
  endfunction

  // The data phase completes the oldest matching transaction.
  function void observe_data_end(int bank, logic [63:0] payload[$]);
    if (!bank_ok(bank)) return;
    foreach (m_pending[i]) begin
      if (m_pending[i].bank == bank) begin
        ddr_txn t = m_pending[i];
        t.data       = payload;
        t.data_cycle = m_cycle;
        t.outcome    = TXN_COMPLETE;
        m_pending.delete(i);
        publish(t);
        return;
      end
    end
    `uvm_error("MON", $sformatf(
      "data observed for bank %0d with no pending access -- the model has diverged", bank))
  endfunction

  function void tick(); m_cycle++; endfunction

  // ── Queries for §15's cross-check. Note these expose the MONITOR's
  //    reconstruction, never the DUT's state.
  function bank_state_e bank_state(int bank);
    return bank_ok(bank) ? m_bank[bank] : BK_UNKNOWN;
  endfunction

  function int pending_for_bank(int bank);
    int n = 0;
    foreach (m_pending[i]) if (m_pending[i].bank == bank) n++;
    return n;
  endfunction

  function int published();        return m_published;          endfunction
  function int abandoned();        return m_abandoned;          endfunction
  function int dropped_overflow(); return m_dropped_overflow;   endfunction
  function int rejected();         return m_rejected_malformed; endfunction
  function int pending_depth();    return m_pending.size();     endfunction

  protected function bit bank_ok(int bank);
    if (bank < 0 || bank >= m_banks) begin
      `uvm_error("MON", $sformatf("bank %0d outside 0..%0d", bank, m_banks-1))
      return 0;
    end
    return 1;
  endfunction

  protected function void abandon_for_bank(int bank, string reason);
    int i = 0;
    while (i < m_pending.size()) begin
      if (m_pending[i].bank == bank) begin
        ddr_txn t = m_pending[i];
        t.outcome        = TXN_ABANDONED;
        t.abandon_reason = reason;
        m_pending.delete(i);
        publish(t);
      end else i++;
    end
  endfunction

  // A malformed transaction is REJECTED, not published. A consumer
  // receiving one would treat monitor damage as design behaviour.
  protected function void publish(ddr_txn t);
    string why = t.validate();
    if (why != "") begin
      m_rejected_malformed++;
      `uvm_error("MON", $sformatf("refusing to publish malformed txn: %s", why))
      return;
    end
    if (t.outcome == TXN_ABANDONED) m_abandoned++;
    else                            m_published++;
    ap.write(t);
  endfunction

  function void report_phase(uvm_phase phase);
    `uvm_info("MON", $sformatf(
      "published=%0d abandoned=%0d dropped=%0d rejected=%0d still_pending=%0d burst_res=%s",
      m_published, m_abandoned, m_dropped_overflow, m_rejected_malformed,
      m_pending.size(), m_burst_res.name()), UVM_LOW)
    if (m_pending.size() != 0)
      // Transactions still pending at end of test are accesses whose
      // data never returned. Silence here would hide a hang.
      `uvm_error("MON", $sformatf(
        "%0d transactions never completed", m_pending.size()))
  endfunction
endclass

// ---------------------------------------------------------------------
// reconstruction_consistency_checker -- two routes to "is this bank
// open?", compared.
//
// CLASSIFICATION: educational, SIMULATION-ONLY.
//
// WHY IT EXISTS: §5. A model diverges silently and stays diverged, so
// every later transaction is subtly wrong and a scoreboard reports a
// mismatch whose cause is upstream. This converts a late,
// misattributed failure into an immediate, correctly attributed one.
//
// WHAT IT DOES NOT MODEL:
//   - the device, the DUT's state, or WHICH route is right. A
//     divergence is escalated for human attention, not resolved.
//
// WHAT IT WOULD MISS:
//   - a divergence both routes SHARE. Both derive from the same
//     command stream, so a missed command corrupts both identically.
//     This is 27.1 §13's correlated-model problem in miniature and
//     it is the ceiling on any internal consistency check.
// ---------------------------------------------------------------------
class reconstruction_consistency_checker extends uvm_component;
  `uvm_component_utils(reconstruction_consistency_checker)

  protected ddr_passive_monitor m_mon;
  protected int m_checks;
  protected int m_divergences;
  protected int m_unknown_skipped;

  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction

  function void set_monitor(ddr_passive_monitor mon);
    if (mon == null) `uvm_fatal("CONS", "null monitor handle")
    m_mon = mon;
  endfunction

  // Route A: event-driven bank state. Route B: outstanding work.
  // §5: not the same function, and they should agree.
  function bit check_bank(int bank);
    bank_state_e a;
    int          b_pending;
    m_checks++;
    if (m_mon == null) begin
      `uvm_error("CONS", "no monitor set")
      return 0;
    end
    a         = m_mon.bank_state(bank);
    b_pending = m_mon.pending_for_bank(bank);

    // §6: an unknown bank is not judgeable, so it is SKIPPED rather
    // than counted as agreement. Counting it as agreement would let a
    // monitor that knows nothing report perfect consistency.
    if (a == BK_UNKNOWN) begin
      m_unknown_skipped++;
      return 1;
    end

    // An outstanding access to a bank the event route believes closed
    // means either a command was missed or a transaction was
    // mis-framed (§5).
    if ((a == BK_CLOSED) && (b_pending > 0)) begin
      m_divergences++;
      `uvm_error("CONS", $sformatf(
        "bank %0d: event route says CLOSED, %0d access(es) outstanding -- reconstruction diverged",
        bank, b_pending))
      return 0;
    end
    return 1;
  endfunction

  function void check_all(int banks);
    for (int b = 0; b < banks; b++) void'(check_bank(b));
  endfunction

  function int checks();          return m_checks;           endfunction
  function int divergences();     return m_divergences;      endfunction
  function int unknown_skipped(); return m_unknown_skipped;  endfunction

  // Consistency is CLAIMABLE only when something was actually
  // compared. A run in which every bank was unknown skipped every
  // check and establishes nothing -- the mirror of 27.2's vacuity.
  function bit consistency_claimable();
    return (m_divergences == 0) && ((m_checks - m_unknown_skipped) > 0);
  endfunction

  function void report_phase(uvm_phase phase);
    `uvm_info("CONS", $sformatf(
      "checks=%0d compared=%0d unknown_skipped=%0d divergences=%0d claimable=%0b",
      m_checks, m_checks - m_unknown_skipped, m_unknown_skipped,
      m_divergences, consistency_claimable()), UVM_LOW)
  endfunction
endclass

// SIMULATION-ONLY. These components are classes with no clock, so
// their invariants are immediate assertions in a checker task rather
// than concurrent properties. 27.2 §11's bindable property set is the
// concurrent counterpart; this is the monitor's own accounting.
task automatic check_monitor_invariants(ddr_passive_monitor mon,
                                        reconstruction_consistency_checker cons,
                                        int banks);

  // P1 -- FORBIDDEN. A pending transaction is never published. §12: a
  // consumer receiving one would treat an incomplete access as an
  // access, and 27.4's scoreboard would compare data that never came.
  begin
    ddr_txn probe = ddr_txn::type_id::create("probe");
    probe.outcome = TXN_PENDING;
    assert (probe.validate() != "")
      else $error("P1: a pending transaction passed validate()");
  end

  // P2 -- FORBIDDEN. An abandoned transaction always carries a reason.
  // §2: publishing it without one loses the evidence that motivated
  // publishing it instead of dropping it.
  begin
    ddr_txn probe = ddr_txn::type_id::create("probe");
    probe.outcome = TXN_ABANDONED; probe.abandon_reason = "";
    assert (probe.validate() != "")
      else $error("P2: an abandoned transaction with no reason passed validate()");
  end

  // P3 -- FORBIDDEN. A complete transaction never carries an abandon
  // reason. The two outcomes are exclusive and a consumer switches on
  // them.
  begin
    ddr_txn probe = ddr_txn::type_id::create("probe");
    probe.outcome = TXN_COMPLETE; probe.abandon_reason = "spurious";
    assert (probe.validate() != "")
      else $error("P3: a complete transaction with an abandon reason passed validate()");
  end

  // P4 -- FORBIDDEN. Data never precedes its command. §3: a monitor
  // reporting this has mis-framed the data phase, which presents
  // downstream as a MISSING access rather than a wrong one.
  begin
    ddr_txn probe = ddr_txn::type_id::create("probe");
    probe.outcome = TXN_COMPLETE; probe.cmd_cycle = 10; probe.data_cycle = 4;
    assert (probe.validate() != "")
      else $error("P4: data_cycle before cmd_cycle passed validate()");
  end

  // P5 -- a malformed transaction is never counted as published. §14:
  // rejection must not inflate the published total, or the monitor
  // reports work it refused to do.
  assert (mon.published() >= 0 && mon.rejected() >= 0)
    else $error("P5: negative accounting");

  // P6 -- PARTITION. Every transaction that left the queue is either
  // published or abandoned, and rejected ones are neither.
  assert (mon.published() + mon.abandoned() >= 0)
    else $error("P6: outcome accounting inconsistent");

  // P7 -- FORBIDDEN. No transaction remains pending at end of test.
  // §14: an access whose data never returned is a hang, and silence
  // here would hide it.
  assert (mon.pending_depth() == 0)
    else $error("P7: %0d transactions never completed", mon.pending_depth());

  // P8 -- the queue never exceeds its configured depth. §2: the depth
  // is real and exceeding it drops an access.
  assert (mon.pending_depth() <= 8)
    else $error("P8: pending depth %0d exceeds the configured maximum",
                mon.pending_depth());

  // P9 -- FORBIDDEN. An unknown bank is never counted as consistency
  // agreement. §6, and it is 27.2's vacuity argument in a monitor:
  // a component that knows nothing must not report perfect agreement.
  assert (cons.unknown_skipped() <= cons.checks())
    else $error("P9: skipped count exceeds checks");

  // P10 -- FORBIDDEN. Consistency is never claimable with nothing
  // compared. The mirror of a vacuous assertion.
  assert (!(cons.consistency_claimable()
            && ((cons.checks() - cons.unknown_skipped()) == 0)))
    else $error("P10: consistency claimed with zero comparisons");

  // P11 -- FORBIDDEN. Consistency is never claimable with a
  // divergence outstanding.
  assert (!(cons.consistency_claimable() && (cons.divergences() > 0)))
    else $error("P11: consistency claimed with %0d divergences", cons.divergences());

  // P12 -- §8's hole, made checkable: a configured burst length
  // always marks its transactions as non-independent.
  begin
    ddr_txn probe = ddr_txn::type_id::create("probe");
    probe.row_res = RES_KNOWN; probe.burst_res = RES_CONFIG;
    assert (!probe.fully_independent())
      else $error("P12: a config-supplied burst length reported as fully independent");
  end

  // P13 -- and a fully observed transaction IS independent, so the
  // flag is not merely always false.
  begin
    ddr_txn probe = ddr_txn::type_id::create("probe");
    probe.row_res = RES_KNOWN; probe.burst_res = RES_KNOWN;
    assert (probe.fully_independent())
      else $error("P13: a fully observed transaction reported as not independent");
  end

  // P14 -- FORBIDDEN. A bank index outside range never changes state.
  assert (mon.bank_state(banks) == BK_UNKNOWN)
    else $error("P14: an out-of-range bank returned a definite state");
endtask

// SIMULATION-ONLY. Coverage over what the MONITOR produced -- which
// is the only place the resolution flags of §12 can be sampled.
// 27.5 owns the DDR functional-coverage model; this covers the
// monitor's own behaviour, which is a different question.
covergroup monitor_behaviour_cg with function sample(ddr_txn t,
                                                     int pending_depth);
  option.per_instance = 1;

  // Both directions, so a read-only suite is visible as one.
  cp_dir : coverpoint t.dir;

  // Every outcome the monitor can publish. TXN_PENDING is deliberately
  // absent as a bin: P1 forbids publishing one, so a hit would be a bug.
  cp_outcome : coverpoint t.outcome {
    bins complete  = {TXN_COMPLETE};
    bins abandoned = {TXN_ABANDONED};
    illegal_bins   pending = {TXN_PENDING};
  }

  // §6's three resolutions for the row, including the one a late
  // attach produces.
  cp_row_res : coverpoint t.row_res {
    bins known   = {RES_KNOWN};
    bins unknown = {RES_UNKNOWN};
    bins config  = {RES_CONFIG};
  }

  // §8's hole: how often a transaction's burst length was configured
  // rather than observed.
  cp_burst_res : coverpoint t.burst_res;

  // The queue at empty, mid-depth and full -- §2's depth is real and
  // the full case is the one that drops an access.
  cp_depth : coverpoint pending_depth {
    bins empty = {0};
    bins mid   = {[1:7]};
    bins full  = {8};
  }

  // The cross that matters: an unknown row on a completed transaction
  // is a usable access with an untrustworthy address, and a suite
  // should know whether it has any.
  x_outcome_res : cross cp_outcome, cp_row_res;

  // And direction against resolution, so a suite cannot claim
  // coverage of writes while only resolving rows on reads.
  x_dir_res : cross cp_dir, cp_row_res;

  // §12's independence flag, sampled. A suite in which no
  // transaction is fully independent has learned nothing the design
  // did not tell it -- §8's hole, measured rather than assumed.
  cp_independent : coverpoint t.fully_independent() {
    bins independent = {1};
    bins weakened    = {0};
  }

  // Bank index at both extremes. A monitor exercised on one bank has
  // exercised one reconstruction, whatever its transaction count.
  cp_bank_edge : coverpoint t.bank {
    bins first  = {0};
    bins middle = {[1:14]};
    bins last   = {15};
  }

  // Whether an abandoned transaction carried a reason at all. P2
  // forbids the empty case, so a hit here is a bug rather than a gap
  // -- the same illegal-bin reasoning as cp_outcome's pending.
  cp_abandon_reasoned : coverpoint (t.abandon_reason != "") {
    bins reasoned   = {1};
    bins unreasoned = {0};
  }
endgroup

// SIMULATION-ONLY. Independent reference model. Replays the same
// command stream and rebuilds bank state with an ASSOCIATIVE ARRAY
// keyed by bank, rather than the monitor's queue-indexed vector -- a
// different representation, so agreement is evidence.
class monitor_reference;
  bank_state_e st[int];
  int unsigned rw[int];
  int          n_open;

  function void reset_all(int banks);
    st.delete(); rw.delete(); n_open = 0;
    for (int b = 0; b < banks; b++) st[b] = BK_UNKNOWN;
  endfunction

  function void act(int b, int unsigned r);
    if (st.exists(b) && st[b] != BK_OPEN) n_open++;
    st[b] = BK_OPEN; rw[b] = r;
  endfunction

  function void pre(int b);
    if (st.exists(b) && st[b] == BK_OPEN) n_open--;
    st[b] = BK_CLOSED;
  endfunction

  function void pre_all(int banks);
    for (int b = 0; b < banks; b++) st[b] = BK_CLOSED;
    n_open = 0;
  endfunction

  // Counted by iteration, not by the maintained n_open -- so the two
  // disagree if the incremental bookkeeping is wrong.
  function int count_open();
    int n = 0;
    foreach (st[b]) if (st[b] == BK_OPEN) n++;
    return n;
  endfunction

  function bit bookkeeping_consistent();
    return (n_open == count_open());
  endfunction
endclass

  THE MISSED COMMAND THAT NO INTERNAL CHECK CAN SEE

    stimulus : 5,000 commands, with ONE activate removed from what
               the monitor observes -- as a sampling race or a
               mis-specified virtual interface would do.

    monitor's view          : bank 7 is CLOSED (it never saw the ACT)
    reference's view        : bank 7 is OPEN, row 1200
    device's actual state   : OPEN, row 1200

    consistency checker :
        checks=16 compared=16 unknown_skipped=0
        divergences=0                     <-- silent
        claimable=TRUE

    monitor accounting :
        published=4,912 abandoned=88 dropped=0 rejected=0

    what happened : the event route thinks bank 7 is closed, so the
      88 accesses to it were published as ABANDONED with the reason
      "access to a bank believed closed". Both reconstruction routes
      agree, because both were fed the same defective stream. The
      internal check compared two corrupted answers and found them
      identical.

    how it presents downstream : 27.4's scoreboard receives 88
      abandoned transactions for a bank the design was using
      correctly. The symptom is a design that appears to violate
      bank legality 88 times, and the cause is one sample the
      monitor never took.

    why it is the ceiling : §14's WHAT IT WOULD MISS says exactly
      this, and it is 27.1 §13's correlated vendor-model error in
      miniature -- two derivations from one source cannot catch a
      fault in the source.

    the only defence : an EXTERNAL reference replaying the stream
      independently, which is what this DV check is. That is why a
      monitor needs its own testbench, and why §10's second row
      prices consistency checking as worth its cost while not
      claiming it is sufficient.