[englishbreakfast,clkmgr,rstmgr] Fix up docs for lint

Symlink all required files for shared IPs. Conditionally generate alert_handler cross-reference links for clkmgr and rstmgr, depending on whether a top actually has an alert_handler. This should fix lint failures. Signed-off-by: Alexander Williams <[email protected]>
lowRISC · Dec 28, 2024 · a9b4833 · a9b4833
1 parent ffe3d8c
commit a9b4833
Show file tree

Hide file tree

Showing 33 changed files with 68 additions and 56 deletions.
diff --git a/hw/ip_templates/clkmgr/data/clkmgr.tpldesc.hjson b/hw/ip_templates/clkmgr/data/clkmgr.tpldesc.hjson
@@ -86,5 +86,11 @@
       type: "int"
       default: "2"
     }
+    {
+      name: "with_alert_handler"
+      desc: "Generate outputs for a clkmgr that would connect to an alert handler"
+      type: "bool"
+      default: "1"
+    }
   ]
 }
diff --git a/...mplates/clkmgr/doc/theory_of_operation.md → ...tes/clkmgr/doc/theory_of_operation.md.tpl b/...mplates/clkmgr/doc/theory_of_operation.md → ...tes/clkmgr/doc/theory_of_operation.md.tpl
@@ -1,4 +1,4 @@
-# Theory of Operation
+<%text filter="n"># Theory of Operation
 
 Clock management in OpenTitan is divided into groups.
 Each group has specific attributes and controls whether software is allowed to influence individual clocks during the active power state.
@@ -98,7 +98,7 @@ The controls can also be individual to each peripheral.
 
 ## Wait-for-Interrupt (wfi) Gating
 
-Wait-for-interrupt clock gating refers to the mechanism of using a processor’s sleep indication to actively gate off module clocks.
+Wait-for-interrupt clock gating refers to the mechanism of using a processor's sleep indication to actively gate off module clocks.
 Of the groups enumerated, only transactional, infrastructural and peripheral groups can be influenced by `wfi`.
 
 As `wfi` is effectively a processor clock request, there are subtleties related to its use.
@@ -156,12 +156,16 @@ For a detailed breakdown between `por` and `life cycle` resets, please see the [
 The following diagram enhances the block diagram to illustrate the overall reset domains of the clock manager.
 ![Clock Manager Block Diagram](clkmgr_rst_domain.svg)
 
-### Clock Gated Indications for Alert Handler
+</%text>\
+% if with_alert_handler:
+<%text filter="n">### Clock Gated Indications for Alert Handler
 
 The alert handler needs to know the status of the various clock domains in the system to avoid false alert indications due to the ping mechanism.
 To that end, the clock manager outputs a 4bit MuBi signal for each clock domain that indicates whether its clock is active.
 For more information on this mechanism, see [alert handler documentation](../../alert_handler/doc/theory_of_operation.md#low-power-management-of-alert-channels).
-
+</%text>\
+% endif
+<%text filter="n">
 ## Design Details
 
 ### Root Clock Gating and Interface with Power Manager
@@ -296,3 +300,4 @@ Clock too slow is registered when the clock cycle count is less than the softwar
 Clock time-out is registered when the clock stops toggling and the timeout threshold is reached.
 
 As these are all software supplied values, the entire measurement control can be locked from further programming through [`MEASURE_CTRL_REGWEN`](registers.md#measure_ctrl_regwen).
+</%text>\
diff --git a/hw/ip_templates/rstmgr/data/rstmgr.tpldesc.hjson b/hw/ip_templates/rstmgr/data/rstmgr.tpldesc.hjson
@@ -111,5 +111,11 @@
       type: "object"
       default: {}
     }
+    {
+      name: "with_alert_handler"
+      desc: "Generate outputs for a rstmgr that would connect to an alert handler"
+      type: "bool"
+      default: "1"
+    }
   ]
 }
diff --git a/...mplates/rstmgr/doc/theory_of_operation.md → ...tes/rstmgr/doc/theory_of_operation.md.tpl b/...mplates/rstmgr/doc/theory_of_operation.md → ...tes/rstmgr/doc/theory_of_operation.md.tpl
@@ -1,4 +1,4 @@
-# Theory of Operation
+<%text filter="n"># Theory of Operation
 
 The OpenTitan reset topology and reset controller block diagram are shown in the diagram below.
 The reset controller is closely related to the [power controller](../../pwrmgr/README.md), please refer to that spec for details on how reset controller inputs are controlled.
@@ -134,12 +134,16 @@ The reset manager then checks as follows:
 
 - If all reset conditions are satisfied, wait for the reset release to gracefully complete the cycle.
 
-### Reset Indications for Alert Handler
+</%text>\
+% if with_alert_handler:
+<%text filter="n">### Reset Indications for Alert Handler
 
 The alert handler needs to know the status of the various reset domains in the system to avoid false alert indications due to the ping mechanism.
 To that end, the reset manager outputs a 4bit MuBi signal for each reset domain that indicates whether its reset is active.
 For more information on this mechanism, see [alert handler documentation](../../alert_handler/doc/theory_of_operation.md#low-power-management-of-alert-channels).
-
+</%text>\
+% endif
+<%text filter="n">
 ## Design Details
 
 The reset manager generates the resets required by the system by synchronizing reset tree components to appropriate output clocks.
@@ -308,3 +312,4 @@ For more details on the CPU dump details, please see [crash dump](../../../../ip
 
 The [`CPU_INFO_ATTR`](registers.md#cpu_info_attr) register indicates how many 32-bit data segments must be read.
 Software then simply needs to write in [`CPU_INFO_CTRL.INDEX`](registers.md#cpu_info_ctrl) which segment it wishes and then read out the [`CPU_INFO`](registers.md#cpu_info) register.
+</%text>\
diff --git a/..._templates/rstmgr/dv/rstmgr_sim_cfg.hjson → ...plates/rstmgr/dv/rstmgr_sim_cfg.hjson.tpl b/..._templates/rstmgr/dv/rstmgr_sim_cfg.hjson → ...plates/rstmgr/dv/rstmgr_sim_cfg.hjson.tpl
@@ -15,7 +15,7 @@
   tool: vcs
 
   // Fusesoc core file used for building the file list.
-  fusesoc_core: lowrisc:dv:rstmgr_sim:0.1
+  fusesoc_core: ${instance_vlnv("lowrisc:dv:rstmgr_sim:0.1")}
 
   // Testplan hjson file.
   testplan: "{self_dir}/../data/rstmgr_testplan.hjson"

diff --git a/hw/top_darjeeling/ip_autogen/clkmgr/data/top_darjeeling_clkmgr.ipconfig.hjson b/hw/top_darjeeling/ip_autogen/clkmgr/data/top_darjeeling_clkmgr.ipconfig.hjson
@@ -248,6 +248,7 @@
     }
     exported_clks: {}
     number_of_clock_groups: 7
+    with_alert_handler: true
     topname: darjeeling
   }
 }
diff --git a/hw/top_darjeeling/ip_autogen/clkmgr/doc/theory_of_operation.md b/hw/top_darjeeling/ip_autogen/clkmgr/doc/theory_of_operation.md
@@ -98,7 +98,7 @@ The controls can also be individual to each peripheral.
 
 ## Wait-for-Interrupt (wfi) Gating
 
-Wait-for-interrupt clock gating refers to the mechanism of using a processor’s sleep indication to actively gate off module clocks.
+Wait-for-interrupt clock gating refers to the mechanism of using a processor's sleep indication to actively gate off module clocks.
 Of the groups enumerated, only transactional, infrastructural and peripheral groups can be influenced by `wfi`.
 
 As `wfi` is effectively a processor clock request, there are subtleties related to its use.

diff --git a/hw/top_darjeeling/ip_autogen/rstmgr/data/top_darjeeling_rstmgr.ipconfig.hjson b/hw/top_darjeeling/ip_autogen/rstmgr/data/top_darjeeling_rstmgr.ipconfig.hjson
@@ -543,6 +543,7 @@
     ]
     rst_ni: lc_io_div4
     export_rsts: {}
+    with_alert_handler: true
     topname: darjeeling
   }
 }
diff --git a/hw/top_darjeeling/ip_autogen/rstmgr/dv/rstmgr_sim_cfg.hjson b/hw/top_darjeeling/ip_autogen/rstmgr/dv/rstmgr_sim_cfg.hjson
@@ -15,7 +15,7 @@
   tool: vcs
 
   // Fusesoc core file used for building the file list.
-  fusesoc_core: lowrisc:dv:rstmgr_sim:0.1
+  fusesoc_core: lowrisc:opentitan:top_darjeeling_rstmgr_sim:0.1
 
   // Testplan hjson file.
   testplan: "{self_dir}/../data/rstmgr_testplan.hjson"

diff --git a/hw/top_earlgrey/ip_autogen/clkmgr/data/top_earlgrey_clkmgr.ipconfig.hjson b/hw/top_earlgrey/ip_autogen/clkmgr/data/top_earlgrey_clkmgr.ipconfig.hjson
@@ -258,6 +258,7 @@
     }
     exported_clks: {}
     number_of_clock_groups: 7
+    with_alert_handler: true
     topname: earlgrey
   }
 }
diff --git a/hw/top_earlgrey/ip_autogen/clkmgr/doc/theory_of_operation.md b/hw/top_earlgrey/ip_autogen/clkmgr/doc/theory_of_operation.md
@@ -98,7 +98,7 @@ The controls can also be individual to each peripheral.
 
 ## Wait-for-Interrupt (wfi) Gating
 
-Wait-for-interrupt clock gating refers to the mechanism of using a processor’s sleep indication to actively gate off module clocks.
+Wait-for-interrupt clock gating refers to the mechanism of using a processor's sleep indication to actively gate off module clocks.
 Of the groups enumerated, only transactional, infrastructural and peripheral groups can be influenced by `wfi`.
 
 As `wfi` is effectively a processor clock request, there are subtleties related to its use.

diff --git a/hw/top_earlgrey/ip_autogen/rstmgr/data/top_earlgrey_rstmgr.ipconfig.hjson b/hw/top_earlgrey/ip_autogen/rstmgr/data/top_earlgrey_rstmgr.ipconfig.hjson
@@ -690,6 +690,7 @@
     ]
     rst_ni: lc_io_div4
     export_rsts: {}
+    with_alert_handler: true
     topname: earlgrey
   }
 }
diff --git a/hw/top_earlgrey/ip_autogen/rstmgr/dv/rstmgr_sim_cfg.hjson b/hw/top_earlgrey/ip_autogen/rstmgr/dv/rstmgr_sim_cfg.hjson
@@ -15,7 +15,7 @@
   tool: vcs
 
   // Fusesoc core file used for building the file list.
-  fusesoc_core: lowrisc:dv:rstmgr_sim:0.1
+  fusesoc_core: lowrisc:opentitan:top_earlgrey_rstmgr_sim:0.1
 
   // Testplan hjson file.
   testplan: "{self_dir}/../data/rstmgr_testplan.hjson"

diff --git a/hw/top_earlgrey/lint/top_earlgrey_dv_lint_cfgs.hjson b/hw/top_earlgrey/lint/top_earlgrey_dv_lint_cfgs.hjson
@@ -34,7 +34,7 @@
                   rel_path: "hw/top_earlgrey/ip/aon_timer/dv/lint/{tool}"
              },
              {    name: clkmgr
-                  fusesoc_core: lowrisc:dv:clkmgr_sim
+                  fusesoc_core: lowrisc:opentitan:top_earlgrey_clkmgr_sim
                   import_cfgs: ["{proj_root}/hw/lint/tools/dvsim/common_lint_cfg.hjson"]
                   rel_path: "hw/top_earlgrey/ip_autogen/clkmgr/dv/lint/{tool}"
              },
@@ -131,7 +131,7 @@
                   rel_path: "hw/ip/prim/dv/prim_prince/lint/{tool}"
              },
              {    name: pwrmgr
-                  fusesoc_core: lowrisc:dv:pwrmgr_sim
+                  fusesoc_core: lowrisc:opentitan:top_earlgrey_pwrmgr_sim
                   import_cfgs: ["{proj_root}/hw/lint/tools/dvsim/common_lint_cfg.hjson"]
                   rel_path: "hw/top_earlgrey/ip_autogen/pwrmgr/dv/lint/{tool}"
              },
@@ -141,7 +141,7 @@
                   rel_path: "hw/ip/rom_ctrl/dv/lint/{tool}"
              },
              {    name: rstmgr
-                  fusesoc_core: lowrisc:dv:rstmgr_sim
+                  fusesoc_core: lowrisc:opentitan:top_earlgrey_rstmgr_sim
                   import_cfgs: ["{proj_root}/hw/lint/tools/dvsim/common_lint_cfg.hjson"]
                   rel_path: "hw/top_earlgrey/ip_autogen/rstmgr/dv/lint/{tool}"
              },

diff --git a/hw/top_englishbreakfast/README.md b/hw/top_englishbreakfast/README.md
@@ -0,0 +1,3 @@
+# Top Englishbreakfast
+
+This is an experimental top intended for SCA/FI activities.
diff --git a/hw/top_englishbreakfast/ip/ast/README.md b/hw/top_englishbreakfast/ip/ast/README.md
@@ -0,0 +1 @@
+../../../top_earlgrey/ip/ast/README.md
diff --git a/hw/top_englishbreakfast/ip/ast/ast_regs.html b/hw/top_englishbreakfast/ip/ast/ast_regs.html
@@ -0,0 +1 @@
+../../../top_earlgrey/ip/ast/ast_regs.html
diff --git a/hw/top_englishbreakfast/ip/ast/data b/hw/top_englishbreakfast/ip/ast/data
@@ -0,0 +1 @@
+../../../top_earlgrey/ip/ast/data
diff --git a/hw/top_englishbreakfast/ip/ast/data/ast.hjson b/hw/top_englishbreakfast/ip/ast/data/ast.hjson
diff --git a/hw/top_englishbreakfast/ip/ast/doc b/hw/top_englishbreakfast/ip/ast/doc
@@ -0,0 +1 @@
+../../../top_earlgrey/ip/ast/doc
diff --git a/hw/top_englishbreakfast/ip/sensor_ctrl/README.md b/hw/top_englishbreakfast/ip/sensor_ctrl/README.md
@@ -0,0 +1 @@
+../../../top_earlgrey/ip/sensor_ctrl/README.md
diff --git a/hw/top_englishbreakfast/ip/sensor_ctrl/data b/hw/top_englishbreakfast/ip/sensor_ctrl/data
@@ -0,0 +1 @@
+../../../top_earlgrey/ip/sensor_ctrl/data
diff --git a/hw/top_englishbreakfast/ip/sensor_ctrl/data/sensor_ctrl.hjson b/hw/top_englishbreakfast/ip/sensor_ctrl/data/sensor_ctrl.hjson
diff --git a/hw/top_englishbreakfast/ip/sensor_ctrl/doc b/hw/top_englishbreakfast/ip/sensor_ctrl/doc
@@ -0,0 +1 @@
+../../../top_earlgrey/ip/sensor_ctrl/doc
diff --git a/hw/top_englishbreakfast/ip_autogen/clkmgr/data/top_englishbreakfast_clkmgr.ipconfig.hjson b/hw/top_englishbreakfast/ip_autogen/clkmgr/data/top_englishbreakfast_clkmgr.ipconfig.hjson
@@ -235,6 +235,7 @@
     }
     exported_clks: {}
     number_of_clock_groups: 8
+    with_alert_handler: false
     topname: englishbreakfast
   }
 }
diff --git a/hw/top_englishbreakfast/ip_autogen/clkmgr/doc/theory_of_operation.md b/hw/top_englishbreakfast/ip_autogen/clkmgr/doc/theory_of_operation.md
@@ -98,7 +98,7 @@ The controls can also be individual to each peripheral.
 
 ## Wait-for-Interrupt (wfi) Gating
 
-Wait-for-interrupt clock gating refers to the mechanism of using a processor’s sleep indication to actively gate off module clocks.
+Wait-for-interrupt clock gating refers to the mechanism of using a processor's sleep indication to actively gate off module clocks.
 Of the groups enumerated, only transactional, infrastructural and peripheral groups can be influenced by `wfi`.
 
 As `wfi` is effectively a processor clock request, there are subtleties related to its use.
@@ -156,11 +156,6 @@ For a detailed breakdown between `por` and `life cycle` resets, please see the [
 The following diagram enhances the block diagram to illustrate the overall reset domains of the clock manager.
 ![Clock Manager Block Diagram](clkmgr_rst_domain.svg)
 
-### Clock Gated Indications for Alert Handler
-
-The alert handler needs to know the status of the various clock domains in the system to avoid false alert indications due to the ping mechanism.
-To that end, the clock manager outputs a 4bit MuBi signal for each clock domain that indicates whether its clock is active.
-For more information on this mechanism, see [alert handler documentation](../../alert_handler/doc/theory_of_operation.md#low-power-management-of-alert-channels).
 
 ## Design Details
 

diff --git a/hw/top_englishbreakfast/ip_autogen/rstmgr/data/top_englishbreakfast_rstmgr.ipconfig.hjson b/hw/top_englishbreakfast/ip_autogen/rstmgr/data/top_englishbreakfast_rstmgr.ipconfig.hjson
@@ -450,6 +450,7 @@
     ]
     rst_ni: lc_io_div4
     export_rsts: {}
+    with_alert_handler: false
     topname: englishbreakfast
   }
 }
diff --git a/hw/top_englishbreakfast/ip_autogen/rstmgr/doc/theory_of_operation.md b/hw/top_englishbreakfast/ip_autogen/rstmgr/doc/theory_of_operation.md
@@ -134,11 +134,6 @@ The reset manager then checks as follows:
 
 - If all reset conditions are satisfied, wait for the reset release to gracefully complete the cycle.
 
-### Reset Indications for Alert Handler
-
-The alert handler needs to know the status of the various reset domains in the system to avoid false alert indications due to the ping mechanism.
-To that end, the reset manager outputs a 4bit MuBi signal for each reset domain that indicates whether its reset is active.
-For more information on this mechanism, see [alert handler documentation](../../alert_handler/doc/theory_of_operation.md#low-power-management-of-alert-channels).
 
 ## Design Details
 

diff --git a/hw/top_englishbreakfast/ip_autogen/rstmgr/dv/rstmgr_sim_cfg.hjson b/hw/top_englishbreakfast/ip_autogen/rstmgr/dv/rstmgr_sim_cfg.hjson
@@ -15,7 +15,7 @@
   tool: vcs
 
   // Fusesoc core file used for building the file list.
-  fusesoc_core: lowrisc:dv:rstmgr_sim:0.1
+  fusesoc_core: lowrisc:opentitan:top_englishbreakfast_rstmgr_sim:0.1
 
   // Testplan hjson file.
   testplan: "{self_dir}/../data/rstmgr_testplan.hjson"

diff --git a/hw/top_englishbreakfast/sw/autogen/tests/BUILD b/hw/top_englishbreakfast/sw/autogen/tests/BUILD
@@ -76,27 +76,3 @@ test_suite(
         "plic_all_irqs_test_0",
     ],
 )
-
-opentitan_test(
-    name = "alert_test",
-    srcs = ["alert_test.c"],
-    exec_env = dicts.add(
-        EARLGREY_TEST_ENVS,
-        EARLGREY_SILICON_OWNER_ROM_EXT_ENVS,
-        {
-            "//hw/top_earlgrey:fpga_cw310_test_rom": None,
-            "//hw/top_earlgrey:fpga_cw310_sival": None,
-            "//hw/top_earlgrey:silicon_creator": None,
-        },
-    ),
-    deps = [
-        "//hw/top_earlgrey/sw/autogen:top_earlgrey",
-        "//sw/device/lib/arch:boot_stage",
-        "//sw/device/lib/base:memory",
-        "//sw/device/lib/base:mmio",
-        "//sw/device/lib/dif:alert_handler",
-        "//sw/device/lib/runtime:log",
-        "//sw/device/lib/testing:alert_handler_testutils",
-        "//sw/device/lib/testing/test_framework:ottf_main",
-    ],
-)
diff --git a/hw/top_englishbreakfast/util/prepare_sw.py b/hw/top_englishbreakfast/util/prepare_sw.py
@@ -138,7 +138,6 @@ def main():
     REG_FILES = [
         'ip/ast/data/ast.hjson',
         'ip/sensor_ctrl/data/sensor_ctrl.hjson',
-        'ip_autogen/alert_handler/data/alert_handler.hjson',
         'ip_autogen/clkmgr/data/clkmgr.hjson',
         'ip_autogen/flash_ctrl/data/flash_ctrl.hjson',
         'ip_autogen/pinmux/data/pinmux.hjson',

diff --git a/util/topgen.py b/util/topgen.py
@@ -377,6 +377,10 @@ def generate_clkmgr(topcfg: Dict[str, object], out_path: Path) -> None:
         ty: {nm: {"src_name": sig.src.name, "endpoint_ip": sig.endpoints[0][0]}
              for nm, sig in mp.items() if isinstance(sig, ClockSignal)}
         for ty, mp in typed_clocks._asdict().items() if isinstance(mp, dict)})
+
+    # Will connect to alert_handler
+    with_alert_handler = lib.find_module(topcfg['module'], 'alert_handler') is not None
+
     params = {
         "src_clks": OrderedDict({
             name: vars(obj) for name, obj in clocks.srcs.items()}),
@@ -387,7 +391,8 @@ def generate_clkmgr(topcfg: Dict[str, object], out_path: Path) -> None:
         "hint_names": hint_names,
         "parent_child_clks": typed_clocks.parent_child_clks,
         "exported_clks": topcfg["exported_clks"],
-        "number_of_clock_groups": len(clocks.groups)
+        "number_of_clock_groups": len(clocks.groups),
+        "with_alert_handler": with_alert_handler,
     }
 
     ipgen_render("clkmgr", topname, params, out_path)
@@ -428,7 +433,7 @@ def generate_pwrmgr(top: Dict[str, object], out_path: Path) -> None:
         "rst_reqs": top["reset_requests"],
         "NumRstReqs": n_rstreqs,
         "wait_for_external_reset": top['power']['wait_for_external_reset'],
-        "NumRomInputs": n_rom_ctrl
+        "NumRomInputs": n_rom_ctrl,
     }
 
     ipgen_render("pwrmgr", topname, params, out_path)
@@ -468,6 +473,9 @@ def generate_rstmgr(topcfg: Dict[str, object], out_path: Path) -> None:
     # Number of reset requests
     n_rstreqs = len(topcfg["reset_requests"]["peripheral"])
 
+    # Will connect to alert_handler
+    with_alert_handler = lib.find_module(topcfg['module'], 'alert_handler') is not None
+
     params = {
         "clks": clks,
         "reqs": topcfg["reset_requests"],
@@ -478,6 +486,7 @@ def generate_rstmgr(topcfg: Dict[str, object], out_path: Path) -> None:
         "leaf_rsts": leaf_rsts,
         "rst_ni": rst_ni['rst_ni']['name'],
         "export_rsts": topcfg["exported_rsts"],
+        "with_alert_handler": with_alert_handler,
     }
 
     ipgen_render("rstmgr", topname, params, out_path)

diff --git a/util/topgen/templates/BUILD.tpl b/util/topgen/templates/BUILD.tpl
@@ -77,6 +77,7 @@ test_suite(
 % endfor
     ],
 )
+% if has_alert_handler:
 
 opentitan_test(
     name = "alert_test",
@@ -103,3 +104,4 @@ opentitan_test(
         "//sw/device/lib/testing/test_framework:ottf_main",
     ],
 )
+% endif\
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Top Englishbreakfast

		This is an experimental top intended for SCA/FI activities.