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 --- documentation/kernel-dev/kernel-dev-common.xml | 528 ++++++++++++++++++++++++- 1 file changed, 522 insertions(+), 6 deletions(-) (limited to 'documentation/kernel-dev/kernel-dev-common.xml') 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.
-- cgit v1.2.3-54-g00ecf