1ABIDW(1) Libabigail ABIDW(1)
2
6 abidw - serialize the ABI of an ELF file
7 abidw reads a shared library in ELF format and emits an XML representa‐
9 tion of its ABI to standard output. The emitted representation
10 includes all the globally defined functions and variables, along with a
11 complete representation of their types. It also includes a representa‐
12 tion of the globally defined ELF symbols of the file. The input shared
13 library must contain associated debug information in DWARF format.
14 When given the --linux-tree option, this program can also handle a
16 Linux kernel tree. That is, a directory tree that contains both the
17 vmlinux binary and Linux kernel modules. It analyses those Linux ker‐
18 nel binaries and emits an XML representation of the interface between
19 the kernel and its module, to standard output. In this case, we don’t
20 call it an ABI, but a KMI (Kernel Module Interface). The emitted KMI
21 includes all the globally defined functions and variables, along with a
22 complete representation of their types. The input binaries must con‐
23 tain associated debug information in DWARF format.
24
26 abidw [options] [<path-to-elf-file>]
27
29 · --help | -h
30 Display a short help about the command and exit.
32 · –version | -v
34 Display the version of the program and exit.
36 · --debug-info-dir | -d <dir-path>
38 In cases where the debug info for path-to-elf-file is in a sepa‐
40 rate file that is located in a non-standard place, this tells
41 abidw where to look for that debug info file.
42 Note that dir-path must point to the root directory under which
44 the debug information is arranged in a tree-like manner. Under
45 Red Hat based systems, that directory is usually
46 <root>/usr/lib/debug.
47 This option can be provided several times with different root
49 directories. In that case, abidw will potentially look into all
50 those root directories to find the split debug info for the elf
51 file.
52 Note that this option is not mandatory for split debug information
54 installed by your system’s package manager because then abidw
55 knows where to find it.
56 · --out-file <file-path>
58 This option instructs abidw to emit the XML representation of
60 path-to-elf-file into the file file-path, rather than emitting it
61 to its standard output.
62 · --noout
64 This option instructs abidw to not emit the XML representation of
66 the ABI. So it only reads the ELF and debug information, builds
67 the internal representation of the ABI and exits. This option is
68 usually useful for debugging purposes.
69 · --no-corpus-path
71 Do not emit the path attribute for the ABI corpus.
73 · --suppressions | suppr <path-to-suppression-specifications-file>
75 Use a suppression specification file located at path-to-suppres‐
77 sion-specifications-file. Note that this option can appear multi‐
78 ple times on the command line. In that case, all of the provided
79 suppression specification files are taken into account. ABI arti‐
80 facts matched by the suppression specifications are suppressed
81 from the output of this tool.
82 · --kmi-whitelist | -kaw <path-to-whitelist>
84 When analyzing a Linux kernel binary, this option points to the
86 white list of names of ELF symbols of functions and variables
87 which ABI must be written out. That white list is called a ” Ker‐
88 nel Module Interface white list”. This is because for the Kernel,
89 we don’t talk about the ABI; we rather talk about the interface
90 between the Kernel and its module. Hence the term KMI rather than
91 ABI
92 Any other function or variable which ELF symbol are not present in
94 that white list will not be considered by the KMI writing process.
95 If this option is not provided – thus if no white list is provided
97 – then the entire KMI, that is, all publicly defined and exported
98 functions and global variables by the Linux Kernel binaries is
99 emitted.
100 · --linux-tree | --lt
102 Make abidw to consider the input path as a path to a directory
104 containing the vmlinux binary as several kernel modules binaries.
105 In that case, this program emits the representation of the Kernel
106 Module Interface (KMI) on the standard output.
107 Below is an example of usage of abidw on a Linux Kernel tree.
109 First, checkout a Linux kernel source tree and build it. Then
111 install the kernel modules in a directory somewhere. Copy the
112 vmlinux binary into that directory too. And then serialize the
113 KMI of that kernel to disk, using abidw:
114 $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
116 $ cd linux && git checkout v4.5
117 $ make allyesconfig all
118 $ mkdir build-output
119 $ make INSTALL_MOD_PATH=./build-output modules_install
120 $ cp vmlinux build-output/modules/4.5.0
121 $ abidw --linux-tree build-output/modules/4.5.0 > build-output/linux-4.5.0.kmi
122 · --headers-dir | --hd <headers-directory-path-1>
124 Specifies where to find the public headers of the first shared
126 library that the tool has to consider. The tool will thus filter
127 out types that are not defined in public headers.
128 · --no-linux-kernel-mode
130 Without this option, if abipkgiff detects that the binaries it is
132 looking at are Linux Kernel binaries (either vmlinux or modules)
133 then it only considers functions and variables which ELF symbols
134 are listed in the __ksymtab and __ksymtab_gpl sections.
135 With this option, abipkgdiff considers the binary as a non-special
137 ELF binary. It thus considers functions and variables which are
138 defined and exported in the ELF sense.
139 · --check-alternate-debug-info <elf-path>
141 If the debug info for the file elf-path contains a reference to an
143 alternate debug info file, abidw checks that it can find that
144 alternate debug info file. In that case, it emits a meaningful
145 success message mentioning the full path to the alternate debug
146 info file found. Otherwise, it emits an error code.
147 · --no-show-locs
149 In the emitted ABI representation, do not show file, line or
150 column where ABI artifacts are defined.
151 · --check-alternate-debug-info-base-name <elf-path>
153 Like --check-alternate-debug-info, but in the success message,
155 only mention the base name of the debug info file; not its full
156 path.
157 · --load-all-types
159 By default, libabigail (and thus abidw) only loads types that are
161 reachable from functions and variables declarations that are pub‐
162 licly defined and exported by the binary. So only those types are
163 present in the output of abidw. This option however makes abidw
164 load all the types defined in the binaries, even those that are
165 not reachable from public declarations.
166 · --abidiff
168 Load the ABI of the ELF binary given in argument, save it in
169 libabigail’s XML format in a temporary file; read the ABI from
170 the temporary XML file and compare the ABI that has been read
171 back against the ABI of the ELF binary given in argument. The
172 ABIs should compare equal. If they don’t, the program emits a
173 diagnostic and exits with a non-zero code.
174 This is a debugging and sanity check option.
176 · --annotate
178 Annotate the ABIXML output with comments above most elements.
179 The comments are made of the pretty-printed form types, declara‐
180 tion or even ELF symbols. The purpose is to make the ABIXML
181 output more human-readable for debugging or documenting pur‐
182 poses.
183 · --stats
185 Emit statistics about various internal things.
187 · --verbose
189 Emit verbose logs about the progress of miscellaneous internal
191 things.
192
194 Alternate debug info files
195 As of the version 4 of the DWARF specification, Alternate debug infor‐
196 mation is a GNU extension to the DWARF specification. It has however
197 been proposed for inclusion into the upcoming version 5 of the DWARF
198 standard. You can read more about the GNU extensions to the DWARF
199 standard here.
200
202 Dodji Seketeli
203
205 2014-2016, Red Hat, Inc.
206 Mar 29, 2019 ABIDW(1)