diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2012-12-27 14:50:40 -0600 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2013-01-16 15:59:12 +0000 |
commit | 49166264bd93d2e4c0b4fcf3641468b37ca18b84 (patch) | |
tree | 543bb003e3a9cebc592b97ef58f74e04a1b6aec8 /documentation/kernel-dev | |
parent | fe1b20f80a2bd1c8c19b8cdb59c04ec2095794d4 (diff) | |
download | poky-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.xml | 182 |
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 | <common>/<ktype>/<machine> | ||
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'> | ||
1421 | Section 3.1 introduced the KBRANCH variable which defines the source branch to | ||
1422 | use from the Linux kernel git repository you are using. Many linux-yocto-custom | ||
1423 | derived recipes will be using Linux kernel sources with only a single branch: | ||
1424 | "master". However, when you are working with multiple boards and architectures, | ||
1425 | you are likely to run into the situation where a series of patches are needed | ||
1426 | for one board to boot. Sometimes these patches are works in progress or | ||
1427 | fundamentally wrong, yet still necessary for specific boards. In these | ||
1428 | situations, you most likely do not want to include these patches in every kernel | ||
1429 | you build. You have a couple of options. | ||
1430 | |||
1431 | First, you could encapsulate these patches in a feature description and only | ||
1432 | include them in the BSP description for the board(s) that require them (see | ||
1433 | 3.3.2 and 3.3.5). | ||
1434 | |||
1435 | Alternatively, you can create a branch in your Linux kernel sources and apply | ||
1436 | the patches there. You can then specify this new branch as the KBRANCH to use | ||
1437 | for this board. You can do this in the recipe with the KBRANCH variable: | ||
1438 | |||
1439 | KBRANCH = "mynewbranch" | ||
1440 | |||
1441 | or in the BSP description using the "branch" command: | ||
1442 | |||
1443 | mybsp.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 | |||
1453 | The decision of which approach to take, feature or branch, is entirely up to you | ||
1454 | and depends on what works best for your development model. If you are actively | ||
1455 | working on board support, you may find that working within a branch is more | ||
1456 | practical than trying to continually reintegrate your patches into a feature. On | ||
1457 | the other hand, if you are simply reusing some patches from an external tree and | ||
1458 | are not working on them, you may find the encapsulated feature to be appropriate | ||
1459 | as it does not require the additional complexity of branching in your Linux | ||
1460 | kernel sources. | ||
1461 | |||
1462 | If you are supporting multiple boards and architectures and find yourself with | ||
1463 | numerous branches, you might consider using a hierarchical branching system | ||
1464 | similar to what the linux-yocto Linux kernel repositories use: | ||
1465 | |||
1466 | <common>/<ktype>/<machine> | ||
1467 | |||
1468 | If you had two ktypes, standard and small for instance, and three machines, your | ||
1469 | git 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 | |||
1479 | This organization can help clarify the relationship of the branches to | ||
1480 | each other. In this case, "common/standard/machine_a" would include everything in | ||
1481 | "common/base" and "common/standard/base". The "standard" and "small" branches | ||
1482 | add sources specific to those kernel types that for whatever reason are not | ||
1483 | appropriate for the other branches. | ||
1484 | |||
1485 | Note: 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 | <!-- |
1313 | vim: expandtab tw=80 ts=4 | 1495 | vim: expandtab tw=80 ts=4 |