Documentation/core-api/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 all gcc versions from
  15 4.5 to 6.0, building out-of-tree modules, cross-compilation and building in a
  16 separate directory.
  17 Plugin source files have to be compilable by both a C and a C++ compiler as well
  18 because gcc versions 4.5 and 4.6 are compiled by a C compiler,
  19 gcc-4.7 can be compiled by a C or a C++ compiler,
  20 and versions 4.8+ can only be compiled by a C++ compiler.
  21
  22 Currently the GCC plugin infrastructure supports only the x86, arm, arm64 and
  23 powerpc architectures.
  24
  25 This infrastructure was ported from grsecurity [6]_ and PaX [7]_.
  26
  27 --
  28
  29 .. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html
  30 .. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API
  31 .. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html
  32 .. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html
  33 .. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html
  34 .. [6] https://grsecurity.net/
  35 .. [7] https://pax.grsecurity.net/
  36
  37
  38 Files
  39 =====
  40
  41 **$(src)/scripts/gcc-plugins**
  42
  43         This is the directory of the GCC plugins.
  44
  45 **$(src)/scripts/gcc-plugins/gcc-common.h**
  46
  47         This is a compatibility header for GCC plugins.
  48         It should be always included instead of individual gcc headers.
  49
  50 **$(src)/scripts/gcc-plugin.sh**
  51
  52         This script checks the availability of the included headers in
  53         gcc-common.h and chooses the proper host compiler to build the plugins
  54         (gcc-4.7 can be built by either gcc or g++).
  55
  56 **$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h,
  57 $(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h,
  58 $(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h,
  59 $(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**
  60
  61         These headers automatically generate the registration structures for
  62         GIMPLE, SIMPLE_IPA, IPA and RTL passes. They support all gcc versions
  63         from 4.5 to 6.0.
  64         They should be preferred to creating the structures by hand.
  65
  66
  67 Usage
  68 =====
  69
  70 You must install the gcc plugin headers for your gcc version,
  71 e.g., on Ubuntu for gcc-4.9::
  72
  73         apt-get install gcc-4.9-plugin-dev
  74
  75 Enable a GCC plugin based feature in the kernel config::
  76
  77         CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y
  78
  79 To compile only the plugin(s)::
  80
  81         make gcc-plugins
  82
  83 or just run the kernel make and compile the whole kernel with
  84 the cyclomatic complexity GCC plugin.
  85
  86
  87 4. How to add a new GCC plugin
  88 ==============================
  89
  90 The GCC plugins are in $(src)/scripts/gcc-plugins/. You can use a file or a directory
  91 here. It must be added to $(src)/scripts/gcc-plugins/Makefile,
  92 $(src)/scripts/Makefile.gcc-plugins and $(src)/arch/Kconfig.
  93 See the cyc_complexity_plugin.c (CONFIG_GCC_PLUGIN_CYC_COMPLEXITY) GCC plugin.