diff --git a/llvm/docs/CommandGuide/index.rst b/llvm/docs/CommandGuide/index.rst --- a/llvm/docs/CommandGuide/index.rst +++ b/llvm/docs/CommandGuide/index.rst @@ -79,6 +79,7 @@ mlir-tblgen lit llvm-exegesis + llvm-ifs llvm-locstats llvm-pdbutil llvm-profgen diff --git a/llvm/docs/CommandGuide/llvm-ifs.rst b/llvm/docs/CommandGuide/llvm-ifs.rst new file mode 100644 --- /dev/null +++ b/llvm/docs/CommandGuide/llvm-ifs.rst @@ -0,0 +1,201 @@ +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= + + Specify the output file for ELF shared object stub. + +.. option:: --output-ifs= + + Specify the output file for text IFS. + +.. option:: --output-tbd= + + 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= + + 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= + + 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. + +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.