.. _refcard:

**************
Reference Card
**************
..
   Document "best practice"; leave out detail.
   Keep format as 1/3rd width of A4/Letter for taping to monitor frames.

   The "| " syntax is a "Line Block", see
      https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks

.. spelling:word-list::
   coro
   coros
   func
   metavalue
   TestFactory


*coro*: a coroutine; *task*: a concurrently-running coroutine; *trigger*: a trigger

+------------------------+-----------------------------------------------------------------+
| Assign                 | ``dut.mysignal.value = 0xFF00``                                 |
+------------------------+-----------------------------------------------------------------+
| Assign immediately     | ``dut.mysignal.value = Immediate(0xFF00)``                      |
+------------------------+-----------------------------------------------------------------+
| Assign metavalue       | | ``dut.mysignal.value = Logic("X")``                           |
|                        | | ``dut.mysignal.value = LogicArray("01XZ")``                   |
+------------------------+-----------------------------------------------------------------+
| Read                   | | ``val = dut.mysignal.value``                                  |
|                        | | (``mysig = dut.mysignal`` *creates an alias/reference*)       |
+------------------------+-----------------------------------------------------------------+
| Bit slice              | | ``mybit = dut.mysignal.value[0]``                             |
|                        | | ``mybits = dut.mysignal.value[3:1]``                          |
+------------------------+-----------------------------------------------------------------+
| Convert                | | ``val = dut.mysignal.value.to_unsigned()``                    |
|                        | | ``val = dut.mysignal.value.to_signed()``                      |
|                        | | ``val = dut.mysignal.value.to_bytes(byteorder="little")``     |
|                        | | ``val = str(dut.mysignal.value)``                             |
+------------------------+-----------------------------------------------------------------+
| Vector length          | ``num_bits = len(dut.mysignal)``                                |
+------------------------+-----------------------------------------------------------------+
| Check                  | ``assert dut.mysignal.value == exp, "Not as expected!"``        |
+------------------------+---------------+-------------------------------------------------+
| Access Extended / Escaped Identifiers  | ``dut["\\!Hello!\\"]``                          |
+----------------------------------------+-------------------------------------------------+
|                                                                                          |
+------------------------+-----------------------------------------------------------------+
| Wait time              | ``await cocotb.triggers.Timer(12, "ns")``                       |
+------------------------+-----------------------------------------------------------------+
| Wait for signal edge   | | ``await cocotb.triggers.RisingEdge(dut.mysignal)``            |
|                        | | ``await cocotb.triggers.FallingEdge(dut.mysignal)``           |
|                        | | ``await cocotb.triggers.ValueChange(dut.mysignal)``           |
+------------------------+-----------------------------------------------------------------+
|                                                                                          |
+------------------------+-----------------------------------------------------------------+
| Run coros concurrently | | ``task_0 = cocotb.start_soon(coro)``                          |
|                        | | ``result = await task_0``                                     |
+------------------------+-----------------------------------------------------------------+
| Cancel task            | ``task_0.cancel()``                                             |
+------------------------++----------------------------------------------------------------+
| Wait for task to finish | ``await task_0.complete``                                      |
+------------------------++----------------------------------------------------------------+
|                                                                                          |
+-------------------------------+----------------------------------------------------------+
| Resume on any Task or Trigger | ``await cocotb.triggers.First(task_0, trigger_1)``       |
+-------------------------------+----------------------------------------------------------+
| Resume on all Task or Trigger | ``await cocotb.triggers.Combine(task_0, trigger_1)``     |
+-------------------------------+----------------------------------------------------------+
|                                                                                          |
+------------------------+-----------------------------------------------------------------+
| Generate clock         | ``clk = Clock(dut.clk, 12, "ns").start()``                      |
+------------------------+-----------------------------------------------------------------+
|                                                                                          |
+------------------------+-----------------------------------------------------------------+
| Queue write            | | ``await cocotb.queue.Queue.put(item)``                        |
|                        | | ``cocotb.queue.Queue.put_nowait(item)``                       |
+------------------------+-----------------------------------------------------------------+
| Queue read             | | ``item = await cocotb.queue.Queue.get()``                     |
|                        | | ``item = cocotb.queue.Queue.get_nowait()``                    |
+------------------------+-----------------------------------------------------------------+
| Queue attributes       | | ``queue.maxsize``  (``None`` *== unlimited*)                  |
|                        | | ``queue.qsize()``                                             |
|                        | | ``queue.empty()``                                             |
|                        | | ``queue.full()``                                              |
+------------------------+-----------------------------------------------------------------+
| Specialized queues     | ``.PriorityQueue``, ``.LifoQueue``                              |
+------------------------+-----------------------------------------------------------------+
|                                                                                          |
+------------------------+-----------------------------------------------------------------+
| Set up event           | ``e = cocotb.triggers.Event()``                                 |
+------------------------+-----------------------------------------------------------------+
| Wake up waiters        | ``e.set()``                                                     |
+------------------------+-----------------------------------------------------------------+
| Wait until ``set()``   | ``await e.wait()``                                              |
+------------------------+-----------------------------------------------------------------+
| Reset after ``set()``  | ``e.clear()``                                                   |
+------------------------+-----------------------------------------------------------------+
| Timeout                | ``await cocotb.triggers.with_timeout(coro, 1, "us")``           |
+------------------------+-----------------------------------------------------------------+
|                                                                                          |
+------------------------+-----------------------------------------------------------------+
| Force value            | ``dut.mysignal.value = cocotb.handle.Force(0xFF00)``            |
+------------------------+-----------------------------------------------------------------+
| Keep value             | ``dut.mysignal.value = cocotb.handle.Freeze()``                 |
+------------------------+-----------------------------------------------------------------+
| Release Force/Freeze   | ``dut.mysignal.value = cocotb.handle.Release()``                |
+------------------------+-----------------------------------------------------------------+
| *Normal assignment is a "deposit"* (``cocotb.handle.Deposit()``)                         |
+------------------------+-----------------------------------------------------------------+
|                                                                                          |
+------------------------+-----------------------------------------------------------------+
| Mark as test           | ``@cocotb.test(skip, expect_fail, timeout_time, timeout_unit)`` |
+------------------------+-----------+-----------------------------------------------------+
|                                                                                          |
+------------------------+-----------------------------------------------------------------+
| Set up TestFactory     | ``tf = cocotb.regression.TestFactory(coro)``                    |
+------------------------+-----------------------------------------------------------------+
| Add test option        | ``tf.add_option("arg", ["val0", "val1"])``                      |
+------------------------+-----------------------------------------------------------------+
| Generate tests         | ``tf.generate_tests()``                                         |
+----------------------+-+-----------------------------------------------------------------+
| Parametrize test     | | ``@cocotb.parametrize(arg1=[1, 2], arg2=["yes", "no"])``        |
|                      | | ``@cocotb.parametrize(("arg1", "arg2"), [(1, "a"), (3, "b")])`` |
+----------------------+-------------------------------------------------------------------+