Commit ccd8d557 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet

gcc-plugins.txt: standardize document format

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- promote main title;
- use the right markup for footnotes;
- use bold markup for files name;
- identify literal blocks;
- add blank lines to avoid Sphinx to complain;
- remove numeration from titles.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent db4df481
=========================
GCC plugin infrastructure GCC plugin infrastructure
========================= =========================
1. Introduction Introduction
=============== ============
GCC plugins are loadable modules that provide extra features to the GCC plugins are loadable modules that provide extra features to the
compiler [1]. They are useful for runtime instrumentation and static analysis. compiler [1]_. They are useful for runtime instrumentation and static analysis.
We can analyse, change and add further code during compilation via We can analyse, change and add further code during compilation via
callbacks [2], GIMPLE [3], IPA [4] and RTL passes [5]. callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_.
The GCC plugin infrastructure of the kernel supports all gcc versions from 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 4.5 to 6.0, building out-of-tree modules, cross-compilation and building in a
...@@ -21,56 +22,61 @@ and versions 4.8+ can only be compiled by a C++ compiler. ...@@ -21,56 +22,61 @@ and versions 4.8+ can only be compiled by a C++ compiler.
Currently the GCC plugin infrastructure supports only the x86, arm, arm64 and Currently the GCC plugin infrastructure supports only the x86, arm, arm64 and
powerpc architectures. powerpc architectures.
This infrastructure was ported from grsecurity [6] and PaX [7]. 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/
.. [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
=====
2. Files **$(src)/scripts/gcc-plugins**
========
$(src)/scripts/gcc-plugins
This is the directory of the GCC plugins. This is the directory of the GCC plugins.
$(src)/scripts/gcc-plugins/gcc-common.h **$(src)/scripts/gcc-plugins/gcc-common.h**
This is a compatibility header for GCC plugins. This is a compatibility header for GCC plugins.
It should be always included instead of individual gcc headers. It should be always included instead of individual gcc headers.
$(src)/scripts/gcc-plugin.sh **$(src)/scripts/gcc-plugin.sh**
This script checks the availability of the included headers in This script checks the availability of the included headers in
gcc-common.h and chooses the proper host compiler to build the plugins gcc-common.h and chooses the proper host compiler to build the plugins
(gcc-4.7 can be built by either gcc or g++). (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-gimple-pass.h,
$(src)/scripts/gcc-plugins/gcc-generate-ipa-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-simple_ipa-pass.h,
$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h $(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**
These headers automatically generate the registration structures for These headers automatically generate the registration structures for
GIMPLE, SIMPLE_IPA, IPA and RTL passes. They support all gcc versions GIMPLE, SIMPLE_IPA, IPA and RTL passes. They support all gcc versions
from 4.5 to 6.0. from 4.5 to 6.0.
They should be preferred to creating the structures by hand. They should be preferred to creating the structures by hand.
3. Usage Usage
======== =====
You must install the gcc plugin headers for your gcc version, You must install the gcc plugin headers for your gcc version,
e.g., on Ubuntu for gcc-4.9: e.g., on Ubuntu for gcc-4.9::
apt-get install gcc-4.9-plugin-dev apt-get install gcc-4.9-plugin-dev
Enable a GCC plugin based feature in the kernel config: Enable a GCC plugin based feature in the kernel config::
CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y
To compile only the plugin(s): To compile only the plugin(s)::
make gcc-plugins make gcc-plugins
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment