From f65aa6e089635df5d7f158b9ac252cf2cdbee7fe Mon Sep 17 00:00:00 2001 From: Quantum Date: Fri, 5 Feb 2021 21:03:24 -0500 Subject: [PATCH] [module] update README to reflect VM->host changes --- module/README.md | 73 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 68 insertions(+), 5 deletions(-) diff --git a/module/README.md b/module/README.md index 44c1244f..07a67365 100644 --- a/module/README.md +++ b/module/README.md @@ -1,6 +1,9 @@ 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 @@ -12,12 +15,20 @@ Then simply run `make` and you're done. ### Loading -This module requires the `uio` module to be loaded first, loading it is as -simple as: +For VM->VM mode, simply run: - modprobe uio 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) You can install this module into DKMS so that it persists across kernel @@ -27,21 +38,73 @@ upgrades. Simply run: ### Loading -Simply modprobe the module: +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 it's +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 +### 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: + +```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