Skip to content

Commit

Permalink
Add initial MinnowBaord Turbot documentation
Browse files Browse the repository at this point in the history 
Signed-off-by: Michał Żygowski <[email protected]>
  • Loading branch information
@miczyg1
miczyg1 committed Aug 6, 2024
1 parent 8d8557a commit 9a04307
Show file tree
Hide file tree
Showing 10 changed files with 398 additions and 0 deletions.
52 changes: 52 additions & 0 deletions docs/variants/minnowboard-turbot/building-manual.md
View file
Original file line number Diff line number Diff line change
@@ -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.
51 changes: 51 additions & 0 deletions docs/variants/minnowboard-turbot/firmware-update.md
View file
Original file line number Diff line number Diff line change
@@ -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<version>_no_sb.rom --fmap \
-i COREBOOT
```

* Images with TXE Secure Boot:

```bash
flashrom -p internal -w intel_minnowmax_v<version>_no_sb.rom --fmap \
-i COREBOOT -i MANIFESTS -i BOOTBLOCK
```
25 changes: 25 additions & 0 deletions docs/variants/minnowboard-turbot/hardware-matrix.md
View file
Original file line number Diff line number Diff line change
@@ -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 |
51 changes: 51 additions & 0 deletions docs/variants/minnowboard-turbot/initial-deployment.md
View file
Original file line number Diff line number Diff line change
@@ -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.
25 changes: 25 additions & 0 deletions docs/variants/minnowboard-turbot/overview.md
View file
Original file line number Diff line number Diff line change
@@ -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.
83 changes: 83 additions & 0 deletions docs/variants/minnowboard-turbot/recovery.md
View file
Original file line number Diff line number Diff line change
@@ -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.
17 changes: 17 additions & 0 deletions docs/variants/minnowboard-turbot/releases.md
View file
Original file line number Diff line number Diff line change
@@ -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).

<center>
[Subscribe to MinnowBoard Turbot Dasharo Release Newsletter]
[newsletter]{.md-button .md-button--primary .center}
</center>

Test results for this platform can be found
[here](TBD).

[newsletter]: https://newsletter.3mdeb.com/subscription/TZnzSJ1Un
79 changes: 79 additions & 0 deletions docs/variants/minnowboard-turbot/test-matrix.md
View file
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit 9a04307

Please sign in to comment.