mirror of
https://github.com/gnif/LookingGlass.git
synced 2025-11-29 12:48:16 +00:00
[doc] update and restructure installation documentation
This commit is contained in:
Geoffrey McRae
255
doc/install_libvirt.rst
Normal file
255
doc/install_libvirt.rst
Normal file
@@ -0,0 +1,255 @@
|
||||
.. _installing_libvirt:
|
||||
|
||||
libvirt/QEMU Installation
|
||||
#########################
|
||||
|
||||
This article assumes you already have a fully functional `libvirt` domain with
|
||||
PCI passthrough working. If you use `virt-manager`, this guide also applies to
|
||||
you, since virt-manager uses `libvirt` as its back end.
|
||||
|
||||
.. _libvirt_determining_memory:
|
||||
|
||||
Determining memory
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You will first need to calculate the memory size to be suitable for your desired
|
||||
maximum resolution using the following formula:
|
||||
|
||||
.. math::
|
||||
|
||||
\text{WIDTH} \times \text{HEIGHT} \times \text{BPP} \times 2 = \text{frame size in bytes}
|
||||
|
||||
\text{frame size in bytes} \div 1024 \div 1024 = \text{ frame size in MiB}
|
||||
|
||||
\text{frame size in MiB} + 10 = \text{ required size in MiB}
|
||||
|
||||
2^{\lceil \log_2(\text {required size in MiB}) \rceil} = \text{ total MiB}
|
||||
|
||||
Where `BPP` is 4 for 32-bit RGB (SDR) or 8 for 64-bit
|
||||
(HDR :ref:`* <libvirt_determining_memory_hdr>`).
|
||||
|
||||
.. hint::
|
||||
The final step in this calculation is simply rounding the value up to the
|
||||
nearest power of two.
|
||||
|
||||
For example, for a resolution of 1920x1080 (1080p) SDR:
|
||||
|
||||
.. math::
|
||||
|
||||
1920 \times 1080 \times 4 \times 2 = 16,588,800 \text{ bytes}
|
||||
|
||||
16,588,800 \div 1024 \div 1024 = 15.82 \text{ MiB}
|
||||
|
||||
15.82 \text{ MiB} + 10 \text{ MiB} = 25.82 \text{ MiB}
|
||||
|
||||
2^{\lceil \log_2(25.82) \rceil} = 32 \text { MiB}
|
||||
|
||||
|
||||
Failure to provide enough memory will cause Looking Glass to truncate the
|
||||
bottom of the screen and will trigger a message popup to inform you of the size
|
||||
you need to increase the value to.
|
||||
|
||||
.. note::
|
||||
Increasing this value beyond what you need does not yield any performance
|
||||
improvements, it simply will block access to that RAM making it unusable by
|
||||
your system.
|
||||
|
||||
.. list-table:: Common Values
|
||||
:widths: 50 25 25
|
||||
:header-rows: 1
|
||||
|
||||
* - Resolution
|
||||
- Standard Dynamic Range
|
||||
- High Dynamic Range (HDR) :ref:`* <libvirt_determining_memory_hdr>`
|
||||
* - 1920x1080 (1080p)
|
||||
- 32
|
||||
- 64
|
||||
* - 1920x1200 (1200p)
|
||||
- 32
|
||||
- 64
|
||||
* - 2560x1440 (1440p)
|
||||
- 64
|
||||
- 128
|
||||
* - 3840x2160 (2160p/4K)
|
||||
- 128
|
||||
- 256
|
||||
|
||||
.. _libvirt_determining_memory_hdr:
|
||||
|
||||
.. warning::
|
||||
While Looking Glass can capture and display HDR, at the time of writing
|
||||
neither Xorg or Wayland can make use of it and it will be converted by the
|
||||
GPU drivers/hardware to SDR. Additionally using HDR doubles the amount of
|
||||
memory, bandwidth, and CPU load and as such should generally not be used
|
||||
unless you have a special reason to do so.
|
||||
|
||||
.. _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 performace as it allows
|
||||
Looking Glass to use your GPUs DMA engine to transfer the frame data.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
ivshmem_kvmfr
|
||||
ivshmem_shm
|
||||
|
||||
|
||||
.. _libvirt_spice_server:
|
||||
|
||||
Keyboard/mouse/display/audio
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Looking Glass makes use of the SPICE protocol to provide keyboard and mouse
|
||||
input, audio input and output, and display fallback.
|
||||
|
||||
.. note::
|
||||
The default configuration that libvirt uses is not optimal and must be
|
||||
adjusted. Failure to perform these changes will cause input issues along
|
||||
with failure to support 5 button mice.
|
||||
|
||||
If you would like to use SPICE to give you keyboard and mouse input
|
||||
along with clipboard sync support, make sure you have a
|
||||
``<graphics type='spice'>`` device, then:
|
||||
|
||||
- Find your ``<video>`` device, and set ``<model type='vga'/>``
|
||||
|
||||
- If you can't find it, make sure you have a ``<graphics>``
|
||||
device, save and edit again.
|
||||
|
||||
- Remove the ``<input type='tablet'/>`` device, if you have one.
|
||||
- Create an ``<input type='mouse' bus='virtio'/>`` device, if you don't
|
||||
already have one.
|
||||
- Create an ``<input type='keyboard' bus='virtio'/>`` device to improve
|
||||
keyboard usage.
|
||||
|
||||
.. note::
|
||||
Be sure to install the the *vioinput* driver from
|
||||
`virtio-win <https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/>`_
|
||||
in the guest
|
||||
|
||||
To enable audio support add a standard Intel HDA audio device to your
|
||||
configuration as per below:
|
||||
|
||||
.. code:: xml
|
||||
|
||||
<sound model='ich9'>
|
||||
<audio id='1'/>
|
||||
</sound>
|
||||
<audio id='1' type='spice'/>
|
||||
|
||||
If you also want clipboard synchronization please see
|
||||
:ref:`libvirt_clipboard_synchronization`
|
||||
|
||||
.. _libvirt_clipboard_synchronization:
|
||||
|
||||
Clipboard synchronization
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Looking Glass can synchronize the clipboard between the host and guest using
|
||||
the SPICE guest agent.
|
||||
|
||||
1. Install the SPICE guest tools from
|
||||
https://www.spice-space.org/download.html#windows-binaries.
|
||||
|
||||
2. Configure your VM to enable the SPICE guest agent:
|
||||
|
||||
- QEMU
|
||||
|
||||
.. code:: bash
|
||||
|
||||
-device virtio-serial-pci \
|
||||
-chardev spicevmc,id=vdagent,name=vdagent \
|
||||
-device virtserialport,chardev=vdagent,name=com.redhat.spice.0
|
||||
|
||||
- libvirt
|
||||
|
||||
.. code:: xml
|
||||
|
||||
<channel type="spicevmc">
|
||||
<target type="virtio" name="com.redhat.spice.0"/>
|
||||
<address type="virtio-serial" controller="0" bus="0" port="1"/>
|
||||
</channel>
|
||||
<!-- No need to add a VirtIO Serial device, it will be added automatically -->
|
||||
|
||||
.. _libvirt_apparmor:
|
||||
|
||||
AppArmor
|
||||
^^^^^^^^
|
||||
|
||||
For libvirt versions before **5.10.0**, if you are using AppArmor, you
|
||||
need to add permissions for QEMU to access the shared memory file. This
|
||||
can be done by adding the following to
|
||||
``/etc/apparmor.d/local/abstractions/libvirt-qemu``::
|
||||
|
||||
/dev/shm/looking-glass rw,
|
||||
|
||||
then, restart AppArmor.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo systemctl restart apparmor
|
||||
|
||||
.. _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
|
||||
|
||||
<memballoon model="none"/>
|
||||
|
||||
.. _host_install:
|
||||
|
||||
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
|
||||
but be sure that 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. Just because your GPU is in a slot that is physically x16 in size, does not
|
||||
mean your GPU is running at x16, this is dependent on how your motherboard
|
||||
is physically wired and the physical slot may be limited to x4 or x8.
|
||||
|
||||
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. AMD users be sure that you have the CPU feature flag `topoext` enabled or
|
||||
your guest operating system will not be aware of which CPU cores are
|
||||
hyper-thread pairs.
|
||||
|
||||
7. NVIDIA users may want to enable NvFBC as an alternative capture API in the
|
||||
guest. Note that NvFBC is officially available on professional cards only
|
||||
and methods to enable NvFBC on non-supported GPUs is against the NVIDIA
|
||||
Capture API SDK License Agreement even though GeForce Experience and
|
||||
Steam make use of it on any NVIDIA GPU.
|
||||
|
||||
How to perform these changes is left as an exercise to the reader.
|
||||
Reference in New Issue
Block a user