1ABIDW(1)                          Libabigail                          ABIDW(1)
2
3
4

NAME

6       abidw - serialize the ABI of an ELF file
7
8       abidw reads a shared library in ELF format and emits an XML representa‐
9       tion of  its  ABI  to  standard  output.   The  emitted  representation
10       includes 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
15       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

INVOCATION

26          abidw [options] [<path-to-elf-file>]
27

OPTIONS

29          · --help | -h
30
31            Display a short help about the command and exit.
32
33          · –version | -v
34
35            Display the version of the program and exit.
36
37          · --debug-info-dir | -d <dir-path>
38
39            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
43            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
48            This  option  can  be  provided  several times with different root
49            directories.  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
53            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
57          · --out-file <file-path>
58
59            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
63          · --noout
64
65            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
70          · --no-corpus-path
71
72            Do not emit the path attribute for the ABI corpus.
73
74          · --suppressions | suppr <path-to-suppression-specifications-file>
75
76            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
83          · --kmi-whitelist | -kaw <path-to-whitelist>
84
85            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
93            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
96            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
101          · --linux-tree | --lt
102
103            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
108            Below is an example of usage of abidw on a Linux Kernel tree.
109
110            First,  checkout  a  Linux  kernel source tree and build it.  Then
111            install the kernel modules in a  directory  somewhere.   Copy  the
112            vmlinux  binary  into  that directory too.  And then serialize the
113            KMI of that kernel to disk, using abidw:
114
115                $ 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
123          · --headers-dir | --hd <headers-directory-path-1>
124
125            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
129            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
134                $ abidw --header-dir /some/path       \
135                        --header-dir /some/other/path \
136                        binary > binary.abi
137
138          · --header-file | --hf <header-file-path>
139
140            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
144          · --drop-private-types
145
146            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
152          · --no-elf-needed
153
154            Do  not include the list of DT_NEEDED dependency names in the cor‐
155            pus.
156
157          · --drop-undefined-syms
158
159            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
164          · --no-linux-kernel-mode
165
166            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
171            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
175          · --check-alternate-debug-info <elf-path>
176
177            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
179            alternate debug info file.  In that case, it  emits  a  meaningful
180            success  message  mentioning  the full path to the alternate debug
181            info file found.  Otherwise, it emits an error code.
182
183          · --no-show-locs
184              In the emitted ABI representation, do not  show  file,  line  or
185              column where ABI artifacts are defined.
186
187          · --no-parameter-names
188
189            In  the  emitted ABI representation, do not show names of function
190            parameters, just the types.
191
192          · --no-write-default-sizes
193
194            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
201          · --type-id-style <sequence``|``hash>
202
203            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
209          · --check-alternate-debug-info-base-name <elf-path>
210
211            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
215          · --load-all-types
216
217            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
224          · --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
232              This is a debugging and sanity check option.
233
234          · --annotate
235              Annotate  the  ABIXML  output with comments above most elements.
236              The comments are made of the pretty-printed form types, declara‐
237              tion  or  even  ELF  symbols.  The purpose is to make the ABIXML
238              output more human-readable for  debugging  or  documenting  pur‐
239              poses.
240
241          · --stats
242
243            Emit statistics about various internal things.
244
245          · --verbose
246
247            Emit  verbose  logs  about  the progress of miscellaneous internal
248            things.
249

NOTES

251   Alternate debug info files
252       As of the version 4 of the DWARF specification, Alternate debug  infor‐
253       mation  is  a GNU extension to the DWARF specification.  It has however
254       been proposed for inclusion into the upcoming version 5  of  the  DWARF
255       standard.   You  can  read  more  about the GNU extensions to the DWARF
256       standard here.
257

AUTHOR

259       Dodji Seketeli
260
262       2014-2021, Red Hat, Inc.
263
264
265
266
267                                 Feb 25, 2021                         ABIDW(1)
Impressum