LookingGlass/doc/install_libvirt.rst

.. _installing_libvirt:

libvirt/QEMU Installation
#########################

This article assumes you already have a working `libvirt` Windows virtual
machine. It also applies to users of `virt-manager`, because `virt-manager` uses
`libvirt` as its back end. A passed-through or virtual GPU is strongly
recommended, but the IDD can start in software mode without one.

.. _libvirt_determining_memory:

Determining memory
^^^^^^^^^^^^^^^^^^

The IVSHMEM size is calculated as:

.. math::

  B &= 3h\left(256\left\lceil\frac{4w}{256}\right\rceil\right)
     + (4 \cdot {1024}^2) \\
  M &= 2^{\left\lceil\log_2 B\right\rceil - 20}

where

* :math:`w` is the desired resolution width;
* :math:`h` is the desired resolution height;
* :math:`B` is the required amount of bytes; and
* :math:`M` is the required amount of bytes in MiB, rounded up to a power of
  two.

You may use the following Python script as a substitute:

.. code-block:: python

  import math

  w = int(input("Width: "))
  h = int(input("Height: "))

  B = 3 * h * (256 * math.ceil(4 * w / 256)) + 4 * 1024**2
  M = 2 ** (math.ceil(math.log2(B)) - 20)

  print(f"IVSHMEM size should be set to {M} MiB")

If a configured mode does not fit, the IDD omits it from the Windows mode list.
If a client-requested dynamic resolution does not fit, the helper refuses it
and reports the minimum power-of-two size to configure. The IDD will not serve a
truncated frame.

.. note::
   Increasing this value beyond what you need does not improve performance, it
   only reserves more host RAM for the VM.

.. list-table:: Common IDD values (already rounded)
   :widths: 50 50
   :header-rows: 1

   * - Maximum resolution
     - Total IVSHMEM size (MiB)
   * - 1920x1080 (1080p)
     - 32
   * - 1920x1200
     - 32
   * - 2560x1440 (1440p)
     - 64
   * - 3440x1440
     - 64
   * - 3840x2160 (4K)
     - 128
   * - 5120x1440
     - 128
   * - 5120x2880 (5K)
     - 256
   * - 7680x4320 (8K)
     - 512

.. _libvirt_determining_memory_hdr:

.. admonition:: HDR Requirements

   HDR uses the same 32-bit IDD transport allocation as SDR, so it does not
   double the IVSHMEM requirement. Native Linux HDR presentation has separate
   compositor and display requirements; see :ref:`client_hdr`.

.. _libvirt_ivshmem:

IVSHMEM
^^^^^^^

There are two methods of configuring IVSHMEM, using shared memory directly, or
using the KVMFR kernel module. While the KVMFR module is slightly more
complicated to configure, it substantially improves performance as it allows
Looking Glass to use your GPUs DMA engine to transfer the frame data.

.. toctree::
   :maxdepth: 1

   ivshmem_kvmfr
   ivshmem_shm

.. seealso::

   :ref:`igpu_kvmfr_recommended`


.. _libvirt_spice_server:

SPICE server
^^^^^^^^^^^^

The Looking Glass client presents a USB audio device to the guest through SPICE
USB redirection, and SPICE is therefore required. See :ref:`client_usb_audio`
for more information.

The Looking Glass client also supports SPICE for video, audio, and input if
there is a problem with the Looking Glass IDD. However, this is no faster than
other SPICE clients like virt-viewer, and should only be used as a fallback when
troubleshooting, not daily use.

To enable SPICE support, add a SPICE graphics server to your virtual machine:

.. code:: xml

   <devices>
     <graphics type='spice'/>
   </devices>

For a fallback display, set up your video device to use VGA:

.. code:: xml

   <devices>
     <video>
       <model type="vga"/>
     </video>
   </devices>

For fallback audio support, add a standard Intel HDA audio device:

.. code:: xml

   <devices>
     <sound model='ich9'>
        <audio id='1'/>
     </sound>
     <audio id='1' type='spice'/>
   </devices>

.. _libvirt_memballoon_tweak:

Memballoon
^^^^^^^^^^

The VirtIO memballoon device enables the host to dynamically reclaim memory
from your VM by growing the balloon inside the guest, reserving reclaimed
memory. Libvirt adds this device to guests by default.

However, this device causes major performance issues with VFIO passthrough
setups, and should be disabled.

Find the ``<memballoon>`` tag and set its type to ``none``:

.. code:: xml

   <devices>
     <memballoon model="none"/>
   </devices>

.. _libvirt_additional_tuning:

Additional tuning
^^^^^^^^^^^^^^^^^

Looking Glass is latency sensitive and as such it may suffer microstutters if
you have not properly tuned your virtual machine. The physical display output of
your GPU will usually not show such issues due to the nature of the hardware.
However, if you are experiencing issues, the following tuning is required to
obtain optimal performance.

1. Do not assign all your CPU cores to your guest VM, you must at minimum
   reserve two CPU cores (4 threads) for your host system to use. For example,
   if you have a 6 core CPU, only assign 4 cores (8 threads) to the guest.

2. Ensure you correctly pin your VMs vCPU threads to the correct cores for your
   CPU architecture.

3. If you are on a NUMA architecture (dual CPU, or early Threadripper) be sure
   that you pin the vCPU threads to the physical CPU/die attached to your GPU.

4. Get familiar with your specific motherboard's PCIe slots. Larger physical
   slots (for example x16) may only operate at a slower speed (like x8),
   depending on your motherboard's layout.

5. Be sure to set your CPU model type to `host-passthrough` so that your guest
   operating system is aware of the acceleration features of your CPU and can
   make full use of them.

6. For users of AMD CPUs, enable the `topoext` feature flag to inform the guest
   operating system of your CPU's hyper-threading core pairs.