Merge pull request #678 from Dasharo/qemu_v0.1.0

variants/qemu_q35/releases.md: v0.1.0 scope

docs/variants/overview.md

@@ -3,6 +3,12 @@
 Following is up to date list of hardware platforms supported by Dasharo
 open-source firmware distribution.
 
+## Emulation
+
+* Following emulation targets are supported under Dasharo Community Support:
+
+    - [QEMU Q35](qemu_q35/overview.md)
+
 ## Network appliance
 
 * Following network appliances are supported under Dasharo Support Package:

docs/variants/qemu_q35/building-manual.md

@@ -1,69 +1,157 @@
-# Dasharo (UEFI) v0.1.0 for QEMU Q35 - Building Manual
+# Building manual
 
-Follow below steps to create the "Dasharo (UEFI) OVMF image for QEMU Q35" from EDK2:
+## Intro
+
+This documents describes the procedure for compiling Dasharo firmware
+for QEMU Q35.
 
 ## Requirements
 
-- Docker
-    + follow [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/)
-    + follow [Post-installation steps for Linux](https://docs.docker.com/engine/install/linux-postinstall/)
+* `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
+```
 
 ## Procedure
 
-Easiest way to build OVMF for QEMU Q35 is to use coreboot Docker image.
-As some dependencies maybe missing in given local instance.
+Obtain Dasharo source code:
+
+> Replace the `REVISION` with one of the:
+>
+> * `qemu_q35_vVERSION` (e.g. `qemu_q35_v0.1.0`) for the given release
+> * `qemu_q35_vVERSION-rcN` (e.g. `qemu_q35_v0.1.0-rc1`) for the given release
+>   candidate
+
+Clone Dasharo EDK II fork:
+
+```bash
+git clone https://github.com/Dasharo/edk2.git -b REVISION
+```
+
+Change directory:
+
+```bash
+cd edk2
+```
+
+Update the submodules in order get latest dependencies.
+
+```bash
+git submodule update --init --checkout --recursive
+```
+
+Change directory:
+
+```bash
+cd ..
+```
+
+Clone Dasharo EDK II Platforms fork:
+
+```bash
+git clone https://github.com/Dasharo/edk2-platforms.git -b v0.9.0
+```
+
+Clone iPXE:
+
+```bash
+git clone https://git.ipxe.org/ipxe.git
+```
+
+### Build iPXE
 
-Obtain the docker image:
+Change directory:
 
 ```bash
-docker pull coreboot/coreboot-sdk:2021-09-23_b0d87f753c
+cd ipxe
 ```
 
-Clone official Dasharo EDK2 repository to your docker instance,
-with git or downloading the source code from github.
+Checkout:
 
 ```bash
-git clone https://github.com/Dasharo/edk2.git
+git checkout 77b07ea4fdc259d7253c6f9df2beda6e6c7a9d85
 ```
 
+> NOTE: This commit was chosen by chainloading netboot.xyz 10x. There was zero
+> failures, where other commits lead to even 50% timeuts.
+
+#### Enabled Dasharo script
+
+```bash
+sed -i 's|//#define\s*IMAGE_SCRIPT.*|#define IMAGE_SCRIPT|' "src/config/general.h"
+```
+
+Get the script:
+
+```bash
+wget https://raw.githubusercontent.com/Dasharo/dasharo-blobs/main/dasharo/dasharo.ipxe
+```
+
+#### Enabled HTTPS
+
+```bash
+sed -i 's|.*DOWNLOAD_PROTO_HTTPS|#define DOWNLOAD_PROTO_HTTPS|g'  "src/config/general.h"
+```
+
+#### Compile
+
 Start the instance of the docker image under the Dasharo/edk2 repository:
 
 ```bash
-sudo docker run --rm -it -v $PWD:/home/coreboot/coreboot \
-    -w /home/coreboot/coreboot coreboot/coreboot-sdk:2021-09-23_b0d87f753c \
+docker run --rm -it -v $PWD/../edk2:/home/coreboot/edk2 \
+    -v $PWD/../edk2-platforms:/home/coreboot/edk2-platforms \
+    -v $PWD:/home/coreboot/ipxe \
+    -w /home/coreboot/ipxe coreboot/coreboot-sdk:2021-09-23_b0d87f753c \
     /bin/bash
 ```
 
-Follow below instructions, to prepare your environment for building OVMF
-image.
+Export cross compiler prefix:
 
-- Setup the environment variables with the following command
+```bash
+export CROSS_COMPILE="x86_64-elf-"
+```
+
+Compile:
 
 ```bash
-make -C BaseTools
-source edksetup.sh
+make -C src bin-x86_64-efi-sb/ipxe.efi EMBED=$PWD/dasharo.ipxe BUILD_ID_CMD="echo 0x1234567890" \
+    EXTRA_CFLAGS="-Wno-address-of-packed-member  -m64  -fuse-ld=bfd \
+    -Wl,--build-id=none -fno-delete-null-pointer-checks -Wlogical-op -march=nocona \
+    -malign-data=abi -mcmodel=large -mno-red-zone -fno-pic"
+```
+
+#### Build EDK II
+
+Change directory:
+
+```bash
+cd ../edk2
 ```
 
-- Update the submodules in order get latest dependencies.
+Setup the environment variables with the following command
 
 ```bash
-git submodule update --init --checkout
+source edksetup.sh
 ```
 
-- Clone the edk2-platforms repository for additional packages
+Compile EDK II base tools:
 
 ```bash
-git clone https://github.com/Dasharo/edk2-platforms.git && \
-cd edk2-platforms && \
-git checkout 3323ed481d35096fb6a7eae7b49f35eff00f86cf && \
-cd -
+make -C BaseTools
 ```
 
-- Update the PACKAGES_PATH variable
+Update the PACKAGES_PATH variable:
 
 ```bash
-export EDK2_PLATFORMS_PATH="$WORKSPACE/edk2-platforms"
+export EDK2_PLATFORMS_PATH="$HOME/edk2-platforms"
 export PACKAGES_PATH="$WORKSPACE:\
+$HOME/ipxe/src/bin-x86_64-efi-sb/:\
 $EDK2_PLATFORMS_PATH/Platform/Intel:\
 $EDK2_PLATFORMS_PATH/Silicon/Intel:\
 $EDK2_PLATFORMS_PATH/Features/Intel:\
@@ -75,38 +163,40 @@ $EDK2_PLATFORMS_PATH/Features/Intel/SystemInformation:\
 $EDK2_PLATFORMS_PATH/Features/Intel/UserInterface"
 ```
 
-## Building the firmware image
-
 To build the image simply invoke the following command
 
 ```bash
 build -a IA32 -a X64 -t GCC5 -b RELEASE -p OvmfPkg/OvmfPkgX64.dsc
 ```
 
-You can also enable additional options, for example CSM with by adding
-`-D CSM_ENABLE`:
+Once the build is completed you should see output as follows:
 
-```bash
-build -a IA32 -a X64 -t GCC5 -b RELEASE -p OvmfPkg/OvmfPkgX64.dsc -D CSM_ENABLE
-```
+```text
+GUID cross reference file can be found at /home/coreboot/edk2/Build/OvmfX64/RELEASE_GCC5/FV/Guid.xref
 
-Once the build is completed, the OVMF firmware image can be found below given
-path:
+FV Space Information
+SECFV [5%Full] 212992 total, 11568 used, 201424 free
+PEIFV [15%Full] 917504 total, 139640 used, 777864 free
+DXEFV [46%Full] 12582912 total, 5849680 used, 6733232 free
+FVMAIN_COMPACT [41%Full] 3440640 total, 1430512 used, 2010128 free
 
-```bash
-edk2/Build/Ovmfx64/RELEASE_GCC5/FV/OVMF_CODE.fd
-edk2/Build/Ovmfx64/RELEASE_GCC5/FV/OVMF_VARS.fd
+- Done -
+  Build end time: 21:52:36, Oct.22 2023
+  Build total time: 00:01:41
 ```
 
-For debug build use:
+The Dasharo firmware image can be found below given path:
 
 ```bash
-build -a IA32 -a X64 -t GCC5 -b DEBUG -p OvmfPkg/OvmfPkgX64.dsc
+/home/coreboot/edk2/Build/OvmfX64/RELEASE_GCC5/FV/OVMF_CODE.fd
+/home/coreboot/edk2/Build/OvmfX64/RELEASE_GCC5/FV/OVMF_VARS.fd
 ```
 
-Then the resulting files will be placed in:
+## Initial Deployment
 
-```bash
-edk2/Build/Ovmfx64/DEBUG_GCC5/FV/OVMF_CODE.fd
-edk2/Build/Ovmfx64/DEBUG_GCC5/FV/OVMF_VARS.fd
-```
+Now you can proceed with initial deployment scenario according to you needs:
+
+* [Dasharo validation](https://github.com/Dasharo/open-source-firmware-validation#qemu-workflow)
+  if you want to use binaries for validation purposes
+* [Dasharo development](development.md) if you want to use binaries in
+  development environment

docs/variants/qemu_q35/firmware-update.md

@@ -1,6 +1,6 @@
 # Firmware Update
 
-The update process of Dasharo OVMF firmware on QEMU Q35 does not need any
+The update process of Dasharo (UEFI) firmware on QEMU Q35 does not need any
 special actions. QEMU Q35 is an emulated platform, not real hardware.
 
 Updating the Dasharo OVMF firmware is as simple as invoking a QEMU command

docs/variants/qemu_q35/initial-deployment.md

@@ -1,9 +1,9 @@
 # Initial Deployment
 
-Initial deployment of Dasharo OVMF firmware on QEMU Q35 does not need any
+Initial deployment of Dasharo (UEFI) firmware on QEMU Q35 does not need any
 special actions. QEMU Q35 is an emulated platform, not real hardware.
 
-Running the Dasharo OVMF is as simple as invoking a QEMU command:
+Running the Dasharo (UEFI) is as simple as invoking a QEMU command:
 
 ```bash
 qemu-system-x86_64 -machine q35,smm=on \
@@ -13,3 +13,11 @@ qemu-system-x86_64 -machine q35,smm=on \
 	-debugcon file:debug.log -global isa-debugcon.iobase=0x402 \
 	-global ICH9-LPC.disable_s3=1
 ```
+
+If you use system without graphical output you may face following issues:
+
+```text
+gtk initialization failed
+```
+
+In such case add `-nographic` at the end of your command.

docs/variants/qemu_q35/recovery.md

@@ -1,6 +1,6 @@
 # Recovery
 
-The recovery process of Dasharo OVMF firmware on QEMU Q35 does not need any
+The recovery process of Dasharo (UEFI) firmware on QEMU Q35 does not need any
 special actions. QEMU Q35 is an emulated platform, not real hardware, so it
 doesn't brick itself.
 

docs/variants/qemu_q35/releases.md

@@ -3,15 +3,51 @@
 Following Release Notes describe status of Open Source Firmware development for
 QEMU Q35 (Emulator).
 
-## v0.1.0 - 2023-01-20
+## v0.1.0 - 2023-12-06
+
+Tests reports and logs can be found
+[here](https://dl.3mdeb.com/open-source-firmware/Dasharo/protectli_vault_cml/v1.1.0/).
 
 ### Added
 
-- Enabled TPM Support.
-- Secure Boot Support for Q35 machine.
-- Option to reset Secure Boot keys to defaults.
-- Dasharo System Features.
-- Dasharo setup password.
-- OPAL disk password support.
-- SATA disk password support.
-- SMM Feature enabled.
+Following features can be fully used:
+- Configurable boot order
+- Configurable boot options
+- [Custom boot menu keys](https://docs.dasharo.com/unified-test-documentation/dasharo-compatibility/303-custom-boot-menu-key/)
+- [UEFI shell](https://docs.dasharo.com/unified-test-documentation/dasharo-compatibility/30P-uefi-shell/)
+- [UEFI Secure Boot](https://docs.dasharo.com/unified-test-documentation/dasharo-security/206-secure-boot/)
+- [TPM Support](https://docs.dasharo.com/unified-test-documentation/dasharo-security/200-tpm-support/)
+- [Dasharo setup password](https://docs.dasharo.com/unified-test-documentation/dasharo-security/20R-uefi-setup-password/)
+- [Serial Port Configuration menu](https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#serial-port-configuration)
+- [iPXE network boot](https://docs.dasharo.com/unified-test-documentation/dasharo-compatibility/315-network-boot/)
+- [ESP partition scanning in look for grubx64.efi or shimx64.efi or Windows bootmgr](https://github.com/Dasharo/dasharo-issues/issues/94)
+
+Following features are visible in setup menu and can be used for testing the menus,
+but have no actual backend hooked up:
+- [PS/2 Controller enable/disable option](https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#chipset-configuration)
+- [Watchdog configuration menu](https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#chipset-configuration)
+- [Early boot DMA protection menu option](https://docs.dasharo.com/unified-test-documentation/dasharo-security/20L-early-boot-dma-protection/)
+- [Intel ME disable support and menu options](https://docs.dasharo.com/unified-test-documentation/dasharo-security/20F-me-neuter/)
+- [SED/OPAL disk password support](https://docs.dasharo.com/unified-test-documentation/dasharo-security/208-opal-disk-password-support/)
+- [SATA disk password support](https://docs.dasharo.com/dasharo-menu-docs/device-manager/#hdd-security-configuration)
+- SMM BIOS Write Protection support and enable/disable option
+- [USB stack and mass storage enable/disable option](https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#usb-configuration)
+- [Firmware Update Mode feature](https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#dasharo-security-options)
+- [One of the two fan profiles can now be selected in Setup Menu](https://docs.dasharo.com/unified/novacustom/fan-profiles/)
+- [Setup menu option for switching between S0ix and S3 suspend mode](https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#power-management-options)
+- [Wi-Fi / Bluetooth module disable option in setup menu](https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#dasharo-security-options)
+- [Built-in webcam disable option in setup menu](https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#dasharo-security-options)
+- [Battery threshold options in setup menu](https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#power-management-options)
+- [PCIe Configuration menu](https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#pcipcie-configuration)
+- [Memory configuration menu](https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#memory-configuration)
+  [Power state after power fail option](https://docs.dasharo.com/dasharo-menu-docs/dasharo-system-features/#power-management-options)
+
+### Binaries
+
+Binaries can be found in
+[GitHub release](https://github.com/Dasharo/edk2/releases/tag/qemu_q35_v0.1.0).
+
+### SBOM
+
+- [Dasharo EDKII fork based on dd7523b5b1 revision 11746340](https://github.com/Dasharo/edk2/tree/11746340)
+- [iPXE revision 77b07ea4](https://github.com/ipxe/ipxe/tree/77b07ea4)