summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-09-26 14:33:56 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-10-06 12:06:32 +0100
commitb8dfb037646c4ccbfda61241e654a703a16cf14b (patch)
treee9825f4589e1a2acd0d0f413a39b136143d0d2bf
parentfcdfe09d9cc4e2977bd602dfd18f729cd9f6d73d (diff)
downloadpoky-b8dfb037646c4ccbfda61241e654a703a16cf14b.tar.gz
kernel-dev: Updated kernel configuration section
A lot of rewriting here in this section to get it up to speed. Also, moved that final section on determining hardware and non-hardware features into an appendix where it belonged. (From yocto-docs rev: 752e80d6ae8f81a0de7743b11b010d0ef36b314b) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml369
-rw-r--r--documentation/kernel-dev/kernel-dev-concepts-appx.xml117
2 files changed, 244 insertions, 242 deletions
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index 0614414955..310e2236f7 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -10,8 +10,8 @@
10 work with the Yocto Project Linux kernel. 10 work with the Yocto Project Linux kernel.
11 These tasks include preparing your host development system for 11 These tasks include preparing your host development system for
12 kernel development, preparing a layer, modifying an existing recipe, 12 kernel development, preparing a layer, modifying an existing recipe,
13 patching the kernel, iterative development, working with your own sources, 13 patching the kernel, configuring the kernel, iterative development,
14 and incorporating out-of-tree modules. 14 working with your own sources, and incorporating out-of-tree modules.
15 <note> 15 <note>
16 The examples presented in this chapter work with the Yocto Project 16 The examples presented in this chapter work with the Yocto Project
17 2.4 Release and forward. 17 2.4 Release and forward.
@@ -1447,34 +1447,6 @@
1447 </para> 1447 </para>
1448 </section> 1448 </section>
1449 1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478 <section id='configuring-the-kernel'> 1450 <section id='configuring-the-kernel'>
1479 <title>Configuring the Kernel</title> 1451 <title>Configuring the Kernel</title>
1480 1452
@@ -1516,17 +1488,22 @@
1516 </para> 1488 </para>
1517 1489
1518 <para> 1490 <para>
1519 To use the <filename>menuconfig</filename> tool in the Yocto Project development 1491 To use the <filename>menuconfig</filename> tool in the Yocto
1520 environment, you must launch it using BitBake. 1492 Project development environment, you must launch it using
1493 BitBake.
1521 Thus, the environment must be set up using the 1494 Thus, the environment must be set up using the
1522 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> 1495 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1523 script found in the 1496 script found in the
1524 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. 1497 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
1525 You must also be sure of the state of your build in the 1498 You must also be sure of the state of your build's configuration
1499 in the
1526 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. 1500 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
1527 The following commands run <filename>menuconfig</filename> 1501 The following commands initialize the BitBake environment,
1528 assuming the Source Directory's top-level folder is 1502 run the
1529 <filename>~/poky</filename>: 1503 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></ulink>
1504 task, and launch <filename>menuconfig</filename>.
1505 These commands assume the Source Directory's top-level folder
1506 is <filename>~/poky</filename>:
1530 <literallayout class='monospaced'> 1507 <literallayout class='monospaced'>
1531 $ cd poky 1508 $ cd poky
1532 $ source oe-init-build-env 1509 $ source oe-init-build-env
@@ -1542,79 +1519,81 @@
1542 </para> 1519 </para>
1543 1520
1544 <para> 1521 <para>
1545 Consider an example that configures the <filename>linux-yocto-3.14</filename> 1522 Consider an example that configures the "CONFIG_SMP" setting
1546 kernel. 1523 for the <filename>linux-yocto-4.12</filename> kernel.
1547 The OpenEmbedded build system recognizes this kernel as 1524 <note>
1548 <filename>linux-yocto</filename>. 1525 The OpenEmbedded build system recognizes this kernel as
1549 Thus, the following commands from the shell in which you previously sourced the 1526 <filename>linux-yocto</filename> through Metadata (e.g.
1550 environment initialization script cleans the shared state cache and the 1527 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink><filename>_linux-yocto ?= "12.4%"</filename>).
1551 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink> 1528 </note>
1552 directory and then runs <filename>menuconfig</filename>: 1529 Once <filename>menuconfig</filename> launches, use the
1553 <literallayout class='monospaced'> 1530 interface to navigate through the selections to find the
1554 $ bitbake linux-yocto -c menuconfig 1531 configuration settings in which you are interested.
1555 </literallayout> 1532 For this example, you deselect "CONFIG_SMP" by clearing the
1556 </para> 1533 "Symmetric Multi-Processing Support" option.
1557 1534 Using the interface, you can find the option under
1558 <para> 1535 "Processor Type and Features".
1559 Once <filename>menuconfig</filename> launches, use the interface 1536 To deselect "CONFIG_SMP", use the arrow keys to
1560 to navigate through the selections to find the configuration settings in 1537 highlight "Symmetric Multi-Processing Support" and enter "N"
1561 which you are interested. 1538 to clear the asterisk.
1562 For example, consider the <filename>CONFIG_SMP</filename> configuration setting. 1539 When you are finished, exit out and save the change.
1563 You can find it at <filename>Processor Type and Features</filename> under 1540 </para>
1564 the configuration selection <filename>Symmetric Multi-processing Support</filename>. 1541
1565 After highlighting the selection, use the arrow keys to select or deselect 1542 <para>
1566 the setting. 1543 Saving the selections updates the <filename>.config</filename>
1567 When you are finished with all your selections, exit out and save them. 1544 configuration file.
1568 </para> 1545 This is the file that the OpenEmbedded build system uses to
1569 1546 configure the kernel during the build.
1570 <para>
1571 Saving the selections updates the <filename>.config</filename> configuration file.
1572 This is the file that the OpenEmbedded build system uses to configure the
1573 kernel during the build.
1574 You can find and examine this file in the Build Directory in 1547 You can find and examine this file in the Build Directory in
1575 <filename>tmp/work/</filename>. 1548 <filename>tmp/work/</filename>.
1576 The actual <filename>.config</filename> is located in the area where the 1549 The actual <filename>.config</filename> is located in the
1577 specific kernel is built. 1550 area where the specific kernel is built.
1578 For example, if you were building a Linux Yocto kernel based on the 1551 For example, if you were building a Linux Yocto kernel based
1579 Linux 3.14 kernel and you were building a QEMU image targeted for 1552 on the <filename>linux-yocto-4.12</filename> kernel and you
1553 were building a QEMU image targeted for
1580 <filename>x86</filename> architecture, the 1554 <filename>x86</filename> architecture, the
1581 <filename>.config</filename> file would be located here: 1555 <filename>.config</filename> file would be:
1582 <literallayout class='monospaced'> 1556 <literallayout class='monospaced'>
1583 poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.14.11+git1+84f... 1557 poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18...
1584 ...656ed30-r1/linux-qemux86-standard-build 1558 ...967-r0/linux-qemux86-standard-build/.config
1585 </literallayout> 1559 </literallayout>
1586 <note> 1560 <note>
1587 The previous example directory is artificially split and many of the characters 1561 The previous example directory is artificially split and
1588 in the actual filename are omitted in order to make it more readable. 1562 many of the characters in the actual filename are omitted
1589 Also, depending on the kernel you are using, the exact pathname 1563 in order to make it more readable.
1590 for <filename>linux-yocto-3.14...</filename> might differ. 1564 Also, depending on the kernel you are using, the exact
1565 pathname might differ.
1591 </note> 1566 </note>
1592 </para> 1567 </para>
1593 1568
1594 <para> 1569 <para>
1595 Within the <filename>.config</filename> file, you can see the kernel settings. 1570 Within the <filename>.config</filename> file, you can see the
1596 For example, the following entry shows that symmetric multi-processor support 1571 kernel settings.
1597 is not set: 1572 For example, the following entry shows that symmetric
1573 multi-processor support is not set:
1598 <literallayout class='monospaced'> 1574 <literallayout class='monospaced'>
1599 # CONFIG_SMP is not set 1575 # CONFIG_SMP is not set
1600 </literallayout> 1576 </literallayout>
1601 </para> 1577 </para>
1602 1578
1603 <para> 1579 <para>
1604 A good method to isolate changed configurations is to use a combination of the 1580 A good method to isolate changed configurations is to use a
1605 <filename>menuconfig</filename> tool and simple shell commands. 1581 combination of the <filename>menuconfig</filename> tool and
1606 Before changing configurations with <filename>menuconfig</filename>, copy the 1582 simple shell commands.
1607 existing <filename>.config</filename> and rename it to something else, 1583 Before changing configurations with
1608 use <filename>menuconfig</filename> to make 1584 <filename>menuconfig</filename>, copy the existing
1609 as many changes as you want and save them, then compare the renamed configuration 1585 <filename>.config</filename> and rename it to something else,
1586 use <filename>menuconfig</filename> to make as many changes as
1587 you want and save them, then compare the renamed configuration
1610 file against the newly created file. 1588 file against the newly created file.
1611 You can use the resulting differences as your base to create configuration fragments 1589 You can use the resulting differences as your base to create
1612 to permanently save in your kernel layer. 1590 configuration fragments to permanently save in your kernel
1591 layer.
1613 <note> 1592 <note>
1614 Be sure to make a copy of the <filename>.config</filename> and don't just 1593 Be sure to make a copy of the <filename>.config</filename>
1615 rename it. 1594 file and do not just rename it.
1616 The build system needs an existing <filename>.config</filename> 1595 The build system needs an existing
1617 from which to work. 1596 <filename>.config</filename> file from which to work.
1618 </note> 1597 </note>
1619 </para> 1598 </para>
1620 </section> 1599 </section>
@@ -1647,7 +1626,8 @@
1647 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> 1626 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
1648 directory in your layer's 1627 directory in your layer's
1649 <filename>recipes-kernel/linux</filename> directory, and rename 1628 <filename>recipes-kernel/linux</filename> directory, and rename
1650 the copied file to "defconfig". 1629 the copied file to "defconfig" (e.g.
1630 <filename>~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig</filename>).
1651 Then, add the following lines to the linux-yocto 1631 Then, add the following lines to the linux-yocto
1652 <filename>.bbappend</filename> file in your layer: 1632 <filename>.bbappend</filename> file in your layer:
1653 <literallayout class='monospaced'> 1633 <literallayout class='monospaced'>
@@ -1678,8 +1658,7 @@
1678 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration'>Changing the Configuration</ulink>" 1658 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration'>Changing the Configuration</ulink>"
1679 and 1659 and
1680 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>" 1660 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>"
1681 sections, both in the Yocto Project Linux Kernel Development 1661 sections.
1682 Manual.
1683 </para> 1662 </para>
1684 </section> 1663 </section>
1685 1664
@@ -1687,21 +1666,39 @@
1687 <title>Creating Configuration Fragments</title> 1666 <title>Creating Configuration Fragments</title>
1688 1667
1689 <para> 1668 <para>
1690 Configuration fragments are simply kernel options that appear in a file 1669 Configuration fragments are simply kernel options that
1691 placed where the OpenEmbedded build system can find and apply them. 1670 appear in a file placed where the OpenEmbedded build system
1692 Syntactically, the configuration statement is identical to what would appear 1671 can find and apply them.
1693 in the <filename>.config</filename> file, which is in the 1672 The build system applies configuration fragments after
1694 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>: 1673 applying configurations from a <filename>defconfig</filename>
1695 <literallayout class='monospaced'> 1674 file.
1696 tmp/work/<replaceable>arch</replaceable>-poky-linux/linux-yocto-<replaceable>release_specific_string</replaceable>/linux-<replaceable>arch</replaceable>-<replaceable>build_type</replaceable> 1675 Thus, the final kernel configuration is a combination of the
1697 </literallayout> 1676 configurations in the <filename>defconfig</filename>
1677 file and then any configuration fragments you provide.
1678 The build system applies fragments on top of and
1679 after applying the existing defconfig file configurations.
1680 </para>
1681
1682 <para>
1683 Syntactically, the configuration statement is identical to
1684 what would appear in the <filename>.config</filename> file,
1685 which is in the
1686 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
1687 <note>
1688 For more information about where the
1689 <filename>.config</filename> file is located, see the
1690 example in the
1691 "<link linkend='using-menuconfig'>Using <filename>menuconfig</filename></link>"
1692 section.
1693 </note>
1698 </para> 1694 </para>
1699 1695
1700 <para> 1696 <para>
1701 It is simple to create a configuration fragment. 1697 It is simple to create a configuration fragment.
1702 For example, issuing the following from the shell creates a configuration fragment 1698 For example, issuing the following from the shell creates a
1703 file named <filename>my_smp.cfg</filename> that enables multi-processor support 1699 configuration fragment file named
1704 within the kernel: 1700 <filename>my_smp.cfg</filename> that enables multi-processor
1701 support within the kernel:
1705 <literallayout class='monospaced'> 1702 <literallayout class='monospaced'>
1706 $ echo "CONFIG_SMP=y" >> my_smp.cfg 1703 $ echo "CONFIG_SMP=y" >> my_smp.cfg
1707 </literallayout> 1704 </literallayout>
@@ -1715,29 +1712,34 @@
1715 1712
1716 <para> 1713 <para>
1717 Where do you put your configuration fragment files? 1714 Where do you put your configuration fragment files?
1718 You can place these files in the same area pointed to by 1715 You can place these files in an area pointed to by
1719 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>. 1716 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1717 as directed by your <filename>bblayers.conf</filename> file,
1718 which is located in your layer.
1720 The OpenEmbedded build system picks up the configuration and 1719 The OpenEmbedded build system picks up the configuration and
1721 adds it to the kernel's configuration. 1720 adds it to the kernel's configuration.
1722 For example, suppose you had a set of configuration options 1721 For example, suppose you had a set of configuration options
1723 in a file called <filename>myconfig.cfg</filename>. 1722 in a file called <filename>myconfig.cfg</filename>.
1724 If you put that file inside a directory named 1723 If you put that file inside a directory named
1725 <filename>linux-yocto</filename> that resides in the same 1724 <filename>linux-yocto</filename> that resides in the same
1726 directory as the kernel's append file and then add a 1725 directory as the kernel's append file within your layer
1727 <filename>SRC_URI</filename> statement such as the following 1726 and then add the following statements to the kernel's append
1728 to the kernel's append file, those configuration options 1727 file, those configuration options will be picked up and applied
1729 will be picked up and applied when the kernel is built. 1728 when the kernel is built:
1730 <literallayout class='monospaced'> 1729 <literallayout class='monospaced'>
1730 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1731 SRC_URI += "file://myconfig.cfg" 1731 SRC_URI += "file://myconfig.cfg"
1732 </literallayout> 1732 </literallayout>
1733 </para> 1733 </para>
1734 1734
1735 <para> 1735 <para>
1736 As mentioned earlier, you can group related configurations into multiple files and 1736 As mentioned earlier, you can group related configurations
1737 name them all in the <filename>SRC_URI</filename> statement as well. 1737 into multiple files and name them all in the
1738 For example, you could group separate configurations specifically for Ethernet and graphics 1738 <filename>SRC_URI</filename> statement as well.
1739 into their own files and add those by using a <filename>SRC_URI</filename> statement like the 1739 For example, you could group separate configurations
1740 following in your append file: 1740 specifically for Ethernet and graphics into their own files
1741 and add those by using a <filename>SRC_URI</filename> statement
1742 like the following in your append file:
1741 <literallayout class='monospaced'> 1743 <literallayout class='monospaced'>
1742 SRC_URI += "file://myconfig.cfg \ 1744 SRC_URI += "file://myconfig.cfg \
1743 file://eth.cfg \ 1745 file://eth.cfg \
@@ -1797,7 +1799,11 @@
1797 </para></listitem> 1799 </para></listitem>
1798 <listitem><para>Separately run the 1800 <listitem><para>Separately run the
1799 <filename>do_kernel_configme</filename> and 1801 <filename>do_kernel_configme</filename> and
1800 <filename>do_kernel_configcheck</filename> tasks. 1802 <filename>do_kernel_configcheck</filename> tasks:
1803 <literallayout class='monospaced'>
1804 $ bitbake linux-yocto -c kernel_configme -f
1805 $ bitbake linux-yocto -c kernel_configcheck -f
1806 </literallayout>
1801 </para></listitem> 1807 </para></listitem>
1802 <listitem><para>Take the resulting list of files from the 1808 <listitem><para>Take the resulting list of files from the
1803 <filename>do_kernel_configcheck</filename> task 1809 <filename>do_kernel_configcheck</filename> task
@@ -1834,135 +1840,14 @@
1834 </para> 1840 </para>
1835 1841
1836 <para> 1842 <para>
1837 Iteratively working through steps two through four eventually yields 1843 Iteratively working through steps two through four eventually
1838 a minimal, streamlined configuration file. 1844 yields a minimal, streamlined configuration file.
1839 Once you have the best <filename>.config</filename>, you can build the Linux 1845 Once you have the best <filename>.config</filename>, you can
1840 Yocto kernel. 1846 build the Linux Yocto kernel.
1841 </para>
1842 </section>
1843
1844 <section id='determining-hardware-and-non-hardware-features-for-the-kernel-configuration-audit-phase'>
1845 <title>Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase</title>
1846
1847 <para>
1848 This section describes part of the kernel configuration audit
1849 phase that most developers can ignore.
1850 During this part of the audit phase, the contents of the final
1851 <filename>.config</filename> file are compared against the
1852 fragments specified by the system.
1853 These fragments can be system fragments, distro fragments,
1854 or user specified configuration elements.
1855 Regardless of their origin, the OpenEmbedded build system
1856 warns the user if a specific option is not included in the
1857 final kernel configuration.
1858 </para>
1859
1860 <para>
1861 In order to not overwhelm the user with configuration warnings,
1862 by default the system only reports on missing "hardware"
1863 options because a missing hardware option could mean a boot
1864 failure or that important hardware is not available.
1865 </para>
1866
1867 <para>
1868 To determine whether or not a given option is "hardware" or
1869 "non-hardware", the kernel Metadata contains files that
1870 classify individual or groups of options as either hardware
1871 or non-hardware.
1872 To better show this, consider a situation where the
1873 Yocto Project kernel cache contains the following files:
1874 <literallayout class='monospaced'>
1875 kernel-cache/features/drm-psb/hardware.cfg
1876 kernel-cache/features/kgdb/hardware.cfg
1877 kernel-cache/ktypes/base/hardware.cfg
1878 kernel-cache/bsp/mti-malta32/hardware.cfg
1879 kernel-cache/bsp/fsl-mpc8315e-rdb/hardware.cfg
1880 kernel-cache/bsp/qemu-ppc32/hardware.cfg
1881 kernel-cache/bsp/qemuarma9/hardware.cfg
1882 kernel-cache/bsp/mti-malta64/hardware.cfg
1883 kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg
1884 kernel-cache/bsp/common-pc/hardware.cfg
1885 kernel-cache/bsp/common-pc-64/hardware.cfg
1886 kernel-cache/features/rfkill/non-hardware.cfg
1887 kernel-cache/ktypes/base/non-hardware.cfg
1888 kernel-cache/features/aufs/non-hardware.kcf
1889 kernel-cache/features/ocf/non-hardware.kcf
1890 kernel-cache/ktypes/base/non-hardware.kcf
1891 kernel-cache/ktypes/base/hardware.kcf
1892 kernel-cache/bsp/qemu-ppc32/hardware.kcf
1893 </literallayout>
1894 The following list provides explanations for the various
1895 files:
1896 <itemizedlist>
1897 <listitem><para><filename>hardware.kcf</filename>:
1898 Specifies a list of kernel Kconfig files that contain
1899 hardware options only.
1900 </para></listitem>
1901 <listitem><para><filename>non-hardware.kcf</filename>:
1902 Specifies a list of kernel Kconfig files that contain
1903 non-hardware options only.
1904 </para></listitem>
1905 <listitem><para><filename>hardware.cfg</filename>:
1906 Specifies a list of kernel
1907 <filename>CONFIG_</filename> options that are hardware,
1908 regardless of whether or not they are within a Kconfig
1909 file specified by a hardware or non-hardware
1910 Kconfig file (i.e. <filename>hardware.kcf</filename> or
1911 <filename>non-hardware.kcf</filename>).
1912 </para></listitem>
1913 <listitem><para><filename>non-hardware.cfg</filename>:
1914 Specifies a list of kernel
1915 <filename>CONFIG_</filename> options that are
1916 not hardware, regardless of whether or not they are
1917 within a Kconfig file specified by a hardware or
1918 non-hardware Kconfig file (i.e.
1919 <filename>hardware.kcf</filename> or
1920 <filename>non-hardware.kcf</filename>).
1921 </para></listitem>
1922 </itemizedlist>
1923 Here is a specific example using the
1924 <filename>kernel-cache/bsp/mti-malta32/hardware.cfg</filename>:
1925 <literallayout class='monospaced'>
1926 CONFIG_SERIAL_8250
1927 CONFIG_SERIAL_8250_CONSOLE
1928 CONFIG_SERIAL_8250_NR_UARTS
1929 CONFIG_SERIAL_8250_PCI
1930 CONFIG_SERIAL_CORE
1931 CONFIG_SERIAL_CORE_CONSOLE
1932 CONFIG_VGA_ARB
1933 </literallayout>
1934 The kernel configuration audit automatically detects these
1935 files (hence the names must be exactly the ones discussed here),
1936 and uses them as inputs when generating warnings about the
1937 final <filename>.config</filename> file.
1938 </para>
1939
1940 <para>
1941 A user-specified kernel Metadata repository, or recipe space
1942 feature, can use these same files to classify options that are
1943 found within its <filename>.cfg</filename> files as hardware
1944 or non-hardware, to prevent the OpenEmbedded build system from
1945 producing an error or warning when an option is not in the
1946 final <filename>.config</filename> file.
1947 </para> 1847 </para>
1948 </section> 1848 </section>
1949 </section> 1849 </section>
1950 1850
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966 <section id='using-an-iterative-development-process'> 1851 <section id='using-an-iterative-development-process'>
1967 <title>Using an Iterative Development Process</title> 1852 <title>Using an Iterative Development Process</title>
1968 1853
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
index 4cacdd13ee..6d236855dd 100644
--- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -479,6 +479,123 @@
479 section for a detailed example that modifies the kernel. 479 section for a detailed example that modifies the kernel.
480 </para> 480 </para>
481 </section> 481 </section>
482
483 <section id='determining-hardware-and-non-hardware-features-for-the-kernel-configuration-audit-phase'>
484 <title>Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase</title>
485
486 <para>
487 This section describes part of the kernel configuration audit
488 phase that most developers can ignore.
489 For general information on kernel configuration including
490 <filename>menuconfig</filename>, <filename>defconfig</filename>
491 files, and configuration fragments, see the
492 "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>"
493 section.
494 </para>
495
496 <para>
497 During this part of the audit phase, the contents of the final
498 <filename>.config</filename> file are compared against the
499 fragments specified by the system.
500 These fragments can be system fragments, distro fragments,
501 or user-specified configuration elements.
502 Regardless of their origin, the OpenEmbedded build system
503 warns the user if a specific option is not included in the
504 final kernel configuration.
505 </para>
506
507 <para>
508 By default, in order to not overwhelm the user with
509 configuration warnings, the system only reports missing
510 "hardware" options as they could result in a boot
511 failure or indicate that important hardware is not available.
512 </para>
513
514 <para>
515 To determine whether or not a given option is "hardware" or
516 "non-hardware", the kernel Metadata contains files that
517 classify individual or groups of options as either hardware
518 or non-hardware.
519 To better show this, consider a situation where the
520 Yocto Project kernel cache contains the following files:
521 <literallayout class='monospaced'>
522 kernel-cache/features/drm-psb/hardware.cfg
523 kernel-cache/features/kgdb/hardware.cfg
524 kernel-cache/ktypes/base/hardware.cfg
525 kernel-cache/bsp/mti-malta32/hardware.cfg
526 kernel-cache/bsp/fsl-mpc8315e-rdb/hardware.cfg
527 kernel-cache/bsp/qemu-ppc32/hardware.cfg
528 kernel-cache/bsp/qemuarma9/hardware.cfg
529 kernel-cache/bsp/mti-malta64/hardware.cfg
530 kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg
531 kernel-cache/bsp/common-pc/hardware.cfg
532 kernel-cache/bsp/common-pc-64/hardware.cfg
533 kernel-cache/features/rfkill/non-hardware.cfg
534 kernel-cache/ktypes/base/non-hardware.cfg
535 kernel-cache/features/aufs/non-hardware.kcf
536 kernel-cache/features/ocf/non-hardware.kcf
537 kernel-cache/ktypes/base/non-hardware.kcf
538 kernel-cache/ktypes/base/hardware.kcf
539 kernel-cache/bsp/qemu-ppc32/hardware.kcf
540 </literallayout>
541 The following list provides explanations for the various
542 files:
543 <itemizedlist>
544 <listitem><para>
545 <filename>hardware.kcf</filename>:
546 Specifies a list of kernel Kconfig files that contain
547 hardware options only.
548 </para></listitem>
549 <listitem><para>
550 <filename>non-hardware.kcf</filename>:
551 Specifies a list of kernel Kconfig files that contain
552 non-hardware options only.
553 </para></listitem>
554 <listitem><para>
555 <filename>hardware.cfg</filename>:
556 Specifies a list of kernel <filename>CONFIG_</filename>
557 options that are hardware, regardless of whether or not
558 they are within a Kconfig file specified by a hardware
559 or non-hardware Kconfig file (i.e.
560 <filename>hardware.kcf</filename> or
561 <filename>non-hardware.kcf</filename>).
562 </para></listitem>
563 <listitem><para>
564 <filename>non-hardware.cfg</filename>:
565 Specifies a list of kernel <filename>CONFIG_</filename>
566 options that are not hardware, regardless of whether or
567 not they are within a Kconfig file specified by a
568 hardware or non-hardware Kconfig file (i.e.
569 <filename>hardware.kcf</filename> or
570 <filename>non-hardware.kcf</filename>).
571 </para></listitem>
572 </itemizedlist>
573 Here is a specific example using the
574 <filename>kernel-cache/bsp/mti-malta32/hardware.cfg</filename>:
575 <literallayout class='monospaced'>
576 CONFIG_SERIAL_8250
577 CONFIG_SERIAL_8250_CONSOLE
578 CONFIG_SERIAL_8250_NR_UARTS
579 CONFIG_SERIAL_8250_PCI
580 CONFIG_SERIAL_CORE
581 CONFIG_SERIAL_CORE_CONSOLE
582 CONFIG_VGA_ARB
583 </literallayout>
584 The kernel configuration audit automatically detects these
585 files (hence the names must be exactly the ones discussed here),
586 and uses them as inputs when generating warnings about the
587 final <filename>.config</filename> file.
588 </para>
589
590 <para>
591 A user-specified kernel Metadata repository, or recipe space
592 feature, can use these same files to classify options that are
593 found within its <filename>.cfg</filename> files as hardware
594 or non-hardware, to prevent the OpenEmbedded build system from
595 producing an error or warning when an option is not in the
596 final <filename>.config</filename> file.
597 </para>
598 </section>
482</appendix> 599</appendix>
483<!-- 600<!--
484vim: expandtab tw=80 ts=4 601vim: expandtab tw=80 ts=4