Several drivers express optional Kconfig dependency with FOO || !FOO,
but for many choices this is not suitable: lack of stubs for !FOO
like in HWMON.  Describe the second, less favorable way of optional
dependency with IS_REACHABLE by moving the code from "imply" chapter to
"Optional dependencies".

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

---

Changes in v3:
1. Significant rewrite to mark IS_REACHABLE as less favorable.

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 | 29 ++++++++++++++---------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
index 2619fdf56e68..c8c20a34525e 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::
 
@@ -588,7 +578,9 @@ uses the slightly counterintuitive::
 	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.  The BAR
+module must provide all the stubs for !BAR case.
+
 For a more formalized approach if there are multiple drivers that have
 the same dependency, a helper symbol can be used, like::
 
@@ -599,6 +591,21 @@ the same dependency, a helper symbol can be used, like::
   config BAR_OPTIONAL
 	def_tristate BAR || !BAR
 
+Much less favorable way to express optional dependency is IS_REACHABLE() within
+the module code, useful for example when the module BAR does not provide
+!BAR stubs::
+
+	foo_init()
+	{
+		if (IS_REACHABLE(CONFIG_BAR))
+			bar_register(&foo);
+		...
+	}
+
+IS_REACHABLE() is generally discouraged, because the code will be silently
+discarded, when CONFIG_BAR=m and this code is built-in.  This is not what users
+usually expect when enabling BAR as module.
+
 Kconfig recursive dependency limitations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.43.0

On Mon, Feb 17, 2025 at 8:32 PM Krzysztof Kozlowski
<krzysztof.kozlowski@linaro.org> wrote:
>
> Several drivers express optional Kconfig dependency with FOO || !FOO,
> but for many choices this is not suitable: lack of stubs for !FOO
> like in HWMON.  Describe the second, less favorable way of optional
> dependency with IS_REACHABLE by moving the code from "imply" chapter to
> "Optional dependencies".
>
> Cc: Masahiro Yamada <masahiroy@kernel.org>
> Cc: Arnd Bergmann <arnd@arndb.de>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
>

Applied to linux-kbuild. Thanks.

For consistency with the existing documentation,
I replaced two spaces between sentences.


> ---
>
> Changes in v3:
> 1. Significant rewrite to mark IS_REACHABLE as less favorable.
>
> 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 | 29 ++++++++++++++---------
>  1 file changed, 18 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
> index 2619fdf56e68..c8c20a34525e 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::
>
> @@ -588,7 +578,9 @@ uses the slightly counterintuitive::
>         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.  The BAR
> +module must provide all the stubs for !BAR case.
> +
>  For a more formalized approach if there are multiple drivers that have
>  the same dependency, a helper symbol can be used, like::
>
> @@ -599,6 +591,21 @@ the same dependency, a helper symbol can be used, like::
>    config BAR_OPTIONAL
>         def_tristate BAR || !BAR
>
> +Much less favorable way to express optional dependency is IS_REACHABLE() within
> +the module code, useful for example when the module BAR does not provide
> +!BAR stubs::
> +
> +       foo_init()
> +       {
> +               if (IS_REACHABLE(CONFIG_BAR))
> +                       bar_register(&foo);
> +               ...
> +       }
> +
> +IS_REACHABLE() is generally discouraged, because the code will be silently
> +discarded, when CONFIG_BAR=m and this code is built-in.  This is not what users
> +usually expect when enabling BAR as module.
> +
>  Kconfig recursive dependency limitations
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> --
> 2.43.0
>


-- 
Best Regards
Masahiro Yamada

On Mon, Feb 17, 2025, at 12:31, Krzysztof Kozlowski wrote:
> Several drivers express optional Kconfig dependency with FOO || !FOO,
> but for many choices this is not suitable: lack of stubs for !FOO
> like in HWMON.  Describe the second, less favorable way of optional
> dependency with IS_REACHABLE by moving the code from "imply" chapter to
> "Optional dependencies".
>
> Cc: Masahiro Yamada <masahiroy@kernel.org>
> Cc: Arnd Bergmann <arnd@arndb.de>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

Acked-by: Arnd Bergmann <arnd@arndb.de>