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 58 59.. include:: tools-use-libabigail.txt 60 61 62Invocation 63========== 64 65More generally, ``kmidiff`` is invoked under the form: :: 66 67 kmidiff [options] <first-modules-dir> <second-modules-dir> 68 69Environment 70=========== 71 72By default, ``kmidiff`` compares all the interfaces (exported 73functions and variables) between the Kernel and its modules. In 74practice, though, some users might want to compare a subset of the 75those interfaces. 76 77By default, ``kmidiff`` uses debug information in `DWARF`_ format, 78if present, otherwise it compares interfaces using debug information 79in `CTF`_ format, if present, finally, if neither is found, it uses 80only `ELF`_ symbols to report which were added or removed. 81 82Users can then define a "white list" of the interfaces to compare. 83Such a white list is a just a file in the "INI" format that looks 84like: :: 85 86 [kernel_version_x86_64_whitelist] 87 function1_name 88 function2_name 89 global_variable1_name 90 .... 91 92 93Note that the name of the section (the name that is between the two 94brackets) of that INI file just has to end with the string 95"whitelist". So you can define the name you want, for instance 96``[kernel_46_x86_64_whitelist]``. 97 98Then each line of that whitelist file is the name of an exported 99function or variable. Only those interfaces along with the types 100reachable from their signatures are going to be compared by 101``kmidiff`` recursively. 102 103Note that by default kmidiff analyzes the types reachable from the 104interfaces associated with `ELF`_ symbols that are defined and 105exported by the `Linux Kernel`_ as being the union of the ``vmlinux`` 106binary and all its compiled modules. It then compares those 107interfaces (along with their types). 108 109Options 110======= 111 112 * ``--help | -h`` 113 114 Display a short help about the command and exit. 115 116 117 * ``--version | -v`` 118 119 Display the version of the program and exit. 120 121 * ``--verbose`` 122 123 Display some verbose messages while executing. 124 125 * ``--debug-info-dir1 | --d1`` <*di-path1*> 126 127 For cases where the debug information for the binaries of the 128 first Linux kernel is split out into separate files, tells 129 ``kmidiff`` where to find those separate debug information files. 130 131 Note that *di-path* must point to the root directory under which 132 the debug information is arranged in a tree-like manner. Under 133 Red Hat based systems, that directory is usually 134 ``<root>/usr/lib/debug``. 135 136 * ``--debug-info-dir2 | --d2`` <*di-path2*> 137 138 Like ``--debug-info-dir1``, this options tells ``kmidiff`` where 139 to find the split debug information for the binaries of the second 140 Linux kernel. 141 142 * ``--vmlinux1 | --l1`` <*path-to-first-vmlinux*> 143 144 Sets the path to the first ``vmlinux`` binary to consider. This 145 has to be the uncompressed vmlinux binary compiled with debug 146 info. 147 148 * ``--vmlinux2 | --l2`` <*path-to-first-vmlinux*> 149 150 Sets the path to the second ``vmlinux`` binary to consider. This 151 has to be the uncompressed vmlinux binary compiled with debug 152 info. 153 154 * ``--kmi-whitelist | -w`` <*path-to-interface-whitelist*> 155 156 Set the path to the white list of interfaces to compare while 157 comparing the Kernel Module Interface of the first kernel against 158 the one of the second kernel. 159 160 If this option is not provided, *all* the exported interfaces of 161 the two kernels are compared. That takes a lot of times and is 162 not necessarily meaningful because many interface are probably 163 meant to see their reachable types change. 164 165 So please, make sure you always use this option unless you really 166 know what you are doing. 167 168 * ``--suppressions | --suppr`` <*path-to-suppressions*> 169 170 Use a :ref:`suppression specification <suppr_spec_label>` file 171 located at *path-to-suppressions*. Note that this option can 172 appear multiple times on the command line. In that case, all of 173 the provided suppression specification files are taken into 174 account. 175 176 Please note that, by default, if this option is not provided, then 177 the :ref:`default suppression specification files 178 <abidiff_default_supprs_label>` are loaded . 179 180 * ``--ctf`` 181 182 Extract ABI information from `CTF`_ debug information, if present in 183 the Kernel and Modules. 184 185 * ``--impacted-interfaces | -i`` 186 187 Tell what interfaces got impacted by each individual ABI change. 188 189 * ``--full-impact | -f`` 190 191 Emit a change report that shows the full impact of each change on 192 exported interfaces. This is the default kind of report emitted 193 by tools like ``abidiff`` or ``abipkgdiff``. 194 195 * ``--exported-interfaces-only`` 196 197 When using this option, this tool analyzes the descriptions of the 198 types reachable by the interfaces (functions and variables) 199 associated with `ELF`_ symbols that are defined and exported by 200 the `Linux Kernel`_. 201 202 Otherwise, the tool also has the ability to analyze the 203 descriptions of the types reachable by the interfaces associated 204 with `ELF`_ symbols that are visible outside their translation 205 unit. This later possibility is however much more resource 206 intensive and results in much slower operations. 207 208 That is why this option is enabled by default. 209 210 211 * ``--allow-non-exported-interfaces`` 212 213 When using this option, this tool analyzes the descriptions of the 214 types reachable by the interfaces (functions and variables) that 215 are visible outside of their translation unit. Once that analysis 216 is done, an ABI Corpus is constructed by only considering the 217 subset of types reachable from interfaces associated to `ELF`_ 218 symbols that are defined and exported by the binary. It's that 219 final ABI corpus which is compared against another one. 220 221 The problem with that approach however is that analyzing all the 222 interfaces that are visible from outside their translation unit 223 can amount to a lot of data, leading to very slow operations. 224 225 Note that this option is turned off by default. 226 227 * ``--show-bytes`` 228 229 Show sizes and offsets in bytes, not bits. This option is 230 activated by default. 231 232 * ``--show-bits`` 233 234 Show sizes and offsets in bits, not bytes. By default, sizes and 235 offsets are shown in bytes. 236 237 * ``--show-hex`` 238 239 Show sizes and offsets in hexadecimal base. This option is 240 activated by default. 241 242 * ``--show-dec`` 243 244 Show sizes and offsets in decimal base. 245 246 247.. _ELF: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format 248.. _ksymtab: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format 249.. _Linux Kernel: https://kernel.org 250.. _DWARF: http://www.dwarfstd.org 251.. _CTF: https://raw.githubusercontent.com/wiki/oracle/binutils-gdb/files/ctf-spec.pdf 252