doc: User VM guide

Create a new User VM OS guide with overview information about setting up
User VMs.  Link to separate standard and RTVM guide for details. Most of
these separate guides need updating to reflect the new ACRN configurator and
the development system/target system development model.

Update titles of existing "using XXX as user vm" to be consistent.

Begin update of ubuntu uservm doc for direction review.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

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

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

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`

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
+

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

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.
 
 

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.
 

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.