Squashed 'yocto-poky/' content from commit ea562de
git-subtree-dir: yocto-poky
git-subtree-split: ea562de57590c966cd5a75fda8defecd397e6436
diff --git a/documentation/profile-manual/profile-manual-intro.xml b/documentation/profile-manual/profile-manual-intro.xml
new file mode 100644
index 0000000..cc47f52
--- /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 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 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
+-->