KMIDIFF(1)

📦 version 3.0, in arch rolling

💅 KMIDIFF(1) 💅

okay so this is kmidiff, and it ships as part of Libabigail (that's the manual name, bestie — remember it, it comes up) 🫶

✨ NAME ✨

kmidiff — compare KMIs of Linux Kernel trees 🌳🦋

kmidiff compares the binary Kernel Module Interfaces of two Linux Kernel trees. The binary KMI is, like, literally the interface that the Linux Kernel exposes to its modules. And the trees we're talking about here? They're the result of building the Linux Kernel source tree. no cap ✨

🌈 GENERAL APPROACH 🌈

So here's an example of how to build your kernel if you want to compare it to another one using kmidiff — screenshot this, it's giving tutorial:

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 your kernel source tree:

mkdir build/modules
make modules_install INSTALL_MOD_PATH=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 compare their KMI, kmidiff needs to know where to find the vmlinux binaries and their associated modules. Here's what the command line looks like — iconic behavior only:

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

This tool uses the libabigail library to analyze the binary as well as its associated debug information. Here's its general mode of operation, and honestly? it ate 💅

When instructed to do so, a binary and its associated debug information is read and analyzed. To that effect, libabigail analyzes by default the descriptions of the types reachable by the interfaces (functions and variables) that are visible outside of their translation unit. Once that analysis is done, an Application Binary Interface Corpus is constructed by only considering the subset of types reachable from interfaces associated to ELF symbols (http://en.wikipedia.org/wiki/Executable_and_Linkable_Format) that are defined and exported by the binary. It's that final ABI corpus which libabigail considers as representing the ABI of the analyzed binary. 🎀

Libabigail then has capabilities to generate textual representations of ABI Corpora, compare them, analyze their changes and report about them. main character energy fr fr ✨

🔥 INVOCATION 🔥

More generally, kmidiff is invoked under the form:

kmidiff [options] <first-modules-dir> <second-modules-dir>

🌸 ENVIRONMENT 🌸

💖 General considerations 💖

  • General considerations — hmm wait, let's actually talk about it 👇

By default, kmidiff compares all the interfaces (exported functions and variables) between the Kernel and its modules. In practice, though, some users might want to compare a subset of those interfaces. valid 🙈

By default, kmidiff uses debug information in the DWARF debug info format (http://www.dwarfstd.org), if present, otherwise it compares interfaces using CTF (https://raw.githubusercontent.com/wiki/oracle/binutils-gdb/files/ctf-spec.pdf) or BTF (https://docs.kernel.org/bpf/btf.html) debug info formats, if present. Finally, if no debug info in these formats is found, it only considers ELF symbols (http://en.wikipedia.org/wiki/Executable_and_Linkable_Format) and reports about their addition or removal. lowkey a whole fallback chain 🫶

Users can then define a "white list" of the interfaces to compare. Such a white list is 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's 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]. your file, your rules 💅

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. obsessed with the recursion ngl 🌀

Note that by default kmidiff analyzes the types reachable from the interfaces associated with ELF symbols (http://en.wikipedia.org/wiki/Executable_and_Linkable_Format) that are defined and exported by the Linux Kernel (https://kernel.org) as being the union of the vmlinux binary and all its compiled modules. It then compares those interfaces (along with their types). 👑

⚡ Parallel processing ⚡

The environment variable ABIGAIL_THREAD_POOL_SIZE can be set to either an integer, or a percentage value, e.g, 10%. The integer value defines the number of threads used by Libabigail to perform parallel processing when applicable. The percentage defines the percentage of the total available cores to use by Libabigail to perform the parallel processing when applicable. do the math, bestie 🧮✨

By default, Libabigail uses all the available cores to perform its parallel processing. go big or go home 🔥

✨ OPTIONS ✨

  • --allow-non-exported-interfaces — okay so with this one on, the tool analyzes the descriptions of the types reachable by the interfaces (functions and variables) that are visible outside of their translation unit. Once that analysis is done, an ABI Corpus is constructed by only considering the subset of types reachable from interfaces associated to ELF <http://en.wikipedia.org/wiki/Executable_and_Linkable_Format> symbols that are defined and exported by the binary. And that final ABI corpus is what gets compared against another one. 💅

The problem tho? Analyzing all the interfaces visible from outside their translation unit can amount to a lot of data, which leads to very slow operations. 😭

Heads up bestie: this option is turned off by default.

Note that di-path must point to the root directory under which the debug information is arranged in a tree-like manner. On Red Hat based systems, that directory is usually <root>/usr/lib/debug. 🌸

  • --debug-info-dir2 | --d2 <di-path2> — like --debug-info-dir1, but this one tells kmidiff where to find the split debug information for the binaries of the second Linux kernel. 🫶
  • --exported-interfaces-only — with this option, the tool analyzes the descriptions of the types reachable by the interfaces (functions and variables) associated with ELF <http://en.wikipedia.org/wiki/Executable_and_Linkable_Format> symbols that are defined and exported by the Linux Kernel <https://kernel.org>.

Otherwise, the tool also has the ability to analyze the descriptions of the types reachable by the interfaces associated with ELF <http://en.wikipedia.org/wiki/Executable_and_Linkable_Format> symbols that are visible outside their translation unit. That later possibility is however much more resource intensive and results in much slower operations. 💀

That is why this option is enabled by default. 👑

  • --full-impact | -f — emit a change report that shows the full impact of each change on exported interfaces. This is the default kind of report emitted by tools like abidiff or abipkgdiff. ✨
  • --help | -h — display a short help about the command and exit. Simple, iconic. 🎀
  • --impacted-interfaces | -i — tell what interfaces got impacted by each individual ABI change. 🔥
  • --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 time and is not necessarily meaningful because many interfaces 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. fr fr.
  • --no-change-categorization | -x — this disables the categorization of changes into harmless and harmful changes. Note that this categorization is a pre-requisite for the filtering of changes, so this option disables that filtering too. The goal of this option is to speed up execution of the program for cases where the graph of changes is huge and where the user is just interested in looking at, for instance, leaf node changes without caring about their possible impact on interfaces. ⚡
  • --show-bits — show sizes and offsets in bits, not bytes. By default, sizes and offsets are shown in bytes. 🔢
  • --show-bytes — show sizes and offsets in bytes, not bits. This option is activated by default. 💖
  • --show-dec — show sizes and offsets in decimal base.
  • --show-hex — show sizes and offsets in hexadecimal base. This option is activated by default. 💜
  • --suppressions | --suppr <path-to-suppressions> — use a 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 default suppression specification files <#abidiff-default-supprs-label> are loaded. (yes, with a lil space before that period, we don't judge 😌)
  • --thread-pool-size <N|N%> | -j <N|N%> — set the size of the thread pool used by Libabigail for parallel processing. The size is either the number of threads or a percentage of the total number of available cores on the machine. By default, all the available cores of the machine are used for parallel processing. 🧚

Note that the environment variable ABIGAIL_THREAD_POOL_SIZE can also be set to similar values. This command line option, if present, supersedes the value of the environment variable. 👑

  • --verbose — display some verbose messages while executing. Chatty era. 🗣️
  • --version | -v — display the version of the program and exit. 🎀
  • --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. 🐧

🌸 Author 🌸

Dodji Seketeli — the main character who wrote this, we stan. 👑

2014-2025, Red Hat, Inc.

And that's the whole page bestie, you ate that 🫶 — this little scroll of wisdom is the KMIDIFF(1) page dated Oct 08, 2026, and it's been giving iconic Unix energy the entire time. Now go diff those kernels 💅✨

📦 where this page comes from