mirror of
https://github.com/gnif/LookingGlass.git
synced 2024-11-10 00:28:20 +00:00
[doc] module: Touchups
This commit is contained in:
parent
6f5e5aa0c2
commit
acac8b40cb
154
doc/module.rst
154
doc/module.rst
@ -1,50 +1,84 @@
|
||||
.. _kernel_module:
|
||||
|
||||
Kernel Module
|
||||
#############
|
||||
|
||||
This kernel module implements a basic interface to the IVSHMEM device
|
||||
for LookingGlass when using LookingGlass in VM->VM mode.
|
||||
for Looking Glass in VM->VM mode.
|
||||
|
||||
Additionally, in VM->host mode, it can be used to generate a shared
|
||||
Additionally in VM->host mode, it can be used to generate a shared
|
||||
memory device on the host machine that supports dmabuf.
|
||||
|
||||
Compiling (Manual)
|
||||
------------------
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Make sure you have your kernel headers installed first, on Debian/Ubuntu
|
||||
use the following command::
|
||||
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 simply run ``make`` and you're done.
|
||||
Then switch to the ``module/`` directory
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cd module/
|
||||
|
||||
.. _module_manual:
|
||||
|
||||
Compiling & Loading (Manual)
|
||||
----------------------------
|
||||
|
||||
To compile the module manually, run ``make`` in the module directory.
|
||||
|
||||
.. _module_manual_loading:
|
||||
|
||||
Loading
|
||||
~~~~~~~
|
||||
|
||||
For VM->VM mode, simply run::
|
||||
For VM->VM mode, run:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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::
|
||||
32 MB shared memory device can be created with:
|
||||
|
||||
insmod kvmfr.ko static_size_mb=128
|
||||
.. code:: bash
|
||||
|
||||
insmod kvmfr.ko static_size_mb=32
|
||||
|
||||
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:
|
||||
.. _module_dkms:
|
||||
|
||||
Compiling & Installing (DKMS)
|
||||
-----------------------------
|
||||
Using DKMS
|
||||
----------
|
||||
|
||||
You can install this module into DKMS so that it persists across kernel
|
||||
upgrades. Simply run::
|
||||
You can use the kernel's DKMS feature to keep the module across upgrades.
|
||||
``dkms`` must be installed.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
apt-get install dkms
|
||||
|
||||
.. _module_dkms_install:
|
||||
|
||||
Installing
|
||||
~~~~~~~~~~
|
||||
|
||||
To install the module into DKMS, run
|
||||
|
||||
.. code:: bash
|
||||
|
||||
dkms install .
|
||||
|
||||
.. _loading-1:
|
||||
.. _module_dkms_loading:
|
||||
|
||||
Loading
|
||||
~~~~~~~
|
||||
@ -54,31 +88,40 @@ For VM->VM, simply modprobe the module::
|
||||
modprobe kvmfr
|
||||
|
||||
For VM->host with dmabuf, modprobe with the parameter
|
||||
``static_size_mb``::
|
||||
``static_size_mb``:
|
||||
|
||||
modprobe kvmfr static_size_mb=128
|
||||
.. code:: bash
|
||||
|
||||
modprobe kvmfr static_size_mb=32
|
||||
|
||||
Just like above, multiple devices can be created by separating the sizes
|
||||
with commas.
|
||||
|
||||
.. _module_usage:
|
||||
|
||||
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::
|
||||
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, ie:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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)::
|
||||
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"
|
||||
|
||||
Usage with looking glass is simple, you only need to specify the path to
|
||||
the device node, for example::
|
||||
(replace ``user`` with your username)
|
||||
|
||||
Usage with Looking Glass is simple, you only need to specify the path to
|
||||
the device node, for example:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
./looking-glass-client -f /dev/kvmfr0
|
||||
|
||||
@ -90,23 +133,30 @@ You may also use a config file: ``~/.looking-glass-client.ini``, or
|
||||
[app]
|
||||
shmFile=/dev/kvmfr0
|
||||
|
||||
.. _module_vm_to_host:
|
||||
|
||||
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::
|
||||
QEMU
|
||||
^^^^
|
||||
|
||||
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=128M,share=yes
|
||||
-object memory-backend-file,id=looking-glass,mem-path=/dev/kvmfr0,size=32M,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.
|
||||
.. note::
|
||||
|
||||
``libvirt``
|
||||
^^^^^^^^^^^
|
||||
The ``size`` argument must be the same size you passed
|
||||
to the ``static_size_mb`` argument when loading the kernel module.
|
||||
|
||||
With ``libvirt``, you can use the following XML block:
|
||||
libvirt
|
||||
^^^^^^^
|
||||
|
||||
Create the following XML block in your domain:
|
||||
|
||||
.. code:: xml
|
||||
|
||||
@ -114,25 +164,29 @@ With ``libvirt``, you can use the following XML block:
|
||||
<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:arg value='memory-backend-file,id=looking-glass,mem-path=/dev/kvmfr0,size=32M,share=yes'/>
|
||||
</qemu:commandline>
|
||||
|
||||
Remember to add
|
||||
``xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'`` to the
|
||||
``<domain>``.
|
||||
.. note::
|
||||
|
||||
On certain distros, running libvirt this way poses issues with apparmor
|
||||
and cgroups.
|
||||
Remember to add ``xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'``
|
||||
to the ``<domain>`` tag.
|
||||
|
||||
For apparmor, create ``/etc/apparmor.d/local/abstractions/libvirt-qemu`` if
|
||||
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, in ``/etc/libvirt/qemu.conf``, uncomment the
|
||||
``cgroup_device_acl`` block and add ``/dev/kvmfr0`` to the list. Then
|
||||
restart ``libvirtd``::
|
||||
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
|
||||
|
||||
@ -144,7 +198,7 @@ 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 a file as ``/etc/modules-load.d/kvmfr.conf`` with the following
|
||||
Create the file ``/etc/modules-load.d/kvmfr.conf`` with the following
|
||||
contents::
|
||||
|
||||
#KVMFR Looking Glass module
|
||||
@ -152,9 +206,13 @@ contents::
|
||||
|
||||
This will now run the next time you start your machine.
|
||||
|
||||
If you are running in VM->host mode, you must additionally add another file in
|
||||
If you are running in VM->host mode, you must additionally create another file
|
||||
``/etc/modprobe.d/kvmfr.conf`` to properly set the size. It should have the
|
||||
following contents, while adjusting ``static_size_mb`` to your needs::
|
||||
following contents::
|
||||
|
||||
#KVMFR Looking Glass module
|
||||
options kvmfr static_size_mb=128
|
||||
options kvmfr static_size_mb=32
|
||||
|
||||
.. note::
|
||||
|
||||
Don't forget to adjust ``static_size_mb`` to your needs.
|
||||
|
Loading…
Reference in New Issue
Block a user