blob: f16db3f0f2f13570382e97e9af3feb6fdf1d74e2 [file] [log] [blame]
<!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 set
<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></ulink>
in the <filename>local.conf</filename> file:
<literallayout class='monospaced'>
PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory'
</literallayout>
</para>
</section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->