From 77a4c114e9de9d7f5fb687c806af96b650d29d1b Mon Sep 17 00:00:00 2001
From: Jonathan Rubenstein <jrubcop@gmail.com>
Date: Fri, 7 May 2021 02:10:08 -0400
Subject: [PATCH] [doc] module: Import from module/README.md

---
 doc/index.rst  |   1 +
 doc/module.rst | 136 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 137 insertions(+)
 create mode 100644 doc/module.rst

diff --git a/doc/index.rst b/doc/index.rst
index e39c45a4..0ff3a668 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -13,6 +13,7 @@ systems for legacy programs that require high-performance graphics.
    install
    troubleshooting
    obs
+   module
    faq
    tech_faq
 
diff --git a/doc/module.rst b/doc/module.rst
new file mode 100644
index 00000000..bce641ab
--- /dev/null
+++ b/doc/module.rst
@@ -0,0 +1,136 @@
+Kernel Module
+#############
+
+This kernel module implements a basic interface to the IVSHMEM device
+for LookingGlass when using LookingGlass in VM->VM mode.
+
+Additionally, in VM->host mode, it can be used to generate a shared
+memory device on the host machine that supports dmabuf.
+
+Compiling (Manual)
+------------------
+
+Make sure you have your kernel headers installed first, on Debian/Ubuntu
+use the following command::
+
+   apt-get install linux-headers-$(uname -r)
+
+Then simply run ``make`` and you're done.
+
+Loading
+~~~~~~~
+
+For VM->VM mode, simply run::
+
+   insmod kvmfr.ko
+
+For VM->host mode with dmabuf, instead of creating a shared memory file,
+load this module with the parameter ``static_size_mb``. For example, a
+128 MB shared memory device can be created with::
+
+   insmod kvmfr.ko static_size_mb=128
+
+Multiple devices can be created by separating the sizes with commas. For
+example, ``static_size_mb=128,64`` would create two kvmfr devices:
+``kvmfr0`` would be 128 MB and ``kvmfr1`` would be 64 MB.
+
+.. _compiling--installing-dkms:
+
+Compiling & Installing (DKMS)
+-----------------------------
+
+You can install this module into DKMS so that it persists across kernel
+upgrades. Simply run::
+
+   dkms install .
+
+.. _loading-1:
+
+Loading
+~~~~~~~
+
+For VM->VM, simply modprobe the module::
+
+   modprobe kvmfr
+
+For VM->host with dmabuf, modprobe with the parameter
+``static_size_mb``::
+
+   modprobe kvmfr static_size_mb=128
+
+Just like above, multiple devices can be created by separating the sizes
+with commas.
+
+Usage
+-----
+
+This will create the ``/dev/kvmfr0`` node that 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, ie::
+
+   sudo chown user:user /dev/kvmfr0
+
+An example udev rule, which you can put in
+``/etc/udev/rules.d/99-kvmfr.rules``, is (replace ``user`` with your
+username)::
+
+   SUBSYSTEM=="kvmfr", OWNER="user", GROUP="kvm", MODE="0660"
+
+Usage with looking glass is simple, you only need to specify the path to
+the device node, for example::
+
+   ./looking-glass-client -f /dev/kvmfr0
+
+You may also use a config file: ``~/.looking-glass-client.ini``, or
+``/etc/looking-glass-client.ini``.
+
+.. code:: ini
+
+   [app]
+   shmFile=/dev/kvmfr0
+
+VM->Host
+~~~~~~~~
+
+In VM->host mode, use this device in place of the shared memory file.
+
+For example, with ``qemu``, you would use the following arguments::
+
+   -device ivshmem-plain,id=shmem0,memdev=looking-glass
+   -object memory-backend-file,id=looking-glass,mem-path=/dev/kvmfr0,size=128M,share=yes
+
+Note that the ``size`` argument must be the same size as what you passed
+to ``static_size_mb`` argument for the kernel module.
+
+``libvirt``
+^^^^^^^^^^^
+
+With ``libvirt``, you can use the following XML block:
+
+.. 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=128M,share=yes'/>
+   </qemu:commandline>
+
+Remember to add
+``xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'`` to the
+``<domain>``.
+
+On certain distros, running libvirt this way poses issues with apparmor
+and cgroups.
+
+For apparmor, in ``/etc/apparmor.d/abstractions/libvirt-qemu``, append::
+
+   # Looking Glass
+   /dev/kvmfr0 rw,
+
+For cgroups, in ``/etc/libvirt/qemu.conf``, uncomment the
+``cgroup_device_acl`` block and add ``/dev/kvmfr0`` to the list. Then
+restart ``libvirtd``::
+
+   sudo systemctl restart libvirtd.service