class RunningCoroutine(object): """Per instance wrapper around an function to turn it into a coroutine. Provides the following: coro.join() creates a Trigger that will fire when this coroutine completes. coro.kill() will destroy a coroutine instance (and cause any Join triggers to fire. """ def __init__(self, inst, parent): if hasattr(inst, "__name__"): self.__name__ = "%s" % inst.__name__ self.log = SimLog("cocotb.coroutine.%s" % self.__name__, id(self)) else: self.log = SimLog("cocotb.coroutine.fail") if sys.version_info[:2] >= (3, 5) and inspect.iscoroutine(inst): self._natively_awaitable = True self._coro = inst.__await__() else: self._natively_awaitable = False self._coro = inst self._started = False self._callbacks = [] self._parent = parent self.__doc__ = parent._func.__doc__ self.module = parent._func.__module__ self.funcname = parent._func.__name__ self._outcome = None if not hasattr(self._coro, "send"): self.log.error("%s isn't a valid coroutine! Did you use the yield " "keyword?" % self.funcname) raise CoroutineComplete() @property def retval(self): if self._outcome is None: raise RuntimeError("coroutine is not complete") return self._outcome.get() @property def _finished(self): return self._outcome is not None def __iter__(self): return self def __str__(self): return str(self.__name__) def _advance(self, outcome): """ Advance to the next yield in this coroutine :param outcome: The `outcomes.Outcome` object to resume with. :returns: The object yielded from the coroutine If the coroutine returns or throws an error, self._outcome is set, and this throws `CoroutineComplete`. """ try: self._started = True return outcome.send(self._coro) except ReturnValue as e: self._outcome = outcomes.Value(e.retval) raise CoroutineComplete() except StopIteration as e: retval = getattr(e, 'value', None) # for python >=3.3 self._outcome = outcomes.Value(retval) raise CoroutineComplete() except BaseException as e: self._outcome = outcomes.Error(e) raise CoroutineComplete() def send(self, value): return self._coro.send(value) def throw(self, exc): return self._coro.throw(exc) def close(self): return self._coro.close() def kill(self): """Kill a coroutine.""" self.log.debug("kill() called on coroutine") # todo: probably better to throw an exception for anyone waiting on the coroutine self._outcome = outcomes.Value(None) cocotb.scheduler.unschedule(self) def join(self): """Return a trigger that will fire when the wrapped coroutine exits.""" return Join(self) def has_started(self): return self._started def __nonzero__(self): """Provide boolean testing if the coroutine has finished return false otherwise return true""" return not self._finished # Needs `yield from` syntax to implement this correctly. # Once 2.7 is dropped, this can be run unconditionally if sys.version_info >= (3, 3): exec_(textwrap.dedent(""" def __await__(self): if self._natively_awaitable: # use the native trampoline, which will only hand back nested # non-natively awaitable objects return (yield from self._coro) else: # hand the coroutine back to the scheduler trampoline return (yield self) """)) __bool__ = __nonzero__ def sort_name(self): if self.stage is None: return "%s.%s" % (self.module, self.funcname) else: return "%s.%d.%s" % (self.module, self.stage, self.funcname)
class RunningCoroutine(object): """Per instance wrapper around an function to turn it into a coroutine Provides the following: coro.join() creates a Trigger that will fire when this coroutine completes coro.kill() will destroy a coroutine instance (and cause any Join triggers to fire """ def __init__(self, inst, parent): if hasattr(inst, "__name__"): self.__name__ = "%s" % inst.__name__ self.log = SimLog("cocotb.coroutine.%s" % self.__name__, id(self)) else: self.log = SimLog("cocotb.coroutine.fail") self._coro = inst self._started = False self._finished = False self._callbacks = [] self._join = _Join(self) self._parent = parent self.__doc__ = parent._func.__doc__ self.module = parent._func.__module__ self.funcname = parent._func.__name__ self.retval = None if not hasattr(self._coro, "send"): self.log.error("%s isn't a valid coroutine! Did you use the yield " "keyword?" % self.funcname) raise CoroutineComplete(callback=self._finished_cb) def __iter__(self): return self def __str__(self): return str(self.__name__) def send(self, value): try: if isinstance(value, ExternalException): self.log.debug("Injecting ExternalException(%s)" % (repr(value))) return self._coro.throw(value.exception) self._started = True return self._coro.send(value) except TestComplete as e: if isinstance(e, TestFailure): self.log.warning(str(e)) raise except ExternalException as e: self.retval = e self._finished = True raise CoroutineComplete(callback=self._finished_cb) except ReturnValue as e: self.retval = e.retval self._finished = True raise CoroutineComplete(callback=self._finished_cb) except StopIteration as e: self._finished = True self.retval = getattr(e, 'value', None) # for python >=3.3 raise CoroutineComplete(callback=self._finished_cb) except Exception as e: self._finished = True raise raise_error(self, "Send raised exception: %s" % (str(e))) def throw(self, exc): return self._coro.throw(exc) def close(self): return self._coro.close() def kill(self): """Kill a coroutine""" self.log.debug("kill() called on coroutine") cocotb.scheduler.unschedule(self) def _finished_cb(self): """Called when the coroutine completes. Allows us to mark the coroutine as finished so that boolean testing works. Also call any callbacks, usually the result of coroutine.join()""" self._finished = True def join(self): """Return a trigger that will fire when the wrapped coroutine exits""" if self._finished: return NullTrigger() else: return self._join def has_started(self): return self._started def __nonzero__(self): """Provide boolean testing if the coroutine has finished return false otherwise return true""" return not self._finished
# NB this cheekily ensures a singleton since we're replacing the reference # so that cocotb.scheduler gives you the singleton instance and not the # scheduler package # GPI logging instance # For autodocumentation don't need the extension modules if "SPHINX_BUILD" not in os.environ: import simulator logging.basicConfig() logging.setLoggerClass(SimBaseLog) log = SimLog('cocotb') level = os.getenv("COCOTB_LOG_LEVEL", "INFO") try: _default_log = getattr(logging, level) except AttributeError as e: log.error("Unable to set loging level to %s" % level) _default_log = logging.INFO log.setLevel(_default_log) loggpi = SimLog('cocotb.gpi') # Notify GPI of log level simulator.log_level(_default_log) scheduler = Scheduler() regression = None plusargs = {} # To save typing provide an alias to scheduler.add fork = scheduler.add
class Scheduler(object): """ 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. 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() _next_timestep = _NextTimeStep() _readwrite = _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._terminate = False self._test_result = None self._entrypoint = None # Select the appropriate scheduling algorithm for this simulator self.advance = self.default_scheduling_algorithm 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") _profile.enable() 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 regresssion object") cocotb.regression.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() if _profiling: _profile.disable() def react(self, trigger, depth=0): """ React called when a trigger fires. We find any coroutines that are waiting on the particular trigger and schedule them. """ if _profiling and not depth: _profile.enable() # 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() if _profiling: _profile.disable() 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) if _profiling: _profile.disable() return 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)) if _profiling: _profile.disable() return # 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)) # If the coroutine was waiting on multiple triggers we may be able # to unprime the other triggers that didn't fire for coro in scheduling: for pending in self._coro2triggers[coro]: for others in self._trigger2coros[pending]: if others not in scheduling: break else: # if pending is not trigger and pending.primed: # pending.unprime() if pending.primed: pending.unprime() del self._trigger2coros[pending] for coro in scheduling: self.schedule(coro, trigger=trigger) if _debug: self.log.debug("Scheduled coroutine %s" % (coro.__name__)) while self._pending_triggers: if _debug: self.log.debug("Scheduling pending trigger %s" % (str(self._pending_triggers[0]))) self.react(self._pending_triggers.pop(0), depth=depth + 1) # We only advance for GPI triggers if not depth and isinstance(trigger, GPITrigger): self.advance() if _debug: self.log.debug("All coroutines scheduled, handing control back" " to simulator") if _profiling: _profile.disable() return 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._coro2triggers[coro] if coro._join in self._trigger2coros: self._pending_triggers.append(coro._join) # Remove references to allow GC to clean up del coro._join def save_write(self, handle, value): if self._mode == Scheduler._MODE_READONLY: raise Exception( "Write to object {} 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 add(self, coroutine): """ Add a new coroutine. Just a wrapper around self.schedule which provides some debug and useful error mesages 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 hasattr(trigger, "pass_retval"): sendval = trigger.retval if _debug: coroutine.log.debug("Scheduling with ReturnValue(%s)" % (repr(sendval))) else: sendval = trigger if _debug: coroutine.log.debug("Scheduling with %s" % str(trigger)) try: result = coroutine.send(sendval) 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 co-routine 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 if isinstance(result, cocotb.decorators.RunningCoroutine): if _debug: self.log.debug("Scheduling nested co-routine: %s" % result.__name__) self.queue(result) new_trigger = result.join() self._coroutine_yielded(coroutine, [new_trigger]) elif isinstance(result, Trigger): self._coroutine_yielded(coroutine, [result]) elif (isinstance(result, list) and not [t for t in result if not isinstance(t, Trigger)]): 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) # 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 regresssion object") cocotb.regression.handle_result(test_result) def cleanup(self): """ Clear up all our state Unprime all pending triggers and kill off any coroutines """ for trigger, waiting in self._trigger2coros.items(): for coro in waiting: if _debug: self.log.debug("Killing %s" % str(coro)) coro.kill()
class Scheduler(object): """ 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. 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() _next_timestep = _NextTimeStep() _readwrite = _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._terminate = False self._test_result = None self._entrypoint = None # Select the appropriate scheduling algorithm for this simulator self.advance = self.default_scheduling_algorithm 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") _profile.enable() 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 regresssion object") cocotb.regression.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() if _profiling: _profile.disable() def react(self, trigger, depth=0): """ React called when a trigger fires. We find any coroutines that are waiting on the particular trigger and schedule them. """ if _profiling and not depth: _profile.enable() # 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() if _profiling: _profile.disable() 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) if _profiling: _profile.disable() return 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)) if _profiling: _profile.disable() return # 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)) # If the coroutine was waiting on multiple triggers we may be able # to unprime the other triggers that didn't fire for coro in scheduling: for pending in self._coro2triggers[coro]: for others in self._trigger2coros[pending]: if others not in scheduling: break else: # if pending is not trigger and pending.primed: # pending.unprime() if pending.primed: pending.unprime() del self._trigger2coros[pending] for coro in scheduling: self.schedule(coro, trigger=trigger) if _debug: self.log.debug("Scheduled coroutine %s" % (coro.__name__)) while self._pending_triggers: if _debug: self.log.debug("Scheduling pending trigger %s" % (str(self._pending_triggers[0]))) self.react(self._pending_triggers.pop(0), depth=depth + 1) # We only advance for GPI triggers if not depth and isinstance(trigger, GPITrigger): self.advance() if _debug: self.log.debug("All coroutines scheduled, handing control back" " to simulator") if _profiling: _profile.disable() return 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._coro2triggers[coro] if coro._join in self._trigger2coros: self._pending_triggers.append(coro._join) # Remove references to allow GC to clean up del coro._join def save_write(self, handle, value): 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 add(self, coroutine): """ Add a new coroutine. Just a wrapper around self.schedule which provides some debug and useful error mesages 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 hasattr(trigger, "pass_retval"): sendval = trigger.retval if _debug: coroutine.log.debug("Scheduling with ReturnValue(%s)" % (repr(sendval))) else: sendval = trigger if _debug: coroutine.log.debug("Scheduling with %s" % str(trigger)) try: result = coroutine.send(sendval) 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 co-routine 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 if isinstance(result, cocotb.decorators.RunningCoroutine): if _debug: self.log.debug("Scheduling nested co-routine: %s" % result.__name__) self.queue(result) new_trigger = result.join() self._coroutine_yielded(coroutine, [new_trigger]) elif isinstance(result, Trigger): self._coroutine_yielded(coroutine, [result]) elif (isinstance(result, list) and not [t for t in result if not isinstance(t, Trigger)]): 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) # 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 regresssion object") cocotb.regression.handle_result(test_result) def cleanup(self): """ Clear up all our state Unprime all pending triggers and kill off any coroutines """ for trigger, waiting in self._trigger2coros.items(): for coro in waiting: if _debug: self.log.debug("Killing %s" % str(coro)) coro.kill()
class TestFactory(object): """Used to automatically generate tests. 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`` and ``gen_b``: >>> tf = TestFactory(run_test) >>> tf.add_option('data_in', [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 idles * ``gen_a`` with no backpressure and ``random_idles`` * ``gen_a`` with ``random_backpressure`` and no idles * ``gen_a`` with ``random_backpressure`` and ``random_idles`` * ``gen_b`` with no backpressure and no idles * ``gen_b`` with no backpressure and ``random_idles`` * ``gen_b`` with ``random_backpressure`` and no idles * ``gen_b`` with ``random_backpressure`` and ``random_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. """ def __init__(self, test_function, *args, **kwargs): """ Args: test_function (function): the function that executes a test. Must take 'dut' as the first argument. *args: Remaining args 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 kwargs 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. """ if not isinstance(test_function, cocotb.coroutine): raise TypeError("TestFactory requires a cocotb coroutine") self.test_function = test_function self.name = self.test_function._func.__name__ self.args = args self.kwargs_constant = kwargs self.kwargs = {} self.log = SimLog("cocotb.regression") def add_option(self, name, optionlist): """Add a named option to the test. Args: name (str): Name of the option. Passed to test as a keyword argument. optionlist (list): A list of possible options for this test knob. """ self.kwargs[name] = optionlist def generate_tests(self, prefix="", postfix=""): """ Generates 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. Args: prefix (str): Text string to append to start of ``test_function`` name when naming generated test cases. This allows reuse of a single ``test_function`` with multiple :class:`TestFactories <.TestFactory>` 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 single ``test_function`` with multiple :class:`TestFactories <.TestFactory>` without name clashes. """ frm = inspect.stack()[1] mod = inspect.getmodule(frm[0]) d = self.kwargs for index, testoptions in enumerate(( dict(zip(d, v)) for v in product(*d.values()) )): name = "%s%s%s_%03d" % (prefix, self.name, postfix, index + 1) doc = "Automatically generated test\n\n" for optname, optvalue in testoptions.items(): if callable(optvalue): if not optvalue.__doc__: desc = "No docstring supplied" else: desc = optvalue.__doc__.split('\n')[0] doc += "\t%s: %s (%s)\n" % (optname, optvalue.__name__, desc) else: doc += "\t%s: %s\n" % (optname, repr(optvalue)) self.log.debug("Adding generated test \"%s\" to module \"%s\"" % (name, mod.__name__)) kwargs = {} kwargs.update(self.kwargs_constant) kwargs.update(testoptions) if hasattr(mod, name): self.log.error("Overwriting %s in module %s. " "This causes a previously defined testcase " "not to be run. Consider setting/changing " "name_postfix" % (name, mod)) setattr(mod, name, _create_test(self.test_function, name, doc, mod, *self.args, **kwargs))
class RunningCoroutine(object): """Per instance wrapper around an function to turn it into a coroutine Provides the following: coro.join() creates a Trigger that will fire when this coroutine completes coro.kill() will destroy a coroutine instance (and cause any Join triggers to fire """ def __init__(self, inst, parent): if hasattr(inst, "__name__"): self.__name__ = "%s" % inst.__name__ self.log = SimLog("cocotb.coroutine.%s" % self.__name__, id(self)) else: self.log = SimLog("cocotb.coroutine.fail") self._coro = inst self._started = False self._finished = False self._callbacks = [] self._join = _Join(self) self._parent = parent self.__doc__ = parent._func.__doc__ self.module = parent._func.__module__ self.funcname = parent._func.__name__ self.retval = None if not hasattr(self._coro, "send"): self.log.error("%s isn't a valid coroutine! Did you use the yield " "keyword?" % self.funcname) raise CoroutineComplete(callback=self._finished_cb) def __iter__(self): return self def __str__(self): return str(self.__name__) def send(self, value): try: if isinstance(value, ExternalException): self.log.debug("Injecting ExternalException(%s)" % (repr(value))) return self._coro.throw(value.exception) self._started = True return self._coro.send(value) except TestComplete as e: if isinstance(e, TestFailure): self.log.warning(str(e)) raise except ExternalException as e: self.retval = e self._finished = True raise CoroutineComplete(callback=self._finished_cb) except ReturnValue as e: self.retval = e.retval self._finished = True raise CoroutineComplete(callback=self._finished_cb) except StopIteration as e: self._finished = True self.retval = getattr(e, 'value', None) # for python >=3.3 raise CoroutineComplete(callback=self._finished_cb) except Exception as e: self._finished = True raise raise_error(self, "Send raised exception: %s" % (str(e))) def throw(self, exc): return self._coro.throw(exc) def close(self): return self._coro.close() def kill(self): """Kill a coroutine""" self.log.debug("kill() called on coroutine") cocotb.scheduler.unschedule(self) def _finished_cb(self): """Called when the coroutine completes. Allows us to mark the coroutine as finished so that boolean testing works. Also call any callbacks, usually the result of coroutine.join()""" self._finished = True def join(self): """Return a trigger that will fire when the wrapped coroutine exits""" if self._finished: return NullTrigger() else: return self._join def has_started(self): return self._started def __nonzero__(self): """Provide boolean testing if the coroutine has finished return false otherwise return true""" return not self._finished def sort_name(self): if self.stage is None: return "%s.%s" % (self.module, self.funcname) else: return "%s.%d.%s" % (self.module, self.stage, self.funcname)
class RegressionManager(object): """Encapsulates all regression capability into a single place""" def __init__(self, dut, modules, tests=None): """ Args: modules (list): A list of python module names to run Kwargs """ self._queue = [] self._dut = dut self._modules = modules self._functions = tests self._running_test = None self.log = SimLog("cocotb.regression") def initialise(self): self.ntests = 0 self.count = 1 self.skipped = 0 self.failures = 0 self.xunit = XUnitReporter() self.xunit.add_testsuite(name="all", tests=repr(self.ntests), package="all") # Auto discovery for module_name in self._modules: module = _my_import(module_name) if self._functions: # Specific functions specified, don't auto discover for test in self._functions.rsplit(','): if not hasattr(module, test): raise AttributeError("Test %s doesn't exist in %s" % (test, module_name)) self._queue.append(getattr(module, test)(self._dut)) self.ntests += 1 break for thing in vars(module).values(): if hasattr(thing, "im_test"): try: test = thing(self._dut) skip = test.skip except TestError: skip = True self.log.warning("Failed to initialise test %s" % thing.name) if skip: self.log.info("Skipping test %s" % thing.name) self.xunit.add_testcase(name=thing.name, classname=module_name, time="0.0") self.xunit.add_skipped() self.skipped += 1 else: self._queue.append(test) self.ntests += 1 self._queue.sort(key=lambda test: "%s.%s" % (test.module, test.funcname)) for valid_tests in self._queue: self.log.info("Found test %s.%s" % (valid_tests.module, valid_tests.funcname)) def tear_down(self): """It's the end of the world as we know it""" if self.failures: self.log.error("Failed %d out of %d tests (%d skipped)" % (self.failures, self.count -1, self.skipped)) else: self.log.info("Passed %d tests (%d skipped)" % (self.count-1, self.skipped)) self.log.info("Shutting down...") self.xunit.write() simulator.stop_simulator() def next_test(self): """Get the next test to run""" if not self._queue: return None return self._queue.pop(0) def handle_result(self, result): """Handle a test result Dumps result to XML and schedules the next test (if any) Args: result (TestComplete exception) """ self.xunit.add_testcase(name =self._running_test.funcname, classname=self._running_test.module, time=repr(time.time() - self._running_test.start_time) ) if isinstance(result, TestSuccess) and not self._running_test.expect_fail and not self._running_test.expect_error: self.log.info("Test Passed: %s" % self._running_test.funcname) elif isinstance(result, TestFailure) and self._running_test.expect_fail: self.log.info("Test failed as expected: %s (result was %s)" % ( self._running_test.funcname, result.__class__.__name__)) elif isinstance(result, TestSuccess) and self._running_test.expect_error: self.log.error("Test passed but we expected an error: %s (result was %s)" % ( self._running_test.funcname, result.__class__.__name__)) self.xunit.add_failure(stdout=repr(str(result)), stderr="\n".join(self._running_test.error_messages)) self.failures += 1 elif isinstance(result, TestSuccess): self.log.error("Test passed but we expected a failure: %s (result was %s)" % ( self._running_test.funcname, result.__class__.__name__)) self.xunit.add_failure(stdout=repr(str(result)), stderr="\n".join(self._running_test.error_messages)) self.failures += 1 elif isinstance(result, TestError) and self._running_test.expect_error: self.log.info("Test errored as expected: %s (result was %s)" % ( self._running_test.funcname, result.__class__.__name__)) elif isinstance(result, SimFailure): if self._running_test.expect_error: self.log.info("Test errored as expected: %s (result was %s)" % ( self._running_test.funcname, result.__class__.__name__)) else: self.log.error("Test error has lead to simulator shuttting us down") self.failures += 1 self.tear_down() return else: self.log.error("Test Failed: %s (result was %s)" % ( self._running_test.funcname, result.__class__.__name__)) self.xunit.add_failure(stdout=repr(str(result)), stderr="\n".join(self._running_test.error_messages)) self.failures += 1 self.execute() def execute(self): self._running_test = cocotb.regression.next_test() if self._running_test: # Want this to stand out a little bit self.log.info("%sRunning test %d/%d:%s %s" % ( ANSI.BLUE_BG +ANSI.BLACK_FG, self.count, self.ntests, ANSI.DEFAULT_FG + ANSI.DEFAULT_BG, self._running_test.funcname)) if self.count is 1: test = cocotb.scheduler.add(self._running_test) else: test = cocotb.scheduler.new_test(self._running_test) self.count+=1 else: self.tear_down()
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 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.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, depth=0): """React called when a trigger fires. We find any coroutines that are waiting on the particular trigger and schedule them. """ if _profiling and not depth: 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 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)) return # 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__)) if not depth: # 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() while self._pending_triggers: if _debug: self.log.debug("Scheduling pending trigger %s" % (str(self._pending_triggers[0]))) self.react(self._pending_triggers.pop(0), depth=depth + 1) # We only advance for GPI triggers if not depth and isinstance(trigger, GPITrigger): 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.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 RegressionManager(object): """Encapsulates all regression capability into a single place""" def __init__(self, root_name, modules, tests=None, seed=None, hooks=[]): """ Args: root_name (str): The name of the root handle. modules (list): A list of Python module names to run. tests (list, optional): A list of tests to run. Defaults to ``None``, meaning all discovered tests will be run. seed (int, optional): The seed for the random number generator to use. Defaults to ``None``. hooks (list, optional): A list of hook modules to import. Defaults to the empty list. """ self._queue = [] self._root_name = root_name self._dut = None self._modules = modules self._functions = tests self._running_test = None self._cov = None self.log = SimLog("cocotb.regression") self._seed = seed self._hooks = hooks def initialise(self): self.start_time = time.time() self.test_results = [] self.ntests = 0 self.count = 1 self.skipped = 0 self.failures = 0 # Setup XUnit ################### results_filename = os.getenv('COCOTB_RESULTS_FILE', "results.xml") suite_name = os.getenv('RESULT_TESTSUITE', "all") package_name = os.getenv('RESULT_TESTPACKAGE', "all") self.xunit = XUnitReporter(filename=results_filename) self.xunit.add_testsuite(name=suite_name, tests=repr(self.ntests), package=package_name) if (self._seed is not None): self.xunit.add_property(name="random_seed", value=("%d" % self._seed)) # Setup Coverage #################### if coverage is not None: self.log.info("Enabling coverage collection of Python code") self._cov = coverage.coverage(branch=True, omit=["*cocotb*"]) self._cov.start() # Setup DUT object ####################### handle = simulator.get_root_handle(self._root_name) self._dut = cocotb.handle.SimHandle(handle) if handle else None if self._dut is None: raise AttributeError("Can not find Root Handle (%s)" % self._root_name) # Test Discovery #################### for module_name in self._modules: try: self.log.debug("Python Path: " + ",".join(sys.path)) self.log.debug("PWD: " + os.getcwd()) module = _my_import(module_name) except Exception as E: self.log.critical("Failed to import module %s: %s", module_name, E) self.log.info("MODULE variable was \"%s\"", ".".join(self._modules)) self.log.info("Traceback: ") self.log.info(traceback.format_exc()) raise if self._functions: # Specific functions specified, don't auto-discover for test in self._functions.rsplit(','): try: _test = getattr(module, test) except AttributeError: self.log.error( "Requested test %s wasn't found in module %s", test, module_name) err = AttributeError("Test %s doesn't exist in %s" % (test, module_name)) _py_compat.raise_from(err, None) # discard nested traceback if not hasattr(_test, "im_test"): self.log.error( "Requested %s from module %s isn't a cocotb.test decorated coroutine", test, module_name) raise ImportError("Failed to find requested test %s" % test) self._init_test(_test) # only look in first module for all functions and don't complain if all functions are not found break # auto-discover for thing in vars(module).values(): if hasattr(thing, "im_test"): self._init_test(thing) self._queue.sort(key=lambda test: (test.stage, test._id)) for valid_tests in self._queue: self.log.info("Found test %s.%s" % (valid_tests.module, valid_tests.funcname)) # Process Hooks ################### for module_name in self._hooks: self.log.info("Loading hook from module '" + module_name + "'") module = _my_import(module_name) for thing in vars(module).values(): if hasattr(thing, "im_hook"): try: test = thing(self._dut) except Exception: self.log.warning("Failed to initialize hook %s" % thing.name, exc_info=True) else: cocotb.scheduler.add(test) def tear_down(self): # fail remaining tests while True: test = self.next_test() if test is None: break self.xunit.add_testcase(name=test.funcname, classname=test.module, time=repr(0), sim_time_ns=repr(0), ratio_time=repr(0)) result_pass, _ = self._score_test( test, cocotb.outcomes.Error(SimFailure())) self._store_test_result(test.__module__, test.__name__, result_pass, 0, 0, 0) if not result_pass: self.xunit.add_failure() self.failures += 1 # Write out final log messages if self.failures: self.log.error("Failed %d out of %d tests (%d skipped)" % (self.failures, self.count - 1, self.skipped)) else: self.log.info("Passed %d tests (%d skipped)" % (self.count - 1, self.skipped)) if len(self.test_results) > 0: self._log_test_summary() self._log_sim_summary() self.log.info("Shutting down...") # Generate output reports self.xunit.write() if self._cov: self._cov.stop() self.log.info("Writing coverage data") self._cov.save() self._cov.html_report() # Setup simulator finalization simulator.stop_simulator() def next_test(self): """Get the next test to run""" if not self._queue: return None return self._queue.pop(0) def handle_result(self, test): """Handle a test completing. Dump result to XML and schedule the next test (if any). Entered by the scheduler. Args: test: The test that completed """ assert test is self._running_test real_time = time.time() - test.start_time sim_time_ns = get_sim_time('ns') - test.start_sim_time ratio_time = self._safe_divide(sim_time_ns, real_time) self.xunit.add_testcase(name=test.funcname, classname=test.module, time=repr(real_time), sim_time_ns=repr(sim_time_ns), ratio_time=repr(ratio_time)) # score test result_pass, sim_failed = self._score_test(test, test._outcome) # stop capturing log output cocotb.log.removeHandler(test.handler) # Save results self._store_test_result(test.__module__, test.__name__, result_pass, sim_time_ns, real_time, ratio_time) if not result_pass: self.xunit.add_failure() self.failures += 1 # Fail if required if sim_failed: self.tear_down() return self.execute() def _init_test(self, test_func): """ Initializes a test. Records outcome if the initialization fails. Records skip if the test is skipped. Saves the initialized test if it successfully initializes. """ test_init_outcome = cocotb.outcomes.capture(test_func, self._dut) if isinstance(test_init_outcome, cocotb.outcomes.Error): self.log.error("Failed to initialize test %s" % test_func.name, exc_info=True) self.xunit.add_testcase(name=test_func.name, classname=test_func.__module__, time="0.0", sim_time_ns="0.0", ratio_time="0.0") result_pass, sim_failed = self._score_test(test_func, test_init_outcome) # Save results self._store_test_result(test_func.__module__, test_func.__name__, result_pass, 0.0, 0.0, 0.0) if not result_pass: self.xunit.add_failure() self.failures += 1 # Fail if required if sim_failed: self.tear_down() raise SimFailure( "Test initialization caused a simulator failure. Shutting down." ) else: test = test_init_outcome.get() if test.skip: self.log.info("Skipping test %s" % test_func.name) self.xunit.add_testcase(name=test_func.name, classname=test.module, time="0.0", sim_time_ns="0.0", ratio_time="0.0") self.xunit.add_skipped() self.skipped += 1 self._store_test_result(test.module, test_func.name, None, 0.0, 0.0, 0.0) else: self._queue.append(test) self.ntests += 1 def _score_test(self, test, outcome): """ Given a test and the test's outcome, determine if the test met expectations and log pertinent information """ # Helper for logging result def _result_was(): result_was = ("{} (result was {})".format( test.__name__, result.__class__.__name__)) return result_was # scoring outcomes result_pass = True sim_failed = False try: outcome.get() except Exception as e: result = remove_traceback_frames(e, ['_score_test', 'get']) else: result = TestSuccess() if (isinstance(result, TestSuccess) and not test.expect_fail and not test.expect_error): self.log.info("Test Passed: %s" % test.__name__) elif (isinstance(result, AssertionError) and test.expect_fail): self.log.info("Test failed as expected: " + _result_was()) elif (isinstance(result, TestSuccess) and test.expect_error): self.log.error("Test passed but we expected an error: " + _result_was()) result_pass = False elif isinstance(result, TestSuccess): self.log.error("Test passed but we expected a failure: " + _result_was()) result_pass = False elif isinstance(result, SimFailure): if isinstance(result, test.expect_error): self.log.info("Test errored as expected: " + _result_was()) else: self.log.error( "Test error has lead to simulator shutting us " "down", exc_info=result) result_pass = False # whether we expected it or not, the simulation has failed unrecoverably sim_failed = True elif test.expect_error: if isinstance(result, test.expect_error): self.log.info("Test errored as expected: " + _result_was()) else: self.log.error("Test errored with unexpected type: " + _result_was(), exc_info=result) result_pass = False else: self.log.error("Test Failed: " + _result_was(), exc_info=result) result_pass = False if _pdb_on_exception: pdb.post_mortem(result.__traceback__) return result_pass, sim_failed def execute(self): self._running_test = cocotb.regression_manager.next_test() if self._running_test: start = '' end = '' if want_color_output(): start = ANSI.COLOR_TEST end = ANSI.COLOR_DEFAULT # Want this to stand out a little bit self.log.info("%sRunning test %d/%d:%s %s" % (start, self.count, self.ntests, end, self._running_test.funcname)) # start capturing log output cocotb.log.addHandler(self._running_test.handler) cocotb.scheduler.add_test(self._running_test) self.count += 1 else: self.tear_down() def _log_test_summary(self): TEST_FIELD = 'TEST' RESULT_FIELD = 'PASS/FAIL' SIM_FIELD = 'SIM TIME(NS)' REAL_FIELD = 'REAL TIME(S)' RATIO_FIELD = 'RATIO(NS/S)' TEST_FIELD_LEN = max( len(TEST_FIELD), len(max([x['test'] for x in self.test_results], key=len))) RESULT_FIELD_LEN = len(RESULT_FIELD) SIM_FIELD_LEN = len(SIM_FIELD) REAL_FIELD_LEN = len(REAL_FIELD) RATIO_FIELD_LEN = len(RATIO_FIELD) LINE_LEN = 3 + TEST_FIELD_LEN + 2 + RESULT_FIELD_LEN + 2 + SIM_FIELD_LEN + 2 + REAL_FIELD_LEN + 2 + RATIO_FIELD_LEN + 3 LINE_SEP = "*" * LINE_LEN + "\n" summary = "" summary += LINE_SEP summary += "** {a:<{a_len}} {b:^{b_len}} {c:>{c_len}} {d:>{d_len}} {e:>{e_len}} **\n".format( a=TEST_FIELD, a_len=TEST_FIELD_LEN, b=RESULT_FIELD, b_len=RESULT_FIELD_LEN, c=SIM_FIELD, c_len=SIM_FIELD_LEN, d=REAL_FIELD, d_len=REAL_FIELD_LEN, e=RATIO_FIELD, e_len=RATIO_FIELD_LEN) summary += LINE_SEP for result in self.test_results: hilite = '' if result['pass'] is None: pass_fail_str = "N/A" elif result['pass']: pass_fail_str = "PASS" else: pass_fail_str = "FAIL" if want_color_output(): hilite = ANSI.COLOR_HILITE_SUMMARY summary += "{start}** {a:<{a_len}} {b:^{b_len}} {c:>{c_len}.2f} {d:>{d_len}.2f} {e:>{e_len}.2f} **\n".format( a=result['test'], a_len=TEST_FIELD_LEN, b=pass_fail_str, b_len=RESULT_FIELD_LEN, c=result['sim'], c_len=SIM_FIELD_LEN - 1, d=result['real'], d_len=REAL_FIELD_LEN - 1, e=result['ratio'], e_len=RATIO_FIELD_LEN - 1, start=hilite) summary += LINE_SEP self.log.info(summary) def _log_sim_summary(self): real_time = time.time() - self.start_time sim_time_ns = get_sim_time('ns') ratio_time = self._safe_divide(sim_time_ns, real_time) summary = "" summary += "*************************************************************************************\n" summary += "** ERRORS : {0:<39}**\n".format( self.failures) summary += "*************************************************************************************\n" summary += "** SIM TIME : {0:<39}**\n".format( '{0:.2f} NS'.format(sim_time_ns)) summary += "** REAL TIME : {0:<39}**\n".format( '{0:.2f} S'.format(real_time)) summary += "** SIM / REAL TIME : {0:<39}**\n".format( '{0:.2f} NS/S'.format(ratio_time)) summary += "*************************************************************************************\n" self.log.info(summary) @staticmethod def _safe_divide(a, b): try: return a / b except ZeroDivisionError: if a == 0: return float('nan') else: return float('inf') def _store_test_result(self, module_name, test_name, result_pass, sim_time, real_time, ratio): result = { 'test': '.'.join([module_name, test_name]), 'pass': result_pass, 'sim': sim_time, 'real': real_time, 'ratio': ratio } self.test_results.append(result)
class RunningCoroutine(object): """Per instance wrapper around an function to turn it into a coroutine. Provides the following: coro.join() creates a Trigger that will fire when this coroutine completes. coro.kill() will destroy a coroutine instance (and cause any Join triggers to fire. """ def __init__(self, inst, parent): if hasattr(inst, "__name__"): self.__name__ = "%s" % inst.__name__ self.log = SimLog("cocotb.coroutine.%s" % self.__name__, id(self)) else: self.log = SimLog("cocotb.coroutine.fail") self._coro = inst self._started = False self._callbacks = [] self._parent = parent self.__doc__ = parent._func.__doc__ self.module = parent._func.__module__ self.funcname = parent._func.__name__ self._outcome = None if not hasattr(self._coro, "send"): self.log.error("%s isn't a valid coroutine! Did you use the yield " "keyword?" % self.funcname) raise CoroutineComplete() @property def retval(self): if self._outcome is None: raise RuntimeError("coroutine is not complete") return self._outcome.get() @property def _finished(self): return self._outcome is not None def __iter__(self): return self def __str__(self): return str(self.__name__) def _advance(self, outcome): """ Advance to the next yield in this coroutine :param outcome: The `outcomes.Outcome` object to resume with. :returns: The object yielded from the coroutine If the coroutine returns or throws an error, self._outcome is set, and this throws `CoroutineComplete`. """ try: self._started = True return outcome.send(self._coro) except ReturnValue as e: self._outcome = outcomes.Value(e.retval) raise CoroutineComplete() except StopIteration as e: retval = getattr(e, 'value', None) # for python >=3.3 self._outcome = outcomes.Value(retval) raise CoroutineComplete() except BaseException as e: self._outcome = outcomes.Error(e) raise CoroutineComplete() def send(self, value): return self._coro.send(value) def throw(self, exc): return self._coro.throw(exc) def close(self): return self._coro.close() def kill(self): """Kill a coroutine.""" self.log.debug("kill() called on coroutine") # todo: probably better to throw an exception for anyone waiting on the coroutine self._outcome = outcomes.Value(None) cocotb.scheduler.unschedule(self) def join(self): """Return a trigger that will fire when the wrapped coroutine exits.""" return Join(self) def has_started(self): return self._started def __nonzero__(self): """Provide boolean testing if the coroutine has finished return false otherwise return true""" return not self._finished __bool__ = __nonzero__ def sort_name(self): if self.stage is None: return "%s.%s" % (self.module, self.funcname) else: return "%s.%d.%s" % (self.module, self.stage, self.funcname)
class RegressionManager(object): """Encapsulates all regression capability into a single place""" def __init__(self, root_name, modules, tests=None): """ Args: modules (list): A list of python module names to run Kwargs """ self._queue = [] self._root_name = root_name self._dut = None self._modules = modules self._functions = tests self._running_test = None self._cov = None self.log = SimLog("cocotb.regression") def initialise(self): self.ntests = 0 self.count = 1 self.skipped = 0 self.failures = 0 self.xunit = XUnitReporter() self.xunit.add_testsuite(name="all", tests=repr(self.ntests), package="all") if coverage is not None: self.log.info("Enabling coverage collection of Python code") self._cov = coverage.coverage(branch=True, omit=["*cocotb*"]) self._cov.start() self._dut = cocotb.handle.SimHandle( simulator.get_root_handle(self._root_name)) if self._dut is None: raise AttributeError("Can not find Root Handle (%s)" % root_name) # Auto discovery for module_name in self._modules: module = _my_import(module_name) if self._functions: # Specific functions specified, don't auto discover for test in self._functions.rsplit(','): if not hasattr(module, test): raise AttributeError("Test %s doesn't exist in %s" % (test, module_name)) self._queue.append(getattr(module, test)(self._dut)) self.ntests += 1 break for thing in vars(module).values(): if hasattr(thing, "im_test"): try: test = thing(self._dut) skip = test.skip except TestError: skip = True self.log.warning("Failed to initialise test %s" % thing.name) if skip: self.log.info("Skipping test %s" % thing.name) self.xunit.add_testcase(name=thing.name, classname=module_name, time="0.0") self.xunit.add_skipped() self.skipped += 1 else: self._queue.append(test) self.ntests += 1 self._queue.sort( key=lambda test: "%s.%s" % (test.module, test.funcname)) for valid_tests in self._queue: self.log.info("Found test %s.%s" % (valid_tests.module, valid_tests.funcname)) def tear_down(self): """It's the end of the world as we know it""" if self.failures: self.log.error("Failed %d out of %d tests (%d skipped)" % (self.failures, self.count - 1, self.skipped)) else: self.log.info("Passed %d tests (%d skipped)" % (self.count - 1, self.skipped)) if self._cov: self._cov.stop() self.log.info("Writing coverage data") self._cov.save() self._cov.html_report() self.log.info("Shutting down...") self.xunit.write() simulator.stop_simulator() def next_test(self): """Get the next test to run""" if not self._queue: return None return self._queue.pop(0) def handle_result(self, result): """Handle a test result Dumps result to XML and schedules the next test (if any) Args: result (TestComplete exception) """ self.xunit.add_testcase(name=self._running_test.funcname, classname=self._running_test.module, time=repr(time.time() - self._running_test.start_time)) if isinstance( result, TestSuccess ) and not self._running_test.expect_fail and not self._running_test.expect_error: self.log.info("Test Passed: %s" % self._running_test.funcname) elif isinstance(result, TestFailure) and self._running_test.expect_fail: self.log.info( "Test failed as expected: %s (result was %s)" % (self._running_test.funcname, result.__class__.__name__)) elif isinstance(result, TestSuccess) and self._running_test.expect_error: self.log.error( "Test passed but we expected an error: %s (result was %s)" % (self._running_test.funcname, result.__class__.__name__)) self.xunit.add_failure(stdout=repr(str(result)), stderr="\n".join( self._running_test.error_messages)) self.failures += 1 elif isinstance(result, TestSuccess): self.log.error( "Test passed but we expected a failure: %s (result was %s)" % (self._running_test.funcname, result.__class__.__name__)) self.xunit.add_failure(stdout=repr(str(result)), stderr="\n".join( self._running_test.error_messages)) self.failures += 1 elif isinstance(result, TestError) and self._running_test.expect_error: self.log.info( "Test errored as expected: %s (result was %s)" % (self._running_test.funcname, result.__class__.__name__)) elif isinstance(result, SimFailure): if self._running_test.expect_error: self.log.info( "Test errored as expected: %s (result was %s)" % (self._running_test.funcname, result.__class__.__name__)) else: self.log.error( "Test error has lead to simulator shuttting us down") self.failures += 1 self.tear_down() return else: self.log.error( "Test Failed: %s (result was %s)" % (self._running_test.funcname, result.__class__.__name__)) self.xunit.add_failure(stdout=repr(str(result)), stderr="\n".join( self._running_test.error_messages)) self.failures += 1 self.execute() def execute(self): self._running_test = cocotb.regression.next_test() if self._running_test: # Want this to stand out a little bit self.log.info("%sRunning test %d/%d:%s %s" % (ANSI.BLUE_BG + ANSI.BLACK_FG, self.count, self.ntests, ANSI.DEFAULT_FG + ANSI.DEFAULT_BG, self._running_test.funcname)) if self.count is 1: test = cocotb.scheduler.add(self._running_test) else: test = cocotb.scheduler.new_test(self._running_test) self.count += 1 else: self.tear_down()
class RunningCoroutine(object): """Per instance wrapper around an function to turn it into a coroutine. Provides the following: coro.join() creates a Trigger that will fire when this coroutine completes. coro.kill() will destroy a coroutine instance (and cause any Join triggers to fire. """ def __init__(self, inst, parent): if hasattr(inst, "__name__"): self.__name__ = "%s" % inst.__name__ self.log = SimLog("cocotb.coroutine.%s" % self.__name__, id(self)) else: self.log = SimLog("cocotb.coroutine.fail") if sys.version_info[:2] >= (3, 5) and inspect.iscoroutine(inst): self._natively_awaitable = True self._coro = inst.__await__() else: self._natively_awaitable = False self._coro = inst self._started = False self._callbacks = [] self._parent = parent self.__doc__ = parent._func.__doc__ self.module = parent._func.__module__ self.funcname = parent._func.__name__ self._outcome = None if not hasattr(self._coro, "send"): self.log.error("%s isn't a valid coroutine! Did you use the yield " "keyword?" % self.funcname) raise CoroutineComplete() @property def retval(self): if self._outcome is None: raise RuntimeError("coroutine is not complete") return self._outcome.get() @property def _finished(self): return self._outcome is not None def __iter__(self): return self def __str__(self): return str(self.__name__) def _advance(self, outcome): """ Advance to the next yield in this coroutine :param outcome: The `outcomes.Outcome` object to resume with. :returns: The object yielded from the coroutine If the coroutine returns or throws an error, self._outcome is set, and this throws `CoroutineComplete`. """ try: self._started = True return outcome.send(self._coro) except ReturnValue as e: self._outcome = outcomes.Value(e.retval) raise CoroutineComplete() except StopIteration as e: retval = getattr(e, 'value', None) # for python >=3.3 self._outcome = outcomes.Value(retval) raise CoroutineComplete() except BaseException as e: self._outcome = outcomes.Error(e) raise CoroutineComplete() def send(self, value): return self._coro.send(value) def throw(self, exc): return self._coro.throw(exc) def close(self): return self._coro.close() def kill(self): """Kill a coroutine.""" if self._outcome is not None: # already finished, nothing to kill return self.log.debug("kill() called on coroutine") # todo: probably better to throw an exception for anyone waiting on the coroutine self._outcome = outcomes.Value(None) cocotb.scheduler.unschedule(self) def join(self): """Return a trigger that will fire when the wrapped coroutine exits.""" return cocotb.triggers.Join(self) def has_started(self): return self._started def __nonzero__(self): """Provide boolean testing if the coroutine has finished return false otherwise return true""" return not self._finished # Once 2.7 is dropped, this can be run unconditionally if sys.version_info >= (3, 3): exec_(textwrap.dedent(""" def __await__(self): # It's tempting to use `return (yield from self._coro)` here, # which bypasses the scheduler. Unfortunately, this means that # we can't keep track of the result or state of the coroutine, # things which we expose in our public API. If you want the # efficiency of bypassing the scheduler, remove the `@coroutine` # decorator from your `async` functions. # Hand the coroutine back to the scheduler trampoline. return (yield self) """)) __bool__ = __nonzero__ def sort_name(self): if self.stage is None: return "%s.%s" % (self.module, self.funcname) else: return "%s.%d.%s" % (self.module, self.stage, self.funcname)
class SimHandle(object): def __init__(self, handle): """ Args: _handle [integer] : vpi/vhpi handle to the simulator object """ self._handle = handle # handle used for future simulator transactions self._sub_handles = {} # Dictionary of SimHandle objects created by getattr self._len = None self.name = simulator.get_name_string(self._handle) self.fullname = self.name + '(%s)' % simulator.get_type_string(self._handle) self.log = SimLog('cocotb.' + self.name) self.log.debug("Created!") self._r_edge = _RisingEdge(self) self._f_edge = _FallingEdge(self) def __hash__(self): return self._handle def __str__(self): return "%s @0x%x" % (self.name, self._handle) def __getattr__(self, name): """ Query the simulator for a object with the specified name and cache the result to build a tree """ if name in self._sub_handles: return self._sub_handles[name] new_handle = simulator.get_handle_by_name(self._handle, name) if not new_handle: self._raise_testerror("%s contains no object named %s" % (self.name, name)) self._sub_handles[name] = SimHandle(new_handle) return self._sub_handles[name] def _raise_testerror(self, msg): lastframe = sys._getframe(2) if sys.version_info[0] >= 3: buff = StringIO() traceback.print_stack(lastframe, file=buff) else: buff_bytes = BytesIO() traceback.print_stack(lastframe, file=buff_bytes) buff = StringIO(buff_bytes.getvalue().decode("UTF8")) self.log.error("%s\n%s" % (msg, buff.getvalue())) exception = TestError(msg) exception.stderr.write(buff.getvalue()) buff.close() raise exception def __setattr__(self, name, value): """Provide transparent access to signals""" if not name.startswith('_') and not name in ["name", "fullname", "log", "value"] \ and self.__hasattr__(name): getattr(self, name).setcachedvalue(value) return object.__setattr__(self, name, value) def __hasattr__(self, name): """ Since calling hasattr(handle, "something") will print out a backtrace to the log since usually attempting to access a non-existent member is an error we provide a 'peek function We still add the found handle to our dictionary to prevent leaking handles. """ if name in self._sub_handles: return self._sub_handles[name] new_handle = simulator.get_handle_by_name(self._handle, name) if new_handle: self._sub_handles[name] = SimHandle(new_handle) return new_handle def __getitem__(self, index): if index in self._sub_handles: return self._sub_handles[index] new_handle = simulator.get_handle_by_index(self._handle, index) if not new_handle: self._raise_testerror("%s contains no object at index %d" % (self.name, index)) self._sub_handles[index] = SimHandle(new_handle) return self._sub_handles[index] def __setitem__(self, index, value): """Provide transparent assignment to bit index""" self.__getitem__(index).setcachedvalue(value) def getvalue(self): result = BinaryValue() result.binstr = self._get_value_str() return result def setimmediatevalue(self, value): """ Set the value of the underlying simulation object to value. Args: value (ctypes.Structure, cocotb.binary.BinaryValue, int) The value to drive onto the simulator object Raises: TypeError This operation will fail unless the handle refers to a modifiable object eg net, signal or variable. We determine the library call to make based on the type of the value Assigning integers less than 32-bits is faster """ if isinstance(value, get_python_integer_types()) and value < 0x7fffffff: simulator.set_signal_val(self._handle, value) return if isinstance(value, ctypes.Structure): value = BinaryValue(value=cocotb.utils.pack(value), bits=len(self)) elif isinstance(value, get_python_integer_types()): value = BinaryValue(value=value, bits=len(self), bigEndian=False) elif not isinstance(value, BinaryValue): self.log.critical("Unsupported type for value assignment: %s (%s)" % (type(value), repr(value))) raise TypeError("Unable to set simulator value with type %s" % (type(value))) simulator.set_signal_val_str(self._handle, value.binstr) def setcachedvalue(self, value): """Intercept the store of a value and hold in cache. This operation is to enable all of the scheduled callbacks to completed with the same read data and for the writes to occour on the next sim time""" cocotb.scheduler.save_write(self, value) # We want to maintain compatability with python 2.5 so we can't use @property with a setter value = property(getvalue, setcachedvalue, None, "A reference to the value") def _get_value_str(self): return simulator.get_signal_val(self._handle) def __le__(self, value): """Overload the less than or equal to operator to provide an hdl-like shortcut module.signal <= 2 """ self.value = value def __len__(self): """Returns the 'length' of the underlying object. For vectors this is the number of bits. TODO: Handle other types (loops, generate etc) """ if self._len is None: self._len = len(self._get_value_str()) return self._len def __cmp__(self, other): # Permits comparison of handles i.e. if clk == dut.clk if isinstance(other, SimHandle): if self._handle == other._handle: return 0 return 1 # Use the comparison method of the other object against our value return self.value.__cmp__(other) def __iter__(self): """Iterates over all known types defined by simulator module""" for handle_type in [simulator.MODULE, simulator.PARAMETER, simulator.REG, simulator.NET, simulator.NETARRAY]: iterator = simulator.iterate(handle_type, self._handle) while True: try: thing = simulator.next(iterator) except StopIteration: break hdl = SimHandle(thing) self._sub_handles[hdl.name] = hdl yield hdl def __int__(self): return int(self.value)
class SimHandleBase(object): """ Base class for all simulation objects. We maintain a handle which we can use for GPI calls """ # For backwards compatibility we support a mapping of old member names # which may alias with the simulator hierarchy. In these cases the # simulator result takes priority, only falling back to the python member # if there is no colliding object in the elaborated design. _compat_mapping = { "log" : "_log", "fullname" : "_fullname", "name" : "_name", } def __init__(self, handle): """ Args: handle (integer) : the GPI handle to the simulator object """ self._handle = handle self._len = None self._sub_handles = {} # Dictionary of children self._invalid_sub_handles = {} # Dictionary of invalid queries self._discovered = False self._name = simulator.get_name_string(self._handle) self._type = simulator.get_type_string(self._handle) self._fullname = self._name + "(%s)" % self._type self._log = SimLog("cocotb.%s" % self._name) self._log.debug("Created") def __hash__(self): return self._handle def __len__(self): """Returns the 'length' of the underlying object. For vectors this is the number of bits. """ if self._len is None: self._len = simulator.get_num_elems(self._handle) return self._len def __eq__(self, other): # Permits comparison of handles i.e. if clk == dut.clk if isinstance(other, SimHandleBase): if self._handle == other._handle: return 0 return 1 def __ne__(self, other): return not self.__eq__(other) def __repr__(self): return self._fullname def _raise_testerror(self, msg): lastframe = sys._getframe(2) if sys.version_info[0] >= 3: buff = StringIO() traceback.print_stack(lastframe, file=buff) else: buff_bytes = BytesIO() traceback.print_stack(lastframe, file=buff_bytes) buff = StringIO(buff_bytes.getvalue().decode("UTF8")) self._log.error("%s\n%s" % (msg, buff.getvalue())) exception = TestError(msg) exception.stderr.write(buff.getvalue()) buff.close() raise exception
# Singleton scheduler instance # NB this cheekily ensures a singleton since we're replacing the reference # so that cocotb.scheduler gives you the singleton instance and not the # scheduler package # GPI logging instance if "COCOTB_SIM" in os.environ: import simulator logging.basicConfig() logging.setLoggerClass(SimBaseLog) log = SimLog('cocotb') level = os.getenv("COCOTB_LOG_LEVEL", "INFO") try: _default_log = getattr(logging, level) except AttributeError as e: log.error("Unable to set loging level to %s" % level) _default_log = logging.INFO log.setLevel(_default_log) loggpi = SimLog('cocotb.gpi') # Notify GPI of log level simulator.log_level(_default_log) # If stdout/stderr are not TTYs, Python may not have opened them with line # buffering. In that case, try to reopen them with line buffering # explicitly enabled. This ensures that prints such as stack traces always # appear. Continue silently if this fails. try: if not sys.stdout.isatty(): sys.stdout = os.fdopen(sys.stdout.fileno(), 'w', 1) log.debug("Reopened stdout with line buffering") if not sys.stderr.isatty():
class TestFactory(object): """Used to automatically generate tests. 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`` and ``gen_b``: >>> tf = TestFactory(run_test) >>> tf.add_option('data_in', [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 idles * ``gen_a`` with no backpressure and ``random_idles`` * ``gen_a`` with ``random_backpressure`` and no idles * ``gen_a`` with ``random_backpressure`` and ``random_idles`` * ``gen_b`` with no backpressure and no idles * ``gen_b`` with no backpressure and ``random_idles`` * ``gen_b`` with ``random_backpressure`` and no idles * ``gen_b`` with ``random_backpressure`` and ``random_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. """ def __init__(self, test_function, *args, **kwargs): """ Args: test_function (function): the function that executes a test. Must take 'dut' as the first argument. *args: Remaining args 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 kwargs 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. """ if not isinstance(test_function, cocotb.coroutine): raise TypeError("TestFactory requires a cocotb coroutine") self.test_function = test_function self.name = self.test_function._func.__name__ self.args = args self.kwargs_constant = kwargs self.kwargs = {} self.log = SimLog("cocotb.regression") def add_option(self, name, optionlist): """Add a named option to the test. Args: name (str): Name of the option. Passed to test as a keyword argument. optionlist (list): A list of possible options for this test knob. """ self.kwargs[name] = optionlist def generate_tests(self, prefix="", postfix=""): """ Generates 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. Args: prefix (str): Text string to append to start of ``test_function`` name when naming generated test cases. This allows reuse of a single ``test_function`` with multiple :class:`TestFactories <.TestFactory>` 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 single ``test_function`` with multiple :class:`TestFactories <.TestFactory>` without name clashes. """ frm = inspect.stack()[1] mod = inspect.getmodule(frm[0]) d = self.kwargs for index, testoptions in enumerate( (dict(zip(d, v)) for v in product(*d.values()))): name = "%s%s%s_%03d" % (prefix, self.name, postfix, index + 1) doc = "Automatically generated test\n\n" for optname, optvalue in testoptions.items(): if callable(optvalue): if not optvalue.__doc__: desc = "No docstring supplied" else: desc = optvalue.__doc__.split('\n')[0] doc += "\t%s: %s (%s)\n" % (optname, optvalue.__name__, desc) else: doc += "\t%s: %s\n" % (optname, repr(optvalue)) self.log.debug("Adding generated test \"%s\" to module \"%s\"" % (name, mod.__name__)) kwargs = {} kwargs.update(self.kwargs_constant) kwargs.update(testoptions) if hasattr(mod, name): self.log.error("Overwriting %s in module %s. " "This causes a previously defined testcase " "not to be run. Consider setting/changing " "name_postfix" % (name, mod)) setattr( mod, name, _create_test(self.test_function, name, doc, mod, *self.args, **kwargs))
class RegressionManager(object): """Encapsulates all regression capability into a single place""" def __init__(self, root_name, modules, tests=None, seed=None, hooks=[]): """ Args: modules (list): A list of python module names to run Kwargs """ self._queue = [] self._root_name = root_name self._dut = None self._modules = modules self._functions = tests self._running_test = None self._cov = None self.log = SimLog("cocotb.regression") self._seed = seed self._hooks = hooks def initialise(self): try: self._initialise() except Exception as e: import traceback self.log.error(traceback.format_exc()) raise def _initialise(self): self.start_time = time.time() self.test_results = [] self.ntests = 0 self.count = 1 self.skipped = 0 self.failures = 0 self.xunit = XUnitReporter() suite_name = os.getenv('RESULT_TESTSUITE') if os.getenv('RESULT_TESTSUITE') else "all" package_name = os.getenv('RESULT_TESTPACKAGE') if os.getenv('RESULT_TESTPACKAGE') else "all" self.xunit.add_testsuite(name=suite_name, tests=repr(self.ntests), package=package_name) if (self._seed is not None): self.xunit.add_property(name="random_seed", value=("%d"%self._seed)) if coverage is not None: self.log.info("Enabling coverage collection of Python code") self._cov = coverage.coverage(branch=True, omit=["*cocotb*"]) self._cov.start() handle = simulator.get_root_handle(self._root_name) self._dut = cocotb.handle.SimHandle(handle) if handle else None if self._dut is None: raise AttributeError("Can not find Root Handle (%s)" % self._root_name) # Auto discovery for module_name in self._modules: try: self.log.debug("Python Path: " + ",".join(sys.path)) self.log.debug("PWD: " + os.getcwd()) module = _my_import(module_name) except Exception as E: self.log.critical("Failed to import module %s: %s", module_name, E) self.log.info("MODULE variable was \"%s\"", ".".join(self._modules)) self.log.info("Traceback: ") self.log.info(traceback.format_exc()) raise if self._functions: # Specific functions specified, don't auto discover for test in self._functions.rsplit(','): if not hasattr(module, test): raise AttributeError("Test %s doesn't exist in %s" % (test, module_name)) self._queue.append(getattr(module, test)(self._dut)) self.ntests += 1 break for thing in vars(module).values(): if hasattr(thing, "im_test"): try: test = thing(self._dut) skip = test.skip except TestError: skip = True self.log.warning("Failed to initialise test %s" % thing.name) if skip: self.log.info("Skipping test %s" % thing.name) self.xunit.add_testcase(name=thing.name, classname=module_name, time="0.0", sim_time_ns="0.0", ratio_time="0.0") self.xunit.add_skipped() self.skipped += 1 self._store_test_result(module_name, thing.name, None, 0.0, 0.0, 0.0) else: self._queue.append(test) self.ntests += 1 self._queue.sort(key=lambda test: "%s.%s" % (test.module, test.funcname)) for valid_tests in self._queue: self.log.info("Found test %s.%s" % (valid_tests.module, valid_tests.funcname)) for module_name in self._hooks: self.log.info("Loading hook from module '"+module_name+"'") module = _my_import(module_name) for thing in vars(module).values(): if hasattr(thing, "im_hook"): try: test = thing(self._dut) except TestError: self.log.warning("Failed to initialize hook %s" % thing.name) else: cocotb.scheduler.add(test) def tear_down(self): """It's the end of the world as we know it""" if self.failures: self.log.error("Failed %d out of %d tests (%d skipped)" % (self.failures, self.count - 1, self.skipped)) else: self.log.info("Passed %d tests (%d skipped)" % (self.count - 1, self.skipped)) if self._cov: self._cov.stop() self.log.info("Writing coverage data") self._cov.save() self._cov.html_report() self._log_test_summary() self._log_sim_summary() self.log.info("Shutting down...") self.xunit.write() simulator.stop_simulator() def next_test(self): """Get the next test to run""" if not self._queue: return None return self._queue.pop(0) def _add_failure(self, result): self.xunit.add_failure(stdout=repr(str(result)), stderr="\n".join(self._running_test.error_messages), message="Test failed with random_seed={}".format(self._seed)) self.failures += 1 def handle_result(self, result): """Handle a test result Dumps result to XML and schedules the next test (if any) Args: result (TestComplete exception) """ real_time = time.time() - self._running_test.start_time sim_time_ns = get_sim_time('ns') - self._running_test.start_sim_time ratio_time = sim_time_ns / real_time self.xunit.add_testcase(name=self._running_test.funcname, classname=self._running_test.module, time=repr(real_time), sim_time_ns=repr(sim_time_ns), ratio_time=repr(ratio_time)) running_test_funcname = self._running_test.funcname # Helper for logging result def _result_was(): result_was = ("%s (result was %s)" % (running_test_funcname, result.__class__.__name__)) return result_was result_pass = True if (isinstance(result, TestSuccess) and not self._running_test.expect_fail and not self._running_test.expect_error): self.log.info("Test Passed: %s" % running_test_funcname) elif (isinstance(result, TestFailure) and self._running_test.expect_fail): self.log.info("Test failed as expected: " + _result_was()) elif (isinstance(result, TestSuccess) and self._running_test.expect_error): self.log.error("Test passed but we expected an error: " + _result_was()) self._add_failure(result) result_pass = False elif isinstance(result, TestSuccess): self.log.error("Test passed but we expected a failure: " + _result_was()) self._add_failure(result) result_pass = False elif isinstance(result, TestError) and self._running_test.expect_error: self.log.info("Test errored as expected: " + _result_was()) elif isinstance(result, SimFailure): if self._running_test.expect_error: self.log.info("Test errored as expected: " + _result_was()) else: self.log.error("Test error has lead to simulator shuttting us " "down") self._add_failure(result) self._store_test_result(self._running_test.module, self._running_test.funcname, False, sim_time_ns, real_time, ratio_time) self.tear_down() return else: self.log.error("Test Failed: " + _result_was()) self._add_failure(result) result_pass = False self._store_test_result(self._running_test.module, self._running_test.funcname, result_pass, sim_time_ns, real_time, ratio_time) self.execute() def execute(self): self._running_test = cocotb.regression.next_test() if self._running_test: start = '' end = '' if self.log.colour: start = ANSI.BLUE_BG + ANSI.BLACK_FG end = ANSI.DEFAULT # Want this to stand out a little bit self.log.info("%sRunning test %d/%d:%s %s" % (start, self.count, self.ntests, end, self._running_test.funcname)) if self.count is 1: test = cocotb.scheduler.add(self._running_test) else: test = cocotb.scheduler.new_test(self._running_test) self.count += 1 else: self.tear_down() def _log_test_summary(self): TEST_FIELD = 'TEST' RESULT_FIELD = 'PASS/FAIL' SIM_FIELD = 'SIM TIME(NS)' REAL_FIELD = 'REAL TIME(S)' RATIO_FIELD = 'RATIO(NS/S)' TEST_FIELD_LEN = max(len(TEST_FIELD),len(max([x['test'] for x in self.test_results],key=len))) RESULT_FIELD_LEN = len(RESULT_FIELD) SIM_FIELD_LEN = len(SIM_FIELD) REAL_FIELD_LEN = len(REAL_FIELD) RATIO_FIELD_LEN = len(RATIO_FIELD) LINE_LEN = 3 + TEST_FIELD_LEN + 2 + RESULT_FIELD_LEN + 2 + SIM_FIELD_LEN + 2 + REAL_FIELD_LEN + 2 + RATIO_FIELD_LEN + 3 LINE_SEP = "*"*LINE_LEN+"\n" summary = "" summary += LINE_SEP summary += "** {a:<{a_len}} {b:^{b_len}} {c:>{c_len}} {d:>{d_len}} {e:>{e_len}} **\n".format(a=TEST_FIELD, a_len=TEST_FIELD_LEN, b=RESULT_FIELD, b_len=RESULT_FIELD_LEN, c=SIM_FIELD, c_len=SIM_FIELD_LEN, d=REAL_FIELD, d_len=REAL_FIELD_LEN, e=RATIO_FIELD, e_len=RATIO_FIELD_LEN) summary += LINE_SEP for result in self.test_results: hilite = '' if result['pass'] is None: pass_fail_str = "N/A" elif result['pass']: pass_fail_str = "PASS" else: pass_fail_str = "FAIL" if self.log.colour: hilite = ANSI.WHITE_FG + ANSI.RED_BG summary += "{start}** {a:<{a_len}} {b:^{b_len}} {c:>{c_len}.2f} {d:>{d_len}.2f} {e:>{e_len}.2f} **\n".format(a=result['test'], a_len=TEST_FIELD_LEN, b=pass_fail_str, b_len=RESULT_FIELD_LEN, c=result['sim'], c_len=SIM_FIELD_LEN-1, d=result['real'], d_len=REAL_FIELD_LEN-1, e=result['ratio'], e_len=RATIO_FIELD_LEN-1, start=hilite) summary += LINE_SEP self.log.info(summary) def _log_sim_summary(self): real_time = time.time() - self.start_time sim_time_ns = get_sim_time('ns') ratio_time = sim_time_ns / real_time summary = "" summary += "*************************************************************************************\n" summary += "** ERRORS : {0:<39}**\n".format(self.failures) summary += "*************************************************************************************\n" summary += "** SIM TIME : {0:<39}**\n".format('{0:.2f} NS'.format(sim_time_ns)) summary += "** REAL TIME : {0:<39}**\n".format('{0:.2f} S'.format(real_time)) summary += "** SIM / REAL TIME : {0:<39}**\n".format('{0:.2f} NS/S'.format(ratio_time)) summary += "*************************************************************************************\n" self.log.info(summary) def _store_test_result(self, module_name, test_name, result_pass, sim_time, real_time, ratio): result = { 'test' : '.'.join([module_name, test_name]), 'pass' : result_pass, 'sim' : sim_time, 'real' : real_time, 'ratio' : ratio} self.test_results.append(result)
class RegressionManager(object): """Encapsulates all regression capability into a single place""" def __init__(self, root_name, modules, tests=None, seed=None, hooks=[]): """ Args: root_name (str): The name of the root handle. modules (list): A list of Python module names to run. tests (list, optional): A list of tests to run. Defaults to ``None``, meaning all discovered tests will be run. seed (int, optional): The seed for the random number generator to use. Defaults to ``None``. hooks (list, optional): A list of hook modules to import. Defaults to the empty list. """ self._queue = [] self._root_name = root_name self._dut = None self._modules = modules self._functions = tests self._running_test = None self._cov = None self.log = SimLog("cocotb.regression") self._seed = seed self._hooks = hooks def initialise(self): self.start_time = time.time() self.test_results = [] self.ntests = 0 self.count = 1 self.skipped = 0 self.failures = 0 self.xunit = XUnitReporter() suite_name = os.getenv('RESULT_TESTSUITE') if os.getenv( 'RESULT_TESTSUITE') else "all" package_name = os.getenv('RESULT_TESTPACKAGE') if os.getenv( 'RESULT_TESTPACKAGE') else "all" self.xunit.add_testsuite(name=suite_name, tests=repr(self.ntests), package=package_name) if (self._seed is not None): self.xunit.add_property(name="random_seed", value=("%d" % self._seed)) if coverage is not None: self.log.info("Enabling coverage collection of Python code") self._cov = coverage.coverage(branch=True, omit=["*cocotb*"]) self._cov.start() handle = simulator.get_root_handle(self._root_name) self._dut = cocotb.handle.SimHandle(handle) if handle else None if self._dut is None: raise AttributeError("Can not find Root Handle (%s)" % self._root_name) # Auto discovery for module_name in self._modules: try: self.log.debug("Python Path: " + ",".join(sys.path)) self.log.debug("PWD: " + os.getcwd()) module = _my_import(module_name) except Exception as E: self.log.critical("Failed to import module %s: %s", module_name, E) self.log.info("MODULE variable was \"%s\"", ".".join(self._modules)) self.log.info("Traceback: ") self.log.info(traceback.format_exc()) raise if self._functions: # Specific functions specified, don't auto discover for test in self._functions.rsplit(','): if not hasattr(module, test): self.log.error( "Requested test %s wasn't found in module %s", test, module_name) raise AttributeError("Test %s doesn't exist in %s" % (test, module_name)) _test = getattr(module, test) if not hasattr(_test, "im_test"): self.log.error( "Requested %s from module %s isn't a cocotb.test decorated coroutine", test, module_name) raise ImportError("Failed to find requested test %s" % test) self._queue.append(getattr(module, test)(self._dut)) self.ntests += 1 break for thing in vars(module).values(): if hasattr(thing, "im_test"): try: test = thing(self._dut) skip = test.skip except TestError: skip = True self.log.warning("Failed to initialize test %s" % thing.name) if skip: self.log.info("Skipping test %s" % thing.name) self.xunit.add_testcase(name=thing.name, classname=module_name, time="0.0", sim_time_ns="0.0", ratio_time="0.0") self.xunit.add_skipped() self.skipped += 1 self._store_test_result(module_name, thing.name, None, 0.0, 0.0, 0.0) else: self._queue.append(test) self.ntests += 1 self._queue.sort(key=lambda test: test.sort_name()) for valid_tests in self._queue: self.log.info("Found test %s.%s" % (valid_tests.module, valid_tests.funcname)) for module_name in self._hooks: self.log.info("Loading hook from module '" + module_name + "'") module = _my_import(module_name) for thing in vars(module).values(): if hasattr(thing, "im_hook"): try: test = thing(self._dut) except TestError: self.log.warning("Failed to initialize hook %s" % thing.name) else: cocotb.scheduler.add(test) def tear_down(self): """It's the end of the world as we know it""" if self.failures: self.log.error("Failed %d out of %d tests (%d skipped)" % (self.failures, self.count - 1, self.skipped)) else: self.log.info("Passed %d tests (%d skipped)" % (self.count - 1, self.skipped)) if self._cov: self._cov.stop() self.log.info("Writing coverage data") self._cov.save() self._cov.html_report() if len(self.test_results) > 0: self._log_test_summary() self._log_sim_summary() self.log.info("Shutting down...") self.xunit.write() simulator.stop_simulator() def next_test(self): """Get the next test to run""" if not self._queue: return None return self._queue.pop(0) def _add_failure(self, result): self.xunit.add_failure( stdout=repr(str(result)), stderr="\n".join(self._running_test.error_messages), message="Test failed with random_seed={}".format(self._seed)) self.failures += 1 def handle_result(self, result): """Handle a test result. Dump result to XML and schedule the next test (if any). Args: result: The sub-exception of TestComplete to raise. """ real_time = time.time() - self._running_test.start_time sim_time_ns = get_sim_time('ns') - self._running_test.start_sim_time ratio_time = sim_time_ns / real_time self.xunit.add_testcase(name=self._running_test.funcname, classname=self._running_test.module, time=repr(real_time), sim_time_ns=repr(sim_time_ns), ratio_time=repr(ratio_time)) running_test_funcname = self._running_test.funcname # Helper for logging result def _result_was(): result_was = ("%s (result was %s)" % (running_test_funcname, result.__class__.__name__)) return result_was result_pass = True if (isinstance(result, TestSuccess) and not self._running_test.expect_fail and not self._running_test.expect_error): self.log.info("Test Passed: %s" % running_test_funcname) elif (isinstance(result, TestFailure) and self._running_test.expect_fail): self.log.info("Test failed as expected: " + _result_was()) elif (isinstance(result, TestSuccess) and self._running_test.expect_error): self.log.error("Test passed but we expected an error: " + _result_was()) self._add_failure(result) result_pass = False elif isinstance(result, TestSuccess): self.log.error("Test passed but we expected a failure: " + _result_was()) self._add_failure(result) result_pass = False elif isinstance(result, TestError) and self._running_test.expect_error: self.log.info("Test errored as expected: " + _result_was()) elif isinstance(result, SimFailure): if self._running_test.expect_error: self.log.info("Test errored as expected: " + _result_was()) else: self.log.error("Test error has lead to simulator shutting us " "down") self._add_failure(result) self._store_test_result(self._running_test.module, self._running_test.funcname, False, sim_time_ns, real_time, ratio_time) self.tear_down() return else: self.log.error("Test Failed: " + _result_was()) self._add_failure(result) result_pass = False self._store_test_result(self._running_test.module, self._running_test.funcname, result_pass, sim_time_ns, real_time, ratio_time) self.execute() def execute(self): self._running_test = cocotb.regression.next_test() if self._running_test: start = '' end = '' if self.log.colour: start = ANSI.COLOR_TEST end = ANSI.COLOR_DEFAULT # Want this to stand out a little bit self.log.info("%sRunning test %d/%d:%s %s" % (start, self.count, self.ntests, end, self._running_test.funcname)) if self.count is 1: test = cocotb.scheduler.add(self._running_test) else: test = cocotb.scheduler.new_test(self._running_test) self.count += 1 else: self.tear_down() def _log_test_summary(self): TEST_FIELD = 'TEST' RESULT_FIELD = 'PASS/FAIL' SIM_FIELD = 'SIM TIME(NS)' REAL_FIELD = 'REAL TIME(S)' RATIO_FIELD = 'RATIO(NS/S)' TEST_FIELD_LEN = max( len(TEST_FIELD), len(max([x['test'] for x in self.test_results], key=len))) RESULT_FIELD_LEN = len(RESULT_FIELD) SIM_FIELD_LEN = len(SIM_FIELD) REAL_FIELD_LEN = len(REAL_FIELD) RATIO_FIELD_LEN = len(RATIO_FIELD) LINE_LEN = 3 + TEST_FIELD_LEN + 2 + RESULT_FIELD_LEN + 2 + SIM_FIELD_LEN + 2 + REAL_FIELD_LEN + 2 + RATIO_FIELD_LEN + 3 LINE_SEP = "*" * LINE_LEN + "\n" summary = "" summary += LINE_SEP summary += "** {a:<{a_len}} {b:^{b_len}} {c:>{c_len}} {d:>{d_len}} {e:>{e_len}} **\n".format( a=TEST_FIELD, a_len=TEST_FIELD_LEN, b=RESULT_FIELD, b_len=RESULT_FIELD_LEN, c=SIM_FIELD, c_len=SIM_FIELD_LEN, d=REAL_FIELD, d_len=REAL_FIELD_LEN, e=RATIO_FIELD, e_len=RATIO_FIELD_LEN) summary += LINE_SEP for result in self.test_results: hilite = '' if result['pass'] is None: pass_fail_str = "N/A" elif result['pass']: pass_fail_str = "PASS" else: pass_fail_str = "FAIL" if self.log.colour: hilite = ANSI.COLOR_HILITE_SUMMARY summary += "{start}** {a:<{a_len}} {b:^{b_len}} {c:>{c_len}.2f} {d:>{d_len}.2f} {e:>{e_len}.2f} **\n".format( a=result['test'], a_len=TEST_FIELD_LEN, b=pass_fail_str, b_len=RESULT_FIELD_LEN, c=result['sim'], c_len=SIM_FIELD_LEN - 1, d=result['real'], d_len=REAL_FIELD_LEN - 1, e=result['ratio'], e_len=RATIO_FIELD_LEN - 1, start=hilite) summary += LINE_SEP self.log.info(summary) def _log_sim_summary(self): real_time = time.time() - self.start_time sim_time_ns = get_sim_time('ns') ratio_time = sim_time_ns / real_time summary = "" summary += "*************************************************************************************\n" summary += "** ERRORS : {0:<39}**\n".format( self.failures) summary += "*************************************************************************************\n" summary += "** SIM TIME : {0:<39}**\n".format( '{0:.2f} NS'.format(sim_time_ns)) summary += "** REAL TIME : {0:<39}**\n".format( '{0:.2f} S'.format(real_time)) summary += "** SIM / REAL TIME : {0:<39}**\n".format( '{0:.2f} NS/S'.format(ratio_time)) summary += "*************************************************************************************\n" self.log.info(summary) def _store_test_result(self, module_name, test_name, result_pass, sim_time, real_time, ratio): result = { 'test': '.'.join([module_name, test_name]), 'pass': result_pass, 'sim': sim_time, 'real': real_time, 'ratio': ratio } self.test_results.append(result)
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 RunningCoroutine(object): """Per instance wrapper around an function to turn it into a coroutine Provides the following: coro.join() creates a Trigger that will fire when this coroutine completes coro.kill() will destroy a coroutine instance (and cause any Join triggers to fire """ def __init__(self, inst, parent): self.__name__ = "%s" % inst.__name__ self.log = SimLog("cocotb.coroutine.%s" % self.__name__, id(self)) self._coro = inst self._finished = False self._callbacks = [] self._parent = parent self.__doc__ = parent._func.__doc__ self.module = parent._func.__module__ self.funcname = parent._func.__name__ self.retval = None if not hasattr(self._coro, "send"): self.log.error("%s isn't a value coroutine! Did you use the yield keyword?" % self.__name__) raise CoroutineComplete(callback=self._finished_cb) def __iter__(self): return self def __str__(self): return str(self.__name__) def send(self, value): try: return self._coro.send(value) except TestComplete as e: if isinstance(e, TestFailure): self.log.warning(str(e)) else: self.log.info(str(e)) raise except ReturnValue as e: self.retval = e.retval raise CoroutineComplete(callback=self._finished_cb) except StopIteration: raise CoroutineComplete(callback=self._finished_cb) except Exception as e: raise_error(self, "Send raised exception: %s" % (str(e))) def throw(self, exc): return self._coro.throw(exc) def close(self): return self._coro.close() def kill(self): """Kill a coroutine""" self.log.debug("kill() called on coroutine") cocotb.scheduler.schedule_remove(self, self._finished_cb) def _finished_cb(self): """Called when the coroutine completes. Allows us to mark the coroutine as finished so that boolean testing works. Also call any callbacks, usually the result of coroutine.join()""" self._finished = True self.log.debug("Coroutine finished calling pending callbacks (%d pending)" % len(self._callbacks)) for cb in self._callbacks: cb() self._callbacks = [] def join(self): """Return a trigger that will fire when the wrapped coroutine exits""" return Join(self) def __nonzero__(self): """Provide boolean testing if the coroutine has finished return false otherwise return true""" return not self._finished