From b8dfb037646c4ccbfda61241e654a703a16cf14b Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 26 Sep 2017 14:33:56 -0700 Subject: 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 Signed-off-by: Richard Purdie --- documentation/kernel-dev/kernel-dev-common.xml | 369 +++++++-------------- .../kernel-dev/kernel-dev-concepts-appx.xml | 117 +++++++ 2 files changed, 244 insertions(+), 242 deletions(-) (limited to 'documentation') 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 @@ work with the Yocto Project Linux kernel. These tasks include preparing your host development system for kernel development, preparing a layer, modifying an existing recipe, - patching the kernel, iterative development, working with your own sources, - and incorporating out-of-tree modules. + patching the kernel, configuring the kernel, iterative development, + working with your own sources, and incorporating out-of-tree modules. The examples presented in this chapter work with the Yocto Project 2.4 Release and forward. @@ -1447,34 +1447,6 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Configuring the Kernel @@ -1516,17 +1488,22 @@ - To use the menuconfig tool in the Yocto Project development - environment, you must launch it using BitBake. + 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 + You must also be sure of the state of your build's configuration + in the Source Directory. - The following commands run menuconfig - assuming the Source Directory's top-level folder is - ~/poky: + The following commands initialize the BitBake environment, + run the + do_kernel_configme + task, and launch menuconfig. + These commands assume the Source Directory's top-level folder + is ~/poky: $ cd poky $ source oe-init-build-env @@ -1542,79 +1519,81 @@ - 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. + Consider an example that configures the "CONFIG_SMP" setting + for the linux-yocto-4.12 kernel. + + The OpenEmbedded build system recognizes this kernel as + linux-yocto through Metadata (e.g. + PREFERRED_VERSION_linux-yocto ?= "12.4%"). + + Once menuconfig launches, use the + interface to navigate through the selections to find the + configuration settings in which you are interested. + For this example, you deselect "CONFIG_SMP" by clearing the + "Symmetric Multi-Processing Support" option. + Using the interface, you can find the option under + "Processor Type and Features". + To deselect "CONFIG_SMP", use the arrow keys to + highlight "Symmetric Multi-Processing Support" and enter "N" + to clear the asterisk. + When you are finished, exit out and save the change. + + + + 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 + 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-yocto-4.12 kernel and you + were building a QEMU image targeted for x86 architecture, the - .config file would be located here: + .config file would be: - poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.14.11+git1+84f... - ...656ed30-r1/linux-qemux86-standard-build + poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18... + ...967-r0/linux-qemux86-standard-build/.config - 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. + 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 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: + 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 + 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. + 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. + Be sure to make a copy of the .config + file and do not just rename it. + The build system needs an existing + .config file from which to work.
@@ -1647,7 +1626,8 @@ ${PN} directory in your layer's recipes-kernel/linux directory, and rename - the copied file to "defconfig". + the copied file to "defconfig" (e.g. + ~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig). Then, add the following lines to the linux-yocto .bbappend file in your layer: @@ -1678,8 +1658,7 @@ "Changing the Configuration" and "Generating Configuration Files" - sections, both in the Yocto Project Linux Kernel Development - Manual. + sections. @@ -1687,21 +1666,39 @@ 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 - + Configuration fragments are simply kernel options that + appear in a file placed where the OpenEmbedded build system + can find and apply them. + The build system applies configuration fragments after + applying configurations from a defconfig + file. + Thus, the final kernel configuration is a combination of the + configurations in the defconfig + file and then any configuration fragments you provide. + The build system applies fragments on top of and + after applying the existing defconfig file configurations. + + + + Syntactically, the configuration statement is identical to + what would appear in the .config file, + which is in the + Build Directory. + + For more information about where the + .config file is located, see the + example in the + "Using menuconfig" + section. + 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: + 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 @@ -1715,29 +1712,34 @@ Where do you put your configuration fragment files? - You can place these files in the same area pointed to by - SRC_URI. + You can place these files in an area pointed to by + SRC_URI + as directed by your bblayers.conf file, + which is located in your layer. 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. + directory as the kernel's append file within your layer + and then add the following statements to the kernel's append + file, those configuration options will be picked up and applied + when the kernel is built: + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" 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: + 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 \ @@ -1797,7 +1799,11 @@ Separately run the do_kernel_configme and - do_kernel_configcheck tasks. + do_kernel_configcheck tasks: + + $ bitbake linux-yocto -c kernel_configme -f + $ bitbake linux-yocto -c kernel_configcheck -f + Take the resulting list of files from the do_kernel_configcheck task @@ -1834,135 +1840,14 @@ - 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. + 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.
- - - - - - - - - - - - - - -
Using an Iterative Development Process 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 @@ section for a detailed example that modifies the 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. + For general information on kernel configuration including + menuconfig, defconfig + files, and configuration fragments, see the + "Configuring the Kernel" + section. + + + + 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. + + + + By default, in order to not overwhelm the user with + configuration warnings, the system only reports missing + "hardware" options as they could result in a boot + failure or indicate 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. + +