ERR_I

// ─────────────────────────────────────────────────────────────────────────
// wb_err_slave — a slave whose error conditions are enumerated explicitly.
//
// The structure is the point: every error condition is a named term, err_o
// is their OR, and the write path is gated on their NOR. That makes the
// Section 2 obligation — an errored transfer changes nothing — structural
// rather than something a reviewer has to verify case by case.
//
// EVERY condition below is a DESIGN DECISION, not a specification rule.
// Documenting them is RULE 2.15's requirement, which is why they are
// enumerated as named signals rather than folded into one expression.
//
// Reset: SYNCHRONOUS, ACTIVE HIGH (RULES 2.30, 3.00).
// ─────────────────────────────────────────────────────────────────────────
module wb_err_slave #(
  parameter int unsigned OFF_AW = 4,
  parameter int unsigned DW     = 32
) (
  input  logic                  clk_i,
  input  logic                  rst_i,
  input  logic                  cyc_i,
  input  logic                  stb_i,
  input  logic                  we_i,
  input  logic [(DW/8)-1:0]     sel_i,
  input  logic [OFF_AW-1:0]     adr_i,
  input  logic [DW-1:0]         dat_i,
  output logic [DW-1:0]         dat_o,
  output logic                  ack_o,
  output logic                  err_o,
  output logic [DW-1:0]         ctrl_o,
  output logic [2:0]            errcode_o      // LOCAL diagnostic, not WB
);
  localparam logic [OFF_AW-1:0] W_CTRL   = 'd0;   // read / write
  localparam logic [OFF_AW-1:0] W_STATUS = 'd1;   // read-only
  localparam logic [OFF_AW-1:0] W_CMD    = 'd2;   // write-only

  logic [DW-1:0] ctrl_q;
  assign ctrl_o = ctrl_q;

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

  // ── ERROR CONDITIONS, ONE NAMED TERM EACH ──────────────────────────────
  logic e_unmapped, e_ro_write, e_wo_read, e_empty_sel;

  always_comb begin
    unique case (adr_i)
      W_CTRL, W_STATUS, W_CMD: e_unmapped = 1'b0;
      default:                 e_unmapped = 1'b1;
    endcase
  end
  assign e_ro_write  =  we_i & (adr_i == W_STATUS);
  assign e_wo_read   = ~we_i & (adr_i == W_CMD);
  assign e_empty_sel = (sel_i == '0);

  logic any_err;
  assign any_err = e_unmapped | e_ro_write | e_wo_read | e_empty_sel;

  // RULE 3.35: both terminations are generated from the qualified transfer.
  // RULE 3.45: mutually exclusive by construction — ack_o carries ~err_o.
  assign err_o = xfer &  any_err;
  assign ack_o = xfer & ~any_err;

  // ── THE SECTION 2 OBLIGATION, MADE STRUCTURAL ──────────────────────────
  // write_ok is the NOR of the same terms err_o is the OR of. They cannot
  // disagree, so there is no reachable state in which this slave reports a
  // failure and performs the operation.
  logic write_ok;
  assign write_ok = xfer & we_i & ~any_err;

  always_ff @(posedge clk_i) begin
    if (rst_i) begin
      ctrl_q <= '0;
    end else if (write_ok && (adr_i == W_CTRL)) begin
      for (int unsigned n = 0; n < DW/8; n++) begin
        if (sel_i[n]) ctrl_q[n*8 +: 8] <= dat_i[n*8 +: 8];
      end
    end
  end

  // ── DIAGNOSTIC CODE ────────────────────────────────────────────────────
  // NOT a Wishbone signal. Wishbone's ERR_O carries no reason code — the
  // master learns only that the transfer failed. Exposing a reason on a
  // side-band output (or in a readable status register) is a common and
  // useful extension, and calling it out as non-standard here is the
  // point: a reader must not infer that Wishbone provides error codes.
  always_comb begin
    if      (!xfer)       errcode_o = 3'd0;
    else if (e_unmapped)  errcode_o = 3'd1;
    else if (e_ro_write)  errcode_o = 3'd2;
    else if (e_wo_read)   errcode_o = 3'd3;
    else if (e_empty_sel) errcode_o = 3'd4;
    else                  errcode_o = 3'd0;
  end

  always_comb begin
    dat_o = '0;                                   // RULE 3.65
    if (xfer && !we_i && ack_o) begin
      unique case (adr_i)
        W_CTRL:   dat_o = ctrl_q;
        W_STATUS: dat_o = {{(DW-8){1'b0}}, 8'hA5};
        default:  dat_o = '0;
      endcase
    end
  end
endmodule

// ─────────────────────────────────────────────────────────────────────────
// wb_err_master — a master with an EXPLICIT, DOCUMENTED error policy.
//
// POLICY (this is what RULE 2.15 would require in the datasheet):
//   * ERR_I abandons the current cycle immediately.
//   * The failing address is latched and reported.
//   * Read data from an errored transfer is NEVER captured.
//   * An errored transfer is NEVER retried by this master; the decision
//     to retry belongs to the client, which knows whether anything has
//     changed that would make a second attempt different.
//   * On a multi-transfer block, transfers already completed STAY
//     completed and the count of them is reported.
//
// None of the above is required by Wishbone. All of it is required to be
// WRITTEN DOWN by RULE 2.15, which is the reason for this comment block.
// ─────────────────────────────────────────────────────────────────────────
module wb_err_master #(
  parameter int unsigned AW = 30,
  parameter int unsigned DW = 32,
  parameter int unsigned CW = 8
) (
  input  logic          clk_i,
  input  logic          rst_i,

  input  logic          go_i,
  input  logic [AW-1:0] base_i,
  input  logic [CW-1:0] count_i,
  output logic          done_o,
  output logic          failed_o,
  output logic [AW-1:0] fail_adr_o,
  output logic [CW-1:0] completed_o,
  output logic [DW-1:0] rdat_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,
  input  logic [DW-1:0] dat_i,
  input  logic          ack_i,
  input  logic          err_i,
  input  logic          rty_i
);
  logic          active_q;
  logic [AW-1:0] adr_q;
  logic [CW-1:0] left_q;

  assign cyc_o = active_q;
  assign stb_o = active_q;
  assign we_o  = 1'b0;
  assign adr_o = adr_q;
  assign dat_o = '0;

  always_ff @(posedge clk_i) begin
    if (rst_i) begin
      active_q    <= 1'b0;                     // RULE 3.20
      adr_q       <= '0;
      left_q      <= '0;
      rdat_o      <= '0;
      done_o      <= 1'b0;
      failed_o    <= 1'b0;
      fail_adr_o  <= '0;
      completed_o <= '0;
    end else begin
      done_o <= 1'b0;

      if (!active_q) begin
        if (go_i && (count_i != '0)) begin
          active_q    <= 1'b1;
          adr_q       <= base_i;
          left_q      <= count_i;
          completed_o <= '0;
          failed_o    <= 1'b0;
        end
      end else if (err_i) begin
        // ── ERROR POLICY, EXECUTED ───────────────────────────────────────
        // Abandon. Latch the failing address so the client can report
        // something actionable — a bare "it failed" is not diagnosable.
        // rdat_o is deliberately NOT written: there is no defined read
        // value on an errored transfer (Chapter 4.5).
        active_q   <= 1'b0;
        done_o     <= 1'b1;
        failed_o   <= 1'b1;
        fail_adr_o <= adr_q;
      end else if (rty_i) begin
        // Distinct from an error, and handled distinctly. Chapter 4.12.
        active_q <= 1'b0;
        done_o   <= 1'b1;
      end else if (ack_i) begin
        rdat_o      <= dat_i;
        completed_o <= completed_o + CW'(1);
        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

// ─────────────────────────────────────────────────────────────────────────
// wb_err_checker — error properties.
//
// P1 is SPECIFICATION (RULES 3.35, 3.45). P2 and P3 are DESIGN OBLIGATIONS
// that follow from what the termination communicates rather than from a
// numbered rule — the specification does not state "an errored transfer
// changes nothing", because it does not define what an error MEANS. They
// are asserted here as this system's documented contract, which is exactly
// the material RULE 2.15 requires in the datasheet.
// ─────────────────────────────────────────────────────────────────────────
module wb_err_checker #(
  parameter int unsigned DW = 32
) (
  input logic          clk_i,
  input logic          rst_i,
  input logic          cyc_i,
  input logic          stb_i,
  input logic          ack_o,
  input logic          err_o,
  input logic          rty_o,
  input logic [DW-1:0] ctrl_q,
  input logic [DW-1:0] m_rdat_q
);
  default disable iff (rst_i);

  // P1 — SPECIFICATION. RULE 3.35: generated from the qualified transfer.
  //      RULE 3.45: never more than one termination at a time.
  property p_err_legal;
    @(posedge clk_i) err_o |-> ((cyc_i && stb_i) && !ack_o && !rty_o);
  endproperty
  a_err_legal : assert property (p_err_legal)
    else $error("ERR_O asserted unqualified or alongside another termination");

  // P2 — DESIGN OBLIGATION. An errored transfer changes no state. This is
  //      the property worth having above all others in this chapter: the
  //      failure it catches leaves software with a correct error report
  //      and a silently modified device.
  property p_err_changes_nothing;
    @(posedge clk_i) $changed(ctrl_q) |-> !$past(err_o);
  endproperty
  a_err_changes_nothing : assert property (p_err_changes_nothing)
    else $error("slave state changed on a transfer terminated with ERR_O");

  // P3 — DESIGN OBLIGATION, master side. No read data is captured from an
  //      errored transfer. There is no defined value to capture.
  property p_no_capture_on_err;
    @(posedge clk_i) $changed(m_rdat_q) |-> !$past(err_o);
  endproperty
  a_no_capture_on_err : assert property (p_no_capture_on_err)
    else $error("master captured read data from an errored transfer");

  // P4 — DESIGN OBLIGATION. This master does not retry an error. Stated as
  //      a property because the alternative — an error retry loop — is a
  //      LIVENESS failure that no signal-level rule forbids.
  property p_err_ends_the_cycle;
    @(posedge clk_i) (cyc_i && stb_i && err_o) |=> !stb_i;
  endproperty
  a_err_ends_the_cycle : assert property (p_err_ends_the_cycle)
    else $error("strobe still asserted the cycle after ERR_O");
endmodule