Enumeration Types

// ── BASIC enum ────────────────────────────────────────────────────
// enum [base_type] { member_list } [variable]
 
// Default base type = int (32-bit 2-state, signed) — BAD for synthesis
enum { IDLE, ACTIVE, DONE } state_bad;  // 32-bit int underneath — don't do this in RTL
 
// ── PREFERRED: explicit base type for RTL ─────────────────────────
typedef enum logic [1:0] {
  ST_IDLE  = 2'b00,
  ST_RUN   = 2'b01,
  ST_DRAIN = 2'b10,
  ST_ERROR = 2'b11
} fsm_state_t;
 
fsm_state_t state, next_state;   // variables of that type
 
// ── AUTO-NUMBERED (no explicit values) ───────────────────────────
typedef enum logic [2:0] {
  IDLE, FETCH, DECODE, EXECUTE, WRITEBACK
} pipeline_t;   // IDLE=0, FETCH=1, DECODE=2, EXECUTE=3, WRITEBACK=4
 
// ── MIXED: some explicit, some auto ──────────────────────────────
typedef enum logic [3:0] {
  OP_NOP   = 4'h0,
  OP_ADD   = 4'h1,
  OP_SUB   = 4'h2,
  OP_LOAD  = 4'h8,   // explicit jump in value
  OP_STORE = 4'h9    // auto: 4'h9
} opcode_t;
 
// ── OPERATIONS ────────────────────────────────────────────────────
state = ST_IDLE;
if (state == ST_RUN) $display("running");
if (state != ST_ERROR) $display("no error");
 
// ── BUILT-IN METHODS ──────────────────────────────────────────────
state.first()     // ST_IDLE (first declared member)
state.last()      // ST_ERROR (last declared member)
state.next()      // next member after current value
state.prev()      // previous member before current value
state.num()       // 4 (number of members in the enum)
state.name()      // "ST_IDLE" (string name of current value)
 
// ── int ↔ enum CONVERSION ─────────────────────────────────────────
int         raw = 2;
fsm_state_t s;
if (!$cast(s, raw))
  $error("Invalid enum value %0d", raw);   // $cast returns 0 if value invalid
int         back = int'(state);             // enum → int: always safe

module tb_enum_basics;
 
  typedef enum logic [1:0] {
    IDLE = 2'b00, RUN = 2'b01, DRAIN = 2'b10, ERR = 2'b11
  } state_t;
 
  state_t s = IDLE;
 
  initial begin
 
    // ── Basic operations ──────────────────────────────────────────
    $display("Initial state: %s (%0d)", s.name(), int'(s));  // IDLE (0)
 
    s = RUN;
    $display("After  assign: %s (%0d)", s.name(), int'(s));  // RUN (1)
 
    // ── Iteration methods ─────────────────────────────────────────
    $display("first = %s",  s.first().name());  // IDLE
    $display("last  = %s",  s.last().name());   // ERR
    $display("next  = %s",  s.next().name());   // DRAIN (next after RUN)
    $display("prev  = %s",  s.prev().name());   // IDLE (prev of RUN)
    $display("num   = %0d", s.num());           // 4
 
    // ── Iterate all members ───────────────────────────────────────
    state_t e = s.first();
    repeat (s.num()) begin
      $display("  %s = %02b", e.name(), e);
      e = e.next();
    end
 
    // ── $cast: int → enum (with validity check) ───────────────────
    int raw = 2;
    if ($cast(s, raw))
      $display("Cast OK: %s", s.name());    // DRAIN
    raw = 10;
    if (!$cast(s, raw))
      $display("Cast FAIL: %0d is not a valid state", raw);
 
    $finish;
  end
 
endmodule

Initial state: IDLE (0)
After  assign: RUN (1)
first = IDLE
last  = ERR
next  = DRAIN
prev  = IDLE
num   = 4
  IDLE = 00
  RUN = 01
  DRAIN = 10
  ERR = 11
Cast OK: DRAIN
Cast FAIL: 10 is not a valid state

typedef enum logic [1:0] {
  S_IDLE  = 2'b00,
  S_REQ   = 2'b01,
  S_WAIT  = 2'b10,
  S_DONE  = 2'b11
} req_state_t;
 
module axi_ctrl (
  input  logic   clk, rst_n, start, done_i,
  output logic   req_o, busy_o
);
  req_state_t state, next_state;
 
  // State register
  always_ff @(posedge clk or negedge rst_n)
    if (!rst_n) state <= S_IDLE;
    else        state <= next_state;
 
  // Next-state logic — unique case ensures: all states covered, no overlaps
  always_comb begin
    next_state = state;    // default: hold current
    req_o  = 1'b0;
    busy_o = 1'b0;
 
    unique case (state)
      S_IDLE: if (start)  next_state = S_REQ;
      S_REQ:  begin req_o = 1; busy_o = 1; next_state = S_WAIT; end
      S_WAIT: begin         busy_o = 1;
              if (done_i)  next_state = S_DONE; end
      S_DONE:              next_state = S_IDLE;
    endcase
  end
 
endmodule
 
// Testbench: read enum state name directly — $display %s works with enum
module tb_axi_ctrl;
  logic clk=0, rst_n, start, done_i, req_o, busy_o;
  axi_ctrl dut(.*);
  always #5 clk = ~clk;
 
  // Monitor state using hierarchical reference
  always @(posedge clk)
    $display("t=%0t state=%s req=%b busy=%b", $time, dut.state.name(), req_o, busy_o);
 
  initial begin
    rst_n=0; start=0; done_i=0; #12; rst_n=1;
    @(posedge clk); start=1; @(posedge clk); start=0;
    @(posedge clk); done_i=1; @(posedge clk); done_i=0;
    repeat(2) @(posedge clk);
    $finish;
  end
endmodule

typedef enum logic [1:0] {
  OKAY=2'b00, EXOKAY=2'b01, SLVERR=2'b10, DECERR=2'b11
} axi_resp_t;
 
typedef enum logic [1:0] {
  FIXED=2'b00, INCR=2'b01, WRAP=2'b10
} axi_burst_t;
 
class axi_txn;
  rand axi_burst_t burst;
  rand axi_resp_t  resp;
  rand logic [7:0]  len;
 
  // Constrain using enum members — readable and type-safe
  constraint no_wrap  { burst != WRAP; }
  constraint ok_resp  { resp inside {OKAY, EXOKAY}; }
  constraint len_c    { len inside {[1:16]}; }
 
  function void print();
    $display("burst=%s resp=%s len=%0d", burst.name(), resp.name(), len);
  endfunction
endclass
 
// Scoreboard: compare enum responses by name for readable error messages
task automatic check_resp(input axi_resp_t exp, got);
  if (exp !== got)
    $error("RESP MISMATCH: expected=%s got=%s", exp.name(), got.name());
  else
    $display("PASS resp=%s", got.name());
endtask
 
module tb_enum_constraints;
  initial begin
    axi_txn t = new();
    repeat(3) begin
      void'(t.randomize()); t.print();
    end
    check_resp(OKAY, SLVERR);   // deliberate mismatch for demo
    check_resp(OKAY, OKAY);
    $finish;
  end
endmodule

module tb_enum_corners;
 
  typedef enum logic [1:0] {
    A = 2'b00, B = 2'b01, C = 2'b10
    // 2'b11 is NOT defined — it's an illegal value!
  } abc_t;
 
  abc_t val;
  int   raw;
 
  initial begin
 
    // ── $cast with validity check ─────────────────────────────────
    for (raw = 0; raw < 4; raw++) begin
      if ($cast(val, raw))
        $display("raw=%0d → val=%s", raw, val.name());
      else
        $display("raw=%0d → INVALID (not in enum)", raw);
    end
    // raw=0 → A, raw=1 → B, raw=2 → C, raw=3 → INVALID
 
    // ── name() on undefined value returns "" ──────────────────────
    // If an enum variable somehow holds an invalid value (via force/DPI/etc.)
    // name() returns "" (empty string) — use this to detect invalid states
    logic [1:0] bits = 2'b11;
    val = abc_t'(bits);           // force-cast — bypasses validation!
    $display("Illegal value name(): '%s'", val.name()); // ""
    if (val.name() == "")
      $error("FSM in illegal state: %02b", val);
 
    // ── Coverage: iterate all enum values ────────────────────────
    val = val.first();
    repeat (val.num()) begin
      $display("Covering: %s", val.name());
      val = val.next();
    end
 
    $finish;
  end
 
endmodule

// ── 1. AXI PROTOCOL FIELDS AS ENUMS ───────────────────────────────
typedef enum logic [1:0] { FIXED, INCR, WRAP }       axi_burst_t;
typedef enum logic [2:0] { SZ_1, SZ_2, SZ_4, SZ_8 }  axi_size_t;
typedef enum logic [1:0] { OKAY, EXOKAY, SLVERR, DECERR } axi_resp_t;
 
// ── 2. UVM PHASE TRACKER ──────────────────────────────────────────
typedef enum { BUILD, CONNECT, RUN, REPORT, FINAL } uvm_phase_t;
uvm_phase_t curr_phase = BUILD;
$display("Phase: %s", curr_phase.name());
 
// ── 3. CONSTRAINT WITH ENUM MEMBERS ──────────────────────────────
rand axi_burst_t burst;
constraint no_wrap_c { burst inside {FIXED, INCR}; }  // readable!
 
// ── 4. SCOREBOARD: compare and report with names ──────────────────
if (got_resp !== exp_resp)
  $error("RESP: exp=%s got=%s", exp_resp.name(), got_resp.name());
 
// ── 5. COVERAGE: cover all enum values ────────────────────────────
// covergroup cg_burst;
//   cp_burst: coverpoint burst {
//     bins fixed = {FIXED};
//     bins incr  = {INCR};
//     bins wrap  = {WRAP};
//   }
// endgroup
 
// ── 6. MONITOR: decode incoming response ─────────────────────────
function automatic string decode_resp(logic [1:0] raw);
  axi_resp_t r;
  if ($cast(r, raw)) return r.name();
  return $sformatf("UNKNOWN(%02b)", raw);
endfunction
 
// ── 7. ASSERTION: valid response check ────────────────────────────
// assert property (@(posedge clk) bvalid |-> bresp inside {OKAY, EXOKAY});

// BUGGY: default base type is int — synthesizes 32 flip-flops for state!
typedef enum { IDLE, RUN, DONE } state_t;   // int underneath = 32-bit
state_t state;
// Synthesis report shows: state uses 32 flip-flops
// Gate-sim shows 32-bit state register — overkill for a 3-state FSM
 
// FIXED: always specify the base type for RTL
typedef enum logic [1:0] {
  IDLE = 2'b00, RUN = 2'b01, DONE = 2'b10
} state_ok_t;
// Now state register is 2 flip-flops — correct

typedef enum logic [1:0] { A, B, C } abc_t;
abc_t val;
int   raw = 1;
 
// BUGGY: direct int → enum assignment
val = raw;    // COMPILE ERROR or WARNING (tool-dependent)
              // Most tools: "implicit type conversion may cause unexpected results"
 
// ALSO BUGGY: force-cast bypasses validation
val = abc_t'(raw);    // compiles but skips the validity check
// If raw=3 (not defined), val holds illegal value — name() returns ""
 
// CORRECT: use $cast with validity check
if (!$cast(val, raw))
  $error("%0d is not a valid abc_t value", raw);

typedef enum logic [1:0] { S0, S1, S2 } s_t;
// Note: 2'b11 is unused — but synthesis tool doesn't know that
 
logic   out;
s_t     s;
 
// BUGGY: 3 arms for a 2-bit type = 4 possible values
// The 4th (2'b11) is uncovered → synthesis infers a latch for 'out'
always_comb
  case (s)
    S0: out = 0;
    S1: out = 1;
    S2: out = 0;
    // missing 2'b11 → latch inferred!
  endcase
 
// CORRECT option 1: add default
always_comb
  case (s)
    S0: out = 0; S1: out = 1; S2: out = 0;
    default: out = 0;   // covers 2'b11 explicitly
  endcase
 
// CORRECT option 2: use unique case (synthesis knows remaining states are illegal)
always_comb
  unique case (s)
    S0: out = 0; S1: out = 1; S2: out = 0;
  endcase   // unique: synthesis knows other values won't occur

typedef enum { INIT, ACTIVE, DONE } phase_t;
phase_t p = DONE;
 
// BUGGY: assuming next() stops at DONE
while (p != DONE) begin
  $display("%s", p.name());
  p = p.next();    // if started at DONE, next() wraps to INIT!
end
// The loop body never executes — p starts at DONE, condition false immediately
// But if you use next() carelessly thinking it "stops" at last member: infinite loop
 
// CORRECT: use num() to count explicitly
p = p.first();
repeat (p.num()) begin
  $display("%s", p.name());
  p = p.next();    // safe: exactly num() iterations
end

module enum_illegal_proof;
 
  typedef enum logic [1:0] { IDLE = 2'b00, BUSY = 2'b01, DONE = 2'b10 } state_t;
  // 2'b11 is a legal BIT PATTERN with no label. That gap is the whole subject.
 
  state_t s;
  logic [1:0] raw;
  int fails = 0;
 
  task automatic expect (input string what, input bit cond);
    if (cond) $display("  PASS  %s", what);
    else begin $display("  FAIL  %s", what); fails++; end
  endtask
 
  initial begin
    $display("\n1. $cast validates and reports");
    raw = 2'b10;
    expect("$cast succeeds for a declared value", $cast(s, raw) == 1);
    raw = 2'b11;
    expect("$cast REFUSES an undeclared value",   $cast(s, raw) == 0);
    // $cast leaves the target unchanged on failure, so s still holds DONE.
    expect("target unchanged after a failed cast", s === DONE);
 
    $display("\n2. The static cast performs no validation at all");
    s = state_t'(2'b11);          // legal SystemVerilog; no error, no warning
    $display("  s now holds 2'b%b", s);
    expect("s holds an encoding no label names", s === 2'b11);
 
    $display("\n3. What the usual diagnostics report about it");
    // name() returns an EMPTY STRING rather than erroring. A $display of the
    // state prints nothing where a name should be, which reads as a format bug.
    $display("  s.name() = \"%s\"  (length %0d)", s.name(), s.name().len());
    expect("name() is empty, not an error", s.name().len() == 0);
 
    $display("\n4. unique case only catches it without a default arm");
    unique case (s)
      IDLE: $display("  IDLE");
      BUSY: $display("  BUSY");
      DONE: $display("  DONE");
      // No default: the tool reports a unique-case no-match violation here.
      // Add `default: ;` to silence a latch warning and this check is gone
      // too - you get one or the other, never both.
    endcase
 
    $display("\n5. The boundary check that prevents all of the above");
    raw = 2'b11;
    if (!$cast(s, raw))
      $display("  rejected 2'b%b at the boundary, as intended", raw);
    else begin
      $display("  accepted an illegal value"); fails++;
    end
 
    $display("\n%0s (%0d failures)\n",
             fails == 0 ? "ALL CHECKS PASSED" : "CHECKS FAILED", fails);
    if (fails) $fatal(1, "enum_illegal_proof failed");
    $finish;
  end
endmodule