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
35Files
36=====
37
38**$(src)/scripts/gcc-plugins**
39
40	This is the directory of the GCC plugins.
41
42**$(src)/scripts/gcc-plugins/gcc-common.h**
43
44	This is a compatibility header for GCC plugins.
45	It should be always included instead of individual gcc headers.
46
47**$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h,
48$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h,
49$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h,
50$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**
51
52	These headers automatically generate the registration structures for
53	GIMPLE, SIMPLE_IPA, IPA and RTL passes.
54	They should be preferred to creating the structures by hand.
55
56
57Usage
58=====
59
60You must install the gcc plugin headers for your gcc version,
61e.g., on Ubuntu for gcc-10::
62
63	apt-get install gcc-10-plugin-dev
64
65Or on Fedora::
66
67	dnf install gcc-plugin-devel
68
69Enable the GCC plugin infrastructure and some plugin(s) you want to use
70in the kernel config::
71
72	CONFIG_GCC_PLUGINS=y
73	CONFIG_GCC_PLUGIN_CYC_COMPLEXITY=y
74	CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y
75	...
76
77To compile the minimum tool set including the plugin(s)::
78
79	make scripts
80
81or just run the kernel make and compile the whole kernel with
82the cyclomatic complexity GCC plugin.
83
84
854. How to add a new GCC plugin
86==============================
87
88The GCC plugins are in scripts/gcc-plugins/. You need to put plugin source files
89right under scripts/gcc-plugins/. Creating subdirectories is not supported.
90It must be added to scripts/gcc-plugins/Makefile, scripts/Makefile.gcc-plugins
91and a relevant Kconfig file.
92See the cyc_complexity_plugin.c (CONFIG_GCC_PLUGIN_CYC_COMPLEXITY) GCC plugin.
93