0001 =========================
0002 GCC plugin infrastructure
0003 =========================
0004
0005
0006 Introduction
0007 ============
0008
0009 GCC plugins are loadable modules that provide extra features to the
0010 compiler [1]_. They are useful for runtime instrumentation and static analysis.
0011 We can analyse, change and add further code during compilation via
0012 callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_.
0013
0014 The GCC plugin infrastructure of the kernel supports building out-of-tree
0015 modules, cross-compilation and building in a separate directory.
0016 Plugin source files have to be compilable by a C++ compiler.
0017
0018 Currently the GCC plugin infrastructure supports only some architectures.
0019 Grep "select HAVE_GCC_PLUGINS" to find out which architectures support
0020 GCC plugins.
0021
0022 This infrastructure was ported from grsecurity [6]_ and PaX [7]_.
0023
0024 --
0025
0026 .. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html
0027 .. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API
0028 .. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html
0029 .. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html
0030 .. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html
0031 .. [6] https://grsecurity.net/
0032 .. [7] https://pax.grsecurity.net/
0033
0034
0035 Purpose
0036 =======
0037
0038 GCC plugins are designed to provide a place to experiment with potential
0039 compiler features that are neither in GCC nor Clang upstream. Once
0040 their utility is proven, the goal is to upstream the feature into GCC
0041 (and Clang), and then to finally remove them from the kernel once the
0042 feature is available in all supported versions of GCC.
0043
0044 Specifically, new plugins should implement only features that have no
0045 upstream compiler support (in either GCC or Clang).
0046
0047 When a feature exists in Clang but not GCC, effort should be made to
0048 bring the feature to upstream GCC (rather than just as a kernel-specific
0049 GCC plugin), so the entire ecosystem can benefit from it.
0050
0051 Similarly, even if a feature provided by a GCC plugin does *not* exist
0052 in Clang, but the feature is proven to be useful, effort should be spent
0053 to upstream the feature to GCC (and Clang).
0054
0055 After a feature is available in upstream GCC, the plugin will be made
0056 unbuildable for the corresponding GCC version (and later). Once all
0057 kernel-supported versions of GCC provide the feature, the plugin will
0058 be removed from the kernel.
0059
0060
0061 Files
0062 =====
0063
0064 **$(src)/scripts/gcc-plugins**
0065
0066 This is the directory of the GCC plugins.
0067
0068 **$(src)/scripts/gcc-plugins/gcc-common.h**
0069
0070 This is a compatibility header for GCC plugins.
0071 It should be always included instead of individual gcc headers.
0072
0073 **$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h,
0074 $(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h,
0075 $(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h,
0076 $(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**
0077
0078 These headers automatically generate the registration structures for
0079 GIMPLE, SIMPLE_IPA, IPA and RTL passes.
0080 They should be preferred to creating the structures by hand.
0081
0082
0083 Usage
0084 =====
0085
0086 You must install the gcc plugin headers for your gcc version,
0087 e.g., on Ubuntu for gcc-10::
0088
0089 apt-get install gcc-10-plugin-dev
0090
0091 Or on Fedora::
0092
0093 dnf install gcc-plugin-devel
0094
0095 Enable the GCC plugin infrastructure and some plugin(s) you want to use
0096 in the kernel config::
0097
0098 CONFIG_GCC_PLUGINS=y
0099 CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y
0100 ...
0101
0102 To compile the minimum tool set including the plugin(s)::
0103
0104 make scripts
0105
0106 or just run the kernel make and compile the whole kernel with
0107 the cyclomatic complexity GCC plugin.
0108
0109
0110 4. How to add a new GCC plugin
0111 ==============================
0112
0113 The GCC plugins are in scripts/gcc-plugins/. You need to put plugin source files
0114 right under scripts/gcc-plugins/. Creating subdirectories is not supported.
0115 It must be added to scripts/gcc-plugins/Makefile, scripts/Makefile.gcc-plugins
0116 and a relevant Kconfig file.
