mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-06-23 05:57:33 +00:00
doc: add using grub tutorial
The GRUB could be used to boot ACRN hypervisor in direct boot mode. Signed-off-by: Victor Sun <victor.sun@intel.com>
This commit is contained in:
Victor Sun
David Kinder
parent
137f7d67e7
commit
5119fa0673
@ -360,6 +360,7 @@ Boot Sequence
|
||||
|
||||
.. _systemd-boot: https://www.freedesktop.org/software/systemd/man/systemd-boot.html
|
||||
.. _grub: https://www.gnu.org/software/grub/manual/grub/
|
||||
.. _Slim Bootloader: https://www.intel.com/content/www/us/en/design/products-and-solutions/technologies/slim-bootloader/overview.html
|
||||
|
||||
ACRN supports two kinds of boots: **De-privilege boot mode** and **Direct
|
||||
boot mode**.
|
||||
@ -397,23 +398,10 @@ bootloader used by the Operating System (OS).
|
||||
|
||||
* In the case of Clear Linux, the EFI bootloader is `systemd-boot`_ and the Linux
|
||||
kernel command-line parameters are defined in the ``.conf`` files.
|
||||
* Another popular EFI bootloader used by Linux distributions is `grub`_.
|
||||
Distributions like Ubuntu/Debian, Fedora/CentOS use `grub`_.
|
||||
|
||||
.. note::
|
||||
|
||||
The `Slim Bootloader
|
||||
<https://www.intel.com/content/www/us/en/design/products-and-solutions/technologies/slim-bootloader/overview.html>`__
|
||||
is an alternative boot firmware that can be used to boot ACRN. The `Boot
|
||||
ACRN Hyervisor
|
||||
<https://slimbootloader.github.io/how-tos/boot-acrn.html>`_ tutorial
|
||||
provides more information on how to use SBL with ACRN.
|
||||
|
||||
.. note::
|
||||
|
||||
A virtual `Slim Bootloader
|
||||
<https://www.intel.com/content/www/us/en/design/products-and-solutions/technologies/slim-bootloader/overview.html>`__,
|
||||
called ``vSBL``, can also be used to start User VMs. The
|
||||
A virtual `Slim Bootloader`_ called ``vSBL``, can also be used to start User VMs. The
|
||||
:ref:`acrn-dm_parameters` provides more information on how to boot a
|
||||
User VM using ``vSBL``. Note that in this case, the kernel command-line
|
||||
parameters are defined by the combination of the ``cmdline.txt`` passed
|
||||
@ -423,6 +411,12 @@ bootloader used by the Operating System (OS).
|
||||
Direct boot mode
|
||||
================
|
||||
|
||||
The ACRN hypervisor could be boot from a third-party bootloader directly and we
|
||||
called this **Direct boot mode**. The most popular bootloader is `grub`_, it is
|
||||
also widely used by Linux distributions.
|
||||
|
||||
:ref:`using_grub` has a introduction on how to boot ACRN hypervisor with GRUB.
|
||||
|
||||
In :numref:`boot-flow-2`, we show the **Direct boot mode** sequence:
|
||||
|
||||
.. graphviz:: images/boot-flow-2.dot
|
||||
@ -442,7 +436,16 @@ The Boot process proceeds as follows:
|
||||
#. The virtual bootloader starts the User-side verified boot process.
|
||||
|
||||
In this boot mode, the boot options are defined via the ``VM{x}_CONFIG_OS_BOOTARGS``
|
||||
macro in the source code (replace ``{x}`` with the VM number).
|
||||
macro in the source code (replace ``{x}`` with the VM number) by default. But they
|
||||
could be overridden by GRUB menu also. Please check :ref:`using_grub` for details.
|
||||
|
||||
.. note::
|
||||
|
||||
`Slim Bootloader`_ is an alternative boot firmware that can be used to
|
||||
boot ACRN with **Direct boot mode**. The `Boot ACRN Hyervisor
|
||||
<https://slimbootloader.github.io/how-tos/boot-acrn.html>`_ tutorial
|
||||
provides more information on how to use SBL with ACRN.
|
||||
|
||||
|
||||
ACRN Hypervisor Architecture
|
||||
****************************
|
||||
|
||||
@ -21,6 +21,7 @@ Follow these getting started guides to give ACRN a try:
|
||||
|
||||
reference/hardware
|
||||
getting-started/building-from-source
|
||||
tutorials/using_grub
|
||||
getting-started/rt_industry_ubuntu
|
||||
tutorials/using_hybrid_mode_on_nuc
|
||||
tutorials/using_partition_mode_on_nuc
|
||||
|
||||
173
doc/tutorials/using_grub.rst
Normal file
173
doc/tutorials/using_grub.rst
Normal file
@ -0,0 +1,173 @@
|
||||
.. _using_grub:
|
||||
|
||||
Getting Started Guide for Using GRUB
|
||||
####################################
|
||||
`GRUB <http://www.gnu.org/software/grub/>`_ is a multiboot boot loader. It supports boot ACRN
|
||||
hypervisor on different working scenarios, it is also widely used for Linux distributions like
|
||||
Ubuntu/Debian/Fedora/CentOS. Please check `<http://www.gnu.org/software/grub/grub-download.html>`_
|
||||
to get the latest source code and `<https://www.gnu.org/software/grub/grub-documentation.html>`_
|
||||
for the detailed documentations.
|
||||
|
||||
ACRN hypervisor could boot from `multiboot protocol <http://www.gnu.org/software/grub/manual/multiboot/multiboot.html>`_
|
||||
or `multiboot2 protocol <http://www.gnu.org/software/grub/manual/multiboot2/multiboot.html>`_.
|
||||
Comparing with multiboot protocol, the multiboot2 protocol adds UEFI support.
|
||||
|
||||
The multiboot protocol is supported in ACRN hypervisor by default, whereas multiboot2 is supported
|
||||
when ``CONFIG_MULTIBOOT2`` is enabled in Kconfig. When hypervisor is loaded by GRUB ``multiboot``
|
||||
command, the multiboot protocol is used, and guest kernel or ramdisk must be loaded with GRUB
|
||||
``module`` command. When hypervisor is loaded by GRUB ``multiboot2`` command, the multiboot2 protocol
|
||||
is used, and guest kernel or ramdisk must be loaded with GRUB ``module2`` command.
|
||||
|
||||
The ACRN hypervisor binary is built with two formats, ``acrn.32.out`` in ELF format and ``acrn.bin``
|
||||
in RAW format. The GRUB ``multiboot`` command support ELF format only and does not support
|
||||
binary relocation, whatever ``CONFIG_RELOC`` is set or not. The GRUB ``multiboot2`` command
|
||||
support ELF format when ``CONFIG_RELOC`` is not set, or RAW format when ``CONFIG_RELOC`` is
|
||||
set.
|
||||
|
||||
.. note::
|
||||
``CONFIG_RELOC`` is set by default, so please use ``acrn.32.out`` in multiboot protocol
|
||||
or ``acrn.bin`` in multiboot2 protocol.
|
||||
|
||||
To make sure platform get correct ACPI RSDP info, we recommand to use ``acrn.bin`` to load
|
||||
ACRN hypervisor on a UEFI platform.
|
||||
|
||||
|
||||
Using pre-installed GRUB
|
||||
************************
|
||||
|
||||
Most Linux distributions support GRUB version 2, we can re-use pre-installed GRUB to load ACRN hypervisor.
|
||||
The prerequisites is GRUB version must be higher than 2.02.
|
||||
Here we take Ubuntu for example to load ACRN on a scenario which has two pre-launched VMs (please
|
||||
note SOS_VM is also a kind of pre-launched VM):
|
||||
|
||||
#. Copy ACRN hypervisor binary acrn.32.out(or acrn.bin) and pre-launched VM kernel images to ``/boot/``;
|
||||
|
||||
#. Modify the ``/etc/default/grub`` file as follows to make the GRUB menu visible when booting:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
# GRUB_HIDDEN_TIMEOUT=0
|
||||
GRUB_HIDDEN_TIMEOUT_QUIET=false
|
||||
|
||||
#. Append the following configuration in the ``/etc/grub.d/40_custom`` file (or ``/boot/grub/custom.cfg``
|
||||
file without following ``update-grub`` step):
|
||||
|
||||
Configuration template for multiboot protocol:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
menuentry 'Boot ACRN hypervisor from multiboot' {
|
||||
insmod part_gpt
|
||||
insmod ext2
|
||||
echo 'Loading ACRN hypervisor ...'
|
||||
multiboot --quirk-modules-after-kernel /boot/acrn.32.out $(HV bootargs) $(SOS bootargs)
|
||||
module /boot/kernel4vm0 xxxxxx $(VM0 bootargs)
|
||||
module /boot/kernel4vm1 yyyyyy $(VM1 bootargs)
|
||||
}
|
||||
|
||||
Configuration template for multiboot2 protocol:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
menuentry 'Boot ACRN hypervisor from multiboot2' {
|
||||
insmod part_gpt
|
||||
insmod ext2
|
||||
echo 'Loading ACRN hypervisor ...'
|
||||
multiboot2 /boot/acrn.bin $(HV bootargs) $(SOS bootargs)
|
||||
module2 /boot/kernel4vm0 xxxxxx $(VM0 bootargs)
|
||||
module2 /boot/kernel4vm1 yyyyyy $(VM1 bootargs)
|
||||
}
|
||||
|
||||
|
||||
.. note::
|
||||
The module ``/boot/kernel4vm0`` is the VM0 kernel file. The param ``xxxxxx`` is
|
||||
VM0's kernel file tag and must exactly match the ``kernel_mod_tag`` of VM0 which
|
||||
is configured in the ``hypervisor/scenarios/$(SCENARIO)/vm_configurations.c``
|
||||
file. The multiboot module ``/boot/kernel4vm1`` is the VM1 kernel file and the param
|
||||
``yyyyyy`` is its tag and must exactly match the ``kernel_mod_tag`` of VM1 in the
|
||||
``hypervisor/scenarios/$(SCENARIO)/vm_configurations.c`` file.
|
||||
|
||||
The guest kernel command line arguments is configured in hypervisor source code by default
|
||||
if no ``$(VMx bootargs)`` presents, but if ``$(VMx bootargs)`` presents, the default
|
||||
command line arguments would be overridden by the ``$(VMx bootargs)`` parameters.
|
||||
|
||||
The ``$(SOS bootargs)`` parameter in multiboot command would be appended to the end of Service
|
||||
VM kernel command line. This is useful to override some SOS kernel cmdline parameters because
|
||||
the later one would win if same parameters configured in Linux kernel cmdline. For example,
|
||||
add ``root=/dev/sda3`` will override the original root device to ``/dev/sda3`` for SOS kernel.
|
||||
|
||||
All parameters after ``#`` character would be ignored since GRUB treat them as comments.
|
||||
|
||||
``\``, ``$``, ``#`` are special characters in GRUB, a escape character ``\`` need to be added
|
||||
before these special charactors if they are included in ``$(HV bootargs)`` or ``$(VM bootargs)``.
|
||||
e.g. ``memmap=0x200000$0xE00000`` for guest kernel cmdline need to be changed to
|
||||
``memmap=0x200000\$0xE00000``
|
||||
|
||||
|
||||
#. Update GRUB::
|
||||
|
||||
$ sudo update-grub
|
||||
|
||||
#. Reboot the platform. Select the **Boot ACRN hypervisor xxx** entry to boot the ACRN hypervisor on the
|
||||
platform's display. The GRUB loader will boot the hypervisor, and the hypervisor will start the VMs automatically.
|
||||
|
||||
|
||||
Installing self-built GRUB
|
||||
**************************
|
||||
|
||||
If the GRUB version on your platform is outdated or has issue to boot ACRN hypervisor, you can have
|
||||
a try with self-built GRUB binary. Please get the latest GRUB code and follow `GRUB Manual
|
||||
<https://www.gnu.org/software/grub/manual/grub/grub.html#Installing-GRUB-using-grub_002dinstall>`_
|
||||
to install your own GRUB, and then follow steps in **Using pre-installed GRUB**.
|
||||
|
||||
Here we provide another simple method to build GRUB in efi application format:
|
||||
|
||||
#. make GRUB efi application:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ git clone https://git.savannah.gnu.org/git/grub.git
|
||||
$ cd grub
|
||||
$ ./bootstrap
|
||||
$ ./configure --with-platform=efi --target=x86_64
|
||||
$ make
|
||||
$ ./grub-mkimage -p /EFI/BOOT -d ./grub-core/ -O x86_64-efi -o grub_x86_64.efi \
|
||||
boot efifwsetup efi_gop efinet efi_uga lsefimmap lsefi lsefisystab \
|
||||
exfat fat multiboot2 multiboot terminal part_msdos part_gpt normal \
|
||||
all_video aout configfile echo file fixvideo fshelp gfxterm gfxmenu \
|
||||
gfxterm_background gfxterm_menu legacycfg video_bochs video_cirrus \
|
||||
video_colors video_fb videoinfo video net tftp
|
||||
|
||||
This will build a ``grub_x86_64.efi`` binary in the current directory, copy it to ``/EFI/boot/`` folder
|
||||
on EFI partition.
|
||||
|
||||
#. create ``/EFI/boot/grub.cfg`` file containing the following:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
set default=0
|
||||
set timeout=5
|
||||
# set correct root device which stores acrn binary and kernel images
|
||||
set root='hd0,gpt3'
|
||||
|
||||
menuentry 'Boot ACRN hypervisor from multiboot' {
|
||||
insmod part_gpt
|
||||
insmod ext2
|
||||
echo 'Loading ACRN hypervisor ...'
|
||||
multiboot --quirk-modules-after-kernel /boot/acrn.32.out $(HV bootargs) $(SOS bootargs)
|
||||
module /boot/kernel4vm0 xxxxxx $(VM0 bootargs)
|
||||
module /boot/kernel4vm1 yyyyyy $(VM1 bootargs)
|
||||
}
|
||||
|
||||
menuentry 'Boot ACRN hypervisor from multiboot2' {
|
||||
insmod part_gpt
|
||||
insmod ext2
|
||||
echo 'Loading ACRN hypervisor ...'
|
||||
multiboot2 /boot/acrn.bin $(HV bootargs) $(SOS bootargs)
|
||||
module2 /boot/kernel4vm0 xxxxxx $(VM0 bootargs)
|
||||
module2 /boot/kernel4vm1 yyyyyy $(VM1 bootargs)
|
||||
}
|
||||
|
||||
#. copy ACRN binary and guest kernel images to the folder which GRUB configures, e.g. ``/boot/`` folder on ``/dev/sda3/``;
|
||||
|
||||
#. run ``/EFI/boot/grub_x86_64.efi`` in EFI shell.
|
||||
Loading…
Reference in New Issue
Block a user