Through the Pads: What Your Chip's Pins Do When Nothing Is Connected

// SPDX-License-Identifier: Apache-2.0
// Youblob silicon rung 6: the rung-3 dimmer, made safe to leave unplugged: every input pad gets a pull-down.
// Port list unchanged from wafer-space/gf180mcu-project-template src/chip_core.sv.

`default_nettype none

module chip_core #(
    parameter NUM_INPUT_PADS,
    parameter NUM_BIDIR_PADS,
    parameter NUM_ANALOG_PADS
    )(
    `ifdef USE_POWER_PINS
    inout  wire VDD,
    inout  wire VSS,
    `endif

    input  wire clk,       // clock
    input  wire rst_n,     // reset (active low)

    input  wire [NUM_INPUT_PADS-1:0] input_in,   // Input value
    output wire [NUM_INPUT_PADS-1:0] input_pu,   // Pull-up
    output wire [NUM_INPUT_PADS-1:0] input_pd,   // Pull-down

    input  wire [NUM_BIDIR_PADS-1:0] bidir_in,   // Input value
    output wire [NUM_BIDIR_PADS-1:0] bidir_out,  // Output value
    output wire [NUM_BIDIR_PADS-1:0] bidir_oe,   // Output enable
    output wire [NUM_BIDIR_PADS-1:0] bidir_cs,   // Input type (0=CMOS Buffer, 1=Schmitt Trigger)
    output wire [NUM_BIDIR_PADS-1:0] bidir_sl,   // Slew rate (0=fast, 1=slow)
    output wire [NUM_BIDIR_PADS-1:0] bidir_ie,   // Input enable
    output wire [NUM_BIDIR_PADS-1:0] bidir_pu,   // Pull-up
    output wire [NUM_BIDIR_PADS-1:0] bidir_pd,   // Pull-down

    inout  wire [NUM_ANALOG_PADS-1:0] analog  // Analog
);

    // Pad 0..7: the duty value comes IN.  Pad 8: the PWM goes OUT.  The rest: outputs held low.
    localparam DUTY_W = 8;
    localparam PWM_PAD = 8;

    // An input nobody drives floats: it reads as noise, and so does everything that depends on it.
    // With PULLDOWNS defined, every input pad is pulled low, so an unplugged chip sits disabled at duty 0.
    // (Rung 3 left them all off; build without PULLDOWNS to see what that does.)
    assign input_pu = '0;
`ifdef PULLDOWNS
    assign input_pd = '1;
`else
    assign input_pd = '0;
`endif

    // Output enable only on pads PWM_PAD and above; inputs get their input buffer enabled.
    assign bidir_oe = {{(NUM_BIDIR_PADS-DUTY_W){1'b1}}, {DUTY_W{1'b0}}};
    assign bidir_ie = ~bidir_oe;
    assign bidir_cs = {{(NUM_BIDIR_PADS-DUTY_W){1'b0}}, {DUTY_W{1'b1}}};  // Schmitt trigger on the inputs
    assign bidir_sl = '0;
    assign bidir_pu = '0;
`ifdef PULLDOWNS
    assign bidir_pd = {{(NUM_BIDIR_PADS-DUTY_W){1'b0}}, {DUTY_W{1'b1}}};   // the pad ignores PD while it drives
`else
    assign bidir_pd = '0;
`endif

    wire enable = input_in[0];
    wire [DUTY_W-1:0] duty = bidir_in[DUTY_W-1:0];

    logic [DUTY_W-1:0] count;
    always_ff @(posedge clk) begin
        if (!rst_n)
            count <= '0;
        else if (enable)
            count <= count + 1'b1;
    end

    // High while the free-running count is below the duty value: duty/256 of every period.
    logic pwm;
    always_ff @(posedge clk) begin
        if (!rst_n)
            pwm <= 1'b0;
        else
            pwm <= enable && (count < duty);
    end

    logic [NUM_BIDIR_PADS-1:0] out;
    always_comb begin
        out = '0;
        out[PWM_PAD] = pwm;
    end
    assign bidir_out = out;

    // Inputs this design does not read (keeps lint quiet, as the template does with _unused).
    logic _unused;
    assign _unused = &{1'b0, input_in[NUM_INPUT_PADS-1:1], bidir_in[NUM_BIDIR_PADS-1:DUTY_W]};

endmodule

`default_nettype wire

// SPDX-License-Identifier: Apache-2.0
// The outside world around chip_top: every pad is either driven by the testbench or left floating (z),
// one bit at a time, the way a breakout board with some wires unplugged would leave it.
`default_nettype none
`include "slot_defines.svh"
module tb_pads;
    reg clk = 0, rst_n = 0;
    reg  [`NUM_INPUT_PADS-1:0] in_val = 0, in_drive = 0;
    reg  [`NUM_BIDIR_PADS-1:0] bi_val = 0, bi_drive = 0;

    wire clk_PAD = clk;
    wire rst_n_PAD = rst_n;
    wire [`NUM_INPUT_PADS-1:0] input_PAD;
    wire [`NUM_BIDIR_PADS-1:0] bidir_PAD;
    wire [`NUM_ANALOG_PADS-1:0] analog_PAD;

    genvar i;
    for (i = 0; i < `NUM_INPUT_PADS; i = i + 1) assign input_PAD[i] = in_drive[i] ? in_val[i] : 1'bz;
    for (i = 0; i < `NUM_BIDIR_PADS; i = i + 1) assign bidir_PAD[i] = bi_drive[i] ? bi_val[i] : 1'bz;

    chip_top chip (.clk_PAD(clk_PAD), .rst_n_PAD(rst_n_PAD), .input_PAD(input_PAD),
                   .bidir_PAD(bidir_PAD), .analog_PAD(analog_PAD));

    wire pwm_pad = bidir_PAD[8];
endmodule
`default_nettype wire

# SPDX-License-Identifier: Apache-2.0
# The dimmer tested from OUTSIDE the chip: through the template's chip_top and the PDK's own I/O pad models
# (gf180mcu_fd_io, gf180mcuD, the commit the template pins). Run twice: with and without the pull-downs.
import os
from pathlib import Path

import cocotb
from cocotb.clock import Clock
from cocotb.triggers import ClockCycles, FallingEdge
from cocotb_tools.runner import get_runner

PULLDOWNS = bool(os.getenv("PULLDOWNS"))
HERE = Path(__file__).resolve().parent
PDK = Path(os.getenv("PDK_ROOT", HERE / "pdk")) / "gf180mcuD" / "libs.ref"
TEMPLATE = Path(os.getenv("TEMPLATE", HERE / "template"))


async def power_up(dut):
    cocotb.start_soon(Clock(dut.clk, 40, unit="ns").start())      # 25 MHz, the template's clock constraint
    dut.rst_n.value = 0
    await ClockCycles(dut.clk, 5)
    dut.rst_n.value = 1


def drive_duty(dut, duty, enable=1):
    dut.bi_val.value = duty
    dut.bi_drive.value = 0xFF          # the testbench drives pads 0..7 only; pad 8 is the chip's
    dut.in_val.value = enable
    dut.in_drive.value = 1             # input pad 0 = enable


async def pad_highs(dut, clocks):
    """Count the high clocks on bidir pad 8, and the clocks where it is neither 0 nor 1."""
    high = unknown = 0
    for _ in range(clocks):
        await FallingEdge(dut.clk)
        v = dut.pwm_pad.value
        if not v.is_resolvable:
            unknown += 1
        elif int(v):
            high += 1
    return high, unknown


@cocotb.test()
async def test_duty_through_the_pads(dut):
    """Rung 3's test again, but every signal goes through a real pad model on its way in and out."""
    await power_up(dut)
    for duty in (0, 1, 64, 128, 200, 255):
        drive_duty(dut, duty)
        await ClockCycles(dut.clk, 256)
        high, unknown = await pad_highs(dut, 1024)
        dut._log.info(f"duty {duty:3d}: pad 8 high {high} of 1024 clocks, unknown {unknown}")
        assert unknown == 0 and high == 4 * duty


@cocotb.test()
async def test_duty_pads_unplugged(dut):
    """The eight duty wires come loose. With pull-downs the chip reads 0 and the output stays low;
    without them the core reads X, and the output pad goes unknown."""
    await power_up(dut)
    drive_duty(dut, 200)
    await ClockCycles(dut.clk, 512)
    trace = []
    for _ in range(512):                       # the last 512 clocks while plugged in...
        await FallingEdge(dut.clk)
        trace.append(str(dut.pwm_pad.value))
    dut.bi_drive.value = 0             # the duty pads float
    for _ in range(512):                       # ...and the first 512 after the wires come loose
        await FallingEdge(dut.clk)
        trace.append(str(dut.pwm_pad.value))
    (HERE / f"trace_{'pd' if PULLDOWNS else 'nopd'}.csv").write_text("\n".join(trace))
    high, unknown = await pad_highs(dut, 1024)
    y = dut.chip.bidir_PAD2CORE.value
    dut._log.info(f"pull-downs {'ON ' if PULLDOWNS else 'OFF'}: core sees duty pads as "
                  f"{str(y)[-8:]}; pad 8 high {high}, unknown {unknown} of 1024 clocks")
    if PULLDOWNS:
        assert unknown == 0 and high == 0
    else:
        assert unknown > 0


@cocotb.test()
async def test_output_pad_fight(dut):
    """Something outside drives pad 8 while the chip drives it too: the pad value is unknown.
    In silicon that is two drivers shorting each other."""
    await power_up(dut)
    drive_duty(dut, 128)
    await ClockCycles(dut.clk, 300)
    dut.bi_val.value = 128                          # keep the duty
    dut.bi_drive.value = 0xFF | (1 << 8)            # ...and now also drive pad 8 low from outside
    high, unknown = await pad_highs(dut, 256)
    dut._log.info(f"pad 8 driven from both sides: unknown for {unknown} of 256 clocks")
    assert unknown > 0


def test_runner():
    defines = {"SLOT_0P5X0P5": True, "PDK_gf180mcuD": True, "SCL_gf180mcu_fd_sc_mcu7t5v0": True,
               "PAD_gf180mcu_fd_io": True, "SRAM_gf180mcu_fd_ip_sram": True}
    if PULLDOWNS:
        defines["PULLDOWNS"] = True
    ip = TEMPLATE / "ip"
    sources = [HERE / "chip_top.sv", HERE / "chip_core.sv", HERE / "tb_pads.sv",
               PDK / "gf180mcu_fd_io" / "verilog" / "gf180mcu_fd_io.v"] + \
              [ip / n / "vh" / f"{n}.v" for n in ("gf180mcu_ws_ip__logo", "gf180mcu_ws_ip__marker",
               "gf180mcu_ws_ip__qrcode_id", "gf180mcu_ws_ip__shuttle_id", "gf180mcu_ws_ip__project_id")]
    runner = get_runner("icarus")
    build = f"sim_build_{'pd' if PULLDOWNS else 'nopd'}"
    runner.build(sources=sources, hdl_toplevel="tb_pads", defines=defines, includes=[HERE],
                 build_args=["-g2012"], timescale=("1ns", "1ps"), always=True, build_dir=build)
    runner.test(hdl_toplevel="tb_pads", test_module="test_pads", build_dir=build)


if __name__ == "__main__":
    test_runner()