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 + + + + + + + + +Remember to add +``xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'`` to the +````. + +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