summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-01-11 14:04:40 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-01-16 15:59:18 +0000
commitc9f796dbd7300970282c4c4bba1ac8e2eca2fba9 (patch)
tree7e7c48cf06eee29be29398d1dcf0408d2533e2f9
parent5b1098dc0b486be2c21caa15b93e52c42372e0a4 (diff)
downloadpoky-c9f796dbd7300970282c4c4bba1ac8e2eca2fba9.tar.gz
kernel-dev: Re-write of the "Organizing Your Source" section.
A serious pass through this system to reorganize it. (From yocto-docs rev: f13abc59730d78e5ffa5bce3d38519f8fc4c127f) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/kernel-dev/kernel-dev-advanced.xml181
1 files changed, 111 insertions, 70 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index 35b935eced..adfd774a41 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -56,7 +56,7 @@ contain the highest level visible CONFIG options as presented by the Linux
56kernel menuconfig system. This reduces your maintenance effort and allows you 56kernel menuconfig system. This reduces your maintenance effort and allows you
57to further separate your configuration in ways that make sense for your project. 57to further separate your configuration in ways that make sense for your project.
58A common split is policy and hardware. For example, all your kernels may support 58A common split is policy and hardware. For example, all your kernels may support
59the proc and sys filesystems, but only specific boards will require sound, usb, 59the proc and sys filesystems, but only specific boards will require sound, USB,
60or specific drivers. Specifying these individually allows you to aggregate them 60or specific drivers. Specifying these individually allows you to aggregate them
61together as needed, but maintain them in only one place. Similar logic applies 61together as needed, but maintain them in only one place. Similar logic applies
62to source changes. 62to source changes.
@@ -136,7 +136,7 @@ to source changes.
136 The linux-yocto recipes define "standard", "tiny", and "preempt-rt" 136 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
137 kernel types. 137 kernel types.
138 See the <link linkend='kernel-types'>Kernel Types</link> section 138 See the <link linkend='kernel-types'>Kernel Types</link> section
139 for more inforation on kernel types. 139 for more information on kernel types.
140 </para> 140 </para>
141 141
142 <para> 142 <para>
@@ -237,7 +237,7 @@ Together with KMACHINE, this defines the search arguments used by the Yocto
237Project Linux kernel tools to find the appropriate description within the 237Project Linux kernel tools to find the appropriate description within the
238metadata with which to build out the sources and configuration. The linux-yocto 238metadata with which to build out the sources and configuration. The linux-yocto
239recipes define "standard", "tiny", and "preempt-rt" kernel types. See 3.3.4 for 239recipes define "standard", "tiny", and "preempt-rt" kernel types. See 3.3.4 for
240more inforation on kernel types. 240more information on kernel types.
241 241
242During the build, the kern-tools will search for the BSP description file that 242During the build, the kern-tools will search for the BSP description file that
243most closely matches the KMACHINE and LINUX_KERNEL_TYPE passed in from the 243most closely matches the KMACHINE and LINUX_KERNEL_TYPE passed in from the
@@ -332,7 +332,7 @@ or if you just don't want to maintain a Linux kernel git repository on your own.
332If you are doing active kernel development and are already maintaining a Linux 332If you are doing active kernel development and are already maintaining a Linux
333kernel git repository of your own, you may find it more convenient to work with 333kernel git repository of your own, you may find it more convenient to work with
334the meta-data in the same repository as the Linux kernel sources. This can make 334the meta-data in the same repository as the Linux kernel sources. This can make
335iterative development of the Linux kernel more efficient outside of the bitbake 335iterative development of the Linux kernel more efficient outside of the BitBake
336environment. 336environment.
337 337
338Regardless of where the meta-data is stored, the syntax as 338Regardless of where the meta-data is stored, the syntax as
@@ -406,10 +406,10 @@ meta/
406 `-- standard.cfg 406 `-- standard.cfg
407 407
408When the meta-data is stored in recipe-space, you must take steps to ensure 408When the meta-data is stored in recipe-space, you must take steps to ensure
409bitbake has the necessary information to decide which files to fetch and when 409BitBake has the necessary information to decide which files to fetch and when
410they need to be fetched again. 410they need to be fetched again.
411 411
412It is only necessary to specify the .scc files on the SRC_URI; bitbake will 412It is only necessary to specify the .scc files on the SRC_URI; BitBake will
413parse them and fetch any files referenced in the .scc files by the include, 413parse them and fetch any files referenced in the .scc files by the include,
414patch, or kconf commands. Because of this, it is necessary to bump the recipe PR 414patch, or kconf commands. Because of this, it is necessary to bump the recipe PR
415value when changing the content of files not explicitly listed in the SRC_URI. 415value when changing the content of files not explicitly listed in the SRC_URI.
@@ -1373,17 +1373,21 @@ the KTYPE has changed, now set to "tiny".
1373 </section> 1373 </section>
1374</section> 1374</section>
1375 1375
1376<section id='working-with-branches'> 1376<section id='organizing-your-source'>
1377 <title>Working with Branches</title> 1377 <title>Organizing Your Source</title>
1378 1378
1379 <para> 1379 <para>
1380 Many recipes based on the <filename>linux-yocto-custom.bb<filename> 1380 Many recipes based on the <filename>linux-yocto-custom.bb</filename>
1381 use Linux kernel sources that have only the single branch - "master". 1381 recipe use Linux kernel sources that have only a single
1382 branch - "master".
1383 This type of repository structure is fine for linear development
1384 supporting a single machine and architecture.
1382 However, if you work with multiple boards and architectures, 1385 However, if you work with multiple boards and architectures,
1383 you are likely to run into the situation where a series of patches 1386 a kernel source repository with multiple branches is more
1384 are needed for one board to boot. 1387 efficient.
1388 For example, suppose you need a series of patches for one board to boot.
1385 Sometimes, these patches are works-in-progress or fundamentally wrong, 1389 Sometimes, these patches are works-in-progress or fundamentally wrong,
1386 yet still necessary for specific boards. 1390 yet they are still necessary for specific boards.
1387 In these situations, you most likely do not want to include these 1391 In these situations, you most likely do not want to include these
1388 patches in every kernel you build (i.e. have the patches as part of 1392 patches in every kernel you build (i.e. have the patches as part of
1389 the lone "master" branch). 1393 the lone "master" branch).
@@ -1392,75 +1396,105 @@ the KTYPE has changed, now set to "tiny".
1392 </para> 1396 </para>
1393 1397
1394 <para> 1398 <para>
1395 If you are supporting multiple boards and architectures, you have 1399 Repository organization strategies exist that maximize source reuse,
1396 some options as to how you want to isolate your changes: 1400 remove redundancy, and logically order your changes.
1401 This section presents strategies for the following cases:
1397 <itemizedlist> 1402 <itemizedlist>
1398 <listitem><para><emphasis>Include feature patches in the BSP:</emphasis> 1403 <listitem><para>Encapsulating patches in a feature description
1399 Encapsulate patches in a feature description and only include 1404 and only including the patches in the BSP descriptions of
1400 the patches in the BSP descriptions of the applicable boards. 1405 the applicable boards.</para></listitem>
1401 For more information, see the 1406 <listitem><para>Creating a machine branch in your
1402 "<link linkend='patches'>Patches</link>" and 1407 kernel source repository and applying the patches on that
1403 "<link linkend='bsp-descriptions'>BSP Descriptions</link>" 1408 branch only.</para></listitem>
1404 sections.</para></listitem> 1409 <listitem><para>Creating a feature branch in your
1405 <listitem><para><emphasis>Create a machine branch:</emphasis> 1410 kernel source repository and merging that branch into your
1406 You can create a machine branch in your Linux kernel sources 1411 BSP when needed.</para></listitem>
1407 and apply the patches there. 1412 </itemizedlist>
1408 You can then specify this new branch as the
1409 <filename>KBRANCH</filename> to use for this board.
1410 You can do this in the recipe with the
1411 <filename>KBRANCH</filename> variable:
1412 <literallayout class='monospaced'>
1413 KBRANCH = "mynewbranch"
1414 </literallayout>
1415 or in the BSP description using the "branch" command:
1416 <literallayout class='monospaced'>
1417 mybsp.scc:
1418 define KMACHINE mybsp
1419 define KTYPE standard
1420 define KARCH i386
1421 include standard.scc
1422
1423 branch mynewbranch
1424
1425 include mybsp-hw.scc
1426 </literallayout>
1427 </para> 1413 </para>
1428 1414
1429 <para> 1415 <para>
1430 The approach you take, feature or branch, is entirely up to you 1416 The approach you take is entirely up to you
1431 and depends on what works best for your development model. 1417 and depends on what works best for your development model.
1432 If you are actively working on board support, you may find that
1433 working within a branch is more practical than trying to continually
1434 reintegrate your patches into a feature.
1435 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
1437 encapsulated feature to be appropriate as it does not require the
1438 additional complexity of branching in your Linux kernel sources.
1439 </para> 1418 </para>
1440 1419
1420 <section id='encapsulating-patches'>
1421 <title>Encapsulating Patches</title>
1422
1423 <para>
1424 if you are reusing patches from an external tree and are not
1425 working on the patches, you might find the encapsulated feature
1426 to be appropriate.
1427 Given this scenario, you don't need to create any branches in the
1428 source repository.
1429 Rather, you just take the static patches you need and encapsulate
1430 them within a feature description.
1431 Once you have the feature description, you simply include that into
1432 the BSP description as described in the
1433 "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
1434 section.
1435 </para>
1436
1437 <para>
1438 You can find information on how to create patches and BSP
1439 descriptions in the "<link linkend='patches'>Patches</link>" and
1440 "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
1441 sections.
1442 </para>
1443 </section>
1444
1441 <section id='machine-branches'> 1445 <section id='machine-branches'>
1442 <title>Machine Branches</title> 1446 <title>Machine Branches</title>
1443 1447
1444 <para> 1448 <para>
1445 The "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>" 1449 When you have multiple machines and architectures to support,
1446 section introduced the <filename>KBRANCH</filename> variable, which 1450 or you are actively working on board support, it is more
1447 defines the source branch to use from the Linux kernel Git repository 1451 efficient to create branches in the repository based on
1448 you are using. 1452 individual machines.
1453 Having machine branches allows common source to remain in the
1454 "master" branch with any features specific to a machine stored
1455 in the appropriate machine branch.
1456 This organization method frees you from continually reintegrating
1457 your patches into a feature.
1449 </para> 1458 </para>
1450 1459
1451 <para> 1460 <para>
1452 If you are supporting multiple boards and architectures and find 1461 Once you have a new branch, you can set up your kernel Metadata
1462 to use the branch a couple different ways.
1463 In the recipe, you can specify the new branch as the
1464 <filename>KBRANCH</filename> to use for the board as
1465 follows:
1466 <literallayout class='monospaced'>
1467 KBRANCH = "mynewbranch"
1468 </literallayout>
1469 Another method is to use the <filename>branch</filename> command
1470 in the BSP description:
1471 <literallayout class='monospaced'>
1472 mybsp.scc:
1473 define KMACHINE mybsp
1474 define KTYPE standard
1475 define KARCH i386
1476 include standard.scc
1477
1478 branch mynewbranch
1479
1480 include mybsp-hw.scc
1481 </literallayout>
1482 </para>
1483
1484 <para>
1485 If you find
1453 yourself with numerous branches, you might consider using a 1486 yourself with numerous branches, you might consider using a
1454 hierarchical branching system similar to what the linux-yocto Linux 1487 hierarchical branching system similar to what the linux-yocto Linux
1455 kernel repositories use: 1488 kernel repositories use:
1456 <literallayout class='monospaced'> 1489 <literallayout class='monospaced'>
1457 &lt;common&gt;/&lt;ktype&gt;/&lt;machine&gt; 1490 &lt;common&gt;/&lt;kernel_type&gt;/&lt;machine&gt;
1458 </literallayout> 1491 </literallayout>
1459 </para> 1492 </para>
1460 1493
1461 <para> 1494 <para>
1462 If you had two ktypes, standard and small for instance, and three 1495 If you had two kernel types, "standard" and "small" for
1463 machines, your Git tree might look like this: 1496 instance, and three machines, the branches in your
1497 Git repository might look like this:
1464 <literallayout class='monospaced'> 1498 <literallayout class='monospaced'>
1465 common/base 1499 common/base
1466 common/standard/base 1500 common/standard/base
@@ -1473,16 +1507,17 @@ the KTYPE has changed, now set to "tiny".
1473 </para> 1507 </para>
1474 1508
1475 <para> 1509 <para>
1476 This organization can help clarify the relationship of the branches to 1510 This organization can help clarify the branch relationships.
1477 each other. 1511 In this case, <filename>common/standard/machine_a</filename>
1478 In this case, "common/standard/machine_a" would include everything in 1512 includes everything in <filename>common/base</filename> and
1479 "common/base" and "common/standard/base". 1513 <filename>common/standard/base</filename>.
1480 The "standard" and "small" branches add sources specific to those 1514 The "standard" and "small" branches add sources specific to those
1481 kernel types that for whatever reason are not appropriate for the 1515 kernel types that for whatever reason are not appropriate for the
1482 other branches. 1516 other branches.
1483 <note>The "base" branches are an artifact of the way Git manages 1517 <note>The "base" branches are an artifact of the way Git manages
1484 its data internally on the filesystem: it will not allow you to use 1518 its data internally on the filesystem: Git will not allow you
1485 "common/standard" and "common/standard/machine_a" because it 1519 to use <filename>common/standard</filename> and
1520 <filename>common/standard/machine_a</filename> because it
1486 would have to create a file and a directory named "standard". 1521 would have to create a file and a directory named "standard".
1487 </note> 1522 </note>
1488 </para> 1523 </para>
@@ -1518,7 +1553,13 @@ mybsp.scc:
1518 define KARCH i386 1553 define KARCH i386
1519 include standard.scc 1554 include standard.scc
1520 1555
1521 branch mynewbranch 1556 branch mynewbranchIf you are actively
1557working on board support, you may find that working within a branch is more
1558practical than trying to continually reintegrate your patches into a feature. On
1559the other hand, if you are simply reusing some patches from an external tree and
1560are not working on them, you may find the encapsulated feature to be appropriate
1561as it does not require the additional complexity of branching in your Linux
1562kernel sources
1522 1563
1523 include mybsp.scc 1564 include mybsp.scc
1524 1565
@@ -1566,9 +1607,9 @@ Note: The "base" branches are an artifact of the way git manages its data
1566 <title>Feature Branches</title> 1607 <title>Feature Branches</title>
1567 1608
1568 <para> 1609 <para>
1569 During active development a new feature, it can be more efficient 1610 When you are actively developing new features, it can be more
1570 to work with that feature as a branch, rather than as a set of 1611 efficient to work with that feature as a branch, rather than
1571 patches which have to be regularly updated. 1612 as a set of patches that have to be regularly updated.
1572 The Yocto Project Linux kernel tools provide for this with 1613 The Yocto Project Linux kernel tools provide for this with
1573 the <filename>git merge</filename> command. 1614 the <filename>git merge</filename> command.
1574 </para> 1615 </para>