docs/variants/hardkernel-odroid-h4: Add

Signed-off-by: Filip Gołaś <[email protected]> mkdocs.yml: Add hardkernel odroid h4 pages Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4_plus/releases.md: Add Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/releases.md: Add newsletter subscribe url Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/releases.md: Add note "Coming soon." Co-authored-by: Michał Żygowski <[email protected]> hardkernel_odroid_h4/releases.md: Dasharo Pro Package Signed-off-by: Filip Gołaś <[email protected]> unified/hardkernel/overview.md: Add Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/overview.md: Add missing links Signed-off-by: Filip Gołaś <[email protected]> odroid_h4 overview.md: Add a short description Signed-off-by: Filip Gołaś <[email protected]> odroid_h4 overview.md: Add an image of the device Signed-off-by: Filip Gołaś <[email protected]> odroid_h4 overview.md: Add link to device's blogpost Signed-off-by: Filip Gołaś <[email protected]> odroid_h4 overview: Remove the term "open source hardware" Signed-off-by: Filip Gołaś <[email protected]> unified/hardkernel/building-manual.md: Add Signed-off-by: Filip Gołaś <[email protected]> Update docs/variants/hardkernel_odroid_h4/building-manual.md Co-authored-by: Michał Żygowski <[email protected]> hardkernel_odroid_h4/building-manual.md: Remove tab Signed-off-by: Filip Gołaś <[email protected]> unified/hardkernel/initial-deployment.md: Add Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/initial_deployment.md: Mention DTS Signed-off-by: Filip Gołaś <[email protected]> odroid_h4 initial-deployment.md: Add G3&CMOS reset if fails to boot Signed-off-by: Filip Gołaś <[email protected]> odroid_h4/initial-deployment.md: Update link to DTS zero touch Signed-off-by: Filip Gołaś <[email protected]> unified/hardkernel/firmware-update.md: Add Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/firmware_update.md: update flash command Co-authored-by: Michał Żygowski <[email protected]> Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/firmware_update.md: Mention DTS Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/firmware-update.md: Update section name Co-authored-by: Michał Żygowski <[email protected]> unified/hardkernel/recovery.md: Add Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/recovery.md: Describe using flash jumper Signed-off-by: Filip Gołaś <[email protected]> docs hardkernel: pre-commit Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/recovery.md: Reword dual bios recovery Co-authored-by: Michał Żygowski <[email protected]> hardkernel_odroid_h4/recovery.md: Remove tab Co-authored-by: Michał Żygowski <[email protected]> hardkernel_odroid_h4/recovery.md: Fix redirect to other section Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/recovery.md: URL to ODROID wiki recovery Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/recovery.md: Suggest hard reset after flashing Signed-off-by: Filip Gołaś <[email protected]> odroid_h4 recovery.md: Link dual bios recovery instructions from WIKI Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4_plus/hardware-matrix.md: Add Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/hardware-matrix.md: Fix PSU Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/hardware-matrix.md: Add RAM model from dmidecode Signed-off-by: Filip Gołaś <[email protected]> unified/hardkernel/test-matrix.md: Add only Dasharo Compatibility Signed-off-by: Filip Gołaś <[email protected]> unified/hardkernel/test-matrix.md: Add reference from script Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/test-matrix.md: Add compatibility links hardkernel_odroid_h4/test-matrix.md: Add performance tests Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/test-matrix.md: Add stability Signed-off-by: Filip Gołaś <[email protected]> hardkernel_odroid_h4/test-matrix.md: Add performance Signed-off-by: Filip Gołaś <[email protected]> hard\/test-matrix.md: Align table columns Signed-off-by: Filip Gołaś <[email protected]> odroid_h4 hardware/test matrices: remove SATA Signed-off-by: Filip Gołaś <[email protected]>
Dasharo · Jan 16, 2025 · e763c67 · e763c67
1 parent ea47e6f
commit e763c67
Show file tree

Hide file tree

Showing 11 changed files with 466 additions and 0 deletions.
diff --git a/docs/images/odroid_flash_switch.jpg b/docs/images/odroid_flash_switch.jpg
diff --git a/docs/images/odroid_h4.jpg b/docs/images/odroid_h4.jpg
diff --git a/docs/variants/hardkernel_odroid_h4/building-manual.md b/docs/variants/hardkernel_odroid_h4/building-manual.md
@@ -0,0 +1,52 @@
+# 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:
+
+1. To build a specific version checkout to the version's tag.
+    Skip this step otherwise.
+
+    ```bash
+    cd coreboot
+    git checkout hardkernel_odroid_h4_<version>
+    ```
+
+    For example
+
+    ```bash
+    git checkout hardkernel_odroid_h4_v0.9.0
+    ```
+
+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_<version>.rom`.
diff --git a/docs/variants/hardkernel_odroid_h4/firmware-update.md b/docs/variants/hardkernel_odroid_h4/firmware-update.md
@@ -0,0 +1,41 @@
+# 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.
+
+## Updating Dasharo manually
+
+```bash
+flashrom -p internal -w hardkernel_odroid_h4_v<version>.rom --fmap -i WP_RO -i RW_SECTION_A
+```
diff --git a/docs/variants/hardkernel_odroid_h4/hardware-matrix.md b/docs/variants/hardkernel_odroid_h4/hardware-matrix.md
@@ -0,0 +1,26 @@
+# Hardware configuration matrix
+
+## Introduction
+
+This document describes the hardware configuration used for validation of
+Dasharo on the Hardkernel ODROID H4.
+
+## Hardkernel ODROID H4+
+
+| Component                      | Description                                 |
+|--------------------------------|---------------------------------------------|
+| **CPU**                        | Intel(R) Processor N97                      |
+| **RAM**                        | Samsung M425R1GB4BB0-CWMOD                  |
+| **SSD**                        | Samsung SSD PRO 900 1TB                     |
+| **eMMC**                       | MMC PJ3032                                  |
+| **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)                       |
+| **Network**                    | Local network wired connection              |
+| **Remote Testing Environment** | RTE v1.1.0                                  |
+| **Power Control**              | RTE v1.1.0                                  |
+| **Power supply**               | ULLPOWER ICP65-150-4000 15V 5A              |
+| **KVM**                        | PiKVM based on Raspberry Pi Zero 2w         |
diff --git a/docs/variants/hardkernel_odroid_h4/initial-deployment.md b/docs/variants/hardkernel_odroid_h4/initial-deployment.md
@@ -0,0 +1,45 @@
+# Initial deployment
+
+Initial flashing of Dasharo firmware can be done from Linux using flashrom with
+the internal programmer or using the Dasharo Tools Suite included in the Dasharo
+Pro Package subscription (formerly Dasharo Entry Subscription). An instruction
+on how to use the DTS can be found in the [DTS documentation](../../dasharo-tools-suite/documentation/features.md#dasharo-zero-touch-initial-deployment)
+
+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
+
+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.
+
+If the platforms fails to boot, try performing a CMOS reset:
+
+1. Disconnect the power supply and the CMOS battery.
+1. Wait for 10 seconds
+1. Reconnect the power supply and the CMOS battery
+1. Press the power button
diff --git a/docs/variants/hardkernel_odroid_h4/overview.md b/docs/variants/hardkernel_odroid_h4/overview.md
@@ -0,0 +1,33 @@
+# Overview
+
+## Hardkernel ODROID-H4 PLUS
+
+<center>
+![](../../images/odroid_h4.jpg)
+</center>
+
+Hardkernel ODROID-H4 PLUS is a small single-board computer with rich schematics
+and documentation available online. One of it's most noteworthy features is the
+use of two distinct switchable BIOS flash memory chips. This makes it a perfect
+device for experimenting with firmware by making the recovery process after
+bricking the device a breeze.
+
+The device is described in detail on [blog.3mdeb.com](https://blog.3mdeb.com/2024/2024-07-25-odroid-h4-getting-started/)
+
+## Documentation
+
+- [Releases](./releases.md) - Groups information about all releases.
+- [Building Manual](./building-manual.md) - Describes how to build Dasharo
+  compatible with the ODROID-H4 PLUS.
+- [Initial Deployment](./initial-deployment.md) - Describes initial Dasharo
+  deployment methods (i. e. flashing new firmware) compatible with ODROID-H4
+  PLUS.
+- [Firmware Update](./firmware-update.md) - Explains supported Dasharo
+    open-source firmware update methods.
+- [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.
diff --git a/docs/variants/hardkernel_odroid_h4/recovery.md b/docs/variants/hardkernel_odroid_h4/recovery.md
@@ -0,0 +1,112 @@
+# 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.
+
+## Dual BIOS
+
+The **ODROID H4+ and ODROID-H4 Ultra** devices both have the Dual BIOS
+feature. If the device does not boot properly, the backup flash chip can be
+selected using the flash selector jumper.
+
+![](../../images/odroid_flash_switch.jpg)
+*First bios chip selected using the flash selector*
+
+1. Move the flash selector jumper to select the backup flash chip. If the
+   device does not boot from any of the flash chips, an external flashing
+   needs to be performed. In that case continue with the
+   [External flashing](#external-flashing) section.
+2. If the device boots, boot to an OS.
+3. Move the flash selector jumper back to it's original position selecting the
+   previous flash chip, from which the device does not boot.
+4. With the device working, an OS booted and the flash chip selector moved
+   back, the firmware can be flashed using the command:
+
+    ```bash
+    flashrom -p internal -w [path_to_binary]
+    ```
+
+5. After the flashing finishes reboot the device. If the platform does not boot
+a CMOS reset and boot from G3 state may be needed:
+
+    1. Unplug the CMOS battery and the power supply
+    2. Wait for 10 seconds
+    3. Plug the CMOS battery and power supply back in
+    4. Press the power button
+
+### Additional methods
+
+Additional methods for flashing the firmware on Windows and using the UEFI Shell
+can be found on the [ODROID Wiki](https://wiki.odroid.com/odroid-h4/hardware/restore_h4_bios).
+
+## External flashing
+
+=== "RTE"
+    ### 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
+        ```
+
+    13. 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.
+
+=== "CH341A"
+    For instructions on how to perform a recovery
+    using the CH341A external programmer refer to
+    the [ODROID Wiki](https://wiki.odroid.com/odroid-h3/hardware/restore_h3_bios_usbprogrammer#with_usb_programmer_module_ch341a)
+    .
diff --git a/docs/variants/hardkernel_odroid_h4/releases.md b/docs/variants/hardkernel_odroid_h4/releases.md
@@ -0,0 +1,19 @@
+# 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>
+
+Coming soon in the [Dasharo Pro Package for Network Appliance](https://shop.3mdeb.com/shop/dasharo-pro-package/1-year-dasharo-entry-subscription-for-network-appliance/).
+
+<!-- TODO -->
+[newsletter]: https://newsletter.3mdeb.com/subscription/pULA4K0Eo