summaryrefslogtreecommitdiffstats
path: root/documentation/bsp-guide/bsp.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/bsp-guide/bsp.xml')
-rw-r--r--documentation/bsp-guide/bsp.xml416
1 files changed, 232 insertions, 184 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 72b065dad3..1edbc049de 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -1425,39 +1425,55 @@
1425 <title>Released BSP Recommendations</title> 1425 <title>Released BSP Recommendations</title>
1426 1426
1427 <para> 1427 <para>
1428 Following are recommendations for a released BSP that conforms to the 1428 Following are recommendations for released BSPs that
1429 Yocto Project: 1429 conform to the Yocto Project:
1430 <itemizedlist> 1430 <itemizedlist>
1431 <listitem><para><emphasis>Bootable Images:</emphasis> 1431 <listitem><para>
1432 BSP releases 1432 <emphasis>Bootable Images:</emphasis>
1433 can contain one or more bootable images. 1433 Released BSPs can contain one or more bootable
1434 Including bootable images allows users to easily try out the BSP 1434 images.
1435 on their own hardware.</para> 1435 Including bootable images allows users to easily
1436 <para>In some cases, it might not be convenient to include a 1436 try out the BSP using their own hardware.</para>
1437 bootable image. 1437
1438 In this case, you might want to make two versions of the 1438 <para>In some cases, it might not be convenient
1439 BSP available: one that contains binary images, and one 1439 to include a bootable image.
1440 that does not. 1440 If so, you might want to make two versions of the
1441 The version that does not contain bootable images avoids 1441 BSP available: one that contains binary images, and
1442 unnecessary download times for users not interested in the images. 1442 one that does not.
1443 </para> 1443 The version that does not contain bootable images
1444 <para>If you need to distribute a BSP and include bootable images or build kernel and 1444 avoids unnecessary download times for users not
1445 filesystems meant to allow users to boot the BSP for evaluation 1445 interested in the images.</para>
1446 purposes, you should put the images and artifacts within a 1446
1447 <filename>binary/</filename> subdirectory located in the 1447 <para>If you need to distribute a BSP and include
1448 <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. 1448 bootable images or build kernel and filesystems
1449 <note>If you do include a bootable image as part of the BSP and the image 1449 meant to allow users to boot the BSP for evaluation
1450 was built by software covered by the GPL or other open source licenses, 1450 purposes, you should put the images and artifacts
1451 it is your responsibility to understand 1451 within a
1452 and meet all licensing requirements, which could include distribution 1452 <filename>binary/</filename> subdirectory located
1453 of source files.</note></para></listitem> 1453 in the
1454 <listitem><para><emphasis>Use a Yocto Linux Kernel:</emphasis> 1454 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1455 Kernel recipes in the BSP should be based on a Yocto Linux kernel. 1455 directory.
1456 Basing your recipes on these kernels reduces the costs for maintaining 1456 <note>
1457 the BSP and increases its scalability. 1457 If you do include a bootable image as part
1458 See the <filename>Yocto Linux Kernel</filename> category in the 1458 of the BSP and the image was built by software
1459 covered by the GPL or other open source licenses,
1460 it is your responsibility to understand
1461 and meet all licensing requirements, which could
1462 include distribution of source files.
1463 </note>
1464 </para></listitem>
1465 <listitem><para>
1466 <emphasis>Use a Yocto Linux Kernel:</emphasis>
1467 Kernel recipes in the BSP should be based on a
1468 Yocto Linux kernel.
1469 Basing your recipes on these kernels reduces
1470 the costs for maintaining the BSP and increases
1471 its scalability.
1472 See the <filename>Yocto Linux Kernel</filename>
1473 category in the
1459 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink> 1474 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink>
1460 for these kernels.</para></listitem> 1475 for these kernels.
1476 </para></listitem>
1461 </itemizedlist> 1477 </itemizedlist>
1462 </para> 1478 </para>
1463 </section> 1479 </section>
@@ -1467,78 +1483,94 @@
1467 <title>Customizing a Recipe for a BSP</title> 1483 <title>Customizing a Recipe for a BSP</title>
1468 1484
1469 <para> 1485 <para>
1470 If you plan on customizing a recipe for a particular BSP, you need to do the 1486 If you plan on customizing a recipe for a particular BSP,
1471 following: 1487 you need to do the following:
1472 <itemizedlist> 1488 <itemizedlist>
1473 <listitem><para>Create a <filename>.bbappend</filename> 1489 <listitem><para>
1474 file for the modified recipe. 1490 Create a <filename>*.bbappend</filename> file for
1475 For information on using append files, see the 1491 the modified recipe.
1476 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>" 1492 For information on using append files, see the
1477 section in the Yocto Project Development Tasks Manual. 1493 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
1478 </para></listitem> 1494 section in the Yocto Project Development Tasks
1479 <listitem><para> 1495 Manual.
1480 Ensure your directory structure in the BSP layer 1496 </para></listitem>
1481 that supports your machine is such that it can be found 1497 <listitem><para>
1482 by the build system. 1498 Ensure your directory structure in the BSP layer
1483 See the example later in this section for more information. 1499 that supports your machine is such that the
1484 </para></listitem> 1500 OpenEmbedded build system can find it.
1485 <listitem><para> 1501 See the example later in this section for more
1486 Put the append file in a directory whose name matches 1502 information.
1487 the machine's name and is located in an appropriate 1503 </para></listitem>
1488 sub-directory inside the BSP layer (i.e. 1504 <listitem><para>
1489 <filename>recipes-bsp</filename>, <filename>recipes-graphics</filename>, 1505 Put the append file in a directory whose name matches
1490 <filename>recipes-core</filename>, and so forth). 1506 the machine's name and is located in an appropriate
1491 </para></listitem> 1507 sub-directory inside the BSP layer (i.e.
1492 <listitem><para>Place the BSP-specific files in the proper directory 1508 <filename>recipes-bsp</filename>,
1493 inside the BSP layer. 1509 <filename>recipes-graphics</filename>,
1494 How expansive the layer is affects where you must place these files. 1510 <filename>recipes-core</filename>, and so forth).
1495 For example, if your layer supports several different machine types, 1511 </para></listitem>
1496 you need to be sure your layer's directory structure includes hierarchy 1512 <listitem><para>
1497 that separates the files out according to machine. 1513 Place the BSP-specific files in the proper
1498 If your layer does not support multiple machines, the layer would not 1514 directory inside the BSP layer.
1499 have that additional hierarchy and the files would obviously not be 1515 How expansive the layer is affects where you must
1500 able to reside in a machine-specific directory. 1516 place these files.
1501 </para></listitem> 1517 For example, if your layer supports several
1502 </itemizedlist> 1518 different machine types, you need to be sure your
1503 </para> 1519 layer's directory structure includes hierarchy
1504 1520 that separates the files according to machine.
1505 <para> 1521 If your layer does not support multiple machines,
1506 Following is a specific example to help you better understand the process. 1522 the layer would not have that additional hierarchy
1507 Consider an example that customizes a recipe by adding 1523 and the files would obviously not be able to reside
1508 a BSP-specific configuration file named <filename>interfaces</filename> to the 1524 in a machine-specific directory.
1509 <filename>init-ifupdown_1.0.bb</filename> recipe for machine "xyz" where the 1525 </para></listitem>
1510 BSP layer also supports several other machines. 1526 </itemizedlist>
1511 Do the following: 1527 </para>
1512 <orderedlist> 1528
1513 <listitem><para>Edit the <filename>init-ifupdown_1.0.bbappend</filename> file so that it 1529 <para>
1514 contains the following: 1530 Following is a specific example to help you better understand
1515 <literallayout class='monospaced'> 1531 the process.
1532 This example customizes customizes a recipe by adding a
1533 BSP-specific configuration file named
1534 <filename>interfaces</filename> to the
1535 <filename>init-ifupdown_1.0.bb</filename> recipe for machine
1536 "xyz" where the BSP layer also supports several other
1537 machines:
1538 <orderedlist>
1539 <listitem><para>
1540 Edit the
1541 <filename>init-ifupdown_1.0.bbappend</filename> file
1542 so that it contains the following:
1543 <literallayout class='monospaced'>
1516 FILESEXTRAPATHS_prepend := "${THISDIR}/files:" 1544 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
1517 </literallayout> 1545 </literallayout>
1518 The append file needs to be in the 1546 The append file needs to be in the
1519 <filename>meta-xyz/recipes-core/init-ifupdown</filename> directory. 1547 <filename>meta-xyz/recipes-core/init-ifupdown</filename>
1520 </para></listitem> 1548 directory.
1521 <listitem><para>Create and place the new <filename>interfaces</filename> 1549 </para></listitem>
1522 configuration file in the BSP's layer here: 1550 <listitem><para>
1523 <literallayout class='monospaced'> 1551 Create and place the new
1552 <filename>interfaces</filename> configuration file in
1553 the BSP's layer here:
1554 <literallayout class='monospaced'>
1524 meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces 1555 meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
1525 </literallayout> 1556 </literallayout>
1526 <note> 1557 <note>
1527 If the <filename>meta-xyz</filename> layer did not support 1558 If the <filename>meta-xyz</filename> layer did
1528 multiple machines, you would place the 1559 not support multiple machines, you would place
1529 <filename>interfaces</filename> configuration file in the 1560 the <filename>interfaces</filename> configuration
1530 layer here: 1561 file in the layer here:
1531 <literallayout class='monospaced'> 1562 <literallayout class='monospaced'>
1532 meta-xyz/recipes-core/init-ifupdown/files/interfaces 1563 meta-xyz/recipes-core/init-ifupdown/files/interfaces
1533 </literallayout> 1564 </literallayout>
1534 </note> 1565 </note>
1535 The 1566 The
1536 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> 1567 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
1537 variable in the append files extends the search path 1568 variable in the append files extends the search path
1538 the build system uses to find files during the build. 1569 the build system uses to find files during the build.
1539 Consequently, for this example you need to have the 1570 Consequently, for this example you need to have the
1540 <filename>files</filename> directory in the same location 1571 <filename>files</filename> directory in the same
1541 as your append file.</para></listitem> 1572 location as your append file.
1573 </para></listitem>
1542 </orderedlist> 1574 </orderedlist>
1543 </para> 1575 </para>
1544 </section> 1576 </section>
@@ -1547,115 +1579,131 @@
1547 <title>BSP Licensing Considerations</title> 1579 <title>BSP Licensing Considerations</title>
1548 1580
1549 <para> 1581 <para>
1550 In some cases, a BSP contains separately licensed Intellectual Property (IP) 1582 In some cases, a BSP contains separately licensed
1551 for a component or components. 1583 Intellectual Property (IP) for a component or components.
1552 For these cases, you are required to accept the terms of a commercial or other 1584 For these cases, you are required to accept the terms
1553 type of license that requires some kind of explicit End User License Agreement (EULA). 1585 of a commercial or other type of license that requires
1554 Once the license is accepted, the OpenEmbedded build system can then build and 1586 some kind of explicit End User License Agreement (EULA).
1555 include the corresponding component in the final BSP image. 1587 Once you accept the license, the OpenEmbedded build system
1556 If the BSP is available as a pre-built image, you can download the image after 1588 can then build and include the corresponding component
1557 agreeing to the license or EULA. 1589 in the final BSP image.
1590 If the BSP is available as a pre-built image, you can
1591 download the image after agreeing to the license or EULA.
1558 </para> 1592 </para>
1559 1593
1560 <para> 1594 <para>
1561 You could find that some separately licensed components that are essential 1595 You could find that some separately licensed components
1562 for normal operation of the system might not have an unencumbered (or free) 1596 that are essential for normal operation of the system might
1563 substitute. 1597 not have an unencumbered (or free) substitute.
1564 Without these essential components, the system would be non-functional. 1598 Without these essential components, the system would be
1565 Then again, you might find that other licensed components that are simply 1599 non-functional.
1566 'good-to-have' or purely elective do have an unencumbered, free replacement 1600 Then again, you might find that other licensed components
1567 component that you can use rather than agreeing to the separately licensed component. 1601 that are simply 'good-to-have' or purely elective do have
1568 Even for components essential to the system, you might find an unencumbered component 1602 an unencumbered, free replacement component that you can
1569 that is not identical but will work as a less-capable version of the 1603 use rather than agreeing to the separately licensed
1570 licensed version in the BSP recipe. 1604 component.
1605 Even for components essential to the system, you might
1606 find an unencumbered component that is not identical but
1607 will work as a less-capable version of the licensed version
1608 in the BSP recipe.
1571 </para> 1609 </para>
1572 1610
1573 <para> 1611 <para>
1574 For cases where you can substitute a free component and still 1612 For cases where you can substitute a free component and
1575 maintain the system's functionality, the "Downloads" page from the 1613 still maintain the system's functionality, the "DOWNLOADS"
1576 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website's</ulink> 1614 selection from the "SOFTWARE" tab on the
1577 makes available de-featured BSPs 1615 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>
1578 that are completely free of any IP encumbrances. 1616 makes available de-featured BSPs that are completely free
1617 of any IP encumbrances.
1579 For these cases, you can use the substitution directly and 1618 For these cases, you can use the substitution directly and
1580 without any further licensing requirements. 1619 without any further licensing requirements.
1581 If present, these fully de-featured BSPs are named appropriately 1620 If present, these fully de-featured BSPs are named
1582 different as compared to the names of the respective 1621 appropriately different as compared to the names of their
1583 encumbered BSPs. 1622 respective encumbered BSPs.
1584 If available, these substitutions are your 1623 If available, these substitutions are your simplest and
1585 simplest and most preferred options. 1624 most preferred options.
1586 Use of these substitutions of course assumes the resulting functionality meets 1625 Obviously, use of these substitutions assumes the resulting
1587 system requirements. 1626 functionality meets system requirements.
1588 </para> 1627 <note>
1589 1628 If however, a non-encumbered version is unavailable or
1590 <para> 1629 it provides unsuitable functionality or quality, you can
1591 If however, a non-encumbered version is unavailable or 1630 use an encumbered version.
1592 it provides unsuitable functionality or quality, you can use an encumbered 1631 </note>
1593 version.
1594 </para> 1632 </para>
1595 1633
1596 <para> 1634 <para>
1597 A couple different methods exist within the OpenEmbedded build system to 1635 A couple different methods exist within the OpenEmbedded
1598 satisfy the licensing requirements for an encumbered BSP. 1636 build system to satisfy the licensing requirements for an
1637 encumbered BSP.
1599 The following list describes them in order of preference: 1638 The following list describes them in order of preference:
1600 <orderedlist> 1639 <orderedlist>
1601 <listitem><para><emphasis>Use the 1640 <listitem><para>
1641 <emphasis>Use the
1602 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink> 1642 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
1603 variable to define the recipes that have commercial or other 1643 Variable to Define the Recipes that Have Commercial
1604 types of specially-licensed packages:</emphasis> 1644 or Other Types of Specially-Licensed Packages:</emphasis>
1605 For each of those recipes, you can 1645 For each of those recipes, you can specify a
1606 specify a matching license string in a 1646 matching license string in a
1607 <filename>local.conf</filename> variable named 1647 <filename>local.conf</filename> variable named
1608 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>. 1648 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>.
1609 Specifying the matching license string signifies that you agree to the license. 1649 Specifying the matching license string signifies
1610 Thus, the build system can build the corresponding recipe and include 1650 that you agree to the license.
1611 the component in the image. 1651 Thus, the build system can build the corresponding
1652 recipe and include the component in the image.
1612 See the 1653 See the
1613 "<ulink url='&YOCTO_DOCS_CM_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>" 1654 "<ulink url='&YOCTO_DOCS_CM_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
1614 section in the Yocto Project Concepts Manual for details on how 1655 section in the Yocto Project Concepts Manual for
1615 to use these variables.</para> 1656 details on how to use these variables.</para>
1657
1616 <para>If you build as you normally would, without 1658 <para>If you build as you normally would, without
1617 specifying any recipes in the 1659 specifying any recipes in the
1618 <filename>LICENSE_FLAGS_WHITELIST</filename>, the build stops and 1660 <filename>LICENSE_FLAGS_WHITELIST</filename>, the
1619 provides you with the list of recipes that you have 1661 build stops and provides you with the list of recipes
1620 tried to include in the image that need entries in 1662 that you have tried to include in the image that
1621 the <filename>LICENSE_FLAGS_WHITELIST</filename>. 1663 need entries in the
1622 Once you enter the appropriate license flags into the whitelist, 1664 <filename>LICENSE_FLAGS_WHITELIST</filename>.
1623 restart the build to continue where it left off. 1665 Once you enter the appropriate license flags into
1666 the whitelist, restart the build to continue where
1667 it left off.
1624 During the build, the prompt will not appear again 1668 During the build, the prompt will not appear again
1625 since you have satisfied the requirement.</para> 1669 since you have satisfied the requirement.</para>
1626 <para>Once the appropriate license flags are on the white list 1670
1627 in the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, you 1671 <para>Once the appropriate license flags are on the
1628 can build the encumbered image with no change at all 1672 white list in the
1629 to the normal build process.</para></listitem> 1673 <filename>LICENSE_FLAGS_WHITELIST</filename> variable,
1630 <listitem><para><emphasis>Get a pre-built version of the BSP:</emphasis> 1674 you can build the encumbered image with no change
1631 You can get this type of BSP by visiting the 1675 at all to the normal build process.
1632 "Downloads" page of the 1676 </para></listitem>
1677 <listitem><para>
1678 <emphasis>Get a Pre-Built Version of the BSP:</emphasis>
1679 You can get this type of BSP by selecting the
1680 "DOWNLOADS" item from the "SOFTWARE" tab on the
1633 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>. 1681 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
1634 You can download BSP tarballs that contain proprietary components 1682 You can download BSP tarballs that contain
1635 after agreeing to the licensing 1683 proprietary components after agreeing to the
1636 requirements of each of the individually encumbered 1684 licensing requirements of each of the individually
1637 packages as part of the download process. 1685 encumbered packages as part of the download process.
1638 Obtaining the BSP this way allows you to access an encumbered 1686 Obtaining the BSP this way allows you to access an
1639 image immediately after agreeing to the 1687 encumbered image immediately after agreeing to the
1640 click-through license agreements presented by the 1688 click-through license agreements presented by the
1641 website. 1689 website.
1642 Note that if you want to build the image 1690 If you want to build the image yourself using
1643 yourself using the recipes contained within the BSP 1691 the recipes contained within the BSP tarball,
1644 tarball, you will still need to create an 1692 you will still need to create an appropriate
1645 appropriate <filename>LICENSE_FLAGS_WHITELIST</filename> to match the 1693 <filename>LICENSE_FLAGS_WHITELIST</filename>
1646 encumbered recipes in the BSP.</para></listitem> 1694 to match the encumbered recipes in the BSP.
1695 </para></listitem>
1647 </orderedlist> 1696 </orderedlist>
1697 <note>
1698 Pre-compiled images are bundled with a time-limited
1699 kernel that runs for a predetermined amount of time
1700 (10 days) before it forces the system to reboot.
1701 This limitation is meant to discourage direct
1702 redistribution of the image.
1703 You must eventually rebuild the image if you want
1704 to remove this restriction.
1705 </note>
1648 </para> 1706 </para>
1649
1650 <note>
1651 Pre-compiled images are bundled with
1652 a time-limited kernel that runs for a
1653 predetermined amount of time (10 days) before it forces
1654 the system to reboot.
1655 This limitation is meant to discourage direct redistribution
1656 of the image.
1657 You must eventually rebuild the image if you want to remove this restriction.
1658 </note>
1659 </section> 1707 </section>
1660 1708
1661 <section id='using-the-yocto-projects-bsp-tools'> 1709 <section id='using-the-yocto-projects-bsp-tools'>
@@ -1818,7 +1866,7 @@
1818 IF THERE IS A LAUNDRY LIST OF ITEMS THAT NEED DEFINITION OR GET SET 1866 IF THERE IS A LAUNDRY LIST OF ITEMS THAT NEED DEFINITION OR GET SET
1819 UP AS A RESULT OF THIS PROCEDURE, LIST THEM HERE.] 1867 UP AS A RESULT OF THIS PROCEDURE, LIST THEM HERE.]
1820 <itemizedlist> 1868 <itemizedlist>
1821 <listitem><para>[PAREMETER 1]</para></listitem> 1869 <listitem><para>[PARAMETER 1]</para></listitem>
1822 <listitem><para>[PARAMETER 2]</para></listitem> 1870 <listitem><para>[PARAMETER 2]</para></listitem>
1823 <listitem><para>[PARAMETER 3]</para></listitem> 1871 <listitem><para>[PARAMETER 3]</para></listitem>
1824 <listitem><para>[PARAMETER 4]</para></listitem> 1872 <listitem><para>[PARAMETER 4]</para></listitem>
@@ -1887,7 +1935,7 @@
1887 </para> 1935 </para>
1888 1936
1889<!-- <para> 1937<!-- <para>
1890 [ASSUMING SIMLILAR ACTION OCCURS]As the [SUBCOMMAND] command runs, default values for 1938 [ASSUMING SIMILAR ACTION OCCURS]As the [SUBCOMMAND] command runs, default values for
1891 the prompts appear in brackets. 1939 the prompts appear in brackets.
1892 Pressing enter without supplying anything on the command line or pressing enter 1940 Pressing enter without supplying anything on the command line or pressing enter
1893 with an invalid response causes the script to accept the default value. 1941 with an invalid response causes the script to accept the default value.
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-12 00:45:27 +0000