diff --git a/doc/develop.rst b/doc/develop.rst index d1959687a..ee93d7d81 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -66,6 +66,7 @@ Advanced Features tutorials/cpu_sharing tutorials/sriov_virtualization tutorials/gpu-passthru + tutorials/enable_multiple_displays tutorials/run_kata_containers tutorials/rtvm_workload_design_guideline tutorials/acrn_on_qemu diff --git a/doc/tutorials/enable_multiple_displays.rst b/doc/tutorials/enable_multiple_displays.rst new file mode 100644 index 000000000..6cbc7967d --- /dev/null +++ b/doc/tutorials/enable_multiple_displays.rst @@ -0,0 +1,96 @@ +.. _enable_multiple_displays: + +Enable User VMs with Multiple Displays +###################################### + +A VM may want to run an OS with a graphical desktop or provide an application +with a human-machine interface (HMI) display. You can enable a graphical display by +using virtio GPU. + +Virtio GPU lets a VM present multiple windowed virtual displays on the physical +monitor. Virtio GPU also allows multiple VMs to share the same physical +display, for example, where the service VM has a Linux desktop window and a +Windows-based User VM has its desktop in a window on the same physical monitor. + +Virtio GPU is a virtio-based graphics adapter that provides a VM with one or +more virtual displays that show on the Service VM's monitor in either windowed +or borderless full screen mode. + +In ACRN, virtio GPU operates in 2D mode only and does not support offloading +rendering operations to a physical GPU. To do that, you must enable SR-IOV of +the physical GPU and passthrough one virtual function (VF) to each VM requiring +a virtual display. + +Dependencies and Constraints +**************************** + +Consider the following dependencies and constraints: + +* Virtio GPU only works with post-launched standard (non real-time) VMs. +* Virtio GPU works best with virtual functions (VFs) of the physical GPUs. + Without the VFs, the post-launched VM must use CPU rendering. +* Virtio GPU allows virtualizing multiple displays for one VM. All displays must + operate in the same mode, either windowed or borderless Full screen. In either + mode, virtio GPU supports at most two virtual displays per VM. +* The hosting Service VM's OS needs to work in graphical mode (instead of the + command line mode). + +.. note:: The virtio GPU mechanism performs best with Single Root I/O + Virtualization (SR-IOV) so that frames can be rendered by SR-IOV VF and + displayed by virtio GPU. Without SR-IOV support on your hardware platform (and + enabled in the BIOS settings), the VM can still render frames using the CPU, but + this is typically less efficient. + +Configuration Overview +********************** + +Use the :ref:`acrn_configurator_tool` to configure virtio GPU in the +post-launched User VM's basic parameters: + + +.. image:: images/virtio-gpu-device-01.png + :align: center + :class: drop-shadow + +Click on the ``+`` to define a new virtio-GPU device. From there you can choose +between a ``window`` or a borderless``full screen`` display for this device. + +.. image:: images/virtio-gpu-device-02.png + :align: center + :class: drop-shadow + +If you select ``window`` you can then choose the size of the window (from a +list), and the window's top-left corner offset (in pixels) from the top-left +corner of the screen, as shown in the following example. + +Configuration Example +********************* + +The following steps show how to select and verify a virtio GPU device by +extending the information provided in the :ref:`gsg`. + +1. In the ACRN Configurator, update the shared scenario you created with a + Service VM and one post-launched User VM by adding these virtio-GPU settings + to the User VM. + + Open the "POST_STD_VM1" -> "Basic Parameters" and scroll down to the "virtio + GPU device" settings. Click on the "+" to create a new virtual display + device and fill out the display settings: + + .. image:: images/virtio-gpu-device-03.png + :align: center + :class: drop-shadow + + In this example, we selected a window device (instead of a full screen + device) with a 1920x1080 size, and with the top-left corner 100 pixels down + and to the right of the (Service VM) display's top-left corner. + +#. Save the scenario and launch script. +#. Follow the :ref:`gsg` instructions to build ACRN and copy all the + necessary files from the development computer to the target system. +#. Reboot the target system to launch the Service VM and use the launch script + to start the post-launched User VM. + +Unlike in the original Getting Started Guide, this time when the Post-launched +User VM starts Ubuntu, the login screen uses the virtio GPU display in a +windowed area instead of being full screen. diff --git a/doc/tutorials/images/virtio-gpu-device-01.png b/doc/tutorials/images/virtio-gpu-device-01.png new file mode 100644 index 000000000..993dee7d4 Binary files /dev/null and b/doc/tutorials/images/virtio-gpu-device-01.png differ diff --git a/doc/tutorials/images/virtio-gpu-device-02.png b/doc/tutorials/images/virtio-gpu-device-02.png new file mode 100644 index 000000000..a7d9e0a66 Binary files /dev/null and b/doc/tutorials/images/virtio-gpu-device-02.png differ diff --git a/doc/tutorials/images/virtio-gpu-device-03.png b/doc/tutorials/images/virtio-gpu-device-03.png new file mode 100644 index 000000000..8fb3b7373 Binary files /dev/null and b/doc/tutorials/images/virtio-gpu-device-03.png differ