[PATCH 02/14] kmidiff.rst: Sort options and their documentation
Dodji Seketeli
dodji@seketeli.org
Fri Sep 25 21:05:56 GMT 2026
This patch sorts the options and their documentation in the kmidiff
manual.
* doc/manuals/kmidiff.rst: Sort option docs.
Signed-off-by: Dodji Seketeli <dodji@seketeli.org>
---
doc/manuals/kmidiff.rst | 174 ++++++++++++++++++++++------------------
1 file changed, 96 insertions(+), 78 deletions(-)
diff --git a/doc/manuals/kmidiff.rst b/doc/manuals/kmidiff.rst
index c2a3c970..7ac91426 100644
--- a/doc/manuals/kmidiff.rst
+++ b/doc/manuals/kmidiff.rst
@@ -124,18 +124,34 @@ interfaces (along with their types).
Options
=======
- * ``--help | -h``
+ * ``--allow-non-exported-interfaces``
- Display a short help about the command and exit.
+ 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.
- * ``--version | -v``
- Display the version of the program and exit.
+ * ``--btf``
- * ``--verbose``
+ Extract ABI information from `BTF`_ debug information, if present,
+ in the Kernel and Modules.
+
+
+ * ``--ctf``
+
+ Extract ABI information from `CTF`_ debug information, if present,
+ in the Kernel and Modules.
- Display some verbose messages while executing.
* ``--debug-info-dir1 | --d1`` <*di-path1*>
@@ -148,23 +164,46 @@ Options
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.
+ * ``--exported-interfaces-only``
- * ``--vmlinux2 | --l2`` <*path-to-first-vmlinux*>
+ 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.
+
+
+ * ``--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.
+
+
+ * ``--impacted-interfaces | -i``
+
+ Tell what interfaces got impacted by each individual ABI change.
- 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*>
@@ -180,17 +219,6 @@ Options
So please, make sure you always use this option unless you really
know what you are doing.
- * ``--suppressions | --suppr`` <*path-to-suppressions*>
-
- Use a :ref:`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 :ref:`default suppression specification files
- <abidiff_default_supprs_label>` are loaded .
* ``--no-change-categorization | -x``
@@ -203,76 +231,42 @@ Options
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.
+ * ``--show-bits``
- 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.
+ Show sizes and offsets in bits, not bytes. By default, sizes and
+ offsets are shown in bytes.
- 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-dec``
+
+ Show sizes and offsets in decimal base.
+
* ``--show-hex``
Show sizes and offsets in hexadecimal base. This option is
activated by default.
- * ``--show-dec``
- Show sizes and offsets in decimal base.
+ * ``--suppressions | --suppr`` <*path-to-suppressions*>
+
+ Use a :ref:`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 :ref:`default suppression specification files
+ <abidiff_default_supprs_label>` are loaded .
+
* ``--thread-pool-size <N|N%> | -j <N|N%>``
@@ -287,6 +281,30 @@ Options
present, supersedes the value of the environment variable.
+ * ``--verbose``
+
+ Display some verbose messages while executing.
+
+
+ * ``--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.
+
+
.. _ELF: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format
.. _ksymtab: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format
.. _Linux Kernel: https://kernel.org
--
2.55.0
More information about the Libabigail
mailing list