[PATCH 0/2] Documentation/kbuild: Document COMPILE_TEST and platform dependencies

[PATCH 0/2] Documentation/kbuild: Document COMPILE_TEST and platform dependencies

[Geert Uytterhoeven]

	Hi all,

This patch series documents best practices for COMPILE_TEST and
architecture/platform dependencies, like already in use in most
subsystems, to serve as a point of reference.

Thanks for your comments!

Geert Uytterhoeven (2):
  Documentation/kbuild: Document COMPILE_TEST dependencies
  Documentation/kbuild: Document platform dependency practises

 Documentation/kbuild/kconfig-language.rst | 35 +++++++++++++++++++++++
 1 file changed, 35 insertions(+)

-- 
2.25.1

Gr{oetje,eeting}s,

						Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
							    -- Linus Torvalds

[PATCH 0/2] Documentation/kbuild: Document COMPILE_TEST and platform dependencies

[Geert Uytterhoeven]

	Hi all,

This patch series documents best practices for COMPILE_TEST and
architecture/platform dependencies, like already in use in most
subsystems, to serve as a point of reference.

Thanks for your comments!

Geert Uytterhoeven (2):
  Documentation/kbuild: Document COMPILE_TEST dependencies
  Documentation/kbuild: Document platform dependency practises

 Documentation/kbuild/kconfig-language.rst | 35 +++++++++++++++++++++++
 1 file changed, 35 insertions(+)

-- 
2.25.1

Gr{oetje,eeting}s,

						Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
							    -- Linus Torvalds

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

[PATCH 1/2] Documentation/kbuild: Document COMPILE_TEST dependencies

[Geert Uytterhoeven]

Document best practises for using COMPILE_TEST dependencies.

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
---
 Documentation/kbuild/kconfig-language.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
index 1cf1aebdd6cdf8fa..2b746332d8aa6bce 100644
--- a/Documentation/kbuild/kconfig-language.rst
+++ b/Documentation/kbuild/kconfig-language.rst
@@ -553,6 +553,17 @@ with "depends on m".  E.g.::
 
 limits FOO to module (=m) or disabled (=n).
 
+Compile-testing
+~~~~~~~~~~~~~~~
+If a config symbol has a dependency, but the code controlled by the config
+symbol can still be compiled if the dependency is not met, it is encouraged to
+increase build coverage by adding an "|| COMPILE_TEST" clause to the
+dependency.  This is especially useful for drivers for more exotic hardware, as
+it allows continuous-integration systems to compile-test the code on a more
+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.
+
 Kconfig recursive dependency limitations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.25.1

[PATCH 1/2] Documentation/kbuild: Document COMPILE_TEST dependencies

[Geert Uytterhoeven]

Document best practises for using COMPILE_TEST dependencies.

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
---
 Documentation/kbuild/kconfig-language.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
index 1cf1aebdd6cdf8fa..2b746332d8aa6bce 100644
--- a/Documentation/kbuild/kconfig-language.rst
+++ b/Documentation/kbuild/kconfig-language.rst
@@ -553,6 +553,17 @@ with "depends on m".  E.g.::
 
 limits FOO to module (=m) or disabled (=n).
 
+Compile-testing
+~~~~~~~~~~~~~~~
+If a config symbol has a dependency, but the code controlled by the config
+symbol can still be compiled if the dependency is not met, it is encouraged to
+increase build coverage by adding an "|| COMPILE_TEST" clause to the
+dependency.  This is especially useful for drivers for more exotic hardware, as
+it allows continuous-integration systems to compile-test the code on a more
+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.
+
 Kconfig recursive dependency limitations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.25.1


_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

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

[Geert Uytterhoeven]

Document best practises for using architecture and platform dependencies.

Signed-off-by: Geert Uytterhoeven <geert+renesas@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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.25.1

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

[Geert Uytterhoeven]

Document best practises for using architecture and platform dependencies.

Signed-off-by: Geert Uytterhoeven <geert+renesas@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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.25.1


_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

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

[Arnd Bergmann]

On Tue, Dec 8, 2020 at 4:28 PM Geert Uytterhoeven
<geert+renesas@glider.be> wrote:
>
> Document best practises for using architecture and platform dependencies.
>
> Signed-off-by: Geert Uytterhoeven <geert+renesas@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

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

[Arnd Bergmann]

On Tue, Dec 8, 2020 at 4:28 PM Geert Uytterhoeven
<geert+renesas@glider.be> wrote:
>
> Document best practises for using architecture and platform dependencies.
>
> Signed-off-by: Geert Uytterhoeven <geert+renesas@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

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

Re: [PATCH 1/2] Documentation/kbuild: Document COMPILE_TEST dependencies

[Arnd Bergmann]

On Tue, Dec 8, 2020 at 4:28 PM Geert Uytterhoeven
<geert+renesas@glider.be> wrote:
>
> Document best practises for using COMPILE_TEST dependencies.
>
> Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>

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

Re: [PATCH 1/2] Documentation/kbuild: Document COMPILE_TEST dependencies

[Arnd Bergmann]

On Tue, Dec 8, 2020 at 4:28 PM Geert Uytterhoeven
<geert+renesas@glider.be> wrote:
>
> Document best practises for using COMPILE_TEST dependencies.
>
> Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>

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

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

Re: [PATCH 1/2] Documentation/kbuild: Document COMPILE_TEST dependencies

[Masahiro Yamada]

On Wed, Dec 9, 2020 at 12:29 AM Geert Uytterhoeven
<geert+renesas@glider.be> wrote:
>
> Document best practises for using COMPILE_TEST dependencies.
>
> Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
> ---
>  Documentation/kbuild/kconfig-language.rst | 11 +++++++++++
>  1 file changed, 11 insertions(+)
>
> diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
> index 1cf1aebdd6cdf8fa..2b746332d8aa6bce 100644
> --- a/Documentation/kbuild/kconfig-language.rst
> +++ b/Documentation/kbuild/kconfig-language.rst
> @@ -553,6 +553,17 @@ with "depends on m".  E.g.::


Both applied to linux-kbuild. Thanks.

I replaced the two-spaces between sentences
because the majority in this file adopts
one-space between sentences.
(I still see some inconsistencies, though.)






>
>  limits FOO to module (=m) or disabled (=n).
>
> +Compile-testing
> +~~~~~~~~~~~~~~~
> +If a config symbol has a dependency, but the code controlled by the config
> +symbol can still be compiled if the dependency is not met, it is encouraged to
> +increase build coverage by adding an "|| COMPILE_TEST" clause to the
> +dependency.  This is especially useful for drivers for more exotic hardware, as
> +it allows continuous-integration systems to compile-test the code on a more
> +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.
> +
>  Kconfig recursive dependency limitations
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> --
> 2.25.1
>


-- 
Best Regards
Masahiro Yamada

Re: [PATCH 1/2] Documentation/kbuild: Document COMPILE_TEST dependencies

[Masahiro Yamada]

On Wed, Dec 9, 2020 at 12:29 AM Geert Uytterhoeven
<geert+renesas@glider.be> wrote:
>
> Document best practises for using COMPILE_TEST dependencies.
>
> Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
> ---
>  Documentation/kbuild/kconfig-language.rst | 11 +++++++++++
>  1 file changed, 11 insertions(+)
>
> diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
> index 1cf1aebdd6cdf8fa..2b746332d8aa6bce 100644
> --- a/Documentation/kbuild/kconfig-language.rst
> +++ b/Documentation/kbuild/kconfig-language.rst
> @@ -553,6 +553,17 @@ with "depends on m".  E.g.::


Both applied to linux-kbuild. Thanks.

I replaced the two-spaces between sentences
because the majority in this file adopts
one-space between sentences.
(I still see some inconsistencies, though.)






>
>  limits FOO to module (=m) or disabled (=n).
>
> +Compile-testing
> +~~~~~~~~~~~~~~~
> +If a config symbol has a dependency, but the code controlled by the config
> +symbol can still be compiled if the dependency is not met, it is encouraged to
> +increase build coverage by adding an "|| COMPILE_TEST" clause to the
> +dependency.  This is especially useful for drivers for more exotic hardware, as
> +it allows continuous-integration systems to compile-test the code on a more
> +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.
> +
>  Kconfig recursive dependency limitations
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> --
> 2.25.1
>


-- 
Best Regards
Masahiro Yamada

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel