Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add hardkernel-odroid-h4-plus placeholder docs #903

Open
wants to merge 12 commits into
base: master
Choose a base branch
from
Open

Add hardkernel-odroid-h4-plus placeholder docs #903

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
f4aa311
docs: Add hardkernel-odroid-h4-plus placeholder files
philipandag Sep 19, 2024
483e421
mkdocs.yml: Add hardkernel odroid h4 pages
philipandag Sep 19, 2024
36190a4
hardkernel_odroid_h4_plus/releases.md: Add
philipandag Sep 19, 2024
6603f8e
unified/hardkernel/overview.md: Add
philipandag Sep 19, 2024
4697210
unified/hardkernel/building-manual.md: Add
philipandag Sep 19, 2024
3b627e4
unified/hardkernel/initial-deployment.md: Add
philipandag Sep 19, 2024
40e79d7
unified/hardkernel/firmware-update.md: Add
philipandag Sep 19, 2024
1d34c93
unified/hardkernel/recovery.md: Add
philipandag Sep 19, 2024
e162fab
docs hardkernel: pre-commit
philipandag Sep 20, 2024
befecc5
hardkernel_odroid_h4_plus/hardware-matrix.md: Add
philipandag Sep 20, 2024
48b99dd
unified/hardkernel/test-matrix.md: Add only Dasharo Compatibility
philipandag Sep 20, 2024
ba5ee6c
unified/hardkernel/test-matrix.md: Add reference from script
philipandag Sep 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions docs/unified/hardkernel/building-manual.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Copy link
Contributor Author

@philipandag philipandag Sep 20, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IT DOES NOT WORK
Will we add this platform to the build script? It might as well be replaced with manual build instructions if not.

```

The resulting coreboot image will be placed in the coreboot directory as
`hardkernel_odroid_h4.rom`.
43 changes: 43 additions & 0 deletions docs/unified/hardkernel/firmware-update.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
```
36 changes: 36 additions & 0 deletions docs/unified/hardkernel/initial-deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only flashing bios works for now, when our fimware image does not include Intel blobs. This might change.

```

After successful operation reboot the platform.
6 changes: 6 additions & 0 deletions docs/unified/hardkernel/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
69 changes: 69 additions & 0 deletions docs/unified/hardkernel/recovery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
145 changes: 145 additions & 0 deletions docs/unified/hardkernel/test-matrix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
-->
27 changes: 27 additions & 0 deletions docs/variants/hardkernel_odroid_h4_plus/hardware-matrix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 |
17 changes: 17 additions & 0 deletions docs/variants/hardkernel_odroid_h4_plus/releases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Copy link
Contributor Author

@philipandag philipandag Sep 20, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

W need to create a newsletter registration link and add it here

Loading
Loading