From 4a4f72ba38b57bee01dae336909bf2e4a9ed4b59 Mon Sep 17 00:00:00 2001
From: Geoffrey McRae <geoff@hostfission.com>
Date: Fri, 8 Mar 2024 18:22:07 +1100
Subject: [PATCH] [doc] update and restructure installation documentation

---
 doc/build.rst           |   9 +
 doc/conf.py             |   2 +-
 doc/index.rst           |   2 +-
 doc/install.rst         | 406 +---------------------------------------
 doc/install_client.rst  |  22 +++
 doc/install_host.rst    |  81 ++++++++
 doc/install_libvirt.rst | 255 +++++++++++++++++++++++++
 doc/ivshmem_kvmfr.rst   | 218 +++++++++++++++++++++
 doc/ivshmem_shm.rst     |  66 +++++++
 9 files changed, 657 insertions(+), 404 deletions(-)
 create mode 100644 doc/install_client.rst
 create mode 100644 doc/install_host.rst
 create mode 100644 doc/install_libvirt.rst
 create mode 100644 doc/ivshmem_kvmfr.rst
 create mode 100644 doc/ivshmem_shm.rst

diff --git a/doc/build.rst b/doc/build.rst
index 799beea9..d6b8717d 100644
--- a/doc/build.rst
+++ b/doc/build.rst
@@ -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 \
diff --git a/doc/conf.py b/doc/conf.py
index 879dcd9a..90371259 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -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 = """
diff --git a/doc/index.rst b/doc/index.rst
index 1726cbff..918d2341 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -11,9 +11,9 @@ systems for legacy programs that require high-performance graphics.
    :maxdepth: 2
 
    requirements
+   build
    install
    usage
-   build
    troubleshooting
    obs
    module
diff --git a/doc/install.rst b/doc/install.rst
index ca85f5b3..750f3d1f 100644
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -3,406 +3,8 @@
 Installation
 ############
 
-.. _libvirt:
-
-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
+.. toctree::
    
-  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
diff --git a/doc/install_client.rst b/doc/install_client.rst
new file mode 100644
index 00000000..63284f22
--- /dev/null
+++ b/doc/install_client.rst
@@ -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
diff --git a/doc/install_host.rst b/doc/install_host.rst
new file mode 100644
index 00000000..e35cc2c5
--- /dev/null
+++ b/doc/install_host.rst
@@ -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 /?``.
diff --git a/doc/install_libvirt.rst b/doc/install_libvirt.rst
new file mode 100644
index 00000000..a9519622
--- /dev/null
+++ b/doc/install_libvirt.rst
@@ -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.
diff --git a/doc/ivshmem_kvmfr.rst b/doc/ivshmem_kvmfr.rst
new file mode 100644
index 00000000..c7814d04
--- /dev/null
+++ b/doc/ivshmem_kvmfr.rst
@@ -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.
+
diff --git a/doc/ivshmem_shm.rst b/doc/ivshmem_shm.rst
new file mode 100644
index 00000000..52051e5b
--- /dev/null
+++ b/doc/ivshmem_shm.rst
@@ -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.