blob: 891c694644348241925dc3e585d632222d8b0948
1 | GCC plugin infrastructure |
2 | ========================= |
3 | |
4 | |
5 | 1. Introduction |
6 | =============== |
7 | |
8 | GCC plugins are loadable modules that provide extra features to the |
9 | compiler [1]. They are useful for runtime instrumentation and static analysis. |
10 | We can analyse, change and add further code during compilation via |
11 | callbacks [2], GIMPLE [3], IPA [4] and RTL passes [5]. |
12 | |
13 | The GCC plugin infrastructure of the kernel supports all gcc versions from |
14 | 4.5 to 6.0, building out-of-tree modules, cross-compilation and building in a |
15 | separate directory. |
16 | Plugin source files have to be compilable by both a C and a C++ compiler as well |
17 | because gcc versions 4.5 and 4.6 are compiled by a C compiler, |
18 | gcc-4.7 can be compiled by a C or a C++ compiler, |
19 | and versions 4.8+ can only be compiled by a C++ compiler. |
20 | |
21 | Currently the GCC plugin infrastructure supports only the x86, arm and arm64 |
22 | architectures. |
23 | |
24 | This infrastructure was ported from grsecurity [6] and PaX [7]. |
25 | |
26 | -- |
27 | [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html |
28 | [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API |
29 | [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html |
30 | [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html |
31 | [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html |
32 | [6] https://grsecurity.net/ |
33 | [7] https://pax.grsecurity.net/ |
34 | |
35 | |
36 | 2. Files |
37 | ======== |
38 | |
39 | $(src)/scripts/gcc-plugins |
40 | This is the directory of the GCC plugins. |
41 | |
42 | $(src)/scripts/gcc-plugins/gcc-common.h |
43 | This is a compatibility header for GCC plugins. |
44 | It should be always included instead of individual gcc headers. |
45 | |
46 | $(src)/scripts/gcc-plugin.sh |
47 | This script checks the availability of the included headers in |
48 | gcc-common.h and chooses the proper host compiler to build the plugins |
49 | (gcc-4.7 can be built by either gcc or g++). |
50 | |
51 | $(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h |
52 | $(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h |
53 | $(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h |
54 | $(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h |
55 | These headers automatically generate the registration structures for |
56 | GIMPLE, SIMPLE_IPA, IPA and RTL passes. They support all gcc versions |
57 | from 4.5 to 6.0. |
58 | They should be preferred to creating the structures by hand. |
59 | |
60 | |
61 | 3. Usage |
62 | ======== |
63 | |
64 | You must install the gcc plugin headers for your gcc version, |
65 | e.g., on Ubuntu for gcc-4.9: |
66 | |
67 | apt-get install gcc-4.9-plugin-dev |
68 | |
69 | Enable a GCC plugin based feature in the kernel config: |
70 | |
71 | CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y |
72 | |
73 | To compile only the plugin(s): |
74 | |
75 | make gcc-plugins |
76 | |
77 | or just run the kernel make and compile the whole kernel with |
78 | the cyclomatic complexity GCC plugin. |
79 | |
80 | |
81 | 4. How to add a new GCC plugin |
82 | ============================== |
83 | |
84 | The GCC plugins are in $(src)/scripts/gcc-plugins/. You can use a file or a directory |
85 | here. It must be added to $(src)/scripts/gcc-plugins/Makefile, |
86 | $(src)/scripts/Makefile.gcc-plugins and $(src)/arch/Kconfig. |
87 | See the cyc_complexity_plugin.c (CONFIG_GCC_PLUGIN_CYC_COMPLEXITY) GCC plugin. |
88 |