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>
This commit is contained in:
Dodji Seketeli 2017-05-31 11:48:50 +02:00
parent 077b977ce5
commit 8bf7b7d26b
2 changed files with 151 additions and 1 deletions

View File

@ -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 =

149
doc/manuals/kmidiff.rst Normal file
View File

@ -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 .