Your Own chip_core: An 8-bit PWM Dimmer, Tested Before It Is Silicon

// SPDX-License-Identifier: Apache-2.0
// Youblob silicon rung 3: an 8-bit PWM dimmer in place of the template's counter.
// 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;

    assign input_pu = '0;
    assign input_pd = '0;

    // 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;
    assign bidir_pd = '0;

    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
# cocotb testbench for the PWM dimmer core, at the chip_core level (no pads, no PDK needed).
import os
from pathlib import Path

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

PERIOD = 256          # clock cycles in one PWM period (8-bit count)
PWM_PAD = 8


async def start(dut):
    cocotb.start_soon(Clock(dut.clk, 20, unit="ns").start())   # 50 MHz, as the template's testbench
    dut.input_in.value = 0
    dut.bidir_in.value = 0
    dut.rst_n.value = 0
    await ClockCycles(dut.clk, 5)
    dut.rst_n.value = 1


async def high_cycles(dut, cycles):
    n = 0
    for _ in range(cycles):
        await RisingEdge(dut.clk)
        n += int(dut.bidir_out.value[PWM_PAD])
    return n


@cocotb.test()
async def test_duty(dut):
    """Over whole PWM periods the output is high exactly duty/256 of the time."""
    await start(dut)
    dut.input_in.value = 1                      # enable
    for duty in (0, 1, 64, 128, 200, 255):
        dut.bidir_in.value = duty
        await ClockCycles(dut.clk, PERIOD)      # let one full period pass with the new value
        high = await high_cycles(dut, 4 * PERIOD)
        dut._log.info(f"duty {duty:3d}: high {high} of {4 * PERIOD} cycles")
        assert high == 4 * duty, f"duty {duty}: expected {4 * duty} high cycles, got {high}"


@cocotb.test()
async def test_disable(dut):
    """With the enable input low the output stays low, whatever the duty."""
    await start(dut)
    dut.input_in.value = 0
    dut.bidir_in.value = 200
    assert await high_cycles(dut, 2 * PERIOD) == 0


@cocotb.test()
async def test_pad_directions(dut):
    """Pads 0-7 are inputs (oe low, ie high); pad 8 and above are outputs."""
    await start(dut)
    oe = int(dut.bidir_oe.value)
    ie = int(dut.bidir_ie.value)
    assert oe & 0xFF == 0 and ie & 0xFF == 0xFF
    assert (oe >> 8) & 1 == 1 and (ie >> 8) & 1 == 0


def test_runner():
    here = Path(__file__).resolve().parent
    runner = get_runner(os.getenv("SIM", "icarus"))
    runner.build(
        sources=[here / "chip_core.sv"],
        hdl_toplevel="chip_core",
        parameters={"NUM_INPUT_PADS": 4, "NUM_BIDIR_PADS": 38, "NUM_ANALOG_PADS": 4},  # the 0p5x0p5 slot
        build_args=["-g2012"],
        timescale=("1ns", "1ps"),
        always=True,
    )
    runner.test(hdl_toplevel="chip_core", test_module="test_pwm")


if __name__ == "__main__":
    test_runner()