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