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