Port Types — input, output, inout, ref

module mux_2to1 (
    // ── Single-bit inputs ──────────────────────────────────────
    input  logic        sel,       // 1-bit: select line
 
    // ── Multi-bit (bus) inputs ─────────────────────────────────
    input  logic [7:0]  data_a,    // 8-bit: first data bus
    input  logic [7:0]  data_b,    // 8-bit: second data bus
 
    // ── Clock and reset (always inputs, always 1-bit) ──────────
    input  logic        clk,       // clock — drives always_ff
    input  logic        rst_n,     // active-low reset
 
    output logic [7:0]  y
);
 
    // Reading inputs is fine — sel is used to choose data
    assign y = sel ? data_a : data_b;
 
    // ERROR: you cannot do this — sel is an input
    // assign sel = 1'b1;  ← compiler error: cannot drive input port
 
endmodule

module counter_8bit (
    input  logic        clk, rst_n, en,
 
    // ── Combinational output: driven by assign ─────────────────
    output logic        is_zero,    // high when count == 0
 
    // ── Registered output: driven by always_ff ─────────────────
    output logic [7:0]  count       // 8-bit counter value
);
 
    // Registered output — driven by a flip-flop
    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n)    count <= 8'd0;
        else if (en)   count <= count + 8'd1;
    end
 
    // Combinational output — driven by assign (no flip-flop)
    assign is_zero = (count == 8'd0);
 
endmodule

// A simple I2C-style SDA pad model
module bidir_pad (
    input  logic  tx_data,    // data to send onto bus
    input  logic  tx_en,      // 1 = drive the bus, 0 = release (Hi-Z)
    output logic  rx_data,    // data received from bus
    inout  wire   sda         // bidirectional I2C data line
);
 
    // Drive sda when tx_en=1, release to Z when tx_en=0
    // The ternary drives a real tri-state buffer
    assign sda = tx_en ? tx_data : 1'bz;
 
    // Always read the bus value back (regardless of who drives)
    assign rx_data = sda;
 
endmodule

// ref is used in module/task/function arguments — testbench use only
module tb_ref_demo;
 
    int counter;            // variable in the calling scope
 
    // Task that uses 'ref' — shares the caller's variable directly
    task automatic increment (ref int val, input int amount);
        val = val + amount;  // modifies the CALLER's variable in-place
    endtask
 
    initial begin
        counter = 10;
        $display("Before: counter = %0d", counter);  // 10
 
        increment(counter, 5);                        // ref passes 'counter' directly
        $display("After:  counter = %0d", counter);  // 15 — changed by the task
    end
 
endmodule

module port_types_demo (
 
    // ── logic: 4-state (0,1,X,Z) — USE THIS for all RTL ────────
    input  logic         clk,
    input  logic [31:0]  data_in,
    output logic [31:0]  data_out,
 
    // ── wire: used for multi-driver nets and inout ─────────────
    inout  wire          sda,
 
    // ── bit: 2-state (0,1) — no X/Z — testbench stimulus ───────
    input  bit   [7:0]   stim_byte,
 
    // ── integer: signed 32-bit — for counts/indices ────────────
    input  integer       loop_count,
 
    // ── Signed ports: for signed arithmetic ────────────────────
    input  logic signed [15:0] signed_val,
    output logic signed [15:0] signed_result,
 
    // ── No type given → defaults to logic ──────────────────────
    input                implicit_logic   // same as: input logic
 
);
    // ... body
endmodule

module gpio_pad (
 
    // ── input: core-side signals (from the SoC fabric) ─────────
    input  logic  clk,          // system clock
    input  logic  rst_n,        // active-low reset
    input  logic  oe,           // output enable: 1=drive pad, 0=read pad
    input  logic  data_out,     // data to drive onto the pad
 
    // ── output: value sampled from the pad ─────────────────────
    output logic  data_in,      // pad value read back into the SoC
 
    // ── inout: the physical pad — bidirectional ────────────────
    inout  wire   pad           // connects to the package pin / PCB trace
 
);
 
    // ── Drive pad when oe=1, release to Hi-Z when oe=0 ─────────
    assign pad     = oe ? data_out : 1'bz;
 
    // ── Always sample whatever is on the pad ───────────────────
    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) data_in <= 1'b0;
        else        data_in <= pad;    // read the live pad value
    end
 
endmodule
 
 
// ── Testbench using ref to share test state ────────────────────
module tb_gpio;
 
    logic clk = 0, rst_n, oe, data_out, data_in;
    wire  pad;
    int   test_id;        // shared via ref in the task below
 
    // Instantiate DUT
    gpio_pad u_dut (.*);  // .* = connect by name automatically
 
    always #5 clk = ~clk;
 
    // Task uses 'ref' — lets it update test_id in the caller's scope
    task automatic run_test (ref int tid, input logic drive_en, drive_val);
        tid++;                               // modifies caller's test_id
        oe       = drive_en;
        data_out = drive_val;
        @(posedge clk); #1;
        $display("Test %0d: pad=%b data_in=%b", tid, pad, data_in);
    endtask
 
    initial begin
        rst_n = 0; @(posedge clk); rst_n = 1;
        run_test(test_id, 1, 1);   // drive pad high
        run_test(test_id, 1, 0);   // drive pad low
        run_test(test_id, 0, 0);   // release pad (Hi-Z)
        $finish;
    end
 
endmodule

module tb_bidir;
    logic      clk;
    logic      oe_tb;        // testbench output-enable
    logic      tx_tb;        // data testbench wants to send
    wire       bus;          // the shared bidirectional wire
 
    // Tri-state driver from testbench side
    // When oe_tb=1 testbench drives, when oe_tb=0 it releases
    assign bus = oe_tb ? tx_tb : 1'bz;
 
    // DUT instance
    bidir_pad u_dut (
        .tx_data  (1'b0),
        .tx_en    (dut_oe),
        .rx_data  (),
        .sda      (bus)       // connects to same wire
    );
 
    initial begin
        oe_tb = 1'b0; tx_tb = 1'b0;   // start released
        #10; oe_tb = 1'b1; tx_tb = 1'b1; // TB drives high
        #20; oe_tb = 1'b0;               // TB releases
        // DUT can now drive bus
    end
endmodule

Time(ns)  oe_a  tx_a  oe_b  tx_b  bus    Event
──────────┬─────┬─────┬─────┬─────┬──────┬──────────────────────────
0         │ 0   │ 0   │ 0   │ 0   │ Z    │ both released, bus floats
10        │ 1   │ 1   │ 0   │ 0   │ 1    │ A drives high (B released)
20        │ 1   │ 0   │ 0   │ 0   │ 0    │ A drives low
30        │ 0   │ 0   │ 0   │ 0   │ Z    │ A releases — turnaround gap
35        │ 0   │ 0   │ 1   │ 0   │ 0    │ B takes bus, drives low (ACK)
50        │ 0   │ 0   │ 1   │ 1   │ 1    │ B drives high
60        │ 0   │ 0   │ 0   │ 0   │ Z    │ B releases — bus idle

Time(ns)  oe_a  tx_a  oe_b  tx_b  bus    Event
──────────┬─────┬─────┬─────┬─────┬──────┬──────────────────────────
0         │ 0   │ 0   │ 0   │ 0   │ Z    │ idle
10        │ 1   │ 1   │ 0   │ 0   │ 1    │ A drives high (OK)
20        │ 1   │ 1   │ 1   │ 0   │ X    │ CONTENTION: A=1, B=0 simultaneously
30        │ 1   │ 1   │ 1   │ 1   │ 1    │ both agree (1) — X clears, but damage done
40        │ 0   │ 0   │ 1   │ 0   │ 0    │ A released, B drives low
──────────┴─────┴─────┴─────┴─────┴──────┴──────────────────────────
// At t=20 the bus value is X — in real silicon this is a physical short circuit

module tb_bidir_complete;
 
    // ── Signals ─────────────────────────────────
    logic  clk = 0;
    logic  rst_n;
    wire   sda;              // shared inout wire
 
    // ── Testbench-side bus driver ──────────────
    logic  tb_oe  = 0;       // testbench output-enable
    logic  tb_tx  = 0;       // testbench drive value
    assign sda = tb_oe ? tb_tx : 1'bz;
 
    // ── DUT ────────────────────────────────────
    logic  dut_oe;
    logic  rx_captured;
    bidir_pad u_dut (
        .tx_data (tb_tx),
        .tx_en   (dut_oe),
        .rx_data (rx_captured),
        .sda     (sda)
    );
 
    // ── Clock ──────────────────────────────────
    always #5 clk = ~clk;
 
    // ── Contention assertion ───────────────────
    property no_contention;
        @(posedge clk) not (tb_oe && dut_oe);
    endproperty
    assert property(no_contention)
        else $fatal(1, "Contention: tb_oe and dut_oe both high!");
 
    // ── Test sequence ──────────────────────────
    initial begin
        rst_n = 0; dut_oe = 0;
        repeat(2) @(posedge clk);
        rst_n = 1;
 
        // TB drives bus high
        @(posedge clk); #1;
        tb_oe = 1; tb_tx = 1;
        @(posedge clk); #1;
        assert(sda === 1'b1) else $error("FAIL: sda should be 1");
 
        // TB releases, DUT drives
        tb_oe = 0;
        @(posedge clk); #1;
        dut_oe = 1;
        @(posedge clk); #1;
        assert(rx_captured === sda)
            else $error("FAIL: rx_data mismatch");
 
        $display("ALL CHECKS PASSED"); $finish;
    end
 
endmodule

covergroup bidir_bus_cg @(posedge clk);
 
    // Cover all four bus states
    cp_bus_val: coverpoint sda {
        bins bus_low   = {1'b0};    // bus actively driven low
        bins bus_high  = {1'b1};    // bus actively driven high
        bins bus_hiz   = {1'bz};    // bus released (Hi-Z)
        bins bus_x     = {1'bx};    // contention — should NEVER hit
    }
 
    // Cover who owns the bus
    cp_oe_owner: coverpoint {tb_oe, dut_oe} {
        bins neither    = {2'b00};   // both released
        bins tb_only    = {2'b10};   // testbench drives
        bins dut_only   = {2'b01};   // DUT drives
        illegal_bins contention = {2'b11}; // both — illegal!
    }
 
    // Cross: who owns × what value
    cx_owner_val: cross cp_oe_owner, cp_bus_val;
 
endgroup

// ════ MISTAKE 1: Driving an input port ════════════════════════════
module bad1 (input logic sel, output logic y);
    assign sel = 1'b1;    // ❌ ERROR: cannot drive an input port
    assign y   = sel;
endmodule
 
// ✅ FIX: change sel to output if the module should drive it
module good1 (output logic sel, output logic y);
    assign sel = 1'b1;    // ✅ OK: sel is an output now
    assign y   = sel;
endmodule
 
 
// ════ MISTAKE 2: Using logic for a multi-driver inout ═════════════
module bad2 (inout logic sda);   // ❌ logic can't model multi-driver
    assign sda = 1'bz;
endmodule
 
// ✅ FIX: use wire for bidirectional multi-driver nets
module good2 (inout wire sda);    // ✅ wire resolves multiple drivers correctly
    assign sda = 1'bz;
endmodule
 
 
// ════ MISTAKE 3: Forgetting to release to Z in inout ══════════════
module bad3 (input logic tx_en, input logic tx_d, inout wire bus);
    assign bus = tx_d;     // ❌ Always drives — never releases — bus fights!
endmodule
 
// ✅ FIX: always use the tri-state ternary pattern
module good3 (input logic tx_en, input logic tx_d, inout wire bus);
    assign bus = tx_en ? tx_d : 1'bz;  // ✅ releases when not driving
endmodule

// ── input: driven by parent, read by module ───────────────────
input  logic        single_bit,
input  logic [7:0]  byte_bus,
input  logic        clk,         // clock is always input
input  logic        rst_n,       // reset is always input
 
// ── output: driven by module, read by parent ──────────────────
output logic        flag,
output logic [15:0] result,
 
// ── inout: bidirectional tri-state — use wire ─────────────────
inout  wire         sda,         // I2C data
inout  wire  [7:0]  data_bus,    // 8-bit bidirectional bus
 
// ── ref: pass by reference — testbench/task only ──────────────
ref    int          counter,     // modifies caller's variable
ref    logic        flag_ref,
 
// ── Tri-state driver pattern (always use this for inout) ──────
assign sda = tx_en ? tx_data : 1'bz;   // drive or release
assign rx  = sda;                       // always read the bus