Rsphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget&/translations/zh_CN/kbuild/gcc-pluginsmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/zh_TW/kbuild/gcc-pluginsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/it_IT/kbuild/gcc-pluginsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/ja_JP/kbuild/gcc-pluginsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/ko_KR/kbuild/gcc-pluginsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/sp_SP/kbuild/gcc-pluginsmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(hGCC plugin infrastructureh]hGCC plugin infrastructure}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhh@/var/lib/git/docbuild/linux/Documentation/kbuild/gcc-plugins.rsthKubh)}(hhh](h)}(h Introductionh]h Introduction}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hXGCC 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]_.h](hMGCC plugins are loadable modules that provide extra features to the compiler }(hhhhhNhNubhfootnote_reference)}(h[1]_h]h1}(hhhhhNhNubah}(h]id1ah ]h"]h$]h&]refidid8docnamekbuild/gcc-pluginsuh1hhhʌresolvedKubh. They are useful for runtime instrumentation and static analysis. We can analyse, change and add further code during compilation via callbacks }(hhhhhNhNubh)}(h[2]_h]h2}(hhhhhNhNubah}(h]id2ah ]h"]h$]h&]hid9hhuh1hhhhKubh , GIMPLE }(hhhhhNhNubh)}(h[3]_h]h3}(hjhhhNhNubah}(h]id3ah ]h"]h$]h&]hid10hhuh1hhhhKubh, IPA }(hhhhhNhNubh)}(h[4]_h]h4}(hjhhhNhNubah}(h]id4ah ]h"]h$]h&]hid11hhuh1hhhhKubh and RTL passes }(hhhhhNhNubh)}(h[5]_h]h5}(hj(hhhNhNubah}(h]id5ah ]h"]h$]h&]hid12hhuh1hhhhKubh.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hThe 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.h]hThe 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.}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hCurrently the GCC plugin infrastructure supports only some architectures. Grep "select HAVE_GCC_PLUGINS" to find out which architectures support GCC plugins.h]hCurrently the GCC plugin infrastructure supports only some architectures. Grep “select HAVE_GCC_PLUGINS” to find out which architectures support GCC plugins.}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hAThis infrastructure was ported from grsecurity [6]_ and PaX [7]_.h](h/This infrastructure was ported from grsecurity }(hj^hhhNhNubh)}(h[6]_h]h6}(hjfhhhNhNubah}(h]id6ah ]h"]h$]h&]hid13hhuh1hhj^hKubh and PaX }(hj^hhhNhNubh)}(h[7]_h]h7}(hjzhhhNhNubah}(h]id7ah ]h"]h$]h&]hid14hhuh1hhj^hKubh.}(hj^hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(h--h]h--}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubhfootnote)}(h2https://gcc.gnu.org/onlinedocs/gccint/Plugins.htmlh](hlabel)}(h1h]h1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh)}(hjh]h reference)}(hjh]h2https://gcc.gnu.org/onlinedocs/gccint/Plugins.html}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]hah ]h"]1ah$]h&]hahhuh1jhhhKhhhhhKubj)}(h@https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-APIh](j)}(h2h]h2}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh)}(hjh]j)}(hjh]h@https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]hah ]h"]2ah$]h&]hahhuh1jhhhKhhhhhKubj)}(h1https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.htmlh](j)}(h3h]h3}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh)}(hj h]j)}(hj h]h1https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurij uh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]jah ]h"]3ah$]h&]j ahhuh1jhhhKhhhhhKubj)}(h.https://gcc.gnu.org/onlinedocs/gccint/IPA.htmlh](j)}(h4h]h4}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj8ubh)}(hj:h]j)}(hj:h]h.https://gcc.gnu.org/onlinedocs/gccint/IPA.html}(hjMhhhNhNubah}(h]h ]h"]h$]h&]refurij:uh1jhjJubah}(h]h ]h"]h$]h&]uh1hhhhKhj8ubeh}(h]j#ah ]h"]4ah$]h&]jahhuh1jhhhKhhhhhKubj)}(h.https://gcc.gnu.org/onlinedocs/gccint/RTL.htmlh](j)}(h5h]h5}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhubh)}(hjjh]j)}(hjjh]h.https://gcc.gnu.org/onlinedocs/gccint/RTL.html}(hj}hhhNhNubah}(h]h ]h"]h$]h&]refurijjuh1jhjzubah}(h]h ]h"]h$]h&]uh1hhhhKhjhubeh}(h]j7ah ]h"]5ah$]h&]j2ahhuh1jhhhKhhhhhKubj)}(hhttps://grsecurity.net/h](j)}(h6h]h6}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh)}(hjh]j)}(hjh]hhttps://grsecurity.net/}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]juah ]h"]6ah$]h&]jpahhuh1jhhhKhhhhhKubj)}(hhttps://pax.grsecurity.net/ h](j)}(h7h]h7}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh)}(hhttps://pax.grsecurity.net/h]j)}(hjh]hhttps://pax.grsecurity.net/}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhK hjubeh}(h]jah ]h"]7ah$]h&]jahhuh1jhhhK hhhhhKubeh}(h] introductionah ]h"] introductionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hPurposeh]hPurpose}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK$ubh)}(hXNGCC plugins are designed to provide a place to experiment with potential compiler features that are neither in GCC nor Clang upstream. Once their utility is proven, the goal is to upstream the feature into GCC (and Clang), and then to finally remove them from the kernel once the feature is available in all supported versions of GCC.h]hXNGCC plugins are designed to provide a place to experiment with potential compiler features that are neither in GCC nor Clang upstream. Once their utility is proven, the goal is to upstream the feature into GCC (and Clang), and then to finally remove them from the kernel once the feature is available in all supported versions of GCC.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK&hjhhubh)}(hySpecifically, new plugins should implement only features that have no upstream compiler support (in either GCC or Clang).h]hySpecifically, new plugins should implement only features that have no upstream compiler support (in either GCC or Clang).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK,hjhhubh)}(hWhen a feature exists in Clang but not GCC, effort should be made to bring the feature to upstream GCC (rather than just as a kernel-specific GCC plugin), so the entire ecosystem can benefit from it.h]hWhen a feature exists in Clang but not GCC, effort should be made to bring the feature to upstream GCC (rather than just as a kernel-specific GCC plugin), so the entire ecosystem can benefit from it.}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK/hjhhubh)}(hSimilarly, even if a feature provided by a GCC plugin does *not* exist in Clang, but the feature is proven to be useful, effort should be spent to upstream the feature to GCC (and Clang).h](h;Similarly, even if a feature provided by a GCC plugin does }(hj<hhhNhNubhemphasis)}(h*not*h]hnot}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1jDhj<ubh{ exist in Clang, but the feature is proven to be useful, effort should be spent to upstream the feature to GCC (and Clang).}(hj<hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK3hjhhubh)}(hAfter a feature is available in upstream GCC, the plugin will be made unbuildable for the corresponding GCC version (and later). Once all kernel-supported versions of GCC provide the feature, the plugin will be removed from the kernel.h]hAfter a feature is available in upstream GCC, the plugin will be made unbuildable for the corresponding GCC version (and later). Once all kernel-supported versions of GCC provide the feature, the plugin will be removed from the kernel.}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK7hjhhubeh}(h]purposeah ]h"]purposeah$]h&]uh1hhhhhhhhK$ubh)}(hhh](h)}(hFilesh]hFiles}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjthhhhhK>ubh)}(h**$(src)/scripts/gcc-plugins**h]hstrong)}(hjh]h$(src)/scripts/gcc-plugins}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhK@hjthhubh block_quote)}(h*This is the directory of the GCC plugins. h]h)}(h)This is the directory of the GCC plugins.h]h)This is the directory of the GCC plugins.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKBhjubah}(h]h ]h"]h$]h&]uh1jhhhKBhjthhubh)}(h+**$(src)/scripts/gcc-plugins/gcc-common.h**h]j)}(hjh]h'$(src)/scripts/gcc-plugins/gcc-common.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKDhjthhubj)}(hpThis is a compatibility header for GCC plugins. It should be always included instead of individual gcc headers. h]h)}(hoThis is a compatibility header for GCC plugins. It should be always included instead of individual gcc headers.h]hoThis is a compatibility header for GCC plugins. It should be always included instead of individual gcc headers.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKFhjubah}(h]h ]h"]h$]h&]uh1jhhhKFhjthhubh)}(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-simple_ipa-pass.h, $(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**h]j)}(hjh]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-simple_ipa-pass.h, $(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKIhjthhubj)}(hThese headers automatically generate the registration structures for GIMPLE, SIMPLE_IPA, IPA and RTL passes. They should be preferred to creating the structures by hand. h]h)}(hThese headers automatically generate the registration structures for GIMPLE, SIMPLE_IPA, IPA and RTL passes. They should be preferred to creating the structures by hand.h]hThese headers automatically generate the registration structures for GIMPLE, SIMPLE_IPA, IPA and RTL passes. They should be preferred to creating the structures by hand.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKNhjubah}(h]h ]h"]h$]h&]uh1jhhhKNhjthhubeh}(h]filesah ]h"]filesah$]h&]uh1hhhhhhhhK>ubh)}(hhh](h)}(hUsageh]hUsage}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKTubh)}(hZYou must install the gcc plugin headers for your gcc version, e.g., on Ubuntu for gcc-10::h]hYYou must install the gcc plugin headers for your gcc version, e.g., on Ubuntu for gcc-10:}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKVhjhhubh literal_block)}(h!apt-get install gcc-10-plugin-devh]h!apt-get install gcc-10-plugin-dev}hj?sbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1j=hhhKYhjhhubh)}(hOr on Fedora::h]h Or on Fedora:}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK[hjhhubj>)}(h)dnf install gcc-plugin-devel libmpc-develh]h)dnf install gcc-plugin-devel libmpc-devel}hj]sbah}(h]h ]h"]h$]h&]jMjNuh1j=hhhK]hjhhubh)}(h>Or on Fedora when using cross-compilers that include plugins::h]h=Or on Fedora when using cross-compilers that include plugins:}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK_hjhhubj>)}(hdnf install libmpc-develh]hdnf install libmpc-devel}hjysbah}(h]h ]h"]h$]h&]jMjNuh1j=hhhKahjhhubh)}(h^Enable the GCC plugin infrastructure and some plugin(s) you want to use in the kernel config::h]h]Enable the GCC plugin infrastructure and some plugin(s) you want to use in the kernel config:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKchjhhubj>)}(h;CONFIG_GCC_PLUGINS=y CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y ...h]h;CONFIG_GCC_PLUGINS=y CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y ...}hjsbah}(h]h ]h"]h$]h&]jMjNuh1j=hhhKfhjhhubh)}(hJRun gcc (native or cross-compiler) to ensure plugin headers are detected::h]hIRun gcc (native or cross-compiler) to ensure plugin headers are detected:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKjhjhhubj>)}(hdgcc -print-file-name=plugin CROSS_COMPILE=arm-linux-gnu- ${CROSS_COMPILE}gcc -print-file-name=pluginh]hdgcc -print-file-name=plugin CROSS_COMPILE=arm-linux-gnu- ${CROSS_COMPILE}gcc -print-file-name=plugin}hjsbah}(h]h ]h"]h$]h&]jMjNuh1j=hhhKlhjhhubh)}(h/The word "plugin" means they are not detected::h]h2The word “plugin” means they are not detected:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKohjhhubj>)}(hpluginh]hplugin}hjsbah}(h]h ]h"]h$]h&]jMjNuh1j=hhhKqhjhhubh)}(h%A full path means they are detected::h]h$A full path means they are detected:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKshjhhubj>)}(h*/usr/lib/gcc/x86_64-redhat-linux/12/pluginh]h*/usr/lib/gcc/x86_64-redhat-linux/12/plugin}hjsbah}(h]h ]h"]h$]h&]jMjNuh1j=hhhKuhjhhubh)}(h9To compile the minimum tool set including the plugin(s)::h]h8To compile the minimum tool set including the plugin(s):}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKwhjhhubj>)}(h make scriptsh]h make scripts}hjsbah}(h]h ]h"]h$]h&]jMjNuh1j=hhhKyhjhhubh)}(hcor just run the kernel make and compile the whole kernel with the cyclomatic complexity GCC plugin.h]hcor just run the kernel make and compile the whole kernel with the cyclomatic complexity GCC plugin.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK{hjhhubeh}(h]usageah ]h"]usageah$]h&]uh1hhhhhhhhKTubh)}(hhh](h)}(h4. How to add a new GCC pluginh]h4. How to add a new GCC plugin}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj)hhhhhKubh)}(hXThe 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.h]hXThe 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.}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj)hhubeh}(h]how-to-add-a-new-gcc-pluginah ]h"]4. how to add a new gcc pluginah$]h&]uh1hhhhhhhhKubeh}(h]gcc-plugin-infrastructureah ]h"]gcc plugin infrastructureah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj{error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}(1]ha2]ha3]ja4]ja5]j(a6]jfa7]jzaurefids}nameids}(jUjRjjjhjhj5jjej#jj7jjujjjqjnjjj&j#jMjJu nametypes}(jUjjjj5jejjjjqjj&jMuh}(jRhjhhhhhj jjjj2j(jpjfjjzhjhjjjj#j8j7jhjujjjjnjjjtj#jjJj)u footnote_refs}(j]haj]haj]jaj]jaj]j(aj]jfaj]jzau citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes](jjjj8jhjje citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}jKsRparse_messages]transform_messages] transformerN include_log] decorationNhhub.