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-plugins/gcc-generate-gimple-pass.h,
  48 $(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h,
  49 $(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h,
  50 $(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**
  51
  52         These headers automatically generate the registration structures for
  53         GIMPLE, SIMPLE_IPA, IPA and RTL passes.
  54         They should be preferred to creating the structures by hand.
  55
  56
  57 Usage
  58 =====
  59
  60 You must install the gcc plugin headers for your gcc version,
  61 e.g., on Ubuntu for gcc-10::
  62
  63         apt-get install gcc-10-plugin-dev
  64
  65 Or on Fedora::
  66
  67         dnf install gcc-plugin-devel
  68
  69 Enable the GCC plugin infrastructure and some plugin(s) you want to use
  70 in the kernel config::
  71
  72         CONFIG_GCC_PLUGINS=y
  73         CONFIG_GCC_PLUGIN_CYC_COMPLEXITY=y
  74         CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y
  75         ...
  76
  77 To compile the minimum tool set including the plugin(s)::
  78
  79         make scripts
  80
  81 or just run the kernel make and compile the whole kernel with
  82 the cyclomatic complexity GCC plugin.
  83
  84
  85 4. How to add a new GCC plugin
  86 ==============================
  87
  88 The GCC plugins are in scripts/gcc-plugins/. You need to put plugin source files
  89 right under scripts/gcc-plugins/. Creating subdirectories is not supported.
  90 It must be added to scripts/gcc-plugins/Makefile, scripts/Makefile.gcc-plugins
  91 and a relevant Kconfig file.
  92 See the cyc_complexity_plugin.c (CONFIG_GCC_PLUGIN_CYC_COMPLEXITY) GCC plugin.