[doc] Unify dashboard, manual spec table

- This PR prototypes a solution to present the same data in a better way - The autogenerated dashboard now links the name to the design spec, and add link to the DV testplan underneath - This saves us from adding an extra column - The D and V numbers are now linked to the checklist directly so that that information is discoverable - Above the table, I added 'ASIC Tool Flow Results' which will serve as the entry point to look at results from the nightly simulation/lint/FPV/synthesis runs Signed-off-by: Srikrishna Iyer <[email protected]>
wk1101 · Apr 3, 2020 · d1f896e · d1f896e
1 parent e849d53
commit d1f896e
Show file tree

Hide file tree

Showing 46 changed files with 304 additions and 176 deletions.
diff --git a/_index.md b/_index.md
@@ -28,10 +28,13 @@ Unless otherwise noted, everything in the repository is covered by the Apache Li
   * User Guides
   * Reference Manuals
   * Security
-* [Hardware Specifications]({{< relref "hw" >}})
-  * Top-level SoC
-  * Ibex processor core
-  * Comportable IP blocks
+* [Hardware Dashboard]({{< relref "hw" >}})
+  * Design specifications
+  * Verification plans
+  * Results of tool-flows
+  * Comportable IPs
+  * Processor cores
+  * Top level designs
 * [Software]({{< relref "sw" >}})
   * READMEs of OpenTitan software
 * [Tools]({{< relref "util" >}})

diff --git a/doc/_index.md b/doc/_index.md
@@ -2,7 +2,11 @@
 
 * [Project]({{< relref "doc/project" >}})
   * How the OpenTitan project is organized
-  * Progress tracking
+  * Hardware development stages
+  * Hardware signoff checklist
+  * Governance
+  * RFC process
+  * Committers
 * [User Guides]({{< relref "doc/ug" >}})
   * How to get started with the repo
   * How to emulate on an FPGA

diff --git a/doc/project/_index.md b/doc/project/_index.md
@@ -9,7 +9,7 @@ More information will be added over time.
 ## Quality standards for open hardware IP
 
 In order to gauge the quality of the different IP that is in our repository, we define a series of [Hardware Development Stages]({{< relref "hw_stages" >}}) to track the designs.
-The current status of different IP is reflected in the [HW Development Stages Dashboard]({{< relref "hw_dashboard" >}}).
+The current status of different IP is reflected in the [Hardware Dashboard]({{< relref "hw" >}}).
 The final state for developed IP is *Signed Off*, indicating that design and verification is complete, and the IP should be bug free.
 To make it to that stage, a [Hardware Signoff Checklist]({{< relref "checklist.md" >}}) is used to confirm completion.
 [Here](https://github.com/lowRISC/opentitan/blob/master/doc/project/ip_checklist.md.tpl) is a template that can be used as a checklist item.

diff --git a/doc/project/hw_dashboard.md b/doc/project/hw_dashboard.md
diff --git a/doc/project/hw_stages.md b/doc/project/hw_stages.md
@@ -6,7 +6,7 @@ This document describes development stages for hardware within the OpenTitan pro
 This includes design and verification stages meant to give a high-level view of the status of a design.
 OpenTitan being an open-source program aimed at a high quality silicon release, the intent is to find a balance between the rigor of a heavy tapeout process and the more fluid workings of an open source development.
 
-This document also serves as a guide to the [hardware design dashboard]({{< relref "doc/project/hw_dashboard" >}}), which gives the status of all of the designs in the OpenTitan repository.
+This document also serves as a guide to the [Hardware Dashboard]({{< relref "hw" >}}), which gives the status of all of the designs in the OpenTitan repository.
 
 This document aims to mostly give a more defined structure to the process that is already followed.
 Proper versioning of RTL designs is a complex topic.
@@ -150,12 +150,12 @@ For example, `file: gpio.prj.hjson`:
 
 ```hjson
 {
-    name: "gpio",
-    version: 1.0,
-    life_stage: "L1",
-    design_stage: "D2",
-    verification_stage: "V1",
-    notes: "information shown on the dashboard"
+    name:               "gpio"
+    version:            1.0
+    life_stage:         "L1"
+    design_stage:       "D2"
+    verification_stage: "V1"
+    notes:              "information shown on the dashboard"
 }
 ```
 
@@ -167,13 +167,27 @@ The commit ID has its own entry in the project Hjson file, as shown below.
 
 ```hjson
 {
-    name: "gpio",
-    version: 1.0,
-    life_stage: "L1",
-    design_stage: "D2",
-    verification_stage: "V1",
-    commit_id: "92e4298f8c2de268b2420a2c16939cd0784f1bf8",
-    notes: "information shown on the dashboard"
+    name:               "gpio"
+    version:            1.0
+    life_stage:         "L1"
+    design_stage:       "D2"
+    verification_stage: "V1"
+    commit_id:          "92e4298f8c2de268b2420a2c16939cd0784f1bf8"
+    notes:              "information shown on the dashboard"
+}
+```
+
+### Other optional fields
+
+Additionally, the tool that generates the dashboard accepts the following optional fields: the design specification, the DV plan and the checklist.
+They are set as partial paths (reference relative to the top of the repository) to the respective documents as shown below.
+They are converted to complete URLs in the generated dashboard.
+
+```hjson
+{
+    design_spec:  "hw/ip/gpio/doc"
+    dv_plan:      "hw/ip/gpio/doc/dv_plan"
+    checklist:    "hw/ip/gpio/doc/checklist"
 }
 ```
 
@@ -240,4 +254,4 @@ The subject will be revisited as we get closer to locking down the design to tak
 
 The stages are reported externally via a script-generated table exposed on the external website.
 This status is a summary of all `prj.hjson` files of all designs in the system, with multiple lines where there are multiple versions.
-The link to that table is [here]({{< relref "doc/project/hw_dashboard" >}}).
+The link to that table is [here]({{< relref "hw" >}}).
diff --git a/doc/project/ip_checklist.md.tpl b/doc/project/ip_checklist.md.tpl
@@ -2,6 +2,11 @@
 title: "${name.upper()} Checklist"
 ---
 
+<!--
+NOTE: This is a template checklist document that is required to be copied over to the 'doc'
+directory for a new design that transitions from L0 (Specification) to L1 (Development)
+stage, and updated as needed. Once done, please remove this comment before checking it in.
+-->
 This checklist is for [Hardware Stage]({{< relref "/doc/project/hw_stages.md" >}}) transitions for the [${name.upper()} peripheral.]({{< relref "hw/ip/${name}/doc" >}})
 All checklist items refer to the content in the [Checklist.]({{< relref "/doc/project/checklist.md" >}})
 

diff --git a/hw/_index.md b/hw/_index.md
@@ -1,35 +1,43 @@
-# Hardware Specifications
-
-This is the landing spot for all hardware specifications within the OpenTitan project.
-This includes: top level specification(s); processor core(s) specifications; and [Comportable IP]({{< relref "doc/rm/comportability_specification" >}}) specifications.
-
-## Available Top Level Specifications
-
-* [`top_earlgrey` design specification]({{< relref "hw/top_earlgrey/doc" >}})
-
-## Available Processor Core Specifications
-
-* [`core_ibex` user manual](https://ibex-core.readthedocs.io/en/latest)
-
-## Available Comportable IP Block Design Specifications and Verification Plans
-
-| Module | Design Spec | DV Plan |
-|--------|-------------|---------|
-| `aes`           | [design spec]({{< relref "hw/ip/aes/doc" >}})           | [DV plan]({{< relref "hw/ip/aes/doc/dv_plan" >}}) |
-| `alert_handler` | [design spec]({{< relref "hw/ip/alert_handler/doc" >}}) | [DV plan]({{< relref "hw/ip/alert_handler/doc/dv_plan" >}}) |
-| `entropy_src`   | [design spec]({{< relref "hw/ip/entropy_src/doc" >}})   | |
-| `flash_ctrl`    | [design spec]({{< relref "hw/ip/flash_ctrl/doc" >}})    | |
-| `gpio`          | [design spec]({{< relref "hw/ip/gpio/doc" >}})          | [DV plan]({{< relref "hw/ip/gpio/doc/dv_plan" >}}) |
-| `hmac`          | [design spec]({{< relref "hw/ip/hmac/doc" >}})          | [DV plan]({{< relref "hw/ip/hmac/doc/dv_plan" >}}) |
-| `i2c`           | [design spec]({{< relref "hw/ip/i2c/doc" >}})           | [DV plan]({{< relref "hw/ip/i2c/doc/dv_plan" >}})  |
-| `nmi_gen`       | [design spec]({{< relref "hw/ip/nmi_gen/doc" >}})       | |
-| `padctrl`       | [design spec]({{< relref "hw/ip/padctrl/doc" >}})       | |
-| `pinmux`        | [design spec]({{< relref "hw/ip/pinmux/doc" >}})        | |
-| `rv_core_ibex`  | [design spec]({{< relref "hw/ip/rv_core_ibex/doc" >}})  | |
-| `rv_dm`         | [design spec]({{< relref "hw/ip/rv_dm/doc" >}})         | |
-| `rv_plic`       | [design spec]({{< relref "hw/ip/rv_plic/doc" >}})       | [DV plan]({{< relref "hw/ip/rv_plic/doc/dv_plan" >}}) |
-| `rv_timer`      | [design spec]({{< relref "hw/ip/rv_timer/doc" >}})      | [DV plan]({{< relref "hw/ip/rv_timer/doc/dv_plan" >}}) |
-| `spi_device`    | [design spec]({{< relref "hw/ip/spi_device/doc" >}})    | [DV plan]({{< relref "hw/ip/spi_device/doc/dv_plan" >}}) |
-| `tlul`          | [design spec]({{< relref "hw/ip/tlul/doc" >}})          | [DV plan]({{< relref "hw/ip/tlul/doc/dv_plan" >}})
-| `uart`          | [design spec]({{< relref "hw/ip/uart/doc" >}})          | [DV plan]({{< relref "hw/ip/uart/doc/dv_plan" >}}) |
-| `usbdev`        | [design spec]({{< relref "hw/ip/usbdev/doc" >}})        | [DV plan]({{< relref "hw/ip/usbdev/doc/dv_plan" >}}) |
+---
+title: "Hardware Dashboard"
+---
+
+This page serves as the landing spot for all hardware development within the OpenTitan project.
+
+We start off by providing links to the [results of various tool-flows](#toolflows-summary-results) run on all of our [Comportable]({{< relref "doc/rm/comportability_specification" >}}) IPs.
+This includes DV simulations, FPV and lint, all of which are run with the `dvsim` tool which serves as the common frontend.
+
+The [Comportable IPs](#comportable-ips) following it provides links to their design specifications and DV plans, and tracks their current stage of development.
+See the [Hardware Development Stages]({{< relref "/doc/project/hw_stages.md" >}}) for description of the hardware stages and how they are determined.
+
+Next, we focus on all available [processor cores](#processor-cores) and provide links to their design specifications, DV plans and the DV simulation results.
+
+Finally, we provide the same set of information for all available [top level designs](#top-level-designs). We may eventually also include the synthesis results for those top level designs.
+
+
+## Results of tool-flows
+
+* [DV simulation summary results, with coverage (nightly)](https://reports.opentitan.org/hw/top_earlgrey/dv/summary.html)
+* FPV summary results (nightly) (TBD)
+* [Lint summary results (nightly)](https://reports.opentitan.org/hw/top_earlgrey/lint/ascentlint/summary.html)
+
+## Comportable IPs
+
+{{< dashboard "hw/ip" >}}
+
+## Processor cores
+
+* `core_ibex`
+  * [User manual](https://ibex-core.readthedocs.io/en/latest)
+  * [DV plan](https://ibex-core.readthedocs.io/en/latest/verification.html)
+  * DV simulation results, with coverage (nightly) (TBD)
+
+## Top level designs
+
+* `top_earlgrey`
+  * [Design specification]({{< relref "hw/top_earlgrey/doc" >}})
+  * DV plan (TBD)
+  * [DV simulation results, with coverage (nightly)](https://reports.opentitan.org/hw/top_earlgrey/dv/latest/results.html)
+  * FPV results (nightly) (TBD)
+  * [Lint results (nightly)](https://reports.opentitan.org/hw/top_earlgrey/lint/latest/results.html)
+  * Synthesis results (nightly) (TBD)
diff --git a/hw/dv/doc/dv_plan_template.md b/hw/dv/doc/dv_plan_template.md
@@ -19,9 +19,9 @@ applicable. Once done, remove this comment before making a PR. -->
   * Verify TileLink device protocol compliance with an SVA based testbench
 
 ## Current status
-* [Design & verification stage]({{< relref "doc/project/hw_dashboard" >}})
+* [Design & verification stage]({{< relref "hw" >}})
   * [HW development stages]({{< relref "doc/project/hw_stages.md" >}})
-* DV regression results dashboard (link TBD)
+* [Simulation results](https://reports.opentitan.org/hw/ip/foo/dv/latest/results.html)
 
 ## Design features
 <!-- TODO: uncomment link to the spec below -->

diff --git a/hw/ip/aes/data/aes.prj.hjson b/hw/ip/aes/data/aes.prj.hjson
@@ -4,6 +4,9 @@
 
 {
     name:               "aes",
+    design_spec:        "hw/ip/aes/doc",
+    dv_plan:            "hw/ip/aes/doc/dv_plan",
+    checklist:          "hw/ip/aes/doc/checklist",
     version:            "0.6",
     life_stage:         "L1",
     design_stage:       "D2",

diff --git a/hw/ip/aes/doc/dv_plan/index.md b/hw/ip/aes/doc/dv_plan/index.md
@@ -10,7 +10,7 @@ title: "AES DV Plan"
   * Verify TileLink device protocol compliance with an SVA based testbench
 
 ## Current status
-* [Design & verification stage]({{< relref "doc/project/hw_dashboard" >}})
+* [Design & verification stage]({{< relref "hw" >}})
   * [HW development stages]({{< relref "doc/project/hw_stages.md" >}})
 * [Simulation results](https://reports.opentitan.org/hw/ip/aes/dv/latest/results.html)
 

diff --git a/hw/ip/alert_handler/data/alert_handler.prj.hjson b/hw/ip/alert_handler/data/alert_handler.prj.hjson
@@ -4,6 +4,9 @@
 
 {
     name:               "alert_handler",
+    design_spec:        "hw/ip/alert_handler/doc",
+    dv_plan:            "hw/ip/alert_handler/doc/dv_plan",
+    checklist:          "hw/ip/alert_handler/doc/checklist",
     version:            "0.5",
     life_stage:         "L1",
     design_stage:       "D1",

diff --git a/hw/ip/alert_handler/doc/checklist.md b/hw/ip/alert_handler/doc/checklist.md
@@ -103,7 +103,7 @@ Review        | Signoff date            | Not Started |
 
 ## Verification Checklist
 
-### Checklists for milestone V1
+### V1
 
  Type         | Item                                  | Resolution  | Note/Collaterals
 --------------|---------------------------------------|-------------|------------------
@@ -153,7 +153,7 @@ Review        | Signoff date                          | Not Started |
 [STD_TEST_CATEGORIES_PLANNED]:        {{<relref "/doc/project/checklist.md#std-test-categories-planned" >}}
 [V2_CHECKLIST_SCOPED]:                {{<relref "/doc/project/checklist.md#v2-checklist-scoped" >}}
 
-### Checklists for milestone V2
+### V2
 
  Type         | Item                                    | Resolution  | Note/Collaterals
 --------------|-----------------------------------------|-------------|------------------
@@ -197,7 +197,7 @@ Review        | Signoff date                            | Not Started |
 [PRE_VERIFIED_SUB_MODULES_V2]:        {{<relref "/doc/project/checklist.md#pre-verified-sub-modules-v2" >}}
 [V3_CHECKLIST_SCOPED]:                {{<relref "/doc/project/checklist.md#v3-checklist-scoped" >}}
 
-### Checklists for milestone V3
+### V3
 
  Type         | Item                              | Resolution  | Note/Collaterals
 --------------|-----------------------------------|-------------|------------------

diff --git a/hw/ip/alert_handler/doc/dv_plan/index.md b/hw/ip/alert_handler/doc/dv_plan/index.md
@@ -12,7 +12,7 @@ title: "ALERT_HANDLER DV Plan"
   * Partially verify ping_timer
 
 ## Current status
-* [Design & verification stage]({{< relref "doc/project/hw_dashboard" >}})
+* [Design & verification stage]({{< relref "hw" >}})
   * [HW development stages]({{< relref "doc/project/hw_stages" >}})
 * [Simulation results](https://reports.opentitan.org/hw/ip/alert_handler/dv/latest/results.html)
 

diff --git a/hw/ip/entropy_src/data/entropy_src.prj.hjson b/hw/ip/entropy_src/data/entropy_src.prj.hjson
@@ -4,6 +4,8 @@
 
 {
     name:               "entropy_src",
+    design_spec:        "hw/ip/entropy_src/doc",
+    checklist:          "hw/ip/entropy_src/doc/checklist",
     version:            "0.5",
     life_stage:         "L0",
 }
diff --git a/hw/ip/flash_ctrl/data/flash_ctrl.prj.hjson b/hw/ip/flash_ctrl/data/flash_ctrl.prj.hjson
@@ -4,6 +4,8 @@
 
 {
     name:               "flash_ctrl",
+    design_spec:        "hw/ip/flash_ctrl/doc",
+    checklist:          "hw/ip/flash_ctrl/doc/checklist",
     version:            "0.5",
     life_stage:         "L1",
     design_stage:       "D1",

diff --git a/hw/ip/gpio/data/gpio.prj.hjson b/hw/ip/gpio/data/gpio.prj.hjson
@@ -4,6 +4,9 @@
 
 {
     name:               "gpio",
+    design_spec:        "hw/ip/gpio/doc",
+    dv_plan:            "hw/ip/gpio/doc/dv_plan",
+    checklist:          "hw/ip/gpio/doc/checklist",
     revisions: [
       {
         version:            "1.0",
@@ -18,7 +21,6 @@
         life_stage:         "L1",
         design_stage:       "D2",
         verification_stage: "V2",
-        commit_id:          "f3039d7006ca8ebd45ae0b52b22864983876175d",
         notes:              "Rolled back to D2 as the register module is updated",
       }
     ]

diff --git a/hw/ip/gpio/doc/dv_plan/index.md b/hw/ip/gpio/doc/dv_plan/index.md
@@ -10,7 +10,7 @@ title: "GPIO DV Plan"
   * Verify TileLink device protocol compliance with an SVA based testbench
 
 ## Current status
-* [Design & verification stage]({{< relref "doc/project/hw_dashboard" >}})
+* [Design & verification stage]({{< relref "hw" >}})
   * [HW development stages]({{< relref "doc/project/hw_stages.md" >}})
 * [Simulation results](https://reports.opentitan.org/hw/ip/gpio/dv/latest/results.html)
 

diff --git a/hw/ip/hmac/data/hmac.prj.hjson b/hw/ip/hmac/data/hmac.prj.hjson
@@ -4,6 +4,9 @@
 
 {
     name:               "hmac",
+    design_spec:        "hw/ip/hmac/doc",
+    dv_plan:            "hw/ip/hmac/doc/dv_plan",
+    checklist:          "hw/ip/hmac/doc/checklist",
     revisions: [
       {
         version:            "0.5",
@@ -18,7 +21,6 @@
         life_stage:         "L1",
         design_stage:       "D2",
         verification_stage: "V1",
-        commit_id:          "48fd7fd2d27c844acf909cfd7dc2b86f0f4e8e43",
         notes:              "Rolled back to D2 in order to add the first alert",
       }
     ]

diff --git a/hw/ip/hmac/doc/dv_plan/index.md b/hw/ip/hmac/doc/dv_plan/index.md
@@ -10,7 +10,7 @@ title: "HMAC DV Plan"
   * Verify TileLink device protocol compliance with an SVA based testbench
 
 ## Current status
-* [Design & verification stage]({{< relref "doc/project/hw_dashboard" >}})
+* [Design & verification stage]({{< relref "hw" >}})
   * [HW development stages]({{< relref "doc/project/hw_stages.md" >}})
 * [Simulation results](https://reports.opentitan.org/hw/ip/hmac/dv/latest/results.html)
 

diff --git a/hw/ip/i2c/data/i2c.prj.hjson b/hw/ip/i2c/data/i2c.prj.hjson
@@ -4,6 +4,8 @@
 
 {
     name:               "i2c",
+    design_spec:        "hw/ip/i2c/doc",
+    dv_plan:            "hw/ip/i2c/doc/dv_plan",
     version:            "0.5",
     life_stage:         "L1",
     design_stage:       "D0",

diff --git a/hw/ip/i2c/doc/dv_plan/index.md b/hw/ip/i2c/doc/dv_plan/index.md
@@ -10,7 +10,7 @@ title: "I2C DV Plan"
   * Verify TileLink device protocol compliance with an SVA based testbench
 
 ## Current status
-* [Design & verification stage]({{< relref "doc/project/hw_dashboard" >}})
+* [Design & verification stage]({{< relref "hw" >}})
   * [HW development stages]({{< relref "doc/project/hw_stages.md" >}})
 * [Simulation results](https://reports.opentitan.org/hw/ip/i2c/dv/latest/results.html)
 

diff --git a/hw/ip/nmi_gen/data/nmi_gen.prj.hjson b/hw/ip/nmi_gen/data/nmi_gen.prj.hjson
@@ -4,6 +4,7 @@
 
 {
     name:               "nmi_gen",
+    design_spec:        "hw/ip/nmi_gen/doc",
     version:            "0.5",
     life_stage:         "L1",
     design_stage:       "D0",

diff --git a/hw/ip/padctrl/data/padctrl.prj.hjson b/hw/ip/padctrl/data/padctrl.prj.hjson
@@ -4,6 +4,8 @@
 
 {
     name:               "padctrl",
+    design_spec:        "hw/ip/padctrl/doc",
+    checklist:          "hw/ip/padctrl/doc/checklist",
     version:            "0.5",
     life_stage:         "L1",
     design_stage:       "D1",