mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-08-01 07:49:39 +00:00
doc: add acrn efi-stub user guide
Add user guide for ACRN EFI application for Secure Boot. Tracked-On: #6078 Signed-off-by: Toshiki Nishioka <toshiki.nishioka@intel.com>
This commit is contained in:
Nishioka, Toshiki
David Kinder
parent
8e7f1dbac8
commit
5fffcdcbd9
@ -74,6 +74,7 @@ Enable ACRN Features
|
||||
tutorials/acrn_on_qemu
|
||||
tutorials/using_grub
|
||||
tutorials/acrn-secure-boot-with-grub
|
||||
tutorials/acrn-secure-boot-with-efi-stub
|
||||
tutorials/pre-launched-rt
|
||||
tutorials/enable_ivshmem
|
||||
tutorials/enable_ptm
|
||||
|
||||
140
doc/tutorials/acrn-secure-boot-with-efi-stub.rst
Normal file
140
doc/tutorials/acrn-secure-boot-with-efi-stub.rst
Normal file
@ -0,0 +1,140 @@
|
||||
.. _how-to-enable-acrn-secure-boot-with-efi-stub:
|
||||
|
||||
Enable ACRN Secure Boot With EFI-Stub
|
||||
#####################################
|
||||
|
||||
Introduction
|
||||
************
|
||||
|
||||
``ACRN EFI-Stub`` is an EFI application to support booting ACRN Hypervisor on
|
||||
UEFI systems with Secure Boot. ACRN has supported
|
||||
:ref:`how-to-enable-acrn-secure-boot-with-grub`.
|
||||
It relies on the GRUB multiboot2 module by default. However, on certain platform
|
||||
the GRUB multiboot2 is intentionally disabled when Secure Boot is enabled due
|
||||
to the `CVE-2015-5281 <https://www.cvedetails.com/cve/CVE-2015-5281/>`_.
|
||||
|
||||
As an alternative booting method, ``ACRN EFI-Stub`` supports to boot ACRN HV on
|
||||
UEFI systems without using GRUB. Although it is based on the legacy EFI-Stub
|
||||
which was obsoleted in ACRN v2.3, the new EFI-Stub can boot ACRN HV in the direct
|
||||
mode rather than the former deprivileged mode.
|
||||
|
||||
In order to boot ACRN HV with the new EFI-Stub, you need to create a container blob
|
||||
which contains HV image and Service VM kernel image (and optionally pre-launched
|
||||
VM kernel image and ACPI table). That blob file is supposed to be stitched to the
|
||||
EFI-Stub to form single EFI application (``acrn.efi``). The overall boot flow is as below.
|
||||
|
||||
.. graphviz::
|
||||
|
||||
digraph G {
|
||||
rankdir=LR;
|
||||
bgcolor="transparent";
|
||||
UEFI -> "acrn.efi" ->
|
||||
"ACRN\nHypervisor" -> "pre-launched RTVM\nKernel";
|
||||
"ACRN\nHypervisor" -> "Service VM\nKernel";
|
||||
}
|
||||
|
||||
- UEFI firmware verifies ``acrn.efi``
|
||||
- ``acrn.efi`` unpacks ACRN Hypervisor image and VM Kernels from a stitched container blob
|
||||
- ``acrn.efi`` loads ACRN Hypervisor to memory
|
||||
- ``acrn.efi`` prepares MBI to store Service VM & pre-launched RTVM Kernel info
|
||||
- ``acrn.efi`` hands over control to ACRN Hypervisor with MBI
|
||||
- ACRN Hypervisor boots Service VM and pre-launched RTVM in parallel
|
||||
|
||||
As the container blob format, ``ACRN EFI-Stub`` uses the `Slim Bootloader Container
|
||||
Boot Image <https://slimbootloader.github.io/how-tos/create-container-boot-image.html>`_.
|
||||
|
||||
Verified Configurations
|
||||
***********************
|
||||
- ACRN Hypervisor Release Version 2.5
|
||||
- hybrid_rt scenario
|
||||
- TGL platform
|
||||
- CONFIG_MULTIBOOT2=y (as default)
|
||||
- CONFIG_RELOC=y (as default)
|
||||
|
||||
Building
|
||||
********
|
||||
|
||||
Build Dependencies
|
||||
==================
|
||||
|
||||
- Build Tools and Dependencies described in the :ref:`getting-started-building` guide
|
||||
- gnu-efi package
|
||||
- Service VM Kernel bzImage
|
||||
- pre-launched RTVM Kernel bzImage
|
||||
- `Slim Bootloader Container Tool <https://slimbootloader.github.io/how-tos/create-container-boot-image.html>`_
|
||||
|
||||
The Slim Bootloader Tools can be downloaded from its `GitHub project <https://github.com/slimbootloader/slimbootloader>`_.
|
||||
The verified version is the commit `9f146af <https://github.com/slimbootloader/slimbootloader/tree/9f146af>`_.
|
||||
You may use the `meta-acrn Yocto Project integration layer <https://github.com/intel/meta-acrn>`_ to build Service VM Kernel and pre-launched one.
|
||||
|
||||
Build EFI-Stub for TGL platform hybrid_rt
|
||||
=========================================
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ TOPDIR=`pwd`
|
||||
$ cd acrn-hypervisor
|
||||
$ make BOARD=tgl-rvp SCENARIO=hybrid_rt hypervisor
|
||||
$ make BOARD=tgl-rvp SCENARIO=hybrid_rt -C misc/efi-stub/ \
|
||||
HV_OBJDIR=`pwd`/build/hypervisor/ EFI_OBJDIR=`pwd`/build/hypervisor/misc/efi-stub `pwd`/build/hypervisor/misc/efi-stub/boot.efi
|
||||
|
||||
Create Container
|
||||
================
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ mkdir -p $TOPDIR/acrn-efi; cd $TOPDIR/acrn-efi
|
||||
$ echo > hv_cmdline.txt
|
||||
$ echo RT_bzImage > vm0_tag.txt
|
||||
$ echo Linux_bzImage > vm1_tag.txt
|
||||
$ echo ACPI_VM0 > acpi_vm0.txt
|
||||
|
||||
$ python3 GenContainer.py create -cl \
|
||||
CMDL:./hv_cmdline.txt \
|
||||
ACRN:$TOPDIR/acrn-hypervisor/build/hypervisor/acrn.32.out \
|
||||
MOD0:./vm0_tag.txt \
|
||||
MOD1:./vm0_kernel \
|
||||
MOD2:./vm1_tag.txt \
|
||||
MOD3:./vm1_kernel \
|
||||
MOD4:./acpi_vm0.txt \
|
||||
MOD5:$TOPDIR/acrn-hypervisor/build/hypervisor/acpi/ACPI_VM0.bin \
|
||||
-o sbl_os \
|
||||
-t MULTIBOOT \
|
||||
-a NONE
|
||||
|
||||
You may optionally put HV boot options in the hv_cmdline.txt. Since the current implementation does not accept empty files,
|
||||
it must contain at least one character even if you don't need additional boot options.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# Acceptable Examples
|
||||
$ echo > hv_cmdline.txt # end-of-line
|
||||
$ echo " " > hv_cmdline.txt # space + end-of-line
|
||||
|
||||
# Not Acceptable Example
|
||||
$ touch hv_cmdline.txt # empty file
|
||||
|
||||
The vm0_kernel is the Kernel bzImage of the pre-launched RTVM, and the vm1_kernel is the one of the Service VM in the above case.
|
||||
|
||||
Stitch Container to EFI-Stub
|
||||
============================
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ objcopy --add-section .hv=sbl_os --change-section-vma .hv=0x6e000 --set-section-flags .hv=alloc,data,contents,load \
|
||||
--section-alignment 0x1000 $TOPDIR/acrn-hypervisor/build/hypervisor/misc/efi-stub/boot.efi acrn.efi
|
||||
|
||||
Installing (w/o SB for testing)
|
||||
*******************************
|
||||
For example:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ sudo mkdir -p /boot/EFI/BOOT/
|
||||
$ sudo cp acrn.efi /boot/EFI/BOOT/
|
||||
$ sudo efibootmgr -c -l "\EFI\BOOT\acrn.efi" -d /dev/nvme0n1 -p 1 -L "ACRN Hypervisor"
|
||||
$ sudo reboot
|
||||
|
||||
Signing
|
||||
*******
|
||||
See the page :ref:`how-to-enable-acrn-secure-boot-with-grub` for how to sign your ``acrn.efi`` file.
|
||||
Loading…
Reference in New Issue
Block a user