1# UEFI Boot 2 3Cloud Hypervisor supports UEFI boot through the utilization of the EDK II based UEFI firmware. 4 5## Building UEFI Firmware 6 7To avoid any unnecessary issues, it is recommended to use Ubuntu 18.04 and its default toolset. Any other compatible Linux distribution is otherwise suitable, however it is suggested to use a temporary Docker container with Ubuntu 18.04 for a quick build on an existing Linux machine. 8 9The commands below will compile an OVMF firmware suitable for Cloud Hypervisor. 10 11```shell 12sudo apt-get update 13sudo apt-get install uuid-dev nasm iasl build-essential python3-distutils git 14 15git clone https://github.com/cloud-hypervisor/edk2 -b ch 16cd edk2 17. edksetup.sh 18git submodule update --init 19 20echo "ACTIVE_PLATFORM=OvmfPkg/OvmfCh.dsc" >> Conf/target.txt 21echo "TARGET_ARCH=X64" >> Conf/target.txt 22echo "TOOL_CHAIN_TAG=GCC5" >> Conf/target.txt 23 24make -C ./BaseTools 25build 26``` 27 28After the successful build, the resulting firmware binaries are available under `Build/OvmfCh/DEBUG_GCC5/FV` underneath the edk2 checkout. 29 30## Using OVMF Binaries 31 32Any UEFI capable image can be booted using the Cloud Hypervisor specific firmware. Windows guests under Cloud Hypervisor only support UEFI boot, therefore OVMF is mandatory there. 33 34To make Cloud Hypervisor use UEFI boot, pass the `OVMF.fd` file path as an argument to the `--kernel` option. The firmware file will be opened in read only mode. 35 36The same firmware can be used with Cloud Hypervisor or with QEMU. This is particularly useful if using QEMU for the preparation phase. 37 38## Building UEFI Firmware with Compatibility Support Module (CSM) 39 40CSM is a module that allows to boot legacy operating systems using the OVMF firmware. OVMF can embed a CSM build of SeaBIOS. To build the SeaBIOS with CSM support, add `CONFIG_CSM=y` to `.config` before the build. The outcome `out/Csm16.bin` is to be moved into `OvmfPkg/Csm/Csm16/Csm16.bin` before OVMF is built. Then, the OVMF build will have to be passed the `-D CSM_ENABLE` option in order to generate a legacy aware UEFI firmware. At the current stage, all the necessary patches are included in the Cloud Hypervisor specific [SeaBIOS branch](https://github.com/cloud-hypervisor/seabios/tree/ch). Taking into account the previous instructions, the modified command sequence to compile an OVMF binary with CSM support is the following one: 41 42```shell 43sudo apt-get update 44sudo apt-get install uuid-dev nasm iasl build-essential python3-distutils git libncurses-dev 45 46git clone https://github.com/cloud-hypervisor/seabios -b ch 47cd seabios 48make menuconfig 49# Enable `CONFIG_CSM` and `CONFIG_QEMU_HARDWARE` 50# Please make sure `python` is in your path 51make CONFIG_CSM=y CONFIG_QEMU_HARDWARE=y 52cd .. 53 54git clone https://github.com/cloud-hypervisor/edk2 -b ch 55cd edk2 56. edksetup.sh 57git submodule update --init --recursive 58cp ../seabios/out/Csm16.bin OvmfPkg/Csm/Csm16/ 59 60echo "ACTIVE_PLATFORM=OvmfPkg/OvmfCh.dsc" >> Conf/target.txt 61echo "TARGET_ARCH=X64" >> Conf/target.txt 62echo "TOOL_CHAIN_TAG=GCC5" >> Conf/target.txt 63 64make -C ./BaseTools 65build -DCSM_ENABLE 66 67``` 68 69Please note, that the CSM support has currently only been tested with Linux guests. There are no plans to provide legacy support for other OSes (e.g. Windows). 70 71# Links 72 73- [OVMF wiki](https://github.com/tianocore/tianocore.github.io/wiki/OVMF) 74- [Cloud Hypervisor specific tree](https://github.com/cloud-hypervisor/edk2/tree/ch) 75- [Redhat OVMF Status Report](https://access.redhat.com/sites/default/files/attachments/ovmf-whtepaper-031815.pdf) 76- [SeaBIOS Build Overview](https://www.seabios.org/Build_overview#Build_as_a_UEFI_Compatibility_Support_Module_.28CSM.29) 77