.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "KMIDIFF" "1" "Dec 02, 2023" "" "Libabigail" .SH NAME kmidiff \- compare KMIs of Linux Kernel trees .sp \fBkmidiff\fP 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. .SH GENERAL APPROACH .sp And example of how to build your kernel if you want to compare it to another one using kmidiff is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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 .ft P .fi .UNINDENT .UNINDENT .sp Then install the modules into a directory, for instance, the build/modules sub\-directory of the your kernel source tree: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mkdir build/modules make modules_install INSTALL_MOD_DIR=build/modules .ft P .fi .UNINDENT .UNINDENT .sp Then construct a list of interfaces exported by the kernel, that you want to compare: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cat > kmi\-whitelist << EOF [kernel_4.5_kmi_whitelist] init_task schedule dev_queue_xmit __kmalloc printk EOF .ft P .fi .UNINDENT .UNINDENT .sp Suppose you\(aqve done something similar for the v4.6 branch of the Linux kernel, you now have these two directories: \fBlinux/v4.5\fP and \fBlinux/v4.6\fP\&. Their modules are present under the directories \fBlinux/v4.5/build/modules\fP and \fBlinux/v4.6/build/modules\fP\&. .sp To Comparing their KMI \fBkmidiff\fP needs to know where to find the vmlinux binaries and their associated modules. Here would be what the command line looks like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C kmidiff \e \-\-kmi\-whitelist linux/v4.6/kmi\-whitelist \e \-\-vmlinux1 linux/v4.5/vmlinux \e \-\-vmlinux2 linux/v4.6/vmlinux \e linux/v4.5/build/modules \e linux/v4.6/build/modules .ft P .fi .UNINDENT .UNINDENT .sp This tool uses the libabigail library to analyze the binary as well as its associated debug information. Here is its general mode of operation. .sp 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 \fI\%ELF\fP symbols that are defined and exported by the binary. It\(aqs that final ABI corpus which libabigail considers as representing the ABI of the analyzed binary. .sp Libabigail then has capabilities to generate textual representations of ABI Corpora, compare them, analyze their changes and report about them. .SH INVOCATION .sp More generally, \fBkmidiff\fP is invoked under the form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C kmidiff [options] .ft P .fi .UNINDENT .UNINDENT .SH ENVIRONMENT .sp By default, \fBkmidiff\fP 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 the those interfaces. .sp By default, \fBkmidiff\fP uses debug information in the \fI\%DWARF\fP debug info format, if present, otherwise it compares interfaces using \fI\%CTF\fP or \fI\%BTF\fP debug info formats, if present. Finally, if no debug info in these formats is found, it only considers \fI\%ELF\fP symbols and report about their addition or removal. .sp Users can then define a \(dqwhite list\(dq of the interfaces to compare. Such a white list is a just a file in the \(dqINI\(dq format that looks like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [kernel_version_x86_64_whitelist] function1_name function2_name global_variable1_name .... .ft P .fi .UNINDENT .UNINDENT .sp 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 \(dqwhitelist\(dq. So you can define the name you want, for instance \fB[kernel_46_x86_64_whitelist]\fP\&. .sp 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 \fBkmidiff\fP recursively. .sp Note that by default kmidiff analyzes the types reachable from the interfaces associated with \fI\%ELF\fP symbols that are defined and exported by the \fI\%Linux Kernel\fP as being the union of the \fBvmlinux\fP binary and all its compiled modules. It then compares those interfaces (along with their types). .SH OPTIONS .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fB\-\-help | \-h\fP .sp Display a short help about the command and exit. .IP \(bu 2 \fB\-\-version | \-v\fP .sp Display the version of the program and exit. .IP \(bu 2 \fB\-\-verbose\fP .sp Display some verbose messages while executing. .IP \(bu 2 \fB\-\-debug\-info\-dir1 | \-\-d1\fP <\fIdi\-path1\fP> .sp For cases where the debug information for the binaries of the first Linux kernel is split out into separate files, tells \fBkmidiff\fP where to find those separate debug information files. .sp Note that \fIdi\-path\fP must point to the root directory under which the debug information is arranged in a tree\-like manner. Under Red Hat based systems, that directory is usually \fB/usr/lib/debug\fP\&. .IP \(bu 2 \fB\-\-debug\-info\-dir2 | \-\-d2\fP <\fIdi\-path2\fP> .sp Like \fB\-\-debug\-info\-dir1\fP, this options tells \fBkmidiff\fP where to find the split debug information for the binaries of the second Linux kernel. .IP \(bu 2 \fB\-\-vmlinux1 | \-\-l1\fP <\fIpath\-to\-first\-vmlinux\fP> .sp Sets the path to the first \fBvmlinux\fP binary to consider. This has to be the uncompressed vmlinux binary compiled with debug info. .IP \(bu 2 \fB\-\-vmlinux2 | \-\-l2\fP <\fIpath\-to\-first\-vmlinux\fP> .sp Sets the path to the second \fBvmlinux\fP binary to consider. This has to be the uncompressed vmlinux binary compiled with debug info. .IP \(bu 2 \fB\-\-kmi\-whitelist | \-w\fP <\fIpath\-to\-interface\-whitelist\fP> .sp 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. .sp If this option is not provided, \fIall\fP 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. .sp So please, make sure you always use this option unless you really know what you are doing. .IP \(bu 2 \fB\-\-suppressions | \-\-suppr\fP <\fIpath\-to\-suppressions\fP> .sp Use a \fI\%suppression specification\fP file located at \fIpath\-to\-suppressions\fP\&. 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. .sp Please note that, by default, if this option is not provided, then the \fI\%default suppression specification files\fP are loaded . .IP \(bu 2 \fB\-\-no\-change\-categorization | \-x\fP .sp This option 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. The goal of this option is to speed\-up the 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. .IP \(bu 2 \fB\-\-ctf\fP .sp Extract ABI information from \fI\%CTF\fP debug information, if present, in the Kernel and Modules. .IP \(bu 2 \fB\-\-btf\fP .sp Extract ABI information from \fI\%BTF\fP debug information, if present, in the Kernel and Modules. .IP \(bu 2 \fB\-\-impacted\-interfaces | \-i\fP .sp Tell what interfaces got impacted by each individual ABI change. .IP \(bu 2 \fB\-\-full\-impact | \-f\fP .sp 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 \fBabidiff\fP or \fBabipkgdiff\fP\&. .IP \(bu 2 \fB\-\-exported\-interfaces\-only\fP .sp When using this option, this tool analyzes the descriptions of the types reachable by the interfaces (functions and variables) associated with \fI\%ELF\fP symbols that are defined and exported by the \fI\%Linux Kernel\fP\&. .sp Otherwise, the tool also has the ability to analyze the descriptions of the types reachable by the interfaces associated with \fI\%ELF\fP symbols that are visible outside their translation unit. This later possibility is however much more resource intensive and results in much slower operations. .sp That is why this option is enabled by default. .IP \(bu 2 \fB\-\-allow\-non\-exported\-interfaces\fP .sp When using this option, this 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 \fI\%ELF\fP symbols that are defined and exported by the binary. It\(aqs that final ABI corpus which is compared against another one. .sp The problem with that approach however is that analyzing all the interfaces that are visible from outside their translation unit can amount to a lot of data, leading to very slow operations. .sp Note that this option is turned off by default. .IP \(bu 2 \fB\-\-show\-bytes\fP .sp Show sizes and offsets in bytes, not bits. This option is activated by default. .IP \(bu 2 \fB\-\-show\-bits\fP .sp Show sizes and offsets in bits, not bytes. By default, sizes and offsets are shown in bytes. .IP \(bu 2 \fB\-\-show\-hex\fP .sp Show sizes and offsets in hexadecimal base. This option is activated by default. .IP \(bu 2 \fB\-\-show\-dec\fP .sp Show sizes and offsets in decimal base. .UNINDENT .UNINDENT .UNINDENT .SH AUTHOR Dodji Seketeli .SH COPYRIGHT 2014-2023, Red Hat, Inc. .\" Generated by docutils manpage writer. .