mirror of
https://github.com/gnif/LookingGlass.git
synced 2024-12-22 13:52:57 +00:00
[doc] update and restructure installation documentation
This commit is contained in:
Geoffrey McRae
parent
eb31815b46
commit
4a4f72ba38
9 changed files with 657 additions and 404 deletions
|
|
@ -132,6 +132,15 @@ Fetching with APT
|
||||||
|
|
||||||
You can fetch these dependencies with the following command:
|
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
|
.. code:: bash
|
||||||
|
|
||||||
apt-get install binutils-dev cmake fonts-dejavu-core libfontconfig-dev \
|
apt-get install binutils-dev cmake fonts-dejavu-core libfontconfig-dev \
|
||||||
|
|
|
||||||
|
|
@ -22,7 +22,7 @@ from lgrelease import release
|
||||||
# -- Project information -----------------------------------------------------
|
# -- Project information -----------------------------------------------------
|
||||||
|
|
||||||
project = 'Looking Glass'
|
project = 'Looking Glass'
|
||||||
copyright = '2022, Looking Glass team'
|
copyright = '2024, Looking Glass team'
|
||||||
author = 'Geoffrey McRae and the Looking Glass team'
|
author = 'Geoffrey McRae and the Looking Glass team'
|
||||||
|
|
||||||
rst_prolog = """
|
rst_prolog = """
|
||||||
|
|
|
||||||
|
|
@ -11,9 +11,9 @@ systems for legacy programs that require high-performance graphics.
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
requirements
|
requirements
|
||||||
|
build
|
||||||
install
|
install
|
||||||
usage
|
usage
|
||||||
build
|
|
||||||
troubleshooting
|
troubleshooting
|
||||||
obs
|
obs
|
||||||
module
|
module
|
||||||
|
|
|
||||||
406
doc/install.rst
406
doc/install.rst
|
|
@ -3,406 +3,8 @@
|
||||||
Installation
|
Installation
|
||||||
############
|
############
|
||||||
|
|
||||||
.. _libvirt:
|
.. toctree::
|
||||||
|
|
||||||
libvirt/QEMU configuration
|
install_libvirt
|
||||||
--------------------------
|
install_host
|
||||||
|
install_client
|
||||||
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
|
|
||||||
|
|
|
||||||
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 a new issue