github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-08-02 16:30:12 +00:00
Code Issues Projects Releases Wiki Activity

doc: terminology cleanup in using_grub.rst

Browse Source 
- 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 2021-10-21 19:00:43 -07:00 committed by David Kinder
parent 6f92eef2be
commit a5a4c112d1
1 changed files with 44 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
doc/tutorials/using_grub.rst
View File

@ -11,51 +11,52 @@ latest GRUB source code and
`<https://www.gnu.org/software/grub/grub-documentation.html>`_ for `<https://www.gnu.org/software/grub/grub-documentation.html>`_ for
detailed documentation. 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 <http://www.gnu.org/software/grub/manual/multiboot/multiboot.html>`_ or
`multiboot2 protocol `multiboot2 protocol
<http://www.gnu.org/software/grub/manual/multiboot2/multiboot.html>`_. <http://www.gnu.org/software/grub/manual/multiboot2/multiboot.html>`_. Compared
Comparing with multiboot protocol, the multiboot2 protocol adds UEFI with the multiboot protocol, the multiboot2 protocol adds UEFI support.
support.
The multiboot protocol is supported by the ACRN hypervisor natively. The multiboot protocol is supported by the ACRN hypervisor natively. The
The multiboot2 protocol is supported when :option:`hv.FEATURES.MULTIBOOT2` is multiboot2 protocol is supported when :option:`hv.FEATURES.MULTIBOOT2` is
enabled in configuration. The :option:`hv.FEATURES.MULTIBOOT2` is enabled by default. enabled in the scenario configuration. The :option:`hv.FEATURES.MULTIBOOT2` is
Which boot protocol is used depends on the hypervisor is loaded by enabled by default. To load the hypervisor with the multiboot protocol, run the
GRUB's ``multiboot`` command or ``multiboot2`` command. The guest kernel GRUB ``multiboot`` command. To load the hypervisor with the multiboot2 protocol,
or ramdisk must be loaded by the GRUB ``module`` command or ``module2`` run the ``multiboot2`` command. To load a VM kernel or ramdisk, run the
command accordingly when different boot protocol is used. 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 The ACRN hypervisor binary is built with two formats: ``acrn.32.out`` in
ELF format and ``acrn.bin`` in RAW format. The GRUB ``multiboot`` 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`` even if :option:`hv.FEATURES.RELOC` is set. The GRUB ``multiboot2``
command supports command supports
ELF format when :option:`hv.FEATURES.RELOC` is not set, or RAW format when ELF format when :option:`hv.FEATURES.RELOC` is not set, or RAW format when
:option:`hv.FEATURES.RELOC` is set. :option:`hv.FEATURES.RELOC` is set.
.. note:: .. note::
* :option:`hv.FEATURES.RELOC` is set by default, so use ``acrn.32.out`` in multiboot * :option:`hv.FEATURES.RELOC` is set by default, so use ``acrn.32.out`` in
protocol and ``acrn.bin`` in multiboot2 protocol. the multiboot protocol and ``acrn.bin`` in the multiboot2 protocol.
* Per ACPI specification, the RSDP pointer is described in the EFI System * 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 Table instead of the legacy ACPI RSDP area on a UEFI-enabled platform. To
sure ACRN hypervisor gets the correct ACPI RSDP info, we recommend using make sure the ACRN hypervisor gets the correct ACPI RSDP information, we
``acrn.bin`` with multiboot2 protocol to load hypervisor on a UEFI platform. recommend using ``acrn.bin`` with the multiboot2 protocol to load the
hypervisor on a UEFI platform.
.. _pre-installed-grub: .. _pre-installed-grub:
Using Pre-Installed GRUB Using Pre-Installed GRUB
************************ ************************
Most Linux distributions use GRUB version 2 by default. If its version Most Linux distributions use GRUB version 2 by default. For version
2.02 or higher, we can re-use the pre-installed GRUB to load the ACRN 2.02 or higher, we can reuse the pre-installed GRUB to load the ACRN
hypervisor. hypervisor.
Here's an example using Ubuntu to load ACRN on a scenario with two 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/``; pre-launched VM kernel images to ``/boot/``;
#. Modify the ``/etc/default/grub`` file as follows to make the GRUB #. 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 ``kernel_mod_tag`` of VM1 in the
``misc/vm_configs/scenarios/$(SCENARIO)/vm_configurations.c`` file. ``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. hypervisor source code by default if no ``$(VMx bootargs)`` is present.
If ``$(VMx bootargs)`` is present, the default command-line arguments If ``$(VMx bootargs)`` is present, the default command-line arguments
are overridden by the ``$(VMx bootargs)`` parameters. are overridden by the ``$(VMx bootargs)`` parameters.
The ``$(Service VM bootargs)`` parameter in the multiboot command The ``$(Service VM bootargs)`` parameter in the multiboot command is
is appended to the end of the Service VM kernel command line. This is appended to the end of the Service VM kernel command line. This is useful
useful to override some Service VM kernel cmdline parameters because the 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 later one would be used if the same parameters were configured in the
kernel cmdline. For example, adding ``root=/dev/sda3`` will override the Linux kernel command line. For example, adding ``root=/dev/sda3`` will
original root device to ``/dev/sda3`` for the Service VM kernel. override the original root device to ``/dev/sda3`` for the Service VM
kernel.
All parameters after a ``#`` character are ignored since GRUB All parameters after a ``#`` character are ignored since GRUB
treats them as comments. treats them as comments.
``\``, ``$``, ``#`` are special characters in GRUB. An escape ``\``, ``$``, ``#`` are special characters in GRUB. An escape character
character ``\`` must be added before these special characters if they ``\`` must be added before these special characters if they are included
are included in ``$(HV bootargs)`` or ``$(VM bootargs)``. For example, in ``$(HV bootargs)`` or ``$(VM bootargs)``. For example,
``memmap=0x200000$0xE00000`` for guest kernel cmdline must be written as ``memmap=0x200000$0xE00000`` for the VM kernel command line must be
``memmap=0x200000\$0xE00000`` written as ``memmap=0x200000\$0xE00000``.
#. Update GRUB:: #. Update GRUB::
$ sudo 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. **Boot ACRN hypervisor xxx** entry to boot the ACRN hypervisor.
The GRUB loader will boot the hypervisor, and the hypervisor will The GRUB loader will boot the hypervisor, and the hypervisor will
start the VMs automatically. 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 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 the latest GRUB code and follow the `GRUB Manual
<https://www.gnu.org/software/grub/manual/grub/grub.html#Installing-GRUB-using-grub_002dinstall>`_ <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 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: 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 .. 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 \ gfxterm_background gfxterm_menu legacycfg video_bochs video_cirrus \
video_colors video_fb videoinfo video net tftp video_colors video_fb videoinfo video net tftp
This will build a ``grub_x86_64.efi`` binary in the current This will build a ``grub_x86_64.efi`` binary in the current directory and
directory, copy it to ``/EFI/boot/`` folder copy it to the ``/EFI/boot/`` directory on the EFI partition (it is typically
on the EFI partition (it is typically mounted under ``/boot/efi/`` folder on rootfs). mounted under the ``/boot/efi/`` directory on rootfs).
#. Create ``/EFI/boot/grub.cfg`` file containing the following: #. 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) module2 /boot/kernel4vm1 yyyyyy $(VM1 bootargs)
} }
#. Copy the ACRN binary and guest kernel images to the GRUB-configured #. Copy the ACRN binary and VM kernel images to the GRUB-configured
folder, e.g. ``/boot/`` folder on ``/dev/sda3/``; directory, e.g., the ``/boot/`` directory on ``/dev/sda3/``.
#. Run ``/EFI/boot/grub_x86_64.efi`` in the EFI shell. #. Run ``/EFI/boot/grub_x86_64.efi`` in the EFI shell.