github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-07-17 08:51:42 +00:00
Code Issues Projects Releases Wiki Activity

doc: terminology cleanup in acrn_on_qemu.rst

Browse Source 
- Replace SOS with Service 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-22 10:20:59 -07:00 committed by David Kinder
parent 8d109003a1
commit 8d572e7319
1 changed files with 71 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
doc/tutorials/acrn_on_qemu.rst
View File

@ -3,26 +3,29 @@
Enable ACRN Over QEMU/KVM Enable ACRN Over QEMU/KVM
######################### #########################
Goal of this document is to bring-up ACRN as a nested Hypervisor on top of QEMU/KVM This document shows how to bring up ACRN as a nested hypervisor on top of
with basic functionality such as running Service VM (SOS) and User VM (UOS) for primarily 2 reasons, QEMU/KVM with basic functionality such as running a Service VM and User VM for
primarily two reasons:
1. Allow users to evaluate ACRN. 1. Enable users to evaluate ACRN.
2. Make ACRN platform agnostic and remove hardware-specific platform configurations setup overhead. 2. Make ACRN platform agnostic and remove the overhead of setting up
hardware-specific platform configurations.
This setup was tested with the following configuration, This setup was tested with the following configuration:
- ACRN Hypervisor: ``v2.6`` tag - ACRN hypervisor: ``v2.6`` tag
- ACRN Kernel: ``v2.6`` tag - ACRN kernel: ``v2.6`` tag
- QEMU emulator version 4.2.1 - QEMU emulator version: 4.2.1
- Service VM/User VM is Ubuntu 20.04 - Service VM/User VM OS: Ubuntu 20.04
- Platforms Tested: Kaby Lake, Skylake - Platforms tested: Kaby Lake, Skylake
Prerequisites Prerequisites
************* *************
1. Make sure the platform supports Intel VMX as well as VT-d 1. Make sure the platform supports Intel VMX as well as VT-d
technologies. On Ubuntu 20.04, this technologies. On Ubuntu 20.04, this
can be checked by installing ``cpu-checker`` tool. If the can be checked by installing the ``cpu-checker`` tool. If the
output displays **KVM acceleration can be used** output displays **KVM acceleration can be used**,
the platform supports it. the platform supports it.
.. code-block:: none .. code-block:: none
@ -45,7 +48,8 @@ Prerequisites
Prepare Service VM (L1 Guest) Prepare Service VM (L1 Guest)
***************************** *****************************
1. Use ``virt-install`` command to create Service VM.
1. Use the ``virt-install`` command to create the Service VM.
.. code-block:: none .. code-block:: none
@ -67,20 +71,22 @@ Prepare Service VM (L1 Guest)
#. Walk through the installation steps as prompted. Here are a few things to note: #. Walk through the installation steps as prompted. Here are a few things to note:
a. Make sure to install an OpenSSH server so that once the installation is complete, we can SSH into the system. a. Make sure to install an OpenSSH server so that once the installation is
complete, you can SSH into the system.
.. figure:: images/acrn_qemu_1.png .. figure:: images/acrn_qemu_1.png
:align: center :align: center
b. We use Grub to boot ACRN, so make sure you install it when prompted. b. We use GRUB to boot ACRN, so make sure you install it when prompted.
.. figure:: images/acrn_qemu_2.png .. figure:: images/acrn_qemu_2.png
:align: center :align: center
c. The Service VM (guest) will be restarted once the installation is complete. c. After the installation is complete, the Service VM (guest) will restart.
#. Login to the Service VM guest. Find the IP address of the guest and use it to connect #. Log in to the Service VM guest. Find the IP address of the guest and use it
via SSH. The IP address can be retrieved using the ``virsh`` command as shown below. to connect via SSH. The IP address can be retrieved using the ``virsh``
command as shown below.
.. code-block:: console .. code-block:: console
@ -97,8 +103,8 @@ Prepare Service VM (L1 Guest)
sudo systemctl enable serial-getty@ttyS0.service sudo systemctl enable serial-getty@ttyS0.service
sudo systemctl start serial-getty@ttyS0.service sudo systemctl start serial-getty@ttyS0.service
#. Enable the Grub menu to choose between Ubuntu and the ACRN hypervisor. #. Enable the GRUB menu to choose between Ubuntu and the ACRN hypervisor.
Modify :file:`/etc/default/grub` and edit below entries, Modify :file:`/etc/default/grub` and edit these entries:
.. code-block:: none .. code-block:: none
@ -107,25 +113,27 @@ Prepare Service VM (L1 Guest)
GRUB_CMDLINE_LINUX_DEFAULT="" GRUB_CMDLINE_LINUX_DEFAULT=""
GRUB_GFXMODE=text GRUB_GFXMODE=text
#. The Service VM guest can also be launched again later using ``virsh start ACRNSOS --console``. #. The Service VM guest can also be launched again later using
Make sure to use the domain name you used while creating the VM in case it is different than ``ACRNSOS``. ``virsh start ACRNSOS --console``. Make sure to use the domain name you used
while creating the VM in case it is different than ``ACRNSOS``.
This concludes the initial configuration of the Service VM, the next steps will install ACRN in it. This concludes the initial configuration of the Service VM. The next steps will
install ACRN in it.
.. _install_acrn_hypervisor: .. _install_acrn_hypervisor:
Install ACRN Hypervisor Install ACRN Hypervisor
*********************** ***********************
1. Launch the ``ACRNSOS`` Service VM guest and log onto it (SSH is recommended but the console is 1. Launch the ``ACRNSOS`` Service VM guest and log into it (SSH is recommended
available too). but the console is available too).
.. important:: All the steps below are performed **inside** the Service VM guest that we built in the .. important:: All the steps below are performed **inside** the Service VM
previous section. guest that we built in the previous section.
#. Install the ACRN build tools and dependencies following the :ref:`gsg` #. Install the ACRN build tools and dependencies following the :ref:`gsg`.
#. Clone ACRN repo and check out the ``v2.6`` tag. #. Clone the ACRN repo and check out the ``v2.6`` tag.
.. code-block:: none .. code-block:: none
@ -134,15 +142,15 @@ Install ACRN Hypervisor
cd acrn-hypervisor cd acrn-hypervisor
git checkout v2.6 git checkout v2.6
#. Build ACRN for QEMU, #. Build ACRN for QEMU:
.. code-block:: none .. code-block:: none
make BOARD=qemu SCENARIO=sdc make BOARD=qemu SCENARIO=sdc
For more details, refer to :ref:`gsg`. For more details, refer to the :ref:`gsg`.
#. Install the ACRN Device Model and tools #. Install the ACRN Device Model and tools:
.. code-block:: .. code-block::
@ -154,13 +162,13 @@ Install ACRN Hypervisor
sudo cp build/hypervisor/acrn.32.out /boot sudo cp build/hypervisor/acrn.32.out /boot
#. Clone and configure the Service VM kernel repository following the instructions at #. Clone and configure the Service VM kernel repository following the
:ref:`gsg` and using the ``v2.6`` tag. The User VM (L2 guest) instructions in the :ref:`gsg` and using the ``v2.6`` tag. The User VM (L2
uses the ``virtio-blk`` driver to mount the rootfs. This driver is included in the default guest) uses the ``virtio-blk`` driver to mount the rootfs. This driver is
kernel configuration as of the ``v2.6`` tag. included in the default kernel configuration as of the ``v2.6`` tag.
#. Update Grub to boot the ACRN hypervisor and load the Service VM kernel. Append the following #. Update GRUB to boot the ACRN hypervisor and load the Service VM kernel.
configuration to the :file:`/etc/grub.d/40_custom`. Append the following configuration to the :file:`/etc/grub.d/40_custom`.
.. code-block:: none .. code-block:: none
@ -177,9 +185,13 @@ Install ACRN Hypervisor
module /boot/bzImage Linux_bzImage module /boot/bzImage Linux_bzImage
} }
#. Update Grub: ``sudo update-grub``. #. Update GRUB:
#. Enable networking for the User VMs .. code-block:: none
sudo update-grub
#. Enable networking for the User VMs:
.. code-block:: none .. code-block:: none
@ -187,16 +199,17 @@ Install ACRN Hypervisor
sudo systemctl start systemd-networkd sudo systemctl start systemd-networkd
#. Shut down the guest and relaunch it using ``virsh start ACRNSOS --console``. #. Shut down the guest and relaunch it using ``virsh start ACRNSOS --console``.
Select the ``ACRN hypervisor`` entry from the Grub menu. Select the ``ACRN hypervisor`` entry from the GRUB menu.
.. note:: .. note::
You may occasionnally run into the following error: ``Assertion failed in file You may occasionally run into the following error: ``Assertion failed in
arch/x86/vtd.c,line 256 : fatal error`` occasionally. This is a transient issue, file arch/x86/vtd.c,line 256 : fatal error``. This is a transient issue,
try to restart the VM when that happens. If you need a more stable setup, you try to restart the VM when that happens. If you need a more stable setup,
can work around the problem by switching your native host to a non-graphical you can work around the problem by switching your native host to a
environment (``sudo systemctl set-default multi-user.target``). non-graphical environment (``sudo systemctl set-default
multi-user.target``).
#. Verify that you are now running ACRN using ``dmesg``. #. Use ``dmesg`` to verify that you are now running ACRN.
.. code-block:: console .. code-block:: console
@ -207,30 +220,33 @@ Install ACRN Hypervisor
[ 2.727905] systemd[1]: Set hostname to <ACRNSOS>. [ 2.727905] systemd[1]: Set hostname to <ACRNSOS>.
.. note:: .. note::
When shutting down the Service VM, make sure to cleanly destroy it with these commands, When shutting down the Service VM, make sure to cleanly destroy it with
to prevent crashes in subsequent boots. these commands, to prevent crashes in subsequent boots.
.. code-block:: none .. code-block:: none
virsh destroy ACRNSOS # where ACRNSOS is the virsh domain name. virsh destroy ACRNSOS # where ACRNSOS is the virsh domain name.
Bring-Up User VM (L2 Guest) Bring Up User VM (L2 Guest)
*************************** ***************************
1. Build the User VM disk image (``UserVM.img``) following :ref:`build-the-ubuntu-kvm-image` and copy it to the ACRNSOS (L1 Guest). 1. Build the User VM disk image (``UserVM.img``) following
Alternatively you can also use an `Ubuntu Desktop ISO image <https://ubuntu.com/#download>`_. :ref:`build-the-ubuntu-kvm-image` and copy it to the Service VM (L1 guest).
Alternatively you can also use an
`Ubuntu Desktop ISO image <https://ubuntu.com/#download>`_.
Rename the downloaded ISO image to ``UserVM.iso``. Rename the downloaded ISO image to ``UserVM.iso``.
#. Transfer the ``UserVM.img`` or ``UserVM.iso`` User VM disk image to the Service VM (L1 guest). #. Transfer the ``UserVM.img`` or ``UserVM.iso`` User VM disk image to the
Service VM (L1 guest).
#. Launch User VM using the ``launch_ubuntu.sh`` script. #. Launch the User VM using the ``launch_ubuntu.sh`` script.
.. code-block:: none .. code-block:: none
cp ~/acrn-hypervisor/misc/config_tools/data/samples_launch_scripts/launch_ubuntu.sh ~/ cp ~/acrn-hypervisor/misc/config_tools/data/samples_launch_scripts/launch_ubuntu.sh ~/
cp ~/acrn-hypervisor/devicemodel/bios/OVMF.fd ~/ cp ~/acrn-hypervisor/devicemodel/bios/OVMF.fd ~/
#. Update the script to use your disk image (``UserVM.img or ``UserVM.iso``). #. Update the script to use your disk image (``UserVM.img`` or ``UserVM.iso``).
.. code-block:: none .. code-block:: none