diff --git a/doc/tutorials/using_grub.rst b/doc/tutorials/using_grub.rst index 046d492fb..1cb2a8f2e 100644 --- a/doc/tutorials/using_grub.rst +++ b/doc/tutorials/using_grub.rst @@ -11,51 +11,52 @@ latest GRUB source code and ``_ for detailed documentation. -The ACRN hypervisor can boot from `multiboot protocol +The ACRN hypervisor can boot from the `multiboot protocol `_ or `multiboot2 protocol -`_. -Comparing with multiboot protocol, the multiboot2 protocol adds UEFI -support. +`_. 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 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 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 support ELF format only and does not support binary relocation, +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 multiboot - protocol and ``acrn.bin`` in multiboot2 protocol. + * :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 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. + 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. If its version -2.02 or higher, we can re-use the pre-installed GRUB to load the ACRN +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 (the SOS_VM is also a kind of pre-launched VM): +pre-launched VMs (the Service VM is also a kind of pre-launched VM): -#. Copy ACRN hypervisor binary ``acrn.32.out`` (or ``acrn.bin``) and the +#. 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 @@ -105,33 +106,34 @@ pre-launched VMs (the SOS_VM is also a kind of pre-launched VM): ``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 + 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. 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. + 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 command-line parameters because the + later one would be used if the same parameters were configured in the + Linux kernel command line. 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`` + ``\``, ``$``, ``#`` 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 +#. 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. @@ -141,16 +143,16 @@ 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 ACRN hypervisor, you can use a self-built GRUB binary. Get the latest GRUB code and follow the `GRUB Manual `_ to build and install your own GRUB, and then follow the steps described -earlier in `pre-installed-grub`_. +earlier in :ref:`pre-installed-grub`. Here we provide another simple method to build GRUB in EFI application format: -#. Make GRUB efi application: +#. Make a GRUB EFI application: .. code-block:: none @@ -166,9 +168,9 @@ Here we provide another simple method to build GRUB in EFI application format: 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). + 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: @@ -197,7 +199,7 @@ Here we provide another simple method to build GRUB in EFI application format: 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/``; +#. 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.