Add documentation on how to test COCOTB_TRUST_INERTIAL_WRITES

docs/source/building.rst

@@ -151,6 +151,21 @@ Cocotb
     but instead trusting that the simulator's inertial write mechanism is correct.
     This allows cocotb to avoid a VPI callback into Python to apply writes.
 
+    .. note::
+        This flag is enabled by default for GHDL and NVC simulators.
+        More simulators may enable this flag by default in the future as they are gradually updated to properly apply inertial writes according to the respective standard.
+
+    .. note::
+        To test if your simulator behaves correctly with your simulator and version,
+        first clone down the cocotb github repo and run:
+
+        .. code-block::
+
+            cd tests/test_cases/test_inertial_writes
+            make simulator_test SIM=<your simulator here> TOPLEVEL_LANG=<vhdl or verilog>
+
+        If the tests pass, your simulator and version apply inertial writes as expected and you can turn on :envvar:`COCOTB_TRUST_INERTIAL_WRITES`.
+
 
 Regression Manager
 ~~~~~~~~~~~~~~~~~~

src/cocotb/_conf.py

@@ -3,4 +3,4 @@
 # SPDX-License-Identifier: BSD-3-Clause
 import os
 
-_trust_inertial = "COCOTB_TRUST_INERTIAL_WRITES" in os.environ
+_trust_inertial = bool(int(os.environ.get("COCOTB_TRUST_INERTIAL_WRITES", "0")))

src/cocotb_tools/makefiles/Makefile.inc

@@ -160,3 +160,11 @@ endef
 else
     $(warning Including Makefile.inc from a user makefile is a no-op and deprecated. Remove the Makefile.inc inclusion from your makefile, and only leave the Makefile.sim include.)
 endif # COCOTB_MAKEFILE_INC_INCLUDED
+
+ifneq ($(filter $(SIM),nvc ghdl),)
+  COCOTB_TRUST_INERTIAL_WRITES ?= 1
+else
+  COCOTB_TRUST_INERTIAL_WRITES ?= 0
+endif
+
+export COCOTB_TRUST_INERTIAL_WRITES

tests/test_cases/test_inertial_writes/Makefile

@@ -4,9 +4,12 @@
 
 .PHONY: override_tests
 override_tests:
-	$(MAKE) sim
+	$(MAKE) COCOTB_TRUST_INERTIAL_WRITES=0 sim
 	$(MAKE) COCOTB_TRUST_INERTIAL_WRITES=1 sim
 
 MODULE := inertial_writes_tests
 
 include ../../designs/sample_module/Makefile
+
+simulator_test:
+	$(MAKE) COCOTB_TRUST_INERTIAL_WRITES=1 COCOTB_SIMULATOR_TEST=1 sim

tests/test_cases/test_inertial_writes/inertial_writes_tests.py

@@ -13,6 +13,8 @@
 vhdl = os.environ.get("TOPLEVEL_LANG", "verilog").lower() == "vhdl"
 verilog = os.environ.get("TOPLEVEL_LANG", "verilog").lower() == "verilog"
 
+_simulator_test = "COCOTB_SIMULATOR_TEST" in os.environ
+
 
 # Riviera's VHPI is skipped in all tests when COCOTB_TRUST_INERTIAL_WRITES mode is enable
 # because it behaves extremely erratically. Their scheduler has some serious issues.
@@ -23,7 +25,8 @@
     expect_error=SimTimeoutError
     if (SIM_NAME.startswith("verilator") and _trust_inertial)
     else (),
-    skip=SIM_NAME.startswith("riviera") and vhdl and _trust_inertial,
+    skip=not _simulator_test
+    and (SIM_NAME.startswith("riviera") and vhdl and _trust_inertial),
 )
 async def test_writes_on_timer_seen_on_edge(dut):
     # steady state
@@ -37,7 +40,9 @@ async def test_writes_on_timer_seen_on_edge(dut):
     await with_timeout(RisingEdge(dut.clk), 10, "ns")
 
 
-if _trust_inertial:
+if _simulator_test:
+    expect_fail = False
+elif _trust_inertial:
     expect_fail = False
 elif SIM_NAME.startswith(("riviera", "modelsim")) and vhdl:
     expect_fail = False
@@ -53,7 +58,8 @@ async def test_writes_on_timer_seen_on_edge(dut):
 # This test will fail because the ReadWrite write applicator task does inertial writes of it's own.
 @cocotb.test(
     expect_fail=expect_fail,
-    skip=SIM_NAME.startswith("riviera") and vhdl and _trust_inertial,
+    skip=not _simulator_test
+    and (SIM_NAME.startswith("riviera") and vhdl and _trust_inertial),
 )
 async def test_read_back_in_readwrite(dut):
     # steady state
@@ -68,7 +74,9 @@ async def test_read_back_in_readwrite(dut):
     assert dut.clk.value == 1
 
 
-if not _trust_inertial:
+if _simulator_test:
+    expect_fail = False
+elif not _trust_inertial:
     expect_fail = False
 elif SIM_NAME.startswith(("icarus", "verilator")):
     expect_fail = True
@@ -82,7 +90,8 @@ async def test_read_back_in_readwrite(dut):
 # Icarus, Questa VPI, and Xcelium VHPI inertial writes aren't actually inertial.
 @cocotb.test(
     expect_fail=expect_fail,
-    skip=SIM_NAME.startswith("riviera") and vhdl and _trust_inertial,
+    skip=not _simulator_test
+    and (SIM_NAME.startswith("riviera") and vhdl and _trust_inertial),
 )
 async def test_writes_dont_update_hdl_this_delta(dut):
     cocotb.start_soon(Clock(dut.clk, 10, "ns").start())