Data Masking

// ─────────────────────────────────────────────────────────────────────────
// wb_masked_register_bank — four registers, four different meanings for
// "this lane participates".
//
// SEL answers ONE question: which lanes of the data word take part. What
// participation MEANS is the register's own business, and the four here
// answer it differently:
//
//   0 CONTROL   ordinary RW   next = (old & ~mask) | (dat & mask)
//   1 OUTPUT    ordinary RW   same
//   2 EVENTS    write-1-clear  a participating 1 clears; a 0 leaves alone
//   3 COMMAND   side effect    a participating write fires one pulse
//
// THE ORDER OF OPERATIONS IS THE POINT OF THE WHOLE CHAPTER:
//
//   mask FIRST, register semantics SECOND.
//
// Not "W1C, then mask" and not "fire the command, then check SEL". The
// lanes that do not participate are not part of the transfer at all, so the
// register's rule is applied only to what is left after masking. Every
// defect in Chapter 13.5 is that order reversed or that step skipped.
//
// COMMIT MODEL, inherited from Module 7 and Module 12: state changes on a
// qualified, acknowledged write and at no other time. `xfer` is
// cyc_i && stb_i; `wr` adds we_i and a mapped offset. Nothing here reacts
// to a presented-but-unterminated transfer.
// ─────────────────────────────────────────────────────────────────────────
module wb_masked_register_bank #(
  parameter int unsigned OFF_AW = 4,
  parameter int unsigned DW     = 32,
  parameter int unsigned GRAN   = 8,
  localparam int unsigned SELW = DW / GRAN
) (
  input  logic              clk_i,
  input  logic              rst_i,
  input  logic              cyc_i,
  input  logic              stb_i,
  input  logic              we_i,
  input  logic [OFF_AW-1:0] adr_i,      // LOCAL word offset
  input  logic [SELW-1:0]   sel_i,
  input  logic [DW-1:0]     dat_i,
  // hardware event sources. A status register is set by the hardware it
  // reports on and cleared by software; without this input the W1C
  // semantics would have nothing to clear.
  input  logic [DW-1:0]     event_set_i,
  output logic [DW-1:0]     dat_o,
  output logic              ack_o,
  output logic              err_o,
  // observation only — not part of the Wishbone interface
  output logic [DW-1:0]     control_o,
  output logic [DW-1:0]     output_o,
  output logic [DW-1:0]     events_o,
  output int unsigned       cmd_count_o,
  output logic [DW-1:0]     cmd_last_o
);
  localparam logic [OFF_AW-1:0] O_CONTROL = OFF_AW'('h0);
  localparam logic [OFF_AW-1:0] O_OUTPUT  = OFF_AW'('h1);
  localparam logic [OFF_AW-1:0] O_EVENTS  = OFF_AW'('h2);
  localparam logic [OFF_AW-1:0] O_COMMAND = OFF_AW'('h3);

  logic xfer, mapped, wr;
  assign xfer   = cyc_i && stb_i;
  assign mapped = (adr_i == O_CONTROL) || (adr_i == O_OUTPUT) ||
                  (adr_i == O_EVENTS)  || (adr_i == O_COMMAND);
  assign ack_o  = xfer &&  mapped;
  assign err_o  = xfer && !mapped;
  assign wr     = xfer && mapped && we_i;

  logic [DW-1:0] mask;
  wb_sel_to_mask #(.DW(DW), .GRAN(GRAN)) u_mask (.sel_i(sel_i), .mask_o(mask));

  logic [DW-1:0] control_q, output_q, events_q, cmd_last_q;
  int unsigned   cmd_count_q;

  // A set from hardware and a clear from software can land on the same
  // clock. SET WINS here, because losing an event that genuinely occurred
  // is worse than reporting it twice. That is a LOCAL RTL POLICY — nothing
  // in Wishbone reaches inside a register — and it is written as one
  // expression so the precedence cannot drift.

  always_ff @(posedge clk_i) begin
    if (rst_i) begin
      control_q   <= 32'hA1B2_C3D4;
      output_q    <= 32'h0000_0000;
      events_q    <= 32'h0000_0000;
      cmd_last_q  <= 32'h0000_0000;
      cmd_count_q <= 0;
    end else if (!wr) begin
      events_q <= events_q | event_set_i;
    end else begin
      case (adr_i)
        // ── ordinary read/write: preserve, then replace ──
        O_CONTROL: control_q <= (control_q & ~mask) | (dat_i & mask);
        O_OUTPUT:  output_q  <= (output_q  & ~mask) | (dat_i & mask);

        // ── write-1-clear ──
        // A bit clears only if BOTH its lane participates AND the written
        // bit is 1. Masking first is what makes the second condition apply
        // to the right bits: (dat_i & mask) is the set of ones the transfer
        // actually delivered, and nothing outside the selected lanes can
        // enter it however dat_i is driven.
        O_EVENTS:  events_q <= (events_q & ~(dat_i & mask)) | event_set_i;

        // ── command with a side effect ──
        // The pulse is conditioned on the command lane PARTICIPATING. A
        // command value sitting in dat_i on an unselected lane was never
        // delivered, so it must not fire anything — which is exactly what
        // wb_broken_cmd_bank gets wrong.
        O_COMMAND: begin
          if (sel_i[0]) begin
            cmd_count_q <= cmd_count_q + 1;
            cmd_last_q  <= dat_i & mask;
          end
        end
        default: ;
      endcase
    end
  end

  // Reads return the whole word. RULE 3.65 qualifies DAT_O() with the
  // termination, and SEL_I() says where data "should be present" on a read
  // — it does not require the slave to blank the other lanes. Returning the
  // full word and letting the master take the lanes it asked for is
  // IMPLEMENTATION BEHAVIOUR, permitted rather than required, and Chapter
  // 13.1 says so rather than presenting it as protocol.
  always_comb begin
    dat_o = '0;
    if (xfer && mapped && !we_i) begin
      case (adr_i)
        O_CONTROL: dat_o = control_q;
        O_OUTPUT:  dat_o = output_q;
        O_EVENTS:  dat_o = events_q;
        O_COMMAND: dat_o = cmd_last_q;
        default:   dat_o = '0;
      endcase
    end
  end

  assign control_o   = control_q;
  assign output_o    = output_q;
  assign events_o    = events_q;
  assign cmd_count_o = cmd_count_q;
  assign cmd_last_o  = cmd_last_q;
endmodule

  === SIM G - an ordinary register under partial writes ===
    CONTROL resets to 0xA1B2C3D4. Each row writes the word
    below through the select pattern shown, and the result is
    compared against a lane-walking reference model.

    SEL    DAT          CONTROL      reference    match
    0001   0x11223344   0xa1b2c344   0xa1b2c344   yes
    0100   0x55667788   0xa166c344   0xa166c344   yes
    1010   0x99aabbcc   0x9966bb44   0x9966bb44   yes
    0110   0xdeadbeef   0x99adbe44   0x99adbe44   yes
    1000   0x00000000   0x00adbe44   0x00adbe44   yes
    1111   0xffffffff   0xffffffff   0xffffffff   yes

    writes 6   mismatches 0

    Row 5 writes 0x00000000 through lane 3 and the register
    keeps its other three bytes. Writing zero is a value, not
    an absence - the lane participated and received zero.

  === SIM H - write-1-clear under a select mask ===
    EVENTS is seeded from hardware to 0xFFFFFFFF before each
    row, so every bit is available to be cleared.

    SEL    DAT          EVENTS       reference    match
    0001   0xffffffff   0xffffff00   0xffffff00   yes
    1000   0xffffffff   0x00ffffff   0x00ffffff   yes
    0101   0xffffffff   0xff00ff00   0xff00ff00   yes
    1111   0x0f0f0f0f   0xf0f0f0f0   0xf0f0f0f0   yes
    1111   0x00000000   0xffffffff   0xffffffff   yes

    writes 5   mismatches 0

    Rows 1-3 write all-ones and clear ONLY the selected lanes.
    An unselected lane survives a word of ones, which is the
    whole point: the mask is applied BEFORE the W1C rule, so
    a bit outside the selected lanes was never written at all.
    Row 4 shows the other condition - selected lanes, but only
    the bits set in DAT clear. Row 5 writes zeros and clears
    nothing despite selecting every lane.

// ── THE DEFECT — a command decoder that never looks at SEL ──────────────
// wb_broken_cmd_bank. NOT A REFERENCE DESIGN.
//
// Identical to wb_masked_register_bank except for the COMMAND case, where
// the `sel_i[0]` condition is gone and the stored value is dat_i rather
// than dat_i & mask.
//
// The reasoning behind it is ordinary and almost right: "a write to the
// COMMAND register is a command." It is true that the write happened. What
// it misses is that a write can happen while the command lane takes no part
// in it — a software routine updating a neighbouring byte of the same word
// delivers nothing to lane 0, and this design fires anyway on whatever
// dat_i happens to carry there.
module wb_broken_cmd_bank #(
  parameter int unsigned OFF_AW = 4,
  parameter int unsigned DW     = 32,
  parameter int unsigned GRAN   = 8,
  localparam int unsigned SELW = DW / GRAN
) (
  input  logic              clk_i,
  input  logic              rst_i,
  input  logic              cyc_i,
  input  logic              stb_i,
  input  logic              we_i,
  input  logic [OFF_AW-1:0] adr_i,
  input  logic [SELW-1:0]   sel_i,
  input  logic [DW-1:0]     dat_i,
  input  logic [DW-1:0]     event_set_i,
  output logic [DW-1:0]     dat_o,
  output logic              ack_o,
  output logic              err_o,
  output logic [DW-1:0]     control_o,
  output logic [DW-1:0]     output_o,
  output logic [DW-1:0]     events_o,
  output int unsigned       cmd_count_o,
  output logic [DW-1:0]     cmd_last_o
);
  localparam logic [OFF_AW-1:0] O_CONTROL = OFF_AW'('h0);
  localparam logic [OFF_AW-1:0] O_OUTPUT  = OFF_AW'('h1);
  localparam logic [OFF_AW-1:0] O_EVENTS  = OFF_AW'('h2);
  localparam logic [OFF_AW-1:0] O_COMMAND = OFF_AW'('h3);

  logic xfer, mapped, wr;
  assign xfer   = cyc_i && stb_i;
  assign mapped = (adr_i == O_CONTROL) || (adr_i == O_OUTPUT) ||
                  (adr_i == O_EVENTS)  || (adr_i == O_COMMAND);
  assign ack_o  = xfer &&  mapped;
  assign err_o  = xfer && !mapped;
  assign wr     = xfer && mapped && we_i;

  logic [DW-1:0] mask;
  wb_sel_to_mask #(.DW(DW), .GRAN(GRAN)) u_mask (.sel_i(sel_i), .mask_o(mask));

  logic [DW-1:0] control_q, output_q, events_q, cmd_last_q;
  int unsigned   cmd_count_q;

  always_ff @(posedge clk_i) begin
    if (rst_i) begin
      control_q   <= 32'hA1B2_C3D4;
      output_q    <= 32'h0000_0000;
      events_q    <= 32'h0000_0000;
      cmd_last_q  <= 32'h0000_0000;
      cmd_count_q <= 0;
    end else if (!wr) begin
      events_q <= events_q | event_set_i;
    end else begin
      case (adr_i)
        O_CONTROL: control_q <= (control_q & ~mask) | (dat_i & mask);
        O_OUTPUT:  output_q  <= (output_q  & ~mask) | (dat_i & mask);
        O_EVENTS:  events_q  <= (events_q & ~(dat_i & mask)) | event_set_i;
        // ── THE DEFECT: no sel_i[0] term, and dat_i is taken unmasked. ──
        O_COMMAND: begin
          cmd_count_q <= cmd_count_q + 1;
          cmd_last_q  <= dat_i;
        end
        default: ;
      endcase
    end
  end

  always_comb begin
    dat_o = '0;
    if (xfer && mapped && !we_i) begin
      case (adr_i)
        O_CONTROL: dat_o = control_q;
        O_OUTPUT:  dat_o = output_q;
        O_EVENTS:  dat_o = events_q;
        O_COMMAND: dat_o = cmd_last_q;
        default:   dat_o = '0;
      endcase
    end
  end

  assign control_o   = control_q;
  assign output_o    = output_q;
  assign events_o    = events_q;
  assign cmd_count_o = cmd_count_q;
  assign cmd_last_o  = cmd_last_q;
endmodule

  === SIM I - a command byte that was not selected ===
    COMMAND lives in lane 0. Both designs get the same write:
    a valid command value in DAT, with lane 0 NOT selected -
    which is what a routine updating a neighbouring byte of
    the same word produces.

    SEL    DAT          correct           ignores SEL
                        fires  last       fires  last
    0010   0x00000042   0      0x00000000   1      0x00000042
    0001   0x00000042   1      0x00000042   1      0x00000042

    Row 1: the command value is on the bus and lane 0 takes no
    part. The correct design fires nothing. The design that
    treats 'a write to COMMAND' as the trigger fires 0x42.

    Row 2 selects lane 0 and both fire exactly once. The
    difference is not whether a command can be issued - it is
    whether an unrelated neighbouring write can issue one.

    Note also the 'last' column. The correct design stores
    dat & mask, so it records only the bytes delivered.

  === SIM J - every select pattern, every register type ===
    16 patterns x 3 register behaviours, each against the
    reference model, from a non-trivial starting state.

    ordinary RW mismatches        0
    write-1-clear mismatches      0
    command fired wrongly         0

    cases checked 48   mismatches 0

    Three different meanings for 'this lane participates',
    one mask, and no exceptions across the whole select space.

// ─────────────────────────────────────────────────────────────────────────
// wb_bank_props — what a select pattern promises about the OTHER register
// behaviours. These are all LOCAL: Wishbone does not reach inside a
// register, so every rule below belongs to this bank's datasheet.
// ─────────────────────────────────────────────────────────────────────────
module wb_bank_props #(
  parameter int unsigned DW   = 32,
  parameter int unsigned GRAN = 8,
  localparam int unsigned SELW = DW / GRAN
) (
  input logic            clk_i,
  input logic            rst_i,
  input logic            wr_i,         // committed write to this bank
  input logic [3:0]      adr_i,
  input logic [SELW-1:0] sel_i,
  input logic [DW-1:0]   dat_i,
  input logic [DW-1:0]   events_i,
  input logic [DW-1:0]   event_set_i,
  input int unsigned     cmd_count_i
);
  default disable iff (rst_i);
  localparam logic [3:0] O_EVENTS  = 4'h2;
  localparam logic [3:0] O_COMMAND = 4'h3;

  // P5 — LOCAL REGISTER SEMANTICS.
  // A write-1-clear lane that was not selected cannot clear anything, no
  // matter what the write data carried there. This is the property that
  // fails when a design applies the W1C rule to dat_i before masking it,
  // and SIM H measures it with all-ones data.
  genvar gn;
  generate
    for (gn = 0; gn < SELW; gn++) begin : g_w1c
      property p_w1c_unselected;
        @(posedge clk_i)
          (wr_i && (adr_i == O_EVENTS) && !sel_i[gn] &&
           (event_set_i[gn*GRAN +: GRAN] == '0)) |=>
            (events_i[gn*GRAN +: GRAN] == $past(events_i[gn*GRAN +: GRAN]));
      endproperty
      a_w1c_unselected: assert property (p_w1c_unselected);
    end
  endgenerate

  // P6 — LOCAL REGISTER SEMANTICS.
  // Within a SELECTED lane, a zero in the write data clears nothing. Both
  // conditions are needed, and this is the half that a mask-only
  // implementation would satisfy while getting P5 wrong.
  property p_w1c_zero_preserves;
    @(posedge clk_i)
      (wr_i && (adr_i == O_EVENTS) && (event_set_i == '0)) |=>
        ((events_i & $past(dat_i)) == ($past(events_i) & $past(dat_i) & '0));
  endproperty
  a_w1c_zero_preserves: assert property (p_w1c_zero_preserves);

  // P7 — LOCAL REGISTER SEMANTICS, and the one wb_broken_cmd_bank violates.
  // A side effect requires its lane to participate. A command value present
  // on dat_i in a lane the transfer did not select was never delivered.
  property p_command_requires_select;
    @(posedge clk_i)
      (wr_i && (adr_i == O_COMMAND) && !sel_i[0]) |=>
        (cmd_count_i == $past(cmd_count_i));
  endproperty
  a_command_requires_select: assert property (p_command_requires_select);

  // P8 — LOCAL REGISTER SEMANTICS.
  // A selected command lane fires exactly once per committed write. Not
  // zero, and not more — the repeated-side-effect failure Module 7 measured.
  property p_command_fires_once;
    @(posedge clk_i)
      (wr_i && (adr_i == O_COMMAND) && sel_i[0]) |=>
        (cmd_count_i == $past(cmd_count_i) + 1);
  endproperty
  a_command_fires_once: assert property (p_command_fires_once);
endmodule