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 DWARF format, if present, otherwise it looks for de‐
26 bug information in CTF format, if present, finally, if neither is
27 found, it uses only ELF symbols to report which of them were added or
28 removed.
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 • --debug-info-dir | -d <dir-path>
65 In cases where the debug info for path-to-elf-file is in a sepa‐
67 rate file that is located in a non-standard place, this tells
68 abidw where to look for that debug info file.
69 Note that dir-path must point to the root directory under which
71 the debug information is arranged in a tree-like manner. Under
72 Red Hat based systems, that directory is usually
73 <root>/usr/lib/debug.
74 This option can be provided several times with different root di‐
76 rectories. In that case, abidw will potentially look into all
77 those root directories to find the split debug info for the elf
78 file.
79 Note that this option is not mandatory for split debug information
81 installed by your system’s package manager because then abidw
82 knows where to find it.
83 • --out-file <file-path>
85 This option instructs abidw to emit the XML representation of
87 path-to-elf-file into the file file-path, rather than emitting it
88 to its standard output.
89 • --noout
91 This option instructs abidw to not emit the XML representation of
93 the ABI. So it only reads the ELF and debug information, builds
94 the internal representation of the ABI and exits. This option is
95 usually useful for debugging purposes.
96 • --no-corpus-path
98 Do not emit the path attribute for the ABI corpus.
100 • --suppressions | suppr <path-to-suppression-specifications-file>
102 Use a suppression specification file located at path-to-suppres‐
104 sion-specifications-file. Note that this option can appear multi‐
105 ple times on the command line. In that case, all of the provided
106 suppression specification files are taken into account. ABI arti‐
107 facts matched by the suppression specifications are suppressed
108 from the output of this tool.
109 • --kmi-whitelist | -kaw <path-to-whitelist>
111 When analyzing a Linux Kernel binary, this option points to the
113 white list of names of ELF symbols of functions and variables
114 which ABI must be written out. That white list is called a ” Ker‐
115 nel Module Interface white list”. This is because for the Kernel,
116 we don’t talk about the ABI; we rather talk about the interface
117 between the Kernel and its module. Hence the term KMI rather than
118 ABI
119 Any other function or variable which ELF symbol are not present in
121 that white list will not be considered by the KMI writing process.
122 If this option is not provided – thus if no white list is provided
124 – then the entire KMI, that is, all publicly defined and exported
125 functions and global variables by the Linux Kernel binaries is
126 emitted.
127 • --linux-tree | --lt
129 Make abidw to consider the input path as a path to a directory
131 containing the vmlinux binary as several kernel modules binaries.
132 In that case, this program emits the representation of the Kernel
133 Module Interface (KMI) on the standard output.
134 Below is an example of usage of abidw on a Linux Kernel tree.
136 First, checkout a Linux Kernel source tree and build it. Then in‐
138 stall the kernel modules in a directory somewhere. Copy the vm‐
139 linux binary into that directory too. And then serialize the KMI
140 of that kernel to disk, using abidw:
141 $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
143 $ cd linux && git checkout v4.5
144 $ make allyesconfig all
145 $ mkdir build-output
146 $ make INSTALL_MOD_PATH=./build-output modules_install
147 $ cp vmlinux build-output/modules/4.5.0
148 $ abidw --linux-tree build-output/modules/4.5.0 > build-output/linux-4.5.0.kmi
149 • --headers-dir | --hd <headers-directory-path-1>
151 Specifies where to find the public headers of the binary that the
153 tool has to consider. The tool will thus filter out types that
154 are not defined in public headers.
155 Note that several public header directories can be specified for
157 the binary to consider. In that case the --header-dir option
158 should be present several times on the command line, like in the
159 following example:
160 $ abidw --header-dir /some/path \
162 --header-dir /some/other/path \
163 binary > binary.abi
164 • --header-file | --hf <header-file-path>
166 Specifies where to find one of the public headers of the abi file
168 that the tool has to consider. The tool will thus filter out
169 types that are not defined in public headers.
170 • --drop-private-types
172 This option is to be used with the --headers-dir and/or
174 header-file options. With this option, types that are NOT defined
175 in the headers are entirely dropped from the internal representa‐
176 tion build by Libabigail to represent the ABI and will not end up
177 in the abi XML file.
178 • --no-elf-needed
180 Do not include the list of DT_NEEDED dependency names in the cor‐
182 pus.
183 • --drop-undefined-syms
185 With this option functions or variables for which the (exported)
187 ELF symbol is undefined are dropped from the internal representa‐
188 tion build by Libabigail to represent the ABI and will not end up
189 in the abi XML file.
190 • --exported-interfaces-only
192 By default, when looking at the debug information accompanying a
194 binary, this tool analyzes the descriptions of the types reachable
195 by the interfaces (functions and variables) that are visible out‐
196 side of their translation unit. Once that analysis is done, an
197 ABI corpus is constructed by only considering the subset of types
198 reachable from interfaces associated to ELF symbols that are de‐
199 fined and exported by the binary. It’s that final ABI corpus
200 which textual representation is saved as ABIXML.
201 The problem with that approach however is that analyzing all the
203 interfaces that are visible from outside their translation unit
204 can amount to a lot of data, especially when those binaries are
205 applications, as opposed to shared libraries. One example of such
206 applications is the Linux Kernel. Analyzing massive ABI corpora
207 like these can be extremely slow.
208 To mitigate that performance issue, this option allows libabigail
210 to only analyze types that are reachable from interfaces associ‐
211 ated with defined and exported ELF symbols.
212 Note that this option is turned on by default when analyzing the
214 Linux Kernel. Otherwise, it’s turned off by default.
215 • --allow-non-exported-interfaces
217 When looking at the debug information accompanying a binary, this
219 tool analyzes the descriptions of the types reachable by the in‐
220 terfaces (functions and variables) that are visible outside of
221 their translation unit. Once that analysis is done, an ABI corpus
222 is constructed by only considering the subset of types reachable
223 from interfaces associated to ELF symbols that are defined and ex‐
224 ported by the binary. It’s that final ABI corpus which textual
225 representation is saved as ABIXML.
226 The problem with that approach however is that analyzing all the
228 interfaces that are visible from outside their translation unit
229 can amount to a lot of data, especially when those binaries are
230 applications, as opposed to shared libraries. One example of such
231 applications is the Linux Kernel. Analyzing massive ABI corpora
232 like these can be extremely slow.
233 In the presence of an “average sized” binary however one can af‐
235 ford having libabigail analyze all interfaces that are visible
236 outside of their translation unit, using this option.
237 Note that this option is turned on by default, unless we are in
239 the presence of the Linux Kernel.
240 • --no-linux-kernel-mode
242 Without this option, if abipkgiff detects that the binaries it is
244 looking at are Linux Kernel binaries (either vmlinux or modules)
245 then it only considers functions and variables which ELF symbols
246 are listed in the __ksymtab and __ksymtab_gpl sections.
247 With this option, abipkgdiff considers the binary as a non-special
249 ELF binary. It thus considers functions and variables which are
250 defined and exported in the ELF sense.
251 • --check-alternate-debug-info <elf-path>
253 If the debug info for the file elf-path contains a reference to an
255 alternate debug info file, abidw checks that it can find that al‐
256 ternate debug info file. In that case, it emits a meaningful suc‐
257 cess message mentioning the full path to the alternate debug info
258 file found. Otherwise, it emits an error code.
259 • --no-show-locs
261 In the emitted ABI representation, do not show file, line or
262 column where ABI artifacts are defined.
263 • --no-parameter-names
265 In the emitted ABI representation, do not show names of function
267 parameters, just the types.
268 • --no-write-default-sizes
270 In the XML ABI representation, do not write the size-in-bits for
272 pointer type definitions, reference type definitions, function
273 declarations and function types when they are equal to the default
274 address size of the translation unit. Note that libabigail before
275 1.8 will not set the default size and will interpret types without
276 a size-in-bits attribute as zero sized.
277 • --type-id-style <sequence``|``hash>
279 This option controls how types are idenfied in the generated XML
281 files. The default sequence style just numbers (with type-id- as
282 prefix) the types in the order they are encountered. The hash
283 style uses a (stable, portable) hash of libabigail’s internal type
284 names and is intended to make the XML files easier to diff.
285 • --check-alternate-debug-info-base-name <elf-path>
287 Like --check-alternate-debug-info, but in the success message,
289 only mention the base name of the debug info file; not its full
290 path.
291 • --load-all-types
293 By default, libabigail (and thus abidw) only loads types that are
295 reachable from functions and variables declarations that are pub‐
296 licly defined and exported by the binary. So only those types are
297 present in the output of abidw. This option however makes abidw
298 load all the types defined in the binaries, even those that are
299 not reachable from public declarations.
300 • --abidiff
302 Load the ABI of the ELF binary given in argument, save it in
303 libabigail’s XML format in a temporary file; read the ABI from
304 the temporary XML file and compare the ABI that has been read
305 back against the ABI of the ELF binary given in argument. The
306 ABIs should compare equal. If they don’t, the program emits a
307 diagnostic and exits with a non-zero code.
308 This is a debugging and sanity check option.
310 • --debug-abidiff
312 Same as --abidiff but in debug mode. In this mode, error mes‐
314 sages are emitted for types which fail type canonicalization.
315 This is an optional debugging and sanity check option. To en‐
317 able it the libabigail package needs to be configured with the
318 –enable-debug-self-comparison option.
319 • --debug-type-canonicalization | --debug-tc
321 Debug the type canonicalization process. This is done by using
323 structural and canonical equality when canonicalizing every sin‐
324 gle type. Structural and canonical equality should yield the
325 same result. If they don’t yield the same result for a given
326 type, then it means that the canonicalization of that type went
327 wrong. In that case, an error message is emitted and the execu‐
328 tion of the program is aborted.
329 This option is available only if the package was configured with
331 the –enable-debug-type-canonicalization option.
332 • --no-assume-odr-for-cplusplus
334 When analysing a binary originating from C++ code using DWARF de‐
336 bug information, libabigail assumes the One Definition Rule to
337 speed-up the analysis. In that case, when several types have the
338 same name in the binary, they are assumed to all be equal.
339 This option disables that assumption and instructs libabigail to
341 actually actually compare the types to determine if they are
342 equal.
343 • --no-leverage-dwarf-factorization
345 When analysing a binary which DWARF debug information was pro‐
347 cessed with the DWZ tool, the type information is supposed to be
348 already factorized. That context is used by libabigail to perform
349 some speed optimizations.
350 This option disables those optimizations.
352 • --ctf
354 Extract ABI information from CTF debug information, if present in
356 the given object.
357 • --annotate
359 Annotate the ABIXML output with comments above most elements.
360 The comments are made of the pretty-printed form types, declara‐
361 tion or even ELF symbols. The purpose is to make the ABIXML
362 output more human-readable for debugging or documenting pur‐
363 poses.
364 • --stats
366 Emit statistics about various internal things.
368 • --verbose
370 Emit verbose logs about the progress of miscellaneous internal
372 things.
373
375 Alternate debug info files
376 As of the version 4 of the DWARF specification, Alternate debug infor‐
377 mation is a GNU extension to the DWARF specification. It has however
378 been proposed for inclusion into the upcoming version 5 of the DWARF
379 standard. You can read more about the GNU extensions to the DWARF
380 standard here.
381
383 Dodji Seketeli
384
386 2014-2022, Red Hat, Inc.
387 Dec 02, 2022 ABIDW(1)