Release Notes

All releases are available from the GitHub Releases Page.

cocotb 2.0.0.dev0+fa3e92c (2024-10-10)

Features

Bugfixes

  • Xcelium 23.09.004 and newer can now be used to test designs with a VHDL toplevel. (#1076)

  • Fix a potential issue where pseudo-region lookup may find the wrong generate block if the name of one generate block starts with the name of another generate block. (#2255)

  • Fix incorrect cleanup of pending Tasks (queued by cocotb.start_soon() but not started yet) when a test ends. (#3354)

  • Support waves argument to Runner.build() for Verilator. (#3681)

  • The test_args argument to Runner.test() is now passed to the Verilator simulation binary when running the simulation, which was previously missing. (#3682)

Deprecations and Removals

  • Removed unmaintained WaveDrom support. Users (if any) are encouraged to include the code in their own codebase, or create a cocotb extension for it. (#2066)

  • cocotb.handle.NonConstantObject was removed, use ValueObjectBase instead. (#2720)

  • Iteration of and querying length and range of IntegerObject, EnumObject, and RealObject have been removed. (#2720)

  • The deprecated cocotb.fork function was removed. (#3425)

  • Support for generator-based coroutines, which used the cocotb.coroutine decorator and yield syntax, has been removed. To update to the new syntax, remove all uses of the decorator and convert the function to a coroutine function using the async and await syntax. (#3509)

  • Removed cocotb.types.Bit. (#3549)

  • The prefix and postfix arguments to TestFactory.generate_tests() are deprecated in favor of the more flexible name argument. (#3578)

  • Methods get_definition_name() and get_definition_file() of cocotb.handle.SimHandleBase were removed in favor of _def_name() and _def_file(), respectively. (#3609)

  • cocotb.binary.BinaryValue, cocotb.binary.BinaryRepresentation, and the cocotb.binary module have been removed in favor of LogicArray. See the guide for a tutorial on upgrading to LogicArray. (#3634)

  • Deprecated MODULE, TOPLEVEL, TESTCASE, COVERAGE, COVERAGE_RCFILE, PLUSARGS, and RANDOM_SEED, that are respectively replaced with COCOTB_TEST_MODULES, COCOTB_TOPLEVEL, COCOTB_TESTCASE, COCOTB_USER_COVERAGE, COCOTB_COVERAGE_RCFILE, COCOTB_PLUSARGS and COCOTB_RANDOM_SEED to avoid issues with simulators overwriting cocotb environment variables. (#3644)

  • HierarchyObject._id() is now deprecated. Use handle["sub_handle_name"] syntax instead. (#3655)

  • Removed cocotb.logging.SimLog, use logging.getLogger() instead. (#3673)

  • cocotb.types.concat was removed. Use Array(itertools.chain(a, b)) instead. (#3705)

  • TestFactory is now deprecated. Use cocotb.parametrize instead. (#3717)

  • cocotb.handle.ModifiableObject was removed along with its non-functional drivers() and loads() methods. (#3733)

  • cocotb.RANDOM_SEED was made private. (#3779)

  • cocotb.LANGUAGE was removed, use os.environ["TOPLEVEL_LANG"] if you need that information. (#3779)

  • Removed cocotb.argc. Use len(cocotb.argv) instead. (#3779)

  • LogicArray.integer has been deprecated. Use LogicArray.to_unsigned() instead. (#3792)

  • Constructing a LogicArray from an int is deprecated. Use LogicArray.from_unsigned() and LogicArray.from_signed() instead. (#3792)

  • LogicArray.signed_integer has been deprecated. Use LogicArray.to_signed() instead. (#3792)

  • LogicArray.binstr has been deprecated. Use str(logic_array) instead. (#3792)

  • Deprecated the verilog_sources and vhdl_sources parameters to Runner.build(). Use the language-agnostic sources parameter instead. (#3836)

  • Made cocotb.triggers.Trigger.primed, cocotb.triggers.GPITrigger.cbhdl, and cocotb.triggers.Timer.sim_steps private. (#3851)

  • Removed cocotb.triggers.PythonTrigger. (#3851)

  • cocotb.result.TestComplete was removed. (#3864)

  • cocotb.result.ExternalException was removed. (#3864)

  • cocotb.triggers.Join.retval was removed. (#3931)

  • Support for passing 0 as the time argument to Timer has been removed. If a rounding operation causes the value to become 0, we change it to 1 simulation time step. (#3937)

  • cocotb.result.SimFailure has been removed. It’s replaced with the _expect_sim_failure argument to cocotb.test(). Users are not intended to use this functionality. (#3938)

  • LogicArray.buff has been deprecated. Use LogicArray.to_unsigned() in combination with int.to_bytes() instead. For example: v.to_unsigned().to_bytes(ceil(len(v) / 8), byteorder="big"). (#3944)

  • The outcome parameter to NullTrigger was removed. There is no alternative. (#3969)

  • Removed the cycles argument to Clock.start(). Use kill() on the clock task instead, or implement manually. (#3983)

  • cocotb.utils.want_color_output(), cocotb.utils.remove_traceback_frames, cocotb.utils.walk_coro_stack, and cocotb.utils.extract_coro_stack were removed. (#4023)

  • The undocumented cocotb.triggers._TriggerException, thrown when a trigger failed to register, was removed. RuntimeError is thrown in its place. (#4024)

  • Removed the undocumented data attribute on Event and on the corresponding Event.set(). (#4079)

  • Task.join() was deprecated, use the Task being joined directly wherever task.join() was previously used. (#4084)

  • Join was deprecated, use the Task being joined directly wherever Join(task) was previously used. (#4084)

  • When constructing a LogicArray from a int, the range argument is now required. (#4093)

  • Constructing a LogicArray from an int now only accepts integer literals (unsigned). Use LogicArray.from_signed() to convert negative integers into LogicArrays using two’s complement representation. (#4093)

  • The module cocotb.decorators was removed. All functionality is now available directly in the cocotb namespace (e.g. cocotb.decorators.test is now cocotb.test()). (#4129)

  • Removed Task.has_started(). (#4149)

  • The RTL_LIBRARY and TOPLEVEL_LIBRARY Makefile variables were merged into TOPLEVEL_LIBRARY. Update all uses of RTL_LIBRARY. (#4189)

Changes

  • cocotb.handle.ConstantObject was removed. Constant value objects are now returned as their corresponding simulator value object subtype (e.g. integers in VHDL and Verilog are now IntegerObjects). You can check if the value object is constant using the is_const() method. (#2720)

  • All casts on simulator value objects have been deprecated. If you want to get the value from a simulator value object, use the value() property; then cast the value. (#2720)

  • All simulator objects when cast to a str now return the repr of the object and not the path. (#2720)

  • Testing equality of simulator value object subtypes no longer does a value equality, but an identity equality. All simulator objects can now be used in hashable collections like dict and set. (#2720)

  • std_(u)logic_vector and std_(u)logic signals and constants in VHDL, and logic and packed arrays of logic signals and parameters in Verilog are now LogicObjects. (#2720)

  • cocotb-bus can no longer be installed at the same time as cocotb using pip install cocotb[bus]. Use pip install cocotb-bus instead. (#3436)

  • cocotb.resume() and cocotb.bridge() are now implemented as decorator functions and not types. All attributes, e.g. log, are no longer available. (#3461)

  • For Aldec simulators, the -dbg and -O2 options are no longer passed by default, as they reduce simulation speed. Pass these options in COMPILE_ARGS and SIM_ARGS if you need them for increased observability. (#3490)

  • Use of the TESTCASE variable has been changed so that each element of TESTCASE will now select all tests with a matching name across all MODULEs instead of just the first one found. (#3578)

  • The cocotb.test() decorator now returns the decorated object instead of a Test object. (#3578)

  • The RegressionManager uses a new mechanism to discover tests. Typical uses of the cocotb.test() decorator and TestFactory should be unaffected, but atypical uses may not. (#3578)

  • Getting a value with LogicObject.value now returns a LogicArray. (#3634)

  • cocotb.handle.RegionObject was renamed to HierarchyObjectBase. (#3655)

  • The module cocotb.xunit_reporter was made private. (#3672)

  • The module cocotb.outcomes was made private. (#3672)

  • The module cocotb.log was renamed to cocotb.logging to prevent clashing with cocotb.log. (#3673)

  • Moved cocotb.config to cocotb_tools.config and cocotb.runner to cocotb_tools.runner to improve startup speed. (#3731)

  • Getting a value with ArrayObject.value now returns an Array with the appropriate Range set instead of a list. This will change how the object is indexed to match the range of the simulation object, instead of 0 to len(handle)-1 like before. (#3733)

  • Renamed cocotb.handle.NonHierarchyIndexableObject to ArrayObject. (#3733)

  • Renamed cocotb.handle.NonHierarchyObject to ValueObjectBase. (#3733)

  • Improved VHPI implementation of cocotb.simulator.get_root_handle(). The name parameter is now used for handle lookup only as the last fallback, after checking it against the name of the vhpiRootInst object and its associated entity object. Handle lookup by name now always includes the : prefix so that it matches the FullName of the instantiated object, and will not match objects in the library information model. (#3774)

  • When constructing a LogicArray, if the given value cannot fit in the given range, an OverflowError is now thrown, instead of a ValueError. (#3792)

  • The cocotb.scheduler module and cocotb.scheduler object have been made private. (#3806)

  • The base class for Python runners has been renamed from Simulator to Runner. (#4025)

  • Moved SimTimeoutError from cocotb.result to cocotb.triggers. (#4039)

  • cocotb.external and cocotb.function have been renamed to cocotb.bridge() and cocotb.resume() to better reflect their intended use case. (#4054)

  • Updated ValueObjectBase.setimmediatevalue() to use GPI_NO_DELAY to set values, so values are actually set immediately and can be read back immediately. (#4068)

  • Writes performed following an await on ReadWrite will be applied immediately (but inertially) and not scheduled for the next ReadWrite. (#4115)

  • Attempting to await on either the ReadWrite or ReadOnly trigger while in the ReadOnly phase now raises a RuntimeError. (#4208)

cocotb 1.9.1 (2024-08-29)

Bugfixes

  • Improve the Verilator Makefile to pass on --trace at runtime as well. (#4088)

  • Pass EXTRA_ARGS in the Verilator Makefile to both the compilation and the simulation step.

Changes

  • Support setuptools 72.2.0

cocotb 1.9.0 (2024-07-14)

Features

  • Not using parentheses on @cocotb.test decorator is now supported. (#2731)

  • The cocotb.runner.Simulator.build() method now accepts a clean argument to remove build_dir completely during build stage. (#3351)

  • Added support for the NVC VHDL simulator. (#3427)

  • Added SIM_CMD_SUFFIX to allow users to redirect simulator output or otherwise suffix the simulation command invocation. (#3561)

  • Added --trace command line argument to Verilator simulation binaries for run-time trace generation. This new argument is passed to the binary when the waves argument to cocotb.runner.Simulator.test() is True. (#3667)

  • The cocotb.runner.Simulator.build() and cocotb.runner.Simulator.test() methods now accept a log_file argument to redirect stdout and stderr to the specified file. (#3668)

  • The results_xml argument to cocotb.runner.Simulator.test() can now be an absolute path. (#3669)

  • Added --trace-file command line argument to Verilator simulation binaries which specifies the trace file name. This can be passed to the binary by using the test_args argument to cocotb.runner.Simulator.test(). (#3683)

  • The cocotb.runner.Simulator.test() method now accepts a pre_cmd argument to run given commands before the simulation starts. These are typically Tcl commands for simulators that support them. Only support for the Questa simulator has been implemented. (#3744)

  • The sources option was added to cocotb.runner.Simulator.build() to better support building mixed-language designs. (#3796)

  • Enable use of VPI fallback in all simulators when attempting to access generate blocks directly via lookup. This enables better support for simulators that don’t support vpiGenScopeArray, allowing discovery of generate blocks without having to iterate over the parent handle. (#3817)

  • Added support for comparing BinaryValue with Logic, LogicArray, and str. (#3845)

  • Riviera-PRO now supports compilation into (multiple) VHDL libraries using VHDL_SOURCES_. (#3922)

Bugfixes

  • Xcelium 23.09.004 and newer can now be used to test designs with a VHDL toplevel. (#1076)

  • Fixed a potential issue where pseudo-region lookup may find the wrong generate block if the name of one generate block starts with the name of another generate block. (#2255)

  • Support waves argument to cocotb.runner.Simulator.build() for Verilator. (#3681)

  • The test_args argument to cocotb.runner.Simulator.test() is now passed to the Verilator simulation binary when running the simulation, which was previously missing. (#3682)

Deprecations and Removals

  • bool(Lock()) is deprecated. Use locked() instead. (#3871)

  • Join.retval is deprecated. Use Task.result() to get the result of a joined Task. (#3871)

  • Passing the outcome argument to NullTrigger - which allowed the user to inject arbitrary outcomes when the trigger was awaited - is deprecated. There is no alternative. (#3871)

  • Event.fired is deprecated. Use is_set() instead. (#3871)

Changes

  • For Aldec simulators, the -dbg and -O2 options are no longer passed by default, as they reduce simulation speed. Pass these options in COMPILE_ARGS and SIM_ARGS if you need them for increased observability. (#3490)

  • awaiting a Join trigger will yield the Join trigger and not the result of the task in the 2.0 release. (#3871)

  • Lock.locked is now a method rather than an attribute to mirror asyncio.Lock.locked(). (#3871)

cocotb 1.8.0 (2023-06-15)

Features

  • cocotb.types.LogicArray now supports a default value construction if a range is given. (#3031)

  • Add support for fraction.Fraction and decimal.Decimal to the period argument of cocotb.clock.Clock. (#3045)

  • This release adds the Python Test Runner, an experimental replacement for the traditional Makefile-based build and run flow. (#3103)

  • Incisive now supports compilation into a named VHDL library lib using VHDL_SOURCES_<lib>. (#3261)

  • Cocotb can now correctly drive Verilator when its new --timing flag is used. (#3316)

  • Creating an FST waveform dump in Icarus Verilog can now be done by setting the WAVES environment variable. Icarus-specific Verilog code is no longer required. (#3324)

Bugfixes

  • Fixed Verilator not writing coverage files in some cases. (#1478)

  • The Regression Manager now correctly handles exceptions raised in tests when the exceptions inherit from BaseException. (#3196)

  • Fix a performance regression when using Questa with FLI introduced in cocotb 1.7.0. (#3229)

  • Adds support for packed union in SystemVerilog when using Cadence Xcelium. (#3239)

  • Fixed RecursionError caused by certain corner cases in the scheduler. (#3267)

  • Fixed cleanup in scheduler which caused sporadic warning messages and bugs in some corner cases. (#3270)

  • Fix “use after free” bug in VHPI implementation causing Riviera to fail to discover some simulation objects. (#3307)

Changes

  • Removed level arg from _sim_event function in the PYGPI_ENTRY_POINT interface. This function can only indicate a request to shutdown from the simulator or GPI. (#3066)

  • Moved cocotb.task.Task and friends to cocotb.task module to alleviate internal cyclic import dependency. Users should update imports of the Task to import from the top-level cocotb namespace. (#3067)

  • Added support for VERILOG_INCLUDE_DIRS in the Makefiles. (#3189)

  • Changed platform support: Added Red Hat Enterprise Linux 9 (RHEL) and compatible clones, added macOS 13 x86_64 (Ventura on Intel), removed Ubuntu 18.04 (end-of-life). Note that Python wheels compatible with Ubuntu 18.04 remain available for the time being. Even though the cocotb project does not provide pre-compiled binaries for unsupported platforms users can typically compile cocotb themselves, as done automatically when running pip install.

cocotb 1.7.2 (2022-11-15)

Changes

  • Python 3.11 is now supported.

  • find_libpython, a library to find (as the name indicates) libpython, is now a dependency of cocotb. Its latest version resolves an issue for users on RedHat Enterprise Linux (RHEL) 8 and Python 3.8, where the correct Python library would not be detected. (#3097)

Bugfixes

  • Fixed a segmentation fault in Aldec Riviera-PRO that prevented mixed-language simulation from running. (#3078)

cocotb 1.7.1 (2022-09-17)

Bugfixes

  • Fixed the packaging of the source distribution (sdist) to include all necessary files. (#3072)

  • Documented the fact that libstdc++-static needs to be available on some Linux distributions to install cocotb from source. (#3082)

cocotb 1.7.0 (2022-09-06)

Features

  • Removed the need for ModelSim or Questa being installed when building cocotb. Similar to the approach taken with VPI and VHPI, cocotb now includes all C header files to build the FLI interface. This improvement was done in close collaboration with Siemens EDA, who changed the license of the relevant source code file. (#2948)

  • With Questa 2022.3 VHPI support is now fully working and no longer experimental. cocotb still defaults to using the FLI interface for VHDL toplevels with Questa. Users can choose VHPI instead by setting the VHDL_GPI_INTERFACE environment variable to vhpi before running cocotb. (#2803)

  • cocotb tests are now more reproducible. (#2721)

  • Force, Freeze, and Release are now supported when using the FLI, Questa’s traditional method to access VHDL. (#2775)

  • cocotb binaries now statically link libstdc++ on Linux, which prevents library load errors even if the simulator ships its own libstdc++. (#3002)

Bugfixes

  • Fixed write scheduling to apply writes oldest to newest. (#2792)

  • Fixed Riviera makefile error for mixed-language simulation when VHDL is the top-level. This bug prevented the VPI library from loading correctly, and was a regression in 1.5.0. (#2912)

  • Fixed FLI issue where unprimed triggers were still firing. (#3010)

Deprecations and Removals

Changes

  • Passing coroutines to with_timeout() is now supported. (#2494)

  • Renamed RunningTask to Task. (#2876)

  • Made Task interface more like asyncio.Task’s. (#2876)

  • When code coverage is enabled with COVERAGE and a configuration file is specified with COVERAGE_RCFILE, default coverage configuration is not applied to avoid overriding the user-defined configuration. (#3014)

cocotb 1.6.2 (2022-02-07)

Bugfixes

  • Fix regression in TestFactory when using generator-based test coroutines. (#2839)

Changes

  • Change how PYTHONHOME is populated to work with broken mingw environments. (#2739)

cocotb 1.6.1 (2021-12-07)

Bugfixes

cocotb 1.6.0 (2021-10-20)

Features

Bugfixes

  • VHDL signals that are zero bits in width now read as the integer 0, instead of raising an exception. (#2294)

  • Correctly parse plusargs with =s in the value. (#2483)

  • COCOTB_RESULTS_FILE now properly communicates with the Regression Manager to allow overloading the result filename. (#2487)

  • Fixed several scheduling issues related to the use of cocotb.start_soon(). (#2504)

  • Verilator and Icarus now support running without specifying a TOPLEVEL. (#2547)

  • Fixed discovery of signals inside SystemVerilog interfaces. (#2683)

Improved Documentation

Deprecations and Removals

  • Setting values on indexed handles using the handle[i] = value syntax is deprecated. Instead use the handle[i].value = value syntax. (#2490)

  • Setting values on handles using the dut.handle = value syntax is deprecated. Instead use the handle.value = value syntax. (#2490)

  • Setting values on handles using the signal <= newval syntax is deprecated. Instead, use the signal.value = newval syntax. (#2681)

  • cocotb.utils.hexdump is deprecated; use scapy.utils.hexdump() instead. (#2691)

  • cocotb.utils.hexdiffs is deprecated; use scapy.utils.hexdiff() instead. (#2691)

  • Passing None to cocotb.utils.get_sim_time() is deprecated; use 'step' as the time unit instead. (#2691)

  • The stdout and stderr attributes on cocotb.result.TestComplete and subclasses are deprecated. (#2692)

  • TestFailure is deprecated, use an assert statement instead. (#2692)

Changes

  • Assigning out-of-range Python integers to signals will now raise an OverflowError. (#2316)

  • cocotb now requires Python 3.6+. (#2422)

  • Selecting tests using TESTCASE will now search for the first occurrence of a test of that name in order of modules listed in MODULEs, and not just the first module in that list. (#2434)

  • The environment variable COCOTB_LOG_LEVEL now supports TRACE value, which is used for verbose low-level logging that was previously in DEBUG logs. (#2502)

  • Improves formatting on test-related logging outputs. (#2564)

  • Shorter log lines (configurable with COCOTB_REDUCED_LOG_FMT) are now the default. For wider log output, similar to previous cocotb releases, set the COCOTB_REDUCED_LOG_FMT environment variable to 0. (#2564)

cocotb 1.5.2 (2021-05-03)

Bugfixes

  • Changed some makefile syntax to support GNU Make 3. (#2496)

  • Fixed behavior of cocotb-config --libpython when finding libpython fails. (#2522)

cocotb 1.5.1 (2021-03-20)

Bugfixes

  • Prevent pytest assertion rewriting (#2028) from capturing stdin, which causes problems with IPython support. (#1649) (#2462)

  • Add dependency on cocotb_bus to prevent breaking users that were previously using the bus and testbenching objects. (#2477)

  • Add back functionality to cocotb.binary.BinaryValue that allows the user to change binaryRepresentation after object creation. (#2480)

cocotb 1.5.0 (2021-03-11)

Features

  • Support for building with Microsoft Visual C++ has been added. See Installation for more details. (#1798)

  • Makefiles now automatically deduce TOPLEVEL_LANG based on the value of VERILOG_SOURCES and VHDL_SOURCES. Makefiles also detect incorrect usage of TOPLEVEL_LANG for simulators that only support one language. (#1982)

  • cocotb.fork() will now raise a descriptive TypeError if a coroutine function is passed into them. (#2006)

  • Added cocotb.scheduler.start_soon() which schedules a coroutine to start after the current coroutine yields control. This behavior is distinct from cocotb.fork() which schedules the given coroutine immediately. (#2023)

  • If pytest is installed, its assertion-rewriting framework will be used to produce more informative tracebacks from the assert statement. (#2028)

  • The handle to TOPLEVEL, typically seen as the first argument to a cocotb test function, is now available globally as cocotb.top. (#2134)

  • The units argument to Timer, Clock and get_sim_steps(), and the timeout_unit argument to with_timeout() and cocotb.test now accepts 'step' to mean the simulator time step. This used to be expressed using None, which is now deprecated. (#2171)

  • TestFactory.add_option() now supports groups of options when a full Cartesian product is not desired. (#2175)

  • Added asyncio-style queues, Queue, PriorityQueue, and LifoQueue. (#2297)

  • Support for the SystemVerilog type bit has been added. (#2322)

  • Added the --lib-dir, --lib-name and --lib-name-path options to the cocotb-config command to make cocotb integration into existing flows easier. (#2387)

  • Support for using Questa’s VHPI has been added. Use VHDL_GPI_INTERFACE to select between using the FLI or VHPI when dealing with VHDL simulations. Note that VHPI support in Questa is still experimental at this time. (#2408)

Bugfixes

  • Assigning Python integers to signals greater than 32 bits wide will now work correctly for negative values. (#913)

  • Fix GHDL’s library search path, allowing libraries other than work to be used in simulation. (#2038)

  • Tests skipped by default (created with skip=True) can again be run manually by setting the TESTCASE variable. (#2045)

  • In Icarus Verilog, generate blocks are now accessible directly via lookup without having to iterate over parent handle. (#2079, #2143)

    # Example pseudo-region
dut.genblk1       #<class 'cocotb.handle.HierarchyArrayObject'>

  • Fixed an issue with VHPI on Mac OS and Linux where negative integers were returned as large positive values. (#2129)

Improved Documentation

Deprecations and Removals

  • The contents of cocotb.generators have been deprecated. (#2047)

  • The outdated “Sorter” example has been removed from the documentation. (#2049)

  • Passing bool values to expect_error option of cocotb.test is deprecated. Pass a specific Exception or a tuple of Exceptions instead. (#2117)

  • The system task overloads for $info, $warn, $error and $fatal in Verilog and mixed language testbenches have been removed. (#2133)

  • TestError has been deprecated, use Built-in Exceptions. (#2177)

  • The undocumented class cocotb.xunit_reporter.File has been removed. (#2200)

  • Deprecated cocotb.hook and COCOTB_HOOKS. See the documentation for cocotb.hook for suggestions on alternatives. (#2201)

  • Deprecate cocotb.utils.pack and cocotb.utils.unpack and the use of ctypes.Structure in signal assignments. (#2203)

  • The outdated “ping” example has been removed from the documentation and repository. (#2232)

  • Using the undocumented custom format dict object in signal assignments has been deprecated. (#2240)

  • The access modes of many interfaces in the cocotb core libraries were re-evaluated. Some interfaces that were previously public are now private and vice versa. Accessing the methods through their old name will create a DeprecationWarning. In the future, the deprecated names will be removed. (#2278)

  • The bus and testbenching components in cocotb have been officially moved to the cocotb-bus package. This includes Bus, Scoreboard, everything in cocotb_bus.drivers, and everything in cocotb_bus.monitors. Documentation will remain in the main cocotb repository for now. Old names will continue to exist, but their use will cause a DeprecationWarning, and will be removed in the future. (#2289)

Changes

  • Assigning negative Python integers to handles does an implicit two’s compliment conversion. (#913)

  • Updated Driver, Monitor, and all their subclasses to use the async/await syntax instead of the yield syntax. (#2022)

  • The package build process is now fully PEP 517 compliant. (#2091)

  • Improved support and performance for Verilator (version 4.106 or later now required). (#2105)

  • Changed how libraries are specified in GPI_EXTRA to allow specifying libraries with paths, and names that don’t start with “lib”. (#2341)

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 the 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.logging.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 cocotb.handle.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 cocotb.handle.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)

  • cocotb.binary.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:

    • cocotb.binary.BinaryValue.buff, which as a consequence means cocotb.binary.BinaryValue.assign, no longer accepts malformed 10xz-style strs (which were treated as binary).

    • The objects produced by cocotb.generators.byte, which means that single bytes are represented by int instead of 1-character strs.

    • The packets produced by the AvalonSTPkts.

    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)

cocotb 1.3.2

Released on 08 July 2020

Notable changes and bug fixes

  • 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.1. (#1882)

cocotb 1.3.1

Released on 15 March 2020

Notable changes and bug fixes

  • The Makefiles for the Aldec Riviera and Cadence Incisive simulators have been fixed to use the correct name of the VHPI library (libcocotbvhpi). This bug prevented VHDL designs from being simulated, and was a regression in 1.3.0. (#1472)

cocotb 1.3.0

Released on 08 January 2020

This will likely be the last release to support Python 2.7.

New features

  • Initial support for the Verilator simulator (version 4.020 and above). The integration of Verilator into cocotb is not yet as fast or as powerful as it is for other simulators. Please use the latest version of Verilator, and report bugs if you experience problems.

  • New makefile variables COCOTB_HDL_TIMEUNIT and COCOTB_HDL_TIMEPRECISION for setting the default time unit and precision that should be assumed for simulation when not specified by modules in the design. (#1113)

  • New timeout_time and timeout_unit arguments to cocotb.test(), for adding test timeouts. (#1119)

  • with_timeout(), for a shorthand for waiting for a trigger with a timeout. (#1119)

  • The expect_error argument to cocotb.test() now accepts a specific exception type. (#1116)

  • New environment variable COCOTB_RESULTS_FILE, to allow configuration of the xUnit XML output filename. (#1053)

  • A new bus_separator argument to cocotb.drivers.BusDriver. (#1160)

  • A new start_high argument to cocotb.clock.Clock.start(). (#1036)

  • A new cocotb.__version__ constant, which contains the version number of the running cocotb. (#1196)

Notable changes and bug fixes

  • DeprecationWarnings are now shown in the output by default.

  • Tracebacks are now preserved correctly for exceptions in Python 2. The tracebacks in all Python versions are now a little shorter.

  • cocotb.bridge() and cocotb.resume() now work more reliably and with fewer race conditions.

  • A failing assert will be considered a test failure. Previously, it was considered a test error.

  • drivers() and loads() now also work correctly in Python 3.7 onwards.

  • Timer can now be used with decimal.Decimal instances, allowing constructs like Timer(Decimal("1e-9"), units="sec") as an alternate spelling for Timer(100, units="us"). (#1114)

  • Many (editorial) documentation improvements.

Deprecations

  • cocotb.result.raise_error and cocotb.result.create_error are deprecated in favor of using Python exceptions directly. TestError can still be used if the same exception type is desired. (#1109)

  • The AvalonSTPktsWithChannel type is deprecated. Use the report_channel argument to AvalonSTPkts instead.

  • The colour attribute of log objects like cocotb.log or some_coro.log is deprecated. Use cocotb.utils.want_color_output instead. (#1231)

Other news

cocotb 1.2.0

Released on 24 July 2019

New features

  • cocotb is now built as Python package and installable through pip. (#517, #799, #800, #803, #805)

  • Support for async functions and generators was added (Python 3 only). Please have a look at Coroutines and Tasks for an example how to use this new feature.

  • VHDL block statements can be traversed. (#850)

  • Support for Python 3.7 was added.

Notable changes and bug fixes

  • The heart of cocotb, its scheduler, is now even more robust. Many small bugs, inconsistencies and unreliable behavior have been ironed out.

  • Exceptions are now correctly propagated between coroutines, giving users the “natural” behavior they’d expect with exceptions. (#633)

  • The setimmediatevalue() function now works for values larger than 32 bit. (#768)

  • The documentation was cleaned up, improved and extended in various places, making it more consistent and complete.

  • Tab completion in newer versions of IPython is fixed. (#825)

  • Python 2.6 is officially not supported any more. cocotb supports Python 2.7 and Python 3.5+.

  • The cocotb GitHub project moved from potentialventures/cocotb to cocotb/cocotb. Redirects for old URLs are in place.

Deprecations

  • The bits argument to cocotb.binary.BinaryValue, which is now called n_bits.

  • The logger attribute of log objects like cocotb.log or some_coro.log, which is now just an alias for self.

  • The cocotb.utils.get_python_integer_types function, which was intended to be private.

Known issues

  • Depending on your simulation, cocotb 1.2 might be roughly 20 percent slower than cocotb 1.1. Much of the work in this release cycle went into fixing correctness bugs in the scheduler, sometimes at the cost of performance. We are continuing to investigate this in issue #961. Independent of the cocotb version, we recommend using the latest Python 3 version, which is shown to be significantly faster than previous Python 3 versions, and slightly faster than Python 2.7.

Please have a look at the issue tracker for more outstanding issues and contribution opportunities.

cocotb 1.1

Released on 24 January 2019.

This release is the result of four years of work with too many bug fixes, improvements and refactorings to name them all.

cocotb 1.0

Released on 15 February 2015.

New features

  • FLI support for ModelSim

  • Mixed Language, Verilog and VHDL

  • Windows

  • 300% performance improvement with VHPI interface

  • WaveDrom support for wave diagrams.

cocotb 0.4

Released on 25 February 2014.

New features

  • Issue #101: Implement Lock primitive to support mutex

  • Issue #105: Compatibility with Aldec Riviera-Pro

  • Issue #109: Combine multiple results.xml into a single results file

  • Issue #111: XGMII drivers and monitors added

  • Issue #113: Add operators to BinaryValue class

  • Issue #116: Native VHDL support by implementing VHPI layer

  • Issue #117: Added AXI4-Lite Master BFM

Bugs fixed

  • Issue #100: Functional bug in endian_swapper example RTL

  • Issue #102: Only 1 coroutine wakes up of multiple coroutines wait() on an Event

  • Issue #114: Fix build issues with Cadence IUS simulator

New examples

  • Issue #106: TUN/TAP example using ping

cocotb 0.3

Released on 27 September 2013.

This contains a raft of fixes and feature enhancements.

cocotb 0.2

Released on 19 July 2013.

New features

  • Release 0.2 supports more simulators and increases robustness over 0.1.

  • A centralized installation is now supported (see documentation) with supporting libraries build when the simulation is run for the first time.

cocotb 0.1

Released on 9 July 2013.

  • The first release of cocotb.

  • Allows installation and running against Icarus, VCS, Aldec simulators.