cocotb 1.9.2__cp311-cp311-win32.whl → 2.0.0rc2__cp311-cp311-win32.whl

cocotb/share/lib/verilator/verilator.cpp

@@ -20,9 +20,12 @@
 #if VM_TRACE
 #if VM_TRACE_FST
 #include <verilated_fst_c.h>
+using verilated_trace_t = VerilatedFstC;
 #else
 #include <verilated_vcd_c.h>
+using verilated_trace_t = VerilatedVcdC;
 #endif
+static verilated_trace_t *tfp;
 #endif
 
 static vluint64_t main_time = 0;  // Current simulation time
@@ -50,18 +53,46 @@ static inline bool settle_value_callbacks() {
     return cbs_called;
 }
 
-int main(int argc, char** argv) {
-    bool traceOn = false;
+void wrap_up() {
+    VerilatedVpi::callCbs(cbEndOfSimulation);
+
+#if VM_TRACE
+    if (tfp) {
+        delete tfp;
+        tfp = nullptr;
+    }
+#endif
+
+    // VM_COVERAGE is a define which is set if Verilator is
+    // instructed to collect coverage (when compiling the simulation)
+#if VM_COVERAGE
+    VerilatedCov::write();  // Uses +verilator+coverage+file+<filename>,
+                            // defaults to coverage.dat
+#endif
+}
+
+int main(int argc, char **argv) {
 #if VM_TRACE_FST
-    const char* traceFile = "dump.fst";
+    const char *traceFile = "dump.fst";
 #else
-    const char* traceFile = "dump.vcd";
+    const char *traceFile = "dump.vcd";
 #endif
+    bool traceOn = false;
+    bool traceFlush = false;
 
     for (int i = 1; i < argc; i++) {
         std::string arg = std::string(argv[i]);
         if (arg == "--trace") {
+#if VM_TRACE
             traceOn = true;
+#else
+            fprintf(stderr,
+                    "Error: --trace requires the design to be built with trace "
+                    "support\n");
+            return -1;
+#endif
+        } else if (arg == "--trace-flush") {
+            traceFlush = true;
         } else if (arg == "--trace-file") {
             if (++i < argc) {
                 traceFile = argv[i];
@@ -70,16 +101,18 @@ int main(int argc, char** argv) {
                 return -1;
             }
         } else if (arg == "--help") {
-            fprintf(stderr,
-                    "usage: %s [--trace] [--trace-file TRACEFILE]\n"
-                    "\n"
-                    "Cocotb + Verilator sim\n"
-                    "\n"
-                    "options:\n"
-                    "  --trace      Enables tracing (VCD or FST)\n"
-                    "  --trace-file Specifies the trace file name (%s by "
-                    "default)\n",
-                    basename(argv[0]), traceFile);
+            fprintf(
+                stderr,
+                "usage: %s [--trace] [--trace-flush] [--trace-file TRACEFILE]\n"
+                "\n"
+                "cocotb + Verilator sim\n"
+                "\n"
+                "options:\n"
+                "  --trace       Enable tracing (VCD or FST)\n"
+                "  --trace-flush Flush trace at each time step (slow)\n"
+                "  --trace-file  Specify the trace file name (%s by "
+                "default)\n",
+                basename(argv[0]), traceFile);
             return 0;
         }
     }
@@ -95,58 +128,48 @@ int main(int argc, char** argv) {
     Verilated::internalsDump();
 #endif
 
-    vlog_startup_routines_bootstrap();
-    VerilatedVpi::callCbs(cbStartOfSimulation);
-
 #if VM_TRACE
-#if VM_TRACE_FST
-    std::unique_ptr<VerilatedFstC> tfp(new VerilatedFstC);
-#else
-    std::unique_ptr<VerilatedVcdC> tfp(new VerilatedVcdC);
-#endif
-
+    Verilated::traceEverOn(true);
     if (traceOn) {
-        Verilated::traceEverOn(true);
-        top->trace(tfp.get(), 99);
+        tfp = new verilated_trace_t;
+        top->trace(tfp, 99);
         tfp->open(traceFile);
     }
 #endif
 
-    while (!Verilated::gotFinish()) {
-        // 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)
-        VerilatedVpi::callTimedCbs();
-
-        // Call Value Change callbacks triggered by Timer callbacks
-        // These can modify signal values
-        settle_value_callbacks();
-
-        // We must evaluate whole design until we process all 'events'
-        bool again = true;
-        while (again) {
-            // Evaluate design
-            top->eval_step();
-
-            // Call Value Change callbacks triggered by eval()
-            // These can modify signal values
-            again = settle_value_callbacks();
+    vlog_startup_routines_bootstrap();
+    Verilated::addExitCb([](void *) { wrap_up(); }, nullptr);
+    VerilatedVpi::callCbs(cbStartOfSimulation);
+    settle_value_callbacks();
 
-            // Call registered ReadWrite callbacks
-            again |= VerilatedVpi::callCbs(cbReadWriteSynch);
+    while (!Verilated::gotFinish()) {
+        do {
+            // We must evaluate whole design until we process all 'events' for
+            // this time step
+            do {
+                top->eval_step();
+                VerilatedVpi::clearEvalNeeded();
+                VerilatedVpi::doInertialPuts();
+                settle_value_callbacks();
+            } while (VerilatedVpi::evalNeeded());
+
+            // Run ReadWrite callback as we are done processing this eval step
+            VerilatedVpi::callCbs(cbReadWriteSynch);
+            VerilatedVpi::doInertialPuts();
+            settle_value_callbacks();
+        } while (VerilatedVpi::evalNeeded());
 
-            // Call Value Change callbacks triggered by ReadWrite callbacks
-            // These can modify signal values
-            again |= settle_value_callbacks();
-        }
         top->eval_end_step();
 
         // Call ReadOnly callbacks
         VerilatedVpi::callCbs(cbReadOnlySynch);
 
 #if VM_TRACE
-        if (traceOn) {
+        if (tfp) {
             tfp->dump(main_time);
+            if (traceFlush) {
+                tfp->flush();
+            }
         }
 #endif
         // cocotb controls the clock inputs using cbAfterDelay so
@@ -169,28 +192,18 @@ int main(int argc, char** argv) {
         // It should be called in simulation cycle before everything else
         // but not on first cycle
         VerilatedVpi::callCbs(cbNextSimTime);
+        settle_value_callbacks();
 
-        // Call Value Change callbacks triggered by NextTimeStep callbacks
-        // These can modify signal values
+        // 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)
+        VerilatedVpi::callTimedCbs();
         settle_value_callbacks();
     }
 
-    VerilatedVpi::callCbs(cbEndOfSimulation);
-
     top->final();
 
-#if VM_TRACE
-    if (traceOn) {
-        tfp->close();
-    }
-#endif
-
-// VM_COVERAGE is a define which is set if Verilator is
-// instructed to collect coverage (when compiling the simulation)
-#if VM_COVERAGE
-    VerilatedCov::write();  // Uses +verilator+coverage+file+<filename>,
-                            // defaults to coverage.dat
-#endif
+    wrap_up();
 
     return 0;
 }

cocotb/simtime.py

@@ -0,0 +1,230 @@
+# Copyright cocotb contributors
+# Copyright (c) 2013 Potential Ventures Ltd
+# Copyright (c) 2013 SolarFlare Communications Inc
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Tools for dealing with simulated time."""
+
+import warnings
+from decimal import Decimal
+from fractions import Fraction
+from functools import lru_cache
+from math import ceil, floor
+from typing import Union, cast, overload
+
+from cocotb import simulator
+from cocotb._py_compat import Literal, TypeAlias
+from cocotb._typing import RoundMode, TimeUnit
+
+__all__ = (
+    "convert",
+    "get_sim_time",
+    "time_precision",
+)
+
+
+Steps: TypeAlias = Literal["step"]
+TimeUnitWithoutSteps: TypeAlias = Literal["fs", "ps", "ns", "us", "ms", "sec"]
+
+
+@overload
+def convert(
+    value: Union[float, Fraction, Decimal],
+    unit: TimeUnit,
+    *,
+    to: Steps,
+    round_mode: RoundMode = "error",
+) -> int: ...
+
+
+@overload
+def convert(
+    value: Union[float, Fraction, Decimal],
+    unit: TimeUnit,
+    *,
+    to: TimeUnitWithoutSteps,
+    round_mode: RoundMode = "error",
+) -> float: ...
+
+
+def convert(
+    value: Union[float, Decimal, Fraction],
+    unit: TimeUnit,
+    *,
+    to: TimeUnit,
+    round_mode: RoundMode = "error",
+) -> float:
+    """Convert time values from one unit to another unit.
+
+    Args:
+        value: The time value.
+
+        unit: The unit of *value* (one of ``'step'``, ``'fs'``, ``'ps'``, ``'ns'``, ``'us'``, ``'ms'``, ``'sec'``).
+
+        to: The unit to convert *value* to (one of ``'step'``, ``'fs'``, ``'ps'``, ``'ns'``, ``'us'``, ``'ms'``, ``'sec'``).
+
+        round_mode:
+            How to handle non-integral step values (one of ``'error'``, ``'round'``, ``'ceil'``, ``'floor'``).
+
+            When *round_mode* is ``"error"``, a :exc:`ValueError` is thrown if the value cannot
+            be accurately represented in terms of simulator time steps.
+            When *round_mode* is ``"round"``, ``"ceil"``, or ``"floor"``, the corresponding
+            rounding function from the standard library will be used to round to a simulator
+            time step.
+
+    Returns:
+        The value scaled by the difference in units.
+
+    .. versionadded:: 2.0
+    """
+    if unit == "step":
+        steps = cast("int", value)
+    else:
+        steps = _get_sim_steps(value, unit, round_mode=round_mode)
+    if to == "step":
+        return steps
+    else:
+        return _get_time_from_sim_steps(steps, to)
+
+
+def get_sim_time(unit: TimeUnit = "step", *, units: None = None) -> float:
+    """Retrieve the simulation time from the simulator.
+
+    Args:
+        unit: String specifying the unit of the result
+            (one of ``'step'``, ``'fs'``, ``'ps'``, ``'ns'``, ``'us'``, ``'ms'``, ``'sec'``).
+            ``'step'`` will return the raw simulation time.
+
+            .. versionchanged:: 2.0
+                Passing ``None`` as the *unit* argument was removed, use ``'step'`` instead.
+
+            .. versionchanged:: 2.0
+                Renamed from ``units``.
+
+    Raises:
+        ValueError: If *unit* is not a valid unit.
+
+    Returns:
+        The simulation time in the specified unit.
+
+    .. versionchanged:: 1.6
+        Support ``'step'`` as the the *unit* argument to mean "simulator time step".
+
+    .. versionchanged:: 2.0
+        Moved from :mod:`cocotb.utils` to :mod:`cocotb.simtime`.
+    """
+    if units is not None:
+        warnings.warn(
+            "The 'units' argument has been renamed to 'unit'.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        unit = units
+    timeh, timel = simulator.get_sim_time()
+    steps = timeh << 32 | timel
+    return _get_time_from_sim_steps(steps, unit) if unit != "step" else steps
+
+
+@overload
+def _ldexp10(frac: float, exp: int) -> float: ...
+
+
+@overload
+def _ldexp10(frac: Fraction, exp: int) -> Fraction: ...
+
+
+@overload
+def _ldexp10(frac: Decimal, exp: int) -> Decimal: ...
+
+
+def _ldexp10(
+    frac: Union[float, Fraction, Decimal], exp: int
+) -> Union[float, Fraction, Decimal]:
+    """Like :func:`math.ldexp`, but base 10."""
+    # using * or / separately prevents rounding errors if `frac` is a
+    # high-precision type
+    if exp > 0:
+        return frac * (10**exp)
+    else:
+        return frac / (10**-exp)
+
+
+def _get_time_from_sim_steps(
+    steps: int,
+    unit: TimeUnit,
+) -> float:
+    if unit == "step":
+        return steps
+    return _ldexp10(steps, time_precision - _get_log_time_scale(unit))
+
+
+def _get_sim_steps(
+    time: Union[float, Fraction, Decimal],
+    unit: TimeUnit = "step",
+    *,
+    round_mode: RoundMode = "error",
+) -> int:
+    result: Union[float, Fraction, Decimal]
+    if unit != "step":
+        result = _ldexp10(time, _get_log_time_scale(unit) - time_precision)
+    else:
+        result = time
+
+    if round_mode == "error":
+        result_rounded = floor(result)
+        if result_rounded != result:
+            raise ValueError(
+                f"Unable to accurately represent {time}({unit}) with the simulator precision of 1e{time_precision}"
+            )
+    elif round_mode == "ceil":
+        result_rounded = ceil(result)
+    elif round_mode == "round":
+        result_rounded = round(result)
+    elif round_mode == "floor":
+        result_rounded = floor(result)
+    else:
+        raise ValueError(f"Invalid round_mode specifier: {round_mode}")
+
+    return result_rounded
+
+
+@lru_cache(maxsize=None)
+def _get_log_time_scale(unit: TimeUnitWithoutSteps) -> int:
+    """Retrieve the ``log10()`` of the scale factor for a given time unit.
+
+    Args:
+        unit: String specifying the unit
+            (one of ``'fs'``, ``'ps'``, ``'ns'``, ``'us'``, ``'ms'``, ``'sec'``).
+
+            .. versionchanged:: 2.0
+                Renamed from ``units``.
+
+    Raises:
+        ValueError: If *unit* is not a valid unit.
+
+    Returns:
+        The ``log10()`` of the scale factor for the time unit.
+    """
+    scale = {"fs": -15, "ps": -12, "ns": -9, "us": -6, "ms": -3, "sec": 0}
+
+    unit_lwr = unit.lower()
+    if unit_lwr not in scale:
+        raise ValueError(f"Invalid unit ({unit}) provided")
+    else:
+        return scale[unit_lwr]
+
+
+time_precision: int = _get_log_time_scale("fs")
+"""The precision of time in the current simulation.
+
+The value is seconds in powers of tens,
+i.e. ``-15`` is ``10**-15`` seconds or 1 femtosecond.
+
+.. versionadded:: 2.0
+"""
+
+
+def _init() -> None:
+    global time_precision
+    time_precision = simulator.get_precision()

cocotb/simulator.pyi

@@ -0,0 +1,107 @@
+# Copyright cocotb contributors
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
+
+# generated with mypy's stubgen script
+
+from logging import Logger
+from typing import Any, Callable
+
+from cocotb.handle import GPIDiscovery
+
+DRIVERS: int
+ENUM: int
+GENARRAY: int
+INTEGER: int
+LOADS: int
+LOGIC: int
+LOGIC_ARRAY: int
+MEMORY: int
+MODULE: int
+NETARRAY: int
+OBJECTS: int
+PACKAGE: int
+REAL: int
+STRING: int
+STRUCTURE: int
+PACKED_STRUCTURE: int
+UNKNOWN: int
+RISING: int
+FALLING: int
+VALUE_CHANGE: int
+RANGE_UP: int
+RANGE_DOWN: int
+RANGE_NO_DIR: int
+
+class gpi_cb_hdl:
+    def deregister(self) -> None: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __ne__(self, other: object) -> bool: ...
+    def __hash__(self) -> int: ...
+
+class gpi_iterator_hdl:
+    def __eq__(self, other: object) -> bool: ...
+    def __ne__(self, other: object) -> bool: ...
+    def __hash__(self) -> int: ...
+    def __iter__(self) -> gpi_iterator_hdl: ...
+    def __next__(self) -> gpi_sim_hdl: ...
+
+class gpi_sim_hdl:
+    def get_const(self) -> bool: ...
+    def get_definition_file(self) -> str: ...
+    def get_definition_name(self) -> str: ...
+    def get_handle_by_index(self, index: int) -> gpi_sim_hdl | None: ...
+    def get_handle_by_name(
+        self, name: str, discovery_method: GPIDiscovery | None = GPIDiscovery.AUTO
+    ) -> gpi_sim_hdl | None: ...
+    def get_indexable(self) -> bool: ...
+    def get_name_string(self) -> str: ...
+    def get_num_elems(self) -> int: ...
+    def get_range(self) -> tuple[int, int, int]: ...
+    def get_signal_val_binstr(self) -> str: ...
+    def get_signal_val_long(self) -> int: ...
+    def get_signal_val_real(self) -> float: ...
+    def get_signal_val_str(self) -> bytes: ...
+    def get_type(self) -> int: ...
+    def get_type_string(self) -> str: ...
+    def iterate(self, mode: int) -> gpi_iterator_hdl: ...
+    def set_signal_val_binstr(self, action: int, value: str) -> None: ...
+    def set_signal_val_int(self, action: int, value: int) -> None: ...
+    def set_signal_val_real(self, action: int, value: float) -> None: ...
+    def set_signal_val_str(self, action: int, value: bytes) -> None: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __ne__(self, other: object) -> bool: ...
+    def __hash__(self) -> int: ...
+
+def get_precision() -> int: ...
+def get_root_handle(name: str | None) -> gpi_sim_hdl | None: ...
+def get_sim_time() -> tuple[int, int]: ...
+def get_simulator_product() -> str: ...
+def get_simulator_version() -> str: ...
+def is_running() -> bool: ...
+def set_gpi_log_level(level: int) -> None: ...
+def package_iterate() -> gpi_iterator_hdl: ...
+def register_nextstep_callback(func: Callable[..., Any], *args: Any) -> gpi_cb_hdl: ...
+def register_readonly_callback(func: Callable[..., Any], *args: Any) -> gpi_cb_hdl: ...
+def register_rwsynch_callback(func: Callable[..., Any], *args: Any) -> gpi_cb_hdl: ...
+def register_timed_callback(
+    time: int, func: Callable[..., Any], *args: Any
+) -> gpi_cb_hdl: ...
+def register_value_change_callback(
+    signal: gpi_sim_hdl, func: Callable[..., Any], edge: int, *args: Any
+) -> gpi_cb_hdl: ...
+def stop_simulator() -> None: ...
+
+class cpp_clock:
+    def __init__(self, signal: gpi_sim_hdl) -> None: ...
+    def start(
+        self, period_steps: int, high_steps: int, start_high: bool, set_action: int
+    ) -> None: ...
+    def stop(self) -> None: ...
+
+def clock_create(hdl: gpi_sim_hdl) -> cpp_clock: ...
+def initialize_logger(
+    log_func: Callable[[Logger, int, str, int, str, str], None],
+    get_logger: Callable[[str], Logger],
+) -> None: ...
+def set_sim_event_callback(sim_event_callback: Callable[[str], None]) -> None: ...