gcc/doc/gccint/link-time-optimization/lto-file-sections.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _lto-object-file-layout:
   7
   8 LTO file sections
   9 *****************
  10
  11 LTO information is stored in several ELF sections inside object files.
  12 Data structures and enum codes for sections are defined in
  13 :samp:`lto-streamer.h`.
  14
  15 These sections are emitted from :samp:`lto-streamer-out.cc` and mapped
  16 in all at once from :samp:`lto/lto.cc`: ``lto_file_read``.  The
  17 individual functions dealing with the reading/writing of each section
  18 are described below.
  19
  20 * Command line options (``.gnu.lto_.opts``)
  21
  22   This section contains the command line options used to generate the
  23   object files.  This is used at link time to determine the optimization
  24   level and other settings when they are not explicitly specified at the
  25   linker command line.
  26
  27   Currently, GCC does not support combining LTO object files compiled
  28   with different set of the command line options into a single binary.
  29   At link time, the options given on the command line and the options
  30   saved on all the files in a link-time set are applied globally.  No
  31   attempt is made at validating the combination of flags (other than the
  32   usual validation done by option processing).  This is implemented in
  33   :samp:`lto/lto.cc`: ``lto_read_all_file_options``.
  34
  35 * Symbol table (``.gnu.lto_.symtab``)
  36
  37   This table replaces the ELF symbol table for functions and variables
  38   represented in the LTO IL.  Symbols used and exported by the optimized
  39   assembly code of 'fat' objects might not match the ones used and
  40   exported by the intermediate code.  This table is necessary because
  41   the intermediate code is less optimized and thus requires a separate
  42   symbol table.
  43
  44   Additionally, the binary code in the 'fat' object will lack a call
  45   to a function, since the call was optimized out at compilation time
  46   after the intermediate language was streamed out.  In some special
  47   cases, the same optimization may not happen during link-time
  48   optimization.  This would lead to an undefined symbol if only one
  49   symbol table was used.
  50
  51   The symbol table is emitted in
  52   :samp:`lto-streamer-out.cc`: ``produce_symtab``.
  53
  54 * Global declarations and types (``.gnu.lto_.decls``)
  55
  56   This section contains an intermediate language dump of all
  57   declarations and types required to represent the callgraph, static
  58   variables and top-level debug info.
  59
  60   The contents of this section are emitted in
  61   :samp:`lto-streamer-out.cc`: ``produce_asm_for_decls``.  Types and
  62   symbols are emitted in a topological order that preserves the sharing
  63   of pointers when the file is read back in
  64   (:samp:`lto.cc`: ``read_cgraph_and_symbols``).
  65
  66 * The callgraph (``.gnu.lto_.cgraph``)
  67
  68   This section contains the basic data structure used by the GCC
  69   inter-procedural optimization infrastructure.  This section stores an
  70   annotated multi-graph which represents the functions and call sites as
  71   well as the variables, aliases and top-level ``asm`` statements.
  72
  73   This section is emitted in
  74   :samp:`lto-streamer-out.cc`: ``output_cgraph`` and read in
  75   :samp:`lto-cgraph.cc`: ``input_cgraph``.
  76
  77 * IPA references (``.gnu.lto_.refs``)
  78
  79   This section contains references between function and static
  80   variables.  It is emitted by :samp:`lto-cgraph.cc`: ``output_refs``
  81   and read by :samp:`lto-cgraph.cc`: ``input_refs``.
  82
  83 * Function bodies (``.gnu.lto_.function_body.<name>``)
  84
  85   This section contains function bodies in the intermediate language
  86   representation.  Every function body is in a separate section to allow
  87   copying of the section independently to different object files or
  88   reading the function on demand.
  89
  90   Functions are emitted in
  91   :samp:`lto-streamer-out.cc`: ``output_function`` and read in
  92   :samp:`lto-streamer-in.cc`: ``input_function``.
  93
  94 * Static variable initializers (``.gnu.lto_.vars``)
  95
  96   This section contains all the symbols in the global variable pool.  It
  97   is emitted by :samp:`lto-cgraph.cc`: ``output_varpool`` and read in
  98   :samp:`lto-cgraph.cc`: ``input_cgraph``.
  99
 100 * Summaries and optimization summaries used by IPA passes
 101   (``.gnu.lto_.<xxx>``, where ``<xxx>`` is one of ``jmpfuncs``,
 102   ``pureconst`` or ``reference``)
 103
 104   These sections are used by IPA passes that need to emit summary
 105   information during LTO generation to be read and aggregated at
 106   link time.  Each pass is responsible for implementing two pass manager
 107   hooks: one for writing the summary and another for reading it in.  The
 108   format of these sections is entirely up to each individual pass.  The
 109   only requirement is that the writer and reader hooks agree on the
 110   format.