RepoMirrors/libabigail
1
0
Fork 0
mirror of git://sourceware.org/git/libabigail.git synced 2025-01-22 01:03:02 +00:00
Code Issues Packages Projects Releases Wiki Activity
077b977ce5
libabigail/doc/manuals/abidw.rst
Dodji Seketeli adb656cc76 Initial support of the serialization of the KMI of a Linux Kernel Tree 
We have the kmidiff program that takes two Linux Kernel trees
containing the vmlinux binary and its modules and compare their Kernel
Module Interface, aka KMI.

We need to be able to serialize (save in a file) a representation of
that KMI.  We need to load that KMI back, and compare two serialized
KMIs.

This patch implements the serialization of the KMI of a Linux Kernel
tree.  It actually serializes an instance of abigail::ir::corpus_group
that is a collection of instances of abigail::ir::corpus.  The KMI of
each individual binary (vmlinux or kernel module) is represented by
one abigail::ir::corpus.  All the corpora share the same definitions
of types and decls, whenever that makes sense.

The patch thus factorizes the routines used to walk a Linux kernel out
of the kmidiff program.  These routines are then re-used in the abidw
program to make it walk a Linux kernel tree (when the --linux-tree
option is provided), load the vmlinux and module binaries as an
instance of abigail::corpus_group and serialize it out into an output
stream.

	* include/abg-tools-utils.h (check_dir)
	(get_binary_paths_from_kernel_dist)
	(build_corpus_group_from_kernel_dist_under): Declare new
	functions.  The last two functions are being moved from
	tools/kmidiff.cc so that they can be re-used.
	* include/abg-writer.h (write_corpus): Declare one overload that
	takes a write_context parameter.
	(write_corpus_group): Declare three overloads of this new function.
	* src/abg-tools-utils.cc (check_dir): Define new function.
	(load_generate_apply_suppressions, is_vmlinux, is_kernel_module)
	(find_vmlinux_and_module_paths)
	(get_binary_paths_from_kernel_dist)
	(build_corpus_group_from_kernel_dist_under): Define new functions.
	* src/abg-writer.cc (write_context::set_annotate): Define new
	member function.
	(write_corpus): Add an overload that takes a write_context.  Adapt
	the existing overload to make it use this new one.
	(write_corpus_group): Define this new function and two additional
	overloads for it.
	* tools/kmidiff.cc (set_suppressions, is_vmlinux)
	(is_kernel_module, find_vmlinux_and_module_paths)
	(get_binary_paths_from_kernel_dist)
	(build_corpus_group_from_kernel_dist_under): Remove.
	(main): Adjust the call to
	build_corpus_group_from_kernel_dist_under as its arguments are now
	adapted since it's been factorized out into abg-tools-utils.h.
	* tools/abidw.cc (options::corpus_group_for_linux): Define new
	data member.
	(options::options): Adjust.
	(display_usage): Add help strings for the new --linux-tree option.
	(load_corpus_and_write_abixml): Factorize this function out of the
	main function.
	(load_kernel_corpus_group_and_write_abixml): Define new function.
	(main): Use the factorized load_corpus_and_write_abixml and the
	new load_corpus_and_write_abixml functions.
	* tests/test-read-write.cc: Adjust.
	* doc/manuals/abidw.rst: Add documentation for the new
	--linux-tree option.

Signed-off-by: Dodji Seketeli <dodji@redhat.com>
2017-07-03 17:45:41 +02:00

214 lines
8.1 KiB
ReStructuredText
Raw Blame History

====== abidw ======
abidw reads a shared library in `ELF`_ format and emits an XML
representation of its ABI to standard output. The emitted
representation includes all the globally defined functions and
variables, along with a complete representation of their types. It
also includes a representation of the globally defined ELF symbols of
the file. The input shared library must contain associated debug
information in `DWARF`_ format.
When given the ``--linux-tree`` option, this program can also handle a
Linux kernel tree. That is, a directory tree that contains both the
vmlinux binary and Linux kernel modules. It analyses those Linux
kernel binaries and emits an XML representation of the interface
between the kernel and its module, to standard output. In this case,
we don't call it an ABI, but a KMI (Kernel Module Interface). The
emitted KMI includes all the globally defined functions and variables,
along with a complete representation of their types. The input
binaries must contain associated debug information in `DWARF`_ format.
Invocation
==========
::
abidw [options] [<path-to-elf-file>]
Options
=======
* ``--help | -h``
Display a short help about the command and exit.
* `--version | -v`
Display the version of the program and exit.
* ``--debug-info-dir | -d`` <*dir-path*>
In cases where the debug info for *path-to-elf-file* is in a
separate file that is located in a non-standard place, this tells
``abidw`` where to look for that debug info file.
Note that *dir-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``.
Note that this option is not mandatory for split debug information
installed by your system's package manager because then
``abidw`` knows where to find it.
* ``--out-file`` <*file-path*>
This option instructs ``abidw`` to emit the XML representation of
*path-to-elf-file* into the file *file-path*, rather than emitting
it to its standard output.
* ``--noout``
This option instructs ``abidw`` to not emit the XML representation
of the ABI. So it only reads the ELF and debug information,
builds the internal representation of the ABI and exits. This
option is usually useful for debugging purposes.
* ``--no-corpus-path``
Do not emit the path attribute for the ABI corpus.
* ``--suppressions | suppr`` <*path-to-suppression-specifications-file*>
Use a :ref:`suppression specification <suppr_spec_label>` file
located at *path-to-suppression-specifications-file*. 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. ABI artifacts matched by the suppression
specifications are suppressed from the output of this tool.
* ``--kmi-whitelist | -kaw`` <*path-to-whitelist*>
When analyzing a Linux kernel binary, this option points to the
white list of names of ELF symbols of functions and variables
which ABI must be written out. That white list is called a "
Kernel Module Interface white list". This is because for the
Kernel, we don't talk about the ABI; we rather talk about the
interface between the Kernel and its module. Hence the term
``KMI`` rather than ``ABI``
Any other function or variable which ELF symbol are not present in
that white list will not be considered by the KMI writing process.
If this option is not provided -- thus if no white list is
provided -- then the entire KMI, that is, all publicly defined and
exported functions and global variables by the Linux Kernel
binaries is emitted.
* ``--linux-tree | --lt``
Make ``abidw`` to consider the input path as a path to a directory
containing the vmlinux binary as several kernel modules binaries.
In that case, this program emits the representation of the Kernel
Module Interface (KMI) on the standard output.
Below is an example of usage of ``abidw`` on a Linux Kernel tree.
First, checkout a Linux kernel source tree and build it. Then
install the kernel modules in a directory somewhere. Copy the
vmlinux binary into that directory too. And then serialize the
KMI of that kernel to disk, using ``abidw``: ::
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
$ cd linux && git checkout v4.5
$ make allyesconfig all
$ mkdir build-output
$ make INSTALL_MOD_PATH=./build-output modules_install
$ cp vmlinux build-output/modules/4.5.0
$ abidw --linux-tree build-output/modules/4.5.0 > build-output/linux-4.5.0.kmi
* ``--headers-dir | --hd`` <headers-directory-path-1>
Specifies where to find the public headers of the first shared
library that the tool has to consider. The tool will thus filter
out types that are not defined in public headers.
* ``--no-linux-kernel-mode``
Without this option, if abipkgiff detects that the binaries it is
looking at are Linux Kernel binaries (either vmlinux or modules)
then it only considers functions and variables which ELF symbols
are listed in the __ksymtab and __ksymtab_gpl sections.
With this option, abipkgdiff considers the binary as a non-special
ELF binary. It thus considers functions and variables which are
defined and exported in the ELF sense.
* ``--check-alternate-debug-info`` <*elf-path*>
If the debug info for the file *elf-path* contains a reference to
an `alternate debug info <alt-di-label>`_ file, ``abidw`` checks
that it can find that alternate debug info file. In that case, it
emits a meaningful success message mentioning the full path to the
alternate debug info file found. Otherwise, it emits an error
code.
* ``--no-show-locs``
Do not show information about where in the *second shared library*
the respective type was changed.
* ``--check-alternate-debug-info-base-name`` <*elf-path*>
Like ``--check-alternate-debug-info``, but in the success message,
only mention the base name of the debug info file; not its full path.
* ``--load-all-types``
By default, ``libabigail`` (and thus ``abidw``) only loads types
that are reachable from functions and variables declarations that
are publicly defined and exported by the binary. So only those
types are present in the output of ``abidw``. This option however
makes ``abidw`` load *all* the types defined in the binaries, even
those that are not reachable from public declarations.
* ``--abidiff``
Load the ABI of the ELF binary given in argument, save it in
libabigail's XML format in a temporary file; read the ABI from the
temporary XML file and compare the ABI that has been read back
against the ABI of the ELF binary given in argument. The ABIs
should compare equal. If they don't, the program emits a
diagnostic and exits with a non-zero code.
This is a debugging and sanity check option.
* ``--annotate``
Annotate the ABIXML output with comments above most elements. The
comments are made of the pretty-printed form types, declaration or
even ELF symbols. The purpose is to make the ABIXML output more
human-readable for debugging or documenting purposes.
* ``--stats``
Emit statistics about various internal things.
* ``--verbose``
Emit verbose logs about the progress of miscellaneous internal
things.
Notes
=====
.. _alt-di-label:
Alternate debug info files
--------------------------
As of the version 4 of the DWARF specification, `Alternate debug
information <http://www.dwarfstd.org/ShowIssue.php?issue=120604.1>`_
is a `GNU`_ extension to the DWARF specification. It has however been
proposed for inclusion into the upcoming version 5 of the DWARF
standard. You can read more about the GNU extensions to the DWARF
standard `here
<https://fedorahosted.org/elfutils/wiki/DwarfExtensions>`_.
.. _ELF: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format
.. _DWARF: http://www.dwarfstd.org
.. _GNU: http://www.gnu.org
Reference in New Issue View Git Blame Copy Permalink