1.. _enable_multiple_displays:
2
3Enable User VMs with Multiple Displays
4######################################
5
6A VM may want to run an OS with a graphical desktop or provide an application
7with a human-machine interface (HMI) display. You can enable a graphical display by
8using virtio GPU.
9
10Virtio GPU lets a VM present multiple windowed virtual displays on the physical
11monitor.  Virtio GPU also allows multiple VMs to share the same physical
12display, for example, where the service VM has a Linux desktop window and a
13Windows-based User VM has its desktop in a window on the same physical monitor.
14
15Virtio GPU is a virtio-based graphics adapter that provides a VM with one or
16more virtual displays that show on the Service VM's monitor in either windowed
17or borderless full screen mode.
18
19In ACRN, virtio GPU operates in 2D mode only and does not support offloading
20rendering operations to a physical GPU. To do that, you must enable SR-IOV of
21the physical GPU and passthrough one virtual function (VF) to each VM requiring
22a virtual display.
23
24Dependencies and Constraints
25****************************
26
27Consider the following dependencies and constraints:
28
29* Virtio GPU only works with post-launched standard (non real-time) VMs.
30* Virtio GPU works best with virtual functions (VFs) of the physical GPUs.
31  Without the VFs, the post-launched VM must use CPU rendering.
32* Virtio GPU allows virtualizing multiple displays for one VM. All displays must
33  operate in the same mode, either windowed or borderless Full screen.  In either
34  mode, virtio GPU supports at most two virtual displays per VM.
35* The hosting Service VM's OS needs to work in graphical mode (instead of the
36  command line mode).
37
38.. note:: The virtio GPU mechanism performs best with Single Root I/O
39   Virtualization (SR-IOV) so that frames can be rendered by SR-IOV VF and
40   displayed by virtio GPU. Without SR-IOV support on your hardware platform (and
41   enabled in the BIOS settings), the VM can still render frames using the CPU, but
42   this is typically less efficient.
43
44Configuration Overview
45**********************
46
47Use the :ref:`acrn_configurator_tool` to configure virtio GPU in the
48post-launched User VM's basic parameters:
49
50
51.. image:: images/virtio-gpu-device-01.png
52   :align: center
53   :class: drop-shadow
54
55Click on the ``+`` to define a new virtio-GPU device.  From there you can choose
56between a ``window`` or a borderless``full screen`` display for this device.
57
58.. image:: images/virtio-gpu-device-02.png
59   :align: center
60   :class: drop-shadow
61
62If you select ``window`` you can then choose the size of the window (from a
63list), and the window's top-left corner offset (in pixels) from the top-left
64corner of the screen, as shown in the following example.
65
66Configuration Example
67*********************
68
69The following steps show how to select and verify a virtio GPU device by
70extending the information provided in the :ref:`gsg`.
71
721. In the ACRN Configurator, update the shared scenario you created with a
73   Service VM and one post-launched User VM by adding these virtio-GPU settings
74   to the User VM.
75
76   Open the "POST_STD_VM1" -> "Basic Parameters" and scroll down to the "virtio
77   GPU device" settings.  Click on the "+" to create a new virtual display
78   device and fill out the display settings:
79
80   .. image:: images/virtio-gpu-device-03.png
81      :align: center
82      :class: drop-shadow
83
84   In this example, we selected a window device (instead of a full screen
85   device) with a 1920x1080 size, and with the top-left corner 100 pixels down
86   and to the right of the (Service VM) display's top-left corner.
87
88#. Save the scenario and launch script.
89#. Follow the :ref:`gsg` instructions to build ACRN and copy all the
90   necessary files from the development computer to the target system.
91#. Reboot the target system to launch the Service VM and use the launch script
92   to start the post-launched User VM.
93
94Unlike in the original Getting Started Guide, this time when the Post-launched
95User VM starts Ubuntu, the login screen uses the virtio GPU display in a
96windowed area instead of being full screen.
97