Documentation/kbuild/gcc-plugins.rst

   1 =========================
   2 GCC plugin infrastructure
   3 =========================
   4
   5
   6 Introduction
   7 ============
   8
   9 GCC plugins are loadable modules that provide extra features to the
  10 compiler [1]_. They are useful for runtime instrumentation and static analysis.
  11 We can analyse, change and add further code during compilation via
  12 callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_.
  13
  14 The GCC plugin infrastructure of the kernel supports building out-of-tree
  15 modules, cross-compilation and building in a separate directory.
  16 Plugin source files have to be compilable by a C++ compiler.
  17
  18 Currently the GCC plugin infrastructure supports only some architectures.
  19 Grep "select HAVE_GCC_PLUGINS" to find out which architectures support
  20 GCC plugins.
  21
  22 This infrastructure was ported from grsecurity [6]_ and PaX [7]_.
  23
  24 --
  25
  26 .. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html
  27 .. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API
  28 .. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html
  29 .. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html
  30 .. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html
  31 .. [6] https://grsecurity.net/
  32 .. [7] https://pax.grsecurity.net/
  33
  34
  35 Purpose
  36 =======
  37
  38 GCC plugins are designed to provide a place to experiment with potential
  39 compiler features that are neither in GCC nor Clang upstream. Once
  40 their utility is proven, the goal is to upstream the feature into GCC
  41 (and Clang), and then to finally remove them from the kernel once the
  42 feature is available in all supported versions of GCC.
  43
  44 Specifically, new plugins should implement only features that have no
  45 upstream compiler support (in either GCC or Clang).
  46
  47 When a feature exists in Clang but not GCC, effort should be made to
  48 bring the feature to upstream GCC (rather than just as a kernel-specific
  49 GCC plugin), so the entire ecosystem can benefit from it.
  50
  51 Similarly, even if a feature provided by a GCC plugin does *not* exist
  52 in Clang, but the feature is proven to be useful, effort should be spent
  53 to upstream the feature to GCC (and Clang).
  54
  55 After a feature is available in upstream GCC, the plugin will be made
  56 unbuildable for the corresponding GCC version (and later). Once all
  57 kernel-supported versions of GCC provide the feature, the plugin will
  58 be removed from the kernel.
  59
  60
  61 Files
  62 =====
  63
  64 **$(src)/scripts/gcc-plugins**
  65
  66         This is the directory of the GCC plugins.
  67
  68 **$(src)/scripts/gcc-plugins/gcc-common.h**
  69
  70         This is a compatibility header for GCC plugins.
  71         It should be always included instead of individual gcc headers.
  72
  73 **$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h,
  74 $(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h,
  75 $(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h,
  76 $(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**
  77
  78         These headers automatically generate the registration structures for
  79         GIMPLE, SIMPLE_IPA, IPA and RTL passes.
  80         They should be preferred to creating the structures by hand.
  81
  82
  83 Usage
  84 =====
  85
  86 You must install the gcc plugin headers for your gcc version,
  87 e.g., on Ubuntu for gcc-10::
  88
  89         apt-get install gcc-10-plugin-dev
  90
  91 Or on Fedora::
  92
  93         dnf install gcc-plugin-devel libmpc-devel
  94
  95 Or on Fedora when using cross-compilers that include plugins::
  96
  97         dnf install libmpc-devel
  98
  99 Enable the GCC plugin infrastructure and some plugin(s) you want to use
 100 in the kernel config::
 101
 102         CONFIG_GCC_PLUGINS=y
 103         CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y
 104         ...
 105
 106 Run gcc (native or cross-compiler) to ensure plugin headers are detected::
 107
 108         gcc -print-file-name=plugin
 109         CROSS_COMPILE=arm-linux-gnu- ${CROSS_COMPILE}gcc -print-file-name=plugin
 110
 111 The word "plugin" means they are not detected::
 112
 113         plugin
 114
 115 A full path means they are detected::
 116
 117        /usr/lib/gcc/x86_64-redhat-linux/12/plugin
 118
 119 To compile the minimum tool set including the plugin(s)::
 120
 121         make scripts
 122
 123 or just run the kernel make and compile the whole kernel with
 124 the cyclomatic complexity GCC plugin.
 125
 126
 127 4. How to add a new GCC plugin
 128 ==============================
 129
 130 The GCC plugins are in scripts/gcc-plugins/. You need to put plugin source files
 131 right under scripts/gcc-plugins/. Creating subdirectories is not supported.
 132 It must be added to scripts/gcc-plugins/Makefile, scripts/Makefile.gcc-plugins
 133 and a relevant Kconfig file.