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 all gcc versions from
15 modules, cross-compilation and building in a s !! 15 4.5 to 6.0, building out-of-tree modules, cross-compilation and building in a
16 Plugin source files have to be compilable by a !! 16 separate directory.
17 !! 17 Plugin source files have to be compilable by both a C and a C++ compiler as well
18 Currently the GCC plugin infrastructure suppor !! 18 because gcc versions 4.5 and 4.6 are compiled by a C compiler,
19 Grep "select HAVE_GCC_PLUGINS" to find out whi !! 19 gcc-4.7 can be compiled by a C or a C++ compiler,
20 GCC plugins. !! 20 and versions 4.8+ can only be compiled by a C++ compiler.
>> 21
>> 22 Currently the GCC plugin infrastructure supports only the x86, arm, arm64 and
>> 23 powerpc architectures.
21 24
22 This infrastructure was ported from grsecurity 25 This infrastructure was ported from grsecurity [6]_ and PaX [7]_.
23 26
24 -- 27 --
25 28
26 .. [1] https://gcc.gnu.org/onlinedocs/gccint/P 29 .. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html
27 .. [2] https://gcc.gnu.org/onlinedocs/gccint/P 30 .. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API
28 .. [3] https://gcc.gnu.org/onlinedocs/gccint/G 31 .. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html
29 .. [4] https://gcc.gnu.org/onlinedocs/gccint/I 32 .. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html
30 .. [5] https://gcc.gnu.org/onlinedocs/gccint/R 33 .. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html
31 .. [6] https://grsecurity.net/ 34 .. [6] https://grsecurity.net/
32 .. [7] https://pax.grsecurity.net/ 35 .. [7] https://pax.grsecurity.net/
33 36
34 37
35 Purpose <<
36 ======= <<
37 <<
38 GCC plugins are designed to provide a place to <<
39 compiler features that are neither in GCC nor <<
40 their utility is proven, the goal is to upstre <<
41 (and Clang), and then to finally remove them f <<
42 feature is available in all supported versions <<
43 <<
44 Specifically, new plugins should implement onl <<
45 upstream compiler support (in either GCC or Cl <<
46 <<
47 When a feature exists in Clang but not GCC, ef <<
48 bring the feature to upstream GCC (rather than <<
49 GCC plugin), so the entire ecosystem can benef <<
50 <<
51 Similarly, even if a feature provided by a GCC <<
52 in Clang, but the feature is proven to be usef <<
53 to upstream the feature to GCC (and Clang). <<
54 <<
55 After a feature is available in upstream GCC, <<
56 unbuildable for the corresponding GCC version <<
57 kernel-supported versions of GCC provide the f <<
58 be removed from the kernel. <<
59 <<
60 <<
61 Files 38 Files
62 ===== 39 =====
63 40
64 **$(src)/scripts/gcc-plugins** 41 **$(src)/scripts/gcc-plugins**
65 42
66 This is the directory of the GCC plugi 43 This is the directory of the GCC plugins.
67 44
68 **$(src)/scripts/gcc-plugins/gcc-common.h** 45 **$(src)/scripts/gcc-plugins/gcc-common.h**
69 46
70 This is a compatibility header for GCC 47 This is a compatibility header for GCC plugins.
71 It should be always included instead o 48 It should be always included instead of individual gcc headers.
72 49
>> 50 **$(src)/scripts/gcc-plugin.sh**
>> 51
>> 52 This script checks the availability of the included headers in
>> 53 gcc-common.h and chooses the proper host compiler to build the plugins
>> 54 (gcc-4.7 can be built by either gcc or g++).
>> 55
73 **$(src)/scripts/gcc-plugins/gcc-generate-gimp 56 **$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h,
74 $(src)/scripts/gcc-plugins/gcc-generate-ipa-pa 57 $(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h,
75 $(src)/scripts/gcc-plugins/gcc-generate-simple 58 $(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h,
76 $(src)/scripts/gcc-plugins/gcc-generate-rtl-pa 59 $(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**
77 60
78 These headers automatically generate t 61 These headers automatically generate the registration structures for
79 GIMPLE, SIMPLE_IPA, IPA and RTL passes !! 62 GIMPLE, SIMPLE_IPA, IPA and RTL passes. They support all gcc versions
>> 63 from 4.5 to 6.0.
80 They should be preferred to creating t 64 They should be preferred to creating the structures by hand.
81 65
82 66
83 Usage 67 Usage
84 ===== 68 =====
85 69
86 You must install the gcc plugin headers for yo 70 You must install the gcc plugin headers for your gcc version,
87 e.g., on Ubuntu for gcc-10:: !! 71 e.g., on Ubuntu for gcc-4.9::
88 72
89 apt-get install gcc-10-plugin-dev !! 73 apt-get install gcc-4.9-plugin-dev
90 74
91 Or on Fedora:: 75 Or on Fedora::
92 76
93 dnf install gcc-plugin-devel libmpc-de !! 77 dnf install gcc-plugin-devel
94 <<
95 Or on Fedora when using cross-compilers that i <<
96 <<
97 dnf install libmpc-devel <<
98 <<
99 Enable the GCC plugin infrastructure and some <<
100 in the kernel config:: <<
101 <<
102 CONFIG_GCC_PLUGINS=y <<
103 CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y <<
104 ... <<
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 78
115 A full path means they are detected:: !! 79 Enable a GCC plugin based feature in the kernel config::
116 80
117 /usr/lib/gcc/x86_64-redhat-linux/12/plu !! 81 CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y
118 82
119 To compile the minimum tool set including the !! 83 To compile only the plugin(s)::
120 84
121 make scripts !! 85 make gcc-plugins
122 86
123 or just run the kernel make and compile the wh 87 or just run the kernel make and compile the whole kernel with
124 the cyclomatic complexity GCC plugin. 88 the cyclomatic complexity GCC plugin.
125 89
126 90
127 4. How to add a new GCC plugin 91 4. How to add a new GCC plugin
128 ============================== 92 ==============================
129 93
130 The GCC plugins are in scripts/gcc-plugins/. Y !! 94 The GCC plugins are in $(src)/scripts/gcc-plugins/. You can use a file or a directory
131 right under scripts/gcc-plugins/. Creating sub !! 95 here. It must be added to $(src)/scripts/gcc-plugins/Makefile,
132 It must be added to scripts/gcc-plugins/Makefi !! 96 $(src)/scripts/Makefile.gcc-plugins and $(src)/arch/Kconfig.
133 and a relevant Kconfig file. !! 97 See the cyc_complexity_plugin.c (CONFIG_GCC_PLUGIN_CYC_COMPLEXITY) GCC plugin.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.