<para>
The easiest way to define kernel configurations is to set them through the
<filename>menuconfig</filename> tool.
+ This tool provides an interactive method with which
+ to set kernel configurations.
For general information on <filename>menuconfig</filename>, see
<ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
</para>
<para>
To use the <filename>menuconfig</filename> tool in the Yocto Project development
environment, you must build the tool using BitBake.
+ Thus, the environment must be set up using the <filename>&OE_INIT_FILE;</filename>
+ script found in the
+ <link linkend='build-directory'>Build Directory</link>.
The following commands build and invoke <filename>menuconfig</filename> assuming the
source directory top-level folder is <filename>~/poky</filename>:
<literallayout class='monospaced'>
$ bitbake linux-yocto -c menuconfig
</literallayout>
Once <filename>menuconfig</filename> 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 <filename>.config</filename> configuration file.
</para>
<para>
- For an example that shows how to change a specific kernel option
- using <filename>menuconfig</filename>, see the
- "<link linkend='changing-the-config-smp-configuration-using-menuconfig'>Changing
- the <filename>CONFIG_SMP</filename> Configuration Using <filename>menuconfig</filename></link>"
- section.
+ Consider an example that configures the <filename>linux-yocto-3.4</filename>
+ kernel.
+ The OpenEmbedded build system recognizes this kernel as
+ <filename>linux-yocto</filename>.
+ Thus, the following commands from the shell in which you previously sourced the
+ environment initialization script cleans the shared state cache and the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
+ directory and then builds and launches <filename>menuconfig</filename>:
+ <literallayout class='monospaced'>
+ $ bitbake linux-yocto -c menuconfig
+ </literallayout>
+ </para>
+
+ <para>
+ Once <filename>menuconfig</filename> launches, you use the interface
+ to navigate through the selections to find the configuration settings in
+ which you are interested.
+ For example, consider the <filename>CONFIG_SMP</filename> configuration setting.
+ You can find it at <filename>Processor Type and Features</filename> under
+ the configuration selection <filename>Symmetric Multi-processing Support</filename>.
+ 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.
+ </para>
+
+ <para>
+ Saving the selections updates the <filename>.config</filename> 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
+ <filename>tmp/work/</filename>.
+ The actual <filename>.config</filename> 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
+ <filename>x86</filename> architecture, the
+ <filename>.config</filename> file would be located here:
+ <literallayout class='monospaced'>
+ ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+84f...
+ ...656ed30-r1/linux-qemux86-standard-build
+ </literallayout>
+ <note>
+ 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 <filename>linux-yocto-3.4...</filename> might differ.
+ </note>
+ </para>
+
+ <para>
+ Within the <filename>.config</filename> file, you can see the kernel settings.
+ For example, the following entry shows that symmetric multi-processor support
+ is not set:
+ <literallayout class='monospaced'>
+ # CONFIG_SMP is not set
+ </literallayout>
+ </para>
+
+ <para>
+ A good method to isolate changed configurations is to use a combination of the
+ <filename>menuconfig</filename> tool and simple shell commands.
+ Before changing configurations with <filename>menuconfig</filename>, copy the
+ existing <filename>.config</filename> and rename it to something else,
+ use <filename>menuconfig</filename> 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.
+ <note>
+ Be sure to make a copy of the <filename>.config</filename> and don't just
+ rename it.
+ The build system needs an existing <filename>.config</filename>
+ from which to work.
+ </note>
</para>
</section>
</para>
</section>
</section>
-
- <section id='changing-the-kernel-configuration'>
- <title>Changing the Kernel Configuration</title>
-
- <para>
- This example changes the default behavior, which is "on", of the Symmetric
- Multi-processing Support (<filename>CONFIG_SMP</filename>) to "off".
- It is a simple example that demonstrates how to reconfigure the kernel.
- </para>
-
- <section id='getting-set-up-to-run-this-example'>
- <title>Getting Set Up to Run this Example</title>
-
- <para>
- If you took the time to work through the example that modifies the kernel source code
- in "<link linkend='modifying-the-kernel-source-code'>Modifying the Kernel Source
- Code</link>" 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
- "<link linkend='examining-the-default-config-smp-behavior'>Examining the Default
- <filename>CONFIG_SMP</filename> Behavior</link>", and continue with the
- example.
- </para>
-
- <para>
- If you don't have the Source Directory established on your system,
- you can get them through tarball extraction or by
- cloning the <filename>poky</filename> Git repository.
- This example uses <filename>poky</filename> as the root directory of the
- <link linkend='source-directory'>Source Directory</link>.
- See the bulleted item
- "<link linkend='local-yp-release'>Yocto Project Release</link>"
- for information on how to get these files.
- </para>
-
- <para>
- 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:
- <literallayout class='monospaced'>
- $ cd poky
- $ git branch -a
- $ git tag -l
- </literallayout>
- This example uses the Yocto Project &DISTRO; Release code named "&DISTRO_NAME;",
- which maps to the <filename>&DISTRO_NAME;</filename> branch in the repository.
- The following commands create and checkout the local <filename>&DISTRO_NAME;</filename>
- branch:
- <literallayout class='monospaced'>
- $ 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;'
- </literallayout>
- </para>
-
- <para>
- Next, you need to build the default <filename>qemux86</filename> image that you
- can boot using QEMU.
- <note>
- Because a full build can take hours, you should check two variables in the
- <filename>build</filename> directory that is created after you source the
- <filename>&OE_INIT_FILE;</filename> script.
- You can find these variables
- <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>
- in the <filename>build/conf</filename> directory in the
- <filename>local.conf</filename> 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 <filename>BB_NUMBER_THREADS</filename> and the
- <filename>PARALLEL_MAKE</filename> variables to twice the number
- of cores your machine supports.
- </note>
- The following two commands <filename>source</filename> the build environment setup script
- and build the default <filename>qemux86</filename> image.
- If necessary, the script creates the build directory:
- <literallayout class='monospaced'>
- $ 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'
- </literallayout>
- </para>
-
- <para>
- The following <filename>bitbake</filename> command starts the build:
- <literallayout class='monospaced'>
- $ bitbake -k core-image-minimal
- </literallayout>
- <note>Be sure to check the settings in the <filename>local.conf</filename>
- before starting the build.</note>
- </para>
- </section>
-
- <section id='examining-the-default-config-smp-behavior'>
- <title>Examining the Default <filename>CONFIG_SMP</filename> Behavior</title>
-
- <para>
- By default, <filename>CONFIG_SMP</filename> supports multiple processor machines.
- To see this default setting from within the QEMU emulator, boot your image using
- the emulator as follows:
- <literallayout class='monospaced'>
- $ runqemu qemux86 qemuparams="-smp 4"
- </literallayout>
- </para>
-
- <para>
- Login to the machine using <filename>root</filename> 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 <filename>-smp</filename> option, four in this case:
- <literallayout class='monospaced'>
- # cat /proc/cpuinfo | grep processor
- processor : 0
- processor : 1
- processor : 2
- processor : 3
- #
- </literallayout>
- To check the setting for <filename>CONFIG_SMP</filename>, you can use the
- following command:
- <literallayout class='monospaced'>
- zcat /proc/config.gz | grep CONFIG_SMP
- </literallayout>
- The console returns the following showing that multi-processor machine support
- is set:
- <literallayout class='monospaced'>
- CONFIG_SMP=y
- </literallayout>
- Logout of the emulator using the <filename>exit</filename> command and
- then close it down.
- </para>
- </section>
-
- <section id='changing-the-config-smp-configuration-using-menuconfig'>
- <title>Changing the <filename>CONFIG_SMP</filename> Configuration Using <filename>menuconfig</filename></title>
-
- <para>
- The <filename>menuconfig</filename> tool provides an interactive method with which
- to set kernel configurations.
- You need to run <filename>menuconfig</filename> inside the Yocto BitBake environment.
- Thus, the environment must be set up using the <filename>&OE_INIT_FILE;</filename>
- script found in the build directory.
- If you have not sourced this script do so with the following commands:
- <literallayout class='monospaced'>
- $ cd ~/poky
- $ source &OE_INIT_FILE;
- </literallayout>
- </para>
-
- <para>
- After setting up the environment to run <filename>menuconfig</filename>, you are ready
- to use the tool to interactively change the kernel configuration.
- In this example, we are basing our changes on the <filename>linux-yocto-3.4</filename>
- kernel.
- The OpenEmbedded build system recognizes this kernel as
- <filename>linux-yocto</filename>.
- Thus, the following commands from the shell in which you previously sourced the
- environment initialization script cleans the shared state cache and the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
- directory and then builds and launches <filename>menuconfig</filename>:
- <literallayout class='monospaced'>
- $ bitbake linux-yocto -c menuconfig
- </literallayout>
- </para>
-
- <para>
- Once <filename>menuconfig</filename> launches, navigate through the user interface
- to find the <filename>CONFIG_SMP</filename> configuration setting.
- You can find it at <filename>Processor Type and Features</filename>.
- The configuration selection is
- <filename>Symmetric Multi-processing Support</filename>.
- After using the arrow keys to highlight this selection, press "n" to turn it off.
- Then, exit out and save your selections.
- </para>
-
- <para>
- Once you save the selection, the <filename>.config</filename> 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:
- <literallayout class='monospaced'>
- ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+84f...
- ...656ed30-r1/linux-qemux86-standard-build
- </literallayout>
- <note>
- 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.
- </note>
- </para>
-
- <para>
- Within the <filename>.config</filename> file, you can see the following setting:
- <literallayout class='monospaced'>
- # CONFIG_SMP is not set
- </literallayout>
- </para>
-
- <para>
- A good method to isolate changed configurations is to use a combination of the
- <filename>menuconfig</filename> tool and simple shell commands.
- Before changing configurations with <filename>menuconfig</filename>, copy the
- existing <filename>.config</filename> and rename it to something else,
- use <filename>menuconfig</filename> 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.
- <note>
- Be sure to make a copy of the <filename>.config</filename> and don't just
- rename it.
- The build system needs an existing <filename>.config</filename>
- from which to work.
- </note>
- </para>
- </section>
-
- <section id='recompiling-the-kernel-and-testing-the-new-configuration'>
- <title>Recompiling the Kernel and Testing the New Configuration</title>
-
- <para>
- At this point, you are ready to recompile your kernel image with
- the new setting in effect using the BitBake command below:
- <literallayout class='monospaced'>
- $ bitbake linux-yocto
- </literallayout>
- </para>
-
- <para>
- Now run the QEMU emulator and pass it the same multi-processor option as before:
- <literallayout class='monospaced'>
- $ runqemu qemux86 qemuparams="-smp 4"
- </literallayout>
- </para>
-
- <para>
- Login to the machine using <filename>root</filename> with no password
- and test for the number of processors the kernel supports:
- <literallayout class='monospaced'>
- # cat /proc/cpuinfo | grep processor
- processor : 0
- #
- </literallayout>
- </para>
-
- <para>
- 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
- <filename>CONFIG_SMP</filename> setting by using this command:
- <literallayout class='monospaced'>
- zcat /proc/config.gz | grep CONFIG_SMP
- </literallayout>
- The console returns the following output:
- <literallayout class='monospaced'>
- # CONFIG_SMP is not set
- </literallayout>
- You have successfully reconfigured the kernel.
- </para>
- </section>
- </section>
-
- <section id='adding-kernel-recipes'>
- <title>Adding Kernel Recipes</title>
-
- <para>
- A future release of this manual will present an example that adds kernel recipes, which provide
- new functionality to the kernel.
- </para>
-
- <para>
- <imagedata fileref="figures/wip.png"
- width="2in" depth="3in" align="center" scalefit="1" />
- </para>
- </section>
</appendix>
<!--
projects / thirdparty / openembedded / openembedded-core-contrib.git / commitdiff
