diff --git a/doc/develop.rst b/doc/develop.rst index 2092f947b..dc6894c8f 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -23,6 +23,8 @@ User VM Tutorials .. toctree:: :maxdepth: 1 + tutorials/user_vm_guide + tutorials/using_ubuntu_as_user_vm tutorials/using_windows_as_user_vm tutorials/using_xenomai_as_user_vm tutorials/using_vxworks_as_user_vm diff --git a/doc/introduction/index.rst b/doc/introduction/index.rst index 5b6f1e65e..3ad056041 100644 --- a/doc/introduction/index.rst +++ b/doc/introduction/index.rst @@ -170,6 +170,8 @@ stopping, and pausing a VM, and pausing or resuming a virtual CPU. See the :ref:`hld-overview` developer reference material for more in-depth information. +.. _static-configuration-scenarios: + Static Configuration Based on Scenarios *************************************** @@ -290,6 +292,7 @@ can define your own configuration scenarios. The :ref:`acrn_configuration_tool` tutorial explains how to use the ACRN Configurator to create your own scenario, or to view and modify an existing one. +.. _dm_architecture_intro: ACRN Device Model Architecture ****************************** @@ -399,7 +402,6 @@ including Xen, KVM, and ACRN hypervisor. In most cases, the User VM OS must be compiled to support passthrough by using kernel build-time options. -.. _static-conmbfiguration-scenarios: Boot Sequence diff --git a/doc/tutorials/images/ubuntu-uservm-0.png b/doc/tutorials/images/ubuntu-uservm-0.png new file mode 100644 index 000000000..bfcf98d0a Binary files /dev/null and b/doc/tutorials/images/ubuntu-uservm-0.png differ diff --git a/doc/tutorials/images/ubuntu-uservm-1.png b/doc/tutorials/images/ubuntu-uservm-1.png new file mode 100644 index 000000000..763a26527 Binary files /dev/null and b/doc/tutorials/images/ubuntu-uservm-1.png differ diff --git a/doc/tutorials/images/ubuntu-uservm-2.png b/doc/tutorials/images/ubuntu-uservm-2.png new file mode 100644 index 000000000..307c5a7c2 Binary files /dev/null and b/doc/tutorials/images/ubuntu-uservm-2.png differ diff --git a/doc/tutorials/images/ubuntu-uservm-3.png b/doc/tutorials/images/ubuntu-uservm-3.png new file mode 100644 index 000000000..627258489 Binary files /dev/null and b/doc/tutorials/images/ubuntu-uservm-3.png differ diff --git a/doc/tutorials/images/ubuntu-uservm-4.png b/doc/tutorials/images/ubuntu-uservm-4.png new file mode 100644 index 000000000..a67f9948e Binary files /dev/null and b/doc/tutorials/images/ubuntu-uservm-4.png differ diff --git a/doc/tutorials/images/ubuntu-uservm-5.png b/doc/tutorials/images/ubuntu-uservm-5.png new file mode 100644 index 000000000..a57235add Binary files /dev/null and b/doc/tutorials/images/ubuntu-uservm-5.png differ diff --git a/doc/tutorials/images/ubuntu_uservm_01.png b/doc/tutorials/images/ubuntu_uservm_01.png new file mode 100644 index 000000000..9e97fbf92 Binary files /dev/null and b/doc/tutorials/images/ubuntu_uservm_01.png differ diff --git a/doc/tutorials/images/ubuntu_uservm_02.png b/doc/tutorials/images/ubuntu_uservm_02.png new file mode 100644 index 000000000..a1d889178 Binary files /dev/null and b/doc/tutorials/images/ubuntu_uservm_02.png differ diff --git a/doc/tutorials/images/ubuntu_uservm_03.png b/doc/tutorials/images/ubuntu_uservm_03.png new file mode 100644 index 000000000..10b5ff13d Binary files /dev/null and b/doc/tutorials/images/ubuntu_uservm_03.png differ diff --git a/doc/tutorials/images/ubuntu_uservm_begin_install.png b/doc/tutorials/images/ubuntu_uservm_begin_install.png new file mode 100644 index 000000000..8365c6286 Binary files /dev/null and b/doc/tutorials/images/ubuntu_uservm_begin_install.png differ diff --git a/doc/tutorials/images/ubuntu_uservm_customize.png b/doc/tutorials/images/ubuntu_uservm_customize.png new file mode 100644 index 000000000..2e78103ff Binary files /dev/null and b/doc/tutorials/images/ubuntu_uservm_customize.png differ diff --git a/doc/tutorials/images/ubuntu_uservm_storage.png b/doc/tutorials/images/ubuntu_uservm_storage.png new file mode 100644 index 000000000..d808e5686 Binary files /dev/null and b/doc/tutorials/images/ubuntu_uservm_storage.png differ diff --git a/doc/tutorials/images/ubuntu_uservm_virtioblock.png b/doc/tutorials/images/ubuntu_uservm_virtioblock.png new file mode 100644 index 000000000..8d0cabaaf Binary files /dev/null and b/doc/tutorials/images/ubuntu_uservm_virtioblock.png differ diff --git a/doc/tutorials/images/vm-guide-create-new-scenario.png b/doc/tutorials/images/vm-guide-create-new-scenario.png new file mode 100644 index 000000000..f03ed0dc8 Binary files /dev/null and b/doc/tutorials/images/vm-guide-create-new-scenario.png differ diff --git a/doc/tutorials/images/vm-guide-image-virtio-block.png b/doc/tutorials/images/vm-guide-image-virtio-block.png new file mode 100644 index 000000000..f4e90c987 Binary files /dev/null and b/doc/tutorials/images/vm-guide-image-virtio-block.png differ diff --git a/doc/tutorials/images/vm-guide-set-vm-basic-parameters.png b/doc/tutorials/images/vm-guide-set-vm-basic-parameters.png new file mode 100644 index 000000000..69cf8a9ad Binary files /dev/null and b/doc/tutorials/images/vm-guide-set-vm-basic-parameters.png differ diff --git a/doc/tutorials/user_vm_guide.rst b/doc/tutorials/user_vm_guide.rst new file mode 100644 index 000000000..abd487ab1 --- /dev/null +++ b/doc/tutorials/user_vm_guide.rst @@ -0,0 +1,186 @@ +.. _user_vm_guide: + +User VM Guide +############# + +The ACRN hypervisor uses a Linux-based Service VM and can run User VMs +simultaneously, providing a powerful software platform to build complex +computing systems. A User VM can run a variety of OSs including Linux or +Windows, or an RTOS such as Zephyr or VxWorks. As shown in the :ref:`gsg`, +you use the ACRN Configurator to define options used to build the static +configuration of your ACRN system based on your system design, available +capabilities of your target hardware, and performance characteristics such as +those required for real-time needs. The Configurator also lets you define +dynamic settings for launching User VMs and specifying the resources they need +access to. + +ACRN provides a framework called the :ref:`ACRN Device Model +<dm_architecture_intro>`, for sharing physical system resources and providing +virtual device emulation with rich I/O mediators. The Device Model also +supports non-emulated device passthrough access to satisfy time-sensitive +requirements and low-latency access needs of real-time applications. + +In this and accompanying documents, we provide guidance for configuring and +deploying post-launched User VMs, and additional information about OS-specific +settings based on your User VM OS choice. We also show how to configure the +system for accessing virtual devices emulated by the ACRN Device Model or +passthrough resources dedicated to a specific VM. + +ACRN also supports pre-launched User VMs, with dedicated resources that are not +shared with other VMs. Pre-launched VMs are configured statically using the +Configurator, with their own boot devices, CPU, memory, and other system +resources. We'll discuss pre-launched VMs separately. + + +User VM OS Choices +****************** + +ACRN has no restrictions on what OS is used by a User VM. The ACRN team has +tested Standard User VMs running Ubuntu 20.04 and Windows 10, and real-time User +VMs running Zephyr, VxWorks, Xenomai, and Linux VMs running on a +PREEMPT_RT-patched kernel. + +The ACRN Service VM and its Device Model run on Ubuntu 20.04 using a patched +kernel built from the `acrn-kernel GitHub repository +<https://github.com/projectacrn/acrn-kernel>`_. The Service VM can access +hardware resources directly by running native drivers and provides device +sharing services to post-launched User VMs. The Service VM is not dependent on +any settings in your User VM configuration and is used for both Standard and +Real-time post-launched User VMs. The Service VM is not used by pre-launched +User VMs. + +Configuration Overview +********************** + +In the following sections, we provide general guidance and then link to +OS-specific guidance documents based on your choice of User VM OS. + +Separately, and out of scope for this document, you'll need to create a combined +application and User VM OS image for each User VM. + +The ACRN Device Model within the Service VM starts your User VM image using a +launch script created by the ACRN Configurator, based on the settings you +provided. These settings include the location on the target system storage +device for that image, User VM memory size, console, vUART settings for +communication, virtual I/O devices your application uses, and more. Available +launch script options are documented in the :ref:`acrn-dm_parameters` and the +:ref:`scenario-config-options` documentation. We'll also provide examples for +selected capabilities in our OS-specific guidance. + +This guide assumes you've already followed the Getting Started Guide and have +followed steps to prepare the development computer and installed development +system prerequisites, prepared the target and generated a board configuration +file, and have installed the ACRN Configurator. + +Using the ACRN Configurator +=========================== + +Independent of your User VM OS choice, run the ACRN Configurator and create a +scenario with a Post-launched VM for each User VM you will be running. We use +one Ubuntu-based User VM in this overview: + +.. figure:: images/vm-guide-create-new-scenario.png + :align: center + :width: 600px + :name: vm-guide-create-new-scenario + :class: drop-shadow + + Creating a new scenario in the Configurator + +Use the Configurator to give the VM a name, and define configuration options +specific for this VM, such as memory and VM type (Standard or Real-time): + +.. figure:: images/vm-guide-set-vm-basic-parameters.png + :align: center + :width: 600px + :name: vm-guide-set-vm-basic-parameters + :class: drop-shadow + + Set VM basic configuration options + +And define where the User VM image will be on the target system (in this +example, an Ubuntu 20.04 desktop ISO image): + +.. figure:: images/vm-guide-image-virtio-block.png + :align: center + :width: 600px + :name: vm-guide-image-virtio-block + :class: drop-shadow + + Set VM image using virtio block device + +After the configuration settings are to your liking, save the configuration. +When saving, the ACRN Configurator first validates your scenario configuration and +reports any issues that need your attention. If successful, it writes out the +updated scenario XML file and launch script to your working directory. You'll +use this launch script to start the User VM on the target. + +Rebuild the ACRN Hypervisor +=========================== + +After exiting the ACRN Configurator, build the ACRN hypervisor (based on the static +configuration parameters in your scenario) on your development computer, as was +done in the :ref:`gsg`:: + + cd ~/acrn-work/acrn-hypervisor + make clean && make BOARD=~/acrn-work/MyConfiguration/my_board.board.xml SCENARIO=~/acrn-work/MyConfiguration/scenario.xml + +The build typically takes a few minutes. When done, the build generates a Debian +package in the ``./build`` directory. + +This Debian package contains the ACRN hypervisor and tools to ease installing ACRN on the target. + +Transfer Files to the Target, Install, and Reboot +================================================= + +We'll need to get the Debian package containing the hypervisor files we built to +the target system, along with the launch scripts and User VM images. In the +:ref:`gsg`, we used a USB stick, but you could also use the network to copy +files using ``scp``. Install the Debian package and reboot to run ACRN and the +Service VM. Then use the launch script to start each User VM. + +User VM Persistence +******************* + +In the :ref:`gsg` (and in the previous overview), we used a standard Ubuntu +20.04 ISO image as our User VM image. By its nature, an ISO image is read-only. +This means that when you reboot the ACRN system, any changes you made to the +User VM such as installing a new package, would be lost; the unmodified ISO +image is used again for the User VM when the system is rebooted. While this +could be the usage model you'd like, an alternative is to set up the User VM +image as read-write so it will retain any changes made while it was running and +return to that state after a reboot. + +One way to create a persistent VM image is by using KVM to define virtual disk +partitions, boot the underlying OS, add additional packages and even an +application to that image, and then save and convert that QCOW2 image to a raw +format we can use with ACRN. + +In separate companion documentation, we provide detail guides for running +User VMs with different OSs, and provide considerations for each of those +standard and real-time OS configurations. + +Standard VM OS Considerations +***************************** + +Here is a list of Standard User VM OS guides with details and topics to consider +when using one of these OSs: + +* :ref:`using_ubuntu_as_user_vm` +* :ref:`using_windows_as_user_vm` + +Real-time VM OS Considerations +****************************** + +Here is a list of real-time User VM OS guides with details and topics to consider +when using one of these OSs: + +* :ref:`using_xenomai_as_user_vm` +* :ref:`using_vxworks_as_user_vm` +* :ref:`using_zephyr_as_user_vm` + +We also recommend reading these RTVM performance guides: + +* :ref:`rtvm_workload_guideline` +* :ref:`rt_perf_tips_rtvm` +* :ref:`rt_performance_tuning` diff --git a/doc/tutorials/using_ubuntu_as_user_vm.rst b/doc/tutorials/using_ubuntu_as_user_vm.rst new file mode 100644 index 000000000..7d578a547 --- /dev/null +++ b/doc/tutorials/using_ubuntu_as_user_vm.rst @@ -0,0 +1,158 @@ +.. _using_ubuntu_as_user_vm: + +Run Ubuntu as the User VM OS +############################ + +Prerequisites +************* + +.. _Ubuntu 20.04 desktop ISO: + http://releases.ubuntu.com/focal/ubuntu-20.04.4-desktop-amd64.iso + +This tutorial assumes you have already set up the ACRN Service VM on your target +system following the instructions in the :ref:`gsg`. + +Install these KVM tools on your development system: + +.. code-block:: none + + sudo apt install qemu-kvm libvirt-clients libvirt-daemon-system bridge-utils virt-manager ovmf + +Validated Versions +================== + +- **Ubuntu version:** 20.04 +- **ACRN hypervisor tag:** v3.0 +- **Service VM Kernel version:** release_3.0 + +.. _build-the-ubuntu-kvm-image: + +Build the Ubuntu KVM Image +************************** + +This tutorial uses the Ubuntu 20.04 desktop ISO as the base image. + +#. Download the `Ubuntu 20.04 desktop ISO`_ on your development machine: + +#. Install Ubuntu via the virt-manager tool: + + .. code-block:: none + + sudo virt-manager + +#. Verify that you can see the main menu as shown in :numref:`vmmanager-ubun` below. + + .. figure:: images/ubuntu_uservm_01.png + :align: center + :name: vmmanager-ubun + :class: drop-shadow + + Virtual Machine Manager + +#. Right-click **QEMU/KVM** and select **New**. + + a. Choose **Local install media (ISO image or CD-ROM)** and then click + **Forward**. + + .. figure:: images/ubuntu_uservm_02.png + :align: center + :name: vmmanager-local-install + :class: drop-shadow + + Choosing Local install media + + A **Create a new virtual machine** box displays. Click **Browse** and + select the Ubuntu ISO file that you downloaded earlier. + If not already auto selected, choose the **OS type:** Linux, **Version:** + Ubuntu 20.04 LTS and then click **Forward**. + + .. figure:: images/ubuntu_uservm_03.png + :align: center + :name: newVM-ubun-image + :class: drop-shadow + + Select Ubuntu ISO file previously downloaded + + #. Choose **Enable storage** and **Create a disk image for the virtual machine**. + Set the storage to 20 GB or more if necessary and click **Forward**. + + .. figure:: images/ubuntu_uservm_storage.png + :align: center + :name: newVM-ubun-storage + :class: drop-shadow + + Select VM disk storage + + #. Rename the image if you desire. Check the + **customize configuration before install** option before you finish all stages. + + .. figure:: images/ubuntu_uservm_customize.png + :align: center + :name: newVM-ubun-customize + :class: drop-shadow + + Ready to customize image + +#. Verify the Firmware and Chipset settings are as shown in this Overview screen: + + .. figure:: images/ubuntu_uservm_begin_install.png + :align: center + :name: ubun-begin-install + :class: drop-shadow + + Ready to begin installation + +#. Click **Apply** and **Begin Installation** (in the top left corner). Complete + the normal Ubuntu installation within the QEMU emulator. Verify that you have + set up the disk partition as follows: + + - /dev/vda1: EFI System Partition + - /dev/vda2: File System Partition + +#. Upon installation completion, click **Restart** Now to make sure the Ubuntu + OS boots successfully. Save the QEMU state and exit. + +#. The KVM image is created in the ``/var/lib/libvirt/images`` folder. + Convert the ``qcow2`` format to ``img`` **as the root user**: + + .. code-block:: none + + cd ~ && mkdir ubuntu_images && cd ubuntu_images + sudo qemu-img convert -f qcow2 -O raw /var/lib/libvirt/images/ubuntu20.04.qcow2 ubuntu_uservm.img + + +Launch the Ubuntu Image as the User VM +************************************** + +In the :ref:`gsg`, we used the ACRN configurator to create a scenario with a +Service VM and an Ubuntu **ISO** image for the post-launched User VM. We can use +that same scenario with a slight edit for the User VM image name by changing +the file name in the Virtio block device for the post-launched User VM. + +1. Change the virtio block device to use the new Ubuntu image we created using + KVM above: + + .. figure:: images/ubuntu_uservm_virtioblock.png + :align: center + :name: ubun-virtio-block + :class: drop-shadow + + Update virtio block device with image location + + Then save this new configuration and write out the updated launch script. + +#. Copy the ``ubuntu_uservm.img`` and the updated launch script from the + development system to your target system. For example, if the development + and target systems are on the same network, you could use ``scp``: + + .. code-block:: none + + scp ~/ubuntu_images/ubuntu_uservm.img ~/acrn-work/MyConfiguration/launch_user_vm_id1.sh user_name@ip_address:~/acrn-work/ + +#. On the target system, launch the Ubuntu User VM after logging in to the Service VM: + + .. code-block:: none + + cd ~/acrn-work + sudo launch_user_vm_id1.sh + diff --git a/doc/tutorials/using_vxworks_as_user_vm.rst b/doc/tutorials/using_vxworks_as_user_vm.rst index b570d5215..b2ecae1b2 100644 --- a/doc/tutorials/using_vxworks_as_user_vm.rst +++ b/doc/tutorials/using_vxworks_as_user_vm.rst @@ -1,8 +1,8 @@ .. _using_vxworks_as_uos: .. _using_vxworks_as_user_vm: -Run VxWorks as the User VM -########################## +Run VxWorks as the User RTVM OS +############################### `VxWorks`_\* is a real-time proprietary OS designed for use in embedded systems requiring real-time, deterministic performance. This tutorial describes how to run VxWorks as the User VM on the ACRN hypervisor diff --git a/doc/tutorials/using_windows_as_user_vm.rst b/doc/tutorials/using_windows_as_user_vm.rst index ef33c647f..394c7d95d 100644 --- a/doc/tutorials/using_windows_as_user_vm.rst +++ b/doc/tutorials/using_windows_as_user_vm.rst @@ -1,10 +1,10 @@ .. _using_windows_as_uos: .. _using_windows_as_user_vm: -Launch Windows as the Guest VM on ACRN -###################################### +Run Windows as the User VM OS +############################# -This tutorial describes how to launch Windows as a Guest (WaaG) VM on the +This tutorial describes how to launch Windows as a Guest (WaaG) User VM on the ACRN hypervisor. diff --git a/doc/tutorials/using_xenomai_as_user_vm.rst b/doc/tutorials/using_xenomai_as_user_vm.rst index 93327986f..444e77ce2 100644 --- a/doc/tutorials/using_xenomai_as_user_vm.rst +++ b/doc/tutorials/using_xenomai_as_user_vm.rst @@ -1,8 +1,8 @@ .. _using_xenomai_as_uos: .. _using_xenomai_as_user_vm: -Run Xenomai as the User VM OS (Real-Time VM) -############################################ +Run Xenomai as the User RTVM OS +############################### `Xenomai`_ is a versatile real-time framework that provides support to user space applications that are seamlessly integrated into Linux environments. diff --git a/doc/tutorials/using_zephyr_as_user_vm.rst b/doc/tutorials/using_zephyr_as_user_vm.rst index 31853c6fd..1bc60a693 100644 --- a/doc/tutorials/using_zephyr_as_user_vm.rst +++ b/doc/tutorials/using_zephyr_as_user_vm.rst @@ -1,8 +1,8 @@ .. _using_zephyr_as_uos: .. _using_zephyr_as_user_vm: -Run Zephyr as the User VM -######################### +Run Zephyr as the User RTVM OS +############################## This tutorial describes how to run Zephyr as the User VM on the ACRN hypervisor. We are using Kaby Lake-based Intel NUC (model NUC7i5DNHE) in this tutorial.