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 includes all the globally defined functions and 9variables, along with a complete representation of their types. It 10also includes a representation of the globally defined ELF symbols of 11the file. The input shared library must contain associated debug 12information in `DWARF`_ format. 13 14When given the ``--linux-tree`` option, this program can also handle a 15Linux kernel tree. That is, a directory tree that contains both the 16vmlinux binary and Linux kernel modules. It analyses those Linux 17kernel binaries and emits an XML representation of the interface 18between the kernel and its module, to standard output. In this case, 19we don't call it an ABI, but a KMI (Kernel Module Interface). The 20emitted KMI includes all the globally defined functions and variables, 21along with a complete representation of their types. The input 22binaries must contain associated debug information in `DWARF`_ format. 23 24Invocation 25========== 26 27:: 28 29 abidw [options] [<path-to-elf-file>] 30 31Options 32======= 33 34 * ``--help | -h`` 35 36 Display a short help about the command and exit. 37 38 * `--version | -v` 39 40 Display the version of the program and exit. 41 42 * ``--debug-info-dir | -d`` <*dir-path*> 43 44 In cases where the debug info for *path-to-elf-file* is in a 45 separate file that is located in a non-standard place, this tells 46 ``abidw`` where to look for that debug info file. 47 48 Note that *dir-path* must point to the root directory under which 49 the debug information is arranged in a tree-like manner. Under 50 Red Hat based systems, that directory is usually 51 ``<root>/usr/lib/debug``. 52 53 This option can be provided several times with different root 54 directories. In that case, ``abidw`` will potentially look into 55 all those root directories to find the split debug info for the 56 elf file. 57 58 Note that this option is not mandatory for split debug information 59 installed by your system's package manager because then 60 ``abidw`` knows where to find it. 61 62 * ``--out-file`` <*file-path*> 63 64 This option instructs ``abidw`` to emit the XML representation of 65 *path-to-elf-file* into the file *file-path*, rather than emitting 66 it to its standard output. 67 68 * ``--noout`` 69 70 This option instructs ``abidw`` to not emit the XML representation 71 of the ABI. So it only reads the ELF and debug information, 72 builds the internal representation of the ABI and exits. This 73 option is usually useful for debugging purposes. 74 75 * ``--no-corpus-path`` 76 77 Do not emit the path attribute for the ABI corpus. 78 79 * ``--suppressions | suppr`` <*path-to-suppression-specifications-file*> 80 81 Use a :ref:`suppression specification <suppr_spec_label>` file 82 located at *path-to-suppression-specifications-file*. Note that 83 this option can appear multiple times on the command line. In 84 that case, all of the provided suppression specification files are 85 taken into account. ABI artifacts matched by the suppression 86 specifications are suppressed from the output of this tool. 87 88 89 * ``--kmi-whitelist | -kaw`` <*path-to-whitelist*> 90 91 When analyzing a Linux kernel binary, this option points to the 92 white list of names of ELF symbols of functions and variables 93 which ABI must be written out. That white list is called a " 94 Kernel Module Interface white list". This is because for the 95 Kernel, we don't talk about the ABI; we rather talk about the 96 interface between the Kernel and its module. Hence the term 97 ``KMI`` rather than ``ABI`` 98 99 Any other function or variable which ELF symbol are not present in 100 that white list will not be considered by the KMI writing process. 101 102 If this option is not provided -- thus if no white list is 103 provided -- then the entire KMI, that is, all publicly defined and 104 exported functions and global variables by the Linux Kernel 105 binaries is emitted. 106 107 * ``--linux-tree | --lt`` 108 109 Make ``abidw`` to consider the input path as a path to a directory 110 containing the vmlinux binary as several kernel modules binaries. 111 In that case, this program emits the representation of the Kernel 112 Module Interface (KMI) on the standard output. 113 114 Below is an example of usage of ``abidw`` on a Linux Kernel tree. 115 116 First, checkout a Linux kernel source tree and build it. Then 117 install the kernel modules in a directory somewhere. Copy the 118 vmlinux binary into that directory too. And then serialize the 119 KMI of that kernel to disk, using ``abidw``: :: 120 121 $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git 122 $ cd linux && git checkout v4.5 123 $ make allyesconfig all 124 $ mkdir build-output 125 $ make INSTALL_MOD_PATH=./build-output modules_install 126 $ cp vmlinux build-output/modules/4.5.0 127 $ abidw --linux-tree build-output/modules/4.5.0 > build-output/linux-4.5.0.kmi 128 129 * ``--headers-dir | --hd`` <headers-directory-path-1> 130 131 Specifies where to find the public headers of the binary that the 132 tool has to consider. The tool will thus filter out types that 133 are not defined in public headers. 134 135 Note that several public header directories can be specified for 136 the binary to consider. In that case the ``--header-dir`` option 137 should be present several times on the command line, like in the 138 following example: :: 139 140 $ abidw --header-dir /some/path \ 141 --header-dir /some/other/path \ 142 binary > binary.abi 143 144 * ``--header-file | --hf`` <header-file-path> 145 146 Specifies where to find one of the public headers of the abi file 147 that the tool has to consider. The tool will thus filter out 148 types that are not defined in public headers. 149 150 * ``--drop-private-types`` 151 152 This option is to be used with the ``--headers-dir`` and/or 153 ``header-file`` options. With this option, types that are *NOT* 154 defined in the headers are entirely dropped from the internal 155 representation build by Libabigail to represent the ABI and will 156 not end up in the abi XML file. 157 158 * ``--no-elf-needed`` 159 160 Do not include the list of DT_NEEDED dependency names in the 161 corpus. 162 163 * ``--drop-undefined-syms`` 164 165 With this option functions or variables for which the (exported) 166 ELF symbol is undefined are dropped from the internal 167 representation build by Libabigail to represent the ABI and will 168 not end up in the abi XML file. 169 170 * ``--merge-translation-units`` 171 172 With this option translation units for the same language (and 173 address size) will be merged together as if the functions, 174 variables and types were all defined together. Note that this 175 also drops the compilation paths used. 176 177 * ``--no-linux-kernel-mode`` 178 179 Without this option, if abipkgiff detects that the binaries it is 180 looking at are Linux Kernel binaries (either vmlinux or modules) 181 then it only considers functions and variables which ELF symbols 182 are listed in the __ksymtab and __ksymtab_gpl sections. 183 184 With this option, abipkgdiff considers the binary as a non-special 185 ELF binary. It thus considers functions and variables which are 186 defined and exported in the ELF sense. 187 188 * ``--check-alternate-debug-info`` <*elf-path*> 189 190 If the debug info for the file *elf-path* contains a reference to 191 an `alternate debug info <alt-di-label>`_ file, ``abidw`` checks 192 that it can find that alternate debug info file. In that case, it 193 emits a meaningful success message mentioning the full path to the 194 alternate debug info file found. Otherwise, it emits an error 195 code. 196 197 * ``--no-show-locs`` 198 199 In the emitted ABI representation, do not show file, line or column 200 where ABI artifacts are defined. 201 202 * ``--no-parameter-names`` 203 204 In the emitted ABI representation, do not show names of function 205 parameters, just the types. 206 207 * ``--no-write-default-sizes`` 208 209 In the XML ABI representation, do not write the size-in-bits for 210 pointer type definitions, reference type definitions, function 211 declarations and function types when they are equal to the default 212 address size of the translation unit. Note that libabigail before 213 1.8 will not set the default size and will interpret types without 214 a size-in-bits attribute as zero sized. 215 216 * ``--type-id-style`` <``sequence``|``hash``> 217 218 This option controls how types are idenfied in the generated XML 219 files. The default ``sequence`` style just numbers (with 220 ``type-id-`` as prefix) the types in the order they are 221 encountered. The ``hash`` style uses a (stable, portable) hash of 222 libabigail's internal type names and is intended to make the XML 223 files easier to diff. 224 225 * ``--check-alternate-debug-info-base-name`` <*elf-path*> 226 227 228 Like ``--check-alternate-debug-info``, but in the success message, 229 only mention the base name of the debug info file; not its full path. 230 231 * ``--load-all-types`` 232 233 By default, ``libabigail`` (and thus ``abidw``) only loads types 234 that are reachable from functions and variables declarations that 235 are publicly defined and exported by the binary. So only those 236 types are present in the output of ``abidw``. This option however 237 makes ``abidw`` load *all* the types defined in the binaries, even 238 those that are not reachable from public declarations. 239 240 * ``--abidiff`` 241 242 Load the ABI of the ELF binary given in argument, save it in 243 libabigail's XML format in a temporary file; read the ABI from the 244 temporary XML file and compare the ABI that has been read back 245 against the ABI of the ELF binary given in argument. The ABIs 246 should compare equal. If they don't, the program emits a 247 diagnostic and exits with a non-zero code. 248 249 This is a debugging and sanity check option. 250 251 * ``--annotate`` 252 253 Annotate the ABIXML output with comments above most elements. The 254 comments are made of the pretty-printed form types, declaration or 255 even ELF symbols. The purpose is to make the ABIXML output more 256 human-readable for debugging or documenting purposes. 257 258 * ``--stats`` 259 260 Emit statistics about various internal things. 261 262 * ``--verbose`` 263 264 Emit verbose logs about the progress of miscellaneous internal 265 things. 266 267Notes 268===== 269 270.. _alt-di-label: 271 272Alternate debug info files 273-------------------------- 274 275As of the version 4 of the DWARF specification, `Alternate debug 276information <http://www.dwarfstd.org/ShowIssue.php?issue=120604.1>`_ 277is a `GNU`_ extension to the DWARF specification. It has however been 278proposed for inclusion into the upcoming version 5 of the DWARF 279standard. You can read more about the GNU extensions to the DWARF 280standard `here 281<https://fedorahosted.org/elfutils/wiki/DwarfExtensions>`_. 282 283.. _ELF: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format 284.. _DWARF: http://www.dwarfstd.org 285.. _GNU: http://www.gnu.org 286 287