Block Transfer Cycle

// ─────────────────────────────────────────────────────────────────────────
// wb_block_master — a block cycle controller.
//
// PURPOSE. Hold ONE bus cycle across N transfers. This is Chapter 8.2's
// wb_single_cycle_ctrl with exactly three additions:
//   * a transfer counter
//   * an address that advances
//   * a cycle that does NOT end when a transfer terminates
// Everything else is unchanged, which is the point: a block cycle is a
// small extension of the single-cycle skeleton, not a new protocol.
//
// ── THE CENTRAL CORRECTNESS RULE ─────────────────────────────────────
//   The address and the transfer index advance on TERMINATION, never on
//   elapsed clocks. A transfer may be presented for many cycles (slave
//   waits) and is still ONE transfer — the same counting rule Chapters
//   6.5 and 7.4 established inside slaves, here applied to sequencing.
//
// CYC/STB ARE SEPARATE. This master pauses between transfers (S_GAP), so
// PERMISSION 3.40's precondition does not hold and the two signals cannot
// share a register.
//
// DIRECTION. we_o is a passthrough, constant for the whole block. Nothing
// in the sequencing branches on it — BLOCK READ and BLOCK WRITE are the
// same controller, per Chapter 8.2 Section 1.
//
// Reset: SYNCHRONOUS, ACTIVE HIGH (RULES 2.30, 3.00, 3.20).
// ─────────────────────────────────────────────────────────────────────────
module wb_block_master #(
  parameter int unsigned AW = 30,
  parameter int unsigned DW = 32,
  parameter int unsigned CW = 4        // transfer-count width
) (
  input  logic            clk_i,
  input  logic            rst_i,

  // ── local client side ───────────────────────────────────────────────
  input  logic            req_i,
  input  logic            req_we_i,
  input  logic [AW-1:0]   req_base_i,  // first WORD address
  input  logic [CW-1:0]   req_len_i,   // number of transfers, >= 1
  input  logic [DW-1:0]   req_dat_i,   // write payload (see SIMPLIFICATIONS)
  input  logic            gap_en_i,    // insert a master wait between transfers
  output logic            busy_o,
  output logic            done_o,      // one pulse when the CYCLE completes
  output logic [CW-1:0]   xfers_o,     // transfers completed this cycle
  output logic [DW-1:0]   last_dat_o,  // last read value captured

  // ── Wishbone MASTER interface ───────────────────────────────────────
  output logic            cyc_o,
  output logic            stb_o,
  output logic            we_o,
  output logic [AW-1:0]   adr_o,
  output logic [DW-1:0]   dat_o,
  output logic [DW/8-1:0] sel_o,
  input  logic [DW-1:0]   dat_i,
  input  logic            ack_i,
  input  logic            err_i,
  input  logic            rty_i
);
  // ── STATE ─────────────────────────────────────────────────────────────
  // S_XFER : a transfer is presented          (CYC=1, STB=1)
  // S_GAP  : the cycle is held, nothing asked (CYC=1, STB=0)  <-- NEW
  //          This is the master-side throttle of Section 2, and the state
  //          that could not exist in Chapters 8.1 and 8.2.
  typedef enum logic [1:0] { S_IDLE, S_XFER, S_GAP } state_e;
  state_e state_q;

  logic [AW-1:0] adr_q;
  logic [CW-1:0] left_q;
  logic          we_q;
  logic [DW-1:0] dat_q;
  logic          gap_q;

  // ── THE SEPARATION ────────────────────────────────────────────────────
  // cyc_o covers BOTH active states; stb_o covers only S_XFER.
  assign cyc_o = (state_q == S_XFER) || (state_q == S_GAP);
  assign stb_o = (state_q == S_XFER);
  assign we_o  = we_q;
  assign adr_o = adr_q;
  assign dat_o = dat_q;
  assign sel_o = '1;                   // full-word transfers; see Module 13
  assign busy_o = (state_q != S_IDLE);

  logic terminated;
  assign terminated = ack_i | err_i | rty_i;

  always_ff @(posedge clk_i) begin
    if (rst_i) begin
      state_q    <= S_IDLE;            // RULE 3.20 via the encoding
      adr_q      <= '0;
      left_q     <= '0;
      we_q       <= 1'b0;
      dat_q      <= '0;
      gap_q      <= 1'b0;
      done_o     <= 1'b0;
      xfers_o    <= '0;
      last_dat_o <= '0;
    end else begin
      done_o <= 1'b0;

      unique case (state_q)
        S_IDLE: begin
          if (req_i && (req_len_i != '0)) begin
            // ── CYCLE START ─────────────────────────────────────────────
            // Once per block, not once per transfer.
            state_q <= S_XFER;
            adr_q   <= req_base_i;
            left_q  <= req_len_i;
            we_q    <= req_we_i;
            dat_q   <= req_dat_i;
            gap_q   <= gap_en_i;
            xfers_o <= '0;
          end
        end

        S_XFER: begin
          // ── TRANSFER END ────────────────────────────────────────────
          // Everything here is gated on `terminated`. Nothing advances on
          // elapsed clocks — that is the bug wb_block_master_fastadv has.
          if (terminated) begin
            if (ack_i && !we_q) last_dat_o <= dat_i;   // Chapter 6.3's window
            xfers_o <= xfers_o + CW'(1);

            if (left_q == CW'(1)) begin
              // ── CYCLE END ─────────────────────────────────────────────
              // The LAST transfer's termination is also the cycle's end,
              // so CYC_O and STB_O negate together — which is how a block
              // cycle ends in Classic, there being no last-transfer flag.
              state_q <= S_IDLE;
              done_o  <= 1'b1;
            end else begin
              // ── NEXT TRANSFER ─────────────────────────────────────────
              // Advance ONLY here. The address moves because a transfer
              // COMPLETED, not because a clock passed.
              left_q  <= left_q - CW'(1);
              adr_q   <= adr_q + AW'(1);
              // Written as if/else rather than a ternary: assigning an enum
              // from a conditional expression needs an explicit cast, and
              // Icarus rejects the bare form (the portability wart recorded
              // in Chapter 4.3).
              if (gap_q) state_q <= S_GAP;
              else       state_q <= S_XFER;
            end
          end
        end

        S_GAP: begin
          // The cycle is held with nothing presented. A slave sees CYC_I
          // asserted and STB_I negated: RULE 3.35 forbids it to terminate
          // and it simply waits. One cycle here; a real master might stay
          // until its client supplies the next word.
          state_q <= S_XFER;
        end

        default: state_q <= S_IDLE;
      endcase
    end
  end
endmodule

// ─────────────────────────────────────────────────────────────────────────
// wb_window_slave — four sequential words, so a block has a target.
//
// PURPOSE. Give the running peripheral a small run of addresses. It is a
// register file, not a memory controller — four words, no latency model,
// no burst awareness.
//
// NOTE WHAT IS ABSENT: this slave has NO knowledge of block cycles. It
// answers each qualified transfer on its own terms. That is Section 1's
// claim in executable form — a correct single-transfer slave already
// supports blocks, provided it gates on CYC_I & STB_I per RULE 3.30.
//
// Reset: SYNCHRONOUS, ACTIVE HIGH (RULES 2.30, 3.00).
// ─────────────────────────────────────────────────────────────────────────
module wb_window_slave #(
  parameter int unsigned OFF_AW = 4,
  parameter int unsigned DW     = 32,
  parameter int unsigned LAT    = 0     // wait states, for SIM D
) (
  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 [DW-1:0]     dat_i,
  input  logic [DW/8-1:0]   sel_i,
  output logic [DW-1:0]     dat_o,
  output logic              ack_o,
  output logic              err_o,
  // observable for QA
  output logic [DW-1:0]     w0_o,
  output logic [DW-1:0]     w1_o,
  output logic [DW-1:0]     w2_o,
  output logic [DW-1:0]     w3_o
);
  localparam int unsigned NL = DW/8;
  localparam logic [OFF_AW-1:0] W_BASE = 4'd12;   // words 12..15

  logic [DW-1:0] win_q [4];
  assign w0_o = win_q[0];
  assign w1_o = win_q[1];
  assign w2_o = win_q[2];
  assign w3_o = win_q[3];

  logic xfer;
  assign xfer = cyc_i & stb_i;                    // RULES 3.30 & 3.35

  logic in_window;
  assign in_window = (adr_i >= W_BASE) && (adr_i <= (W_BASE + 4'd3));

  logic [1:0] idx;
  assign idx = adr_i[1:0];                        // words 12..15 -> 0..3

  // ── LATENCY, only so SIM D can delay one transfer ──────────────────────
  // `ready` is declared and assigned before the block that uses it.
  logic [7:0] waited_q;
  logic       ready;
  assign ready = (waited_q >= 8'(LAT));

  always_ff @(posedge clk_i) begin
    if (rst_i)       waited_q <= '0;
    else if (!xfer)  waited_q <= '0;
    else if (!ready) waited_q <= waited_q + 8'd1;
    else             waited_q <= '0;
  end

  assign err_o = xfer & ready & ~in_window;
  assign ack_o = xfer & ready &  in_window;

  logic commit;
  assign commit = xfer & we_i & ack_o;            // Module 7's commit policy

  always_ff @(posedge clk_i) begin
    if (rst_i) begin
      for (int unsigned i = 0; i < 4; i++) win_q[i] <= '0;
    end else if (commit) begin
      for (int unsigned n = 0; n < NL; n++)
        if (sel_i[n]) win_q[idx][n*8 +: 8] <= dat_i[n*8 +: 8];
    end
  end

  always_comb begin
    dat_o = '0;                                   // RULE 3.65
    if (xfer && !we_i && ack_o) dat_o = win_q[idx];
  end
endmodule

// ─────────────────────────────────────────────────────────────────────────
// wb_block_master_fastadv — THE EARLY-ADVANCE BUG, isolated.
//
// NOT A REFERENCE DESIGN. Identical to wb_block_master except that the
// address and the counter advance on every clock the transfer is
// presented, rather than on termination:
//
//     if (terminated) ...        becomes      unconditional advance
//
// Against a zero-wait-state slave every transfer terminates in the cycle
// it is presented, so the two masters are INDISTINGUISHABLE. Introduce one
// wait state and the address runs ahead of the transfers.
// ─────────────────────────────────────────────────────────────────────────
module wb_block_master_fastadv #(
  parameter int unsigned AW = 30,
  parameter int unsigned DW = 32,
  parameter int unsigned CW = 4
) (
  input  logic            clk_i,
  input  logic            rst_i,
  input  logic            req_i,
  input  logic            req_we_i,
  input  logic [AW-1:0]   req_base_i,
  input  logic [CW-1:0]   req_len_i,
  input  logic [DW-1:0]   req_dat_i,
  output logic            busy_o,
  output logic            done_o,
  output logic [CW-1:0]   xfers_o,

  output logic            cyc_o,
  output logic            stb_o,
  output logic            we_o,
  output logic [AW-1:0]   adr_o,
  output logic [DW-1:0]   dat_o,
  output logic [DW/8-1:0] sel_o,
  input  logic [DW-1:0]   dat_i,
  input  logic            ack_i,
  input  logic            err_i,
  input  logic            rty_i
);
  logic          active_q, we_q;
  logic [AW-1:0] adr_q;
  logic [CW-1:0] left_q;
  logic [DW-1:0] dat_q;

  assign cyc_o  = active_q;
  assign stb_o  = active_q;
  assign we_o   = we_q;
  assign adr_o  = adr_q;
  assign dat_o  = dat_q;
  assign sel_o  = '1;
  assign busy_o = active_q;

  always_ff @(posedge clk_i) begin
    if (rst_i) begin
      active_q <= 1'b0; adr_q <= '0; left_q <= '0; we_q <= 1'b0;
      dat_q <= '0; done_o <= 1'b0; xfers_o <= '0;
    end else begin
      done_o <= 1'b0;
      if (!active_q) begin
        if (req_i && (req_len_i != '0)) begin
          active_q <= 1'b1; adr_q <= req_base_i; left_q <= req_len_i;
          we_q <= req_we_i; dat_q <= req_dat_i; xfers_o <= '0;
        end
      end else begin
        if (ack_i || err_i || rty_i) xfers_o <= xfers_o + CW'(1);
        // ── THE BUG: advance every clock, regardless of termination ────
        if (left_q == CW'(1)) begin
          active_q <= 1'b0; done_o <= 1'b1;
        end else begin
          left_q <= left_q - CW'(1);
          adr_q  <= adr_q + AW'(1);
        end
      end
    end
  end
endmodule

  === SIM C - block, immediate ACK ===
    bus cycles begun        1
    transfers completed     4
    reads / writes          4 / 0
    wait cycles             0
    gaps (CYC & !STB)       0
    clocks with CYC high    4
    addresses presented     0xc 0xd 0xe 0xf
    done pulses             1

  === SIM D - block with waits and a master gap ===
    bus cycles begun        1
    transfers completed     4
    wait cycles             4
    gaps (CYC & !STB)       3
    clocks with CYC high    11
    addresses presented     0xc 0xd 0xe 0xf
    address changes while a transfer was outstanding   0
    done pulses             1

  === SIM E - early address advance (1 wait state) ===
    correct master   addresses presented   0xc 0xd 0xe 0xf
                     transfers completed   4
                     addresses acknowledged 0xc 0xd 0xe 0xf
    fast-advance     addresses presented   0xc 0xd 0xe 0xf
                     transfers completed   2
                     address changes while outstanding   2
                     addresses acknowledged 0xd 0xf

// ─────────────────────────────────────────────────────────────────────────
// wb_block_checker — block-cycle properties.
//
// P1 and P2 are SPECIFICATION (RULES 3.25, 3.60). P3 and P4 are LOCAL
// DESIGN POLICY describing THIS master's sequencing — the specification
// says nothing about how a block master computes its addresses, so nothing
// here can be a Wishbone rule.
//
// NOTE what is ABSENT: Chapter 8.1's P3 ("the cycle ends with its
// transfer"). A block master violates it by design, and this checker
// REPLACES it with P4 rather than simply dropping it.
// ─────────────────────────────────────────────────────────────────────────
module wb_block_checker #(
  parameter int unsigned AW = 30,
  parameter int unsigned CW = 4
) (
  input logic          clk_i,
  input logic          rst_i,
  input logic          cyc_o,
  input logic          stb_o,
  input logic [AW-1:0] adr_o,
  input logic          ack_i,
  input logic          err_i,
  input logic          rty_i,
  // white-box
  input logic [CW-1:0] left_q,
  input logic [CW-1:0] xfers_q,
  input logic          done_o
);
  default disable iff (rst_i);

  logic terminated;
  assign terminated = ack_i | err_i | rty_i;

  // P1 — SPECIFICATION (RULE 3.25). A strobe never exists outside a cycle.
  //      Unchanged from Chapters 8.1 and 8.2: this rule does not care how
  //      many transfers the cycle contains.
  property p_stb_inside_cyc;
    @(posedge clk_i) stb_o |-> cyc_o;
  endproperty
  a_stb_inside_cyc : assert property (p_stb_inside_cyc)
    else $error("RULE 3.25: STB_O asserted outside a bus cycle");

  // P2 — SPECIFICATION (RULE 3.60). The address is stable while its
  //      transfer is outstanding. This is what the fast-advance master
  //      violates, and it fires on the FIRST early advance rather than
  //      when the address sequence is noticed to be wrong.
  property p_addr_stable_while_outstanding;
    @(posedge clk_i) (cyc_o && stb_o && !terminated) |=> $stable(adr_o);
  endproperty
  a_addr_stable_while_outstanding :
    assert property (p_addr_stable_while_outstanding)
    else $error("RULE 3.60: ADR_O moved while a transfer was outstanding");

  // P3 — LOCAL POLICY. The transfer index advances ONLY on a termination.
  //      The sequencing form of the counting rule Chapters 6.5 and 7.4
  //      established for side effects.
  property p_index_advances_on_termination;
    @(posedge clk_i) $changed(xfers_q) |-> $past(cyc_o && stb_o && terminated);
  endproperty
  a_index_advances_on_termination :
    assert property (p_index_advances_on_termination)
    else $error("LOCAL: transfer index advanced without a termination");

  // P4 — LOCAL POLICY, REPLACING Chapter 8.1's P3. The cycle ends only
  //      when the LAST transfer terminates — not when any transfer does.
  //      This is the block-cycle form of "the cycle ends with its work".
  property p_cycle_ends_only_at_last;
    @(posedge clk_i) ($fell(cyc_o)) |-> $past(terminated && (left_q == CW'(1)));
  endproperty
  a_cycle_ends_only_at_last : assert property (p_cycle_ends_only_at_last)
    else $error("LOCAL: cycle ended before the last transfer");
endmodule