dev-manual: second pass of poky-tiny section.

(From yocto-docs rev: 44be6fdc992809846fcaade8986c1a1323c14f0c)

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

1 files changed, 209 insertions, 34 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 39da63436f..a6aa8fafbe 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -2086,7 +2086,7 @@
                     You can include nearly any variable from the
                     <filename>local.conf</filename> file.
                     The variables you use are not limited to the list in the
-                    previous bulletted item.</para></listitem>
+                    previous bulleted item.</para></listitem>
                 <listitem><para><emphasis>Point to Your Distribution Configuration File:</emphasis>
                     In your <filename>local.conf</filename> file in the
                     <link linkend='build-directory'>Build Directory</link>,
@@ -2130,22 +2130,14 @@
     <section id='building-a-tiny-system'>
         <title>Building a Tiny System</title>
 
-        <literallayout class='monospaced'>
-     * Introduction that tells what, why, and benefits
-     * Overview of the process
-     * Cutting back on the kernel size
-     * Cutting back on the filesystem (libc and busybox)
-        </literallayout>
-
         <para>
             Very small distributions have some significant advantages such
-            requiring less on-die memory (cheaper), better performance through
-            efficient cache usage, lower power requirements due to less 
+            as requiring less on-die memory (cheaper), better performance 
+            through efficient cache usage, lower power requirements due to less 
             memory, faster boot times, and reduced development overhead.
             Some real-world examples where a very small distribution gives 
             you distinct advantages are digital cameras, medical devices,
             small headless systems, and partitioned flash.
-            You can use the Yocto Project to create very small distribution.
         </para>            
 
         <para>
@@ -2167,11 +2159,13 @@
                 <itemizedlist>
                     <listitem><para>Determine your goals and guiding 
                         principles.</para></listitem>
-                    <listitem><para>Know what you are starting with.
+                    <listitem><para>Understand what gives your image size.
                         </para></listitem>
-                    <listitem><para>Trim the root filesystem.
+                    <listitem><para>Reduce the size of the root filesystem.
                         </para></listitem> 
-                    <listitem><para>Trim the kernel</para></listitem>
+                    <listitem><para>Reduce the size of the kernel.
+                        </para></listitem>
+                    <listitem><para>Iterate on the process.</para></listitem>
                 </itemizedlist>
             </para>
         </section>
@@ -2190,15 +2184,15 @@
                         a root filesystem that is 3 Mbytes or less).
                         </para></listitem>
                     <listitem><para>Find the areas that are currently 
-                        taking 90% of the space and concentrate on that
-                        for trimming.
+                        taking 90% of the space and concentrate on reducing
+                        those areas.
                         </para></listitem>
                     <listitem><para>Do not create any difficult "hacks" 
                         to achieve your goals.</para></listitem>
-                    <listitem><para>Leverage of the device-specific 
+                    <listitem><para>Leverage off the device-specific 
                         options.</para></listitem>
-                    <listitem><para>Do your work in a separate layer 
-                        to keep changes isolated.
+                    <listitem><para>Work in a separate layer so that you 
+                        keep changes isolated.
                         For information on how to create layers, see 
                         the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section.
                         </para></listitem>
@@ -2206,8 +2200,8 @@
             </para>
         </section>
 
-        <section id='know-what-you-are-starting-with'>
-            <title>Know What You Are Starting With</title>
+        <section id='understand-what-gives-your-image-size'>
+            <title>Understand What Gives Your Image Size</title>
 
             <para>
                 You will need to have an image from which you can 
@@ -2218,27 +2212,30 @@
                 that works with two shipped Board Support Packages (BSPs):
                 Fish River Island 2 and QEMU.
                 You can use this distribution as a starting point and trim
-                down from there.
+                the size down from there.
                 If you need to build out the <filename>poky-tiny</filename>
                 distribution, see the
                 "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
-                section.
+                section for information.
             </para>
             
             <para>
                 Understanding some memory concepts will help you reduce the 
                 system size. 
                 Memory consists of static, dynamic, and temporary memory.
-                Static memory is the TEXT, DATA, and BSS sections.  
+                Static memory is the TEXT (the code), DATA (initialized data 
+                in the code), and BSS (uninitialized data) sections.  
                 Dynamic memory contains memory that is allocate at runtime, 
-                stacks, hashtables, and so forth.
-                Temporary memory is decompression and 
-                <filename>__init__</filename>
+                stacks, hash tables, and so forth.
+                Temporary memory is decompressed from the expanded kernel  
+                after boot.
+                Temporary memory also includes the <filename>__init__</filename>
+                functions.
             </para>
 
             <para>
                 To help you see where you currently are with kernel and root
-                filesystem sizes, you can use some tools found in the 
+                filesystem sizes, you can use two tools found in the 
                 <link linkend='source-directory'>Source Directory</link> in 
                 the <filename>scripts</filename> directory:
                 <itemizedlist>
@@ -2247,17 +2244,29 @@
                     <listitem><para><filename>dirsize.py</filename>: Reports
                         the size of the root filesystem.</para></listitem>
                 </itemizedlist>
-                This next tool and command helps you organized configuration 
+                This next tool and command helps you organize configuration 
                 fragments and view file dependencies in a human-readable form:
                 <itemizedlist>
                     <listitem><para><filename>merge_config.sh</filename>:
-                        Merges individual configuration fragments.
-                        For more information on configuration fragments, see
-                        the 
+                        Helps you manage configuration files and fragments
+                        within the kernel.
+                        With this tool you can merge individual configuration
+                        fragments together. 
+                        The tool allows you to make overrides and warns you 
+                        of any missing configuration options.
+                        The tool is ideal for allowing you to iterate on 
+                        configurations, create minimal configurations, and 
+                        create a configuration files for different machines
+                        without having to duplicate your process.</para>
+                        <para>The <filename>merge_config.sh</filename> script is 
+                        part of the Linux Yocto kernel Git repository in the 
+                        <filename>scripts/kconfig</filename> directory.</para>
+                        <para>For more information on configuration fragments, 
+                        see the 
                         "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>"
                         section of the Yocto Project Linux Kernel Development 
                         Manual and the "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
-                        section in this manual.</para></listitem>
+                        section, which is in this manual.</para></listitem>
                     <listitem><para><filename>bitbake -u depexp -g core-image-*</filename>:
                         Using the BitBake command with these options brings up
                         a Dependency Explorer from which you can view file 
@@ -2272,6 +2281,172 @@
         <section id='trim-the-root-filesystem'>
             <title>Trim the Root Filesystem</title>
 
+            <para>
+                Root filesystem is made up of packages for booting, libraries, 
+                and applications.
+                To change things you can configure how the packaging happens,
+                which changes the way you build them. 
+                You can also tweak the filesystem itself or select a different
+                file system.
+            </para>
+
+            <para>
+                First, check out what is hogging your file system running the 
+                <filename>dirsize.sh</filename> script from your root directory:
+                <literallayout class='monospaced'>
+     $ cd &lt;root-directory-of-image&gt;
+     $ dirsize.py 100000 > dirsize-100k.log
+     $ cat dirsize-100k.log
+                </literallayout>
+                You can apply a filter to the script to ignore files under
+                a certain size.   
+                This example filters out anything below 100 Kbytes.
+                When you examine your log file, you can focus on areas of the
+                root filesystem that take up large amounts of memory.
+            </para>
+
+            <para>
+                You need to be sure that what you eliminate does not cripple
+                the functionality you need. 
+                One way to see how packages relate to each other is by using 
+                the Dependency Explorer UI with the BitBake command:
+                <literallayout class='monospaced'>
+     $ cd &lt;image-directory&gt;
+     $ bitbake -u depexp -g &lt;image&gt;
+                </literallayout>
+                Use the interface to select potential packages you wish to 
+                eliminate and see their dependency relationships.
+            </para>
+
+            <para>
+                When deciding how to reduce the size, get rid of packages that 
+                result in minimal impact on the feature set.  
+                For example, you might not need a VGA display.
+                Or, you might be able to get by with <filename>devtmpfs</filename>
+                and <filename>mdev</filename>.
+            </para>
+
+            <para>
+                Use the <filename>local.conf</filename> file to make changes.
+                For example, to eliminate <filename>udev</filename> and 
+                <filename>glib</filename>, set the following in the 
+                local configuration file:
+                <literallayout class='monospaced'>
+     VIRTUAL-RUNTIME_dev_manager = ""
+                </literallayout>
+            </para>
+
+            <para>
+                Some other examples of where you can look to eliminate size 
+                from the root filesystem are using <filename>ext2</filename>
+                rather than <filename>ext3</filename>, which requires a
+                1 Mbyte journal.
+                If you are okay with running read-only you don't need this 
+                journal. 
+            </para>
+
+            <note>
+                After each round of elimination, you need to rebuild your 
+                system and then use the tools to see the effects of your 
+                reductions.
+            </note>
+
+ 
+        </section>
+
+        <section id='trim-the-kernel'>
+            <title>Trim the Kernel</title>
+
+            <para>
+                Kernel is built by including policies for hardware-independent
+                aspects.
+                What subsystems do you enable?
+                What architecture are you building for?
+                Which drivers do you build by default.
+                <note>You can modify the kernel source if you want to help
+                    with boot time.
+                </note>
+            </para>
+
+            <para>
+                Run the <filename>ksize.py</filename> script from the top-level
+                Linux build directory to get an idea of what is making up 
+                the kernel:
+                <literallayout class='monospaced'>
+     $ cd &lt;top-level-linux-build-directory&gt;
+     $ ksize.py > ksize.log
+     $ cat ksize.log
+                </literallayout>
+                When you examine the log, you will see how much space is 
+                taken up with the built-in <filename>.o</filename> files for 
+                drivers, networking, core kernel files, filesystem, sound, 
+                and so forth.
+                Look to reduce the areas that are large and taking up around
+                the "90% rule".
+            </para>
+
+            <para>
+                To examine, or drill down, into any particular area, use the 
+                <filename>-d</filename> option with the script:
+                <literallayout class='monospaced'>
+     $ ksize.py -d > ksize.log
+                </literallayout>
+                Using this option breaks out the individual file information
+                for each area of the kernel (e.g. drivers, networking, and 
+                so forth).
+            </para>
+
+            <para>
+                Use your log file to see what you can eliminate from the kernel
+                based on features you can let go. 
+                For example, if you are not going to need sound, you do not
+                need any drivers that support sound.
+            </para>
+
+            <para>
+                After figuring out what to eliminate, you need to reconfigure
+                kernel to reflect those changes during the next build. 
+                You could run <filename>menuconfig</filename> and make all your
+                changes at once.  
+                However, that makes it difficult to see the effects of your 
+                individual eliminations and also makes it difficult to replicate
+                the changes for perhaps another target device. 
+                A better method is to start with no configurations using
+                <filename>allnoconfig</filename>, create configuration 
+                fragments for individual changes, and then manage the 
+                fragments into a single configuration file using 
+                <filename>merge_config.sh</filename>.
+                The tool makes it easy for you to iterate using the
+                configuration change/build cycle.
+            </para>
+
+            <para>
+                Each time you make configuration changes, you need to rebuild
+                the kernel and check to see what impact your changes had on 
+                the overall size.
+            </para>
+        </section>
+
+        <section id='iterate-on-the-process'>
+            <title>Iterate on the Process</title>
+
+            <para>
+                If you have not reached your goals on system size, you need
+                to iterate on the process.  
+                The process is the same. 
+                Use the tools and see just what is taking up 90% of the root
+                filesystem and the kernel. 
+                Decide what you can eliminate without limiting your device
+                beyond what you need.
+            </para>
+
+            <para>
+                Depending on your system, a good place to look might be 
+                Busybox, which provides a stripped down
+                version of Unix tools in a single, executable file.
+                You might be able to drop virtual terminal services or perhaps
+                ipv6.
+            </para>
         </section>
     </section>
 
@@ -3005,7 +3180,7 @@
                     </literallayout>
                     Once the binary is built, you can find it here:
                     <literallayout class='monospaced'>
-     tmp/sysroots/&lt;host-arch&gt;/usr/bin/&lt;target-abi&gt;-gdb
+     tmp/sysroots/&lt;host-arch&gt;/usr/bin/&lt;target-platform&gt;/&lt;target-abi&gt;-gdb
                     </literallayout>
                 </para>
             </section>