path: root/documentation/kernel-dev
diff options
authorScott Rifenbark <>2013-01-14 20:16:50 (GMT)
committerRichard Purdie <>2013-01-16 15:59:21 (GMT)
commit29d5511d026f365b2db68b8e87a487515d82cc69 (patch)
tree5245e30213b7bd868b7ba3e1e9ea5fb7c92ccec0 /documentation/kernel-dev
parent5487eeb730bd4ea4ab188c74352d80b4f5f413f8 (diff)
kernel-dev: Edits to Advanced Metadata chapter
Removed all the orginal text. (From yocto-docs rev: 8a3b11fb6936574edb4fd0daf60d21ee2c2ccd8f) Signed-off-by: Scott Rifenbark <> Signed-off-by: Richard Purdie <>
Diffstat (limited to 'documentation/kernel-dev')
1 files changed, 0 insertions, 658 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index adfd774..df3f301 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -38,30 +38,6 @@
38 together as needed, but maintain them in only one place. 38 together as needed, but maintain them in only one place.
39 Similar logic applies to source changes. 39 Similar logic applies to source changes.
40 </para> 40 </para>
42 <para>
43 Original Text:
44 <literallayout class='monospaced'>
45In addition to configuration fragments and patches, the Yocto Project kernel
46tools support rich metadata which you can use to define complex policies and
47BSP support. The purpose of the metadata and the tools to manage it, known as
48the kern-tools (, is to assist in managing the
49complexity of the configuration and sources in support of multiple BSPs and
50Linux kernel types.
52In particular, the kernel tools allow you to specify only what you must, and
53nothing more. Where a complete Linux kernel .config includes all the
54automatically selected CONFIG options, the configuration fragments only need to
55contain the highest level visible CONFIG options as presented by the Linux
56kernel menuconfig system. This reduces your maintenance effort and allows you
57to further separate your configuration in ways that make sense for your project.
58A common split is policy and hardware. For example, all your kernels may support
59the proc and sys filesystems, but only specific boards will require sound, USB,
60or specific drivers. Specifying these individually allows you to aggregate them
61together as needed, but maintain them in only one place. Similar logic applies
62to source changes.
63 </literallayout>
64 </para>
65</section> 41</section>
66 42
67<section id='using-kernel-metadata-in-a-recipe'> 43<section id='using-kernel-metadata-in-a-recipe'>
@@ -197,88 +173,6 @@ to source changes.
197 releases of the Yocto Project. 173 releases of the Yocto Project.
198 </note> 174 </note>
199 </para> 175 </para>
201 <para>
202 Original Text.
203 <literallayout class='monospaced'>
204The metadata provided with any linux-yocto style Linux kernel sources must
205define a BSP that corresponds to the definition laid out in the recipe. A BSP
206consists of an aggregation of kernel policy and hardware specific feature
207enablement. This can be influenced from within the recipe.
209Every linux-yocto style recipe must define the following variables:
213KMACHINE is typically set to the same value as used within the recipe-space BSP
214definition, such as "routerstationpro" or "fri2". However, multiple BSPs can
215reuse the same KMACHINE name if they are built using the same BSP description
216(see 3.3.5). The meta-intel "fri2" and "fri2-noemgd" are good examples of such
217a situation where each specifies KMACHINE as "fri2".
219They may optionally define the following variables:
225KBRANCH_DEFAULT defines the default source branch within the Linux kernel source
226repository to be used to build the Linux kernel. It is used as the default value
227for KBRANCH which may define an alternate branch, typically with a machine
228override, such as:
230KBRANCH_fri2 = "standard/fri2"
232Unless you specify otherwise, KBRANCH_DEFAULT is initialized to "master".
234LINUX_KERNEL_TYPE defines the kernel type to be used in assembling the
235configuration and defaults to "standard" if you do not specify otherwise.
236Together with KMACHINE, this defines the search arguments used by the Yocto
237Project Linux kernel tools to find the appropriate description within the
238metadata with which to build out the sources and configuration. The linux-yocto
239recipes define "standard", "tiny", and "preempt-rt" kernel types. See 3.3.4 for
240more information on kernel types.
242During the build, the kern-tools will search for the BSP description file that
243most closely matches the KMACHINE and LINUX_KERNEL_TYPE passed in from the
244recipe. It will use the first BSP description it finds matching both variables.
245Failing that it will issue a warning such as the following:
247 WARNING: Can't find any BSP hardware or required configuration fragments.
248 WARNING: Looked at meta/cfg/broken/fri2-broken/hdw_frags.txt and
249 meta/cfg/broken/fri2-broken/required_frags.txt in directory:
250 meta/cfg/broken/fri2-broken
252 In this example KMACHINE was set to "fri2-broken" and LINUX_KERNEL_TYPE
253 was set to "broken".
255It will then search first for the KMACHINE and then
256for the LINUX_KERNEL_TYPE. If it cannot find a partial match, it will use the
257sources from the KBRANCH and any configuration specified in the SRC_URI.
259KERNEL_FEATURES can be used to include features (configuration fragments,
260patches, or both) that are not already included by the KMACHINE and
261LINUX_KERNEL_TYPE combination. To include a feature specified as
262"features/netfilter.scc" for example, specify:
264KERNEL_FEATURES += "features/netfilter.scc"
266To include a feature called "cfg/sound.scc" just for the qemux86 machine,
269KERNEL_FEATURES_append_qemux86 = "cfg/sound.scc"
271The value of the entries in KERNEL_FEATURES are dependent on their location
272within the metadata itself. The examples here are taken from the
273linux-yocto-3.4 repository where "features" and "cfg" are subdirectories of the
274metadata directory. For details, see 3.3.
276 Note: The processing of the these variables has evolved some between the
277 0.9 and 1.3 releases of the Yocto Project and associated
278 kern-tools sources. The above is accurate for 1.3 and later
279 releases of the Yocto Project.
280 </literallayout>
281 </para>
282</section> 176</section>
283 177
284<section id='kernel-metadata-location'> 178<section id='kernel-metadata-location'>
@@ -315,31 +209,6 @@ metadata directory. For details, see 3.3.
315 more efficient outside of the BitBake environment. 209 more efficient outside of the BitBake environment.
316 </para> 210 </para>
317 211
318 <para>
319 Original Text:
320 <literallayout class='monospaced'>
321This meta-data can be defined along with the Linux kernel recipe (recipe-space)
322as partially described in section 2.2 as well as within the Linux kernel sources
323themselves (in-tree).
325Where you choose to store the meta-data depends on what you want to do and how
326you intend to work. If you are unfamiliar with the Linux kernel and only wish
327to apply a config and possibly a couple of patches provided to you by others,
328you may find the recipe-space mechanism to be easier to work with. This is also
329a good approach if you are working with Linux kernel sources you do not control
330or if you just don't want to maintain a Linux kernel git repository on your own.
332If you are doing active kernel development and are already maintaining a Linux
333kernel git repository of your own, you may find it more convenient to work with
334the meta-data in the same repository as the Linux kernel sources. This can make
335iterative development of the Linux kernel more efficient outside of the BitBake
338Regardless of where the meta-data is stored, the syntax as
339described in the following sections applies equally.
340 </literallayout>
341 </para>
343 <section id='recipe-space-metadata'> 212 <section id='recipe-space-metadata'>
344 <title>Recipe-Space Metadata</title> 213 <title>Recipe-Space Metadata</title>
345 214
@@ -386,35 +255,6 @@ described in the following sections applies equally.
386 value when changing the content of files not explicitly listed 255 value when changing the content of files not explicitly listed
387 in the <filename>SRC_URI</filename>. 256 in the <filename>SRC_URI</filename>.
388 </para> 257 </para>
390 <para>
391 Original text:
392 <literallayout class='monospaced'>
393When stored in recipe-space, the meta-data files reside in a directory hierarchy
394below FILESEXTRAPATHS, which is typically set to ${THISDIR}/${PN} for a
395linux-yocto or linux-yocto-custom derived Linux kernel recipe. See 2.2.
397By way of example, a trivial tree of meta-data stored in recipe-space within a
398BSP layer might look like the following:
401`-- recipes-kernel
402 `-- linux
403 `-- linux-yocto
404 |-- bsp-standard.scc
405 |-- bsp.cfg
406 `-- standard.cfg
408When the meta-data is stored in recipe-space, you must take steps to ensure
409BitBake has the necessary information to decide which files to fetch and when
410they need to be fetched again.
412It is only necessary to specify the .scc files on the SRC_URI; BitBake will
413parse them and fetch any files referenced in the .scc files by the include,
414patch, or kconf commands. Because of this, it is necessary to bump the recipe PR
415value when changing the content of files not explicitly listed in the SRC_URI.
416 </literallayout>
417 </para>
418 </section> 258 </section>
419 259
420 <section id='in-tree-metadata'> 260 <section id='in-tree-metadata'>
@@ -474,48 +314,6 @@ value when changing the content of files not explicitly listed in the SRC_URI.
474 $ git commit --allow-empty -m "Create orphan meta branch" 314 $ git commit --allow-empty -m "Create orphan meta branch"
475 </literallayout> 315 </literallayout>
476 </para> 316 </para>
478 <para>
479 Original text:
480 <literallayout class='monospaced'>
481When stored in-tree, the meta-data files reside in the "meta" directory of the
482Linux kernel sources. They may be present in the same branch as the sources,
483such as "master", or in their own orphan branch, typically named "meta". An
484orphan branch in git is a branch with unique history and content to the other
485branches in the repository. This is useful to track meta-data changes
486independently from the sources of the Linux kernel, while still keeping them
487together in the same repository. For the purposes of this document, we will
488discuss all in-tree meta-data as residing below the "meta/cfg/kernel-cache"
491By way of example, a trivial tree of meta-data stored in a custom Linux kernel
492git repository might look like the following:
495`-- cfg
496 `-- kernel-cache
497 |-- bsp-standard.scc
498 |-- bsp.cfg
499 `-- standard.cfg
501To use a specific branch for the meta-data, specify the branch in the KMETA
502variable in your Linux kernel recipe, for example:
504 KMETA = "meta"
506To use the same branch as the sources, set KMETA to the empty string:
508 KMETA = ""
510If you are working with your own sources and want to create an orphan meta
511branch, you can do so using the following commands from within your Linux kernel
512git repository:
514 $ git checkout --orphan meta
515 $ git rm -rf .
516 $ git commit --allow-empty -m "Create orphan meta branch"
517 </literallayout>
518 </para>
519 </section> 317 </section>
520</section> 318</section>
521 319
@@ -635,66 +433,6 @@ git repository:
635 Metadata <link linkend='in-tree-metadata'>in-tree</link>. 433 Metadata <link linkend='in-tree-metadata'>in-tree</link>.
636 </para> 434 </para>
637 435
638 <para>
639 Original text:
640 <literallayout class='monospaced'>
641The Yocto Project Linux kernel tools meta-data consists of three primary types
642of files: scc* description files, configuration fragments, and patches. The scc
643files define variables and include or otherwise reference any of the three file
644types. The description files are used to aggregate all types of meta-data into
645what ultimately describes the sources and the configuration required to build a
646Linux kernel tailored to a specific machine.
648The scc description files are used to define two fundamental types of meta-data:
649 o Features
650 o BSPs
652Features aggregate sources in the form of patches and configuration in the form
653of configuration fragments into a modular reusable unit. Features are used to
654implement conceptually separate meta-data descriptions like pure configuration
655fragments, simple patches, complex features, and kernel types (ktypes). Kernel
656types define general kernel features and policy to be reused in the BSPs.
658BSPs define hardware-specific features and aggregate them with kernel types to
659form the final description of what will be assembled and built.
661While the meta-data syntax does not enforce any logical separation of
662configuration fragments, patches, features or kernel types, best practices
663dictate a logical separation of these types of meta-data. The following
664meta-data file hierarchy is recommended:
666 &lt;base&gt;/
667 bsp/
668 cfg/
669 features/
670 ktypes/
671 patches/
673The bsp directory should contain the BSP descriptions, described in detail in
6743.3.5. The remaining directories all contain "features"; the separation is meant
675to aid in conceptualizing their intended usage. A simple guide to determine
676where your scc description file should go is as follows. If it contains only
677configuration fragments, it belongs in cfg. If it contains only source-code
678fixes, it belongs in patches. If it encapsulates a major feature, often
679combining sources and configurations, it belongs in features. If it aggregates
680non-hardware configuration and patches in order to define a base kernel policy
681or major kernel type to be reused across multiple BSPs, it belongs in ktypes.
682The line between these can easily become blurred, especially as out-of-tree
683features are slowly merged upstream over time. Also remember that this is purely
684logical organization and has no impact on the functionality of the meta-data as
685all of cfg, features, patches, and ktypes, contain "features" as far as the
686Yocto Project Linux kernel tools are concerned.
688Paths used in meta-data files are relative to &lt;base&gt; which is either
689FILESEXTRAPATHS if you are creating meta-data in recipe-space (see 3.2.1), or
690meta/cfg/kernel-cache/ if you are creating meta-data in-tree (see 3.2.2).
692* scc stands for Series Configuration Control, but the naming has less
693 significance in the current implementation of the tooling than it had in the
694 past. Consider it to be a description file.
695 </literallayout>
696 </para>
698 <section id='configuration'> 436 <section id='configuration'>
699 <title>Configuration</title> 437 <title>Configuration</title>
700 438
@@ -757,45 +495,6 @@ meta/cfg/kernel-cache/ if you are creating meta-data in-tree (see 3.2.2).
757 $ bitbake linux-yocto -c kernel_configcheck -f 495 $ bitbake linux-yocto -c kernel_configcheck -f
758 </literallayout> 496 </literallayout>
759 </para> 497 </para>
761 <para>
762 Original text:
763 <literallayout class='monospaced'>
764The simplest unit of meta-data is the configuration-only feature. It consists of
765one or more Linux kernel configuration parameters in a .cfg file (as described
766in section XYZ) and an scc file describing the fragment. The SMP fragment
767included in the linux-yocto-3.4 git repository consists of the following two
772 kconf hardware smp.cfg
778See 2.3.1 for details on creating configuration fragments.
780KFEATURE_DESCRIPTION provides a short description of the fragment, the
781primary use is for higher level tooling, such as the Yocto Project BSP Tools
784The "kconf" command is used to include the actual configuration fragment in an
785scc file, and the "hardware" keyword identifies the fragment as being hardware
786enabling, as opposed to general policy (which would use the keyword
787"non-hardware"). The distinction is made for the benefit of the configuration
788validation tools which will warn you if a hardware fragment overrides a policy
789set by a non-hardware fragment.
791As described in 2.3.1, the following bitbake command can be used to audit your
794 $ bitbake linux-yocto -c kernel_configcheck -f
796The description file can include multiple kconf statements, one per fragment.
797 </literallayout>
798 </para>
799 </section> 498 </section>
800 499
801 <section id='patches'> 500 <section id='patches'>
@@ -826,23 +525,6 @@ The description file can include multiple kconf statements, one per fragment.
826 The description file can include multiple patch statements, 525 The description file can include multiple patch statements,
827 one per patch. 526 one per patch.
828 </para> 527 </para>
830 <para>
831 Original text:
832 <literallayout class='monospaced'>
833Patches are described in a very similar way to configuration fragments (see
8343.3.1). Instead of a .cfg file, they work with source patches. A typical patch
835includes a description file and the patch itself:
838 patch mypatch.patch
841 &lt;typical patch created with 'diff -Nurp' or 'git format-patch'&gt;
843The description file can include multiple patch statements, one per patch.
844 </literallayout>
845 </para>
846 </section> 528 </section>
847 529
848 <section id='features'> 530 <section id='features'>
@@ -881,33 +563,6 @@ The description file can include multiple patch statements, one per patch.
881 See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>" 563 See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
882 section earlier in the manual. 564 section earlier in the manual.
883 </para> 565 </para>
885 <para>
886 Original text:
887 <literallayout class='monospaced'>
888Features are a combination of configuration fragments and patches, or, more
889accurately, configuration fragments and patches are simple forms of a feature, a
890more complex meta-data type. In addition to the kconf and patch commands,
891features often aggregate description files with the include command.
893A hypothetical example of a feature description file might look like the
897 define KFEATURE_DESCRIPTION "Enable myfeature"
899 patch 0001-myfeature-core.patch
900 patch 0002-myfeature-interface.patch
902 include cfg/myfeature_dependency.scc
903 kconf non-hardware myfeature.cfg
905Features are typically less granular than configuration fragments and are more
906likely than configurations fragments and patches to be the types of things you
907will want to specify in the KERNEL_FEATURES variable of the Linux kernel recipe
908(see 3.1).
909 </literallayout>
910 </para>
911 </section> 566 </section>
912 567
913 <section id='kernel-types'> 568 <section id='kernel-types'>
@@ -1003,58 +658,6 @@ will want to specify in the KERNEL_FEATURES variable of the Linux kernel recipe
1003 See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>" 658 See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
1004 section for more information. 659 section for more information.
1005 </note> 660 </note>
1007 <para>
1008 Original text:
1009 <literallayout class='monospaced'>
1010Kernel types, or ktypes, are used to aggregate all non-hardware configuration
1011fragments together with any patches you want to use for all Linux kernel builds
1012of the specified ktype. In short, ktypes are where you define a high-level
1013kernel policy. Syntactically, however, they are no different than features (see
10143.3.3). preempt-rt, and tiny. The ktype is selected by the LINUX_KERNEL_TYPE
1015variable in the recipe (see 3.1).
1017By way of example, the linux-yocto-3.4 tree defines three ktypes: standard,
1018tiny, and preempt-rt. The standard kernel type includes the generic Linux kernel
1019policy of the Yocto Project linux-yocto kernel recipes. This includes things
1020like which filesystems, which networking options, which core kernel features,
1021and which debugging and tracing optoins are supported. The preempt-rt kernel
1022type applies the PREEMPT_RT patches and the configuration options required to
1023build a real-time Linux kernel. It inherits from standard. The tiny kernel type
1024is independent from the standard configuration and defines a bare minimum
1025configuration meant to serve as a base for very small Linux kernels. Tiny does
1026not currently include any source changes, but it may in the future.
1028The standard ktype is defined by standard.scc:
1029 # Include this kernel type fragment to get the standard features and
1030 # configuration values.
1032 # Include all standard features
1033 include standard-nocfg.scc
1035 kconf non-hardware standard.cfg
1037 # individual cfg block section
1038 include cfg/fs/devtmpfs.scc
1039 include cfg/fs/debugfs.scc
1040 include cfg/fs/btrfs.scc
1041 include cfg/fs/ext2.scc
1042 include cfg/fs/ext3.scc
1043 include cfg/fs/ext4.scc
1045 include cfg/net/ipv6.scc
1046 include cfg/net/ip_nf.scc
1047 include cfg/net/ip6_nf.scc
1048 include cfg/net/bridge.scc
1050As with any scc file, a ktype definition can aggregate other scc files with the
1051include command, or directly pull in configuration fragments and patches with
1052the kconf and patch commands, respectively.
1054Note: It is not strictly necessary to create a ktype scc file. The BSP file can
1055 define the ktype implicitly with a "define KTYPE myktype" line. See 3.3.5.
1056 </literallayout>
1057 </para>
1058 </section> 661 </section>
1059 662
1060 <section id='bsp-descriptions'> 663 <section id='bsp-descriptions'>
@@ -1246,130 +849,6 @@ Note: It is not strictly necessary to create a ktype scc file. The BSP file can
1246 Of these variables, only the <filename>KTYPE</filename> has changed. 849 Of these variables, only the <filename>KTYPE</filename> has changed.
1247 It is now set to "tiny". 850 It is now set to "tiny".
1248 </para> 851 </para>
1250 <para>
1251 Original text:
1252 <literallayout class='monospaced'>
1253BSP descriptions combine kernel types (see 3.3.4) with hardware-specific
1254features (see 3.3.3). The hardware specific portion is typically defined
1255independently, and then aggregated with each supported kernel type. Consider a
1256simple example:
1259 define KMACHINE mybsp
1260 define KTYPE standard
1261 define KARCH i386
1263 kconf mybsp.cfg
1265Every BSP description should include the definition of the KMACHINE, KTYPE, and
1266KARCH variables. These variables allow the build-system to identify this
1267description as meeting the criteria set by the recipe being built. This
1268particular description can be said to support the "mybsp" machine for the
1269"standard" kernel type and the "i386" architecture. Note that there is no hard
1270link between the KTYPE and a ktype description file. If you do not have kernel
1271types defined in your meta-data, you only need to ensure that the recipe
1272LINUX_KERNEL_TYPE and the KTYPE here match.
1274NOTE: future versions of the tooling make the specification of KTYPE in the BSP
1275 optional.
1277If you did want to separate your kernel policy from your hardware configuration,
1278you could do so by specifying a kernel type, such as "standard" (see 3.3.4) and
1279including that description in the BSP description. You might also have multiple
1280hardware configurations that you aggregate into a single hardware description
1281file which you could include here, rather than referencing a single .cfg file.
1282Consider the following:
1285 define KMACHINE mybsp
1286 define KTYPE standard
1287 define KARCH i386
1289 include standard.scc
1290 include mybsp.scc
1292In the above example standard.scc aggregates all the configuration fragments,
1293patches, and features that make up your standard kernel policy whereas mybsp.scc
1294aggregates all those necessary to support the hardware available on the mybsp
1295machine. For information on how to break a complete .config into the various
1296fragments, see 2.3.1.
1298Many real-world examples are more complex. Like any other scc file, BSP
1299descriptions can aggregate features. Consider the Fish River Island II (fri2)
1300BSP definitions from the linux-yocto-3.4 repository:
1303 kconf hardware fri2.cfg
1305 include cfg/x86.scc
1306 include features/eg20t/eg20t.scc
1307 include cfg/dmaengine.scc
1308 include features/ericsson-3g/f5521gw.scc
1309 include features/power/intel.scc
1310 include cfg/efi.scc
1311 include features/usb/ehci-hcd.scc
1312 include features/usb/ohci-hcd.scc
1313 include features/iwlwifi/iwlwifi.scc
1315The fri2.scc description file includes a hardware configuration fragment
1316(fri2.cfg) specific to the fri2 BSP as well as several more general
1317configuration fragments and features enabling hardware found on the fri2. This
1318description is then included in each of the three machine-ktype descriptions
1319(standard, preempt-rt, and tiny). Consider the fri2 standard description:
1322 define KMACHINE fri2
1323 define KTYPE standard
1324 define KARCH i386
1326 include ktypes/standard/standard.scc
1327 branch fri2
1329 git merge emgd-1.14
1331 include fri2.scc
1333 # Extra fri2 configs above the minimal defined in fri2.scc
1334 include cfg/efi-ext.scc
1335 include features/drm-emgd/drm-emgd.scc
1336 include cfg/vesafb.scc
1338 # default policy for standard kernels
1339 include cfg/usb-mass-storage.scc
1341Note the "include fri2.scc" line about midway through the file. By defining all
1342hardware enablement common to the BSP for all kernel types, duplication is
1343significantly reduced.
1345This description introduces a few more variables and commands worthy of further
1346discussion. Note the "branch" command which is used to create a
1347machine-specific branch into which source changes can be applied. With this
1348branch set up, the "git merge" command uses the git SCM to merge in a feature
1349branch "emgd-1.14". This could also be handled with the patch command, but for
1350commonly used features such as this, feature branches can be a convenient
1351mechanism (see 3.5).
1353Next consider the fri2 tiny description:
1356 define KMACHINE fri2
1357 define KTYPE tiny
1358 define KARCH i386
1360 include ktypes/tiny/tiny.scc
1361 branch fri2
1363 include fri2.scc
1365As you might expect, the tiny description includes quite a bit less. In fact,
1366it includes only the minimal policy defined by the tiny ktype and the
1367hardware-specific configuration required for boot and the most basic
1368functionality of the system as defined in the base fri2 description file. Note
1369again the three critical variables: KMACHINE, KTYPE, and KARCH. Of these, only
1370the KTYPE has changed, now set to "tiny".
1371 </literallayout>
1372 </para>
1373 </section> 852 </section>
1374</section> 853</section>
1375 854
@@ -1521,86 +1000,6 @@ the KTYPE has changed, now set to "tiny".
1521 would have to create a file and a directory named "standard". 1000 would have to create a file and a directory named "standard".
1522 </note> 1001 </note>
1523 </para> 1002 </para>
1525 <para>
1526 Original text:
1527 <literallayout class='monospaced'>
1528Section 3.1 introduced the KBRANCH variable which defines the source branch to
1529use from the Linux kernel git repository you are using. Many linux-yocto-custom
1530derived recipes will be using Linux kernel sources with only a single branch:
1531"master". However, when you are working with multiple boards and architectures,
1532you are likely to run into the situation where a series of patches are needed
1533for one board to boot. Sometimes these patches are works in progress or
1534fundamentally wrong, yet still necessary for specific boards. In these
1535situations, you most likely do not want to include these patches in every kernel
1536you build. You have a couple of options.
1538First, you could encapsulate these patches in a feature description and only
1539include them in the BSP description for the board(s) that require them (see
15403.3.2 and 3.3.5).
1542Alternatively, you can create a branch in your Linux kernel sources and apply
1543the patches there. You can then specify this new branch as the KBRANCH to use
1544for this board. You can do this in the recipe with the KBRANCH variable:
1546 KBRANCH = "mynewbranch"
1548or in the BSP description using the "branch" command:
1551 define KMACHINE mybsp
1552 define KTYPE standard
1553 define KARCH i386
1554 include standard.scc
1556 branch mynewbranchIf you are actively
1557working on board support, you may find that working within a branch is more
1558practical than trying to continually reintegrate your patches into a feature. On
1559the other hand, if you are simply reusing some patches from an external tree and
1560are not working on them, you may find the encapsulated feature to be appropriate
1561as it does not require the additional complexity of branching in your Linux
1562kernel sources
1564 include mybsp.scc
1566The decision of which approach to take, feature or branch, is entirely up to you
1567and depends on what works best for your development model. If you are actively
1568working on board support, you may find that working within a branch is more
1569practical than trying to continually reintegrate your patches into a feature. On
1570the other hand, if you are simply reusing some patches from an external tree and
1571are not working on them, you may find the encapsulated feature to be appropriate
1572as it does not require the additional complexity of branching in your Linux
1573kernel sources.
1575If you are supporting multiple boards and architectures and find yourself with
1576numerous branches, you might consider using a hierarchical branching system
1577similar to what the linux-yocto Linux kernel repositories use:
1579 &lt;common&gt;/&lt;ktype&gt;/&lt;machine&gt;
1581If you had two ktypes, standard and small for instance, and three machines, your
1582git tree might look like this:
1584 common/base
1585 common/standard/base
1586 common/standard/machine_a
1587 common/standard/machine_b
1588 common/standard/machine_c
1589 common/small/base
1590 common/small/machine_a
1592This organization can help clarify the relationship of the branches to
1593each other. In this case, "common/standard/machine_a" would include everything in
1594"common/base" and "common/standard/base". The "standard" and "small" branches
1595add sources specific to those kernel types that for whatever reason are not
1596appropriate for the other branches.
1598Note: The "base" branches are an artifact of the way git manages its data
1599 internally on the filesystem: it will not allow you to use
1600 "common/standard" and "common/standard/machine_a" because it would have to
1601 create a file and a directory named "standard".
1602 </literallayout>
1603 </para>
1604 </section> 1003 </section>
1605 1004
1606 <section id='feature-branches'> 1005 <section id='feature-branches'>
@@ -1631,30 +1030,6 @@ Note: The "base" branches are an artifact of the way git manages its data
1631 include mybsp-hw.scc 1030 include mybsp-hw.scc
1632 </literallayout> 1031 </literallayout>
1633 </para> 1032 </para>
1635 <para>
1636 Original text:
1637 <literallayout class='monospaced'>
1638During active development a new feature, it can be more efficient to work with
1639that feature as a branch, rather than as a set of patches which have to be
1640regularly updated. The Yocto Project Linux kernel tools provide for this with
1641the "git merge" command.
1643To merge a feature branch into a BSP, insert the "git merge" command after any
1644branch commands:
1647 define KMACHINE mybsp
1648 define KTYPE standard
1649 define KARCH i386
1650 include standard.scc
1652 branch mynewbranch
1653 git merge myfeature
1655 include mybsp.scc
1656 </literallayout>
1657 </para>
1658 </section> 1033 </section>
1659</section> 1034</section>
1660 1035
@@ -1687,39 +1062,6 @@ mybsp.scc:
1687 Applies the patch to the current Git branch.</para></listitem> 1062 Applies the patch to the current Git branch.</para></listitem>
1688 </itemizedlist> 1063 </itemizedlist>
1689 </para> 1064 </para>
1691 <para>
1692 Original text:
1693 <literallayout class='monospaced'>
1694* branch [ref]
1696 Create a new branch relative to the current branch (typically ${KTYPE}) using
1697 the currently checked-out branch, or "ref" if specified.
1699 TODO: Bruce, we need to clarify the "relative to the current branch" bit.
1701* define
1703 Define variables, such as KMACHINE, KTYPE, KARCH, and KFEATURE_DESCRIPTION.
1705* include SCC_FILE
1707 Include an scc file in the current file. It will be parsed as if inserted
1708 inline.
1710* kconf [hardware|non-hardware] CFG_FILE
1712 Queue a configuration fragment for merging into the final Linux .config file.
1714* merge (or "git merge") GIT_BRANCH
1716 Merge the feature branch into the current branch.
1718* patch PATCH_FILE
1720 Apply the patch to the current git branch.
1721 </literallayout>
1722 </para>
1723</section> 1065</section>
1724 1066
1725</chapter> 1067</chapter>