[doc] module: Touchups

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.