Commit | Line | Data |
---|---|---|
ccd8d557 | 1 | ========================= |
6b90bd4b ER |
2 | GCC plugin infrastructure |
3 | ========================= | |
4 | ||
5 | ||
ccd8d557 MCC |
6 | Introduction |
7 | ============ | |
6b90bd4b ER |
8 | |
9 | GCC plugins are loadable modules that provide extra features to the | |
ccd8d557 | 10 | compiler [1]_. They are useful for runtime instrumentation and static analysis. |
6b90bd4b | 11 | We can analyse, change and add further code during compilation via |
ccd8d557 | 12 | callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_. |
6b90bd4b | 13 | |
9b616434 MY |
14 | The GCC plugin infrastructure of the kernel supports building out-of-tree |
15 | modules, cross-compilation and building in a separate directory. | |
16 | Plugin source files have to be compilable by a C++ compiler. | |
6b90bd4b | 17 | |
9b616434 MY |
18 | Currently the GCC plugin infrastructure supports only some architectures. |
19 | Grep "select HAVE_GCC_PLUGINS" to find out which architectures support | |
20 | GCC plugins. | |
6b90bd4b | 21 | |
ccd8d557 | 22 | This infrastructure was ported from grsecurity [6]_ and PaX [7]_. |
6b90bd4b ER |
23 | |
24 | -- | |
6b90bd4b | 25 | |
ccd8d557 MCC |
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 | ||
8bd51a2b KC |
35 | Purpose |
36 | ======= | |
37 | ||
38 | GCC plugins are designed to provide a place to experiment with potential | |
39 | compiler features that are neither in GCC nor Clang upstream. Once | |
40 | their 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 | |
42 | feature is available in all supported versions of GCC. | |
43 | ||
44 | Specifically, new plugins should implement only features that have no | |
45 | upstream compiler support (in either GCC or Clang). | |
46 | ||
47 | When a feature exists in Clang but not GCC, effort should be made to | |
48 | bring the feature to upstream GCC (rather than just as a kernel-specific | |
49 | GCC plugin), so the entire ecosystem can benefit from it. | |
50 | ||
51 | Similarly, even if a feature provided by a GCC plugin does *not* exist | |
52 | in Clang, but the feature is proven to be useful, effort should be spent | |
53 | to upstream the feature to GCC (and Clang). | |
54 | ||
55 | After a feature is available in upstream GCC, the plugin will be made | |
56 | unbuildable for the corresponding GCC version (and later). Once all | |
57 | kernel-supported versions of GCC provide the feature, the plugin will | |
58 | be removed from the kernel. | |
59 | ||
60 | ||
ccd8d557 MCC |
61 | Files |
62 | ===== | |
6b90bd4b | 63 | |
ccd8d557 | 64 | **$(src)/scripts/gcc-plugins** |
6b90bd4b | 65 | |
6b90bd4b ER |
66 | This is the directory of the GCC plugins. |
67 | ||
ccd8d557 MCC |
68 | **$(src)/scripts/gcc-plugins/gcc-common.h** |
69 | ||
6b90bd4b ER |
70 | This is a compatibility header for GCC plugins. |
71 | It should be always included instead of individual gcc headers. | |
72 | ||
ccd8d557 MCC |
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 | ||
6b90bd4b | 78 | These headers automatically generate the registration structures for |
9b616434 | 79 | GIMPLE, SIMPLE_IPA, IPA and RTL passes. |
6b90bd4b ER |
80 | They should be preferred to creating the structures by hand. |
81 | ||
82 | ||
ccd8d557 MCC |
83 | Usage |
84 | ===== | |
6b90bd4b ER |
85 | |
86 | You must install the gcc plugin headers for your gcc version, | |
9b616434 | 87 | e.g., on Ubuntu for gcc-10:: |
6b90bd4b | 88 | |
9b616434 | 89 | apt-get install gcc-10-plugin-dev |
6b90bd4b | 90 | |
43e96ef8 ME |
91 | Or on Fedora:: |
92 | ||
3832d1fd RE |
93 | dnf install gcc-plugin-devel libmpc-devel |
94 | ||
95 | Or on Fedora when using cross-compilers that include plugins:: | |
96 | ||
97 | dnf install libmpc-devel | |
43e96ef8 | 98 | |
9b616434 MY |
99 | Enable the GCC plugin infrastructure and some plugin(s) you want to use |
100 | in the kernel config:: | |
6b90bd4b | 101 | |
9b616434 | 102 | CONFIG_GCC_PLUGINS=y |
9b616434 MY |
103 | CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y |
104 | ... | |
6b90bd4b | 105 | |
3832d1fd RE |
106 | Run gcc (native or cross-compiler) to ensure plugin headers are detected:: |
107 | ||
108 | gcc -print-file-name=plugin | |
109 | CROSS_COMPILE=arm-linux-gnu- ${CROSS_COMPILE}gcc -print-file-name=plugin | |
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/plugin | |
118 | ||
9b616434 | 119 | To compile the minimum tool set including the plugin(s):: |
6b90bd4b | 120 | |
9b616434 | 121 | make scripts |
6b90bd4b ER |
122 | |
123 | or just run the kernel make and compile the whole kernel with | |
124 | the cyclomatic complexity GCC plugin. | |
125 | ||
126 | ||
127 | 4. How to add a new GCC plugin | |
128 | ============================== | |
129 | ||
9b616434 MY |
130 | The GCC plugins are in scripts/gcc-plugins/. You need to put plugin source files |
131 | right under scripts/gcc-plugins/. Creating subdirectories is not supported. | |
132 | It must be added to scripts/gcc-plugins/Makefile, scripts/Makefile.gcc-plugins | |
133 | and a relevant Kconfig file. |