12b4cbd5cSJonathan Corbet========================= 22b4cbd5cSJonathan CorbetGCC plugin infrastructure 32b4cbd5cSJonathan Corbet========================= 42b4cbd5cSJonathan Corbet 52b4cbd5cSJonathan Corbet 62b4cbd5cSJonathan CorbetIntroduction 72b4cbd5cSJonathan Corbet============ 82b4cbd5cSJonathan Corbet 92b4cbd5cSJonathan CorbetGCC plugins are loadable modules that provide extra features to the 102b4cbd5cSJonathan Corbetcompiler [1]_. They are useful for runtime instrumentation and static analysis. 112b4cbd5cSJonathan CorbetWe can analyse, change and add further code during compilation via 122b4cbd5cSJonathan Corbetcallbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_. 132b4cbd5cSJonathan Corbet 149b616434SMasahiro YamadaThe GCC plugin infrastructure of the kernel supports building out-of-tree 159b616434SMasahiro Yamadamodules, cross-compilation and building in a separate directory. 169b616434SMasahiro YamadaPlugin source files have to be compilable by a C++ compiler. 172b4cbd5cSJonathan Corbet 189b616434SMasahiro YamadaCurrently the GCC plugin infrastructure supports only some architectures. 199b616434SMasahiro YamadaGrep "select HAVE_GCC_PLUGINS" to find out which architectures support 209b616434SMasahiro YamadaGCC plugins. 212b4cbd5cSJonathan Corbet 222b4cbd5cSJonathan CorbetThis infrastructure was ported from grsecurity [6]_ and PaX [7]_. 232b4cbd5cSJonathan Corbet 242b4cbd5cSJonathan Corbet-- 252b4cbd5cSJonathan Corbet 262b4cbd5cSJonathan Corbet.. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html 272b4cbd5cSJonathan Corbet.. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API 282b4cbd5cSJonathan Corbet.. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html 292b4cbd5cSJonathan Corbet.. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html 302b4cbd5cSJonathan Corbet.. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html 312b4cbd5cSJonathan Corbet.. [6] https://grsecurity.net/ 322b4cbd5cSJonathan Corbet.. [7] https://pax.grsecurity.net/ 332b4cbd5cSJonathan Corbet 342b4cbd5cSJonathan Corbet 358bd51a2bSKees CookPurpose 368bd51a2bSKees Cook======= 378bd51a2bSKees Cook 388bd51a2bSKees CookGCC plugins are designed to provide a place to experiment with potential 398bd51a2bSKees Cookcompiler features that are neither in GCC nor Clang upstream. Once 408bd51a2bSKees Cooktheir utility is proven, the goal is to upstream the feature into GCC 418bd51a2bSKees Cook(and Clang), and then to finally remove them from the kernel once the 428bd51a2bSKees Cookfeature is available in all supported versions of GCC. 438bd51a2bSKees Cook 448bd51a2bSKees CookSpecifically, new plugins should implement only features that have no 458bd51a2bSKees Cookupstream compiler support (in either GCC or Clang). 468bd51a2bSKees Cook 478bd51a2bSKees CookWhen a feature exists in Clang but not GCC, effort should be made to 488bd51a2bSKees Cookbring the feature to upstream GCC (rather than just as a kernel-specific 498bd51a2bSKees CookGCC plugin), so the entire ecosystem can benefit from it. 508bd51a2bSKees Cook 518bd51a2bSKees CookSimilarly, even if a feature provided by a GCC plugin does *not* exist 528bd51a2bSKees Cookin Clang, but the feature is proven to be useful, effort should be spent 538bd51a2bSKees Cookto upstream the feature to GCC (and Clang). 548bd51a2bSKees Cook 558bd51a2bSKees CookAfter a feature is available in upstream GCC, the plugin will be made 568bd51a2bSKees Cookunbuildable for the corresponding GCC version (and later). Once all 578bd51a2bSKees Cookkernel-supported versions of GCC provide the feature, the plugin will 588bd51a2bSKees Cookbe removed from the kernel. 598bd51a2bSKees Cook 608bd51a2bSKees Cook 612b4cbd5cSJonathan CorbetFiles 622b4cbd5cSJonathan Corbet===== 632b4cbd5cSJonathan Corbet 642b4cbd5cSJonathan Corbet**$(src)/scripts/gcc-plugins** 652b4cbd5cSJonathan Corbet 662b4cbd5cSJonathan Corbet This is the directory of the GCC plugins. 672b4cbd5cSJonathan Corbet 682b4cbd5cSJonathan Corbet**$(src)/scripts/gcc-plugins/gcc-common.h** 692b4cbd5cSJonathan Corbet 702b4cbd5cSJonathan Corbet This is a compatibility header for GCC plugins. 712b4cbd5cSJonathan Corbet It should be always included instead of individual gcc headers. 722b4cbd5cSJonathan Corbet 732b4cbd5cSJonathan Corbet**$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h, 742b4cbd5cSJonathan Corbet$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h, 752b4cbd5cSJonathan Corbet$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h, 762b4cbd5cSJonathan Corbet$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h** 772b4cbd5cSJonathan Corbet 782b4cbd5cSJonathan Corbet These headers automatically generate the registration structures for 799b616434SMasahiro Yamada GIMPLE, SIMPLE_IPA, IPA and RTL passes. 802b4cbd5cSJonathan Corbet They should be preferred to creating the structures by hand. 812b4cbd5cSJonathan Corbet 822b4cbd5cSJonathan Corbet 832b4cbd5cSJonathan CorbetUsage 842b4cbd5cSJonathan Corbet===== 852b4cbd5cSJonathan Corbet 862b4cbd5cSJonathan CorbetYou must install the gcc plugin headers for your gcc version, 879b616434SMasahiro Yamadae.g., on Ubuntu for gcc-10:: 882b4cbd5cSJonathan Corbet 899b616434SMasahiro Yamada apt-get install gcc-10-plugin-dev 902b4cbd5cSJonathan Corbet 912b4cbd5cSJonathan CorbetOr on Fedora:: 922b4cbd5cSJonathan Corbet 93*3832d1fdSRobert Elliott dnf install gcc-plugin-devel libmpc-devel 94*3832d1fdSRobert Elliott 95*3832d1fdSRobert ElliottOr on Fedora when using cross-compilers that include plugins:: 96*3832d1fdSRobert Elliott 97*3832d1fdSRobert Elliott dnf install libmpc-devel 982b4cbd5cSJonathan Corbet 999b616434SMasahiro YamadaEnable the GCC plugin infrastructure and some plugin(s) you want to use 1009b616434SMasahiro Yamadain the kernel config:: 1012b4cbd5cSJonathan Corbet 1029b616434SMasahiro Yamada CONFIG_GCC_PLUGINS=y 1039b616434SMasahiro Yamada CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y 1049b616434SMasahiro Yamada ... 1052b4cbd5cSJonathan Corbet 106*3832d1fdSRobert ElliottRun gcc (native or cross-compiler) to ensure plugin headers are detected:: 107*3832d1fdSRobert Elliott 108*3832d1fdSRobert Elliott gcc -print-file-name=plugin 109*3832d1fdSRobert Elliott CROSS_COMPILE=arm-linux-gnu- ${CROSS_COMPILE}gcc -print-file-name=plugin 110*3832d1fdSRobert Elliott 111*3832d1fdSRobert ElliottThe word "plugin" means they are not detected:: 112*3832d1fdSRobert Elliott 113*3832d1fdSRobert Elliott plugin 114*3832d1fdSRobert Elliott 115*3832d1fdSRobert ElliottA full path means they are detected:: 116*3832d1fdSRobert Elliott 117*3832d1fdSRobert Elliott /usr/lib/gcc/x86_64-redhat-linux/12/plugin 118*3832d1fdSRobert Elliott 1199b616434SMasahiro YamadaTo compile the minimum tool set including the plugin(s):: 1202b4cbd5cSJonathan Corbet 1219b616434SMasahiro Yamada make scripts 1222b4cbd5cSJonathan Corbet 1232b4cbd5cSJonathan Corbetor just run the kernel make and compile the whole kernel with 1242b4cbd5cSJonathan Corbetthe cyclomatic complexity GCC plugin. 1252b4cbd5cSJonathan Corbet 1262b4cbd5cSJonathan Corbet 1272b4cbd5cSJonathan Corbet4. How to add a new GCC plugin 1282b4cbd5cSJonathan Corbet============================== 1292b4cbd5cSJonathan Corbet 1309b616434SMasahiro YamadaThe GCC plugins are in scripts/gcc-plugins/. You need to put plugin source files 1319b616434SMasahiro Yamadaright under scripts/gcc-plugins/. Creating subdirectories is not supported. 1329b616434SMasahiro YamadaIt must be added to scripts/gcc-plugins/Makefile, scripts/Makefile.gcc-plugins 1339b616434SMasahiro Yamadaand a relevant Kconfig file. 134