1=========================
2GCC plugin infrastructure
3=========================
4
5
6Introduction
7============
8
9GCC plugins are loadable modules that provide extra features to the
10compiler [1]_. They are useful for runtime instrumentation and static analysis.
11We can analyse, change and add further code during compilation via
12callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_.
13
14The GCC plugin infrastructure of the kernel supports building out-of-tree
15modules, cross-compilation and building in a separate directory.
16Plugin source files have to be compilable by a C++ compiler.
17
18Currently the GCC plugin infrastructure supports only some architectures.
19Grep "select HAVE_GCC_PLUGINS" to find out which architectures support
20GCC plugins.
21
22This 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
35Purpose
36=======
37
38GCC plugins are designed to provide a place to experiment with potential
39compiler features that are neither in GCC nor Clang upstream. Once
40their utility is proven, the goal is to upstream the feature into GCC
41(and Clang), and then to finally remove them from the kernel once the
42feature is available in all supported versions of GCC.
43
44Specifically, new plugins should implement only features that have no
45upstream compiler support (in either GCC or Clang).
46
47When a feature exists in Clang but not GCC, effort should be made to
48bring the feature to upstream GCC (rather than just as a kernel-specific
49GCC plugin), so the entire ecosystem can benefit from it.
50
51Similarly, even if a feature provided by a GCC plugin does *not* exist
52in Clang, but the feature is proven to be useful, effort should be spent
53to upstream the feature to GCC (and Clang).
54
55After a feature is available in upstream GCC, the plugin will be made
56unbuildable for the corresponding GCC version (and later). Once all
57kernel-supported versions of GCC provide the feature, the plugin will
58be removed from the kernel.
59
60
61Files
62=====
63
64**$(src)/scripts/gcc-plugins**
65
66	This is the directory of the GCC plugins.
67
68**$(src)/scripts/gcc-plugins/gcc-common.h**
69
70	This is a compatibility header for GCC plugins.
71	It should be always included instead of individual gcc headers.
72
73**$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h,
74$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h,
75$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h,
76$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**
77
78	These headers automatically generate the registration structures for
79	GIMPLE, SIMPLE_IPA, IPA and RTL passes.
80	They should be preferred to creating the structures by hand.
81
82
83Usage
84=====
85
86You must install the gcc plugin headers for your gcc version,
87e.g., on Ubuntu for gcc-10::
88
89	apt-get install gcc-10-plugin-dev
90
91Or on Fedora::
92
93	dnf install gcc-plugin-devel
94
95Enable the GCC plugin infrastructure and some plugin(s) you want to use
96in the kernel config::
97
98	CONFIG_GCC_PLUGINS=y
99	CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y
100	...
101
102To compile the minimum tool set including the plugin(s)::
103
104	make scripts
105
106or just run the kernel make and compile the whole kernel with
107the cyclomatic complexity GCC plugin.
108
109
1104. How to add a new GCC plugin
111==============================
112
113The GCC plugins are in scripts/gcc-plugins/. You need to put plugin source files
114right under scripts/gcc-plugins/. Creating subdirectories is not supported.
115It must be added to scripts/gcc-plugins/Makefile, scripts/Makefile.gcc-plugins
116and a relevant Kconfig file.
117