class Feed(object):
def __init__(self, name, filepath=None):
self.name = name
self._packets = {}
self._filepath = filepath
self.fullname = '\'' + self.name + '\''
self.log = SimLog('cocotb.' + self.name)
if self._filepath:
self._source = open(self._filepath)
self.log.debug("loaded file %s" % self._filepath)
self.log.debug("Created feed!")
def addmsg(self, tag, data):
""" Add a defined message to the internal feed store """
self._packets[tag] = data
def getmsg(self):
""" Get a string representation of the current list head
This packet will be ready to send
"""
if self._packets:
tag, packet = self._packets.popitem()
return str(packet)
else:
self.log.warn("No packets in feed %s" % self.fullname)
return None
class Feed(object):
def __init__(self, name, filepath=None):
self.name = name
self._packets = {}
self._filepath = filepath
self.fullname = '\'' + self.name + '\''
self.log = SimLog('cocotb.' + self.name)
if self._filepath:
self._source = open(self._filepath)
self.log.debug("loaded file %s" % self._filepath)
self.log.debug("Created feed!")
def addmsg(self, tag, data):
""" Add a defined message to the internal feed store """
self._packets[tag] = data
def getmsg(self):
""" Get a string representation of the current list head
This packet will be ready to send
"""
if self._packets:
tag, packet = self._packets.popitem()
return str(packet)
else:
self.log.warn("No packets in feed %s" % self.fullname)
return None
class Scheduler(object):
"""The main scheduler.
Here we accept callbacks from the simulator and schedule the appropriate
coroutines.
A callback fires, causing the :any:`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. NB 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) or vhpiCbLastKnownDeltaCycle
(VHPI). In this state we are not allowed to perform writes.
Write mode
- Corresponds to cbReadWriteSynch (VPI) or vhpiCbEndOfProcesses (VHPI)
In this mode we play back all the cached write updates.
We can legally transition from normal->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.
"""
_MODE_NORMAL = 1 # noqa
_MODE_READONLY = 2 # noqa
_MODE_WRITE = 3 # noqa
_MODE_TERM = 4 # noqa
# Singleton events, recycled to avoid spurious object creation
_readonly = ReadOnly()
# TODO[gh-759]: For some reason, the scheduler requires that these triggers
# are _not_ the same instances used by the tests themselves. This is risky,
# because it can lead to them overwriting each other's callbacks. We should
# try to remove this `copy.copy` in future.
_next_timestep = copy.copy(NextTimeStep())
_readwrite = copy.copy(ReadWrite())
_timer1 = Timer(1)
_timer0 = Timer(0)
def __init__(self):
self.log = SimLog("cocotb.scheduler")
if _debug:
self.log.setLevel(logging.DEBUG)
# A dictionary of pending coroutines for each trigger,
# indexed by trigger
self._trigger2coros = collections.defaultdict(list)
# A dictionary of pending triggers for each coroutine, indexed by coro
self._coro2triggers = collections.defaultdict(list)
# Our main state
self._mode = Scheduler._MODE_NORMAL
# A dictionary of pending writes
self._writes = {}
self._pending_coros = []
self._pending_callbacks = []
self._pending_triggers = []
self._pending_threads = []
self._pending_events = [] # Events we need to call set on once we've unwound
self._terminate = False
self._test_result = None
self._entrypoint = None
self._main_thread = threading.current_thread()
# Select the appropriate scheduling algorithm for this simulator
self.advance = self.default_scheduling_algorithm
self._is_reacting = False
def default_scheduling_algorithm(self):
"""
Decide whether we need to schedule our own triggers (if at all) in
order to progress to the next mode.
This algorithm has been tested against the following simulators:
Icarus Verilog
"""
if not self._terminate and self._writes:
if self._mode == Scheduler._MODE_NORMAL:
if not self._readwrite.primed:
self._readwrite.prime(self.react)
elif not self._next_timestep.primed:
self._next_timestep.prime(self.react)
elif self._terminate:
if _debug:
self.log.debug("Test terminating, scheduling Timer")
for t in self._trigger2coros:
t.unprime()
for t in [self._readwrite, self._readonly, self._next_timestep,
self._timer1, self._timer0]:
if t.primed:
t.unprime()
self._timer1.prime(self.begin_test)
self._trigger2coros = collections.defaultdict(list)
self._coro2triggers = collections.defaultdict(list)
self._terminate = False
self._mode = Scheduler._MODE_TERM
def begin_test(self, trigger=None):
"""Called to initiate a test.
Could be called on start-up or from a callback.
"""
if _debug:
self.log.debug("begin_test called with trigger: %s" %
(str(trigger)))
if _profiling:
ps = pstats.Stats(_profile).sort_stats('cumulative')
ps.dump_stats("test_profile.pstat")
ctx = profiling_context()
else:
ctx = nullcontext()
with ctx:
self._mode = Scheduler._MODE_NORMAL
if trigger is not None:
trigger.unprime()
# Issue previous test result, if there is one
if self._test_result is not None:
if _debug:
self.log.debug("Issue test result to regression object")
cocotb.regression_manager.handle_result(self._test_result)
self._test_result = None
if self._entrypoint is not None:
test = self._entrypoint
self._entrypoint = None
self.schedule(test)
self.advance()
def react(self, trigger):
"""
Called when a trigger fires.
We ensure that we only start the event loop once, rather than
letting it recurse.
"""
if self._is_reacting:
# queue up the trigger, the event loop will get to it
self._pending_triggers.append(trigger)
return
# start the event loop
self._is_reacting = True
try:
self._event_loop(trigger)
finally:
self._is_reacting = False
def _event_loop(self, trigger):
"""
Run an event loop triggered by the given trigger.
The loop will keep running until no further triggers fire.
This should be triggered by only:
* The beginning of a test, when there is no trigger to react to
* A GPI trigger
"""
if _profiling:
ctx = profiling_context()
else:
ctx = nullcontext()
with ctx:
# When a trigger fires it is unprimed internally
if _debug:
self.log.debug("Trigger fired: %s" % str(trigger))
# trigger.unprime()
if self._mode == Scheduler._MODE_TERM:
if _debug:
self.log.debug("Ignoring trigger %s since we're terminating" %
str(trigger))
return
if trigger is self._readonly:
self._mode = Scheduler._MODE_READONLY
# Only GPI triggers affect the simulator scheduling mode
elif isinstance(trigger, GPITrigger):
self._mode = Scheduler._MODE_NORMAL
# We're the only source of ReadWrite triggers which are only used for
# playing back any cached signal updates
if trigger is self._readwrite:
if _debug:
self.log.debug("Writing cached signal updates")
while self._writes:
handle, value = self._writes.popitem()
handle.setimmediatevalue(value)
self._readwrite.unprime()
return
# Similarly if we've scheduled our next_timestep on way to readwrite
if trigger is self._next_timestep:
if not self._writes:
self.log.error(
"Moved to next timestep without any pending writes!")
else:
self.log.debug(
"Priming ReadWrite trigger so we can playback writes")
self._readwrite.prime(self.react)
return
# work through triggers one by one
is_first = True
self._pending_triggers.append(trigger)
while self._pending_triggers:
trigger = self._pending_triggers.pop(0)
if not is_first and isinstance(trigger, GPITrigger):
self.log.warning(
"A GPI trigger occurred after entering react - this "
"should not happen."
)
assert False
# this only exists to enable the warning above
is_first = False
if trigger not in self._trigger2coros:
# GPI triggers should only be ever pending if there is an
# associated coroutine waiting on that trigger, otherwise it would
# have been unprimed already
if isinstance(trigger, GPITrigger):
self.log.critical(
"No coroutines waiting on trigger that fired: %s" %
str(trigger))
trigger.log.info("I'm the culprit")
# For Python triggers this isn't actually an error - we might do
# event.set() without knowing whether any coroutines are actually
# waiting on this event, for example
elif _debug:
self.log.debug(
"No coroutines waiting on trigger that fired: %s" %
str(trigger))
continue
# Scheduled coroutines may append to our waiting list so the first
# thing to do is pop all entries waiting on this trigger.
scheduling = self._trigger2coros.pop(trigger)
if _debug:
debugstr = "\n\t".join([coro.__name__ for coro in scheduling])
if len(scheduling):
debugstr = "\n\t" + debugstr
self.log.debug("%d pending coroutines for event %s%s" %
(len(scheduling), str(trigger), debugstr))
# This trigger isn't needed any more
trigger.unprime()
# If the coroutine was waiting on multiple triggers we may be able
# to unprime the other triggers that didn't fire
scheduling_set = set(scheduling)
other_triggers = {
t
for coro in scheduling
for t in self._coro2triggers[coro]
} - {trigger}
for pending in other_triggers:
# every coroutine waiting on this trigger is already being woken
if scheduling_set.issuperset(self._trigger2coros[pending]):
if pending.primed:
pending.unprime()
del self._trigger2coros[pending]
for coro in scheduling:
if _debug:
self.log.debug("Scheduling coroutine %s" % (coro.__name__))
self.schedule(coro, trigger=trigger)
if _debug:
self.log.debug("Scheduled coroutine %s" % (coro.__name__))
# Schedule may have queued up some events so we'll burn through those
while self._pending_events:
if _debug:
self.log.debug("Scheduling pending event %s" %
(str(self._pending_events[0])))
self._pending_events.pop(0).set()
# no more pending triggers
self.advance()
if _debug:
self.log.debug("All coroutines scheduled, handing control back"
" to simulator")
def unschedule(self, coro):
"""Unschedule a coroutine. Unprime any pending triggers"""
for trigger in self._coro2triggers[coro]:
if coro in self._trigger2coros[trigger]:
self._trigger2coros[trigger].remove(coro)
if not self._trigger2coros[trigger]:
trigger.unprime()
del self._trigger2coros[trigger]
del self._coro2triggers[coro]
if Join(coro) in self._trigger2coros:
self._pending_triggers.append(Join(coro))
else:
try:
# throws an error if the background coroutine errored
# and no one was monitoring it
coro.retval
except Exception as e:
self._test_result = TestError(
"Forked coroutine {} raised exception {}"
.format(coro, e)
)
self._terminate = True
def save_write(self, handle, value):
if self._mode == Scheduler._MODE_READONLY:
raise Exception("Write to object {0} was scheduled during a read-only sync phase.".format(handle._name))
self._writes[handle] = value
def _coroutine_yielded(self, coro, triggers):
"""Prime the triggers and update our internal mappings."""
self._coro2triggers[coro] = triggers
for trigger in triggers:
self._trigger2coros[trigger].append(coro)
if not trigger.primed:
try:
trigger.prime(self.react)
except Exception as e:
# Convert any exceptions into a test result
self.finish_test(
create_error(self, "Unable to prime trigger %s: %s" %
(str(trigger), str(e))))
def queue(self, coroutine):
"""Queue a coroutine for execution"""
self._pending_coros.append(coroutine)
def queue_function(self, coroutine):
"""Queue a coroutine for execution and move the containing thread
so that it does not block execution of the main thread any longer.
"""
# We should be able to find ourselves inside the _pending_threads list
for t in self._pending_threads:
if t.thread == threading.current_thread():
t.thread_suspend()
self._pending_coros.append(coroutine)
return t
def run_in_executor(self, func, *args, **kwargs):
"""Run the coroutine in a separate execution thread
and return a yieldable object for the caller.
"""
# Create a thread
# Create a trigger that is called as a result of the thread finishing
# Create an Event object that the caller can yield on
# Event object set when the thread finishes execution, this blocks the
# calling coroutine (but not the thread) until the external completes
def execute_external(func, _waiter):
_waiter._outcome = outcomes.capture(func, *args, **kwargs)
if _debug:
self.log.debug("Execution of external routine done %s" % threading.current_thread())
_waiter.thread_done()
waiter = external_waiter()
thread = threading.Thread(group=None, target=execute_external,
name=func.__name__ + "_thread",
args=([func, waiter]), kwargs={})
waiter.thread = thread;
self._pending_threads.append(waiter)
return waiter
def add(self, coroutine):
"""Add a new coroutine.
Just a wrapper around self.schedule which provides some debug and
useful error messages in the event of common gotchas.
"""
if isinstance(coroutine, cocotb.decorators.coroutine):
self.log.critical(
"Attempt to schedule a coroutine that hasn't started")
coroutine.log.error("This is the failing coroutine")
self.log.warning(
"Did you forget to add parentheses to the @test decorator?")
self._test_result = TestError(
"Attempt to schedule a coroutine that hasn't started")
self._terminate = True
return
elif not isinstance(coroutine, cocotb.decorators.RunningCoroutine):
self.log.critical(
"Attempt to add something to the scheduler which isn't a "
"coroutine")
self.log.warning(
"Got: %s (%s)" % (str(type(coroutine)), repr(coroutine)))
self.log.warning("Did you use the @coroutine decorator?")
self._test_result = TestError(
"Attempt to schedule a coroutine that hasn't started")
self._terminate = True
return
if _debug:
self.log.debug("Adding new coroutine %s" % coroutine.__name__)
self.schedule(coroutine)
self.advance()
return coroutine
def new_test(self, coroutine):
self._entrypoint = coroutine
def schedule(self, coroutine, trigger=None):
"""Schedule a coroutine by calling the send method.
Args:
coroutine (cocotb.decorators.coroutine): The coroutine to schedule.
trigger (cocotb.triggers.Trigger): The trigger that caused this
coroutine to be scheduled.
"""
if trigger is None:
send_outcome = outcomes.Value(None)
else:
send_outcome = trigger._outcome
if _debug:
self.log.debug("Scheduling with {}".format(send_outcome))
try:
result = coroutine._advance(send_outcome)
if _debug:
self.log.debug("Coroutine %s yielded %s (mode %d)" %
(coroutine.__name__, str(result), self._mode))
# TestComplete indication is game over, tidy up
except TestComplete as test_result:
# Tag that close down is needed, save the test_result
# for later use in cleanup handler
self.log.debug("TestComplete received: %s" % test_result.__class__.__name__)
self.finish_test(test_result)
return
# Normal coroutine completion
except cocotb.decorators.CoroutineComplete as exc:
if _debug:
self.log.debug("Coroutine completed: %s" % str(coroutine))
self.unschedule(coroutine)
return
# Don't handle the result if we're shutting down
if self._terminate:
return
# Queue current routine to schedule when the nested routine exits
yield_successful = False
if isinstance(result, cocotb.decorators.RunningCoroutine):
if not result.has_started():
self.queue(result)
if _debug:
self.log.debug("Scheduling nested coroutine: %s" %
result.__name__)
else:
if _debug:
self.log.debug("Joining to already running coroutine: %s" %
result.__name__)
new_trigger = result.join()
self._coroutine_yielded(coroutine, [new_trigger])
yield_successful = True
elif isinstance(result, Trigger):
if _debug:
self.log.debug("%s: is instance of Trigger" % result)
self._coroutine_yielded(coroutine, [result])
yield_successful = True
# If we get a list, make sure it's a list of triggers or coroutines.
# For every coroutine, replace it with coroutine.join().
# This could probably be done more elegantly via list comprehension.
elif isinstance(result, list):
new_triggers = []
for listobj in result:
if isinstance(listobj, Trigger):
new_triggers.append(listobj)
elif isinstance(listobj, cocotb.decorators.RunningCoroutine):
if _debug:
self.log.debug("Scheduling coroutine in list: %s" %
listobj.__name__)
if not listobj.has_started():
self.queue(listobj)
new_trigger = listobj.join()
new_triggers.append(new_trigger)
else:
# If we encounter something not a coroutine or trigger,
# set the success flag to False and break out of the loop.
yield_successful = False
break
# Make sure the lists are the same size. If they are not, it means
# it contained something not a trigger/coroutine, so do nothing.
if len(new_triggers) == len(result):
self._coroutine_yielded(coroutine, new_triggers)
yield_successful = True
# If we didn't successfully yield anything, thrown an error.
# Do it this way to make the logic in the list case simpler.
if not yield_successful:
msg = ("Coroutine %s yielded something the scheduler can't handle"
% str(coroutine))
msg += ("\nGot type: %s repr: %s str: %s" %
(type(result), repr(result), str(result)))
msg += "\nDid you forget to decorate with @cocotb.coroutine?"
try:
raise_error(self, msg)
except Exception as e:
self.finish_test(e)
# We do not return from here until pending threads have completed, but only
# from the main thread, this seems like it could be problematic in cases
# where a sim might change what this thread is.
def unblock_event(ext):
@cocotb.coroutine
def wrapper():
ext.event.set()
yield PythonTrigger()
if self._main_thread is threading.current_thread():
for ext in self._pending_threads:
ext.thread_start()
if _debug:
self.log.debug("Blocking from %s on %s" % (threading.current_thread(), ext.thread))
state = ext.thread_wait()
if _debug:
self.log.debug("Back from wait on self %s with newstate %d" % (threading.current_thread(), state))
if state == external_state.EXITED:
self._pending_threads.remove(ext)
self._pending_events.append(ext.event)
# Handle any newly queued coroutines that need to be scheduled
while self._pending_coros:
self.add(self._pending_coros.pop(0))
while self._pending_callbacks:
self._pending_callbacks.pop(0)()
def finish_test(self, test_result):
"""Cache the test result and set the terminate flag."""
self.log.debug("finish_test called with %s" % (repr(test_result)))
if not self._terminate:
self._terminate = True
self._test_result = test_result
self.cleanup()
def finish_scheduler(self, test_result):
"""Directly call into the regression manager and end test
once we return the sim will close us so no cleanup is needed.
"""
self.log.debug("Issue sim closedown result to regression object")
cocotb.regression_manager.handle_result(test_result)
def cleanup(self):
"""Clear up all our state.
Unprime all pending triggers and kill off any coroutines stop all externals.
"""
for trigger, waiting in dict(self._trigger2coros).items():
for coro in waiting:
if _debug:
self.log.debug("Killing %s" % str(coro))
coro.kill()
if self._main_thread is not threading.current_thread():
raise Exception("Cleanup() called outside of the main thread")
for ext in self._pending_threads:
self.log.warn("Waiting for %s to exit", ext.thread)
class Scoreboard:
"""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.
TODO:
Statistics for end-of-test summary etc.
Args:
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 :any:`TestFailure`
immediately when something is wrong instead of just
recording an error. Default is ``True``.
"""
def __init__(self,
dut,
reorder_depth=0,
fail_immediately=True): # FIXME: reorder_depth needed here?
self.dut = dut
self.log = SimLog("cocotb.scoreboard.%s" % self.dut._name)
self.errors = 0
self.expected = {}
self._imm = fail_immediately
@property
def result(self):
"""Determine the test result, do we have any pending data remaining?
Returns:
:any:`TestFailure`: If not all expected output was received or
error were recorded during the test.
"""
fail = False
for monitor, expected_output in self.expected.items():
if callable(expected_output):
self.log.debug("Can't check all data returned for %s since "
"expected output is callable function rather "
"than a list" % str(monitor))
continue
if len(expected_output):
self.log.warn("Still expecting %d transactions on %s" %
(len(expected_output), str(monitor)))
for index, transaction in enumerate(expected_output):
self.log.info("Expecting %d:\n%s" %
(index, hexdump(str(transaction))))
if index > 5:
self.log.info("... and %d more to come" %
(len(expected_output) - index - 1))
break
fail = True
if fail:
return TestFailure("Not all expected output was received")
if self.errors:
return TestFailure("Errors were recorded during the test")
return TestSuccess()
def compare(self, got, exp, log, strict_type=True):
"""Common function for comparing two transactions.
Can be re-implemented by a sub-class.
Args:
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:
:any:`TestFailure`: If received transaction differed from
expected transaction when :attr:`fail_immediately` is ``True``.
If *strict_type* is ``True``,
also the transaction type must match.
"""
# Compare the types
if strict_type and type(got) != type(exp):
self.errors += 1
log.error("Received transaction type is different than expected")
log.info("Received: %s but expected %s" %
(str(type(got)), str(type(exp))))
if self._imm:
raise TestFailure("Received transaction of wrong type. "
"Set strict_type=False to avoid this.")
return
# Or convert to a string before comparison
elif not strict_type:
got, exp = str(got), str(exp)
# Compare directly
if got != exp:
self.errors += 1
# Try our best to print out something useful
strgot, strexp = str(got), str(exp)
log.error("Received transaction differed from expected output")
if not strict_type:
log.info("Expected:\n" + hexdump(strexp))
else:
log.info("Expected:\n" + repr(exp))
if not isinstance(exp, str):
try:
for word in exp:
log.info(str(word))
except Exception:
pass
if not strict_type:
log.info("Received:\n" + hexdump(strgot))
else:
log.info("Received:\n" + repr(got))
if not isinstance(got, str):
try:
for word in got:
log.info(str(word))
except Exception:
pass
log.warning("Difference:\n%s" % hexdiffs(strexp, strgot))
if self._imm:
raise TestFailure(
"Received transaction differed from expected "
"transaction")
else:
# Don't want to fail the test
# if we're passed something without __len__
try:
log.debug("Received expected transaction %d bytes" %
(len(got)))
log.debug(repr(got))
except Exception:
pass
def add_interface(self,
monitor,
expected_output,
compare_fn=None,
reorder_depth=0,
strict_type=True):
"""Add an interface to be scoreboarded.
Provides a function which the monitor will callback with received
transactions.
Simply check against the expected output.
Args:
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:
:any:`TypeError`: If no monitor is on the interface or
*compare_fn* is not a callable function.
"""
# save a handle to the expected output so we can check if all expected
# data has been received at the end of a test.
self.expected[monitor] = expected_output
# Enforce some type checking as we only work with a real monitor
if not isinstance(monitor, Monitor):
raise TypeError("Expected monitor on the interface but got %s" %
(type(monitor).__qualname__))
if compare_fn is not None:
if callable(compare_fn):
monitor.add_callback(compare_fn)
return
raise TypeError("Expected a callable compare function but got %s" %
str(type(compare_fn)))
self.log.info("Created with reorder_depth %d" % reorder_depth)
def check_received_transaction(transaction):
"""Called back by the monitor when a new transaction has been
received."""
if monitor.name:
log_name = self.log.name + '.' + monitor.name
else:
log_name = self.log.name + '.' + type(monitor).__qualname__
log = logging.getLogger(log_name)
if callable(expected_output):
exp = expected_output(transaction)
elif len(expected_output): # we expect something
for i in range(min((reorder_depth + 1), len(expected_output))):
if expected_output[i] == transaction:
break # break out of enclosing for loop
else: # run when for loop is exhausted (but no break occurs)
i = 0
exp = expected_output.pop(i)
else:
self.errors += 1
log.error("Received a transaction but wasn't expecting "
"anything")
log.info("Got: %s" % (hexdump(str(transaction))))
if self._imm:
raise TestFailure("Received a transaction but wasn't "
"expecting anything")
return
self.compare(transaction, exp, log, strict_type=strict_type)
monitor.add_callback(check_received_transaction)
class Scheduler(object):
"""The main scheduler.
Here we accept callbacks from the simulator and schedule the appropriate
coroutines.
A callback fires, causing the :any:`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. NB 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) or vhpiCbLastKnownDeltaCycle
(VHPI). In this state we are not allowed to perform writes.
Write mode
- Corresponds to cbReadWriteSynch (VPI) or vhpiCbEndOfProcesses (VHPI)
In this mode we play back all the cached write updates.
We can legally transition from normal->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.
"""
_MODE_NORMAL = 1 # noqa
_MODE_READONLY = 2 # noqa
_MODE_WRITE = 3 # noqa
_MODE_TERM = 4 # noqa
# Singleton events, recycled to avoid spurious object creation
_next_time_step = NextTimeStep()
_read_write = ReadWrite()
_read_only = ReadOnly()
_timer1 = Timer(1)
def __init__(self):
self.log = SimLog("cocotb.scheduler")
if _debug:
self.log.setLevel(logging.DEBUG)
# Use OrderedDict here for deterministic behavior (gh-934)
# A dictionary of pending coroutines for each trigger,
# indexed by trigger
self._trigger2coros = _ordered_dict()
# A dictionary mapping coroutines to the trigger they are waiting for
self._coro2trigger = _ordered_dict()
# Our main state
self._mode = Scheduler._MODE_NORMAL
# A dictionary of pending writes
self._writes = _ordered_dict()
self._pending_coros = []
self._pending_triggers = []
self._pending_threads = []
self._pending_events = [] # Events we need to call set on once we've unwound
self._terminate = False
self._test_result = None
self._entrypoint = None
self._main_thread = threading.current_thread()
self._is_reacting = False
self._write_coro_inst = None
self._writes_pending = Event()
@cocotb.decorators.coroutine
def _do_writes(self):
""" An internal coroutine that performs pending writes """
while True:
yield self._writes_pending.wait()
if self._mode != Scheduler._MODE_NORMAL:
yield self._next_time_step
yield self._read_write
while self._writes:
handle, value = self._writes.popitem()
handle.setimmediatevalue(value)
self._writes_pending.clear()
def _check_termination(self):
"""
Handle a termination that causes us to move onto the next test.
"""
if self._terminate:
if _debug:
self.log.debug("Test terminating, scheduling Timer")
if self._write_coro_inst is not None:
self._write_coro_inst.kill()
self._write_coro_inst = None
for t in self._trigger2coros:
t.unprime()
if self._timer1.primed:
self._timer1.unprime()
self._timer1.prime(self.begin_test)
self._trigger2coros = _ordered_dict()
self._coro2trigger = _ordered_dict()
self._terminate = False
self._writes = _ordered_dict()
self._writes_pending.clear()
self._mode = Scheduler._MODE_TERM
def begin_test(self, trigger=None):
"""Called to initiate a test.
Could be called on start-up or from a callback.
"""
if _debug:
self.log.debug("begin_test called with trigger: %s" %
(str(trigger)))
if _profiling:
ps = pstats.Stats(_profile).sort_stats('cumulative')
ps.dump_stats("test_profile.pstat")
ctx = profiling_context()
else:
ctx = nullcontext()
with ctx:
self._mode = Scheduler._MODE_NORMAL
if trigger is not None:
trigger.unprime()
# Issue previous test result, if there is one
if self._test_result is not None:
if _debug:
self.log.debug("Issue test result to regression object")
cocotb.regression_manager.handle_result(self._test_result)
self._test_result = None
if self._entrypoint is not None:
test = self._entrypoint
self._entrypoint = None
self.schedule(test)
self._check_termination()
def react(self, trigger):
"""
Called when a trigger fires.
We ensure that we only start the event loop once, rather than
letting it recurse.
"""
if self._is_reacting:
# queue up the trigger, the event loop will get to it
self._pending_triggers.append(trigger)
return
if self._pending_triggers:
raise InternalError(
"Expected all triggers to be handled but found {}"
.format(self._pending_triggers)
)
# start the event loop
self._is_reacting = True
try:
self._event_loop(trigger)
finally:
self._is_reacting = False
def _event_loop(self, trigger):
"""
Run an event loop triggered by the given trigger.
The loop will keep running until no further triggers fire.
This should be triggered by only:
* The beginning of a test, when there is no trigger to react to
* A GPI trigger
"""
if _profiling:
ctx = profiling_context()
else:
ctx = nullcontext()
with ctx:
# When a trigger fires it is unprimed internally
if _debug:
self.log.debug("Trigger fired: %s" % str(trigger))
# trigger.unprime()
if self._mode == Scheduler._MODE_TERM:
if _debug:
self.log.debug("Ignoring trigger %s since we're terminating" %
str(trigger))
return
if trigger is self._read_only:
self._mode = Scheduler._MODE_READONLY
# Only GPI triggers affect the simulator scheduling mode
elif isinstance(trigger, GPITrigger):
self._mode = Scheduler._MODE_NORMAL
# work through triggers one by one
is_first = True
self._pending_triggers.append(trigger)
while self._pending_triggers:
trigger = self._pending_triggers.pop(0)
if not is_first and isinstance(trigger, GPITrigger):
self.log.warning(
"A GPI trigger occurred after entering react - this "
"should not happen."
)
assert False
# this only exists to enable the warning above
is_first = False
# Scheduled coroutines may append to our waiting list so the first
# thing to do is pop all entries waiting on this trigger.
try:
scheduling = self._trigger2coros.pop(trigger)
except KeyError:
# GPI triggers should only be ever pending if there is an
# associated coroutine waiting on that trigger, otherwise it would
# have been unprimed already
if isinstance(trigger, GPITrigger):
self.log.critical(
"No coroutines waiting on trigger that fired: %s" %
str(trigger))
trigger.log.info("I'm the culprit")
# For Python triggers this isn't actually an error - we might do
# event.set() without knowing whether any coroutines are actually
# waiting on this event, for example
elif _debug:
self.log.debug(
"No coroutines waiting on trigger that fired: %s" %
str(trigger))
del trigger
continue
if _debug:
debugstr = "\n\t".join([coro.__name__ for coro in scheduling])
if len(scheduling):
debugstr = "\n\t" + debugstr
self.log.debug("%d pending coroutines for event %s%s" %
(len(scheduling), str(trigger), debugstr))
# This trigger isn't needed any more
trigger.unprime()
for coro in scheduling:
if _debug:
self.log.debug("Scheduling coroutine %s" % (coro.__name__))
self.schedule(coro, trigger=trigger)
if _debug:
self.log.debug("Scheduled coroutine %s" % (coro.__name__))
# Schedule may have queued up some events so we'll burn through those
while self._pending_events:
if _debug:
self.log.debug("Scheduling pending event %s" %
(str(self._pending_events[0])))
self._pending_events.pop(0).set()
# remove our reference to the objects at the end of each loop,
# to try and avoid them being destroyed at a weird time (as
# happened in gh-957)
del trigger
del coro
del scheduling
# no more pending triggers
self._check_termination()
if _debug:
self.log.debug("All coroutines scheduled, handing control back"
" to simulator")
def unschedule(self, coro):
"""Unschedule a coroutine. Unprime any pending triggers"""
# Unprime the trigger this coroutine is waiting on
try:
trigger = self._coro2trigger.pop(coro)
except KeyError:
# coroutine probably finished
pass
else:
if coro in self._trigger2coros.setdefault(trigger, []):
self._trigger2coros[trigger].remove(coro)
if not self._trigger2coros[trigger]:
trigger.unprime()
del self._trigger2coros[trigger]
if Join(coro) in self._trigger2coros:
self.react(Join(coro))
else:
try:
# throws an error if the background coroutine errored
# and no one was monitoring it
coro.retval
except TestComplete as test_result:
self.log.debug("TestComplete received: {}".format(test_result.__class__.__name__))
self.finish_test(test_result)
except Exception as e:
self.finish_test(create_error(self, "Forked coroutine {} raised exception: {}".format(coro, e)))
def save_write(self, handle, value):
if self._mode == Scheduler._MODE_READONLY:
raise Exception("Write to object {0} was scheduled during a read-only sync phase.".format(handle._name))
# TODO: we should be able to better keep track of when this needs to
# be scheduled
if self._write_coro_inst is None:
self._write_coro_inst = self._do_writes()
self.schedule(self._write_coro_inst)
self._writes[handle] = value
self._writes_pending.set()
def _coroutine_yielded(self, coro, trigger):
"""Prime the trigger and update our internal mappings."""
self._coro2trigger[coro] = trigger
trigger_coros = self._trigger2coros.setdefault(trigger, [])
if coro is self._write_coro_inst:
# Our internal write coroutine always runs before any user coroutines.
# This preserves the behavior prior to the refactoring of writes to
# this coroutine.
trigger_coros.insert(0, coro)
else:
# Everything else joins the back of the queue
trigger_coros.append(coro)
if not trigger.primed:
if trigger_coros != [coro]:
# should never happen
raise InternalError(
"More than one coroutine waiting on an unprimed trigger")
try:
trigger.prime(self.react)
except Exception as e:
# discard the trigger we associated, it will never fire
self._trigger2coros.pop(trigger)
# replace it with a new trigger that throws back the exception
error_trigger = NullTrigger(outcome=outcomes.Error(e))
self._coro2trigger[coro] = error_trigger
self._trigger2coros[error_trigger] = [coro]
# wake up the coroutines
error_trigger.prime(self.react)
def queue(self, coroutine):
"""Queue a coroutine for execution"""
self._pending_coros.append(coroutine)
def queue_function(self, coroutine):
"""Queue a coroutine for execution and move the containing thread
so that it does not block execution of the main thread any longer.
"""
# We should be able to find ourselves inside the _pending_threads list
matching_threads = [
t
for t in self._pending_threads
if t.thread == threading.current_thread()
]
if len(matching_threads) == 0:
raise RuntimeError("queue_function called from unrecognized thread")
# Raises if there is more than one match. This can never happen, since
# each entry always has a unique thread.
t, = matching_threads
t.thread_suspend()
self._pending_coros.append(coroutine)
return t
def run_in_executor(self, func, *args, **kwargs):
"""Run the coroutine in a separate execution thread
and return a yieldable object for the caller.
"""
# Create a thread
# Create a trigger that is called as a result of the thread finishing
# Create an Event object that the caller can yield on
# Event object set when the thread finishes execution, this blocks the
# calling coroutine (but not the thread) until the external completes
def execute_external(func, _waiter):
_waiter._outcome = outcomes.capture(func, *args, **kwargs)
if _debug:
self.log.debug("Execution of external routine done %s" % threading.current_thread())
_waiter.thread_done()
waiter = external_waiter()
thread = threading.Thread(group=None, target=execute_external,
name=func.__name__ + "_thread",
args=([func, waiter]), kwargs={})
waiter.thread = thread
self._pending_threads.append(waiter)
return waiter
def add(self, coroutine):
"""Add a new coroutine.
Just a wrapper around self.schedule which provides some debug and
useful error messages in the event of common gotchas.
"""
if isinstance(coroutine, cocotb.decorators.coroutine):
raise TypeError(
"Attempt to schedule a coroutine that hasn't started: {}.\n"
"Did you forget to add parentheses to the @cocotb.test() "
"decorator?"
.format(coroutine)
)
elif not isinstance(coroutine, cocotb.decorators.RunningCoroutine):
raise TypeError(
"Attempt to add a object of type {} to the scheduler, which "
"isn't a coroutine: {!r}\n"
"Did you forget to use the @cocotb.coroutine decorator?"
.format(type(coroutine), coroutine)
)
if _debug:
self.log.debug("Adding new coroutine %s" % coroutine.__name__)
self.schedule(coroutine)
self._check_termination()
return coroutine
def new_test(self, coroutine):
self._entrypoint = coroutine
# This collection of functions parses a trigger out of the object
# that was yielded by a coroutine, converting `list` -> `Waitable`,
# `Waitable` -> `RunningCoroutine`, `RunningCoroutine` -> `Trigger`.
# Doing them as separate functions allows us to avoid repeating unencessary
# `isinstance` checks.
def _trigger_from_started_coro(self, result):
# type: (cocotb.decorators.RunningCoroutine) -> Trigger
if _debug:
self.log.debug("Joining to already running coroutine: %s" %
result.__name__)
return result.join()
def _trigger_from_unstarted_coro(self, result):
# type: (cocotb.decorators.RunningCoroutine) -> Trigger
self.queue(result)
if _debug:
self.log.debug("Scheduling nested coroutine: %s" %
result.__name__)
return result.join()
def _trigger_from_waitable(self, result):
# type: (cocotb.triggers.Waitable) -> Trigger
return self._trigger_from_unstarted_coro(result._wait())
def _trigger_from_list(self, result):
# type: (list) -> Trigger
return self._trigger_from_waitable(cocotb.triggers.First(*result))
def _trigger_from_any(self, result):
"""Convert a yielded object into a Trigger instance"""
# note: the order of these can significantly impact performance
if isinstance(result, Trigger):
return result
if isinstance(result, cocotb.decorators.RunningCoroutine):
if not result.has_started():
return self._trigger_from_unstarted_coro(result)
else:
return self._trigger_from_started_coro(result)
if isinstance(result, list):
return self._trigger_from_list(result)
if isinstance(result, cocotb.triggers.Waitable):
return self._trigger_from_waitable(result)
raise TypeError(
"Coroutine yielded an object of type {}, which the scheduler can't "
"handle: {!r}\n"
"Did you forget to decorate with @cocotb.coroutine?"
.format(type(result), result)
)
def schedule(self, coroutine, trigger=None):
"""Schedule a coroutine by calling the send method.
Args:
coroutine (cocotb.decorators.coroutine): The coroutine to schedule.
trigger (cocotb.triggers.Trigger): The trigger that caused this
coroutine to be scheduled.
"""
if trigger is None:
send_outcome = outcomes.Value(None)
else:
send_outcome = trigger._outcome
if _debug:
self.log.debug("Scheduling with {}".format(send_outcome))
try:
result = coroutine._advance(send_outcome)
if _debug:
self.log.debug("Coroutine %s yielded %s (mode %d)" %
(coroutine.__name__, str(result), self._mode))
# TestComplete indication is game over, tidy up
except TestComplete as test_result:
# Tag that close down is needed, save the test_result
# for later use in cleanup handler
self.log.debug("TestComplete received: %s" % test_result.__class__.__name__)
self.finish_test(test_result)
return
# Normal coroutine completion
except cocotb.decorators.CoroutineComplete as exc:
if _debug:
self.log.debug("Coroutine completed: %s" % str(coroutine))
self.unschedule(coroutine)
return
# Don't handle the result if we're shutting down
if self._terminate:
return
try:
result = self._trigger_from_any(result)
except TypeError as exc:
# restart this coroutine with an exception object telling it that
# it wasn't allowed to yield that
result = NullTrigger(outcome=outcomes.Error(exc))
self._coroutine_yielded(coroutine, result)
# We do not return from here until pending threads have completed, but only
# from the main thread, this seems like it could be problematic in cases
# where a sim might change what this thread is.
def unblock_event(ext):
@cocotb.coroutine
def wrapper():
ext.event.set()
yield PythonTrigger()
if self._main_thread is threading.current_thread():
for ext in self._pending_threads:
ext.thread_start()
if _debug:
self.log.debug("Blocking from %s on %s" % (threading.current_thread(), ext.thread))
state = ext.thread_wait()
if _debug:
self.log.debug("Back from wait on self %s with newstate %d" % (threading.current_thread(), state))
if state == external_state.EXITED:
self._pending_threads.remove(ext)
self._pending_events.append(ext.event)
# Handle any newly queued coroutines that need to be scheduled
while self._pending_coros:
self.add(self._pending_coros.pop(0))
def finish_test(self, test_result):
"""Cache the test result and set the terminate flag."""
self.log.debug("finish_test called with %s" % (repr(test_result)))
if not self._terminate:
self._terminate = True
self._test_result = test_result
self.cleanup()
def finish_scheduler(self, test_result):
"""Directly call into the regression manager and end test
once we return the sim will close us so no cleanup is needed.
"""
self.log.debug("Issue sim closedown result to regression object")
cocotb.regression_manager.handle_result(test_result)
def cleanup(self):
"""Clear up all our state.
Unprime all pending triggers and kill off any coroutines stop all externals.
"""
# copy since we modify this in kill
items = list(self._trigger2coros.items())
# reversing seems to fix gh-928, although the order is still somewhat
# arbitrary.
for trigger, waiting in items[::-1]:
for coro in waiting:
if _debug:
self.log.debug("Killing %s" % str(coro))
coro.kill()
if self._main_thread is not threading.current_thread():
raise Exception("Cleanup() called outside of the main thread")
for ext in self._pending_threads:
self.log.warn("Waiting for %s to exit", ext.thread)
class Scoreboard(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.
TODO:
Statistics for end-of-test summary etc.
"""
def __init__(self, dut, reorder_depth=0, fail_immediately=True):
self.dut = dut
self.log = SimLog("cocotb.scoreboard.%s" % self.dut.name)
self.errors = 0
self.expected = {}
self._imm = fail_immediately
@property
def result(self):
"""Determine the test result, do we have any pending data remaining?"""
fail = False
for monitor, expected_output in self.expected.items():
if callable(expected_output):
self.log.debug("Can't check all data returned for %s since "
"expected output is callable function rather "
"than a list" % str(monitor))
continue
if len(expected_output):
self.log.warn("Still expecting %d transactions on %s" %
(len(expected_output), str(monitor)))
for index, transaction in enumerate(expected_output):
self.log.info("Expecting %d:\n%s" %
(index, hexdump(str(transaction))))
if index > 5:
self.log.info("... and %d more to come" %
(len(expected_output) - index - 1))
break
fail = True
if fail:
return TestFailure("Not all expected output was received")
if self.errors:
return TestFailure("Errors were recorded during the test")
return TestSuccess()
def compare(self, got, exp, log, strict_type=True):
"""
Common function for comparing two transactions.
Can be re-implemented by a subclass.
"""
# Compare the types
if strict_type and type(got) != type(exp):
self.errors += 1
log.error("Received transaction is a different type to expected "
"transaction")
log.info("Got: %s but expected %s" %
(str(type(got)), str(type(exp))))
if self._imm:
raise TestFailure("Received transaction of wrong type")
return
# Or convert to a string before comparison
elif not strict_type:
got, exp = str(got), str(exp)
# Compare directly
if got != exp:
self.errors += 1
# Try our best to print out something useful
strgot, strexp = str(got), str(exp)
log.error("Received transaction differed from expected output")
if not strict_type:
log.info("Expected:\n" + hexdump(strexp))
else:
log.info("Expected:\n" + repr(exp))
if not isinstance(exp, str):
try:
for word in exp:
log.info(str(word))
except:
pass
if not strict_type:
log.info("Received:\n" + hexdump(strgot))
else:
log.info("Received:\n" + repr(got))
if not isinstance(got, str):
try:
for word in got:
log.info(str(word))
except:
pass
log.warning("Difference:\n%s" % hexdiffs(strexp, strgot))
if self._imm:
raise TestFailure("Received transaction differed from expected"
"transaction")
else:
# Don't want to fail the test
# if we're passed something without __len__
try:
log.debug("Received expected transaction %d bytes" %
(len(got)))
log.debug(repr(got))
except:
pass
def add_interface(self,
monitor,
expected_output,
compare_fn=None,
reorder_depth=0,
strict_type=True):
"""Add an interface to be scoreboarded.
Provides a function which the monitor will callback with received
transactions
Simply check against the expected output.
"""
# save a handle to the expected output so we can check if all expected
# data has been received at the end of a test.
self.expected[monitor] = expected_output
# Enforce some type checking as we only work with a real monitor
if not isinstance(monitor, Monitor):
raise TypeError("Expected monitor on the interface but got %s" %
(monitor.__class__.__name__))
if compare_fn is not None:
if callable(compare_fn):
monitor.add_callback(compare_fn)
return
raise TypeError("Expected a callable compare function but got %s" %
str(type(compare_fn)))
self.log.info("Created with reorder_depth %d" % reorder_depth)
def check_received_transaction(transaction):
"""Called back by the monitor when a new transaction has been
received"""
log = logging.getLogger(self.log.name + '.' + monitor.name)
if callable(expected_output):
exp = expected_output(transaction)
elif len(expected_output):
for i in range(min((reorder_depth + 1), len(expected_output))):
if expected_output[i] == transaction:
break
else:
i = 0
exp = expected_output.pop(i)
else:
self.errors += 1
log.error("Received a transaction but wasn't expecting "
"anything")
log.info("Got: %s" % (hexdump(str(transaction))))
if self._imm:
raise TestFailure("Received a transaction but wasn't "
"expecting anything")
return
self.compare(transaction, exp, log, strict_type=strict_type)
monitor.add_callback(check_received_transaction)
class Scheduler(object):
"""The main scheduler.
Here we accept callbacks from the simulator and schedule the appropriate
coroutines.
A callback fires, causing the :any:`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. NB 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) or vhpiCbLastKnownDeltaCycle
(VHPI). In this state we are not allowed to perform writes.
Write mode
- Corresponds to cbReadWriteSynch (VPI) or vhpiCbEndOfProcesses (VHPI)
In this mode we play back all the cached write updates.
We can legally transition from normal->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.
"""
_MODE_NORMAL = 1 # noqa
_MODE_READONLY = 2 # noqa
_MODE_WRITE = 3 # noqa
_MODE_TERM = 4 # noqa
# Singleton events, recycled to avoid spurious object creation
_readonly = ReadOnly()
# TODO[gh-759]: For some reason, the scheduler requires that these triggers
# are _not_ the same instances used by the tests themselves. This is risky,
# because it can lead to them overwriting each other's callbacks. We should
# try to remove this `copy.copy` in future.
_next_timestep = copy.copy(NextTimeStep())
_readwrite = copy.copy(ReadWrite())
_timer1 = Timer(1)
_timer0 = Timer(0)
def __init__(self):
self.log = SimLog("cocotb.scheduler")
if _debug:
self.log.setLevel(logging.DEBUG)
# A dictionary of pending coroutines for each trigger,
# indexed by trigger
self._trigger2coros = collections.defaultdict(list)
# A dictionary mapping coroutines to the trigger they are waiting for
self._coro2trigger = {}
# Our main state
self._mode = Scheduler._MODE_NORMAL
# A dictionary of pending writes
self._writes = {}
self._pending_coros = []
self._pending_callbacks = []
self._pending_triggers = []
self._pending_threads = []
self._pending_events = [] # Events we need to call set on once we've unwound
self._terminate = False
self._test_result = None
self._entrypoint = None
self._main_thread = threading.current_thread()
# Select the appropriate scheduling algorithm for this simulator
self.advance = self.default_scheduling_algorithm
self._is_reacting = False
def default_scheduling_algorithm(self):
"""
Decide whether we need to schedule our own triggers (if at all) in
order to progress to the next mode.
This algorithm has been tested against the following simulators:
Icarus Verilog
"""
if not self._terminate and self._writes:
if self._mode == Scheduler._MODE_NORMAL:
if not self._readwrite.primed:
self._readwrite.prime(self.react)
elif not self._next_timestep.primed:
self._next_timestep.prime(self.react)
elif self._terminate:
if _debug:
self.log.debug("Test terminating, scheduling Timer")
for t in self._trigger2coros:
t.unprime()
for t in [self._readwrite, self._readonly, self._next_timestep,
self._timer1, self._timer0]:
if t.primed:
t.unprime()
self._timer1.prime(self.begin_test)
self._trigger2coros = collections.defaultdict(list)
self._coro2trigger = {}
self._terminate = False
self._mode = Scheduler._MODE_TERM
def begin_test(self, trigger=None):
"""Called to initiate a test.
Could be called on start-up or from a callback.
"""
if _debug:
self.log.debug("begin_test called with trigger: %s" %
(str(trigger)))
if _profiling:
ps = pstats.Stats(_profile).sort_stats('cumulative')
ps.dump_stats("test_profile.pstat")
ctx = profiling_context()
else:
ctx = nullcontext()
with ctx:
self._mode = Scheduler._MODE_NORMAL
if trigger is not None:
trigger.unprime()
# Issue previous test result, if there is one
if self._test_result is not None:
if _debug:
self.log.debug("Issue test result to regression object")
cocotb.regression_manager.handle_result(self._test_result)
self._test_result = None
if self._entrypoint is not None:
test = self._entrypoint
self._entrypoint = None
self.schedule(test)
self.advance()
def react(self, trigger):
"""
Called when a trigger fires.
We ensure that we only start the event loop once, rather than
letting it recurse.
"""
if self._is_reacting:
# queue up the trigger, the event loop will get to it
self._pending_triggers.append(trigger)
return
# start the event loop
self._is_reacting = True
try:
self._event_loop(trigger)
finally:
self._is_reacting = False
def _event_loop(self, trigger):
"""
Run an event loop triggered by the given trigger.
The loop will keep running until no further triggers fire.
This should be triggered by only:
* The beginning of a test, when there is no trigger to react to
* A GPI trigger
"""
if _profiling:
ctx = profiling_context()
else:
ctx = nullcontext()
with ctx:
# When a trigger fires it is unprimed internally
if _debug:
self.log.debug("Trigger fired: %s" % str(trigger))
# trigger.unprime()
if self._mode == Scheduler._MODE_TERM:
if _debug:
self.log.debug("Ignoring trigger %s since we're terminating" %
str(trigger))
return
if trigger is self._readonly:
self._mode = Scheduler._MODE_READONLY
# Only GPI triggers affect the simulator scheduling mode
elif isinstance(trigger, GPITrigger):
self._mode = Scheduler._MODE_NORMAL
# We're the only source of ReadWrite triggers which are only used for
# playing back any cached signal updates
if trigger is self._readwrite:
if _debug:
self.log.debug("Writing cached signal updates")
while self._writes:
handle, value = self._writes.popitem()
handle.setimmediatevalue(value)
self._readwrite.unprime()
return
# Similarly if we've scheduled our next_timestep on way to readwrite
if trigger is self._next_timestep:
if not self._writes:
self.log.error(
"Moved to next timestep without any pending writes!")
else:
self.log.debug(
"Priming ReadWrite trigger so we can playback writes")
self._readwrite.prime(self.react)
return
# work through triggers one by one
is_first = True
self._pending_triggers.append(trigger)
while self._pending_triggers:
trigger = self._pending_triggers.pop(0)
if not is_first and isinstance(trigger, GPITrigger):
self.log.warning(
"A GPI trigger occurred after entering react - this "
"should not happen."
)
assert False
# this only exists to enable the warning above
is_first = False
if trigger not in self._trigger2coros:
# GPI triggers should only be ever pending if there is an
# associated coroutine waiting on that trigger, otherwise it would
# have been unprimed already
if isinstance(trigger, GPITrigger):
self.log.critical(
"No coroutines waiting on trigger that fired: %s" %
str(trigger))
trigger.log.info("I'm the culprit")
# For Python triggers this isn't actually an error - we might do
# event.set() without knowing whether any coroutines are actually
# waiting on this event, for example
elif _debug:
self.log.debug(
"No coroutines waiting on trigger that fired: %s" %
str(trigger))
continue
# Scheduled coroutines may append to our waiting list so the first
# thing to do is pop all entries waiting on this trigger.
scheduling = self._trigger2coros.pop(trigger)
if _debug:
debugstr = "\n\t".join([coro.__name__ for coro in scheduling])
if len(scheduling):
debugstr = "\n\t" + debugstr
self.log.debug("%d pending coroutines for event %s%s" %
(len(scheduling), str(trigger), debugstr))
# This trigger isn't needed any more
trigger.unprime()
for coro in scheduling:
if _debug:
self.log.debug("Scheduling coroutine %s" % (coro.__name__))
self.schedule(coro, trigger=trigger)
if _debug:
self.log.debug("Scheduled coroutine %s" % (coro.__name__))
# Schedule may have queued up some events so we'll burn through those
while self._pending_events:
if _debug:
self.log.debug("Scheduling pending event %s" %
(str(self._pending_events[0])))
self._pending_events.pop(0).set()
# no more pending triggers
self.advance()
if _debug:
self.log.debug("All coroutines scheduled, handing control back"
" to simulator")
def unschedule(self, coro):
"""Unschedule a coroutine. Unprime any pending triggers"""
# Unprime the trigger this coroutine is waiting on
try:
trigger = self._coro2trigger.pop(coro)
except KeyError:
# coroutine probably finished
pass
else:
if coro in self._trigger2coros[trigger]:
self._trigger2coros[trigger].remove(coro)
if not self._trigger2coros[trigger]:
trigger.unprime()
del self._trigger2coros[trigger]
if Join(coro) in self._trigger2coros:
self._pending_triggers.append(Join(coro))
else:
try:
# throws an error if the background coroutine errored
# and no one was monitoring it
coro.retval
except Exception as e:
self._test_result = TestError(
"Forked coroutine {} raised exception {}"
.format(coro, e)
)
self._terminate = True
def save_write(self, handle, value):
if self._mode == Scheduler._MODE_READONLY:
raise Exception("Write to object {0} was scheduled during a read-only sync phase.".format(handle._name))
self._writes[handle] = value
def _coroutine_yielded(self, coro, trigger):
"""Prime the trigger and update our internal mappings."""
self._coro2trigger[coro] = trigger
self._trigger2coros[trigger].append(coro)
if not trigger.primed:
try:
trigger.prime(self.react)
except Exception as e:
# Convert any exceptions into a test result
self.finish_test(
create_error(self, "Unable to prime trigger %s: %s" %
(str(trigger), str(e))))
def queue(self, coroutine):
"""Queue a coroutine for execution"""
self._pending_coros.append(coroutine)
def queue_function(self, coroutine):
"""Queue a coroutine for execution and move the containing thread
so that it does not block execution of the main thread any longer.
"""
# We should be able to find ourselves inside the _pending_threads list
for t in self._pending_threads:
if t.thread == threading.current_thread():
t.thread_suspend()
self._pending_coros.append(coroutine)
return t
def run_in_executor(self, func, *args, **kwargs):
"""Run the coroutine in a separate execution thread
and return a yieldable object for the caller.
"""
# Create a thread
# Create a trigger that is called as a result of the thread finishing
# Create an Event object that the caller can yield on
# Event object set when the thread finishes execution, this blocks the
# calling coroutine (but not the thread) until the external completes
def execute_external(func, _waiter):
_waiter._outcome = outcomes.capture(func, *args, **kwargs)
if _debug:
self.log.debug("Execution of external routine done %s" % threading.current_thread())
_waiter.thread_done()
waiter = external_waiter()
thread = threading.Thread(group=None, target=execute_external,
name=func.__name__ + "_thread",
args=([func, waiter]), kwargs={})
waiter.thread = thread;
self._pending_threads.append(waiter)
return waiter
def add(self, coroutine):
"""Add a new coroutine.
Just a wrapper around self.schedule which provides some debug and
useful error messages in the event of common gotchas.
"""
if isinstance(coroutine, cocotb.decorators.coroutine):
self.log.critical(
"Attempt to schedule a coroutine that hasn't started")
coroutine.log.error("This is the failing coroutine")
self.log.warning(
"Did you forget to add parentheses to the @test decorator?")
self._test_result = TestError(
"Attempt to schedule a coroutine that hasn't started")
self._terminate = True
return
elif not isinstance(coroutine, cocotb.decorators.RunningCoroutine):
self.log.critical(
"Attempt to add something to the scheduler which isn't a "
"coroutine")
self.log.warning(
"Got: %s (%s)" % (str(type(coroutine)), repr(coroutine)))
self.log.warning("Did you use the @coroutine decorator?")
self._test_result = TestError(
"Attempt to schedule a coroutine that hasn't started")
self._terminate = True
return
if _debug:
self.log.debug("Adding new coroutine %s" % coroutine.__name__)
self.schedule(coroutine)
self.advance()
return coroutine
def new_test(self, coroutine):
self._entrypoint = coroutine
def schedule(self, coroutine, trigger=None):
"""Schedule a coroutine by calling the send method.
Args:
coroutine (cocotb.decorators.coroutine): The coroutine to schedule.
trigger (cocotb.triggers.Trigger): The trigger that caused this
coroutine to be scheduled.
"""
if trigger is None:
send_outcome = outcomes.Value(None)
else:
send_outcome = trigger._outcome
if _debug:
self.log.debug("Scheduling with {}".format(send_outcome))
try:
result = coroutine._advance(send_outcome)
if _debug:
self.log.debug("Coroutine %s yielded %s (mode %d)" %
(coroutine.__name__, str(result), self._mode))
# TestComplete indication is game over, tidy up
except TestComplete as test_result:
# Tag that close down is needed, save the test_result
# for later use in cleanup handler
self.log.debug("TestComplete received: %s" % test_result.__class__.__name__)
self.finish_test(test_result)
return
# Normal coroutine completion
except cocotb.decorators.CoroutineComplete as exc:
if _debug:
self.log.debug("Coroutine completed: %s" % str(coroutine))
self.unschedule(coroutine)
return
# Don't handle the result if we're shutting down
if self._terminate:
return
# convert lists into `First` Waitables.
if isinstance(result, list):
result = cocotb.triggers.First(*result)
# convert waitables into coroutines
if isinstance(result, cocotb.triggers.Waitable):
result = result._wait()
# convert coroutinues into triggers
if isinstance(result, cocotb.decorators.RunningCoroutine):
if not result.has_started():
self.queue(result)
if _debug:
self.log.debug("Scheduling nested coroutine: %s" %
result.__name__)
else:
if _debug:
self.log.debug("Joining to already running coroutine: %s" %
result.__name__)
result = result.join()
if isinstance(result, Trigger):
if _debug:
self.log.debug("%s: is instance of Trigger" % result)
self._coroutine_yielded(coroutine, result)
else:
msg = ("Coroutine %s yielded something the scheduler can't handle"
% str(coroutine))
msg += ("\nGot type: %s repr: %s str: %s" %
(type(result), repr(result), str(result)))
msg += "\nDid you forget to decorate with @cocotb.coroutine?"
try:
raise_error(self, msg)
except Exception as e:
self.finish_test(e)
# We do not return from here until pending threads have completed, but only
# from the main thread, this seems like it could be problematic in cases
# where a sim might change what this thread is.
def unblock_event(ext):
@cocotb.coroutine
def wrapper():
ext.event.set()
yield PythonTrigger()
if self._main_thread is threading.current_thread():
for ext in self._pending_threads:
ext.thread_start()
if _debug:
self.log.debug("Blocking from %s on %s" % (threading.current_thread(), ext.thread))
state = ext.thread_wait()
if _debug:
self.log.debug("Back from wait on self %s with newstate %d" % (threading.current_thread(), state))
if state == external_state.EXITED:
self._pending_threads.remove(ext)
self._pending_events.append(ext.event)
# Handle any newly queued coroutines that need to be scheduled
while self._pending_coros:
self.add(self._pending_coros.pop(0))
while self._pending_callbacks:
self._pending_callbacks.pop(0)()
def finish_test(self, test_result):
"""Cache the test result and set the terminate flag."""
self.log.debug("finish_test called with %s" % (repr(test_result)))
if not self._terminate:
self._terminate = True
self._test_result = test_result
self.cleanup()
def finish_scheduler(self, test_result):
"""Directly call into the regression manager and end test
once we return the sim will close us so no cleanup is needed.
"""
self.log.debug("Issue sim closedown result to regression object")
cocotb.regression_manager.handle_result(test_result)
def cleanup(self):
"""Clear up all our state.
Unprime all pending triggers and kill off any coroutines stop all externals.
"""
for trigger, waiting in dict(self._trigger2coros).items():
for coro in waiting:
if _debug:
self.log.debug("Killing %s" % str(coro))
coro.kill()
if self._main_thread is not threading.current_thread():
raise Exception("Cleanup() called outside of the main thread")
for ext in self._pending_threads:
self.log.warn("Waiting for %s to exit", ext.thread)
class Scoreboard(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.
TODO:
Statistics for end-of-test summary etc.
"""
def __init__(self, dut, reorder_depth=0, fail_immediately=True):
self.dut = dut
self.log = SimLog("cocotb.scoreboard.%s" % self.dut._name)
self.errors = 0
self.expected = {}
self._imm = fail_immediately
@property
def result(self):
"""Determine the test result, do we have any pending data remaining?"""
fail = False
for monitor, expected_output in self.expected.items():
if callable(expected_output):
self.log.debug("Can't check all data returned for %s since "
"expected output is callable function rather "
"than a list" % str(monitor))
continue
if len(expected_output):
self.log.warn("Still expecting %d transactions on %s" %
(len(expected_output), str(monitor)))
for index, transaction in enumerate(expected_output):
self.log.info("Expecting %d:\n%s" %
(index, hexdump(str(transaction))))
if index > 5:
self.log.info("... and %d more to come" %
(len(expected_output) - index - 1))
break
fail = True
if fail:
return TestFailure("Not all expected output was received")
if self.errors:
return TestFailure("Errors were recorded during the test")
return TestSuccess()
def compare(self, got, exp, log, strict_type=True):
"""
Common function for comparing two transactions.
Can be re-implemented by a subclass.
"""
# Compare the types
if strict_type and type(got) != type(exp):
self.errors += 1
log.error("Received transaction type is different than expected")
log.info("Received: %s but expected %s" %
(str(type(got)), str(type(exp))))
if self._imm:
raise TestFailure("Received transaction of wrong type. "
"Set strict_type=False to avoid this.")
return
# Or convert to a string before comparison
elif not strict_type:
got, exp = str(got), str(exp)
# Compare directly
if got != exp:
self.errors += 1
# Try our best to print out something useful
strgot, strexp = str(got), str(exp)
log.error("Received transaction differed from expected output")
if not strict_type:
log.info("Expected:\n" + hexdump(strexp))
else:
log.info("Expected:\n" + repr(exp))
if not isinstance(exp, str):
try:
for word in exp:
log.info(str(word))
except:
pass
if not strict_type:
log.info("Received:\n" + hexdump(strgot))
else:
log.info("Received:\n" + repr(got))
if not isinstance(got, str):
try:
for word in got:
log.info(str(word))
except:
pass
log.warning("Difference:\n%s" % hexdiffs(strexp, strgot))
if self._imm:
raise TestFailure("Received transaction differed from expected"
"transaction")
else:
# Don't want to fail the test
# if we're passed something without __len__
try:
log.debug("Received expected transaction %d bytes" %
(len(got)))
log.debug(repr(got))
except:
pass
def add_interface(self, monitor, expected_output, compare_fn=None,
reorder_depth=0, strict_type=True):
"""Add an interface to be scoreboarded.
Provides a function which the monitor will callback with received
transactions
Simply check against the expected output.
"""
# save a handle to the expected output so we can check if all expected
# data has been received at the end of a test.
self.expected[monitor] = expected_output
# Enforce some type checking as we only work with a real monitor
if not isinstance(monitor, Monitor):
raise TypeError("Expected monitor on the interface but got %s" %
(monitor.__class__.__name__))
if compare_fn is not None:
if callable(compare_fn):
monitor.add_callback(compare_fn)
return
raise TypeError("Expected a callable compare function but got %s" %
str(type(compare_fn)))
self.log.info("Created with reorder_depth %d" % reorder_depth)
def check_received_transaction(transaction):
"""Called back by the monitor when a new transaction has been
received"""
if monitor.name:
log_name = self.log.name + '.' + monitor.name
else:
log_name = self.log.name + '.' + monitor.__class__.__name__
log = logging.getLogger(log_name)
if callable(expected_output):
exp = expected_output(transaction)
elif len(expected_output):
for i in range(min((reorder_depth + 1), len(expected_output))):
if expected_output[i] == transaction:
break
else:
i = 0
exp = expected_output.pop(i)
else:
self.errors += 1
log.error("Received a transaction but wasn't expecting "
"anything")
log.info("Got: %s" % (hexdump(str(transaction))))
if self._imm:
raise TestFailure("Received a transaction but wasn't "
"expecting anything")
return
self.compare(transaction, exp, log, strict_type=strict_type)
monitor.add_callback(check_received_transaction)
class Scoreboard(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.
TODO:
Statistics for end-of-test summary etc.
"""
def __init__(self, dut, reorder_depth=0, fail_immediately=True):
self.dut = dut
self.log = SimLog("cocotb.scoreboard.%s" % self.dut.name)
self.errors = 0
self.expected = {}
self._imm = fail_immediately
@property
def result(self):
"""Determine the test result - do we have any pending data remaining?"""
fail = False
for monitor, expected_output in self.expected.iteritems():
if callable(expected_output):
self.log.debug("Can't check all data returned for %s since expected output is \
callable function rather than a list" % str(monitor))
continue
if len(expected_output):
self.log.warn("Still expecting %d transactions on %s" % (len(expected_output), str(monitor)))
for index, transaction in enumerate(expected_output):
self.log.info("Expecting %d:\n%s" % (index, hexdump(str(transaction))))
if index > 5:
self.log.info("... and %d more to come" % (len(expected_output) - index - 1))
break
fail = True
if fail:
return TestFailure("Not all expected output was received")
if self.errors:
return TestFailure("Errors were recorded during the test")
return TestSuccess()
def add_interface(self, monitor, expected_output, compare_fn=None):
"""Add an interface to be scoreboarded.
Provides a function which the monitor will callback with received transactions
Simply check against the expected output.
"""
# save a handle to the expected output so we can check if all expected data has
# been received at the end of a test.
self.expected[monitor] = expected_output
# Enforce some type checking as we only work with a real monitor
if not isinstance(monitor, Monitor):
raise TypeError("Expected monitor on the interface but got %s" % (monitor.__class__.__name__))
if compare_fn is not None:
if callable(compare_fn):
monitor.add_callback(compare_fn)
return
raise TypeError("Expected a callable compare function but got %s" % str(type(compare_fn)))
def check_received_transaction(transaction):
"""Called back by the monitor when a new transaction has been received"""
log = logging.getLogger(self.log.name + '.' + monitor.name)
if callable(expected_output):
exp = expected_output(transaction)
elif len(expected_output):
exp = expected_output.pop(0)
else:
self.errors += 1
log.error("Received a transaction but wasn't expecting anything")
log.info("Got: %s" % (hexdump(str(transaction))))
if self._imm: raise TestFailure("Received a transaction but wasn't expecting anything")
return
if type(transaction) != type(exp):
self.errors += 1
log.error("Received transaction is a different type to expected transaction")
log.info("Got: %s but expected %s" % (str(type(transaction)), str(type(exp))))
if self._imm: raise TestFailure("Received transaction of wrong type")
return
if transaction != exp:
self.errors += 1
log.error("Received transaction differed from expected output")
log.info("Expected:\n" + hexdump(exp))
if not isinstance(exp, str):
try:
for word in exp: self.log.info(str(word))
except: pass
log.info("Received:\n" + hexdump(transaction))
if not isinstance(transaction, str):
try:
for word in transaction: self.log.info(str(word))
except: pass
log.warning("Difference:\n%s" % hexdiffs(exp, transaction))
if self._imm: raise TestFailure("Received transaction differed from expected transaction")
else:
# Don't want to fail the test if we're passed something without __len__
try:
log.debug("Received expected transaction %d bytes" % (len(transaction)))
log.debug(repr(transaction))
except: pass
monitor.add_callback(check_received_transaction)
