1 files changed, 102 insertions, 0 deletions

diff --git a/documentation/profile-manual/profile-manual-intro.xml b/documentation/profile-manual/profile-manual-intro.xml
new file mode 100644
index 0000000000..96f819c4d9
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-intro.xml
@@ -0,0 +1,102 @@
+<!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 Tracing and Profiling Manual</title>
+    <section id='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 putting the following
+                in your local.conf 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
+-->