Extend verilator main loop to support clock generation in C++

cocotb/share/lib/verilator/verilator.cpp

@@ -23,6 +23,11 @@
 
 static vluint64_t main_time = 0;       // Current simulation time
 
+#ifdef VERILATOR_USRCLK_FILE
+static vluint64_t next_user_clock_time = 0;
+vluint64_t user_clock_cb(std::unique_ptr<Vtop> & topp, vluint64_t current_time);
+#endif
+
 double sc_time_stamp() {       // Called by $time in Verilog
     return main_time;           // converts to double, to match
                                 // what SystemC does
@@ -75,6 +80,18 @@ int main(int argc, char** argv) {
 #endif
 
     while (!Verilated::gotFinish()) {
+
+#ifdef VERILATOR_USRCLK_FILE
+        // Call user callback for clock toggle
+        if (main_time == next_user_clock_time) {
+            next_user_clock_time = user_clock_cb(top, main_time);
+
+            // Call Value Change callbacks triggered by clock toggle
+            // These can modify signal values
+            settle_value_callbacks();
+        }
+#endif
+
         // Call registered timed callbacks (e.g. clock timer)
         // These are called at the beginning of the time step
         // before the iterative regions (IEEE 1800-2012 4.4.1)
@@ -112,14 +129,19 @@ int main(int argc, char** argv) {
         // skip ahead to the next registered callback
         vluint64_t next_time = VerilatedVpi::cbNextDeadline();
 
+#ifdef VERILATOR_USRCLK_FILE
+        // Don't skip past the next user clock callback
+        next_time = std::min(next_user_clock_time, next_time);
+#endif
+
         // If there are no more cbAfterDelay callbacks,
         // the next deadline is max value, so end the simulation now
+        // Also end if the simulation reaches max time
         if (next_time == static_cast<vluint64_t>(~0ULL)) {
             vl_finish(__FILE__, __LINE__, "");
             break;
-        } else {
-            main_time = next_time;
         }
+        main_time = next_time;
 
         // Call registered NextSimTime
         // It should be called in simulation cycle before everything else

cocotb/share/makefiles/simulators/Makefile.verilator

@@ -39,6 +39,11 @@ ifeq ($(VERILATOR_TRACE),1)
   EXTRA_ARGS += --trace --trace-structs
 endif
 
+ifneq ($(VERILATOR_USRCLK_FILE),)
+  SIM_BUILD_FLAGS += -DVERILATOR_USRCLK_FILE
+  COMPILE_ARGS += $(VERILATOR_USRCLK_FILE)
+endif
+
 EXTRA_ARGS += --timescale $(COCOTB_HDL_TIMEUNIT)/$(COCOTB_HDL_TIMEPRECISION)
 
 SIM_BUILD_FLAGS += -std=c++11

documentation/source/simulator_support.rst

@@ -131,6 +131,37 @@ For Verilator 4.102 and above, the `-CFLAGS -DVM_TRACE_FST=1` argument is no lon
 
 The resulting file will be ``dump.fst`` and can be opened by ``gtkwave dump.fst``.
 
+.. _sim-verilator-user-clocks:
+
+C++ clocks
+----------
+
+For increased performance, clocks may be generated in C++ with a user-defined callback function.
+First define a callback matching the cocotb-provided declaration:
+
+  .. code-block:: cpp
+
+    #include <memory>       // unique_ptr
+    #include "Vtop.h"
+    #include "verilated.h"  // vluint64_t
+
+    vluint64_t user_clock_cb(std::unique_ptr<Vtop> & topp, vluint64_t current_time) {
+        if (current_time % CLK_HALFPERIOD == 0) {
+            topp->clk = !topp->clk;
+        }
+        // Return the next simulation time to call this callback
+        return current_time + CLK_HALFPERIOD;
+    }
+
+Then add the C++ file to the Makefile using ``VERILATOR_USRCLK_FILE`` as shown below.
+The user file will be compiled and linked with the cocotb simulation files.
+
+  .. code-block:: make
+
+    VERILATOR_USRCLK_FILE = verilator_usrclk.cpp
+
+.. versionadded: 1.5
+
 .. _sim-verilator-issues:
 
 Issues for this simulator

tests/test_cases/test_verilator_user_clock/Makefile

@@ -0,0 +1,35 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+
+TOPLEVEL_LANG ?= verilog
+
+ifneq ($(TOPLEVEL_LANG),verilog)
+
+all:
+	@echo "Skipping test due to TOPLEVEL_LANG=$(TOPLEVEL_LANG) not being verilog"
+
+clean::
+# nothing to clean, just define target in this branch
+
+else ifneq ($(shell echo $(SIM) | tr A-Z a-z),verilator)
+all:
+	@echo "Skipping test_verilator_user_clock due to SIM=$(SIM) not being verilator"
+
+clean::
+# nothing to clean, just define target in this branch
+
+else
+
+
+PWD=$(shell pwd)
+
+VERILOG_SOURCES = $(PWD)/dual_clock.sv
+
+TOPLEVEL = dual_clock
+MODULE = test_verilator_user_clock
+VERILATOR_USRCLK_FILE = verilator_usrclk.cpp
+
+include $(shell cocotb-config --makefiles)/Makefile.sim
+
+endif

tests/test_cases/test_verilator_user_clock/dual_clock.sv

@@ -0,0 +1,27 @@
+// Copyright cocotb contributors
+// Licensed under the Revised BSD License, see LICENSE for details.
+// SPDX-License-Identifier: BSD-3-Clause
+
+`timescale 1 ns / 1 ps
+
+module dual_clock (
+  input clk1,
+  input clk2
+);
+
+integer count1, count2;
+
+initial begin
+    count1 = 0;
+    count2 = 0;
+end
+
+always @(posedge clk1) begin
+    count1 <= count1 + 1;
+end
+
+always @(posedge clk2) begin
+    count2 <= count2 + 1;
+end
+
+endmodule

tests/test_cases/test_verilator_user_clock/test_verilator_user_clock.py

@@ -0,0 +1,15 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+import cocotb
+from cocotb.triggers import Timer
+
+
+@cocotb.test(skip=not cocotb.SIM_NAME.lower().startswith("verilator"))
+async def test_user_clock(dut):
+    await Timer(100, 'us')
+
+    assert dut.count1.value.integer == 114, "Expected count1 of 114, not {}".format(dut.count1.value.integer)
+    assert dut.count2.value.integer == 47, "Expected count2 of 47, not {}".format(dut.count1.value.integer)

tests/test_cases/test_verilator_user_clock/verilator_usrclk.cpp

@@ -0,0 +1,39 @@
+// Copyright cocotb contributors
+// Licensed under the Revised BSD License, see LICENSE for details.
+// SPDX-License-Identifier: BSD-3-Clause
+
+#include <algorithm>    // min
+#include <cassert>      // assert
+#include <memory>       // unique_ptr
+
+#include "Vtop.h"
+#include "verilated.h"  // vluint64_t
+
+static const int CLK1_HALFPERIOD_PS = 438000;  // 438ns
+static const int CLK2_HALFPERIOD_PS = 1056000; // 1.056us
+
+static vluint64_t next_clk1_toggle = CLK1_HALFPERIOD_PS;
+static vluint64_t next_clk2_toggle = CLK2_HALFPERIOD_PS;
+
+vluint64_t user_clock_cb(std::unique_ptr<Vtop> & topp, vluint64_t current_time) {
+
+// Initial clock value
+if (current_time == 0) {
+    topp->clk1 = 0;
+    topp->clk2 = 0;
+} else {
+    if (current_time == next_clk1_toggle) {
+        topp->clk1 = !topp->clk1;
+        next_clk1_toggle += CLK1_HALFPERIOD_PS;
+    }
+    if (current_time == next_clk2_toggle) {
+        topp->clk2 = !topp->clk2;
+        next_clk2_toggle += CLK2_HALFPERIOD_PS;
+    }
+}
+
+auto next_time = std::min(next_clk1_toggle, next_clk2_toggle);
+assert(next_time > current_time);
+
+return next_time;
+}