From b865f82b3fbfb07aad7817fb55fa759cc982ef6c Mon Sep 17 00:00:00 2001 From: Pawel Langowski Date: Fri, 19 Apr 2024 08:14:55 +0200 Subject: [PATCH 1/7] unified/novacustom/overview.md: Change links Signed-off-by: Pawel Langowski --- docs/unified/novacustom/overview.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/unified/novacustom/overview.md b/docs/unified/novacustom/overview.md index fd2aa43210..5d696a985c 100644 --- a/docs/unified/novacustom/overview.md +++ b/docs/unified/novacustom/overview.md @@ -15,8 +15,8 @@ Select your Dasharo firmware flavor:
- - [NS51 Series](https://configurelaptop.eu/ns51-series/) - - [NS70 Series](https://configurelaptop.eu/ns70-series/) + - [NS51 Series](https://configurelaptop.eu/product/ns51-series/) + - [NS70 Series](https://configurelaptop.eu/product/ns70-series/)
@@ -28,7 +28,7 @@ Select your Dasharo firmware flavor:
- - [NV41 Series](https://configurelaptop.eu/nv41-series/) + - [NV41 Series](https://configurelaptop.eu/product/nv41-series/)
@@ -40,8 +40,8 @@ Select your Dasharo firmware flavor:
- - [NS51 Series](https://configurelaptop.eu/ns51-series/) - - [NS70 Series](https://configurelaptop.eu/ns70-series/) + - [NS51 Series](https://configurelaptop.eu/product/ns51-series/) + - [NS70 Series](https://configurelaptop.eu/product/ns70-series/)
@@ -53,7 +53,7 @@ Select your Dasharo firmware flavor:
- - [NV41 Series](https://configurelaptop.eu/nv41-series/) + - [NV40 Series](https://novacustom.com/product/nv40-series/)
From 7eb0bd3d1805e27a321c43b8903b7430c958a1e7 Mon Sep 17 00:00:00 2001 From: Pawel Langowski Date: Fri, 19 Apr 2024 10:51:59 +0200 Subject: [PATCH 2/7] Remove variants/novacustom_nv4x_adl/heads and move its sections to other files Signed-off-by: Pawel Langowski --- docs/unified/novacustom/building-manual.md | 344 ++++++++++-------- .../unified/novacustom/firmware-transition.md | 86 +++++ docs/unified/novacustom/firmware-update.md | 102 +++--- docs/unified/novacustom/initial-deployment.md | 6 + .../novacustom_nv4x_adl/hardware-matrix.md | 9 + docs/variants/novacustom_nv4x_adl/heads.md | 208 ----------- .../novacustom_nv4x_adl/releases_heads.md | 49 +++ .../novacustom_nv4x_adl/test-matrix.md | 4 + mkdocs.yml | 2 + 9 files changed, 410 insertions(+), 400 deletions(-) create mode 100644 docs/unified/novacustom/firmware-transition.md delete mode 100644 docs/variants/novacustom_nv4x_adl/heads.md create mode 100644 docs/variants/novacustom_nv4x_adl/releases_heads.md diff --git a/docs/unified/novacustom/building-manual.md b/docs/unified/novacustom/building-manual.md index 6fb1f07722..f8838b5c5c 100644 --- a/docs/unified/novacustom/building-manual.md +++ b/docs/unified/novacustom/building-manual.md @@ -1,228 +1,280 @@ # Dasharo firmware building guide -## Intro +=== "Dasharo (UEFI)" -This guide shows how to build Dasharo firmware for NovaCustom devices. It -contains two components: + ## Intro -- [BIOS firmware](#build-dasharo-bios-firmware) -- [EC firmware](#build-dasharo-ec-firmware) + This guide shows how to build Dasharo firmware for NovaCustom devices. It + contains two components: -## Requirements + - [BIOS firmware](#build-dasharo-bios-firmware) + - [EC firmware](#build-dasharo-ec-firmware) -This guide was verified on Ubuntu 22.04. In practice, any Linux distribution -with [Docker](https://www.docker.com/) support should be enough to complete it. + ## Requirements -Make sure that you have following packages installed: + This guide was verified on Ubuntu 22.04. In practice, any Linux distribution + with [Docker](https://www.docker.com/) support should be enough to complete + it. -- 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 + Make sure that you have following packages installed: - ```bash - sudo apt -y install git - ``` + - 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 Dasharo coreboot repository: - - ```bash - git clone https://github.com/Dasharo/coreboot.git - ``` - -1. Navigate to the source code directory and checkout to the desired revision: + ```bash + sudo apt -y install git + ``` - ```bash - cd coreboot - ``` + ## Build Dasharo BIOS firmware - > Replace `X.Y.Z` with a valid version + 1. Clone the Dasharo coreboot repository: - === "NS5x/7x 12th Gen" ```bash - git checkout novacustom_ns5x_adl_vX.Y.Z + git clone https://github.com/Dasharo/coreboot.git ``` - === "NV4x 12th Gen" - ```bash - git checkout novacustom_nv4x_adl_vX.Y.Z - ``` + 1. Navigate to the source code directory and checkout to the desired revision: - === "NX5x/7x 11th Gen" ```bash - git checkout novacustom_ns5x_tgl_vX.Y.Z + cd coreboot ``` - === "NV4x 11th Gen" - ```bash - git checkout novacustom_nv4x_tgl_vX.Y.Z - ``` + > Replace `X.Y.Z` with a valid version -1. Checkout submodules: + === "NS5x/7x 12th Gen" + ```bash + git checkout novacustom_ns5x_adl_vX.Y.Z + ``` - ```bash - git submodule update --init --recursive --checkout - ``` + === "NV4x 12th Gen" + ```bash + git checkout novacustom_nv4x_adl_vX.Y.Z + ``` -1. Start docker container: + === "NX5x/7x 11th Gen" + ```bash + git checkout novacustom_ns5x_tgl_vX.Y.Z + ``` - === "NS5x/7x 12th Gen" - ```bash - docker run --rm -it -u $UID \ - -v $PWD:/home/coreboot/coreboot \ - -w /home/coreboot/coreboot \ - coreboot/coreboot-sdk:2021-09-23_b0d87f753c /bin/bash - ``` + === "NV4x 11th Gen" + ```bash + git checkout novacustom_nv4x_tgl_vX.Y.Z + ``` - === "NV4x 12th Gen" - ```bash - docker run --rm -it -u $UID \ - -v $PWD:/home/coreboot/coreboot \ - -w /home/coreboot/coreboot \ - coreboot/coreboot-sdk:2021-09-23_b0d87f753c /bin/bash - ``` + 1. Checkout submodules: - === "NX5x/7x 11th Gen" ```bash - docker run --rm -it -u $UID \ - -v $PWD:/home/coreboot/coreboot \ - -w /home/coreboot/coreboot \ - coreboot/coreboot-sdk:0ad5fbd48d /bin/bash + git submodule update --init --recursive --checkout ``` - === "NV4x 11th Gen" + 1. Start docker container: + + === "NS5x/7x 12th Gen" + ```bash + docker run --rm -it -u $UID \ + -v $PWD:/home/coreboot/coreboot \ + -w /home/coreboot/coreboot \ + coreboot/coreboot-sdk:2021-09-23_b0d87f753c /bin/bash + ``` + + === "NV4x 12th Gen" + ```bash + docker run --rm -it -u $UID \ + -v $PWD:/home/coreboot/coreboot \ + -w /home/coreboot/coreboot \ + coreboot/coreboot-sdk:2021-09-23_b0d87f753c /bin/bash + ``` + + === "NX5x/7x 11th Gen" + ```bash + docker run --rm -it -u $UID \ + -v $PWD:/home/coreboot/coreboot \ + -w /home/coreboot/coreboot \ + coreboot/coreboot-sdk:0ad5fbd48d /bin/bash + ``` + + === "NV4x 11th Gen" + ```bash + docker run --rm -it -u $UID \ + -v $PWD:/home/coreboot/coreboot \ + -w /home/coreboot/coreboot \ + coreboot/coreboot-sdk:0ad5fbd48d /bin/bash + ``` + + 1. Inside of the container, configure the build process: + + === "NS5x/7x 12th Gen" + ```bash + make distclean && cp configs/config.novacustom_ns5x_adl .config + ``` + + === "NV4x 12th Gen" + ```bash + make distclean && cp configs/config.novacustom_nv4x_adl .config + ``` + + === "NX5x/7x 11th Gen" + ```bash + make distclean && cp configs/config.novacustom_ns5x_tgl .config + ``` + + === "NV4x 11th Gen" + ```bash + make distclean && cp configs/config.novacustom_nv4x_tgl .config + ``` + + 1. Start the build process: + ```bash - docker run --rm -it -u $UID \ - -v $PWD:/home/coreboot/coreboot \ - -w /home/coreboot/coreboot \ - coreboot/coreboot-sdk:0ad5fbd48d /bin/bash + make olddefconfig && make ``` -1. Inside of the container, configure the build process: + This will produce a Dasharo binary placed in `build/coreboot.rom`. - === "NS5x/7x 12th Gen" - ```bash - make distclean && cp configs/config.novacustom_ns5x_adl .config - ``` + At the end of the build process, the following warning will be displayed: - === "NV4x 12th Gen" - ```bash - make distclean && cp configs/config.novacustom_nv4x_adl .config - ``` + ** WARNING ** + coreboot has been built without an Intel Firmware Descriptor. + Never write a complete coreboot.rom without an IFD to your + board's flash chip! You can use flashrom's IFD or layout + parameters to flash only to the BIOS region. + + This is expected, and something you have to pay attention to if you would like + to flash your Dasharo binary. Make sure to only overwrite the BIOS region, + leaving everything else untouched. Otherwise, expect that your device will no + longer be able to boot unless fixed using an external programmer. + + The binary will not contain a boot splash logo. Refer to + [logo customization](../../guides/logo-customization.md) for including one. + + ## Build Dasharo EC firmware + + 1. Clone the Dasharo ec repository: - === "NX5x/7x 11th Gen" ```bash - make distclean && cp configs/config.novacustom_ns5x_tgl .config + git clone https://github.com/Dasharo/ec.git ``` - === "NV4x 11th Gen" + 1. Navigate to the source code directory and checkout to the desired revision: + ```bash - make distclean && cp configs/config.novacustom_nv4x_tgl .config + cd ec ``` -1. Start the build process: + > Replace `X.Y.Z` with a valid version - ```bash - make olddefconfig && make - ``` + === "NS5x/7x 12th Gen" + ```bash + git checkout novacustom_ns5x_adl_vX.Y.Z + ``` -This will produce a Dasharo binary placed in `build/coreboot.rom`. + === "NV4x 12th Gen" + ```bash + git checkout novacustom_nv4x_adl_vX.Y.Z + ``` -At the end of the build process, the following warning will be displayed: + === "NX5x/7x 11th Gen" + ```bash + git checkout novacustom_ns5x_tgl_vX.Y.Z + ``` - ** WARNING ** - coreboot has been built without an Intel Firmware Descriptor. - Never write a complete coreboot.rom without an IFD to your - board's flash chip! You can use flashrom's IFD or layout - parameters to flash only to the BIOS region. + === "NV4x 11th Gen" + ```bash + git checkout novacustom_nv4x_tgl_vX.Y.Z + ``` -This is expected, and something you have to pay attention to if you would like -to flash your Dasharo binary. Make sure to only overwrite the BIOS region, -leaving everything else untouched. Otherwise, expect that your device will no -longer be able to boot unless fixed using an external programmer. + 1. Checkout submodules: -The binary will not contain a boot splash logo. Refer to -[logo customization](../../guides/logo-customization.md) for including one. + ```bash + git submodule update --init --recursive --checkout + ``` -## Build Dasharo EC firmware + 1. Build the EC firmware: -1. Clone the Dasharo ec repository: + === "NS5x/7x 12th Gen" + ```bash + EC_BOARD_VENDOR=novacustom EC_BOARD_MODEL=ns5x_adl ./build.sh + ``` - ```bash - git clone https://github.com/Dasharo/ec.git - ``` + The resulting image will be placed in: `novacustom_ns5x_adl_ec.rom`. -1. Navigate to the source code directory and checkout to the desired revision: + === "NV4x 12th Gen" + ```bash + EC_BOARD_VENDOR=novacustom EC_BOARD_MODEL=nv4x_adl ./build.sh + ``` - ```bash - cd ec - ``` + The resulting image will be placed in: `novacustom_nv4x_adl_ec.rom`. - > Replace `X.Y.Z` with a valid version + === "NX5x/7x 11th Gen" + ```bash + EC_BOARD_VENDOR=novacustom EC_BOARD_MODEL=ns5x_tgl ./build.sh + ``` - === "NS5x/7x 12th Gen" - ```bash - git checkout novacustom_ns5x_adl_vX.Y.Z - ``` + The resulting image will be placed in: `novacustom_ns5x_tgl_ec.rom`. - === "NV4x 12th Gen" - ```bash - git checkout novacustom_nv4x_adl_vX.Y.Z - ``` + === "NV4x 11th Gen" + ```bash + EC_BOARD_VENDOR=novacustom EC_BOARD_MODEL=nv4x_tgl ./build.sh + ``` - === "NX5x/7x 11th Gen" - ```bash - git checkout novacustom_ns5x_tgl_vX.Y.Z - ``` + The resulting image will be placed in: `novacustom_nv4x_tgl_ec.rom`. - === "NV4x 11th Gen" - ```bash - git checkout novacustom_nv4x_tgl_vX.Y.Z - ``` +=== "Dasharo (coreboot + Heads)" -1. Checkout submodules: + ## Intro - ```bash - git submodule update --init --recursive --checkout - ``` + This section presents the crucial steps required to build the Dasharo Heads + firmware. For more information, you may also refer to the official + [Heads building documentation](https://osresearch.net/general-building/). -1. Build the EC firmware: + ## Requirements + + This guide was verified on Ubuntu 22.04. In practice, any Linux distribution + with [Docker](https://www.docker.com/) support should be enough to complete it. + + Make sure that you have following packages installed: + + - 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 - === "NS5x/7x 12th Gen" ```bash - EC_BOARD_VENDOR=novacustom EC_BOARD_MODEL=ns5x_adl ./build.sh + sudo apt -y install git ``` - The resulting image will be placed in: `novacustom_ns5x_adl_ec.rom`. + ## Building + + 1. Clone Dasharo Heads repository: - === "NV4x 12th Gen" ```bash - EC_BOARD_VENDOR=novacustom EC_BOARD_MODEL=nv4x_adl ./build.sh + git clone https://github.com/Dasharo/heads.git ``` - The resulting image will be placed in: `novacustom_nv4x_adl_ec.rom`. + 1. Navigate to the source code directory and checkout to the desired revision: - === "NX5x/7x 11th Gen" ```bash - EC_BOARD_VENDOR=novacustom EC_BOARD_MODEL=ns5x_tgl ./build.sh + cd heads + git checkout novacustom_nv4x_adl_v0.9.0 ``` - The resulting image will be placed in: `novacustom_ns5x_tgl_ec.rom`. + 1. Start the build inside the docker container: - === "NV4x 11th Gen" ```bash - EC_BOARD_VENDOR=novacustom EC_BOARD_MODEL=nv4x_tgl ./build.sh + docker run --rm -it -v $PWD:$PWD -w $PWD \ + 3mdeb/heads-docker:3.0.1 make BOARD=nitropad-nv41 ``` - The resulting image will be placed in: `novacustom_nv4x_tgl_ec.rom`. + This will produce a Dasharo binary placed in + `build/x86/nitropad-nv41/dasharo-nitropad-nv41-*.rom`. ## Install Dasharo firmware The Dasharo firmware can be flashed in following ways, depending on your situation: -- To flash Dasharo for the first time, refer to the - [initial deployment guide](initial-deployment.md). -- To update Dasharo, refer to the [firmware update guide](firmware-update.md). + - To flash Dasharo for the first time, refer to the + [initial deployment guide](initial-deployment.md). + - To update Dasharo, refer to the [firmware update guide](firmware-update.md). diff --git a/docs/unified/novacustom/firmware-transition.md b/docs/unified/novacustom/firmware-transition.md new file mode 100644 index 0000000000..d333fa11f4 --- /dev/null +++ b/docs/unified/novacustom/firmware-transition.md @@ -0,0 +1,86 @@ +# Firmware transition + +## Introduction + +This document describes the process of transitioning from Dasharo UEFI to Heads +and the other way around. + +## Switching from Dasharo UEFI to Heads + +To change firmware branches from UEFI to Heads, because of how different the two +firmware types are, it's required to disable some security measures before +flashing. Follow the steps below to install Heads from an existing Dasharo UEFI +firmware installation: + +- Hold down the ++f2++ key and press the ++power++ button to enter the UEFI + Setup Menu +- Enter the `Device Manager` submenu and disable `Secure Boot` +- Enter the `Dasharo System Features` submenu +- In the `Dasharo Security Options` submenu, disable: + + SMM BIOS Write Protection + + BIOS boot medium lock +- In the `Intel Management Engine Options` submenu disable the Management Engine + +!!! tip + + For a more detailed guide on the UEFI Setup Menu options, check out the + [Dasharo menu documentation](https://docs.dasharo.com/dasharo-menu-docs/). + +- [Boot into Dasharo Tools Suite](https://docs.dasharo.com/dasharo-tools-suite/documentation/#running) +- Enter your DES subscription credentials +- Select `Update Dasharo firmware` to check for updates +- When asked to switch to Heads firmware, press `Y` +- Proceed with [DTS firmware update](https://docs.dasharo.com/dasharo-tools-suite/documentation/#firmware-update) + as usual + +When the update is finished, your laptop will shut down automatically. Power it +back on to boot into your new Heads installation! + +!!! warning "TOTP secrets warning" + + On the first boot, you will be shown a warning about TOTP secrets. This is + normal and expected on the first boot. Run `OEM Factory Reset / + Re-Ownership` to finish deploying Heads. + + Check out [Heads documentation](https://osresearch.net/Configuring-Keys/#oem-factory-resetre-ownership) + for a detailed factory reset guide. + +!!! note "Note for Qubes OS users" + + After installing Qubes while Heads is installed, you will need to select + `Reset TPM` in the Heads menu to finish the installation. + + From the main menu, enter `Options` -> `TPM/TOTP/HOTP Options` and select + `Reset the TPM`. + + Users upgrading to Heads while Qubes is already installed are not affected. + +## Switching from Dasharo Heads back to UEFI + +To revert back to UEFI, you will need to boot into DTS from a USB stick. + +- Follow the [Dasharo Tools Suite documentation](https://docs.dasharo.com/dasharo-tools-suite/documentation/#running) + to boot DTS from a USB stick +- In the DTS main menu, select `Update Dasharo firmware` to check for available + updates. +- When prompted to revert back to UEFI, press `Y` +- Proceed with [DTS firmware update](https://docs.dasharo.com/dasharo-tools-suite/documentation/#firmware-update) + as usual + +Once finished, your laptop will shut down automatically. Power it back on to +boot into your UEFI firmware. + +> When reverting to UEFI, it's not possible to restore EFI boot manager entries +> that were added before installing Heads. Therefore, you may need to re-create +> your boot entries manually, or find your boot loader using `Boot From File` +> option in the UEFI setup menu. + +## Logo customization + +Normally, the logo can be replaced using the +[Dasharo Configuration Utility](https://github.com/Dasharo/dcu?tab=readme-ov-file#dcu---dasharo-configuration-utility) +– a tool designed to modify Dasharo binary images. However, logo customization is +not supported as of now. To replace the logo, one must rebuild the firmware. You +would need to replace the `branding/Dasharo/bootsplash.jpg` with your own, and +proceed with the +[Building manual](/unified/novacustom/building-manual/#dasharo-coreboot--heads). diff --git a/docs/unified/novacustom/firmware-update.md b/docs/unified/novacustom/firmware-update.md index 02e642b89e..162486f4aa 100644 --- a/docs/unified/novacustom/firmware-update.md +++ b/docs/unified/novacustom/firmware-update.md @@ -8,65 +8,75 @@ 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. -## Prerequisites +=== "Dasharo (UEFI)" -Depending on the firmware version, there may be manual steps required to ensure -that the firmware can be updated. `11th Gen` devices starting from version v1.5.0 -and `12th Gen` devices starting from version v1.7.0 have support for [Firmware -Update Mode](#firmware-update-mode). For older versions, please continue with -the [Updating older versions](#updating-older-versions) section. + ## Prerequisites -> Advanced users can also [build](./building-manual.md) and/or flash the -> binaries themselves by following the steps under the [Manual -> update](#manual-update) section. + Depending on the firmware version, there may be manual steps required to ensure + that the firmware can be updated. `11th Gen` devices starting from version v1.5.0 + and `12th Gen` devices starting from version v1.7.0 have support for [Firmware + Update Mode](#firmware-update-mode). For older versions, please continue with + the [Updating older versions](#updating-older-versions) section. -### Firmware Update Mode + > Advanced users can also [build](./building-manual.md) and/or flash the + > binaries themselves by following the steps under the [Manual + > update](#manual-update) section. -If the currently installed Dasharo version supports Firmware Update Mode, follow -the steps outlined in the [generic Firmware Update documentation](../../guides/firmware-update.md#firmware-update-mode). + ### Firmware Update Mode -Check out our [YouTube video](https://www.youtube.com/watch?v=muWjhrQ7bQk) -for a demonstration of Firmware Update Mode. + If the currently installed Dasharo version supports Firmware Update Mode, follow + the steps outlined in the [generic Firmware Update documentation](../../guides/firmware-update.md#firmware-update-mode). -### Updating older versions + Check out our [YouTube video](https://www.youtube.com/watch?v=muWjhrQ7bQk) + for a demonstration of Firmware Update Mode. -1. First, ensure that [UEFI Secure Boot](../../dasharo-menu-docs/device-manager.md#secure-boot-configuration) - has been disabled. + ### Updating older versions -1. Boot to the [Dasharo Tools Suite](../../dasharo-tools-suite/documentation.md#bootable-over-a-network). - We recommend the network boot option. + 1. First, ensure that [UEFI Secure Boot](../../dasharo-tools-suite/documentation.md#disabling-secure-boot) + has been disabled. -1. In the main menu of Dasharo Tools Suite, select option `5` to proceed with - the installation of the firmware update. + 1. Boot to the [Dasharo Tools Suite](../../dasharo-tools-suite/documentation.md#bootable-over-a-network). + We recommend the network boot option. -1. In case you want to know more about the firmware update option in Dasharo - Tools Suite, please check out the - [features section](../../dasharo-tools-suite/documentation.md#firmware-update) - of the dedicated Dasharo Tools Suite documentation page. + 1. In the main menu of Dasharo Tools Suite, select option `5` to proceed with + the installation of the firmware update. -### Manual update + 1. In case you want to know more about the firmware update option in Dasharo + Tools Suite, please check out the + [features section](../../dasharo-tools-suite/documentation.md#firmware-update) + of the dedicated Dasharo Tools Suite documentation page. -This update method is for advanced users only and is not recommended for -regular end users. + ### Manual update -Ensure that the firmware protections are disabled (1) in -[Dasharo Security Options](../../dasharo-menu-docs/dasharo-system-features.md). -Both `BIOS boot medium lock` and `Enable SMM BIOS write protection` should -be unchecked. [UEFI Secure Boot](../../dasharo-menu-docs/device-manager.md#secure-boot-configuration) -must be disabled as well (uncheck `Attempt Secure Boot` if -`Current Secure Boot State` does not say `Disabled`). To apply changes, you -will need to reboot. -{ .annotate } + This update method is for advanced users only and is not recommended for + regular end users. -1. These options were introduced in v1.5.0 for TGL models and v1.7.0 for ADL - models. You can skip these steps if you are using an older firmware version. + Ensure that the firmware protections are disabled (1) in + [Dasharo Security Options](../../dasharo-menu-docs/dasharo-system-features.md). + Both `BIOS boot medium lock` and `Enable SMM BIOS write protection` should + be unchecked. [UEFI Secure Boot](../../dasharo-menu-docs/device-manager.md#secure-boot-configuration) + must be disabled as well (uncheck `Attempt Secure Boot` if + `Current Secure Boot State` does not say `Disabled`). To apply changes, you + will need to reboot. + { .annotate } -Follow the manual update procedure described in the [DTS firmware update -documentation](https://docs.dasharo.com/dasharo-tools-suite/documentation/#local-firmware-update). + 1. These options were introduced in v1.5.0 for TGL models and v1.7.0 for ADL + models. You can skip these steps if you are using an older firmware version. -> Please make sure you that you update the BIOS firmware and the EC firmware -> respectively, as the laptop will power off after the EC firmware flash. -> -> Please also note that -> [network boot must be enabled](https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#networking-options) -> if you want to boot to the Dasharo Tools Suite over a network connection. + Follow the manual update procedure described in the [DTS firmware update + documentation](https://docs.dasharo.com/dasharo-tools-suite/documentation/#local-firmware-update). + + > Please make sure you that you update the BIOS firmware and the EC firmware + > respectively, as the laptop will power off after the EC firmware flash. + > + > Please also note that + > [network boot must be enabled](https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#networking-options) + > if you want to boot to the Dasharo Tools Suite over a network connection. + +=== "Dasharo (coreboot + Heads)" + + ## Firmware update + + [Build](/unified/novacustom/building-manual/#dasharo-coreboot--head) or + download Dasharo Heads firmware, and proceed with + the official [Heads update documentation](https://osresearch.net/Updating). diff --git a/docs/unified/novacustom/initial-deployment.md b/docs/unified/novacustom/initial-deployment.md index 9290a330b6..b7a1feb241 100644 --- a/docs/unified/novacustom/initial-deployment.md +++ b/docs/unified/novacustom/initial-deployment.md @@ -150,3 +150,9 @@ devices. In such case please follow the EC firmware update instructions for a specific board variant. + +## coreboot + Heads + +The supported method for initial deployment of the coreboot + Heads variant is +to follow [installing Dasharo](#installing-dasharo), and then +[transition from Dasharo UEFI to Heads variant](/unified/novacustom/firmware-transition#switching-from-dasharo-uefi-to-heads). diff --git a/docs/variants/novacustom_nv4x_adl/hardware-matrix.md b/docs/variants/novacustom_nv4x_adl/hardware-matrix.md index 87dfebe445..9f793f8071 100644 --- a/docs/variants/novacustom_nv4x_adl/hardware-matrix.md +++ b/docs/variants/novacustom_nv4x_adl/hardware-matrix.md @@ -66,3 +66,12 @@ for the NV41 platforms. | **KVM** | PiKVM based on Raspberry Pi 4 | [HCL]: https://docs.dasharo.com/unified/novacustom/hcl/#nv4x-12th-gen + +## coreboot + heads + +Generally, the same hardware configuration as for the +UEFI variant applies. + +A notable addition is usage of the +[Nitrokey 3A Mini](https://novacustom.com/product/nitrokey-3a-mini/) +USB device, which is required for Heads installation and usage. diff --git a/docs/variants/novacustom_nv4x_adl/heads.md b/docs/variants/novacustom_nv4x_adl/heads.md deleted file mode 100644 index f9e8d57bf3..0000000000 --- a/docs/variants/novacustom_nv4x_adl/heads.md +++ /dev/null @@ -1,208 +0,0 @@ -# Dasharo (coreboot + Heads) firmware variant - -For the NovaCustom NV4x 12th Gen, Heads-based variant of Dasharo firmware is -offered as a Technology Preview Release. - -Please consider supporting the project financially by purchasing the -[Dasharo Entry Subscription](https://novacustom.com/product/dasharo-entry-subscription/). -With this subscription, you get access to the -[Transition from Dasharo UEFI to Heads variant](#transition-from-dasharo-uefi-to-heads-variant) -feature in Dasharo Tools Suite and support from Dasharo directly via Matrix. -The subscription is not automatically renewed. - -Following Release Notes describe status of development of Dasharo (coreboot + -Heads) firmware for NovaCustom NV4x 12th Gen. - -## v0.9.0 - 2024-02-29 - -Test results for this release can be found -[here](https://docs.google.com/spreadsheets/d/1yWZ--zFPIsQhXZByf7nJIrasQYuRSf1yCi60lY_RGsQ/edit#gid=2042954457). - -### Changed - -- [This is a Dasharo Entry Subscription release](https://docs.dasharo.com/dev-proc/versioning/#dasharo-entry-subscription-releases) -- Heads Linux is used as a payload - -### Known issues - -- [Power button does not work in Qubes](https://github.com/Dasharo/dasharo-issues/issues/710) -- [Heads shuts down instead of rebooting](https://github.com/Dasharo/dasharo-issues/issues/711) -- [Existing Qubes installation is not found as bootable after transition back to EDK2](https://github.com/Dasharo/dasharo-issues/issues/713) -- [Builds are not fully reproducible](https://github.com/linuxboot/heads/issues/1616) - -### Binaries - -[sha256][novacustom_nv4x_adl_v0.9.0_heads.rom_hash]{.md-button} -[sha256.sig][novacustom_nv4x_adl_v0.9.0_heads.rom_sig]{.md-button} - -This is a Dasharo Entry Subscription Release. To obtain access to the pre-built -binaries you will have to -[become the Dasharo Entry Subscription subscriber](../../ways-you-can-help-us.md#become-a-dasharo-entry-subscription-subscriber). -You will get the access to all of the firmware updates for the duration of the -subscription via Dasharo Entry Subscription newsletter. - -To verify binary integrity with hash and signature please follow the -instructions in [Dasharo release signature verification](/guides/signature-verification) -using [this key](https://github.com/3mdeb/3mdeb-secpack/blob/master/customer-keys/novacustom/dasharo-release-0.9.x-for-novacustom-signing-key.asc) - -### SBOM (Software Bill of Materials) - -- [Dasharo heads fork based on v0.2.0 revision ccf49703](https://github.com/Dasharo/heads/tree/ccf49703) -- [Dasharo coreboot fork based on 4.21 revision 3a9aa3a4](https://github.com/Dasharo/coreboot/tree/3a9aa3a4) -- [Intel Management Engine based on v16.1.30.2307 revision d0b63476](https://github.com/Dasharo/dasharo-blobs/blob/d0b63476/novacustom/nv4x_adl/me.bin) -- [Intel Flash Descriptor based on v1.0 revision d0b63476](https://github.com/Dasharo/dasharo-blobs/blob/d0b63476/novacustom/nv4x_adl/descriptor.bin) -- [Intel Firmware Support Package based on ADL-P C.1.75.10 revision 481ea7cf](https://github.com/intel/FSP/tree/481ea7cf/AlderLakeFspBinPkg/Client/AlderLakeP) -- [Intel microcode based on ADL L0/R0 0x0000042c revision microcode-20230808](https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/tree/microcode-20230808/intel-ucode/06-9a-04) -- [Intel microcode based on RPL J0/Q0 0x00004119 revision microcode-20230808](https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/tree/microcode-20230808/intel-ucode/06-ba-02) - -## Hardware Configuration Matrix - -Generally, the same [hardware configuration](hardware-matrix.md) as for the -UEFI variant applies. - -A notable addition is usage of the -[Nitrokey 3A Mini](https://novacustom.com/product/nitrokey-3a-mini/) -USB device, which is required for Heads installation and usage. - -## Test Matrix - -Please refer to the [tests results spreadsheet](https://docs.google.com/spreadsheets/d/1yWZ--zFPIsQhXZByf7nJIrasQYuRSf1yCi60lY_RGsQ). - -## Building manual - -This section presents the crucial steps required to build the Dasharo Heads -firmware. For more information, you may also refer to the official -[Heads building documentation](https://osresearch.net/general-building/). - -### Requirements - -This guide was verified on Ubuntu 22.04. In practice, any Linux distribution -with [Docker](https://www.docker.com/) support should be enough to complete it. - -Make sure that you have following packages installed: - -- 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 - - ```bash - sudo apt -y install git - ``` - -### Building - -1. Clone Dasharo Heads repository: - - ```bash - git clone https://github.com/Dasharo/heads.git - ``` - -1. Navigate to the source code directory and checkout to the desired revision: - - ```bash - cd heads - git checkout novacustom_nv4x_adl_v0.9.0 - ``` - -1. Start the build inside the docker container: - - ```bash - docker run --rm -it -v $PWD:$PWD -w $PWD \ - 3mdeb/heads-docker:3.0.1 make BOARD=nitropad-nv41 - ``` - -This will produce a Dasharo binary placed in -`build/x86/nitropad-nv41/dasharo-nitropad-nv41-*.rom`. - -## Switching from Dasharo UEFI to Heads - -To change firmware branches from UEFI to Heads, because of how different the two -firmware types are, it's required to disable some security measures before -flashing. Follow the steps below to install Heads from an existing Dasharo UEFI -firmware installation: - -- Hold down the ++f2++ key and press the ++power++ button to enter the UEFI - Setup Menu -- Enter the `Device Manager` submenu and disable `Secure Boot` -- Enter the `Dasharo System Features` submenu -- In the `Dasharo Security Options` submenu, disable: - + SMM BIOS Write Protection - + BIOS boot medium lock -- In the `Intel Management Engine Options` submenu disable the Management Engine - -!!! tip - - For a more detailed guide on the UEFI Setup Menu options, check out the - [Dasharo menu documentation](https://docs.dasharo.com/dasharo-menu-docs/). - -- [Boot into Dasharo Tools Suite](https://docs.dasharo.com/dasharo-tools-suite/documentation/#running) -- Enter your DES subscription credentials -- Select `Update Dasharo firmware` to check for updates -- When asked to switch to Heads firmware, press `Y` -- Proceed with [DTS firmware update](https://docs.dasharo.com/dasharo-tools-suite/documentation/#firmware-update) - as usual - -When the update is finished, your laptop will shut down automatically. Power it -back on to boot into your new Heads installation! - -!!! warning "TOTP secrets warning" - - On the first boot, you will be shown a warning about TOTP secrets. This is - normal and expected on the first boot. Run `OEM Factory Reset / - Re-Ownership` to finish deploying Heads. - - Check out [Heads documentation](https://osresearch.net/Configuring-Keys/#oem-factory-resetre-ownership) - for a detailed factory reset guide. - -!!! note "Note for Qubes OS users" - - After installing Qubes while Heads is installed, you will need to select - `Reset TPM` in the Heads menu to finish the installation. - - From the main menu, enter `Options` -> `TPM/TOTP/HOTP Options` and select - `Reset the TPM`. - - Users upgrading to Heads while Qubes is already installed are not affected. - -## Switching from Dasharo Heads back to UEFI - -To revert back to UEFI, you will need to boot into DTS from a USB stick. - -- Follow the [Dasharo Tools Suite documentation](https://docs.dasharo.com/dasharo-tools-suite/documentation/#running) - to boot DTS from a USB stick -- In the DTS main menu, select `Update Dasharo firmware` to check for available - updates. -- When prompted to revert back to UEFI, press `Y` -- Proceed with [DTS firmware update](https://docs.dasharo.com/dasharo-tools-suite/documentation/#firmware-update) - as usual - -Once finished, your laptop will shut down automatically. Power it back on to -boot into your UEFI firmware. - -> When reverting to UEFI, it's not possible to restore EFI boot manager entries -> that were added before installing Heads. Therefore, you may need to re-create -> your boot entries manually, or find your boot loader using `Boot From File` -> option in the UEFI setup menu. - -## Logo customization - -To replace the logo, one must rebuild the firmware. Other methods are not -supported as of now. You would need to replace the -`branding/Dasharo/bootsplash.jpg` with your own, and proceed with the -[Building manual](#building-manual). - -## Initial deployment - -The supported method is to follow the -[initial deployment](/unified/novacustom/initial-deployment.md), and then the -[Transition from Dasharo UEFI to Heads variant](#switching-from-dasharo-uefi-to-heads). - -## Firmware update - -[Build](#building-manual) or download Dasharo Heads firmware, and proceed with -the official [Heads update documentation](https://osresearch.net/Updating). - -[newsletter]: https://newsletter.3mdeb.com/subscription/RJrTXDhWR -[novacustom_nv4x_adl_v0.9.0_heads.rom_hash]: https://dl.3mdeb.com/open-source-firmware/Dasharo/novacustom_nv4x_adl/heads/v0.9.0/novacustom_nv4x_adl_v0.9.0_heads.rom.sha256 -[novacustom_nv4x_adl_v0.9.0_heads.rom_sig]: https://dl.3mdeb.com/open-source-firmware/Dasharo/novacustom_nv4x_adl/heads/v0.9.0/novacustom_nv4x_adl_v0.9.0_heads.rom.sha256.sig diff --git a/docs/variants/novacustom_nv4x_adl/releases_heads.md b/docs/variants/novacustom_nv4x_adl/releases_heads.md new file mode 100644 index 0000000000..b8ef890a6f --- /dev/null +++ b/docs/variants/novacustom_nv4x_adl/releases_heads.md @@ -0,0 +1,49 @@ +# NovaCustom NV4x 12th Gen Dasharo (coreboot + heads) Release Notes + +Following Release Notes describe status of development of Dasharo (coreboot + +Heads) firmware for NovaCustom NV4x 12th Gen. + +## v0.9.0 - 2024-02-29 + +Test results for this release can be found +[here](https://docs.google.com/spreadsheets/d/1yWZ--zFPIsQhXZByf7nJIrasQYuRSf1yCi60lY_RGsQ/edit#gid=2042954457). + +### Changed + +- [This is a Dasharo Entry Subscription release](https://docs.dasharo.com/dev-proc/versioning/#dasharo-entry-subscription-releases) +- Heads Linux is used as a payload + +### Known issues + +- [Power button does not work in Qubes](https://github.com/Dasharo/dasharo-issues/issues/710) +- [Heads shuts down instead of rebooting](https://github.com/Dasharo/dasharo-issues/issues/711) +- [Existing Qubes installation is not found as bootable after transition back to EDK2](https://github.com/Dasharo/dasharo-issues/issues/713) +- [Builds are not fully reproducible](https://github.com/linuxboot/heads/issues/1616) + +### Binaries + +[sha256][novacustom_nv4x_adl_v0.9.0_heads.rom_hash]{.md-button} +[sha256.sig][novacustom_nv4x_adl_v0.9.0_heads.rom_sig]{.md-button} + +This is a Dasharo Entry Subscription Release. To obtain access to the pre-built +binaries you will have to +[become the Dasharo Entry Subscription subscriber](../../ways-you-can-help-us.md#become-a-dasharo-entry-subscription-subscriber). +You will get the access to all of the firmware updates for the duration of the +subscription via Dasharo Entry Subscription newsletter. + +To verify binary integrity with hash and signature please follow the +instructions in [Dasharo release signature verification](/guides/signature-verification) +using [this key](https://github.com/3mdeb/3mdeb-secpack/blob/master/customer-keys/novacustom/dasharo-release-0.9.x-for-novacustom-signing-key.asc) + +### SBOM (Software Bill of Materials) + +- [Dasharo heads fork based on v0.2.0 revision ccf49703](https://github.com/Dasharo/heads/tree/ccf49703) +- [Dasharo coreboot fork based on 4.21 revision 3a9aa3a4](https://github.com/Dasharo/coreboot/tree/3a9aa3a4) +- [Intel Management Engine based on v16.1.30.2307 revision d0b63476](https://github.com/Dasharo/dasharo-blobs/blob/d0b63476/novacustom/nv4x_adl/me.bin) +- [Intel Flash Descriptor based on v1.0 revision d0b63476](https://github.com/Dasharo/dasharo-blobs/blob/d0b63476/novacustom/nv4x_adl/descriptor.bin) +- [Intel Firmware Support Package based on ADL-P C.1.75.10 revision 481ea7cf](https://github.com/intel/FSP/tree/481ea7cf/AlderLakeFspBinPkg/Client/AlderLakeP) +- [Intel microcode based on ADL L0/R0 0x0000042c revision microcode-20230808](https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/tree/microcode-20230808/intel-ucode/06-9a-04) +- [Intel microcode based on RPL J0/Q0 0x00004119 revision microcode-20230808](https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/tree/microcode-20230808/intel-ucode/06-ba-02) + +[novacustom_nv4x_adl_v0.9.0_heads.rom_hash]: https://dl.3mdeb.com/open-source-firmware/Dasharo/novacustom_nv4x_adl/heads/v0.9.0/novacustom_nv4x_adl_v0.9.0_heads.rom.sha256 +[novacustom_nv4x_adl_v0.9.0_heads.rom_sig]: https://dl.3mdeb.com/open-source-firmware/Dasharo/novacustom_nv4x_adl/heads/v0.9.0/novacustom_nv4x_adl_v0.9.0_heads.rom.sha256.sig diff --git a/docs/variants/novacustom_nv4x_adl/test-matrix.md b/docs/variants/novacustom_nv4x_adl/test-matrix.md index 9966994e9a..13eacc593b 100644 --- a/docs/variants/novacustom_nv4x_adl/test-matrix.md +++ b/docs/variants/novacustom_nv4x_adl/test-matrix.md @@ -139,3 +139,7 @@ subjected from before the release of the new binary. [SMW]: ../../unified-test-documentation/dasharo-stability/C02-m2-wi-fi.md [SNV]: ../../unified-test-documentation/dasharo-stability/C03-nvme-detection.md [NET]: ../../unified-test-documentation/dasharo-stability/01-net-controller-after-coldboot-warmboot-reboot-suspend.md + +## coreboot + heads + +Please refer to the [tests results spreadsheet](https://docs.google.com/spreadsheets/d/1yWZ--zFPIsQhXZByf7nJIrasQYuRSf1yCi60lY_RGsQ). diff --git a/mkdocs.yml b/mkdocs.yml index df77eb930b..a2c273a483 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -142,8 +142,10 @@ nav: - 'Post-installation setup': unified/clevo/post-install.md - 'Features': unified/novacustom/features.md - 'Hardware Compatibility List': unified/novacustom/hcl.md + - 'Firmare transition': unified/novacustom/firmware-transition.md - 'NV4x 12th Gen': - 'Releases': variants/novacustom_nv4x_adl/releases.md + - 'Heads releases': variants/novacustom_nv4x_adl/releases_heads.md - 'Hardware Configuration Matrix': variants/novacustom_nv4x_adl/hardware-matrix.md - 'Test matrix': variants/novacustom_nv4x_adl/test-matrix.md - 'Openness score': variants/novacustom_nv4x_adl/openness-score.md From b504155bb04df0c57229f615eef08b3a53dbad36 Mon Sep 17 00:00:00 2001 From: Pawel Langowski Date: Fri, 19 Apr 2024 14:58:47 +0200 Subject: [PATCH 3/7] Remove variants/msi_z790(+ msi_z690)/heads and move the sections to other files Signed-off-by: Pawel Langowski --- docs/unified/msi/building-manual.md | 297 ++++++++++++++-------- docs/unified/msi/firmware-transition.md | 53 ++++ docs/unified/msi/firmware-update.md | 275 ++++++++++---------- docs/unified/msi/initial-deployment.md | 6 + docs/variants/msi_z690/hardware-matrix.md | 9 + docs/variants/msi_z690/heads.md | 204 --------------- docs/variants/msi_z690/releases_heads.md | 61 +++++ docs/variants/msi_z690/test-matrix.md | 4 + docs/variants/msi_z790/hardware-matrix.md | 9 + docs/variants/msi_z790/heads.md | 209 --------------- docs/variants/msi_z790/releases_heads.md | 60 +++++ docs/variants/msi_z790/test-matrix.md | 4 + mkdocs.yml | 6 +- 13 files changed, 546 insertions(+), 651 deletions(-) create mode 100644 docs/unified/msi/firmware-transition.md delete mode 100644 docs/variants/msi_z690/heads.md create mode 100644 docs/variants/msi_z690/releases_heads.md delete mode 100644 docs/variants/msi_z790/heads.md create mode 100644 docs/variants/msi_z790/releases_heads.md diff --git a/docs/unified/msi/building-manual.md b/docs/unified/msi/building-manual.md index 333af5c5d4..b400ba1c46 100644 --- a/docs/unified/msi/building-manual.md +++ b/docs/unified/msi/building-manual.md @@ -1,121 +1,216 @@ # Building manual -## Intro - -This documents describes the procedure for compiling Dasharo firmware -compatible with MSI PRO Z690-A and MSI PRO Z790-P. - -## Requirements - -* `Ubuntu 20.04/21.04/22.04` as a host OS was tested -* Internet connection -* Docker installed - - 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, wget, unzip installed - -```bash -sudo apt install git unzip wget -``` - -* UEFIExtract installed - - this tool is used in the `build.sh` script to extract CPU microcode from - the original MSI firmware - -```bash -sudo apt install wget -wget https://github.com/LongSoft/UEFITool/releases/download/A59/UEFIExtract_NE_A59_linux_x86_64.zip -unzip UEFIExtract_NE_A59_linux_x86_64.zip -sudo cp ./UEFIExtract /usr/local/bin -``` - -## Procedure - -Obtain Dasharo source code: - -=== "PRO Z690-A (WIFI) DDR4" - > Replace the `REVISION` with one of the: - > - > - `msi_ms7d25_vVERSION` tag for the given release `VERSION` - > (e.g. `msi_ms7d25_v1.1.3`), **RECOMMENDED** - > - `dasharo` branch for a development version with unreleased changes past - > most recent release version - > - `msi_ms7d25/release` branch for the release versions up to v1.1.2 - -=== "PRO Z690-A (WIFI)" - > Replace the `REVISION` with one of the: - > - > - `msi_ms7d25_vVERSION` tag for the given release `VERSION` - > (e.g. `msi_ms7d25_v1.1.3`), **RECOMMENDED** - > - `dasharo` branch for a development version with unreleased changes past - > most recent release version - > - `msi_ms7d25/release` branch for the release versions up to v1.1.2 - -=== "PRO Z790-P (WIFI) DDR4" - > Replace the `REVISION` with one of the: - > - > - `msi_ms7e06_vVERSION` tag for the given release `VERSION` - > (e.g. `msi_ms7e06_v0.9.1`), **RECOMMENDED** - > - `dasharo` branch for a development version with unreleased changes past - > most recent release version - > - `msi_ms7d25/release` branch for the release versions up to v0.9.0 - -=== "PRO Z790-P (WIFI)" - > Replace the `REVISION` with one of the: - > - > - `msi_ms7e06_vVERSION` tag for the given release `VERSION` - > (e.g. `msi_ms7e06_v0.9.1`), **RECOMMENDED** - > - `dasharo` branch for a development version with unreleased changes past - > most recent release version - > - `msi_ms7d25/release` branch for the release versions up to v0.9.0 - -```bash -git clone https://github.com/Dasharo/coreboot.git -b REVISION -cd coreboot -``` - -Start the build process: - -=== "PRO Z690-A (WIFI) DDR4" - For v1.1.1 and older: +=== "Dasharo (UEFI)" - ```bash - ./build.sh ddr4 - ``` + ## Intro - For v1.1.2 and newer: + This documents describes the procedure for compiling Dasharo firmware + compatible with MSI PRO Z690-A and MSI PRO Z790-P. - ```bash - ./build.sh z690a_ddr4 - ``` + ## Requirements - The resulting Dasharo firmware image will be placed at `$PWD/msi_ms7d25_VERSION_ddr4.rom`. - -=== "PRO Z690-A (WIFI)" - For v1.1.1 and older: + * `Ubuntu 20.04/21.04/22.04` as a host OS was tested + * Internet connection + * Docker installed + - 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, wget, unzip installed ```bash - ./build.sh ddr5 + sudo apt install git unzip wget ``` - For v1.1.2 and newer: + * UEFIExtract installed + - this tool is used in the `build.sh` script to extract CPU microcode from + the original MSI firmware ```bash - ./build.sh z690a_ddr5 + sudo apt install wget + wget https://github.com/LongSoft/UEFITool/releases/download/A59/UEFIExtract_NE_A59_linux_x86_64.zip + unzip UEFIExtract_NE_A59_linux_x86_64.zip + sudo cp ./UEFIExtract /usr/local/bin ``` - The resulting Dasharo firmware image will be placed at `$PWD/msi_ms7d25_VERSION_ddr5.rom`. + ## Procedure + + Obtain Dasharo source code: + + === "PRO Z690-A (WIFI) DDR4" + > Replace the `REVISION` with one of the: + > + > - `msi_ms7d25_vVERSION` tag for the given release `VERSION` + > (e.g. `msi_ms7d25_v1.1.3`), **RECOMMENDED** + > - `dasharo` branch for a development version with unreleased changes past + > most recent release version + > - `msi_ms7d25/release` branch for the release versions up to v1.1.2 + + === "PRO Z690-A (WIFI)" + > Replace the `REVISION` with one of the: + > + > - `msi_ms7d25_vVERSION` tag for the given release `VERSION` + > (e.g. `msi_ms7d25_v1.1.3`), **RECOMMENDED** + > - `dasharo` branch for a development version with unreleased changes past + > most recent release version + > - `msi_ms7d25/release` branch for the release versions up to v1.1.2 + + === "PRO Z790-P (WIFI) DDR4" + > Replace the `REVISION` with one of the: + > + > - `msi_ms7e06_vVERSION` tag for the given release `VERSION` + > (e.g. `msi_ms7e06_v0.9.1`), **RECOMMENDED** + > - `dasharo` branch for a development version with unreleased changes past + > most recent release version + > - `msi_ms7d25/release` branch for the release versions up to v0.9.0 + + === "PRO Z790-P (WIFI)" + > Replace the `REVISION` with one of the: + > + > - `msi_ms7e06_vVERSION` tag for the given release `VERSION` + > (e.g. `msi_ms7e06_v0.9.1`), **RECOMMENDED** + > - `dasharo` branch for a development version with unreleased changes past + > most recent release version + > - `msi_ms7d25/release` branch for the release versions up to v0.9.0 -=== "PRO Z790-P (WIFI) DDR4" ```bash - ./build.sh z790p_ddr4 + git clone https://github.com/Dasharo/coreboot.git -b REVISION + cd coreboot ``` - The resulting Dasharo firmware image will be placed at `$PWD/msi_ms7e06_VERSION_ddr4.rom`. + Start the build process: -=== "PRO Z790-P (WIFI)" - ```bash - ./build.sh z790p_ddr5 - ``` + === "PRO Z690-A (WIFI) DDR4" + For v1.1.1 and older: + + ```bash + ./build.sh ddr4 + ``` + + For v1.1.2 and newer: + + ```bash + ./build.sh z690a_ddr4 + ``` + + The resulting Dasharo firmware image will be placed at `$PWD/msi_ms7d25_VERSION_ddr4.rom`. + + === "PRO Z690-A (WIFI)" + For v1.1.1 and older: + + ```bash + ./build.sh ddr5 + ``` + + For v1.1.2 and newer: + + ```bash + ./build.sh z690a_ddr5 + ``` + + The resulting Dasharo firmware image will be placed at `$PWD/msi_ms7d25_VERSION_ddr5.rom`. + + === "PRO Z790-P (WIFI) DDR4" + ```bash + ./build.sh z790p_ddr4 + ``` + + The resulting Dasharo firmware image will be placed at `$PWD/msi_ms7e06_VERSION_ddr4.rom`. + + === "PRO Z790-P (WIFI)" + ```bash + ./build.sh z790p_ddr5 + ``` + + The resulting Dasharo firmware image will be placed at `$PWD/msi_ms7e06_VERSION_ddr4.rom`. + +=== "Dasharo (coreboot + Heads)" + + # Intro + + This section presents the crucial steps required to build the Dasharo Heads + firmware. For more information, you may also refer to the official + [Heads building documentation](https://osresearch.net/general-building/). + + ## Requirements + + This guide was verified on Ubuntu 22.04. In practice, any Linux distribution + with [Docker](https://www.docker.com/) support should be enough to complete it. + + Make sure that you have following packages installed: + + - 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 + + ```bash + sudo apt -y install git + ``` + + ## Building + + 1. Clone Dasharo Heads repository + + ```bash + git clone https://github.com/Dasharo/heads.git + ``` + + 2. Navigate to the source code directory and checkout to the desired revision: + + === "PRO Z690-A" + + ```bash + cd heads + git checkout msi_ms7d25_v0.9.0 + ``` + + === "PRO Z790-P" + + ```bash + cd heads + git checkout msi_ms7e06_v0.9.0 + ``` + + 3. Start docker container: + + ```bash + docker run --rm -it -v $PWD:$PWD -w $PWD \ + 3mdeb/heads-docker:3.0.0 /bin/bash + ``` + + 4. Inside of the container, start the build process: + + === "PRO Z690-A (WIFI) DDR4" + + ```bash + BOARD=msi_z690a_ddr4 make + ``` + + This will produce a Dasharo binary placed in + `build/x86/msi_z690a_ddr4/dasharo-msi_z690a_ddr4-*.rom`. + + === "PRO Z690-A (WIFI)" + + ```bash + BOARD=msi_z690a_ddr5 make + ``` + + This will produce a Dasharo binary placed in + `build/x86/msi_z690a_ddr5/dasharo-msi_z690a_ddr5-*.rom`. + + === "PRO Z790-P (WIFI) DDR4" + + ```bash + BOARD=msi_z790p_ddr4 make + ``` + + This will produce a Dasharo binary placed in + `build/x86/msi_z790p_ddr4/dasharo-msi_z790p_ddr4-*.rom`. + + === "PRO Z790-P (WIFI)" + + ```bash + BOARD=msi_z790p_ddr5 make + ``` - The resulting Dasharo firmware image will be placed at `$PWD/msi_ms7e06_VERSION_ddr4.rom`. + This will produce a Dasharo binary placed in + `build/x86/msi_z790p_ddr5/dasharo-msi_z790p_ddr5-*.rom`. diff --git a/docs/unified/msi/firmware-transition.md b/docs/unified/msi/firmware-transition.md new file mode 100644 index 0000000000..0d14784671 --- /dev/null +++ b/docs/unified/msi/firmware-transition.md @@ -0,0 +1,53 @@ +# Firmware transition + +## Introduction + +This document describes the process of transitioning from Dasharo UEFI to Heads +and the other way around. + +## Transition from Dasharo UEFI to Heads variant + +**Recommended** + +Please use [Dasharo Tools Suite](../../dasharo-tools-suite/overview.md) with +Heads subscription credentials to transition to Heads. + +**Manual** + +Use [FlashBIOS](../../unified/msi/recovery.md#using-msi-flashbios-button) +method (recommended) or flash with flashrom in OS. To use FlashBIOS we +recommend to switch back to MSI UEFI firmware (if you don't have the desktop +Dasharo Entry Subscription or not running Dasharo v1.1.3) and then use +FlashBIOS with heads binary. + +To transition to heads firmware with flashrom, whole binary has to be flashed: + +```bash +flashrom -p internal -w +``` + +!!! warning "ME has to be disabled to flash full file." + +## Transition from Dasharo Heads back to UEFI + +At the moment, Dasharo Tools Suite does not support switching from Heads back to +UEFI-based firmware. Use [FlashBIOS](../../unified/msi/recovery.md#using-msi-flashbios-button) +to restore a saved backup, stock, or Dasharo UEFI firmware. + +!!! warning "Warning for Qubes OS users" + + If you installed Qubes OS under Heads, it has been installed in legacy BIOS + boot mode and will not be bootable under UEFI. You will likely need to + install Qubes OS again. + + Users who installed Qubes OS *before* switching to Heads are not affected. + +## Logo customization + +Normally, the logo can be replaced using the +[Dasharo Configuration Utility](https://github.com/Dasharo/dcu?tab=readme-ov-file#dcu---dasharo-configuration-utility) +– a tool designed to modify Dasharo binary images. However, logo customization is +not supported as of now. To replace the logo, one must rebuild the firmware. You +would need to replace the `branding/Dasharo/bootsplash.jpg` with your own, and +proceed with the +[Building manual](/unified/novacustom/building-manual/#dasharo-coreboot--heads). diff --git a/docs/unified/msi/firmware-update.md b/docs/unified/msi/firmware-update.md index 57f079d12d..ec31d6e743 100644 --- a/docs/unified/msi/firmware-update.md +++ b/docs/unified/msi/firmware-update.md @@ -12,173 +12,180 @@ sudo dmidecode -t bios | grep Version Alternatively, it can be checked in the `BIOS Setup Menu`. -## Prerequisites +=== "Dasharo (UEFI)" -Depending on firmware version (1) there may be manual steps required to ensure that -the firmware can be updated. -{ .annotate } + ## Prerequisites -1. v0.9.0 for Z790-P and v1.1.2 for Z690-A introduced support for Firmware - Update Mode + Depending on firmware version (1) there may be manual steps required to ensure that + the firmware can be updated. + { .annotate } -### Firmware Update Mode + 1. v0.9.0 for Z790-P and v1.1.2 for Z690-A introduced support for Firmware + Update Mode -If the currently installed Dasharo version supports Firmware Update Mode, follow -the steps outlined in -[generic Firmware Update documentation](../../guides/firmware-update.md#firmware-update-mode). + ### Firmware Update Mode -### Manual + If the currently installed Dasharo version supports Firmware Update Mode, follow + the steps outlined in + [generic Firmware Update documentation](../../guides/firmware-update.md#firmware-update-mode). -Ensure that the firmware protections are disabled in -[Dasharo Security Options](../../dasharo-menu-docs/dasharo-system-features.md). -Both `BIOS boot medium lock` and `Enable SMM BIOS write protection` should -be unchecked. [UEFI Secure Boot](../../dasharo-menu-docs/device-manager.md#secure-boot-configuration) -must be disabled as well (uncheck `Attempt Secure Boot` if -`Current Secure Boot State` does not say `Disabled`). To apply changes you -will need to reboot. + ### Manual -Please use one of the following environments to perform Dasharo update: + Ensure that the firmware protections are disabled in + [Dasharo Security Options](../../dasharo-menu-docs/dasharo-system-features.md). + Both `BIOS boot medium lock` and `Enable SMM BIOS write protection` should + be unchecked. [UEFI Secure Boot](../../dasharo-menu-docs/device-manager.md#secure-boot-configuration) + must be disabled as well (uncheck `Attempt Secure Boot` if + `Current Secure Boot State` does not say `Disabled`). To apply changes you + will need to reboot. -* [Dasharo Tools Suite (DTS)](#dasharo-tools-suite) -* [Linux distribution of your choice](#linux-distribution-of-your-choice) + Please use one of the following environments to perform Dasharo update: -We recommend using DTS for updating firmware. + * [Dasharo Tools Suite (DTS)](#dasharo-tools-suite) + * [Linux distribution of your choice](#linux-distribution-of-your-choice) -### Dasharo Tools Suite + We recommend using DTS for updating firmware. -The DTS allows performing automatic firmware update process, which is the -recommended method. To update your firmware, follow below steps. + ### Dasharo Tools Suite -1. Boot [DTS using iPXE](../../dasharo-tools-suite/documentation.md#bootable-over-a-network) - on your platform. -2. Follow [firmware update](../../dasharo-tools-suite/documentation.md#firmware-update) - procedure described in DTS documentation. + The DTS allows performing automatic firmware update process, which is the + recommended method. To update your firmware, follow below steps. -### Linux distribution of your choice + 1. Boot [DTS using iPXE](../../dasharo-tools-suite/documentation.md#bootable-over-a-network) + on your platform. + 2. Follow [firmware update](../../dasharo-tools-suite/documentation.md#firmware-update) + procedure described in DTS documentation. -Linux distributions may not yet have the support for the newest chipsets in -flashrom installed via package manager so building the flashrom from source -may be inevitable. You may check if your flashrom supports the Z690 and Z790 -chipset by doing a dry run without firmware binary: + ### Linux distribution of your choice -```bash -sudo flashrom -p internal -``` + Linux distributions may not yet have the support for the newest chipsets in + flashrom installed via package manager so building the flashrom from source + may be inevitable. You may check if your flashrom supports the Z690 and Z790 + chipset by doing a dry run without firmware binary: -Example output of undetected chipset: - -```txt -flashrom v1.2 on Linux 5.19.0-32-generic (x86_64) -flashrom is free software, get the source code at https://flashrom.org - -Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns). -Cannot open file stream for /dev/mtd0 -No DMI table found. -WARNING: No chipset found. Flash detection will most likely fail. -======================================================================== -You may be running flashrom on an unknown laptop. We could not -detect this for sure because your vendor has not set up the SMBIOS -tables correctly. Some internal buses have been disabled for -safety reasons. You can enforce using all buses by adding - -p internal:laptop=this_is_not_a_laptop -to the command line, but please read the following warning if you -are not sure. - -Laptops, notebooks and netbooks are difficult to support and we -recommend to use the vendor flashing utility. The embedded controller -(EC) in these machines often interacts badly with flashing. -See the manpage and https://flashrom.org/Laptops for details. - -If flash is shared with the EC, erase is guaranteed to brick your laptop -and write may brick your laptop. -Read and probe may irritate your EC and cause fan failure, backlight -failure and sudden poweroff. -You have been warned. -======================================================================== -No EEPROM/flash device found. -Note: flashrom can never write if the flash chip isn't found automatically. -``` + ```bash + sudo flashrom -p internal + ``` -It means you cannot proceed with this flashrom version and you have to remove -it using your package manager. Then follow the procedure for building the right -flashrom is described in `Build flashrom` section in the -[Initial deployment documentation](./initial-deployment.md#initial-deployment-manually) -(note the procedure describes Ubuntu case only, your package manager and -package names to install may be slightly different). We recommend to use -[Dasharo Tools Suite](#dasharo-tools-suite). - -Example of good output: - -```txt -flashrom v1.2-1031-g6b2061b on Linux 5.19.0-32-generic (x86_64) -flashrom is free software, get the source code at https://flashrom.org - -Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns). -No DMI table found. -Found chipset "Intel Z690". -Enabling flash write... SPI Configuration is locked down. -FREG0: Flash Descriptor region (0x00000000-0x00000fff) is read-write. -FREG1: BIOS region (0x01000000-0x01ffffff) is read-write. -FREG2: Management Engine region (0x00001000-0x003d8fff) is read-write. -Enabling hardware sequencing because some important opcode is locked. -OK. -Found Programmer flash chip "Opaque flash chip" (32768 kB, Programmer-specific) on internal. -No operations were specified. -``` + Example output of undetected chipset: + + ```txt + flashrom v1.2 on Linux 5.19.0-32-generic (x86_64) + flashrom is free software, get the source code at https://flashrom.org + + Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns). + Cannot open file stream for /dev/mtd0 + No DMI table found. + WARNING: No chipset found. Flash detection will most likely fail. + ======================================================================== + You may be running flashrom on an unknown laptop. We could not + detect this for sure because your vendor has not set up the SMBIOS + tables correctly. Some internal buses have been disabled for + safety reasons. You can enforce using all buses by adding + -p internal:laptop=this_is_not_a_laptop + to the command line, but please read the following warning if you + are not sure. + + Laptops, notebooks and netbooks are difficult to support and we + recommend to use the vendor flashing utility. The embedded controller + (EC) in these machines often interacts badly with flashing. + See the manpage and https://flashrom.org/Laptops for details. + + If flash is shared with the EC, erase is guaranteed to brick your laptop + and write may brick your laptop. + Read and probe may irritate your EC and cause fan failure, backlight + failure and sudden poweroff. + You have been warned. + ======================================================================== + No EEPROM/flash device found. + Note: flashrom can never write if the flash chip isn't found automatically. + ``` -That means you are good to go. + It means you cannot proceed with this flashrom version and you have to remove + it using your package manager. Then follow the procedure for building the right + flashrom is described in `Build flashrom` section in the + [Initial deployment documentation](./initial-deployment.md#initial-deployment-manually) + (note the procedure describes Ubuntu case only, your package manager and + package names to install may be slightly different). We recommend to use + [Dasharo Tools Suite](#dasharo-tools-suite). + + Example of good output: + + ```txt + flashrom v1.2-1031-g6b2061b on Linux 5.19.0-32-generic (x86_64) + flashrom is free software, get the source code at https://flashrom.org + + Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns). + No DMI table found. + Found chipset "Intel Z690". + Enabling flash write... SPI Configuration is locked down. + FREG0: Flash Descriptor region (0x00000000-0x00000fff) is read-write. + FREG1: BIOS region (0x01000000-0x01ffffff) is read-write. + FREG2: Management Engine region (0x00001000-0x003d8fff) is read-write. + Enabling hardware sequencing because some important opcode is locked. + OK. + Found Programmer flash chip "Opaque flash chip" (32768 kB, Programmer-specific) on internal. + No operations were specified. + ``` -#### Migrating SMBIOS unique data (optional) + That means you are good to go. -Before flashing you may migrate your serial number and UUID as -described in [Initial deployment](./initial-deployment.md#migrating-smbios-unique-data). -Applicable to Dasharo v1.1.0 (PRO Z690-A) / v0.9.0 (PRO Z790-P) and later. + #### Migrating SMBIOS unique data (optional) -#### Flashing using flashrom + Before flashing you may migrate your serial number and UUID as + described in [Initial deployment](./initial-deployment.md#migrating-smbios-unique-data). + Applicable to Dasharo v1.1.0 (PRO Z690-A) / v0.9.0 (PRO Z790-P) and later. -=== "PRO Z690-A boards" + #### Flashing using flashrom - ##### Version v1.1.0 or newer + === "PRO Z690-A boards" - > Version v1.1.0 and v1.1.2 had to change the flashmap layout and requires - > usage of the [procedure below](#version-older-than-v110) when migrating from - > v1.0.0 or older. + ##### Version v1.1.0 or newer - Only the `RW_SECTION_A` and `RW_SECTION_B` partitions of the flash needs to be - updated. Flash it using the following command: + > Version v1.1.0 and v1.1.2 had to change the flashmap layout and requires + > usage of the [procedure below](#version-older-than-v110) when migrating from + > v1.0.0 or older. - ```bash - flashrom -p internal -w [path] --fmap -i RW_SECTION_A -i RW_SECTION_B - ``` + Only the `RW_SECTION_A` and `RW_SECTION_B` partitions of the flash needs to be + updated. Flash it using the following command: - > To flash newer firmware the command described in the [section below](#version-older-than-v110) - > might be also used. But remember, in that case, all Dasharo UEFI settings - > will be lost. Also, the memory training procedure will have to be carried out - > again. + ```bash + flashrom -p internal -w [path] --fmap -i RW_SECTION_A -i RW_SECTION_B + ``` - ##### Version older than v1.1.0 + > To flash newer firmware the command described in the [section below](#version-older-than-v110) + > might be also used. But remember, in that case, all Dasharo UEFI settings + > will be lost. Also, the memory training procedure will have to be carried out + > again. - In this case, the whole `bios` region must be updated. + ##### Version older than v1.1.0 - ```bash - flashrom -p internal -w [path] --ifd -i bios - ``` + In this case, the whole `bios` region must be updated. -=== "PRO Z790-P boards" + ```bash + flashrom -p internal -w [path] --ifd -i bios + ``` - There is only one version available for now. Please follow instructions - described in [Initial deployment](./initial-deployment.md) to deploy the - Dasharo. + === "PRO Z790-P boards" - If updating firmware using custom builds without changing the flashmap, - only the `RW_SECTION_A` and `RW_SECTION_B` partitions of the flash needs to be - updated. Flash it using the following command: + There is only one version available for now. Please follow instructions + described in [Initial deployment](./initial-deployment.md) to deploy the + Dasharo. - ```bash - flashrom -p internal -w [path] --fmap -i RW_SECTION_A -i RW_SECTION_B - ``` + If updating firmware using custom builds without changing the flashmap, + only the `RW_SECTION_A` and `RW_SECTION_B` partitions of the flash needs to be + updated. Flash it using the following command: + + ```bash + flashrom -p internal -w [path] --fmap -i RW_SECTION_A -i RW_SECTION_B + ``` + + #### Troubleshooting + + Possible errors are described in the + [Generic deployment problems with flashrom](../../osf-trivia-list/deployment.md#flashrom) -#### Troubleshooting +=== "Dasharo (coreboot + Heads)" -Possible errors are described in the -[Generic deployment problems with flashrom](../../osf-trivia-list/deployment.md#flashrom) + [Build](#building-manual) or download Dasharo Heads firmware, and proceed with + the official [Heads update documentation](https://osresearch.net/Updating). diff --git a/docs/unified/msi/initial-deployment.md b/docs/unified/msi/initial-deployment.md index 097806f13d..75e24e1824 100644 --- a/docs/unified/msi/initial-deployment.md +++ b/docs/unified/msi/initial-deployment.md @@ -275,3 +275,9 @@ sudo flashrom -p internal -w dump.rom --ifd -i bios NOTE: Dasharo version v0.1.0 will not have a network connection. Use a different USB storage or a USB to Ethernet/USB WiFi adapter to move the binary to the live system. + +## coreboot + Heads + +The supported method is to follow +[initial deployment](#initial-deployment), and then the +[Transition from Dasharo UEFI to Heads variant](/unified/msi/firmware-transition#transition-from-dasharo-uefi-to-heads-variant). diff --git a/docs/variants/msi_z690/hardware-matrix.md b/docs/variants/msi_z690/hardware-matrix.md index 22aea3fd54..1d52a5f53c 100644 --- a/docs/variants/msi_z690/hardware-matrix.md +++ b/docs/variants/msi_z690/hardware-matrix.md @@ -84,3 +84,12 @@ please check the [FAQ section](../../unified/msi/faq.md). | **Power Control** | Sonoff S20 EU type E | | **Remote Testing Environment** | RTE v1.1.0 | | **KVM** | PiKVM based on Raspberry Pi Zero 2w | + +## coreboot + Heads + +Generally, the same hardware configuration as for the +UEFI variant applies. + +A notable addition is usage of the +[Nitrokey 3A Mini](https://shop.nitrokey.com/shop/nk3am-nitrokey-3a-mini-149) +USB device, which is required for Heads installation and usage. diff --git a/docs/variants/msi_z690/heads.md b/docs/variants/msi_z690/heads.md deleted file mode 100644 index 50dc59a9b7..0000000000 --- a/docs/variants/msi_z690/heads.md +++ /dev/null @@ -1,204 +0,0 @@ -# Dasharo (coreboot + Heads) firmware variant - -Heads-based variant of Dasharo firmware compatible with MSI PRO Z690-A boards -is offered as a Technology Preview Release. - -Please consider to support the project financially by purchasing the -`Dasharo Heads Subscription for Desktop`. -With this subscription, you will get access to the -[Transition from Dasharo UEFI to Heads variant](#transition-from-dasharo-uefi-to-heads-variant) -feature in Dasharo Tools Suite and support from Dasharo directly via Matrix. -The subscription is not automatically renewed. - -## Releases - -Following Release Notes describe status of Dasharo (coreboot + Heads) firmware -development compatible with MSI PRO Z690-A boards. - -## v0.9.0 - 2024-03-21 - -Test results for this release can be found -[here](https://docs.google.com/spreadsheets/d/1yWZ--zFPIsQhXZByf7nJIrasQYuRSf1yCi60lY_RGsQ/edit#gid=5649308). - -### Added - -- [Dual TPM feature in coreboot. When ME is disabled, fTPM becomes inactive as well and chipset will route the TPM traffic to SPI bus. coreboot will now probe for all possible TPMs and initialize the one that is currently active.](https://github.com/Dasharo/dasharo-issues/issues/113) - -### Changed - -- [This is a Dasharo Entry Subscription release](https://docs.dasharo.com/dev-proc/versioning/#dasharo-entry-subscription-releases) -- Heads Linux is used as a payload -- [Updated Flash Descriptor to enlarge BIOS region; refer to SBOM section below](https://github.com/Dasharo/dasharo-blobs/tree/main/msi/ms7e06) -- ME hardcoded to be HAP disabled for heads builds. Discrete SPI TPM in JTPM1 - header is required to provide TPM functionality. - -### Known issues - -- [Cannot wake from suspend via RTC on QubesOS](https://github.com/Dasharo/dasharo-issues/issues/484) -- [Builds are not fully reproducible](https://github.com/linuxboot/heads/issues/1616) - -### Binaries - -[sha256][msi_ms7d25_v0.9.0_ddr4_heads.rom_hash]{.md-button} -[sha256.sig][msi_ms7d25_v0.9.0_ddr4_heads.rom_sig]{.md-button} - -[sha256][msi_ms7d25_v0.9.0_ddr5_heads.rom_hash]{.md-button} -[sha256.sig][msi_ms7d25_v0.9.0_ddr5_heads.rom_sig]{.md-button} - -This is a Dasharo Entry Subscription Release. To obtain access to the pre-built -binaries you will have to -[become the Dasharo Entry Subscription subscriber](../../ways-you-can-help-us.md#become-a-dasharo-entry-subscription-subscriber). -You will get the access to all of the firmware updates for the duration of the -subscription via Dasharo Entry Subscription newsletter. - -To verify binary integrity with hash and signature please follow the -instructions in [Dasharo release signature verification](/guides/signature-verification) -using [this key](https://raw.githubusercontent.com/3mdeb/3mdeb-secpack/master/dasharo/msi_ms7d25/dasharo-release-0.x-compatible-with-msi-ms-7d25-signing-key.asc) - -### SBOM (Software Bill of Materials) - -- [Dasharo heads fork based on v0.2.0 revision 13aa08ce](https://github.com/Dasharo/heads/tree/13aa08ce) -- [Dasharo coreboot fork based on 4.21 revision 38215f5a](https://github.com/Dasharo/coreboot/tree/38215f5a) -- [Intel Management Engine based on v16.1.30.2307 revision d0b63476](https://github.com/Dasharo/dasharo-blobs/blob/d0b63476/msi/ms7d25/me.bin) -- [Intel Flash Descriptor based on v1.2 revision d0b63476](https://github.com/Dasharo/dasharo-blobs/blob/d0b63476/msi/ms7d25/descriptor.bin) -- [Intel Firmware Support Package based on RPL-S C.0.BD.40 revision 481ea7cf](https://github.com/intel/FSP/tree/481ea7cf/RaptorLakeFspBinPkg/Client/RaptorLakeS) -- [Intel microcode based on ADL/RPL C0/H0 0x0000002e revision microcode-20230808](https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/tree/microcode-20230808/intel-ucode/06-97-05) -- [Intel microcode based on RPL B0 0x00000119 revision microcode-20230808](https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/tree/microcode-20230808/intel-ucode/06-b7-01) - -[newsletter]: https://newsletter.3mdeb.com/subscription/D7dQvGx6k -[msi_ms7d25_v0.9.0_ddr4_heads.rom_hash]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7d25/heads/v0.9.0/msi_ms7d25_v0.9.0_ddr4_heads.rom.sha256 -[msi_ms7d25_v0.9.0_ddr4_heads.rom_sig]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7d25/heads/v0.9.0/msi_ms7d25_v0.9.0_ddr4_heads.rom.sha256.sig -[msi_ms7d25_v0.9.0_ddr5_heads.rom_hash]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7d25/heads/v0.9.0/msi_ms7d25_v0.9.0_ddr5_heads.rom.sha256 -[msi_ms7d25_v0.9.0_ddr5_heads.rom_sig]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7d25/heads/v0.9.0/msi_ms7d25_v0.9.0_ddr5_heads.rom.sha256.sig - -## Hardware Configuration Matrix - -Generally, the same [hardware configuration](hardware-matrix.md) as for the -UEFI variant applies. - -A notable addition is usage of the -[Nitrokey 3A Mini](https://shop.nitrokey.com/shop/nk3am-nitrokey-3a-mini-149) -USB device, which is required for Heads installation and usage. - -## Test Matrix - -Please refer to the [tests results spreadsheet](https://docs.google.com/spreadsheets/d/1yWZ--zFPIsQhXZByf7nJIrasQYuRSf1yCi60lY_RGsQ/edit#gid=5649308). - -## Building manual - -This section presents the crucial steps required to build the Dasharo Heads -firmware. For more information, you may also refer to the official -[Heads building documentation](https://osresearch.net/general-building/). - -### Requirements - -This guide was verified on Ubuntu 22.04. In practice, any Linux distribution -with [Docker](https://www.docker.com/) support should be enough to complete it. - -Make sure that you have following packages installed: - -- 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 - - ```bash - sudo apt -y install git - ``` - -### Building - -1. Clone Dasharo Heads repository - - ```bash - git clone https://github.com/Dasharo/heads.git - ``` - -2. Navigate to the source code directory and checkout to the desired revision: - - ```bash - cd heads - git checkout msi_ms7d25_v0.9.0 - ``` - -3. Start docker container: - - ```bash - docker run --rm -it -v $PWD:$PWD -w $PWD \ - 3mdeb/heads-docker:3.0.0 /bin/bash - ``` - -4. Inside of the container, start the build process: - -=== "PRO Z690-A (WIFI) DDR4" - - ```bash - BOARD=msi_z690a_ddr4 make - ``` - - This will produce a Dasharo binary placed in - `build/x86/msi_z690a_ddr4/dasharo-msi_z690a_ddr4-*.rom`. - -=== "PRO Z690-A (WIFI)" - - ```bash - BOARD=msi_z690a_ddr5 make - ``` - - This will produce a Dasharo binary placed in - `build/x86/msi_z690a_ddr5/dasharo-msi_z690a_ddr5-*.rom`. - -## Transition from Dasharo UEFI to Heads variant - -**Recommended** - -Please use [Dasharo Tools Suite](../../dasharo-tools-suite/overview.md) with -Heads subscription credentials to transition to Heads. - -**Manual** - -Use [FlashBIOS](../../unified/msi/recovery.md#using-msi-flashbios-button) -method (recommended) or flash with flashrom in OS. To use FlashBIOS we -recommend to switch back to MSI UEFI firmware (if you don't have the desktop -Dasharo Entry Subscription or not running Dasharo v1.1.3) and then use -FlashBIOS with heads binary. - -To transition to heads firmware with flashrom, whole binary has to be flashed: - -```bash -flashrom -p internal -w -``` - -!!! warning "ME has to be disabled to flash full file." - -## Transition from Dasharo Heads back to UEFI - -At the moment, Dasharo Tools Suite does not support switching from Heads back to -UEFI-based firmware. Use [FlashBIOS](../../unified/msi/recovery.md#using-msi-flashbios-button) -to restore a saved backup, stock, or Dasharo UEFI firmware. - -!!! warning "Warning for Qubes OS users" - - If you installed Qubes OS under Heads, it has been installed in legacy BIOS - boot mode and will not be bootable under UEFI. You will likely need to - install Qubes OS again. - - Users who installed Qubes OS *before* switching to Heads are not affected. - -## Logo customization - -To replace the logo, one must rebuild the firmware. Other methods are not -supported as of now. You would need to replace the -`branding/Dasharo/bootsplash.jpg` in the heads repository with your own, and -proceed with the [Building manual](#building-manual). - -## Initial deployment - -The supported method is to follow the -[initial deployment](/unified/msi/initial-deployment.md), and then the -[Transition from Dasharo UEFI to Heads variant](#transition-from-dasharo-uefi-to-heads-variant). - -## Firmware update - -[Build](#building-manual) or download Dasharo Heads firmware, and proceed with -the official [Heads update documentation](https://osresearch.net/Updating). diff --git a/docs/variants/msi_z690/releases_heads.md b/docs/variants/msi_z690/releases_heads.md new file mode 100644 index 0000000000..b115b9b309 --- /dev/null +++ b/docs/variants/msi_z690/releases_heads.md @@ -0,0 +1,61 @@ + +# MSI PRO Z690-A (WIFI) (DDR4) Dasharo (coreboot + Heads) Release Notes + +Following Release Notes describe status of Dasharo (coreboot + Heads) firmware +development compatible with MSI PRO Z690-A boards. + +## v0.9.0 - 2024-03-21 + +Test results for this release can be found +[here](https://docs.google.com/spreadsheets/d/1yWZ--zFPIsQhXZByf7nJIrasQYuRSf1yCi60lY_RGsQ/edit#gid=5649308). + +### Added + +- [Dual TPM feature in coreboot. When ME is disabled, fTPM becomes inactive as well and chipset will route the TPM traffic to SPI bus. coreboot will now probe for all possible TPMs and initialize the one that is currently active.](https://github.com/Dasharo/dasharo-issues/issues/113) + +### Changed + +- [This is a Dasharo Entry Subscription release](https://docs.dasharo.com/dev-proc/versioning/#dasharo-entry-subscription-releases) +- Heads Linux is used as a payload +- [Updated Flash Descriptor to enlarge BIOS region; refer to SBOM section below](https://github.com/Dasharo/dasharo-blobs/tree/main/msi/ms7e06) +- ME hardcoded to be HAP disabled for heads builds. Discrete SPI TPM in JTPM1 + header is required to provide TPM functionality. + +### Known issues + +- [Cannot wake from suspend via RTC on QubesOS](https://github.com/Dasharo/dasharo-issues/issues/484) +- [Builds are not fully reproducible](https://github.com/linuxboot/heads/issues/1616) + +### Binaries + +[sha256][msi_ms7d25_v0.9.0_ddr4_heads.rom_hash]{.md-button} +[sha256.sig][msi_ms7d25_v0.9.0_ddr4_heads.rom_sig]{.md-button} + +[sha256][msi_ms7d25_v0.9.0_ddr5_heads.rom_hash]{.md-button} +[sha256.sig][msi_ms7d25_v0.9.0_ddr5_heads.rom_sig]{.md-button} + +This is a Dasharo Entry Subscription Release. To obtain access to the pre-built +binaries you will have to +[become the Dasharo Entry Subscription subscriber](../../ways-you-can-help-us.md#become-a-dasharo-entry-subscription-subscriber). +You will get the access to all of the firmware updates for the duration of the +subscription via Dasharo Entry Subscription newsletter. + +To verify binary integrity with hash and signature please follow the +instructions in [Dasharo release signature verification](/guides/signature-verification) +using [this key](https://raw.githubusercontent.com/3mdeb/3mdeb-secpack/master/dasharo/msi_ms7d25/dasharo-release-0.x-compatible-with-msi-ms-7d25-signing-key.asc) + +### SBOM (Software Bill of Materials) + +- [Dasharo heads fork based on v0.2.0 revision 13aa08ce](https://github.com/Dasharo/heads/tree/13aa08ce) +- [Dasharo coreboot fork based on 4.21 revision 38215f5a](https://github.com/Dasharo/coreboot/tree/38215f5a) +- [Intel Management Engine based on v16.1.30.2307 revision d0b63476](https://github.com/Dasharo/dasharo-blobs/blob/d0b63476/msi/ms7d25/me.bin) +- [Intel Flash Descriptor based on v1.2 revision d0b63476](https://github.com/Dasharo/dasharo-blobs/blob/d0b63476/msi/ms7d25/descriptor.bin) +- [Intel Firmware Support Package based on RPL-S C.0.BD.40 revision 481ea7cf](https://github.com/intel/FSP/tree/481ea7cf/RaptorLakeFspBinPkg/Client/RaptorLakeS) +- [Intel microcode based on ADL/RPL C0/H0 0x0000002e revision microcode-20230808](https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/tree/microcode-20230808/intel-ucode/06-97-05) +- [Intel microcode based on RPL B0 0x00000119 revision microcode-20230808](https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/tree/microcode-20230808/intel-ucode/06-b7-01) + +[newsletter]: https://newsletter.3mdeb.com/subscription/D7dQvGx6k +[msi_ms7d25_v0.9.0_ddr4_heads.rom_hash]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7d25/heads/v0.9.0/msi_ms7d25_v0.9.0_ddr4_heads.rom.sha256 +[msi_ms7d25_v0.9.0_ddr4_heads.rom_sig]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7d25/heads/v0.9.0/msi_ms7d25_v0.9.0_ddr4_heads.rom.sha256.sig +[msi_ms7d25_v0.9.0_ddr5_heads.rom_hash]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7d25/heads/v0.9.0/msi_ms7d25_v0.9.0_ddr5_heads.rom.sha256 +[msi_ms7d25_v0.9.0_ddr5_heads.rom_sig]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7d25/heads/v0.9.0/msi_ms7d25_v0.9.0_ddr5_heads.rom.sha256.sig diff --git a/docs/variants/msi_z690/test-matrix.md b/docs/variants/msi_z690/test-matrix.md index 1be335cffb..2485659706 100644 --- a/docs/variants/msi_z690/test-matrix.md +++ b/docs/variants/msi_z690/test-matrix.md @@ -93,3 +93,7 @@ tested platforms: `MSI PRO Z690-A WiFi DDR4` and `MSI PRO Z690-A DDR5`. | 1. | [coreboot bring up time measurement][CBMEM] | CBMEM | All | [CBMEM]: ../../unified-test-documentation/dasharo-performance/400-coreboot-boot-measure.md + +## coreboot + Heads + +Please refer to the [tests results spreadsheet](https://docs.google.com/spreadsheets/d/1yWZ--zFPIsQhXZByf7nJIrasQYuRSf1yCi60lY_RGsQ/edit#gid=5649308). diff --git a/docs/variants/msi_z790/hardware-matrix.md b/docs/variants/msi_z790/hardware-matrix.md index b423a41f4e..e3b04736e0 100644 --- a/docs/variants/msi_z790/hardware-matrix.md +++ b/docs/variants/msi_z790/hardware-matrix.md @@ -32,3 +32,12 @@ please check the [FAQ section](../../unified/msi/faq.md). | **Power Control** | Sonoff S20 EU type E | | **Remote Testing Environment** | RTE v1.1.0 | | **KVM** | PiKVM based on Raspberry Pi 4 | + +# coreboot + Heads + +Generally, the same [hardware configuration](hardware-matrix.md) as for the +UEFI variant applies. + +A notable addition is usage of the +[Nitrokey 3A Mini](https://shop.nitrokey.com/shop/nk3am-nitrokey-3a-mini-149) +USB device, which is required for Heads installation and usage. diff --git a/docs/variants/msi_z790/heads.md b/docs/variants/msi_z790/heads.md deleted file mode 100644 index 9ce7a54e85..0000000000 --- a/docs/variants/msi_z790/heads.md +++ /dev/null @@ -1,209 +0,0 @@ -# Dasharo (coreboot + Heads) firmware variant - -Heads-based variant of Dasharo firmware compatible with MSI PRO Z790-P boards -is offered as a Technology Preview Release. - -Please consider to support the project financially by purchasing the -`Dasharo Heads Subscription for Desktop`. -With this subscription, you will get access to the -[Transition from Dasharo UEFI to Heads variant](#transition-from-dasharo-uefi-to-heads-variant) -feature in Dasharo Tools Suite and support from Dasharo directly via Matrix. -The subscription is not automatically renewed. - -## Releases - -Following Release Notes describe status of Dasharo (coreboot + Heads) firmware -development compatible with MSI PRO Z790-P boards. - -## v0.9.0 - 2024-03-21 - -Test results for this release can be found -[here](https://docs.google.com/spreadsheets/d/1yWZ--zFPIsQhXZByf7nJIrasQYuRSf1yCi60lY_RGsQ/edit#gid=5649308). - -### Added - -- [Dual TPM feature in coreboot. When ME is disabled, fTPM becomes inactive as well and chipset will route the TPM traffic to SPI bus. coreboot will now probe for all possible TPMs and initialize the one that is currently active.](https://github.com/Dasharo/dasharo-issues/issues/113) - -### Changed - -- [This is a Dasharo Entry Subscription release](https://docs.dasharo.com/dev-proc/versioning/#dasharo-entry-subscription-releases) -- Heads Linux is used as a payload -- [Updated Flash Descriptor to enlarge BIOS region; refer to SBOM section below](https://github.com/Dasharo/dasharo-blobs/tree/main/msi/ms7e06) -- ME hardcoded to be HAP disabled for heads builds. Discrete SPI TPM in JTPM1 - header is required to provide TPM functionality. - -### Known issues - -- [Cannot wake from suspend via RTC on QubesOS](https://github.com/Dasharo/dasharo-issues/issues/484) -- [Builds are not fully reproducible](https://github.com/linuxboot/heads/issues/1616) - -### Binaries - -[sha256][msi_ms7e06_v0.9.0_ddr4_heads.rom_hash]{.md-button} -[sha256.sig][msi_ms7e06_v0.9.0_ddr4_heads.rom_sig]{.md-button} - -[sha256][msi_ms7e06_v0.9.0_ddr5_heads.rom_hash]{.md-button} -[sha256.sig][msi_ms7e06_v0.9.0_ddr5_heads.rom_sig]{.md-button} - -This is a Dasharo Entry Subscription Release. To obtain access to the pre-built -binaries you will have to -[become the Dasharo Entry Subscription subscriber](../../ways-you-can-help-us.md#become-a-dasharo-entry-subscription-subscriber). -You will get the access to all of the firmware updates for the duration of the -subscription via Dasharo Entry Subscription newsletter. - -To verify binary integrity with hash and signature please follow the -instructions in [Dasharo release signature verification](/guides/signature-verification) -using [this key](https://raw.githubusercontent.com/3mdeb/3mdeb-secpack/master/dasharo/msi_ms7e06/dasharo-release-0.x-compatible-with-msi-ms-7e06-signing-key.asc) - -### SBOM (Software Bill of Materials) - -- [Dasharo heads fork based on v0.2.0 revision 13aa08ce](https://github.com/Dasharo/heads/tree/13aa08ce) -- [Dasharo coreboot fork based on 4.21 revision 38215f5a](https://github.com/Dasharo/coreboot/tree/38215f5a) -- [Intel Management Engine based on v16.1.30.2307 revision d0b63476](https://github.com/Dasharo/dasharo-blobs/blob/d0b63476/msi/ms7e06/me.bin) -- [Intel Flash Descriptor based on v1.2 revision d0b63476](https://github.com/Dasharo/dasharo-blobs/blob/d0b63476/msi/ms7e06/descriptor.bin) -- [Intel Firmware Support Package based on RPL-S C.0.BD.40 revision 481ea7cf](https://github.com/intel/FSP/tree/481ea7cf/RaptorLakeFspBinPkg/Client/RaptorLakeS) -- [Intel microcode based on ADL/RPL C0/H0 0x0000002e revision microcode-20230808](https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/tree/microcode-20230808/intel-ucode/06-97-05) -- [Intel microcode based on RPL B0 0x00000119 revision microcode-20230808](https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/tree/microcode-20230808/intel-ucode/06-b7-01) - -[newsletter]: https://newsletter.3mdeb.com/subscription/D7dQvGx6k -[msi_ms7e06_v0.9.0_ddr4_heads.rom_hash]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7e06/heads/v0.9.0/msi_ms7e06_v0.9.0_ddr4_heads.rom.sha256 -[msi_ms7e06_v0.9.0_ddr4_heads.rom_sig]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7e06/heads/v0.9.0/msi_ms7e06_v0.9.0_ddr4_heads.rom.sha256.sig -[msi_ms7e06_v0.9.0_ddr5_heads.rom_hash]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7e06/heads/v0.9.0/msi_ms7e06_v0.9.0_ddr5_heads.rom.sha256 -[msi_ms7e06_v0.9.0_ddr5_heads.rom_sig]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7e06/heads/v0.9.0/msi_ms7e06_v0.9.0_ddr5_heads.rom.sha256.sig - -## Hardware Configuration Matrix - -Generally, the same [hardware configuration](hardware-matrix.md) as for the -UEFI variant applies. - -A notable addition is usage of the -[Nitrokey 3A Mini](https://shop.nitrokey.com/shop/nk3am-nitrokey-3a-mini-149) -USB device, which is required for Heads installation and usage. - -## Test Matrix - -Please refer to the [tests results spreadsheet](https://docs.google.com/spreadsheets/d/1yWZ--zFPIsQhXZByf7nJIrasQYuRSf1yCi60lY_RGsQ/edit#gid=5649308). - -## Building manual - -This section presents the crucial steps required to build the Dasharo Heads -firmware. For more information, you may also refer to the official -[Heads building documentation](https://osresearch.net/general-building/). - -### Requirements - -This guide was verified on Ubuntu 22.04. In practice, any Linux distribution -with [Docker](https://www.docker.com/) support should be enough to complete it. - -Make sure that you have following packages installed: - -- 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 - - ```bash - sudo apt -y install git - ``` - -### Building - -1. Clone Dasharo Heads repository - - ```bash - git clone https://github.com/Dasharo/heads.git - ``` - -2. Navigate to the source code directory and checkout to the desired revision: - - ```bash - cd heads - git checkout msi_ms7e06_v0.9.0 - ``` - -3. Start docker container: - - ```bash - docker run --rm -it -v $PWD:$PWD -w $PWD \ - 3mdeb/heads-docker:3.0.0 /bin/bash - ``` - -4. Inside of the container, start the build process: - -=== "PRO Z790-P (WIFI) DDR4" - - ```bash - BOARD=msi_z790p_ddr4 make - ``` - - This will produce a Dasharo binary placed in - `build/x86/msi_z790p_ddr4/dasharo-msi_z790p_ddr4-*.rom`. - -=== "PRO Z790-P (WIFI)" - - ```bash - BOARD=msi_z790p_ddr5 make - ``` - - This will produce a Dasharo binary placed in - `build/x86/msi_z790p_ddr5/dasharo-msi_z790p_ddr5-*.rom`. - -## Transition from Dasharo UEFI to Heads variant - -**Recommended** - -Please use [Dasharo Tools Suite](../../dasharo-tools-suite/overview.md) with -Heads subscription credentials to transition to Heads. - -**Manual** - -Use [FlashBIOS](../../unified/msi/recovery.md#using-msi-flashbios-button) -method (recommended) or flash with flashrom in OS. To use FlashBIOS we -recommend to switch back to MSI UEFI firmware (if you don't have the desktop -Dasharo Entry Subscription or not running Dasharo v0.9.1) and then use -FlashBIOS with heads binary. - -To transition to heads firmware with flashrom, whole binary has to be flashed: - -```bash -flashrom -p internal -w -``` - -!!! warning - - ME has to be disabled and descriptor unlocked to flash full file. MSI - firmware began to ship the platforms with ME and flash descriptor regions - read-only. Unlocking the descriptor is possible using Firmware Update Mode - on Dasharo v0.9.1. - -## Transition from Dasharo Heads back to UEFI - -At the moment, Dasharo Tools Suite does not support switching from Heads back to -UEFI-based firmware. Use [FlashBIOS](../../unified/msi/recovery.md#using-msi-flashbios-button) -to restore a saved backup, stock, or Dasharo UEFI firmware. - -!!! warning "Warning for Qubes OS users" - - If you installed Qubes OS under Heads, it has been installed in legacy BIOS - boot mode and will not be bootable under UEFI. You will likely need to - install Qubes OS again. - - Users who installed Qubes OS *before* switching to Heads are not affected. - -## Logo customization - -To replace the logo, one must rebuild the firmware. Other methods are not -supported as of now. You would need to replace the -`branding/Dasharo/bootsplash.jpg` in the heads repository with your own, and -proceed with the [Building manual](#building-manual). - -## Initial deployment - -The supported method is to follow the -[initial deployment](/unified/msi/initial-deployment.md), and then the -[Transition from Dasharo UEFI to Heads variant](#transition-from-dasharo-uefi-to-heads-variant). - -## Firmware update - -[Build](#building-manual) or download Dasharo Heads firmware, and proceed with -the official [Heads update documentation](https://osresearch.net/Updating). diff --git a/docs/variants/msi_z790/releases_heads.md b/docs/variants/msi_z790/releases_heads.md new file mode 100644 index 0000000000..c392270d3b --- /dev/null +++ b/docs/variants/msi_z790/releases_heads.md @@ -0,0 +1,60 @@ +# MSI PRO Z790-P (WIFI) (DDR4) Dasharo (coreboot + Heads) Release Notes + +Following Release Notes describe status of Dasharo (coreboot + Heads) firmware +development compatible with MSI PRO Z790-P boards. + +## v0.9.0 - 2024-03-21 + +Test results for this release can be found +[here](https://docs.google.com/spreadsheets/d/1yWZ--zFPIsQhXZByf7nJIrasQYuRSf1yCi60lY_RGsQ/edit#gid=5649308). + +### Added + +- [Dual TPM feature in coreboot. When ME is disabled, fTPM becomes inactive as well and chipset will route the TPM traffic to SPI bus. coreboot will now probe for all possible TPMs and initialize the one that is currently active.](https://github.com/Dasharo/dasharo-issues/issues/113) + +### Changed + +- [This is a Dasharo Entry Subscription release](https://docs.dasharo.com/dev-proc/versioning/#dasharo-entry-subscription-releases) +- Heads Linux is used as a payload +- [Updated Flash Descriptor to enlarge BIOS region; refer to SBOM section below](https://github.com/Dasharo/dasharo-blobs/tree/main/msi/ms7e06) +- ME hardcoded to be HAP disabled for heads builds. Discrete SPI TPM in JTPM1 + header is required to provide TPM functionality. + +### Known issues + +- [Cannot wake from suspend via RTC on QubesOS](https://github.com/Dasharo/dasharo-issues/issues/484) +- [Builds are not fully reproducible](https://github.com/linuxboot/heads/issues/1616) + +### Binaries + +[sha256][msi_ms7e06_v0.9.0_ddr4_heads.rom_hash]{.md-button} +[sha256.sig][msi_ms7e06_v0.9.0_ddr4_heads.rom_sig]{.md-button} + +[sha256][msi_ms7e06_v0.9.0_ddr5_heads.rom_hash]{.md-button} +[sha256.sig][msi_ms7e06_v0.9.0_ddr5_heads.rom_sig]{.md-button} + +This is a Dasharo Entry Subscription Release. To obtain access to the pre-built +binaries you will have to +[become the Dasharo Entry Subscription subscriber](../../ways-you-can-help-us.md#become-a-dasharo-entry-subscription-subscriber). +You will get the access to all of the firmware updates for the duration of the +subscription via Dasharo Entry Subscription newsletter. + +To verify binary integrity with hash and signature please follow the +instructions in [Dasharo release signature verification](/guides/signature-verification) +using [this key](https://raw.githubusercontent.com/3mdeb/3mdeb-secpack/master/dasharo/msi_ms7e06/dasharo-release-0.x-compatible-with-msi-ms-7e06-signing-key.asc) + +### SBOM (Software Bill of Materials) + +- [Dasharo heads fork based on v0.2.0 revision 13aa08ce](https://github.com/Dasharo/heads/tree/13aa08ce) +- [Dasharo coreboot fork based on 4.21 revision 38215f5a](https://github.com/Dasharo/coreboot/tree/38215f5a) +- [Intel Management Engine based on v16.1.30.2307 revision d0b63476](https://github.com/Dasharo/dasharo-blobs/blob/d0b63476/msi/ms7e06/me.bin) +- [Intel Flash Descriptor based on v1.2 revision d0b63476](https://github.com/Dasharo/dasharo-blobs/blob/d0b63476/msi/ms7e06/descriptor.bin) +- [Intel Firmware Support Package based on RPL-S C.0.BD.40 revision 481ea7cf](https://github.com/intel/FSP/tree/481ea7cf/RaptorLakeFspBinPkg/Client/RaptorLakeS) +- [Intel microcode based on ADL/RPL C0/H0 0x0000002e revision microcode-20230808](https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/tree/microcode-20230808/intel-ucode/06-97-05) +- [Intel microcode based on RPL B0 0x00000119 revision microcode-20230808](https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files/tree/microcode-20230808/intel-ucode/06-b7-01) + +[newsletter]: https://newsletter.3mdeb.com/subscription/D7dQvGx6k +[msi_ms7e06_v0.9.0_ddr4_heads.rom_hash]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7e06/heads/v0.9.0/msi_ms7e06_v0.9.0_ddr4_heads.rom.sha256 +[msi_ms7e06_v0.9.0_ddr4_heads.rom_sig]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7e06/heads/v0.9.0/msi_ms7e06_v0.9.0_ddr4_heads.rom.sha256.sig +[msi_ms7e06_v0.9.0_ddr5_heads.rom_hash]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7e06/heads/v0.9.0/msi_ms7e06_v0.9.0_ddr5_heads.rom.sha256 +[msi_ms7e06_v0.9.0_ddr5_heads.rom_sig]: https://dl.3mdeb.com/open-source-firmware/Dasharo/msi_ms7e06/heads/v0.9.0/msi_ms7e06_v0.9.0_ddr5_heads.rom.sha256.sig diff --git a/docs/variants/msi_z790/test-matrix.md b/docs/variants/msi_z790/test-matrix.md index 885229836e..ec9d966d3a 100644 --- a/docs/variants/msi_z790/test-matrix.md +++ b/docs/variants/msi_z790/test-matrix.md @@ -91,3 +91,7 @@ Note that the test scope is used during Dasharo Certification Procedure for for | 1. | [coreboot bring up time measurement][CBMEM] | CBMEM | All | [CBMEM]: ../../unified-test-documentation/dasharo-performance/400-coreboot-boot-measure.md + +## coreboot + Heads + +Please refer to the [tests results spreadsheet](https://docs.google.com/spreadsheets/d/1yWZ--zFPIsQhXZByf7nJIrasQYuRSf1yCi60lY_RGsQ/edit#gid=5649308). diff --git a/mkdocs.yml b/mkdocs.yml index a2c273a483..f093ef8613 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -149,7 +149,6 @@ nav: - 'Hardware Configuration Matrix': variants/novacustom_nv4x_adl/hardware-matrix.md - 'Test matrix': variants/novacustom_nv4x_adl/test-matrix.md - 'Openness score': variants/novacustom_nv4x_adl/openness-score.md - - 'Heads firmware variant': variants/novacustom_nv4x_adl/heads.md - 'NV4x 11th Gen': - 'Releases': variants/novacustom_nv4x_tgl/releases.md - 'Hardware Configuration Matrix': variants/novacustom_nv4x_tgl/hardware-matrix.md @@ -282,15 +281,16 @@ nav: - 'Development': unified/msi/development.md - 'FAQ': unified/msi/faq.md - 'Hardware Compatibility': unified/msi/hcl.md + - 'Firmware transition': unified/msi/firmware-transition.md - 'MSI PRO Z690-A': - 'Releases': variants/msi_z690/releases.md - - 'Heads firmware variant': variants/msi_z690/heads.md + - 'Heads releases': variants/msi_z690/releases_heads.md - 'Hardware Configuration Matrix': variants/msi_z690/hardware-matrix.md - 'Test matrix': variants/msi_z690/test-matrix.md - 'Openness score': variants/msi_z690/openness_score.md - 'MSI PRO Z790-P': - 'Releases': variants/msi_z790/releases.md - - 'Heads firmware variant': variants/msi_z790/heads.md + - 'Heads releases': variants/msi_z790/releases_heads.md - 'Hardware Configuration Matrix': variants/msi_z790/hardware-matrix.md - 'Test matrix': variants/msi_z790/test-matrix.md - 'Openness score': variants/msi_z790/openness_score.md From 220bfb2bdc95d27fd6fd0925a57330878c75442f Mon Sep 17 00:00:00 2001 From: Pawel Langowski Date: Mon, 27 May 2024 08:59:51 +0200 Subject: [PATCH 4/7] unified/novacustom/overview.md: Fix incorrect links Signed-off-by: Pawel Langowski --- docs/unified/novacustom/overview.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/unified/novacustom/overview.md b/docs/unified/novacustom/overview.md index 5d696a985c..b3975d7a04 100644 --- a/docs/unified/novacustom/overview.md +++ b/docs/unified/novacustom/overview.md @@ -15,8 +15,8 @@ Select your Dasharo firmware flavor:
- - [NS51 Series](https://configurelaptop.eu/product/ns51-series/) - - [NS70 Series](https://configurelaptop.eu/product/ns70-series/) + - [NS51 Series](https://novacustom.com/product/ns51-series/) + - [NS70 Series](https://novacustom.com/product/ns70-series/)
@@ -28,7 +28,7 @@ Select your Dasharo firmware flavor:
- - [NV41 Series](https://configurelaptop.eu/product/nv41-series/) + - [NV41 Series](https://novacustom.com/product/nv41-series/)
@@ -40,8 +40,8 @@ Select your Dasharo firmware flavor:
- - [NS51 Series](https://configurelaptop.eu/product/ns51-series/) - - [NS70 Series](https://configurelaptop.eu/product/ns70-series/) + - [NS51 Series](https://novacustom.com/product/ns51-series/) + - [NS70 Series](https://novacustom.com/product/ns70-series/)
@@ -95,7 +95,7 @@ Select your Dasharo firmware flavor:
- - [NV41 Series](https://configurelaptop.eu/nv41-series/) + - [NV41 Series](https://novacustom.com/nv41-series/)
From aab6d54f8523d97571bfab9e2ca46b941ba596c8 Mon Sep 17 00:00:00 2001 From: Pawel Langowski Date: Mon, 27 May 2024 09:19:37 +0200 Subject: [PATCH 5/7] docs/unified: Small refinements Signed-off-by: Pawel Langowski --- docs/unified/msi/firmware-transition.md | 7 ++++++- docs/unified/novacustom/building-manual.md | 4 ++-- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/unified/msi/firmware-transition.md b/docs/unified/msi/firmware-transition.md index 0d14784671..1143962bbf 100644 --- a/docs/unified/msi/firmware-transition.md +++ b/docs/unified/msi/firmware-transition.md @@ -26,7 +26,12 @@ To transition to heads firmware with flashrom, whole binary has to be flashed: flashrom -p internal -w ``` -!!! warning "ME has to be disabled to flash full file." +!!! warning + + ME has to be disabled and descriptor unlocked to flash full file. MSI + firmware began to ship the platforms with ME and flash descriptor regions + read-only. Unlocking the descriptor is possible using Firmware Update Mode + on Dasharo v0.9.1. ## Transition from Dasharo Heads back to UEFI diff --git a/docs/unified/novacustom/building-manual.md b/docs/unified/novacustom/building-manual.md index f8838b5c5c..eef547d48a 100644 --- a/docs/unified/novacustom/building-manual.md +++ b/docs/unified/novacustom/building-manual.md @@ -275,6 +275,6 @@ The Dasharo firmware can be flashed in following ways, depending on your situation: - - To flash Dasharo for the first time, refer to the +- To flash Dasharo for the first time, refer to the [initial deployment guide](initial-deployment.md). - - To update Dasharo, refer to the [firmware update guide](firmware-update.md). +- To update Dasharo, refer to the [firmware update guide](firmware-update.md). From 74c116072f84a49200359dc74e5bfec378db631f Mon Sep 17 00:00:00 2001 From: Pawel Langowski Date: Tue, 28 May 2024 15:32:47 +0200 Subject: [PATCH 6/7] docs/unified: Move logo customization info to docs/guides/logo-customization.md Signed-off-by: Pawel Langowski --- docs/guides/logo-customization.md | 27 ++++++++++++++----- docs/unified/msi/firmware-transition.md | 10 ------- .../unified/novacustom/firmware-transition.md | 10 ------- mkdocs.yml | 1 + 4 files changed, 21 insertions(+), 27 deletions(-) diff --git a/docs/guides/logo-customization.md b/docs/guides/logo-customization.md index 91200c935b..a811932961 100644 --- a/docs/guides/logo-customization.md +++ b/docs/guides/logo-customization.md @@ -4,13 +4,26 @@ The logo displayed at boot can be customized according to the client's preferences. For this, we have created a script that automates the process of -replacing the logo. +replacing the logo. It is part of the +[Dasharo Configuration Utility](https://github.com/Dasharo/dcu) - a tool +designed to configure Dasharo binary images. -## Procedure +=== "Dasharo" -Use the [Dasharo Configuration Utility](https://github.com/Dasharo/dcu#usage) -to put custom logo into a Dasharo coreboot image. + ## Procedure -```bash -./dcu logo -l -``` + Use the [Dasharo Configuration Utility](https://github.com/Dasharo/dcu#usage) + to put custom logo into a Dasharo coreboot image. + + ```bash + ./dcu logo -l + ``` + +=== "Dasharo (coreboot + Heads)" + + ## Procedure + + Logo customization is not supported as of now. To replace the logo, + you must rebuild the firmware. You need to replace the + `branding/Dasharo/bootsplash.jpg` with your own, and proceed with the + building manual. diff --git a/docs/unified/msi/firmware-transition.md b/docs/unified/msi/firmware-transition.md index 1143962bbf..a64b682c3c 100644 --- a/docs/unified/msi/firmware-transition.md +++ b/docs/unified/msi/firmware-transition.md @@ -46,13 +46,3 @@ to restore a saved backup, stock, or Dasharo UEFI firmware. install Qubes OS again. Users who installed Qubes OS *before* switching to Heads are not affected. - -## Logo customization - -Normally, the logo can be replaced using the -[Dasharo Configuration Utility](https://github.com/Dasharo/dcu?tab=readme-ov-file#dcu---dasharo-configuration-utility) -– a tool designed to modify Dasharo binary images. However, logo customization is -not supported as of now. To replace the logo, one must rebuild the firmware. You -would need to replace the `branding/Dasharo/bootsplash.jpg` with your own, and -proceed with the -[Building manual](/unified/novacustom/building-manual/#dasharo-coreboot--heads). diff --git a/docs/unified/novacustom/firmware-transition.md b/docs/unified/novacustom/firmware-transition.md index d333fa11f4..b5906a15e4 100644 --- a/docs/unified/novacustom/firmware-transition.md +++ b/docs/unified/novacustom/firmware-transition.md @@ -74,13 +74,3 @@ boot into your UEFI firmware. > that were added before installing Heads. Therefore, you may need to re-create > your boot entries manually, or find your boot loader using `Boot From File` > option in the UEFI setup menu. - -## Logo customization - -Normally, the logo can be replaced using the -[Dasharo Configuration Utility](https://github.com/Dasharo/dcu?tab=readme-ov-file#dcu---dasharo-configuration-utility) -– a tool designed to modify Dasharo binary images. However, logo customization is -not supported as of now. To replace the logo, one must rebuild the firmware. You -would need to replace the `branding/Dasharo/bootsplash.jpg` with your own, and -proceed with the -[Building manual](/unified/novacustom/building-manual/#dasharo-coreboot--heads). diff --git a/mkdocs.yml b/mkdocs.yml index f093ef8613..152f548145 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -327,6 +327,7 @@ nav: - 'Firmware signing for vboot': guides/vboot-signing.md - 'Dasharo Reviewers Guide': guides/dasharo-reviewers-guide.md - 'Verifying signatures': guides/signature-verification.md + - 'Boot logo replacement': guides/logo-customization.md - 'Development Process': - 'Source code structure': dev-proc/source-code-structure.md - 'Dasharo Product Guidelines: SMBIOS Information': dev-proc/smbios-rules.md From 330e32a333f639d93730191ab6734ad52ce864bf Mon Sep 17 00:00:00 2001 From: Pawel Langowski Date: Tue, 28 May 2024 15:50:52 +0200 Subject: [PATCH 7/7] docs/guides/logo-customization.md: Move Procedure header above tabs Signed-off-by: Pawel Langowski --- docs/guides/logo-customization.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/guides/logo-customization.md b/docs/guides/logo-customization.md index a811932961..359ad11ad8 100644 --- a/docs/guides/logo-customization.md +++ b/docs/guides/logo-customization.md @@ -8,9 +8,9 @@ replacing the logo. It is part of the [Dasharo Configuration Utility](https://github.com/Dasharo/dcu) - a tool designed to configure Dasharo binary images. -=== "Dasharo" +## Procedure - ## Procedure +=== "Dasharo" Use the [Dasharo Configuration Utility](https://github.com/Dasharo/dcu#usage) to put custom logo into a Dasharo coreboot image. @@ -21,8 +21,6 @@ designed to configure Dasharo binary images. === "Dasharo (coreboot + Heads)" - ## Procedure - Logo customization is not supported as of now. To replace the logo, you must rebuild the firmware. You need to replace the `branding/Dasharo/bootsplash.jpg` with your own, and proceed with the