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 format,
10 named ABIXML, includes all the globally defined functions and vari‐
11 ables, along with a complete representation of their types. It also
12 includes a representation of the globally defined ELF symbols of the
13 file.
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.
23 To generate either ABI or KMI representation, by default abidw uses de‐
25 bug information in the DWARF format, if present, otherwise it looks for
26 debug information in CTF or BTF formats, if present. Finally, if no
27 debug info in these formats is found, it only considers ELF symbols and
28 report about their addition or removal.
29 This tool uses the libabigail library to analyze the binary as well as
31 its associated debug information. Here is its general mode of opera‐
32 tion.
33 When instructed to do so, a binary and its associated debug information
35 is read and analyzed. To that effect, libabigail analyzes by default
36 the descriptions of the types reachable by the interfaces (functions
37 and variables) that are visible outside of their translation unit.
38 Once that analysis is done, an Application Binary Interface Corpus is
39 constructed by only considering the subset of types reachable from in‐
40 terfaces associated to ELF symbols that are defined and exported by the
41 binary. It’s that final ABI corpus which libabigail considers as rep‐
42 resenting the ABI of the analyzed binary.
43 Libabigail then has capabilities to generate textual representations of
45 ABI Corpora, compare them, analyze their changes and report about them.
46
48 abidw [options] [<path-to-elf-file>]
49
51 • --help | -h
52 Display a short help about the command and exit.
54 • --version | -v
56 Display the version of the program and exit.
58 • --abixml-version
60 Display the version of the ABIXML format emitted by this program
62 and exit.
63 • --add-binaries <bin1,bin2,…>
65 For each of the comma-separated binaries given in argument to this
67 option, if the binary is found in the directory specified by the
68 –added-binaries-dir option, then load the ABI corpus of the binary
69 and add it to a set of ABI corpora (called a ABI Corpus Group)
70 made of the binary denoted by the Argument of abidw. That corpus
71 group is then serialized out.
72 • --follow-dependencies
74 For each dependency of the input binary of abidw, if it is found
76 in the directory specified by the --added-binaries-dir option,
77 then construct an ABI corpus out of the dependency and add it to a
78 set of ABI corpora (called an ABI Corpus Group) along with the ABI
79 corpus of the input binary of the program. The ABI Corpus Group
80 is then serialized out.
81 • --list-dependencies
83 For each dependency of the input binary of``abidw``, if it’s found
85 in the directory specified by the --added-binaries-dir option,
86 then the name of the dependency is printed out.
87 • --added-binaries-dir | --abd <dir-path>
89 This option is to be used in conjunction with the --add-binaries,
91 the --follow-dependencies or the --list-dependencies option. Bi‐
92 naries listed as arguments of the --add-binaries option or being
93 dependencies of the input binary in the case of the --follow-de‐
94 pendencies option and found in the directory <dir-path> are going
95 to be loaded as ABI corpus and added to the set of ABI corpora
96 (called an ABI corpus group) built and serialized.
97 • --debug-info-dir | -d <dir-path>
99 In cases where the debug info for path-to-elf-file is in a sepa‐
101 rate file that is located in a non-standard place, this tells
102 abidw where to look for that debug info file.
103 Note that dir-path must point to the root directory under which
105 the debug information is arranged in a tree-like manner. Under
106 Red Hat based systems, that directory is usually
107 <root>/usr/lib/debug.
108 This option can be provided several times with different root di‐
110 rectories. In that case, abidw will potentially look into all
111 those root directories to find the split debug info for the elf
112 file.
113 Note that this option is not mandatory for split debug information
115 installed by your system’s package manager because then abidw
116 knows where to find it.
117 • --out-file <file-path>
119 This option instructs abidw to emit the XML representation of
121 path-to-elf-file into the file file-path, rather than emitting it
122 to its standard output.
123 • --noout
125 This option instructs abidw to not emit the XML representation of
127 the ABI. So it only reads the ELF and debug information, builds
128 the internal representation of the ABI and exits. This option is
129 usually useful for debugging purposes.
130 • --no-corpus-path
132 Do not emit the path attribute for the ABI corpus.
134 • --suppressions | suppr <path-to-suppression-specifications-file>
136 Use a suppression specification file located at path-to-suppres‐
138 sion-specifications-file. Note that this option can appear multi‐
139 ple times on the command line. In that case, all of the provided
140 suppression specification files are taken into account. ABI arti‐
141 facts matched by the suppression specifications are suppressed
142 from the output of this tool.
143 • --kmi-whitelist | -kaw <path-to-whitelist>
145 When analyzing a Linux Kernel binary, this option points to the
147 white list of names of ELF symbols of functions and variables
148 which ABI must be written out. That white list is called a ” Ker‐
149 nel Module Interface white list”. This is because for the Kernel,
150 we don’t talk about the ABI; we rather talk about the interface
151 between the Kernel and its module. Hence the term KMI rather than
152 ABI
153 Any other function or variable which ELF symbol are not present in
155 that white list will not be considered by the KMI writing process.
156 If this option is not provided – thus if no white list is provided
158 – then the entire KMI, that is, all publicly defined and exported
159 functions and global variables by the Linux Kernel binaries is
160 emitted.
161 • --linux-tree | --lt
163 Make abidw to consider the input path as a path to a directory
165 containing the vmlinux binary as several kernel modules binaries.
166 In that case, this program emits the representation of the Kernel
167 Module Interface (KMI) on the standard output.
168 Below is an example of usage of abidw on a Linux Kernel tree.
170 First, checkout a Linux Kernel source tree and build it. Then in‐
172 stall the kernel modules in a directory somewhere. Copy the vm‐
173 linux binary into that directory too. And then serialize the KMI
174 of that kernel to disk, using abidw:
175 $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
177 $ cd linux && git checkout v4.5
178 $ make allyesconfig all
179 $ mkdir build-output
180 $ make INSTALL_MOD_PATH=./build-output modules_install
181 $ cp vmlinux build-output/modules/4.5.0
182 $ abidw --linux-tree build-output/modules/4.5.0 > build-output/linux-4.5.0.kmi
183 • --headers-dir | --hd <headers-directory-path-1>
185 Specifies where to find the public headers of the binary that the
187 tool has to consider. The tool will thus filter out types that
188 are not defined in public headers.
189 Note that several public header directories can be specified for
191 the binary to consider. In that case the --header-dir option
192 should be present several times on the command line, like in the
193 following example:
194 $ abidw --header-dir /some/path \
196 --header-dir /some/other/path \
197 binary > binary.abi
198 • --header-file | --hf <header-file-path>
200 Specifies where to find one of the public headers of the abi file
202 that the tool has to consider. The tool will thus filter out
203 types that are not defined in public headers.
204 • --drop-private-types
206 This option is to be used with the --headers-dir and/or
208 header-file options. With this option, types that are NOT defined
209 in the headers are entirely dropped from the internal representa‐
210 tion build by Libabigail to represent the ABI and will not end up
211 in the abi XML file.
212 • --no-elf-needed
214 Do not include the list of DT_NEEDED dependency names in the cor‐
216 pus.
217 • --drop-undefined-syms
219 With this option functions or variables for which the (exported)
221 ELF symbol is undefined are dropped from the internal representa‐
222 tion build by Libabigail to represent the ABI and will not end up
223 in the abi XML file.
224 • --exported-interfaces-only
226 By default, when looking at the debug information accompanying a
228 binary, this tool analyzes the descriptions of the types reachable
229 by the interfaces (functions and variables) that are visible out‐
230 side of their translation unit. Once that analysis is done, an
231 ABI corpus is constructed by only considering the subset of types
232 reachable from interfaces associated to ELF symbols that are de‐
233 fined and exported by the binary. It’s that final ABI corpus
234 which textual representation is saved as ABIXML.
235 The problem with that approach however is that analyzing all the
237 interfaces that are visible from outside their translation unit
238 can amount to a lot of data, especially when those binaries are
239 applications, as opposed to shared libraries. One example of such
240 applications is the Linux Kernel. Analyzing massive ABI corpora
241 like these can be extremely slow.
242 To mitigate that performance issue, this option allows libabigail
244 to only analyze types that are reachable from interfaces associ‐
245 ated with defined and exported ELF symbols.
246 Note that this option is turned on by default when analyzing the
248 Linux Kernel. Otherwise, it’s turned off by default.
249 • --allow-non-exported-interfaces
251 When looking at the debug information accompanying a binary, this
253 tool analyzes the descriptions of the types reachable by the in‐
254 terfaces (functions and variables) that are visible outside of
255 their translation unit. Once that analysis is done, an ABI corpus
256 is constructed by only considering the subset of types reachable
257 from interfaces associated to ELF symbols that are defined and ex‐
258 ported by the binary. It’s that final ABI corpus which textual
259 representation is saved as ABIXML.
260 The problem with that approach however is that analyzing all the
262 interfaces that are visible from outside their translation unit
263 can amount to a lot of data, especially when those binaries are
264 applications, as opposed to shared libraries. One example of such
265 applications is the Linux Kernel. Analyzing massive ABI corpora
266 like these can be extremely slow.
267 In the presence of an “average sized” binary however one can af‐
269 ford having libabigail analyze all interfaces that are visible
270 outside of their translation unit, using this option.
271 Note that this option is turned on by default, unless we are in
273 the presence of the Linux Kernel.
274 • --no-linux-kernel-mode
276 Without this option, if abipkgiff detects that the binaries it is
278 looking at are Linux Kernel binaries (either vmlinux or modules)
279 then it only considers functions and variables which ELF symbols
280 are listed in the __ksymtab and __ksymtab_gpl sections.
281 With this option, abipkgdiff considers the binary as a non-special
283 ELF binary. It thus considers functions and variables which are
284 defined and exported in the ELF sense.
285 • --check-alternate-debug-info <elf-path>
287 If the debug info for the file elf-path contains a reference to an
289 alternate debug info file, abidw checks that it can find that al‐
290 ternate debug info file. In that case, it emits a meaningful suc‐
291 cess message mentioning the full path to the alternate debug info
292 file found. Otherwise, it emits an error code.
293 • --no-show-locs
295 In the emitted ABI representation, do not show file, line or
296 column where ABI artifacts are defined.
297 • --no-parameter-names
299 In the emitted ABI representation, do not show names of function
301 parameters, just the types.
302 • --no-write-default-sizes
304 In the XML ABI representation, do not write the size-in-bits for
306 pointer type definitions, reference type definitions, function
307 declarations and function types when they are equal to the default
308 address size of the translation unit. Note that libabigail before
309 1.8 will not set the default size and will interpret types without
310 a size-in-bits attribute as zero sized.
311 • --type-id-style <sequence``|``hash>
313 This option controls how types are idenfied in the generated XML
315 files. The default sequence style just numbers (with type-id- as
316 prefix) the types in the order they are encountered. The hash
317 style uses a (stable, portable) hash of libabigail’s internal type
318 names and is intended to make the XML files easier to diff.
319 • --check-alternate-debug-info-base-name <elf-path>
321 Like --check-alternate-debug-info, but in the success message,
323 only mention the base name of the debug info file; not its full
324 path.
325 • --load-all-types
327 By default, libabigail (and thus abidw) only loads types that are
329 reachable from functions and variables declarations that are pub‐
330 licly defined and exported by the binary. So only those types are
331 present in the output of abidw. This option however makes abidw
332 load all the types defined in the binaries, even those that are
333 not reachable from public declarations.
334 • --abidiff
336 Load the ABI of the ELF binary given in argument, save it in
337 libabigail’s XML format in a temporary file; read the ABI from
338 the temporary XML file and compare the ABI that has been read
339 back against the ABI of the ELF binary given in argument. The
340 ABIs should compare equal. If they don’t, the program emits a
341 diagnostic and exits with a non-zero code.
342 This is a debugging and sanity check option.
344 • --debug-abidiff
346 Same as --abidiff but in debug mode. In this mode, error mes‐
348 sages are emitted for types which fail type canonicalization.
349 This is an optional debugging and sanity check option. To en‐
351 able it the libabigail package needs to be configured with the
352 –enable-debug-self-comparison option.
353 • --debug-type-canonicalization | --debug-tc
355 Debug the type canonicalization process. This is done by using
357 structural and canonical equality when canonicalizing every sin‐
358 gle type. Structural and canonical equality should yield the
359 same result. If they don’t yield the same result for a given
360 type, then it means that the canonicalization of that type went
361 wrong. In that case, an error message is emitted and the execu‐
362 tion of the program is aborted.
363 This option is available only if the package was configured with
365 the –enable-debug-type-canonicalization option.
366 • --no-assume-odr-for-cplusplus
368 When analysing a binary originating from C++ code using DWARF de‐
370 bug information, libabigail assumes the One Definition Rule to
371 speed-up the analysis. In that case, when several types have the
372 same name in the binary, they are assumed to all be equal.
373 This option disables that assumption and instructs libabigail to
375 actually actually compare the types to determine if they are
376 equal.
377 • --no-leverage-dwarf-factorization
379 When analysing a binary which DWARF debug information was pro‐
381 cessed with the DWZ tool, the type information is supposed to be
382 already factorized. That context is used by libabigail to perform
383 some speed optimizations.
384 This option disables those optimizations.
386 • --ctf
388 Extract ABI information from CTF debug information, if present in
390 the given object.
391 • --annotate
393 Annotate the ABIXML output with comments above most elements.
394 The comments are made of the pretty-printed form types, declara‐
395 tion or even ELF symbols. The purpose is to make the ABIXML
396 output more human-readable for debugging or documenting pur‐
397 poses.
398 • --stats
400 Emit statistics about various internal things.
402 • --verbose
404 Emit verbose logs about the progress of miscellaneous internal
406 things.
407
409 1. Emitting an ABIXML representation of a binary:
410 $ abidw binary > binary.abi
412 2. Emitting an ABIXML representation of a set of binaries specified
414 on the command line:
415 $ abidw --added-binaries=bin1,bin2,bin3 \
417 --added-binaries-dir /some/where \
418 binary > binaries.abi
419 Note that the binaries bin1, bin2 and bin3 are to be found in the
421 directory /some/where. A representation of the ABI of the set of
422 binaries binary, bin1, bin2 and bin3 called an ABI corpus group
423 is serialized in the file binaries.abi.
424 3. Emitting an ABIXML representation of a binary and its dependen‐
426 cies:
427 $ abidw --follow-dependencies \
429 --added-binaries-dir /some/where \
430 binary > binary.abi
431 Note that only the dependencies that are found in the directory
433 /some/where are analysed. Their ABIs, along with the ABI the bi‐
434 nary named binary are represented as an ABI corpus group and se‐
435 rialized in the file binary.abi, in the ABIXML format.
436
438 Alternate debug info files
439 As of the version 4 of the DWARF specification, Alternate debug infor‐
440 mation is a GNU extension to the DWARF specification. It has however
441 been proposed for inclusion into the upcoming version 5 of the DWARF
442 standard. You can read more about the GNU extensions to the DWARF
443 standard here.
444
446 Dodji Seketeli
447
449 2014-2023, Red Hat, Inc.
450 Nov 20, 2023 ABIDW(1)