doc: terminology cleanup in using_grub.rst
- Replace SOS with Service VM - Replace guest with VM - Clean up some of the grammar Signed-off-by: Amy Reyes <amy.reyes@intel.com>
This commit is contained in:
Amy Reyes
David Kinder
parent
6f92eef2be
commit
a5a4c112d1
|
|
@ -11,51 +11,52 @@ 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
|
||||
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>`_.
|
||||
Comparing with multiboot protocol, the multiboot2 protocol adds UEFI
|
||||
support.
|
||||
<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 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
|
||||
<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`_.
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue