Package-Level Parameters & Types

// ── axi4_cfg_pkg.sv — clear parameter hierarchy ────────────────────
package axi4_cfg_pkg;
 
    // ── "Knobs" — values that may be reconfigured at compile time ──
    parameter int AXI_DATA_W = 64;    // primary bus data width
    parameter int AXI_ADDR_W = 40;    // address width
    parameter int AXI_ID_W   = 8;     // transaction ID width
    parameter int AXI_LEN_W  = 8;     // burst length field width
 
    // ── Derived constants — computed from knobs, immutable ─────────
    localparam int AXI_STRB_W  = AXI_DATA_W / 8;
    localparam int AXI_WDATA_B = AXI_DATA_W / 8;     // bytes per beat
    localparam int AXI_MAX_LEN = (1 << AXI_LEN_W);   // max burst length
 
    // ── Protocol fixed constants — never user-configurable ─────────
    localparam logic [1:0] RESP_OKAY   = 2'b00;
    localparam logic [1:0] RESP_EXOKAY = 2'b01;
    localparam logic [1:0] RESP_SLVERR = 2'b10;
    localparam logic [1:0] RESP_DECERR = 2'b11;
 
endpackage : axi4_cfg_pkg
 
// ── Consumer ───────────────────────────────────────────────────────
module axi_slave
    import axi4_cfg_pkg::*;
(
    input  logic [AXI_DATA_W-1:0] wdata,
    input  logic [AXI_STRB_W-1:0] wstrb,    // derived localparam — visible too
    output logic [1:0]            bresp
);
    assign bresp = RESP_OKAY;
endmodule

package opcode_pkg;
 
    // ── Basic enum — base type defaults to int (32 bits — usually wrong)
    typedef enum {
        OP_NOP   = 0,
        OP_ADD   = 1,
        OP_SUB   = 2,
        OP_AND   = 3,
        OP_OR    = 4,
        OP_XOR   = 5,
        OP_SHIFT = 6
    } opcode_e;                            // _e suffix convention
 
    // ── Sized enum — hardware-friendly, maps to exact bit width ────
    typedef enum logic [2:0] {
        ST_IDLE   = 3'b000,
        ST_FETCH  = 3'b001,
        ST_DECODE = 3'b010,
        ST_EXEC   = 3'b011,
        ST_WB     = 3'b100
    } cpu_state_e;
 
    // ── One-hot encoding — common in FSMs ──────────────────────────
    typedef enum logic [4:0] {
        ARB_IDLE = 5'b00001,
        ARB_GNT0 = 5'b00010,
        ARB_GNT1 = 5'b00100,
        ARB_GNT2 = 5'b01000,
        ARB_GNT3 = 5'b10000
    } arb_state_e;
 
    // ── Enum without explicit values — auto-increments from 0 ──────
    typedef enum logic [1:0] {
        PRIO_LOW, PRIO_MED, PRIO_HIGH, PRIO_CRIT
    } priority_e;
 
endpackage : opcode_pkg
 
// ── Using package enums ────────────────────────────────────────────
module cpu_fsm
    import opcode_pkg::*;
(
    input  logic       clk, rst_n,
    output cpu_state_e state
);
    cpu_state_e next_state;
 
    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) state <= ST_IDLE;
        else        state <= next_state;
    end
 
    always_comb begin
        unique case (state)
            ST_IDLE  : next_state = ST_FETCH;
            ST_FETCH : next_state = ST_DECODE;
            ST_DECODE: next_state = ST_EXEC;
            ST_EXEC  : next_state = ST_WB;
            ST_WB    : next_state = ST_IDLE;
            default  : next_state = ST_IDLE;
        endcase
    end
endmodule
 
// ── Casting between enum and logic ─────────────────────────────────
logic [2:0] raw_bits = 3'b010;
opcode_pkg::cpu_state_e decoded;
 
decoded = opcode_pkg::cpu_state_e'(raw_bits);    // explicit cast — safe
// Without the cast: assigning logic to enum is a type error in strict tools

package axi4_types_pkg;
    import axi4_cfg_pkg::*;                // bring in DATA_W, ADDR_W, etc.
 
    // ── AW channel — packed: maps to a single logic vector ─────────
    typedef struct packed {
        logic [AXI_ID_W-1:0]   awid;
        logic [AXI_ADDR_W-1:0] awaddr;
        logic [AXI_LEN_W-1:0]  awlen;
        logic [2:0]            awsize;
        logic [1:0]            awburst;
        logic                  awvalid;
    } axi_aw_t;
 
    // ── W channel ──────────────────────────────────────────────────
    typedef struct packed {
        logic [AXI_DATA_W-1:0] wdata;
        logic [AXI_STRB_W-1:0] wstrb;
        logic                  wlast;
        logic                  wvalid;
    } axi_w_t;
 
    // ── B channel ──────────────────────────────────────────────────
    typedef struct packed {
        logic [AXI_ID_W-1:0] bid;
        logic [1:0]          bresp;
        logic                bvalid;
    } axi_b_t;
 
    // ── Full write bundle — struct of structs ──────────────────────
    typedef struct packed {
        axi_aw_t aw;
        axi_w_t  w;
    } axi_wr_req_t;
 
endpackage : axi4_types_pkg
 
// ── Packed struct in module signals ────────────────────────────────
module axi_master
    import axi4_types_pkg::*;
(
    output axi_aw_t aw,           // entire AW channel as one port
    output axi_w_t  w,
    input  axi_b_t  b
);
    localparam int AW_BITS = $bits(axi_aw_t);   // $bits works on packed types
 
    // Field access via dot notation
    assign aw.awburst = 2'b01;    // INCR burst
    assign aw.awsize  = 3'd3;     // 8-byte beats
endmodule
 
// ── Casting packed struct to/from logic vector ─────────────────────
logic [$bits(axi_aw_t)-1:0] raw;
axi4_types_pkg::axi_aw_t    aw_decoded;
 
aw_decoded = axi4_types_pkg::axi_aw_t'(raw);    // raw bits → struct

package tb_types_pkg;
 
    // ── Unpacked struct — fields may be any type ───────────────────
    typedef struct {                       // no 'packed' keyword
        logic [31:0] addr;
        logic [63:0] data;
        int          timestamp;            // int allowed in unpacked only
        string       tag;                  // string allowed in unpacked only
        bit          is_write;
    } txn_record_t;
 
    typedef enum logic [1:0] { CHK_PASS, CHK_FAIL, CHK_SKIP } chk_result_e;
 
    typedef struct {
        string       test_name;
        chk_result_e result;
        int          error_count;
    } test_report_t;
 
endpackage : tb_types_pkg
 
// ── Scoreboard using the package types ─────────────────────────────
class Scoreboard;
    import tb_types_pkg::*;
 
    txn_record_t  exp_q[$];                // queue of expected transactions
    txn_record_t  got_q[$];                // queue of observed transactions
    test_report_t report;
 
    function void check(txn_record_t exp, txn_record_t got);
        if (exp.addr !== got.addr || exp.data !== got.data) begin
            report.result = CHK_FAIL;
            report.error_count++;
        end
    endfunction
endclass

package instr_pkg;
 
    // ── R-type instruction — 32 bits ───────────────────────────────
    typedef struct packed {
        logic [6:0] funct7;
        logic [4:0] rs2;
        logic [4:0] rs1;
        logic [2:0] funct3;
        logic [4:0] rd;
        logic [6:0] opcode;
    } r_type_t;                            // 7+5+5+3+5+7 = 32 bits
 
    // ── I-type instruction — 32 bits ───────────────────────────────
    typedef struct packed {
        logic [11:0] imm12;
        logic [4:0]  rs1;
        logic [2:0]  funct3;
        logic [4:0]  rd;
        logic [6:0]  opcode;
    } i_type_t;                            // 12+5+3+5+7 = 32 bits
 
    // ── Union — same 32 bits, viewed as R-type, I-type, or raw word
    typedef union packed {
        r_type_t     r;                    // R-format view
        i_type_t     i;                    // I-format view
        logic [31:0] raw;                  // raw 32-bit view
    } instr_t;                             // all members MUST be 32 bits
 
endpackage : instr_pkg
 
// ── Decode unit uses the union ─────────────────────────────────────
module decode
    import instr_pkg::*;
(
    input  instr_t instr,
    output logic   is_rtype
);
    assign is_rtype = (instr.r.opcode == 7'b0110011);
 
    always_comb begin
        unique case (instr.r.opcode)
            7'b0110011:                    // R-type — use instr.r fields
                $display("R-type: rd=%0d rs1=%0d rs2=%0d",
                         instr.r.rd, instr.r.rs1, instr.r.rs2);
            7'b0010011:                    // I-type — use instr.i fields
                $display("I-type: rd=%0d rs1=%0d imm=%0d",
                         instr.i.rd, instr.i.rs1, $signed(instr.i.imm12));
            default: $display("raw=%08h", instr.raw);
        endcase
    end
endmodule

package bus_types_pkg;
    parameter int DATA_W = 64;
    parameter int ADDR_W = 40;
 
    // ── Simple bit-vector aliases ──────────────────────────────────
    typedef logic [DATA_W-1:0]    data_t;
    typedef logic [ADDR_W-1:0]    addr_t;
    typedef logic [DATA_W/8-1:0]  strb_t;
 
    // ── Struct built from the aliases ──────────────────────────────
    typedef struct packed {
        addr_t addr;
        data_t data;
        strb_t strb;
        logic  valid;
        logic  last;
    } beat_t;
 
    // ── Derived localparam from $bits() ────────────────────────────
    localparam int BEAT_BITS  = $bits(beat_t);          // total beat width
    localparam int BEAT_BYTES = BEAT_BITS / 8;          // bytes per beat
    localparam int FIFO_DEPTH = 2 ** $clog2(BEAT_BYTES * 4);
 
endpackage : bus_types_pkg
 
// ── Consumer — widths cascade from the single parameter ───────────
module beat_fifo
    import bus_types_pkg::*;
(
    input  logic  clk, rst_n,
    input  beat_t din,
    input  logic  push,
    output beat_t dout,
    output logic  full, empty
);
    beat_t mem [FIFO_DEPTH];               // FIFO_DEPTH computed from $bits(beat_t)
    // ...
endmodule

// ── Approach C — parameterised class as a type factory ─────────────
package generic_types_pkg;
 
    class FifoTypes #(int DATA_W = 32, int DEPTH = 16);
        typedef logic [DATA_W-1:0]       data_t;
        typedef logic [$clog2(DEPTH):0]  ptr_t;       // pointer needs +1 bit
        typedef struct packed {
            data_t entry;
            ptr_t  rd_ptr;
            ptr_t  wr_ptr;
        } fifo_status_t;
    endclass
 
endpackage : generic_types_pkg
 
// ── Consumer — specialise the class to get the needed types ───────
module sync_fifo #(
    parameter int DATA_W = 32,
    parameter int DEPTH  = 16
);
    // Create a local alias for the specialised type set
    typedef generic_types_pkg::FifoTypes #(DATA_W, DEPTH) T;
 
    T::data_t        mem [DEPTH];          // element storage
    T::ptr_t         rd_ptr, wr_ptr;       // pointers
    T::fifo_status_t status;
endmodule
 
// ── Approach B — local typedef inside each module (more common) ───
module simple_fifo #(
    parameter int DATA_W = 8,
    parameter int DEPTH  = 4
);
    typedef logic [DATA_W-1:0] data_t;     // local typedef — straightforward
    data_t mem [DEPTH];
endmodule

// ── File: spi_pkg.sv ───────────────────────────────────────────────
package spi_pkg;
 
    // ── Configuration knobs (parameter — user may override at compile)
    parameter int SPI_DATA_W   = 8;        // bits per SPI frame
    parameter int SPI_CLK_DIV  = 4;        // SCLK = system_clk / CLK_DIV
    parameter int SPI_CS_COUNT = 4;        // number of chip selects
 
    // ── Derived constants (localparam — computed, immutable) ───────
    localparam int SPI_HALF_CLK = SPI_CLK_DIV / 2;
    localparam int SPI_CS_W     = $clog2(SPI_CS_COUNT);
    localparam int SPI_CNT_W    = $clog2(SPI_DATA_W);
 
    // ── Clock polarity/phase (CPOL, CPHA) mode ─────────────────────
    typedef enum logic [1:0] {
        SPI_MODE0 = 2'b00,                 // CPOL=0, CPHA=0
        SPI_MODE1 = 2'b01,                 // CPOL=0, CPHA=1
        SPI_MODE2 = 2'b10,                 // CPOL=1, CPHA=0
        SPI_MODE3 = 2'b11                  // CPOL=1, CPHA=1
    } spi_mode_e;
 
    typedef enum logic {
        SPI_MSB_FIRST = 1'b0,
        SPI_LSB_FIRST = 1'b1
    } spi_bit_order_e;
 
    // ── Transaction descriptor ─────────────────────────────────────
    typedef struct packed {
        logic [SPI_CS_W-1:0]   cs_sel;     // which CS to assert
        spi_mode_e             mode;
        spi_bit_order_e        bit_order;
        logic [SPI_DATA_W-1:0] tx_data;
    } spi_txn_t;
 
    // ── Status from controller back to SW ──────────────────────────
    typedef struct packed {
        logic [SPI_DATA_W-1:0] rx_data;
        logic                  busy;
        logic                  done;
        logic                  rx_valid;
    } spi_status_t;
 
    // ── Utility — extract CPOL/CPHA from mode ──────────────────────
    function automatic logic get_cpol(input spi_mode_e m);
        return m[1];
    endfunction
 
    function automatic logic get_cpha(input spi_mode_e m);
        return m[0];
    endfunction
 
    // ── Utility — reverse bit order for LSB-first transfers ────────
    function automatic logic [SPI_DATA_W-1:0] reverse_bits(
        input logic [SPI_DATA_W-1:0] d
    );
        for (int i = 0; i < SPI_DATA_W; i++)
            reverse_bits[i] = d[SPI_DATA_W-1-i];
    endfunction
 
endpackage : spi_pkg
 
// ── DUT imports the package ────────────────────────────────────────
module spi_controller
    import spi_pkg::*;
(
    input  logic                    clk, rst_n,
    input  spi_txn_t                txn_in,
    input  logic                    txn_valid,
    output spi_status_t             status,
    output logic                    sclk, mosi,
    input  logic                    miso,
    output logic [SPI_CS_COUNT-1:0] cs_n
);
    logic cpol, cpha;
    assign cpol = get_cpol(txn_in.mode);
    assign cpha = get_cpha(txn_in.mode);
endmodule

// ── Parameters ─────────────────────────────────────────────────────
parameter  int DATA_W = 64;          // knob — possible tool-level override
localparam int STRB_W = DATA_W/8;    // derived — explicitly immutable
// NEITHER can be overridden via #()  — packages are not instantiated
// Declare base parameters BEFORE the derived localparams — order matters
 
// ── Enum ───────────────────────────────────────────────────────────
typedef enum logic [N-1:0] { A=0, B=1 } myenum_e;   // ALWAYS size base type
// _e suffix for enum types; ALL_CAPS for literals; use unique case in FSMs
my_e val = my_e'(raw_bits);          // cast logic → enum (explicit)
 
// ── Packed struct (hardware signal) ────────────────────────────────
typedef struct packed {
    logic [A-1:0] f1;
    logic [B-1:0] f2;
} mystruct_t;
// _t suffix; only bit-type fields; $bits(mystruct_t) → total width
 
// ── Unpacked struct (testbench / class) ────────────────────────────
typedef struct { int count; string name; logic flag; } tb_rec_t;
// Holds any type; cannot appear on hardware port; no $bits() constraint
 
// ── Packed union (overlapping interpretations) ─────────────────────
typedef union packed { struct_a_t a; struct_b_t b; logic [N-1:0] raw; } u_t;
// All members MUST have identical total bit width
 
// ── Type alias ─────────────────────────────────────────────────────
typedef logic [DATA_W-1:0] data_t;
localparam int DATA_BITS = $bits(data_t);    // $bits on typedef = const int
 
// ── Eight rules to live by ─────────────────────────────────────────
// 1.  parameter in a package = configurable; localparam = explicitly immutable.
// 2.  Declare base parameters BEFORE the localparams that reference them.
// 3.  Always size enum base types: 'typedef enum logic [N:0]' — never bare.
// 4.  Use 'struct packed' for hardware; plain 'struct' for testbench objects.
// 5.  All packed union members must have identical bit widths.
// 6.  $bits(pkg_type) is a compile-time constant — legal in port/param widths.
// 7.  Parameterised typedef is NOT valid SV — use parameterised class workaround.
// 8.  Naming: _e for enums, _t for structs/unions/aliases, ALL_CAPS for literals.