summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-08-12 07:19:04 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-08-20 17:51:59 -0700
commit1ae239ff80de3caa8b27ab84972b8e38f1cc4eae (patch)
treea91c135c6ad7957e50c75a15b6e8caccc164b80e /documentation
parent958c355665c38a0a6429b934d139ee16864ac3f5 (diff)
downloadpoky-1ae239ff80de3caa8b27ab84972b8e38f1cc4eae.tar.gz
documentation/dev-manual/dev-manual-kernel-appendix.xml: Added kernel reconfigure example.
this example uses the CONFIG_SMP configuration. By default, this configuration is disabled. The example shows how to use menuconfig and explains the .config file role and how you can use it combined with menuconfig to manage multiple configuration changes. Thanks to Darren Hart for identifying this simple change to demonstrate how to change the kernel configuration. (From yocto-docs rev: c571c01b8589ad6f76e66388c3ae24a1de029f65) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-kernel-appendix.xml210
1 files changed, 169 insertions, 41 deletions
diff --git a/documentation/dev-manual/dev-manual-kernel-appendix.xml b/documentation/dev-manual/dev-manual-kernel-appendix.xml
index 4000a0b943..ffe3230126 100644
--- a/documentation/dev-manual/dev-manual-kernel-appendix.xml
+++ b/documentation/dev-manual/dev-manual-kernel-appendix.xml
@@ -495,14 +495,176 @@
495 <title>Changing the Kernel Configuration</title> 495 <title>Changing the Kernel Configuration</title>
496 496
497 <para> 497 <para>
498 This section presents an example that changes the kernel configuration. 498 This example changes the default behavior (off) of the Symmetric Multi-processing Support
499 The example shows how to use <filename>menuconfig</filename> to quickly see 499 (<filename>CONFIG_SMP</filename>) to on.
500 and set configurations used by the kernel. 500 It is a simple example that demonstrates how to reconfigure the kernel.
501 </para> 501 </para>
502 502
503 <para> 503 <section id='getting-set-up-to-run-this-example'>
504 [Example to be supplied] 504 <title>Getting Set Up to Run this Example</title>
505 </para> 505
506 <para>
507 If you took the time to work through the example that modifies the kernel source code
508 in <xref linkend='modifying-the-kernel-source-code'>Modifying the Kernel Source
509 Code</xref> you are set up to quickly work through this example.
510 If not, then work through the following list to prepare:
511 <itemizedlist>
512 <listitem><para><emphasis>Understand the development environment:</emphasis>
513 See <xref linkend='understanding-the-files-you-need'>
514 Understanding the Files You Need</xref> for information.</para></listitem>
515 <listitem><para><emphasis>Set up the local Yocto Project files Git
516 repository:</emphasis>
517 See <xref linkend='setting-up-the-local-yocto-project-files-git-repository'>
518 Setting Up the Local Yocto Project Files Git Repository</xref> for
519 information.</para></listitem>
520 <listitem><para><emphasis>Set up the <filename>poky-extras</filename> Git
521 repository:</emphasis>
522 See <xref linkend='setting-up-the-poky-extras-git-repository'>
523 Setting Up <filename>poky-extras</filename> Git repository</xref> for
524 information.</para></listitem>
525 <listitem><para><emphasis>Set up the the bare clone and its copy:</emphasis>
526 See <xref linkend='setting-up-the-bare-clone-and-its-copy'>
527 Setting Up the Bare Clone and its Copy</xref> for information.
528 </para></listitem>
529 <listitem><para><emphasis>Build the default QEMU kernel image:</emphasis>
530 See <xref linkend='building-and-booting-the-default-qemu-kernel-image'>
531 Building and Booting the Default QEMU Kernel image</xref>
532 for information.
533 Do not boot the image in the QEMU emulator at this point.</para></listitem>
534 </itemizedlist>
535 </para>
536 </section>
537
538 <section id='examining-the-default-config-smp-behavior'>
539 <title>Examining the Default <filename>CONFIG_SMP</filename> Behavior</title>
540
541 <para>
542 By default, <filename>CONFIG_SMP</filename> supports single processor machines.
543 To see this default setting from within the QEMU emulator boot your image using
544 the emulator as follows:
545 <literallayout class='monospaced'>
546 $ runqemu qemux86
547 </literallayout>
548 </para>
549
550 <para>
551 Login to the machine using <filename>root</filename> with no password.
552 After logging in, enter the following command to see how many processors are
553 being supported in the emulator.
554 The emulator reports support for a single processor:
555 <literallayout class='monospaced'>
556 # cat /proc/cpuinfo | grep processor
557 processor : 0
558 #
559 </literallayout>
560 </para>
561 </section>
562
563 <section id='changing-the-config-smp-configuration-using-menuconfig'>
564 <title>Changing the <filename>CONFIG_SMP</filename> Configuration Using <filename>menuconfig</filename></title>
565
566 <para>
567 The <filename>menuconfig</filename> tool provides an interactive method with which
568 to set kernel configurations.
569 You need to run <filename>menuconfig</filename> inside the BitBake environment.
570 Thus, the environment must be set up using the <filename>oe-init-build-env</filename>
571 script found in the Yocto Project files Git repository build directory.
572 If you have not sourced this script do so with the following commands:
573 <literallayout class='monospaced'>
574 $ cd ~/poky
575 $ source oe-init-build-env
576 </literallayout>
577 </para>
578
579 <para>
580 After setting up the environment to run <filename>menuconfig</filename>, you are ready
581 to use the tool to interactively change the kernel configuration.
582 In this example we are basing our changes on the <filename>linux-yocto-3.0</filename>
583 kernel.
584 The Yocto Project build environment recognizes this kernel as
585 <filename>linux-yocto</filename>.
586 Thus, the following command from the shell in which you previously sourced the
587 environment initialization script launches <filename>menuconfig</filename>:
588 <literallayout class='monospaced'>
589 $ bitbake linux-yocto -c menuconfig
590 </literallayout>
591 </para>
592
593 <para>
594 Once <filename>menuconfig</filename> launches, navigate through the user interface
595 to find the <filename>CONFIG_SMP</filename> configuration setting.
596 You can find it at <filename>Processor Type and Features</filename>.
597 The configuration selection is
598 <filename>Symmetric Multi-processing Support</filename>.
599 </para>
600
601 <para>
602 Once you save the selection the <filename>.config</filename> configuration file
603 is updated.
604 This is the file that the build system uses to configure the Linux Yocto kernel
605 when it is built.
606 You can find and examine this file in the Yocto Project files Git repository in
607 the build directory.
608 This example uses the following:
609 <literallayout class='monospaced'>
610 ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-2.6.37+git1+84f...r20/linux-qemux86-standard-build
611 </literallayout>
612 </para>
613
614 <para>
615 Within the <filename>.config</filename> you can see the following setting:
616 <literallayout class='monospaced'>
617 CONFIG_SMP=y
618 </literallayout>
619 </para>
620
621 <para>
622 A good method to isolate changed configurations is to use a combination of the
623 <filename>menuconfig</filename> tool and simple shell commands.
624 Before changing configurations with <filename>menuconfig</filename> simply rename
625 the default <filename>.config</filename>, use <filename>menuconfig</filename> to make
626 as many changes an you want and save them, then compare the renamed configuration
627 file against the newly created file.
628 You can use the resulting differences as your base to create configuration fragments
629 to permanently save in your kernel layer.
630 For an example of this procedure, see [WRITER'S NOTE: need forwarding link to section].
631 </para>
632 </section>
633
634 <section id='recompiling-the-kernel-and-testing-the-new-configuration'>
635 <title>Recompiling the Kernel and Testing the New Configuration</title>
636
637 <para>
638 At this point you are ready to recompile your kernel image with
639 the new setting in effect using the BitBake commands below:
640 <literallayout class='monospaced'>
641 $ bitbake linux-yocto -c compile -f
642 $ bitbake linux-yocto
643 </literallayout>
644 </para>
645
646 <para>
647 Now run the QEMU emulator:
648 <literallayout class='monospaced'>
649 $ runqemu qemux86
650 </literallayout>
651 </para>
652
653 <para>
654 Login to the machine using <filename>root</filename> with no password
655 and test for the number of processors the kernel supports:
656 <literallayout class='monospaced'>
657 # cat /proc/cpuinfo | grep processor
658 processor : 0
659 processor : 1
660 #
661 </literallayout>
662 </para>
663
664 <para>
665 From the output you can see that you have successfully reconfigured the kernel.
666 </para>
667 </section>
506 </section> 668 </section>
507 669
508 <section id='adding-kernel-recipes'> 670 <section id='adding-kernel-recipes'>
@@ -516,7 +678,7 @@
516 <para> 678 <para>
517 [Example to be supplied] 679 [Example to be supplied]
518 </para> 680 </para>
519 </section> 681 </section>
520 682
521 683
522 684
@@ -584,40 +746,6 @@ It should just build whatever is necessary and not go through an entire build ag
584 <section id='prepare-to-use-menuconfig'> 746 <section id='prepare-to-use-menuconfig'>
585 <title>Prepare to use <filename>menuconfig</filename></title> 747 <title>Prepare to use <filename>menuconfig</filename></title>
586 748
587 <para>
588 The <filename>menuconfig</filename> tool provides an interactive method with which
589 to set kernel configurations.
590 In order to use <filename>menuconfig</filename> from within the BitBake environment
591 you need to source an environment setup script.
592 This script is located in the local Yocto Project file structure and is called
593 <filename>oe-init-build-env</filename>.
594 </para>
595
596 <para>
597 The following command sets up the environment:
598 <literallayout class='monospaced'>
599 $ cd ~/poky
600 $ source oe-init-build-env
601 </literallayout>
602 </para>
603 </section>
604
605 <section id='make-configuration-changes-to-the-kernel'>
606 <title>Make Configuration Changes to the Kernel</title>
607
608 <para>
609 After setting up the environment to run <filename>menuconfig</filename> you are ready
610 to use the tool to interactively change the kernel configuration.
611 In this example we are basing our changes on the <filename>linux-yocto-2.6.37</filename>
612 kernel.
613 The Yocto Project build environment recognizes this kernel as
614 <filename>linux-yocto</filename>.
615 Thus, the following command from the shell in which you previously sourced the
616 environment initialization script launches <filename>menuconfig</filename>:
617 <literallayout class='monospaced'>
618 $ bitbake linux-yocto -c menuconfig
619 </literallayout>
620 </para>
621 749
622 <para> 750 <para>
623 [WRITER'S NOTE: Stuff from here down are crib notes] 751 [WRITER'S NOTE: Stuff from here down are crib notes]