ADR_O

// ─────────────────────────────────────────────────────────────────────────
// wb_adr_path — the three places a Wishbone address is handled, in one file
// so the transformation is visible.
//
//   wb_adr_master   drives a STABLE, QUALIFIED address        (RULE 3.60)
//   wb_adr_decode   turns a system address into select+offset (Chapter 3.5)
//   wb_adr_slave    interprets the LOCAL offset only          (Chapter 3.4)
//
// WORD-ADDRESSED PORT. Unlike Module 3's simplification, the master here
// presents a WORD address — the specification's ADR_O(n..2) form for a
// 32-bit port with byte granularity. Byte selection is SEL_O's job
// (Chapter 4.7), so the two low bits of a byte pointer do not appear.
//
// Reset: SYNCHRONOUS, ACTIVE HIGH (RULES 2.30, 3.00).
// ─────────────────────────────────────────────────────────────────────────
module wb_adr_master #(
  parameter int unsigned BYTE_AW = 32,          // byte-address width
  parameter int unsigned DW      = 32
) (
  input  logic                 clk_i,
  input  logic                 rst_i,

  input  logic                 go_i,
  input  logic [BYTE_AW-1:0]   byte_adr_i,      // ordinary pointer value

  output logic                 cyc_o,
  output logic                 stb_o,
  // The WORD address: the low $clog2(DW/8) bits of the byte pointer are
  // not carried. For DW=32 this is ADR_O(31..2) presented as [29:0].
  output logic [BYTE_AW-1-$clog2(DW/8):0] adr_o,
  input  logic                 ack_i,
  input  logic                 err_i,
  input  logic                 rty_i
);
  localparam int unsigned SHIFT = $clog2(DW / 8);   // 2 for a 32-bit port

  // Elaboration check: a byte-granular port must have a byte-multiple width.
  initial begin
    if ((DW % 8) != 0)
      $fatal(1, "wb_adr_master: DW=%0d is not a multiple of 8", DW);
  end

  logic active_q;
  logic [BYTE_AW-1-SHIFT:0] adr_q;

  // The bus is driven from the LATCHED copy, never from byte_adr_i. That is
  // what makes RULE 3.60's stability obligation structural rather than a
  // rule the client must remember (Chapter 3.3).
  assign cyc_o = active_q;
  assign stb_o = active_q;
  assign adr_o = adr_q;

  always_ff @(posedge clk_i) begin
    if (rst_i) begin
      active_q <= 1'b0;                          // RULE 3.20
      adr_q    <= '0;
    end else if (!active_q) begin
      if (go_i) begin
        // Drop the byte-select bits: they are SEL_O's information.
        adr_q    <= byte_adr_i[BYTE_AW-1:SHIFT];
        active_q <= 1'b1;
      end
    end else if (ack_i || err_i || rty_i) begin
      active_q <= 1'b0;
    end
  end
endmodule

// ─────────────────────────────────────────────────────────────────────────
// wb_adr_decode — system WORD address → one-hot select + local WORD offset.
//
// Regions are expressed in BYTES in the parameters, because that is how an
// address map is written and read, and converted to word terms internally.
// Keeping the parameter in the units of the document it comes from is a
// small thing that prevents a whole class of factor-of-four errors.
// ─────────────────────────────────────────────────────────────────────────
module wb_adr_decode #(
  parameter int unsigned BYTE_AW = 32,
  parameter int unsigned DW      = 32,
  parameter int unsigned NS      = 3,
  parameter logic [NS*32-1:0] BASE_FLAT =
      { 32'h4000_2000, 32'h4000_1000, 32'h4000_0000 },
  parameter logic [NS*32-1:0] SIZE_FLAT =
      { 32'h0000_1000, 32'h0000_1000, 32'h0000_1000 }
) (
  input  logic [BYTE_AW-1-$clog2(DW/8):0] adr_i,      // system WORD address
  output logic [NS-1:0]                   sel_o,      // one-hot
  output logic [BYTE_AW-1-$clog2(DW/8):0] offset_o,   // local WORD offset
  output logic                            unmapped_o
);
  localparam int unsigned SHIFT = $clog2(DW / 8);
  localparam int unsigned WAW   = BYTE_AW - SHIFT;

  function automatic logic [31:0] base_of(input int unsigned i);
    return BASE_FLAT[i*32 +: 32];
  endfunction
  function automatic logic [31:0] size_of(input int unsigned i);
    return SIZE_FLAT[i*32 +: 32];
  endfunction
  // The same two values expressed in WORD units. Converting here, once and
  // in a named place, is what keeps byte-valued parameters from being
  // compared against a word address by accident.
  function automatic logic [WAW-1:0] wbase_of(input int unsigned i);
    return WAW'(base_of(i) >> SHIFT);
  endfunction
  function automatic logic [WAW-1:0] wmask_of(input int unsigned i);
    return WAW'((size_of(i) - 32'd1) >> SHIFT);
  endfunction

  initial begin
    for (int unsigned i = 0; i < NS; i++) begin
      if (size_of(i) != (32'd1 << $clog2(size_of(i))))
        $fatal(1, "wb_adr_decode: region %0d size %0h not a power of two",
               i, size_of(i));
      if ((base_of(i) & (size_of(i) - 32'd1)) != 32'd0)
        $fatal(1, "wb_adr_decode: region %0d base %0h not naturally aligned",
               i, base_of(i));
      // A region smaller than one bus word cannot be addressed at all.
      if (size_of(i) < 32'(DW / 8))
        $fatal(1, "wb_adr_decode: region %0d size %0h is smaller than one word",
               i, size_of(i));
      for (int unsigned j = i + 1; j < NS; j++)
        if ((base_of(i) < base_of(j) + size_of(j)) &&
            (base_of(j) < base_of(i) + size_of(i)))
          $fatal(1, "wb_adr_decode: regions %0d and %0d overlap", i, j);
    end
  end

  logic [NS-1:0] hit;
  always_comb begin
    // Compare in WORD terms: both sides of the comparison come from the
    // word-valued helpers, so the units can never silently disagree.
    for (int unsigned i = 0; i < NS; i++)
      hit[i] = ((adr_i & ~wmask_of(i)) == wbase_of(i));
  end

  assign unmapped_o = ~(|hit);
  assign sel_o      = hit;

  always_comb begin
    offset_o = adr_i;                       // unmapped passes through
    // Priority-free-safe: at most one hit[i] can be set, which the
    // elaboration overlap check above guarantees.
    for (int unsigned i = 0; i < NS; i++)
      if (hit[i]) offset_o = adr_i & wmask_of(i);
  end
endmodule

// ─────────────────────────────────────────────────────────────────────────
// wb_adr_slave — interprets a LOCAL WORD offset and nothing else.
//
// Note what is absent: no base address, no comparison against a system
// address, no knowledge that other slaves exist. That absence is what lets
// this design be instantiated three times (Chapter 3.6).
// ─────────────────────────────────────────────────────────────────────────
module wb_adr_slave #(
  parameter int unsigned OFF_AW = 10,      // local WORD-offset width
  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 [OFF_AW-1:0]   adr_i,       // LOCAL WORD offset
  input  logic [DW-1:0]       dat_i,
  output logic [DW-1:0]       dat_o,
  output logic                ack_o,
  output logic                err_o
);
  // Register offsets in WORD units. The documented byte offsets 0x00, 0x04,
  // 0x08 become word offsets 0, 1, 2 — the factor of four that the missing
  // low address bits account for.
  localparam logic [OFF_AW-1:0] W_CTRL   = 'd0;    // byte 0x00
  localparam logic [OFF_AW-1:0] W_STATUS = 'd1;    // byte 0x04
  localparam logic [OFF_AW-1:0] W_DATA   = 'd2;    // byte 0x08

  logic [DW-1:0] ctrl_q, data_q;

  logic xfer;
  assign xfer = cyc_i & stb_i;              // RULES 3.30 & 3.35, see Chapter 4.8

  logic legal;
  always_comb begin
    unique case (adr_i)
      W_CTRL, W_STATUS, W_DATA: legal = 1'b1;
      default:                  legal = 1'b0;
    endcase
  end

  assign err_o = xfer & ~legal;
  assign ack_o = xfer & legal;

  always_ff @(posedge clk_i) begin
    if (rst_i) begin
      ctrl_q <= '0;
      data_q <= '0;
    end else if (xfer && we_i && legal) begin
      unique case (adr_i)
        W_CTRL: ctrl_q <= dat_i;
        W_DATA: data_q <= dat_i;
        default: ;                          // W_STATUS is read-only
      endcase
    end
  end

  always_comb begin
    dat_o = '0;
    if (xfer && !we_i && legal) begin
      unique case (adr_i)
        W_CTRL:   dat_o = ctrl_q;
        W_STATUS: dat_o = {{(DW-1){1'b0}}, 1'b1};
        W_DATA:   dat_o = data_q;
        default:  dat_o = '0;
      endcase
    end
  end
endmodule

// ─────────────────────────────────────────────────────────────────────────
// wb_adr_checker — address-path properties.
//
// P1 and P2 are SPECIFICATION requirements derived from RULE 3.60.
// P3 is a LOCAL DESIGN POLICY of this module's decoder and is labelled.
// ─────────────────────────────────────────────────────────────────────────
module wb_adr_checker #(
  parameter int unsigned AW = 30,
  parameter int unsigned NS = 3
) (
  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,
  input logic [NS-1:0]  dec_sel,
  input logic           dec_unmapped
);
  default disable iff (rst_i);

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

  // P1 — SPECIFICATION (RULE 3.60, as stability). While a transfer is
  //      presented and not yet terminated, the qualified address must not
  //      move. This is the property that separates a master driven from a
  //      register from one driven from its client's live inputs.
  property p_adr_stable_while_presented;
    @(posedge clk_i) (stb_o && !terminated) |=> $stable(adr_o);
  endproperty
  a_adr_stable : assert property (p_adr_stable_while_presented)
    else $error("RULE 3.60: ADR_O moved while the transfer was outstanding");

  // P2 — SPECIFICATION (RULE 3.25, the cheap half). A strobe without a
  //      cycle means the address is being qualified outside a bus cycle.
  property p_stb_implies_cyc;
    @(posedge clk_i) stb_o |-> cyc_o;
  endproperty
  a_stb_implies_cyc : assert property (p_stb_implies_cyc)
    else $error("RULE 3.25: STB_O asserted without CYC_O");

  // P3 — LOCAL POLICY, not a Wishbone rule. This decoder is built so that
  //      at most one region matches and `unmapped` is its complement. The
  //      SPECIFICATION does not prescribe a decode structure at all
  //      (Chapter 3.5) — an INTERCON is defined by its job, so this is a
  //      claim about THIS fabric and must not be bound to another one.
  property p_decode_onehot0;
    @(posedge clk_i) $onehot0(dec_sel);
  endproperty
  a_decode_onehot0 : assert property (p_decode_onehot0)
    else $error("local policy: two regions matched one address");

  property p_unmapped_complement;
    @(posedge clk_i) dec_unmapped == (dec_sel == '0);
  endproperty
  a_unmapped_complement : assert property (p_unmapped_complement)
    else $error("local policy: unmapped disagrees with the select vector");
endmodule