Add testplans for I3C core

Signed-off-by: Maciej Kurc <[email protected]>

.github/workflows/build-docs.yml

@@ -22,6 +22,12 @@ jobs:
       - name: Setup repository
         uses: actions/checkout@v4
 
+      - name: Generate VP
+        run: |
+          export I3C_ROOT_DIR="`pwd`"
+          pip3 install git+https://github.com/antmicro/testplanner.git
+          REPO_URL="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/tree/$GITHUB_REF_NAME/" make verification-docs
+
       - name: Build Docs
         run: |
           pushd doc

Makefile

@@ -15,6 +15,7 @@ BLOCK_VERIF_DIR     := $(COCOTB_VERIF_DIR)/block
 TOP_VERIF_DIR       := $(COCOTB_VERIF_DIR)/top
 TOOL_VERIF_DIR      := $(VERIFICATION_DIR)/tools/
 UVM_VERIF_DIR       := $(VERIFICATION_DIR)/uvm_i3c/
+TESTPLAN_DIR        := $(VERIFICATION_DIR)/testplan
 
 TOOL_DIR            := $(I3C_ROOT_DIR)/tools/
 UVM_TOOL_DIR        := $(TOOL_DIR)/uvm/
@@ -25,6 +26,7 @@ CALIPTRA_ROOT       ?= $(THIRD_PARTY_DIR)/caliptra-rtl## Path: caliptra-rtl repo
 # TODO: Connect to version selection in tools/simulators/
 UVM_DIR             ?= $(VERILATOR_UVM_DIR)/## Select UVM version
 SIMULATOR           ?= verilator## Supported: verilator, dsim, questa, vcs
+REPO_URL            ?= https://github.com/chipsalliance/i3c-core/tree/main/
 
 NUM_PROC            := $$(($$(nproc)-1))
 # Environment variables
@@ -132,6 +134,12 @@ tests-uvm-debug: config ## Run debugging I3C Core UVM tests with nox
 tests-tool: ## Run all tool tests
 	cd $(TOOL_VERIF_DIR) && $(PYTHON) -m nox -k "verify" --no-venv
 
+BLOCKS_VERIFICATION_PLANS = $(shell find $(TESTPLAN_DIR) -type f -name "*.hjson" ! -name "target*.hjson" -printf "%P\n")
+CORE_VERIFICATION_PLANS = $(shell find $(TESTPLAN_DIR) -type f -name "*target*.hjson" -printf "%P\n")
+verification-docs:
+	cd $(TESTPLAN_DIR) && testplanner $(BLOCKS_VERIFICATION_PLANS) -ot $(TESTPLAN_DIR)/generated/testplans_blocks.md --project-root $(I3C_ROOT_DIR) --testplan-file-map $(TESTPLAN_DIR)/source-maps.yml --source-url-prefix $(REPO_URL)
+	cd $(TESTPLAN_DIR) && testplanner $(CORE_VERIFICATION_PLANS) -ot $(TESTPLAN_DIR)/generated/testplans_core.md --project-root $(I3C_ROOT_DIR) --testplan-file-map $(TESTPLAN_DIR)/source-maps.yml --source-url-prefix $(REPO_URL)
+
 #
 # Utilities
 #

doc/source/dv.md

@@ -21,9 +21,11 @@ Definitions:
 ### Testplans for individual blocks
 
 ```{include} ../../verification/testplan/generated/testplans_blocks.md
+:heading-offset: 2
 ```
 
 ### Testplans for the core
 
 ```{include} ../../verification/testplan/generated/testplans_core.md
+:heading-offset: 2
 ```

requirements.txt

@@ -11,6 +11,7 @@ cocotb-coverage==1.2.0
 cocotb-test==0.2.5
 cocotbext-axi==0.1.24
 -e git+https://github.com/alexforencich/cocotbext-i2c@3b32eedc15302f1299a23bb35aa669fffad2ca22#egg=cocotbext_i2c
+git+https://github.com/antmicro/testplanner.git@bbf374a
 -e ${I3C_ROOT_DIR}/third_party/cocotbext-i3c
 -e ${I3C_ROOT_DIR}/tools/nox_utils
 -e ${I3C_ROOT_DIR}/tools/cocotb_helpers

verification/cocotb/block/i2c/test_write.py

@@ -61,7 +61,7 @@ async def test_write_sequence(
 
 
 @cocotb.test()
-async def run_test(dut):
+async def test_write(dut):
     TARGET_ADDR = 0x18
     CLK_SPEED = 400e3
 

verification/cocotb/block/i2c_controller_fsm/test_mem_rw.py

@@ -17,7 +17,7 @@
 
 
 @cocotb.test()
-async def run_test(dut):
+async def test_mem_rw(dut):
     """
     Executes random read and writes while checking data on the I2C FSM.
     """

verification/cocotb/block/i2c_standby_controller/test_read.py

@@ -102,7 +102,7 @@ def ord_or_null(idx):
 
 
 @cocotb.test()
-async def run_test(dut):
+async def test_read(dut):
     TARGET_ADDR = 0x18
     CLK_SPEED = 400e3
 

verification/cocotb/block/i2c_standby_controller/test_wr_restart_rd.py

@@ -159,7 +159,7 @@ async def master_write_read():
 
 
 @cocotb.test()
-async def run_test(dut):
+async def test_wr_restart_rd(dut):
     TARGET_ADDR = 12
     CLK_SPEED = 400000
 

verification/cocotb/block/i2c_target_fsm/test_mem_r.py

@@ -75,7 +75,7 @@ async def test_read_sequence(dut: Any, address: int, master: I2cMaster, data: by
 
 
 @cocotb.test()
-async def run_test(dut):
+async def test_mem_r(dut):
     TARGET_ADDR = 12
     CLK_SPEED = 400000
 

verification/cocotb/block/i2c_target_fsm/test_mem_w.py

@@ -48,7 +48,7 @@ def MatchWDataExact(value, dut):
 
 
 @cocotb.test()
-async def run_test(dut):
+async def test_mem_w(dut):
     TARGET_ADDR = 12
     CLK_SPEED = 400000
 

verification/cocotb/block/lib_adapter/test_csr_sw_access.py

@@ -65,7 +65,7 @@ async def write_csr_and_verify(
 
 # Common test cases for frontend adapters:
 @cocotb.test()
-async def run_read_hci_version_csr(dut: SimHandleBase):
+async def test_read_hci_version_csr(dut: SimHandleBase):
     """Run test to read HCI version register."""
 
     tb = get_frontend_bus_if()(dut)
@@ -78,7 +78,7 @@ async def run_read_hci_version_csr(dut: SimHandleBase):
 
 
 @cocotb.test()
-async def run_read_pio_section_offset(dut: SimHandleBase):
+async def test_read_pio_section_offset(dut: SimHandleBase):
     """Run test to read PIO section offset register."""
 
     tb = get_frontend_bus_if()(dut)
@@ -88,7 +88,7 @@ async def run_read_pio_section_offset(dut: SimHandleBase):
 
 
 @cocotb.test()
-async def run_write_to_controller_device_addr(dut: SimHandleBase):
+async def test_write_to_controller_device_addr(dut: SimHandleBase):
     """Run test to write & read from Controller Device Address."""
 
     tb = get_frontend_bus_if()(dut)
@@ -102,7 +102,7 @@ async def run_write_to_controller_device_addr(dut: SimHandleBase):
 
 
 @cocotb.test()
-async def run_write_should_not_affect_ro_csr(dut: SimHandleBase):
+async def test_write_should_not_affect_ro_csr(dut: SimHandleBase):
     """Run test to write to RO HC Capabilities."""
 
     tb = get_frontend_bus_if()(dut)
@@ -118,7 +118,7 @@ async def run_write_should_not_affect_ro_csr(dut: SimHandleBase):
 
 
 @cocotb.test()
-async def run_sequence_csr_read(dut: SimHandleBase):
+async def test_sequence_csr_read(dut: SimHandleBase):
     tb = get_frontend_bus_if()(dut)
     await tb.register_test_interfaces()
 
@@ -152,7 +152,7 @@ async def run_sequence_csr_read(dut: SimHandleBase):
 
 
 @cocotb.test()
-async def run_sequence_csr_write(dut: SimHandleBase):
+async def test_sequence_csr_write(dut: SimHandleBase):
     tb = get_frontend_bus_if()(dut)
     await tb.register_test_interfaces()
 

verification/cocotb/block/lib_hci_queues/test_clear.py

@@ -11,7 +11,7 @@
 
 
 @cocotb.test()
-async def run_clear_on_nonempty_resp_queue(dut: SimHandleBase):
+async def test_clear_on_nonempty_resp_queue(dut: SimHandleBase):
     """
     Issue Response queue clear through RESET_CONTROL and verify the newly enqueued
     response will be returned on the read
@@ -39,7 +39,7 @@ async def run_clear_on_nonempty_resp_queue(dut: SimHandleBase):
 
 
 @cocotb.test()
-async def run_clear_on_nonempty_cmd_queue(dut: SimHandleBase):
+async def test_clear_on_nonempty_cmd_queue(dut: SimHandleBase):
     """
     Issue Command queue clear through RESET_CONTROL and verify the newly enqueued
     command will be returned on the read
@@ -66,7 +66,7 @@ async def run_clear_on_nonempty_cmd_queue(dut: SimHandleBase):
 
 
 @cocotb.test()
-async def run_clear_on_nonempty_rx_queue(dut: SimHandleBase):
+async def test_clear_on_nonempty_rx_queue(dut: SimHandleBase):
     """
     Issue RX queue clear through RESET_CONTROL and verify the newly enqueued
     data will be returned on the read
@@ -91,7 +91,7 @@ async def run_clear_on_nonempty_rx_queue(dut: SimHandleBase):
 
 
 @cocotb.test()
-async def run_clear_on_nonempty_tx_queue(dut: SimHandleBase):
+async def test_clear_on_nonempty_tx_queue(dut: SimHandleBase):
     """
     Issue TX queue clear through RESET_CONTROL and verify the newly enqueued
     data will be returned on the read
@@ -116,7 +116,7 @@ async def run_clear_on_nonempty_tx_queue(dut: SimHandleBase):
 
 
 @cocotb.test()
-async def run_clear_on_nonempty_ibi_queue(dut: SimHandleBase):
+async def test_clear_on_nonempty_ibi_queue(dut: SimHandleBase):
     """
     Issue IBI queue clear through RESET_CONTROL and verify the newly enqueued
     data will be returned on the read

verification/cocotb/block/lib_hci_queues/test_empty.py

@@ -20,50 +20,50 @@ async def should_be_empty_after_rst(dut: SimHandleBase, if_name: str, queue: str
 
 
 @cocotb.test()
-async def run_cmd_capacity_status_test(dut: SimHandleBase):
+async def test_cmd_capacity_status(dut: SimHandleBase):
     await should_be_empty_after_rst(dut, "hci", "cmd")
 
 
 @cocotb.test()
-async def run_rx_capacity_status_test(dut: SimHandleBase):
+async def test_rx_capacity_status(dut: SimHandleBase):
     await should_be_empty_after_rst(dut, "hci", "rx")
 
 
 @cocotb.test()
-async def run_resp_capacity_status_test(dut: SimHandleBase):
+async def test_resp_capacity_status(dut: SimHandleBase):
     await should_be_empty_after_rst(dut, "hci", "resp")
 
 
 @cocotb.test()
-async def run_tx_capacity_status_test(dut: SimHandleBase):
+async def test_tx_capacity_status(dut: SimHandleBase):
     await should_be_empty_after_rst(dut, "hci", "tx")
 
 
 @cocotb.test()
-async def run_ibi_capacity_status_test(dut: SimHandleBase):
+async def test_ibi_capacity_status(dut: SimHandleBase):
     await should_be_empty_after_rst(dut, "hci", "ibi")
 
 
 @cocotb.test()
-async def run_tti_tx_desc_capacity_status_test(dut: SimHandleBase):
+async def test_tti_tx_desc_capacity_status(dut: SimHandleBase):
     await should_be_empty_after_rst(dut, "tti", "tx_desc")
 
 
 @cocotb.test()
-async def run_tti_rx_capacity_status_test(dut: SimHandleBase):
+async def test_tti_rx_capacity_status(dut: SimHandleBase):
     await should_be_empty_after_rst(dut, "tti", "rx")
 
 
 @cocotb.test()
-async def run_tti_rx_desc_capacity_status_test(dut: SimHandleBase):
+async def test_tti_rx_desc_capacity_status(dut: SimHandleBase):
     await should_be_empty_after_rst(dut, "tti", "rx_desc")
 
 
 @cocotb.test()
-async def run_tti_tx_capacity_status_test(dut: SimHandleBase):
+async def test_tti_tx_capacity_status(dut: SimHandleBase):
     await should_be_empty_after_rst(dut, "tti", "tx")
 
 
 @cocotb.test()
-async def run_tti_ibi_capacity_status_test(dut: SimHandleBase):
+async def test_tti_ibi_capacity_status(dut: SimHandleBase):
     await should_be_empty_after_rst(dut, "tti", "ibi")