1.. _how-to-enable-acrn-secure-boot-with-efi-stub:
2
3Enable ACRN Secure Boot With EFI-Stub
4#####################################
5
6Introduction
7************
8
9``ACRN EFI-Stub`` is an EFI application to support booting ACRN Hypervisor on
10UEFI systems with Secure Boot. ACRN has supported
11:ref:`how-to-enable-acrn-secure-boot-with-grub`.
12It relies on the GRUB multiboot2 module by default. However, on certain platform
13the GRUB multiboot2 is intentionally disabled when Secure Boot is enabled due
14to the `CVE-2015-5281 <https://www.cvedetails.com/cve/CVE-2015-5281/>`_.
15
16As an alternative booting method, ``ACRN EFI-Stub`` supports to boot ACRN HV on
17UEFI systems without using GRUB. Although it is based on the legacy EFI-Stub
18which was obsoleted in ACRN v2.3, the new EFI-Stub can boot ACRN HV in the direct
19mode rather than the former deprivileged mode.
20
21In order to boot ACRN HV with the new EFI-Stub, you need to create a container blob
22which contains HV image and Service VM kernel image (and optionally pre-launched
23VM kernel image and ACPI table). That blob file is stitched to the
24EFI-Stub to form a single EFI application (``acrn.efi``). The overall boot flow is as below.
25
26.. graphviz::
27
28   digraph G {
29      rankdir=LR;
30      bgcolor="transparent";
31      UEFI -> "acrn.efi" ->
32      "ACRN\nHypervisor" -> "pre-launched RTVM\nKernel";
33      "ACRN\nHypervisor" -> "Service VM\nKernel";
34   }
35
36- UEFI firmware verifies ``acrn.efi``
37- ``acrn.efi`` unpacks ACRN Hypervisor image and VM Kernels from a stitched container blob
38- ``acrn.efi`` loads ACRN Hypervisor to memory
39- ``acrn.efi`` prepares MBI to store Service VM & pre-launched RTVM Kernel info
40- ``acrn.efi`` hands over control to ACRN Hypervisor with MBI
41- ACRN Hypervisor boots Service VM and pre-launched RTVM in parallel
42
43As the container blob format, ``ACRN EFI-Stub`` uses the `Slim Bootloader Container
44Boot Image <https://slimbootloader.github.io/how-tos/create-container-boot-image.html>`_.
45
46Verified Configurations
47***********************
48- ACRN Hypervisor Release Version 2.5
49- hybrid_rt scenario
50- TGL platform
51- CONFIG_MULTIBOOT2=y (as default)
52- CONFIG_RELOC=y (as default)
53
54Building
55********
56
57Build Dependencies
58==================
59
60- Build Tools and Dependencies described in the :ref:`gsg` guide
61- ``gnu-efi`` package
62- Service VM Kernel ``bzImage``
63- pre-launched RTVM Kernel ``bzImage``
64- `Slim Bootloader Container Tool <https://slimbootloader.github.io/how-tos/create-container-boot-image.html>`_
65
66The Slim Bootloader Tools can be downloaded from its `GitHub project <https://github.com/slimbootloader/slimbootloader>`_.
67The verified version is the commit `9f146af <https://github.com/slimbootloader/slimbootloader/tree/9f146af>`_.
68You may use the `meta-acrn Yocto Project integration layer
69<https://github.com/intel/meta-acrn>`_ to build Service VM Kernel and
70pre-launched VM.
71
72Build EFI-Stub for TGL hybrid_rt
73======================================
74
75.. code-block:: none
76
77   $ TOPDIR=`pwd`
78   $ cd acrn-hypervisor
79   $ make BOARD=tgl-rvp SCENARIO=hybrid_rt hypervisor
80   $ make BOARD=tgl-rvp SCENARIO=hybrid_rt -C misc/efi-stub/ \
81     HV_OBJDIR=`pwd`/build/hypervisor/ \
82     EFI_OBJDIR=`pwd`/build/hypervisor/misc/efi-stub `pwd`/build/hypervisor/misc/efi-stub/boot.efi
83
84Create Container
85================
86
87.. code-block:: none
88
89   $ mkdir -p $TOPDIR/acrn-efi; cd $TOPDIR/acrn-efi
90   $ echo > hv_cmdline.txt
91   $ echo RT_bzImage    > vm0_tag.txt
92   $ echo Linux_bzImage > vm1_tag.txt
93   $ echo ACPI_VM0      > acpi_vm0.txt
94
95   $ python3 GenContainer.py create -cl \
96     CMDL:./hv_cmdline.txt \
97     ACRN:$TOPDIR/acrn-hypervisor/build/hypervisor/acrn.32.out \
98     MOD0:./vm0_tag.txt  \
99     MOD1:./vm0_kernel   \
100     MOD2:./vm1_tag.txt  \
101     MOD3:./vm1_kernel   \
102     MOD4:./acpi_vm0.txt \
103     MOD5:$TOPDIR/acrn-hypervisor/build/hypervisor/acpi/ACPI_VM0.bin \
104     -o sbl_os    \
105     -t MULTIBOOT \
106     -a NONE
107
108You may optionally put HV boot options in the ``hv_cmdline.txt`` file. This file
109must contain at least one character even if you don't need additional boot options.
110
111.. code-block:: none
112
113   # Acceptable Examples
114   $ echo     > hv_cmdline.txt    # end-of-line
115   $ echo " " > hv_cmdline.txt    # space + end-of-line
116
117   # Not Acceptable Example
118   $ touch hv_cmdline.txt         # empty file
119
120The ``vm0_kernel`` is the Kernel ``bzImage`` of the pre-launched RTVM, and the
121``vm1_kernel`` is the image of the Service VM in the above case.
122
123Stitch Container to EFI-Stub
124============================
125
126.. code-block:: none
127
128   $ objcopy --add-section .hv=sbl_os --change-section-vma .hv=0x6e000 \
129     --set-section-flags .hv=alloc,data,contents,load \
130     --section-alignment 0x1000 $TOPDIR/acrn-hypervisor/build/hypervisor/misc/efi-stub/boot.efi acrn.efi
131
132Installing (without SB for testing)
133***********************************
134For example:
135
136.. code-block:: none
137
138   $ sudo mkdir -p /boot/EFI/BOOT/
139   $ sudo cp acrn.efi /boot/EFI/BOOT/
140   $ sudo efibootmgr -c -l "\EFI\BOOT\acrn.efi" -d /dev/nvme0n1 -p 1 -L "ACRN Hypervisor"
141   $ sudo reboot
142
143Signing
144*******
145See :ref:`how-to-enable-acrn-secure-boot-with-grub` for how to sign your ``acrn.efi`` file.
146
147