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 in‐
10 cludes 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 di‐
49 rectories. 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 in‐
111 stall the kernel modules in a directory somewhere. Copy the vm‐
112 linux binary into that directory too. And then serialize the KMI
113 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 binary that the
126 tool has to consider. The tool will thus filter out types that
127 are not defined in public headers.
128 Note that several public header directories can be specified for
130 the binary to consider. In that case the --header-dir option
131 should be present several times on the command line, like in the
132 following example:
133 $ abidw --header-dir /some/path \
135 --header-dir /some/other/path \
136 binary > binary.abi
137 • --header-file | --hf <header-file-path>
139 Specifies where to find one of the public headers of the abi file
141 that the tool has to consider. The tool will thus filter out
142 types that are not defined in public headers.
143 • --drop-private-types
145 This option is to be used with the --headers-dir and/or
147 header-file options. With this option, types that are NOT defined
148 in the headers are entirely dropped from the internal representa‐
149 tion build by Libabigail to represent the ABI and will not end up
150 in the abi XML file.
151 • --no-elf-needed
153 Do not include the list of DT_NEEDED dependency names in the cor‐
155 pus.
156 • --drop-undefined-syms
158 With this option functions or variables for which the (exported)
160 ELF symbol is undefined are dropped from the internal representa‐
161 tion build by Libabigail to represent the ABI and will not end up
162 in the abi XML file.
163 • --no-linux-kernel-mode
165 Without this option, if abipkgiff detects that the binaries it is
167 looking at are Linux Kernel binaries (either vmlinux or modules)
168 then it only considers functions and variables which ELF symbols
169 are listed in the __ksymtab and __ksymtab_gpl sections.
170 With this option, abipkgdiff considers the binary as a non-special
172 ELF binary. It thus considers functions and variables which are
173 defined and exported in the ELF sense.
174 • --check-alternate-debug-info <elf-path>
176 If the debug info for the file elf-path contains a reference to an
178 alternate debug info file, abidw checks that it can find that al‐
179 ternate debug info file. In that case, it emits a meaningful suc‐
180 cess message mentioning the full path to the alternate debug info
181 file found. Otherwise, it emits an error code.
182 • --no-show-locs
184 In the emitted ABI representation, do not show file, line or
185 column where ABI artifacts are defined.
186 • --no-parameter-names
188 In the emitted ABI representation, do not show names of function
190 parameters, just the types.
191 • --no-write-default-sizes
193 In the XML ABI representation, do not write the size-in-bits for
195 pointer type definitions, reference type definitions, function
196 declarations and function types when they are equal to the default
197 address size of the translation unit. Note that libabigail before
198 1.8 will not set the default size and will interpret types without
199 a size-in-bits attribute as zero sized.
200 • --type-id-style <sequence``|``hash>
202 This option controls how types are idenfied in the generated XML
204 files. The default sequence style just numbers (with type-id- as
205 prefix) the types in the order they are encountered. The hash
206 style uses a (stable, portable) hash of libabigail’s internal type
207 names and is intended to make the XML files easier to diff.
208 • --check-alternate-debug-info-base-name <elf-path>
210 Like --check-alternate-debug-info, but in the success message,
212 only mention the base name of the debug info file; not its full
213 path.
214 • --load-all-types
216 By default, libabigail (and thus abidw) only loads types that are
218 reachable from functions and variables declarations that are pub‐
219 licly defined and exported by the binary. So only those types are
220 present in the output of abidw. This option however makes abidw
221 load all the types defined in the binaries, even those that are
222 not reachable from public declarations.
223 • --abidiff
225 Load the ABI of the ELF binary given in argument, save it in
226 libabigail’s XML format in a temporary file; read the ABI from
227 the temporary XML file and compare the ABI that has been read
228 back against the ABI of the ELF binary given in argument. The
229 ABIs should compare equal. If they don’t, the program emits a
230 diagnostic and exits with a non-zero code.
231 This is a debugging and sanity check option.
233 • --debug-abidiff
235 Same as --abidiff but in debug mode. In this mode, error mes‐
237 sages are emitted for types which fail type canonicalization.
238 This is an optional debugging and sanity check option. To en‐
240 able it the libabigail package needs to be configured with the
241 –enable-debug-self-comparison option.
242 • --annotate
244 Annotate the ABIXML output with comments above most elements.
245 The comments are made of the pretty-printed form types, declara‐
246 tion or even ELF symbols. The purpose is to make the ABIXML
247 output more human-readable for debugging or documenting pur‐
248 poses.
249 • --stats
251 Emit statistics about various internal things.
253 • --verbose
255 Emit verbose logs about the progress of miscellaneous internal
257 things.
258
260 Alternate debug info files
261 As of the version 4 of the DWARF specification, Alternate debug infor‐
262 mation is a GNU extension to the DWARF specification. It has however
263 been proposed for inclusion into the upcoming version 5 of the DWARF
264 standard. You can read more about the GNU extensions to the DWARF
265 standard here.
266
268 Dodji Seketeli
269
271 2014-2022, Red Hat, Inc.
272 Jan 20, 2022 ABIDW(1)