Merge pull request #804 from Dasharo/novacustom-changes

Novacustom + MSI changes

docs/guides/logo-customization.md

@@ -4,13 +4,24 @@
 
 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
 
-Use the [Dasharo Configuration Utility](https://github.com/Dasharo/dcu#usage)
-to put custom logo into a Dasharo coreboot image.
+=== "Dasharo"
 
-```bash
-./dcu logo <dasharo_image> -l <logo_file>
-```
+    Use the [Dasharo Configuration Utility](https://github.com/Dasharo/dcu#usage)
+    to put custom logo into a Dasharo coreboot image.
+
+    ```bash
+    ./dcu logo <dasharo_image> -l <logo_file>
+    ```
+
+=== "Dasharo (coreboot + Heads)"
+
+    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.

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`.

docs/unified/msi/firmware-transition.md

@@ -0,0 +1,48 @@
+# 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 <heads_fw_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
+
+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.