From 8bf7b7d26bb3eacebaaba518c90907a5cf53b094 Mon Sep 17 00:00:00 2001 From: Dodji Seketeli Date: Wed, 31 May 2017 11:48:50 +0200 Subject: [PATCH] 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 --- doc/manuals/Makefile.am | 3 +- doc/manuals/kmidiff.rst | 149 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 151 insertions(+), 1 deletion(-) create mode 100644 doc/manuals/kmidiff.rst diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am index 573fb3bf..5c31fa3d 100644 --- 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 index 00000000..1b184c35 --- /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] + +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 ` 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 + ` are loaded . -- 2.43.5