blob: d38d61a8208a1f206afb5aff3bfdf7d9e61b7867 [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='profile-manual-intro'>
6
7<title>Yocto Project Profiling and Tracing Manual</title>
8 <section id='profile-intro'>
9 <title>Introduction</title>
10
11 <para>
12 Yocto bundles a number of tracing and profiling tools - this 'HOWTO'
13 describes their basic usage and shows by example how to make use
14 of them to examine application and system behavior.
15 </para>
16
17 <para>
18 The tools presented are for the most part completely open-ended and
19 have quite good and/or extensive documentation of their own which
20 can be used to solve just about any problem you might come across
21 in Linux.
22 Each section that describes a particular tool has links to that
23 tool's documentation and website.
24 </para>
25
26 <para>
27 The purpose of this 'HOWTO' is to present a set of common and
28 generally useful tracing and profiling idioms along with their
29 application (as appropriate) to each tool, in the context of a
30 general-purpose 'drill-down' methodology that can be applied
31 to solving a large number (90%?) of problems.
32 For help with more advanced usages and problems, please see
33 the documentation and/or websites listed for each tool.
34 </para>
35
36 <para>
37 The final section of this 'HOWTO' is a collection of real-world
38 examples which we'll be continually adding to as we solve more
39 problems using the tools - feel free to add your own examples
40 to the list!
41 </para>
42 </section>
43
44 <section id='profile-manual-general-setup'>
45 <title>General Setup</title>
46
47 <para>
48 Most of the tools are available only in 'sdk' images or in images
49 built after adding 'tools-profile' to your local.conf.
50 So, in order to be able to access all of the tools described here,
51 please first build and boot an 'sdk' image e.g.
52 <literallayout class='monospaced'>
53 $ bitbake core-image-sato-sdk
54 </literallayout>
55 or alternatively by adding 'tools-profile' to the
56 EXTRA_IMAGE_FEATURES line in your local.conf:
57 <literallayout class='monospaced'>
58 EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile"
59 </literallayout>
60 If you use the 'tools-profile' method, you don't need to build an
61 sdk image - the tracing and profiling tools will be included in
62 non-sdk images as well e.g.:
63 <literallayout class='monospaced'>
64 $ bitbake core-image-sato
65 </literallayout>
66 <note><para>
67 By default, the Yocto build system strips symbols from the
68 binaries it packages, which makes it difficult to use some
69 of the tools.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060070 </para><para>You can prevent that by setting the
71 <ulink url='&YOCTO_DOCS_REF_URL;#var-INHIBIT_PACKAGE_STRIP'><filename>INHIBIT_PACKAGE_STRIP</filename></ulink>
72 variable to "1" in your
73 <filename>local.conf</filename> when you build the image:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050074 </para>
75 </note>
76 <literallayout class='monospaced'>
77 INHIBIT_PACKAGE_STRIP = "1"
78 </literallayout>
79 The above setting will noticeably increase the size of your image.
80 </para>
81
82 <para>
83 If you've already built a stripped image, you can generate
84 debug packages (xxx-dbg) which you can manually install as
85 needed.
86 </para>
87
88 <para>
89 To generate debug info for packages, you can add dbg-pkgs to
90 EXTRA_IMAGE_FEATURES in local.conf. For example:
91 <literallayout class='monospaced'>
92 EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile dbg-pkgs"
93 </literallayout>
94 Additionally, in order to generate the right type of
95 debuginfo, we also need to add the following to local.conf:
96 <literallayout class='monospaced'>
97 PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory'
98 </literallayout>
99 </para>
100 </section>
101</chapter>
102<!--
103vim: expandtab tw=80 ts=4
104-->