Back to home page

LXR

 
 

    


0001 GCC plugin infrastructure
0002 =========================
0003 
0004 
0005 1. Introduction
0006 ===============
0007 
0008 GCC plugins are loadable modules that provide extra features to the
0009 compiler [1]. They are useful for runtime instrumentation and static analysis.
0010 We can analyse, change and add further code during compilation via
0011 callbacks [2], GIMPLE [3], IPA [4] and RTL passes [5].
0012 
0013 The GCC plugin infrastructure of the kernel supports all gcc versions from
0014 4.5 to 6.0, building out-of-tree modules, cross-compilation and building in a
0015 separate directory.
0016 Plugin source files have to be compilable by both a C and a C++ compiler as well
0017 because gcc versions 4.5 and 4.6 are compiled by a C compiler,
0018 gcc-4.7 can be compiled by a C or a C++ compiler,
0019 and versions 4.8+ can only be compiled by a C++ compiler.
0020 
0021 Currently the GCC plugin infrastructure supports only the x86, arm and arm64
0022 architectures.
0023 
0024 This infrastructure was ported from grsecurity [6] and PaX [7].
0025 
0026 --
0027 [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html
0028 [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API
0029 [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html
0030 [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html
0031 [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html
0032 [6] https://grsecurity.net/
0033 [7] https://pax.grsecurity.net/
0034 
0035 
0036 2. Files
0037 ========
0038 
0039 $(src)/scripts/gcc-plugins
0040         This is the directory of the GCC plugins.
0041 
0042 $(src)/scripts/gcc-plugins/gcc-common.h
0043         This is a compatibility header for GCC plugins.
0044         It should be always included instead of individual gcc headers.
0045 
0046 $(src)/scripts/gcc-plugin.sh
0047         This script checks the availability of the included headers in
0048         gcc-common.h and chooses the proper host compiler to build the plugins
0049         (gcc-4.7 can be built by either gcc or g++).
0050 
0051 $(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h
0052 $(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h
0053 $(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h
0054 $(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h
0055         These headers automatically generate the registration structures for
0056         GIMPLE, SIMPLE_IPA, IPA and RTL passes. They support all gcc versions
0057         from 4.5 to 6.0.
0058         They should be preferred to creating the structures by hand.
0059 
0060 
0061 3. Usage
0062 ========
0063 
0064 You must install the gcc plugin headers for your gcc version,
0065 e.g., on Ubuntu for gcc-4.9:
0066 
0067         apt-get install gcc-4.9-plugin-dev
0068 
0069 Enable a GCC plugin based feature in the kernel config:
0070 
0071         CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y
0072 
0073 To compile only the plugin(s):
0074 
0075         make gcc-plugins
0076 
0077 or just run the kernel make and compile the whole kernel with
0078 the cyclomatic complexity GCC plugin.
0079 
0080 
0081 4. How to add a new GCC plugin
0082 ==============================
0083 
0084 The GCC plugins are in $(src)/scripts/gcc-plugins/. You can use a file or a directory
0085 here. It must be added to $(src)/scripts/gcc-plugins/Makefile,
0086 $(src)/scripts/Makefile.gcc-plugins and $(src)/arch/Kconfig.
0087 See the cyc_complexity_plugin.c (CONFIG_GCC_PLUGIN_CYC_COMPLEXITY) GCC plugin.