[doc] Update Hugo's document index.
Cleanup Hugo's software documentation.
1. Add _index.md files under sw/ directory to unflatten the directory
index.
2. Update README.md files with Hugo document headers.
3. Skip README.md files that don't have documentation intended for
docs.opentitan.org.
Signed-off-by: Miguel Osorio <miguelosorio@google.com>
diff --git a/site/docs/config.toml b/site/docs/config.toml
index b05e14c..397d608 100644
--- a/site/docs/config.toml
+++ b/site/docs/config.toml
@@ -47,6 +47,8 @@
".*\\.clang-format$",
"/__pycache__/*",
"/build/*",
+ "/ci/",
+ "/sw/device/tock/chips/*",
"/hw/vendor/*",
"/sw/vendor/*",
"/meson.build$",
diff --git a/sw/README.md b/sw/README.md
index 359dabc..102d15c 100644
--- a/sw/README.md
+++ b/sw/README.md
@@ -1,12 +1,11 @@
-# OpenTitan Software
-
-This subtree contains all software intended to run on the OpenTitan chip, as well as some tools.
-
-## Building
+---
+title: "OpenTitan Software Build Instructions"
+---
OpenTitan software is built using [Meson](https://mesonbuild.com), although OpenTitan's project structure is sufficiently idiosyncratic that we use a custom workflow.
For example, to build the OpenTitan executable located at `sw/device/examples/hello_world` for FPGA, run the following commands:
+
```console
$ cd "$REPO_TOP"
$ ./meson_init.sh
diff --git a/sw/_index.md b/sw/_index.md
index 26a3033..4123f28 100644
--- a/sw/_index.md
+++ b/sw/_index.md
@@ -26,46 +26,6 @@
Device software must be written in C, Assembly, or Rust.
-## Reference Firmware Images
-
-The OpenTitan Reference Firmware Images together make up the Opentitan Reference Firmware Stack.
-Different images are used for different boot stages.
-
-The Reference Firmware Images are, in boot order:
-1. The [Mask ROM]({{< relref "sw/device/silicon_creator/mask_rom/docs" >}}) (in `sw/device/mask_rom`), executed at chip reset;
-2. The ROM_EXT (in `sw/device/silicon_creator/rom_exts`), the second stage Silicon Creator code, executed from flash; and
-3. The [Tock Image]({{< relref "sw/device/tock/README.md" >}}) (in `sw/device/tock`), the Silicon Owner code, also executed from flash.
-
-### Testing-only Images
-
-There are also some other standalone firmware images in the repository, which are only used for testing.
-
-* [`sw/device/tests`]({{< relref "sw/device/tests/README.md" >}}) contains many standalone smoke test images.
- This directory also contains unit tests for software modules, which are executed on host (not device) systems using [GoogleTest](https://github.com/google/googletest).
-
-* [`sw/device/benchmarks/coremark`]({{< relref "sw/device/benchmarks/coremark/README.md" >}}) contains infrastructure for running the [CoreMark](https://github.com/eembc/coremark) benchmark suite on the OpenTitan device.
-* `sw/device/riscv_compliance_support` contains infrastructure so we can run the [RISC-V Compliance](https://github.com/riscv/riscv-compliance) tests on the OpenTitan core.
-* `sw/device/sca` contains on-device software used for Side-Channel Analysis.
-* `sw/device/prebuilt` contains pre-built Tock images, which may not be up-to-date.
-* `sw/device/examples` contains example images, including a simple [Hello World]({{< relref "sw/device/examples/hello_world/README.md" >}}).
-
-There are also prototype versions of some of the boot stages, now only used for testing:
-* [`sw/device/boot_rom`]({{< relref "sw/device/boot_rom/README.md" >}}) is a previous, testing-only version of the Mask ROM.
-* `sw/device/exts` contains software for our prototype second boot stage images.
-
-## Firmware Libraries
-
-
-The OpenTitan repository also contains device libraries which are used within our Reference Firmware Images, and can (and should) be used by other OpenTitan device software.
-
-These are organised into the `sw/device/lib` directory.
-
-* [`sw/device/lib/base`]({{< relref "sw/device/lib/base/README.md" >}}) contains the Base Libraries, including [freestanding C library headers]({{< relref "sw/device/lib/base/freestanding/README.md" >}}).
- The Base Libraries are simple libraries that can be used by any other OpenTitan device software libraries.
-* [`sw/device/lib/dif`]({{< relref "sw/device/lib/dif/README.md" >}}) contains the [Device Interface Functions]({{< relref "doc/rm/device_interface_functions.md" >}}).
-* [`sw/device/lib/arch`]({{< relref "sw/device/lib/arch/README.md" >}}) contains the libraries to be used on specific device configurations (for instance FPGA, Simulation, etc.).
-* [`sw/device/lib/runtime`]({{< relref "sw/device/lib/runtime/README.md" >}}) contains general libraries for more advanced on-device functionality (including logging, printing, and interacting with the RISC-V core).
-
# OTBN Software
This software runs on the OTBN cryptographic co-processor within the OpenTitan platform chip.
diff --git a/sw/device/_index.md b/sw/device/_index.md
new file mode 100644
index 0000000..916dd91
--- /dev/null
+++ b/sw/device/_index.md
@@ -0,0 +1,36 @@
+---
+title: "OpenTitan Device Software"
+---
+
+## Reference Firmware Images
+
+The OpenTitan Reference Firmware Images together make up the Opentitan Reference Firmware Stack.
+Different images are used for different boot stages.
+
+The Reference Firmware Images are, in boot order:
+
+1. The [Mask ROM]({{< relref "sw/device/silicon_creator/mask_rom/docs" >}}) (in `sw/device/mask_rom`), executed at chip reset;
+2. The ROM_EXT (in `sw/device/silicon_creator/rom_exts`), the second stage Silicon Creator code, executed from flash; and
+3. The [Tock Image]({{< relref "sw/device/tock/README.md" >}}) (in `sw/device/tock`), the Silicon Owner code, also executed from flash.
+
+### Testing-only Images
+
+There are also some other standalone firmware images in the repository, which are only used for testing.
+
+- [`sw/device/tests`]({{< relref "sw/device/tests/README.md" >}}) contains many standalone smoke test images.
+ This directory also contains unit tests for software modules, which are executed on host (not device) systems using [GoogleTest](https://github.com/google/googletest).
+
+- [`sw/device/benchmarks/coremark`]({{< relref "sw/device/benchmarks/coremark/README.md" >}}) contains infrastructure for running the [CoreMark](https://github.com/eembc/coremark) benchmark suite on the OpenTitan device.
+- `sw/device/riscv_compliance_support` contains infrastructure so we can run the [RISC-V Compliance](https://github.com/riscv/riscv-compliance) tests on the OpenTitan core.
+- `sw/device/sca` contains on-device software used for Side-Channel Analysis.
+- `sw/device/prebuilt` contains pre-built Tock images, which may not be up-to-date.
+- `sw/device/examples` contains example images, including a simple [Hello World]({{< relref "sw/device/examples/hello_world/README.md" >}}).
+
+There are also prototype versions of some of the boot stages, now only used for testing:
+
+- [`sw/device/boot_rom`]({{< relref "sw/device/boot_rom/README.md" >}}) is a previous, testing-only version of the Mask ROM.
+- `sw/device/exts` contains software for our prototype second boot stage images.
+
+## Documentation Index
+
+{{% sectionContent %}}
diff --git a/sw/device/benchmarks/coremark/README.md b/sw/device/benchmarks/coremark/README.md
index 56dfc20..d66f7a4 100644
--- a/sw/device/benchmarks/coremark/README.md
+++ b/sw/device/benchmarks/coremark/README.md
@@ -1,4 +1,8 @@
-# Building CoreMark
+---
+title: "CoreMark Benchmark"
+---
+
+## Building CoreMark
To build CoreMark under meson:
@@ -14,7 +18,7 @@
giving directly to `--meminit` for Verilator) which can be found in
`build-bin/sw/device/fpga/benchmarks/coremark`
-# CoreMark Options
+## CoreMark Options
The meson build script alters ITERATIONS (specifying how many iterations
CoreMark does) depending on whether it is a sim-verilator or an fpga build. 1
diff --git a/sw/device/boot_rom/README.md b/sw/device/boot_rom/README.md
index 621eb46..abc41f3 100644
--- a/sw/device/boot_rom/README.md
+++ b/sw/device/boot_rom/README.md
@@ -1,4 +1,6 @@
-# Boot ROM Overview
+---
+title: "Test Boot ROM"
+---
The Boot ROM is a **testing-only** device image.
The [Mask ROM]({{< relref "sw/device/silicon_creator/mask_rom/docs/index.md" >}}) is the reference implementation of the OpenTitan Secure Boot specification.
diff --git a/sw/device/examples/_index.md b/sw/device/examples/_index.md
new file mode 100644
index 0000000..914593e
--- /dev/null
+++ b/sw/device/examples/_index.md
@@ -0,0 +1,7 @@
+---
+title: "Example Programs"
+---
+
+## Documentation Index
+
+{{% sectionContent %}}
diff --git a/sw/device/examples/hello_world/README.md b/sw/device/examples/hello_world/README.md
index 2ae418c..59f1b8e 100644
--- a/sw/device/examples/hello_world/README.md
+++ b/sw/device/examples/hello_world/README.md
@@ -1,4 +1,9 @@
+---
+title: "Hello World"
+---
+
## Overview
+
`Hello_world` is the demo program used to show case basic functionality of the system.
The test itself does 2 main things:
* Echo pin changes over UART.
diff --git a/sw/device/lib/_index.md b/sw/device/lib/_index.md
new file mode 100644
index 0000000..a1afd51
--- /dev/null
+++ b/sw/device/lib/_index.md
@@ -0,0 +1,29 @@
+---
+title: "Device Libraries"
+---
+
+## Overview
+
+The OpenTitan repository contains device libraries which are used within our
+Reference Firmware Images, and can (and should) be used by other OpenTitan
+device software.
+
+These are organised into the `sw/device/lib` directory.
+
+- [`sw/device/lib/base`]({{< relref "sw/device/lib/base/README.md" >}})
+ contains the Base Libraries, including
+ [freestanding C library headers]({{< relref "sw/device/lib/base/freestanding/README.md" >}}).
+ The Base Libraries are simple libraries that can be used by any other OpenTitan device software libraries.
+- [`sw/device/lib/dif`]({{< relref "sw/device/lib/dif/README.md" >}})
+ contains the
+ [Device Interface Functions]({{< relref "doc/rm/device_interface_functions.md" >}}).
+- [`sw/device/lib/arch`]({{< relref "sw/device/lib/arch/README.md" >}})
+ contains the libraries to be used on specific device configurations (for
+ instance FPGA, Simulation, etc.).
+- [`sw/device/lib/runtime`]({{< relref "sw/device/lib/runtime/README.md" >}})
+ contains general libraries for more advanced on-device functionality
+ (including logging, printing, and interacting with the RISC-V core).
+
+## Documentation Index
+
+{{% sectionContent %}}
diff --git a/sw/device/lib/arch/README.md b/sw/device/lib/arch/README.md
index 3ebfc18..cca41d8 100644
--- a/sw/device/lib/arch/README.md
+++ b/sw/device/lib/arch/README.md
@@ -1,4 +1,6 @@
-# Device-specific Symbols
+---
+title: "arch: Device-specific Symbols"
+---
This subtree provides the header `device.h`, which contains declarations for symbols that represent device-specific information, like the clock frequency.
@@ -18,7 +20,7 @@
device_lib,
],
)
-
+
# ...
endforeach
```
@@ -53,4 +55,4 @@
)
```
- Your device may be specialized and require symbols that are straight-up not meaningful on other devices.
- These symbols should be specified in a separate header in this subtree, and targets that use that header should not be declared using the `sw_lib_arch_core_devices` shorthand above.
\ No newline at end of file
+ These symbols should be specified in a separate header in this subtree, and targets that use that header should not be declared using the `sw_lib_arch_core_devices` shorthand above.
diff --git a/sw/device/lib/base/README.md b/sw/device/lib/base/README.md
index 84b1f1a..70fd503 100644
--- a/sw/device/lib/base/README.md
+++ b/sw/device/lib/base/README.md
@@ -1,4 +1,6 @@
-# `libbase`, the OpenTitan Standard Library
+---
+title: "libbase: The OpenTitan Standard Library"
+---
This subtree provides headers and libraries known collectively as `libbase`, which serve as OpenTitan's ersatz `libc`.
diff --git a/sw/device/lib/base/freestanding/README.md b/sw/device/lib/base/freestanding/README.md
index d871686..4ff7b11 100644
--- a/sw/device/lib/base/freestanding/README.md
+++ b/sw/device/lib/base/freestanding/README.md
@@ -1,4 +1,7 @@
-# OpenTitan Freestanding C Headers
+
+---
+title: "Freestanding C Headers"
+---
This subtree defines headers requred for a C freestanding implementation, as specified in S4p6 of the C11 standard.
Said headers are implemented to the letter as described in respective sections of said standard.
diff --git a/sw/device/lib/dif/README.md b/sw/device/lib/dif/README.md
index 6670231..6cd2430 100644
--- a/sw/device/lib/dif/README.md
+++ b/sw/device/lib/dif/README.md
@@ -1,4 +1,6 @@
-# The OpenTitan DIF Library
+---
+title: "The OpenTitan DIF Library"
+---
A DIF is a "Device Interface Function". DIFs are low-level routines for
accessing the hardware functionality directly, and are agnostic to the
diff --git a/sw/device/lib/dif/_index.md b/sw/device/lib/dif/_index.md
new file mode 100644
index 0000000..fe3905f
--- /dev/null
+++ b/sw/device/lib/dif/_index.md
@@ -0,0 +1,5 @@
+---
+title: "Device Interface Functions"
+---
+
+{{% sectionContent %}}
diff --git a/sw/device/lib/runtime/README.md b/sw/device/lib/runtime/README.md
index ee9d84a..881dc5c 100644
--- a/sw/device/lib/runtime/README.md
+++ b/sw/device/lib/runtime/README.md
@@ -1,4 +1,6 @@
-# `libruntime`, the OpenTitan Runtime Library
+---
+title: "libruntime: The OpenTitan Runtime Library"
+---
This directory contains machine-aware base libraries for OpenTitan, being more
aware and able to control the execution environment than the "pure algorithm"
diff --git a/sw/device/silicon_creator/_index.md b/sw/device/silicon_creator/_index.md
new file mode 100644
index 0000000..9b1d0e5
--- /dev/null
+++ b/sw/device/silicon_creator/_index.md
@@ -0,0 +1,7 @@
+---
+title: "Silicon Creator Software"
+---
+
+## Documentation Index
+
+{{% sectionContent %}}
diff --git a/sw/device/silicon_creator/keys/README.md b/sw/device/silicon_creator/keys/README.md
index 032197c..8cc1efe 100644
--- a/sw/device/silicon_creator/keys/README.md
+++ b/sw/device/silicon_creator/keys/README.md
@@ -1,3 +1,7 @@
+---
+title: "Signing Keys"
+---
+
This directory contains ASN1 DER encoded development keys for signing ROM\_EXT
images. Until we have a more ergonomic tool for working with keys and signatures,
below snippets can be used for various operations.
@@ -74,7 +78,7 @@
0120 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
0130 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
0140 - ff ff ff ff ff ff ff ff-ff ff ff ff 00 30 31 30 .............010
-0150 - 0d 06 09 60 86 48 01 65-03 04 02 01 05 00 04 20 ...`.H.e.......
+0150 - 0d 06 09 60 86 48 01 65-03 04 02 01 05 00 04 20 ...`.H.e.......
0160 - 9f 86 d0 81 88 4c 7d 65-9a 2f ea a0 c5 5a d0 15 .....L}e./...Z..
0170 - a3 bf 4f 1b 2b 0b 82 2c-d1 5d 6c 15 b0 f0 0a 08 ..O.+..,.]l.....
```
@@ -95,4 +99,3 @@
884c7d65
9f86d081
```
-
diff --git a/sw/device/silicon_creator/mask_rom/docs/index.md b/sw/device/silicon_creator/mask_rom/docs/index.md
index b088592..424fed5 100644
--- a/sw/device/silicon_creator/mask_rom/docs/index.md
+++ b/sw/device/silicon_creator/mask_rom/docs/index.md
@@ -1,5 +1,5 @@
---
-title: "Reference Mask ROM: Secure Boot Description"
+title: "Mask ROM"
aliases:
- /sw/device/silicon_creator/mask_rom/boot
---
diff --git a/sw/device/silicon_creator/rom_exts/docs/manifest.md b/sw/device/silicon_creator/rom_exts/docs/manifest.md
index 6701fe4..53571d9 100644
--- a/sw/device/silicon_creator/rom_exts/docs/manifest.md
+++ b/sw/device/silicon_creator/rom_exts/docs/manifest.md
@@ -1,17 +1,9 @@
---
-title: Reference ROM_EXT Manifest Format
+title: Manifest Format
aliases:
-- /sw/device/silicon_creator/rom_exts/manifest
+- /sw/device/silicon_creator/manifest
---
-<p style="text-align: right">
-Contributors(s):
- <a href="https://github.com/lenary">Sam Elliott</a>,
- <a href="https://github.com/gkelly">Garret Kelly</a>,
- <a href="https://github.com/silvestrst">Silvestrs Timofejevs</a>,
- <a href="https://github.com/moidx">Miguel Osorio</a>
-</p>
-
<p style="color: red; text-align: right;">
Status: Draft
</p>
diff --git a/sw/device/tests/README.md b/sw/device/tests/README.md
index d5e6f96..1e7753c 100644
--- a/sw/device/tests/README.md
+++ b/sw/device/tests/README.md
@@ -1,5 +1,5 @@
---
-title: "Software Tests Readme"
+title: "Software Device Tests"
---
# Overview
diff --git a/sw/device/tock/README.md b/sw/device/tock/README.md
index 8c38339..eb25ff3 100644
--- a/sw/device/tock/README.md
+++ b/sw/device/tock/README.md
@@ -1,4 +1,6 @@
-# Tock OS
+---
+title: "Tock OS"
+---
Tock OS is a secure embedded operating system for microcontrollers.
@@ -47,4 +49,4 @@
`tock` directory implements a crate that pulls in external tock dependencies
(packages that are not maintained downstream). These dependencies can be either
-pulled directly from the upstream, or from a local Tock directory.
\ No newline at end of file
+pulled directly from the upstream, or from a local Tock directory.
diff --git a/sw/device/tock/_index.md b/sw/device/tock/_index.md
new file mode 100644
index 0000000..c61c2a3
--- /dev/null
+++ b/sw/device/tock/_index.md
@@ -0,0 +1,7 @@
+---
+title: "Tock Integration"
+---
+
+## Documentation Index
+
+{{% sectionContent %}}
diff --git a/sw/device/tock/chips/earlgrey/README.md b/sw/device/tock/chips/earlgrey/README.md
index 8d1138b..3c4c4c5 100644
--- a/sw/device/tock/chips/earlgrey/README.md
+++ b/sw/device/tock/chips/earlgrey/README.md
@@ -1,6 +1,7 @@
-# Earlgrey chip
+---
+title: "Earlgrey chip"
+---
OpenTitan chip implementation, which corresponds to the hardware as
instantiated from `hw/top_earlgrey` RTL. It includes Ibex chip and
a specific peripheral configuration, interrupt list and memory layout.
-
diff --git a/sw/device/tock/chips/opentitan_common/README.md b/sw/device/tock/chips/opentitan_common/README.md
index 96e9add..85919ab 100644
--- a/sw/device/tock/chips/opentitan_common/README.md
+++ b/sw/device/tock/chips/opentitan_common/README.md
@@ -1,5 +1,6 @@
-# OpenTitan common peripherals
+---
+title: "OpenTitan common peripherals"
+---
This crate contains various peripherals shared between OpenTitan
chips (earlgrey, etc...).
-
diff --git a/sw/host/_index.md b/sw/host/_index.md
new file mode 100644
index 0000000..336e95e
--- /dev/null
+++ b/sw/host/_index.md
@@ -0,0 +1,3 @@
+---
+title: "OpenTitan Host Software"
+---
diff --git a/sw/host/rom_ext_image_tools/signer/README.md b/sw/host/rom_ext_image_tools/signer/README.md
index ac4a777..4a35c7e 100644
--- a/sw/host/rom_ext_image_tools/signer/README.md
+++ b/sw/host/rom_ext_image_tools/signer/README.md
@@ -1,3 +1,7 @@
+---
+title: "Code Signing Tool"
+---
+
# Introduction
[OpenTitan Secure Boot][rom-ext-manifest] process consists of several stages.
diff --git a/sw/host/spiflash/README.md b/sw/host/spiflash/README.md
index 16ca8a5..287d028 100644
--- a/sw/host/spiflash/README.md
+++ b/sw/host/spiflash/README.md
@@ -1,4 +1,6 @@
-# SPI Flash
+---
+title: "SPI Flash"
+---
`spiflash` is a tool used to update the firmware stored in OpenTitan's embedded flash.
The tool resets OpenTitan and signals the boot ROM to enter bootstrap mode before sending the update payload.
diff --git a/sw/otbn/code-snippets/README.md b/sw/otbn/code-snippets/README.md
index 618231a..4043a0f 100644
--- a/sw/otbn/code-snippets/README.md
+++ b/sw/otbn/code-snippets/README.md
@@ -1,16 +1,18 @@
-# OTBN code snippet collection
+---
+title: "OTBN Code Snippets"
+---
This directory contains some code snippets that give examples of how
to do various tasks in OTBN code.
- - `modexp.s`: An example of how to do modular exponentiation.
- - `pseudo-ops.s`: An example of the pseudo-operations supported by the OTBN ISA.
- - `mul256.s`: An example of a 256x256 bit multiply using the MULQACC
- instruction.
- - `mul384.s`: An example of a 384x384 bit multiply using the MULQACC
- instruction.
- - `barrett384.s`: An example of a modular multiplication kernel based on
- Barrett reduction.
+- `modexp.s`: An example of how to do modular exponentiation.
+- `pseudo-ops.s`: An example of the pseudo-operations supported by the OTBN ISA.
+- `mul256.s`: An example of a 256x256 bit multiply using the MULQACC
+ instruction.
+- `mul384.s`: An example of a 384x384 bit multiply using the MULQACC
+ instruction.
+- `barrett384.s`: An example of a modular multiplication kernel based on
+ Barrett reduction.
Also included in this directory is a Makefile fragment that can be
used to assemble and link the snippets. This can be used standalone or
diff --git a/test/systemtest/README.md b/test/systemtest/README.md
index b1b012d..3ba4a33 100644
--- a/test/systemtest/README.md
+++ b/test/systemtest/README.md
@@ -1,4 +1,6 @@
-# OpenTitan System Tests
+---
+title: "OpenTitan System Tests"
+---
System tests are end-to-end tests for the whole OpenTitan system. They operate
on build outputs (typically in `build-bin`) and can be used to check that the
