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 local.conf file. The variables you use are not limited to the list in the - previous bulletted item. + previous bulleted item. Point to Your Distribution Configuration File: In your local.conf file in the Build Directory, @@ -2130,22 +2130,14 @@
Building a Tiny System - - * 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) - - 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. @@ -2167,11 +2159,13 @@ Determine your goals and guiding principles. - Know what you are starting with. + Understand what gives your image size. - Trim the root filesystem. + Reduce the size of the root filesystem. - Trim the kernel + Reduce the size of the kernel. + + Iterate on the process.
@@ -2190,15 +2184,15 @@ a root filesystem that is 3 Mbytes or less). 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. Do not create any difficult "hacks" to achieve your goals. - Leverage of the device-specific + Leverage off the device-specific options. - Do your work in a separate layer - to keep changes isolated. + Work in a separate layer so that you + keep changes isolated. For information on how to create layers, see the "Understanding and Creating Layers" section. @@ -2206,8 +2200,8 @@ -
- Know What You Are Starting With +
+ Understand What Gives Your Image Size 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 poky-tiny distribution, see the "Creating Your Own Distribution" - section. + section for information. 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 - __init__ + stacks, hash tables, and so forth. + Temporary memory is decompressed from the expanded kernel + after boot. + Temporary memory also includes the __init__ + functions. 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 Source Directory in the scripts directory: @@ -2247,17 +2244,29 @@ dirsize.py: Reports the size of the root filesystem. - 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: merge_config.sh: - 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. + The merge_config.sh script is + part of the Linux Yocto kernel Git repository in the + scripts/kconfig directory. + For more information on configuration fragments, + see the "Generating Configuration Files" section of the Yocto Project Linux Kernel Development Manual and the "Creating Configuration Fragments" - section in this manual. + section, which is in this manual. bitbake -u depexp -g core-image-*: Using the BitBake command with these options brings up a Dependency Explorer from which you can view file @@ -2272,6 +2281,172 @@
Trim the Root Filesystem + + 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. + + + + First, check out what is hogging your file system running the + dirsize.sh script from your root directory: + + $ cd <root-directory-of-image> + $ dirsize.py 100000 > dirsize-100k.log + $ cat dirsize-100k.log + + 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. + + + + 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: + + $ cd <image-directory> + $ bitbake -u depexp -g <image> + + Use the interface to select potential packages you wish to + eliminate and see their dependency relationships. + + + + 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 devtmpfs + and mdev. + + + + Use the local.conf file to make changes. + For example, to eliminate udev and + glib, set the following in the + local configuration file: + + VIRTUAL-RUNTIME_dev_manager = "" + + + + + Some other examples of where you can look to eliminate size + from the root filesystem are using ext2 + rather than ext3, which requires a + 1 Mbyte journal. + If you are okay with running read-only you don't need this + journal. + + + + After each round of elimination, you need to rebuild your + system and then use the tools to see the effects of your + reductions. + + + +
+ +
+ Trim the Kernel + + + 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. + You can modify the kernel source if you want to help + with boot time. + + + + + Run the ksize.py script from the top-level + Linux build directory to get an idea of what is making up + the kernel: + + $ cd <top-level-linux-build-directory> + $ ksize.py > ksize.log + $ cat ksize.log + + When you examine the log, you will see how much space is + taken up with the built-in .o 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". + + + + To examine, or drill down, into any particular area, use the + -d option with the script: + + $ ksize.py -d > ksize.log + + Using this option breaks out the individual file information + for each area of the kernel (e.g. drivers, networking, and + so forth). + + + + 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. + + + + After figuring out what to eliminate, you need to reconfigure + kernel to reflect those changes during the next build. + You could run menuconfig 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 + allnoconfig, create configuration + fragments for individual changes, and then manage the + fragments into a single configuration file using + merge_config.sh. + The tool makes it easy for you to iterate using the + configuration change/build cycle. + + + + 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. + +
+ +
+ Iterate on the Process + + + 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. + + + + 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. +
@@ -3005,7 +3180,7 @@ Once the binary is built, you can find it here: - tmp/sysroots/<host-arch>/usr/bin/<target-abi>-gdb + tmp/sysroots/<host-arch>/usr/bin/<target-platform>/<target-abi>-gdb