From c29e8cbb2f2178af0b59e4eb70aed3673ab39f73 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 8 Oct 2012 08:49:23 -0700 Subject: documentation: dev-manual - Updates to configuring Kernel section Eliminated the section A.2, which had an example of how to use menuconfig in the kerenl example appendix. The information is now merged into the similar section in Chapter 4 "Common Tasks." It was decided that the Appendix A examples in the manual were too detailed for a general development guide. (From yocto-docs rev: f88ec421b257657f02cc0f132ec2580c17f07cef) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 88 ++++++- .../dev-manual/dev-manual-kernel-appendix.xml | 293 --------------------- 2 files changed, 81 insertions(+), 300 deletions(-) (limited to 'documentation/dev-manual') diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 824aac1236..918d884681 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1352,6 +1352,8 @@ 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 . @@ -1359,6 +1361,9 @@ To use the menuconfig tool in the Yocto Project development environment, you must build the tool using BitBake. + Thus, the environment must be set up using the &OE_INIT_FILE; + script found in the + Build Directory. The following commands build and invoke menuconfig assuming the source directory top-level folder is ~/poky: @@ -1367,17 +1372,86 @@ $ bitbake linux-yocto -c menuconfig Once menuconfig comes up, its standard interface allows you to - examine and configure all the kernel configuration parameters. - Once you have made your changes, simply exit the tool and save your changes 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. - For an example that shows how to change a specific kernel option - using menuconfig, see the - "Changing - the CONFIG_SMP Configuration Using menuconfig" - section. + Consider an example that configures the linux-yocto-3.4 + 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 builds and launches menuconfig: + + $ bitbake linux-yocto -c menuconfig + + + + + Once menuconfig launches, you 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, you can 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.4 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.4.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.4... 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 an 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. + diff --git a/documentation/dev-manual/dev-manual-kernel-appendix.xml b/documentation/dev-manual/dev-manual-kernel-appendix.xml index 9070fcb561..6ea77d030c 100644 --- a/documentation/dev-manual/dev-manual-kernel-appendix.xml +++ b/documentation/dev-manual/dev-manual-kernel-appendix.xml @@ -546,299 +546,6 @@ - -
- Changing the Kernel Configuration - - - This example changes the default behavior, which is "on", of the Symmetric - Multi-processing Support (CONFIG_SMP) to "off". - It is a simple example that demonstrates how to reconfigure the kernel. - - -
- Getting Set Up to Run this Example - - - If you took the time to work through the example that modifies the kernel source code - in "Modifying the Kernel Source - Code" you should already have the Source Directory set up on your - host machine. - If this is the case, go to the next section, which is titled - "Examining the Default - CONFIG_SMP Behavior", and continue with the - example. - - - - If you don't have the Source Directory established on your system, - you can get them through tarball extraction or by - cloning the poky Git repository. - This example uses poky as the root directory of the - Source Directory. - See the bulleted item - "Yocto Project Release" - for information on how to get these files. - - - - Once you have the local copy of the repository set up, - you have many development branches from which you can work. - From inside the repository you can see the branch names and the tag names used - in the upstream Git repository using either of the following commands: - - $ cd poky - $ git branch -a - $ git tag -l - - This example uses the Yocto Project &DISTRO; Release code named "&DISTRO_NAME;", - which maps to the &DISTRO_NAME; branch in the repository. - The following commands create and checkout the local &DISTRO_NAME; - branch: - - $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; - Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin. - Switched to a new branch '&DISTRO_NAME;' - - - - - Next, you need to build the default qemux86 image that you - can boot using QEMU. - - Because a full build can take hours, you should check two variables in the - build directory that is created after you source the - &OE_INIT_FILE; script. - You can find these variables - BB_NUMBER_THREADS and PARALLEL_MAKE - in the build/conf directory in the - local.conf configuration file. - By default, these variables are commented out. - If your host development system supports multi-core and multi-thread capabilities, - you can uncomment these statements and set the variables to significantly shorten - the full build time. - As a guideline, set both the BB_NUMBER_THREADS and the - PARALLEL_MAKE variables to twice the number - of cores your machine supports. - - The following two commands source the build environment setup script - and build the default qemux86 image. - If necessary, the script creates the build directory: - - $ cd ~/poky - $ source &OE_INIT_FILE; - - ### Shell environment set up for builds. ### - - You can now run 'bitbake <target>' - - Common targets are: - core-image-minimal - core-image-sato - meta-toolchain - meta-toolchain-sdk - adt-installer - meta-ide-support - - You can also run generated qemu images with a command like 'runqemu qemux86' - - - - - The following bitbake command starts the build: - - $ bitbake -k core-image-minimal - - Be sure to check the settings in the local.conf - before starting the build. - -
- -
- Examining the Default  <filename>CONFIG_SMP</filename> Behavior - - - By default, CONFIG_SMP supports multiple processor machines. - To see this default setting from within the QEMU emulator, boot your image using - the emulator as follows: - - $ runqemu qemux86 qemuparams="-smp 4" - - - - - Login to the machine using root with no password. - After logging in, enter the following command to see how many processors are - being supported in the emulator. - The emulator reports support for the number of processors you specified using - the -smp option, four in this case: - - # cat /proc/cpuinfo | grep processor - processor : 0 - processor : 1 - processor : 2 - processor : 3 - # - - To check the setting for CONFIG_SMP, you can use the - following command: - - zcat /proc/config.gz | grep CONFIG_SMP - - The console returns the following showing that multi-processor machine support - is set: - - CONFIG_SMP=y - - Logout of the emulator using the exit command and - then close it down. - -
- -
- Changing the  <filename>CONFIG_SMP</filename> Configuration Using  <filename>menuconfig</filename> - - - The menuconfig tool provides an interactive method with which - to set kernel configurations. - You need to run menuconfig inside the Yocto BitBake environment. - Thus, the environment must be set up using the &OE_INIT_FILE; - script found in the build directory. - If you have not sourced this script do so with the following commands: - - $ cd ~/poky - $ source &OE_INIT_FILE; - - - - - After setting up the environment to run menuconfig, you are ready - to use the tool to interactively change the kernel configuration. - In this example, we are basing our changes on the linux-yocto-3.4 - 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 builds and launches menuconfig: - - $ bitbake linux-yocto -c menuconfig - - - - - Once menuconfig launches, navigate through the user interface - to find the CONFIG_SMP configuration setting. - You can find it at Processor Type and Features. - The configuration selection is - Symmetric Multi-processing Support. - After using the arrow keys to highlight this selection, press "n" to turn it off. - Then, exit out and save your selections. - - - - Once you save the selection, the .config configuration file - is updated. - This is the file that the build system uses to configure the Yocto Project kernel - when it is built. - You can find and examine this file in the build directory. - This example uses the following: - - ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.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 might differ - slightly. - - - - - Within the .config file, you can see the following setting: - - # 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 an 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. - - -
- -
- Recompiling the Kernel and Testing the New Configuration - - - At this point, you are ready to recompile your kernel image with - the new setting in effect using the BitBake command below: - - $ bitbake linux-yocto - - - - - Now run the QEMU emulator and pass it the same multi-processor option as before: - - $ runqemu qemux86 qemuparams="-smp 4" - - - - - Login to the machine using root with no password - and test for the number of processors the kernel supports: - - # cat /proc/cpuinfo | grep processor - processor : 0 - # - - - - - From the output, you can see that the kernel no longer supports multi-processor systems. - The output indicates support for a single processor. You can verify the - CONFIG_SMP setting by using this command: - - zcat /proc/config.gz | grep CONFIG_SMP - - The console returns the following output: - - # CONFIG_SMP is not set - - You have successfully reconfigured the kernel. - -
-
- -
- Adding Kernel Recipes - - - A future release of this manual will present an example that adds kernel recipes, which provide - new functionality to the kernel. - - - - - -