kmidiff(1) — Linux manual page

NAME | GENERAL APPROACH | INVOCATION | ENVIRONMENT | OPTIONS | AUTHOR | COPYRIGHT | COLOPHON

KMIDIFF(1)                     Libabigail                     KMIDIFF(1)

NAME         top

       kmidiff - compare KMIs of Linux Kernel trees

       kmidiff 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.

GENERAL APPROACH         top

       And example of how to build your kernel if you want to compare it
       to another one using kmidiff is:

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

          mkdir build/modules
          make modules_install INSTALL_MOD_DIR=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 Comparing their KMI kmidiff needs to know where to find the
       vmlinux binaries and their associated modules.  Here would be
       what the command line looks like:

          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 is its general
       mode of operation.

       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 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.

INVOCATION         top

       More generally, kmidiff is invoked under the form:

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

ENVIRONMENT         top

       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
       the those interfaces.

       By default, kmidiff uses debug information in the DWARF debug
       info format, if present, otherwise it compares interfaces using
       CTF or BTF debug info formats, if present.  Finally, if no debug
       info in these formats is found, it only considers ELF symbols and
       report about their addition or removal.

       Users can then define a "white list" of the interfaces to
       compare.  Such a white list is a 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 is 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].

       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.

       Note that by default kmidiff analyzes the types reachable from
       the interfaces associated with ELF symbols that are defined and
       exported by the Linux Kernel as being the union of the vmlinux
       binary and all its compiled modules.  It then compares those
       interfaces (along with their types).

OPTIONS         top

--help | -h

            Display a short help about the command and exit.

          • --version | -v

            Display the version of the program and exit.

          • --verbose

            Display some verbose messages while executing.

          • --debug-info-dir1 | --d1 <di-path1>

            For cases where the debug information for the binaries of
            the first Linux kernel is split out into separate files,
            tells kmidiff where to find those separate debug information
            files.

            Note that di-path 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 <root>/usr/lib/debug.

          • --debug-info-dir2 | --d2 <di-path2>

            Like --debug-info-dir1, this options tells kmidiff where to
            find the split debug information for the binaries of the
            second Linux kernel.

          • --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.

          • --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 times
            and is not necessarily meaningful because many interface 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.

          • --suppressions | --suppr <path-to-suppressions>

            Use a suppression specification 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
            are loaded .

          • --no-change-categorization | -x

            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.

          • --ctf

            Extract ABI information from CTF debug information, if
            present, in the Kernel and Modules.

          • --btf

            Extract ABI information from BTF debug information, if
            present, in the Kernel and Modules.

          • --impacted-interfaces | -i

            Tell what interfaces got impacted by each individual ABI
            change.

          • --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.

          • --exported-interfaces-only

            When using this option, this tool analyzes the descriptions
            of the types reachable by the interfaces (functions and
            variables) associated with ELF symbols that are defined and
            exported by the Linux Kernel.

            Otherwise, the tool also has the ability to analyze the
            descriptions of the types reachable by the interfaces
            associated with ELF symbols that are visible outside their
            translation unit.  This later possibility is however much
            more resource intensive and results in much slower
            operations.

            That is why this option is enabled by default.

          • --allow-non-exported-interfaces

            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 ELF symbols that are
            defined and exported by the binary.  It's that final ABI
            corpus which is compared against another one.

            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.

            Note that this option is turned off by default.

          • --show-bytes

            Show sizes and offsets in bytes, not bits.  This option is
            activated by default.

          • --show-bits

            Show sizes and offsets in bits, not bytes.  By default,
            sizes and offsets are shown in bytes.

          • --show-hex

            Show sizes and offsets in hexadecimal base.  This option is
            activated by default.

          • --show-dec

            Show sizes and offsets in decimal base.

AUTHOR         top

       Dodji Seketeli

COPYRIGHT         top

       2014-2022, Red Hat, Inc.

COLOPHON         top

       This page is part of the libabigail (ABI Generic Analysis and
       Instrumentation Library) project.  Information about the project
       can be found at ⟨https://sourceware.org/libabigail/⟩.  If you
       have a bug report for this manual page, see
       ⟨http://sourceware.org/bugzilla/enter_bug.cgi?product=libabigail⟩.
       This page was obtained from the project's upstream Git repository
       ⟨git://sourceware.org/git/libabigail.git⟩ on 2024-06-14.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2024-05-31.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

                              Jun 14, 2024                    KMIDIFF(1)