Skip to content

Commit 6d3de91

Browse files
mkurc-anttmichalak
mkurc-ant
authored and
tmichalak
committed
Add testplans for the I3C core in target mode
Internal-tag: [#72243] Signed-off-by: Maciej Kurc <[email protected]>
1 parent 66bef3b commit 6d3de91

32 files changed

+2694
-6
lines changed

‎.github/workflows/build-docs.yml‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,22 +24,21 @@ jobs:
2424

2525
- name: Build Docs
2626
run: |
27-
pushd docs
27+
pushd testplans-template
2828
pip3 install -r requirements.txt
2929
TZ=UTC make html
3030
popd
31-
ls -lah docs/build
3231
3332
- name: Pack artifacts
3433
if: always()
3534
uses: actions/upload-artifact@v4
3635
with:
3736
name: docs
38-
path: ./docs/build
37+
path: ./testplans-template/build
3938

4039
- name: Deploy
4140
uses: peaceiris/actions-gh-pages@v4
4241
if: ${{ github.ref == 'refs/heads/main' }}
4342
with:
4443
github_token: ${{ secrets.GITHUB_TOKEN }}
45-
publish_dir: ./docs/build/html
44+
publish_dir: ./testplans-template/build/html

‎docs/source/dv.md‎

Lines changed: 66 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,70 @@
33
This chapter presents the available models and tools which are used for I3C verification.
44
The core is verified with [the Cocotb/Verilator + unit tests](https://github.com/chipsalliance/i3c-core/tree/main/verification/cocotb/block) and [the UVM test suite](https://github.com/chipsalliance/i3c-core/tree/main/verification/uvm_i3c).
55

6-
## Verification plan
6+
There are also non-public tests which utilize Avery I3C VIP framework. The tests include: `private_read`, `private_write` and `recovery` and verify operation of target mode private reads and writes and the secure firmware recovery flow respectively.
77

8-
The verification plans can be found [here](https://github.com/chipsalliance/i3c-core/tree/main/verification/uvm_i3c).
8+
## Testplans
9+
10+
This section contains testplans for the verification.
11+
12+
Definitions:
13+
* `testplan` - an organized collection of testpoints
14+
* `testpoint` - an actionable item, which can be turned into a test:
15+
* `name` - typically related to the tested feature
16+
* `desc` - detailed description; should contain description of the feature, configuration mode, stimuli, expected behavior.
17+
* `stage` - can be used to assign testpoints to milestones.
18+
* `tests` - names of implemented tests, which cover the testpoint. Relation test-testpoint can be many to many.
19+
* `tags` - additional tags that can be used to group testpoints
20+
21+
### Testplans for individual blocks
22+
23+
```{include} ../../verification/testplan/generated/bus_monitor.md
24+
```
25+
```{include} ../../verification/testplan/generated/bus_rx_flow.md
26+
```
27+
```{include} ../../verification/testplan/generated/bus_timers.md
28+
```
29+
```{include} ../../verification/testplan/generated/bus_tx_flow.md
30+
```
31+
```{include} ../../verification/testplan/generated/bus_tx.md
32+
```
33+
```{include} ../../verification/testplan/generated/ccc.md
34+
```
35+
```{include} ../../verification/testplan/generated/csr_sw_access.md
36+
```
37+
```{include} ../../verification/testplan/generated/descriptor_rx.md
38+
```
39+
```{include} ../../verification/testplan/generated/descriptor_tx.md
40+
```
41+
```{include} ../../verification/testplan/generated/drivers.md
42+
```
43+
```{include} ../../verification/testplan/generated/edge_detector.md
44+
```
45+
```{include} ../../verification/testplan/generated/flow_standby_i3c.md
46+
```
47+
```{include} ../../verification/testplan/generated/hci_queues.md
48+
```
49+
```{include} ../../verification/testplan/generated/tti_queues.md
50+
```
51+
```{include} ../../verification/testplan/generated/i3c_bus_monitor.md
52+
```
53+
```{include} ../../verification/testplan/generated/pec.md
54+
```
55+
```{include} ../../verification/testplan/generated/width_converter_8toN.md
56+
```
57+
```{include} ../../verification/testplan/generated/width_converter_Nto8.md
58+
```
59+
60+
### Testplans for the core
61+
62+
```{include} ../../verification/testplan/generated/target_ccc.md
63+
```
64+
```{include} ../../verification/testplan/generated/target_hdr.md
65+
```
66+
```{include} ../../verification/testplan/generated/target_interrupts.md
67+
```
68+
```{include} ../../verification/testplan/generated/target.md
69+
```
70+
```{include} ../../verification/testplan/generated/target_recovery.md
71+
```
72+
```{include} ../../verification/testplan/generated/target_reset.md

‎testplans-template/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.venv

‎testplans-template/Makefile‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
SPHINXOPTS ?=
2+
SPHINXBUILD ?= sphinx-build
3+
SOURCEDIR = source
4+
BUILDDIR = build
5+
6+
# Catch-all target: route all unknown targets to Sphinx using the "make mode" option.
7+
# $(O) is meant as a shortcut for $(SPHINXOPTS).
8+
%:
9+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎testplans-template/requirements.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Sphinx>=8.0
2+
https://github.com/antmicro/antmicro-sphinx-utils/archive/main.zip

‎testplans-template/source/conf.py‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# This file is execfile()d with the current directory set to its containing dir.
4+
#
5+
# Note that not all possible configuration values are present in this file.
6+
#
7+
# All configuration values have a default; values that are commented out
8+
# serve to show the default.
9+
#
10+
# Updated documentation of the configuration options is available at
11+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
12+
13+
from datetime import datetime
14+
15+
from antmicro_sphinx_utils.defaults import (
16+
numfig_format,
17+
extensions as default_extensions,
18+
myst_enable_extensions as default_myst_enable_extensions,
19+
myst_fence_as_directive as default_myst_fence_as_directive,
20+
antmicro_html,
21+
antmicro_latex
22+
)
23+
24+
# If extensions (or modules to document with autodoc) are in another directory,
25+
# add these directories to sys.path here. If the directory is relative to the
26+
# documentation root, use os.path.abspath to make it absolute, like shown here.
27+
#sys.path.insert(0, os.path.abspath('.'))
28+
29+
# -- General configuration -----------------------------------------------------
30+
31+
# General information about the project.
32+
project = u'I3C Core - testplan'
33+
basic_filename = u'i3c-core--testplan'
34+
authors = u'Antmicro'
35+
copyright = f'{authors}, {datetime.now().year}'
36+
37+
# The short X.Y version.
38+
version = ''
39+
# The full version, including alpha/beta/rc tags.
40+
release = ''
41+
42+
# This is temporary before the clash between myst-parser and immaterial is fixed
43+
sphinx_immaterial_override_builtin_admonitions = False
44+
45+
numfig = True
46+
47+
# If you need to add extensions just add to those lists
48+
extensions = default_extensions + ['sphinx.ext.extlinks']
49+
myst_enable_extensions = default_myst_enable_extensions
50+
myst_fence_as_directive = default_myst_fence_as_directive
51+
52+
myst_substitutions = {
53+
"project": project
54+
}
55+
56+
myst_heading_anchors = 4
57+
58+
today_fmt = '%Y-%m-%d'
59+
60+
todo_include_todos=False
61+
62+
# -- Options for HTML output ---------------------------------------------------
63+
64+
html_theme = 'sphinx_immaterial'
65+
66+
html_last_updated_fmt = today_fmt
67+
68+
html_show_sphinx = False
69+
70+
(
71+
html_logo,
72+
html_theme_options,
73+
html_context
74+
) = antmicro_html(pdf_url=f"{basic_filename}.pdf")
75+
76+
html_title = project
77+
78+
(
79+
latex_elements,
80+
latex_documents,
81+
latex_logo,
82+
latex_additional_files
83+
) = antmicro_latex(basic_filename, authors, project)
84+
85+
extlinks = {
86+
"rdl-docs": ("https://github.com/chipsalliance/i3c-core/blob/main/src/rdl/docs/README.md#%s", "%s")
87+
}

‎testplans-template/source/dv.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Design verification
2+
3+
This chapter presents the available models and tools which are used for I3C verification.
4+
The core is verified with [the Cocotb/Verilator + unit tests](https://github.com/chipsalliance/i3c-core/tree/main/verification/cocotb/block) and [the UVM test suite](https://github.com/chipsalliance/i3c-core/tree/main/verification/uvm_i3c).
5+
6+
There are also non-public tests which utilize Avery I3C VIP framework. The tests include: `private_read`, `private_write` and `recovery` and verify operation of target mode private reads and writes and the secure firmware recovery flow respectively.
7+
8+
## Testplans
9+
10+
This section contains testplans for the verification.
11+
12+
Definitions:
13+
* `testplan` - an organized collection of testpoints
14+
* `testpoint` - an actionable item, which can be turned into a test:
15+
* `name` - typically related to the tested feature
16+
* `desc` - detailed description; should contain description of the feature, configuration mode, stimuli, expected behavior.
17+
* `stage` - can be used to assign testpoints to milestones.
18+
* `tests` - names of implemented tests, which cover the testpoint. Relation test-testpoint can be many to many.
19+
* `tags` - additional tags that can be used to group testpoints
20+
21+
### Testplans for individual blocks
22+
23+
```{include} ../../verification/testplan/generated/bus_monitor.md
24+
```
25+
```{include} ../../verification/testplan/generated/bus_rx_flow.md
26+
```
27+
```{include} ../../verification/testplan/generated/bus_timers.md
28+
```
29+
```{include} ../../verification/testplan/generated/bus_tx_flow.md
30+
```
31+
```{include} ../../verification/testplan/generated/bus_tx.md
32+
```
33+
```{include} ../../verification/testplan/generated/ccc.md
34+
```
35+
```{include} ../../verification/testplan/generated/csr_sw_access.md
36+
```
37+
```{include} ../../verification/testplan/generated/descriptor_rx.md
38+
```
39+
```{include} ../../verification/testplan/generated/descriptor_tx.md
40+
```
41+
```{include} ../../verification/testplan/generated/drivers.md
42+
```
43+
```{include} ../../verification/testplan/generated/edge_detector.md
44+
```
45+
```{include} ../../verification/testplan/generated/flow_standby_i3c.md
46+
```
47+
```{include} ../../verification/testplan/generated/hci_queues.md
48+
```
49+
```{include} ../../verification/testplan/generated/tti_queues.md
50+
```
51+
```{include} ../../verification/testplan/generated/i3c_bus_monitor.md
52+
```
53+
```{include} ../../verification/testplan/generated/pec.md
54+
```
55+
```{include} ../../verification/testplan/generated/width_converter_8toN.md
56+
```
57+
```{include} ../../verification/testplan/generated/width_converter_Nto8.md
58+
```
59+
60+
### Testplans for the core
61+
62+
```{include} ../../verification/testplan/generated/target_ccc.md
63+
```
64+
```{include} ../../verification/testplan/generated/target_hdr.md
65+
```
66+
```{include} ../../verification/testplan/generated/target_interrupts.md
67+
```
68+
```{include} ../../verification/testplan/generated/target.md
69+
```
70+
```{include} ../../verification/testplan/generated/target_recovery.md
71+
```
72+
```{include} ../../verification/testplan/generated/target_reset.md

‎testplans-template/source/index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# {{project}}
2+
3+
```{toctree}
4+
:caption: Verification
5+
:maxdepth: 2
6+
7+
dv
8+
```

‎verification/testplan/block/bus_monitor.hjson‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
name: bus_monitor
3+
testpoints:
4+
[
5+
{
6+
name: get_status
7+
desc:
8+
'''
9+
Tests operation of the bus_monitor module along with its sub-modules.
10+
Performs a number of I3C transactions between a simulated controller
11+
and a simulated target. Counts start, repeated start and stop events
12+
reported by bus_monitor. Verifies that the counts match what's expected.
13+
'''
14+
stage: N.A.
15+
tests:
16+
[
17+
test_get_status
18+
]
19+
tags:
20+
[
21+
bus_monitor
22+
]
23+
}
24+
]
25+
}

‎verification/testplan/block/bus_rx_flow.hjson‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
{
2+
name: bus_rx_flow
3+
testpoints:
4+
[
5+
{
6+
name: multiple_bit_reads
7+
desc:
8+
'''
9+
Drives SCL line with a steady clock, issues multiple bit read
10+
requests, verifies that the module returns correct data sampled
11+
from the SDA line.
12+
'''
13+
stage: N.A.
14+
tests:
15+
[
16+
test_multiple_bit_reads
17+
]
18+
tags:
19+
[
20+
bus_rx_flow
21+
]
22+
}
23+
{
24+
name: multiple_byte_reads
25+
desc:
26+
'''
27+
Drives SCL line with a steady clock, issues multiple byte read
28+
requests, verifies that the module returns correct data sampled
29+
from the SDA line.
30+
'''
31+
stage: N.A.
32+
tests:
33+
[
34+
test_multiple_byte_reads
35+
]
36+
tags:
37+
[
38+
bus_rx_flow
39+
]
40+
}
41+
]
42+
}

0 commit comments

Comments
 (0)