Library Reference¶
Test Results¶
The exceptions in this module can be raised at any point by any code and will terminate the test.
-
cocotb.result.
raise_error
(obj, msg)[source]¶ Create a
TestError
exception and raise it after printing a traceback.Deprecated since version 1.3: Use
raise TestError(msg)
instead of this function. A stacktrace will be printed by cocotb automatically if the exception is unhandled.- Parameters
obj – Object with a log method.
msg (str) – The log message.
-
cocotb.result.
create_error
(obj, msg)[source]¶ Like
raise_error()
, but return the exception rather than raise it, simply to avoid too many levels of nested try/except blocks.Deprecated since version 1.3: Use
TestError(msg)
directly instead of this function.- Parameters
obj – Object with a log method.
msg (str) – The log message.
-
exception
cocotb.result.
ReturnValue
(retval)[source]¶ Helper exception needed for Python versions prior to 3.3.
Deprecated since version 1.4: Use a
return
statement instead; this works in all supported versions of Python.
-
exception
cocotb.result.
TestComplete
(*args, **kwargs)[source]¶ Exception showing that the test was completed. Sub-exceptions detail the exit status.
-
exception
cocotb.result.
ExternalException
(exception)[source]¶ Exception thrown by
cocotb.external
functions.
-
exception
cocotb.result.
TestError
(*args, **kwargs)[source]¶ Exception showing that the test was completed with severity Error.
-
exception
cocotb.result.
TestFailure
(*args, **kwargs)[source]¶ Exception showing that the test was completed with severity Failure.
-
exception
cocotb.result.
TestSuccess
(*args, **kwargs)[source]¶ Exception showing that the test was completed successfully.
Writing and Generating tests¶
-
class
cocotb.
test
(*args, **kwargs)[source]¶ Decorator to mark a function as a test.
All tests are coroutines. The test decorator provides some common reporting etc., a test timeout and allows us to mark tests as expected failures.
Tests are evaluated in the order they are defined in a test module.
Used as
@cocotb.test(...)
.- Parameters
timeout_time (numbers.Real or decimal.Decimal, optional) –
Simulation time duration before timeout occurs.
New in version 1.3.
Note
Test timeout is intended for protection against deadlock. Users should use
with_timeout
if they require a more general-purpose timeout mechanism.timeout_unit (str or None, optional) –
Units of timeout_time, accepts any units that
Timer
does.New in version 1.3.
expect_fail (bool, optional) – Don’t mark the result as a failure if the test fails.
expect_error (bool or exception type or tuple of exception types, optional) –
If
True
, consider this test passing if it raises anyException
, and failing if it does not. If given an exception type or tuple of exception types, catching only a listed exception type is considered passing. This is primarily for cocotb internal regression use for when a simulator error is expected.Users are encouraged to use the following idiom instead:
@cocotb.test() async def my_test(dut): try: await thing_that_should_fail() except ExceptionIExpect: pass else: assert False, "Exception did not occur"
Changed in version 1.3: Specific exception types can be expected
skip (bool, optional) – Don’t execute this test as part of the regression.
stage (int, optional) – Order tests logically into stages, where multiple tests can share a stage.
-
class
cocotb.
coroutine
(func)[source]¶ Decorator class that allows us to provide common coroutine mechanisms:
log
methods will log tococotb.coroutine.name
.join()
method returns an event which will fire when the coroutine exits.Used as
@cocotb.coroutine
.
-
class
cocotb.
external
(func)[source]¶ Decorator to apply to an external function to enable calling from cocotb.
This turns a normal function that isn’t a coroutine into a blocking coroutine. Currently, this creates a new execution thread for each function that is called. Scope for this to be streamlined to a queue in future.
-
class
cocotb.
function
(func)[source]¶ Decorator class that allows a function to block.
This allows a coroutine that consumes simulation time to be called by a thread started with
cocotb.external
; in other words, to internally block while externally appear to yield.
-
class
cocotb.
hook
(*args, **kwargs)[source]¶ Decorator to mark a function as a hook for cocotb.
Used as
@cocotb.hook()
.All hooks are run at the beginning of a cocotb test suite, prior to any test code being run.
-
class
cocotb.regression.
TestFactory
(test_function, *args, **kwargs)[source]¶ Factory to automatically generate tests.
- Parameters
test_function – The function that executes a test. Must take dut as the first argument.
*args – Remaining arguments are passed directly to the test function. Note that these arguments are not varied. An argument that varies with each test must be a keyword argument to the test function.
**kwargs – Remaining keyword arguments are passed directly to the test function. Note that these arguments are not varied. An argument that varies with each test must be a keyword argument to the test function.
Assuming we have a common test function that will run a test. This test function will take keyword arguments (for example generators for each of the input interfaces) and generate tests that call the supplied function.
This Factory allows us to generate sets of tests based on the different permutations of the possible arguments to the test function.
For example if we have a module that takes backpressure and idles and have some packet generation routines
gen_a
andgen_b
:>>> tf = TestFactory(test_function=run_test) >>> tf.add_option(name='data_in', optionlist=[gen_a, gen_b]) >>> tf.add_option('backpressure', [None, random_backpressure]) >>> tf.add_option('idles', [None, random_idles]) >>> tf.generate_tests()
We would get the following tests:
gen_a
with no backpressure and no idlesgen_a
with no backpressure andrandom_idles
gen_a
withrandom_backpressure
and no idlesgen_a
withrandom_backpressure
andrandom_idles
gen_b
with no backpressure and no idlesgen_b
with no backpressure andrandom_idles
gen_b
withrandom_backpressure
and no idlesgen_b
withrandom_backpressure
andrandom_idles
The tests are appended to the calling module for auto-discovery.
Tests are simply named
test_function_N
. The docstring for the test (hence the test description) includes the name and description of each generator.-
generate_tests
(prefix='', postfix='')[source]¶ Generate an exhaustive set of tests using the cartesian product of the possible keyword arguments.
The generated tests are appended to the namespace of the calling module.
- Parameters
prefix (str) – Text string to append to start of
test_function
name when naming generated test cases. This allows reuse of a singletest_function
with multipleTestFactories
without name clashes.postfix (str) – Text string to append to end of
test_function
name when naming generated test cases. This allows reuse of a singletest_function
with multipleTestFactories
without name clashes.
Interacting with the Simulator¶
-
class
cocotb.binary.
BinaryRepresentation
[source]¶ -
UNSIGNED
= 0¶ Unsigned format
-
SIGNED_MAGNITUDE
= 1¶ Sign and magnitude format
-
TWOS_COMPLEMENT
= 2¶ Two’s complement format
-
-
class
cocotb.binary.
BinaryValue
(value=None, n_bits=None, bigEndian=True, binaryRepresentation=0, bits=None)[source]¶ Representation of values in binary format.
The underlying value can be set or accessed using these aliasing attributes:
BinaryValue.integer
is an integerBinaryValue.signed_integer
is a signed integerBinaryValue.binstr
is a string of01xXzZ
BinaryValue.buff
is a binary buffer of bytesBinaryValue.value
is an integer deprecated
For example:
>>> vec = BinaryValue() >>> vec.integer = 42 >>> print(vec.binstr) 101010 >>> print(vec.buff) b'*'
- Parameters
value (str or int or long, optional) – Value to assign to the bus.
n_bits (int, optional) – Number of bits to use for the underlying binary representation.
bigEndian (bool, optional) – Interpret the binary as big-endian when converting to/from a string buffer.
binaryRepresentation (BinaryRepresentation) – The representation of the binary value (one of
UNSIGNED
,SIGNED_MAGNITUDE
,TWOS_COMPLEMENT
). Defaults to unsigned representation.bits (int, optional) – Deprecated: Compatibility wrapper for
n_bits
.
-
assign
(value)[source]¶ Decides how best to assign the value to the vector.
Picks from the type of its argument whether to set
integer
,binstr
, orbuff
.
-
property
integer
¶ The integer representation of the underlying vector.
-
property
value
¶ Integer access to the value. deprecated
-
property
signed_integer
¶ The signed integer representation of the underlying vector.
-
property
is_resolvable
¶ Does the value contain any
X
’s? Inquiring minds want to know.
-
property
buff
¶ The value as a binary string buffer.
>>> BinaryValue("01000001" + "00101111").buff == b"\x41\x2F" True
-
property
binstr
¶ The binary representation stored as a string of
0
,1
, and possiblyx
,z
, and other states.
-
property
n_bits
¶ The number of bits of the binary value.
-
class
cocotb.bus.
Bus
(entity, name, signals, optional_signals=[], bus_separator='_', array_idx=None)[source]¶ Wraps up a collection of signals.
Assumes we have a set of signals/nets named
entity.<bus_name><separator><signal>
.For example a bus
stream_in
with signalsvalid
anddata
is assumed to be nameddut.stream_in_valid
anddut.stream_in_data
(with the default separator ‘_’).- Parameters
entity (SimHandle) –
SimHandle
instance to the entity containing the bus.name (str) – Name of the bus.
None
for a nameless bus, e.g. bus-signals in an interface or amodport
(untested onstruct
/record
, but could work here as well).signals (list or dict) – In the case of an object (passed to
drive()
/capture()
) that has the same attribute names as the signal names of the bus, the signals argument can be a list of those names. When the object has different attribute names, the signals argument should be a dict that maps bus attribute names to object signal names.optional_signals (list or dict, optional) – Signals that don’t have to be present on the interface. See the signals argument above for details.
bus_separator (str, optional) – Character(s) to use as separator between bus name and signal name. Defaults to ‘_’.
array_idx (int or None, optional) – Optional index when signal is an array.
-
drive
(obj, strict=False)[source]¶ Drives values onto the bus.
- Parameters
obj – Object with attribute names that match the bus signals.
strict (bool, optional) – Check that all signals are being assigned.
- Raises
AttributeError – If not all signals have been assigned when
strict=True
.
-
capture
()[source]¶ Capture the values from the bus, returning an object representing the capture.
- Returns
A dictionary that supports access by attribute, where each attribute corresponds to each signal’s value.
- Return type
- Raises
RuntimeError – If signal not present in bus, or attempt to modify a bus capture.
-
sample
(obj, strict=False)[source]¶ Sample the values from the bus, assigning them to obj.
- Parameters
obj – Object with attribute names that match the bus signals.
strict (bool, optional) – Check that all signals being sampled are present in obj.
- Raises
AttributeError – If attribute is missing in obj when
strict=True
.
-
cocotb.
fork
(coro)[source]¶ Schedule a coroutine to be run concurrently. See Coroutines for details on its use.
-
cocotb.decorators.RunningTask.
join
(self)¶ Return a trigger that will fire when the wrapped coroutine exits.
-
cocotb.decorators.RunningTask.
kill
(self)¶ Kill a coroutine.
Triggers¶
See Simulator Triggers for a list of sub-classes. Below are the internal
classes used within cocotb
.
-
class
cocotb.triggers.
Trigger
[source]¶ Base class to derive from.
-
abstract
prime
(callback)[source]¶ Set a callback to be invoked when the trigger fires.
The callback will be invoked with a single argument, self.
Sub-classes must override this, but should end by calling the base class method.
Do not call this directly within coroutines, it is intended to be used only by the scheduler.
-
unprime
()[source]¶ Remove the callback, and perform cleanup if necessary.
After being un-primed, a Trigger may be re-primed again in the future. Calling unprime multiple times is allowed, subsequent calls should be a no-op.
Sub-classes may override this, but should end by calling the base class method.
Do not call this directly within coroutines, it is intended to be used only by the scheduler.
-
abstract
-
class
cocotb.triggers.
GPITrigger
[source]¶ Base Trigger class for GPI triggers.
Consumes simulation time.
Testbench Structure¶
Driver¶
-
class
cocotb.drivers.
Driver
[source]¶ Class defining the standard interface for a driver within a testbench.
The driver is responsible for serializing transactions onto the physical pins of the interface. This may consume simulation time.
Constructor for a driver instance.
-
append
(transaction: Any, callback: Callable[[Any], Any] = None, event: cocotb.triggers.Event = None, **kwargs: Any) → None[source]¶ Queue up a transaction to be sent over the bus.
Mechanisms are provided to permit the caller to know when the transaction is processed.
- Parameters
transaction – The transaction to be sent.
callback – Optional function to be called when the transaction has been sent.
event –
Event
to be set when the transaction has been sent.**kwargs – Any additional arguments used in child class’
_driver_send
method.
-
send
(transaction: Any, sync: bool = True, **kwargs: Any) → None[source]¶ Blocking send call (hence must be “yielded” rather than called).
Sends the transaction over the bus.
- Parameters
transaction – The transaction to be sent.
sync – Synchronize the transfer by waiting for a rising edge.
**kwargs – Additional arguments used in child class’
_driver_send
method.
-
_driver_send
(transaction: Any, sync: bool = True, **kwargs: Any) → None[source]¶ Actual implementation of the send.
Sub-classes should override this method to implement the actual
send()
routine.- Parameters
transaction – The transaction to be sent.
sync – Synchronize the transfer by waiting for a rising edge.
**kwargs – Additional arguments if required for protocol implemented in a sub-class.
-
_send
(transaction: Any, callback: Callable[[Any], Any], event: cocotb.triggers.Event, sync: bool = True, **kwargs) → None[source]¶ Send coroutine.
- Parameters
transaction – The transaction to be sent.
callback – Optional function to be called when the transaction has been sent.
event – event to be set when the transaction has been sent.
sync – Synchronize the transfer by waiting for a rising edge.
**kwargs – Any additional arguments used in child class’
_driver_send
method.
-
-
class
cocotb.drivers.
BitDriver
(signal, clk, generator=None)[source]¶ Bases:
object
Drives a signal onto a single bit.
Useful for exercising ready/valid flags.
-
start
(generator: Iterable[Tuple[int, int]] = None) → None[source]¶ Start generating data.
- Parameters
generator –
Generator yielding data. The generator should yield tuples
(on, off)
with the number of cycles to be on, followed by the number of cycles to be off. Typically the generator should go on forever.Example:
bit_driver.start((1, i % 5) for i in itertools.count())
-
-
class
cocotb.drivers.
BusDriver
(entity: cocotb.handle.SimHandleBase, name: Optional[str], clock: cocotb.handle.SimHandleBase, **kwargs: Any)[source]¶ Bases:
cocotb.drivers.Driver
Wrapper around common functionality for buses which have:
a list of
_signals
(class attribute)a list of
_optional_signals
(class attribute)a clock
a name
an entity
- Parameters
entity – A handle to the simulator entity.
name – Name of this bus.
None
for a nameless bus, e.g. bus-signals in an interface or amodport
. (untested onstruct
/record
, but could work here as well).clock – A handle to the clock associated with this bus.
**kwargs – Keyword arguments forwarded to
cocotb.Bus
, see docs for that class for more information.
Constructor for a driver instance.
-
_driver_send
(transaction, sync: bool = True) → None[source]¶ Implementation for BusDriver.
- Parameters
transaction – The transaction to send.
sync – Synchronize the transfer by waiting for a rising edge.
-
_wait_for_signal
(signal)[source]¶ This method will return when the specified signal has hit logic
1
. The state will be in theReadOnly
phase so sim will need to move toNextTimeStep
before registering more callbacks can occur.
-
_wait_for_nsignal
(signal)[source]¶ This method will return when the specified signal has hit logic
0
. The state will be in theReadOnly
phase so sim will need to move toNextTimeStep
before registering more callbacks can occur.
-
class
cocotb.drivers.
ValidatedBusDriver
(entity: cocotb.handle.SimHandleBase, name: str, clock: cocotb.handle.SimHandleBase, *, valid_generator: Iterable[Tuple[int, int]] = None, **kwargs: Any)[source]¶ Bases:
cocotb.drivers.BusDriver
Same as a
BusDriver
except we support an optional generator to control which cycles are valid.- Parameters
entity (SimHandle) – A handle to the simulator entity.
name (str) – Name of this bus.
clock (SimHandle) – A handle to the clock associated with this bus.
valid_generator (generator, optional) – a generator that yields tuples of
(valid, invalid)
cycles to insert.
Constructor for a driver instance.
Monitor¶
-
class
cocotb.monitors.
Monitor
(callback=None, event=None)[source]¶ Base class for Monitor objects.
Monitors are passive ‘listening’ objects that monitor pins going in or out of a DUT. This class should not be used directly, but should be sub-classed and the internal
_monitor_recv
method should be overridden and decorated as acoroutine
. This_monitor_recv
method should capture some behavior of the pins, form a transaction, and pass this transaction to the internal_recv
method. The_monitor_recv
method is added to the cocotb scheduler during the__init__
phase, so it should not be yielded anywhere.The primary use of a Monitor is as an interface for a
Scoreboard
.- Parameters
callback (callable) – Callback to be called with each recovered transaction as the argument. If the callback isn’t used, received transactions will be placed on a queue and the event used to notify any consumers.
event (cocotb.triggers.Event) – Event that will be called when a transaction is received through the internal
_recv
method. Event.data is set to the received transaction.
-
add_callback
(callback)[source]¶ Add function as a callback.
- Parameters
callback (callable) – The function to call back.
-
wait_for_recv
(timeout=None)[source]¶ With timeout,
wait()
for transaction to arrive on monitor and return its data.- Parameters
timeout – The timeout value for
Timer
. Defaults toNone
.- Returns
Data of received transaction.
-
class
cocotb.monitors.
BusMonitor
(entity, name, clock, reset=None, reset_n=None, callback=None, event=None, bus_separator='_', array_idx=None)[source]¶ Bases:
cocotb.monitors.Monitor
Wrapper providing common functionality for monitoring buses.
-
property
in_reset
¶ Boolean flag showing whether the bus is in reset state or not.
-
property
Scoreboard¶
Common scoreboarding capability.
-
class
cocotb.scoreboard.
Scoreboard
(dut, reorder_depth=0, fail_immediately=True)[source]¶ Bases:
object
Generic scoreboarding class.
We can add interfaces by providing a monitor and an expected output queue.
The expected output can either be a function which provides a transaction or a simple list containing the expected output.
- Parameters
dut (SimHandle) – Handle to the DUT.
reorder_depth (int, optional) – Consider up to reorder_depth elements of the expected result list as passing matches. Default is 0, meaning only the first element in the expected result list is considered for a passing match.
fail_immediately (bool, optional) – Raise
TestFailure
immediately when something is wrong instead of just recording an error. Default isTrue
.
-
property
result
¶ Determine the test result, do we have any pending data remaining?
- Returns
If not all expected output was received or error were recorded during the test.
- Return type
-
compare
(got, exp, log, strict_type=True)[source]¶ Common function for comparing two transactions.
Can be re-implemented by a sub-class.
- Parameters
got – The received transaction.
exp – The expected transaction.
log – The logger for reporting messages.
strict_type (bool, optional) – Require transaction type to match exactly if
True
, otherwise compare its string representation.
- Raises
TestFailure – If received transaction differed from expected transaction when
fail_immediately
isTrue
. If strict_type isTrue
, also the transaction type must match.
-
add_interface
(monitor, expected_output, compare_fn=None, reorder_depth=0, strict_type=True)[source]¶ Add an interface to be scoreboarded.
Provides a function which the monitor will callback with received transactions.
Simply check against the expected output.
- Parameters
monitor – The monitor object.
expected_output – Queue of expected outputs.
compare_fn (callable, optional) – Function doing the actual comparison.
reorder_depth (int, optional) – Consider up to reorder_depth elements of the expected result list as passing matches. Default is 0, meaning only the first element in the expected result list is considered for a passing match.
strict_type (bool, optional) – Require transaction type to match exactly if
True
, otherwise compare its string representation.
- Raises
TypeError – If no monitor is on the interface or compare_fn is not a callable function.
Clock¶
-
class
cocotb.clock.
Clock
(signal, period, units=None)[source]¶ Simple 50:50 duty cycle clock driver.
Instances of this class should call its
start()
method andfork()
the result. This will create a clocking thread that drives the signal at the desired period/frequency.Example:
c = Clock(dut.clk, 10, 'ns') cocotb.fork(c.start())
- Parameters
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
fork()
):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 <= 1 await high_time dut.clk <= 0 await low_time
If you also want to change the timing during simulation, use this slightly more inefficient example instead where the
Timer
s inside the while loop are created with current delay values:async def custom_clock(): while True: dut.clk <= 1 await Timer(high_delay, units="ns") dut.clk <= 0 await Timer(low_delay, units="ns") high_delay = low_delay = 100 cocotb.fork(custom_clock()) await Timer(1000, units="ns") high_delay = low_delay = 10 # change the clock speed await Timer(1000, units="ns")
-
async
start
(cycles=None, start_high=True)[source]¶ Clocking coroutine. Start driving your clock by
fork()
ing a call to this.- Parameters
cycles (int, optional) – Cycle the clock cycles number of times, or if
None
then cycle the clock forever. Note:0
is not the same asNone
, as0
will cycle no times.start_high (bool, optional) –
Whether to start the clock with a
1
for the first half of the period. Default isTrue
.New in version 1.3.
Utilities¶
Collection of handy functions.
-
cocotb.utils.
get_time_from_sim_steps
(steps, units)[source]¶ Calculates simulation time in the specified units from the steps based on the simulator precision.
-
cocotb.utils.
get_sim_steps
(time, units=None)[source]¶ Calculates the number of simulation time steps for a given amount of time.
- Parameters
time (numbers.Real or decimal.Decimal) – The value to convert to simulation time steps.
units (str or None, optional) – String specifying the units of the result (one of
None
,'fs'
,'ps'
,'ns'
,'us'
,'ms'
,'sec'
).None
means time is already in simulation time steps.
- Returns
The number of simulation time steps.
- Return type
- Raises
ValueError – If given time cannot be represented by simulator precision.
-
cocotb.utils.
pack
(ctypes_obj)[source]¶ Convert a
ctypes
structure into a Python string.- Parameters
ctypes_obj (ctypes.Structure) – The
ctypes
structure to convert to a string.- Returns
New Python string containing the bytes from memory holding ctypes_obj.
-
cocotb.utils.
unpack
(ctypes_obj, string, bytes=None)[source]¶ Unpack a Python string into a
ctypes
structure.If the length of string is not the correct size for the memory footprint of the
ctypes
structure then the bytes keyword argument must be used.- Parameters
ctypes_obj (ctypes.Structure) – The
ctypes
structure to pack into.string (str) – String to copy over the ctypes_obj memory space.
bytes (int, optional) – Number of bytes to copy. Defaults to
None
, meaning the length of string is used.
- Raises
ValueError – If length of string and size of ctypes_obj are not equal.
MemoryError – If bytes is longer than size of ctypes_obj.
-
cocotb.utils.
hexdump
(x: bytes) → str[source]¶ Hexdump a buffer.
- Parameters
x – Object that supports conversion to
bytes
.- Returns
A string containing the hexdump.
Deprecated since version 1.4: Passing a
str
to this function is deprecated, as it is not an appropriate type for binary data. Doing so anyway will encode the string to latin1.Example
>>> print(hexdump(b'this somewhat long string')) 0000 74 68 69 73 20 73 6F 6D 65 77 68 61 74 20 6C 6F this somewhat lo 0010 6E 67 20 73 74 72 69 6E 67 ng string
-
cocotb.utils.
hexdiffs
(x: bytes, y: bytes) → str[source]¶ Return a diff string showing differences between two binary strings.
- Parameters
Deprecated since version 1.4: Passing
str
s to this function is deprecated, as it is not an appropriate type for binary data. Doing so anyway will encode the string to latin1.Example
>>> print(hexdiffs(b'a', b'b')) 0000 61 a 0000 62 b >>> print(hexdiffs(b'this short thing', b'this also short')) 0000 746869732073686F 7274207468696E67 this short thing 0000 7468697320616C73 6F 2073686F7274 this also short
-
class
cocotb.utils.
ParametrizedSingleton
(*args, **kwargs)[source]¶ A metaclass that allows class construction to reuse an existing instance.
We use this so that
RisingEdge(sig)
andJoin(coroutine)
always return the same instance, rather than creating new copies.
-
cocotb.utils.
reject_remaining_kwargs
(name, kwargs)[source]¶ Helper function to emulate Python 3 keyword-only arguments.
Use as:
def func(x1, **kwargs): a = kwargs.pop('a', 1) b = kwargs.pop('b', 2) reject_remaining_kwargs('func', kwargs) ...
To emulate the Python 3 syntax:
def func(x1, *, a=1, b=2): ...
Deprecated since version 1.4: Since the minimum supported Python version is now 3.5, this function is not needed.
-
class
cocotb.utils.
lazy_property
(fget)[source]¶ A property that is executed the first time, then cached forever.
It does this by replacing itself on the instance, which works because unlike @property it does not define __set__.
This should be used for expensive members of objects that are not always used.
-
cocotb.utils.
want_color_output
()[source]¶ Return
True
if colored output is possible/requested and not running in GUI.Colored output can be explicitly requested by setting
COCOTB_ANSI_OUTPUT
to1
.
-
cocotb.utils.
remove_traceback_frames
(tb_or_exc, frame_names)[source]¶ Strip leading frames from a traceback
- Parameters
tb_or_exc (Union[traceback, BaseException, exc_info]) – Object to strip frames from. If an exception is passed, creates a copy of the exception with a new shorter traceback. If a tuple from sys.exc_info is passed, returns the same tuple with the traceback shortened
frame_names (List[str]) – Names of the frames to strip, which must be present.
Logging¶
-
cocotb.log.
default_config
()[source]¶ Apply the default cocotb log formatting to the root logger.
This hooks up the logger to write to stdout, using either
SimColourLogFormatter
orSimLogFormatter
depending on whether colored output is requested. It also adds aSimTimeContextFilter
filter so thatcreated_sim_time
is available to the formatter.The logging level for cocotb logs is set based on the
COCOTB_LOG_LEVEL
environment variable, which defaults toINFO
.If desired, this logging configuration can be overwritten by calling
logging.basicConfig(..., force=True)
(in Python 3.8 onwards), or by manually resetting the root logger instance. An example of this can be found in the section on Rotating Log Files.New in version 1.4.
-
class
cocotb.log.
SimLogFormatter
[source]¶ Bases:
logging.Formatter
Log formatter to provide consistent log message handling.
This will only add simulator timestamps if the handler object this formatter is attached to has a
SimTimeContextFilter
filter attached, which cocotb ensures by default.Takes no arguments.
-
class
cocotb.log.
SimColourLogFormatter
[source]¶ Bases:
cocotb.log.SimLogFormatter
Log formatter to provide consistent log message handling.
Takes no arguments.
-
class
cocotb.log.
SimTimeContextFilter
[source]¶ Bases:
logging.Filter
A filter to inject simulator times into the log records.
This uses the approach described in the Python logging cookbook.
This adds the
created_sim_time
attribute.New in version 1.4.
-
logging.LogRecord.
created_sim_time
¶ The result of
get_sim_time()
at the point the log was created (in simulator units). The formatter is responsible for converting this to something like nanoseconds viaget_time_from_sim_steps()
.This is added by
cocotb.log.SimTimeContextFilter
.
Simulation Object Handles¶
-
class
cocotb.handle.
SimHandleBase
(handle, path)[source]¶ Bases:
object
Base class for all simulation objects.
We maintain a handle which we can use for GPI calls.
-
class
cocotb.handle.
RegionObject
(handle, path)[source]¶ Bases:
cocotb.handle.SimHandleBase
A region object, such as a scope or namespace.
Region objects don’t have values, they are effectively scopes or namespaces.
-
class
cocotb.handle.
HierarchyObject
(handle, path)[source]¶ Bases:
cocotb.handle.RegionObject
Hierarchy objects are namespace/scope objects.
- Parameters
-
class
cocotb.handle.
HierarchyArrayObject
(handle, path)[source]¶ Bases:
cocotb.handle.RegionObject
Hierarchy Arrays are containers of Hierarchy Objects.
-
class
cocotb.handle.
NonHierarchyObject
(handle, path)[source]¶ Bases:
cocotb.handle.SimHandleBase
Common base class for all non-hierarchy objects.
- Parameters
-
property
value
¶ The value of this simulation object.
Note
When setting this property, the value is stored by the
Scheduler
and all stored values are written at the same time at the end of the current simulator time step.Use
setimmediatevalue()
to set the value immediately.
-
class
cocotb.handle.
ConstantObject
(handle, path, handle_type)[source]¶ Bases:
cocotb.handle.NonHierarchyObject
An object which has a value that can be read, but not set.
The value is cached in the class since it is fixed at elaboration time and won’t change within a simulation.
- Parameters
-
property
value
¶ The value of this simulation object.
-
class
cocotb.handle.
NonHierarchyIndexableObject
(handle, path)[source]¶ Bases:
cocotb.handle.NonHierarchyObject
A non-hierarchy indexable object.
Getting and setting the current value of an array is done by iterating through sub-handles in left-to-right order.
Given an HDL array
arr
:Verilog
VHDL
arr.value
is equivalent toarr[4:7]
arr(4 to 7)
[arr[4].value, arr[5].value, arr[6].value, arr[7].value]
arr[7:4]
arr(7 downto 4)
[arr[7].value, arr[6].value, arr[5].value, arr[4].value]
When setting the signal as in
arr.value = ...
, the same index equivalence as noted in the table holds.Warning
Assigning a value to a sub-handle:
Wrong:
dut.some_array.value[0] = 1
(gets value as a list then updates index 0)Correct:
dut.some_array[0].value = 1
- Parameters
-
class
cocotb.handle.
NonConstantObject
(handle, path)[source]¶ Bases:
cocotb.handle.NonHierarchyIndexableObject
A non-constant object
- Parameters
-
class
cocotb.handle.
ModifiableObject
(handle, path)[source]¶ Bases:
cocotb.handle.NonConstantObject
Base class for simulator objects whose values can be modified.
- Parameters
-
class
cocotb.handle.
RealObject
(handle, path)[source]¶ Bases:
cocotb.handle.ModifiableObject
Specific object handle for Real signals and variables.
- Parameters
-
class
cocotb.handle.
EnumObject
(handle, path)[source]¶ Bases:
cocotb.handle.ModifiableObject
Specific object handle for enumeration signals and variables.
- Parameters
-
class
cocotb.handle.
IntegerObject
(handle, path)[source]¶ Bases:
cocotb.handle.ModifiableObject
Specific object handle for Integer and Enum signals and variables.
- Parameters
-
class
cocotb.handle.
StringObject
(handle, path)[source]¶ Bases:
cocotb.handle.ModifiableObject
Specific object handle for String variables.
- Parameters
Implemented Testbench Structures¶
Drivers¶
AMBA¶
Advanced Microcontroller Bus Architecture.
-
class
cocotb.drivers.amba.
AXI4LiteMaster
(entity, name, clock, **kwargs)[source]¶ AXI4-Lite Master.
TODO: Kill all pending transactions if reset is asserted.
Constructor for a driver instance.
-
write
(address: int, value: int, byte_enable: int = 15, address_latency: int = 0, data_latency: int = 0, sync: bool = True) → cocotb.binary.BinaryValue[source]¶ Write a value to an address.
- Parameters
address – The address to write to.
value – The data value to write.
byte_enable – Which bytes in value to actually write. Default is to write all bytes.
address_latency – Delay before setting the address (in clock cycles). Default is no delay.
data_latency – Delay before setting the data value (in clock cycles). Default is no delay.
sync – Wait for rising edge on clock initially. Defaults to True.
- Returns
The write response value.
- Raises
AXIProtocolError – If write response from AXI is not
OKAY
.
-
read
(address: int, sync: bool = True) → cocotb.binary.BinaryValue[source]¶ Read from an address.
- Parameters
address – The address to read from.
sync – Wait for rising edge on clock initially. Defaults to True.
- Returns
The read data value.
- Raises
AXIProtocolError – If read response from AXI is not
OKAY
.
-
Avalon¶
-
class
cocotb.drivers.avalon.
AvalonMM
(entity, name, clock, **kwargs)[source]¶ Bases:
cocotb.drivers.BusDriver
Avalon Memory Mapped Interface (Avalon-MM) Driver.
Currently we only support the mode required to communicate with SF
avalon_mapper
which is a limited subset of all the signals.Blocking operation is all that is supported at the moment, and for the near future as well. Posted responses from a slave are not supported.
Constructor for a driver instance.
-
class
cocotb.drivers.avalon.
AvalonMaster
(entity, name, clock, **kwargs)[source]¶ Bases:
cocotb.drivers.avalon.AvalonMM
Avalon Memory Mapped Interface (Avalon-MM) Master.
Constructor for a driver instance.
-
read
(address: int, sync: bool = True) → cocotb.binary.BinaryValue[source]¶ Issue a request to the bus and block until this comes back.
Simulation time still progresses but syntactically it blocks.
- Parameters
address – The address to read from.
sync – Wait for rising edge on clock initially. Defaults to True.
- Returns
The read data value.
- Raises
TestError – If master is write-only.
-
-
class
cocotb.drivers.avalon.
AvalonMemory
(entity, name, clock, readlatency_min=1, readlatency_max=1, memory=None, avl_properties={}, **kwargs)[source]¶ Bases:
cocotb.drivers.BusDriver
Emulate a memory, with back-door access.
Constructor for a driver instance.
-
class
cocotb.drivers.avalon.
AvalonST
(entity, name, clock, *, config={}, **kwargs)[source]¶ Bases:
cocotb.drivers.ValidatedBusDriver
Avalon Streaming Interface (Avalon-ST) Driver
Constructor for a driver instance.
-
class
cocotb.drivers.avalon.
AvalonSTPkts
(entity, name, clock, *, config={}, **kwargs)[source]¶ Bases:
cocotb.drivers.ValidatedBusDriver
Avalon Streaming Interface (Avalon-ST) Driver, packetized.
Constructor for a driver instance.
OPB¶
-
class
cocotb.drivers.opb.
OPBMaster
(entity, name, clock, **kwargs)[source]¶ Bases:
cocotb.drivers.BusDriver
On-chip peripheral bus master.
Constructor for a driver instance.
-
read
(address: int, sync: bool = True) → cocotb.binary.BinaryValue[source]¶ Issue a request to the bus and block until this comes back.
Simulation time still progresses but syntactically it blocks.
- Parameters
address – The address to read from.
sync – Wait for rising edge on clock initially. Defaults to True.
- Returns
The read data value.
- Raises
OPBException – If read took longer than 16 cycles.
-
write
(address: int, value: int, sync: bool = True) → None[source]¶ Issue a write to the given address with the specified value.
- Parameters
address – The address to read from.
value – The data value to write.
sync – Wait for rising edge on clock initially. Defaults to True.
- Raises
OPBException – If write took longer than 16 cycles.
-
XGMII¶
-
class
cocotb.drivers.xgmii.
XGMII
(signal: cocotb.handle.SimHandleBase, clock: cocotb.handle.SimHandleBase, interleaved: bool = True)[source]¶ Bases:
cocotb.drivers.Driver
XGMII (10 Gigabit Media Independent Interface) driver.
- Parameters
signal – The XGMII data bus.
clock – The associated clock (assumed to be driven by another coroutine).
interleaved – Whether control bits are interleaved with the data bytes or not.
- If interleaved the bus is
byte0, byte0_control, byte1, byte1_control, …
- Otherwise expect
byte0, byte1, …, byte0_control, byte1_control, …
Monitors¶
Avalon¶
-
class
cocotb.monitors.avalon.
AvalonST
(entity, name, clock, *, config={}, **kwargs)[source]¶ Bases:
cocotb.monitors.BusMonitor
Avalon-ST bus.
Non-packetized so each valid word is a separate transaction.
-
class
cocotb.monitors.avalon.
AvalonSTPkts
(entity, name, clock, *, config={}, report_channel=False, **kwargs)[source]¶ Bases:
cocotb.monitors.BusMonitor
Packetized Avalon-ST bus.
XGMII¶
-
class
cocotb.monitors.xgmii.
XGMII
(signal, clock, interleaved=True, callback=None, event=None)[source]¶ Bases:
cocotb.monitors.Monitor
XGMII (10 Gigabit Media Independent Interface) Monitor.
Assumes a single vector, either 4 or 8 bytes plus control bit for each byte.
If interleaved is
True
then the control bits are adjacent to the bytes.Changed in version 1.4.0: This now emits packets of type
bytes
rather thanstr
, which matches the behavior ofcocotb.drivers.xgmii.XGMII
.- Parameters
signal (SimHandle) – The XGMII data bus.
clock (SimHandle) – The associated clock (assumed to be driven by another coroutine).
interleaved (bool, optional) – Whether control bits are interleaved with the data bytes or not.
- If interleaved the bus is
byte0, byte0_control, byte1, byte1_control, …
- Otherwise expect
byte0, byte1, …, byte0_control, byte1_control, …
Miscellaneous¶
Other Runtime Information¶
-
cocotb.
SIM_NAME
: str = None¶ The running simulator product information.
None
ifcocotb
was not loaded from a simulator
-
cocotb.
SIM_VERSION
: str = None¶ The version of the running simulator.
None
ifcocotb
was not loaded from a simulator
-
cocotb.
RANDOM_SEED
: int = None¶ The value passed to the Python default random number generator. See
RANDOM_SEED
for details on how the value is computed.
-
cocotb.
plusargs
: Dict[str, Union[bool, str]] = None¶ A dictionary of “plusargs” handed to the simulation. See
PLUSARGS
for details.
-
cocotb.
LANGUAGE
: str = None¶ The value of
TOPLEVEL_LANG
Signal Tracer for WaveDrom¶
-
class
cocotb.wavedrom.
trace
(*args, clk=None)[source]¶ Context manager to enable tracing of signals.
Arguments are an arbitrary number of signals or buses to trace. We also require a clock to sample on, passed in as a keyword argument.
Usage:
with trace(sig1, sig2, a_bus, clk=clk) as waves: # Stuff happens, we trace it # Dump to JSON format compatible with WaveDrom j = waves.dumpj()
Implementation Details¶
Note
In general, nothing in this section should be interacted with directly - these components work mostly behind the scenes.
The Scheduler¶
-
cocotb.
scheduler
: cocotb.scheduler.Scheduler = None¶ The global scheduler instance.
-
class
cocotb.scheduler.
Scheduler
[source]¶ The main scheduler.
Here we accept callbacks from the simulator and schedule the appropriate coroutines.
A callback fires, causing the
react
method to be called, with the trigger that caused the callback as the first argument.We look up a list of coroutines to schedule (indexed by the trigger) and schedule them in turn.
Attention
Implementors should not depend on the scheduling order!
Some additional management is required since coroutines can return a list of triggers, to be scheduled when any one of the triggers fires. To ensure we don’t receive spurious callbacks, we have to un-prime all the other triggers when any one fires.
Due to the simulator nuances and fun with delta delays we have the following modes:
- Normal mode
Callbacks cause coroutines to be scheduled
Any pending writes are cached and do not happen immediately
- ReadOnly mode
Corresponds to
cbReadOnlySynch
(VPI) orvhpiCbLastKnownDeltaCycle
(VHPI). In this state we are not allowed to perform writes.
- Write mode
Corresponds to
cbReadWriteSynch
(VPI) orvhpiCbEndOfProcesses
(VHPI) In this mode we play back all the cached write updates.
We can legally transition from Normal to Write by registering a
ReadWrite
callback, however usually once a simulator has entered the ReadOnly phase of a given timestep then we must move to a new timestep before performing any writes. The mechanism for moving to a new timestep may not be consistent across simulators and therefore we provide an abstraction to assist with compatibility.Unless a coroutine has explicitly requested to be scheduled in ReadOnly mode (for example wanting to sample the finally settled value after all delta delays) then it can reasonably be expected to be scheduled during “normal mode” i.e. where writes are permitted.
-
react
(trigger)[source]¶ Called when a trigger fires.
We ensure that we only start the event loop once, rather than letting it recurse.
-
queue_function
(coro)[source]¶ Queue a coroutine for execution and move the containing thread so that it does not block execution of the main thread any longer.
-
run_in_executor
(func, *args, **kwargs)[source]¶ Run the coroutine in a separate execution thread and return an awaitable object for the caller.
-
add
(coroutine)[source]¶ Add a new coroutine.
Just a wrapper around self.schedule which provides some debug and useful error messages in the event of common gotchas.
-
schedule
(coroutine, trigger=None)[source]¶ Schedule a coroutine by calling the send method.
- Parameters
coroutine (cocotb.decorators.coroutine) – The coroutine to schedule.
trigger (cocotb.triggers.Trigger) – The trigger that caused this coroutine to be scheduled.
The Regression Manager¶
-
cocotb.
regression_manager
: cocotb.regression.RegressionManager = None¶ The global regression manager instance.
-
class
cocotb.regression.
RegressionManager
(dut: cocotb.handle.SimHandle, tests: Iterable[cocotb.decorators.test], hooks: Iterable[cocotb.decorators.hook])[source]¶ Encapsulates all regression capability into a single place
- Parameters
dut (SimHandle) – The root handle to pass into test functions.
tests (Iterable[Test]) – tests to run
hooks (Iterable[Hook]) – hooks to tun
-
classmethod
from_discovery
(dut: cocotb.handle.SimHandle)[source]¶ Obtains the test and hook lists by discovery.
See
MODULE
andTESTCASE
for details on how tests are discovered.- Parameters
dut (SimHandle) – The root handle to pass into test functions.
The cocotb.simulator
module¶
This module is a Python wrapper to libgpi. It should not be considered public API, but is documented here for developers of cocotb.
-
cocotb.simulator.
get_precision
() → int¶ Get the precision of the simulator in powers of 10.
For example, if
-12
is returned, the simulator’s time precision is 10**-12 or 1 ps.
-
cocotb.simulator.
get_root_handle
(name: str) → cocotb.simulator.gpi_sim_hdl¶ Get the root handle.
-
cocotb.simulator.
get_sim_time
() → Tuple[int, int]¶ Get the current simulation time.
Time is represented as a tuple of 32 bit integers ([low32, high32]) comprising a single 64 bit integer.
-
class
cocotb.simulator.
gpi_cb_hdl
¶ GPI callback handle
-
class
cocotb.simulator.
gpi_iterator_hdl
¶ GPI iterator handle.
-
class
cocotb.simulator.
gpi_sim_hdl
¶ GPI object handle
Contains methods for getting and setting the value of a GPI object, and introspection.
-
get_handle_by_index
(index: int) → cocotb.simulator.gpi_sim_hdl¶ Get a handle to a child object by index.
-
get_handle_by_name
(name: str) → cocotb.simulator.gpi_sim_hdl¶ Get a handle to a child object by name.
-
get_range
() → Tuple[int, int]¶ Get the range of elements (tuple) contained in the handle, return
None
if not indexable.
-
get_signal_val_binstr
() → str¶ Get the value of a logic vector signal as a string of (
0
,1
,X
, etc.), one element per character.
-
iterate
(mode: int) → cocotb.simulator.gpi_iterator_hdl¶ Get an iterator handle to loop over all members in an object.
-
-
cocotb.simulator.
is_running
() → bool¶ Returns
True
if the caller is running within a simulator.New in version 1.4.
-
cocotb.simulator.
log_msg
(name: str, path: str, funcname: str, lineno: int, msg: str) → None¶ Log a message.
-
cocotb.simulator.
register_nextstep_callback
(func: Callable[…, None], *args: Any) → cocotb.simulator.gpi_cb_hdl¶ Register a callback for the NextSimTime callback.
-
cocotb.simulator.
register_readonly_callback
(func: Callable[…, None], *args: Any) → cocotb.simulator.gpi_cb_hdl¶ Register a callback for the read-only section.
-
cocotb.simulator.
register_rwsynch_callback
(func: Callable[…, None], *args: Any) → cocotb.simulator.gpi_cb_hdl¶ Register a callback for the read-write section.
-
cocotb.simulator.
register_timed_callback
(time: int, func: Callable[…, None], *args: Any) → cocotb.simulator.gpi_cb_hdl¶ Register a timed callback.
-
cocotb.simulator.
register_value_change_callback
(signal: cocotb.simulator.gpi_sim_hdl, func: Callable[…, None], edge: int, *args: Any) → cocotb.simulator.gpi_cb_hdl¶ Register a signal change callback.
The cocotb-config
script¶
usage: cocotb-config [-h] [--prefix] [--share] [--makefiles] [--python-bin]
[--help-vars] [-v]
Named Arguments¶
- --prefix
echo the package-prefix of cocotb
- --share
echo the package-share of cocotb
- --makefiles
echo the package-makefiles of cocotb
- --python-bin
echo the path to the Python binary cocotb is installed for
- --help-vars
show help about supported variables
- -v, --version
echo the version of cocotb