mirror of
https://github.com/torvalds/linux.git
synced 2024-11-11 22:51:42 +00:00
9b6164342e
This document was written a long time ago. Update it. [1] Drop the version information The range of the supported GCC versions are always changing. The current minimal GCC version is 4.9, and commit1e860048c5("gcc-plugins: simplify GCC plugin-dev capability test") removed the old code accordingly. We do not need to mention specific version ranges like "all gcc versions from 4.5 to 6.0" since we forget to update the documentation when we raise the minimal compiler version. [2] Drop the C compiler statements Since commit77342a02ff("gcc-plugins: drop support for GCC <= 4.7") the GCC plugin infrastructure only supports g++. [3] Drop supported architectures As of v5.11-rc4, the infrastructure supports more architectures; arm, arm64, mips, powerpc, riscv, s390, um, and x86. (just grep "select HAVE_GCC_PLUGINS") Again, we miss to update this document when a new architecture is supported. Let's just say "only some architectures". [4] Update the apt-get example We are now discussing to bump the minimal version to GCC 5. The GCC 4.9 support will be removed sooner or later. Change the package example to gcc-10-plugin-dev while we are here. [5] Update the build target Since commitce2fd53a10("kbuild: descend into scripts/gcc-plugins/ via scripts/Makefile"), "make gcc-plugins" is not supported. "make scripts" builds all the enabled plugins, including some other tools. [6] Update the steps for adding a new plugin At first, all CONFIG options for GCC plugins were located in arch/Kconfig. After commit45332b1bdf("gcc-plugins: split out Kconfig entries to scripts/gcc-plugins/Kconfig"), scripts/gcc-plugins/Kconfig became the central place to collect plugin CONFIG options. In my understanding, this requirement no longer exists because commit9f671e5815("security: Create "kernel hardening" config area") moved some of plugin CONFIG options to another file. Find an appropriate place to add the new CONFIG. The sub-directory support was never used by anyone, and removed by commitc17d6179ad("gcc-plugins: remove unused GCC_PLUGIN_SUBDIR"). Remove the useless $(src)/ prefix. Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
93 lines
2.7 KiB
ReStructuredText
93 lines
2.7 KiB
ReStructuredText
=========================
|
|
GCC plugin infrastructure
|
|
=========================
|
|
|
|
|
|
Introduction
|
|
============
|
|
|
|
GCC plugins are loadable modules that provide extra features to the
|
|
compiler [1]_. They are useful for runtime instrumentation and static analysis.
|
|
We can analyse, change and add further code during compilation via
|
|
callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_.
|
|
|
|
The GCC plugin infrastructure of the kernel supports building out-of-tree
|
|
modules, cross-compilation and building in a separate directory.
|
|
Plugin source files have to be compilable by a C++ compiler.
|
|
|
|
Currently the GCC plugin infrastructure supports only some architectures.
|
|
Grep "select HAVE_GCC_PLUGINS" to find out which architectures support
|
|
GCC plugins.
|
|
|
|
This infrastructure was ported from grsecurity [6]_ and PaX [7]_.
|
|
|
|
--
|
|
|
|
.. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html
|
|
.. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API
|
|
.. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html
|
|
.. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html
|
|
.. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html
|
|
.. [6] https://grsecurity.net/
|
|
.. [7] https://pax.grsecurity.net/
|
|
|
|
|
|
Files
|
|
=====
|
|
|
|
**$(src)/scripts/gcc-plugins**
|
|
|
|
This is the directory of the GCC plugins.
|
|
|
|
**$(src)/scripts/gcc-plugins/gcc-common.h**
|
|
|
|
This is a compatibility header for GCC plugins.
|
|
It should be always included instead of individual gcc headers.
|
|
|
|
**$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h,
|
|
$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h,
|
|
$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h,
|
|
$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**
|
|
|
|
These headers automatically generate the registration structures for
|
|
GIMPLE, SIMPLE_IPA, IPA and RTL passes.
|
|
They should be preferred to creating the structures by hand.
|
|
|
|
|
|
Usage
|
|
=====
|
|
|
|
You must install the gcc plugin headers for your gcc version,
|
|
e.g., on Ubuntu for gcc-10::
|
|
|
|
apt-get install gcc-10-plugin-dev
|
|
|
|
Or on Fedora::
|
|
|
|
dnf install gcc-plugin-devel
|
|
|
|
Enable the GCC plugin infrastructure and some plugin(s) you want to use
|
|
in the kernel config::
|
|
|
|
CONFIG_GCC_PLUGINS=y
|
|
CONFIG_GCC_PLUGIN_CYC_COMPLEXITY=y
|
|
CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y
|
|
...
|
|
|
|
To compile the minimum tool set including the plugin(s)::
|
|
|
|
make scripts
|
|
|
|
or just run the kernel make and compile the whole kernel with
|
|
the cyclomatic complexity GCC plugin.
|
|
|
|
|
|
4. How to add a new GCC plugin
|
|
==============================
|
|
|
|
The GCC plugins are in scripts/gcc-plugins/. You need to put plugin source files
|
|
right under scripts/gcc-plugins/. Creating subdirectories is not supported.
|
|
It must be added to scripts/gcc-plugins/Makefile, scripts/Makefile.gcc-plugins
|
|
and a relevant Kconfig file.
|
|
See the cyc_complexity_plugin.c (CONFIG_GCC_PLUGIN_CYC_COMPLEXITY) GCC plugin.
|