diff --git a/docs/variants/minnowboard-turbot/building-manual.md b/docs/variants/minnowboard-turbot/building-manual.md new file mode 100644 index 0000000000..5032213b70 --- /dev/null +++ b/docs/variants/minnowboard-turbot/building-manual.md @@ -0,0 +1,52 @@ +# Building manual + +## Intro + +This document describes the procedure for compiling coreboot compatible with +MinnowBoard Turbot. + +## 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 + +## Build Dasharo BIOS firmware + +1. Clone the coreboot repository: + + ```bash + git clone https://github.com/Dasharo/coreboot + ``` + +2. Checkout the desired version, e.g. `v0.9.0`: + + ```bash + cd coreboot + git checkout intel_minnowmax_v0.9.0 + ``` + +3. Checkout submodules: + + ```bash + git submodule update --init --checkout + ``` + +4. Build the firmware: + + + no TXE Secure Boot + + ```bash + ./build.sh minnow_no_sb + ``` + + + with TXE Secure Boot (evaluation mode) + + ```bash + ./build.sh minnow_sb + ``` + +The resulting coreboot image will be placed in the coreboot directory as +`intel_minnowmax_v0.9.0_no_sb.rom` or `intel_minnowmax_v0.9.0_sb.rom` +respectvely. diff --git a/docs/variants/minnowboard-turbot/firmware-update.md b/docs/variants/minnowboard-turbot/firmware-update.md new file mode 100644 index 0000000000..8520407420 --- /dev/null +++ b/docs/variants/minnowboard-turbot/firmware-update.md @@ -0,0 +1,51 @@ +# 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 update process, we recommend using +[Dasharo Tools Suite](../../dasharo-tools-suite/overview.md). + +Before starting the update procedure be sure to disable Secure Boot: + +1. Power on the device. +2. While the device is booting, hold the `F2` key to enter the UEFI Setup + Menu. +3. Enter the `Device Manager` menu. +4. Enter the [Secure Boot Configuration](../../dasharo-menu-docs/device-manager.md#secure-boot-configuration) + submenu. +5. Verify that the `Current Secure Boot State` field says Disabled - if not, + unselect the `Enable Secure Boot` option below then press `F10` to save + the changes. +6. Enter the [Dasharo System Features](../../dasharo-menu-docs/dasharo-system-features.md). +7. Enter the [Dasharo Security Options](../../dasharo-menu-docs/dasharo-system-features.md#dasharo-security-options). +8. Verify that the `Lock the BIOS boot medium` is unchecked - if not, unselect + the `Lock the BIOS boot medium` option, then press `F10` to save the + changes. +9. Verify that the `Enable SMM BIOS write protection` is unchecked - if not, + unselect the `Enable SMM BIOS write protection` option, 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 + +* Images without TXE Secure Boot: + + ```bash + flashrom -p internal -w intel_minnowmax_v_no_sb.rom --fmap \ + -i COREBOOT + ``` + +* Images with TXE Secure Boot: + + ```bash + flashrom -p internal -w intel_minnowmax_v_no_sb.rom --fmap \ + -i COREBOOT -i MANIFESTS -i BOOTBLOCK + ``` diff --git a/docs/variants/minnowboard-turbot/hardware-matrix.md b/docs/variants/minnowboard-turbot/hardware-matrix.md new file mode 100644 index 0000000000..f60dfb2f54 --- /dev/null +++ b/docs/variants/minnowboard-turbot/hardware-matrix.md @@ -0,0 +1,25 @@ +# Hardware configuration matrix + +## Introduction + +This document describes the hardware configuration used for validation of +Dasharo on the Intel MinnowBoard Turbot. + +## MinnowBoard Turbot Quad Core + +| Component | Description | +|--------------------------------|---------------------------------------------| +| **CPU** | Intel(R) Atom(R) CPU E3845 @ 1.91GHz | +| **RAM** | LPDDR3 soldered down | +| **Flash memory** | Winbond 25Q64JVSIQ | +| **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** | RTE v1.1.0 | +| **Power supply** | Phihong PSAA20R-050L6 5V 4A | diff --git a/docs/variants/minnowboard-turbot/initial-deployment.md b/docs/variants/minnowboard-turbot/initial-deployment.md new file mode 100644 index 0000000000..388f7fb23a --- /dev/null +++ b/docs/variants/minnowboard-turbot/initial-deployment.md @@ -0,0 +1,51 @@ +# 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 22.04. + +## Deploy using Dasharo Tools Suite + +For simplicity we recommend using +[Dasharo Tools Suite](../../dasharo-tools-suite/overview.md) to +omit all compilation steps and deploy the Dasharo firmware seamlessly. + +1. Boot Dasharo Tools Suite. +2. Perform Dasharo installation. + +This will flash the BIOS region only. After the successful operation, DTS will +reboot the platform. + +This concludes Dasharo deployment process using DTS. + +## 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 +``` + +## Flashing Dasharo + +To flash Dasharo on the platform, execute the following command: + +1. For TXE Secure Boot enabled images: + + ```bash + flashrom -p internal -w intel_minnowmax_v0.9.0_sb.rom + ``` + +2. For TXE Secure Boot disabled images: + + ```bash + flashrom -p internal -w intel_minnowmax_v0.9.0_no_sb.rom + ``` + +This will flash the whole image. After the operation is successful, power +cycle the platform. diff --git a/docs/variants/minnowboard-turbot/overview.md b/docs/variants/minnowboard-turbot/overview.md new file mode 100644 index 0000000000..39d2a649a0 --- /dev/null +++ b/docs/variants/minnowboard-turbot/overview.md @@ -0,0 +1,25 @@ +# Overview + +MinnowBoard Turbot is a small, versatile, embedded board with Intel Bay Trail +SoC. It comes in two main variants: + +* Dual Core - Intel® Atom® E3826, 1GB, 2GB or 4GB LPDDR3, fanless +* Quad Core - Intel® Atom® E3845, 1GB, 2GB or 4GB LPDDR3, with CPU fan + +## Documentation sections + +* [Releases](releases.md) - groups information about all releases. +* [Building manual](building-manual.md) - describes how to build Dasharo + compatible with MinnowBoard Turbot. +* [Initial deployment](initial-deployment.md) - describes initial Dasharo + deployment methods (i. e. flashing new firmware) compatible with MinnowBoard + Turbot. +* [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/minnowboard-turbot/recovery.md b/docs/variants/minnowboard-turbot/recovery.md new file mode 100644 index 0000000000..0dd24db4bf --- /dev/null +++ b/docs/variants/minnowboard-turbot/recovery.md @@ -0,0 +1,83 @@ +# Recovery + +## Intro + +The following documentation describes the process of recovering hardware from +the brick state with [RTE](../../transparent-validation/rte/introduction.md) and +Dasharo open-source firmware. + +## 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 below: + +1. Open the platform cover. +2. Connect the 6-pin flash header to the + [SPI header](../../transparent-validation/rte/v1.1.0/specification.md) + on RTE. + + | RTE SPI header | 8 pin J1 header | + |:--------------:|:---------------:| + | Vcc | pin 1 (Vcc) | + | GND | pin 2 (GND) | + | CS | pin 3 (CS) | + | SCLK | pin 4 (CLK) | + | MISO | pin 5 (MISO) | + | MOSI | pin 6 (MOSI) | + + ```txt + ______ + > | | + Vcc 3.3V ----1 2---- GND + | | + CS ----3 4---- CLK + | | + MISO ----5 6---- MOSI + | | + NC ----7 8---- IO3L + |______| + ``` + +> The IO3L signal is used to cut off the SPI flash from the SoC for flashing +> the board while it is powered. However, with RTE it is not necessary to +> drive this signal. + +## Firmware flashing + +To flash firmware follow the steps described below: + +1. Login to RTE via `ssh` or `minicom`. +2. Turn off the platform by disconnecting the power supply (turn off the + relay). +3. 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 + ``` + +4. Wait at least 2 seconds. +5. 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. + +6. 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/gpio406/value + ``` + +7. Turn on the platform by connecting the power supply. diff --git a/docs/variants/minnowboard-turbot/releases.md b/docs/variants/minnowboard-turbot/releases.md new file mode 100644 index 0000000000..e33de08369 --- /dev/null +++ b/docs/variants/minnowboard-turbot/releases.md @@ -0,0 +1,17 @@ +# Release Notes + +Following Release Notes describe status of Open Source Firmware development +of Dasharo compatible with MinnowBoard Turbot + +For details about our release process please read +[Dasharo Standard Release Process](../../dev-proc/standard-release-process.md). + +
+[Subscribe to MinnowBoard Turbot Dasharo Release Newsletter] +[newsletter]{.md-button .md-button--primary .center} +
+ +Test results for this platform can be found +[here](TBD). + +[newsletter]: https://newsletter.3mdeb.com/subscription/TZnzSJ1Un diff --git a/docs/variants/minnowboard-turbot/test-matrix.md b/docs/variants/minnowboard-turbot/test-matrix.md new file mode 100644 index 0000000000..5aa2eca1cb --- /dev/null +++ b/docs/variants/minnowboard-turbot/test-matrix.md @@ -0,0 +1,79 @@ +# 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 +MinnowBoard Turbot. + +## Module: Dasharo compatibility + +| No. | Supported test suite | Test suite ID | Supported test cases | +|:---:|:--------------------------------------|:-------------:|:-------------------------------------| +| 1. | [UEFI compatible interface][EFI] | EFI | All | +| 2. | [Display ports][DSP] | DSP | DSP002.001, DSP002.003 | +| 3. | [Network boot][PXE] | PXE | All | +| 4. | [Custom logo][CLG] | CLG | All | +| 5. | [Custom Boot Keys][CBK] | CBK | All | +| 6. | [USB HID and MSC Support][USB] | USB | USB001.xxx and USB002.xxx | +| 7. | [Debian Stable and Ubuntu LTS support][LBT] | LBT | LBT003.001, LBT003.002, LBT004.001, LBT004.002| +| 8. | [SMBIOS][DMI] | DMI | DMI002.001, DMI003.001, DMI004.001, DMI005.001, DMI006.001 | +| 9. | [Custom network boot entries][CNB] | CNB | CNB001.002 | +| 10. | [Audio subsystem][AUD] | AUD | AUD007.001, AUD008.001 | +| 11. | [UEFI Shell][USH] | USH | All | +| 12. | [USB detection][UDT] | UDT | All | +| 13. | [USB booting][UBT] | UBT | All | +| 14. | [Dasharo Tools Suite][DTS] | DTS | DTS001.001, DTS002.001, DTS003.001, DTS004.001, DTS005.001, DTS006.001 | +| 15. | [CPU status][CPU] | CPU | CPU001.001, CPU001.002 | + +[EFI]: ../../unified-test-documentation/dasharo-compatibility/30M-uefi-compatible-interface.md +[DSP]: ../../unified-test-documentation/dasharo-compatibility/31E-display-ports-and-lcd.md +[NBT]: ../../unified-test-documentation/dasharo-compatibility/315b-netboot-utilities.md +[CLG]: ../../unified-test-documentation/dasharo-compatibility/304-custom-logo.md +[CBK]: ../../unified-test-documentation/dasharo-compatibility/303-custom-boot-menu-key.md +[USB]: ../../unified-test-documentation/dasharo-compatibility/306-usb-hid-and-msc-support.md +[LBT]: ../../unified-test-documentation/dasharo-compatibility/308-debian-stable-and-ubuntu-lts-support.md +[PXE]: ../../unified-test-documentation/dasharo-compatibility/315-network-boot.md +[CNB]: ../../unified-test-documentation/dasharo-compatibility/30A-custom-network-boot-entries.md +[USH]: ../../unified-test-documentation/dasharo-compatibility/30P-uefi-shell.md +[DMI]: ../../unified-test-documentation/dasharo-compatibility/31L-smbios.md +[AUD]: ../../unified-test-documentation/dasharo-compatibility/31F-audio-subsystem.md +[UDT]: ../../unified-test-documentation/dasharo-compatibility/31O-usb-detect.md +[UBT]: ../../unified-test-documentation/dasharo-compatibility/31N-usb-boot.md +[CPU]: ../../unified-test-documentation/dasharo-compatibility/31T-cpu-status.md +[DTS]: ../../unified-test-documentation/dasharo-compatibility/326-dasharo-tools-suite.md + +## 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 | + +[TPM]: ../../unified-test-documentation/dasharo-security/200-tpm-support.md +[SBO]: ../../unified-test-documentation/dasharo-security/206-secure-boot.md +[BLS]: ../../unified-test-documentation/dasharo-security/20J-bios-lock-support.md +[SMM]: ../../unified-test-documentation/dasharo-security/20O-SMM-bios-write-protection.md +[PSW]: ../../unified-test-documentation/dasharo-security/20R-uefi-setup-password.md +[NBA]: ../../unified-test-documentation/dasharo-security/20T-network-boot.md +[USS]: ../../unified-test-documentation/dasharo-security/20S-usb-stack.md + +## 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/overview.md b/docs/variants/overview.md index a09be1deee..1b4f896046 100644 --- a/docs/variants/overview.md +++ b/docs/variants/overview.md @@ -9,6 +9,12 @@ open-source firmware distribution. - [QEMU Q35](qemu_q35/overview.md) +## Embedded + +* Following embedded targets are supported under Dasharo Community Support: + + - [MinnowBoard Turbot](minnowboard-turbot/overview.md) + ## Network appliance * Following network appliances are supported under Dasharo Support Package: diff --git a/mkdocs.yml b/mkdocs.yml index a7fe6177ee..fc584f8490 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -339,6 +339,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 + - 'MinnowBoard Turbot': + - 'Overview': variants/minnowboard-turbot/overview.md + - 'Releases': variants/minnowboard-turbot/releases.md + - 'Building manual': variants/minnowboard-turbot/building-manual.md + - 'Test matrix': variants/minnowboard-turbot/test-matrix.md + - 'Initial Deployment': variants/minnowboard-turbot/initial-deployment.md + - 'Firmware update': variants/minnowboard-turbot/firmware-update.md + - 'Recovery': variants/minnowboard-turbot/recovery.md + - 'Hardware Configuration Matrix': variants/minnowboard-turbot/hardware-matrix.md # - 'Development Environment': # - 'Nix': dev-env/nix-dev-env.md - 'Guides':