<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

<chapter id='profile-manual-intro'>

<title>Yocto Project Profiling and Tracing Manual</title>
    <section id='profile-intro'>
        <title>Introduction</title>

        <para>
            Yocto bundles a number of tracing and profiling tools - this 'HOWTO'
            describes their basic usage and shows by example how to make use
            of them to examine application and system behavior.
        </para>

        <para>
            The tools presented are for the most part completely open-ended and
            have quite good and/or extensive documentation of their own which
            can be used to solve just about any problem you might come across
            in Linux.
            Each section that describes a particular tool has links to that
            tool's documentation and website.
        </para>

        <para>
            The purpose of this 'HOWTO' is to present a set of common and
            generally useful tracing and profiling idioms along with their
            application (as appropriate) to each tool, in the context of a
            general-purpose 'drill-down' methodology that can be applied
            to solving a large number (90%?) of problems.
            For help with more advanced usages and problems, please see
            the documentation and/or websites listed for each tool.
        </para>

        <para>
            The final section of this 'HOWTO' is a collection of real-world
            examples which we'll be continually adding to as we solve more
            problems using the tools - feel free to add your own examples
            to the list!
        </para>
    </section>

    <section id='profile-manual-general-setup'>
        <title>General Setup</title>

        <para>
            Most of the tools are available only in 'sdk' images or in images
            built after adding 'tools-profile' to your local.conf.
            So, in order to be able to access all of the tools described here,
            please first build and boot an 'sdk' image e.g.
            <literallayout class='monospaced'>
     $ bitbake core-image-sato-sdk
            </literallayout>
            or alternatively by adding 'tools-profile' to the
            EXTRA_IMAGE_FEATURES line in your local.conf:
            <literallayout class='monospaced'>
      EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile"
            </literallayout>
            If you use the 'tools-profile' method, you don't need to build an
            sdk image - the tracing and profiling tools will be included in
            non-sdk images as well e.g.:
            <literallayout class='monospaced'>
     $ bitbake core-image-sato
            </literallayout>
            <note><para>
                By default, the Yocto build system strips symbols from the
                binaries it packages, which makes it difficult to use some
                of the tools.
                </para><para>You can prevent that by setting the
                <ulink url='&YOCTO_DOCS_REF_URL;#var-INHIBIT_PACKAGE_STRIP'><filename>INHIBIT_PACKAGE_STRIP</filename></ulink>
                variable to "1" in your
                <filename>local.conf</filename> when you build the image:
                </para>
            </note>
            <literallayout class='monospaced'>
     INHIBIT_PACKAGE_STRIP = "1"
            </literallayout>
            The above setting will noticeably increase the size of your image.
        </para>

        <para>
            If you've already built a stripped image, you can generate
            debug packages (xxx-dbg) which you can manually install as
            needed.
        </para>

        <para>
            To generate debug info for packages, you can add dbg-pkgs to
            EXTRA_IMAGE_FEATURES in local.conf. For example:
            <literallayout class='monospaced'>
     EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile dbg-pkgs"
            </literallayout>
            Additionally, in order to generate the right type of
            debuginfo, we also need to add the following to local.conf:
            <literallayout class='monospaced'>
     PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory'
            </literallayout>
        </para>
    </section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->