doc/ug/design.md

# Design Methodology within OpenTitan

The design methodology within OpenTitan combines the challenges of industry-strength design methodologies with open source ambitions.
When in conflict, quality must win, and thus we aim to create a final design product that is equal to the quality required from a full production silicon chip tapeout.

## Language and Tool Selection

Starting with the language, the strategy is to use the SystemVerilog language, restricted to a feature set described by our
[Verilog Style Guide](https://github.com/lowRISC/style-guides/blob/master/VerilogCodingStyle.md).
All IP should be developed and delivered under the feature set described by this style guide.
Inconsistencies or lack of clarity within the style guide should be solved by filing and helping close an issue on the style guide in the
[lowrisc/style-guides GitHub repo](https://github.com/lowRISC/style-guides).

For professional tooling, the team has chosen several industry-grade tools for its design signoff process.
Wherever possible we attempt to remain tool-agnostic, but we must choose a selection of tools as our ground truth for our own confidence of signoff-level assurances.
As a project we promote other open source methodologies and work towards a future where these are signoff-grade.
The discussions on how the design tools are used and which ones are chosen are given below in separate sections.

## Comportability and the Importance of Architectural Conformity

The OpenTitan program is adopting a design methodology aimed at unifying as much as possible the interfaces between individual designs and the rest of the SOC.
These are detailed in the [Comportability Specification](../rm/comportability_specification.md).
This document details how peripheral IP interconnects with the embedded processor, the chip IO, other designs, and the security infrastructure within the SOC.
Not all of the details are complete at this time, but will be tracked and finalized within that specification.

TODO: briefly discuss key architectural decisions, and how we came to the conclusion, with pointers to more thorough documentation. List?
*   Processor/RISC-V strategy
*   Bus strategy
*   Reset strategy

## Defining Design Complete: milestones and tracking

Designs within the OpenTitan project come in a variety of completion status levels.
Some designs are “tapeout ready” while others are still a work in progress.
Understanding the status of a design is important to gauge the confidence in its advertised feature set.
To that end, we’ve designated a spectrum of design milestones in the *OpenTitan IP project tracking* <Coming Soon&rt; document.
This document defines the design milestones and references where one can find the current status of each of the designs in the repository.

## Documentation

Documentation is a critical part of any design methodology.
Within the OpenTitan project there are two important tooling components to efficient and effective documentation.
The first is the [docgen](../../util/docgen/README.md) tool, which converts an annotated markdown file into a rendered HTML file (including this document).
See the linked docgen specification for information about the annotations and how to use it to create enhanced auto-generated additions to standard Markdown files.
The second is the [reggen](../rm/register_tool.md) register tool that helps define the methodology and description language for specifying hardware registers.
These descriptions are fed into docgen through annotations and ensure that the technical specifications for the IP are accurate and up to date with the hardware being built.

Underlying and critical to this tooling is the human-written content that goes into the source markdown and register descriptions.
Clarity and consistency is key, and we will add guidelines for technical specification documentation flow. (TODO).

## Usage of Register Tool

One design element that is prime for consistent definitions and usages is in the area of register definitions.
Registers are critical, being at the intersection of hardware and software, where uniformity can reduce confusion and increase reusability.
The [register tool](../rm/register_tool.md) used within OpenTitan is custom for the project’s needs, but flexible to add new features as they arise.
It attempts to stay lightweight yet solve most of the needs in this space.
The description language (using HJSON format) described within that specification also details other features described in the
[Comportability Specification](../rm/comportability_specification.md).
See those two specifications as well as the [Markdown Style Guide](../rm/markdown_usage_style.md) for details on the tool and the description language.

## Linting Methodology

Linting is a productivity tool for designers to quickly find typos and bugs at the time when the RTL is written.
Capturing fast and efficient feedback on syntactic and semantic (as well as style) content early in the process proves to be useful for high quality as well as consistent usage of the language.
Running lint is especially useful with SystemVerilog, a weakly-typed language, unlike more modern hardware description languages.
Running lint is faster than running a simulation.

The tool [AscentLint](https://www.realintent.com/rtl-linting-ascent-lint) from the company Real Intent was chosen for this project.
It has the benefit of fast execution times, and provides a list of concise lint errors and warnings.
It is understandable that not all partner members will have access to this tool.
The project will use AscentLint as its linting sign-off tool, and results will be shared in some form through continuous integration build results, published tool outputs, pre-submit checks, and/or linting summaries of tool output (final decision TBD).
For partners without access to this tool, the recommendation is to run their code through whatever linting tool they have available at their disposal before creating a design Pull Request, then work with the maintainers of the linting sign-off methodology to close linting errors.
(TODO: decide on available pre-submit linting options).
Linting errors and warnings can be closed by fixing the code in question (preferred), or waiving the error.

Due to the proprietary nature of this particular linting tool, content towards running the tool can not be checked in in an open source repository.
In the current state of the project, all lint scripts, policy files, and waivers are **not** provided, but are being kept privately until we can suggest a workable open source solution.
When this methodology is finalized the details will be given here. (TODO)
See the [Linting README](../../hw/lint/README.md) for details on how the tool is being run internally.
This shows the methodology that we are aiming to release in a fully open manner, but for now is being run, with results shared among partner members.

Goals for linting closure per design milestone are given in the *OpenTitan IP project tracking* <Coming Soon> document.

## Assertion Methodology

The creation and maintenance of assertions within RTL design code is an essential way to get feedback if a design is being used improperly.
Common examples include asserting that a full FIFO should never be written to, a state machine doesn’t receive an input while in a particular state, or two signals should remain mutually exclusive.
Usually these will eventually result in a downstream error (incorrect data, bus collisions, etc) but early feedback at the first point of inconsistency gives designers and verifiers alike fast access to easier debug.

Within OpenTitan we attempt to maintain uniformity in assertion style and syntax using SystemVerilog Assertions and a list of common macros.
An overview of the included macros and how to use them is given in this
[Design Assertion README file](../../hw/formal/README.md).
This document also describes how to formally verify assertions using
[JasperGold](https://www.cadence.com/content/cadence-www/global/en_US/home/tools/system-design-and-verification/formal-and-static-verification/jasper-gold-verification-platform/formal-property-verification-app.html)
from the company Cadence.

## CDC Methodology

Logic designs that have signals that cross from one clock domain to another unrelated clock domain are notorious for introducing hard to debug problems.
The reason is that design verification, with its constant and unrealistic timing relationships on signals, does not represent the variability and uncertainty of real world systems.
For this reason, maintaining a robust Clock Domain Crossing verification strategy ("CDC methodology") is critical to the success of any mutli-clock design.

Our general strategy is threefold:
maintain a list of proven domain crossing submodules;
enforce the usage of these submodules;
use a production-worthy tool to check all signals within the design conform to correct crossing rules.
This *CDC Methodology document* <Coming Soon> gives details on the submodules, discusses the tool chosen and how to run it, and explains more rationale for the designs chosen.

The tool chosen for this program is
[Meridian]([https://www.realintent.com/clock-domain-crossing-meridian-cdc](https://www.realintent.com/clock-domain-crossing-meridian-cdc))
from RealIntent.
It is a sign-off-grade CDC checking tool that provides the features needed for CDC assurance.
It is understandable that not all partner members will have access to this tool.
The project will use it as its sign-off tool, and results will be shared in some form (final decision TBD).
CDC checking errors can be closed by fixing the code in question (preferred), or waiving the error.
All CDC waivers will be reviewed as part of the Pull Request review process.
See the *CDC README* <Coming Soon> for details on how to run the tool if you have a Meridian license.

Similar to the linting tool, due to the proprietary nature of the CDC tool, some content towards running the tool can not be checked in in an open source repository.
For those items, the tool provider will be giving us a method to check in encrypted content that still allows for full functionality without exposing their tool’s feature set.
When this methodology is finalized the details will be given here. (TODO)

## DFT

Design For Testability is another critical part of any design methodology.
It is the preparation of a design for a successful manufacturing test regime.
This includes, but is not limited to, the ability to use scan chains for testing digital logic;
the optimization of design logic to allow maximum access of test logic for fault coverage;
the ability to observe and control memory cells and other storage macros;
the control of analog designs and other items that are often outside the reach of test logic;
built in self test (BIST) insertion for logic and memories.
In this context, our primary concern at this stage is what impact does this have on the RTL that makes up the IP in our library.

DFT in OpenTitan is particularly interesting for two primary reasons:
the RTL in the OpenTitan repository is targeted towards an FPGA implementation, but must be prepared for a silicon implementation
(see the FPGA vs Silicon discussion in the [OpenTitan Product](../../doc/product.md) document);
the whole purpose of a DFT methodology is full and efficient access to all logic and storage content,
while the whole purpose of a security microcontroller is restricting access to private secured information.
In light of the latter dilemma, special care must be taken in a security design to ensure DFT has access at only the appropriate times, but not while in use in production.

At this time the DFT methodology for OpenTitan is not finalized.
The expectation is that the RTL collateral will undergo a DFT introduction -
likely with the propagation of such signals as `testmode`, `scanmode`, `bistmode`, etc -
at a stage before final project completion.
At this point there are a few references to such signals but they are not yet built into a coherent whole.
At that future time the DFT considerations will be fully documented and carried out throughout all IP.

## Generated Code

The OpenTitan project contains a lot of generated code through a variety of methods.
Most modern SystemVerilog-based projects work around the weaknesses in the language in such a way.
But our first goal is to take full advantage of the language as much as possible, and only resort to generated code where necessary.

At the moment, all generated code is checked in with the source files.
The pros and cons of this decision are still being discussed, and the decision may be reversed, to be replaced with a master build-all script to prepare a final design as source files changed.
Until that time, all generated files (see for example the output files from the
[register generation tool](../rm/register_tool.md))
are checked in.
There is a master build file in the repository under `hw/Makefile` that builds all of the `regtool` content.
This is used by an Azure Pipelines presubmit check script to ensure that the source files produce a generated file that is identical to the one being submitted.

## Getting Started with a Design

The process for getting started with a design involves many steps, including getting clarity on its purpose, its feature set, ownership assignments, documentation, etc.
These are discussed in the *Getting Started with a Design* <Coming Soon> document that is still being developed.