1.. _kmidiff_label:
2
3===========
4kmidiff
5===========
6
7``kmidiff`` compares the binary Kernel Module Interfaces of two Linux
8Kernel trees.  The binary KMI is the interface that the Linux Kernel
9exposes to its modules.  The trees we are interested in here are the
10result of the build of the Linux Kernel source tree.
11
12
13General approach
14=================
15
16And example of how to build your kernel if you want to compare it to
17another one using kmidiff is: ::
18
19    git clone -b v4.5 git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git linux/v4.5
20    cd linux/v4.5
21    make allyesconfig all
22
23Then install the modules into a directory, for instance, the
24build/modules sub-directory of the your kernel source tree: ::
25
26    mkdir build/modules
27    make modules_install INSTALL_MOD_DIR=build/modules
28
29
30Then construct a list of interfaces exported by the kernel, that you
31want to compare: ::
32
33    cat > kmi-whitelist << EOF
34    [kernel_4.5_kmi_whitelist]
35     init_task
36     schedule
37     dev_queue_xmit
38     __kmalloc
39     printk
40    EOF
41
42Suppose you've done something similar for the v4.6 branch of the Linux
43kernel, you now have these two directories: ``linux/v4.5`` and ``linux/v4.6``.
44Their modules are present under the directories
45``linux/v4.5/build/modules`` and ``linux/v4.6/build/modules``.
46
47To Comparing their KMI ``kmidiff`` needs to know where to find the
48vmlinux binaries and their associated modules.  Here would be what the
49command line looks like: ::
50
51    kmidiff                                     \
52      --kmi-whitelist  linux/v4.6/kmi-whitelist \
53      --vmlinux1       linux/v4.5/vmlinux       \
54      --vmlinux2       linux/v4.6/vmlinux       \
55		       linux/v4.5/build/modules \
56		       linux/v4.6/build/modules
57
58Invocation
59==========
60
61More generally, ``kmidiff`` is invoked under the form: ::
62
63    kmidiff [options] <first-modules-dir> <second-modules-dir>
64
65Environment
66===========
67
68By default, ``kmidiff`` compares all the interfaces (exported
69functions and variables) between the Kernel and its modules.  In
70practice, though, users want to compare a subset of the those
71interfaces.
72
73Users can then define a "symbol list" of the interfaces to compare.
74Such a list is a just a file in the "INI" format that looks like: ::
75
76    [kernel_version_x86_64_symbol_list]
77      function1_name
78      function2_name
79      global_variable1_name
80      ....
81
82
83Note that the name of the section (the name that is between the two brackets)
84of that INI file just has to end with the string "symbol_list" or "whitelist".
85So you can define the name you want, for instance
86``[kernel_46_x86_64_symbol_list]``.
87
88Then each line of that symbol list file is the name of an exported
89function or variable.  Only those interfaces along with the types
90reachable from their signatures are going to be compared by
91``kmidiff`` recursively.
92
93Note that kmidiff compares the interfaces exported by the ``vmlinux``
94binary and by the all of the compiled modules.
95
96Options
97=======
98
99  * ``--help | -h``
100
101    Display a short help about the command and exit.
102
103
104  * ``--version | -v``
105
106    Display the version of the program and exit.
107
108  * ``--verbose``
109
110    Display some verbose messages while executing.
111
112  * ``--debug-info-dir1 | --d1`` <*di-path1*>
113
114    For cases where the debug information for the binaries of the
115    first Linux kernel is split out into separate files, tells
116    ``kmidiff`` where to find those separate debug information files.
117
118    Note that *di-path* must point to the root directory under which
119    the debug information is arranged in a tree-like manner.  Under
120    Red Hat based systems, that directory is usually
121    ``<root>/usr/lib/debug``.
122
123  * ``--debug-info-dir2 | --d2`` <*di-path2*>
124
125    Like ``--debug-info-dir1``, this options tells ``kmidiff`` where
126    to find the split debug information for the binaries of the second
127    Linux kernel.
128
129  * ``--vmlinux1 | --l1`` <*path-to-first-vmlinux*>
130
131    Sets the path to the first ``vmlinux`` binary to consider.  This
132    has to be the uncompressed vmlinux binary compiled with debug
133    info.
134
135  * ``--vmlinux2 | --l2`` <*path-to-first-vmlinux*>
136
137    Sets the path to the second ``vmlinux`` binary to consider.  This
138    has to be the uncompressed vmlinux binary compiled with debug
139    info.
140
141  * ``--kmi-whitelist | -w`` <*path-to-interface-whitelist*>
142
143    Set the path to the white list of interfaces to compare while
144    comparing the Kernel Module Interface of the first kernel against
145    the one of the second kernel.
146
147    If this option is not provided, *all* the exported interfaces of
148    the two kernels are compared.  That takes a lot of times and is
149    not necessarily meaningful because many interface are probably
150    meant to see their reachable types change.
151
152    So please, make sure you always use this option unless you really
153    know what you  are doing.
154
155  * ``--suppressions | --suppr`` <*path-to-suppressions*>
156
157    Use a :ref:`suppression specification <suppr_spec_label>` file
158    located at *path-to-suppressions*.  Note that this option can
159    appear multiple times on the command line.  In that case, all of
160    the provided suppression specification files are taken into
161    account.
162
163    Please note that, by default, if this option is not provided, then
164    the :ref:`default suppression specification files
165    <abidiff_default_supprs_label>` are loaded .
166
167
168  * ``--impacted-interfaces | -i``
169
170    Tell what interfaces got impacted by each individual ABI change.
171
172  * ``--full-impact | -f``
173
174    Emit a change report that shows the full impact of each change on
175    exported interfaces.  This is the default kind of report emitted
176    by tools like ``abidiff`` or ``abipkgdiff``.
177
178  * ``--show-bytes``
179
180    Show sizes and offsets in bytes, not bits.  This option is
181    activated by default.
182
183  * ``--show-bits``
184
185    Show sizes and offsets in bits, not bytes.  By default, sizes and
186    offsets are shown in bytes.
187
188  * ``--show-hex``
189
190    Show sizes and offsets in hexadecimal base.  This option is
191    activated by default.
192
193  * ``--show-dec``
194
195    Show sizes and offsets in decimal base.
196