From de671802c8de9311cc292456d69cafb7be128b0b Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 22 Sep 2017 12:18:18 -0700 Subject: dev-manual: Compatibility program and moving kernel configuration Should have been two commits but I forgot to do them separately. 1. I updated the YP Compatible Program section. 2. I moved the "Configuring the Kernel" section from the dev-manual to the kernel-dev manual. (From yocto-docs rev: cdb5bbc917db55a2ca987ce9b9ed371f9fca6524) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 591 +++------------------ documentation/kernel-dev/kernel-dev-advanced.xml | 6 +- documentation/kernel-dev/kernel-dev-common.xml | 528 +++++++++++++++++- documentation/kernel-dev/kernel-dev-intro.xml | 2 +- documentation/ref-manual/ref-tasks.xml | 8 +- 5 files changed, 592 insertions(+), 543 deletions(-) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 0c2e60f006..f82d37e1dc 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -442,54 +442,65 @@ existing Yocto Project layers (i.e. the layer is compatible with the Yocto Project). Ensuring compatibility makes the layer easy to be consumed - by others in the Yocto Project community and allows you - permission to use the Yocto Project Compatibility logo. - - - - Version 1.0 of the Yocto Project Compatibility Program has - been in existence for a number of releases. - This version of the program consists of the layer application - process that requests permission to use the Yocto Project - Compatibility logo for your layer and application. - You can find version 1.0 of the form at - . - To be granted permission to use the logo, you need to be able - to answer "Yes" to the questions or have an acceptable - explanation for any questions answered "No". + by others in the Yocto Project community and could allow you + permission to use the Yocto Project Compatibility Logo. + + Only Yocto Project member organizations are permitted to + use the Yocto Project Compatibility Logo. + The logo is not available for general use. + For information on how to become a Yocto Project member + organization, see the + Member Organizations + page of the Yocto Project website. + - A second version (2.0) of the Yocto Project Compatibility - Program is currently under development. - Included as part of version 2.0 (and currently available) is - the yocto-compat-layer.py script. - When run against a layer, this script tests the layer against - tighter constraints based on experiences of how layers have - worked in the real world and where pitfalls have been found. + The Yocto Project Compatibility Program consists of a layer + application process that requests permission to use the Yocto + Project Compatibility Logo for your layer and application. + The process consists of two parts: + + + Successfully passing a script + (yocto-compat-layer.py) that + when run against your layer, tests it against + constraints based on experiences of how layers have + worked in the real world and where pitfalls have been + found. + Getting a "PASS" result from the script is required for + successful compatibility registration. + + + Completion of an application acceptance form, which + you can find at + . + + - Part of the 2.0 version of the program that is not currently - available but is in development is an updated compatibility - application form. - This updated form, among other questions, specifically - asks if your layer has passed the test using the - yocto-compat-layer.py script. - Tip - Even though the updated application form is currently - unavailable for version 2.0 of the Yocto Project - Compatibility Program, the - yocto-compat-layer.py script is - available in OE-Core. - You can use the script to assess the status of your - layers in advance of the 2.0 release of the program. - + To be granted permission to use the logo, you need to satisfy + the following: + + + Be able to check the box indicating that you + got a "PASS" when running the script against your + layer. + + + Answer "Yes" to the questions on the form or have an + acceptable explanation for any questions answered "No". + + + You need to be a Yocto Project Member Organization. + + The remainder of this section presents information on the - version 1.0 registration form and on the + registration form and on the yocto-compat-layer.py script. @@ -497,10 +508,10 @@ Yocto Project Compatibility Program Application - Use the 1.0 version of the form to apply for your - layer's compatibility approval. + Use the form to apply for your layer's compatibility + approval. Upon successful application, you can use the Yocto - Project Compatibility logo with your layer and the + Project Compatibility Logo with your layer and the application that uses your layer. @@ -542,22 +553,14 @@ <filename>yocto-compat-layer.py</filename> Script - The yocto-compat-layer.py script, - which is currently available, provides you a way to - assess how compatible your layer is with the Yocto - Project. + The yocto-compat-layer.py script + provides you a way to assess how compatible your layer is + with the Yocto Project. You should run this script prior to using the form to apply for compatibility as described in the previous section. - - Because the script is part of the 2.0 release of the - Yocto Project Compatibility Program, you are not - required to successfully run your layer against it - in order to be granted compatibility status. - However, it is a good idea as it promotes - well-behaved layers and gives you an idea of where your - layer stands regarding compatibility. - + You need to achieve a "PASS" result in order to have + your application form successfully processed. @@ -6142,479 +6145,6 @@ Some notes from Cal: -
- Configuring the Kernel - - - Configuring the Yocto Project kernel consists of making sure the - .config file has all the right information - in it for the image you are building. - You can use the menuconfig tool and - configuration fragments to make sure your - .config file is just how you need it. - You can also save known configurations in a - defconfig file that the build system can use - for kernel configuration. - - - - This section describes how to use menuconfig, - create and use configuration fragments, and how to interactively - modify your .config file to create the - leanest kernel configuration file possible. - - - - For more information on kernel configuration, see the - "Changing the Configuration" - section in the Yocto Project Linux Kernel Development Manual. - - -
- Using  <filename>menuconfig</filename> - - - The easiest way to define kernel configurations is to set them through the - menuconfig tool. - This tool provides an interactive method with which - to set kernel configurations. - For general information on menuconfig, see - . - - - - To use the menuconfig tool in the Yocto Project development - environment, you must launch it using BitBake. - Thus, the environment must be set up using the - &OE_INIT_FILE; - script found in the - Build Directory. - You must also be sure of the state of your build in the - Source Directory. - The following commands run menuconfig - assuming the Source Directory's top-level folder is - ~/poky: - - $ cd poky - $ source oe-init-build-env - $ bitbake linux-yocto -c kernel_configme -f - $ bitbake linux-yocto -c menuconfig - - Once menuconfig comes up, its standard - interface allows you to interactively examine and configure - all the kernel configuration parameters. - After making your changes, simply exit the tool and save your - changes to create an updated version of the - .config configuration file. - - - - Consider an example that configures the linux-yocto-3.14 - kernel. - The OpenEmbedded build system recognizes this kernel as - linux-yocto. - Thus, the following commands from the shell in which you previously sourced the - environment initialization script cleans the shared state cache and the - WORKDIR - directory and then runs menuconfig: - - $ bitbake linux-yocto -c menuconfig - - - - - Once menuconfig launches, use the interface - to navigate through the selections to find the configuration settings in - which you are interested. - For example, consider the CONFIG_SMP configuration setting. - You can find it at Processor Type and Features under - the configuration selection Symmetric Multi-processing Support. - After highlighting the selection, use the arrow keys to select or deselect - the setting. - When you are finished with all your selections, exit out and save them. - - - - Saving the selections updates the .config configuration file. - This is the file that the OpenEmbedded build system uses to configure the - kernel during the build. - You can find and examine this file in the Build Directory in - tmp/work/. - The actual .config is located in the area where the - specific kernel is built. - For example, if you were building a Linux Yocto kernel based on the - Linux 3.14 kernel and you were building a QEMU image targeted for - x86 architecture, the - .config file would be located here: - - poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.14.11+git1+84f... - ...656ed30-r1/linux-qemux86-standard-build - - - The previous example directory is artificially split and many of the characters - in the actual filename are omitted in order to make it more readable. - Also, depending on the kernel you are using, the exact pathname - for linux-yocto-3.14... might differ. - - - - - Within the .config file, you can see the kernel settings. - For example, the following entry shows that symmetric multi-processor support - is not set: - - # CONFIG_SMP is not set - - - - - A good method to isolate changed configurations is to use a combination of the - menuconfig tool and simple shell commands. - Before changing configurations with menuconfig, copy the - existing .config and rename it to something else, - use menuconfig to make - as many changes as you want and save them, then compare the renamed configuration - file against the newly created file. - You can use the resulting differences as your base to create configuration fragments - to permanently save in your kernel layer. - - Be sure to make a copy of the .config and don't just - rename it. - The build system needs an existing .config - from which to work. - - -
- -
- Creating a  <filename>defconfig</filename> File - - - A defconfig file is simply a - .config renamed to "defconfig". - You can use a defconfig file - to retain a known set of kernel configurations from which the - OpenEmbedded build system can draw to create the final - .config file. - - Out-of-the-box, the Yocto Project never ships a - defconfig or - .config file. - The OpenEmbedded build system creates the final - .config file used to configure the - kernel. - - - - - To create a defconfig, start with a - complete, working Linux kernel .config - file. - Copy that file to the appropriate - ${PN} - directory in your layer's - recipes-kernel/linux directory, and rename - the copied file to "defconfig". - Then, add the following lines to the linux-yocto - .bbappend file in your layer: - - FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - SRC_URI += "file://defconfig" - - The - SRC_URI - tells the build system how to search for the file, while the - FILESEXTRAPATHS - extends the - FILESPATH - variable (search directories) to include the - ${PN} directory you created to hold the - configuration changes. - - The build system applies the configurations from the - defconfig file before applying any - subsequent configuration fragments. - The final kernel configuration is a combination of the - configurations in the defconfig - file and any configuration fragments you provide. - You need to realize that if you have any configuration - fragments, the build system applies these on top of and - after applying the existing defconfig file configurations. - - For more information on configuring the kernel, see the - "Changing the Configuration" - and - "Generating Configuration Files" - sections, both in the Yocto Project Linux Kernel Development - Manual. - -
- -
- Creating Configuration Fragments - - - Configuration fragments are simply kernel options that appear in a file - placed where the OpenEmbedded build system can find and apply them. - Syntactically, the configuration statement is identical to what would appear - in the .config file, which is in the - Build Directory: - - tmp/work/arch-poky-linux/linux-yocto-release_specific_string/linux-arch-build_type - - - - - It is simple to create a configuration fragment. - For example, issuing the following from the shell creates a configuration fragment - file named my_smp.cfg that enables multi-processor support - within the kernel: - - $ echo "CONFIG_SMP=y" >> my_smp.cfg - - - All configuration fragment files must use the - .cfg extension in order for the - OpenEmbedded build system to recognize them as a - configuration fragment. - - - - - Where do you put your configuration fragment files? - You can place these files in the same area pointed to by - SRC_URI. - The OpenEmbedded build system picks up the configuration and - adds it to the kernel's configuration. - For example, suppose you had a set of configuration options - in a file called myconfig.cfg. - If you put that file inside a directory named - linux-yocto that resides in the same - directory as the kernel's append file and then add a - SRC_URI statement such as the following - to the kernel's append file, those configuration options - will be picked up and applied when the kernel is built. - - SRC_URI += "file://myconfig.cfg" - - - - - As mentioned earlier, you can group related configurations into multiple files and - name them all in the SRC_URI statement as well. - For example, you could group separate configurations specifically for Ethernet and graphics - into their own files and add those by using a SRC_URI statement like the - following in your append file: - - SRC_URI += "file://myconfig.cfg \ - file://eth.cfg \ - file://gfx.cfg" - - -
- -
- Fine-Tuning the Kernel Configuration File - - - You can make sure the .config file is as lean or efficient as - possible by reading the output of the kernel configuration fragment audit, - noting any issues, making changes to correct the issues, and then repeating. - - - - As part of the kernel build process, the - do_kernel_configcheck task runs. - This task validates the kernel configuration by checking the final - .config file against the input files. - During the check, the task produces warning messages for the following - issues: - - Requested options that did not make the final - .config file. - Configuration items that appear twice in the same - configuration fragment. - Configuration items tagged as "required" that were overridden. - - A board overrides a non-board specific option. - Listed options not valid for the kernel being processed. - In other words, the option does not appear anywhere. - - - The do_kernel_configcheck task can - also optionally report if an option is overridden during - processing. - - - - - For each output warning, a message points to the file - that contains a list of the options and a pointer to the - configuration fragment that defines them. - Collectively, the files are the key to streamlining the - configuration. - - - - To streamline the configuration, do the following: - - Start with a full configuration that you - know works - it builds and boots successfully. - This configuration file will be your baseline. - - Separately run the - do_kernel_configme and - do_kernel_configcheck tasks. - - Take the resulting list of files from the - do_kernel_configcheck task - warnings and do the following: - - - Drop values that are redefined in the fragment - but do not change the final - .config file. - - - Analyze and potentially drop values from the - .config file that override - required configurations. - - - Analyze and potentially remove non-board - specific options. - - - Remove repeated and invalid options. - - - - After you have worked through the output of the kernel - configuration audit, you can re-run the - do_kernel_configme and - do_kernel_configcheck tasks to - see the results of your changes. - If you have more issues, you can deal with them as - described in the previous step. - - - - - - Iteratively working through steps two through four eventually yields - a minimal, streamlined configuration file. - Once you have the best .config, you can build the Linux - Yocto kernel. - -
- -
- Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase - - - This section describes part of the kernel configuration audit - phase that most developers can ignore. - During this part of the audit phase, the contents of the final - .config file are compared against the - fragments specified by the system. - These fragments can be system fragments, distro fragments, - or user specified configuration elements. - Regardless of their origin, the OpenEmbedded build system - warns the user if a specific option is not included in the - final kernel configuration. - - - - In order to not overwhelm the user with configuration warnings, - by default the system only reports on missing "hardware" - options because a missing hardware option could mean a boot - failure or that important hardware is not available. - - - - To determine whether or not a given option is "hardware" or - "non-hardware", the kernel Metadata contains files that - classify individual or groups of options as either hardware - or non-hardware. - To better show this, consider a situation where the - Yocto Project kernel cache contains the following files: - - kernel-cache/features/drm-psb/hardware.cfg - kernel-cache/features/kgdb/hardware.cfg - kernel-cache/ktypes/base/hardware.cfg - kernel-cache/bsp/mti-malta32/hardware.cfg - kernel-cache/bsp/fsl-mpc8315e-rdb/hardware.cfg - kernel-cache/bsp/qemu-ppc32/hardware.cfg - kernel-cache/bsp/qemuarma9/hardware.cfg - kernel-cache/bsp/mti-malta64/hardware.cfg - kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg - kernel-cache/bsp/common-pc/hardware.cfg - kernel-cache/bsp/common-pc-64/hardware.cfg - kernel-cache/features/rfkill/non-hardware.cfg - kernel-cache/ktypes/base/non-hardware.cfg - kernel-cache/features/aufs/non-hardware.kcf - kernel-cache/features/ocf/non-hardware.kcf - kernel-cache/ktypes/base/non-hardware.kcf - kernel-cache/ktypes/base/hardware.kcf - kernel-cache/bsp/qemu-ppc32/hardware.kcf - - The following list provides explanations for the various - files: - - hardware.kcf: - Specifies a list of kernel Kconfig files that contain - hardware options only. - - non-hardware.kcf: - Specifies a list of kernel Kconfig files that contain - non-hardware options only. - - hardware.cfg: - Specifies a list of kernel - CONFIG_ options that are hardware, - regardless of whether or not they are within a Kconfig - file specified by a hardware or non-hardware - Kconfig file (i.e. hardware.kcf or - non-hardware.kcf). - - non-hardware.cfg: - Specifies a list of kernel - CONFIG_ options that are - not hardware, regardless of whether or not they are - within a Kconfig file specified by a hardware or - non-hardware Kconfig file (i.e. - hardware.kcf or - non-hardware.kcf). - - - Here is a specific example using the - kernel-cache/bsp/mti-malta32/hardware.cfg: - - CONFIG_SERIAL_8250 - CONFIG_SERIAL_8250_CONSOLE - CONFIG_SERIAL_8250_NR_UARTS - CONFIG_SERIAL_8250_PCI - CONFIG_SERIAL_CORE - CONFIG_SERIAL_CORE_CONSOLE - CONFIG_VGA_ARB - - The kernel configuration audit automatically detects these - files (hence the names must be exactly the ones discussed here), - and uses them as inputs when generating warnings about the - final .config file. - - - - A user-specified kernel Metadata repository, or recipe space - feature, can use these same files to classify options that are - found within its .cfg files as hardware - or non-hardware, to prevent the OpenEmbedded build system from - producing an error or warning when an option is not in the - final .config file. - -
-
-
Making Images More Secure @@ -7243,8 +6773,11 @@ Some notes from Cal: see the "Generating Configuration Files" section of the Yocto Project Linux Kernel Development - Manual and the "Creating Configuration Fragments" - section, which is in this manual. + Manual and the + "Creating Configuration Fragments" + section in the Yocto Project Linux Kernel Development + Manual. + bitbake -u taskexp -g bitbake_target: Using the BitBake command with these options brings up a Dependency Explorer from which you can view file diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index 0394e08444..a6f01a8e2a 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml @@ -318,10 +318,10 @@ CONFIG_NR_CPUS=64 You can find information on configuration fragment files in the - "Creating Configuration Fragments" - section of the Yocto Project Development Manual and in + "Creating Configuration Fragments" + section and in the "Generating Configuration Files" - section earlier in this manual. + section. diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml index 28bedd1785..7f61b434cd 100644 --- a/documentation/kernel-dev/kernel-dev-common.xml +++ b/documentation/kernel-dev/kernel-dev-common.xml @@ -900,8 +900,8 @@ For a detailed example showing how to configure the kernel, see the - "Configuring the Kernel" - section in the Yocto Project Development Manual. + "Configuring the Kernel" + section.
@@ -1445,6 +1445,522 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Configuring the Kernel + + + Configuring the Yocto Project kernel consists of making sure the + .config file has all the right information + in it for the image you are building. + You can use the menuconfig tool and + configuration fragments to make sure your + .config file is just how you need it. + You can also save known configurations in a + defconfig file that the build system can use + for kernel configuration. + + + + This section describes how to use menuconfig, + create and use configuration fragments, and how to interactively + modify your .config file to create the + leanest kernel configuration file possible. + + + + For more information on kernel configuration, see the + "Changing the Configuration" + section. + + +
+ Using  <filename>menuconfig</filename> + + + The easiest way to define kernel configurations is to set them through the + menuconfig tool. + This tool provides an interactive method with which + to set kernel configurations. + For general information on menuconfig, see + . + + + + To use the menuconfig tool in the Yocto Project development + environment, you must launch it using BitBake. + Thus, the environment must be set up using the + &OE_INIT_FILE; + script found in the + Build Directory. + You must also be sure of the state of your build in the + Source Directory. + The following commands run menuconfig + assuming the Source Directory's top-level folder is + ~/poky: + + $ cd poky + $ source oe-init-build-env + $ bitbake linux-yocto -c kernel_configme -f + $ bitbake linux-yocto -c menuconfig + + Once menuconfig comes up, its standard + interface allows you to interactively examine and configure + all the kernel configuration parameters. + After making your changes, simply exit the tool and save your + changes to create an updated version of the + .config configuration file. + + + + Consider an example that configures the linux-yocto-3.14 + kernel. + The OpenEmbedded build system recognizes this kernel as + linux-yocto. + Thus, the following commands from the shell in which you previously sourced the + environment initialization script cleans the shared state cache and the + WORKDIR + directory and then runs menuconfig: + + $ bitbake linux-yocto -c menuconfig + + + + + Once menuconfig launches, use the interface + to navigate through the selections to find the configuration settings in + which you are interested. + For example, consider the CONFIG_SMP configuration setting. + You can find it at Processor Type and Features under + the configuration selection Symmetric Multi-processing Support. + After highlighting the selection, use the arrow keys to select or deselect + the setting. + When you are finished with all your selections, exit out and save them. + + + + Saving the selections updates the .config configuration file. + This is the file that the OpenEmbedded build system uses to configure the + kernel during the build. + You can find and examine this file in the Build Directory in + tmp/work/. + The actual .config is located in the area where the + specific kernel is built. + For example, if you were building a Linux Yocto kernel based on the + Linux 3.14 kernel and you were building a QEMU image targeted for + x86 architecture, the + .config file would be located here: + + poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.14.11+git1+84f... + ...656ed30-r1/linux-qemux86-standard-build + + + The previous example directory is artificially split and many of the characters + in the actual filename are omitted in order to make it more readable. + Also, depending on the kernel you are using, the exact pathname + for linux-yocto-3.14... might differ. + + + + + Within the .config file, you can see the kernel settings. + For example, the following entry shows that symmetric multi-processor support + is not set: + + # CONFIG_SMP is not set + + + + + A good method to isolate changed configurations is to use a combination of the + menuconfig tool and simple shell commands. + Before changing configurations with menuconfig, copy the + existing .config and rename it to something else, + use menuconfig to make + as many changes as you want and save them, then compare the renamed configuration + file against the newly created file. + You can use the resulting differences as your base to create configuration fragments + to permanently save in your kernel layer. + + Be sure to make a copy of the .config and don't just + rename it. + The build system needs an existing .config + from which to work. + + +
+ +
+ Creating a  <filename>defconfig</filename> File + + + A defconfig file is simply a + .config renamed to "defconfig". + You can use a defconfig file + to retain a known set of kernel configurations from which the + OpenEmbedded build system can draw to create the final + .config file. + + Out-of-the-box, the Yocto Project never ships a + defconfig or + .config file. + The OpenEmbedded build system creates the final + .config file used to configure the + kernel. + + + + + To create a defconfig, start with a + complete, working Linux kernel .config + file. + Copy that file to the appropriate + ${PN} + directory in your layer's + recipes-kernel/linux directory, and rename + the copied file to "defconfig". + Then, add the following lines to the linux-yocto + .bbappend file in your layer: + + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + SRC_URI += "file://defconfig" + + The + SRC_URI + tells the build system how to search for the file, while the + FILESEXTRAPATHS + extends the + FILESPATH + variable (search directories) to include the + ${PN} directory you created to hold the + configuration changes. + + The build system applies the configurations from the + defconfig file before applying any + subsequent configuration fragments. + The final kernel configuration is a combination of the + configurations in the defconfig + file and any configuration fragments you provide. + You need to realize that if you have any configuration + fragments, the build system applies these on top of and + after applying the existing defconfig file configurations. + + For more information on configuring the kernel, see the + "Changing the Configuration" + and + "Generating Configuration Files" + sections, both in the Yocto Project Linux Kernel Development + Manual. + +
+ +
+ Creating Configuration Fragments + + + Configuration fragments are simply kernel options that appear in a file + placed where the OpenEmbedded build system can find and apply them. + Syntactically, the configuration statement is identical to what would appear + in the .config file, which is in the + Build Directory: + + tmp/work/arch-poky-linux/linux-yocto-release_specific_string/linux-arch-build_type + + + + + It is simple to create a configuration fragment. + For example, issuing the following from the shell creates a configuration fragment + file named my_smp.cfg that enables multi-processor support + within the kernel: + + $ echo "CONFIG_SMP=y" >> my_smp.cfg + + + All configuration fragment files must use the + .cfg extension in order for the + OpenEmbedded build system to recognize them as a + configuration fragment. + + + + + Where do you put your configuration fragment files? + You can place these files in the same area pointed to by + SRC_URI. + The OpenEmbedded build system picks up the configuration and + adds it to the kernel's configuration. + For example, suppose you had a set of configuration options + in a file called myconfig.cfg. + If you put that file inside a directory named + linux-yocto that resides in the same + directory as the kernel's append file and then add a + SRC_URI statement such as the following + to the kernel's append file, those configuration options + will be picked up and applied when the kernel is built. + + SRC_URI += "file://myconfig.cfg" + + + + + As mentioned earlier, you can group related configurations into multiple files and + name them all in the SRC_URI statement as well. + For example, you could group separate configurations specifically for Ethernet and graphics + into their own files and add those by using a SRC_URI statement like the + following in your append file: + + SRC_URI += "file://myconfig.cfg \ + file://eth.cfg \ + file://gfx.cfg" + + +
+ +
+ Fine-Tuning the Kernel Configuration File + + + You can make sure the .config file is as lean or efficient as + possible by reading the output of the kernel configuration fragment audit, + noting any issues, making changes to correct the issues, and then repeating. + + + + As part of the kernel build process, the + do_kernel_configcheck task runs. + This task validates the kernel configuration by checking the final + .config file against the input files. + During the check, the task produces warning messages for the following + issues: + + Requested options that did not make the final + .config file. + Configuration items that appear twice in the same + configuration fragment. + Configuration items tagged as "required" that were overridden. + + A board overrides a non-board specific option. + Listed options not valid for the kernel being processed. + In other words, the option does not appear anywhere. + + + The do_kernel_configcheck task can + also optionally report if an option is overridden during + processing. + + + + + For each output warning, a message points to the file + that contains a list of the options and a pointer to the + configuration fragment that defines them. + Collectively, the files are the key to streamlining the + configuration. + + + + To streamline the configuration, do the following: + + Start with a full configuration that you + know works - it builds and boots successfully. + This configuration file will be your baseline. + + Separately run the + do_kernel_configme and + do_kernel_configcheck tasks. + + Take the resulting list of files from the + do_kernel_configcheck task + warnings and do the following: + + + Drop values that are redefined in the fragment + but do not change the final + .config file. + + + Analyze and potentially drop values from the + .config file that override + required configurations. + + + Analyze and potentially remove non-board + specific options. + + + Remove repeated and invalid options. + + + + After you have worked through the output of the kernel + configuration audit, you can re-run the + do_kernel_configme and + do_kernel_configcheck tasks to + see the results of your changes. + If you have more issues, you can deal with them as + described in the previous step. + + + + + + Iteratively working through steps two through four eventually yields + a minimal, streamlined configuration file. + Once you have the best .config, you can build the Linux + Yocto kernel. + +
+ +
+ Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase + + + This section describes part of the kernel configuration audit + phase that most developers can ignore. + During this part of the audit phase, the contents of the final + .config file are compared against the + fragments specified by the system. + These fragments can be system fragments, distro fragments, + or user specified configuration elements. + Regardless of their origin, the OpenEmbedded build system + warns the user if a specific option is not included in the + final kernel configuration. + + + + In order to not overwhelm the user with configuration warnings, + by default the system only reports on missing "hardware" + options because a missing hardware option could mean a boot + failure or that important hardware is not available. + + + + To determine whether or not a given option is "hardware" or + "non-hardware", the kernel Metadata contains files that + classify individual or groups of options as either hardware + or non-hardware. + To better show this, consider a situation where the + Yocto Project kernel cache contains the following files: + + kernel-cache/features/drm-psb/hardware.cfg + kernel-cache/features/kgdb/hardware.cfg + kernel-cache/ktypes/base/hardware.cfg + kernel-cache/bsp/mti-malta32/hardware.cfg + kernel-cache/bsp/fsl-mpc8315e-rdb/hardware.cfg + kernel-cache/bsp/qemu-ppc32/hardware.cfg + kernel-cache/bsp/qemuarma9/hardware.cfg + kernel-cache/bsp/mti-malta64/hardware.cfg + kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg + kernel-cache/bsp/common-pc/hardware.cfg + kernel-cache/bsp/common-pc-64/hardware.cfg + kernel-cache/features/rfkill/non-hardware.cfg + kernel-cache/ktypes/base/non-hardware.cfg + kernel-cache/features/aufs/non-hardware.kcf + kernel-cache/features/ocf/non-hardware.kcf + kernel-cache/ktypes/base/non-hardware.kcf + kernel-cache/ktypes/base/hardware.kcf + kernel-cache/bsp/qemu-ppc32/hardware.kcf + + The following list provides explanations for the various + files: + + hardware.kcf: + Specifies a list of kernel Kconfig files that contain + hardware options only. + + non-hardware.kcf: + Specifies a list of kernel Kconfig files that contain + non-hardware options only. + + hardware.cfg: + Specifies a list of kernel + CONFIG_ options that are hardware, + regardless of whether or not they are within a Kconfig + file specified by a hardware or non-hardware + Kconfig file (i.e. hardware.kcf or + non-hardware.kcf). + + non-hardware.cfg: + Specifies a list of kernel + CONFIG_ options that are + not hardware, regardless of whether or not they are + within a Kconfig file specified by a hardware or + non-hardware Kconfig file (i.e. + hardware.kcf or + non-hardware.kcf). + + + Here is a specific example using the + kernel-cache/bsp/mti-malta32/hardware.cfg: + + CONFIG_SERIAL_8250 + CONFIG_SERIAL_8250_CONSOLE + CONFIG_SERIAL_8250_NR_UARTS + CONFIG_SERIAL_8250_PCI + CONFIG_SERIAL_CORE + CONFIG_SERIAL_CORE_CONSOLE + CONFIG_VGA_ARB + + The kernel configuration audit automatically detects these + files (hence the names must be exactly the ones discussed here), + and uses them as inputs when generating warnings about the + final .config file. + + + + A user-specified kernel Metadata repository, or recipe space + feature, can use these same files to classify options that are + found within its .cfg files as hardware + or non-hardware, to prevent the OpenEmbedded build system from + producing an error or warning when an option is not in the + final .config file. + +
+
+ + + + + + + + + + + + + + + +
Using an Iterative Development Process @@ -1538,8 +2054,8 @@ "Changing the Configuration" section. For more information on the .config file, see the - "Using menuconfig" - section in the Yocto Project Development Manual. + "Using menuconfig" + section. You can determine what a variable expands to by looking at the output of the bitbake -e @@ -1650,8 +2166,8 @@ For more information on how to use the menuconfig tool, see the - "Using menuconfig" - section in the Yocto Project Development Manual. + "Using menuconfig" + section.
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml index b2fe19c175..174ab93ab0 100644 --- a/documentation/kernel-dev/kernel-dev-intro.xml +++ b/documentation/kernel-dev/kernel-dev-intro.xml @@ -231,7 +231,7 @@ and you have saved them, you can directly compare the resulting .config file against an existing original and gather those changes into a - configuration fragment file + configuration fragment file to be referenced from within the kernel's .bbappend file. diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml index 2d23bbaabf..e145518989 100644 --- a/documentation/ref-manual/ref-tasks.xml +++ b/documentation/ref-manual/ref-tasks.xml @@ -960,8 +960,8 @@ section in the Yocto Project Linux Kernel Development Manual for more information on this configuration tool. You can also reference the - "Using menuconfig" - section in the Yocto Project Development Manual. + "Using menuconfig" + section in the Yocto Project Linux Kernel Development Manual. @@ -988,8 +988,8 @@ Runs make menuconfig for the kernel. For information on menuconfig, see the - "Using  menuconfig" - section in the Yocto Project Development Manual. + "Using  menuconfig" + section in the Yocto Project Linux Kernel Development Manual. -- cgit v1.2.3-54-g00ecf