Triggers

Triggers are used to indicate when the cocotb scheduler should resume coroutine execution. To use a trigger, a coroutine should await or yield it. This will cause execution of the current coroutine to pause. When the trigger fires, execution of the paused coroutine will resume:

@cocotb.coroutine
def coro():
    print("Some time before the edge")
    yield RisingEdge(clk)
    print("Immediately after the edge")

Or using the syntax in Python 3.5 onwards:

@cocotb.coroutine
async def coro():
    print("Some time before the edge")
    await RisingEdge(clk)
    print("Immediately after the edge")

Simulator Triggers

Signals

class cocotb.triggers.Edge(signal)[source]

Fires on any value change of signal.

class cocotb.triggers.RisingEdge(signal)[source]

Fires on the rising edge of signal, on a transition from 0 to 1.

class cocotb.triggers.FallingEdge(signal)[source]

Fires on the falling edge of signal, on a transition from 1 to 0.

class cocotb.triggers.ClockCycles(signal, num_cycles, rising=True)[source]

Fires after num_cycles transitions of signal from 0 to 1.

Parameters

rising – If true, the default, count rising edges. Otherwise, count falling edges

Timing

class cocotb.triggers.Timer(time_ps, units=None)[source]

Fires after the specified simulation time period has elapsed.

class cocotb.triggers.ReadOnly[source]

Fires when the current simulation timestep moves to the read-only phase.

The read-only phase is entered when the current timestep no longer has any further delta steps. This will be a point where all the signal values are stable as there are no more RTL events scheduled for the timestep. The simulator will not allow scheduling of more events in this timestep. Useful for monitors which need to wait for all processes to execute (both RTL and cocotb) to ensure sampled signal values are final.

class cocotb.triggers.ReadWrite[source]

Fires when the read-write portion of the sim cycles is reached.

class cocotb.triggers.NextTimeStep[source]

Fires when the next time step is started.

Python Triggers

class cocotb.triggers.Combine(*triggers)[source]

Fires when all of triggers have fired.

Like most triggers, this simply returns itself.

class cocotb.triggers.First(*triggers)[source]

Fires when the first trigger in triggers fires.

Returns the result of the trigger that fired.

As a shorthand, t = yield [a, b] can be used instead of t = yield First(a, b). Note that this shorthand is not available when using await.

Note

The event loop is single threaded, so while events may be simultaneous in simulation time, they can never be simultaneous in real time. For this reason, the value of t_ret is t1 in the following example is implementation-defined, and will vary by simulator:

t1 = Timer(10, units='ps')
t2 = Timer(10, units='ps')
t_ret = yield First(t1, t2)
class cocotb.triggers.Join(coroutine)[source]

Fires when a fork()ed coroutine completes

The result of blocking on the trigger can be used to get the coroutine result:

@cocotb.coroutine()
def coro_inner():
    yield Timer(1)
    raise ReturnValue("Hello world")

task = cocotb.fork(coro_inner())
result = yield Join(task)
assert result == "Hello world"

Or using the syntax in Python 3.5 onwards:

@cocotb.coroutine()
async def coro_inner():
    await Timer(1)
    return "Hello world"

task = cocotb.fork(coro_inner())
result = await Join(task)
assert result == "Hello world"

If the coroutine threw an exception, the await or yield will re-raise it.

property retval

The return value of the joined coroutine.

Note

Typically there is no need to use this attribute - the following code samples are equivalent:

forked = cocotb.fork(mycoro())
j = Join(forked)
yield j
result = j.retval
forked = cocotb.fork(mycoro())
result = yield Join(forked)

Synchronization

These are not Triggers themselves, but contain methods that can be used as triggers. These are used to synchronize coroutines with each other.

class cocotb.triggers.Event(name='')[source]

Event to permit synchronization between two coroutines.

Yielding wait() from one coroutine will block the coroutine until set() is called somewhere else.

set(data=None)[source]

Wake up all coroutines blocked on this event.

wait()[source]

Get a trigger which fires when another coroutine sets the event.

If the event has already been set, the trigger will fire immediately.

To reset the event (and enable the use of wait again), clear() should be called.

clear()[source]

Clear this event that has fired.

Subsequent calls to wait() will block until set() is called again.

class cocotb.triggers.Lock(name='')[source]

Lock primitive (not re-entrant).

This should be used as:

yield lock.acquire()
try:
    # do some stuff
finally:
    lock.release()
locked = None

True if the lock is held

acquire()[source]

Produce a trigger which fires when the lock is acquired.

release()[source]

Release the lock.