Commit 8bd51a2b authored by Kees Cook's avatar Kees Cook
Browse files

gcc-plugins: Explicitly document purpose and deprecation schedule 



GCC plugins should only exist when some compiler feature needs to be
proven but does not exist in either GCC nor Clang. For example, if a
desired feature is already in Clang, it should be added to GCC upstream.
Document this explicitly.

Additionally, mark the plugins with matching upstream GCC features as
removable past their respective GCC versions.

Cc: Masahiro Yamada <masahiroy@kernel.org>
Cc: Michal Marek <michal.lkml@markovi.net>
Cc: Nick Desaulniers <ndesaulniers@google.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: James Morris <jmorris@namei.org>
Cc: "Serge E. Hallyn" <serge@hallyn.com>
Cc: Nathan Chancellor <nathan@kernel.org>
Cc: linux-hardening@vger.kernel.org
Cc: linux-kbuild@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: linux-security-module@vger.kernel.org
Cc: llvm@lists.linux.dev
Signed-off-by: default avatarKees Cook <keescook@chromium.org>
Reviewed-by: default avatarNathan Chancellor <nathan@kernel.org>
Reviewed-by: default avatarMiguel Ojeda <ojeda@kernel.org>
Acked-by: default avatarNick Desaulniers <ndesaulniers@google.com>
Acked-by: default avatarArd Biesheuvel <ardb@kernel.org>
Link: https://lore.kernel.org/r/20211020173554.38122-2-keescook@chromium.org
parent 6eb4bd92

Documentation/kbuild/gcc-plugins.rst

+26 −0
Original line number Diff line number Diff line
@@ -32,6 +32,32 @@ This infrastructure was ported from grsecurity [6]_ and PaX [7]_. 
.. [7] https://pax.grsecurity.net/





Purpose

=======



GCC 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.



Specifically, new plugins should implement only features that have no

upstream compiler support (in either GCC or Clang).



When 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.



Similarly, 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).



After 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.





Files

=====

scripts/gcc-plugins/Kconfig

+2 −2
Original line number Diff line number Diff line
@@ -37,6 +37,8 @@ config GCC_PLUGIN_CYC_COMPLEXITY 


config GCC_PLUGIN_SANCOV

	bool

	# Plugin can be removed once the kernel only supports GCC 6+

	depends on !CC_HAS_SANCOV_TRACE_PC

	help

	  This plugin inserts a __sanitizer_cov_trace_pc() call at the start of

	  basic blocks. It supports all gcc versions with plugin support (from
@@ -83,8 +85,6 @@ config GCC_PLUGIN_RANDSTRUCT 
	  the existing seed and will be removed by a make mrproper or

	  make distclean.



	  Note that the implementation requires gcc 4.7 or newer.



	  This plugin was ported from grsecurity/PaX. More information at:

	   * https://grsecurity.net/

	   * https://pax.grsecurity.net/

security/Kconfig.hardening

+6 −3
Original line number Diff line number Diff line
@@ -56,7 +56,8 @@ choice 


	config GCC_PLUGIN_STRUCTLEAK_USER

		bool "zero-init structs marked for userspace (weak)"

		depends on GCC_PLUGINS

		# Plugin can be removed once the kernel only supports GCC 12+

		depends on GCC_PLUGINS && !CC_HAS_AUTO_VAR_INIT_ZERO

		select GCC_PLUGIN_STRUCTLEAK

		help

		  Zero-initialize any structures on the stack containing
@@ -67,7 +68,8 @@ choice 


	config GCC_PLUGIN_STRUCTLEAK_BYREF

		bool "zero-init structs passed by reference (strong)"

		depends on GCC_PLUGINS

		# Plugin can be removed once the kernel only supports GCC 12+

		depends on GCC_PLUGINS && !CC_HAS_AUTO_VAR_INIT_ZERO

		depends on !(KASAN && KASAN_STACK)

		select GCC_PLUGIN_STRUCTLEAK

		help
@@ -85,7 +87,8 @@ choice 


	config GCC_PLUGIN_STRUCTLEAK_BYREF_ALL

		bool "zero-init everything passed by reference (very strong)"

		depends on GCC_PLUGINS

		# Plugin can be removed once the kernel only supports GCC 12+

		depends on GCC_PLUGINS && !CC_HAS_AUTO_VAR_INIT_ZERO

		depends on !(KASAN && KASAN_STACK)

		select GCC_PLUGIN_STRUCTLEAK

		help