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

doc: add hv parameter usage

Browse Source 
The hv parameter could be configured in GRUB menu, currently we support
"uart=" parameter to override uart settings.

The patch also has modifications on tutorial of using_grub.

Signed-off-by: Victor Sun <victor.sun@intel.com>
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
Victor Sun 2020-06-16 01:52:23 +08:00 committed by David Kinder
parent 5119fa0673
commit 780c87d9da
6 changed files with 150 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/develop.rst
View File

@ -15,6 +15,7 @@ Configuration and Tools
tutorials/acrn_configuration_tool tutorials/acrn_configuration_tool
reference/kconfig/index reference/kconfig/index
user-guides/hv-parameters
user-guides/kernel-parameters user-guides/kernel-parameters
user-guides/acrn-shell user-guides/acrn-shell
user-guides/acrn-dm-parameters user-guides/acrn-dm-parameters
@ -99,6 +100,7 @@ Additional Tutorials
tutorials/up2 tutorials/up2
tutorials/building_acrn_in_docker tutorials/building_acrn_in_docker
tutorials/using_grub
tutorials/acrn_ootb tutorials/acrn_ootb
tutorials/static-ip tutorials/static-ip
tutorials/increase-uos-disk-size tutorials/increase-uos-disk-size

19
doc/introduction/index.rst
View File

@ -26,7 +26,8 @@ user VM sharing optimizations for IoT and embedded devices.
ACRN Open Source Roadmap 2020 ACRN Open Source Roadmap 2020
***************************** *****************************
Stay informed on what's ahead for ACRN in 2020 by visiting the `ACRN 2020 Roadmap <https://projectacrn.org/wp-content/uploads/sites/59/2020/03/ACRN-Roadmap-External-2020.pdf>`_. Stay informed on what's ahead for ACRN in 2020 by visiting the
`ACRN 2020 Roadmap <https://projectacrn.org/wp-content/uploads/sites/59/2020/03/ACRN-Roadmap-External-2020.pdf>`_.
For up-to-date happenings, visit the `ACRN blog <https://projectacrn.org/blog/>`_. For up-to-date happenings, visit the `ACRN blog <https://projectacrn.org/blog/>`_.
@ -411,8 +412,8 @@ bootloader used by the Operating System (OS).
Direct boot mode Direct boot mode
================ ================
The ACRN hypervisor could be boot from a third-party bootloader directly and we The ACRN hypervisor can be booted from a third-party bootloader
called this **Direct boot mode**. The most popular bootloader is `grub`_, it is directly, called **Direct boot mode**. A popular bootloader is `grub`_ and is
also widely used by Linux distributions. also widely used by Linux distributions.
:ref:`using_grub` has a introduction on how to boot ACRN hypervisor with GRUB. :ref:`using_grub` has a introduction on how to boot ACRN hypervisor with GRUB.
@ -435,14 +436,18 @@ The Boot process proceeds as follows:
the ACRN Device Model and Virtual bootloader through ``dm-verity``. the ACRN Device Model and Virtual bootloader through ``dm-verity``.
#. The virtual bootloader starts the User-side verified boot process. #. 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`` In this boot mode, the boot options of pre-launched VM and service VM are defined
macro in the source code (replace ``{x}`` with the VM number) by default. But they in the variable of ``bootargs`` of struct ``vm_configs[vm id].os_config``
could be overridden by GRUB menu also. Please check :ref:`using_grub` for details. in the source code ``hypervisor/$(SCENARIO)/vm_configurations.c`` by default.
Their boot options can be overridden by the GRUB menu. See :ref:`using_grub` for
details. The boot options of post-launched VM is not covered by hypervisor
source code or GRUB menu, it is defined in guest image file or specified by
launch scripts.
.. note:: .. note::
`Slim Bootloader`_ is an alternative boot firmware that can be used to `Slim Bootloader`_ is an alternative boot firmware that can be used to
boot ACRN with **Direct boot mode**. The `Boot ACRN Hyervisor boot ACRN in **Direct boot mode**. The `Boot ACRN Hypervisor
<https://slimbootloader.github.io/how-tos/boot-acrn.html>`_ tutorial <https://slimbootloader.github.io/how-tos/boot-acrn.html>`_ tutorial
provides more information on how to use SBL with ACRN. provides more information on how to use SBL with ACRN.

18
doc/reference/index.rst
View File

@ -1,18 +0,0 @@
:orphan:
.. _reference:
Developer references
####################
.. toctree::
:maxdepth: 1
../api/index
kconfig/index
../user-guides/acrn-shell
../user-guides/kernel-parameters
../user-guides/acrn-dm-parameters
* :ref:`glossary`
* :ref:`genindex`

1
doc/try.rst
View File

@ -21,7 +21,6 @@ Follow these getting started guides to give ACRN a try:
reference/hardware reference/hardware
getting-started/building-from-source getting-started/building-from-source
tutorials/using_grub
getting-started/rt_industry_ubuntu getting-started/rt_industry_ubuntu
tutorials/using_hybrid_mode_on_nuc tutorials/using_hybrid_mode_on_nuc
tutorials/using_partition_mode_on_nuc tutorials/using_partition_mode_on_nuc

126
doc/tutorials/using_grub.rst
View File

@ -1,46 +1,55 @@
.. _using_grub: .. _using_grub:
Getting Started Guide for Using GRUB Using GRUB to boot ACRN
#################################### #######################
`GRUB <http://www.gnu.org/software/grub/>`_ is a multiboot boot loader. It supports boot ACRN `GRUB <http://www.gnu.org/software/grub/>`_ is a multiboot boot loader
hypervisor on different working scenarios, it is also widely used for Linux distributions like used by many popular Linux distributions. It also supports booting the
Ubuntu/Debian/Fedora/CentOS. Please check `<http://www.gnu.org/software/grub/grub-download.html>`_ ACRN hypervisor.
to get the latest source code and `<https://www.gnu.org/software/grub/grub-documentation.html>`_ See `<http://www.gnu.org/software/grub/grub-download.html>`_
for the detailed documentations. to get the latest GRUB source code and `<https://www.gnu.org/software/grub/grub-documentation.html>`_
for detailed documentation.
ACRN hypervisor could boot from `multiboot protocol <http://www.gnu.org/software/grub/manual/multiboot/multiboot.html>`_ The ACRN hypervisor can boot from `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>`_. or `multiboot2 protocol <http://www.gnu.org/software/grub/manual/multiboot2/multiboot.html>`_.
Comparing with multiboot protocol, the multiboot2 protocol adds UEFI support. Comparing with multiboot protocol, the multiboot2 protocol adds UEFI support.
The multiboot protocol is supported in ACRN hypervisor by default, whereas multiboot2 is supported The multiboot protocol is supported by the ACRN hypervisor natively.
when ``CONFIG_MULTIBOOT2`` is enabled in Kconfig. When hypervisor is loaded by GRUB ``multiboot`` The multiboot2 protocol is supported when ``CONFIG_MULTIBOOT2`` is
command, the multiboot protocol is used, and guest kernel or ramdisk must be loaded with GRUB enabled in Kconfig. The ``CONFIG_MULTIBOOT2`` is enabled by default.
``module`` command. When hypervisor is loaded by GRUB ``multiboot2`` command, the multiboot2 protocol Which boot protocol is used depends on the hypervisor is loaded by
is used, and guest kernel or ramdisk must be loaded with GRUB ``module2`` command. 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 ACRN hypervisor binary is built with two formats, ``acrn.32.out`` in ELF format and ``acrn.bin`` The ACRN hypervisor binary is built with two formats: ``acrn.32.out`` in
in RAW format. The GRUB ``multiboot`` command support ELF format only and does not support ELF format and ``acrn.bin`` in RAW format. The GRUB ``multiboot``
binary relocation, whatever ``CONFIG_RELOC`` is set or not. The GRUB ``multiboot2`` command command support ELF format only and does not support binary relocation,
support ELF format when ``CONFIG_RELOC`` is not set, or RAW format when ``CONFIG_RELOC`` is even if ``CONFIG_RELOC`` is set. The GRUB ``multiboot2`` command support
set. ELF format when ``CONFIG_RELOC`` is not set, or RAW format when
``CONFIG_RELOC`` is set.
.. note:: .. note::
``CONFIG_RELOC`` is set by default, so please use ``acrn.32.out`` in multiboot protocol ``CONFIG_RELOC`` is set by default, so use ``acrn.32.out`` in multiboot
or ``acrn.bin`` in multiboot2 protocol. protocol and ``acrn.bin`` in multiboot2 protocol.
To make sure platform get correct ACPI RSDP info, we recommand to use ``acrn.bin`` to load Per ACPI specification, the RSDP pointer is described in the EFI System
ACRN hypervisor on a UEFI platform. 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.
.. _pre-installed-grub:
Using pre-installed GRUB Using pre-installed GRUB
************************ ************************
Most Linux distributions support GRUB version 2, we can re-use pre-installed GRUB to load ACRN hypervisor. Most Linux distributions use GRUB version 2 by default. We can re-use
The prerequisites is GRUB version must be higher than 2.02. pre-installed GRUB to load ACRN hypervisor if its version 2.02 or
Here we take Ubuntu for example to load ACRN on a scenario which has two pre-launched VMs (please higher.
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/``; 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):
#. Copy 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: #. Modify the ``/etc/default/grub`` file as follows to make the GRUB menu visible when booting:
@ -49,8 +58,7 @@ note SOS_VM is also a kind of pre-launched VM):
# GRUB_HIDDEN_TIMEOUT=0 # GRUB_HIDDEN_TIMEOUT=0
GRUB_HIDDEN_TIMEOUT_QUIET=false GRUB_HIDDEN_TIMEOUT_QUIET=false
#. Append the following configuration in the ``/etc/grub.d/40_custom`` file (or ``/boot/grub/custom.cfg`` #. Append the following configuration in the ``/etc/grub.d/40_custom`` file:
file without following ``update-grub`` step):
Configuration template for multiboot protocol: Configuration template for multiboot protocol:
@ -60,7 +68,7 @@ note SOS_VM is also a kind of pre-launched VM):
insmod part_gpt insmod part_gpt
insmod ext2 insmod ext2
echo 'Loading ACRN hypervisor ...' echo 'Loading ACRN hypervisor ...'
multiboot --quirk-modules-after-kernel /boot/acrn.32.out $(HV bootargs) $(SOS bootargs) multiboot --quirk-modules-after-kernel /boot/acrn.32.out $(HV bootargs) $(Service VM bootargs)
module /boot/kernel4vm0 xxxxxx $(VM0 bootargs) module /boot/kernel4vm0 xxxxxx $(VM0 bootargs)
module /boot/kernel4vm1 yyyyyy $(VM1 bootargs) module /boot/kernel4vm1 yyyyyy $(VM1 bootargs)
} }
@ -73,7 +81,7 @@ note SOS_VM is also a kind of pre-launched VM):
insmod part_gpt insmod part_gpt
insmod ext2 insmod ext2
echo 'Loading ACRN hypervisor ...' echo 'Loading ACRN hypervisor ...'
multiboot2 /boot/acrn.bin $(HV bootargs) $(SOS bootargs) multiboot2 /boot/acrn.bin $(HV bootargs) $(Service VM bootargs)
module2 /boot/kernel4vm0 xxxxxx $(VM0 bootargs) module2 /boot/kernel4vm0 xxxxxx $(VM0 bootargs)
module2 /boot/kernel4vm1 yyyyyy $(VM1 bootargs) module2 /boot/kernel4vm1 yyyyyy $(VM1 bootargs)
} }
@ -81,48 +89,54 @@ note SOS_VM is also a kind of pre-launched VM):
.. note:: .. note::
The module ``/boot/kernel4vm0`` is the VM0 kernel file. The param ``xxxxxx`` is 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 VM0's kernel file tag and must exactly match the ``kernel_mod_tag`` of VM0
is configured in the ``hypervisor/scenarios/$(SCENARIO)/vm_configurations.c`` configured in the ``hypervisor/scenarios/$(SCENARIO)/vm_configurations.c``
file. The multiboot module ``/boot/kernel4vm1`` is the VM1 kernel file and the param 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 ``yyyyyy`` is its tag and must exactly match the ``kernel_mod_tag`` of VM1 in the
``hypervisor/scenarios/$(SCENARIO)/vm_configurations.c`` file. ``hypervisor/scenarios/$(SCENARIO)/vm_configurations.c`` file.
The guest kernel command line arguments is configured in hypervisor source code by default The guest kernel command line arguments is configured in the hypervisor source code by default
if no ``$(VMx bootargs)`` presents, but if ``$(VMx bootargs)`` presents, the default if no ``$(VMx bootargs)`` is present. If ``$(VMx bootargs)`` is present, the default
command line arguments would be overridden by the ``$(VMx bootargs)`` parameters. command line arguments is overridden by the ``$(VMx bootargs)`` parameters.
The ``$(SOS bootargs)`` parameter in multiboot command would be appended to the end of Service The ``$(Service VM bootargs)`` parameter in the multiboot command is appended to the end of Service
VM kernel command line. This is useful to override some SOS kernel cmdline parameters because VM kernel command line. This is useful to override some Service VM kernel cmdline parameters because
the later one would win if same parameters configured in Linux kernel cmdline. For example, 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. adding ``root=/dev/sda3`` will override the original root device
to ``/dev/sda3`` for the Service VM kernel.
All parameters after ``#`` character would be ignored since GRUB treat them as comments. All parameters after ``#`` character are ignored since GRUB treat them as comments.
``\``, ``$``, ``#`` are special characters in GRUB, a escape character ``\`` need to be added ``\``, ``$``, ``#`` are special characters in GRUB, a escape character ``\`` must be added
before these special charactors if they are included in ``$(HV bootargs)`` or ``$(VM bootargs)``. before these special characters if they are included in ``$(HV bootargs)`` or ``$(VM bootargs)``.
e.g. ``memmap=0x200000$0xE00000`` for guest kernel cmdline need to be changed to For example, ``memmap=0x200000$0xE00000`` for guest kernel cmdline
``memmap=0x200000\$0xE00000`` must be written as ``memmap=0x200000\$0xE00000``
#. Update GRUB:: #. Update GRUB::
$ sudo update-grub $ sudo update-grub
#. Reboot the platform. Select the **Boot ACRN hypervisor xxx** entry to boot the ACRN hypervisor on the #. Reboot the platform. On the platform's console, Select the
platform's display. The GRUB loader will boot the hypervisor, and the hypervisor will start the VMs automatically. **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 Installing self-built GRUB
************************** **************************
If the GRUB version on your platform is outdated or has issue to boot ACRN hypervisor, you can have If the GRUB version on your platform is outdated or has issues booting
a try with self-built GRUB binary. Please get the latest GRUB code and follow `GRUB Manual the ACRN hypervisor, you can have a try with 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>`_ <https://www.gnu.org/software/grub/manual/grub/grub.html#Installing-GRUB-using-grub_002dinstall>`_
to install your own GRUB, and then follow steps in **Using pre-installed GRUB**. to build and install your own GRUB, and then follow the steps described
earlier in `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 GRUB efi application:
.. code-block:: none .. code-block:: none
@ -139,9 +153,9 @@ Here we provide another simple method to build GRUB in efi application format:
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 directory, copy it to ``/EFI/boot/`` folder This will build a ``grub_x86_64.efi`` binary in the current directory, copy it to ``/EFI/boot/`` folder
on EFI partition. on the EFI partition (it is typically mounted under ``/boot/efi/`` folder on rootfs).
#. create ``/EFI/boot/grub.cfg`` file containing the following: #. Create ``/EFI/boot/grub.cfg`` file containing the following:
.. code-block:: none .. code-block:: none
@ -154,7 +168,7 @@ Here we provide another simple method to build GRUB in efi application format:
insmod part_gpt insmod part_gpt
insmod ext2 insmod ext2
echo 'Loading ACRN hypervisor ...' echo 'Loading ACRN hypervisor ...'
multiboot --quirk-modules-after-kernel /boot/acrn.32.out $(HV bootargs) $(SOS bootargs) multiboot --quirk-modules-after-kernel /boot/acrn.32.out $(HV bootargs) $(Service VM bootargs)
module /boot/kernel4vm0 xxxxxx $(VM0 bootargs) module /boot/kernel4vm0 xxxxxx $(VM0 bootargs)
module /boot/kernel4vm1 yyyyyy $(VM1 bootargs) module /boot/kernel4vm1 yyyyyy $(VM1 bootargs)
} }
@ -163,11 +177,11 @@ Here we provide another simple method to build GRUB in efi application format:
insmod part_gpt insmod part_gpt
insmod ext2 insmod ext2
echo 'Loading ACRN hypervisor ...' echo 'Loading ACRN hypervisor ...'
multiboot2 /boot/acrn.bin $(HV bootargs) $(SOS bootargs) multiboot2 /boot/acrn.bin $(HV bootargs) $(Service VM bootargs)
module2 /boot/kernel4vm0 xxxxxx $(VM0 bootargs) module2 /boot/kernel4vm0 xxxxxx $(VM0 bootargs)
module2 /boot/kernel4vm1 yyyyyy $(VM1 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/``; #. Copy ACRN binary and guest kernel images to the GRUB-configured folder, e.g. ``/boot/`` folder on ``/dev/sda3/``;
#. run ``/EFI/boot/grub_x86_64.efi`` in EFI shell. #. Run ``/EFI/boot/grub_x86_64.efi`` in the EFI shell.

65
doc/user-guides/hv-parameters.rst Normal file
View File

@ -0,0 +1,65 @@
.. _hv-parameters:
ACRN Hypervisor Parameters
##########################
Generic hypervisor parameters
*****************************
The ACRN hypervisor supports the following parameter:
+-----------------+-----------------------------+----------------------------------------------------------------------------------------+
| Parameter | Value | Description |
+=================+=============================+========================================================================================+
| | disabled | This disables the serial port completely. |
| +-----------------------------+----------------------------------------------------------------------------------------+
| uart= | bdf@<BDF value> | This sets the PCI serial port based on its BDF. e.g. bdf@0:18.1 |
| +-----------------------------+----------------------------------------------------------------------------------------+
| | port@<port address> | This sets the serial port address. |
+-----------------+-----------------------------+----------------------------------------------------------------------------------------+
The Generic hypervisor parameters are specified in the GRUB multiboot/multiboot2 command.
For example:
.. code-block:: none
:emphasize-lines: 5
menuentry 'Boot ACRN hypervisor from multiboot' {
insmod part_gpt
insmod ext2
echo 'Loading ACRN hypervisor ...'
multiboot --quirk-modules-after-kernel /boot/acrn.32.out uart=bdf@0:18.1
module /boot/bzImage Linux_bzImage
module /boot/bzImage2 Linux_bzImage2
}
For de-privilege mode, the parameters are specified in the ``efibootmgr -u`` command:
.. code-block:: none
:emphasize-lines: 2
$ sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN NUC Hypervisor" \
-u "uart=disabled"
De-privilege mode hypervisor parameters
***************************************
The de-privilege mode hypervisor parameters can only be specified in the efibootmgr command.
Currently we support the ``bootloader=`` parameter:
+-----------------+-------------------------------------------------+-------------------------------------------------------------------------+
| Parameter | Value | Description |
+=================+=================================================+=========================================================================+
| bootloader= | ``\EFI\org.clearlinux\bootloaderx64.efi`` | This sets the EFI executable to be loaded once the hypervisor is up |
| | | and running. This is typically the bootloader of the Service OS. |
| | | i.e. : ``\EFI\org.clearlinux\bootloaderx64.efi`` |
+-----------------+-------------------------------------------------+-------------------------------------------------------------------------+
For example:
.. code-block:: none
:emphasize-lines: 2
$ sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN NUC Hypervisor" \
-u "bootloader=\EFI\boot\bootloaderx64.efi"