summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml88
-rw-r--r--documentation/dev-manual/dev-manual-kernel-appendix.xml293
2 files changed, 81 insertions, 300 deletions
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 @@
1352 <para> 1352 <para>
1353 The easiest way to define kernel configurations is to set them through the 1353 The easiest way to define kernel configurations is to set them through the
1354 <filename>menuconfig</filename> tool. 1354 <filename>menuconfig</filename> tool.
1355 This tool provides an interactive method with which
1356 to set kernel configurations.
1355 For general information on <filename>menuconfig</filename>, see 1357 For general information on <filename>menuconfig</filename>, see
1356 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>. 1358 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
1357 </para> 1359 </para>
@@ -1359,6 +1361,9 @@
1359 <para> 1361 <para>
1360 To use the <filename>menuconfig</filename> tool in the Yocto Project development 1362 To use the <filename>menuconfig</filename> tool in the Yocto Project development
1361 environment, you must build the tool using BitBake. 1363 environment, you must build the tool using BitBake.
1364 Thus, the environment must be set up using the <filename>&OE_INIT_FILE;</filename>
1365 script found in the
1366 <link linkend='build-directory'>Build Directory</link>.
1362 The following commands build and invoke <filename>menuconfig</filename> assuming the 1367 The following commands build and invoke <filename>menuconfig</filename> assuming the
1363 source directory top-level folder is <filename>~/poky</filename>: 1368 source directory top-level folder is <filename>~/poky</filename>:
1364 <literallayout class='monospaced'> 1369 <literallayout class='monospaced'>
@@ -1367,17 +1372,86 @@
1367 $ bitbake linux-yocto -c menuconfig 1372 $ bitbake linux-yocto -c menuconfig
1368 </literallayout> 1373 </literallayout>
1369 Once <filename>menuconfig</filename> comes up, its standard interface allows you to 1374 Once <filename>menuconfig</filename> comes up, its standard interface allows you to
1370 examine and configure all the kernel configuration parameters. 1375 interactively examine and configure all the kernel configuration parameters.
1371 Once you have made your changes, simply exit the tool and save your changes to 1376 After making your changes, simply exit the tool and save your changes to
1372 create an updated version of the <filename>.config</filename> configuration file. 1377 create an updated version of the <filename>.config</filename> configuration file.
1373 </para> 1378 </para>
1374 1379
1375 <para> 1380 <para>
1376 For an example that shows how to change a specific kernel option 1381 Consider an example that configures the <filename>linux-yocto-3.4</filename>
1377 using <filename>menuconfig</filename>, see the 1382 kernel.
1378 "<link linkend='changing-the-config-smp-configuration-using-menuconfig'>Changing 1383 The OpenEmbedded build system recognizes this kernel as
1379 the <filename>CONFIG_SMP</filename> Configuration Using <filename>menuconfig</filename></link>" 1384 <filename>linux-yocto</filename>.
1380 section. 1385 Thus, the following commands from the shell in which you previously sourced the
1386 environment initialization script cleans the shared state cache and the
1387 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
1388 directory and then builds and launches <filename>menuconfig</filename>:
1389 <literallayout class='monospaced'>
1390 $ bitbake linux-yocto -c menuconfig
1391 </literallayout>
1392 </para>
1393
1394 <para>
1395 Once <filename>menuconfig</filename> launches, you use the interface
1396 to navigate through the selections to find the configuration settings in
1397 which you are interested.
1398 For example, consider the <filename>CONFIG_SMP</filename> configuration setting.
1399 You can find it at <filename>Processor Type and Features</filename> under
1400 the configuration selection <filename>Symmetric Multi-processing Support</filename>.
1401 After highlighting the selection, you can use the arrow keys to select or deselect
1402 the setting.
1403 When you are finished with all your selections, exit out and save them.
1404 </para>
1405
1406 <para>
1407 Saving the selections updates the <filename>.config</filename> configuration file.
1408 This is the file that the OpenEmbedded build system uses to configure the
1409 kernel during the build.
1410 You can find and examine this file in the build directory in
1411 <filename>tmp/work/</filename>.
1412 The actual <filename>.config</filename> is located in the area where the
1413 specific kernel is built.
1414 For example, if you were building a Linux Yocto kernel based on the
1415 Linux 3.4 kernel and you were building a QEMU image targeted for
1416 <filename>x86</filename> architecture, the
1417 <filename>.config</filename> file would be located here:
1418 <literallayout class='monospaced'>
1419 ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+84f...
1420 ...656ed30-r1/linux-qemux86-standard-build
1421 </literallayout>
1422 <note>
1423 The previous example directory is artificially split and many of the characters
1424 in the actual filename are omitted in order to make it more readable.
1425 Also, depending on the kernel you are using, the exact pathname
1426 for <filename>linux-yocto-3.4...</filename> might differ.
1427 </note>
1428 </para>
1429
1430 <para>
1431 Within the <filename>.config</filename> file, you can see the kernel settings.
1432 For example, the following entry shows that symmetric multi-processor support
1433 is not set:
1434 <literallayout class='monospaced'>
1435 # CONFIG_SMP is not set
1436 </literallayout>
1437 </para>
1438
1439 <para>
1440 A good method to isolate changed configurations is to use a combination of the
1441 <filename>menuconfig</filename> tool and simple shell commands.
1442 Before changing configurations with <filename>menuconfig</filename>, copy the
1443 existing <filename>.config</filename> and rename it to something else,
1444 use <filename>menuconfig</filename> to make
1445 as many changes an you want and save them, then compare the renamed configuration
1446 file against the newly created file.
1447 You can use the resulting differences as your base to create configuration fragments
1448 to permanently save in your kernel layer.
1449 <note>
1450 Be sure to make a copy of the <filename>.config</filename> and don't just
1451 rename it.
1452 The build system needs an existing <filename>.config</filename>
1453 from which to work.
1454 </note>
1381 </para> 1455 </para>
1382 </section> 1456 </section>
1383 1457
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<!--