mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-04-29 12:14:13 +00:00
0bd384d41b
While we hoped to make the headings consistent over time while doing other edits, we should instead just make the squirrels happy and do them all at once or they'll likely never be made consistent. A python script was used to find the headings, and then a call to https://pypi.org/project/titlecase to transform the title. A visual inspection was used to tweak a few unexpected resulting titles. Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
204 lines
8.1 KiB
ReStructuredText
204 lines
8.1 KiB
ReStructuredText
.. _using_grub:
|
|
|
|
Using GRUB to Boot ACRN
|
|
#######################
|
|
|
|
`GRUB <http://www.gnu.org/software/grub/>`_ is a multiboot bootloader
|
|
used by many popular Linux distributions. It also supports booting the
|
|
ACRN hypervisor. See
|
|
`<http://www.gnu.org/software/grub/grub-download.html>`_ to get the
|
|
latest GRUB source code and
|
|
`<https://www.gnu.org/software/grub/grub-documentation.html>`_ for
|
|
detailed documentation.
|
|
|
|
The ACRN hypervisor can 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 by the ACRN hypervisor natively.
|
|
The multiboot2 protocol is supported when :option:`hv.FEATURES.MULTIBOOT2` is
|
|
enabled in configuration. The :option:`hv.FEATURES.MULTIBOOT2` is enabled by default.
|
|
Which boot protocol is used depends on the hypervisor is loaded by
|
|
GRUB's ``multiboot`` command or ``multiboot2`` command. The guest kernel
|
|
or ramdisk must be loaded by the GRUB ``module`` command or ``module2``
|
|
command accordingly when different boot protocol is used.
|
|
|
|
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,
|
|
even if :option:`hv.FEATURES.RELOC` is set. The GRUB ``multiboot2``
|
|
command supports
|
|
ELF format when :option:`hv.FEATURES.RELOC` is not set, or RAW format when
|
|
:option:`hv.FEATURES.RELOC` is set.
|
|
|
|
.. note::
|
|
* :option:`hv.FEATURES.RELOC` is set by default, so use ``acrn.32.out`` in multiboot
|
|
protocol and ``acrn.bin`` in multiboot2 protocol.
|
|
|
|
* Per ACPI specification, the RSDP pointer is described in the EFI System
|
|
Table instead of legacy ACPI RSDP area on a UEFI enabled platform. To make
|
|
sure ACRN hypervisor gets the correct ACPI RSDP info, we recommend using
|
|
``acrn.bin`` with multiboot2 protocol to load hypervisor on a UEFI platform.
|
|
|
|
.. _pre-installed-grub:
|
|
|
|
Using Pre-Installed GRUB
|
|
************************
|
|
|
|
Most Linux distributions use GRUB version 2 by default. If its version
|
|
2.02 or higher, we can re-use the pre-installed GRUB to load the ACRN
|
|
hypervisor.
|
|
|
|
Here's an example using Ubuntu to load ACRN on a scenario with two
|
|
pre-launched VMs (the SOS_VM is also a kind of pre-launched VM):
|
|
|
|
#. Copy ACRN hypervisor binary ``acrn.32.out`` (or ``acrn.bin``) and the
|
|
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:
|
|
|
|
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) $(Service VM 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) $(Service VM 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 configured in the
|
|
``misc/vm_configs/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
|
|
``misc/vm_configs/scenarios/$(SCENARIO)/vm_configurations.c`` file.
|
|
|
|
The guest kernel command-line arguments are configured in the
|
|
hypervisor source code by default if no ``$(VMx bootargs)`` is present.
|
|
If ``$(VMx bootargs)`` is present, the default command-line arguments
|
|
are overridden by the ``$(VMx bootargs)`` parameters.
|
|
|
|
The ``$(Service VM bootargs)`` parameter in the multiboot command
|
|
is appended to the end of the Service VM kernel command line. This is
|
|
useful to override some Service VM kernel cmdline parameters because the
|
|
later one would be used if the same parameters were configured in the Linux
|
|
kernel cmdline. For example, adding ``root=/dev/sda3`` will override the
|
|
original root device to ``/dev/sda3`` for the Service VM kernel.
|
|
|
|
All parameters after a ``#`` character are ignored since GRUB
|
|
treats them as comments.
|
|
|
|
``\``, ``$``, ``#`` are special characters in GRUB. An escape
|
|
character ``\`` must be added before these special characters if they
|
|
are included in ``$(HV bootargs)`` or ``$(VM bootargs)``. For example,
|
|
``memmap=0x200000$0xE00000`` for guest kernel cmdline must be written as
|
|
``memmap=0x200000\$0xE00000``
|
|
|
|
|
|
#. Update GRUB::
|
|
|
|
$ sudo update-grub
|
|
|
|
#. Reboot the platform. On the platform's console, Select the
|
|
**Boot ACRN hypervisor xxx** entry to boot the ACRN hypervisor.
|
|
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 issues booting
|
|
the ACRN hypervisor, you can have a try with self-built GRUB binary. Get
|
|
the latest GRUB code and follow the `GRUB Manual
|
|
<https://www.gnu.org/software/grub/manual/grub/grub.html#Installing-GRUB-using-grub_002dinstall>`_
|
|
to build and install your own GRUB, and then follow the steps described
|
|
earlier in `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 the EFI partition (it is typically mounted under ``/boot/efi/`` folder on rootfs).
|
|
|
|
#. 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) $(Service VM 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) $(Service VM bootargs)
|
|
module2 /boot/kernel4vm0 xxxxxx $(VM0 bootargs)
|
|
module2 /boot/kernel4vm1 yyyyyy $(VM1 bootargs)
|
|
}
|
|
|
|
#. Copy the ACRN binary and guest kernel images to the GRUB-configured
|
|
folder, e.g. ``/boot/`` folder on ``/dev/sda3/``;
|
|
|
|
#. Run ``/EFI/boot/grub_x86_64.efi`` in the EFI shell.
|