documentation/dev-manual/dev-manual-kernel-appendix.xml: Kernel example fixed

Due to a bug (2256) the example that changes the kernel configuration
through menuconfig did not work.  I have re-written the section
to now start with the default behavior of CONFIG_SMP=y and then
have the user change the configuration to where it is not set.

The changes include the reversing of the flow and the work-around
needed due to bug 2256.

(From yocto-docs rev: 6fa9eee12ed83f81470beb9792fb4fc1c5104f69)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 57 insertions, 21 deletions

diff --git a/documentation/dev-manual/dev-manual-kernel-appendix.xml b/documentation/dev-manual/dev-manual-kernel-appendix.xml
index 7ee0e70..db6629d 100644
--- a/documentation/dev-manual/dev-manual-kernel-appendix.xml
+++ b/documentation/dev-manual/dev-manual-kernel-appendix.xml
@@ -509,8 +509,8 @@
         <title>Changing the Kernel Configuration</title>
 
         <para>
-            This example changes the default behavior, which is "off", of the Symmetric 
-            Multi-processing Support (<filename>CONFIG_SMP</filename>) to "on".  
+            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>
 
@@ -533,7 +533,7 @@
                 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 
-                local Yocto Project files Git repository.
+                local <link linkend='yocto-project-files'>Yocto Project Files</link> Git repository.
                 See the bulleted item
                 "<link linkend='local-yp-release'>Yocto Project Release</link>"
                 for information on how to get these files.
@@ -616,11 +616,11 @@
             <title>Examining the Default&nbsp;&nbsp;<filename>CONFIG_SMP</filename> Behavior</title>
 
             <para>
-                By default, <filename>CONFIG_SMP</filename> supports single processor machines.
+                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 2"
+     $ runqemu qemux86 qemuparams="-smp 4"
                 </literallayout>
             </para>
 
@@ -628,12 +628,26 @@
                 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 a single processor:
+                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>
@@ -662,11 +676,21 @@
                 kernel.
                 The Yocto Project build environment recognizes this kernel as 
                 <filename>linux-yocto</filename>.
-                Thus, the following command from the shell in which you previously sourced the 
-                environment initialization script launches <filename>menuconfig</filename>:
+                Thus, the following commands from the shell in which you previously sourced the 
+                environment initialization script cleans the shared state memory 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 cleansstate
      $ bitbake linux-yocto -c menuconfig
                 </literallayout>
+                <note>
+                    Due to a bug in the release, it is necessary to clean the shared state memory
+                    in order for configurations made using <filename>menuconfig</filename> to take
+                    effect.
+                    For information on the bug, see
+                    <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=2256'></ulink>
+                </note>
             </para>
                   
             <para>
@@ -675,7 +699,7 @@
                 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 "y" to select it.
+                After using the arrow keys to highlight this selection, press "n" to turn it off.
                 Then, exit out and save your selections.
             </para>
 
@@ -684,22 +708,25 @@
                 is updated. 
                 This is the file that the build system uses to configure the Linux Yocto kernel
                 when it is built. 
-                You can find and examine this file in the Yocto Project files Git repository in 
+                You can find and examine this file in the Yocto Project Files Git repository in 
                 the build directory. 
-                This example uses the following.
-                Note that this example directory is artificially split and many of the characters 
-                in the actually filename are omitted in order to make it more
-                readable:
+                This example uses the following:
                 <literallayout class='monospaced'>
-     ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-2.6.37+git1+84f...
-        ...r20/linux-qemux86-standard-build
+     ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.2.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=y
+     # CONFIG_SMP is not set
                 </literallayout>
             </para>
 
@@ -735,9 +762,9 @@
             </para>
  
             <para>
-                Now run the QEMU emulator:
+                Now run the QEMU emulator and pass it the same multi-processor option as before:
                 <literallayout class='monospaced'>
-     $ runqemu qemux86 qemuparams="-smp 2"
+     $ runqemu qemux86 qemuparams="-smp 4"
                 </literallayout>
             </para>
 
@@ -747,13 +774,22 @@
                 <literallayout class='monospaced'>
      # cat /proc/cpuinfo | grep processor 
      processor       : 0
-     processor       : 1
      #
                 </literallayout>
             </para>
 
             <para>
-                From the output, you can see that you have successfully reconfigured the kernel.
+                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>