cocotb 2.0.0.dev0+ce15cd8 (2024-05-16)

Features

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

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

• Python 3.12 is now supported. (#3409)

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

• Added cocotb.parameterize(), a decorator that serves as an alternative to TestFactory. (#3513)

• Added cocotb.packages, a types.SimpleNamespace which contains handles to SystemVerilog packages in a design. (#3536)

• Added SIM_OUTPUT_REDIRECT, an environment variable to control how simulator output is redirected. (#3561)

• The current Git revision will now be added to cocotb.__version__ for all dev versions. (#3568)

• The cocotb.test() decorator now accepts a name argument to override the name of the test in the RegressionManager. (#3578)

• Add support for handle[sub_handle_name] syntax to HierarchyObject as a more readable alternative to HierarchyObject._id(). (#3655)

• Added range, left, direction, right, and len() support to HierarchyArrayObject. (#3655)

• Added _keys(), _values(), and _items() to help users dynamically interact with the DUT object model. (#3655)

• Array now supports equality with list and tuple. (#3659)

• 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_tools.runner.Simulator.test() is True. (#3667)

• The cocotb_tools.runner.Simulator.build() and cocotb_tools.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_tools.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_tools.runner.Simulator.test(). (#3683)

• Support comparing LogicArray with str, list, and tuple. (#3696)

• Support specifying arguments like in TestFactory.add_option() in cocotb.parameterize(). (#3717)

• Use parameter values in generated test names of cocotb.parameterize(), which should be clearer and allow the user to better group tests using COCOTB_TEST_FILTER. (#3717)

• set() was added to value-having simulation object handles as an alternative to the value property that provides correct type checking information. (#3733)

• The cocotb_tools.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)

• Introduced cocotb.is_simulation which is True only when the cocotb library was loaded in a simulation. (#3779)

• The combine_results.py script now ships with the cocotb installation. (#3791)

• Added LogicArray.from_unsigned() and LogicArray.from_signed() to construct LogicArray from int. (#3792)

• Added LogicArray.to_unsigned() and LogicArray.to_signed() to convert LogicArray into int. (#3792)

• The sources option was added to cocotb_tools.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 COCOTB_TEST_FILTER which filters tests like TESTCASE, but is a regular expression to allow for more expressive test filtering. (#3841)

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 cocotb_tools.runner.Simulator.build() for Verilator. (#3681)

• The test_args argument to cocotb_tools.runner.Simulator.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)

• 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.parameterize 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 cocotb.runner.Simulator.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)

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.function() and cocotb.external() 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 with the appropriate Range set. (#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)

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

• Renamed cocotb.handle.NonHierarchyIndexableObjectBase to IndexableValueObjectBase. (#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)