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 Files
  36 =====
  37
  38 **$(src)/scripts/gcc-plugins**
  39
  40         This is the directory of the GCC plugins.
  41
  42 **$(src)/scripts/gcc-plugins/gcc-common.h**
  43
  44         This is a compatibility header for GCC plugins.
  45         It should be always included instead of individual gcc headers.
  46
  47 **$(src)/scripts/gcc-plugin.sh**
  48
  49         This script checks the availability of the included headers in
  50         gcc-common.h and chooses the proper host compiler to build the plugins
  51         (gcc-4.7 can be built by either gcc or g++).
  52
  53 **$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h,
  54 $(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h,
  55 $(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h,
  56 $(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**
  57
  58         These headers automatically generate the registration structures for
  59         GIMPLE, SIMPLE_IPA, IPA and RTL passes.
  60         They should be preferred to creating the structures by hand.
  61
  62
  63 Usage
  64 =====
  65
  66 You must install the gcc plugin headers for your gcc version,
  67 e.g., on Ubuntu for gcc-10::
  68
  69         apt-get install gcc-10-plugin-dev
  70
  71 Or on Fedora::
  72
  73         dnf install gcc-plugin-devel
  74
  75 Enable the GCC plugin infrastructure and some plugin(s) you want to use
  76 in the kernel config::
  77
  78         CONFIG_GCC_PLUGINS=y
  79         CONFIG_GCC_PLUGIN_CYC_COMPLEXITY=y
  80         CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y
  81         ...
  82
  83 To compile the minimum tool set including the plugin(s)::
  84
  85         make scripts
  86
  87 or just run the kernel make and compile the whole kernel with
  88 the cyclomatic complexity GCC plugin.
  89
  90
  91 4. How to add a new GCC plugin
  92 ==============================
  93
  94 The GCC plugins are in scripts/gcc-plugins/. You need to put plugin source files
  95 right under scripts/gcc-plugins/. Creating subdirectories is not supported.
  96 It must be added to scripts/gcc-plugins/Makefile, scripts/Makefile.gcc-plugins
  97 and a relevant Kconfig file.
  98 See the cyc_complexity_plugin.c (CONFIG_GCC_PLUGIN_CYC_COMPLEXITY) GCC plugin.