209 lines
7.2 KiB
ReStructuredText
209 lines
7.2 KiB
ReStructuredText
llvm-ifs - shared object stubbing tool
|
|
======================================
|
|
|
|
.. program:: llvm-ifs
|
|
|
|
SYNOPSIS
|
|
--------
|
|
|
|
:program:`llvm-ifs` [*options*] *inputs*
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
:program:`llvm-ifs` is a tool that jointly produces human readable text-based
|
|
stubs (.ifs files) for shared objects and linkable shared object stubs
|
|
(.so files) from either ELF shared objects or text-based stubs. The text-based
|
|
stubs is useful for monitoring ABI changes of the shared object. The linkable
|
|
shared object stubs can be used to avoid unnecessary relinks when the ABI of
|
|
shared libraries does not change.
|
|
|
|
|
|
IFS FORMATS
|
|
-----------
|
|
|
|
Here is an example of the text representation (IFS) of a shared object produced
|
|
by the :program:`llvm-ifs`:
|
|
|
|
::
|
|
|
|
--- !ifs-v1
|
|
IFSVersion: 3.0
|
|
SoName: libtest.so /* Optional */
|
|
Target: x86_64-unknown-linux-gnu /* Optional, format 1, same format as llvm target triple */
|
|
Target: { Arch: x86_64, Endianness: little, Bitwidth: 64 } /* Optional, format 2 */
|
|
NeededLibs:
|
|
- libc.so.6
|
|
Symbols:
|
|
- { Name: sym0, Type: Notype }
|
|
- { Name: sym1, Type: Object, Size: 0 }
|
|
- { Name: sym2, Type: Func, Weak: false }
|
|
- { Name: sym3, Type: TLS }
|
|
- { Name: sym4, Type: Unknown, Warning: foo }
|
|
...
|
|
|
|
* ``IFSVersion``: Version of the IFS file for reader compatibility.
|
|
|
|
* ``SoName`` (optional): Name of the shared object file that is being stubbed.
|
|
|
|
* ``Target`` (optional): The architecture, endianness and bitwise information of
|
|
this shared object. It can be either in explicit format or in implicit LLVM
|
|
triple format. It can be optional and can be overridden from command line
|
|
options.
|
|
|
|
* ``NeededLibs``: The list of the external shared objects that this library depends on.
|
|
|
|
* ``Symbols``: A collection of all data needed to link objects for each symbol, sorted by name in ascending order.
|
|
|
|
+ ``Name``: Symbol name.
|
|
|
|
+ ``Type``: Whether the symbol is an object, function, no-type, thread local storage, or unknown. Symbol types not explicitly supported are mapped as unknown to improve signal-to-noise ratio.
|
|
|
|
+ ``Size``: The size of the symbol in question, doesn't apply to functions, and is optional for NoType symbols.
|
|
|
|
+ ``Undefined``: Whether or not the symbol is defined in this shared object file.
|
|
|
|
+ ``Weak``: Whether or not the symbol should be treated as weak.
|
|
|
|
+ ``Warning`` (optional): Warning text to output when this symbol is linked against.
|
|
|
|
This YAML based text format contains everything that is needed to generate a
|
|
linkable ELF shared object as well as an Apple TAPI format file. The ordering
|
|
of symbols is sorted, so these files can be easily compared using diff tools.
|
|
If the content of the file changes, it indicates a potentially ABI breaking
|
|
change.
|
|
|
|
|
|
ELF STUB FORMAT
|
|
---------------
|
|
|
|
A minimum ELF file that can be used by linker should have following sections properly populated:
|
|
|
|
* ELF header.
|
|
|
|
* Section headers.
|
|
|
|
* Dynamic symbol table (``.dynsym`` section).
|
|
|
|
* Dynamic string table (``.dynstr`` section).
|
|
|
|
* Dynamic table (``.dynamic`` section).
|
|
|
|
+ ``DT_SYMTAB`` entry.
|
|
|
|
+ ``DT_STRTAB`` entry.
|
|
|
|
+ ``DT_STRSZ`` entry.
|
|
|
|
+ ``DT_NEEDED`` entries. (optional)
|
|
|
|
+ ``DT_SONAME`` entry. (optional)
|
|
|
|
* Section header string table (``.shstrtab`` section)
|
|
|
|
This ELF file may have compatibility issues with ELF analysis tools that rely on the program headers.
|
|
Linkers like LLD work fine with such a minimum ELF file without errors.
|
|
|
|
OPTIONS
|
|
-------
|
|
|
|
.. option:: --input-format=[IFS|ELF|OtherObjectFileFormats]
|
|
|
|
Specify input file format. Currently, only text IFS files and ELF shared
|
|
object files are supported. This flag is optional as the input format can be
|
|
inferred.
|
|
|
|
.. option:: --output-elf=<output-filename>
|
|
|
|
Specify the output file for ELF shared object stub.
|
|
|
|
.. option:: --output-ifs=<output-filename>
|
|
|
|
Specify the output file for text IFS.
|
|
|
|
.. option:: --output-tbd=<output-filename>
|
|
|
|
Specify the output file for Apple TAPI tbd.
|
|
|
|
.. option:: --arch=[x86_64|AArch64|...]
|
|
|
|
This flag is optional and it should only be used when reading an IFS file
|
|
which does not define the ``Arch`` (architecture). This flag defines the
|
|
architecture of the output file, and can be any string supported by ELF
|
|
'e_machine' field. If the value is conflicting with the IFS file, an error
|
|
will be reported and the program will stop.
|
|
|
|
.. option:: --endianness=[little|big]
|
|
|
|
This flag is optional and it should only be used when reading an IFS file
|
|
which does not define the ``Endianness``. This flag defines the endianness of
|
|
the output file. If the value is conflicting with the IFS file, an error
|
|
will be reported and the program will stop.
|
|
|
|
.. option:: --bitwidth=[32|64]
|
|
|
|
This flag is optional and it should only be used when reading an IFS file
|
|
which does not define the ``BitWidth``. This flag defines the bit width of the
|
|
output file. If the value is conflicting with the input IFS file, an error
|
|
will be reported and the program will stop.
|
|
|
|
.. option:: --target=<target triple>
|
|
|
|
This flag is optional and should only be used when reading an IFS file
|
|
which does not define any target information. This flag defines architecture,
|
|
endianness and bit width of the output file using llvm target triple.
|
|
This flag cannot be used simultaneously with other target related flags.
|
|
|
|
.. option:: --hint-ifs-target=<target triple>
|
|
|
|
This flag is optional and should only be used when reading an ELF shared
|
|
object and generating an IFS file. by default, llvm-ifs will use '``Arch``,
|
|
``Endianness`` and ``BitWidth``' fields to reflect the target information from the
|
|
input object file. Using this flag will tell llvm-ifs the expected target
|
|
triple in the output IFS file. If the value matches the target information
|
|
from the object file, this value will be used in the 'Target:' filed in the
|
|
generated IFS. If it conflicts with the input object file, an error will be
|
|
reported and the program will stop.
|
|
|
|
.. option:: --hint-ifs-target
|
|
|
|
This flag is optional and should only be used when outputting an IFS file.
|
|
This flag strips the ``Arch`` field from the IFS file so it can be overridden
|
|
later.
|
|
|
|
.. option:: --strip-ifs-endianness
|
|
|
|
This flag is optional and should only be used when outputting an IFS file.
|
|
This flag strips the ``Endianness`` field from the IFS file so it can be
|
|
overridden later.
|
|
|
|
.. option:: --strip-ifs-bitwidth
|
|
|
|
This flag is optional and should only be used when outputting an IFS file.
|
|
This flag strips the ``BitWidth`` field from the IFS file so it can be overridden
|
|
later.
|
|
|
|
.. option:: --strip-ifs-target
|
|
|
|
This flag is optional and should only be used when outputting an IFS file.
|
|
This flag strips the ``Target`` field from the IFS file so it can be overridden
|
|
later.
|
|
|
|
.. option:: --write-if-changed
|
|
|
|
When this flag is set, llvm-ifs will only write the output file if it does not
|
|
already exist or the content will be different from the existing file.
|
|
|
|
.. option:: --strip-size
|
|
|
|
When this flag is set, llvm-ifs will remove the size field from the output ifs
|
|
file. This is useful for shared objects that only intend to be linked against
|
|
position independent code which doesn't need copy relocations, or where the size
|
|
of an object is not a useful part of the abi to track.
|
|
|
|
EXIT STATUS
|
|
-----------
|
|
|
|
If :program:`llvm-ifs` succeeds, it will exit with 0. Otherwise, if an
|
|
error occurs, it will exit with a non-zero value.
|