LLVM-IFS(1) LLVM LLVM-IFS(1)
NAME
llvm-ifs - shared object stubbing tool
SYNOPSIS
llvm-ifs [options] inputs
DESCRIPTION
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 ob-
ject. 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 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 informa-
tion 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 func-
tions, and is optional for NoType symbols.
• Undefined: Whether or not the symbol is defined in this shared ob-
ject 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 gen-
erate 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 in-
dicates 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
--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.
--output-elf=<output-filename>
Specify the output file for ELF shared object stub.
--output-ifs=<output-filename>
Specify the output file for text IFS.
--output-tbd=<output-filename>
Specify the output file for Apple TAPI tbd.
--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 con-
flicting with the IFS file, an error will be reported and the
program will stop.
--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.
--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 pro-
gram will stop.
--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 simul-
taneously with other target related flags.
--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 re-
flect 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 ob-
ject file, an error will be reported and the program will stop.
--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.
--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.
--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.
--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.
--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.
--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 llvm-ifs succeeds, it will exit with 0. Otherwise, if an error oc-
curs, it will exit with a non-zero value.
AUTHOR
Maintained by the LLVM Team (https://llvm.org/).
COPYRIGHT
2003-2023, LLVM Project
15 2023-10-16 LLVM-IFS(1)
Generated by dwww version 1.15 on Sun Jun 23 21:39:55 CEST 2024.