[PATCH v2] docs: kconfig: Mention IS_REACHABLE as way for optional dependency

[PATCH v2] docs: kconfig: Mention IS_REACHABLE as way for optional dependency

[Krzysztof Kozlowski]

Several drivers express optional Kconfig dependency with FOO || !FOO,
but for many choices this is neither suitable (lack of stubs for !FOO
like in HWMON) nor really needed and driver can be built in even if FOO
is the module.  This is achieved with IS_REACHABLE, so move earlier
section from "imply" chapter to "Optional dependencies" and grow the
description.

Cc: Masahiro Yamada <masahiroy@kernel.org>
Cc: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

---

Changes in v2:
1. Replace FOO->BAR
2. Instead of referencing earlier "imply", move the code here and add
   more text (Masahiro)
---
 Documentation/kbuild/kconfig-language.rst | 35 ++++++++++++++---------
 1 file changed, 21 insertions(+), 14 deletions(-)

diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
index 2619fdf56e68..9a8dff58b3af 100644
--- a/Documentation/kbuild/kconfig-language.rst
+++ b/Documentation/kbuild/kconfig-language.rst
@@ -194,16 +194,6 @@ applicable everywhere (see syntax).
   ability to hook into a secondary subsystem while allowing the user to
   configure that subsystem out without also having to unset these drivers.
 
-  Note: If the combination of FOO=y and BAZ=m causes a link error,
-  you can guard the function call with IS_REACHABLE()::
-
-	foo_init()
-	{
-		if (IS_REACHABLE(CONFIG_BAZ))
-			baz_register(&foo);
-		...
-	}
-
   Note: If the feature provided by BAZ is highly desirable for FOO,
   FOO should imply not only BAZ, but also its dependency BAR::
 
@@ -580,15 +570,32 @@ Some drivers are able to optionally use a feature from another module
 or build cleanly with that module disabled, but cause a link failure
 when trying to use that loadable module from a built-in driver.
 
-The most common way to express this optional dependency in Kconfig logic
-uses the slightly counterintuitive::
+There are two ways to express this optional dependency:
 
-  config FOO
+1. If pre-processor can discard entire optional code or module BAR does not
+   provide !BAR stubs then call can be guarded with IS_REACHABLE()::
+
+	foo_init()
+	{
+		if (IS_REACHABLE(CONFIG_BAR))
+			bar_register(&foo);
+		...
+	}
+
+   Drawback: this might lead to run-time debugging, when looking why
+   bar_register() was not called.
+
+2. Otherwise (and module BAR must provide all !BAR stubs) use the slightly
+   counterintuitive Kconfig syntax::
+
+     config FOO
 	tristate "Support for foo hardware"
 	depends on BAR || !BAR
 
 This means that there is either a dependency on BAR that disallows
-the combination of FOO=y with BAR=m, or BAR is completely disabled.
+the combination of FOO=y with BAR=m, or BAR is completely disabled.  Unlike
+IS_REACHABLE(), this option favors configuration-time debugging.
+
 For a more formalized approach if there are multiple drivers that have
 the same dependency, a helper symbol can be used, like::
 
-- 
2.43.0

Re: [PATCH v2] docs: kconfig: Mention IS_REACHABLE as way for optional dependency

[Arnd Bergmann]

On Sat, Feb 15, 2025, at 14:17, Krzysztof Kozlowski wrote:
> Several drivers express optional Kconfig dependency with FOO || !FOO,
> but for many choices this is neither suitable (lack of stubs for !FOO
> like in HWMON) nor really needed and driver can be built in even if FOO
> is the module.  This is achieved with IS_REACHABLE, so move earlier
> section from "imply" chapter to "Optional dependencies" and grow the
> description.
>
> Cc: Masahiro Yamada <masahiroy@kernel.org>
> Cc: Arnd Bergmann <arnd@arndb.de>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

I think this needs to be more strongly worded to heavy discourage
the use of IS_REACHABLE(). In most cases, anyone trying this has
just given up on writing correct dependencies and works around
it in a user-hostile way.

> +1. If pre-processor can discard entire optional code or module BAR does not
> +   provide !BAR stubs then call can be guarded with IS_REACHABLE()::
> +
> +	foo_init()
> +	{
> +		if (IS_REACHABLE(CONFIG_BAR))
> +			bar_register(&foo);
> +		...
> +	}
> +
> +   Drawback: this might lead to run-time debugging, when looking why
> +   bar_register() was not called.

From this description, I wouldn't expect most readers to understand
what you mean with "run-time debugging". The behavior that users
are going to see is just a bug -- they turned on CONFIG_BAR=m because
they wanted to use BAR, but then it doesn't work.

      Arnd

Re: [PATCH v2] docs: kconfig: Mention IS_REACHABLE as way for optional dependency

[Krzysztof Kozlowski]

On 17/02/2025 08:51, Arnd Bergmann wrote:
> On Sat, Feb 15, 2025, at 14:17, Krzysztof Kozlowski wrote:
>> Several drivers express optional Kconfig dependency with FOO || !FOO,
>> but for many choices this is neither suitable (lack of stubs for !FOO
>> like in HWMON) nor really needed and driver can be built in even if FOO
>> is the module.  This is achieved with IS_REACHABLE, so move earlier
>> section from "imply" chapter to "Optional dependencies" and grow the
>> description.
>>
>> Cc: Masahiro Yamada <masahiroy@kernel.org>
>> Cc: Arnd Bergmann <arnd@arndb.de>
>> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> 
> I think this needs to be more strongly worded to heavy discourage
> the use of IS_REACHABLE(). In most cases, anyone trying this has
> just given up on writing correct dependencies and works around
> it in a user-hostile way.
> 

Ack

>> +1. If pre-processor can discard entire optional code or module BAR does not
>> +   provide !BAR stubs then call can be guarded with IS_REACHABLE()::
>> +
>> +	foo_init()
>> +	{
>> +		if (IS_REACHABLE(CONFIG_BAR))
>> +			bar_register(&foo);
>> +		...
>> +	}
>> +
>> +   Drawback: this might lead to run-time debugging, when looking why
>> +   bar_register() was not called.
> 
> From this description, I wouldn't expect most readers to understand
> what you mean with "run-time debugging". The behavior that users
> are going to see is just a bug -- they turned on CONFIG_BAR=m because
> they wanted to use BAR, but then it doesn't work.

Ack


Best regards,
Krzysztof