################# Welcome to cocotb ################# .. This documentation tries to follow https://diataxis.fr/ Other media about the same topic: - https://ep2018.europython.eu/media/conference/slides/get-your-documentation-right.pdf - https://www.youtube.com/watch?v=t4vKPhjcMZg - A good example: http://docs.django-cms.org/en/latest/contributing/documentation.html#contributing-documentation See also https://github.com/cocotb/cocotb/wiki/Howto:-Writing-Documentation *************** What is cocotb? *************** cocotb enables users to test and verify their chip designs in `Python `_ as opposed to VHDL, (System)Verilog, or other EDA-specific languages. *********** Why cocotb? *********** cocotb was specifically designed to lower the overhead of creating a testbench. But it is still capable of -- and encourages -- reuse and randomized testing for building larger, more complex testbenches. Python offers many advantages over languages traditionally used for test and verification, such as VHDL or (System)Verilog. * Writing Python is **fast** - it's a very productive language. * It's **easy** to interface to other languages from Python. * Python has a huge library of existing code to **reuse**. * Python is **interpreted** - tests can be edited and re-run without having to recompile the design or the testbench. * Python is **popular** - far more engineers know Python than SystemVerilog or VHDL. cocotb supports :ref:`most popular simulators ` on :ref:`most relevant platforms `. When writing cocotb testbenches, users will typically not have to write any :term:`HDL`. cocotb has built-in support for integrating with continuous integration systems, such as Jenkins, GitLab, etc. through standardized, machine-readable test reporting formats. cocotb is provided free of charge under the `BSD License `_ and is hosted publicly on `GitHub `_. ********************* How does cocotb work? ********************* cocotb is a **co**\ routine-based **co**\ simulation **t**\ est\ **b**\ ench environment. This means that when the design is simulated, cocotb runs as a cosimulation using one of the procedural interfaces (:term:`VPI`, :term:`VHPI`, or :term:`FLI`). A Python interpreter is embedded into the running simulator process to provide a Python execution environment. A :doc:`Python library ` and `coroutine `_\ -based concurrency system are built on top of the procedural interfaces to interact with the simulated design in a Pythonic way. .. image:: diagrams/svg/cocotb_overview.svg ************** Who is cocotb? ************** cocotb is a Free and Open Source project and is developed collaboratively by its `contributors `_ and :ref:`maintainers`. cocotb has many serious commercial users and sponsors. See `cocotb.org `_ for more details. ********************* How do I get started? ********************* Read the :doc:`install` instructions to get cocotb installed and set up. Then follow the :doc:`first_steps` tutorial to get a simple test running. .. Tutorials - lessons that take the reader by the hand through a series of steps to complete a project (Example: kid cooking; learning-oriented) - learning by doing - getting started - inspiring confidence - repeatability - immediate sense of achievement - concreteness, not abstraction - minimum necessary explanation - no distractions .. toctree:: :maxdepth: 1 :caption: Tutorials :name: tutorials :hidden: install first_steps writing_testbenches scheduler runner pytest_plugin .. Examples - completed and working projects that demonstrate how cocotb can be used to solve a particular problem (Example: testing a mixed language design; study-oriented) - explain the solution, don't just present it - not a step-by-step guide - not interactive with the user - mention design considerations, alternatives, and trade-offs .. toctree:: :maxdepth: 1 :caption: Examples :name: examples :hidden: matrix_multiplier mixed_language mixed_signal analog_model more_examples .. How-To Guides - guides that take the reader through the steps required to solve a common problem (Example: recipe; problem-oriented) - a series of steps - a focus on the goal - addressing a specific question - no unnecessary explanation - a little flexibility - practical usability - good naming .. toctree:: :maxdepth: 1 :caption: How-to Guides :name: howto_guides :hidden: install_devel custom_flows extensions junit upgrade-2.0 update_indexing rotating_logger separating_logs profiling coverage .. todo:: - Add IPython section - How to deal with existing Verification IP? - Point to https://github.com/cocotb/cocotb/wiki/Code-Examples .. Explanation (Background, Discussions) - discussions that clarify and illuminate a particular topic (Example: history of cooking; understanding-oriented) - giving context - explaining why - multiple examples, alternative approaches - making connections - no instruction or technical description .. toctree:: :maxdepth: 1 :caption: Key topics :name: key_topics :hidden: troubleshooting timing_model build_systems .. todo:: - Move section "How does cocotb work?" from Introduction to here - Add GPI section .. Reference - technical descriptions of the machinery and its operation (Example: Wikipedia pages of ingredients; information-oriented) - structure - consistency - description - accuracy .. toctree:: :maxdepth: 1 :caption: Reference :name: reference :hidden: building Python Code Library Reference Pytest Plugin Reference JUnit Tests Report Reference GPI Library Reference simulator_support platform_support refcard .. toctree:: :maxdepth: 1 :caption: Development & Community :name: development_community :hidden: support contributing developing maintaining contributors roadmap release_notes further_resources .. todo:: - merge `further_resources` into Contributing .. toctree:: :maxdepth: 1 :caption: Index :name: index :hidden: Classes, Methods, Variables etc. Python Modules glossary