cocotb 2.0.0.dev0+248b95c (2024-04-22)
Features
Not using parentheses on
@cocotb.test
decorator is now supported. (#2731)The
cocotb_tools.runner.Simulator.build()
method now accepts aclean
argument to removebuild_dir
completely during build stage. (#3351)Python 3.12 is now supported. (#3409)
Added
cocotb.parameterize()
, a decorator that serves as an alternative toTestFactory
. (#3513)Added
cocotb.packages
, atypes.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 alldev
versions. (#3568)The
cocotb.test()
decorator now accepts aname
argument to override the name of the test in theRegressionManager
. (#3578)Add support for
handle[sub_handle_name]
syntax toHierarchyObject
as a more readable alternative toHierarchyObject._id()
. (#3655)Added
range
,left
,direction
,right
, andlen()
support toHierarchyArrayObject
. (#3655)Added
_keys()
,_values()
, and_items()
to help users dynamically interact with the DUT object model. (#3655)Added
--trace
command line argument to Verilator simulation binaries for run-time trace generation. This new argument is passed to the binary when thewaves
argument tococotb_tools.runner.Simulator.test()
isTrue
. (#3667)The
cocotb_tools.runner.Simulator.build()
andcocotb_tools.runner.Simulator.test()
methods now accept alog_file
argument to redirect stdout and stderr to the specified file. (#3668)The
results_xml
argument tococotb_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 thetest_args
argument tococotb_tools.runner.Simulator.test()
. (#3683)Support comparing
LogicArray
withstr
,list
, andtuple
. (#3696)Support specifying arguments like in
TestFactory.add_option()
incocotb.parameterize()
. (#3717)Use parameter values in generated test names of
cocotb.parameterize()
, which should be clearer and allow the user to better group tests usingCOCOTB_TEST_FILTER
. (#3717)set()
was added to value-having simulation object handles as an alternative to thevalue
property that provides correct type checking information. (#3733)The
cocotb_tools.runner.Simulator.test()
method now accepts apre_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 isTrue
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()
andLogicArray.from_signed()
to constructLogicArray
fromint
. (#3792)Added
LogicArray.to_unsigned()
andLogicArray.to_signed()
to convertLogicArray
intoint
. (#3792)The
sources
option was added tococotb_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 likeTESTCASE
, 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 tococotb_tools.runner.Simulator.build()
for Verilator. (#3681)The
test_args
argument tococotb_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, useValueObjectBase
instead. (#2720)Iteration of and querying length and range of
IntegerObject
,EnumObject
, andRealObject
have been removed. (#2720)The deprecated
cocotb.fork
function was removed. (#3425)Support for generator-based coroutines, which used the
cocotb.coroutine
decorator andyield
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 theasync
andawait
syntax. (#3509)Removed
cocotb.types.Bit
. (#3549)The
prefix
andpostfix
arguments toTestFactory.generate_tests()
are deprecated in favor of the more flexiblename
argument. (#3578)Methods
get_definition_name()
andget_definition_file()
ofcocotb.handle.SimHandleBase
were removed in favor of_def_name()
and_def_file()
, respectively. (#3609)cocotb.binary.BinaryValue
,cocotb.binary.BinaryRepresentation
, and thecocotb.binary
module have been removed in favor ofLogicArray
. See the guide for a tutorial on upgrading toLogicArray
. (#3634)HierarchyObject._id()
is now deprecated. Usehandle["sub_handle_name"]
syntax instead. (#3655)Removed
cocotb.logging.SimLog
, uselogging.getLogger()
instead. (#3673)cocotb.types.concat
was removed. UseArray(itertools.chain(a, b))
instead. (#3705)TestFactory
is now deprecated. Usecocotb.parameterize
instead. (#3717)cocotb.handle.ModifiableObject
was removed along with its non-functionaldrivers()
andloads()
methods. (#3733)cocotb.RANDOM_SEED
was made private. (#3779)cocotb.LANGUAGE
was removed, useos.environ["TOPLEVEL_LANG"]
if you need that information. (#3779)Removed
cocotb.argc
. Uselen(cocotb.argv)
instead. (#3779)LogicArray.integer
has been deprecated. UseLogicArray.to_unsigned()
instead. (#3792)Constructing a
LogicArray
from anint
is deprecated. UseLogicArray.from_unsigned()
andLogicArray.from_signed()
instead. (#3792)LogicArray.signed_integer
has been deprecated. UseLogicArray.to_signed()
instead. (#3792)LogicArray.binstr
has been deprecated. Usestr(logic_array)
instead. (#3792)Deprecated the
verilog_sources
andvhdl_sources
parameters tococotb.runner.Simulator.build()
. Use the language-agnosticsources
parameter instead. (#3836)
Changes
cocotb.handle.ConstantObject
was removed. Constant value objects are now returned as their correspondingsimulator value object
subtype (e.g. integers in VHDL and Verilog are nowIntegerObject
s). You can check if the value object is constant using theis_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 thevalue()
property; then cast the value. (#2720)All
simulator objects
when cast to astr
now return therepr
of the object and not thepath
. (#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 likedict
andset
. (#2720)std_(u)logic_vector
andstd_(u)logic
signals and constants in VHDL, andlogic
and packed arrays oflogic
signals and parameters in Verilog are nowLogicObject
s. (#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()
andcocotb.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
andSIM_ARGS
if you need them for increased observability. (#3490)Use of the
TESTCASE
variable has been changed so that each element ofTESTCASE
will now select all tests with a matching name across allMODULE
s instead of just the first one found. (#3578)The
cocotb.test()
decorator now returns the decorated object instead of aTest
object. (#3578)The
RegressionManager
uses a new mechanism to discover tests. Typical uses of thecocotb.test()
decorator andTestFactory
should be unaffected, but atypical uses may not. (#3578)Getting a value with
LogicObject.value
now returns aLogicArray
with the appropriateRange
set. (#3634)cocotb.handle.RegionObject
was renamed toHierarchyObjectBase
. (#3655)The module
cocotb.xunit_reporter
was made private. (#3672)The module
cocotb.outcomes
was made private. (#3672)The module
cocotb.log
was renamed tococotb.logging
to prevent clashing withcocotb.log
. (#3673)Moved
cocotb.config
tococotb_tools.config
andcocotb.runner
tococotb_tools.runner
to improve startup speed. (#3731)Renamed
cocotb.handle.NonHierarchyIndexableObject
toArrayObject
. (#3733)Renamed
cocotb.handle.NonHierarchyIndexableObjectBase
toIndexableValueObjectBase
. (#3733)Renamed
cocotb.handle.NonHierarchyObject
toValueObjectBase
. (#3733)Improved VHPI implementation of
cocotb.simulator.get_root_handle()
. Thename
parameter is now used for handle lookup only as the last fallback, after checking it against the name of thevhpiRootInst
object and its associatedentity
object. Handle lookup by name now always includes the:
prefix so that it matches theFullName
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, anOverflowError
is now thrown, instead of aValueError
. (#3792)The
cocotb.scheduler
module andcocotb.scheduler
object have been made private. (#3806)