diff options
Diffstat (limited to 'documentation/profile-manual/intro.rst')
-rw-r--r-- | documentation/profile-manual/intro.rst | 75 |
1 files changed, 75 insertions, 0 deletions
diff --git a/documentation/profile-manual/intro.rst b/documentation/profile-manual/intro.rst new file mode 100644 index 0000000000..4e1008b05e --- /dev/null +++ b/documentation/profile-manual/intro.rst | |||
@@ -0,0 +1,75 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | ****************************************** | ||
4 | Yocto Project Profiling and Tracing Manual | ||
5 | ****************************************** | ||
6 | |||
7 | Introduction | ||
8 | ============ | ||
9 | |||
10 | Yocto bundles a number of tracing and profiling tools - this 'HOWTO' | ||
11 | describes their basic usage and shows by example how to make use of them | ||
12 | to examine application and system behavior. | ||
13 | |||
14 | The tools presented are for the most part completely open-ended and have | ||
15 | quite good and/or extensive documentation of their own which can be used | ||
16 | to solve just about any problem you might come across in Linux. Each | ||
17 | section that describes a particular tool has links to that tool's | ||
18 | documentation and website. | ||
19 | |||
20 | The purpose of this 'HOWTO' is to present a set of common and generally | ||
21 | useful tracing and profiling idioms along with their application (as | ||
22 | appropriate) 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, | ||
25 | please see the documentation and/or websites listed for each tool. | ||
26 | |||
27 | The final section of this 'HOWTO' is a collection of real-world examples | ||
28 | which we'll be continually adding to as we solve more problems using the | ||
29 | tools - feel free to add your own examples to the list! | ||
30 | |||
31 | General Setup | ||
32 | ============= | ||
33 | |||
34 | Most of the tools are available only in 'sdk' images or in images built | ||
35 | after adding 'tools-profile' to your local.conf. So, in order to be able | ||
36 | to access all of the tools described here, please first build and boot | ||
37 | an 'sdk' image e.g. :: | ||
38 | |||
39 | $ bitbake core-image-sato-sdk | ||
40 | |||
41 | or alternatively by adding 'tools-profile' to the EXTRA_IMAGE_FEATURES line in | ||
42 | your local.conf: :: | ||
43 | |||
44 | EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile" | ||
45 | |||
46 | If you use the 'tools-profile' method, you don't need to build an sdk image - | ||
47 | the tracing and profiling tools will be included in non-sdk images as well e.g.: :: | ||
48 | |||
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` | ||
58 | variable to "1" in your ``local.conf`` when you build the image: :: | ||
59 | |||
60 | INHIBIT_PACKAGE_STRIP = "1" | ||
61 | |||
62 | The above setting will noticeably increase the size of your image. | ||
63 | |||
64 | If you've already built a stripped image, you can generate debug | ||
65 | packages (xxx-dbg) which you can manually install as needed. | ||
66 | |||
67 | To generate debug info for packages, you can add dbg-pkgs to | ||
68 | EXTRA_IMAGE_FEATURES in local.conf. For example: :: | ||
69 | |||
70 | EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile dbg-pkgs" | ||
71 | |||
72 | Additionally, in order to generate the right type of debuginfo, we also need to | ||
73 | set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the ``local.conf`` file: :: | ||
74 | |||
75 | PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory' | ||