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