User:Pigsonthewing/sandbox3

cocotb is an open-source COroutine-based COsimuation TestBench (hence the name) environment, developed for the verification of hardware description languages like VHDL, Verilog and SystemVerilog, by means of Python programming language in the field of electronic design automation (EDA). The project is hosted on GitHub, and is available for use, relying on an HDL simulator for simulating the HDL code, on Windows, Linux and macOS.

History
cocotb was first released on Jul 9, 2013 by Stuart Hodgson, one of its first developers together with Chris Higgs, both from Potential Ventures, and supported also by Solarflare Communications Ltd (then acquired, in July 2019, by Xilinx Inc), and is currently developed and maintained by an active community.

cocotb, as an independent project, is since 2018 under the auspices of the Free and Open Source Silicon Foundation, which provides for cocotb's financial, legal and administrative support, holding also its assets.

cocotb vs UVM
While relying on the same concept of design re-use and random testing, UVM (Universal Verification Methodology) is based on a SystemVerilog library, resulting in a powerful, yet more complicated environment than the one granted by cocotb. Indeed, cocotb limits the usage of the target HDL for the design itself, using instead Python for the design of the tests. Being Python an object-oriented, interpreted, and interactive programming language, the advantages given by cocotb while building the tests are numerous:
 * cocotb is fast, allowing to build test in a fraction of the time needed for a UVM test;
 * cocotb is easy to interface with;
 * Python features huge standard libraries;
 * Python is popular and widespread;
 * Python is interpreted, allowing edits on the tests without the need of the design to be recompiled.

Working principle
Once the developer has completed the part of the design that is to be tested, i.e. the Device under test (DUT), he can instantiate it as top-level in the simulator. cocotb provides an interface between the simulator and Python, and allows to drive the DUT inputs, waiting for the simulation time to pass and monitoring its outputs, all through Python functions. The design and testbenches can be simulated independently, using the concept of cosimulation. The simulation is run when the Python code, which in this context is called "coroutine" is paused and, viceversa, simulation does not advance while a coroutine is in execution. The triggering conditions that determine which is to advance and which to pause can be one of the many triggers that cocotb offers, such as timers, edges of predetermined signals, certain number of clock cycles.

Coroutines
A cocotb testbench is based on what are called coroutines. As mentioned, coroutines execute when the simulation is paused, using the  keyword for passing the control back to the simulator when simulation time is needed to advance. The "awaited" object is, typically, a trigger, that awakes the coroutine on its occurrence, or it can also be another coroutine. A coroutine is, in the end, a Python function, identified by the decorator, and can, thus, return values to be used in other coroutines. They can be forked, which means that they can be used in concurrent operations, and even killed before their natural end.

Triggers
Triggers are a cocotb class that is used to indicate the moment when the cocotb scheduler should regain a coroutine execution, upon having waited an  event, pausing then the simulation for the coroutine to advance. There is a complete class of triggers provided for cocotb, both for the simulator and for Python, that comprises, for example:
 * Signals, which include
 * Edge, for triggering on whatever edge of a signal
 * Rising Edge, for triggering on the rising edge of a signal
 * Falling Edge, for triggering on the falling edge of a signal
 * Clock Cycles, that triggers after num_cycles, given as a parameter
 * Timing, featuring a "Timer" that allows to specify
 * time, as a real or decimal value
 * units, to specify the magnitude of the inserted value

Supported simulators
cocotb has grown its support to many of the available HDL simulators, and, more in general, can be used with any simulator supporting the industry-standard Verilog Procedural Interface (VPI), VHDL Procedural Interface (VHPI), or ModelSim Foreign Language Interface (FLI) interfaces, showing a behavior with minor differences from one simulator to the other, all taken care by cocotb. Here is a list of the supported simulators: The simulator in use must be specified in the Makefile, referred to the  variable, so that cocotb can properly make use of it.
 * Icarus Verilog
 * Verilator (version 4.106 or later required)
 * Synopsys VCS (only VPI is supported)
 * Aldec Riviera-PRO (deprecated since version 1.4)
 * Aldec Active-HDL
 * Mentor/Siemens EDA Questa
 * Mentor/Siemens EDA ModelSim
 * Cadence Incisive
 * Cadence Xcelium
 * GHDL (support is experimental, implements VPI interface despite being a VHDL simulator)
 * Tachyon DA CVC

Buses
Supported buses, previously part of the same GitHub repository, are now pre-packaged as testbenching tools and re-usable interfaces under the cocotb_bus repository. The tools comprehend both drivers and monitors, supporting standard such as AMBA Advanced eXtensible Interface protocols, which represent a de facto standard in terms of embedded processors bus architectures, Intel's Avalon (limited functionalities), IBM's On-chip Peripheral Bus (OPB, with limited functionalities), which is part of the CoreConnect microprocessor bus-architecture for SoCs and XGMII (10 Gigabit Media-Independent Interface), an IEEE 802.3 standard for full duplex 10 Gigabit Ethernet connection for electronic devices, which is a variant of the original Media-independent interface, and is typically used for on-chip connections.

The cocotb_bus repository also includes scoreboards, which are a class used to compare actual outputs from the simulations to the expected outputs generated using Python. Scoreboards make use of the previously mentioned monitors in order to perform the comparison. These buses drivers and monitor play, via Python, the role that a Bus Functional Model (BFM) plays when verifying integrated circuits in the classical way, which is via a non-synthesizable model of an Integrated circuit written in HDL, featuring one or more external buses.

Extensions
cocotb, taking advantage of being open-source, is prone to be extended by its users. In fact, when the available functionalities do not cover some needs, which is the case, in particular, for drivers and monitors, users can package new functionalities and distribute them as extensions, sharing them allowing their re-use. Such extensions, which in the verification world are usually referred to as "verification IPs" (VIPs), are, for cocotb, normal Python packages, and can, thus, make use of all standard Python packaging and distribution techniques. The cocotb community has come up with naming conventions, in order to ease the making and discovering of extensions. A bus extension, for example, could be providing an interface to a bus such as SPI, and should be built on top of a set of common classes to offer a uniform interface to the users. There are, usually, three kinds of functionalities that a bus extension should deliver:
 * the bus itself, as an abstraction
 * an active part, the driver, which drives the signals on the bus
 * a passive part, the monitor, which serves to observe the signal changes

VHDL vs Python
Here is reported a code example of a D Flip-Flop in both the VHDL implementation and in the correspondent Python couterpart, using cocotb.

AXI4 Lite Master example
This is, instead, an example of a cocotb test on an AXI4Lite Master

Export waveforms
cocotb has also the ability, based on the simulation option and simulator behavior, to export waveform files such as VCD, a Verilog standard used by almost any wave viewer, GHW (GHdl Waveform), a file format supporting dumping of any VHDL typ, as VCD only supports a few of them, and fst, which handles the same signals of VCD, but in a much smaller file.



Additional material

 * Digital electronics
 * Electronic design automation
 * Functional verification
 * Waveform viewer
 * HDL
 * VUnit
 * Python

HDL languages

 * VHDL
 * Verilog
 * SystemVerilog
 * SystemC — C++ library providing HDL event-driven semantics
 * MyHDL - A hardware description language build on top of Python
 * Chisel