[dif] Update DIF milestones and descriptions
The DIF milestones were out of date. This commit addresses (and a task
in #10504).
Signed-off-by: Timothy Trippel <ttrippel@google.com>
diff --git a/doc/project/checklist.md b/doc/project/checklist.md
index 9aba662..86967bc 100644
--- a/doc/project/checklist.md
+++ b/doc/project/checklist.md
@@ -600,15 +600,12 @@
### DIF_EXISTS
-`dif_<ip>.h` and, optionally, `dif_<ip>.c` exist in `sw/device/lib/dif`.
+Autogenerated IRQ and Alert DIFs have been created with the `util/make_new_dif.py` tool, and exist in `sw/device/lib/dif/autogen/`.
+Additionally, a header file, `dif_<ip>.h` and, optionally, `dif_<ip>.c` exist in `sw/device/lib/dif/`.
### DIF_USED_IN_TREE
-All existing non-production code in the tree which uses the device does so via the DIF or a production driver.
-
-### DIF_TEST_UNIT
-
-Software unit tests exist for the DIF in `sw/device/tests/dif` named `dif_<ip>_unittest.cc`.
+All existing **non-production** code in the tree which uses the device does so via the DIF or a production driver.
### DIF_TEST_SMOKE
@@ -617,38 +614,17 @@
This should perform a basic test of the main datapath of the hardware module by the embedded core, via the DIF, and should be able to be run on all OpenTitan platforms (including FPGA, simulation, and DV).
This test will be shared with DV.
-Smoke tests are for diagnosing major issues in both software and hardware, and with this in mind, they should execute quickly.
-Initially we expect this kind of test to be written by hardware designers for debugging issues during module development.
-This happens long before a DIF is implemented, so there are no requirements on how these should work, though we suggest they are placed in `sw/device/tests/<ip>/<ip>.c` as this has been the convention until now.
-Later, when a DIF is written, the DIF author is responsible for updating this test to use the DIF, and for moving this test into the aforementioned location.
-
## S2
For a transition from S1 to S2, the following items are expected to be completed.
-### DIF_FEATURES
-
-The DIF has functions to cover all specified hardware functionality.
-
-### DIF_HW_USAGE_REVIEWED
-
-The DIF's usage of its respective IP device has been reviewed by the device's hardware designer.
-
### DIF_HW_FEATURE_COMPLETE
The DIF's respective device IP is at least stage D2.
-### DIF_HW_PARAMS
+### DIF_FEATURES
-The DIF uses automatically generated HW parameters and register definitions.
-
-### DIF_DOC_HW
-
-The HW IP Programmer's guide references specific DIF APIs that can be used for operations.
-
-### DIF_CODE_STYLE
-
-The DIF follows DIF-specific guidelines in [`sw/device/lib/dif/README.md`]({{< relref "sw/device/lib/dif/README.md" >}}) and the OpenTitan C style guidelines.
+The DIF has functions to cover all specified hardware functionality.
### DIF_DV_TESTS
@@ -666,12 +642,17 @@
The DIF's respective device IP is at least stage V3.
-### DIF_REVIEW_C_STABLE
+### DIF_DOC_HW
-The C interface and its implementation have been fully re-reviewed, with a view to the interface not changing in future.
+The HW IP Programmer's guide references specific DIF APIs that can be used for operations.
-### DIF_TEST_UNIT_COMPLETE
+### DIF_CODE_STYLE
+The DIF follows DIF-specific guidelines in [`sw/device/lib/dif/README.md`]({{< relref "sw/device/lib/dif/README.md" >}}) and the OpenTitan C style guidelines.
+
+### DIF_TEST_UNIT
+
+Software unit tests exist for the DIF in `sw/device/tests/dif` named `dif_<ip>_unittest.cc`.
Unit tests exist to cover (at least):
- Device Initialisation
diff --git a/doc/project/sw_checklist.md.tpl b/doc/project/sw_checklist.md.tpl
index 2004b00..605cbd0 100644
--- a/doc/project/sw_checklist.md.tpl
+++ b/doc/project/sw_checklist.md.tpl
@@ -17,59 +17,48 @@
This checklist is for [Development Stage]({{< relref "/doc/project/development_stages.md" >}}) transitions for the [${ip.name_long_upper} DIF]({{< relref "hw/ip/${ip.name_snake}/doc" >}}).
All checklist items refer to the content in the [Checklist]({{< relref "/doc/project/checklist.md" >}}).
-## DIF Checklist
+<h2>DIF Checklist</h2>
-### S1
+<h3>S1</h3>
Type | Item | Resolution | Note/Collaterals
---------------|----------------------|-------------|------------------
Implementation | [DIF_EXISTS][] | Not Started |
Implementation | [DIF_USED_IN_TREE][] | Not Started |
-Tests | [DIF_TEST_UNIT][] | Not Started |
Tests | [DIF_TEST_SMOKE][] | Not Started |
[DIF_EXISTS]: {{< relref "/doc/project/checklist.md#dif_exists" >}}
[DIF_USED_IN_TREE]: {{< relref "/doc/project/checklist.md#dif_used_in_tree" >}}
-[DIF_TEST_UNIT]: {{< relref "/doc/project/checklist.md#dif_test_unit" >}}
[DIF_TEST_SMOKE]: {{< relref "/doc/project/checklist.md#dif_test_smoke" >}}
-### S2
+<h3>S2</h3>
Type | Item | Resolution | Note/Collaterals
---------------|-----------------------------|-------------|------------------
-Implementation | [DIF_FEATURES][] | Not Started |
-Coordination | [DIF_HW_USAGE_REVIEWED][] | Not Started |
Coordination | [DIF_HW_FEATURE_COMPLETE][] | Not Started | [HW Dashboard]({{< relref "hw" >}})
-Implementation | [DIF_HW_PARAMS][] | Not Started |
-Documentation | [DIF_DOC_HW][] | Not Started |
-Documentation | [DIF_DOC_API][] | Not Started |
-Code Quality | [DIF_CODE_STYLE][] | Not Started |
+Implementation | [DIF_FEATURES][] | Not Started |
Coordination | [DIF_DV_TESTS][] | Not Started |
-Review | HW IP Usage Reviewer(s) | Not Started |
-[DIF_FEATURES]: {{< relref "/doc/project/checklist.md#dif_features" >}}
-[DIF_HW_USAGE_REVIEWED]: {{< relref "/doc/project/checklist.md#dif_hw_usage_reviewed" >}}
[DIF_HW_FEATURE_COMPLETE]: {{< relref "/doc/project/checklist.md#dif_hw_feature_complete" >}}
-[DIF_HW_PARAMS]: {{< relref "/doc/project/checklist.md#dif_hw_params" >}}
-[DIF_DOC_HW]: {{< relref "/doc/project/checklist.md#dif_doc_hw" >}}
-[DIF_DOC_API]: {{< relref "/doc/project/checklist.md#dif_doc_api" >}}
-[DIF_CODE_STYLE]: {{< relref "/doc/project/checklist.md#dif_code_style" >}}
+[DIF_FEATURES]: {{< relref "/doc/project/checklist.md#dif_features" >}}
[DIF_DV_TESTS]: {{< relref "/doc/project/checklist.md#dif_dv_tests" >}}
-### S3
+<h3>S3</h3>
Type | Item | Resolution | Note/Collaterals
---------------|----------------------------------|-------------|------------------
Coordination | [DIF_HW_DESIGN_COMPLETE][] | Not Started |
Coordination | [DIF_HW_VERIFICATION_COMPLETE][] | Not Started |
-Review | [DIF_REVIEW_C_STABLE][] | Not Started |
-Tests | [DIF_TEST_UNIT_COMPLETE][] | Not Started |
+Documentation | [DIF_DOC_HW][] | Not Started |
+Code Quality | [DIF_CODE_STYLE][] | Not Started |
+Tests | [DIF_TEST_UNIT][] | Not Started |
Review | [DIF_TODO_COMPLETE][] | Not Started |
Review | Reviewer(s) | Not Started |
Review | Signoff date | Not Started |
[DIF_HW_DESIGN_COMPLETE]: {{< relref "/doc/project/checklist.md#dif_hw_design_complete" >}}
[DIF_HW_VERIFICATION_COMPLETE]: {{< relref "/doc/project/checklist.md#dif_hw_verification_complete" >}}
-[DIF_REVIEW_C_STABLE]: {{< relref "/doc/project/checklist.md#dif_review_c_stable" >}}
-[DIF_TEST_UNIT_COMPLETE]: {{< relref "/doc/project/checklist.md#dif_test_unit_complete" >}}
+[DIF_DOC_HW]: {{< relref "/doc/project/checklist.md#dif_doc_hw" >}}
+[DIF_CODE_STYLE]: {{< relref "/doc/project/checklist.md#dif_code_style" >}}
+[DIF_TEST_UNIT]: {{< relref "/doc/project/checklist.md#dif_test_unit" >}}
[DIF_TODO_COMPLETE]: {{< relref "/doc/project/checklist.md#dif_todo_complete" >}}
diff --git a/util/make_new_dif.py b/util/make_new_dif.py
index b329b01..fc9ff09 100755
--- a/util/make_new_dif.py
+++ b/util/make_new_dif.py
@@ -36,18 +36,18 @@
import argparse
import glob
-import hjson
import logging
import shutil
import subprocess
import sys
from pathlib import Path
+import hjson
from mako.template import Template
+import topgen.lib as lib
from autogen_banner import get_autogen_banner
from make_new_dif.ip import Ip
-import topgen.lib as lib
# This file is $REPO_TOP/util/make_new_dif.py, so it takes two parent()
# calls to get back to the top.
@@ -69,9 +69,7 @@
required=True,
help="mode to generate DIF code. Use 'new' if no DIF code exists."
"Use 'rege' to regenerate all auto-generated DIFs for all IPs.")
- parser.add_argument("--topcfg",
- "-t",
- help="path of the top hjson file.")
+ parser.add_argument("--topcfg", "-t", help="path of the top hjson file.")
parser.add_argument("--ip-name-snake",
"-i",
help="the short name of the IP, in snake_case.")
@@ -95,15 +93,14 @@
try:
with open(topcfg_path, 'r') as ftop:
- topcfg = hjson.load(ftop,
- use_decimal=True)
+ topcfg = hjson.load(ftop, use_decimal=True)
except FileNotFoundError:
print(f"hjson {topcfg_path} could not be found")
sys.exit(1)
templated_modules = lib.get_templated_modules(topcfg)
ipgen_modules = lib.get_ipgen_modules(topcfg)
- print (f"modules {templated_modules} {ipgen_modules}")
+ print(f"modules {templated_modules} {ipgen_modules}")
# Check for regeneration mode (used in CI check:
# ci/scripts/check-generated.sh)
@@ -120,12 +117,14 @@
ip_name_snake = Path(autogen_src_filename).stem[4:-8]
# NOTE: ip.name_long_* not needed for auto-generated files which
# are the only files (re-)generated in regen mode.
- ips.append(Ip(ip_name_snake, "AUTOGEN",
- templated_modules, ipgen_modules))
+ ips.append(
+ Ip(ip_name_snake, "AUTOGEN", templated_modules, ipgen_modules))
else:
assert args.ip_name_snake and args.ip_name_long, \
"ERROR: pass --ip-name-snake and --ip-name-long when --mode=new."
- ips.append(Ip(args.ip_name_snake, args.ip_name_long))
+ ips.append(
+ Ip(args.ip_name_snake, args.ip_name_long, templated_modules,
+ ipgen_modules))
# Default to generating all parts.
if len(args.only) == 0:
