summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-kernel-appendix.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-kernel-appendix.xml')
-rw-r--r--documentation/dev-manual/dev-manual-kernel-appendix.xml293
1 files changed, 0 insertions, 293 deletions
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 @@
546 </para> 546 </para>
547 </section> 547 </section>
548 </section> 548 </section>
549
550 <section id='changing-the-kernel-configuration'>
551 <title>Changing the Kernel Configuration</title>
552
553 <para>
554 This example changes the default behavior, which is "on", of the Symmetric
555 Multi-processing Support (<filename>CONFIG_SMP</filename>) to "off".
556 It is a simple example that demonstrates how to reconfigure the kernel.
557 </para>
558
559 <section id='getting-set-up-to-run-this-example'>
560 <title>Getting Set Up to Run this Example</title>
561
562 <para>
563 If you took the time to work through the example that modifies the kernel source code
564 in "<link linkend='modifying-the-kernel-source-code'>Modifying the Kernel Source
565 Code</link>" you should already have the Source Directory set up on your
566 host machine.
567 If this is the case, go to the next section, which is titled
568 "<link linkend='examining-the-default-config-smp-behavior'>Examining the Default
569 <filename>CONFIG_SMP</filename> Behavior</link>", and continue with the
570 example.
571 </para>
572
573 <para>
574 If you don't have the Source Directory established on your system,
575 you can get them through tarball extraction or by
576 cloning the <filename>poky</filename> Git repository.
577 This example uses <filename>poky</filename> as the root directory of the
578 <link linkend='source-directory'>Source Directory</link>.
579 See the bulleted item
580 "<link linkend='local-yp-release'>Yocto Project Release</link>"
581 for information on how to get these files.
582 </para>
583
584 <para>
585 Once you have the local copy of the repository set up,
586 you have many development branches from which you can work.
587 From inside the repository you can see the branch names and the tag names used
588 in the upstream Git repository using either of the following commands:
589 <literallayout class='monospaced'>
590 $ cd poky
591 $ git branch -a
592 $ git tag -l
593 </literallayout>
594 This example uses the Yocto Project &DISTRO; Release code named "&DISTRO_NAME;",
595 which maps to the <filename>&DISTRO_NAME;</filename> branch in the repository.
596 The following commands create and checkout the local <filename>&DISTRO_NAME;</filename>
597 branch:
598 <literallayout class='monospaced'>
599 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
600 Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
601 Switched to a new branch '&DISTRO_NAME;'
602 </literallayout>
603 </para>
604
605 <para>
606 Next, you need to build the default <filename>qemux86</filename> image that you
607 can boot using QEMU.
608 <note>
609 Because a full build can take hours, you should check two variables in the
610 <filename>build</filename> directory that is created after you source the
611 <filename>&OE_INIT_FILE;</filename> script.
612 You can find these variables
613 <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>
614 in the <filename>build/conf</filename> directory in the
615 <filename>local.conf</filename> configuration file.
616 By default, these variables are commented out.
617 If your host development system supports multi-core and multi-thread capabilities,
618 you can uncomment these statements and set the variables to significantly shorten
619 the full build time.
620 As a guideline, set both the <filename>BB_NUMBER_THREADS</filename> and the
621 <filename>PARALLEL_MAKE</filename> variables to twice the number
622 of cores your machine supports.
623 </note>
624 The following two commands <filename>source</filename> the build environment setup script
625 and build the default <filename>qemux86</filename> image.
626 If necessary, the script creates the build directory:
627 <literallayout class='monospaced'>
628 $ cd ~/poky
629 $ source &OE_INIT_FILE;
630
631 ### Shell environment set up for builds. ###
632
633 You can now run 'bitbake &lt;target&gt;'
634
635 Common targets are:
636 core-image-minimal
637 core-image-sato
638 meta-toolchain
639 meta-toolchain-sdk
640 adt-installer
641 meta-ide-support
642
643 You can also run generated qemu images with a command like 'runqemu qemux86'
644 </literallayout>
645 </para>
646
647 <para>
648 The following <filename>bitbake</filename> command starts the build:
649 <literallayout class='monospaced'>
650 $ bitbake -k core-image-minimal
651 </literallayout>
652 <note>Be sure to check the settings in the <filename>local.conf</filename>
653 before starting the build.</note>
654 </para>
655 </section>
656
657 <section id='examining-the-default-config-smp-behavior'>
658 <title>Examining the Default&nbsp;&nbsp;<filename>CONFIG_SMP</filename> Behavior</title>
659
660 <para>
661 By default, <filename>CONFIG_SMP</filename> supports multiple processor machines.
662 To see this default setting from within the QEMU emulator, boot your image using
663 the emulator as follows:
664 <literallayout class='monospaced'>
665 $ runqemu qemux86 qemuparams="-smp 4"
666 </literallayout>
667 </para>
668
669 <para>
670 Login to the machine using <filename>root</filename> with no password.
671 After logging in, enter the following command to see how many processors are
672 being supported in the emulator.
673 The emulator reports support for the number of processors you specified using
674 the <filename>-smp</filename> option, four in this case:
675 <literallayout class='monospaced'>
676 # cat /proc/cpuinfo | grep processor
677 processor : 0
678 processor : 1
679 processor : 2
680 processor : 3
681 #
682 </literallayout>
683 To check the setting for <filename>CONFIG_SMP</filename>, you can use the
684 following command:
685 <literallayout class='monospaced'>
686 zcat /proc/config.gz | grep CONFIG_SMP
687 </literallayout>
688 The console returns the following showing that multi-processor machine support
689 is set:
690 <literallayout class='monospaced'>
691 CONFIG_SMP=y
692 </literallayout>
693 Logout of the emulator using the <filename>exit</filename> command and
694 then close it down.
695 </para>
696 </section>
697
698 <section id='changing-the-config-smp-configuration-using-menuconfig'>
699 <title>Changing the&nbsp;&nbsp;<filename>CONFIG_SMP</filename> Configuration Using&nbsp;&nbsp;<filename>menuconfig</filename></title>
700
701 <para>
702 The <filename>menuconfig</filename> tool provides an interactive method with which
703 to set kernel configurations.
704 You need to run <filename>menuconfig</filename> inside the Yocto BitBake environment.
705 Thus, the environment must be set up using the <filename>&OE_INIT_FILE;</filename>
706 script found in the build directory.
707 If you have not sourced this script do so with the following commands:
708 <literallayout class='monospaced'>
709 $ cd ~/poky
710 $ source &OE_INIT_FILE;
711 </literallayout>
712 </para>
713
714 <para>
715 After setting up the environment to run <filename>menuconfig</filename>, you are ready
716 to use the tool to interactively change the kernel configuration.
717 In this example, we are basing our changes on the <filename>linux-yocto-3.4</filename>
718 kernel.
719 The OpenEmbedded build system recognizes this kernel as
720 <filename>linux-yocto</filename>.
721 Thus, the following commands from the shell in which you previously sourced the
722 environment initialization script cleans the shared state cache and the
723 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
724 directory and then builds and launches <filename>menuconfig</filename>:
725 <literallayout class='monospaced'>
726 $ bitbake linux-yocto -c menuconfig
727 </literallayout>
728 </para>
729
730 <para>
731 Once <filename>menuconfig</filename> launches, navigate through the user interface
732 to find the <filename>CONFIG_SMP</filename> configuration setting.
733 You can find it at <filename>Processor Type and Features</filename>.
734 The configuration selection is
735 <filename>Symmetric Multi-processing Support</filename>.
736 After using the arrow keys to highlight this selection, press "n" to turn it off.
737 Then, exit out and save your selections.
738 </para>
739
740 <para>
741 Once you save the selection, the <filename>.config</filename> configuration file
742 is updated.
743 This is the file that the build system uses to configure the Yocto Project kernel
744 when it is built.
745 You can find and examine this file in the build directory.
746 This example uses the following:
747 <literallayout class='monospaced'>
748 ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+84f...
749 ...656ed30-r1/linux-qemux86-standard-build
750 </literallayout>
751 <note>
752 The previous example directory is artificially split and many of the characters
753 in the actual filename are omitted in order to make it more readable.
754 Also, depending on the kernel you are using, the exact pathname might differ
755 slightly.
756 </note>
757 </para>
758
759 <para>
760 Within the <filename>.config</filename> file, you can see the following setting:
761 <literallayout class='monospaced'>
762 # CONFIG_SMP is not set
763 </literallayout>
764 </para>
765
766 <para>
767 A good method to isolate changed configurations is to use a combination of the
768 <filename>menuconfig</filename> tool and simple shell commands.
769 Before changing configurations with <filename>menuconfig</filename>, copy the
770 existing <filename>.config</filename> and rename it to something else,
771 use <filename>menuconfig</filename> to make
772 as many changes an you want and save them, then compare the renamed configuration
773 file against the newly created file.
774 You can use the resulting differences as your base to create configuration fragments
775 to permanently save in your kernel layer.
776 <note>
777 Be sure to make a copy of the <filename>.config</filename> and don't just
778 rename it.
779 The build system needs an existing <filename>.config</filename>
780 from which to work.
781 </note>
782 </para>
783 </section>
784
785 <section id='recompiling-the-kernel-and-testing-the-new-configuration'>
786 <title>Recompiling the Kernel and Testing the New Configuration</title>
787
788 <para>
789 At this point, you are ready to recompile your kernel image with
790 the new setting in effect using the BitBake command below:
791 <literallayout class='monospaced'>
792 $ bitbake linux-yocto
793 </literallayout>
794 </para>
795
796 <para>
797 Now run the QEMU emulator and pass it the same multi-processor option as before:
798 <literallayout class='monospaced'>
799 $ runqemu qemux86 qemuparams="-smp 4"
800 </literallayout>
801 </para>
802
803 <para>
804 Login to the machine using <filename>root</filename> with no password
805 and test for the number of processors the kernel supports:
806 <literallayout class='monospaced'>
807 # cat /proc/cpuinfo | grep processor
808 processor : 0
809 #
810 </literallayout>
811 </para>
812
813 <para>
814 From the output, you can see that the kernel no longer supports multi-processor systems.
815 The output indicates support for a single processor. You can verify the
816 <filename>CONFIG_SMP</filename> setting by using this command:
817 <literallayout class='monospaced'>
818 zcat /proc/config.gz | grep CONFIG_SMP
819 </literallayout>
820 The console returns the following output:
821 <literallayout class='monospaced'>
822 # CONFIG_SMP is not set
823 </literallayout>
824 You have successfully reconfigured the kernel.
825 </para>
826 </section>
827 </section>
828
829 <section id='adding-kernel-recipes'>
830 <title>Adding Kernel Recipes</title>
831
832 <para>
833 A future release of this manual will present an example that adds kernel recipes, which provide
834 new functionality to the kernel.
835 </para>
836
837 <para>
838 <imagedata fileref="figures/wip.png"
839 width="2in" depth="3in" align="center" scalefit="1" />
840 </para>
841 </section>
842</appendix> 549</appendix>
843 550
844<!-- 551<!--
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-01 13:16:33 +0000