| | 1 | ========================= |
| | 2 | GCC plugin infrastructure |
| | 3 | ========================= |
| | 4 | |
| | 5 | |
| | 6 | Introduction |
| | 7 | ============ |
| | 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. |
| | 11 | We can analyse, change and add further code during compilation via |
| | 12 | callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_. |
| | 13 | |
| | 14 | The GCC plugin infrastructure of the kernel supports building out-of-tree |
| | 15 | modules, cross-compilation and building in a separate directory. |
| | 16 | Plugin source files have to be compilable by a C++ compiler. |
| | 17 | |
| | 18 | Currently the GCC plugin infrastructure supports only some architectures. |
| | 19 | Grep "select HAVE_GCC_PLUGINS" to find out which architectures support |
| | 20 | GCC plugins. |
| | 21 | |
| | 22 | This infrastructure was ported from grsecurity [6]_ and PaX [7]_. |
| | 23 | |
| | 24 | -- |
| | 25 | |
| | 26 | .. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html |
| | 27 | .. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API |
| | 28 | .. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html |
| | 29 | .. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html |
| | 30 | .. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html |
| | 31 | .. [6] https://grsecurity.net/ |
| | 32 | .. [7] https://pax.grsecurity.net/ |
| | 33 | |
| | 34 | |
| | 35 | Purpose |
| | 36 | ======= |
| | 37 | |
| | 38 | GCC plugins are designed to provide a place to experiment with potential |
| | 39 | compiler features that are neither in GCC nor Clang upstream. Once |
| | 40 | their utility is proven, the goal is to upstream the feature into GCC |
| | 41 | (and Clang), and then to finally remove them from the kernel once the |
| | 42 | feature is available in all supported versions of GCC. |
| | 43 | |
| | 44 | Specifically, new plugins should implement only features that have no |
| | 45 | upstream compiler support (in either GCC or Clang). |
| | 46 | |
| | 47 | When a feature exists in Clang but not GCC, effort should be made to |
| | 48 | bring the feature to upstream GCC (rather than just as a kernel-specific |
| | 49 | GCC plugin), so the entire ecosystem can benefit from it. |
| | 50 | |
| | 51 | Similarly, even if a feature provided by a GCC plugin does *not* exist |
| | 52 | in Clang, but the feature is proven to be useful, effort should be spent |
| | 53 | to upstream the feature to GCC (and Clang). |
| | 54 | |
| | 55 | After a feature is available in upstream GCC, the plugin will be made |
| | 56 | unbuildable for the corresponding GCC version (and later). Once all |
| | 57 | kernel-supported versions of GCC provide the feature, the plugin will |
| | 58 | be removed from the kernel. |
| | 59 | |
| | 60 | |
| | 61 | Files |
| | 62 | ===== |
| | 63 | |
| | 64 | **$(src)/scripts/gcc-plugins** |
| | 65 | |
| | 66 | This is the directory of the GCC plugins. |
| | 67 | |
| | 68 | **$(src)/scripts/gcc-plugins/gcc-common.h** |
| | 69 | |
| | 70 | This is a compatibility header for GCC plugins. |
| | 71 | It should be always included instead of individual gcc headers. |
| | 72 | |
| | 73 | **$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h, |
| | 74 | $(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h, |
| | 75 | $(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h, |
| | 76 | $(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h** |
| | 77 | |
| | 78 | These headers automatically generate the registration structures for |
| | 79 | GIMPLE, SIMPLE_IPA, IPA and RTL passes. |
| | 80 | They should be preferred to creating the structures by hand. |
| | 81 | |
| | 82 | |
| | 83 | Usage |
| | 84 | ===== |
| | 85 | |
| | 86 | You must install the gcc plugin headers for your gcc version, |
| | 87 | e.g., on Ubuntu for gcc-10:: |
| | 88 | |
| | 89 | apt-get install gcc-10-plugin-dev |
| | 90 | |
| | 91 | Or on Fedora:: |
| | 92 | |
| | 93 | dnf install gcc-plugin-devel libmpc-devel |
| | 94 | |
| | 95 | Or on Fedora when using cross-compilers that include plugins:: |
| | 96 | |
| | 97 | dnf install libmpc-devel |
| | 98 | |
| | 99 | Enable the GCC plugin infrastructure and some plugin(s) you want to use |
| | 100 | in the kernel config:: |
| | 101 | |
| | 102 | CONFIG_GCC_PLUGINS=y |
| | 103 | CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y |
| | 104 | ... |
| | 105 | |
| | 106 | Run gcc (native or cross-compiler) to ensure plugin headers are detected:: |
| | 107 | |
| | 108 | gcc -print-file-name=plugin |
| | 109 | CROSS_COMPILE=arm-linux-gnu- ${CROSS_COMPILE}gcc -print-file-name=plugin |
| | 110 | |
| | 111 | The word "plugin" means they are not detected:: |
| | 112 | |
| | 113 | plugin |
| | 114 | |
| | 115 | A full path means they are detected:: |
| | 116 | |
| | 117 | /usr/lib/gcc/x86_64-redhat-linux/12/plugin |
| | 118 | |
| | 119 | To compile the minimum tool set including the plugin(s):: |
| | 120 | |
| | 121 | make scripts |
| | 122 | |
| | 123 | or just run the kernel make and compile the whole kernel with |
| | 124 | the cyclomatic complexity GCC plugin. |
| | 125 | |
| | 126 | |
| | 127 | 4. How to add a new GCC plugin |
| | 128 | ============================== |
| | 129 | |
| | 130 | The GCC plugins are in scripts/gcc-plugins/. You need to put plugin source files |
| | 131 | right under scripts/gcc-plugins/. Creating subdirectories is not supported. |
| | 132 | It must be added to scripts/gcc-plugins/Makefile, scripts/Makefile.gcc-plugins |
| | 133 | and a relevant Kconfig file. |
projects / linux-2.6-block.git / blame_incremental