Multi-Master Systems

// ─────────────────────────────────────────────────────────────────────────
// wb_owner2 — the smallest thing that can give two masters one slave.
//
// THIS IS LABORATORY EQUIPMENT, NOT AN ARBITER DESIGN. It exists so that
// atomicity can be measured against competition, because atomicity cannot
// be demonstrated honestly with one master. Fairness, starvation, priority
// schemes, round-robin and scalable fabrics are Module 17's subject and
// none of them appear here: this selector is fixed-priority, two-port, and
// deliberately uninteresting.
//
// The specification is explicit that this is the integrator's territory:
// "Arbitration methodology is defined by the end user (priority arbiter,
// round-robin arbiter, etc.)." So every behaviour below is LOCAL POLICY.
//
// THE ONE PARAMETER THAT MATTERS: HONOUR_LOCK.
//
//   HONOUR_LOCK = 1  once a master owns the bus with LOCK_O asserted, the
//                    owner is not changed until that master negates LOCK_O
//                    or CYC_O. This is the behaviour LOCK_O's description
//                    states: "Once the transfer has started, the INTERCON
//                    does not grant the bus to any other MASTER, until the
//                    current MASTER negates [LOCK_O] or [CYC_O]."
//
//   HONOUR_LOCK = 0  ownership is re-evaluated whenever the current owner
//                    is not presenting a transfer, LOCK_O or not.
//
// HONOUR_LOCK = 0 IS NOT A PROTOCOL VIOLATION IN ANY RULE I CAN CITE. No
// numbered rule in the Classic chapter constrains an arbiter. What it
// violates is LOCK_O's stated meaning, and Chapter 15.4 measures what a
// system loses when a signal's meaning is not implemented.
//
// RECOMMENDATION 3.05 is the closest the specification comes to describing
// arbiter behaviour: "Arbitration logic often uses [CYC_I] to select
// between MASTER interfaces." Note "often" - it is advisory, and it
// describes selection, not retention.
// ─────────────────────────────────────────────────────────────────────────
module wb_owner2 #(
  parameter int unsigned AW          = 30,
  parameter int unsigned DW          = 32,
  parameter bit          HONOUR_LOCK = 1'b1
) (
  input  logic            clk_i,
  input  logic            rst_i,
  // master A
  input  logic            a_cyc_i,
  input  logic            a_stb_i,
  input  logic            a_lock_i,
  input  logic            a_we_i,
  input  logic [AW-1:0]   a_adr_i,
  input  logic [DW-1:0]   a_dat_i,
  input  logic [DW/8-1:0] a_sel_i,
  output logic [DW-1:0]   a_dat_o,
  output logic            a_ack_o,
  output logic            a_err_o,
  // master B
  input  logic            b_cyc_i,
  input  logic            b_stb_i,
  input  logic            b_lock_i,
  input  logic            b_we_i,
  input  logic [AW-1:0]   b_adr_i,
  input  logic [DW-1:0]   b_dat_i,
  input  logic [DW/8-1:0] b_sel_i,
  output logic [DW-1:0]   b_dat_o,
  output logic            b_ack_o,
  output logic            b_err_o,
  // slave side
  output logic            s_cyc_o,
  output logic            s_stb_o,
  output logic            s_we_o,
  output logic [AW-1:0]   s_adr_o,
  output logic [DW-1:0]   s_dat_o,
  output logic [DW/8-1:0] s_sel_o,
  input  logic [DW-1:0]   s_dat_i,
  input  logic            s_ack_i,
  input  logic            s_err_i,
  // observation only
  output logic            owner_o,        // 0 = A, 1 = B
  output logic            owned_o         // somebody holds it
);
  logic owner_q, owned_q;

  // The current owner's own signals, whoever that is.
  logic cur_cyc, cur_stb, cur_lock;
  assign cur_cyc  = owner_q ? b_cyc_i  : a_cyc_i;
  assign cur_stb  = owner_q ? b_stb_i  : a_stb_i;
  assign cur_lock = owner_q ? b_lock_i : a_lock_i;

  // Who else wants it.
  logic other_cyc;
  assign other_cyc = owner_q ? a_cyc_i : b_cyc_i;

  // OWNERSHIP, in one always_comb so the precedence is readable.
  //
  // This selector implements LOCK_O's stated meaning and nothing more:
  // "Once the transfer has started, the INTERCON does not grant the bus to
  // any other MASTER, until the current MASTER negates [LOCK_O] or
  // [CYC_O]." A LOCKED owner is therefore untouchable until it drops one.
  //
  // An UNLOCKED owner is a case the specification does not legislate.
  // RECOMMENDATION 3.05 observes only that arbiters "often use [CYC_I] to
  // select between MASTER interfaces", and warns that "keeping [CYC_O]
  // asserted may lead to arbitration problems". This selector's LOCAL
  // POLICY is the ordinary one that warning describes: an unlocked owner
  // that is not presenting a transfer yields to a master that is waiting.
  //
  // That single rule is what makes retaining CYC_O and asserting LOCK_O
  // measurably different. Without it, an owner would keep the bus through
  // its own idle clocks and every policy would look identical.
  //
  // With HONOUR_LOCK cleared, the locked branch is removed and a locked
  // owner is treated exactly like an unlocked one - Chapter 15.4's broken
  // interconnect.
  logic next_owner, next_owned;
  always_comb begin
    next_owner = owner_q;
    next_owned = owned_q;
    if (!owned_q) begin
      if      (a_cyc_i) begin next_owner = 1'b0; next_owned = 1'b1; end
      else if (b_cyc_i) begin next_owner = 1'b1; next_owned = 1'b1; end
    end else if (!cur_cyc) begin
      // the owner has finished its cycle
      if      (other_cyc) begin next_owner = ~owner_q; next_owned = 1'b1; end
      else                       next_owned = 1'b0;
    end else if (HONOUR_LOCK && cur_lock) begin
      next_owner = owner_q;              // locked: nothing moves
    end else if (!cur_stb && other_cyc) begin
      next_owner = ~owner_q;             // unlocked and idle: yield
    end
  end

  always_ff @(posedge clk_i) begin
    if (rst_i) begin
      owner_q <= 1'b0; owned_q <= 1'b0;
    end else begin
      owner_q <= next_owner;
      owned_q <= next_owned;
    end
  end

  // Route the owner's request down, and the slave's answer back to the
  // owner only. A non-owner sees no termination and no data, so it simply
  // waits - which is what makes it a competitor rather than a corrupter.
  assign s_cyc_o = owned_q && (owner_q ? b_cyc_i  : a_cyc_i);
  assign s_stb_o = owned_q && (owner_q ? b_stb_i  : a_stb_i);
  assign s_we_o  =            owner_q ? b_we_i   : a_we_i;
  assign s_adr_o =            owner_q ? b_adr_i  : a_adr_i;
  assign s_dat_o =            owner_q ? b_dat_i  : a_dat_i;
  assign s_sel_o =            owner_q ? b_sel_i  : a_sel_i;

  assign a_ack_o = owned_q && !owner_q && s_ack_i;
  assign a_err_o = owned_q && !owner_q && s_err_i;
  assign a_dat_o = s_dat_i;
  assign b_ack_o = owned_q &&  owner_q && s_ack_i;
  assign b_err_o = owned_q &&  owner_q && s_err_i;
  assign b_dat_o = s_dat_i;

  assign owner_o = owner_q;
  assign owned_o = owned_q;
endmodule

// ─────────────────────────────────────────────────────────────────────────
// wb_rmw_probe — the ownership timeline, and three checkers built on it.
//
// The three checkers are the ones Chapter 15.4 validates in BOTH
// directions: each must pass a correct system AND fail a targeted broken
// one, for the reason it claims to check. A checker that has only ever
// passed is an untested checker.
//
//   OWNER STABILITY    ownership does not change while a locked owner is
//                      mid-operation. Targeted defect: an owner selector
//                      that ignores LOCK_O.
//   COMMIT COUNT       one successful increment produces exactly one write
//                      commit. Targeted defect: a slave that re-executes a
//                      write while its termination is held.
//   ATOMIC RESULT      N successful increments move the counter by exactly
//                      N. Targeted defect: any lost update.
//
// The protected interval is defined here once, because every ownership
// claim in the module depends on which clocks are inside it:
//
//   from the clock a master's CYC_O is first asserted for the operation
//   through the clock its write phase is answered
//
// That is the interval an RMW must protect. An owner change inside it is
// the defect; an owner change outside it is ordinary arbitration.
//
// Everything here is simulation instrumentation. `int unsigned` counters
// are not synthesizable and none of this is a Wishbone feature.
// ─────────────────────────────────────────────────────────────────────────
module wb_rmw_probe (
  input  logic        clk_i,
  input  logic        rst_i,
  input  logic        owner_i,        // 0 = A, 1 = B
  input  logic        owned_i,
  // the two masters' own signals
  input  logic        a_cyc_i,
  input  logic        a_lock_i,
  input  logic        b_cyc_i,
  input  logic        b_lock_i,
  // the slave's commit evidence
  input  logic        wr_commit_i,    // one clock per committed write
  output int unsigned owner_changes_o,
  output int unsigned unsafe_changes_o,   // changes inside a protected interval
  output int unsigned commits_o,
  output int unsigned a_cycles_o,
  output int unsigned b_cycles_o
);
  logic owner_q, owned_q, a_cyc_q, b_cyc_q;

  // A master is mid-operation while its own CYC_O is asserted. Protection
  // is claimed only while it also asserts LOCK_O - that is the difference
  // between requesting the resource and holding it.
  logic a_protected, b_protected, cur_protected;
  assign a_protected = a_cyc_i && a_lock_i;
  assign b_protected = b_cyc_i && b_lock_i;
  assign cur_protected = owner_i ? b_protected : a_protected;

  always_ff @(posedge clk_i) begin
    if (rst_i) begin
      owner_q <= 1'b0; owned_q <= 1'b0; a_cyc_q <= 1'b0; b_cyc_q <= 1'b0;
      owner_changes_o <= 0; unsafe_changes_o <= 0; commits_o <= 0;
      a_cycles_o <= 0; b_cycles_o <= 0;
    end else begin
      owner_q <= owner_i; owned_q <= owned_i;
      a_cyc_q <= a_cyc_i; b_cyc_q <= b_cyc_i;

      if (owned_q && owned_i && (owner_i != owner_q)) begin
        owner_changes_o <= owner_changes_o + 1;
        // Was the master that just lost the bus still holding it under
        // lock? If so the selector took the bus from a protected owner.
        if (owner_q ? b_protected : a_protected)
          unsafe_changes_o <= unsafe_changes_o + 1;
      end

      if (wr_commit_i) commits_o <= commits_o + 1;
      if (a_cyc_i && !a_cyc_q) a_cycles_o <= a_cycles_o + 1;
      if (b_cyc_i && !b_cyc_q) b_cycles_o <= b_cycles_o + 1;
    end
  end
endmodule

  === SIM G - two masters, the selector honours LOCK_O ===
    Both masters are released on the same clock. Both assert
    LOCK_O across their read and write halves.

    clk  owner  CYC  LOCK  STB  WE  ACK  phase
      4    A     1    1     1    0   1   read answered
      5    A     1    1     0    0   0   -
      6    A     1    1     1    1   1   write commits
      8    B     1    1     1    0   1   read answered
      9    B     1    1     0    0   0   -
     10    B     1    1     1    1   1   write commits

    A read 10, wrote 11    B read 11, wrote 12
    owner changes                      1
    owner changes inside a protected interval  0
    write commits                      2
    counter  10 -> 12   expected 12

    Ownership changed once, and it changed between the two
    operations rather than inside either of them.

  === SIM H - the same masters, the selector ignores LOCK_O ===
    Identical masters, identical slave, identical stimulus.
    HONOUR_LOCK is cleared, so a locked owner is treated
    exactly like an unlocked one.

    clk  owner  CYC  LOCK  STB  WE  ACK  phase
     17    A     1    1     1    0   1   read answered
     18    A     1    1     0    0   0   -
     19    B     1    1     1    0   1   read answered
     20    B     1    1     0    0   0   -
     21    A     1    1     1    1   1   write commits
     23    B     1    1     1    1   1   write commits

    A read 10, wrote 11    B read 10, wrote 11
    owner changes                      3
    owner changes inside a protected interval  2
    write commits                      2
    counter  10 -> 11   expected 12

    Both masters are byte-identical to SIM G's. Both asserted
    LOCK_O for the whole interval. The signal was correct and
    the interconnect did not implement its meaning.

  === SIM I - wait states inside the protected interval ===
    The slave withholds its termination for two clocks on
    every phase, so each half of each RMW waits.

    clk  owner  CYC  LOCK  STB  WE  ACK  phase
     30    A     1    1     1    0   0   read
     31    A     1    1     1    0   0   read
     32    A     1    1     1    0   1   read answered
     33    A     1    1     0    0   0   -
     34    A     1    1     1    1   0   write
     35    A     1    1     1    1   0   write
     36    A     1    1     1    1   1   write commits
     38    B     1    1     1    0   0   read
     39    B     1    1     1    0   0   read
     40    B     1    1     1    0   1   read answered
     41    B     1    1     0    0   0   -
     42    B     1    1     1    1   0   write
     43    B     1    1     1    1   0   write
     44    B     1    1     1    1   1   write commits

    owner changes inside a protected interval  0
    write commits                      2
    counter  10 -> 12   expected 12

    Longer interval, same guarantee. The wait states stretch
    the window an interloper would need, and ownership did
    not move for any of those clocks. Note also that a held
    phase produced ONE commit, not one per clock.

  === NEGATIVE-CONTROL GATE ===
    Each checker run against a correct system and against the
    one defect it claims to detect. A checker that cannot
    fail has not been shown to check anything.

    checker          invariant                        correct  broken
    OWNER STABILITY  no owner change inside a          PASS     FAIL
                     protected interval
    COMMIT COUNT     two increments, two write         PASS     FAIL
                     commits
    ATOMIC RESULT    counter moves by exactly two      PASS     FAIL

    targeted defects:
      OWNER STABILITY  wb_owner2 with HONOUR_LOCK = 0
      COMMIT COUNT     slave committing on every presented clock
      ATOMIC RESULT    the same lock-ignoring selector

    'commits' below is the slave's own register-update count,
    not a count of acknowledgements. The held-phase rig
    produces one ACK per phase either way.

    evidence behind each verdict:
      correct rig    unsafe owner changes 0   commits 2   counter 12
      lock-ignoring  unsafe owner changes 2   commits 2   counter 11
      held-phase     unsafe owner changes 0   commits 6   counter 12

    CHECKERS REQUIRED                >= 3
    CHECKERS PASSING CORRECT DUT     3 / 3
    CHECKERS FAILING TARGET DEFECT   3 / 3

  === SIM J - errors inside a read-modify-write ===
    The slave implements offset 0 and answers ERR for any
    other offset, which is Module 12's ordinary unmapped
    behaviour. Aiming a phase at offset 1 injects a real ERR.

    --- ERR on the read half ---
    client result            failure
    read phases served       0
    write commits            0
    counter  10 -> 10

    LOCAL MASTER POLICY: an error on the read abandons the
    operation. No write phase was presented, so nothing was
    committed and there is nothing to undo. The client is
    told the operation failed.

    --- ERR on the write half ---
    value read               10
    value the master derived 11
    client result            failure
    read phases served       1
    write commits            0
    counter  10 -> 10

    The read succeeded and the write did not. The client is
    told failure, and the counter is unchanged.

    THE COUNTER IS UNCHANGED BECAUSE OF THIS SLAVE, NOT
    BECAUSE OF WISHBONE. wb_counter_slave gates its commit on
    an acknowledged write, so a phase it answers with ERR
    commits nothing - LOCAL SLAVE POLICY, and verifiable in
    its source. A slave that latched first and errored after
    would leave the value changed and report failure, and
    nothing in the specification forbids that.

    NOTHING HERE IS A ROLLBACK. Wishbone defines error
    termination; it defines no mechanism for undoing a
    committed write, and no master can restore a value it
    never knew had changed.

    Across both cases: one client request, one client
    completion, and no partial success reported as success.

// ─────────────────────────────────────────────────────────────────────────
// wb_owner_props — the interconnect's half of atomicity. All LOCAL: the
// specification places no numbered requirement on an arbiter, and states
// that "Arbitration methodology is defined by the end user".
// ─────────────────────────────────────────────────────────────────────────
module wb_owner_props (
  input logic clk_i,
  input logic rst_i,
  input logic owner_i,
  input logic owned_i,
  input logic a_cyc_i,
  input logic a_lock_i,
  input logic b_cyc_i,
  input logic b_lock_i
);
  default disable iff (rst_i);

  logic cur_locked;
  assign cur_locked = owner_i ? (b_cyc_i && b_lock_i) : (a_cyc_i && a_lock_i);

  // P9 — LOCAL INTERCONNECT POLICY, implementing LOCK_O's stated meaning:
  // "Once the transfer has started, the INTERCON does not grant the bus to
  // any other MASTER, until the current MASTER negates [LOCK_O] or
  // [CYC_O]." This is the property wb_owner2 with HONOUR_LOCK = 0
  // violates, and it is validated in both directions in Chapter 15.4.
  property p_owner_stable_while_locked;
    @(posedge clk_i) (owned_i && cur_locked) |=> $stable(owner_i);
  endproperty
  a_owner_stable_while_locked: assert property (p_owner_stable_while_locked);

  // P10 — LOCAL INTERCONNECT POLICY. A master that holds nothing is not
  // the owner. Ownership implies somebody is asserting CYC_O.
  property p_owned_implies_requesting;
    @(posedge clk_i) owned_i |-> (a_cyc_i || b_cyc_i);
  endproperty
  a_owned_implies_requesting: assert property (p_owned_implies_requesting);
endmodule