cocotb 1.4.0 (2020-07-08)

Features

  • Lock can now be used in async with statements. (#1031)

  • Add support for distinguishing between NET (vpiNet) and REG (vpiReg) type when using vpi interface. (#1107)

  • Support for dropping into pdb upon failure, via the new COCOTB_PDB_ON_EXCEPTION environment variable (#1180)

  • Simulators run through a TCL script (Aldec Riviera Pro and Mentor simulators) now support a new RUN_ARGS Makefile variable, which is passed to the first invocation of the tool during runtime. (#1244)

  • Cocotb now supports the following example of forking a non-decorated async coroutine.

    async def example():
    for i in range(10):
        await cocotb.triggers.Timer(10, "ns")

cocotb.fork(example())

    Issue (#1255)

  • The cocotb log configuration is now less intrusive, and only configures the root logger instance, logging.getLogger(), as part of cocotb.log.default_config() (#1266).

    As such, it is now possible to override the default cocotb logging behavior with something like:

    # remove the cocotb log handler and formatting
root = logging.getLogger()
for h in root.handlers[:]:
    root.remove_handler(h)
    h.close()

# add your own
logging.basicConfig()

  • Support for vpiRealNet (#1282)

  • The colored output can now be disabled by the NO_COLOR environment variable. (#1309)

  • Cocotb now supports deposit/force/release/freeze actions on simulator handles, exposing functionality similar to the respective Verilog/VHDL assignments.

    from cocotb.handle import Deposit, Force, Release, Freeze

dut.q <= 1            # A regular value deposit
dut.q <= Deposit(1)   # The same, higher verbosity
dut.q <= Force(1)     # Force value of q to 1
dut.q <= Release()    # Release q from a Force
dut.q <= Freeze()     # Freeze the current value of q

    Issue (#1403)

  • Custom logging handlers can now access the simulator time using logging.LogRecord.created_sim_time, provided the SimTimeContextFilter filter added by default_config() is not removed from the logger instance. (#1411)

  • Questa now supports PLUSARGS. This requires that tcl.h be present on the system. This is likely included in your installation of Questa, otherwise, specify CFLAGS=-I/path/to/tcl/includedir. (#1424)

  • The name of the entry point symbol for libraries in GPI_EXTRA can now be customized. The delimiter between each library in the list has changed from : to ,. (#1457)

  • New methods for setting the value of a NonHierarchyIndexableObject (HDL arrays). (#1507)

    # Now supported
dut.some_array <= [0xAA, 0xBB, 0xCC]
dut.some_array.value = [0xAA, 0xBB, 0xCC]

# For simulators that support n-dimensional arrays
dut.some_2d_array <= [[0xAA, 0xBB], [0xCC, 0xDD]]
dut.some_2d_array.value = [[0xAA, 0xBB], [0xCC, 0xDD]]

  • Added support for Aldec’s Active-HDL simulator. (#1601)

  • Including Makefile.inc from user makefiles is now a no-op and deprecated. Lines like include $(shell cocotb-config --makefiles)/Makefile.inc can be removed from user makefiles without loss in functionality. (#1629)

  • Support for using await inside an embedded IPython terminal, using cocotb.ipython_support. (#1649)

  • Added is_set(), so users may check if an Event has fired. (#1723)

  • The cocotb.simulator.is_running() function was added so a user of cocotb could determine if they are running within a simulator. (#1843)

Bugfixes

  • Tests which fail at initialization, for instance due to no yield being present, are no longer silently ignored (#1253)

  • Tests that were not run because predecessors threw cocotb.result.SimFailure, and caused the simulator to exit, are now recorded with an outcome of cocotb.result.SimFailure. Previously, these tests were ignored. (#1279)

  • Makefiles now correctly fail if the simulation crashes before a results.xml file can be written. (#1314)

  • Logging of non-string messages with colored log output is now working. (#1410)

  • Getting and setting the value of a NonHierarchyIndexableObject now iterates through the correct range of the simulation object, so arrays that do not start/end at index 0 are supported. (#1507)

  • The XGMII monitor no longer crashes on Python 3, and now assembles packets as bytes instead of str. The XGMII driver has expected bytes since cocotb 1.2.0. (#1545)

  • signal <= value_of_wrong_type no longer breaks the scheduler, and throws an error immediately. (#1661)

  • Scheduling behavior is now consistent before and after the first await of a GPITrigger. (#1705)

  • Iterating over for generate statements using VHPI has been fixed. This bug caused some simulators to crash, and was a regression in version 1.3. (#1882)

  • The XGMII driver no longer emits a corrupted word on the first transfer. (#1905)

Improved Documentation

  • If a makefile uses cocotb’s Makefile.sim, make help now lists the supported targets and variables. (#1318)

  • A new section Rotating Log Files has been added. (#1400)

  • The documentation at http://docs.cocotb.org/ has been restructured, making it easier to find relevant information. (#1482)

Deprecations and Removals

  • cocotb.utils.reject_remaining_kwargs() is deprecated, as it is no longer needed now that we only support Python 3.5 and newer. (#1339)

  • The value of cocotb.handle.StringObjects is now of type bytes, instead of str with an implied ASCII encoding scheme. (#1381)

  • ReturnValue is now deprecated. Use a return statement instead; this works in all supported versions of Python. (#1489)

  • The makefile variable VERILATOR_TRACE that was not supported for all simulators has been deprecated. Using it prints a deprecation warning and points to the documentation section Simulator Support explaining how to get the same effect by other means. (#1495)

  • BinaryValue.get_hex_buff produced nonsense and has been removed. (#1511)

  • Passing str instances to cocotb.utils.hexdump() and cocotb.utils.hexdiffs() is deprecated. bytes objects should be passed instead. (#1519)

  • Makefile.pylib, which provided helpers for building C extension modules for Python, has been removed. Users of the PYTHON_LIBDIR and PYTHON_INCLUDEDIR variables will now have to compute these values themselves. See the endian_swapper example for how to do this. (#1632)

  • Makefile and documentation for the NVC simulator which has never worked have been removed. (#1693)

Changes

  • Cocotb no longer supports Python 2, at least Python 3.5 is now required. Users of Python 2.7 can still use cocotb 1.3, but are heavily encouraged to update. It is recommended to use the latest release of Python 3 for improved performance over older Python 3 versions. (#767)

  • Mentor Questa, Aldec Riviera-PRO and GHDL are now started in the directory containing the Makefile and also save results.xml there, bringing them in line with the behavior used by other simulators. (#1598) (#1599) (#1063)

  • Tests are now evaluated in order of their appearance in the MODULE environment variable, their stage, and the order of invocation of the cocotb.test decorator within a module. (#1380)

  • All libraries are compiled during installation to the cocotb/libs directory. The interface libraries libcocotbvpi and libcocotbvhpi have been renamed to have a _simulator_name postfix. The simulator module has moved to cocotb.simulator. The LD_LIBRARY_PATH environment variable no longer needs to be set by the makefiles, as the libraries now discover each other via RPATH settings. (#1425)

  • Cocotb must now be installed before it can be used. (#1445)

  • cocotb.handle.NonHierarchyIndexableObject.value is now a list in left-to-right range order of the underlying simulation object. Previously the list was always ordered low-to-high. (#1507)

  • Various binary representations have changed type from str to bytes. These include:

    Code working with these objects may find it needs to switch from creating str objects like "this" to bytes objects like b"this". This change is a consequence of the move to Python 3. (#1514)

  • There’s no longer any need to set the PYTHON_BIN makefile variable, the Python executable automatically matches the one cocotb was installed into. (#1574)

  • The SIM setting for Aldec Riviera-PRO has changed from aldec to riviera. (#1691)

  • Certain methods on the cocotb.simulator Python module now throw a RuntimeError when no simulator is present, making it safe to use cocotb without a simulator present. (#1843)

  • Invalid values of the environment variable COCOTB_LOG_LEVEL are no longer ignored. They now raise an exception with instructions how to fix the problem. (#1898)