cocotb 1.9.2__cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl

cocotb/clock.py

@@ -0,0 +1,174 @@
+# Copyright (c) 2013 Potential Ventures Ltd
+# Copyright (c) 2013 SolarFlare Communications Inc
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#     * Redistributions of source code must retain the above copyright
+#       notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+#     * Neither the name of Potential Ventures Ltd,
+#       SolarFlare Communications Inc nor the
+#       names of its contributors may be used to endorse or promote products
+#       derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL POTENTIAL VENTURES LTD BE LIABLE FOR ANY
+# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+"""A clock class."""
+
+import itertools
+import warnings
+from decimal import Decimal
+from numbers import Real
+from typing import Union
+
+from cocotb.log import SimLog
+from cocotb.triggers import Timer
+from cocotb.utils import get_sim_steps, get_time_from_sim_steps, lazy_property
+
+
+class BaseClock:
+    """Base class to derive from."""
+
+    def __init__(self, signal):
+        self.signal = signal
+
+    @lazy_property
+    def log(self):
+        return SimLog("cocotb.{}.{}".format(type(self).__qualname__, self.signal._name))
+
+
+class Clock(BaseClock):
+    r"""Simple 50:50 duty cycle clock driver.
+
+    Instances of this class should call its :meth:`start` method
+    and pass the coroutine object to one of the functions in :ref:`task-management`.
+
+    This will create a clocking task that drives the signal at the
+    desired period/frequency.
+
+    Example:
+
+    .. code-block:: python
+
+        c = Clock(dut.clk, 10, 'ns')
+        await cocotb.start(c.start())
+
+    Args:
+        signal: The clock pin/signal to be driven.
+        period (int): The clock period. Must convert to an even number of
+            timesteps.
+        units (str, optional): One of
+            ``'step'``, ``'fs'``, ``'ps'``, ``'ns'``, ``'us'``, ``'ms'``, ``'sec'``.
+            When *units* is ``'step'``,
+            the timestep is determined by the simulator (see :make:var:`COCOTB_HDL_TIMEPRECISION`).
+
+    If you need more features like a phase shift and an asymmetric duty cycle,
+    it is simple to create your own clock generator (that you then :func:`~cocotb.start`):
+
+    .. code-block:: python
+
+        async def custom_clock():
+            # pre-construct triggers for performance
+            high_time = Timer(high_delay, units="ns")
+            low_time = Timer(low_delay, units="ns")
+            await Timer(initial_delay, units="ns")
+            while True:
+                dut.clk.value = 1
+                await high_time
+                dut.clk.value = 0
+                await low_time
+
+    If you also want to change the timing during simulation,
+    use this slightly more inefficient example instead where
+    the :class:`Timer`\ s inside the while loop are created with
+    current delay values:
+
+    .. code-block:: python
+
+        async def custom_clock():
+            while True:
+                dut.clk.value = 1
+                await Timer(high_delay, units="ns")
+                dut.clk.value = 0
+                await Timer(low_delay, units="ns")
+
+        high_delay = low_delay = 100
+        await cocotb.start(custom_clock())
+        await Timer(1000, units="ns")
+        high_delay = low_delay = 10  # change the clock speed
+        await Timer(1000, units="ns")
+
+    .. versionchanged:: 1.5
+        Support ``'step'`` as the *units* argument to mean "simulator time step".
+
+    .. deprecated:: 1.5
+        Using ``None`` as the *units* argument is deprecated, use ``'step'`` instead.
+    """
+
+    def __init__(
+        self, signal, period: Union[float, Real, Decimal], units: str = "step"
+    ):
+        BaseClock.__init__(self, signal)
+        if units is None:
+            warnings.warn(
+                'Using units=None is deprecated, use units="step" instead.',
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            units = "step"  # don't propagate deprecated value
+        self.period = get_sim_steps(period, units)
+        self.half_period = get_sim_steps(period / 2, units)
+        self.frequency = 1 / get_time_from_sim_steps(self.period, units="us")
+        self.hdl = None
+        self.signal = signal
+        self.coro = None
+        self.mcoro = None
+
+    async def start(self, cycles=None, start_high=True):
+        r"""Clocking coroutine.  Start driving your clock by :func:`cocotb.start`\ ing a
+        call to this.
+
+        Args:
+            cycles (int, optional): Cycle the clock *cycles* number of times,
+                or if ``None`` then cycle the clock forever.
+                Note: ``0`` is not the same as ``None``, as ``0`` will cycle no times.
+            start_high (bool, optional): Whether to start the clock with a ``1``
+                for the first half of the period.
+                Default is ``True``.
+
+                .. versionadded:: 1.3
+        """
+        t = Timer(self.half_period)
+        if cycles is None:
+            it = itertools.count()
+        else:
+            it = range(cycles)
+
+        # branch outside for loop for performance (decision has to be taken only once)
+        if start_high:
+            for _ in it:
+                self.signal.value = 1
+                await t
+                self.signal.value = 0
+                await t
+        else:
+            for _ in it:
+                self.signal.value = 0
+                await t
+                self.signal.value = 1
+                await t
+
+    def __str__(self):
+        return type(self).__qualname__ + "(%3.1f MHz)" % self.frequency

cocotb/config.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python
+###############################################################################
+# Copyright (c) 2013 Potential Ventures Ltd
+# Copyright (c) 2013 SolarFlare Communications Inc
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#     * Redistributions of source code must retain the above copyright
+#       notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+#     * Neither the name of Potential Ventures Ltd,
+#       SolarFlare Communications Inc nor the
+#       names of its contributors may be used to endorse or promote products
+#       derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL POTENTIAL VENTURES LTD BE LIABLE FOR ANY
+# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+###############################################################################
+
+"""
+Module for querying the cocotb configuration
+
+This module provides information in module global variables and through a
+``main()`` function that is used in the cocotb-config script.
+
+Global variables:
+    share_dir: str, path where the cocotb data is stored
+    makefiles_dir: str, path where the cocotb makefiles are installed
+    libs_dir: str, path where the cocotb interface libraries are located
+"""
+import argparse
+import os
+import sys
+import textwrap
+from pathlib import Path
+
+import find_libpython
+
+import cocotb
+
+__all__ = ["share_dir", "makefiles_dir", "libs_dir"]
+
+base_dir = Path(cocotb.__file__).parent.resolve()
+share_dir = base_dir.joinpath("share").as_posix()
+makefiles_dir = base_dir.joinpath("share").joinpath("makefiles").as_posix()
+libs_dir = base_dir.joinpath("libs").as_posix()
+
+
+def help_vars_text():
+    if "dev" in cocotb.__version__:
+        doclink = "https://docs.cocotb.org/en/latest/building.html"
+    else:
+        doclink = f"https://docs.cocotb.org/en/v{cocotb.__version__}/building.html"
+
+    # NOTE: make sure to keep "helpmsg" aligned with documentation/source/building.rst
+    # Also keep it at 80 chars.
+    helpmsg = textwrap.dedent(
+        """\
+    The following variables are environment variables:
+
+    Cocotb
+    ------
+    TOPLEVEL                  Instance in the hierarchy to use as the DUT
+    RANDOM_SEED               Random seed, to recreate a previous test stimulus
+    COCOTB_ANSI_OUTPUT        Force cocotb to print or not print in color
+    COCOTB_REDUCED_LOG_FMT    Display log lines shorter
+    COCOTB_ATTACH             Pause time value in seconds before the simulator start
+    COCOTB_ENABLE_PROFILING   Performance analysis of the Python portion of cocotb
+    COCOTB_LOG_LEVEL          Default logging level (default INFO)
+    COCOTB_RESOLVE_X          How to resolve X, Z, U, W on integer conversion
+    MEMCHECK                  HTTP port to use for debugging Python memory usage
+    LIBPYTHON_LOC             Absolute path to libpython
+
+    Regression Manager
+    ------------------
+    COCOTB_PDB_ON_EXCEPTION   Drop into the Python debugger (pdb) on exception
+    MODULE                    Modules to search for test functions (comma-separated)
+    TESTCASE                  Test function(s) to run (comma-separated list)
+    COCOTB_RESULTS_FILE       File name for xUnit XML tests results
+    COVERAGE                  Report Python coverage (also HDL for some simulators)
+
+    GPI
+    ---
+    GPI_EXTRA                 Extra libraries to load at runtime (comma-separated)
+
+    Scheduler
+    ---------
+    COCOTB_SCHEDULER_DEBUG    Enable additional output of coroutine scheduler
+
+    For details, see {}"""
+    ).format(doclink)
+    return helpmsg
+
+
+def lib_name(interface: str, simulator: str) -> str:
+    """
+    Return the name of interface library for given interface (VPI/VHPI/FLI) and simulator.
+    """
+
+    interface_name = interface.lower()
+    supported_interfaces = ["vpi", "vhpi", "fli"]
+    if interface_name not in supported_interfaces:
+        raise ValueError(
+            "Wrong interface used. Supported: " + ", ".join(supported_interfaces)
+        )
+
+    simulator_name = simulator.lower()
+    supported_sims = [
+        "icarus",
+        "questa",
+        "modelsim",
+        "ius",
+        "xcelium",
+        "vcs",
+        "ghdl",
+        "riviera",
+        "activehdl",
+        "cvc",
+        "nvc",
+    ]
+    if simulator not in supported_sims:
+        raise ValueError(
+            "Wrong simulator name. Supported: " + ", ".join(supported_sims)
+        )
+
+    if simulator_name in ["questa", "cvc"]:
+        library_name = "modelsim"
+    elif simulator_name == "xcelium":
+        library_name = "ius"
+    elif simulator_name in ["riviera", "activehdl"]:
+        library_name = "aldec"
+    else:
+        library_name = simulator_name
+
+    if library_name == "icarus":
+        lib_ext = ""
+    elif os.name == "nt":
+        lib_ext = ".dll"
+    else:
+        lib_ext = ".so"
+
+    # check if compiled with msvc
+    if os.path.isfile(os.path.join(libs_dir, "cocotb.dll")):
+        lib_prefix = ""
+    else:
+        lib_prefix = "lib"
+
+    return lib_prefix + "cocotb" + interface_name + "_" + library_name + lib_ext
+
+
+def lib_name_path(interface, simulator):
+    """
+    Return the absolute path of interface library for given interface (VPI/VHPI/FLI) and simulator
+    """
+    library_name_path = os.path.join(libs_dir, lib_name(interface, simulator))
+
+    return Path(library_name_path).as_posix()
+
+
+def _findlibpython():
+    libpython_path = find_libpython.find_libpython()
+    if libpython_path is None:
+        sys.exit(1)
+    return Path(libpython_path).as_posix()
+
+
+class PrintAction(argparse.Action):
+    def __init__(self, option_strings, dest, text=None, **kwargs):
+        super().__init__(option_strings, dest, nargs=0, **kwargs)
+        self.text = text
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        print(self.text)
+        parser.exit()
+
+
+class PrintFuncAction(argparse.Action):
+    def __init__(self, option_strings, dest, function=None, **kwargs):
+        super().__init__(option_strings, dest, **kwargs)
+        self.function = function
+
+    def __call__(self, parser, args, values, option_string=None):
+        try:
+            print(self.function(*values))
+        except ValueError as e:
+            parser.error(e)
+        parser.exit()
+
+
+def get_parser():
+    prefix_dir = base_dir.parent.resolve().as_posix()
+    version = cocotb.__version__
+    python_bin = Path(sys.executable).as_posix()
+
+    parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter)
+    parser.add_argument(
+        "--prefix",
+        help="echo the package-prefix of cocotb",
+        action=PrintAction,
+        text=prefix_dir,
+    )
+    parser.add_argument(
+        "--share",
+        help="echo the package-share of cocotb",
+        action=PrintAction,
+        text=share_dir,
+    )
+    parser.add_argument(
+        "--makefiles",
+        help="echo the package-makefiles of cocotb",
+        action=PrintAction,
+        text=makefiles_dir,
+    )
+    parser.add_argument(
+        "--python-bin",
+        help="echo the path to the Python binary cocotb is installed for",
+        action=PrintAction,
+        text=python_bin,
+    )
+    parser.add_argument(
+        "--help-vars",
+        help="show help about supported variables",
+        action=PrintAction,
+        text=help_vars_text(),
+    )
+    parser.add_argument(
+        "--libpython",
+        help="Print the absolute path to the libpython associated with the current Python installation",
+        nargs=0,
+        metavar=(),
+        action=PrintFuncAction,
+        function=_findlibpython,
+    )
+    parser.add_argument(
+        "--lib-dir",
+        help="Print the absolute path to the interface libraries location",
+        action=PrintAction,
+        text=libs_dir,
+    )
+    parser.add_argument(
+        "--lib-name",
+        help="Print the name of interface library for given interface (VPI/VHPI/FLI) and simulator",
+        nargs=2,
+        metavar=("INTERFACE", "SIMULATOR"),
+        action=PrintFuncAction,
+        function=lib_name,
+    )
+    parser.add_argument(
+        "--lib-name-path",
+        help="Print the absolute path of interface library for given interface (VPI/VHPI/FLI) and simulator",
+        nargs=2,
+        metavar=("INTERFACE", "SIMULATOR"),
+        action=PrintFuncAction,
+        function=lib_name_path,
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        help="echo the version of cocotb",
+        action=PrintAction,
+        text=version,
+    )
+
+    return parser
+
+
+def main():
+    parser = get_parser()
+
+    if len(sys.argv) == 1:
+        parser.print_help(sys.stderr)
+        sys.exit(1)
+
+    parser.parse_args()
+
+
+if __name__ == "__main__":
+    main()