gcc-plugins.txt 2.87 KB
Newer Older
Emese Revfy's avatar
Emese Revfy committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
GCC plugin infrastructure
=========================


1. 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 all gcc versions from
4.5 to 6.0, building out-of-tree modules, cross-compilation and building in a
separate directory.
Plugin source files have to be compilable by both a C and a C++ compiler as well
because gcc versions 4.5 and 4.6 are compiled by a C compiler,
gcc-4.7 can be compiled by a C or a C++ compiler,
and versions 4.8+ can only be compiled by a C++ compiler.

21 22
Currently the GCC plugin infrastructure supports only the x86, arm, arm64 and
powerpc architectures.
Emese Revfy's avatar
Emese Revfy committed
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87

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/


2. 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-plugin.sh
	This script checks the availability of the included headers in
	gcc-common.h and chooses the proper host compiler to build the plugins
	(gcc-4.7 can be built by either gcc or g++).

$(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 support all gcc versions
	from 4.5 to 6.0.
	They should be preferred to creating the structures by hand.


3. Usage
========

You must install the gcc plugin headers for your gcc version,
e.g., on Ubuntu for gcc-4.9:

	apt-get install gcc-4.9-plugin-dev

Enable a GCC plugin based feature in the kernel config:

	CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y

To compile only the plugin(s):

	make gcc-plugins

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 $(src)/scripts/gcc-plugins/. You can use a file or a directory
here. It must be added to $(src)/scripts/gcc-plugins/Makefile,
$(src)/scripts/Makefile.gcc-plugins and $(src)/arch/Kconfig.
See the cyc_complexity_plugin.c (CONFIG_GCC_PLUGIN_CYC_COMPLEXITY) GCC plugin.