summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-01-14 12:16:50 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-01-16 15:59:21 +0000
commit29d5511d026f365b2db68b8e87a487515d82cc69 (patch)
tree5245e30213b7bd868b7ba3e1e9ea5fb7c92ccec0
parent5487eeb730bd4ea4ab188c74352d80b4f5f413f8 (diff)
downloadpoky-29d5511d026f365b2db68b8e87a487515d82cc69.tar.gz
kernel-dev: Edits to Advanced Metadata chapter
Removed all the orginal text. (From yocto-docs rev: 8a3b11fb6936574edb4fd0daf60d21ee2c2ccd8f) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/kernel-dev/kernel-dev-advanced.xml658
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 adfd774a41..df3f30141a 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>
41
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 (kern-tools-native_git.bb), is to assist in managing the
49complexity of the configuration and sources in support of multiple BSPs and
50Linux kernel types.
51
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>
200
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.
208
209Every linux-yocto style recipe must define the following variables:
210
211 KMACHINE
212
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".
218
219They may optionally define the following variables:
220 KBRANCH
221 KERNEL_FEATURES
222 KBRANCH_DEFAULT
223 LINUX_KERNEL_TYPE
224
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:
229
230KBRANCH_fri2 = "standard/fri2"
231
232Unless you specify otherwise, KBRANCH_DEFAULT is initialized to "master".
233
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.
241
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:
246
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
251
252 In this example KMACHINE was set to "fri2-broken" and LINUX_KERNEL_TYPE
253 was set to "broken".
254
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.
258
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:
263
264KERNEL_FEATURES += "features/netfilter.scc"
265
266To include a feature called "cfg/sound.scc" just for the qemux86 machine,
267specify:
268
269KERNEL_FEATURES_append_qemux86 = "cfg/sound.scc"
270
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.
275
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).
324
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.
331
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
336environment.
337
338Regardless of where the meta-data is stored, the syntax as
339described in the following sections applies equally.
340 </literallayout>
341 </para>
342
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>
389
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.
396
397By way of example, a trivial tree of meta-data stored in recipe-space within a
398BSP layer might look like the following:
399
400meta/
401`-- recipes-kernel
402 `-- linux
403 `-- linux-yocto
404 |-- bsp-standard.scc
405 |-- bsp.cfg
406 `-- standard.cfg
407
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.
411
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>
477
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"
489directory.
490
491By way of example, a trivial tree of meta-data stored in a custom Linux kernel
492git repository might look like the following:
493
494meta/
495`-- cfg
496 `-- kernel-cache
497 |-- bsp-standard.scc
498 |-- bsp.cfg
499 `-- standard.cfg
500
501To use a specific branch for the meta-data, specify the branch in the KMETA
502variable in your Linux kernel recipe, for example:
503
504 KMETA = "meta"
505
506To use the same branch as the sources, set KMETA to the empty string:
507
508 KMETA = ""
509
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:
513
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.
647
648The scc description files are used to define two fundamental types of meta-data:
649 o Features
650 o BSPs
651
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.
657
658BSPs define hardware-specific features and aggregate them with kernel types to
659form the final description of what will be assembled and built.
660
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:
665
666 &lt;base&gt;/
667 bsp/
668 cfg/
669 features/
670 ktypes/
671 patches/
672
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.
687
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).
691
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>
697
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>
760
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
768files:
769
770cfg/smp.scc:
771 define KFEATURE_DESCRIPTION "Enable SMP"
772 kconf hardware smp.cfg
773
774cfg/smp.cfg:
775 CONFIG_SMP=y
776 CONFIG_SCHED_SMT=y
777
778See 2.3.1 for details on creating configuration fragments.
779
780KFEATURE_DESCRIPTION provides a short description of the fragment, the
781primary use is for higher level tooling, such as the Yocto Project BSP Tools
782(TODO:Citation).
783
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.
790
791As described in 2.3.1, the following bitbake command can be used to audit your
792configuration:
793
794 $ bitbake linux-yocto -c kernel_configcheck -f
795
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>
829
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:
836
837patches/mypatch.scc:
838 patch mypatch.patch
839
840patches/mypatch.patch:
841 &lt;typical patch created with 'diff -Nurp' or 'git format-patch'&gt;
842
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>
884
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.
892
893A hypothetical example of a feature description file might look like the
894following:
895
896features/myfeature.scc
897 define KFEATURE_DESCRIPTION "Enable myfeature"
898
899 patch 0001-myfeature-core.patch
900 patch 0002-myfeature-interface.patch
901
902 include cfg/myfeature_dependency.scc
903 kconf non-hardware myfeature.cfg
904
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>
1006
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).
1016
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.
1027
1028The standard ktype is defined by standard.scc:
1029 # Include this kernel type fragment to get the standard features and
1030 # configuration values.
1031
1032 # Include all standard features
1033 include standard-nocfg.scc
1034
1035 kconf non-hardware standard.cfg
1036
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
1044
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
1049
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.
1053
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>
1249
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:
1257
1258mybsp.scc:
1259 define KMACHINE mybsp
1260 define KTYPE standard
1261 define KARCH i386
1262
1263 kconf mybsp.cfg
1264
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.
1273
1274NOTE: future versions of the tooling make the specification of KTYPE in the BSP
1275 optional.
1276
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:
1283
1284mybsp.scc:
1285 define KMACHINE mybsp
1286 define KTYPE standard
1287 define KARCH i386
1288
1289 include standard.scc
1290 include mybsp.scc
1291
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.
1297
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:
1301
1302fri2.scc:
1303 kconf hardware fri2.cfg
1304
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
1314
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:
1320
1321fri2-standard.scc:
1322 define KMACHINE fri2
1323 define KTYPE standard
1324 define KARCH i386
1325
1326 include ktypes/standard/standard.scc
1327 branch fri2
1328
1329 git merge emgd-1.14
1330
1331 include fri2.scc
1332
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
1337
1338 # default policy for standard kernels
1339 include cfg/usb-mass-storage.scc
1340
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.
1344
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).
1352
1353Next consider the fri2 tiny description:
1354
1355fri2-tiny.scc:
1356 define KMACHINE fri2
1357 define KTYPE tiny
1358 define KARCH i386
1359
1360 include ktypes/tiny/tiny.scc
1361 branch fri2
1362
1363 include fri2.scc
1364
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>
1524
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.
1537
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).
1541
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:
1545
1546 KBRANCH = "mynewbranch"
1547
1548or in the BSP description using the "branch" command:
1549
1550mybsp.scc:
1551 define KMACHINE mybsp
1552 define KTYPE standard
1553 define KARCH i386
1554 include standard.scc
1555
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
1563
1564 include mybsp.scc
1565
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.
1574
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:
1578
1579 &lt;common&gt;/&lt;ktype&gt;/&lt;machine&gt;
1580
1581If you had two ktypes, standard and small for instance, and three machines, your
1582git tree might look like this:
1583
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
1591
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.
1597
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>
1634
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.
1642
1643To merge a feature branch into a BSP, insert the "git merge" command after any
1644branch commands:
1645
1646mybsp.scc:
1647 define KMACHINE mybsp
1648 define KTYPE standard
1649 define KARCH i386
1650 include standard.scc
1651
1652 branch mynewbranch
1653 git merge myfeature
1654
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>
1690
1691 <para>
1692 Original text:
1693 <literallayout class='monospaced'>
1694* branch [ref]
1695
1696 Create a new branch relative to the current branch (typically ${KTYPE}) using
1697 the currently checked-out branch, or "ref" if specified.
1698
1699 TODO: Bruce, we need to clarify the "relative to the current branch" bit.
1700
1701* define
1702
1703 Define variables, such as KMACHINE, KTYPE, KARCH, and KFEATURE_DESCRIPTION.
1704
1705* include SCC_FILE
1706
1707 Include an scc file in the current file. It will be parsed as if inserted
1708 inline.
1709
1710* kconf [hardware|non-hardware] CFG_FILE
1711
1712 Queue a configuration fragment for merging into the final Linux .config file.
1713
1714* merge (or "git merge") GIT_BRANCH
1715
1716 Merge the feature branch into the current branch.
1717
1718* patch PATCH_FILE
1719
1720 Apply the patch to the current git branch.
1721 </literallayout>
1722 </para>
1723</section> 1065</section>
1724 1066
1725</chapter> 1067</chapter>