Wildcard Equality — ==? and !=?

// Syntax: value ==? pattern           <-- ORDER MATTERS
// Returns: 1-bit - always 0 or 1, NEVER X
// Rule: for each bit - if the RIGHT operand's bit is X or Z, that position
//       is a wildcard and matches anything on the left. Otherwise the bits
//       must match exactly, with X and Z on the LEFT treated as literal
//       values (as `===` does), not as don't-cares.
 
logic [7:0] cmd = 8'b1010_0011;
 
// ── Pattern matching: X marks don't-care bits ─────────────────────
cmd ==? 8'b1XXX_XXXX   // 1 — bit7=1 matches; all other bits are X (don't-care)
cmd ==? 8'b1010_XXXX   // 1 — bits[7:4]=1010 match; lower nibble is X
cmd ==? 8'b1010_0011   // 1 — exact match (no wildcards needed)
cmd ==? 8'b0XXX_XXXX   // 0 — bit7=1 in cmd, pattern requires bit7=0
 
// ── Inequality ───────────────────────────────────────────────────
cmd !=? 8'b1XXX_XXXX   // 0 — they wildcard-match, so !=? is 0
cmd !=? 8'b0XXX_XXXX   // 1 — they don't match, so !=? is 1
 
// ── X in the LEFT operand is NOT a wildcard ──────────────────────
//    This is where the symmetric intuition fails. The pattern on the
//    right is fully known, so nothing is masked, and the X on the left
//    is matched literally - exactly as === would match it.
logic [3:0] val = 4'bx101;
val ==? 4'b0101   // 0 - bit3: left X vs right 0 -> literal mismatch
val ==? 4'b1101   // 0 - bit3: left X vs right 1 -> literal mismatch
val ==? 4'b0100   // 0 - bit0 also mismatches on a known bit
val ==? 4'bx101   // 1 - NOW bit3 is a wildcard: it is on the RIGHT
 
// ── Swapping the operands changes the answer ─────────────────────
4'b0101 ==? val   // 1 - val is now the pattern; its X masks bit 3
val ==? 4'b0101   // 0 - val is now the value; its X is literal
//                       Same two values. Opposite results.
 
// ── Use in if statement ───────────────────────────────────────────
if (opcode ==? 8'b1010_XXXX)
  $display("ALU class opcode");
 
// ── casex is NOT the same as ==?  It is SYMMETRIC: an X in the
//    expression `opcode` is also a don't-care and can match the
//    wrong item. Prefer casez with `?`, or an if-else on ==?.
casex (opcode)
  8'b1010_XXXX: /* ALU */
  8'b1100_XXXX: /* LOAD */
  default:       /* ILLEGAL */
endcase

module tb_equality_compare;
 
  logic [3:0] clean  = 4'b1010;
  logic [3:0] dirty  = 4'b1X10;   // bit2 is X
  logic [3:0] pattn  = 4'b1X1X;   // wildcard pattern: care about bits 3,1 only
 
  initial begin
 
    $display("--- Clean vs clean ---");
    $display("1010 ==  1010 : %0b", clean ==  clean);   // 1
    $display("1010 === 1010 : %0b", clean === clean);   // 1
    $display("1010 ==? 1010 : %0b", clean ==? clean);   // 1
 
    $display("--- Dirty (1X10) vs clean (1010) ---");
    $display("1X10 ==  1010 : %0b", dirty ==  clean);   // X  — X propagates
    $display("1X10 === 1010 : %0b", dirty === clean);   // 0  — X != 0 literally
    $display("1X10 ==? 1010 : %0b", dirty ==? clean);   // 1  — X in dirty masks bit2
 
    $display("--- Pattern (1X1X) matching ---");
    $display("1010 ==? 1X1X : %0b", clean ==? pattn);   // 1 — bit3=1✓ bit1=1✓
    $display("1000 ==? 1X1X : %0b", 4'b1000 ==? pattn); // 0 — bit1: 0≠1
    $display("1110 ==? 1X1X : %0b", 4'b1110 ==? pattn); // 1 — bit3=1✓ bit1=1✓
 
    $display("--- Detecting X with === ---");
    $display("1X10 === 1X10 : %0b", dirty === dirty);   // 1 — X matches X exactly
    $display("1X10 !== 1010 : %0b", dirty !== clean);   // 1 — they are not case-equal
 
    $finish;
  end
 
endmodule

--- Clean vs clean ---
1010 ==  1010 : 1
1010 === 1010 : 1
1010 ==? 1010 : 1
--- Dirty (1X10) vs clean (1010) ---
1X10 ==  1010 : x
1X10 === 1010 : 0
1X10 ==? 1010 : 1
--- Pattern (1X1X) matching ---
1010 ==? 1X1X : 1
1000 ==? 1X1X : 0
1110 ==? 1X1X : 1
--- Detecting X with === ---
1X10 === 1X10 : 1
1X10 !== 1010 : 1

// 8-bit opcode classification by bit pattern:
// ALU:        1010_XXXX  (bit7:4 = 1010, lower nibble = don't-care)
// LOAD/STORE: 110X_XXXX  (bit7:5 = 110, bit4 = R/W, lower = don't-care)
// BRANCH:     0001_XXXX
// NOP:        0000_0000
 
module tb_pattern_decoder;
 
  function automatic string classify(input logic [7:0] op);
    if      (op ==? 8'b1010_XXXX)  return "ALU";
    else if (op ==? 8'b110X_XXXX)  return "LD/ST";
    else if (op ==? 8'b0001_XXXX)  return "BRANCH";
    else if (op ==? 8'b0000_0000)  return "NOP";
    else                            return "ILLEGAL";
  endfunction
 
  initial begin
    $display("0xA0 → %s", classify(8'hA0));   // ALU   (1010_0000)
    $display("0xAF → %s", classify(8'hAF));   // ALU   (1010_1111)
    $display("0xC5 → %s", classify(8'hC5));   // LD/ST (1100_0101)
    $display("0xD3 → %s", classify(8'hD3));   // LD/ST (1101_0011)
    $display("0x17 → %s", classify(8'h17));   // BRANCH(0001_0111)
    $display("0x00 → %s", classify(8'h00));   // NOP
    $display("0x55 → %s", classify(8'h55));   // ILLEGAL
    $finish;
  end
 
endmodule

0xA0 → ALU
0xAF → ALU
0xC5 → LD/ST
0xD3 → LD/ST
0x17 → BRANCH
0x00 → NOP
0x55 → ILLEGAL

module tb_scoreboard_operators;
 
  logic [7:0] dut_out;
  logic [7:0] expected;
 
  task automatic check(input logic [7:0] got, exp);
 
    // Step 1: ALWAYS detect X first using === before comparing values
    // If DUT output has X bits, that is always a bug — flag it immediately
    if (got === 8'hXX || got !=? 8'hXX == 0) // simpler: check for X
    if (^got === 1'bX)                           // reduction XOR: X if any bit is X
      $error("DUT output has X bits: %08b", got);
 
    // Step 2: Compare known bits — use === for exact match
    if (got !== exp)
      $error("MISMATCH: got=0x%02h exp=0x%02h", got, exp);
    else
      $display("PASS: 0x%02h", got);
  endtask
 
  // Protocol checker: verify opcode class using ==?
  function automatic void check_opcode_class(input logic [7:0] op);
    // Use ==? when you only care about WHICH class the opcode belongs to
    if (!(op ==? 8'b1010_XXXX || op ==? 8'b110X_XXXX ||
          op ==? 8'b0001_XXXX || op == 8'h00))
      $error("Illegal opcode received from DUT: 0x%02h", op);
  endfunction
 
  initial begin
    // Normal pass
    dut_out = 8'hAB; expected = 8'hAB;
    check(dut_out, expected);       // PASS
 
    // X in output — always an error
    dut_out = 8'hXX; expected = 8'hAB;
    check(dut_out, expected);       // ERROR: X bits detected
 
    // Opcode class check
    check_opcode_class(8'hA5);     // ALU class: passes
    check_opcode_class(8'h55);     // ILLEGAL: error
 
    $finish;
  end
 
endmodule

module tb_casex_wildcard;
 
  logic [3:0] op;
  logic [1:0] class_out;
 
  // casex uses ==? semantics — X in case item = don't-care
  always_comb begin
    casex (op)
      4'b1XXX: class_out = 2'b11;   // any op with bit3=1
      4'b01XX: class_out = 2'b10;   // bit3=0, bit2=1
      4'b001X: class_out = 2'b01;   // bit3=0, bit2=0, bit1=1
      default: class_out = 2'b00;
    endcase
  end
 
  // Equivalent using ==? chained if-else
  function automatic logic [1:0] classify_wc(input logic [3:0] v);
    if      (v ==? 4'b1XXX) return 2'b11;
    else if (v ==? 4'b01XX) return 2'b10;
    else if (v ==? 4'b001X) return 2'b01;
    else                     return 2'b00;
  endfunction
 
  initial begin
    $display("4'b1010 → %02b (expect 11)", classify_wc(4'b1010));  // 11
    $display("4'b0110 → %02b (expect 10)", classify_wc(4'b0110));  // 10
    $display("4'b0011 → %02b (expect 01)", classify_wc(4'b0011));  // 01
    $display("4'b0000 → %02b (expect 00)", classify_wc(4'b0000));  // 00
 
    // Priority trap: 4'b1100 matches BOTH 4'b1XXX and 4'b01XX patterns
    // casex/if-else takes the FIRST match — this is priority encoding
    // 4'b1100: bit3=1 → matches 4'b1XXX first → class_out = 2'b11
    $display("4'b1100 → %02b (expect 11 — first match wins)",
              classify_wc(4'b1100));   // 11, NOT 10
 
    $finish;
  end
 
endmodule

// wildcard_equality_proof.sv
//
// Self-checking proof that ==? is ASYMMETRIC, plus the canonical
// ==  /  ===  /  ==?  matrix on shared operands.
module wildcard_equality_proof;
 
  int errors = 0;
 
  task automatic chk(string name, logic got, logic exp);
    if (got !== exp) begin
      errors++;
      $display("FAIL %-52s got=%b exp=%b", name, got, exp);
    end else
      $display("pass %-52s = %b", name, got);
  endtask
 
  initial begin
    logic [3:0] val = 4'bx101;      // an X in the DATA
    logic [3:0] pat = 4'bx101;      // the same bits, used as a PATTERN
 
    // ================================================================
    // 1. THE ASYMMETRY - the whole point of the page
    //    Identical bit patterns. Opposite results. Operand order decides.
    // ================================================================
    chk("val ==? 4'b0101   (left X is LITERAL -> mismatch)",
        val ==? 4'b0101, 1'b0);
    chk("4'b0101 ==? pat   (right X is WILDCARD -> match)",
        4'b0101 ==? pat, 1'b1);
 
    // With no wildcards on the right, ==? degenerates to ===:
    chk("4'bxxxx ==? 4'b0000  (right known -> like ===)",
        4'bxxxx ==? 4'b0000, 1'b0);
    chk("4'b0000 ==? 4'bxxxx  (right all wildcards)",
        4'b0000 ==? 4'bxxxx, 1'b1);
    chk("4'bxxxx ==? 4'b0000  equals  4'bxxxx === 4'b0000",
        (4'bxxxx ==? 4'b0000), (4'bxxxx === 4'b0000));
 
    // A wildcard matches ANY left value, including X and Z:
    chk("4'bxxxx ==? 4'bxxxx  (wildcards match X too)",
        4'bxxxx ==? 4'bxxxx, 1'b1);
    chk("4'bzzzz ==? 4'bxxxx  (wildcards match Z too)",
        4'bzzzz ==? 4'bxxxx, 1'b1);
 
    // ================================================================
    // 2. THE CANONICAL MATRIX - one pair of operands, three operators
    //    a = 8'b1010_01xz   (X and Z in the DATA)
    //    b = 8'b1010_01xz   (the identical literal, as a PATTERN)
    // ================================================================
    begin
      logic [7:0] a = 8'b1010_01xz;
      logic       r;
 
      r = (a ==  8'b1010_01xz); chk("a ==  same-bits  -> X (propagates)", r, 1'bx);
      r = (a === 8'b1010_01xz); chk("a === same-bits  -> 1 (literal match)", r, 1'b1);
      r = (a ==? 8'b1010_01xz); chk("a ==? same-bits  -> 1 (right wildcards)", r, 1'b1);
 
      // Now compare against a fully-KNOWN value. The X/Z are on the left
      // only, so ==? has nothing to wildcard and behaves like ===.
      r = (a ==  8'b1010_0100); chk("a ==  known      -> X", r, 1'bx);
      r = (a === 8'b1010_0100); chk("a === known      -> 0", r, 1'b0);
      r = (a ==? 8'b1010_0100); chk("a ==? known      -> 0  (NOT masked!)", r, 1'b0);
 
      // And a pattern that deliberately wildcards the low nibble:
      r = (a ==? 8'b1010_xxxx); chk("a ==? 8'b1010_xxxx -> 1 (masked)", r, 1'b1);
    end
 
    // ================================================================
    // 3. THE CHECKER CONSEQUENCE
    //    ==? does NOT hide an X in the value under test.
    // ================================================================
    begin
      logic [7:0] dut_out  = 8'hxx;
      logic [7:0] expected = 8'hA5;
 
      chk("dut_out ==? expected  -> 0  (X is caught)",
          dut_out ==? expected, 1'b0);
      chk("expected ==? dut_out  -> 1  (X MASKS - operands reversed!)",
          expected ==? dut_out, 1'b1);
      // ^ The second line is the bug in Debug Lab 5. Same two signals,
      //   written the other way round, and the checker stops working.
    end
 
    if (errors == 0) $display("\nwildcard_equality_proof: ALL CHECKS PASSED");
    else             $display("\nwildcard_equality_proof: %0d FAILURES", errors);
    $finish;
  end
endmodule

// ── 1. MONITOR: classify received AXI transaction ─────────────────
function automatic string axi_op_type(input logic [7:0] awid);
  if      (awid ==? 8'b0000_XXXX) return "MGMT";
  else if (awid ==? 8'b0001_XXXX) return "DATA";
  else if (awid ==? 8'b1XXX_XXXX) return "DMA";
  else                             return "UNKNOWN";
endfunction
 
// ── 2. SCOREBOARD: detect X in DUT output (use ===, not ==?) ──────
function automatic void assert_no_x(input logic [31:0] data, input string sig);
  if (^data === 1'bX)   // XOR reduction: 1'bX if any bit is X
    $error("%s contains X bits: %08h", sig, data);
endfunction
 
// ── 3. SVA ASSERTION: pattern-based property ──────────────────────
// assert property (@(posedge clk)
//   cmd_valid |-> cmd_opcode ==? 8'b1010_XXXX || cmd_opcode ==? 8'b0001_XXXX);
 
// ── 4. PROTOCOL CHECKER: bus mask verification ─────────────────────
// AHB: HSIZE must be 3'b000, 3'b001, or 3'b010 — upper bits always 0
function automatic void check_hsize(input logic [2:0] hsize);
  if (!(hsize inside {3'b000, 3'b001, 3'b010}))
    $error("Illegal HSIZE: 3'b%03b", hsize);
endfunction
 
// ── 5. COVERAGE: sample by pattern class ──────────────────────────
// covergroup cg_opcode;
//   cp_class: coverpoint {
//     (opcode ==? 8'b1010_XXXX),   // ALU
//     (opcode ==? 8'b110X_XXXX)    // LD/ST
//   }
// endgroup
 
// ── 6. DRIVER: choose payload based on address pattern ────────────
logic [31:0] addr;
logic [31:0] write_data;
// Peripheral region: addr[31:28] = 4'hA
write_data = (addr ==? 32'hAXXX_XXXX) ? 32'h0000_0001  // reg init value
                                        : 32'hCAFE_BABE; // memory fill

logic [7:0] dut_out = 8'hXX;   // DUT output corrupted with X
 
// BUGGY: == with X on left operand → result is X, not 0 or 1
// if (dut_out == 8'hXX) evaluates to X — the if-body never runs!
if (dut_out == 8'hXX)
  $error("X detected");    // NEVER FIRES — condition is X, treated as false
 
// ALSO BUGGY: != doesn't detect X either
if (dut_out != 8'hAB)
  $error("Mismatch");      // also X → doesn't fire! Bug passes silently
 
// CORRECT: use === (case equality) to detect X
if (dut_out === 8'hXX)
  $error("X detected");    // FIRES correctly
 
// CORRECT: use !== (case inequality) for mismatch check
if (dut_out !== 8'hAB)
  $error("Mismatch");      // FIRES correctly — X !== AB is true
 
// BEST PRACTICE: always use !== in scoreboard comparisons
// This catches both value mismatches AND unexpected X/Z values

logic [7:0] opcode = 8'bXXXX_1010;   // upper nibble is X!
 
// BUGGY: engineer checks if opcode is an ALU instruction
// But upper nibble of opcode is X, not 1010
if (opcode ==? 8'b1010_XXXX)
  $display("ALU instruction");   // FIRES — but upper nibble is unknown!
// X in opcode[7:4] + X in pattern[3:0] = ALL bits masked = always matches!
// The engineer doesn't notice the DUT sent garbage in the upper nibble
 
// CORRECT: first verify no X in the value, THEN pattern-match
if (^opcode === 1'bX)            // reduction XOR detects any X bit
  $error("Opcode has X bits");
else if (opcode ==? 8'b1010_XXXX)
  $display("ALU instruction");   // now safe to pattern-match

logic [3:0] op = 4'b1100;
logic [1:0] result;
 
// BUGGY: both 4'b1XXX and 4'b11XX match op=1100
// casex picks the FIRST matching arm — order matters!
casex (op)
  4'b1XXX: result = 2'b01;   // matches 4'b1100 FIRST
  4'b11XX: result = 2'b10;   // never reached for op=1100
  default: result = 2'b00;
endcase
// result = 2'b01 — engineer expected 2'b10 for the more specific pattern
 
// CORRECT: put more specific patterns FIRST
casex (op)
  4'b11XX: result = 2'b10;   // more specific — check first
  4'b1XXX: result = 2'b01;   // less specific — fallthrough
  default: result = 2'b00;
endcase
// result = 2'b10 — correct
 
// BETTER: use unique casex to get a warning if patterns overlap
// unique casex (op) — tool reports overlap if any two patterns can both match

class txn;
  rand logic [7:0] opcode;
 
  // INTENT: constrain opcode to ALU class (upper nibble = 4'b1010)
  // BUGGY: ==? is NOT valid in a constraint expression
  // Constraint solver works on 2-state values — no X/Z
  // Most simulators will error or ignore this
  // constraint alu_c { opcode ==? 8'b1010_XXXX; } // ILLEGAL / undefined
 
  // CORRECT option 1: constrain the specific bits directly
  constraint alu_c { opcode[7:4] == 4'b1010; }
  // Solver picks any opcode where upper nibble is exactly 1010
 
  // CORRECT option 2: use inside with explicit values
  // constraint alu_c { opcode inside {[8'hA0:8'hAF]}; }
 
endclass