kernel-dev: document patch handling for discovered BSP descriptions

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(+)

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

On Fri, Jun 5, 2026 at 10:18 AM Antonin Godard <antonin.godard@bootlin.com>
wrote:

> 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.
>


It's just a non zero value. We have to define it to something, what it is,
doesn't matter.

Bruce



>
> > +
> > +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
>