1 2====== 3abidw 4====== 5 6abidw reads a shared library in `ELF`_ format and emits an XML 7representation of its ABI to standard output. The emitted 8representation format, named ``ABIXML``, includes all the globally 9defined functions and variables, along with a complete representation 10of their types. It also includes a representation of the globally 11defined ELF symbols of the file. 12 13When given the ``--linux-tree`` option, this program can also handle a 14`Linux kernel`_ tree. That is, a directory tree that contains both 15the vmlinux binary and `Linux Kernel`_ modules. It analyses those 16`Linux Kernel`_ binaries and emits an XML representation of the 17interface between the kernel and its module, to standard output. In 18this case, we don't call it an ABI, but a KMI (Kernel Module 19Interface). The emitted KMI includes all the globally defined 20functions and variables, along with a complete representation of their 21types. 22 23To generate either ABI or KMI representation, by default ``abidw`` 24uses debug information in `DWARF`_ format, if present, otherwise it 25looks for debug information in `CTF`_ format, if present, finally, if 26neither is found, it uses only `ELF`_ symbols to report which of them 27were added or removed. 28 29.. include:: tools-use-libabigail.txt 30 31.. _abidiff_invocation_label: 32 33Invocation 34========== 35 36:: 37 38 abidw [options] [<path-to-elf-file>] 39 40Options 41======= 42 43 * ``--help | -h`` 44 45 Display a short help about the command and exit. 46 47 * `--version | -v` 48 49 Display the version of the program and exit. 50 51 * `--abixml-version` 52 53 Display the version of the ABIXML format emitted by this program and exit. 54 55 * ``--debug-info-dir | -d`` <*dir-path*> 56 57 In cases where the debug info for *path-to-elf-file* is in a 58 separate file that is located in a non-standard place, this tells 59 ``abidw`` where to look for that debug info file. 60 61 Note that *dir-path* must point to the root directory under which 62 the debug information is arranged in a tree-like manner. Under 63 Red Hat based systems, that directory is usually 64 ``<root>/usr/lib/debug``. 65 66 This option can be provided several times with different root 67 directories. In that case, ``abidw`` will potentially look into 68 all those root directories to find the split debug info for the 69 elf file. 70 71 Note that this option is not mandatory for split debug information 72 installed by your system's package manager because then 73 ``abidw`` knows where to find it. 74 75 * ``--out-file`` <*file-path*> 76 77 This option instructs ``abidw`` to emit the XML representation of 78 *path-to-elf-file* into the file *file-path*, rather than emitting 79 it to its standard output. 80 81 * ``--noout`` 82 83 This option instructs ``abidw`` to not emit the XML representation 84 of the ABI. So it only reads the ELF and debug information, 85 builds the internal representation of the ABI and exits. This 86 option is usually useful for debugging purposes. 87 88 * ``--no-corpus-path`` 89 90 Do not emit the path attribute for the ABI corpus. 91 92 * ``--suppressions | suppr`` <*path-to-suppression-specifications-file*> 93 94 Use a :ref:`suppression specification <suppr_spec_label>` file 95 located at *path-to-suppression-specifications-file*. Note that 96 this option can appear multiple times on the command line. In 97 that case, all of the provided suppression specification files are 98 taken into account. ABI artifacts matched by the suppression 99 specifications are suppressed from the output of this tool. 100 101 102 * ``--kmi-whitelist | -kaw`` <*path-to-whitelist*> 103 104 When analyzing a `Linux Kernel`_ binary, this option points to the 105 white list of names of ELF symbols of functions and variables 106 which ABI must be written out. That white list is called a " 107 Kernel Module Interface white list". This is because for the 108 Kernel, we don't talk about the ABI; we rather talk about the 109 interface between the Kernel and its module. Hence the term 110 ``KMI`` rather than ``ABI`` 111 112 Any other function or variable which ELF symbol are not present in 113 that white list will not be considered by the KMI writing process. 114 115 If this option is not provided -- thus if no white list is 116 provided -- then the entire KMI, that is, all publicly defined and 117 exported functions and global variables by the `Linux Kernel`_ 118 binaries is emitted. 119 120 * ``--linux-tree | --lt`` 121 122 Make ``abidw`` to consider the input path as a path to a directory 123 containing the vmlinux binary as several kernel modules binaries. 124 In that case, this program emits the representation of the Kernel 125 Module Interface (KMI) on the standard output. 126 127 Below is an example of usage of ``abidw`` on a `Linux Kernel`_ 128 tree. 129 130 First, checkout a `Linux Kernel`_ source tree and build it. Then 131 install the kernel modules in a directory somewhere. Copy the 132 vmlinux binary into that directory too. And then serialize the 133 KMI of that kernel to disk, using ``abidw``: :: 134 135 $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git 136 $ cd linux && git checkout v4.5 137 $ make allyesconfig all 138 $ mkdir build-output 139 $ make INSTALL_MOD_PATH=./build-output modules_install 140 $ cp vmlinux build-output/modules/4.5.0 141 $ abidw --linux-tree build-output/modules/4.5.0 > build-output/linux-4.5.0.kmi 142 143 * ``--headers-dir | --hd`` <headers-directory-path-1> 144 145 Specifies where to find the public headers of the binary that the 146 tool has to consider. The tool will thus filter out types that 147 are not defined in public headers. 148 149 Note that several public header directories can be specified for 150 the binary to consider. In that case the ``--header-dir`` option 151 should be present several times on the command line, like in the 152 following example: :: 153 154 $ abidw --header-dir /some/path \ 155 --header-dir /some/other/path \ 156 binary > binary.abi 157 158 * ``--header-file | --hf`` <header-file-path> 159 160 Specifies where to find one of the public headers of the abi file 161 that the tool has to consider. The tool will thus filter out 162 types that are not defined in public headers. 163 164 * ``--drop-private-types`` 165 166 This option is to be used with the ``--headers-dir`` and/or 167 ``header-file`` options. With this option, types that are *NOT* 168 defined in the headers are entirely dropped from the internal 169 representation build by Libabigail to represent the ABI and will 170 not end up in the abi XML file. 171 172 * ``--no-elf-needed`` 173 174 Do not include the list of DT_NEEDED dependency names in the 175 corpus. 176 177 * ``--drop-undefined-syms`` 178 179 With this option functions or variables for which the (exported) 180 ELF symbol is undefined are dropped from the internal 181 representation build by Libabigail to represent the ABI and will 182 not end up in the abi XML file. 183 184 * ``--exported-interfaces-only`` 185 186 By default, when looking at the debug information accompanying a 187 binary, this tool analyzes the descriptions of the types reachable 188 by the interfaces (functions and variables) that are visible 189 outside of their translation unit. Once that analysis is done, an 190 ABI corpus is constructed by only considering the subset of types 191 reachable from interfaces associated to `ELF`_ symbols that are 192 defined and exported by the binary. It's that final ABI corpus 193 which textual representation is saved as ``ABIXML``. 194 195 The problem with that approach however is that analyzing all the 196 interfaces that are visible from outside their translation unit 197 can amount to a lot of data, especially when those binaries are 198 applications, as opposed to shared libraries. One example of such 199 applications is the `Linux Kernel`_. Analyzing massive ABI 200 corpora like these can be extremely slow. 201 202 To mitigate that performance issue, this option allows libabigail 203 to only analyze types that are reachable from interfaces 204 associated with defined and exported `ELF`_ symbols. 205 206 Note that this option is turned on by default when analyzing the 207 `Linux Kernel`_. Otherwise, it's turned off by default. 208 209 * ``--allow-non-exported-interfaces`` 210 211 When looking at the debug information accompanying a binary, this 212 tool analyzes the descriptions of the types reachable by the 213 interfaces (functions and variables) that are visible outside of 214 their translation unit. Once that analysis is done, an ABI corpus 215 is constructed by only considering the subset of types reachable 216 from interfaces associated to `ELF`_ symbols that are defined and 217 exported by the binary. It's that final ABI corpus which textual 218 representation is saved as ``ABIXML``. 219 220 The problem with that approach however is that analyzing all the 221 interfaces that are visible from outside their translation unit 222 can amount to a lot of data, especially when those binaries are 223 applications, as opposed to shared libraries. One example of such 224 applications is the `Linux Kernel`_. Analyzing massive ABI 225 corpora like these can be extremely slow. 226 227 In the presence of an "average sized" binary however one can 228 afford having libabigail analyze all interfaces that are visible 229 outside of their translation unit, using this option. 230 231 Note that this option is turned on by default, unless we are in 232 the presence of the `Linux Kernel`_. 233 234 * ``--no-linux-kernel-mode`` 235 236 Without this option, if abipkgiff detects that the binaries it is 237 looking at are Linux Kernel binaries (either vmlinux or modules) 238 then it only considers functions and variables which ELF symbols 239 are listed in the __ksymtab and __ksymtab_gpl sections. 240 241 With this option, abipkgdiff considers the binary as a non-special 242 ELF binary. It thus considers functions and variables which are 243 defined and exported in the ELF sense. 244 245 * ``--check-alternate-debug-info`` <*elf-path*> 246 247 If the debug info for the file *elf-path* contains a reference to 248 an `alternate debug info <alt-di-label>`_ file, ``abidw`` checks 249 that it can find that alternate debug info file. In that case, it 250 emits a meaningful success message mentioning the full path to the 251 alternate debug info file found. Otherwise, it emits an error 252 code. 253 254 * ``--no-show-locs`` 255 256 In the emitted ABI representation, do not show file, line or column 257 where ABI artifacts are defined. 258 259 * ``--no-parameter-names`` 260 261 In the emitted ABI representation, do not show names of function 262 parameters, just the types. 263 264 * ``--no-write-default-sizes`` 265 266 In the XML ABI representation, do not write the size-in-bits for 267 pointer type definitions, reference type definitions, function 268 declarations and function types when they are equal to the default 269 address size of the translation unit. Note that libabigail before 270 1.8 will not set the default size and will interpret types without 271 a size-in-bits attribute as zero sized. 272 273 * ``--type-id-style`` <``sequence``|``hash``> 274 275 This option controls how types are idenfied in the generated XML 276 files. The default ``sequence`` style just numbers (with 277 ``type-id-`` as prefix) the types in the order they are 278 encountered. The ``hash`` style uses a (stable, portable) hash of 279 libabigail's internal type names and is intended to make the XML 280 files easier to diff. 281 282 * ``--check-alternate-debug-info-base-name`` <*elf-path*> 283 284 285 Like ``--check-alternate-debug-info``, but in the success message, 286 only mention the base name of the debug info file; not its full path. 287 288 * ``--load-all-types`` 289 290 By default, ``libabigail`` (and thus ``abidw``) only loads types 291 that are reachable from functions and variables declarations that 292 are publicly defined and exported by the binary. So only those 293 types are present in the output of ``abidw``. This option however 294 makes ``abidw`` load *all* the types defined in the binaries, even 295 those that are not reachable from public declarations. 296 297 * ``--abidiff`` 298 299 Load the ABI of the ELF binary given in argument, save it in 300 libabigail's XML format in a temporary file; read the ABI from the 301 temporary XML file and compare the ABI that has been read back 302 against the ABI of the ELF binary given in argument. The ABIs 303 should compare equal. If they don't, the program emits a 304 diagnostic and exits with a non-zero code. 305 306 This is a debugging and sanity check option. 307 308 * ``--debug-abidiff`` 309 310 Same as ``--abidiff`` but in debug mode. In this mode, error 311 messages are emitted for types which fail type canonicalization. 312 313 This is an optional debugging and sanity check option. To enable 314 it the libabigail package needs to be configured with 315 the --enable-debug-self-comparison option. 316 317 * ``--debug-type-canonicalization | --debug-tc`` 318 319 Debug the type canonicalization process. This is done by using 320 structural and canonical equality when canonicalizing every single 321 type. Structural and canonical equality should yield the same 322 result. If they don't yield the same result for a given type, 323 then it means that the canonicalization of that type went wrong. 324 In that case, an error message is emitted and the execution of the 325 program is aborted. 326 327 This option is available only if the package was configured with 328 the --enable-debug-type-canonicalization option. 329 330 * ``--no-assume-odr-for-cplusplus`` 331 332 When analysing a binary originating from C++ code using `DWARF`_ 333 debug information, libabigail assumes the `One Definition Rule`_ 334 to speed-up the analysis. In that case, when several types have 335 the same name in the binary, they are assumed to all be equal. 336 337 This option disables that assumption and instructs libabigail to 338 actually actually compare the types to determine if they are 339 equal. 340 341 * ``--no-leverage-dwarf-factorization`` 342 343 When analysing a binary which `DWARF`_ debug information was 344 processed with the `DWZ`_ tool, the type information is supposed 345 to be already factorized. That context is used by libabigail to 346 perform some speed optimizations. 347 348 This option disables those optimizations. 349 350 * ``--ctf`` 351 352 Extract ABI information from `CTF`_ debug information, if present in 353 the given object. 354 355 * ``--annotate`` 356 357 Annotate the ABIXML output with comments above most elements. The 358 comments are made of the pretty-printed form types, declaration or 359 even ELF symbols. The purpose is to make the ABIXML output more 360 human-readable for debugging or documenting purposes. 361 362 * ``--stats`` 363 364 Emit statistics about various internal things. 365 366 * ``--verbose`` 367 368 Emit verbose logs about the progress of miscellaneous internal 369 things. 370 371Notes 372===== 373 374.. _alt-di-label: 375 376Alternate debug info files 377-------------------------- 378 379As of the version 4 of the DWARF specification, `Alternate debug 380information <http://www.dwarfstd.org/ShowIssue.php?issue=120604.1>`_ 381is a `GNU`_ extension to the DWARF specification. It has however been 382proposed for inclusion into the upcoming version 5 of the DWARF 383standard. You can read more about the GNU extensions to the DWARF 384standard `here 385<https://fedorahosted.org/elfutils/wiki/DwarfExtensions>`_. 386 387.. _ELF: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format 388.. _DWARF: http://www.dwarfstd.org 389.. _GNU: http://www.gnu.org 390.. _Linux Kernel: https://kernel.org/ 391.. _CTF: https://raw.githubusercontent.com/wiki/oracle/binutils-gdb/files/ctf-spec.pdf 392.. _ODR: https://en.wikipedia.org/wiki/One_Definition_Rule 393.. _One Definition Rule: https://en.wikipedia.org/wiki/One_Definition_Rule 394.. _DWZ: https://sourceware.org/dwz 395