Alignment

  byte address  0x0000_1002
        |
        +-- bits 31..2  ->  ADR   = 0x0000_0400      which word
        |
        +-- bits 1..0   ->  offset = 2               where in it
                                |
                                +-- with the size  ->  SEL = 0100

// ─────────────────────────────────────────────────────────────────────────
// wb_byte_address_adapter — software's byte address and operand size become
// a Wishbone word address plus a select pattern.
//
// THREE NUMBERS, KEPT APART. Module 12 insisted on the first two; this
// module adds the third.
//
//   byte_adr_i   what a C pointer holds. Byte units.
//   adr_o        what appears on ADR. WORD units — the organization32
//                figure lists ADR_I/ADR_O(63..02) for a 32-bit port with
//                8-bit granularity, so the low two bits are not on the
//                wires at all (Chapter 4.3).
//   sel_o        which lanes of that one word carry the operand.
//
// The low two bits of the byte address do not vanish. They become sel_o.
// That is the whole content of this module: ADR says WHICH WORD, SEL says
// WHERE IN IT, and the bits that stopped being address became select.
//
// ENDIANNESS. The lane binding SEL[n] <-> DAT[8n+7:8n] is normative
// (RULE 3.100) and fixed. Which BYTE NUMBER of an operand sits on which
// lane is NOT fixed — the same organization32 figure gives BIG and LITTLE
// ENDIAN as two different rows. RULE 2.15 requires a core's datasheet to
// state which it uses.
//
//   LITTLE ENDIAN: byte offset 0 -> lane 0 -> SEL[0]
//   BIG ENDIAN:    byte offset 0 -> lane 3 -> SEL[3]
//
// THIS ADAPTER IS LITTLE ENDIAN, matching the convention Chapter 4.7
// declared for the whole course. That is a SOC CONVENTION, not a Wishbone
// requirement, and LITTLE_ENDIAN can be cleared to get the other one.
//
// ALIGNMENT IS LOCAL POLICY. Nothing in Wishbone forbids a misaligned
// access. What the specification does say (RULE 2.15) is that a datasheet
// states the port's granularity and maximum operand size; whether a given
// operand at a given offset can be carried is then a property of THIS
// system. This adapter declares its policy in ok_o/reason_o and rejects
// nothing silently.
// ─────────────────────────────────────────────────────────────────────────
module wb_byte_address_adapter #(
  parameter int unsigned BYTE_AW       = 32,
  parameter int unsigned DW            = 32,
  parameter int unsigned GRAN          = 8,
  parameter bit          LITTLE_ENDIAN = 1'b1,
  localparam int unsigned SELW  = DW / GRAN,
  localparam int unsigned SHIFT = $clog2(DW / 8),
  localparam int unsigned WAW   = BYTE_AW - SHIFT
) (
  input  logic [BYTE_AW-1:0] byte_adr_i,
  input  logic [2:0]         size_i,     // operand size in BYTES: 1, 2 or 4
  output logic [WAW-1:0]     adr_o,      // WORD address
  output logic [SELW-1:0]    sel_o,
  output logic [1:0]         off_o,      // byte offset within the word
  output logic               ok_o,       // representable in ONE transfer
  output logic [1:0]         reason_o    // 0 ok, 1 bad size, 2 crosses word
);
  initial begin
    if (DW % GRAN != 0)
      $fatal(1, "wb_byte_address_adapter: DW not a multiple of GRAN");
    if (GRAN != 8)
      $fatal(1, "wb_byte_address_adapter: assumes byte granularity");
  end

  localparam int unsigned BPW = DW / 8;          // bytes per bus word

  logic [SHIFT-1:0] off;
  assign off   = byte_adr_i[SHIFT-1:0];
  assign off_o = 2'(off);
  assign adr_o = byte_adr_i[BYTE_AW-1 -: WAW];   // == byte_adr_i >> SHIFT

  // A contiguous run of `size` lanes starting at the byte offset. Built as
  // a run over LANE indices, then flipped if the system is big endian —
  // because the flip is about byte NUMBERING, and doing it in one named
  // place is what keeps it from leaking into the mask expansion.
  logic [SELW-1:0] run_lo;
  always_comb begin
    run_lo = '0;
    for (int unsigned n = 0; n < SELW; n++)
      if ((32'(n) >= 32'(off)) &&
          (32'(n) <  32'(off) + 32'(size_i)))
        run_lo[n] = 1'b1;
  end

  logic [SELW-1:0] run_be;
  always_comb begin
    run_be = '0;
    for (int unsigned n = 0; n < SELW; n++)
      run_be[SELW-1-n] = run_lo[n];
  end

  // Policy, stated once. Size must be a supported operand, and the operand
  // must lie inside one bus word — a byte set that straddles the boundary
  // is not one word's worth of lanes, so no single SEL pattern names it.
  logic size_ok, fits;
  assign size_ok = (size_i == 3'd1) || (size_i == 3'd2) || (size_i == 3'd4);
  assign fits    = (32'(off) + 32'(size_i)) <= 32'(BPW);

  assign ok_o     = size_ok && fits;
  assign reason_o = !size_ok ? 2'd1 : (!fits ? 2'd2 : 2'd0);

  // A rejected request emits no selects. Driving a partial pattern for a
  // request the adapter has refused would invite a caller to use it.
  assign sel_o = !ok_o ? '0 : (LITTLE_ENDIAN ? run_lo : run_be);
endmodule

  === SIM E - a byte address becomes ADR plus SEL ===
    32-bit port, byte granularity. ADR is a WORD address, so
    the two low bits of the byte address are not on the wires
    - they become the byte offset, and the offset picks lanes.
    Little endian: byte offset 0 is lane 0.

    byte adr    size        ADR (word)    off   SEL  classification
    0x00001000  byte        0x00000400    0     0001   one transfer
    0x00001001  byte        0x00000400    1     0010   one transfer
    0x00001002  byte        0x00000400    2     0100   one transfer
    0x00001003  byte        0x00000400    3     1000   one transfer
    0x00001004  byte        0x00000401    0     0001   one transfer

    0x00001000  halfword    0x00000400    0     0011   one transfer
    0x00001002  halfword    0x00000400    2     1100   one transfer

    0x00001000  word        0x00000400    0     1111   one transfer
    0x00001004  word        0x00000401    0     1111   one transfer

    The first five rows walk one byte at a time. The ADR column
    changes only at 0x1004, where the byte address crossed into
    the next word - four byte addresses share one ADR, and SEL
    is what tells them apart.

  --- the same byte addresses, big endian ---

    byte adr    off   SEL little   SEL big
    0x00001000   0    0001         1000
    0x00001001   1    0010         0100
    0x00001002   2    0100         0010
    0x00001003   3    1000         0001

    Same address, same lane wiring, different lane chosen.
    RULE 3.100 fixes SEL(n) to DAT(8n+7..8n) in both columns;
    what moved is which byte NUMBER sits on which lane.
    RULE 2.15 requires a datasheet to say which ordering a
    core uses. This course is little endian throughout.

  === SIM F - operands one bus word cannot carry ===
    a halfword at offset 3 needs bytes 3 and 4. Byte 4 is in
    the NEXT word, and one transfer presents one ADR.

    byte adr    size        ADR (word)    off   SEL  classification
    0x00001003  halfword    0x00000400    3     0000   crosses word
    0x00001001  word        0x00000400    1     0000   crosses word
    0x00001002  word        0x00000400    2     0000   crosses word
    0x00001003  word        0x00000400    3     0000   crosses word
    0x00001000  unsupported 0x00000400    0     0000   bad size

    SEL reads 0000 on every rejected row. The adapter emits no
    lanes for a request it refused, so a caller cannot use a
    partial pattern for an operand that was never representable.

    MISALIGNED AND CROSS-WORD ARE NOT THE SAME TEST:

    0x00001001  halfword    0x00000400    1     0110   one transfer

    A halfword at offset 1 is misaligned by the usual software
    rule - its address is not a multiple of its size - and it
    still fits inside one bus word, so one transfer carries it
    with SEL = 0110. What one transfer cannot represent is a
    byte set spanning TWO words, because a transfer presents
    one ADR. Cross-word is the constraint; alignment is a
    separate convention that this adapter does not enforce.

  --- every offset and size, classified ---

    size       off 0        off 1        off 2        off 3
    byte       single       single       single       single
    halfword   single       single       single       cross-word
    word       single       cross-word   cross-word   cross-word

    8 of the 12 combinations fit in one transfer; 4 span two.

    NOTHING IN WISHBONE FORBIDS THE 4 THAT SPAN. The spec has
    no alignment rule; it requires a datasheet to state the
    port's granularity and maximum operand size (RULE 2.15), and
    leaves what a core accepts to the core. Rejecting them is
    THIS SoC'S POLICY. Splitting them into two transfers would
    be equally conformant, and RECOMMENDATION 3.20 advises the
    low-address half first if a design chooses to split.

    cases probed 15   single transfer 10   crosses word 4   bad size 1

// ─────────────────────────────────────────────────────────────────────────
// wb_adapter_props — the address/lane translation and the alignment policy.
// ─────────────────────────────────────────────────────────────────────────
module wb_adapter_props #(
  parameter int unsigned DW   = 32,
  parameter int unsigned GRAN = 8,
  localparam int unsigned SELW = DW / GRAN
) (
  input logic            clk_i,
  input logic [31:0]     byte_adr_i,
  input logic [2:0]      size_i,
  input logic [29:0]     adr_i,
  input logic [SELW-1:0] sel_i,
  input logic [1:0]      off_i,
  input logic            ok_i
);
  // P9 — SPEC-DERIVED (DESC ADR_O, and the organization32 figure).
  // The word address is the byte address with the granularity bits removed.
  // The figure lists ADR_I/ADR_O(63..02) for a 32-bit byte-granular port,
  // so those two bits are not carried and cannot be recovered from ADR.
  property p_word_address;
    @(posedge clk_i) adr_i == byte_adr_i[31:2];
  endproperty
  a_word_address: assert property (p_word_address);

  // P10 — SPEC-DERIVED, same source.
  // The bits ADR does not carry are exactly the byte offset. Together with
  // P9 this says no information was lost: the address split in two.
  property p_offset_is_low_bits;
    @(posedge clk_i) off_i == byte_adr_i[1:0];
  endproperty
  a_offset_is_low_bits: assert property (p_offset_is_low_bits);

  // P11 — LOCAL SOC POLICY (little endian, declared by this course).
  // For an accepted operand the selected lanes are exactly the run of
  // `size` lanes starting at the byte offset. Under BIG ENDIAN the same
  // adapter produces the mirrored run, which is why this property names
  // its endianness instead of assuming one.
  property p_lane_run;
    @(posedge clk_i) (ok_i) |->
      (sel_i == (SELW'((1 << size_i) - 1) << off_i));
  endproperty
  a_lane_run: assert property (p_lane_run);

  // P12 — LOCAL SOC POLICY.
  // A refused request selects nothing. Wishbone forbids neither misaligned
  // nor cross-word operands; this adapter declines to represent the ones it
  // cannot carry in a single transfer, and emits no partial pattern that a
  // caller might mistake for a usable one.
  property p_rejected_selects_nothing;
    @(posedge clk_i) (!ok_i) |-> (sel_i == '0);
  endproperty
  a_rejected_selects_nothing: assert property (p_rejected_selects_nothing);
endmodule