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/unified/novacustom/firmware-update.md b/docs/unified/novacustom/firmware-update.md index 162486f4aa..00c45b7a2e 100644 --- a/docs/unified/novacustom/firmware-update.md +++ b/docs/unified/novacustom/firmware-update.md @@ -4,6 +4,14 @@ The following documentation describes the process of Dasharo open-source firmware update. The update process may be different, depending on which firmware version is currently installed on your device. +This process can be performed using the Dasharo Tools Suite available in the +Dasharo Pro Package (formerly Dasharo Entry Subscription) instead. For +instructions on how to use the DTS instead check + +This process can be performed using the Dasharo Tools Suite included in the Dasharo +Pro Package subscription (formerly Dasharo Entry Subscription) instead. For +instructions on how to use the DTS see the [DTS documentation](../../dasharo-tools-suite/documentation.md#firmware-update) + Your firmware version can be checked by entering the [Dasharo Setup Menu](/dasharo-menu-docs/overview/#dasharo-menu-guides) using the ++f2++ key while booting. 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..3e9a83a05c --- /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 + +```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..44cdf35a5d --- /dev/null +++ b/docs/variants/hardkernel_odroid_h4/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. + +## Hardkernel ODROID H4+ + +| 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/initial-deployment.md b/docs/variants/hardkernel_odroid_h4/initial-deployment.md new file mode 100644 index 0000000000..088959734e --- /dev/null +++ b/docs/variants/hardkernel_odroid_h4/initial-deployment.md @@ -0,0 +1,38 @@ +# 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.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. diff --git a/docs/variants/hardkernel_odroid_h4/overview.md b/docs/variants/hardkernel_odroid_h4/overview.md new file mode 100644 index 0000000000..34d4efed1e --- /dev/null +++ b/docs/variants/hardkernel_odroid_h4/overview.md @@ -0,0 +1,6 @@ +# Overview + +=== "Hardkernel ODROID H4" + - [Releases](../../variants/hardkernel_odroid_h4/releases.md) + - [Hardware Configuration Matrix](../../variants/hardkernel_odroid_h4/hardware-matrix.md) + - [Test Matrix](./test-matrix.md#hardkernel-odroid-h4) diff --git a/docs/variants/hardkernel_odroid_h4/recovery.md b/docs/variants/hardkernel_odroid_h4/recovery.md new file mode 100644 index 0000000000..7d98958fa8 --- /dev/null +++ b/docs/variants/hardkernel_odroid_h4/recovery.md @@ -0,0 +1,92 @@ +# 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 recovery + needs to be performed. In that case continue with the recovery instructions + for the ODROID H4 model. +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] + ``` + +## External flashing + +### 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. diff --git a/docs/variants/hardkernel_odroid_h4/releases.md b/docs/variants/hardkernel_odroid_h4/releases.md new file mode 100644 index 0000000000..ac261e904c --- /dev/null +++ b/docs/variants/hardkernel_odroid_h4/releases.md @@ -0,0 +1,20 @@ +# 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. + + +[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..831d8db0b1 --- /dev/null +++ b/docs/variants/hardkernel_odroid_h4/test-matrix.md @@ -0,0 +1,144 @@ +# 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. | [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]: . + + + + + + diff --git a/mkdocs.yml b/mkdocs.yml index b33ad6a144..98aaf7766e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -350,6 +350,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':