{"id":8023,"library":"cocotb","title":"cocotb","description":"cocotb is a coroutine-based cosimulation library that enables writing Verilog and VHDL testbenches in Python. It provides a robust framework for verifying hardware designs by interacting directly with commercial and open-source HDL simulators. The current version is 2.0.1, with major releases typically aligning with significant architectural changes, moving towards more Pythonic async/await patterns.","status":"active","version":"2.0.1","language":"en","source_language":"en","source_url":"https://github.com/cocotb/cocotb","tags":["HDL","cosimulation","verification","FPGA","ASIC","Verilog","VHDL","hardware"],"install":[{"cmd":"pip install cocotb","lang":"bash","label":"Install cocotb"}],"dependencies":[],"imports":[{"note":"The @cocotb.test() decorator is the primary entry point for tests.","symbol":"test","correct":"import cocotb"},{"symbol":"Timer","correct":"from cocotb.triggers import Timer"},{"symbol":"Clock","correct":"from cocotb.clock import Clock"},{"note":"The TestFactory class was moved to cocotb.regression in cocotb 2.0.0.","wrong":"from cocotb.test import TestFactory","symbol":"TestFactory","correct":"from cocotb.regression import TestFactory"}],"quickstart":{"code":"import cocotb\nfrom cocotb.triggers import Timer, RisingEdge\nfrom cocotb.clock import Clock\nimport os\n\n@cocotb.test()\nasync def my_first_test(dut):\n    \"\"\"Attempt to verify D flip-flop functionality\"\"\"\n    cocotb.log.info(\"Starting my_first_test\")\n\n    # Access signals on the DUT (Design Under Test)\n    # These signal names (clk, i, q) correspond to ports in an HDL design\n    clk = dut.clk\n    i = dut.i\n    q = dut.q\n\n    # Set initial values\n    i.value = 0\n    await Timer(1, units=\"ns\")\n\n    # Create a clock\n    clock = Clock(clk, 10, units=\"ns\")  # 10 ns period, 100MHz\n    cocotb.start_soon(clock.start())\n\n    # Assert reset if available (common in DFF designs)\n    if hasattr(dut, 'reset_n'): # Check if 'reset_n' signal exists on DUT\n        dut.reset_n.value = 0\n        await RisingEdge(clk)\n        await RisingEdge(clk) # Ensure reset holds for a bit\n        dut.reset_n.value = 1\n        await RisingEdge(clk)\n    else:\n        await RisingEdge(clk) # Just advance clock if no reset\n\n    # Test case 1: input 0, expect output 0 (after clock edge)\n    i.value = 0\n    await RisingEdge(clk)\n    cocotb.log.info(f\"Input: {i.value}, Output: {q.value}\")\n    assert q.value == 0, f\"Expected q=0, got {q.value}\"\n\n    # Test case 2: input 1, expect output 0 (output lags input by one clock cycle)\n    i.value = 1\n    await RisingEdge(clk)\n    cocotb.log.info(f\"Input: {i.value}, Output: {q.value}\")\n    assert q.value == 0, f\"Expected q=0, got {q.value}\" \n\n    # Test case 3: input 1, expect output 1 (on the next clock edge)\n    await RisingEdge(clk)\n    cocotb.log.info(f\"Input: {i.value}, Output: {q.value}\")\n    assert q.value == 1, f\"Expected q=1, got {q.value}\"\n\n    cocotb.log.info(\"Test finished\")","lang":"python","description":"This Python code defines a basic `cocotb` test for a D flip-flop (DFF) with clock and data inputs (`clk`, `i`) and a data output (`q`). To run this, you need a corresponding Verilog/VHDL DFF design file (e.g., `dff.v` or `dff.vhdl`) and a `Makefile` to integrate with an HDL simulator (like Icarus Verilog or GHDL). The `Makefile` typically specifies `TOPLEVEL`, `TOPLEVEL_LANG`, and `SIM` variables, and orchestrates the simulation. For simpler execution, `pytest-cocotb` can also be used."},"warnings":[{"fix":"Update test functions to `async def` and use `@cocotb.test()`. For parameterized tests, import `TestFactory` from `cocotb.regression`. Review cocotb 2.0 migration guides for full details.","message":"cocotb 2.0 introduced significant breaking changes, migrating towards native Python `async`/`await` syntax. The `@cocotb.coroutine` decorator was removed (use `async def` with `@cocotb.test()`), `cocotb.test.TestFactory` moved to `cocotb.regression.TestFactory`, and `cocotb.result` module was removed.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Install a compatible HDL simulator for your target HDL (Verilog or VHDL) and ensure its executable is in your system's PATH environment variable.","message":"cocotb itself is a Python library, but it requires an external HDL simulator (e.g., Icarus Verilog, GHDL, QuestaSim, VCS) to run any tests. This simulator must be installed and accessible in your system's PATH.","severity":"gotcha","affected_versions":"all"},{"fix":"Carefully review the `cocotb` documentation on `Makefile` setup. Ensure `TOPLEVEL` matches your HDL top module, `TOPLEVEL_LANG` is correct, `SIM` points to an installed simulator, and `PYTHONPATH` includes the directory containing your Python test files.","message":"Running `cocotb` tests typically relies on a `Makefile` to configure the simulation environment (e.g., `TOPLEVEL`, `TOPLEVEL_LANG`, `SIM`, `VERILOG_SOURCES`/`VHDL_SOURCES`, `PYTHONPATH`) and invoke the simulator. Incorrect `Makefile` configuration is a common source of issues.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure all calls to `cocotb` triggers or other `async` functions are preceded by the `await` keyword. If using an older `cocotb` version, ensure `yield` is used for `@cocotb.coroutine` functions.","message":"All `cocotb` triggers (e.g., `Timer`, `RisingEdge`) and asynchronous cocotb functions must be `await`ed within an `async` test function. Forgetting `await` will not pause the simulation and can lead to unexpected behavior or tests that complete instantly.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install cocotb` in your active Python environment. If using a `Makefile`, ensure `PYTHONPATH` is correctly set to include the directory containing your Python test file(s).","cause":"The Python environment running the test does not have `cocotb` installed or the `PYTHONPATH` is not correctly configured to find the test modules.","error":"ModuleNotFoundError: No module named 'cocotb'"},{"fix":"Ensure your test functions are decorated with `@cocotb.test()`. Verify the `Makefile`'s `MODULE` variable points to the correct Python module (e.g., `MODULE=test_my_design`) and `PYTHONPATH` includes the directory containing `test_my_design.py`.","cause":"The `cocotb` test runner could not find any functions decorated with `@cocotb.test()` in the specified test modules, or the Python test modules were not correctly loaded.","error":"ERROR: No tests discovered"},{"fix":"Install the required HDL simulator (e.g., Icarus Verilog for Verilog, GHDL for VHDL). Ensure its executable is added to your system's PATH environment variable.","cause":"The HDL simulator specified in the `SIM` variable of your `Makefile` (e.g., `ghdl`, `iverilog`, `vsim`) is not installed or not accessible in your system's PATH.","error":"ERROR: [simulator] command not found"},{"fix":"Change your import statement from `from cocotb.test import TestFactory` to `from cocotb.regression import TestFactory`.","cause":"You are attempting to import `TestFactory` from `cocotb.test` in `cocotb` version 2.0.0 or later.","error":"AttributeError: module 'cocotb.test' has no attribute 'TestFactory'"}]}