gcc-plugins.txt 2.93 KB
Newer Older
1
=========================
Emese Revfy's avatar
Emese Revfy committed
2 3 4 5
GCC plugin infrastructure
=========================


6 7
Introduction
============
Emese Revfy's avatar
Emese Revfy committed
8 9

GCC plugins are loadable modules that provide extra features to the
10
compiler [1]_. They are useful for runtime instrumentation and static analysis.
Emese Revfy's avatar
Emese Revfy committed
11
We can analyse, change and add further code during compilation via
12
callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_.
Emese Revfy's avatar
Emese Revfy committed
13 14 15 16 17 18 19 20 21

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.

22 23
Currently the GCC plugin infrastructure supports only the x86, arm, arm64 and
powerpc architectures.
Emese Revfy's avatar
Emese Revfy committed
24

25
This infrastructure was ported from grsecurity [6]_ and PaX [7]_.
Emese Revfy's avatar
Emese Revfy committed
26 27 28

--

29 30 31 32 33 34 35 36 37 38 39
.. [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
=====
Emese Revfy's avatar
Emese Revfy committed
40

41
**$(src)/scripts/gcc-plugins**
Emese Revfy's avatar
Emese Revfy committed
42 43 44

	This is the directory of the GCC plugins.

45 46
**$(src)/scripts/gcc-plugins/gcc-common.h**

Emese Revfy's avatar
Emese Revfy committed
47 48 49
	This is a compatibility header for GCC plugins.
	It should be always included instead of individual gcc headers.

50 51
**$(src)/scripts/gcc-plugin.sh**

Emese Revfy's avatar
Emese Revfy committed
52 53 54 55
	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++).

56 57 58 59 60
**$(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**

Emese Revfy's avatar
Emese Revfy committed
61 62 63 64 65 66
	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.


67 68
Usage
=====
Emese Revfy's avatar
Emese Revfy committed
69 70

You must install the gcc plugin headers for your gcc version,
71
e.g., on Ubuntu for gcc-4.9::
Emese Revfy's avatar
Emese Revfy committed
72 73 74

	apt-get install gcc-4.9-plugin-dev

75
Enable a GCC plugin based feature in the kernel config::
Emese Revfy's avatar
Emese Revfy committed
76 77 78

	CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y

79
To compile only the plugin(s)::
Emese Revfy's avatar
Emese Revfy committed
80 81 82 83 84 85 86 87 88 89 90 91 92 93

	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.