// Syntax: `timescale <unit> / <precision>
// Valid unit multipliers: 1, 10, 100
// Valid suffixes: fs, ps, ns, us, ms, s

`timescale 1ns/1ps      // most common RTL: #1 = 1ns, resolution 1ps
`timescale 10ns/1ns    // #1 = 10ns, resolution 1ns
`timescale 1us/100ns   // microcontroller / slow design
`timescale 1ps/1fs     // switch-level / analog-mixed signal

// Effect on delay values in code below this directive:
`timescale 1ns/100ps
always #5     clk = ~clk;       // 5ns period
assign #(2.3) y   = a & b;      // 2.3ns (rounded to 2.3 per 100ps prec)

// ── Rules ────────────────────────────────────────────────────
// ✅ precision ≤ time_unit (1ps ≤ 1ns — legal)
// ❌ precision > time_unit (`timescale 1ps/1ns — ILLEGAL)
// The simulator uses the smallest precision of ALL modules

// ── Common pairing for different use cases ────────────────────
// RTL simulation:        `timescale 1ns/1ps
// Gate-level simulation: `timescale 1ns/100ps  (SDF precision)
// Standard cell models:  `timescale 1ns/1ps
// Testbench w/ real arith: `timescale 1ns/1ps with $timeformat

// ── `define: create a text macro ──────────────────────────────
`define BUS_WIDTH    32              // constant macro
`define CLK_PERIOD   10              // used as #(`CLK_PERIOD/2)
`define RESET_VAL    8'h00           // multi-character value

// Using a macro — prefix with backtick
wire [`BUS_WIDTH-1:0] data;           // expands to wire [31:0] data
always #(`CLK_PERIOD/2) clk=~clk; // expands to #(10/2) = #5

// ── Function-like macros (with arguments) ─────────────────────
`define MIN(a,b)  ((a) < (b) ? (a) : (b))
`define MAX(a,b)  ((a) > (b) ? (a) : (b))
`define ABS(x)   ((x) >= 0 ? (x) : -(x))

assign y = `MIN(a, b);             // expands inline

// ── `undef: remove a macro definition ─────────────────────────
`define DEBUG                       // defined (no value — just a flag)
// ... use `DEBUG in `ifdef blocks ...
`undef  DEBUG                       // undefine — no longer exists

// ── `ifdef / `ifndef / `elsif / `else / `endif ────────────────
`ifdef SYNTHESIS
  // code compiled for synthesis only
  assign y = a & b;
`elsif FPGA_TARGET
  // code compiled for FPGA targets
  fpga_and u1(y, a, b);
`else
  // code compiled otherwise (simulation default)
  and (y, a, b);
`endif

// ── `ifndef: compile if NOT defined ───────────────────────────
`ifndef SYNTHESIS
  initial $monitor("%t y=%b", $time, y); // sim-only
`endif

// ── global_pkg.vh — shared project header ─────────────────────
`ifndef GLOBAL_PKG_VH
`define GLOBAL_PKG_VH                 // include guard

  `timescale 1ns/1ps
  `define DATA_W     32
  `define ADDR_W     10
  `define CLK_PERIOD 10
  `define RESET_ADDR 32'h0000_0000

`endif  // GLOBAL_PKG_VH

// ── axi_master.v — module file using shared header ────────────
`include "global_pkg.vh"   // paste header contents here
`include "axi_defs.vh"     // AXI-specific macros

module axi_master (
  input  [`ADDR_W-1:0] addr,
  input  [`DATA_W-1:0] wdata,
  output [`DATA_W-1:0] rdata
);
  // ... uses macros from included header ...
endmodule

// ── axi_slave.v — same header, guaranteed consistent ──────────
`include "global_pkg.vh"   // guard prevents redefinition error

module axi_slave ( ... );
  // macros identical to axi_master — no inconsistency
endmodule

// ── Hierarchical path names for above design ─────────────────
tb.u_dut                      // DUT module instance
tb.u_dut.u_alu               // ALU inside DUT
tb.u_dut.u_alu.result        // signal inside ALU
tb.u_dut.u_alu.carry_out     // another signal in ALU
tb.u_dut.u_alu.u_adder.sum  // signal 4 levels deep
tb.u_dut.u_regfile.mem[5]   // array element in register file

// ── Things that can have hierarchical names ───────────────────
top.u1.my_wire           // wire / reg / net
top.u1.my_task           // task
top.u1.my_func           // function
top.u1.PARAM_N           // parameter
top.u1.BLK_NAME          // named block

// ── Testbench: read internal DUT signals ─────────────────────
module tb;
  reg  clk, rst_n;
  wire [7:0] out;

  my_dut u_dut(.clk(clk), .rst_n(rst_n), .out(out));

  initial begin
    // Read internal state register
    $display("state = %b", tb.u_dut.state);  // hierarchical read

    // Monitor internal counter
    $monitor("%t cnt=%d", $time, tb.u_dut.u_counter.cnt);

    // Force internal signal (hierarchical drive)
    force   tb.u_dut.state = 3'b101;  // override internal state
    @(posedge clk);
    release tb.u_dut.state;          // release override

    // Read internal memory array element
    $display("mem[0] = %h", tb.u_dut.u_mem.data[0]);
  end
endmodule

// ── defparam: set parameters via hierarchy ────────────────────
my_module u1(...);
defparam tb.u1.WIDTH    = 16;      // override parameter via hier path
defparam tb.u1.u_sub.DEPTH = 64;  // override in sub-instance

module fsm_whitebox_tb;
  reg  clk=0, rst_n, en;
  wire done;

  my_fsm dut(.clk(clk), .rst_n(rst_n), .en(en), .done(done));
  always #5 clk = ~clk;

  // Decode internal state for readability
  reg [2:0] last_state;
  always @(posedge clk) begin
    if (fsm_whitebox_tb.dut.state !== last_state) begin
      $display("%0t: FSM state changed %0d → %0d",
        $time, last_state, fsm_whitebox_tb.dut.state);
      last_state = fsm_whitebox_tb.dut.state;
    end
  end

  initial begin
    // Inject corner case: force specific state
    rst_n=0; #20; rst_n=1;
    repeat(5) @(posedge clk);

    force   fsm_whitebox_tb.dut.state = 3'd6; // FAULT state
    @(posedge clk);
    release fsm_whitebox_tb.dut.state;
    repeat(10) @(posedge clk);
    $finish;
  end
endmodule

initial begin
  // Pre-load instruction memory inside the DUT CPU
  $readmemh("program.hex", tb.u_cpu.u_imem.mem);

  // Pre-load data RAM with test data
  $readmemh("data.hex",    tb.u_cpu.u_dmem.mem);

  // Verify load was successful by reading back first word
  $display("PC reset: imem[0] = %h", tb.u_cpu.u_imem.mem[0]);

  // Read internal register file value after test
  repeat(100) @(posedge clk);
  $display("R0 = %h", tb.u_cpu.u_regfile.regs[0]);
  $display("R1 = %h", tb.u_cpu.u_regfile.regs[1]);
end

primitive udp_majority (out, a, b, c);
  output out;
  input  a, b, c;

  table
  // a  b  c  : out
     0  0  ?  : 0;   // a=0, b=0 → out=0 regardless of c
     0  ?  0  : 0;   // a=0, c=0 → out=0 regardless of b
     ?  0  0  : 0;   // b=0, c=0 → out=0 regardless of a
     1  1  ?  : 1;   // a=1, b=1 → out=1 regardless of c
     1  ?  1  : 1;   // a=1, c=1 → out=1 regardless of b
     ?  1  1  : 1;   // b=1, c=1 → out=1 regardless of a
  endtable
endprimitive

primitive udp_sr_latch(
  q, s, r
);
  output reg q;     // reg for sequential
  input s, r;
  initial q = 1'b0; // power-on state

  table
  // s  r  state : next
     1  0    ?  :  1;  // Set
     0  1    ?  :  0;  // Reset
     0  0    0  :  -;  // Hold 0
     0  0    1  :  -;  // Hold 1
     1  1    ?  :  x;  // Forbidden
     x  0    1  :  1;
     0  x    0  :  0;
  endtable
endprimitive

In a sequential UDP table, the colon separates the current state from the next state: // s r current_state : next_state. The dash - in the output column means “no change — retain current state”.

primitive udp_d_latch (q, d, en);
  output reg q;
  input d, en;
  initial q = 1'b0;

  table
  // d  en  state : next
     0  1    ?  :  0;  // en=1, d=0 → q=0 (transparent)
     1  1    ?  :  1;  // en=1, d=1 → q=1 (transparent)
     ?  0    0  :  -;  // en=0, state=0 → hold 0
     ?  0    1  :  -;  // en=0, state=1 → hold 1
     0  x    0  :  -;  // en=x but d=0 and state=0 → hold
     1  x    1  :  -;  // en=x but d=1 and state=1 → hold
     x  1    ?  :  x;  // d=x when transparent → x
  endtable
endprimitive

primitive udp_jk_ff (q, j, k, clk);
  output reg q;
  input j, k, clk;
  initial q = 1'b0;

  table
  // j  k   clk   state : next
     0  0  (01)   ?   :  -;  // J=0,K=0 → hold
     0  1  (01)   ?   :  0;  // J=0,K=1 → reset
     1  0  (01)   ?   :  1;  // J=1,K=0 → set
     1  1  (01)   0   :  1;  // J=1,K=1, state=0 → toggle → 1
     1  1  (01)   1   :  0;  // J=1,K=1, state=1 → toggle → 0
     ?  ?   n     ?   :  -;  // falling edge → hold
     ?  ?  (0x)   ?   :  -;  // ambiguous edge → hold
     ?  ?  (x1)   ?   :  -;  // ambiguous edge → hold
  endtable
endprimitive

// ── Instantiation with delay ──────────────────────────────────
udp_mux2  #(2, 3)    m1(y, a, b, sel);  // rise=2, fall=3
udp_dff   #(3, 4, 1) ff1(q, d, clk, rst); // rise=3, fall=4, off=1

// ── Instantiation with drive strength ─────────────────────────
udp_mux2  (strong1, strong0)
           #(2, 3) m2(y, a, b, sel);

// ── Array of UDP instances ────────────────────────────────────
udp_dff   ff[7:0](q, d, {8{clk}}, {8{rst}});
// Creates 8 D flip-flop instances — one per bit