diff --git a/doc/introduction/index.rst b/doc/introduction/index.rst index 5374a0360..785bd5d8e 100644 --- a/doc/introduction/index.rst +++ b/doc/introduction/index.rst @@ -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 - `__ - is an alternative boot firmware that can be used to boot ACRN. The `Boot - ACRN Hyervisor - `_ tutorial - provides more information on how to use SBL with ACRN. - -.. note:: - - A virtual `Slim Bootloader - `__, - 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 + `_ tutorial + provides more information on how to use SBL with ACRN. + ACRN Hypervisor Architecture **************************** diff --git a/doc/try.rst b/doc/try.rst index 5a55419b3..f1b12e45a 100644 --- a/doc/try.rst +++ b/doc/try.rst @@ -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 diff --git a/doc/tutorials/using_grub.rst b/doc/tutorials/using_grub.rst new file mode 100644 index 000000000..f409a55c0 --- /dev/null +++ b/doc/tutorials/using_grub.rst @@ -0,0 +1,173 @@ +.. _using_grub: + +Getting Started Guide for Using GRUB +#################################### +`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 ``_ +to get the latest source code and ``_ +for the detailed documentations. + +ACRN hypervisor could boot from `multiboot protocol `_ +or `multiboot2 protocol `_. +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 +`_ +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.