Dasharo · philipandag · Sep 19, 2024 · Sep 19, 2024 · Sep 19, 2024 · Sep 19, 2024
diff --git a/docs/unified/hardkernel/building-manual.md b/docs/unified/hardkernel/building-manual.md
@@ -0,0 +1,46 @@
+# Dasharo firmware building guide
+
+## Intro
+
+This guide shows how to build Dasharo firmware for Hardkernel devices.
+
+## 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 firmware image, first clone the coreboot repository:
+    ```bash
+    git clone https://github.com/Dasharo/coreboot.git
+    ```
+then follow the steps below:
+
+=== "Odroid H4+"
+
+    1. Checkout to the device's branch:
+            ```bash
+            cd coreboot
+            git checkout hardkernel_odroid_h4/release
+            ```
+
+    To build a specific version replace `hardkernel_odroid_h4/release` with
+    `hardkernel_odroid_h4_v0.9.x` where `x` is the version number.
+
+    2. Checkout submodules:
+
+    ```bash
+    git submodule update --init --checkout
+    ```
+    3. Build the firmware:
+
+    ```bash
+    ./build.sh odroid_h4
+    ```
+
+    The resulting coreboot image will be placed in the coreboot directory as
+    `hardkernel_odroid_h4.rom`.
diff --git a/docs/unified/hardkernel/firmware-update.md b/docs/unified/hardkernel/firmware-update.md
@@ -0,0 +1,43 @@
+# Firmware update
+
+The following documentation describes the process of Dasharo open-source
+firmware update. If your device is currently flashed with the proprietary
+firmware please refer to the [Initial deployment](initial-deployment.md)
+documentation.
+
+The update process may be different, depending on the currently installed
+Dasharo firmware version.
+
+For simplicity of the process we recommend using
+[Dasharo Tools Suite](../../dasharo-tools-suite/overview.md).
+
+Before starting the update procedure be sure to disable Dasharo BIOS Boot
+medium lock and Secure Boot:
+
+1. Power on the device.
+2. While the device is booting, hold the `DELETE` key to enter the UEFI Setup
+    Menu.
+3. Enter the `Dasharo System Features` menu using the arrow keys and Enter.
+4. Enter the [Dasharo Security Options](https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#dasharo-security-options)
+    submenu.
+5. Verify the state of the `Lock the BIOS boot medium` option - if the option
+    is chosen, press `Space` and then `F10` to save the changes.
+6. Go back to the main menu using the `ESC` key.
+7. Enter the `Device Manager` menu.
+8. Enter the [Secure Boot Configuration](https://docs.dasharo.com/dasharo-menu-docs/device-manager/#secure-boot-configuration)
+    submenu.
+9. Verify that the `Current Secure Boot State` field says Disabled - if not,
+    unselect the `Attempt Secure Boot` option below then press `F10` to save
+    the changes.
+10. Reboot the device to properly apply the changes.
+
+The settings of all the above options can be restored after a firmware
+update.
+
+=== "ODROID H4+"
+
+    ## Updating Dasharo
+
+    ```bash
+    flashrom -p internal -w hardkernel_odroid_h4_v<version>.rom --fmap -i bios
+    ```
diff --git a/docs/unified/hardkernel/initial-deployment.md b/docs/unified/hardkernel/initial-deployment.md
@@ -0,0 +1,36 @@
+# Initial deployment
+
+Initial flashing of Dasharo firmware can be done from Linux using flashrom with
+the internal programmer. This document describes the process of building,
+installing and running flashrom on Ubuntu 24.04.
+
+## Build flashrom
+
+Please follow generic guide for [Dasharo flashrom fork](../../osf-trivia-list/deployment.md#how-to-install-dasharo-flashrom-fork).
+
+## Reading flash contents
+
+Always prepare a backup of the current firmware image. To read from the flash
+and save it to a file (`dump.rom`), execute the following command:
+
+```bash
+flashrom -p internal -r dump.rom
+```
+
+If you forgot to do this, you can get the original, proprietary
+firmware from the [ODROID wiki website](https://wiki.odroid.com/odroid-h4/hardware/h4_bios_update#bios_release)
+ to restore it in case it is bricked. Using the firmware other than
+your own backup should be the last resort.
+
+## Flashing Dasharo
+
+=== "ODROID H4+"
+
+    To flash Dasharo on the platform, execute the following command - replace `[path]`
+    with the path to the Dasharo image you want to flash, e.g. `hardkernel_odroid_h4_v0.9.0.rom`.
+
+    ```bash
+    sudo flashrom -p internal -w [path] --ifd -i bios
+    ```
+
+    After successful operation reboot the platform.
diff --git a/docs/unified/hardkernel/overview.md b/docs/unified/hardkernel/overview.md
@@ -0,0 +1,6 @@
+# Overview
+
+=== "Hardkernel ODROID H4+"
+    - [Releases](../../variants/hardkernel_odroid_h4_plus/releases.md)
+    - [Hardware Configuration Matrix](../../variants/hardkernel_odroid_h4_plus/hardware-matrix.md)
+    - [Test Matrix](./test-matrix.md#hardkernel-odroid-h4-plus)
diff --git a/docs/unified/hardkernel/recovery.md b/docs/unified/hardkernel/recovery.md
@@ -0,0 +1,69 @@
+# 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.
+
+=== "V1000-series"
+
+    ## Prerequisites
+
+    * [Prepared RTE](../../transparent-validation/rte/v1.1.0/quick-start-guide.md)
+    * 6x female-female wire cables
+
+    ## 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)
+
+    ## 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
+        ```
+
+    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]
+        ```
+
+        > Flashing with flashrom takes about 1 minute.
+
+    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
+        ```
+
+    12. Turn on the platform by connecting the power supply.
+
+    The first boot of the platform after proceeding with the above procedure can
+    take much longer than normal.
diff --git a/docs/unified/hardkernel/test-matrix.md b/docs/unified/hardkernel/test-matrix.md
@@ -0,0 +1,145 @@
+# Test matrix
+
+## About
+
+The test matrix is used to determine the scope of tests which the DUT is
+subjected from before the release of the new binary compatible with
+Hardkernel devices.
+
+=== "Hardkernel ODROID H4+"
+    ## Module: Dasharo compatibility
+
+    | No. | Supported test suite                  | Test suite ID | Supported test cases                 |
+    |:---:|:--------------------------------------|:-------------:|:-------------------------------------|
+    | 1.  | [Custom boot order][CBO]              | CBO           | CBO001.002                           |
+    | 2.  | [Custom Boot Keys][CBK]               | CBK           | All                                  |
+    | 3.  | [Custom logo][CLG]                    | CLG           | All                                  |
+    | 4.  | [USB HID and MSC Support][USB]        | USB           | USB001.0001, USB001.002, USB002.001, USB002.002|
+    | 5.  | [Custom network boot entries][CNB]    | CNB           | CNB001.002                           |
+    | 6.  | [UEFI compatible interface][EFI]      | EFI           | EFI001.001                           |
+    | 7.  | [UEFI Shell][USH]                     | USH           | All                                  |
+    | 8.  | [NVMe support][NVM]                   | NVM           | NVM001.001, NVM001.002               |
+    | 9.  | [Network boot][PXE]                   | PXE           | All                                  |
+    | 10. | [Display ports][DSP]                  | DSP           | DSP002.001, DSP003.001               |
+    | 11. | [Audio subsystem][AUD]                | AUD           | AUD007.001, AUD008.001               |
+    | 12. | [Sleep mode][SUSP]                    | SUSP          | SUSP001.001, SUSP002.001, SUSP003.001, SUSP005.001|
+    | 13. | [SMBIOS verification][DMI]            | DMI           | All                                  |
+    | 14. | [eMMC support][MMC]                  | MMC           | All                                  |
+    | 15. | [SATA support][SATA]                  |               | All                                  |
+    | 16. | [Sign of life][SOL]                   | SOL           | All                                  |
+    | 17. | [Persistent Boot Splash][LCM]         | LCM           | All                                  |
+    | 18. | [Debian Stable and Ubuntu LTS support][LBT] | LBT     | LBT003.001, LBT003.002, LBT004.001, LBT004.002|
+    | 19. | [Power state after power fail][PSF]    | PSF           | All                                  |
+    | 20. | [Dasharo Tools Suite][DTS]            | DTS           | DTS001.001, DTS002.001, DTS003.001, DTS004.001, DTS005.001, DTS006.001 |
+    | 21. | [Reset to defaults][RTD]              | RTD           | RTD001.001, RTD002.001, RTD003.001, RTD004.001, RTD006.001 |
+    | 22. | [Ethernet interface][NET]             | NET           | All                                  |
+    | 23. | [Dasharo Configuration Utility][NET]  | DCU           | DCU001.001, DCU002.001, DCU003.001   |
+    | 24. | [ESP scanning][ESP]                   | ESP           | All                                  |
+    | 25. | [Network Boot Utilities][NBT]          | NBT           | All                                  |
+    | 26. | [USB detection][UDT]                  | UDT           | All                                  |
+    | 27. | [USB booting][UBT]                    | UBT           | All                                  |
+    | 28. | [Setup Menu information][SET]         | SET           | All                                  |
+    | 29. | [Ubuntu booting performance test][BUB]| BUB           | All                                  |
+    | 30. | [CPU status][CPU]                     | CPU           | CPU001.001, CPU002.001, CPU003.001, CPU004.001|
+    | 31. | [Auto boot time-out][BMM]             | BMM           | All                                  |
+
+    [CBO]: .
+    [CBK]: ../../unified-test-documentation/dasharo-compatibility/303-custom-boot-menu-key.md
+    [CLG]: ../../unified-test-documentation/dasharo-compatibility/304-custom-logo.md
+    [USB]: ../../unified-test-documentation/dasharo-compatibility/306-usb-hid-and-msc-support.md
+    [CNB]: ../../unified-test-documentation/dasharo-compatibility/30A-custom-network-boot-entries.md
+    [EFI]: ../../unified-test-documentation/dasharo-compatibility/30M-uefi-compatible-interface.md
+    [USH]: ../../unified-test-documentation/dasharo-compatibility/30P-uefi-shell.md
+    [NVM]: .
+    [PXE]: ../../unified-test-documentation/dasharo-compatibility/315-network-boot.md
+    [DSP]: ../../unified-test-documentation/dasharo-compatibility/31E-display-ports-and-lcd.md
+    [AUD]: ../../unified-test-documentation/dasharo-compatibility/31F-audio-subsystem.md
+    [SUSP]: .
+    [DMI]: ../../unified-test-documentation/dasharo-compatibility/31L-smbios.md
+    [MMC]: .
+    [SATA]: .
+    [SOL]: .
+    [LCM]: .
+    [LBT]: ../../unified-test-documentation/dasharo-compatibility/308-debian-stable-and-ubuntu-lts-support.md
+    [PSF]: .
+    [DTS]: ../../unified-test-documentation/dasharo-compatibility/326-dasharo-tools-suite.md
+    [RTD]: .
+    [NET]: .
+    [DCU]: .
+    [ESP]: .
+    [NBT]: ../../unified-test-documentation/dasharo-compatibility/315b-netboot-utilities.md
+    [UDT]: ../../unified-test-documentation/dasharo-compatibility/31O-usb-detect.md
+    [UBT]: ../../unified-test-documentation/dasharo-compatibility/31N-usb-boot.md
+    [SET]: .
+    [BUB]: .
+    [CPU]: ../../unified-test-documentation/dasharo-compatibility/31T-cpu-status.md
+    [BMM]: .
+
+<!--
+    Test cases copied from spreadsheet using a script, may be a good reference
+    but need refactoring, adding links and manual check
+-->
+<!--
+    ## Module: Dasharo Security
+
+    | No. | Supported test suite                  | Test suite ID | Supported test cases                 |
+    |:---:|:--------------------------------------|:-------------:|:-------------------------------------|
+    | 1.  | [TPM Support][TPM]                    | TPM           | TPM001.002,TPM002.001,TPM002.002,TPM003.001,TPM003.002,TPM003.004, |
+    | 2.  | [Verified Boot Integration][VBO]      | VBO           | All                                  |
+    | 3.  | [BIOS lock support][BLS]              | BLS           | BLS001.001,BLS002.001,               |
+    | 4.  | [Measured boot integration][MBO] | MBO | MBO001.001, |
+    | 5.  | [UEFI Secure Boot integration][SBO] | SBO | SBO001.001,SBO002.001,SBO003.001,SBO004.001,SBO005.001,SBO006.001,SBO007.001,SBO008.001, |
+    | 6.  | [UEFI Setup password][PSW] | PSW | PSW001.001,PSW002.001,PSW003.001,PSW004.001,PSW005.001,PSW006.001,PSW007.001,PSW008.001, |
+    | 7.  | [Early Boot DMA Protection][EDP] | EDP | EDP001.001,EDP002.001, |
+    | 8.  | [USB stack enable/disable][USS] | USS | USS001.001,USS002.001,USS003.001,USS004.001, |
+    | 9.  | [Network stack enable/disable][NBA] | NBA | NBA001.001,NBA002.001, |
+    | 10. | [SMM BIOS write protection][SMM] | SMM | SMM001.001,SMM002.001, |
+    | 11. | [TPM2 Commands][TPMCMD] | TPMCMD | TPMCMD001.001,TPMCMD002.001,TPMCMD003.001,TPMCMD003.002,TPMCMD004.001,TPMCMD005.001,TPMCMD006.001,TPMCMD007.001,TPMCMD007.002,TPMCMD008.001,TPMCMD009.001,TPMCMD010.001,TPMCMD011.001, |
+
+    ## Module: Dasharo Stability
+
+    | No. | Supported test suite                  | Test suite ID | Supported test cases                 |
+    |:---:|:--------------------------------------|:-------------:|:-------------------------------------|
+    | 1. | [TPM Support][TPD] | TPD | TPD003.001,TPD004.001,TPD003.001,TPD004.001, |
+    | 2. | [USB support][] |  | SUD0001.001,SUD0002.001,SUD0003.001,SUD0004.001, |
+
+    ## Module: Dasharo Performance
+
+    | No. | Supported test suite                  | Test suite ID | Supported test cases                 |
+    |:---:|:--------------------------------------|:-------------:|:-------------------------------------|
+    | 1. | [Serial Boot Measure][CBMEM] | CBMEM | CBMEM001.001,CBMEM002.001,CBMEM003.001, |
+    | 2. | [CPU][CPT] | CPT | CPT001.001,CPT002.001, |
+    | 3. | [CPU][CPF] | CPF | CPF001.001,CPF002.001,CPF004.001, |
+    | 4. | [Platform stability][STB] | STB | STB001.001,STB001.002,STB002.001, |
+    | 5. | [Ubuntu booting performance test][BUB] | BUB | BUB001.001,BUB002.001,BUB003.001, |
+-->
+
+<!-- turbot test matrix, reference -->
+<!--
+    ## Module: Dasharo security
+
+    | No. | Supported test suite                  | Test suite ID | Supported test cases                 |
+    |:----|:--------------------------------------|:-------------:|:-------------------------------------|
+    | 1.  | [Secure Boot support][SBO]            | SBO           | All                                  |
+    | 2.  | [BIOS lock support][BLS]              | BLS           | All                                  |
+    | 3.  | [SMM BIOS write protection][SMM]      | SMM           | All                                  |
+    | 4.  | [UEFI Setup password][PSW]            | PSW           | All                                  |
+    | 5.  | [Network stack enable/disable][NBA]   | NBA           | All                                  |
+    | 6.  | [USB stack enable/disable][USS]       | USS           | All                                  |
+
+    ## Module: Dasharo performance
+
+    | No. | Supported test suite                  | Test suite ID | Supported test cases                 |
+    |:----|:--------------------------------------|:-------------:|:-------------------------------------|
+    | 1.  | [coreboot bring up time measurement][CBMEM] | CBMEM         | All                            |
+    | 2.  | [CPU temperature measure][CPT]        | CPT           | All                                  |
+    | 3.  | [CPU frequency measure][CPF]          | CPF           | Without CPU003.XXX and CPU005.XXX    |
+    | 4.  | [Platform stability][STB]             | STB           | All                                  |
+
+    [CBMEM]: ../../unified-test-documentation/dasharo-performance/400-coreboot-boot-measure.md
+    [CPT]: ../../unified-test-documentation/dasharo-performance/401-cpu-temperature.md
+    [CPF]: ../../unified-test-documentation/dasharo-performance/402-cpu-frequency.md
+    [STB]: ../../unified-test-documentation/dasharo-performance/404-platform-stability.md
+    [BUB]: ../../unified-test-documentation/dasharo-performance/407-ubuntu-booting-performance-test.md
+    [BDE]: ../../unified-test-documentation/dasharo-performance/408-debian-booting-performance-test.md
+-->
diff --git a/docs/variants/hardkernel_odroid_h4_plus/hardware-matrix.md b/docs/variants/hardkernel_odroid_h4_plus/hardware-matrix.md
@@ -0,0 +1,27 @@
+# Hardware configuration matrix
+
+## Introduction
+
+This document describes the hardware configuration used for validation of
+Dasharo on the Hardkernel ODROID H4+.
+
+## MinnowBoard Turbot Quad Core
+
+| Component                      | Description                                 |
+|--------------------------------|---------------------------------------------|
+| **CPU**                        | Intel(R) Processor N97                      |
+| **RAM**                        | DDR5 SODIMM up to 4800MHz                   |
+| **SSD**                        | Samsung SSD PRO 900 1TB                     |
+| **Flash memory**               | Winbond W25Q128JV                           |
+| **USB Keyboard**               | DELL KB216                                  |
+| **USB Mouse**                  | None                                        |
+| **USB pendrives**              | 1. SanDisk Ultra  Flair USB 3.0 16 GB       |
+| **Display**                    | HDMI 1920x1080p                             |
+| **Ethernet controller**        | Intel i210 (on-board)                       |
+| **Storage devices**            | microSD card SanDisk Ultra 16GB             |
+|                                | SATA disk (TBD)                             |
+| **Network**                    | Local network wired connection              |
+| **Remote Testing Environment** | RTE v1.1.0                                  |
+| **Power Control**              | Sonoff                                      |
+| **Power supply**               | Phihong PSAA20R-050L6 5V 4A                 |
+| **KVM**                        | PiKVM based on Raspberry Pi Zero 2w         |
diff --git a/docs/variants/hardkernel_odroid_h4_plus/releases.md b/docs/variants/hardkernel_odroid_h4_plus/releases.md
@@ -0,0 +1,17 @@
+# Dasharo compatible with Hardkernel ODROID H4+
+
+Following Release Notes describe status of Open Source Firmware development for
+Hardkernel ODROID H4+
+
+For details about our release process please read
+[Dasharo Standard Release Process](../../dev-proc/standard-release-process.md).
+
+<center>
+
+[Subscribe to Hardkernel ODROID H4+ Dasharo Release Newsletter]
+[newsletter]{ .md-button .md-button--primary .center }
+
+</center>
+
+<!-- TODO -->
+[newsletter]: ./releases.md