[PATCH 2/2] Documentation/kbuild: Document platform dependency practises

[Arnd Bergmann]

On Tue, Dec 8, 2020 at 4:28 PM Geert Uytterhoeven
<geert+renesas at glider.be> wrote:
>
> Document best practises for using architecture and platform dependencies.
>
> Signed-off-by: Geert Uytterhoeven <geert+renesas at glider.be>
> ---
>  Documentation/kbuild/kconfig-language.rst | 24 +++++++++++++++++++++++
>  1 file changed, 24 insertions(+)
>
> diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
> index 2b746332d8aa6bce..87e9bbe14a21ce83 100644
> --- a/Documentation/kbuild/kconfig-language.rst
> +++ b/Documentation/kbuild/kconfig-language.rst
> @@ -564,6 +564,30 @@ common system, and detect bugs that way.
>  Note that compile-tested code should avoid crashing when run on a system where
>  the dependency is not met.
>
> +Architecture and platform dependencies
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Due to the presence of stubs, most drivers can now be compiled on most
> +architectures.  However, this does not mean it makes sense to have all drivers
> +available everywhere, as the actual hardware may only exist on specific
> +architectures and platforms.  This is especially true for on-SoC IP cores,
> +which may be limited to a specific vendor or SoC family.
> +
> +To prevent asking the user about drivers that cannot be used on the system(s)
> +the user is compiling a kernel for, and if it makes sense, config symbols
> +controlling the compilation of a driver should contain proper dependencies,
> +limiting the visibility of the symbol to (a superset of) the platform(s) the
> +driver can be used on.  The dependency can be an architecture (e.g. ARM) or
> +platform (e.g. ARCH_OMAP4) dependency.  This makes life simpler not only for
> +distro config owners, but also for every single developer or user who
> +configures a kernel.
> +
> +Such a dependency can be relaxed by combining it with the compile-testing rule
> +above, leading to:
> +
> +  config FOO
> +       bool "Support for foo hardware"
> +       depends on ARCH_FOO_VENDOR || COMPILE_TEST
> +
>  Kconfig recursive dependency limitations
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The addition seems useful, but I wonder if we should mention more
patterns here.:

- Some drivers are turned on implicitly for a platform, like

 config FOO
       bool "Support for foo hardware"
       depends on ARCH_FOO_VENDOR || COMPILE_TEST
       default ARCH_FOO_VENDOR

- some drivers can use a feature that may be a loadable module
  itself, or can compile if that feature is disabled, but the driver
  itself must not be built-in if the feature is in a loadable module, e.g.

config FOO
        tristate "Foo device"
        depends on HWSPINLOCK || (COMPILE_TEST && !HWSPINLOCK)

       Arnd