[doc] clean up product, project documentation

_index.md

@@ -1,10 +1,8 @@
 # Introduction to OpenTitan
 
-The OpenTitan project aims to design and ship an open source, industry-leading piece of secure silicon for Root of Trust applications.
-OpenTitan is administered by lowRISC CIC as a collaborative
-[project]({{< relref "doc/project.md" >}})
-to produce high quality, open IP for instantiation as a full-featured
-[product]({{< relref "doc/product.md" >}}).
+[OpenTitan](https://opentitan.org) is an open source silicon Root of Trust (RoT) project.
+OpenTitan will make the silicon RoT design and implementation more transparent, trustworthy, and secure for enterprises, platform providers, and chip manufacturers.
+OpenTitan is administered by lowRISC CIC as a collaborative [project]({{< relref "doc/project" >}}) to produce high quality, open IP for instantiation as a full-featured product.
 This repository exists to enable collaboration across partners participating in the OpenTitan project.
 
 To get started using or contributing to the OpenTitan codebase, see the
@@ -13,6 +11,7 @@ For details on coding styles or how to use our project-specific tooling, see the
 [reference manuals]({{< relref "doc/rm" >}}).
 [This page]({{< relref "hw" >}})
 contains technical documentation on the SoC, the Ibex processor core, and the individual IP blocks.
+For questions about how the project is organized, see the [project]({{< relref "doc/project" >}}) landing spot for more information.
 
 ## Repository Structure
 
@@ -24,28 +23,21 @@ See also [repository readme]({{< relref "README.md" >}}) for licensing informati
 
 ## Documentation Sections
 
-* [Project]({{< relref "doc/project.md" >}})
+* [Project]({{< relref "doc/project" >}})
   * How the OpenTitan project is organized
-  * Governance of the program, how to get involved
   * Progress tracking
-* [Product]({{< relref "doc/product.md" >}})
-  * What is the OpenTitan product
-  * Architecture and technical hardware specifications
-  * Software roadmap
-  * Security and manufacturing
 * [User Guides]({{< relref "doc/ug" >}})
   * How to get started with the repo
   * How to emulate on an FPGA
+  * How hardware design is done in OpenTitan
   * How verification is done in OpenTitan
-  * How validation is done on FPGA in the project
 * [Reference Manuals]({{< relref "doc/rm" >}})
   * Defining comportable IP peripherals
-  * Coding style guides for Verilog, Python, and Markdown
+  * Coding style guides for Verilog, Python, Hjson, C/C++ and Markdown
   * OpenTitan tools
-  * Working with vendor tools
 * [Hardware Specifications]({{< relref "hw" >}})
   * Top-level SoC
   * Ibex processor core
   * Comportable IP blocks
 * [Tools]({{< relref "util" >}})
-  * Readme's of OpenTitan tools
+  * READMEs of OpenTitan tools

doc/project/_index.md

@@ -0,0 +1,18 @@
+---
+title: "Introduction to the OpenTitan Project"
+---
+
+OpenTitan is a collaborative hardware and software development program with contributors from many organization.
+This area gives some more information about how the project itself is organized.
+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 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.
+
+## Initiating new development
+
+The [OpenTitan RFC process]({{< relref "rfc_process" >}}) guides developers on how to initiate new development within the program.

doc/rm/checklist.md → doc/project/checklist.md

@@ -2,7 +2,7 @@
 title: "Signoff Checklist"
 ---
 
-This document explains the recommended checklist items to review when transitioning from one [Hardware Stage]({{<relref "/doc/ug/hw_stages.md" >}}) to another, for both design and verification stages.
+This document explains the recommended checklist items to review when transitioning from one [Hardware Stage]({{<relref "/doc/project/hw_stages.md" >}}) to another, for both design and verification stages.
 It is expected that the items in each stage (D1, V1, etc) are completed.
 
 ## D1

doc/project/hw_dashboard.md

@@ -3,6 +3,6 @@
 This dashboard gives the current status of
 [Comportable](/doc/rm/comportability_specification)
 designs within the OpenTitan project.
-See the [Hardware Development Stages](/doc/ug/hw_stages) for description of the hardware stages and how they are determined.
+See the [Hardware Development Stages]({{< relref "/doc/project/hw_stages.md" >}}) for description of the hardware stages and how they are determined.
 
 {{< dashboard "hw/ip" >}}

doc/ug/hw_stages.md → 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* (TODO: link), which gives the status of all of the designs in the OpenTitan repository.
+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 aims to mostly give a more defined structure to the process that is already followed.
 Proper versioning of RTL designs is a complex topic.
@@ -20,7 +20,7 @@ At the moment, this is strictly limited to a hardware design, but could be expan
 Transitions between these stages are decided by the Technical Committee via the RFC process.
 
 The first life stage is **Specification**.
-The proposed design is written up and submitted through the *RFC process* (TODO: link).
+The proposed design is written up and submitted through the [RFC process]({{< relref "doc/project/rfc_process" >}}).
 Depending on the complexity of the design and the guidance of the Technical Committee, it is possible a single design might require multiple RFCs.
 For example, a first RFC for the rationale, feature list, and a rough overview; followed by a more detailed RFC to get approval for the draft technical specification.
 As part of the specification process, the design author might reach out for feedback from a smaller group of reviewers while formulating an RFC proposal.
@@ -143,10 +143,9 @@ Transitions for Design and Verification stages are _self-nominated_ in the sense
 In this manner other reviewers can challenge the transition in the standard pull request review process.
 These transitions should be done in their own PR (i.e. not interspersed with other changes), and the PR summary and commit message should give any necessary detail on how the transition criteria have been met, as well as any other notes useful for a reviewer.
 
-The content below shows a proposal for the project file that contains the stage information.
-The final content, location, and name of that file will be updated in this space soon. (TODO)
-
-`file: gpio.prj.hjson`
+The content below shows the format of the project file that contains the stage information.
+The file for a design named `name` should be placed under `hw/ip/name/data/name.prj.hjson`.
+For example, `file: gpio.prj.hjson`:
 
 ```hjson
 {
@@ -155,6 +154,7 @@ The final content, location, and name of that file will be updated in this space
   life_stage: "L1",
   design_stage: "D2",
   verification_stage: "V1",
+  notes: "information shown on the dashboard"
 }
 ```
 
@@ -185,4 +185,4 @@ This would require a new RFC process, and thus the Life Stage would start again
 
 The stages are reported externally via a script-generated table exposed on the external website.
 This status will be a summary of all `prj.hjson` files of all designs in the system.
-The link to that table is here (TODO: link).
+The link to that table is [here]({{< relref "doc/project/hw_dashboard" >}}).