Documentation/lto-build

   1 Link time optimization (LTO) for the Linux kernel
   2
   3 This is an experimental feature.
   4
   5 Link Time Optimization allows the compiler to optimize the complete program
   6 instead of just each file.  LTO requires at least gcc 4.8 (but
   7 works more efficiently with 4.9+) LTO requires Linux binutils (the normal FSF
   8 releases used in many distributions do not work at the moment)
   9
  10 The compiler can inline functions between files and do various other global
  11 optimizations, like specializing functions for common parameters,
  12 determing when global variables are clobbered, making functions pure/const,
  13 propagating constants globally, removing unneeded data and others.
  14
  15 It will also drop unused functions which can make the kernel
  16 image smaller in some circumstances, in particular for small kernel
  17 configurations.
  18
  19 For small monolithic kernels it can throw away unused code very effectively
  20 (especially when modules are disabled) and usually shrinks
  21 the code size.
  22
  23 Build time and memory consumption at build time will increase, depending
  24 on the size of the largest binary. Modular kernels are less affected.
  25 With LTO incremental builds are less incremental, as always the whole
  26 binary needs to be re-optimized (but not re-parsed)
  27
  28 Oops can be somewhat more difficult to read, due to the more aggressive
  29 inlining.
  30
  31 Normal "reasonable" builds work with less than 4GB of RAM, but very large
  32 configurations like allyesconfig may need more memory. The actual
  33 memory needed depends on the available memory (gcc sizes its garbage
  34 collector pools based on that or on the ulimit -m limits) and
  35 the compiler version.
  36
  37 gcc 4.9+ has much better build performance and less memory consumption
  38
  39 - A few kernel features are currently incompatible with LTO, in particular
  40 function tracing, because they require special compiler flags for
  41 specific files, which is not supported in LTO right now.
  42 - Jobserver control for -j does not work correctly for the final
  43 LTO phase due to some problems with the kernel's pipe code.
  44 The makefiles hard codes -j<number of online cpus> for the final
  45 LTO phase to work around for this
  46
  47 Configuration:
  48 - Enable CONFIG_LTO_MENU and then disable CONFIG_LTO_DISABLE.
  49 This is mainly to not have allyesconfig default to LTO.
  50 - FUNCTION_TRACER, STACK_TRACER, FUNCTION_GRAPH_TRACER, KALLSYMS_ALL, GCOV
  51 have to disabled because they are currently incompatible with LTO.
  52 - MODVERSIONS have to be disabled (may work with 4.9+)
  53
  54 Requirements:
  55 - Enough memory: 4GB for a standard build, more for allyesconfig
  56 The peak memory usage happens single threaded (when lto-wpa merges types),
  57 so dialing back -j options will not help much.
  58
  59 A 32bit compiler is unlikely to work due to the memory requirements.
  60 You can however build a kernel targeted at 32bit on a 64bit host.
  61
  62 Example build procedure:
  63
  64 Simplified procedure for distributions that have gcc 4.8, but not
  65 the Linux binutils (for example openSUSE 13.1 or FC20):
  66
  67 The LTO builds requires gcc-nm/gcc-ar. Some distributions ship
  68 those in separate packages, which may need to be explicitely installed.
  69
  70 - Get the latest Linux binutils from
  71 http://www.kernel.org/pub/linux/devel/binutils/
  72 and unpack it.
  73
  74 We install it in a separate directory to not overwrite the system binutils.
  75
  76 # replace VERSION with respective version numbers
  77
  78 cd binutils*
  79 # don't forget the --enable-plugins!
  80 ./configure --prefix=/opt/binutils-VERSION --enable-plugins
  81 make -j $(getconf _NPROCESSORS_ONLN) && sudo make install
  82
  83 Fix up the kernel configuration to allow LTO:
  84
  85 <start with a suitable kernel configuration>
  86 ./source/scripts/config --disable function_tracer \
  87                         --disable function_graph_tracer \
  88                         --disable stack_tracer --enable lto_menu \
  89                         --disable lto_disable \
  90                         --disable gcov \
  91                         --disable kallsyms_all \
  92                         --disable modversions
  93 make oldconfig
  94
  95 Then you can build with
  96
  97 # The COMPILER_PATH is needed to let gcc use the new binutils
  98 # as the LTO plugin linker
  99 # if you installed gcc in a separate directory like below also
 100 # add it to the PATH line below before the regular $PATH
 101 # The COMPILER_PATH setting is only needed if the gcc was not built
 102 # with --with-plugin-ld pointing to the Linux binutils ld
 103 # The AR/NM setting works around a Makefile bug
 104 COMPILER_PATH=/opt/binutils-VERSION/bin PATH=$COMPILER_PATH:$PATH \
 105 make -j$(getconf _NPROCESSORS_ONLN) AR=gcc-ar NM=gcc-nm
 106
 107 If you don't have gcc 4.8+ as system compiler you would also need
 108 to install that compiler. In this case I recommend getting
 109 a gcc 4.9+ snapshot from http://gcc.gnu.org (or release when available),
 110 as it builds much faster for LTO than 4.8.
 111
 112 Here's an example build procedure:
 113
 114 Assuming gcc is unpacked in gcc-VERSION
 115
 116 cd gcc-VERSION
 117 ./contrib/download_preqrequisites
 118 cd ..
 119
 120 mkdir obj-gcc
 121 # please don't skip this cd. the build will not work correctly in the
 122 # source dir, you have to use the separate object dir
 123 cd obj-gcc
 124 ../gcc-VERSION/configure --prefix=/opt/gcc-VERSION --enable-lto \
 125 --with-plugin-ld=/opt/binutils-VERSION/bin/ld
 126 --disable-nls --enable-languages=c,c++ \
 127 --disable-libstdcxx-pch
 128 make -j$(getconf _NPROCESSORS_ONLN)
 129 sudo make install-no-fixedincludes
 130
 131 FAQs:
 132
 133 Q: I get a section type attribute conflict
 134 A: Usually because of someone doing
 135 const __initdata (should be const __initconst) or const __read_mostly
 136 (should be just const). Check both symbols reported by gcc.
 137
 138 Q: I see lots of undefined symbols for memcmp etc.
 139 A: Usually because NM=gcc-nm AR=gcc-ar are missing.
 140 The Makefile tries to set those automatically, but it doesn't always
 141 work. Better to set it manually on the make command line.
 142
 143 Q: It's quite slow / uses too much memory.
 144 A: Consider a gcc 4.9 snapshot/release (not released yet)
 145 The main problem in 4.8 is the type merging in the single threaded WPA pass,
 146 which has been improved considerably in 4.9 by running it distributed.
 147
 148 Q: It's still slow
 149 A: It'll always be somewhat slower than non LTO sorry.
 150
 151 Q: What's up with .XXXXX numeric post fixes
 152 A: This is due LTO turning (near) all symbols to static
 153 Use gcc 4.9, it avoids them in most cases. They are also filtered out
 154 in kallsyms.
 155
 156 References:
 157
 158 Presentation on Kernel LTO
 159 (note, performance numbers/details outdated.  In particular gcc 4.9 fixed
 160 most of the build time problems):
 161 http://halobates.de/kernel-lto.pdf
 162
 163 Generic gcc LTO:
 164 http://www.ucw.cz/~hubicka/slides/labs2013.pdf
 165 http://www.hipeac.net/system/files/barcelona.pdf
 166
 167 Somewhat outdated too:
 168 http://gcc.gnu.org/projects/lto/lto.pdf
 169 http://gcc.gnu.org/projects/lto/whopr.pdf
 170
 171 Happy Link-Time-Optimizing!
 172
 173 Andi Kleen