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