1 ========================= 1 =========================
2 GCC plugin infrastructure 2 GCC plugin infrastructure
3 ========================= 3 =========================
4 4
5 5
6 Introduction 6 Introduction
7 ============ 7 ============
8 8
9 GCC plugins are loadable modules that provide 9 GCC plugins are loadable modules that provide extra features to the
10 compiler [1]_. They are useful for runtime ins 10 compiler [1]_. They are useful for runtime instrumentation and static analysis.
11 We can analyse, change and add further code du 11 We can analyse, change and add further code during compilation via
12 callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL 12 callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_.
13 13
14 The GCC plugin infrastructure of the kernel su 14 The GCC plugin infrastructure of the kernel supports building out-of-tree
15 modules, cross-compilation and building in a s 15 modules, cross-compilation and building in a separate directory.
16 Plugin source files have to be compilable by a 16 Plugin source files have to be compilable by a C++ compiler.
17 17
18 Currently the GCC plugin infrastructure suppor 18 Currently the GCC plugin infrastructure supports only some architectures.
19 Grep "select HAVE_GCC_PLUGINS" to find out whi 19 Grep "select HAVE_GCC_PLUGINS" to find out which architectures support
20 GCC plugins. 20 GCC plugins.
21 21
22 This infrastructure was ported from grsecurity 22 This infrastructure was ported from grsecurity [6]_ and PaX [7]_.
23 23
24 -- 24 --
25 25
26 .. [1] https://gcc.gnu.org/onlinedocs/gccint/P 26 .. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html
27 .. [2] https://gcc.gnu.org/onlinedocs/gccint/P 27 .. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API
28 .. [3] https://gcc.gnu.org/onlinedocs/gccint/G 28 .. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html
29 .. [4] https://gcc.gnu.org/onlinedocs/gccint/I 29 .. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html
30 .. [5] https://gcc.gnu.org/onlinedocs/gccint/R 30 .. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html
31 .. [6] https://grsecurity.net/ 31 .. [6] https://grsecurity.net/
32 .. [7] https://pax.grsecurity.net/ 32 .. [7] https://pax.grsecurity.net/
33 33
34 34
35 Purpose 35 Purpose
36 ======= 36 =======
37 37
38 GCC plugins are designed to provide a place to 38 GCC plugins are designed to provide a place to experiment with potential
39 compiler features that are neither in GCC nor 39 compiler features that are neither in GCC nor Clang upstream. Once
40 their utility is proven, the goal is to upstre 40 their utility is proven, the goal is to upstream the feature into GCC
41 (and Clang), and then to finally remove them f 41 (and Clang), and then to finally remove them from the kernel once the
42 feature is available in all supported versions 42 feature is available in all supported versions of GCC.
43 43
44 Specifically, new plugins should implement onl 44 Specifically, new plugins should implement only features that have no
45 upstream compiler support (in either GCC or Cl 45 upstream compiler support (in either GCC or Clang).
46 46
47 When a feature exists in Clang but not GCC, ef 47 When a feature exists in Clang but not GCC, effort should be made to
48 bring the feature to upstream GCC (rather than 48 bring the feature to upstream GCC (rather than just as a kernel-specific
49 GCC plugin), so the entire ecosystem can benef 49 GCC plugin), so the entire ecosystem can benefit from it.
50 50
51 Similarly, even if a feature provided by a GCC 51 Similarly, even if a feature provided by a GCC plugin does *not* exist
52 in Clang, but the feature is proven to be usef 52 in Clang, but the feature is proven to be useful, effort should be spent
53 to upstream the feature to GCC (and Clang). 53 to upstream the feature to GCC (and Clang).
54 54
55 After a feature is available in upstream GCC, 55 After a feature is available in upstream GCC, the plugin will be made
56 unbuildable for the corresponding GCC version 56 unbuildable for the corresponding GCC version (and later). Once all
57 kernel-supported versions of GCC provide the f 57 kernel-supported versions of GCC provide the feature, the plugin will
58 be removed from the kernel. 58 be removed from the kernel.
59 59
60 60
61 Files 61 Files
62 ===== 62 =====
63 63
64 **$(src)/scripts/gcc-plugins** 64 **$(src)/scripts/gcc-plugins**
65 65
66 This is the directory of the GCC plugi 66 This is the directory of the GCC plugins.
67 67
68 **$(src)/scripts/gcc-plugins/gcc-common.h** 68 **$(src)/scripts/gcc-plugins/gcc-common.h**
69 69
70 This is a compatibility header for GCC 70 This is a compatibility header for GCC plugins.
71 It should be always included instead o 71 It should be always included instead of individual gcc headers.
72 72
73 **$(src)/scripts/gcc-plugins/gcc-generate-gimp 73 **$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h,
74 $(src)/scripts/gcc-plugins/gcc-generate-ipa-pa 74 $(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h,
75 $(src)/scripts/gcc-plugins/gcc-generate-simple 75 $(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h,
76 $(src)/scripts/gcc-plugins/gcc-generate-rtl-pa 76 $(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**
77 77
78 These headers automatically generate t 78 These headers automatically generate the registration structures for
79 GIMPLE, SIMPLE_IPA, IPA and RTL passes 79 GIMPLE, SIMPLE_IPA, IPA and RTL passes.
80 They should be preferred to creating t 80 They should be preferred to creating the structures by hand.
81 81
82 82
83 Usage 83 Usage
84 ===== 84 =====
85 85
86 You must install the gcc plugin headers for yo 86 You must install the gcc plugin headers for your gcc version,
87 e.g., on Ubuntu for gcc-10:: 87 e.g., on Ubuntu for gcc-10::
88 88
89 apt-get install gcc-10-plugin-dev 89 apt-get install gcc-10-plugin-dev
90 90
91 Or on Fedora:: 91 Or on Fedora::
92 92
93 dnf install gcc-plugin-devel libmpc-de !! 93 dnf install gcc-plugin-devel
94 <<
95 Or on Fedora when using cross-compilers that i <<
96 <<
97 dnf install libmpc-devel <<
98 94
99 Enable the GCC plugin infrastructure and some 95 Enable the GCC plugin infrastructure and some plugin(s) you want to use
100 in the kernel config:: 96 in the kernel config::
101 97
102 CONFIG_GCC_PLUGINS=y 98 CONFIG_GCC_PLUGINS=y
103 CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y 99 CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y
104 ... 100 ...
105 <<
106 Run gcc (native or cross-compiler) to ensure p <<
107 <<
108 gcc -print-file-name=plugin <<
109 CROSS_COMPILE=arm-linux-gnu- ${CROSS_C <<
110 <<
111 The word "plugin" means they are not detected: <<
112 <<
113 plugin <<
114 <<
115 A full path means they are detected:: <<
116 <<
117 /usr/lib/gcc/x86_64-redhat-linux/12/plu <<
118 101
119 To compile the minimum tool set including the 102 To compile the minimum tool set including the plugin(s)::
120 103
121 make scripts 104 make scripts
122 105
123 or just run the kernel make and compile the wh 106 or just run the kernel make and compile the whole kernel with
124 the cyclomatic complexity GCC plugin. 107 the cyclomatic complexity GCC plugin.
125 108
126 109
127 4. How to add a new GCC plugin 110 4. How to add a new GCC plugin
128 ============================== 111 ==============================
129 112
130 The GCC plugins are in scripts/gcc-plugins/. Y 113 The GCC plugins are in scripts/gcc-plugins/. You need to put plugin source files
131 right under scripts/gcc-plugins/. Creating sub 114 right under scripts/gcc-plugins/. Creating subdirectories is not supported.
132 It must be added to scripts/gcc-plugins/Makefi 115 It must be added to scripts/gcc-plugins/Makefile, scripts/Makefile.gcc-plugins
133 and a relevant Kconfig file. 116 and a relevant Kconfig file.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.