setup testbench structure and add getting started example

Author: builderdev212

.github/workflows/main.yml

@@ -0,0 +1,11 @@
+name: python-black
+on: [push, pull_request]
+jobs:
+  linter_name:
+    name: runner / black formatter
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: rickstaa/action-black@v1
+        with:
+          black_args: ". --check"

.gitignore

@@ -0,0 +1,5 @@
+*.venv/
+*.pytest_cache/
+*__pycache__/
+*sim_build/
+*.log

Containerfile

@@ -0,0 +1,46 @@
+# Setup dependancy versions
+ARG DEBIAN_VERSION=12
+ 
+FROM docker.io/library/debian:${DEBIAN_VERSION}
+ 
+RUN apt-get update && apt-get upgrade -y && \
+    apt-get install -y \
+    python3.11 \
+    python3-pip \
+    python3-venv \
+    autoconf gperf make gcc g++ bison flex \
+    git help2man perl perl-doc \
+    libfl2 libfl-dev \
+    ccache mold libgoogle-perftools-dev numactl \
+    zlib1g zlib1g-dev \
+    gtkwave
+
+# Setup verilator
+WORKDIR /usr/src/
+ENV VERILATOR_VERSION=5.020
+RUN git clone https://github.com/verilator/verilator.git
+WORKDIR /usr/src/verilator
+RUN git checkout v${VERILATOR_VERSION}
+RUN autoconf && ./configure && make -j `nproc` && make install
+WORKDIR /usr/src/
+ 
+# compile and install iverilog
+WORKDIR /usr/src/
+RUN git clone https://github.com/steveicarus/iverilog.git
+WORKDIR /usr/src/iverilog/
+RUN sh autoconf.sh && ./configure --prefix /usr && make && make install
+ 
+WORKDIR /usr/src/
+# setup python virtual environment
+ENV VIRTUAL_ENV=.venv
+RUN python3 -m venv ${VIRTUAL_ENV}
+ENV PATH="${VIRTUAL_ENV}/bin:$PATH"
+
+RUN pip3 install wheel
+# install needed python libraries
+COPY requirements.txt .
+RUN pip3 install -r requirements.txt && \
+    rm requirements.txt
+ 
+# jank way to activate the virtual environment
+ENTRYPOINT . .venv/bin/activate && /bin/bash

Makefile

@@ -0,0 +1,25 @@
+CONTAINER_IMG := cocotb-dev
+CONTAINER_FILE := Containerfile
+
+build::
+	@podman build -f ${CONTAINER_FILE} -t ${CONTAINER_IMG} "${PWD}"
+
+# publish::
+# 	@podman login
+# 	@podman push ${CONTAINER_IMG}:latest
+
+run::
+	@podman run -it --rm \
+	    -e DISPLAY \
+	    -v "/tmp/.X11-unix":"/tmp/.X11-unix" \
+	    -v "${XAUTHORITY}":"/root/.Xauthority" \
+		-v "${PWD}":"/usr/src/verilogbits/" \
+	    --ipc host \
+	    ${CONTAINER_IMG}
+
+clean::
+	@find . -type d -name "*__pycache__" -exec echo {} + -exec rm -rf {} +
+	@find . -type d -name "*.pytest_cache" -exec echo {} + -exec rm -rf {} +
+	@find . -type d -name "*sim_build" -exec echo {} + -exec rm -rf {} +
+	@find . -type d -name "*.venv" -exec echo {} + -exec rm -rf {} +
+	@find . -name "verilogbits.log" -exec echo {} + -exec rm -rf {} +

README.md

@@ -1,2 +1,9 @@
 # verilogbits
 My solutions and my own tests for problems from the HDLBits website.
+
+## Setting up a virtual environment
+```bash
+python3 -m venv .venv --prompt verilogbits
+source .venv/bin/activate
+pip3 install -r requirements.txt
+```

problems/getting-started/getting-started/rtl/constant_one.v

@@ -0,0 +1,11 @@
+`resetall
+`timescale 1ns / 1ps
+`default_nettype none
+
+module constant_one (
+    output wire one
+);
+
+    assign one = 1;
+
+endmodule

problems/getting-started/getting-started/tb/constant_one.py

@@ -0,0 +1,24 @@
+import logging
+
+
+class DataError(Exception):
+    pass
+
+
+class TB:
+    def __init__(self, dut):
+        self.dut = dut
+
+        # Start logging
+        self.log = logging.getLogger("cocotb.tb")
+        self.log.setLevel(logging.DEBUG)
+
+        # Simulation Signals
+        self.get_signals()
+
+    def get_signals(self):
+        self.one = self.dut.one
+
+    async def one_check(self):
+        if int(self.one.value) != 1:
+            raise DataError(f"Output should always be 1, got {self.one.value} instead.")

problems/getting-started/getting-started/tb/test_constant_one.py

@@ -0,0 +1,58 @@
+import os
+import pytest
+import cocotb
+from cocotb.clock import Timer
+from cocotb.regression import TestFactory
+from cocotb_test.simulator import run
+
+from top_module import TB
+
+
+async def output_stays_one(dut):
+    tb = TB(dut)
+
+    tb.log.info("Checking output value...")
+    # Await one nanosecond so the model can start.
+    await Timer(1, units="ns")
+    tb.one_check()
+
+
+if cocotb.SIM_NAME:
+    test1 = TestFactory(output_stays_one)
+    test1.generate_tests()
+
+# cocotb-test
+
+tests_dir = os.path.abspath(os.path.dirname(__file__))
+rtl_dir = os.path.abspath(os.path.join(tests_dir, "..", "rtl"))
+
+parameter_list = [{}]
+
+
+@pytest.mark.parametrize("parameters", parameter_list)
+def test_constant_one(request, parameters):
+    dut = "constant_one"
+    module = os.path.splitext(os.path.basename(__file__))[0]
+    toplevel = dut
+
+    verilog_sources = [
+        os.path.join(rtl_dir, f"{dut}.v"),
+    ]
+
+    extra_env = {f"PARAM_{k}": str(v) for k, v in parameters.items()}
+
+    sim_build = os.path.join(
+        tests_dir, "sim_build", request.node.name.replace("[", "-").replace("]", "")
+    )
+
+    run(
+        python_search=[tests_dir],
+        verilog_sources=verilog_sources,
+        toplevel=toplevel,
+        module=module,
+        parameters=parameters,
+        sim_build=sim_build,
+        extra_env=extra_env,
+        compile_args=["--timing", "-O3"],
+        waves=True,
+    )

pytest.ini

@@ -0,0 +1,10 @@
+[pytest]
+env =
+    SIM=verilator
+    CXXFLAGS=-std=c++14
+    WAVES=0
+    
+log_file = verilogbits.log
+log_file_level = DEBUG
+testpaths =
+    problems/getting-started/getting-started/tb/test_constant_one.py

requirements.txt

@@ -0,0 +1,7 @@
+cocotb == 1.8.1
+cocotb-test == 0.2.5
+pytest == 7.4.3
+pytest-xdist == 3.5.0
+pytest-sugar == 0.9.7
+pytest-env == 1.1.3
+pytest-retry == 1.6.1