Skip to content

Commit

Permalink
Merge pull request #804 from Dasharo/novacustom-changes
Browse files Browse the repository at this point in the history 
Novacustom + MSI changes
  • Loading branch information
@artur-rs
artur-rs authored Jun 3, 2024
2 parents 2f64e1b + 330e32a commit 34cfc5a
Show file tree
Hide file tree
Showing 23 changed files with 964 additions and 1,062 deletions.
23 changes: 17 additions & 6 deletions docs/guides/logo-customization.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
297 changes: 196 additions & 101 deletions docs/unified/msi/building-manual.md
View file
Original file line number Diff line number Diff line change
@@ -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`.
48 changes: 48 additions & 0 deletions docs/unified/msi/firmware-transition.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit 34cfc5a

Please sign in to comment.