Skip to contentSkip to conversation

kernel-dev: document patch handling for discovered BSP descriptions

PATCH Applied [email protected] 2 participants 5 messages Jun 5 – Jul 3

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 kernel-dev: document patch handling for discovered BSP descriptions

From: Bruce Ashfield <[email protected]>

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.

---

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(+)
documentation/kernel-dev/advanced.rst +58 -0
index 97cb66322..12473cbb3 100644
@@ -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
+*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
+
+With that directive present, the discovered BSP description is also injected
+into the patch phase and its ``patch`` directives are applied.
+
 Organizing Your Source
 ======================
 
Signature · 1 line
2.43.0
#1 lore raw

Hi,

Quoted 71 lines · Bruce Ashfield via lists.yoctoproject.org

From: Bruce Ashfield <[email protected]>

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.

---

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(+)
documentation/kernel-dev/advanced.rst +17 -0
index 97cb66322..12473cbb3 100644
@@ -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

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches and not updating the · line 779

Quoted 10 lines
documentation/kernel-dev/advanced.rst +10 -0
+``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/ ?

Quoted 17 lines
documentation/kernel-dev/advanced.rst +17 -0
+*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

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches and not updating the · line 806

Quoted 10 lines
documentation/kernel-dev/advanced.rst +10 -0
+``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.

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches and not updating the · line 813

Quoted 7 lines
documentation/kernel-dev/advanced.rst +4 -0
+
+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

#2 lore raw
Quoted 139 lines · Antonin Godard

Hi,

Quoted 32 lines · Bruce Ashfield via lists.yoctoproject.org

From: Bruce Ashfield <[email protected]>

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.

---

Hi all,

This is my first direct patch to the docuentation after all these years.

So I'm sure I've got something wrong!

Review

Quoted 8 lines

Cheers,

Bruce

 documentation/kernel-dev/advanced.rst | 58 +++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
(quoted diff) +0 -0

b/documentation/kernel-dev/advanced.rst

documentation/kernel-dev/advanced.rst form from your kernel append file:: · line 722

Quoted 8 lines

index 97cb66322..12473cbb3 100644

documentation/kernel-dev/advanced.rst +1 -0
@@ -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

documentation/kernel-dev/advanced.rst form from your kernel append file:: · line 724

Quoted 2 lines
documentation/kernel-dev/advanced.rst +2 -0
+kernel Metadata that the tools search to *discover* the BSP description
+matching :term:`KMACHINE` and ``LINUX_KERNEL_TYPE``. A ``.scc`` file

listed

documentation/kernel-dev/advanced.rst form from your kernel append file:: · line 725

Quoted 1 line
documentation/kernel-dev/advanced.rst +1 -0
+directly on :term:`SRC_URI` (for example ``file://myplatform.scc``) is

instead

documentation/kernel-dev/advanced.rst form from your kernel append file:: · line 726

Quoted 1 line
documentation/kernel-dev/advanced.rst +1 -0
+treated as a configuration fragment and is processed in both the

configuration

documentation/kernel-dev/advanced.rst form from your kernel append file:: · line 727

Quoted 1 line
documentation/kernel-dev/advanced.rst +1 -0
+and the patch phases. Any ``patch`` directives that such a fragment

references,

documentation/kernel-dev/advanced.rst form from your kernel append file:: · line 728

Quoted 1 line
documentation/kernel-dev/advanced.rst +1 -0
+or that are reached through files it ``include``\ s (such as an

``arch/`` or

documentation/kernel-dev/advanced.rst form from your kernel append file:: · line 729

Quoted 1 line
documentation/kernel-dev/advanced.rst +1 -0
+``bsp/`` description), are then applied to the kernel source and will

fail if

documentation/kernel-dev/advanced.rst form from your kernel append file:: · line 731

Quoted 2 lines
documentation/kernel-dev/advanced.rst +2 -0
+those patches are already present in the branch. See the
+":ref:`kernel-dev/advanced:patch application for bsp descriptions`"

section for

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches

Quoted 6 lines
documentation/kernel-dev/advanced.rst +2 -0
+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

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches · line 762

Quoted 1 line
documentation/kernel-dev/advanced.rst +0 -0
 :term:`SRCREV` statements to match will cause the build to fetch an

older

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches and not updating the

Quoted 6 lines
documentation/kernel-dev/advanced.rst +4 -0
 commit.
 
+Patch Application for BSP Descriptions
+--------------------------------------
+
+During the build, the kernel tools search the kernel Metadata for the

BSP

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches · line 770

Quoted 2 lines
documentation/kernel-dev/advanced.rst +2 -0
+description that most closely matches the :term:`KMACHINE` and
+``LINUX_KERNEL_TYPE`` values passed in from the recipe, and use the

first

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches and not updating the

Quoted 4 lines
documentation/kernel-dev/advanced.rst +4 -0
+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

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches · line 775

Quoted 1 line
documentation/kernel-dev/advanced.rst +1 -0
+``patch`` directives reachable from it, either directly or through any

files it

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches · line 776

Quoted 1 line
documentation/kernel-dev/advanced.rst +1 -0
+``include``\ s. The kernel source branch you are building

(:term:KBRANCH) is

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches · line 777

Quoted 1 line
documentation/kernel-dev/advanced.rst +1 -0
+assumed to already contain those commits as part of its history, so

re-applying

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches · line 778

Quoted 1 line
documentation/kernel-dev/advanced.rst +1 -0
+them would fail. Configuration fragments (``kconf`` directives) are

always

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches · line 779

Quoted 1 line
documentation/kernel-dev/advanced.rst +1 -0
+applied. In other words, a discovered BSP contributes *configuration*,

not

s/discovered BSP/discovered BSP description/ ?

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches and not updating the

Quoted 4 lines
documentation/kernel-dev/advanced.rst +4 -0
+*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

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches · line 785

Quoted 2 lines
documentation/kernel-dev/advanced.rst +2 -0
+:term:`SRC_URI` (see the
+":ref:`kernel-dev/advanced:recipe-space metadata`" section). To have

your

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches and not updating the

Quoted 10 lines
documentation/kernel-dev/advanced.rst +10 -0
+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

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches · line 796

Quoted 1 line
documentation/kernel-dev/advanced.rst +1 -0
+``myplatform-standard.scc``, beginning with ``define KMACHINE

myplatform`` and

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches · line 797

Quoted 1 line
documentation/kernel-dev/advanced.rst +1 -0
+``define KTYPE standard``). Because the description is discovered

rather than

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches · line 798

Quoted 1 line
documentation/kernel-dev/advanced.rst +1 -0
+supplied as a fragment, its ``patch`` directives, and those of

everything it

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches and not updating the

Quoted 3 lines
documentation/kernel-dev/advanced.rst +3 -0
+``include``\ s, are inhibited, while its configuration is still applied.
+
+If your BSP genuinely lives outside the kernel source history (the

branch you

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches · line 802

Quoted 1 line
documentation/kernel-dev/advanced.rst +1 -0
+build does **not** already contain the BSP commits, and the patches

*must* be

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches · line 803

Quoted 1 line
documentation/kernel-dev/advanced.rst +1 -0
+applied), the BSP description can opt back in to patch application by
Quoted 9 lines

adding the

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches and not updating the · line 806

Quoted 3 lines
documentation/kernel-dev/advanced.rst +3 -0
+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

Quoted 17 lines

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches · line 808

Quoted 3 lines
documentation/kernel-dev/advanced.rst +2 -0
+
+With that directive present, the discovered BSP description is also

injected

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches and not updating the · line 813

Quoted 5 lines
documentation/kernel-dev/advanced.rst +2 -0
+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

Signature · 3 lines
- Thou shalt not follow the NULL pointer, for chaos and madness await thee
at its end
- "Use the force Harry" - Gandalf, Star Trek II
#3 lore raw

On Fri Jun 5, 2026 at 6:52 PM CEST, Bruce Ashfield wrote:
[...]

Quoted 12 lines
Quoted 10 lines
Quoted 1 line

+applied), the BSP description can opt back in to patch application by

adding the

documentation/kernel-dev/advanced.rst wish to use. Changing the data in these branches and not updating the · line 806

Quoted 3 lines
documentation/kernel-dev/advanced.rst +3 -0
+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.

Quoted 2 lines

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

Even if it doesn't matter, I think setting it to "1" in the docs or something similar is less confusing than "t".

Antonin