summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-01-09 17:26:01 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-01-16 15:59:17 +0000
commit7eccfa6849a3ee870ceb59a28f590f6cfcb305fb (patch)
tree81ad60c89d89fd2628390f5a1f30d45b78af15da /documentation/kernel-dev
parentf42c87a1acd6419e78ad1567cb2e88720e63c4b5 (diff)
downloadpoky-7eccfa6849a3ee870ceb59a28f590f6cfcb305fb.tar.gz
kernel-dev: Created super section for Branches.
The sections for "Machine Branches" and "Feature Branches" really should be encapsulated within a section on branching. Much of the text in the "Machine Branches" section presents the rationale behind both types of branches. I have created a larger section to contain these and will edit the text to fit. (From yocto-docs rev: c7c67f5867f22ebbbd49cab79bb2d4e52422ecac) 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.xml218
1 files changed, 115 insertions, 103 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index ff8374c635..d02654f13a 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -1373,47 +1373,58 @@ the KTYPE has changed, now set to "tiny".
1373 </section> 1373 </section>
1374</section> 1374</section>
1375 1375
1376<section id='machine-branches'> 1376<section id='working-with-branches'>
1377 <title>Machine Branches</title> 1377 <title>Working with Branches</title>
1378 1378
1379 <para> 1379 <para>
1380 The "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>" 1380 We need a top-level section here that introduces branches in general.
1381 section introduced the <filename>KBRANCH</filename> variable, which 1381 There is information that can be pulled from the embedded machine
1382 defines the source branch to use from the Linux kernel Git repository 1382 and feature sections to introduce this stuff.
1383 you are using. 1383 The two subsections should deal with each type of specific branch
1384 Many linux-yocto-custom derived recipes will be using Linux kernel 1384 that can be used.
1385 sources with only a single branch: "master".
1386 However, when you are working with multiple boards and architectures,
1387 you are likely to run into the situation where a series of patches
1388 are needed for one board to boot.
1389 Sometimes, these patches are works-in-progress or fundamentally wrong,
1390 yet still necessary for specific boards.
1391 In these situations, you most likely do not want to include these
1392 patches in every kernel you build.
1393 You have a couple of options.
1394 </para> 1385 </para>
1395 1386
1396 <para> 1387 <section id='machine-branches'>
1397 First, you could encapsulate these patches in a feature description 1388 <title>Machine Branches</title>
1398 and only include them in the BSP description for the board(s) that
1399 require them.
1400 For more information, see the
1401 "<link linkend='patches'>Patches</link>" and
1402 "<link linkend='bsp-descriptions'>BSP Descriptions</link>" sections.
1403 </para>
1404 1389
1405 <para> 1390 <para>
1406 Alternatively, you can create a branch in your Linux kernel sources 1391 The "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
1407 and apply the patches there. 1392 section introduced the <filename>KBRANCH</filename> variable, which
1408 You can then specify this new branch as the 1393 defines the source branch to use from the Linux kernel Git repository
1409 <filename>KBRANCH</filename> to use for this board. 1394 you are using.
1410 You can do this in the recipe with the 1395 Many linux-yocto-custom derived recipes will be using Linux kernel
1411 <filename>KBRANCH</filename> variable: 1396 sources with only a single branch: "master".
1412 <literallayout class='monospaced'> 1397 However, when you are working with multiple boards and architectures,
1398 you are likely to run into the situation where a series of patches
1399 are needed for one board to boot.
1400 Sometimes, these patches are works-in-progress or fundamentally wrong,
1401 yet still necessary for specific boards.
1402 In these situations, you most likely do not want to include these
1403 patches in every kernel you build.
1404 You have a couple of options.
1405 </para>
1406
1407 <para>
1408 First, you could encapsulate these patches in a feature description
1409 and only include them in the BSP description for the board(s) that
1410 require them.
1411 For more information, see the
1412 "<link linkend='patches'>Patches</link>" and
1413 "<link linkend='bsp-descriptions'>BSP Descriptions</link>" sections.
1414 </para>
1415
1416 <para>
1417 Alternatively, you can create a branch in your Linux kernel sources
1418 and apply the patches there.
1419 You can then specify this new branch as the
1420 <filename>KBRANCH</filename> to use for this board.
1421 You can do this in the recipe with the
1422 <filename>KBRANCH</filename> variable:
1423 <literallayout class='monospaced'>
1413 KBRANCH = "mynewbranch" 1424 KBRANCH = "mynewbranch"
1414 </literallayout> 1425 </literallayout>
1415 or in the BSP description using the "branch" command: 1426 or in the BSP description using the "branch" command:
1416 <literallayout class='monospaced'> 1427 <literallayout class='monospaced'>
1417 mybsp.scc: 1428 mybsp.scc:
1418 define KMACHINE mybsp 1429 define KMACHINE mybsp
1419 define KTYPE standard 1430 define KTYPE standard
@@ -1423,35 +1434,35 @@ the KTYPE has changed, now set to "tiny".
1423 branch mynewbranch 1434 branch mynewbranch
1424 1435
1425 include mybsp-hw.scc 1436 include mybsp-hw.scc
1426 </literallayout> 1437 </literallayout>
1427 </para> 1438 </para>
1428 1439
1429 <para> 1440 <para>
1430 The approach you take, feature or branch, is entirely up to you 1441 The approach you take, feature or branch, is entirely up to you
1431 and depends on what works best for your development model. 1442 and depends on what works best for your development model.
1432 If you are actively working on board support, you may find that 1443 If you are actively working on board support, you may find that
1433 working within a branch is more practical than trying to continually 1444 working within a branch is more practical than trying to continually
1434 reintegrate your patches into a feature. 1445 reintegrate your patches into a feature.
1435 On the other hand, if you are simply reusing some patches from an 1446 On the other hand, if you are simply reusing some patches from an
1436 external tree and are not working on them, you may find the 1447 external tree and are not working on them, you may find the
1437 encapsulated feature to be appropriate as it does not require the 1448 encapsulated feature to be appropriate as it does not require the
1438 additional complexity of branching in your Linux kernel sources. 1449 additional complexity of branching in your Linux kernel sources.
1439 </para> 1450 </para>
1440 1451
1441 <para> 1452 <para>
1442 If you are supporting multiple boards and architectures and find 1453 If you are supporting multiple boards and architectures and find
1443 yourself with numerous branches, you might consider using a 1454 yourself with numerous branches, you might consider using a
1444 hierarchical branching system similar to what the linux-yocto Linux 1455 hierarchical branching system similar to what the linux-yocto Linux
1445 kernel repositories use: 1456 kernel repositories use:
1446 <literallayout class='monospaced'> 1457 <literallayout class='monospaced'>
1447 &lt;common&gt;/&lt;ktype&gt;/&lt;machine&gt; 1458 &lt;common&gt;/&lt;ktype&gt;/&lt;machine&gt;
1448 </literallayout> 1459 </literallayout>
1449 </para> 1460 </para>
1450 1461
1451 <para> 1462 <para>
1452 If you had two ktypes, standard and small for instance, and three 1463 If you had two ktypes, standard and small for instance, and three
1453 machines, your Git tree might look like this: 1464 machines, your Git tree might look like this:
1454 <literallayout class='monospaced'> 1465 <literallayout class='monospaced'>
1455 common/base 1466 common/base
1456 common/standard/base 1467 common/standard/base
1457 common/standard/machine_a 1468 common/standard/machine_a
@@ -1459,27 +1470,27 @@ the KTYPE has changed, now set to "tiny".
1459 common/standard/machine_c 1470 common/standard/machine_c
1460 common/small/base 1471 common/small/base
1461 common/small/machine_a 1472 common/small/machine_a
1462 </literallayout> 1473 </literallayout>
1463 </para> 1474 </para>
1464 1475
1465 <para> 1476 <para>
1466 This organization can help clarify the relationship of the branches to 1477 This organization can help clarify the relationship of the branches to
1467 each other. 1478 each other.
1468 In this case, "common/standard/machine_a" would include everything in 1479 In this case, "common/standard/machine_a" would include everything in
1469 "common/base" and "common/standard/base". 1480 "common/base" and "common/standard/base".
1470 The "standard" and "small" branches add sources specific to those 1481 The "standard" and "small" branches add sources specific to those
1471 kernel types that for whatever reason are not appropriate for the 1482 kernel types that for whatever reason are not appropriate for the
1472 other branches. 1483 other branches.
1473 <note>The "base" branches are an artifact of the way Git manages 1484 <note>The "base" branches are an artifact of the way Git manages
1474 its data internally on the filesystem: it will not allow you to use 1485 its data internally on the filesystem: it will not allow you to use
1475 "common/standard" and "common/standard/machine_a" because it 1486 "common/standard" and "common/standard/machine_a" because it
1476 would have to create a file and a directory named "standard". 1487 would have to create a file and a directory named "standard".
1477 </note> 1488 </note>
1478 </para> 1489 </para>
1479 1490
1480 <para> 1491 <para>
1481 Original text: 1492 Original text:
1482 <literallayout class='monospaced'> 1493 <literallayout class='monospaced'>
1483Section 3.1 introduced the KBRANCH variable which defines the source branch to 1494Section 3.1 introduced the KBRANCH variable which defines the source branch to
1484use from the Linux kernel git repository you are using. Many linux-yocto-custom 1495use from the Linux kernel git repository you are using. Many linux-yocto-custom
1485derived recipes will be using Linux kernel sources with only a single branch: 1496derived recipes will be using Linux kernel sources with only a single branch:
@@ -1548,26 +1559,26 @@ Note: The "base" branches are an artifact of the way git manages its data
1548 internally on the filesystem: it will not allow you to use 1559 internally on the filesystem: it will not allow you to use
1549 "common/standard" and "common/standard/machine_a" because it would have to 1560 "common/standard" and "common/standard/machine_a" because it would have to
1550 create a file and a directory named "standard". 1561 create a file and a directory named "standard".
1551 </literallayout> 1562 </literallayout>
1552 </para> 1563 </para>
1553</section> 1564 </section>
1554 1565
1555<section id='feature-branches'> 1566 <section id='feature-branches'>
1556 <title>Feature Branches</title> 1567 <title>Feature Branches</title>
1557 1568
1558 <para> 1569 <para>
1559 During active development a new feature, it can be more efficient 1570 During active development a new feature, it can be more efficient
1560 to work with that feature as a branch, rather than as a set of 1571 to work with that feature as a branch, rather than as a set of
1561 patches which have to be regularly updated. 1572 patches which have to be regularly updated.
1562 The Yocto Project Linux kernel tools provide for this with 1573 The Yocto Project Linux kernel tools provide for this with
1563 the <filename>git merge</filename> command. 1574 the <filename>git merge</filename> command.
1564 </para> 1575 </para>
1565 1576
1566 <para> 1577 <para>
1567 To merge a feature branch into a BSP, insert the 1578 To merge a feature branch into a BSP, insert the
1568 <filename>git merge</filename> command after any 1579 <filename>git merge</filename> command after any
1569 <filename>branch</filename> commands: 1580 <filename>branch</filename> commands:
1570 <literallayout class='monospaced'> 1581 <literallayout class='monospaced'>
1571 mybsp.scc: 1582 mybsp.scc:
1572 define KMACHINE mybsp 1583 define KMACHINE mybsp
1573 define KTYPE standard 1584 define KTYPE standard
@@ -1578,12 +1589,12 @@ Note: The "base" branches are an artifact of the way git manages its data
1578 git merge myfeature 1589 git merge myfeature
1579 1590
1580 include mybsp-hw.scc 1591 include mybsp-hw.scc
1581 </literallayout> 1592 </literallayout>
1582 </para> 1593 </para>
1583 1594
1584 <para> 1595 <para>
1585 Original text: 1596 Original text:
1586 <literallayout class='monospaced'> 1597 <literallayout class='monospaced'>
1587During active development a new feature, it can be more efficient to work with 1598During active development a new feature, it can be more efficient to work with
1588that feature as a branch, rather than as a set of patches which have to be 1599that feature as a branch, rather than as a set of patches which have to be
1589regularly updated. The Yocto Project Linux kernel tools provide for this with 1600regularly updated. The Yocto Project Linux kernel tools provide for this with
@@ -1602,8 +1613,9 @@ mybsp.scc:
1602 git merge myfeature 1613 git merge myfeature
1603 1614
1604 include mybsp.scc 1615 include mybsp.scc
1605 </literallayout> 1616 </literallayout>
1606 </para> 1617 </para>
1618 </section>
1607</section> 1619</section>
1608 1620
1609<section id='scc-reference'> 1621<section id='scc-reference'>