[llvm] 8ada9b5 - [doc] Add llvm-ifs commandline guide

[Haowei Wu via llvm-commits]

Author: Haowei Wu
Date: 2022-02-28T11:18:09-08:00
New Revision: 8ada9b570d6e3185c10bc030a3b51f7d2d11c634

URL: https://github.com/llvm/llvm-project/commit/8ada9b570d6e3185c10bc030a3b51f7d2d11c634
DIFF: https://github.com/llvm/llvm-project/commit/8ada9b570d6e3185c10bc030a3b51f7d2d11c634.diff

LOG: [doc] Add llvm-ifs commandline guide

This patch adds llvm-ifs commandline guide

Differential Review: https://reviews.llvm.org/D118514

Added: 
    llvm/docs/CommandGuide/llvm-ifs.rst

Modified: 
    llvm/docs/CommandGuide/index.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/CommandGuide/index.rst b/llvm/docs/CommandGuide/index.rst
index ee69cd83074f1..f358aae754c54 100644
--- a/llvm/docs/CommandGuide/index.rst
+++ b/llvm/docs/CommandGuide/index.rst
@@ -79,6 +79,7 @@ Developer Tools
    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
index 0000000000000..34db332a8d3d2
--- /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=<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 
diff erent 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.