mirror of
https://github.com/gnif/LookingGlass.git
synced 2024-11-09 16:18:20 +00:00
[doc] update and restructure installation documentation
This commit is contained in:
parent
eb31815b46
commit
4a4f72ba38
@ -132,6 +132,15 @@ Fetching with APT
|
||||
|
||||
You can fetch these dependencies with the following command:
|
||||
|
||||
.. warning::
|
||||
|
||||
Do not just blindly install the list below, check if you are using PipeWire
|
||||
or PulseAudio and adjust the list accordingly. Installing PipeWire libraries
|
||||
on a PulseAudio system will result in a broken partial PipeWire install.
|
||||
|
||||
If you are not already using PipeWire we highly recommend you upgrade,
|
||||
Looking Glass does not support audio input (microphone) with PulseAudio.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
apt-get install binutils-dev cmake fonts-dejavu-core libfontconfig-dev \
|
||||
|
@ -22,7 +22,7 @@ from lgrelease import release
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = 'Looking Glass'
|
||||
copyright = '2022, Looking Glass team'
|
||||
copyright = '2024, Looking Glass team'
|
||||
author = 'Geoffrey McRae and the Looking Glass team'
|
||||
|
||||
rst_prolog = """
|
||||
|
@ -11,9 +11,9 @@ systems for legacy programs that require high-performance graphics.
|
||||
:maxdepth: 2
|
||||
|
||||
requirements
|
||||
build
|
||||
install
|
||||
usage
|
||||
build
|
||||
troubleshooting
|
||||
obs
|
||||
module
|
||||
|
406
doc/install.rst
406
doc/install.rst
@ -3,406 +3,8 @@
|
||||
Installation
|
||||
############
|
||||
|
||||
.. _libvirt:
|
||||
.. toctree::
|
||||
|
||||
libvirt/QEMU configuration
|
||||
--------------------------
|
||||
|
||||
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_ivshmem:
|
||||
|
||||
IVSHMEM
|
||||
^^^^^^^
|
||||
|
||||
Configuration
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. note::
|
||||
If your host GPU is either AMD or Intel it is better to set this up using the
|
||||
KVMFR kernel module as this will allow you to make use of DMA transfers to
|
||||
offload some of the memory transfers to the GPU.
|
||||
See `VM->host` in :ref:`kernel_module`.
|
||||
|
||||
Add the following to your libvirt machine configuration inside the
|
||||
'devices' section by running ``virsh edit <VM>`` where ``<VM>`` is the name of
|
||||
your virtual machine.
|
||||
|
||||
.. code:: xml
|
||||
|
||||
<shmem name='looking-glass'>
|
||||
<model type='ivshmem-plain'/>
|
||||
<size unit='M'>32</size>
|
||||
</shmem>
|
||||
|
||||
.. note::
|
||||
If you are using QEMU directly without libvirt the following arguments are
|
||||
required instead.
|
||||
|
||||
Add the following to the commands to your QEMU command line, adjusting
|
||||
the ``bus`` parameter to suit your particular configuration:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
-device ivshmem-plain,memdev=ivshmem,bus=pcie.0 \
|
||||
-object memory-backend-file,id=ivshmem,share=on,mem-path=/dev/shm/looking-glass,size=32M
|
||||
|
||||
The memory size (show as 32 in the example above) may need to be
|
||||
adjusted as per the :ref:`Determining memory <libvirt_determining_memory>`
|
||||
section.
|
||||
|
||||
.. warning::
|
||||
If you change the size of this after starting your virtual machine you may
|
||||
need to remove the file `/dev/shm/looking-glass` to allow QEMU to re-create
|
||||
it with the correct size. If you do this the permissions of the file may be
|
||||
incorrect for your user to be able to access it and you will need to correct
|
||||
this. See :ref:`libvirt_shmfile_permissions`
|
||||
|
||||
.. _libvirt_determining_memory:
|
||||
|
||||
Determining memory
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You will need to adjust the memory size to be suitable for your desired maximum
|
||||
resolution, with the following formula:
|
||||
|
||||
.. code:: text
|
||||
|
||||
width x height x pixel size x 2 = frame bytes
|
||||
|
||||
frame bytes / 1024 / 1024 = frame megabytes
|
||||
|
||||
frame megabytes + 10 MiB = total megabytes
|
||||
|
||||
Where `pixel size` is 4 for 32-bit RGB (SDR) or 8 for 64-bit
|
||||
(HDR :ref:`* <libvirt_determining_memory_hdr>`).
|
||||
|
||||
Failure to do so 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.
|
||||
|
||||
For example, for a resolution of 1920x1080 (1080p):
|
||||
|
||||
.. code:: text
|
||||
|
||||
1920 x 1080 x 4 x 2 = 16,588,800 bytes
|
||||
|
||||
16,588,800 / 1024 / 1024 = 15.82 MiB
|
||||
|
||||
15.82 MiB + 10 MiB = 25.82 MiB
|
||||
|
||||
You must round this value up to the nearest power of two, which for the
|
||||
provided example is 32 MiB.
|
||||
|
||||
.. 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 should generally not be used unless you
|
||||
have a special reason to do so.
|
||||
|
||||
.. _libvirt_shmfile_permissions:
|
||||
|
||||
Permissions
|
||||
~~~~~~~~~~~
|
||||
|
||||
The shared memory file used by IVSHMEM is found in ``/dev/shm/looking-glass``.
|
||||
By default, it is owned by QEMU, and does not give read/write permissions to
|
||||
your user, which are required for Looking Glass to run properly.
|
||||
|
||||
You can use ``systemd-tmpfiles`` to create the file before running your VM,
|
||||
granting the necessary permissions which allow Looking Glass to use the file
|
||||
properly.
|
||||
|
||||
Create a new file ``/etc/tmpfiles.d/10-looking-glass.conf``, and populate it
|
||||
with the following::
|
||||
|
||||
# Type Path Mode UID GID Age Argument
|
||||
|
||||
f /dev/shm/looking-glass 0660 user kvm -
|
||||
|
||||
Change ``UID`` to the user name you will run Looking Glass with, usually your
|
||||
own.
|
||||
|
||||
.. _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.
|
||||
|
||||
Host application
|
||||
----------------
|
||||
|
||||
The Looking Glass Host application captures frames from the guest OS using a
|
||||
capture API, and sends them to the
|
||||
:ref:`client <client_install>`—be it on the host OS (hypervisor) or another
|
||||
Virtual Machine—through a low-latency transfer protocol over shared memory.
|
||||
|
||||
You can get the host program in two ways:
|
||||
|
||||
- Download a pre-built binary from https://looking-glass.io/downloads
|
||||
(**recommended**)
|
||||
|
||||
- Download the source code as described in :ref:`building`, then
|
||||
:ref:`build the host <host_building>`.
|
||||
|
||||
.. _host_install_linux:
|
||||
|
||||
For Linux
|
||||
^^^^^^^^^
|
||||
|
||||
While the host application can be compiled and is somewhat functional for Linux
|
||||
it is currently considered incomplete and not ready for usage. As such use at
|
||||
your own risk and do not ask for support.
|
||||
|
||||
.. _host_install_osx:
|
||||
|
||||
|
||||
For OSX
|
||||
^^^^^^^
|
||||
|
||||
Currently there is no support or plans for support for OSX due to technical
|
||||
limitations.
|
||||
|
||||
.. _host_install_windows:
|
||||
|
||||
For Windows
|
||||
^^^^^^^^^^^
|
||||
|
||||
To begin, you must first run the Windows VM with the changes noted above in
|
||||
either the :ref:`libvirt` section.
|
||||
|
||||
.. _installing_the_ivshmem_driver:
|
||||
|
||||
Installing the IVSHMEM driver
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Since B6 the host installer available on the official Looking Glass website
|
||||
comes with the IVSHMEM driver and will install this for you. If you are running
|
||||
an older version of Looking Glass please refer to the documentation for your
|
||||
version.
|
||||
|
||||
.. _host_install_service:
|
||||
|
||||
Installing the Looking Glass service
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
After installing your IVSHMEM driver, we can now install the Looking Glass Host
|
||||
onto our Windows Virtual Machine.
|
||||
|
||||
1. First, run ``looking-glass-host-setup.exe`` as an administrator
|
||||
(:ref:`Why? <faq_host_admin_privs>`)
|
||||
2. You will be greeted by an intro screen. Press ``Next`` to continue.
|
||||
3. You are presented with the |license| license. Please read and agree to the
|
||||
license by pressing ``Agree``.
|
||||
4. You can change the install path if you wish, otherwise press ``Next`` to
|
||||
continue.
|
||||
5. You may enable or disable options on this screen to configure the
|
||||
installation. The default values are recommended for most users.
|
||||
Press ``Install`` to begin installation.
|
||||
6. After a few moments, installation will complete, and you will have a
|
||||
running instance of Looking Glass. If you experience failures, you can
|
||||
see them in the install log appearing in the middle of the window.
|
||||
7. Press ``Close`` to exit the installer.
|
||||
|
||||
Command line users can run ``looking-glass-host-setup.exe /S`` to execute a
|
||||
silent install with default options selected. Further configuration from the
|
||||
command line can be done with flags. You can list all available flags by
|
||||
running ``looking-glass-host-setup.exe /?``.
|
||||
|
||||
.. _client_install:
|
||||
|
||||
Client application
|
||||
------------------
|
||||
|
||||
The Looking Glass client receives frames from the :ref:`host <host_install>` to
|
||||
display on your screen. It also handles input, and can optionally share the
|
||||
system clipboard with your guest OS through SPICE.
|
||||
|
||||
First you must build the client from source, see :ref:`building`. Once you have
|
||||
built the client, you can install it. Run the following as root::
|
||||
|
||||
make install
|
||||
|
||||
To install for the local user only, run::
|
||||
|
||||
cmake -DCMAKE_INSTALL_PREFIX=~/.local .. && make install
|
||||
install_libvirt
|
||||
install_host
|
||||
install_client
|
||||
|
22
doc/install_client.rst
Normal file
22
doc/install_client.rst
Normal file
@ -0,0 +1,22 @@
|
||||
.. _installing_client:
|
||||
|
||||
Client Application Installation
|
||||
###############################
|
||||
|
||||
.. _client_install:
|
||||
|
||||
For Linux
|
||||
---------
|
||||
|
||||
The Looking Glass client receives frames from the :ref:`host <host_install>` to
|
||||
display on your screen. It also handles input, and can optionally share the
|
||||
system clipboard with your guest OS through SPICE.
|
||||
|
||||
First you must build the client from source, see :ref:`building`. Once you have
|
||||
built the client, you can install it. Run the following as root::
|
||||
|
||||
make install
|
||||
|
||||
To install for the local user only, run::
|
||||
|
||||
cmake -DCMAKE_INSTALL_PREFIX=~/.local .. && make install
|
81
doc/install_host.rst
Normal file
81
doc/install_host.rst
Normal file
@ -0,0 +1,81 @@
|
||||
.. _installing_host:
|
||||
|
||||
Host Application Installation
|
||||
#############################
|
||||
|
||||
The Looking Glass Host application captures frames from the guest OS using a
|
||||
capture API, and sends them to the
|
||||
:ref:`client <client_install>`—be it on the host OS (hypervisor) or another
|
||||
Virtual Machine—through a low-latency transfer protocol over shared memory.
|
||||
|
||||
You can get the host program in two ways:
|
||||
|
||||
- Download a pre-built binary from https://looking-glass.io/downloads
|
||||
(**recommended**)
|
||||
|
||||
- Download the source code as described in :ref:`building`, then
|
||||
:ref:`build the host <host_building>`.
|
||||
|
||||
.. _host_install_linux:
|
||||
|
||||
For Linux
|
||||
^^^^^^^^^
|
||||
|
||||
While the host application can be compiled and is somewhat functional for Linux
|
||||
it is currently considered incomplete and not ready for usage. As such use at
|
||||
your own risk and do not ask for support.
|
||||
|
||||
.. _host_install_osx:
|
||||
|
||||
|
||||
For OSX
|
||||
^^^^^^^
|
||||
|
||||
Currently there is no support or plans for support for OSX due to technical
|
||||
limitations.
|
||||
|
||||
.. _host_install_windows:
|
||||
|
||||
For Windows
|
||||
^^^^^^^^^^^
|
||||
|
||||
To begin, you must first run the Windows VM with the changes noted above in
|
||||
either the :ref:`libvirt` section.
|
||||
|
||||
.. _installing_the_ivshmem_driver:
|
||||
|
||||
Installing the IVSHMEM driver
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Since B6 the host installer available on the official Looking Glass website
|
||||
comes with the IVSHMEM driver and will install this for you. If you are running
|
||||
an older version of Looking Glass please refer to the documentation for your
|
||||
version.
|
||||
|
||||
.. _host_install_service:
|
||||
|
||||
Installing the Looking Glass service
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
After installing your IVSHMEM driver, we can now install the Looking Glass Host
|
||||
onto our Windows Virtual Machine.
|
||||
|
||||
1. First, run ``looking-glass-host-setup.exe`` as an administrator
|
||||
(:ref:`Why? <faq_host_admin_privs>`)
|
||||
2. You will be greeted by an intro screen. Press ``Next`` to continue.
|
||||
3. You are presented with the |license| license. Please read and agree to the
|
||||
license by pressing ``Agree``.
|
||||
4. You can change the install path if you wish, otherwise press ``Next`` to
|
||||
continue.
|
||||
5. You may enable or disable options on this screen to configure the
|
||||
installation. The default values are recommended for most users.
|
||||
Press ``Install`` to begin installation.
|
||||
6. After a few moments, installation will complete, and you will have a
|
||||
running instance of Looking Glass. If you experience failures, you can
|
||||
see them in the install log appearing in the middle of the window.
|
||||
7. Press ``Close`` to exit the installer.
|
||||
|
||||
Command line users can run ``looking-glass-host-setup.exe /S`` to execute a
|
||||
silent install with default options selected. Further configuration from the
|
||||
command line can be done with flags. You can list all available flags by
|
||||
running ``looking-glass-host-setup.exe /?``.
|
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.
|
218
doc/ivshmem_kvmfr.rst
Normal file
218
doc/ivshmem_kvmfr.rst
Normal file
@ -0,0 +1,218 @@
|
||||
:orphan:
|
||||
.. _ivshmem_kvmfr:
|
||||
|
||||
IVSHMEM with the KVMFR module (Recommended)
|
||||
###########################################
|
||||
|
||||
The kernel module implements a basic interface to the IVSHMEM device
|
||||
for Looking Glass allowing DMA GPU transfers.
|
||||
|
||||
.. _ivshmem_kvmfr_prereq:
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
The Linux kernel headers for your kernel version are required for building.
|
||||
Install them with ``apt-get``
|
||||
|
||||
.. code:: bash
|
||||
|
||||
apt-get install linux-headers-$(uname -r)
|
||||
|
||||
Then switch to the ``module/`` directory
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cd module/
|
||||
|
||||
.. _ivshmem_kvmfr_dkms:
|
||||
|
||||
Using DKMS (recommended)
|
||||
------------------------
|
||||
|
||||
You can use the kernel's DKMS feature to keep the module across upgrades.
|
||||
``dkms`` must be installed.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
apt-get install dkms
|
||||
|
||||
.. _ivshmem_kvmfr_installing:
|
||||
|
||||
Installing
|
||||
~~~~~~~~~~
|
||||
|
||||
To install the module into DKMS, run
|
||||
|
||||
.. code:: bash
|
||||
|
||||
dkms install "."
|
||||
|
||||
.. _ivshmem_kvmfr_loading:
|
||||
|
||||
Loading
|
||||
~~~~~~~
|
||||
|
||||
Using the value you should have already calculated as per
|
||||
:ref:`Determining Memory <libvirt_determining_memory>`, simply use
|
||||
``modprobe`` with the parameter ``static_size_mb``, for example:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
modprobe kvmfr static_size_mb=32
|
||||
|
||||
Alternatively you can make this setting permanant by creating the file
|
||||
``/etc/modprobe.d/kvmfr.conf`` with the following content.
|
||||
|
||||
.. code:: text
|
||||
|
||||
options kvmfr static_size_mb=32
|
||||
|
||||
After this has been done, simply running ``modprobe kvmfr`` is all that is
|
||||
required.
|
||||
|
||||
.. note::
|
||||
|
||||
Don't forget to adjust ``static_size_mb`` to your needs.
|
||||
|
||||
.. _ivshmem_kvmfr_systemd:
|
||||
|
||||
systemd-modules-load
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For convenience, you may load the KVMFR module when starting your computer.
|
||||
We can use the ``systemd-modules-load.service(8)`` service for this task.
|
||||
|
||||
Create the file ``/etc/modules-load.d/kvmfr.conf`` with the following
|
||||
contents::
|
||||
|
||||
# KVMFR Looking Glass module
|
||||
kvmfr
|
||||
|
||||
This will now run the next time you start your machine.
|
||||
|
||||
.. _ivshmem_kvmfr_verification:
|
||||
|
||||
Verification
|
||||
~~~~~~~~~~~~
|
||||
|
||||
If everything has been done correctly you should see the following output in
|
||||
dmesg:
|
||||
|
||||
.. code:: text
|
||||
|
||||
kvmfr: creating 1 static devices
|
||||
|
||||
You should now also have the character device ``/dev/kvmfr0``
|
||||
|
||||
.. warning::
|
||||
|
||||
If you start the VM prior to loading the module, QEMU will create the file
|
||||
``/dev/kvmfr0`` as a regular file. You can confirm if this has happened by
|
||||
running ``ls -l /dev/kvmfr0`` and checking if the filesize is greater then
|
||||
zero, or the permissions do not start with ``c``. If this has occured, you
|
||||
must delete the file and reload the module.
|
||||
|
||||
.. _ivhsmem_kvmfr_permissions:
|
||||
|
||||
Permissions
|
||||
~~~~~~~~~~~
|
||||
|
||||
The module will create the ``/dev/kvmfr0`` node, which represents the KVMFR
|
||||
interface. To use the interface, you need permission to access it by either
|
||||
creating a udev rule to ensure your user can read and write to it, or simply
|
||||
change its ownership manually, i.e.:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo chown user:user /dev/kvmfr0
|
||||
|
||||
As an example, you can create a new file in ``/etc/udev/rules.d/99-kvmfr.rules``
|
||||
with the following contents::
|
||||
|
||||
SUBSYSTEM=="kvmfr", OWNER="user", GROUP="kvm", MODE="0660"
|
||||
|
||||
(replace ``user`` with your username)
|
||||
|
||||
.. _ivshmem_kvmfr_libvirt:
|
||||
|
||||
libvirt
|
||||
^^^^^^^
|
||||
|
||||
Starting with QEMU 6.2 and libvirt 7.9, JSON style QEMU configuration is the
|
||||
default syntax. Users running QEMU 6.2 or later **and** libvirt 7.9 or later,
|
||||
should use this XML block to configure their VM for kvmfr:
|
||||
|
||||
.. code:: xml
|
||||
|
||||
<qemu:commandline>
|
||||
<qemu:arg value='-device'/>
|
||||
<qemu:arg value='{"driver":"ivshmem-plain","id":"shmem0","memdev":"looking-glass"}'/>
|
||||
<qemu:arg value='-object'/>
|
||||
<qemu:arg value='{"qom-type":"memory-backend-file","id":"looking-glass","mem-path":"/dev/kvmfr0","size":33554432,"share":true}'/>
|
||||
</qemu:commandline>
|
||||
|
||||
.. note::
|
||||
|
||||
- The ``"size"`` tag represents the size of the shared memory device in
|
||||
bytes. Once you determine the proper size of the device as per
|
||||
:ref:`Determining Memory <libvirt_determining_memory>`, use the figure you
|
||||
got to calculate the size in bytes:
|
||||
|
||||
``size_in_MB x 1024 x 1024 = size_in_bytes``
|
||||
|
||||
If you are running QEMU older than 6.2 or libvirt older than 7.9, please use
|
||||
legacy syntax for IVSHMEM setup:
|
||||
|
||||
.. code:: xml
|
||||
|
||||
<qemu:commandline>
|
||||
<qemu:arg value='-device'/>
|
||||
<qemu:arg value='ivshmem-plain,id=shmem0,memdev=looking-glass'/>
|
||||
<qemu:arg value='-object'/>
|
||||
<qemu:arg value='memory-backend-file,id=looking-glass,mem-path=/dev/kvmfr0,size=32M,share=yes'/>
|
||||
</qemu:commandline>
|
||||
|
||||
.. note::
|
||||
|
||||
- Using the legacy syntax on QEMU 6.2/libvirt 7.9 may cause QEMU to
|
||||
abort with the following error message:
|
||||
"``error: internal error: ... PCI: slot 1 function 0 not available for pcie-root-port, in use by ivshmem-plain``"
|
||||
|
||||
- Remember to add ``xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'``
|
||||
to the ``<domain>`` tag.
|
||||
|
||||
Running libvirt this way violates AppArmor and cgroups policies, which will
|
||||
block the VM from running. These policies must be amended to allow the VM
|
||||
to start:
|
||||
|
||||
- For AppArmor, create ``/etc/apparmor.d/local/abstractions/libvirt-qemu`` if
|
||||
it doesn't exist, and add the following::
|
||||
|
||||
# Looking Glass
|
||||
/dev/kvmfr0 rw,
|
||||
|
||||
- For cgroups, edit ``/etc/libvirt/qemu.conf``, uncomment the
|
||||
``cgroup_device_acl`` block, and add ``/dev/kvmfr0`` to the list.
|
||||
Then restart ``libvirtd``:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo systemctl restart libvirtd.service
|
||||
|
||||
.. _ivshmem_kvmfr_qemu:
|
||||
|
||||
QEMU
|
||||
^^^^
|
||||
|
||||
If you are using QEMU directly without libvirt, add the following arguments to your
|
||||
``qemu`` command line::
|
||||
|
||||
-device ivshmem-plain,id=shmem0,memdev=looking-glass
|
||||
-object memory-backend-file,id=looking-glass,mem-path=/dev/kvmfr0,size=32M,share=yes
|
||||
|
||||
.. note::
|
||||
|
||||
The ``size`` argument must be the same size you passed
|
||||
to the ``static_size_mb`` argument when loading the kernel module.
|
||||
|
66
doc/ivshmem_shm.rst
Normal file
66
doc/ivshmem_shm.rst
Normal file
@ -0,0 +1,66 @@
|
||||
:orphan:
|
||||
.. _ivshmem_shm:
|
||||
|
||||
IVSHMEM with standard shared memory
|
||||
###################################
|
||||
|
||||
This method is here for those that can not use the KVMFR kernel module. Please
|
||||
be aware that as a result you will not be able to take advantage of your GPUs
|
||||
abillity to access memory via it's hardware DMA engine if you use this method.
|
||||
|
||||
Add the following to your libvirt machine configuration inside the
|
||||
'devices' section by running ``virsh edit <VM>`` where ``<VM>`` is the name of
|
||||
your virtual machine.
|
||||
|
||||
.. code:: xml
|
||||
|
||||
<shmem name='looking-glass'>
|
||||
<model type='ivshmem-plain'/>
|
||||
<size unit='M'>32</size>
|
||||
</shmem>
|
||||
|
||||
.. note::
|
||||
If you are using QEMU directly without libvirt the following arguments are
|
||||
required instead.
|
||||
|
||||
Add the following to the commands to your QEMU command line, adjusting
|
||||
the ``bus`` parameter to suit your particular configuration:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
-device ivshmem-plain,memdev=ivshmem,bus=pcie.0 \
|
||||
-object memory-backend-file,id=ivshmem,share=on,mem-path=/dev/shm/looking-glass,size=32M
|
||||
|
||||
The memory size (show as 32 in the example above) may need to be
|
||||
adjusted as per the :ref:`Determining memory <libvirt_determining_memory>`
|
||||
section.
|
||||
|
||||
.. warning::
|
||||
If you change the size of this after starting your virtual machine you may
|
||||
need to remove the file `/dev/shm/looking-glass` to allow QEMU to re-create
|
||||
it with the correct size. If you do this the permissions of the file may be
|
||||
incorrect for your user to be able to access it and you will need to correct
|
||||
this. See :ref:`libvirt_shmfile_permissions`
|
||||
|
||||
.. _libvirt_shmfile_permissions:
|
||||
|
||||
Permissions
|
||||
~~~~~~~~~~~
|
||||
|
||||
The shared memory file used by IVSHMEM is found in ``/dev/shm/looking-glass``.
|
||||
By default, it is owned by QEMU, and does not give read/write permissions to
|
||||
your user, which are required for Looking Glass to run properly.
|
||||
|
||||
You can use ``systemd-tmpfiles`` to create the file before running your VM,
|
||||
granting the necessary permissions which allow Looking Glass to use the file
|
||||
properly.
|
||||
|
||||
Create a new file ``/etc/tmpfiles.d/10-looking-glass.conf``, and populate it
|
||||
with the following::
|
||||
|
||||
# Type Path Mode UID GID Age Argument
|
||||
|
||||
f /dev/shm/looking-glass 0660 user kvm -
|
||||
|
||||
Change ``UID`` to the user name you will run Looking Glass with, usually your
|
||||
own.
|
Loading…
Reference in New Issue
Block a user