summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-12-27 14:50:40 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-01-16 15:59:12 +0000
commit49166264bd93d2e4c0b4fcf3641468b37ca18b84 (patch)
tree543bb003e3a9cebc592b97ef58f74e04a1b6aec8 /documentation/kernel-dev
parentfe1b20f80a2bd1c8c19b8cdb59c04ec2095794d4 (diff)
downloadpoky-49166264bd93d2e4c0b4fcf3641468b37ca18b84.tar.gz
kernel-dev: Formatting "Machine Branches" section.
(From yocto-docs rev: 30a0d3c1ef3d91221ce3f90a3fd2f4b93bff1c30) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/kernel-dev')
-rw-r--r--documentation/kernel-dev/kernel-dev-advanced.xml182
1 files changed, 182 insertions, 0 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index ee90df2732..dbc3dfbe89 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -1308,6 +1308,188 @@ the KTYPE has changed, now set to "tiny".
1308 </section> 1308 </section>
1309</section> 1309</section>
1310 1310
1311
1312
1313
1314<section id='machine-branches'>
1315 <title>Machine Branches</title>
1316
1317 <para>
1318 The "<link linkend='using-metadata-in-a-recipe'>Using Metadata in a Recipe</link>"
1319 section introduced the <filename>KBRANCH</filename> variable, which
1320 defines the source branch to use from the Linux kernel Git repository
1321 you are using.
1322 Many linux-yocto-custom derived recipes will be using Linux kernel
1323 sources with only a single branch: "master".
1324 However, when you are working with multiple boards and architectures,
1325 you are likely to run into the situation where a series of patches
1326 are needed for one board to boot.
1327 Sometimes, these patches are works-in-progress or fundamentally wrong,
1328 yet still necessary for specific boards.
1329 In these situations, you most likely do not want to include these
1330 patches in every kernel you build.
1331 You have a couple of options.
1332 </para>
1333
1334 <para>
1335 First, you could encapsulate these patches in a feature description
1336 and only include them in the BSP description for the board(s) that
1337 require them.
1338 For more information, see the
1339 "<link linkend='patches'>Patches</link>" and
1340 "<link linkend='bsp-descriptions'>BSP Descriptions</link>" sections.
1341 </para>
1342
1343 <para>
1344 Alternatively, you can create a branch in your Linux kernel sources
1345 and apply the patches there.
1346 You can then specify this new branch as the
1347 <filename>KBRANCH</filename> to use for this board.
1348 You can do this in the recipe with the
1349 <filename>KBRANCH</filename> variable:
1350 <literallayout class='monospaced'>
1351 KBRANCH = "mynewbranch"
1352 </literallayout>
1353 or in the BSP description using the "branch" command:
1354 <literallayout class='monospaced'>
1355 mybsp.scc:
1356 define KMACHINE mybsp
1357 define KTYPE standard
1358 define KARCH i386
1359 include standard.scc
1360
1361 branch mynewbranch
1362
1363 include mybsp.scc
1364 </literallayout>
1365 </para>
1366
1367 <para>
1368 The approach you take, feature or branch, is entirely up to you
1369 and depends on what works best for your development model.
1370 If you are actively working on board support, you may find that
1371 working within a branch is more practical than trying to continually
1372 reintegrate your patches into a feature.
1373 On the other hand, if you are simply reusing some patches from an
1374 external tree and are not working on them, you may find the
1375 encapsulated feature to be appropriate as it does not require the
1376 additional complexity of branching in your Linux kernel sources.
1377 </para>
1378
1379 <para>
1380 If you are supporting multiple boards and architectures and find
1381 yourself with numerous branches, you might consider using a
1382 hierarchical branching system similar to what the linux-yocto Linux
1383 kernel repositories use:
1384 <literallayout class='monospaced'>
1385 &lt;common&gt;/&lt;ktype&gt;/&lt;machine&gt;
1386 </literallayout>
1387 </para>
1388
1389 <para>
1390 If you had two ktypes, standard and small for instance, and three
1391 machines, your Git tree might look like this:
1392 <literallayout class='monospaced'>
1393 common/base
1394 common/standard/base
1395 common/standard/machine_a
1396 common/standard/machine_b
1397 common/standard/machine_c
1398 common/small/base
1399 common/small/machine_a
1400 </literallayout>
1401 </para>
1402
1403 <para>
1404 This organization can help clarify the relationship of the branches to
1405 each other.
1406 In this case, "common/standard/machine_a" would include everything in
1407 "common/base" and "common/standard/base".
1408 The "standard" and "small" branches add sources specific to those
1409 kernel types that for whatever reason are not appropriate for the
1410 other branches.
1411 <note>The "base" branches are an artifact of the way Git manages
1412 its data internally on the filesystem: it will not allow you to use
1413 "common/standard" and "common/standard/machine_a" because it
1414 would have to create a file and a directory named "standard".
1415 </note>
1416 </para>
1417
1418 <para>
1419 Original text:
1420 <literallayout class='monospaced'>
1421Section 3.1 introduced the KBRANCH variable which defines the source branch to
1422use from the Linux kernel git repository you are using. Many linux-yocto-custom
1423derived recipes will be using Linux kernel sources with only a single branch:
1424"master". However, when you are working with multiple boards and architectures,
1425you are likely to run into the situation where a series of patches are needed
1426for one board to boot. Sometimes these patches are works in progress or
1427fundamentally wrong, yet still necessary for specific boards. In these
1428situations, you most likely do not want to include these patches in every kernel
1429you build. You have a couple of options.
1430
1431First, you could encapsulate these patches in a feature description and only
1432include them in the BSP description for the board(s) that require them (see
14333.3.2 and 3.3.5).
1434
1435Alternatively, you can create a branch in your Linux kernel sources and apply
1436the patches there. You can then specify this new branch as the KBRANCH to use
1437for this board. You can do this in the recipe with the KBRANCH variable:
1438
1439 KBRANCH = "mynewbranch"
1440
1441or in the BSP description using the "branch" command:
1442
1443mybsp.scc:
1444 define KMACHINE mybsp
1445 define KTYPE standard
1446 define KARCH i386
1447 include standard.scc
1448
1449 branch mynewbranch
1450
1451 include mybsp.scc
1452
1453The decision of which approach to take, feature or branch, is entirely up to you
1454and depends on what works best for your development model. If you are actively
1455working on board support, you may find that working within a branch is more
1456practical than trying to continually reintegrate your patches into a feature. On
1457the other hand, if you are simply reusing some patches from an external tree and
1458are not working on them, you may find the encapsulated feature to be appropriate
1459as it does not require the additional complexity of branching in your Linux
1460kernel sources.
1461
1462If you are supporting multiple boards and architectures and find yourself with
1463numerous branches, you might consider using a hierarchical branching system
1464similar to what the linux-yocto Linux kernel repositories use:
1465
1466 &lt;common&gt;/&lt;ktype&gt;/&lt;machine&gt;
1467
1468If you had two ktypes, standard and small for instance, and three machines, your
1469git tree might look like this:
1470
1471 common/base
1472 common/standard/base
1473 common/standard/machine_a
1474 common/standard/machine_b
1475 common/standard/machine_c
1476 common/small/base
1477 common/small/machine_a
1478
1479This organization can help clarify the relationship of the branches to
1480each other. In this case, "common/standard/machine_a" would include everything in
1481"common/base" and "common/standard/base". The "standard" and "small" branches
1482add sources specific to those kernel types that for whatever reason are not
1483appropriate for the other branches.
1484
1485Note: The "base" branches are an artifact of the way git manages its data
1486 internally on the filesystem: it will not allow you to use
1487 "common/standard" and "common/standard/machine_a" because it would have to
1488 create a file and a directory named "standard".
1489 </literallayout>
1490 </para>
1491</section>
1492
1311</chapter> 1493</chapter>
1312<!-- 1494<!--
1313vim: expandtab tw=80 ts=4 1495vim: expandtab tw=80 ts=4