blob: 9c8fa3dbfa150f0612c4765326f65d3390c6b442 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3******************************************
4Yocto Project Profiling and Tracing Manual
5******************************************
6
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007Introduction
8============
9
10Yocto bundles a number of tracing and profiling tools - this 'HOWTO'
11describes their basic usage and shows by example how to make use of them
12to examine application and system behavior.
13
14The tools presented are for the most part completely open-ended and have
15quite good and/or extensive documentation of their own which can be used
16to solve just about any problem you might come across in Linux. Each
17section that describes a particular tool has links to that tool's
18documentation and website.
19
20The purpose of this 'HOWTO' is to present a set of common and generally
21useful tracing and profiling idioms along with their application (as
22appropriate) to each tool, in the context of a general-purpose
23'drill-down' methodology that can be applied to solving a large number
24(90%?) of problems. For help with more advanced usages and problems,
25please see the documentation and/or websites listed for each tool.
26
27The final section of this 'HOWTO' is a collection of real-world examples
28which we'll be continually adding to as we solve more problems using the
29tools - feel free to add your own examples to the list!
30
Andrew Geisslerc9f78652020-09-18 14:11:35 -050031General Setup
32=============
33
34Most of the tools are available only in 'sdk' images or in images built
35after adding 'tools-profile' to your local.conf. So, in order to be able
36to access all of the tools described here, please first build and boot
37an 'sdk' image e.g. ::
38
39 $ bitbake core-image-sato-sdk
40
41or alternatively by adding 'tools-profile' to the EXTRA_IMAGE_FEATURES line in
Andrew Geisslerc926e172021-05-07 16:11:35 -050042your local.conf::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050043
44 EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile"
45
46If you use the 'tools-profile' method, you don't need to build an sdk image -
Andrew Geisslerc926e172021-05-07 16:11:35 -050047the tracing and profiling tools will be included in non-sdk images as well e.g.::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050048
49 $ bitbake core-image-sato
50
51.. note::
52
53 By default, the Yocto build system strips symbols from the binaries
54 it packages, which makes it difficult to use some of the tools.
55
56 You can prevent that by setting the
57 :term:`INHIBIT_PACKAGE_STRIP`
Andrew Geisslerc926e172021-05-07 16:11:35 -050058 variable to "1" in your ``local.conf`` when you build the image::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050059
60 INHIBIT_PACKAGE_STRIP = "1"
61
62 The above setting will noticeably increase the size of your image.
63
64If you've already built a stripped image, you can generate debug
65packages (xxx-dbg) which you can manually install as needed.
66
67To generate debug info for packages, you can add dbg-pkgs to
Andrew Geisslerc926e172021-05-07 16:11:35 -050068EXTRA_IMAGE_FEATURES in local.conf. For example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050069
70 EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile dbg-pkgs"
71
72Additionally, in order to generate the right type of debuginfo, we also need to
Andrew Geisslerc926e172021-05-07 16:11:35 -050073set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050074
75 PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory'