From cfce42bb7e1c42ba552f08ddcd255eb4a3c6c1f9 Mon Sep 17 00:00:00 2001 From: Amaury Pouly Date: Fri, 10 Feb 2023 13:38:09 +0000 Subject: [PATCH] [doc] Replace old snippets & pkgmrg_cmd shortcodes The 'snippets' shortcode can be replaced with mdbook's built in #include pre-processor. The 'pkgmgr_cmd' shortcode is only used once and can be replaced with a command that doesn't need to change when `apt_requirements.txt` is updated. `util/rewrite_frontmatter.py` can be removed because it won't be needed again. Signed-off-by: Amaury Pouly Co-authored-by: Hugo McNally --- doc/guides/getting_started/src/README.md | 4 +- hw/ip/lc_ctrl/README.md | 18 +++--- hw/ip/otp_ctrl/README.md | 6 +- hw/ip/pinmux/README.md | 2 +- hw/top_earlgrey/ip/ast/README.md | 3 +- .../doc/{media/image1.png => top_diagram.png} | Bin util/rewrite_frontmatter.py | 61 ------------------ 7 files changed, 17 insertions(+), 77 deletions(-) rename hw/top_earlgrey/ip/ast/doc/{media/image1.png => top_diagram.png} (100%) delete mode 100644 util/rewrite_frontmatter.py diff --git a/doc/guides/getting_started/src/README.md b/doc/guides/getting_started/src/README.md index 77f90aa7905ba..fda574bb166da 100644 --- a/doc/guides/getting_started/src/README.md +++ b/doc/guides/getting_started/src/README.md @@ -58,7 +58,9 @@ have a minimum of **32GiB of physical RAM** and at least **512GiB of SSD/HDD sto A number of software packages from the distribution's package manager are required. On Ubuntu 20.04, the required packages can be installed with the following command. -{{< pkgmgr_cmd "apt" >}} +```sh +sed -e '/^$/d' -e '/^#/d' ./apt-requirements.txt | sudo apt install -y +``` Some tools in this repository are written in Python 3 and require Python dependencies to be installed through `pip`. We recommend installing the latest version of `pip` and `setuptools` (especially if on older systems such as Ubuntu 18.04) using: diff --git a/hw/ip/lc_ctrl/README.md b/hw/ip/lc_ctrl/README.md index 4d507b4b0fa13..f9f8fb4641b60 100644 --- a/hw/ip/lc_ctrl/README.md +++ b/hw/ip/lc_ctrl/README.md @@ -151,7 +151,7 @@ They exist only after specific events, and are restored to normal once the devic The individual signals summarized in the table below are described in the following subsections. -{{< snippet "lc_ctrl_function_signals_table.md" >}} +{{#include doc/lc_ctrl_function_signals_table.md}} Signals marked with an asterisk (Y\*) are only asserted under certain conditions as explained in detail below. @@ -232,7 +232,7 @@ For details on the clock switch, please see [clkmgr](../clkmgr/README.md#life-cy The individual signals summarized in the table below are described in the following subsections. -{{< snippet "lc_ctrl_access_signals_table.md" >}} +{{#include doc/lc_ctrl_access_signals_table.md}} Signals marked with an asterisk (Y\*) are only asserted under certain conditions as explained in detail below. @@ -267,7 +267,7 @@ The following is a list of all life cycle related collateral stored in OTP. Most collateral also contain associated metadata to indicate when the collateral is restricted from further software access, see [accessibility summary](#otp-accessibility-summary-and-impact-of-provision_en) for more details. Since not all collateral is consumed by the life cycle controller, the consuming agent is also shown. -{{< snippet "lc_ctrl_otp_collateral.md" >}} +{{#include doc/lc_ctrl_otp_collateral.md}} The TOKENs and KEYS are considered secret data and are stored in [wrapped format](#conditional-transitions). Before use, the secrets are unwrapped. @@ -313,7 +313,7 @@ These are The table below summarizes the software accessibility of all life cycle collateral. -{{< snippet "lc_ctrl_otp_accessibility.md" >}} +{{#include doc/lc_ctrl_otp_accessibility.md}} Note that CREATOR_SEED_SW_RW_EN is set to OFF if SECRET2_DIGEST has a nonzero value in PROD, PROD_END and DEV states. SEED_HW_RD_EN only becomes active if SECRET2_DIGEST has a nonzero value in DEV, PROD, PROD_END and RMA states. @@ -325,11 +325,11 @@ As it pertains to life cycle, the flash contains two sets of important collatera They are enumerated in the table below. Just as with OTP, the consumer and usage of each is also described. -{{< snippet "lc_ctrl_flash_collateral.md" >}} +{{#include doc/lc_ctrl_flash_collateral.md}} Each collateral belongs to a separate flash partition, the table below enumerates the partition and whether the partition is memory mapped. -{{< snippet "lc_ctrl_flash_partitions.md" >}} +{{#include doc/lc_ctrl_flash_partitions.md}} The general flash partition refers to any software managed storage in flash, and is not a specific carve out in the non-memory mapped area. @@ -342,7 +342,7 @@ It is expected that ROM_ext during secure boot programs the protection correctly The CREATOR_DATA partitions however, are further qualified based on the personalization state of the device. Just as with OTP, the table below enumerates accessibility of flash collateral. -{{< snippet "lc_ctrl_flash_accessibility.md" >}} +{{#include doc/lc_ctrl_flash_accessibility.md}} Note that CREATOR_SEED_SW_RW_EN is set to OFF if SECRET2_DIGEST has a nonzero value in PROD, PROD_END and DEV states. SEED_HW_RD_EN only becomes active if SECRET2_DIGEST has a nonzero value in DEV, PROD, PROD_END and RMA states. @@ -503,7 +503,7 @@ See [pinmux documentation](../pinmux/README.md#strap-sampling-and-tap-isolation) The encoding of the life-cycle state is used both for OTP storage and as part of the FSM state in the life cycle controller. In other words the state stored within OTP is not re-encoded before it is consumed as part of the life cycle controller FSM state. -{{< snippet "lc_ctrl_encoding_table.md" >}} +{{#include doc/lc_ctrl_encoding_table.md}} Any decoding that does not fall into the table above is considered **INVALID**. @@ -537,7 +537,7 @@ The second readout pass uses a linearly increasing address sequence, whereas the The life cycle transition counter has 24 strokes where each stroke maps to one 16bit OTP word. The strokes are similarly encoded as the life cycle state in the sense that upon the first transition attempt, all words are initialized with unique Cx values that can later be overwritten with unique Dx values without producing an ECC error. -{{< snippet "lc_ctrl_counter_table.md" >}} +{{#include doc/lc_ctrl_counter_table.md}} Upon each life cycle transition attempt, the life cycle controller **FIRST** increments the transition counter before initiating any token hashing and comparison operations. diff --git a/hw/ip/otp_ctrl/README.md b/hw/ip/otp_ctrl/README.md index a9aa5e79b0b6d..ed408845acf68 100644 --- a/hw/ip/otp_ctrl/README.md +++ b/hw/ip/otp_ctrl/README.md @@ -103,7 +103,7 @@ Thus the security of both volatile (OTP controller) and non-volatile (OTP IP) st The OTP controller for OpenTitan contains the seven logical partitions shown below. -{{< snippet "otp_ctrl_partitions.md" >}} +{{#include doc/otp_ctrl_partitions.md}} Generally speaking, the production life cycle of a device is split into 5 stages "Manufacturing" -> "Calibration and Testing" -> "Provisioning" -> "Mission" -> "RMA". OTP values are usually programmed during "Calibration and Testing", "Provisioning" and "RMA" stages, as explained below. @@ -928,14 +928,14 @@ Hence, a read access to those windows will take in the order of 10-20 cycles unt Sizes below are specified in multiples of 32bit words. -{{< snippet "otp_ctrl_mmap.md" >}} +{{#include doc/otp_ctrl_mmap.md}} Note that since the content in the SECRET* partitions are scrambled using a 64bit PRESENT cipher, read and write access through the DAI needs to occur at a 64bit granularity. Also, all digests (no matter whether they are SW or HW digests) have an access granule of 64bit. The table below lists digests locations, and the corresponding locked partitions. -{{< snippet "otp_ctrl_digests.md" >}} +{{#include doc/otp_ctrl_digests.md}} Write access to the affected partition will be locked if the digest has a nonzero value. diff --git a/hw/ip/pinmux/README.md b/hw/ip/pinmux/README.md index c9c74d6536463..568bfd9bfe973 100644 --- a/hw/ip/pinmux/README.md +++ b/hw/ip/pinmux/README.md @@ -372,7 +372,7 @@ The tables below summarize the pinout and pinmux connectivity for certain top-le ### Top Earlgrey -{{< snippet "../../../top_earlgrey/ip/pinmux/doc/autogen/targets.md" >}} +{{#include ../../top_earlgrey/ip/pinmux/doc/autogen/targets.md}} ## Device Interface Functions (DIFs) diff --git a/hw/top_earlgrey/ip/ast/README.md b/hw/top_earlgrey/ip/ast/README.md index 07492dc5f9afd..6ac4c91c8713f 100644 --- a/hw/top_earlgrey/ip/ast/README.md +++ b/hw/top_earlgrey/ip/ast/README.md @@ -10,8 +10,7 @@ device from physical attacks or manipulation. At a high level, AST communicates with a number of OpenTitan comportable modules. See diagram below. - +![Analog Sensor Top Diagram](./doc/top_diagram.png) In the following sections, each family of connection is briefly described and explained. Note, the analog connections to AST are not diff --git a/hw/top_earlgrey/ip/ast/doc/media/image1.png b/hw/top_earlgrey/ip/ast/doc/top_diagram.png similarity index 100% rename from hw/top_earlgrey/ip/ast/doc/media/image1.png rename to hw/top_earlgrey/ip/ast/doc/top_diagram.png diff --git a/util/rewrite_frontmatter.py b/util/rewrite_frontmatter.py deleted file mode 100644 index e19a90c600f9b..0000000000000 --- a/util/rewrite_frontmatter.py +++ /dev/null @@ -1,61 +0,0 @@ -#!/usr/bin/env python3 -# Copyright lowRISC contributors. -# Licensed under the Apache License, Version 2.0, see LICENSE for details. -# SPDX-License-Identifier: Apache-2.0 -"""Replaces front-matter with a standard markdown title, ignoring all other fields""" - -from pathlib import Path -import argparse - - -parser = argparse.ArgumentParser() -parser.add_argument("root_doc", - help = "path to the root of documentation") -g_args = parser.parse_args() - -g_root_doc = Path(g_args.root_doc).resolve() -# if root doc is a link to a book.toml file, just open this one -assert g_root_doc.is_dir(), "you must give a path to the root of the repo" - - -def apply_to_md_files(path, fn): - """ - List all files under the directory of the book and call a function on each one - """ - def apply_rec(path): - for child in path.iterdir(): - if child.name.endswith(".md"): - fn(child) - if child.is_dir(): - apply_rec(child.resolve()) - apply_rec(path) - - -def rewrite_title(path): - relpath = path.relative_to(g_root_doc) - # don't touch files in site/, sw/vendor/, hw/vendor/ - if relpath.parts[0] == "site" or relpath.parts[0:2] in (('sw', 'vendor'), ('hw', 'vendor')): - return - with path.open() as f: - lines = [] - for line in f: - lines.append(line) - # it must start with --- - if len(lines) == 0 or not lines[0].startswith("---"): - return # ignore - line_nr = 1 - title = None - while not lines[line_nr].startswith("---"): - this_line = lines[line_nr] - line_nr += 1 - if this_line.startswith("title:"): - title = this_line[6:].strip() - # remove quotes if any - if title[0] == '"' and title[-1] == '"': - title = title[1:-1] - new_lines = [f"# {title}\n"] - lines = new_lines + lines[line_nr + 1:] - path.write_text("".join(lines)) - - -apply_to_md_files(g_root_doc, rewrite_title)