Andrew Geissler | f034379 | 2020-11-18 10:42:21 -0600 | [diff] [blame] | 1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2 | |
| 3 | ******************************************************* |
| 4 | Working with Advanced Metadata (``yocto-kernel-cache``) |
| 5 | ******************************************************* |
| 6 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 7 | Overview |
| 8 | ======== |
| 9 | |
| 10 | In addition to supporting configuration fragments and patches, the Yocto |
| 11 | Project kernel tools also support rich |
| 12 | :term:`Metadata` that you can use to define |
| 13 | complex policies and Board Support Package (BSP) support. The purpose of |
| 14 | the Metadata and the tools that manage it is to help you manage the |
| 15 | complexity of the configuration and sources used to support multiple |
| 16 | BSPs and Linux kernel types. |
| 17 | |
| 18 | Kernel Metadata exists in many places. One area in the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 19 | :ref:`overview-manual/development-environment:yocto project source repositories` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 20 | is the ``yocto-kernel-cache`` Git repository. You can find this repository |
| 21 | grouped under the "Yocto Linux Kernel" heading in the |
| 22 | :yocto_git:`Yocto Project Source Repositories <>`. |
| 23 | |
William A. Kennington III | ac69b48 | 2021-06-02 12:28:27 -0700 | [diff] [blame] | 24 | Kernel development tools ("kern-tools") are also available in the Yocto Project |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 25 | Source Repositories under the "Yocto Linux Kernel" heading in the |
| 26 | ``yocto-kernel-tools`` Git repository. The recipe that builds these |
| 27 | tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in |
| 28 | the :term:`Source Directory` (e.g. |
| 29 | ``poky``). |
| 30 | |
| 31 | Using Kernel Metadata in a Recipe |
| 32 | ================================= |
| 33 | |
| 34 | As mentioned in the introduction, the Yocto Project contains kernel |
| 35 | Metadata, which is located in the ``yocto-kernel-cache`` Git repository. |
| 36 | This Metadata defines Board Support Packages (BSPs) that correspond to |
| 37 | definitions in linux-yocto recipes for corresponding BSPs. A BSP |
| 38 | consists of an aggregation of kernel policy and enabled |
| 39 | hardware-specific features. The BSP can be influenced from within the |
| 40 | linux-yocto recipe. |
| 41 | |
| 42 | .. note:: |
| 43 | |
| 44 | A Linux kernel recipe that contains kernel Metadata (e.g. inherits |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 45 | from the ``linux-yocto.inc`` file) is said to be a "linux-yocto style" recipe. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 46 | |
| 47 | Every linux-yocto style recipe must define the |
| 48 | :term:`KMACHINE` variable. This |
| 49 | variable is typically set to the same value as the ``MACHINE`` variable, |
| 50 | which is used by :term:`BitBake`. |
| 51 | However, in some cases, the variable might instead refer to the |
| 52 | underlying platform of the ``MACHINE``. |
| 53 | |
| 54 | Multiple BSPs can reuse the same ``KMACHINE`` name if they are built |
| 55 | using the same BSP description. Multiple Corei7-based BSPs could share |
| 56 | the same "intel-corei7-64" value for ``KMACHINE``. It is important to |
| 57 | realize that ``KMACHINE`` is just for kernel mapping, while ``MACHINE`` |
| 58 | is the machine type within a BSP Layer. Even with this distinction, |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 59 | however, these two variables can hold the same value. See the |
| 60 | ":ref:`kernel-dev/advanced:bsp descriptions`" section for more information. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 61 | |
| 62 | Every linux-yocto style recipe must also indicate the Linux kernel |
| 63 | source repository branch used to build the Linux kernel. The |
| 64 | :term:`KBRANCH` variable must be set |
| 65 | to indicate the branch. |
| 66 | |
| 67 | .. note:: |
| 68 | |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 69 | You can use the ``KBRANCH`` value to define an alternate branch typically |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 70 | with a machine override as shown here from the ``meta-yocto-bsp`` layer:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 71 | |
| 72 | KBRANCH_edgerouter = "standard/edgerouter" |
| 73 | |
| 74 | |
| 75 | The linux-yocto style recipes can optionally define the following |
| 76 | variables: |
| 77 | |
| 78 | - :term:`KERNEL_FEATURES` |
| 79 | |
| 80 | - :term:`LINUX_KERNEL_TYPE` |
| 81 | |
| 82 | :term:`LINUX_KERNEL_TYPE` |
| 83 | defines the kernel type to be used in assembling the configuration. If |
| 84 | you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to "standard". |
| 85 | Together with ``KMACHINE``, ``LINUX_KERNEL_TYPE`` defines the search |
| 86 | arguments used by the kernel tools to find the appropriate description |
| 87 | within the kernel Metadata with which to build out the sources and |
| 88 | configuration. The linux-yocto recipes define "standard", "tiny", and |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 89 | "preempt-rt" kernel types. See the ":ref:`kernel-dev/advanced:kernel types`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 90 | section for more information on kernel types. |
| 91 | |
| 92 | During the build, the kern-tools search for the BSP description file |
| 93 | that most closely matches the ``KMACHINE`` and ``LINUX_KERNEL_TYPE`` |
| 94 | variables passed in from the recipe. The tools use the first BSP |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 95 | description they find that matches both variables. If the tools cannot find |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 96 | a match, they issue a warning. |
| 97 | |
| 98 | The tools first search for the ``KMACHINE`` and then for the |
| 99 | ``LINUX_KERNEL_TYPE``. If the tools cannot find a partial match, they |
| 100 | will use the sources from the ``KBRANCH`` and any configuration |
| 101 | specified in the :term:`SRC_URI`. |
| 102 | |
| 103 | You can use the |
| 104 | :term:`KERNEL_FEATURES` |
| 105 | variable to include features (configuration fragments, patches, or both) |
| 106 | that are not already included by the ``KMACHINE`` and |
| 107 | ``LINUX_KERNEL_TYPE`` variable combination. For example, to include a |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 108 | feature specified as "features/netfilter/netfilter.scc", specify:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 109 | |
| 110 | KERNEL_FEATURES += "features/netfilter/netfilter.scc" |
| 111 | |
| 112 | To include a |
| 113 | feature called "cfg/sound.scc" just for the ``qemux86`` machine, |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 114 | specify:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 115 | |
| 116 | KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc" |
| 117 | |
| 118 | The value of |
| 119 | the entries in ``KERNEL_FEATURES`` are dependent on their location |
| 120 | within the kernel Metadata itself. The examples here are taken from the |
| 121 | ``yocto-kernel-cache`` repository. Each branch of this repository |
| 122 | contains "features" and "cfg" subdirectories at the top-level. For more |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 123 | information, see the ":ref:`kernel-dev/advanced:kernel metadata syntax`" |
| 124 | section. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 125 | |
| 126 | Kernel Metadata Syntax |
| 127 | ====================== |
| 128 | |
| 129 | The kernel Metadata consists of three primary types of files: ``scc`` |
| 130 | [1]_ description files, configuration fragments, and patches. The |
| 131 | ``scc`` files define variables and include or otherwise reference any of |
| 132 | the three file types. The description files are used to aggregate all |
| 133 | types of kernel Metadata into what ultimately describes the sources and |
| 134 | the configuration required to build a Linux kernel tailored to a |
| 135 | specific machine. |
| 136 | |
| 137 | The ``scc`` description files are used to define two fundamental types |
| 138 | of kernel Metadata: |
| 139 | |
| 140 | - Features |
| 141 | |
| 142 | - Board Support Packages (BSPs) |
| 143 | |
| 144 | Features aggregate sources in the form of patches and configuration |
| 145 | fragments into a modular reusable unit. You can use features to |
| 146 | implement conceptually separate kernel Metadata descriptions such as |
| 147 | pure configuration fragments, simple patches, complex features, and |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 148 | kernel types. :ref:`kernel-dev/advanced:kernel types` define general kernel |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 149 | features and policy to be reused in the BSPs. |
| 150 | |
| 151 | BSPs define hardware-specific features and aggregate them with kernel |
| 152 | types to form the final description of what will be assembled and built. |
| 153 | |
| 154 | While the kernel Metadata syntax does not enforce any logical separation |
| 155 | of configuration fragments, patches, features or kernel types, best |
| 156 | practices dictate a logical separation of these types of Metadata. The |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 157 | following Metadata file hierarchy is recommended:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 158 | |
| 159 | base/ |
| 160 | bsp/ |
| 161 | cfg/ |
| 162 | features/ |
| 163 | ktypes/ |
| 164 | patches/ |
| 165 | |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 166 | The ``bsp`` directory contains the :ref:`kernel-dev/advanced:bsp descriptions`. |
| 167 | The remaining directories all contain "features". Separating ``bsp`` from the |
| 168 | rest of the structure aids conceptualizing intended usage. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 169 | |
| 170 | Use these guidelines to help place your ``scc`` description files within |
| 171 | the structure: |
| 172 | |
| 173 | - If your file contains only configuration fragments, place the file in |
| 174 | the ``cfg`` directory. |
| 175 | |
| 176 | - If your file contains only source-code fixes, place the file in the |
| 177 | ``patches`` directory. |
| 178 | |
| 179 | - If your file encapsulates a major feature, often combining sources |
| 180 | and configurations, place the file in ``features`` directory. |
| 181 | |
| 182 | - If your file aggregates non-hardware configuration and patches in |
| 183 | order to define a base kernel policy or major kernel type to be |
| 184 | reused across multiple BSPs, place the file in ``ktypes`` directory. |
| 185 | |
| 186 | These distinctions can easily become blurred - especially as out-of-tree |
| 187 | features slowly merge upstream over time. Also, remember that how the |
| 188 | description files are placed is a purely logical organization and has no |
| 189 | impact on the functionality of the kernel Metadata. There is no impact |
| 190 | because all of ``cfg``, ``features``, ``patches``, and ``ktypes``, |
| 191 | contain "features" as far as the kernel tools are concerned. |
| 192 | |
| 193 | Paths used in kernel Metadata files are relative to base, which is |
| 194 | either |
| 195 | :term:`FILESEXTRAPATHS` if |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 196 | you are creating Metadata in |
| 197 | :ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`, |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 198 | or the top level of |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 199 | :yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/>` |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 200 | if you are creating |
| 201 | :ref:`kernel-dev/advanced:metadata outside the recipe-space`. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 202 | |
| 203 | .. [1] |
| 204 | ``scc`` stands for Series Configuration Control, but the naming has |
| 205 | less significance in the current implementation of the tooling than |
| 206 | it had in the past. Consider ``scc`` files to be description files. |
| 207 | |
| 208 | Configuration |
| 209 | ------------- |
| 210 | |
| 211 | The simplest unit of kernel Metadata is the configuration-only feature. |
| 212 | This feature consists of one or more Linux kernel configuration |
| 213 | parameters in a configuration fragment file (``.cfg``) and a ``.scc`` |
| 214 | file that describes the fragment. |
| 215 | |
| 216 | As an example, consider the Symmetric Multi-Processing (SMP) fragment |
| 217 | used with the ``linux-yocto-4.12`` kernel as defined outside of the |
| 218 | recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of |
| 219 | two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the |
| 220 | ``cfg`` directory of the ``yocto-4.12`` branch in the |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 221 | ``yocto-kernel-cache`` Git repository:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 222 | |
| 223 | cfg/smp.scc: |
| 224 | define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds" |
| 225 | define KFEATURE_COMPATIBILITY all |
| 226 | |
| 227 | kconf hardware smp.cfg |
| 228 | |
| 229 | cfg/smp.cfg: |
| 230 | CONFIG_SMP=y |
| 231 | CONFIG_SCHED_SMT=y |
| 232 | # Increase default NR_CPUS from 8 to 64 so that platform with |
| 233 | # more than 8 processors can be all activated at boot time |
| 234 | CONFIG_NR_CPUS=64 |
| 235 | # The following is needed when setting NR_CPUS to something |
| 236 | # greater than 8 on x86 architectures, it should be automatically |
| 237 | # disregarded by Kconfig when using a different arch |
| 238 | CONFIG_X86_BIGSMP=y |
| 239 | |
| 240 | You can find general information on configuration |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 241 | fragment files in the ":ref:`kernel-dev/common:creating configuration fragments`" section. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 242 | |
| 243 | Within the ``smp.scc`` file, the |
| 244 | :term:`KFEATURE_DESCRIPTION` |
| 245 | statement provides a short description of the fragment. Higher level |
| 246 | kernel tools use this description. |
| 247 | |
| 248 | Also within the ``smp.scc`` file, the ``kconf`` command includes the |
| 249 | actual configuration fragment in an ``.scc`` file, and the "hardware" |
| 250 | keyword identifies the fragment as being hardware enabling, as opposed |
| 251 | to general policy, which would use the "non-hardware" keyword. The |
| 252 | distinction is made for the benefit of the configuration validation |
| 253 | tools, which warn you if a hardware fragment overrides a policy set by a |
| 254 | non-hardware fragment. |
| 255 | |
| 256 | .. note:: |
| 257 | |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 258 | The description file can include multiple ``kconf`` statements, one per |
| 259 | fragment. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 260 | |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 261 | As described in the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 262 | ":ref:`kernel-dev/common:validating configuration`" section, you can |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 263 | use the following BitBake command to audit your configuration:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 264 | |
| 265 | $ bitbake linux-yocto -c kernel_configcheck -f |
| 266 | |
| 267 | Patches |
| 268 | ------- |
| 269 | |
| 270 | Patch descriptions are very similar to configuration fragment |
| 271 | descriptions, which are described in the previous section. However, |
| 272 | instead of a ``.cfg`` file, these descriptions work with source patches |
| 273 | (i.e. ``.patch`` files). |
| 274 | |
| 275 | A typical patch includes a description file and the patch itself. As an |
| 276 | example, consider the build patches used with the ``linux-yocto-4.12`` |
| 277 | kernel as defined outside of the recipe space (i.e. |
| 278 | ``yocto-kernel-cache``). This Metadata consists of several files: |
| 279 | ``build.scc`` and a set of ``*.patch`` files. You can find these files |
| 280 | in the ``patches/build`` directory of the ``yocto-4.12`` branch in the |
| 281 | ``yocto-kernel-cache`` Git repository. |
| 282 | |
| 283 | The following listings show the ``build.scc`` file and part of the |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 284 | ``modpost-mask-trivial-warnings.patch`` file:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 285 | |
| 286 | patches/build/build.scc: |
| 287 | patch arm-serialize-build-targets.patch |
| 288 | patch powerpc-serialize-image-targets.patch |
| 289 | patch kbuild-exclude-meta-directory-from-distclean-processi.patch |
| 290 | |
| 291 | # applied by kgit |
| 292 | # patch kbuild-add-meta-files-to-the-ignore-li.patch |
| 293 | |
| 294 | patch modpost-mask-trivial-warnings.patch |
| 295 | patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch |
| 296 | |
| 297 | patches/build/modpost-mask-trivial-warnings.patch: |
| 298 | From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001 |
| 299 | From: Paul Gortmaker <paul.gortmaker@windriver.com> |
| 300 | Date: Sun, 25 Jan 2009 17:58:09 -0500 |
| 301 | Subject: [PATCH] modpost: mask trivial warnings |
| 302 | |
| 303 | Newer HOSTCC will complain about various stdio fcns because |
| 304 | . |
| 305 | . |
| 306 | . |
| 307 | char *dump_write = NULL, *files_source = NULL; |
| 308 | int opt; |
| 309 | -- |
| 310 | 2.10.1 |
| 311 | |
| 312 | generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT) |
| 313 | |
| 314 | The description file can |
| 315 | include multiple patch statements where each statement handles a single |
William A. Kennington III | ac69b48 | 2021-06-02 12:28:27 -0700 | [diff] [blame] | 316 | patch. In the example ``build.scc`` file, there are five patch statements |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 317 | for the five patches in the directory. |
| 318 | |
| 319 | You can create a typical ``.patch`` file using ``diff -Nurp`` or |
| 320 | ``git format-patch`` commands. For information on how to create patches, |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 321 | see the ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" |
| 322 | and ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 323 | sections. |
| 324 | |
| 325 | Features |
| 326 | -------- |
| 327 | |
| 328 | Features are complex kernel Metadata types that consist of configuration |
| 329 | fragments, patches, and possibly other feature description files. As an |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 330 | example, consider the following generic listing:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 331 | |
| 332 | features/myfeature.scc |
| 333 | define KFEATURE_DESCRIPTION "Enable myfeature" |
| 334 | |
| 335 | patch 0001-myfeature-core.patch |
| 336 | patch 0002-myfeature-interface.patch |
| 337 | |
| 338 | include cfg/myfeature_dependency.scc |
| 339 | kconf non-hardware myfeature.cfg |
| 340 | |
| 341 | This example shows how the ``patch`` and ``kconf`` commands are used as well |
| 342 | as how an additional feature description file is included with the |
| 343 | ``include`` command. |
| 344 | |
| 345 | Typically, features are less granular than configuration fragments and |
| 346 | are more likely than configuration fragments and patches to be the types |
| 347 | of things you want to specify in the ``KERNEL_FEATURES`` variable of the |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 348 | Linux kernel recipe. See the |
| 349 | ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier |
| 350 | in the manual. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 351 | |
| 352 | Kernel Types |
| 353 | ------------ |
| 354 | |
| 355 | A kernel type defines a high-level kernel policy by aggregating |
| 356 | non-hardware configuration fragments with patches you want to use when |
| 357 | building a Linux kernel of a specific type (e.g. a real-time kernel). |
| 358 | Syntactically, kernel types are no different than features as described |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 359 | in the ":ref:`kernel-dev/advanced:features`" section. The |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 360 | :term:`LINUX_KERNEL_TYPE` |
| 361 | variable in the kernel recipe selects the kernel type. For example, in |
| 362 | the ``linux-yocto_4.12.bb`` kernel recipe found in |
| 363 | ``poky/meta/recipes-kernel/linux``, a |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 364 | :ref:`require <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` directive |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 365 | includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file, |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 366 | which has the following statement that defines the default kernel type:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 367 | |
| 368 | LINUX_KERNEL_TYPE ??= "standard" |
| 369 | |
| 370 | Another example would be the real-time kernel (i.e. |
| 371 | ``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 372 | type as follows:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 373 | |
| 374 | LINUX_KERNEL_TYPE = "preempt-rt" |
| 375 | |
| 376 | .. note:: |
| 377 | |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 378 | You can find kernel recipes in the ``meta/recipes-kernel/linux`` directory |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 379 | of the :ref:`overview-manual/development-environment:yocto project source repositories` |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 380 | (e.g. ``poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb``). See the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 381 | ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 382 | section for more information. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 383 | |
| 384 | Three kernel types ("standard", "tiny", and "preempt-rt") are supported |
| 385 | for Linux Yocto kernels: |
| 386 | |
| 387 | - "standard": Includes the generic Linux kernel policy of the Yocto |
| 388 | Project linux-yocto kernel recipes. This policy includes, among other |
| 389 | things, which file systems, networking options, core kernel features, |
| 390 | and debugging and tracing options are supported. |
| 391 | |
| 392 | - "preempt-rt": Applies the ``PREEMPT_RT`` patches and the |
| 393 | configuration options required to build a real-time Linux kernel. |
| 394 | This kernel type inherits from the "standard" kernel type. |
| 395 | |
| 396 | - "tiny": Defines a bare minimum configuration meant to serve as a base |
| 397 | for very small Linux kernels. The "tiny" kernel type is independent |
| 398 | from the "standard" configuration. Although the "tiny" kernel type |
| 399 | does not currently include any source changes, it might in the |
| 400 | future. |
| 401 | |
| 402 | For any given kernel type, the Metadata is defined by the ``.scc`` (e.g. |
| 403 | ``standard.scc``). Here is a partial listing for the ``standard.scc`` |
| 404 | file, which is found in the ``ktypes/standard`` directory of the |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 405 | ``yocto-kernel-cache`` Git repository:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 406 | |
| 407 | # Include this kernel type fragment to get the standard features and |
| 408 | # configuration values. |
| 409 | |
| 410 | # Note: if only the features are desired, but not the configuration |
| 411 | # then this should be included as: |
| 412 | # include ktypes/standard/standard.scc nocfg |
| 413 | # if no chained configuration is desired, include it as: |
| 414 | # include ktypes/standard/standard.scc nocfg inherit |
| 415 | |
| 416 | |
| 417 | |
| 418 | include ktypes/base/base.scc |
| 419 | branch standard |
| 420 | |
| 421 | kconf non-hardware standard.cfg |
| 422 | |
| 423 | include features/kgdb/kgdb.scc |
| 424 | . |
| 425 | . |
| 426 | . |
| 427 | |
| 428 | include cfg/net/ip6_nf.scc |
| 429 | include cfg/net/bridge.scc |
| 430 | |
| 431 | include cfg/systemd.scc |
| 432 | |
| 433 | include features/rfkill/rfkill.scc |
| 434 | |
| 435 | As with any ``.scc`` file, a kernel type definition can aggregate other |
| 436 | ``.scc`` files with ``include`` commands. These definitions can also |
| 437 | directly pull in configuration fragments and patches with the ``kconf`` |
| 438 | and ``patch`` commands, respectively. |
| 439 | |
| 440 | .. note:: |
| 441 | |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 442 | It is not strictly necessary to create a kernel type ``.scc`` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 443 | file. The Board Support Package (BSP) file can implicitly define the |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 444 | kernel type using a ``define`` :term:`KTYPE` ``myktype`` line. See the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 445 | ":ref:`kernel-dev/advanced:bsp descriptions`" section for more |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 446 | information. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 447 | |
| 448 | BSP Descriptions |
| 449 | ---------------- |
| 450 | |
| 451 | BSP descriptions (i.e. ``*.scc`` files) combine kernel types with |
| 452 | hardware-specific features. The hardware-specific Metadata is typically |
| 453 | defined independently in the BSP layer, and then aggregated with each |
| 454 | supported kernel type. |
| 455 | |
| 456 | .. note:: |
| 457 | |
| 458 | For BSPs supported by the Yocto Project, the BSP description files |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 459 | are located in the ``bsp`` directory of the ``yocto-kernel-cache`` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 460 | repository organized under the "Yocto Linux Kernel" heading in the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 461 | :yocto_git:`Yocto Project Source Repositories <>`. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 462 | |
| 463 | This section overviews the BSP description structure, the aggregation |
| 464 | concepts, and presents a detailed example using a BSP supported by the |
| 465 | Yocto Project (i.e. BeagleBone Board). For complete information on BSP |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 466 | layer file hierarchy, see the :doc:`/bsp-guide/index`. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 467 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 468 | Description Overview |
| 469 | ~~~~~~~~~~~~~~~~~~~~ |
| 470 | |
| 471 | For simplicity, consider the following root BSP layer description files |
| 472 | for the BeagleBone board. These files employ both a structure and naming |
| 473 | convention for consistency. The naming convention for the file is as |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 474 | follows:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 475 | |
| 476 | bsp_root_name-kernel_type.scc |
| 477 | |
| 478 | Here are some example root layer |
| 479 | BSP filenames for the BeagleBone Board BSP, which is supported by the |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 480 | Yocto Project:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 481 | |
| 482 | beaglebone-standard.scc |
| 483 | beaglebone-preempt-rt.scc |
| 484 | |
| 485 | Each file uses the root name (i.e "beaglebone") BSP name followed by the |
| 486 | kernel type. |
| 487 | |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 488 | Examine the ``beaglebone-standard.scc`` file:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 489 | |
| 490 | define KMACHINE beaglebone |
| 491 | define KTYPE standard |
| 492 | define KARCH arm |
| 493 | |
| 494 | include ktypes/standard/standard.scc |
| 495 | branch beaglebone |
| 496 | |
| 497 | include beaglebone.scc |
| 498 | |
| 499 | # default policy for standard kernels |
| 500 | include features/latencytop/latencytop.scc |
| 501 | include features/profiling/profiling.scc |
| 502 | |
| 503 | Every top-level BSP description file |
| 504 | should define the :term:`KMACHINE`, |
| 505 | :term:`KTYPE`, and |
| 506 | :term:`KARCH` variables. These |
| 507 | variables allow the OpenEmbedded build system to identify the |
| 508 | description as meeting the criteria set by the recipe being built. This |
| 509 | example supports the "beaglebone" machine for the "standard" kernel and |
| 510 | the "arm" architecture. |
| 511 | |
William A. Kennington III | ac69b48 | 2021-06-02 12:28:27 -0700 | [diff] [blame] | 512 | Be aware that there is no hard link between the ``KTYPE`` variable and a kernel |
| 513 | type description file. Thus, if you do not have the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 514 | kernel type defined in your kernel Metadata as it is here, you only need |
| 515 | to ensure that the |
| 516 | :term:`LINUX_KERNEL_TYPE` |
| 517 | variable in the kernel recipe and the ``KTYPE`` variable in the BSP |
| 518 | description file match. |
| 519 | |
| 520 | To separate your kernel policy from your hardware configuration, you |
| 521 | include a kernel type (``ktype``), such as "standard". In the previous |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 522 | example, this is done using the following:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 523 | |
| 524 | include ktypes/standard/standard.scc |
| 525 | |
| 526 | This file aggregates all the configuration |
| 527 | fragments, patches, and features that make up your standard kernel |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 528 | policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 529 | information. |
| 530 | |
| 531 | To aggregate common configurations and features specific to the kernel |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 532 | for `mybsp`, use the following:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 533 | |
| 534 | include mybsp.scc |
| 535 | |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 536 | You can see that in the BeagleBone example with the following:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 537 | |
| 538 | include beaglebone.scc |
| 539 | |
| 540 | For information on how to break a complete ``.config`` file into the various |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 541 | configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" section. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 542 | |
| 543 | Finally, if you have any configurations specific to the hardware that |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 544 | are not in a ``*.scc`` file, you can include them as follows:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 545 | |
| 546 | kconf hardware mybsp-extra.cfg |
| 547 | |
| 548 | The BeagleBone example does not include these |
| 549 | types of configurations. However, the Malta 32-bit board does |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 550 | ("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 551 | |
| 552 | define KMACHINE mti-malta32-le |
| 553 | define KMACHINE qemumipsel |
| 554 | define KTYPE standard |
| 555 | define KARCH mips |
| 556 | |
| 557 | include ktypes/standard/standard.scc |
| 558 | branch mti-malta32 |
| 559 | |
| 560 | include mti-malta32.scc |
| 561 | kconf hardware mti-malta32-le.cfg |
| 562 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 563 | Example |
| 564 | ~~~~~~~ |
| 565 | |
| 566 | Many real-world examples are more complex. Like any other ``.scc`` file, |
| 567 | BSP descriptions can aggregate features. Consider the Minnow BSP |
| 568 | definition given the ``linux-yocto-4.4`` branch of the |
| 569 | ``yocto-kernel-cache`` (i.e. |
| 570 | ``yocto-kernel-cache/bsp/minnow/minnow.scc``): |
| 571 | |
| 572 | .. note:: |
| 573 | |
| 574 | Although the Minnow Board BSP is unused, the Metadata remains and is |
| 575 | being used here just as an example. |
| 576 | |
| 577 | :: |
| 578 | |
| 579 | include cfg/x86.scc |
| 580 | include features/eg20t/eg20t.scc |
| 581 | include cfg/dmaengine.scc |
| 582 | include features/power/intel.scc |
| 583 | include cfg/efi.scc |
| 584 | include features/usb/ehci-hcd.scc |
| 585 | include features/usb/ohci-hcd.scc |
| 586 | include features/usb/usb-gadgets.scc |
| 587 | include features/usb/touchscreen-composite.scc |
| 588 | include cfg/timer/hpet.scc |
| 589 | include features/leds/leds.scc |
| 590 | include features/spi/spidev.scc |
| 591 | include features/i2c/i2cdev.scc |
| 592 | include features/mei/mei-txe.scc |
| 593 | |
| 594 | # Earlyprintk and port debug requires 8250 |
| 595 | kconf hardware cfg/8250.cfg |
| 596 | |
| 597 | kconf hardware minnow.cfg |
| 598 | kconf hardware minnow-dev.cfg |
| 599 | |
| 600 | The ``minnow.scc`` description file includes a hardware configuration |
| 601 | fragment (``minnow.cfg``) specific to the Minnow BSP as well as several |
| 602 | more general configuration fragments and features enabling hardware |
| 603 | found on the machine. This ``minnow.scc`` description file is then |
| 604 | included in each of the three "minnow" description files for the |
| 605 | supported kernel types (i.e. "standard", "preempt-rt", and "tiny"). |
| 606 | Consider the "minnow" description for the "standard" kernel type (i.e. |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 607 | ``minnow-standard.scc``):: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 608 | |
| 609 | define KMACHINE minnow |
| 610 | define KTYPE standard |
| 611 | define KARCH i386 |
| 612 | |
| 613 | include ktypes/standard |
| 614 | |
| 615 | include minnow.scc |
| 616 | |
| 617 | # Extra minnow configs above the minimal defined in minnow.scc |
| 618 | include cfg/efi-ext.scc |
| 619 | include features/media/media-all.scc |
| 620 | include features/sound/snd_hda_intel.scc |
| 621 | |
| 622 | # The following should really be in standard.scc |
| 623 | # USB live-image support |
| 624 | include cfg/usb-mass-storage.scc |
| 625 | include cfg/boot-live.scc |
| 626 | |
| 627 | # Basic profiling |
| 628 | include features/latencytop/latencytop.scc |
| 629 | include features/profiling/profiling.scc |
| 630 | |
| 631 | # Requested drivers that don't have an existing scc |
| 632 | kconf hardware minnow-drivers-extra.cfg |
| 633 | |
| 634 | The ``include`` command midway through the file includes the ``minnow.scc`` description |
| 635 | that defines all enabled hardware for the BSP that is common to all |
| 636 | kernel types. Using this command significantly reduces duplication. |
| 637 | |
| 638 | Now consider the "minnow" description for the "tiny" kernel type (i.e. |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 639 | ``minnow-tiny.scc``):: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 640 | |
| 641 | define KMACHINE minnow |
| 642 | define KTYPE tiny |
| 643 | define KARCH i386 |
| 644 | |
| 645 | include ktypes/tiny |
| 646 | |
| 647 | include minnow.scc |
| 648 | |
| 649 | As you might expect, |
| 650 | the "tiny" description includes quite a bit less. In fact, it includes |
| 651 | only the minimal policy defined by the "tiny" kernel type and the |
| 652 | hardware-specific configuration required for booting the machine along |
| 653 | with the most basic functionality of the system as defined in the base |
| 654 | "minnow" description file. |
| 655 | |
| 656 | Notice again the three critical variables: |
| 657 | :term:`KMACHINE`, |
| 658 | :term:`KTYPE`, and |
| 659 | :term:`KARCH`. Of these variables, only |
| 660 | ``KTYPE`` has changed to specify the "tiny" kernel type. |
| 661 | |
| 662 | Kernel Metadata Location |
| 663 | ======================== |
| 664 | |
| 665 | Kernel Metadata always exists outside of the kernel tree either defined |
| 666 | in a kernel recipe (recipe-space) or outside of the recipe. Where you |
| 667 | choose to define the Metadata depends on what you want to do and how you |
| 668 | intend to work. Regardless of where you define the kernel Metadata, the |
| 669 | syntax used applies equally. |
| 670 | |
| 671 | If you are unfamiliar with the Linux kernel and only wish to apply a |
| 672 | configuration and possibly a couple of patches provided to you by |
| 673 | others, the recipe-space method is recommended. This method is also a |
| 674 | good approach if you are working with Linux kernel sources you do not |
| 675 | control or if you just do not want to maintain a Linux kernel Git |
| 676 | repository on your own. For partial information on how you can define |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 677 | kernel Metadata in the recipe-space, see the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 678 | ":ref:`kernel-dev/common:modifying an existing recipe`" section. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 679 | |
| 680 | Conversely, if you are actively developing a kernel and are already |
| 681 | maintaining a Linux kernel Git repository of your own, you might find it |
| 682 | more convenient to work with kernel Metadata kept outside the |
| 683 | recipe-space. Working with Metadata in this area can make iterative |
| 684 | development of the Linux kernel more efficient outside of the BitBake |
| 685 | environment. |
| 686 | |
| 687 | Recipe-Space Metadata |
| 688 | --------------------- |
| 689 | |
| 690 | When stored in recipe-space, the kernel Metadata files reside in a |
| 691 | directory hierarchy below |
| 692 | :term:`FILESEXTRAPATHS`. For |
| 693 | a linux-yocto recipe or for a Linux kernel recipe derived by copying and |
| 694 | modifying |
| 695 | ``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to |
| 696 | a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to |
| 697 | ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``. |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 698 | See the ":ref:`kernel-dev/common:modifying an existing recipe`" |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 699 | section for more information. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 700 | |
| 701 | Here is an example that shows a trivial tree of kernel Metadata stored |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 702 | in recipe-space within a BSP layer:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 703 | |
| 704 | meta-my_bsp_layer/ |
| 705 | `-- recipes-kernel |
| 706 | `-- linux |
| 707 | `-- linux-yocto |
| 708 | |-- bsp-standard.scc |
| 709 | |-- bsp.cfg |
| 710 | `-- standard.cfg |
| 711 | |
| 712 | When the Metadata is stored in recipe-space, you must take steps to |
| 713 | ensure BitBake has the necessary information to decide what files to |
| 714 | fetch and when they need to be fetched again. It is only necessary to |
| 715 | specify the ``.scc`` files on the |
| 716 | :term:`SRC_URI`. BitBake parses them |
| 717 | and fetches any files referenced in the ``.scc`` files by the |
| 718 | ``include``, ``patch``, or ``kconf`` commands. Because of this, it is |
| 719 | necessary to bump the recipe :term:`PR` |
| 720 | value when changing the content of files not explicitly listed in the |
| 721 | ``SRC_URI``. |
| 722 | |
| 723 | If the BSP description is in recipe space, you cannot simply list the |
| 724 | ``*.scc`` in the ``SRC_URI`` statement. You need to use the following |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 725 | form from your kernel append file:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 726 | |
| 727 | SRC_URI_append_myplatform = " \ |
| 728 | file://myplatform;type=kmeta;destsuffix=myplatform \ |
| 729 | " |
| 730 | |
| 731 | Metadata Outside the Recipe-Space |
| 732 | --------------------------------- |
| 733 | |
| 734 | When stored outside of the recipe-space, the kernel Metadata files |
| 735 | reside in a separate repository. The OpenEmbedded build system adds the |
| 736 | Metadata to the build as a "type=kmeta" repository through the |
| 737 | :term:`SRC_URI` variable. As an |
| 738 | example, consider the following ``SRC_URI`` statement from the |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 739 | ``linux-yocto_4.12.bb`` kernel recipe:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 740 | |
| 741 | SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \ |
| 742 | git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" |
| 743 | |
| 744 | |
| 745 | ``${KMETA}``, in this context, is simply used to name the directory into |
| 746 | which the Git fetcher places the Metadata. This behavior is no different |
| 747 | than any multi-repository ``SRC_URI`` statement used in a recipe (e.g. |
| 748 | see the previous section). |
| 749 | |
| 750 | You can keep kernel Metadata in a "kernel-cache", which is a directory |
| 751 | containing configuration fragments. As with any Metadata kept outside |
| 752 | the recipe-space, you simply need to use the ``SRC_URI`` statement with |
| 753 | the "type=kmeta" attribute. Doing so makes the kernel Metadata available |
| 754 | during the configuration phase. |
| 755 | |
| 756 | If you modify the Metadata, you must not forget to update the ``SRCREV`` |
| 757 | statements in the kernel's recipe. In particular, you need to update the |
| 758 | ``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you |
| 759 | wish to use. Changing the data in these branches and not updating the |
| 760 | ``SRCREV`` statements to match will cause the build to fetch an older |
| 761 | commit. |
| 762 | |
| 763 | Organizing Your Source |
| 764 | ====================== |
| 765 | |
| 766 | Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux |
| 767 | kernel sources that have only a single branch - "master". This type of |
| 768 | repository structure is fine for linear development supporting a single |
| 769 | machine and architecture. However, if you work with multiple boards and |
| 770 | architectures, a kernel source repository with multiple branches is more |
| 771 | efficient. For example, suppose you need a series of patches for one |
| 772 | board to boot. Sometimes, these patches are works-in-progress or |
| 773 | fundamentally wrong, yet they are still necessary for specific boards. |
| 774 | In these situations, you most likely do not want to include these |
| 775 | patches in every kernel you build (i.e. have the patches as part of the |
| 776 | lone "master" branch). It is situations like these that give rise to |
| 777 | multiple branches used within a Linux kernel sources Git repository. |
| 778 | |
William A. Kennington III | ac69b48 | 2021-06-02 12:28:27 -0700 | [diff] [blame] | 779 | Here are repository organization strategies maximizing source reuse, |
| 780 | removing redundancy, and logically ordering your changes. This section |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 781 | presents strategies for the following cases: |
| 782 | |
| 783 | - Encapsulating patches in a feature description and only including the |
| 784 | patches in the BSP descriptions of the applicable boards. |
| 785 | |
| 786 | - Creating a machine branch in your kernel source repository and |
| 787 | applying the patches on that branch only. |
| 788 | |
| 789 | - Creating a feature branch in your kernel source repository and |
| 790 | merging that branch into your BSP when needed. |
| 791 | |
| 792 | The approach you take is entirely up to you and depends on what works |
| 793 | best for your development model. |
| 794 | |
| 795 | Encapsulating Patches |
| 796 | --------------------- |
| 797 | |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 798 | If you are reusing patches from an external tree and are not working on |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 799 | the patches, you might find the encapsulated feature to be appropriate. |
| 800 | Given this scenario, you do not need to create any branches in the |
| 801 | source repository. Rather, you just take the static patches you need and |
| 802 | encapsulate them within a feature description. Once you have the feature |
| 803 | description, you simply include that into the BSP description as |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 804 | described in the ":ref:`kernel-dev/advanced:bsp descriptions`" section. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 805 | |
| 806 | You can find information on how to create patches and BSP descriptions |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 807 | in the ":ref:`kernel-dev/advanced:patches`" and |
| 808 | ":ref:`kernel-dev/advanced:bsp descriptions`" sections. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 809 | |
| 810 | Machine Branches |
| 811 | ---------------- |
| 812 | |
| 813 | When you have multiple machines and architectures to support, or you are |
| 814 | actively working on board support, it is more efficient to create |
| 815 | branches in the repository based on individual machines. Having machine |
| 816 | branches allows common source to remain in the "master" branch with any |
| 817 | features specific to a machine stored in the appropriate machine branch. |
| 818 | This organization method frees you from continually reintegrating your |
| 819 | patches into a feature. |
| 820 | |
| 821 | Once you have a new branch, you can set up your kernel Metadata to use |
| 822 | the branch a couple different ways. In the recipe, you can specify the |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 823 | new branch as the ``KBRANCH`` to use for the board as follows:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 824 | |
| 825 | KBRANCH = "mynewbranch" |
| 826 | |
| 827 | Another method is to use the ``branch`` command in the BSP |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 828 | description:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 829 | |
| 830 | mybsp.scc: |
| 831 | define KMACHINE mybsp |
| 832 | define KTYPE standard |
| 833 | define KARCH i386 |
| 834 | include standard.scc |
| 835 | |
| 836 | branch mynewbranch |
| 837 | |
| 838 | include mybsp-hw.scc |
| 839 | |
| 840 | If you find yourself with numerous branches, you might consider using a |
| 841 | hierarchical branching system similar to what the Yocto Linux Kernel Git |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 842 | repositories use:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 843 | |
| 844 | common/kernel_type/machine |
| 845 | |
| 846 | If you had two kernel types, "standard" and "small" for instance, three |
| 847 | machines, and common as ``mydir``, the branches in your Git repository |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 848 | might look like this:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 849 | |
| 850 | mydir/base |
| 851 | mydir/standard/base |
| 852 | mydir/standard/machine_a |
| 853 | mydir/standard/machine_b |
| 854 | mydir/standard/machine_c |
| 855 | mydir/small/base |
| 856 | mydir/small/machine_a |
| 857 | |
| 858 | This organization can help clarify the branch relationships. In this |
| 859 | case, ``mydir/standard/machine_a`` includes everything in ``mydir/base`` |
| 860 | and ``mydir/standard/base``. The "standard" and "small" branches add |
| 861 | sources specific to those kernel types that for whatever reason are not |
| 862 | appropriate for the other branches. |
| 863 | |
| 864 | .. note:: |
| 865 | |
| 866 | The "base" branches are an artifact of the way Git manages its data |
| 867 | internally on the filesystem: Git will not allow you to use |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 868 | ``mydir/standard`` and ``mydir/standard/machine_a`` because it would have to |
| 869 | create a file and a directory named "standard". |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 870 | |
| 871 | Feature Branches |
| 872 | ---------------- |
| 873 | |
| 874 | When you are actively developing new features, it can be more efficient |
| 875 | to work with that feature as a branch, rather than as a set of patches |
| 876 | that have to be regularly updated. The Yocto Project Linux kernel tools |
| 877 | provide for this with the ``git merge`` command. |
| 878 | |
| 879 | To merge a feature branch into a BSP, insert the ``git merge`` command |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 880 | after any ``branch`` commands:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 881 | |
| 882 | mybsp.scc: |
| 883 | define KMACHINE mybsp |
| 884 | define KTYPE standard |
| 885 | define KARCH i386 |
| 886 | include standard.scc |
| 887 | |
| 888 | branch mynewbranch |
| 889 | git merge myfeature |
| 890 | |
| 891 | include mybsp-hw.scc |
| 892 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 893 | SCC Description File Reference |
| 894 | ============================== |
| 895 | |
| 896 | This section provides a brief reference for the commands you can use |
| 897 | within an SCC description file (``.scc``): |
| 898 | |
| 899 | - ``branch [ref]``: Creates a new branch relative to the current branch |
| 900 | (typically ``${KTYPE}``) using the currently checked-out branch, or |
| 901 | "ref" if specified. |
| 902 | |
| 903 | - ``define``: Defines variables, such as |
| 904 | :term:`KMACHINE`, |
| 905 | :term:`KTYPE`, |
| 906 | :term:`KARCH`, and |
| 907 | :term:`KFEATURE_DESCRIPTION`. |
| 908 | |
| 909 | - ``include SCC_FILE``: Includes an SCC file in the current file. The |
| 910 | file is parsed as if you had inserted it inline. |
| 911 | |
| 912 | - ``kconf [hardware|non-hardware] CFG_FILE``: Queues a configuration |
| 913 | fragment for merging into the final Linux ``.config`` file. |
| 914 | |
| 915 | - ``git merge GIT_BRANCH``: Merges the feature branch into the current |
| 916 | branch. |
| 917 | |
| 918 | - ``patch PATCH_FILE``: Applies the patch to the current Git branch. |
| 919 | |
| 920 | |