llvm/docs/FatLTO.rst

   1 ===================
   2 FatLTO
   3 ===================
   4 .. contents::
   5    :local:
   6    :depth: 2
   7
   8 .. toctree::
   9    :maxdepth: 1
  10
  11 Introduction
  12 ============
  13
  14 FatLTO objects are a special type of `fat object file
  15 <https://en.wikipedia.org/wiki/Fat_binary>`_ that contain LTO compatible IR in
  16 addition to generated object code, instead of containing object code for
  17 multiple target architectures. This allows users to defer the choice of whether
  18 to use LTO or not to link-time, and has been a feature available in other
  19 compilers, like `GCC
  20 <https://gcc.gnu.org/onlinedocs/gccint/LTO-Overview.html>`_, for some time.
  21
  22 Under FatLTO the compiler can emit standard object files which contain both the
  23 machine code in the ``.text`` section and LLVM bitcode in the ``.llvm.lto``
  24 section.
  25
  26 Overview
  27 ========
  28
  29 Within LLVM, FatLTO is supported by choosing the ``FatLTODefaultPipeline``.
  30 This pipeline will:
  31
  32 #) Clone the IR module.
  33 #) Run the pre-link (Thin)LTO pipeline using the cloned module.
  34 #) Embed the pre-link bitcode in a special ``.llvm.lto`` section.
  35 #) Optimize the unmodified copy of the module using the normal compilation pipeline.
  36 #) Emit the object file, including the new ``.llvm.lto`` section.
  37
  38 .. NOTE
  39
  40    At the time of writing, we conservatively run independent pipelines to
  41    generate the bitcode section and the object code, which happen to be
  42    identical to those used outside of FatLTO. This results in  compiled
  43    artifacts that are identical to those produced by the default and (Thin)LTO
  44    pipelines. However, this is not a guarantee, and we reserve the right to
  45    change this at any time. Explicitly, users should not rely on the produced
  46    bitcode or object code to mach their non-LTO counterparts precisely. They
  47    will exhibit similar performance characteristics, but may not be bit-for-bit
  48    the same.
  49
  50 Internally, the ``.llvm.lto`` section is created by running the
  51 ``EmbedBitcodePass`` at the start of the ``PerModuleDefaultPipeline``. This
  52 pass is responsible for cloning and optimizing the module with the appropriate
  53 LTO pipeline and emitting the ``.llvm.lto`` section. Afterwards, the
  54 ``PerModuleDefaultPipeline`` runs normally and the compiler can emit the fat
  55 object file.
  56
  57 Limitations
  58 ===========
  59
  60 Linkers
  61 -------
  62
  63 Currently, using LTO with LLVM fat lto objects is supported by LLD and by the
  64 GNU linkers via :doc:`GoldPlugin`. This may change in the future, but
  65 extending support to other linkers isn't planned for now.
  66
  67 .. NOTE
  68    For standard linking the fat object files should be usable by any
  69    linker capable of using ELF objects, since the ``.llvm.lto`` section is
  70    marked ``SHF_EXCLUDE``.
  71
  72 Supported File Formats
  73 ----------------------
  74
  75 The current implementation only supports ELF files. At time of writing, it is
  76 unclear if it will be useful to support other object file formats like ``COFF``
  77 or ``Mach-O``.