| aliases | |
|---|---|
|
This document describes development stages for hardware within the OpenTitan program. 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 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. This document proposes a sensible path forwards, but this may be revisited as we gain further experience and get more feedback.
The stages listed here are created to give insight into where a design is in its life from specification to silicon-ready signoff. At the moment, this is strictly limited to a hardware design, but could be expanded to other components of development within OpenTitan. 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]({{< 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. RFCs are always shared with the wider OpenTitan community prior to vote by the Technical Committee. However, wherever there is potentially sensitive material from a future certification standpoint it should be passed through the security review team. Once the specification has been shared with the OpenTitan audience and sufficient review has been completed, this phase is exited.
The next life stage is Development. The hardware IP is being developed in GitHub, the specification is converted to Markdown, and design and verification planning is underway. This is a long phase expected to last until a more formal review is requested for full completion signoff. When in Development phase, the stage tracking of the design and verification milestones are valid. See those sections that follow for details there. To exit this stage, a signoff process review must occur. See the section on signoff for details.
The final life stage is Signed Off. At this point, a design is frozen and not expected to be updated. There are exceptions if post-signoff bugs are found, in which case the stage returns to Development and the version number is not updated. Feature requests towards a signed-off design requires review and approval by the Technical Committee. Once accepted, it results in creating a new version and return a design to the appropriate life stage, based upon the size of the change. See the Versioning section of the document for more discussion. Signed off fully-functioning (read: not buggy) designs stay in the Signoff stage as an available complete IP, with an associated revision ID.
There exists a template for IP checklists. The DIF stages use a separate, software-specific checklist. All the checklist items are listed in the [Signoff Checklist]({{< relref "doc/project/checklist.md" >}}).
| Stage | Name | Definition |
|---|---|---|
| L0 | Specification | Specification is being written, is in review process |
| L1 | Development | Design is in development in GitHub, possibly integrated in top level |
| L2 | Signed Off | Design has been frozen at version number, signed off, available for tapeout |
We may later evaluate adding a Silicon Proven stage, after deciding criteria for a tapeout to qualify as proven.
The following development milestones are for hardware peripheral designs, i.e. SystemVerilog RTL development. They are similar to typical chip design milestones, but less rigid in the movement from one stage to the next. The metric here is the quality bar and feature completeness of the design.
The first design stage is Initial Work. This indicates the period of time between the Specification life stage and the RTL being functional enough to pass sanity checks. The RTL is still in progress, registers being defined, etc. Once the device has passed a basic sanity check, has the lint flow setup, has the registers completely defined, it has completed the Initial Work stage.
The second design stage is Functional. In this stage, the design is functional but not complete. Once all of the features in the specification are implemented, it has completed this stage.
The third design stage is Feature Complete. In this phase, no changes are expected on the design except for bug fixes. Once all bugs have fixed, lint and CDC violations cleaned up, the design moves into its final stage: Design Complete.
| Stage | Name | Definition |
|---|---|---|
| D0 | Initial Work | RTL being developed, not functional |
| D1 | Functional |
|
| D2 | Feature Complete |
|
| D3 | Design Complete |
|
The following development milestones are for hardware peripheral verification work. They are similar to typical chip verification milestones, but less rigid in the movement from one stage to the next. The metric here is the progress towards testing completion and proof of testing coverage. The verification stages can be applied to simulation-based DV and formal property verification (FPV) approaches.
The first verification stage is Initial Work. This indicates the period of time between the beginning of verification planning and the testbench up and running. The testbench is still being created, scoreboards implemented, testplan being written, nightly regressions running, etc. Once the verification environment is available for writing tests, with a testplan written, it has completed the Initial Work stage.
The second verification stage is Under Test. In this stage, the verification environment is available but not tests in the testplan are completed. Once all of the items in the testplan are implemented, it exits this stage.
The third verification stage is Testing Complete. In this phase, no changes are expected on the testplan, no changes expected on the testbench, and no new tests are expected except to complete full coverage of the design. Once all coverage metrics have been met, waivers checked, the verification moves into its final stage: Verification Complete.
Stages for simulation-based DV:
| Stage | Name | Definition |
|---|---|---|
| V0 | Initial Work | Testbench being developed, not functional; testplan being written; decided which methodology to use (sim-based DV, FPV, or both). |
| V1 | Under Test |
|
| V2 | Testing Complete |
|
| V3 | Verification Complete |
|
Stages for FPV approaches:
| Stage | Name | Definition |
|---|---|---|
| V0 | Initial Work | Testbench being developed, not functional; testplan being written; decided which methodology to use (sim-based DV, FPV, or both). |
| V1 | Under Test |
|
| V2 | Testing Complete |
|
| V3 | Verification Complete |
|
The following development stages are for [Device Interface Function (DIF)]({{< relref "doc/rm/device_interface_functions.md" >}}) work. These milestones have a slightly different emphasis to the hardware design and verification milestones, because software is much easier to change if bugs are found. The metric they are trying to capture is the stability and completeness of a low-level software interface to hardware design. We are aiming to keep this process fairly lightweight in the early stages, and not significantly burdeonsome to the associated HW designer through all stages.
There are explicit checkpoints in these stages to ensure that DIF development does not overtake design and verification.
The first DIF stage is Initial Work. This indicates the period of time between starting the software API, and it being complete enough for other software to start using it. The exact API is still being defined. Once the DIF is complete enough to cover all existing in-tree uses of the device, and has mock tests, it has completed the Initial Work stage.
The second stage is Functional. In this stage, the DIF can be used for basic operations, but may not cover all the specified functionality of the device. Once the DIF is complete enough to cover all the functionality of the device, in the way the hardware designer envisioned; is used for both DV testing; and can be used Tock, it has completed this stage.
The third stage is Complete. In this stage, no changes to the interface are expected. Once testing is complete, and we are satisfied that the interface will not change (except for bug fixes), the DIF moves into its final stage: Stable.
| Stage | Name | Definition |
|---|---|---|
| S0 | Initial Work | Work has started on a DIF for the given IP block. |
| S1 | Functional |
|
| S2 | Complete |
|
| S3 | Stable |
|
At the end of the final design and verification phase, the IP block should be proposed to the Technical Committee as ready for sign-off. This will be done by submitting an RFC (possibly following a suggested template). The Technical Committee may decide to nominate individuals to evaluate the codebase and make a recommendation or may review directly. Generally, this process would involve:
- Specification and RTL are re-reviewed for readability, consistency, and code coverage standards
- All design items are complete, reviewed against committed specification
- All lint and CDC errors and warnings are waived, waivers reviewed
- Test plan is re-reviewed for completeness
- All test items are confirmed complete
- All code coverage items are completed or waived
- Performance requirements are reviewed, performance metrics met
- Software interface (DIF) files are completed, tested, and signed off by software representative
The process will be refined by the Technical Committee as necessary.
Stages are indicated via a text file checked into the GitHub and thus transitions can be reviewed through the standard pull request process. Transitions for Design and Verification stages are self-nominated in the sense that the design or verification owner can modify the text file and submit a pull request (PR) to transition the stage. 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 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:
{
name: "gpio"
version: 1.0
life_stage: "L1"
design_stage: "D2"
verification_stage: "V1"
dif_stage: "S0"
notes: "information shown on the dashboard"
}
When a design transitions from one stage to another, the project file can optionally provide a commit ID for the transition to be able to recreate the repository at the point of that transition. This is optional for all transitions except for signoff, where it is required. The commit ID has its own entry in the project Hjson file, as shown below.
{
name: "gpio"
version: 1.0
life_stage: "L1"
design_stage: "D2"
verification_stage: "V1"
dif_stage: "S0"
commit_id: "92e4298f8c2de268b2420a2c16939cd0784f1bf8"
notes: "information shown on the dashboard"
}
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.
{
design_spec: "hw/ip/gpio/doc"
dv_plan: "hw/ip/gpio/doc/dv_plan"
hw_checklist: "hw/ip/gpio/doc/checklist"
sw_checklist: "sw/device/lib/dif/dif_gpio"
}
The Version of a design element indicates its progress towards its final feature set for expected product. Typically all designs are expected to simply be in 1.0 version, but there are reasons for exceptions. Designs which have a specification that defines an intermediate goal are indicated as < 1.0 version. There are many times where this is useful: when the intermediate goal is a beneficial subset of functionality to enable other development; when the final feature set is not known but a sufficient set is ready for development; when the final feature set is postponed until a future date, but owners are keen to get the design started; etc. In essence, the sub-1.0 designation indicates that it is understood that the stage metrics are temporary pending a final feature set. Rarely will a sub-1.0 design be taken past Feature Complete and Testing Complete stages. An exception is as proof of concept to show what a signoff process looks like for a design that has modifications expected in the future. This was the case with public launch, where we took five designs to completion to test out the signoff process, the verification methodology, and the checklist system. In several of these cases, the feature set was not final product complete.
Once a design has completed all stages for a product feature set, the Signoff process intends to end all development for that design.
Its Life Stage should transition to Signoff after the review process, and no more modifications should be made.
The commit ID of the version that was signed off is recorded in the commit_id field of the .prj.hjson file.
After signoff, three events could cause a change. Possibility 1: If a bug is found in top-level testing, software development, etc., the design should stay in its current revision (assumedly 1.0) but revert in design and/or verification staging until the bug is fixed and a new signoff process occurs, followed by a new tag to replace the previous one. Possibility 2: if a small collection of new features are requested, a new version increment of 0.1 would be created, and the design and verification stages would be reset. The expectation is that this would create its life as a newly tracked revision number, while the previous (assumedly 1.0) version retains its status. Possibility 3: if enough new features are requested to greatly change the spirit of the design, a new version increment of 1.0 would be created in a fashion similar to above. This would require a new RFC process, and thus the Life Stage would start again as L0 - Specification.
Over the course of the project, designs may regress from signed off to "opened" when new features are added. When regressing a signed off design, the old signed off version should remain in the project file as a retrievable version. This is indicated as two versions as shown in this example.
{
name: "uart",
revisions: [
{
version: "1.0",
life_stage: "L2",
design_stage: "D3",
verification_stage: "V3",
dif_stage: "S0",
commit_id: "92e4298f8c2de268b2420a2c16939cd0784f1bf8",
notes: ""
}
{
version: "1.1",
life_stage: "L1",
design_stage: "D2",
verification_stage: "V2",
dif_stage: "S0",
commit_id: "f3039d7006ca8ebd45ae0b52b22864983876175d",
notes: "Rolled back to D2 as the register module is updated",
}
]
}
One may choose to commemorate a non-signed off version of a design if it reached enough maturity to be a useful version to checkpoint before regressing. In this case the version number should also be incremented.
No hard rules for version numbering are mandated at this stage. The subject will be revisited as we get closer to locking down the design to take it to a silicon implementation milestone.
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 "hw" >}}).