Decoder Logic

// ─────────────────────────────────────────────────────────────────────────
// wb_mask_decode — the same map, decoded by prefix comparison.
//
//   sel[i] = (a & ~wmask[i]) == wbase[i]
//
// Cheaper than a range compare: it is a bitwise AND and an equality, with
// no magnitude comparator and no borrow chain. On the canonical map it
// produces results IDENTICAL to wb_range_decode — Chapter 12.3 sweeps the
// space and proves it rather than asserting it.
//
// IT IS NOT A GENERAL SUBSTITUTE, and that is the point of publishing both.
// The equivalence holds only when, for every window:
//
//   SIZE is a power of two            (so ~mask is a contiguous prefix)
//   BASE is naturally aligned to SIZE (so no in-window address escapes and
//                                      no out-of-window address is caught)
//
// Violate either and the mask decode silently means something else. It does
// not fail loudly; it decodes a DIFFERENT region than the map describes,
// which is why the elaboration checks below are $fatal rather than warnings.
// Chapter 12.7 shows what the silent version costs.
// ─────────────────────────────────────────────────────────────────────────
module wb_mask_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_1000, 32'h4000_0000, 32'h0000_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,
  output logic [NS-1:0]                   sel_o,
  output logic [BYTE_AW-1-$clog2(DW/8):0] offset_o,
  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
  function automatic logic [WAW-1:0] wbase_of(input int unsigned i);
    return WAW'(base_of(i) >> SHIFT);
  endfunction
  // The in-window mask: SIZE-1 in word terms. Valid ONLY because the
  // elaboration check below has established SIZE is a power of two.
  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'd0)
        $fatal(1, "wb_mask_decode: region %0d has zero size", i);
      // The two preconditions, enforced rather than documented.
      if ((size_of(i) & (size_of(i) - 32'd1)) != 32'd0)
        $fatal(1, "wb_mask_decode: region %0d size %0h is not a power of two",
               i, size_of(i));
      if ((base_of(i) & (size_of(i) - 32'd1)) != 32'd0)
        $fatal(1, "wb_mask_decode: region %0d base %0h not aligned to size %0h",
               i, base_of(i), size_of(i));
      if (size_of(i) < 32'(DW / 8))
        $fatal(1, "wb_mask_decode: region %0d size %0h is under one bus word",
               i, size_of(i));
      for (int unsigned j = i + 1; j < NS; j++)
        if ((base_of(i) <= base_of(j) + size_of(j) - 32'd1) &&
            (base_of(j) <= base_of(i) + size_of(i) - 32'd1))
          $fatal(1, "wb_mask_decode: regions %0d and %0d overlap", i, j);
    end
  end

  logic [NS-1:0] hit;
  always_comb begin
    hit = '0;
    for (int unsigned i = 0; i < NS; i++)
      hit[i] = ((adr_i & ~wmask_of(i)) == wbase_of(i));
  end

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

  // For an aligned power-of-two window the masked address IS the offset,
  // so no subtractor is needed. This equivalence is exactly as conditional
  // as the decode itself.
  always_comb begin
    offset_o = adr_i;
    for (int unsigned i = 0; i < NS; i++)
      if (hit[i]) offset_o = adr_i & wmask_of(i);
  end
endmodule

  // Illustrative only. Not used in this module's SoC.
  always_comb begin
    sel = 3'b000;
    unique case (adr_i[29:20])      // the 4 KiB-window prefix
      10'h000: sel = 3'b001;        // RAM
      10'h100: sel = 3'b010;        // GPIO   word 0x1000_0000
      10'h100: sel = 3'b100;        // TIMER  -- same prefix!
      default: sel = 3'b000;
    endcase
  end

// ── 1. Overlapping windows ──────────────────────────────────────────────
// wb_overlap_decode — wb_range_decode with the elaboration audit REMOVED.
//
// The map it is given is the plausible kind of wrong: someone sized the GPIO
// window at 8 KiB "to leave room for expansion" and left the TIMER where the
// document already placed it, 4 KiB above GPIO's base. The two windows now
// share their upper half. Nothing in the source of either window looks
// incorrect; the defect exists only in the relationship between them, which
// is exactly why the check that catches it has to compare PAIRS.
//
// The decoder still computes each predicate correctly. Both are simply true.
module wb_overlap_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_1000, 32'h4000_0000, 32'h0000_0000 },
  parameter logic [NS*32-1:0] SIZE_FLAT =
      { 32'h0000_1000, 32'h0000_2000, 32'h0000_1000 },   // GPIO is 8 KiB
  localparam int unsigned WAW = BYTE_AW - $clog2(DW / 8)
) (
  input  logic [WAW-1:0] adr_i,
  output logic [NS-1:0]  sel_o,
  output logic [WAW-1:0] offset_o,
  output logic           unmapped_o
);
  localparam int unsigned SHIFT = $clog2(DW / 8);
  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
  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] wlast_of(input int unsigned i);
    return WAW'((base_of(i) + size_of(i) - 32'd1) >> SHIFT);
  endfunction

  // ── THE DEFECT: no pairwise overlap check. Nothing else differs. ──

  logic [NS-1:0] hit;
  always_comb begin
    hit = '0;
    for (int unsigned i = 0; i < NS; i++)
      hit[i] = (adr_i >= wbase_of(i)) && (adr_i <= wlast_of(i));
  end
  assign sel_o      = hit;
  assign unmapped_o = ~(|hit);
  // With two hits the last one wins here — an arbitrary outcome that the
  // correct decoder's one-hot guarantee made impossible rather than
  // resolving by accident of loop order.
  always_comb begin
    offset_o = adr_i;
    for (int unsigned i = 0; i < NS; i++)
      if (hit[i]) offset_o = adr_i - wbase_of(i);
  end
endmodule

  === SIM C - the same map with one window resized ===
    GPIO widened to 8 KiB 'for expansion'. TIMER left where the
    document put it. No pairwise check anywhere.

    byte adr     correct map      overlapping map
    0x40000004   010  GPIO         010  GPIO
    0x40000ffc   010  GPIO         010  GPIO
    0x40001004   100  TIMER        110  MULTIPLE
    0x40001ffc   100  TIMER        110  MULTIPLE

    words in 0x4000_0000..0x4000_1FFC owned by two targets: 1024
    the correct map's elaboration check rejects this configuration
    outright, which is why it cannot be measured on that decoder.

// ─────────────────────────────────────────────────────────────────────────
// Three more decode forms, published together so the differences between
// them are visible rather than described. All four decoders in this module
// are given the SAME map parameters; what differs is how they turn those
// parameters into a predicate.
// ─────────────────────────────────────────────────────────────────────────

// ── The off-by-one that a map document cannot catch ─────────────────────
// wb_offbyone_decode — wb_range_decode with the upper bound written as
// "<= base + size" instead of "<= base + size - 1".
//
// Every window is now ONE WORD too large. On an isolated window that shows
// up as an address that should have been unmapped being accepted. On two
// ADJACENT windows it is worse: each window's extra word is the next
// window's FIRST word, so the two overlap by exactly one location and the
// decoder answers with whichever the loop wrote last.
module wb_offbyone_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_1000, 32'h4000_0000, 32'h0000_0000 },
  parameter logic [NS*32-1:0] SIZE_FLAT =
      { 32'h0000_1000, 32'h0000_1000, 32'h0000_1000 },
  localparam int unsigned WAW = BYTE_AW - $clog2(DW / 8)
) (
  input  logic [WAW-1:0] adr_i,
  output logic [NS-1:0]  sel_o,
  output logic [WAW-1:0] offset_o,
  output logic           unmapped_o
);
  localparam int unsigned SHIFT = $clog2(DW / 8);
  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
  function automatic logic [WAW-1:0] wbase_of(input int unsigned i);
    return WAW'(base_of(i) >> SHIFT);
  endfunction
  // ── THE DEFECT: no "- 1". One word too many, in every window. ──
  function automatic logic [WAW-1:0] wend_of(input int unsigned i);
    return WAW'((base_of(i) + size_of(i)) >> SHIFT);
  endfunction

  logic [NS-1:0] hit;
  always_comb begin
    hit = '0;
    for (int unsigned i = 0; i < NS; i++)
      hit[i] = (adr_i >= wbase_of(i)) && (adr_i <= wend_of(i));
  end
  assign sel_o      = hit;
  assign unmapped_o = ~(|hit);
  always_comb begin
    offset_o = adr_i;
    for (int unsigned i = 0; i < NS; i++)
      if (hit[i]) offset_o = adr_i - wbase_of(i);
  end
endmodule

// ── A mask decode on a window that does not satisfy its preconditions ───
// wb_unchecked_mask_decode — wb_mask_decode with the elaboration checks
// REMOVED, so it can be given a window that is not a power of two.
//
// This is the module that shows why those checks are $fatal rather than
// warnings. Given a 3 KiB window it does not refuse, and it does not
// approximate: (size - 1) for 0x0C00 is 0x0BFF, whose bit pattern is not a
// contiguous low-order run, so ~mask has holes in it and the equality
// matches a set of addresses that is not an interval at all.
module wb_unchecked_mask_decode #(
  parameter int unsigned BYTE_AW = 32,
  parameter int unsigned DW      = 32,
  parameter logic [31:0] BASE    = 32'h4000_0000,
  parameter logic [31:0] SIZE    = 32'h0000_0C00,   // 3 KiB: not a power of 2
  localparam int unsigned WAW = BYTE_AW - $clog2(DW / 8)
) (
  input  logic [WAW-1:0] adr_i,
  output logic           sel_mask_o,     // what the mask form decides
  output logic           sel_range_o     // what the map actually says
);
  localparam int unsigned SHIFT = $clog2(DW / 8);
  localparam logic [WAW-1:0] WBASE = WAW'(BASE >> SHIFT);
  localparam logic [WAW-1:0] WMASK = WAW'((SIZE - 32'd1) >> SHIFT);
  localparam logic [WAW-1:0] WLAST = WAW'((BASE + SIZE - 32'd1) >> SHIFT);

  // ── no preconditions checked, and no complaint made ──
  assign sel_mask_o  = ((adr_i & ~WMASK) == WBASE);
  assign sel_range_o = (adr_i >= WBASE) && (adr_i <= WLAST);
endmodule

// ── A decoder whose comparison is sized to the offset, not the address ──
// wb_truncated_decode — identical to wb_range_decode except that the
// comparison uses the low CMP_W bits of the word address instead of all of
// them.
//
// This is not a typo bug. It is what happens when a width is chosen from
// the wrong quantity: the windows are 4 KiB, so an offset needs 10 word
// bits, and 10 bits therefore looks like the natural width for "the address
// the decoder cares about". The offset needs 10 bits. The SELECT needs all
// 30, because that is where the targets differ.
//
// With CMP_W = 20 the top ten bits vanish, and RAM at word 0x0000_0000 and
// GPIO at word 0x1000_0000 become indistinguishable — their low twenty bits
// are identical. Two windows that the map placed a gigabyte apart now
// occupy the same place.
module wb_truncated_decode #(
  parameter int unsigned BYTE_AW = 32,
  parameter int unsigned DW      = 32,
  parameter int unsigned NS      = 3,
  parameter int unsigned CMP_W   = 20,     // how much of the address is used
  parameter logic [NS*32-1:0] BASE_FLAT =
      { 32'h4000_1000, 32'h4000_0000, 32'h0000_0000 },
  parameter logic [NS*32-1:0] SIZE_FLAT =
      { 32'h0000_1000, 32'h0000_1000, 32'h0000_1000 },
  localparam int unsigned WAW = BYTE_AW - $clog2(DW / 8)
) (
  input  logic [WAW-1:0] adr_i,
  output logic [NS-1:0]  sel_o,
  output logic           unmapped_o
);
  localparam int unsigned SHIFT = $clog2(DW / 8);
  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 DEFECT: the comparison is CMP_W bits wide, not WAW. ──
  logic [CMP_W-1:0] a_cmp;
  assign a_cmp = adr_i[CMP_W-1:0];

  function automatic logic [CMP_W-1:0] cbase_of(input int unsigned i);
    return CMP_W'(base_of(i) >> SHIFT);
  endfunction
  function automatic logic [CMP_W-1:0] clast_of(input int unsigned i);
    return CMP_W'((base_of(i) + size_of(i) - 32'd1) >> SHIFT);
  endfunction

  logic [NS-1:0] hit;
  always_comb begin
    hit = '0;
    for (int unsigned i = 0; i < NS; i++)
      hit[i] = (a_cmp >= cbase_of(i)) && (a_cmp <= clast_of(i));
  end
  assign sel_o      = hit;
  assign unmapped_o = ~(|hit);
endmodule

  --- decode forms, same map, four implementations ---

  1. upper bound written as <= base + size

     byte adr     correct      off-by-one
     0x40000ffc   010 GPIO      010 GPIO
     0x40001000   100 TIMER     110 MULTI
     0x00001000   000 -none-    001 RAM

     addresses owned by two targets, correct decoder:     0
     addresses owned by two targets, off-by-one decoder:  1
     each window gained one word, and that word was the
     next window's first.

  2. comparison sized to the offset (20 bits) not the address

     byte adr     correct      truncated
     0x00000000   001 RAM       011 RAM+GPIO
     0x40000000   010 GPIO      011 RAM+GPIO
     0x80000000   000 -none-    011 RAM+GPIO

     GPIO's window words seen as two targets at once: 1024
     RAM and GPIO differ only above bit 19, so a 20-bit
     comparison cannot tell them apart at all.

  3. mask decode on a 3 KiB window (not a power of two)

     the map says 0x40000000 .. 0x40000BFF. mask = 0x0BFF >> 2.

     byte adr     map says   mask says
     0x40000000   inside     inside
     0x40000800   inside     inside
     0x40000bfc   inside     inside
     0x40000c00   outside    outside
     0x40000400   inside     outside

     words the mask ACCEPTS that the map excludes: 0
     words the mask REJECTS that the map includes: 256
     the mask form did not fail. It decoded a different
     region, and said nothing.

// ─────────────────────────────────────────────────────────────────────────
// wb_form_props — properties about the DECODE FORM rather than the map.
//
// NOTE ON EXECUTION: Icarus Verilog does not support SVA. These were
// reviewed by inspection and are NOT claimed to have been executed. The
// numbers in Sections 5 and 6 come from procedural checks, which Icarus
// does run.
// ─────────────────────────────────────────────────────────────────────────
module wb_form_props #(
  parameter int unsigned NS = 3
) (
  input logic          clk_i,
  input logic          rst_i,
  input logic [NS-1:0] sel_range_i,     // the general decoder
  input logic [NS-1:0] sel_mask_i,      // the cheap decoder
  input logic [29:0]   offset_range_i,
  input logic [29:0]   offset_mask_i
);
  default disable iff (rst_i);

  // P14 — LOCAL, AND CONDITIONAL ON THE MAP.
  // The two forms agree. This is TRUE of the running map and FALSE in
  // general: it holds only while every window is a power of two and
  // naturally aligned. Section 6 measures a window where it fails, and the
  // property is stated here precisely so that the condition is recorded
  // alongside the claim rather than remembered separately.
  property p_forms_agree;
    @(posedge clk_i) sel_range_i == sel_mask_i;
  endproperty
  a_forms_agree: assert property (p_forms_agree);

  // P15 — LOCAL, AND CONDITIONAL ON THE SAME PRECONDITIONS.
  // Masking and subtracting give the same offset. The equivalence has
  // exactly the same preconditions as P14, because it is the same fact
  // about prefixes applied to the low bits instead of the high ones.
  property p_offsets_agree;
    @(posedge clk_i) (sel_range_i != '0) |->
      (offset_range_i == offset_mask_i);
  endproperty
  a_offsets_agree: assert property (p_offsets_agree);

  // P16 — LOCAL ADDRESS-MAP POLICY, and the one SIM C violates.
  // No two targets are ever selected together. Stated on the general
  // decoder because that is the one that can be given an overlapping map
  // without refusing to elaborate.
  property p_no_double_owner;
    @(posedge clk_i) $onehot0(sel_range_i);
  endproperty
  a_no_double_owner: assert property (p_no_double_owner);
endmodule