summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev/kernel-dev-advanced.xml
blob: 8b626e5ec9ba3bdc5d2c725aefc2b7d5ab7ec137 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

<chapter id='kernel-dev-advanced'>

<title>Working with Advanced Metadata</title>

    <para>
        In addition to supporting configuration fragments and patches, the
        Yocto Project kernel tools also support rich
        <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> that you can
        use to define complex policies and Board Support Package (BSP) support.
        The purpose of the Metadata and the tools that manage it, known as
        the kern-tools (<filename>kern-tools-native_git.bb</filename>), is
        to help you manage the complexity of the configuration and sources
        used to support multiple BSPs and Linux kernel types.
    </para>

    <para>
        In particular, the kernel tools allow you to specify only what you
        must, and nothing more.
        Where a complete Linux kernel <filename>.config</filename> includes
        all the automatically selected <filename>CONFIG</filename> options,
        the configuration fragments only need to contain the highest level
        visible <filename>CONFIG</filename> options as presented by the Linux
        kernel <filename>menuconfig</filename> system.
        This reduces your maintenance effort and allows you
        to further separate your configuration in ways that make sense for
        your project.
        A common split is policy and hardware.
        For example, all your kernels might support
        the <filename>proc</filename> and <filename>sys</filename> filesystems,
        but only specific boards will require sound, USB, or specific drivers.
        Specifying these individually allows you to aggregate them
        together as needed, but maintain them in only one place.
        Similar logic applies to source changes.
    </para>

    <para>
        Original Text:
        <literallayout class='monospaced'>
In addition to configuration fragments and patches, the Yocto Project kernel
tools support rich metadata which you can use to define complex policies and
BSP support. The purpose of the metadata and the tools to manage it, known as
the kern-tools (kern-tools-native_git.bb), is to assist in managing the
complexity of the configuration and sources in support of multiple BSPs and
Linux kernel types.

In particular, the kernel tools allow you to specify only what you must, and
nothing more.  Where a complete Linux kernel .config includes all the
automatically selected CONFIG options, the configuration fragments only need to
contain the highest level visible CONFIG options as presented by the Linux
kernel menuconfig system. This reduces your maintenance effort and allows you
to further separate your configuration in ways that make sense for your project.
A common split is policy and hardware. For example, all your kernels may support
the proc and sys filesystems, but only specific boards will require sound, usb,
or specific drivers. Specifying these individually allows you to aggregate them
together as needed, but maintain them in only one place. Similar logic applies
to source changes.
        </literallayout>
    </para>

<section id='using-metadata-in-a-recipe'>
    <title>Using Metadata in a Recipe</title>

    <para>
        The metadata provided with any linux-yocto style Linux kernel sources
        must define a BSP that corresponds to the definition laid out in the
        recipe.
        A BSP consists of an aggregation of kernel policy and hardware specific
        feature enablement.
        This can be influenced from within the recipe.
    </para>

    <para>
        Every linux-yocto style recipe must define the following variable:
        <literallayout class='monospaced'>
     KMACHINE
        </literallayout>
        <filename>KMACHINE</filename> is typically set to the same value as
        used within the recipe-space BSP definition, such as "routerstationpro"
        or "fri2".
        However, multiple BSPs can reuse the same <filename>KMACHINE</filename>
        name if they are built using the same BSP description.
        See section 3.3.5 for more information.
        The <filename>meta-intel</filename> "fri2" and "fri2-noemgd" are good
        examples of such a situation where each specifies
        <filename>KMACHINE</filename> as "fri2".
    </para>

    <para>
        They may optionally define the following variables:
        <literallayout class='monospaced'>
     KBRANCH
     KERNEL_FEATURES
     KBRANCH_DEFAULT
     LINUX_KERNEL_TYPE
        </literallayout>
        <filename>KBRANCH_DEFAULT</filename> defines the default source branch
        within the Linux kernel source repository to be used to build the
        Linux kernel.
        It is used as the default value for <filename>KBRANCH</filename> which
        may define an alternate branch, typically with a machine override,
        such as:
        <literallayout class='monospaced'>
     KBRANCH_fri2 = "standard/fri2"
        </literallayout>
        Unless you specify otherwise, <filename>KBRANCH_DEFAULT</filename>
        is initialized to "master".
    </para>

    <para>
        <filename>LINUX_KERNEL_TYPE</filename> defines the kernel type to be
        used in assembling the configuration and defaults to "standard"
        if you do not specify otherwise.
        Together with <filename>KMACHINE</filename>, this defines the search
        arguments used by the Yocto Project Linux kernel tools to find the
        appropriate description within the metadata with which to build out
        the sources and configuration.
        The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
        kernel types.
        See section 3.3.4 for more inforation on kernel types.
    </para>

    <para>
        During the build, the kern-tools will search for the BSP description
        file that most closely matches the <filename>KMACHINE</filename>
        and <filename>LINUX_KERNEL_TYPE</filename> passed in from the
        recipe.
        It will use the first BSP description it finds matching both variables.
        Failing that it will issue a warning such as the following:
        <literallayout class='monospaced'>
     WARNING: Can't find any BSP hardware or required configuration fragments.
     WARNING: Looked at meta/cfg/broken/fri2-broken/hdw_frags.txt and
              meta/cfg/broken/fri2-broken/required_frags.txt in directory:
              meta/cfg/broken/fri2-broken
        </literallayout>
        In this example, <filename>KMACHINE</filename> was set to "fri2-broken"
        and <filename>LINUX_KERNEL_TYPE</filename> was set to "broken".
    </para>

    <para>
        It will then search first for the <filename>KMACHINE</filename> and
        then for the <filename>LINUX_KERNEL_TYPE</filename>.
        If it cannot find a partial match, it will use the
        sources from the <filename>KBRANCH</filename> and any configuration
        specified in the <filename>SRC_URI</filename>.
    </para>

    <para>
        <filename>KERNEL_FEATURES</filename> can be used to include features
        (configuration fragments, patches, or both) that are not already
        included by the <filename>KMACHINE</filename> and
        <filename>LINUX_KERNEL_TYPE</filename> combination.
        To include a feature specified as "features/netfilter.scc" for example,
        specify:
        <literallayout class='monospaced'>
     KERNEL_FEATURES += "features/netfilter.scc"
        </literallayout>
        To include a feature called "cfg/sound.scc" just for the
        <filename>qemux86</filename> machine, specify:
        <literallayout class='monospaced'>
     KERNEL_FEATURES_append_qemux86 = "cfg/sound.scc"
        </literallayout>
        The value of the entries in <filename>KERNEL_FEATURES</filename>
        are dependent on their location within the metadata itself.
        The examples here are taken from the
        <filename>linux-yocto-3.4</filename> repository where "features"
        and "cfg" are subdirectories of the <filename>metadata</filename>
        directory.
        For details, see section 3.3.
        <note>
            The processing of the these variables has evolved some between the
	        0.9 and 1.3 releases of the Yocto Project and associated
	        kern-tools sources.
            The descriptions in this section are accurate for 1.3 and later
	        releases of the Yocto Project.
        </note>
    </para>

    <para>
        Original Text.
        <literallayout class='monospaced'>
The metadata provided with any linux-yocto style Linux kernel sources must
define a BSP that corresponds to the definition laid out in the recipe. A BSP
consists of an aggregation of kernel policy and hardware specific feature
enablement. This can be influenced from within the recipe.

Every linux-yocto style recipe must define the following variables:

	KMACHINE

KMACHINE is typically set to the same value as used within the recipe-space BSP
definition, such as "routerstationpro" or "fri2". However, multiple BSPs can
reuse the same KMACHINE name if they are built using the same BSP description
(see 3.3.5). The meta-intel "fri2" and "fri2-noemgd" are good examples of such
a situation where each specifies KMACHINE as "fri2".

They may optionally define the following variables:
	KBRANCH
	KERNEL_FEATURES
	KBRANCH_DEFAULT
	LINUX_KERNEL_TYPE

KBRANCH_DEFAULT defines the default source branch within the Linux kernel source
repository to be used to build the Linux kernel. It is used as the default value
for KBRANCH which may define an alternate branch, typically with a machine
override, such as:

KBRANCH_fri2 = "standard/fri2"

Unless you specify otherwise, KBRANCH_DEFAULT is initialized to "master".

LINUX_KERNEL_TYPE defines the kernel type to be used in assembling the
configuration and defaults to "standard" if you do not specify otherwise.
Together with KMACHINE, this defines the search arguments used by the Yocto
Project Linux kernel tools to find the appropriate description within the
metadata with which to build out the sources and configuration. The linux-yocto
recipes define "standard", "tiny", and "preempt-rt" kernel types. See 3.3.4 for
more inforation on kernel types.

During the build, the kern-tools will search for the BSP description file that
most closely matches the KMACHINE and LINUX_KERNEL_TYPE passed in from the
recipe. It will use the first BSP description it finds matching both variables.
Failing that it will issue a warning such as the following:

	WARNING: Can't find any BSP hardware or required configuration fragments.
	WARNING: Looked at meta/cfg/broken/fri2-broken/hdw_frags.txt and
	         meta/cfg/broken/fri2-broken/required_frags.txt in directory:
	         meta/cfg/broken/fri2-broken

	In this example KMACHINE was set to "fri2-broken" and LINUX_KERNEL_TYPE
	was set to "broken".

It will then search first for the KMACHINE and then
for the LINUX_KERNEL_TYPE. If it cannot find a partial match, it will use the
sources from the KBRANCH and any configuration specified in the SRC_URI.

KERNEL_FEATURES can be used to include features (configuration fragments,
patches, or both) that are not already included by the KMACHINE and
LINUX_KERNEL_TYPE combination. To include a feature specified as
"features/netfilter.scc" for example, specify:

KERNEL_FEATURES += "features/netfilter.scc"

To include a feature called "cfg/sound.scc" just for the qemux86 machine,
specify:

KERNEL_FEATURES_append_qemux86 = "cfg/sound.scc"

The value of the entries in KERNEL_FEATURES are dependent on their location
within the metadata itself. The examples here are taken from the
linux-yocto-3.4 repository where "features" and "cfg" are subdirectories of the
metadata directory. For details, see 3.3.

	Note: The processing of the these variables has evolved some between the
	      0.9 and 1.3 releases of the Yocto Project and associated
	      kern-tools sources. The above is accurate for 1.3 and later
	      releases of the Yocto Project.
        </literallayout>
    </para>
</section>

<section id='metadata-location'>
    <title>Metadata Location</title>

    <para>
        This metadata can be defined along with the Linux kernel
        recipe (recipe-space) as partially described in the
        "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
        section as well as within the Linux kernel sources themselves
        (in-tree).
    </para>

    <para>
        Where you choose to store the metadata depends on what you want
        to do and how you intend to work.
        If you are unfamiliar with the Linux kernel and only wish
        to apply a config and possibly a couple of patches provided to
        you by others, you may find the recipe-space mechanism to be easier
        to work with.
        This is also a good approach if you are working with Linux kernel
        sources you do not control or if you just don't want to maintain a
        Linux kernel git repository on your own.
    </para>

    <para>
        If you are doing active kernel development and are already
        maintaining a Linux kernel git repository of your own, you may find
        it more convenient to work with the metadata in the same
        repository as the Linux kernel sources.
        This can make iterative development of the Linux kernel more efficient
        outside of the BitBake environment.

    </para>

    <para>
        Regardless of where the meta-data is stored, the syntax as
        described in the following sections applies equally.
    </para>

    <para>
        Original Text:
        <literallayout class='monospaced'>
This meta-data can be defined along with the Linux kernel recipe (recipe-space)
as partially described in section 2.2 as well as within the Linux kernel sources
themselves (in-tree).

Where you choose to store the meta-data depends on what you want to do and how
you intend to work. If you are unfamiliar with the Linux kernel and only wish
to apply a config and possibly a couple of patches provided to you by others,
you may find the recipe-space mechanism to be easier to work with. This is also
a good approach if you are working with Linux kernel sources you do not control
or if you just don't want to maintain a Linux kernel git repository on your own.

If you are doing active kernel development and are already maintaining a Linux
kernel git repository of your own, you may find it more convenient to work with
the meta-data in the same repository as the Linux kernel sources. This can make
iterative development of the Linux kernel more efficient outside of the bitbake
environment.

Regardless of where the meta-data is stored, the syntax as
described in the following sections applies equally.
        </literallayout>
    </para>

    <section id='recipe-space-metadata'>
        <title>Recipe-Space Metadata</title>

        <para>
            When stored in recipe-space, the metadata files reside in a
            directory hierarchy below
            <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>,
            which is typically set to
            <filename>${THISDIR}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
            for a linux-yocto or linux-yocto-custom derived Linux kernel
            recipe.
            See the "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
            section for more information.
        </para>

        <para>
            By way of example, a trivial tree of metadata stored in
            recipe-space within a BSP layer might look like the following:
            <literallayout class='monospaced'>
     meta/
     `-- recipes-kernel
         `-- linux
             `-- linux-yocto
                 |-- bsp-standard.scc
                 |-- bsp.cfg
                 `-- standard.cfg
            </literallayout>
        </para>

        <para>
            When the metadata is stored in recipe-space, you must take
            steps to ensure BitBake has the necessary information to decide
            which files to fetch and when they need to be fetched again.
        </para>

        <para>
            It is only necessary to specify the <filename>.scc</filename>
            files on the
            <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
            BitBake parses them and fetches any files referenced in the
            <filename>.scc</filename> files by the <filename>include</filename>,
            <filename>patch</filename>, or <filename>kconf</filename> commands.
            Because of this, it is necessary to bump the recipe
            <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
            value when changing the content of files not explicitly listed
            in the SRC_URI.
        </para>

        <para>
            Original text:
            <literallayout class='monospaced'>
When stored in recipe-space, the meta-data files reside in a directory hierarchy
below FILESEXTRAPATHS, which is typically set to ${THISDIR}/${PN} for a
linux-yocto or linux-yocto-custom derived Linux kernel recipe. See 2.2.

By way of example, a trivial tree of meta-data stored in recipe-space within a
BSP layer might look like the following:

meta/
`-- recipes-kernel
    `-- linux
        `-- linux-yocto
            |-- bsp-standard.scc
            |-- bsp.cfg
            `-- standard.cfg

When the meta-data is stored in recipe-space, you must take steps to ensure
bitbake has the necessary information to decide which files to fetch and when
they need to be fetched again.

It is only necessary to specify the .scc files on the SRC_URI; bitbake will
parse them and fetch any files referenced in the .scc files by the include,
patch, or kconf commands. Because of this, it is necessary to bump the recipe PR
value when changing the content of files not explicitly listed in the SRC_URI.
            </literallayout>
        </para>
    </section>

    <section id='in-tree-metadata'>
        <title>In-Tree Metadata</title>

        <para>
            When stored in-tree, the metadata files reside in the
            "meta" directory of the Linux kernel sources.
            They may be present in the same branch as the sources,
            such as "master", or in their own orphan branch,
            typically named "meta".
            An orphan branch in Git is a branch with unique history and
            content to the other branches in the repository.
            This is useful to track metadata changes independently from the
            sources of the Linux kernel, while still keeping them
            together in the same repository.
            For the purposes of this document, we will discuss all
            in-tree metadata as residing below the
            <filename>meta/cfg/kernel-cache</filename> directory.
        </para>

        <para>
            By way of example, a trivial tree of metadata stored in a custom
            Linux kernel Git repository might look like the following:
            <literallayout class='monospaced'>
     meta/
     `-- cfg
         `-- kernel-cache
             |-- bsp-standard.scc
             |-- bsp.cfg
             `-- standard.cfg
            </literallayout>
        </para>

        <para>
            To use a specific branch for the metadata, specify the branch
            in the <filename>KMETA</filename> variable in your Linux kernel
            recipe, for example:
            <literallayout class='monospaced'>
     KMETA = "meta"
            </literallayout>
            To use the same branch as the sources, set
            <filename>KMETA</filename> to the empty string:
            <literallayout class='monospaced'>
     KMETA = ""
            </literallayout>
            If you are working with your own sources and want to create an
            orphan <filename>meta</filename> branch, you can do so using the
            following commands from within your Linux kernel Git repository:
            <literallayout class='monospaced'>
     $ git checkout --orphan meta
     $ git rm -rf .
     $ git commit --allow-empty -m "Create orphan meta branch"
            </literallayout>
        </para>

        <para>
            Original text:
            <literallayout class='monospaced'>
When stored in-tree, the meta-data files reside in the "meta" directory of the
Linux kernel sources. They may be present in the same branch as the sources,
such as "master", or in their own orphan branch, typically named "meta". An
orphan branch in git is a branch with unique history and content to the other
branches in the repository. This is useful to track meta-data changes
independently from the sources of the Linux kernel, while still keeping them
together in the same repository. For the purposes of this document, we will
discuss all in-tree meta-data as residing below the "meta/cfg/kernel-cache"
directory.

By way of example, a trivial tree of meta-data stored in a custom Linux kernel
git repository might look like the following:

meta/
`-- cfg
    `-- kernel-cache
        |-- bsp-standard.scc
        |-- bsp.cfg
        `-- standard.cfg

To use a specific branch for the meta-data, specify the branch in the KMETA
variable in your Linux kernel recipe, for example:

	KMETA = "meta"

To use the same branch as the sources, set KMETA to the empty string:

	KMETA = ""

If you are working with your own sources and want to create an orphan meta
branch, you can do so using the following commands from within your Linux kernel
git repository:

	$ git checkout --orphan meta
	$ git rm -rf .
	$ git commit --allow-empty -m "Create orphan meta branch"
            </literallayout>
        </para>
    </section>
</section>

<section id='metadata-syntax'>
    <title>Metadata Syntax</title>

    <para>
        The Yocto Project Linux kernel tools metadata consists of three
        primary types of files: <filename>scc</filename>
        <footnote>
            <para>
                <filename>scc</filename> stands for Series Configuration
                Control, but the naming has less significance in the
                current implementation of the tooling than it had in the
                past.
                Consider it to be a description file.
            </para>
        </footnote>
        description files, configuration fragments, and patches.
        The <filename>scc</filename> files define variables and include or
        otherwise reference any of the three file types.
        The description files are used to aggregate all types of metadata into
        what ultimately describes the sources and the configuration required
        to build a Linux kernel tailored to a specific machine.
    </para>

    <para>
        The <filename>scc</filename> description files are used to define two
        fundamental types of metadata:
        <itemizedlist>
            <listitem><para>Features</para></listitem>
            <listitem><para>Board Support Packages (BSPs)</para></listitem>
        </itemizedlist>
    </para>

    <para>
        Features aggregate sources in the form of patches and configuration
        in the form of configuration fragments into a modular reusable unit.
        Features are used to implement conceptually separate metadata
        descriptions like pure configuration fragments, simple patches,
        complex features, and kernel types (ktypes).
        Kernel types define general kernel features and policy to be reused
        in the BSPs.
    </para>

    <para>
        BSPs define hardware-specific features and aggregate them with kernel
        types to form the final description of what will be assembled and built.
    </para>

    <para>
        While the metadata syntax does not enforce any logical separation of
        configuration fragments, patches, features or kernel types, best
        practices dictate a logical separation of these types of meta-data.
        The following metadata file hierarchy is recommended:
        <literallayout class='monospaced'>
     &lt;base&gt;/
        bsp/
        cfg/
        features/
        ktypes/
        patches/
        </literallayout>
    </para>

    <para>
        The <filename>bsp</filename> directory should contain the
        BSP descriptions, described in detail in section 3.3.5.
        The remaining directories all contain "features"; the separation
        is meant to aid in conceptualizing their intended usage.
        A simple guide to determine where your <filename>scc</filename>
        description file should go is as follows.
        If it contains only configuration fragments, it belongs in
        <filename>cfg</filename>.
        If it contains only source-code fixes, it belongs in
        <filename>patches</filename>.
        If it encapsulates a major feature, often combining sources and
        configurations, it belongs in <filename>features</filename>.
        If it aggregates non-hardware configuration and patches
        in order to define a base kernel policy or major kernel type to
        be reused across multiple BSPs, it belongs in
        <filename>ktypes</filename>.
    </para>

    <para>
        The lines between these can easily become blurred, especially as
        out-of-tree features are slowly merged upstream over time.
        Also remember that this is purely logical organization and has
        no impact on the functionality of the metadata as
        all of <filename>cfg</filename>, <filename>features</filename>,
        <filename>patches</filename>, and <filename>ktypes</filename>,
        contain "features" as far as the Yocto Project Linux kernel
        tools are concerned.
    </para>

    <para>
        Paths used in metadata files are relative to
        <filename>&lt;base&gt;</filename>, which is either
        <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
        if you are creating metadata in recipe-space as described in
        section "<link linkend='recipe-space-metadata'>Recipe-Space Metadata</link>",
        or <filename>meta/cfg/kernel-cache/</filename> if you are creating
        metadata in-tree as described in
        the "<link linkend='in-tree-metadata'>In-Tree Metadata</link>" section.
    </para>

    <para>
        Original text:
        <literallayout class='monospaced'>
The Yocto Project Linux kernel tools meta-data consists of three primary types
of files: scc* description files, configuration fragments, and patches. The scc
files define variables and include or otherwise reference any of the three file
types. The description files are used to aggregate all types of meta-data into
what ultimately describes the sources and the configuration required to build a
Linux kernel tailored to a specific machine.

The scc description files are used to define two fundamental types of meta-data:
	o Features
	o BSPs

Features aggregate sources in the form of patches and configuration in the form
of configuration fragments into a modular reusable unit. Features are used to
implement conceptually separate meta-data descriptions like pure configuration
fragments, simple patches, complex features, and kernel types (ktypes). Kernel
types define general kernel features and policy to be reused in the BSPs.

BSPs define hardware-specific features and aggregate them with kernel types to
form the final description of what will be assembled and built.

While the meta-data syntax does not enforce any logical separation of
configuration fragments, patches, features or kernel types, best practices
dictate a logical separation of these types of meta-data. The following
meta-data file hierarchy is recommended:

	&lt;base&gt;/
		bsp/
		cfg/
		features/
		ktypes/
		patches/

The bsp directory should contain the BSP descriptions, described in detail in
3.3.5. The remaining directories all contain "features"; the separation is meant
to aid in conceptualizing their intended usage.  A simple guide to determine
where your scc description file should go is as follows. If it contains only
configuration fragments, it belongs in cfg. If it contains only source-code
fixes, it belongs in patches. If it encapsulates a major feature, often
combining sources and configurations, it belongs in features. If it aggregates
non-hardware configuration and patches in order to define a base kernel policy
or major kernel type to be reused across multiple BSPs, it belongs in ktypes.
The line between these can easily become blurred, especially as out-of-tree
features are slowly merged upstream over time. Also remember that this is purely
logical organization and has no impact on the functionality of the meta-data as
all of cfg, features, patches, and ktypes, contain "features" as far as the
Yocto Project Linux kernel tools are concerned.

Paths used in meta-data files are relative to &lt;base&gt; which is either
FILESEXTRAPATHS if you are creating meta-data in recipe-space (see 3.2.1), or
meta/cfg/kernel-cache/ if you are creating meta-data in-tree (see 3.2.2).

* scc stands for Series Configuration Control, but the naming has less
  significance in the current implementation of the tooling than it had in the
  past. Consider it to be a description file.
        </literallayout>
    </para>

    <section id='configuration'>
        <title>Configuration</title>

        <para>
            The simplest unit of metadata is the configuration-only feature.
            It consists of one or more Linux kernel configuration parameters
            in a configuration fragment file (<filename>.cfg</filename>)
            and an <filename>scc</filename> file describing the fragment.
        </para>

        <para>
            The SMP fragment included in the linux-yocto-3.4 Git repository
            consists of the following two files:
            <literallayout class='monospaced'>
     cfg/smp.scc:
        define KFEATURE_DESCRIPTION "Enable SMP"
        kconf hardware smp.cfg

     cfg/smp.cfg:
        CONFIG_SMP=y
        CONFIG_SCHED_SMT=y
            </literallayout>
            You can find information on configuration fragment files in the
            "<ulink url='&YOCTO_DOCS_REF_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>"
            section of the Yocto Project Development Manual and in
            the "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
            section earlier in this manual.
        </para>

        <para>
            <filename>KFEATURE_DESCRIPTION</filename> provides a short
            description of the fragment, the primary use is for higher level
            tooling, such as the Yocto Project BSP Tools (TODO:Citation).
        </para>

        <para>
            The <filename>kconf</filename> command is used to include the
            actual configuration fragment in an <filename>scc</filename>
            file, and the "hardware" keyword identifies the fragment as
            being hardware enabling, as opposed to general policy,
            which would use the keyword "non-hardware".
            The distinction is made for the benefit of the configuration
            validation tools, which will warn you if a hardware fragment
            overrides a policy set by a non-hardware fragment.
        </para>

        <para>
            As described in the
            "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
            section, the following BitBake command can be used to audit your
            configuration:
            <literallayout class='monospaced'>
     $ bitbake linux-yocto -c kernel_configcheck -f
            </literallayout>
            The description file can include multiple <filename>kconf</filename>
            statements, one per fragment.
        </para>

        <para>
        Original text:
            <literallayout class='monospaced'>
The simplest unit of meta-data is the configuration-only feature. It consists of
one or more Linux kernel configuration parameters in a .cfg file (as described
in section XYZ) and an scc file describing the fragment. The SMP fragment
included in the linux-yocto-3.4 git repository consists of the following two
files:

cfg/smp.scc:
	define KFEATURE_DESCRIPTION "Enable SMP"
	kconf hardware smp.cfg

cfg/smp.cfg:
	CONFIG_SMP=y
	CONFIG_SCHED_SMT=y

See 2.3.1 for details on creating configuration fragments.

KFEATURE_DESCRIPTION provides a short description of the fragment, the
primary use is for higher level tooling, such as the Yocto Project BSP Tools
(TODO:Citation).

The "kconf" command is used to include the actual configuration fragment in an
scc file, and the "hardware" keyword identifies the fragment as being hardware
enabling, as opposed to general policy (which would use the keyword
"non-hardware"). The distinction is made for the benefit of the configuration
validation tools which will warn you if a hardware fragment overrides a policy
set by a non-hardware fragment.

As described in 2.3.1, the following bitbake command can be used to audit your
configuration:

	$ bitbake linux-yocto -c kernel_configcheck -f

The description file can include multiple kconf statements, one per fragment.
            </literallayout>
        </para>
    </section>

    <section id='patches'>
        <title>Patches</title>

        <para>
            Patches are described in a very similar way to configuration
            fragments, which are described in the previous section.
            Instead of a <filename>.cfg</filename> file, they work with
            source patches.
            A typical patch includes a description file and the patch itself:
            <literallayout class='monospaced'>
     patches/mypatch.scc:
        patch mypatch.patch

     patches/mypatch.patch:
        &lt;typical-patch&gt;
            </literallayout>
            For <filename>.patch</filename> files, the typical patch
            is created with <filename>diff -Nurp</filename> or
            <filename>git format-patch</filename>.
        </para>

        <para>
            The description file can include multiple patch statements,
            one per patch.
        </para>

        <para>
            Original text:
            <literallayout class='monospaced'>
Patches are described in a very similar way to configuration fragments (see
3.3.1). Instead of a .cfg file, they work with source patches. A typical patch
includes a description file and the patch itself:

patches/mypatch.scc:
	patch mypatch.patch

patches/mypatch.patch:
	&lt;typical patch created with 'diff -Nurp' or 'git format-patch'&gt;

The description file can include multiple patch statements, one per patch.
            </literallayout>
        </para>
    </section>

    <section id='features'>
        <title>Features</title>

        <para>
            Features are a combination of configuration fragments and patches.
            Or, more accurately, configuration fragments and patches are
            simple forms of a feature, which is a more complex metadata type.
            In addition to the <filename>kconf</filename> and
            <filename>patch</filename> commands, features often aggregate
            description files with the <filename>include</filename> command.
        </para>

        <para>
            A hypothetical example of a feature description file might look
            like the following:
            <literallayout class='monospaced'>
     features/myfeature.scc
        define KFEATURE_DESCRIPTION "Enable myfeature"

        patch 0001-myfeature-core.patch
        patch 0002-myfeature-interface.patch

        include cfg/myfeature_dependency.scc
        kconf non-hardware myfeature.cfg
            </literallayout>
        </para>

        <para>
            Features are typically less granular than configuration
            fragments and are more likely than configurations fragments
            and patches to be the types of things you will want to specify
            in the <filename>KERNEL_FEATURES</filename> variable of the
            Linux kernel recipe.
            See the "<link linkend='using-metadata-in-a-recipe'>Using Metadata in a Recipe</link>"
            section earlier in the manual.
        </para>

        <para>
        Original text:
            <literallayout class='monospaced'>
Features are a combination of configuration fragments and patches, or, more
accurately, configuration fragments and patches are simple forms of a feature, a
more complex meta-data type. In addition to the kconf and patch commands,
features often aggregate description files with the include command.

A hypothetical example of a feature description file might look like the
following:

features/myfeature.scc
	define KFEATURE_DESCRIPTION "Enable myfeature"

	patch 0001-myfeature-core.patch
	patch 0002-myfeature-interface.patch

	include cfg/myfeature_dependency.scc
	kconf non-hardware myfeature.cfg

Features are typically less granular than configuration fragments and are more
likely than configurations fragments and patches to be the types of things you
will want to specify in the KERNEL_FEATURES variable of the Linux kernel recipe
(see 3.1).
            </literallayout>
        </para>
    </section>

    <section id='kernel-types'>
        <title>Kernel Types</title>

        <para>
            Kernel types, or <filename>ktypes</filename>, are used to
            aggregate all non-hardware configuration fragments together
            with any patches you want to use for all Linux kernel builds
            of the specified <filename>ktype</filename>.
            In short, <filename>ktypes</filename> are where you define a
            high-level kernel policy.
            Syntactically, however, they are no different than features
            as described in the previous section.
            The <filename>ktype</filename> is selected by the
            <filename>LINUX_KERNEL_TYPE</filename> variable in the recipe.
            See the "<link linkend='using-metadata-in-a-recipe'>Using Metadata in a Recipe</link>"
            section for more information.
        </para>

        <para>
            By way of example, the linux-yocto-3.4 tree defines three
            <filename>ktypes</filename>: standard, tiny, and preempt-rt.
            <itemizedlist>
                <listitem><para>standard:
                    Includes the generic Linux kernel
                    policy of the Yocto Project linux-yocto kernel recipes.
                    This includes things like which file systems, which
                    networking options, which core kernel features, and which
                    debugging and tracing options are supported.
                    </para></listitem>
                <listitem><para>preempt-rt:
                    Applies the <filename>PREEMPT_RT</filename>
                    patches and the configuration options required to
                    build a real-time Linux kernel.
                    It inherits from standard.</para></listitem>
                <listitem><para>tiny:
                    Independent from the standard configuration
                    and defines a bare minimum configuration meant to serve as a
                    base for very small Linux kernels.
                    Tiny does not currently include any source changes, but it
                    might in the future.</para></listitem>
            </itemizedlist>
        </para>

        <para>
            The standard kernel type is defined by
            <filename>standard.scc</filename>:
            <literallayout class='monospaced'>
     # Include this kernel type fragment to get the standard features and
     # configuration values.

     # Include all standard features
     include standard-nocfg.scc

     kconf non-hardware standard.cfg

     # individual cfg block section
     include cfg/fs/devtmpfs.scc
     include cfg/fs/debugfs.scc
     include cfg/fs/btrfs.scc
     include cfg/fs/ext2.scc
     include cfg/fs/ext3.scc
     include cfg/fs/ext4.scc

     include cfg/net/ipv6.scc
     include cfg/net/ip_nf.scc
     include cfg/net/ip6_nf.scc
     include cfg/net/bridge.scc
            </literallayout>
        </para>

        <para>
            As with any <filename>scc</filename> file, a
            <filename>ktype</filename> definition can aggregate other
            <filename>scc</filename> files with the
            <filename>include</filename> command, or directly pull in
            configuration fragments and patches with the
            <filename>kconf</filename> and <filename>patch</filename>
            commands, respectively.
        </para>

        <note>
            It is not strictly necessary to create a
            <filename>ktype scc</filename> file.
            The BSP file can define the <filename>ktype</filename> implicitly
            with a <filename>define KTYPE myktype</filename> line. See the
            next section for more information.
        </note>

        <para>
            Original text:
            <literallayout class='monospaced'>
Kernel types, or ktypes, are used to aggregate all non-hardware configuration
fragments together with any patches you want to use for all Linux kernel builds
of the specified ktype. In short, ktypes are where you define a high-level
kernel policy. Syntactically, however, they are no different than features (see
3.3.3).  preempt-rt, and tiny. The ktype is selected by the LINUX_KERNEL_TYPE
variable in the recipe (see 3.1).

By way of example, the linux-yocto-3.4 tree defines three ktypes: standard,
tiny, and preempt-rt. The standard kernel type includes the generic Linux kernel
policy of the Yocto Project linux-yocto kernel recipes. This includes things
like which filesystems, which networking options, which core kernel features,
and which debugging and tracing optoins are supported. The preempt-rt kernel
type applies the PREEMPT_RT patches and the configuration options required to
build a real-time Linux kernel. It inherits from standard. The tiny kernel type
is independent from the standard configuration and defines a bare minimum
configuration meant to serve as a base for very small Linux kernels. Tiny does
not currently include any source changes, but it may in the future.

The standard ktype is defined by standard.scc:
	# Include this kernel type fragment to get the standard features and
	# configuration values.

	# Include all standard features
	include standard-nocfg.scc

	kconf non-hardware standard.cfg

	# individual cfg block section
	include cfg/fs/devtmpfs.scc
	include cfg/fs/debugfs.scc
	include cfg/fs/btrfs.scc
	include cfg/fs/ext2.scc
	include cfg/fs/ext3.scc
	include cfg/fs/ext4.scc

	include cfg/net/ipv6.scc
	include cfg/net/ip_nf.scc
	include cfg/net/ip6_nf.scc
	include cfg/net/bridge.scc

As with any scc file, a ktype definition can aggregate other scc files with the
include command, or directly pull in configuration fragments and patches with
the kconf and patch commands, respectively.

Note: It is not strictly necessary to create a ktype scc file. The BSP file can
      define the ktype implicitly with a "define KTYPE myktype" line. See 3.3.5.
            </literallayout>
        </para>
    </section>

    <section id='bsp-descriptions'>
        <title>BSP Descriptions</title>

        <para>
            BSP descriptions combine kernel types with hardware-specific
            features.
            The hardware specific portion is typically defined
            independently, and then aggregated with each supported kernel
            type.
            Consider a simple example:
            <literallayout class='monospaced'>
     mybsp.scc:
        define KMACHINE mybsp
        define KTYPE standard
        define KARCH i386

        kconf mybsp.cfg
            </literallayout>
            Every BSP description should include the definition of the
            <filename>KMACHINE</filename>, <filename>KTYPE</filename>,
            and <filename>KARCH</filename> variables.
            These variables allow the build-system to identify this
            description as meeting the criteria set by the recipe being built.
            This particular description can be said to support the "mybsp"
            machine for the "standard" kernel type and the "i386" architecture.
            Be aware that there is no hard link between the
            <filename>KTYPE</filename> and a ktype description file.
            If you do not have kernel types defined in your metadata, you
            only need to ensure that the recipe
            <filename>LINUX_KERNEL_TYPE</filename> and the
            <filename>KTYPE</filename> here match.
            <note>
                Future versions of the tooling make the specification of
                <filename>KTYPE</filename> in the BSP optional.
            </note>
        </para>

        <para>
            If you did want to separate your kernel policy from your
            hardware configuration, you could do so by specifying a kernel
            type, such as "standard" (see 3.3.4) and including that
            description in the BSP description.
            You might also have multiple hardware configurations that you
            aggregate into a single hardware description file which you
            could include here, rather than referencing a single
            <filename>.cfg</filename> file.
            Consider the following:
            <literallayout class='monospaced'>
     mybsp.scc:
        define KMACHINE mybsp
        define KTYPE standard
        define KARCH i386

        include standard.scc
        include mybsp.scc
            </literallayout>
        </para>

        <para>
            In the above example, <filename>standard.scc</filename>
            aggregates all the configuration fragments, patches, and
            features that make up your standard kernel policy whereas
            <filename>mybsp.scc</filename> aggregates all those necessary
            to support the hardware available on the <filename>mybsp</filename>
            machine.
            For information on how to break a complete <filename>.config</filename>
            into the various, see the
            "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
            section.
        </para>

        <para>
            Many real-world examples are more complex.
            Like any other <filename>scc</filename> file, BSP
            descriptions can aggregate features.
            Consider the Fish River Island II (fri2)
            BSP definitions from the linux-yocto-3.4 repository:
            <literallayout class='monospaced'>
     fri2.scc:
        kconf hardware fri2.cfg

        include cfg/x86.scc
        include features/eg20t/eg20t.scc
        include cfg/dmaengine.scc
        nclude features/ericsson-3g/f5521gw.scc
        include features/power/intel.scc
        include cfg/efi.scc
        include features/usb/ehci-hcd.scc
        include features/usb/ohci-hcd.scc
        include features/iwlwifi/iwlwifi.scc
            </literallayout>
        </para>

        <para>
            The <filename>fri2.scc</filename> description file includes
            a hardware configuration fragment
            (<filename>fri2.cfg</filename>) specific to the fri2 BSP
            as well as several more general configuration fragments and
            features enabling hardware found on the fri2.
            This description is then included in each of the three
            machine-ktype descriptions (standard, preempt-rt, and tiny).
            Consider the fri2 standard description:
            <literallayout class='monospaced'>
     fri2-standard.scc:
        define KMACHINE fri2
        define KTYPE standard
        define KARCH i386

        include ktypes/standard/standard.scc
        branch fri2

        git merge emgd-1.14

        include fri2.scc

        # Extra fri2 configs above the minimal defined in fri2.scc
        include cfg/efi-ext.scc
        include features/drm-emgd/drm-emgd.scc
        include cfg/vesafb.scc

        # default policy for standard kernels
        include cfg/usb-mass-storage.scc
            </literallayout>
            The "include fri2.scc" line about midway through the file defines
            all hardware enablement common to the BSP for all kernel types.
            Including the statement significantly reduces duplication.
        </para>

        <para>
            This description introduces a few more variables and commands
            worthy of further discussion.
            Notice the "branch" command, which is used to create a
            machine-specific branch into which source changes can be applied.
            With this branch set up, the <filename>git merge</filename> command
            uses Git to merge in a feature branch "emgd-1.14".
            This could also be handled with the patch command, but for
            commonly used features such as this, feature branches can be a
            convenient mechanism.
            See the "<link linkend='feature-branches'>Feature Branches</link>"
            section for more information.
        </para>

        <para>
            Now consider the Fish River Island 2 tiny
            (<filename>fri2-tiny</filename>) BSP description:
            <literallayout class='monospaced'>
     fri2-tiny.scc:
        define KMACHINE fri2
        define KTYPE tiny
        define KARCH i386

        include ktypes/tiny/tiny.scc
        branch fri2

        include fri2.scc
            </literallayout>
            As you might expect, the tiny description includes quite a bit less.
            In fact, it includes only the minimal policy defined by the
            tiny ktype and the hardware-specific configuration required for
            boot and the most basic functionality of the system as defined in
            the base fri2 description file.
        </para>

        <para>
            Notice again the three critical variables: <filename>KMACHINE</filename>,
            <filename>KTYPE</filename>, and <filename>KARCH</filename>.
            Of these, only the <filename>KTYPE</filename> has changed.
            It is now set to "tiny".
        </para>

        <para>
            Original text:
            <literallayout class='monospaced'>
BSP descriptions combine kernel types (see 3.3.4) with hardware-specific
features (see 3.3.3). The hardware specific portion is typically defined
independently, and then aggregated with each supported kernel type. Consider a
simple example:

mybsp.scc:
	define KMACHINE mybsp
	define KTYPE standard
	define KARCH i386

	kconf mybsp.cfg

Every BSP description should include the definition of the KMACHINE, KTYPE, and
KARCH variables. These variables allow the build-system to identify this
description as meeting the criteria set by the recipe being built. This
particular description can be said to support the "mybsp" machine for the
"standard" kernel type and the "i386" architecture. Note that there is no hard
link between the KTYPE and a ktype description file. If you do not have kernel
types defined in your meta-data, you only need to ensure that the recipe
LINUX_KERNEL_TYPE and the KTYPE here match.

NOTE: future versions of the tooling make the specification of KTYPE in the BSP
      optional.

If you did want to separate your kernel policy from your hardware configuration,
you could do so by specifying a kernel type, such as "standard" (see 3.3.4) and
including that description in the BSP description. You might also have multiple
hardware configurations that you aggregate into a single hardware description
file which you could include here, rather than referencing a single .cfg file.
Consider the following:

mybsp.scc:
	define KMACHINE mybsp
	define KTYPE standard
	define KARCH i386

	include standard.scc
	include mybsp.scc

In the above example standard.scc aggregates all the configuration fragments,
patches, and features that make up your standard kernel policy whereas mybsp.scc
aggregates all those necessary to support the hardware available on the mybsp
machine. For information on how to break a complete .config into the various
fragments, see 2.3.1.

Many real-world examples are more complex. Like any other scc file, BSP
descriptions can aggregate features. Consider the Fish River Island II (fri2)
BSP definitions from the linux-yocto-3.4 repository:

fri2.scc:
	kconf hardware fri2.cfg

	include cfg/x86.scc
	include features/eg20t/eg20t.scc
	include cfg/dmaengine.scc
	include features/ericsson-3g/f5521gw.scc
	include features/power/intel.scc
	include cfg/efi.scc
	include features/usb/ehci-hcd.scc
	include features/usb/ohci-hcd.scc
	include features/iwlwifi/iwlwifi.scc

The fri2.scc description file includes a hardware configuration fragment
(fri2.cfg) specific to the fri2 BSP as well as several more general
configuration fragments and features enabling hardware found on the fri2. This
description is then included in each of the three machine-ktype descriptions
(standard, preempt-rt, and tiny). Consider the fri2 standard description:

fri2-standard.scc:
	define KMACHINE fri2
	define KTYPE standard
	define KARCH i386

	include ktypes/standard/standard.scc
	branch fri2

	git merge emgd-1.14

	include fri2.scc

	# Extra fri2 configs above the minimal defined in fri2.scc
	include cfg/efi-ext.scc
	include features/drm-emgd/drm-emgd.scc
	include cfg/vesafb.scc

	# default policy for standard kernels
	include cfg/usb-mass-storage.scc

Note the "include fri2.scc" line about midway through the file. By defining all
hardware enablement common to the BSP for all kernel types, duplication is
significantly reduced.

This description introduces a few more variables and commands worthy of further
discussion.  Note the "branch" command which is used to create a
machine-specific branch into which source changes can be applied. With this
branch set up, the "git merge" command uses the git SCM to merge in a feature
branch "emgd-1.14".  This could also be handled with the patch command, but for
commonly used features such as this, feature branches can be a convenient
mechanism (see 3.5).

Next consider the fri2 tiny description:

fri2-tiny.scc:
	define KMACHINE fri2
	define KTYPE tiny
	define KARCH i386

	include ktypes/tiny/tiny.scc
	branch fri2

	include fri2.scc

As you might expect, the tiny description includes quite a bit less. In fact,
it includes only the minimal policy defined by the tiny ktype and the
hardware-specific configuration required for boot and the most basic
functionality of the system as defined in the base fri2 description file. Note
again the three critical variables: KMACHINE, KTYPE, and KARCH. Of these, only
the KTYPE has changed, now set to "tiny".
            </literallayout>
        </para>
    </section>
</section>




<section id='machine-branches'>
    <title>Machine Branches</title>

    <para>
        The "<link linkend='using-metadata-in-a-recipe'>Using Metadata in a Recipe</link>"
        section introduced the <filename>KBRANCH</filename> variable, which
        defines the source branch to use from the Linux kernel Git repository
        you are using.
        Many linux-yocto-custom derived recipes will be using Linux kernel
        sources with only a single branch: "master".
        However, when you are working with multiple boards and architectures,
        you are likely to run into the situation where a series of patches
        are needed for one board to boot.
        Sometimes, these patches are works-in-progress or fundamentally wrong,
        yet still necessary for specific boards.
        In these situations, you most likely do not want to include these
        patches in every kernel you build.
        You have a couple of options.
    </para>

    <para>
        First, you could encapsulate these patches in a feature description
        and only include them in the BSP description for the board(s) that
        require them.
        For more information, see the
        "<link linkend='patches'>Patches</link>" and
        "<link linkend='bsp-descriptions'>BSP Descriptions</link>" sections.
    </para>

    <para>
        Alternatively, you can create a branch in your Linux kernel sources
        and apply the patches there.
        You can then specify this new branch as the
        <filename>KBRANCH</filename> to use for this board.
        You can do this in the recipe with the
        <filename>KBRANCH</filename> variable:
        <literallayout class='monospaced'>
     KBRANCH = "mynewbranch"
        </literallayout>
        or in the BSP description using the "branch" command:
        <literallayout class='monospaced'>
     mybsp.scc:
        define KMACHINE mybsp
        define KTYPE standard
        define KARCH i386
        include standard.scc

        branch mynewbranch

        include mybsp.scc
        </literallayout>
    </para>

    <para>
        The approach you take, feature or branch, is entirely up to you
        and depends on what works best for your development model.
        If you are actively working on board support, you may find that
        working within a branch is more practical than trying to continually
        reintegrate your patches into a feature.
        On the other hand, if you are simply reusing some patches from an
        external tree and are not working on them, you may find the
        encapsulated feature to be appropriate as it does not require the
        additional complexity of branching in your Linux kernel sources.
    </para>

    <para>
        If you are supporting multiple boards and architectures and find
        yourself with numerous branches, you might consider using a
        hierarchical branching system similar to what the linux-yocto Linux
        kernel repositories use:
        <literallayout class='monospaced'>
     &lt;common&gt;/&lt;ktype&gt;/&lt;machine&gt;
        </literallayout>
    </para>

    <para>
        If you had two ktypes, standard and small for instance, and three
        machines, your Git tree might look like this:
        <literallayout class='monospaced'>
     common/base
     common/standard/base
     common/standard/machine_a
     common/standard/machine_b
     common/standard/machine_c
     common/small/base
     common/small/machine_a
        </literallayout>
    </para>

    <para>
        This organization can help clarify the relationship of the branches to
        each other.
        In this case, "common/standard/machine_a" would include everything in
        "common/base" and "common/standard/base".
        The "standard" and "small" branches add sources specific to those
        kernel types that for whatever reason are not appropriate for the
        other branches.
        <note>The "base" branches are an artifact of the way Git manages
            its data internally on the filesystem: it will not allow you to use
            "common/standard" and "common/standard/machine_a" because it
            would have to create a file and a directory named "standard".
        </note>
    </para>

    <para>
        Original text:
        <literallayout class='monospaced'>
Section 3.1 introduced the KBRANCH variable which defines the source branch to
use from the Linux kernel git repository you are using. Many linux-yocto-custom
derived recipes will be using Linux kernel sources with only a single branch:
"master". However, when you are working with multiple boards and architectures,
you are likely to run into the situation where a series of patches are needed
for one board to boot. Sometimes these patches are works in progress or
fundamentally wrong, yet still necessary for specific boards. In these
situations, you most likely do not want to include these patches in every kernel
you build. You have a couple of options.

First, you could encapsulate these patches in a feature description and only
include them in the BSP description for the board(s) that require them (see
3.3.2 and 3.3.5).

Alternatively, you can create a branch in your Linux kernel sources and apply
the patches there. You can then specify this new branch as the KBRANCH to use
for this board. You can do this in the recipe with the KBRANCH variable:

	KBRANCH = "mynewbranch"

or in the BSP description using the "branch" command:

mybsp.scc:
	define KMACHINE mybsp
	define KTYPE standard
	define KARCH i386
	include standard.scc

	branch mynewbranch

	include mybsp.scc

The decision of which approach to take, feature or branch, is entirely up to you
and depends on what works best for your development model. If you are actively
working on board support, you may find that working within a branch is more
practical than trying to continually reintegrate your patches into a feature. On
the other hand, if you are simply reusing some patches from an external tree and
are not working on them, you may find the encapsulated feature to be appropriate
as it does not require the additional complexity of branching in your Linux
kernel sources.

If you are supporting multiple boards and architectures and find yourself with
numerous branches, you might consider using a hierarchical branching system
similar to what the linux-yocto Linux kernel repositories use:

	&lt;common&gt;/&lt;ktype&gt;/&lt;machine&gt;

If you had two ktypes, standard and small for instance, and three machines, your
git tree might look like this:

	common/base
	common/standard/base
	common/standard/machine_a
	common/standard/machine_b
	common/standard/machine_c
	common/small/base
	common/small/machine_a

This organization can help clarify the relationship of the branches to
each other. In this case, "common/standard/machine_a" would include everything in
"common/base" and "common/standard/base". The "standard" and "small" branches
add sources specific to those kernel types that for whatever reason are not
appropriate for the other branches.

Note: The "base" branches are an artifact of the way git manages its data
      internally on the filesystem: it will not allow you to use
      "common/standard" and "common/standard/machine_a" because it would have to
      create a file and a directory named "standard".
        </literallayout>
    </para>
</section>

<section id='feature-branches'>
    <title>Feature Branches</title>

    <para>
        During active development a new feature, it can be more efficient
        to work with that feature as a branch, rather than as a set of
        patches which have to be regularly updated.
        The Yocto Project Linux kernel tools provide for this with
        the <filename>git merge</filename> command.
    </para>

    <para>
        To merge a feature branch into a BSP, insert the
        <filename>git merge</filename> command after any
        <filename>branch</filename> commands:
        <literallayout class='monospaced'>
     mybsp.scc:
        define KMACHINE mybsp
        define KTYPE standard
        define KARCH i386
        include standard.scc

        branch mynewbranch
        git merge myfeature

        include mybsp.scc
        </literallayout>
    </para>

    <para>
        Original text:
        <literallayout class='monospaced'>
During active development a new feature, it can be more efficient to work with
that feature as a branch, rather than as a set of patches which have to be
regularly updated. The Yocto Project Linux kernel tools provide for this with
the "git merge" command.

To merge a feature branch into a BSP, insert the "git merge" command after any
branch commands:

mybsp.scc:
	define KMACHINE mybsp
	define KTYPE standard
	define KARCH i386
	include standard.scc

	branch mynewbranch
	git merge myfeature

	include mybsp.scc
        </literallayout>
    </para>
</section>

<section id='scc-reference'>
    <title>SCC Reference</title>

    <para>
        This section provides short descriptions for the commands you can
        use from an <filename>.scc</filename>:
        <itemizedlist>
            <listitem><para><filename>branch [ref]</filename>:
                Creates a new branch relative to the current branch
                (typically <filename>${KTYPE}</filename>) using
                the currently checked-out branch, or "ref" if specified.</para>
                <para><emphasis>TODO:</emphasis> Bruce, we need to clarify
                the "relative to the current branch" bit.</para></listitem>
            <listitem><para><filename>define</filename>:
                Defines variables, such as <filename>KMACHINE</filename>,
                <filename>KTYPE</filename>, <filename>KARCH</filename>,
                and <filename>KFEATURE_DESCRIPTION</filename>.</para></listitem>
            <listitem><para><filename>include SCC_FILE</filename>:
                Includes an <filename>scc</filename> file in the current file.
                It will be parsed as if inserted inline.</para></listitem>
            <listitem><para><filename>kconf [hardware|non-hardware] CFG_FILE</filename>:
                Queues a configuration fragment for merging into the final
                Linux <filename>.config</filename> file.</para></listitem>
            <listitem><para><filename>git merge GIT_BRANCH</filename>:
                Merges the feature branch into the current branch.</para></listitem>
            <listitem><para><filename>patch PATCH_FILE</filename>:
                Applies the patch to the current Git branch.</para></listitem>
        </itemizedlist>
    </para>

    <para>
        Original text:
        <literallayout class='monospaced'>
* branch [ref]

  Create a new branch relative to the current branch (typically ${KTYPE}) using
  the currently checked-out branch, or "ref" if specified.

  TODO: Bruce, we need to clarify the "relative to the current branch" bit.

* define

  Define variables, such as KMACHINE, KTYPE, KARCH, and KFEATURE_DESCRIPTION.

* include SCC_FILE

  Include an scc file in the current file. It will be parsed as if inserted
  inline.

* kconf [hardware|non-hardware] CFG_FILE

  Queue a configuration fragment for merging into the final Linux .config file.

* merge (or "git merge") GIT_BRANCH

  Merge the feature branch into the current branch.

* patch PATCH_FILE

  Apply the patch to the current git branch.
        </literallayout>
    </para>
</section>

</chapter>
<!--
vim: expandtab tw=80 ts=4
-->