[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 <[email protected]>
Co-authored-by: Hugo McNally <[email protected]>

Author: 2 people

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:

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.
 

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.
 

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)
 

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.
 
-<img src="./media/image1.png"
-style="width:7.08333in;height:5.60417in" />
+![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