Initial commit

poky/documentation/profile-manual/arch.rst

@@ -0,0 +1,29 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+*************************************************************
+Overall Architecture of the Linux Tracing and Profiling Tools
+*************************************************************
+
+Architecture of the Tracing and Profiling Tools
+===============================================
+
+It may seem surprising to see a section covering an 'overall
+architecture' for what seems to be a random collection of tracing tools
+that together make up the Linux tracing and profiling space. The fact
+is, however, that in recent years this seemingly disparate set of tools
+has started to converge on a 'core' set of underlying mechanisms:
+
+-  static tracepoints
+-  dynamic tracepoints
+
+   -  kprobes
+   -  uprobes
+
+-  the perf_events subsystem
+-  debugfs
+
+.. admonition:: Tying it Together
+
+   Rather than enumerating here how each tool makes use of these common
+   mechanisms, textboxes like this will make note of the specific usages
+   in each tool as they come up in the course of the text.

poky/documentation/profile-manual/examples.rst

@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+*******************
+Real-World Examples
+*******************
+
+|
+
+This chapter contains real-world examples.
+
+Slow Write Speed on Live Images
+===============================
+
+In one of our previous releases (denzil), users noticed that booting off
+of a live image and writing to disk was noticeably slower. This included
+the boot itself, especially the first one, since first boots tend to do
+a significant amount of writing due to certain post-install scripts.
+
+The problem (and solution) was discovered by using the Yocto tracing
+tools, in this case 'perf stat', 'perf script', 'perf record' and 'perf
+report'.
+
+See all the unvarnished details of how this bug was diagnosed and solved
+here: Yocto Bug #3049

poky/documentation/profile-manual/index.rst

@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+==========================================
+Yocto Project Profiling and Tracing Manual
+==========================================
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   intro
+   arch
+   usage
+   examples
+
+.. include:: /boilerplate.rst

poky/documentation/profile-manual/intro.rst

@@ -0,0 +1,75 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+******************************************
+Yocto Project Profiling and Tracing Manual
+******************************************
+
+Introduction
+============
+
+Yocto bundles a number of tracing and profiling tools --- this 'HOWTO'
+describes their basic usage and shows by example how to make use of them
+to examine application and system behavior.
+
+The tools presented are for the most part completely open-ended and have
+quite good and/or extensive documentation of their own which can be used
+to solve just about any problem you might come across in Linux. Each
+section that describes a particular tool has links to that tool's
+documentation and website.
+
+The purpose of this 'HOWTO' is to present a set of common and generally
+useful tracing and profiling idioms along with their application (as
+appropriate) to each tool, in the context of a general-purpose
+'drill-down' methodology that can be applied to solving a large number
+(90%?) of problems. For help with more advanced usages and problems,
+please see the documentation and/or websites listed for each tool.
+
+The final section of this 'HOWTO' is a collection of real-world examples
+which we'll be continually adding to as we solve more problems using the
+tools --- feel free to add your own examples to the list!
+
+General Setup
+=============
+
+Most of the tools are available only in 'sdk' images or in images built
+after adding 'tools-profile' to your local.conf. So, in order to be able
+to access all of the tools described here, please first build and boot
+an 'sdk' image e.g. ::
+
+   $ bitbake core-image-sato-sdk
+
+or alternatively by adding 'tools-profile' to the :term:`EXTRA_IMAGE_FEATURES` line in
+your local.conf::
+
+   EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile"
+
+If you use the 'tools-profile' method, you don't need to build an sdk image -
+the tracing and profiling tools will be included in non-sdk images as well e.g.::
+
+   $ bitbake core-image-sato
+
+.. note::
+
+   By default, the Yocto build system strips symbols from the binaries
+   it packages, which makes it difficult to use some of the tools.
+
+   You can prevent that by setting the
+   :term:`INHIBIT_PACKAGE_STRIP`
+   variable to "1" in your ``local.conf`` when you build the image::
+
+      INHIBIT_PACKAGE_STRIP = "1"
+
+   The above setting will noticeably increase the size of your image.
+
+If you've already built a stripped image, you can generate debug
+packages (xxx-dbg) which you can manually install as needed.
+
+To generate debug info for packages, you can add dbg-pkgs to
+:term:`EXTRA_IMAGE_FEATURES` in local.conf. For example::
+
+   EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile dbg-pkgs"
+
+Additionally, in order to generate the right type of debuginfo, we also need to
+set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the ``local.conf`` file::
+
+   PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory'