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 35Purpose 36======= 37 38GCC plugins are designed to provide a place to experiment with potential 39compiler features that are neither in GCC nor Clang upstream. Once 40their 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 42feature is available in all supported versions of GCC. 43 44Specifically, new plugins should implement only features that have no 45upstream compiler support (in either GCC or Clang). 46 47When a feature exists in Clang but not GCC, effort should be made to 48bring the feature to upstream GCC (rather than just as a kernel-specific 49GCC plugin), so the entire ecosystem can benefit from it. 50 51Similarly, even if a feature provided by a GCC plugin does *not* exist 52in Clang, but the feature is proven to be useful, effort should be spent 53to upstream the feature to GCC (and Clang). 54 55After a feature is available in upstream GCC, the plugin will be made 56unbuildable for the corresponding GCC version (and later). Once all 57kernel-supported versions of GCC provide the feature, the plugin will 58be removed from the kernel. 59 60 61Files 62===== 63 64**$(src)/scripts/gcc-plugins** 65 66 This is the directory of the GCC plugins. 67 68**$(src)/scripts/gcc-plugins/gcc-common.h** 69 70 This is a compatibility header for GCC plugins. 71 It should be always included instead of individual gcc headers. 72 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 78 These headers automatically generate the registration structures for 79 GIMPLE, SIMPLE_IPA, IPA and RTL passes. 80 They should be preferred to creating the structures by hand. 81 82 83Usage 84===== 85 86You must install the gcc plugin headers for your gcc version, 87e.g., on Ubuntu for gcc-10:: 88 89 apt-get install gcc-10-plugin-dev 90 91Or on Fedora:: 92 93 dnf install gcc-plugin-devel libmpc-devel 94 95Or on Fedora when using cross-compilers that include plugins:: 96 97 dnf install libmpc-devel 98 99Enable the GCC plugin infrastructure and some plugin(s) you want to use 100in the kernel config:: 101 102 CONFIG_GCC_PLUGINS=y 103 CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y 104 ... 105 106Run 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 111The word "plugin" means they are not detected:: 112 113 plugin 114 115A full path means they are detected:: 116 117 /usr/lib/gcc/x86_64-redhat-linux/12/plugin 118 119To compile the minimum tool set including the plugin(s):: 120 121 make scripts 122 123or just run the kernel make and compile the whole kernel with 124the cyclomatic complexity GCC plugin. 125 126 1274. How to add a new GCC plugin 128============================== 129 130The GCC plugins are in scripts/gcc-plugins/. You need to put plugin source files 131right under scripts/gcc-plugins/. Creating subdirectories is not supported. 132It must be added to scripts/gcc-plugins/Makefile, scripts/Makefile.gcc-plugins 133and a relevant Kconfig file. 134