mirror of
https://git.yoctoproject.org/poky
synced 2026-06-03 01:40:07 +00:00
sphinx: import docs
The Yocto Project docs was migrated from Docbook to Sphinx in YP 3.2. This 3.1 is an LTS release, and since 3.1 docs are 'close to' the docs in 3.2, we agreed to backport sphinx docs onto 3.1. This first patch brings all changes done in 3.2 until: 7f64574f7 README: include detailed information about sphinx There are other changes after this commit, but they will be selectively backported in individual patches. This patch was generated with the following command: git cherry-pick -n \ $(git log --reverse --oneline \ ac352ad7f95db7eeacb53c2778caa31800bd7c26..7f64574f7 \ | cut -f1 -d' ') The following commits were applies in the dunfell docs, but not in master, so they were first reverted (and squashed into this change). A commit will reintroduce the content from these patches in the Sphinx files in a followup patch. 069c27574 Documenation: Prepared for the 3.1.1 release bd140f0f9 Documentation: Add 3.1.1 version updates missing from previous commit 17cc71a8f Documenation: Prepared for the 3.1.2 release 1a69e2c02 Documenation: Prepared for the 3.1.3 release 8910ac1c7 Documenation: Prepared for the 3.1.4 release (From yocto-docs rev: c25fe058b88b893b0d146f3ed27320b47cdec236) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Nicolas Dechesne
committed by
Richard Purdie
Richard Purdie
parent
a038e58f3c
commit
fa0cb4d34b
@@ -0,0 +1,58 @@
|
||||
.. SPDX-License-Identifier: CC-BY-2.0-UK
|
||||
|
||||
***********************
|
||||
Manual Revision History
|
||||
***********************
|
||||
|
||||
.. list-table::
|
||||
:widths: 10 15 40
|
||||
:header-rows: 1
|
||||
|
||||
* - Revision
|
||||
- Date
|
||||
- Note
|
||||
* - 1.4
|
||||
- April 2013
|
||||
- The initial document released with the Yocto Project 1.4 Release
|
||||
* - 1.5
|
||||
- October 2013
|
||||
- Released with the Yocto Project 1.5 Release.
|
||||
* - 1.6
|
||||
- April 2014
|
||||
- Released with the Yocto Project 1.6 Release.
|
||||
* - 1.7
|
||||
- October 2014
|
||||
- Released with the Yocto Project 1.7 Release.
|
||||
* - 1.8
|
||||
- April 2015
|
||||
- Released with the Yocto Project 1.8 Release.
|
||||
* - 2.0
|
||||
- October 2015
|
||||
- Released with the Yocto Project 2.0 Release.
|
||||
* - 2.1
|
||||
- April 2016
|
||||
- Released with the Yocto Project 2.1 Release.
|
||||
* - 2.2
|
||||
- October 2016
|
||||
- Released with the Yocto Project 2.2 Release.
|
||||
* - 2.3
|
||||
- May 2017
|
||||
- Released with the Yocto Project 2.3 Release.
|
||||
* - 2.4
|
||||
- October 2017
|
||||
- Released with the Yocto Project 2.4 Release.
|
||||
* - 2.5
|
||||
- May 2018
|
||||
- Released with the Yocto Project 2.5 Release.
|
||||
* - 2.6
|
||||
- November 2018
|
||||
- Released with the Yocto Project 2.6 Release.
|
||||
* - 2.7
|
||||
- May 2019
|
||||
- Released with the Yocto Project 2.7 Release.
|
||||
* - 3.0
|
||||
- October 2019
|
||||
- Released with the Yocto Project 3.0 Release.
|
||||
* - 3.1
|
||||
- April 2020
|
||||
- Released with the Yocto Project 3.1 Release.
|
||||
@@ -0,0 +1,29 @@
|
||||
.. SPDX-License-Identifier: CC-BY-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.
|
||||
@@ -1,6 +1,7 @@
|
||||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
||||
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
|
||||
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
|
||||
|
||||
<chapter id='profile-manual-arch'>
|
||||
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
<?xml version='1.0'?>
|
||||
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
|
||||
|
||||
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
|
||||
|
||||
<xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
.. SPDX-License-Identifier: CC-BY-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
|
||||
@@ -1,6 +1,7 @@
|
||||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
||||
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
|
||||
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
|
||||
|
||||
<chapter id='profile-manual-examples'>
|
||||
|
||||
|
||||
@@ -0,0 +1,79 @@
|
||||
.. SPDX-License-Identifier: CC-BY-2.0-UK
|
||||
|
||||
******************************************
|
||||
Yocto Project Profiling and Tracing Manual
|
||||
******************************************
|
||||
|
||||
.. _profile-intro:
|
||||
|
||||
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!
|
||||
|
||||
.. _profile-manual-general-setup:
|
||||
|
||||
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 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
|
||||
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'
|
||||
@@ -1,6 +1,7 @@
|
||||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
||||
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
|
||||
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
|
||||
|
||||
<chapter id='profile-manual-intro'>
|
||||
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
/*
|
||||
|
||||
SPDX-License-Identifier: CC-BY-2.0-UK
|
||||
|
||||
Generic XHTML / DocBook XHTML CSS Stylesheet.
|
||||
|
||||
Browser wrangling and typographic design by
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,6 +1,7 @@
|
||||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
||||
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
|
||||
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
|
||||
|
||||
<chapter id='profile-manual-usage'>
|
||||
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
.. SPDX-License-Identifier: CC-BY-2.0-UK
|
||||
|
||||
==========================================
|
||||
Yocto Project Profiling and Tracing Manual
|
||||
==========================================
|
||||
|
||||
|
|
||||
|
||||
.. toctree::
|
||||
:caption: Table of Contents
|
||||
:numbered:
|
||||
|
||||
profile-manual-intro
|
||||
profile-manual-arch
|
||||
profile-manual-usage
|
||||
profile-manual-examples
|
||||
history
|
||||
|
||||
.. include:: /boilerplate.rst
|
||||
@@ -1,6 +1,7 @@
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
||||
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
|
||||
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
|
||||
|
||||
<book id='profile-manual' lang='en'
|
||||
xmlns:xi="http://www.w3.org/2003/XInclude"
|
||||
@@ -102,28 +103,8 @@
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>3.1</revnumber>
|
||||
<date>April 2020</date>
|
||||
<revremark>Released with the Yocto Project 3.1 Release.</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>3.1.1</revnumber>
|
||||
<date>June 2020</date>
|
||||
<revremark>Released with the Yocto Project 3.1.1 Release.</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>3.1.2</revnumber>
|
||||
<date>August 2020</date>
|
||||
<revremark>Released with the Yocto Project 3.1.2 Release.</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>3.1.3</revnumber>
|
||||
<date>October 2020</date>
|
||||
<revremark>Released with the Yocto Project 3.1.3 Release.</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>3.1.4</revnumber>
|
||||
<date>&REL_MONTH_YEAR;</date>
|
||||
<revremark>Released with the Yocto Project 3.1.4 Release.</revremark>
|
||||
<revremark>Released with the Yocto Project 3.1 Release.</revremark>
|
||||
</revision>
|
||||
</revhistory>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user