kernel-dev: document patch handling for discovered BSP descriptions
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
@@ -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
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_URIas a ``file://*.scc`` fragment. That fragment is processed in both the configuration and patch phases, so any ``patch`` directives it (or thearch/bspdescriptions it includes) reference are applied to the kernel source. When the branch being built already contains those commits,do_patchfails -- 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_BSPopt-in for genuinely out-of-tree BSPs whose patches must still be applied.Signed-off-by Bruce Ashfield <[email protected]>---
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@@ -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
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_URIas a ``file://*.scc`` fragment. That fragment is processed in both the configuration and patch phases, so any ``patch`` directives it (or thearch/bspdescriptions it includes) reference are applied to the kernel source. When the branch being built already contains those commits,do_patchfails -- 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_BSPopt-in for genuinely out-of-tree BSPs whose patches must still be applied.Signed-off-by Bruce Ashfield <[email protected]>---
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.rstdocumentation/kernel-dev/advanced.rst form from your kernel append file:: · line 722
Quoted 8 lines
index
97cb66322..12473cbb3100644documentation/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 tothe
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`` filelisted
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``) isinstead
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 theconfiguration
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 fragmentreferences,
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 willfail 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 branchesand 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 anolder
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
-0commit. +Patch Application for BSP Descriptions +-------------------------------------- + +During the build, the kernel tools search the kernel Metadata for theBSP
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 thefirst
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 anyfiles 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) isdocumentation/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, sore-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) arealways
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 haveyour
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 (forexample
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 KMACHINEmyplatform`` 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 discoveredrather 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 ofeverything 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 (thebranch 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 tJust 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 alsoinjected
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
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 tJust 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
Antonin Godard
AppliedApplied, thanks!
[1/1] kernel-dev: document patch handling for discovered BSP descriptions
commit: 63b90ab4b818f888cd2e4ca36de5e5260f17e500