1llvm-ifs - shared object stubbing tool 2====================================== 3 4.. program:: llvm-ifs 5 6SYNOPSIS 7-------- 8 9:program:`llvm-ifs` [*options*] *inputs* 10 11DESCRIPTION 12----------- 13 14:program:`llvm-ifs` is a tool that jointly produces human readable text-based 15stubs (.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 17stubs is useful for monitoring ABI changes of the shared object. The linkable 18shared object stubs can be used to avoid unnecessary relinks when the ABI of 19shared libraries does not change. 20 21 22IFS FORMATS 23----------- 24 25Here is an example of the text representation (IFS) of a shared object produced 26by 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 70This YAML based text format contains everything that is needed to generate a 71linkable ELF shared object as well as an Apple TAPI format file. The ordering 72of symbols is sorted, so these files can be easily compared using diff tools. 73If the content of the file changes, it indicates a potentially ABI breaking 74change. 75 76 77ELF STUB FORMAT 78--------------- 79 80A 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 104This ELF file may have compatibility issues with ELF analysis tools that rely on the program headers. 105Linkers like LLD work fine with such a minimum ELF file without errors. 106 107OPTIONS 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 204EXIT STATUS 205----------- 206 207If :program:`llvm-ifs` succeeds, it will exit with 0. Otherwise, if an 208error occurs, it will exit with a non-zero value. 209