diff --git a/docs/images/odroid_flash_switch.jpg b/docs/images/odroid_flash_switch.jpg new file mode 100644 index 0000000000..e514222103 Binary files /dev/null and b/docs/images/odroid_flash_switch.jpg differ diff --git a/docs/images/odroid_h4.jpg b/docs/images/odroid_h4.jpg new file mode 100644 index 0000000000..4e398f6e12 Binary files /dev/null and b/docs/images/odroid_h4.jpg differ diff --git a/docs/variants/hardkernel_odroid_h4/building-manual.md b/docs/variants/hardkernel_odroid_h4/building-manual.md new file mode 100644 index 0000000000..572af99b49 --- /dev/null +++ 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_ + ``` + + 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_.rom`. diff --git a/docs/variants/hardkernel_odroid_h4/firmware-update.md b/docs/variants/hardkernel_odroid_h4/firmware-update.md new file mode 100644 index 0000000000..ddaa4936cc --- /dev/null +++ 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.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 new file mode 100644 index 0000000000..50286a0ad1 --- /dev/null +++ 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 new file mode 100644 index 0000000000..9471637f77 --- /dev/null +++ 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 new file mode 100644 index 0000000000..14f9eb52ac --- /dev/null +++ b/docs/variants/hardkernel_odroid_h4/overview.md @@ -0,0 +1,33 @@ +# Overview + +## Hardkernel ODROID-H4 PLUS + +
+![](../../images/odroid_h4.jpg) +
+ +Hardkernel ODROID-H4 PLUS is a small single-board computer with publicly +available schematics and documentation. 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 new file mode 100644 index 0000000000..c2acccda43 --- /dev/null +++ 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-h4/hardware/restore_h4_bios#using_tool_and_soldering_skills) + . diff --git a/docs/variants/hardkernel_odroid_h4/releases.md b/docs/variants/hardkernel_odroid_h4/releases.md new file mode 100644 index 0000000000..7f3b808e79 --- /dev/null +++ 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). + +
+ +[Subscribe to Hardkernel ODROID H4 Dasharo Release Newsletter] +[newsletter]{ .md-button .md-button--primary .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/). + + +[newsletter]: https://newsletter.3mdeb.com/subscription/pULA4K0Eo diff --git a/docs/variants/hardkernel_odroid_h4/test-matrix.md b/docs/variants/hardkernel_odroid_h4/test-matrix.md new file mode 100644 index 0000000000..83bb880494 --- /dev/null +++ b/docs/variants/hardkernel_odroid_h4/test-matrix.md @@ -0,0 +1,129 @@ +# 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. + +## 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. | [Sign of life][SOL] | SOL | All | +| 16. | [Persistent Boot Splash][LCM] | LCM | All | +| 17. | [Debian Stable and Ubuntu LTS support][LBT] | LBT | LBT003.001, LBT003.002, LBT004.001, LBT004.002| +| 18. | [Power state after power fail][PSF] | PSF | All | +| 19. | [Dasharo Tools Suite][DTS] | DTS | DTS001.001, DTS002.001, DTS003.001, DTS004.001, DTS005.001, DTS006.001 | +| 20. | [Reset to defaults][RTD] | RTD | RTD001.001, RTD002.001, RTD003.001, RTD004.001, RTD006.001 | +| 21. | [Ethernet interface][NET] | NET | All | +| 22. | [Dasharo Configuration Utility][NET] | DCU | DCU001.001, DCU002.001, DCU003.001 | +| 23. | [ESP scanning][ESP] | ESP | All | +| 24. | [Network Boot Utilities][NBT] | NBT | All | +| 25. | [USB detection][UDT] | UDT | All | +| 26. | [USB booting][UBT] | UBT | All | +| 27. | Setup Menu information | SET | All | +| 28. | [Ubuntu booting performance test][BUB]| BUB | All | +| 29. | [CPU status][CPU] | CPU | CPU001.001, CPU002.001, CPU003.001, CPU004.001| +| 30. | [Auto boot time-out][BMM] | BMM | All | + +[CBO]: ../../unified-test-documentation/dasharo-compatibility/325-custom-boot-order.md +[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]: ../../unified-test-documentation/dasharo-compatibility/312-nvme-support.md +[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]: ../../unified-test-documentation/dasharo-compatibility/31M-platform-suspend-and-resume.md +[DMI]: ../../unified-test-documentation/dasharo-compatibility/31L-smbios.md +[MMC]: ../../unified-test-documentation/dasharo-compatibility/31M-emmc-support.md + +[SOL]: ../../unified-test-documentation/dasharo-compatibility/347-sign-of-life.md +[LCM]: ../../unified-test-documentation/dasharo-compatibility/328-logo-customization-functionality.md +[LBT]: ../../unified-test-documentation/dasharo-compatibility/308-debian-stable-and-ubuntu-lts-support.md +[PSF]: ../../unified-test-documentation/dasharo-compatibility/360-power-after-fail.md +[DTS]: ../../unified-test-documentation/dasharo-compatibility/326-dasharo-tools-suite.md +[RTD]: ../../dasharo-menu-docs/overview.md#f9-reset-to-defaults +[NET]: ../../unified-test-documentation/dasharo-stability/01-net-controller-after-coldboot-warmboot-reboot-suspend.md +[DCU]: ../../unified-test-documentation/dasharo-compatibility/362-dcu.md +[ESP]: ../../unified-test-documentation/dasharo-compatibility/361-esp-scanning.md +[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 + +[BUB]: ../../unified-test-documentation/dasharo-performance/407-ubuntu-booting-performance-test.md +[CPU]: ../../unified-test-documentation/dasharo-compatibility/31T-cpu-status.md +[BMM]: ../../dasharo-menu-docs/boot-maintenance-mgr.md#boot-maintenance-manager + +## 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 | All | +| 4. | [Measured boot integration][MBO] | MBO | All | +| 5. | [UEFI Secure Boot integration][SBO] | SBO | All | +| 6. | [UEFI Setup password][PSW] | PSW | All | +| 8. | [USB stack enable/disable][USS] | USS | All | +| 9. | [Network stack enable/disable][NBA] | NBA | All | +| 10. | [SMM BIOS write protection][SMM] | SMM | All | +| 11. | [TPM2 Commands][TPMCMD] | TPMCMD | All | + +[TPM]: ../../unified-test-documentation/dasharo-security/200-tpm-support.md +[VBO]: ../../unified-test-documentation/dasharo-security/201-verified-boot.md +[BLS]: ../../unified-test-documentation/dasharo-security/20J-bios-lock-support.md +[MBO]: ../../unified-test-documentation/dasharo-security/203-measured-boot.md +[SBO]: ../../unified-test-documentation/dasharo-security/206-secure-boot.md +[PSW]: ../../unified-test-documentation/dasharo-security/20R-uefi-setup-password.md +[EDP]: ../../unified-test-documentation/dasharo-security/20L-early-boot-dma-protection.md +[USS]: ../../unified-test-documentation/dasharo-security/20S-usb-stack.md +[NBA]: ../../unified-test-documentation/dasharo-security/20T-network-boot.md +[SMM]: ../../unified-test-documentation/dasharo-security/20O-SMM-bios-write-protection.md +[TPMCMD]: ../../unified-test-documentation/dasharo-security/200-tpm2-commands.md + +## Module: Dasharo Stability + +| No. | Supported test suite | Test suite ID | Supported test cases | +|:---:|:--------------------------------------|:-------------:|:-------------------------------------| +| 1. | TPM Support | TPD | TPD003.001,TPD004.001 | +| 2. | [USB Devices Detection][SUD] | SUD | All | +| 3. | [NVMe detection][SNV] | SNV | All | + + +[SUD]: ../../unified-test-documentation/dasharo-stability/C01-usb-type-a-devices-detection.md +[SNV]: ../../unified-test-documentation/dasharo-stability/C03-nvme-detection.md + +## Module: Dasharo Performance + +| No. | Supported test suite | Test suite ID | Supported test cases | +|:---:|:--------------------------------------|:-------------:|:-------------------------------------| +| 1. | [Serial Boot Measure][CBMEM] | CBMEM | All | +| 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 | 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 diff --git a/mkdocs.yml b/mkdocs.yml index da11655510..afbc2d0131 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -393,6 +393,15 @@ nav: - 'FAQ': variants/pc_engines/faq.md - 'Announcement': variants/pc_engines/post-eol-fw-announcement.md - 'Firmware write protection': variants/pc_engines/bios-lock.md + - 'Hardkernel ODROID H4': + - 'Overview': variants/hardkernel_odroid_h4/overview.md + - 'Releases': variants/hardkernel_odroid_h4/releases.md + - 'Building manual': variants/hardkernel_odroid_h4/building-manual.md + - 'Initial deployment': variants/hardkernel_odroid_h4/initial-deployment.md + - 'Firmware update': variants/hardkernel_odroid_h4/firmware-update.md + - 'Recovery': variants/hardkernel_odroid_h4/recovery.md + - 'Hardware Configuration Matrix': variants/hardkernel_odroid_h4/hardware-matrix.md + - 'Test matrix': variants/hardkernel_odroid_h4/test-matrix.md # - 'Development Environment': # - 'Nix': dev-env/nix-dev-env.md - 'Guides':