Re: [docs][PATCH] kernel-dev: document patch handling for discovered BSP descriptions

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi,

On Fri Jun 5, 2026 at 1:58 PM CEST, Bruce Ashfield via lists.yoctoproject.org wrote:
> From: Bruce Ashfield <bruce.ashfield@gmail.com>
>
> Users adding a recipe-space BSP commonly list their machine ``.scc``
> directly on SRC_URI as a ``file://*.scc`` fragment. That fragment is
> processed in both the configuration and patch phases, so any ``patch``
> directives it (or the arch/bsp descriptions it includes) reference are
> applied to the kernel source. When the branch being built already
> contains those commits, do_patch fails -- a confusing result with no
> documentation explaining it.
>
> The kernel tools only inhibit patch application for the *discovered*
> BSP description (the one located via KMACHINE/LINUX_KERNEL_TYPE), on the
> assumption that its commits are already in the branch's history. Nothing
> in the manual states this, nor that delivering the description as a
> type=kmeta directory is what makes it discoverable rather than a plain
> fragment.
>
> Document the discovered-BSP patch-skip behavior, show the KMACHINE +
> type=kmeta form required to trigger it, and describe the
> KMETA_EXTERNAL_BSP opt-in for genuinely out-of-tree BSPs whose patches
> must still be applied.
>
> Signed-off-by: Bruce Ashfield <bruce.ashfield@gmail.com>
> ---
>
> Hi all,
>
> This is my first direct patch to the docuentation after all these
> years.
>
> So I'm sure I've got something wrong!
>
> Cheers,
>
> Bruce
>
>  documentation/kernel-dev/advanced.rst | 58 +++++++++++++++++++++++++++
>  1 file changed, 58 insertions(+)
>
> diff --git a/documentation/kernel-dev/advanced.rst b/documentation/kernel-dev/advanced.rst
> index 97cb66322..12473cbb3 100644
> --- a/documentation/kernel-dev/advanced.rst
> +++ b/documentation/kernel-dev/advanced.rst
> @@ -719,6 +719,18 @@ form from your kernel append file::
>         file://myplatform;type=kmeta;destsuffix=myplatform \
>         "
>  
> +The ``type=kmeta`` attribute is significant: it adds the directory to the
> +kernel Metadata that the tools search to *discover* the BSP description
> +matching :term:`KMACHINE` and ``LINUX_KERNEL_TYPE``. A ``.scc`` file listed
> +directly on :term:`SRC_URI` (for example ``file://myplatform.scc``) is instead
> +treated as a configuration fragment and is processed in both the configuration
> +and the patch phases. Any ``patch`` directives that such a fragment references,
> +or that are reached through files it ``include``\ s (such as an ``arch/`` or
> +``bsp/`` description), are then applied to the kernel source and will fail if
> +those patches are already present in the branch. See the
> +":ref:`kernel-dev/advanced:patch application for bsp descriptions`" section for
> +the reasoning behind this.
> +
>  Metadata Outside the Recipe-Space
>  ---------------------------------
>  
> @@ -750,6 +762,52 @@ wish to use. Changing the data in these branches and not updating the
>  :term:`SRCREV` statements to match will cause the build to fetch an older
>  commit.
>  
> +Patch Application for BSP Descriptions
> +--------------------------------------
> +
> +During the build, the kernel tools search the kernel Metadata for the BSP
> +description that most closely matches the :term:`KMACHINE` and
> +``LINUX_KERNEL_TYPE`` values passed in from the recipe, and use the first
> +description they find that matches both. This is referred to as the
> +*discovered* BSP description.
> +
> +For a discovered BSP description, the tools deliberately do **not** apply the
> +``patch`` directives reachable from it, either directly or through any files it
> +``include``\ s. The kernel source branch you are building (:term:`KBRANCH`) is
> +assumed to already contain those commits as part of its history, so re-applying
> +them would fail. Configuration fragments (``kconf`` directives) are always
> +applied. In other words, a discovered BSP contributes *configuration*, not

s/discovered BSP/discovered BSP description/ ?

> +*patches*.
> +
> +This is why a recipe-space BSP description must be delivered as a
> +``type=kmeta`` directory rather than as an individual ``file://*.scc`` entry on
> +:term:`SRC_URI` (see the
> +":ref:`kernel-dev/advanced:recipe-space metadata`" section). To have your
> +description discovered, place it in a ``type=kmeta`` directory and set
> +:term:`KMACHINE` so the tools locate it::
> +
> +   KMACHINE:myplatform ?= "myplatform"
> +
> +   SRC_URI:append:myplatform = " \
> +       file://myplatform;type=kmeta;destsuffix=myplatform \
> +       "
> +
> +Here, the ``myplatform`` directory contains the BSP description (for example
> +``myplatform-standard.scc``, beginning with ``define KMACHINE myplatform`` and
> +``define KTYPE standard``). Because the description is discovered rather than
> +supplied as a fragment, its ``patch`` directives, and those of everything it
> +``include``\ s, are inhibited, while its configuration is still applied.
> +
> +If your BSP genuinely lives outside the kernel source history (the branch you
> +build does **not** already contain the BSP commits, and the patches *must* be
> +applied), the BSP description can opt back in to patch application by adding the
> +following directive to the description itself::
> +
> +   define KMETA_EXTERNAL_BSP t

Just making sure, but you meant to add that "t", right? What does it stand for?
Maybe you could quickly explain it below.

> +
> +With that directive present, the discovered BSP description is also injected
> +into the patch phase and its ``patch`` directives are applied.
> +
>  Organizing Your Source
>  ======================
>  

Otherwise the explanation is clear to me although I don't have much experience
with advanced kernel metadata.

Thanks,
Antonin