205 lines
8.1 KiB
ReStructuredText
205 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 the `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>`_. Compared
|
|
with the 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 the scenario configuration. The :option:`hv.FEATURES.MULTIBOOT2` is
|
|
enabled by default. To load the hypervisor with the multiboot protocol, run the
|
|
GRUB ``multiboot`` command. To load the hypervisor with the multiboot2 protocol,
|
|
run the ``multiboot2`` command. To load a VM kernel or ramdisk, run the
|
|
GRUB ``module`` command for the multiboot protocol or the ``module2`` command
|
|
for the multiboot2 protocol.
|
|
|
|
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 supports 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
|
|
the multiboot protocol and ``acrn.bin`` in the multiboot2 protocol.
|
|
|
|
* Per ACPI specification, the RSDP pointer is described in the EFI System
|
|
Table instead of the legacy ACPI RSDP area on a UEFI-enabled platform. To
|
|
make sure the ACRN hypervisor gets the correct ACPI RSDP information, we
|
|
recommend using ``acrn.bin`` with the multiboot2 protocol to load the
|
|
hypervisor on a UEFI platform.
|
|
|
|
.. _pre-installed-grub:
|
|
|
|
Using Pre-Installed GRUB
|
|
************************
|
|
|
|
Most Linux distributions use GRUB version 2 by default. For version
|
|
2.02 or higher, we can reuse 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:
|
|
|
|
#. Copy the 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 VM 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. If a
|
|
command-line configuration parameter is specified more than once, the last
|
|
one wins and earlier ones are ignored. For example, adding
|
|
``root=/dev/sda3`` will override the original root device 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 the VM kernel command line 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 use a 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 :ref:`pre-installed-grub`.
|
|
|
|
|
|
Here we provide another simple method to build GRUB in EFI application format:
|
|
|
|
#. Make a 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 and
|
|
copy it to the ``/EFI/boot/`` directory on the EFI partition (it is typically
|
|
mounted under the ``/boot/efi/`` directory 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 VM kernel images to the GRUB-configured
|
|
directory, e.g., the ``/boot/`` directory on ``/dev/sda3/``.
|
|
|
|
#. Run ``/EFI/boot/grub_x86_64.efi`` in the EFI shell.
|