docs/variants/asrock_turind8ud: Add initial docs

docs/variants/asrock_turind8ud/building-manual.md

@@ -0,0 +1,54 @@
+# Dasharo firmware building guide
+
+## Intro
+
+This guide shows how to build Dasharo firmware compatible with ASRock Rack
+TURIND8UD-2T/X550.
+
+## Requirements
+
+- Docker
+    + follow [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/)
+    + follow [Post-installation steps for Linux](https://docs.docker.com/engine/install/linux-postinstall/)
+- Git
+    + `sudo apt-get install git`
+
+## Building
+
+To build Dasharo (coreboot+UEFI) firmware image, first clone the coreboot
+repository:
+
+```bash
+git clone https://github.com/Dasharo/coreboot.git
+```
+
+then follow the steps below:
+
+1. To build a specific version checkout to the version's tag.
+    Skip this step otherwise.
+
+    ```bash
+    cd coreboot
+    git checkout asrock_turind8ud_linuxboot_<version>
+    ```
+
+    For example
+
+    ```bash
+    git checkout asrock_turind8ud_linuxboot_v0.9.0
+    ```
+
+2. Checkout submodules:
+
+    ```bash
+    git submodule update --init --checkout
+    ```
+
+3. Build the firmware:
+
+    ```bash
+    ./build.sh asrock_turind8ud_linuxboot
+    ```
+
+    The resulting coreboot image will be placed in the coreboot directory as
+    `asrock_turind8ud_linuxboot_<version>.rom`.

docs/variants/asrock_turind8ud/firmware-update.md

@@ -0,0 +1,17 @@
+# Firmware update
+
+!!! warning "No in-band firmware update is available yet"
+
+    There is currently **no supported method for updating the Dasharo
+    firmware from the running operating system** on this platform.
+
+    In-place firmware update support is planned and will become available once
+    OpenBMC support is implemented for the platform. Once OpenBMC is in place,
+    firmware will be updatable through the BMC. This page will be updated with
+    the procedure when that support lands.
+
+## Reflashing the firmware
+
+Until an in-band update method is available, the only way to change the
+firmware is to externally program the BIOS SPI flash chip. Follow the process
+described in the [Recovery](recovery.md#external-flashing) section.

docs/variants/asrock_turind8ud/hardware-matrix.md

@@ -0,0 +1,24 @@
+# Hardware configuration matrix
+
+## Introduction
+
+This document describes the hardware configuration used for validation of the
+coreboot port on the ASRock Rack TURIND8UD-2T/X550.
+
+> Under construction
+
+<!-- TODO: fill in the validation stand configuration once available, using
+     the table format below (see asrock_spc741d8/hardware-matrix.md).
+
+| Component                  | Description           |
+| -------------------------- | --------------------- |
+| CPU                        | AMD EPYC 9xxx (Turin) |
+| RAM                        |                       |
+| Flash memory               |                       |
+| Network                    |                       |
+| Attached devices           |                       |
+| Power Supply               |                       |
+| Power Control              |                       |
+| Remote Testing Environment |                       |
+| TPM                        |                       |
+-->

docs/variants/asrock_turind8ud/initial-deployment.md

@@ -0,0 +1,10 @@
+# Initial deployment
+
+Initial deployment of Dasharo firmware can be performed by externally flashing
+the BIOS SPI flash chip.
+
+## Flashing Dasharo
+
+Flashing Dasharo on the platform is currently only possible with an
+external programmer. Follow the same process as in the
+[recovery section](recovery.md#external-flashing).

docs/variants/asrock_turind8ud/openness-score.md

@@ -0,0 +1,13 @@
+# Dasharo Openness Score
+
+This page contains the [Dasharo Openness
+Score](../../glossary.md#dasharo-openness-score) for ASRock Rack
+TURIND8UD-2T/X550 Dasharo releases. The content of the page is generated with
+[Dasharo Openness Score utility](https://github.com/Dasharo/Openness-Score).
+
+> Under construction
+
+<!-- TODO: once a release binary exists, generate the Openness Score with the
+     Dasharo Openness Score utility and paste the report here, adding the
+     generated chart images to this directory. See
+     gigabyte_mz33-ar1/openness-score.md for the expected format. -->

docs/variants/asrock_turind8ud/overview.md

@@ -0,0 +1,29 @@
+# Overview
+
+## ASRock Rack TURIND8UD-2T/X550
+
+<center>
+![](../../images/turind8ud.jpg)
+</center>
+
+ASRock Rack TURIND8UD-2T/X550 is a full-fledged single socket server board
+supporting AMD EPYC 9005 "Turin" (socket SP5) server processors. Dasharo for
+this platform is built with a [LinuxBoot](https://www.linuxboot.org/) payload.
+
+## Documentation
+
+- [Releases](./releases.md) - Groups information about all releases.
+- [Building Manual](./building-manual.md) - Describes how to build Dasharo
+  compatible with the ASRock Rack TURIND8UD-2T/X550.
+- [Firmware update](./firmware-update.md) - explains supported Dasharo
+  open-source firmware update methods.
+- [Initial Deployment](./initial-deployment.md) - Describes initial Dasharo
+  deployment methods (i. e. flashing new firmware) compatible with ASRock Rack
+  TURIND8UD-2T/X550.
+- [Recovery](./recovery.md) - Gathers information on how to recover the platform
+    from potential failure.
+- [Hardware Configuration Matrix](./hardware-matrix.md) - Describes the
+    platform's hardware configuration used during the Dasharo firmware
+    validation procedure.
+- [Test Matrix](./test-matrix.md) - Describes validation scope used during
+    Dasharo firmware validation procedure.

docs/variants/asrock_turind8ud/recovery.md

@@ -0,0 +1,126 @@
+# Recovery
+
+## Intro
+
+The following documentation describes the process of recovering hardware from
+the brick state using an [RTE](../../transparent-validation/rte/introduction.md)
+and Dasharo open-source firmware.
+
+## External flashing
+
+The external programming and recovery from bricks caused by Dasharo can be
+achieved by flashing the BIOS SPI flash chip through the on-board TPM header,
+which exposes the SPI bus. No SOIC8 clip is required - the programmer is wired
+directly to the TPM header with the TPM module removed.
+
+<center>
+![](../../images/turind8ud_tpm_header.png)
+</center>
+
+=== "RTE"
+    ### Prerequisites
+
+    * [Prepared RTE](../../transparent-validation/rte/v1.1.0/quick-start-guide.md)
+    * 6x female-female wire cables
+    * TPM module removed
+
+    ### Connections
+
+    To prepare the stand for flashing follow the steps described in
+    the [Generic test stand setup](../../unified-test-documentation/generic-testing-stand-setup.md#detailed-description-of-the-process).
+
+    Remove the TPM module and connect the RTE to the TPM header according to
+    the pinout above.
+
+    ### Firmware flashing
+
+    To flash firmware follow the steps described below:
+
+    1. Login to RTE via `ssh` or `minicom`.
+    2. Turn on the platform by connecting the power supply.
+    3. Wait at least 5 seconds.
+    4. Turn off the platform by using the power button.
+    5. Wait at least 3 seconds.
+    6. Set the proper state of the SPI by using the following commands on RTE:
+
+        ```bash
+        # set SPI Vcc to 3.3V
+        echo 1 > /sys/class/gpio/gpio405/value
+        # SPI Vcc on
+        echo 1 > /sys/class/gpio/gpio406/value
+        # SPI lines ON
+        echo 1 > /sys/class/gpio/gpio404/value
+        ```
+
+        > Starting with RTE distro v0.8.x the GPIOS are 517, 518, 516.
+
+    7. Wait at least 2 seconds.
+    8. Disconnect the power supply from the platform.
+    9. Wait at least 2 seconds.
+    10. Check if the flash chip is connected properly
+
+        ```bash
+        flashrom -p linux_spi:dev=/dev/spidev1.0,spispeed=16000
+        ```
+
+    11. Flash the platform by using the following command:
+
+        ```bash
+        flashrom -p linux_spi:dev=/dev/spidev1.0,spispeed=16000 \
+            -w [path_to_binary]
+        ```
+
+    12. Change back the state of the SPI by using the following commands:
+
+        ```bash
+        echo 0 > /sys/class/gpio/gpio404/value
+        echo 0 > /sys/class/gpio/gpio405/value
+        echo 0 > /sys/class/gpio/gpio406/value
+        ```
+
+        > Starting with RTE distro v0.8.x the GPIOS are 516, 517, 518.
+
+    13. Turn on the platform by connecting the power supply.
+
+    The AMD board takes longer to boot due to memory training happening on the
+    PSP side. Thus the first signs of life from open-source firmware may appear
+    even after a couple of minutes (depends on amount of populated RAM).
+
+=== "CH341A"
+
+    ### Prerequisites
+
+    * CH341A USB to SPI programmer
+    * 6x female-female wire cables
+    * TPM module removed
+
+    ### Connections
+
+    1. Remove the TPM module from the board.
+    2. Wire the CH341A programmer to the TPM header according to the pinout
+       above.
+
+    ### Firmware flashing
+
+    To flash firmware follow the steps described below:
+
+    3. Disconnect the power supply from the platform.
+    4. Wait at least 2 seconds.
+    5. Check if the flash chip is connected properly
+
+        ```bash
+        flashrom -p ch341a_spi
+        ```
+
+    6.  Flash the platform by using the following command:
+
+        ```bash
+        flashrom -p ch341a_spi -w [path_to_binary]
+        ```
+
+    7. Disconnect the programmer from the TPM header.
+    8. Turn on the platform by connecting the power supply.
+
+    The AMD board takes longer to boot due to memory training happening on the
+    PSP side. Thus the first signs of life from open-source firmware may appear
+    even after a couple of minutes (depends on amount of populated RAM).

docs/variants/asrock_turind8ud/releases.md

@@ -0,0 +1,27 @@
+# ASRock Rack TURIND8UD-2T/X550 Dasharo Release Notes
+
+Following Release Notes describe status of Open Source Firmware development
+for ASRock Rack TURIND8UD-2T/X550.
+
+For details about our release process please read
+[Dasharo Standard Release Process](../../dev-proc/standard-release-process.md).
+
+<!-- TODO: create a newsletter list for this board and paste its UUID below,
+     then uncomment the subscribe form.
+<center>
+
+{{ subscribe_form("REPLACE-WITH-NEWSLETTER-UUID",
+"Subscribe to ASRock Rack TURIND8UD-2T/X550 Dasharo Release Newsletter") }}
+
+</center>
+-->
+
+!!! note "Note"
+
+    Before using this firmware, please review the [Dasharo Terms of
+    Service](https://www.dasharo.com/pages/terms/) and AMD's [openSIL project
+    page](https://github.com/openSIL/openSIL), which describes openSIL's
+    current Proof-of-Concept status and AMD's evaluation-only support model.
+    Use of this firmware is at the user's own responsibility.
+
+> Under construction - there are no public releases for this platform yet.

docs/variants/asrock_turind8ud/test-matrix.md

@@ -0,0 +1,9 @@
+# Test matrix
+
+## About
+
+The test matrix is used to determine the scope of tests which the DUT is
+subjected to before the release of the new binary compatible with
+ASRock Rack TURIND8UD-2T/X550.
+
+> Under construction

mkdocs.yml

@@ -237,6 +237,16 @@ nav:
           - 'Hardware Configuration Matrix': variants/asrock_spc741d8/hardware-matrix.md
           - 'Test matrix': variants/asrock_spc741d8/test-matrix.md
           - 'Openness Score': variants/asrock_spc741d8/openness_score.md
+      - 'ASRock Rack TURIND8UD-2T/X550':
+          - 'Overview': variants/asrock_turind8ud/overview.md
+          - 'Releases': variants/asrock_turind8ud/releases.md
+          - 'Firmware Update': variants/asrock_turind8ud/firmware-update.md
+          - 'Building manual': variants/asrock_turind8ud/building-manual.md
+          - 'Initial deployment': variants/asrock_turind8ud/initial-deployment.md
+          - 'Recovery': variants/asrock_turind8ud/recovery.md
+          - 'Hardware Configuration Matrix': variants/asrock_turind8ud/hardware-matrix.md
+          - 'Test matrix': variants/asrock_turind8ud/test-matrix.md
+          - 'Openness Score': variants/asrock_turind8ud/openness-score.md
       - 'Asus KGPE-D16':
           - 'Overview': variants/asus_kgpe_d16/overview.md
           - 'Releases': variants/asus_kgpe_d16/releases.md