xref: /openbmc/linux/Documentation/kbuild/gcc-plugins.rst (revision 4f2c0a4acffbec01079c28f839422e64ddeff004)
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