llvm/docs/CommandGuide/llvm-ifs.rst

   1 llvm-ifs - shared object stubbing tool
   2 ======================================
   3
   4 .. program:: llvm-ifs
   5
   6 SYNOPSIS
   7 --------
   8
   9 :program:`llvm-ifs` [*options*] *inputs*
  10
  11 DESCRIPTION
  12 -----------
  13
  14 :program:`llvm-ifs` is a tool that jointly produces human readable text-based
  15 stubs (.ifs files) for shared objects and linkable shared object stubs
  16 (.so files) from either ELF shared objects or text-based stubs. The text-based
  17 stubs is useful for monitoring ABI changes of the shared object. The linkable
  18 shared object stubs can be used to avoid unnecessary relinks when the ABI of
  19 shared libraries does not change.
  20
  21
  22 IFS FORMATS
  23 -----------
  24
  25 Here is an example of the text representation (IFS) of a shared object produced
  26 by the :program:`llvm-ifs`:
  27
  28 ::
  29
  30   --- !ifs-v1
  31   IFSVersion: 3.0
  32   SoName: libtest.so /* Optional */
  33   Target: x86_64-unknown-linux-gnu   /* Optional, format 1, same format as llvm target triple */
  34   Target: { Arch: x86_64, Endianness: little, Bitwidth: 64 } /* Optional, format 2 */
  35   NeededLibs:
  36     - libc.so.6
  37   Symbols:
  38     - { Name: sym0, Type: Notype }
  39     - { Name: sym1, Type: Object, Size: 0 }
  40     - { Name: sym2, Type: Func, Weak: false }
  41     - { Name: sym3, Type: TLS }
  42     - { Name: sym4, Type: Unknown, Warning: foo }
  43   ...
  44
  45 * ``IFSVersion``: Version of the IFS file for reader compatibility.
  46
  47 * ``SoName`` (optional): Name of the shared object file that is being stubbed.
  48
  49 * ``Target`` (optional): The architecture, endianness and bitwise information of
  50   this shared object. It can be either in explicit format or in implicit LLVM
  51   triple format. It can be optional and can be overridden from command line
  52   options.
  53
  54 * ``NeededLibs``: The list of the external shared objects that this library depends on.
  55
  56 * ``Symbols``: A collection of all data needed to link objects for each symbol, sorted by name in ascending order.
  57
  58   + ``Name``: Symbol name.
  59
  60   + ``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.
  61
  62   + ``Size``: The size of the symbol in question, doesn't apply to functions, and is optional for NoType symbols.
  63
  64   + ``Undefined``: Whether or not the symbol is defined in this shared object file.
  65
  66   + ``Weak``: Whether or not the symbol should be treated as weak.
  67
  68   + ``Warning`` (optional): Warning text to output when this symbol is linked against.
  69
  70 This YAML based text format contains everything that is needed to generate a
  71 linkable ELF shared object as well as an Apple TAPI format file. The ordering
  72 of symbols is sorted, so these files can be easily compared using diff tools.
  73 If the content of the file changes, it indicates a potentially ABI breaking
  74 change.
  75
  76
  77 ELF STUB FORMAT
  78 ---------------
  79
  80 A minimum ELF file that can be used by linker should have following sections properly populated:
  81
  82 * ELF header.
  83
  84 * Section headers.
  85
  86 * Dynamic symbol table (``.dynsym`` section).
  87
  88 * Dynamic string table (``.dynstr`` section).
  89
  90 * Dynamic table (``.dynamic`` section).
  91
  92   + ``DT_SYMTAB`` entry.
  93
  94   + ``DT_STRTAB`` entry.
  95
  96   + ``DT_STRSZ`` entry.
  97
  98   + ``DT_NEEDED`` entries. (optional)
  99
 100   + ``DT_SONAME`` entry. (optional)
 101
 102 * Section header string table (``.shstrtab`` section)
 103
 104 This ELF file may have compatibility issues with ELF analysis tools that rely on the program headers.
 105 Linkers like LLD work fine with such a minimum ELF file without errors.
 106
 107 OPTIONS
 108 -------
 109
 110 .. option:: --input-format=[IFS|ELF|OtherObjectFileFormats]
 111
 112  Specify input file format. Currently, only text IFS files and ELF shared
 113  object files are supported. This flag is optional as the input format can be
 114  inferred.
 115
 116 .. option:: --output-elf=<output-filename>
 117
 118  Specify the output file for ELF shared object stub.
 119
 120 .. option:: --output-ifs=<output-filename>
 121
 122  Specify the output file for text IFS.
 123
 124 .. option:: --output-tbd=<output-filename>
 125
 126  Specify the output file for Apple TAPI tbd.
 127
 128 .. option:: --arch=[x86_64|AArch64|...]
 129
 130  This flag is optional and it should only be used when reading an IFS file
 131  which does not define the ``Arch`` (architecture). This flag defines the
 132  architecture of the output file, and can be any string supported by ELF
 133  'e_machine' field. If the value is conflicting with the IFS file, an error
 134  will be reported and the program will stop.
 135
 136 .. option:: --endianness=[little|big]
 137
 138  This flag is optional and it should only be used when reading an IFS file
 139  which does not define the ``Endianness``. This flag defines the endianness of
 140  the output file. If the value is conflicting with the IFS file, an error
 141  will be reported and the program will stop.
 142
 143 .. option:: --bitwidth=[32|64]
 144
 145  This flag is optional and it should only be used when reading an IFS file
 146  which does not define the ``BitWidth``. This flag defines the bit width of the
 147  output file. If the value is conflicting with the input IFS file, an error
 148  will be reported and the program will stop.
 149
 150 .. option:: --target=<target triple>
 151
 152  This flag is optional and should only be used when reading an IFS file
 153  which does not define any target information. This flag defines architecture,
 154  endianness and bit width of the output file using llvm target triple.
 155  This flag cannot be used simultaneously with other target related flags.
 156
 157 .. option:: --hint-ifs-target=<target triple>
 158
 159  This flag is optional and should only be used when reading an ELF shared
 160  object and generating an IFS file. by default, llvm-ifs will use '``Arch``,
 161  ``Endianness`` and ``BitWidth``' fields to reflect the target information from the
 162  input object file. Using this flag will tell llvm-ifs the expected target
 163  triple in the output IFS file. If the value matches the target information
 164  from the object file, this value will be used in the 'Target:' filed in the
 165  generated IFS. If it conflicts with the input object file, an error will be
 166  reported and the program will stop.
 167
 168 .. option:: --hint-ifs-target
 169
 170  This flag is optional and should only be used when outputting an IFS file.
 171  This flag strips the ``Arch`` field from the IFS file so it can be overridden
 172  later.
 173
 174 .. option:: --strip-ifs-endianness
 175
 176  This flag is optional and should only be used when outputting an IFS file.
 177  This flag strips the ``Endianness`` field from the IFS file so it can be
 178  overridden later.
 179
 180 .. option:: --strip-ifs-bitwidth
 181
 182  This flag is optional and should only be used when outputting an IFS file.
 183  This flag strips the ``BitWidth`` field from the IFS file so it can be overridden
 184  later.
 185
 186 .. option:: --strip-ifs-target
 187
 188  This flag is optional and should only be used when outputting an IFS file.
 189  This flag strips the ``Target`` field from the IFS file so it can be overridden
 190  later.
 191
 192 .. option:: --write-if-changed
 193
 194  When this flag is set, llvm-ifs will only write the output file if it does not
 195  already exist or the content will be different from the existing file.
 196
 197 .. option:: --strip-size
 198
 199  When this flag is set, llvm-ifs will remove the size field from the output ifs
 200  file. This is useful for shared objects that only intend to be linked against
 201  position independent code which doesn't need copy relocations, or where the size
 202  of an object is not a useful part of the abi to track.
 203
 204 EXIT STATUS
 205 -----------
 206
 207 If :program:`llvm-ifs` succeeds, it will exit with 0. Otherwise, if an
 208 error occurs, it will exit with a non-zero value.