Add custom clocking example to docstring of Clock()
Closes by providing a recipe for the feature requested there in the docs.
@@ -48,9 +48,9 @@ class BaseClock(object):
class Clock(BaseClock):
- """Simple 50:50 duty cycle clock driver.
+ r"""Simple 50:50 duty cycle clock driver.
- Instances of this class should call its :meth:`start` method and fork the
+ Instances of this class should call its :meth:`start` method and :func:`fork` the
result. This will create a clocking thread that drives the signal at the
desired period/frequency.
@@ -69,6 +69,45 @@ class Clock(BaseClock):
``None``, ``'fs'``, ``'ps'``, ``'ns'``, ``'us'``, ``'ms'``, ``'sec'``.
When no *units* is given (``None``) the timestep is determined by
the simulator.
+
+
+ If you need more features like a phase shift and an asymmetric duty cycle,
+ it is simple to create your own clock generator (that you then :func:`fork`):
+
+ .. code-block:: python
+
+ @cocotb.coroutine
+ def custom_clock():
+ # pre-construct triggers for performance
+ high_time = Timer(high_delay, units="ns")
+ low_time = Timer(low_delay, units="ns")
+ yield Timer(initial_delay, units="ns")
+ while True:
+ dut.clk <= 1
+ yield high_time
+ dut.clk <= 0
+ yield low_time
+
+ If you also want to change the timing during simulation,
+ use this slightly more inefficient example instead where
+ the :class:`Timer`\ s inside the while loop are created with
+ current delay values:
+
+ .. code-block:: python
+
+ @cocotb.coroutine
+ def custom_clock():
+ while True:
+ dut.clk <= 1
+ yield Timer(high_delay, units="ns")
+ dut.clk <= 0
+ yield Timer(low_delay, units="ns")
+
+ high_delay = low_delay = 100
+ cocotb.fork(custom_clock())
+ yield Timer(1000, units="ns")
+ high_delay = low_delay = 10 # change the clock speed
+ yield Timer(1000, units="ns")
"""
def __init__(self, signal, period, units=None):
@@ -83,7 +122,7 @@ class Clock(BaseClock):
@cocotb.coroutine
def start(self, cycles=None, start_high=True):
- """Clocking coroutine. Start driving your clock by forking a
+ r"""Clocking coroutine. Start driving your clock by :func:`fork`\ ing a
call to this.
Args:
