Add documentation for the kmidiff tool

	* doc/manuals/kmidiff.rst: New doc file.
	* doc/manuals/Makefile.am: Add the above file to source
	distribution.

Signed-off-by: Dodji Seketeli <dodji@redhat.com>

diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am
index 573fb3bfe5a10d66339f814e476e74892318c27d..5c31fa3db25f20982dbd81db15ba56cb6244a792 100644 (file)
--- a/doc/manuals/Makefile.am
+++ b/doc/manuals/Makefile.am
@@ -11,7 +11,8 @@ index.rst \
 libabigail-concepts.rst \
 libabigail-overview.rst \
 libabigail-tools.rst \
-fedabipkgdiff.rst
+fedabipkgdiff.rst \
+kmidiff.rst
 
 # You can set these variables from the command line.
 SPHINXOPTS    =

diff --git a/doc/manuals/kmidiff.rst b/doc/manuals/kmidiff.rst
new file mode 100644 (file)
index 0000000..1b184c3
--- /dev/null
+++ b/doc/manuals/kmidiff.rst
@@ -0,0 +1,149 @@
+.. _kmidiff_label:
+
+===========
+kmidiff
+===========
+
+``kmidiff`` compares the binary Kernel Module Interfaces of two Linux
+Kernel trees.  The binary KMI is the interface that the Linux Kernel
+exposes to its modules.  The trees we are interested in here are the
+result of the build of the Linux Kernel source tree.
+
+=================
+General approach
+=================
+
+And example of how to build your kernel if you want to compare it to
+another one using kmidiff is: ::
+
+    git clone -b v4.5 git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git linux/v4.5
+    cd linux/v4.5
+    make allyesconfig all
+
+Then install the modules into a directory, for instance, the
+build/modules sub-directory of the your kernel source tree: ::
+
+    mkdir build/modules
+    make modules_install INSTALL_MOD_DIR=build/modules
+
+
+Then construct a list of interfaces exported by the kernel, that you
+want to compare: ::
+
+    cat > kmi-whitelist << EOF
+    [kernel_4.5_kmi_whitelist]
+     init_task
+     schedule
+     dev_queue_xmit
+     __kmalloc
+     printk
+    EOF
+
+Suppose you've done something similar for the v4.6 branch of the Linux
+kernel, you now have these two directories: ``linux/v4.5`` and ``linux/v4.6``.
+Their modules are present under the directories
+``linux/v4.5/build/modules`` and ``linux/v4.6/build/modules``.
+
+To Comparing their KMI ``kmidiff`` needs to know where to find the
+vmlinux binaries and their associated modules.  Here would be what the
+command line looks like: ::
+
+    kmidiff                                     \
+      --kmi-whitelist  linux/v4.6/kmi-whitelist \
+      --vmlinux1       linux/v4.5/vmlinux       \
+      --vmlinux2       linux/v4.6/vmlinux       \
+                      linux/v4.5/build/modules \
+                      linux/v4.6/build/modules
+
+Invocation
+==========
+
+More generally, ``kmidiff`` is invoked under the form: ::
+
+    kmidiff [options] <first-modules-dir> <second-modules-dir>
+
+Environment
+===========
+
+By default, ``kmidiff`` compares all the interfaces (exported
+functions and variables) between the Kernel and its modules.  In
+practice, though, users want to compare a subset of the those
+interfaces.
+
+Users can then define a "white list" of the interfaces to compare.
+Such a white list is a just a file in the "INI" format that looks
+like: ::
+
+    [kernel_version_x86_64_whitelist]
+      function1_name
+      function2_name
+      global_variable1_name
+      ....
+
+
+Note that the name of the section (the name that is between the two
+brackets) of that INI file just has to end with the string
+"whitelist".  So you can define the name you want, for instance
+``[kernel_46_x86_64_whitelist]``.
+
+Then each line of that whitelist file is the name of an exported
+function or variable.  Only those interfaces along with the types
+reachable from their signatures are going to be compared by
+``kmidiff`` recursively.
+
+Note that kmidiff compares the interfaces exported by the ``vmlinux``
+binary and by the all of the compiled modules.
+
+Options
+=======
+
+  * ``--help | -h``
+
+    Display a short help about the command and exit.
+
+
+  * ``--version | -v``
+
+    Display the version of the program and exit.
+
+  * ``--verbose``
+
+    Display some verbose messages while executing.
+
+  * ``--vmlinux1 | --l1`` <*path-to-first-vmlinux*>
+
+    Sets the path to the first ``vmlinux`` binary to consider.  This
+    has to be the uncompressed vmlinux binary compiled with debug
+    info.
+
+  * ``--vmlinux2 | --l2`` <*path-to-first-vmlinux*>
+
+    Sets the path to the second ``vmlinux`` binary to consider.  This
+    has to be the uncompressed vmlinux binary compiled with debug
+    info.
+
+  * ``--kmi-whitelist | -w`` <*path-to-interface-whitelist*>
+
+    Set the path to the white list of interfaces to compare while
+    comparing the Kernel Module Interface of the first kernel against
+    the one of the second kernel.
+
+    If this option is not provided, *all* the exported interfaces of
+    the two kernels are compared.  That takes a lot of times and is
+    not necessarily meaningful because many interface are probably
+    meant to see their reachable types change.
+
+    So please, make sure you always use this option unless you really
+    know what you  are doing.
+
+  * ``--suppressions | --suppr`` <*path-to-suppressions*>
+
+    Use a :ref:`suppression specification <suppr_spec_label>` file
+    located at *path-to-suppressions*.  Note that this option can
+    appear multiple times on the command line.  In that case, all of
+    the provided suppression specification files are taken into
+    account.
+
+    Please note that, by default, if this option is not provided, then
+    the :ref:`default suppression specification files
+    <abidiff_default_supprs_label>` are loaded .