[doc] Consistently use title and headings
* Add a "title" attribute to make the page title show up in the
generated TOC. (The first heading isn't used there unfortunately.)
* The title serves as "h1" heading, use "h2" headings (`##`) and below
within the document.
Signed-off-by: Philipp Wagner <phw@lowrisc.org>
diff --git a/doc/project/development_stages.md b/doc/project/development_stages.md
index 3c81faa..b3a86ae 100644
--- a/doc/project/development_stages.md
+++ b/doc/project/development_stages.md
@@ -1,9 +1,8 @@
---
aliases: [/doc/project/hw_stages/]
+title: OpenTitan Hardware Development Stages
---
-# OpenTitan Hardware Development Stages
-
## Document Goals
This document describes development stages for hardware within the OpenTitan program.
diff --git a/doc/project/rfc_process.md b/doc/project/rfc_process.md
index 2e00b57..ef1873d 100644
--- a/doc/project/rfc_process.md
+++ b/doc/project/rfc_process.md
@@ -1,4 +1,6 @@
-# OpenTitan RFC Process
+---
+title: OpenTitan RFC Process
+---
## Introduction
diff --git a/doc/rm/device_interface_functions.md b/doc/rm/device_interface_functions.md
index 996222b..9aa65a6 100644
--- a/doc/rm/device_interface_functions.md
+++ b/doc/rm/device_interface_functions.md
@@ -2,21 +2,21 @@
title: "Device Interface Functions (DIFs)"
---
-# Motivation
+## Motivation
Every hardware peripheral needs some form of higher-level software to actuate it to perform its intended function.
Device Interface Functions (DIFs) aim to make it easy to use hardware for its intended purposes while making it difficult, or impossible, to misuse.
DIFs can be seen as a living best-practices document for interacting with a given piece of hardware.
-# Objectives
+## Objectives
DIFs provide extensively reviewed APIs for actuating hardware for three separate use cases: design verification, FPGA + post-silicon validation, and reference firmware including end-consumer applications.
-# Requirements
+## Requirements
-## Common Requirements
+### Common Requirements
-### Language
+#### Language
DIFs **must** be written in C, specifically [C11 (with a few allowed extensions)]({{< relref "doc/rm/c_cpp_coding_style.md#c-style-guide" >}}).
DIFs **must** conform to the style guide in [`sw/device/lib/dif/README.md`]({{< relref "sw/device/lib/dif/README.md" >}}).
@@ -34,7 +34,7 @@
This decision is motivated by the requirement that DIFs must be extremely flexible in their possible execution environments, including being hosted in bare metal, or being called from other languages such as Rust through Foreign Function Interface.
-### Runtime Independence
+#### Runtime Independence
DIFs **must not** depend on runtime services provided by an operating system.
If functions must be called in response to system stimulus such as interrupts then the DIF must make these requirements explicit in their documentation.
@@ -47,22 +47,22 @@
This highlights a clear separation of concern: making a pin on the package driven from the SPI block involves multiple systems.
By design, a DIF cannot coordinate cross-functional control.
-### Coverage Requirements
+#### Coverage Requirements
DIFs *must* actuate all of the specification-required functionality of the hardware that they are written for, and no more.
A DIF cannot be declared complete until it provides an API for accessing all of the functionality that is expected of the hardware.
This is distinct from mandating that a DIF be required to cover all of the functionality of a given piece of hardware.
-# Details
+## Details
-## Verification Stage Allowances
+### Verification Stage Allowances
DV, FPGA, and early silicon validation have unique requirements in their use of hardware.
They might actuate hardware on vastly different timescales, use verification-specific registers, or otherwise manipulate aspects of the hardware that “production"-level code would not (or cannot) do.
To this end, verification-only functionality may be added to a DIF **only** in modules that are included in verification.
This functionality **must not** be made accessible outside of verification environments, and is enforced by not including DV-specific code in non-DV builds.
-## Separation of Concerns and Stateful Information
+### Separation of Concerns and Stateful Information
In addition to the interface functions themselves, DIFs are expected to usually take the form of a structure that contains instance-specific information such as base register addresses and non-hardware-backed state required to actuate the hardware.
DIFs **should not** track hardware-backed state in their own state machine.
@@ -88,7 +88,7 @@
DIFs **must not** store or provide information in their implementation or state that is outside of their area of concern.
The number of timers in a system is the concern of the system, not the timer DIF.
-## Naming
+### Naming
All DIF functions **must** have clear direct objects and verbs, be written in the imperative mood, and follow the format of `dif_<object>_<verb_phrase>`.
The object in the name must be common to the DIF it appears it, and unique among DIFs.
@@ -109,7 +109,7 @@
Prefer common names: `init` is more commonly written than `initialize`, but `reset` is more commonly written than `rst`, for example.
This is a subjective call on the DIF author and reviewers' parts, so common agreement will be more useful than strict prescription.
-## Documentation
+### Documentation
All DIF exported types and functions **must** have associated API documentation.
All function parameters **must** be documented.
@@ -126,7 +126,7 @@
The programmers' guide must also include a list of DIF functions which relate to it, along with a brief description of each, and a link to further API documentation.
-## Source Layout
+### Source Layout
DIFs **must** live in the `sw/device/lib/dif` folder.
They **must** comprise at least one header unique to the hardware in question, and **may** contain more than one C file providing the implementation, if the complexity of the implementation warrants it (this is subjective).
@@ -136,7 +136,7 @@
This code must be placed in the directory belonging to the verification domain which the extension is applicable to.
Verification-specific extensions must not be built and included in production firmware builds.
-## Testing
+### Testing
Tests **must** live in the `sw/device/tests/dif` folder.
@@ -149,7 +149,7 @@
DIFs are also being used by DV for chip-level tests, which should help catch any issues with the DIFs not corresponding to the hardware implementation exactly.
These tests may not live in `sw/device/tests/dif`.
-## DIF Development Stages
+### DIF Development Stages
As part of the DIF Standardisation process, we've decided to establish more concrete DIF lifecycle stages.
These are documented with the [Development Stages]({{< relref "doc/project/development_stages.md" >}}).
@@ -162,7 +162,7 @@
The current proposal only covers a DIF being written against a single version of its respective hardware IP block.
This specifically excludes how to disambiguate DIFs in the repository that are written against different versions of the same IP block, or writing a single DIF that is compatible with multiple versions of an IP block.
-## Signoff Review
+### Signoff Review
The DIF lead author is expected to participate in the hardware IP block's L2 signoff review.
-This review can only happen once hardware design and verification are complete, and the DIF itself has reached stage S3.
\ No newline at end of file
+This review can only happen once hardware design and verification are complete, and the DIF itself has reached stage S3.
diff --git a/doc/ug/getting_started_sw.md b/doc/ug/getting_started_sw.md
index f0c2aab..dbf54e2 100644
--- a/doc/ug/getting_started_sw.md
+++ b/doc/ug/getting_started_sw.md
@@ -1,4 +1,6 @@
-# Build Software
+---
+title: Build Software
+---
## Prerequisites
@@ -80,4 +82,4 @@
```
If you do not specify your own toolchain configuration file (using `./meson_init.sh -t`), and `meson_init.sh` cannot find the default configuration in your toolchain, the legacy `toolchain.txt` from the main OpenTitan repository will be used.
-If `TOOLCHAIN_PATH` is set, this will be used to update any paths within the legacy configuration.
\ No newline at end of file
+If `TOOLCHAIN_PATH` is set, this will be used to update any paths within the legacy configuration.
diff --git a/doc/ug/getting_started_verilator.md b/doc/ug/getting_started_verilator.md
index 4efdf56..d9b61a9 100644
--- a/doc/ug/getting_started_verilator.md
+++ b/doc/ug/getting_started_verilator.md
@@ -1,4 +1,6 @@
-# Getting started with Verilator
+---
+title: Getting started with Verilator
+---
## About Verilator
diff --git a/doc/ug/github_notes.md b/doc/ug/github_notes.md
index 22d2b00..e442de0 100644
--- a/doc/ug/github_notes.md
+++ b/doc/ug/github_notes.md
@@ -1,4 +1,6 @@
-# GitHub Notes
+---
+title: GitHub Notes
+---
The OpenTitan source tree is maintained on GitHub in a [monolithic repository](https://github.com/lowRISC/opentitan) called opentitan.
diff --git a/doc/ug/install_instructions/index.md b/doc/ug/install_instructions/index.md
index 0adee47..edb5e11 100644
--- a/doc/ug/install_instructions/index.md
+++ b/doc/ug/install_instructions/index.md
@@ -1,5 +1,6 @@
-# Install Build Requirements
-
+---
+title: Install Build Requirements
+---
## System requirements
diff --git a/doc/ug/otbn_sw.md b/doc/ug/otbn_sw.md
index ee6ff7f..82485a4 100644
--- a/doc/ug/otbn_sw.md
+++ b/doc/ug/otbn_sw.md
@@ -10,16 +10,16 @@
The core of OTBN's instruction set is based on RV32I, the RISC-V base integer instruction set.
As such, we implement the toolchain as a thin wrapper around RISC-V binutils.
-# Assembly format and examples
+## Assembly format and examples
The OTBN ISA and programmer model are described in the [OTBN reference manual]({{< relref "hw/ip/otbn/doc" >}}).
In particular, note that the register `x1` has special stack-like behaviour.
There are some example programs at `sw/otbn/code-snippets`.
These range from simple examples of how to use pseudo-operations up to example cryptographic primitives.
-# The tools
+## The tools
-## Assembler
+### Assembler
The OTBN assembler is called `otbn-as` and can be found at `hw/ip/otbn/util/otbn-as`.
This has the same command line interface as `riscv32-unknown-elf-as` (indeed, it's a wrapper around that program).
@@ -31,7 +31,7 @@
hw/ip/otbn/util/otbn-as -o foo.o foo.S
```
-## Linker
+### Linker
The OTBN linker is called `otbn-ld` and can be found at `hw/ip/otbn/util/otbn-ld`.
This is a thin wrapper around `riscv32-unknown-elf-ld`, but supplies a default linker script that matches the OTBN memory layout.
@@ -44,7 +44,7 @@
hw/ip/otbn/util/otbn-ld -o foo foo0.o foo1.o foo2.o
```
-## Objdump
+### Objdump
To disassemble OTBN code, use `otbn-objdump`, which can be found at `hw/ip/otbn/util/otbn-objdump`.
This wraps `riscv32-unknown-elf-objdump`, but correctly disassembles OTBN instructions when run with the `-d` flag.
diff --git a/doc/ug/vendor_hw.md b/doc/ug/vendor_hw.md
index ba29437..8e33215 100644
--- a/doc/ug/vendor_hw.md
+++ b/doc/ug/vendor_hw.md
@@ -1,4 +1,6 @@
-# Work with hardware code in external repositories
+---
+title: Work with hardware code in external repositories
+---
OpenTitan is not a closed ecosystem: we incorporate code from third parties, and we split out pieces of our code to reach a wider audience.
In both cases, we need to import and use code from external repositories in our OpenTitan code base.
