scripts/Kconfig.toolchain: Highlight cc-option differences between Kconfig and Kbuild

Performing cc-option checks in Kconfig instead of Kbuild can help speed
up incremental builds where the configuration does not change, as the
results of the probes can be easily cached. However, there are two
potential issues that folks need to consider when using cc-option in
Kconfig compared to Kbuild.

The first is that in Kbuild, cc-option additions are cumulative, so

  KBUILD_CFLAGS += $(call cc-option,-mfoo)
  KBUILD_CFLAGS += $(call cc-option,-mbar)

results in '-mbar' being tested with '-mfoo' if it was supported. In
Kconfig, '-mbar' would be tested without '-mfoo', which could change the
result if '-mbar' depends on '-mfoo' being present, so it would need to
test support with

  $(cc-option,-mbar -mfoo)

The second is that the Kconfig stage is where questions like "is the
target architecture 32-bit or 64-bit" or "is the target architecture big
or little endian" are answered, which very much matters for testing
compiler options. Toolchains may be configured for either option, so the
kernel needs to pass compiler flags like '-m32', '-m64',
'-mlittle-endian', and '-mbig-endian' to properly match a user's
configuration choices. Without these flags, '-mfoo' is tested against a
toolchain's configured default, resulting in an inconsistent answer to
whether the flag is actually supported for the requested configuration.
This could manifest as a build breakage from an unexpectedly included
but unsupported flag or missing functionality from an unexpected omitted
flag.

Add a big comment summarizing these two issues to help future travelers.

Link: https://patch.msgid.link/20261020-kconfig-fix-mfentry-check-v1-2-428258bc0fc0@kernel.org
Signed-off-by: Nathan Chancellor <nathan@kernel.org>

1 files changed, 19 insertions, 0 deletions

diff --git a/scripts/Kconfig.toolchain b/scripts/Kconfig.toolchain
index 01b49fa5d6be..a99d875489ee 100644
--- a/scripts/Kconfig.toolchain
+++ b/scripts/Kconfig.toolchain
@@ -144,6 +144,25 @@ config CC_HAS_ASSUME
 config CC_HAS_NO_PROFILE_FN_ATTR
 	def_bool $(success,echo '__attribute__((no_profile_instrument_function)) int x();' | $(CC) -x c - -c -o /dev/null -Werror)
 
+# Beware of two problems when using cc-option in Kconfig compared to Kbuild
+#
+# 1. cc-option in Kbuild tests the provided flags with all previously added
+#    CFLAGS, whereas cc-option in Kconfig only tests the provided flags with a
+#    small, constant set of additional flags.  If a flag (e.g., '-mfoo')
+#    depends on another (e.g, '-fbar') to function properly, the dependency
+#    must be included in the cc-option call (e.g, '-fbar -mfoo').
+#
+# 2. Bit and endianness flags ('-m32', '-m64', '-mbig-endian', and
+#    '-mlittle-endian') are not present in Kconfig cc-option checks because
+#    they may be included in KBUILD_CFLAGS / KBUILD_CPPFLAGS based on the
+#    finalized configuration result. This can result in inconsistent results
+#    when probing toolchains that support either option, as the toolchain's
+#    configured default tested in Kconfig may not support the tested flag but
+#    the post-configuration result in Kbuild would.
+#
+#    In general, prefer adding truly generic compiler flags to avoid this
+#    pitfall.
+
 config CC_OPT_ZERO_INIT_PADDING_BITS
 	def_string "$(cc-option-str,-fzero-init-padding-bits=all)"