Re: [PATCH v2] docs: trace: Refactor index documentation

From: Steven Rostedt
Date: Mon Feb 10 2025 - 17:47:16 EST


On Thu, 6 Feb 2025 19:44:53 +0530
Purva Yeshi <purvayeshi550@xxxxxxxxx> wrote:

Note, subject should start with: "docs: tracing: ..." as "tracing" is the
subsystem and not "trace". Even though the directory is "trace" the
subsystem is "tracing".

> Refactored Documentation/trace/index.rst to improve clarity, structure,
> and organization. Reformatted sections, added appropriate headings.
>
> Background of Patch:
> This patch is inspired by the maintainer's suggestion on the v1 patch to

Usually it's bad form to have a patch reference itself as "Patch". The
above could be written as:

Background:
These changes were inspired by...

> bring the documentation into real order, similar to commit '270beb5b2aae'
> from Linux 6.13, improving clarity, structure, and usability.
>
> Signed-off-by: Purva Yeshi <purvayeshi550@xxxxxxxxx>
> ---
> V1 - https://lore.kernel.org/all/20250204133616.27694-1-purvayeshi550@xxxxxxxxx/
> V2 - Refined formatting and improved section organization.
>
> Documentation/trace/index.rst | 86 ++++++++++++++++++++++++++++++-----
> 1 file changed, 75 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
> index 2c991dc96..c4ff7e7de 100644
> --- a/Documentation/trace/index.rst
> +++ b/Documentation/trace/index.rst
> @@ -1,39 +1,103 @@
> -==========================
> -Linux Tracing Technologies
> -==========================
> +================================
> +Linux Tracing Technologies Guide
> +================================
> +
> +Tracing in the Linux kernel is a powerful mechanism that allows
> +developers and system administrators to analyze and debug system
> +behavior. This guide provides documentation on various tracing
> +frameworks and tools available in the Linux kernel.
> +
> +Introduction to Tracing
> +-----------------------
> +
> +This section provides an overview of Linux tracing mechanisms
> +and debugging approaches.
>
> .. toctree::
> - :maxdepth: 2
> + :maxdepth: 1

I don't really know what the maxdepth gives here, but there was no mention
in the change log why it had to be converted from 2 to 1.

>
> - ftrace-design
> + debugging
> + tracepoints
> tracepoint-analysis
> +
> +Core Tracing Frameworks
> +-----------------------
> +
> +The following are the primary tracing frameworks integrated into
> +the Linux kernel.
> +
> +.. toctree::
> + :maxdepth: 1
> +
> ftrace
> + ftrace-design
> ftrace-uses
> - fprobe
> kprobes
> kprobetrace
> uprobetracer
> fprobetrace
> - tracepoints
> + fprobe
> +
> +Event Tracing and Analysis
> +--------------------------
> +
> +A detailed explanation of event tracing mechanisms and their
> +applications.
> +
> +.. toctree::
> + :maxdepth: 1
> +
> events
> events-kmem
> events-power
> events-nmi
> events-msr
> - mmiotrace
> + boottime-trace
> histogram
> histogram-design
> - boottime-trace
> - debugging


> hwlat_detector
> osnoise-tracer
> timerlat-tracer

The above 3 probably should be in the hardware interactions section below.

> +
> +Hardware and Performance Tracing
> +--------------------------------
> +
> +This section covers tracing features that monitor hardware
> +interactions and system performance.
> +
> +.. toctree::
> + :maxdepth: 1
> +
> intel_th

> ring-buffer-design

The ring-buffer-design should be in "Core Tracing Frameworks".

> ring-buffer-map

This describes how to map the ring buffer in user space. Maybe it should go
at the "Introduction" section?


> stm
> sys-t
> coresight/index
> - user_events
> rv/index
> hisi-ptt
> +
> +User-space Tracing
> +------------------
> +
> +These tools allow tracing user-space applications and
> +interactions.
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + user_events

> + mmiotrace

mmiotrace traces events between hardware and the drivers. Perhaps this
should go up into the Hardware and Performance tracing.

> +
> +Additional Resources
> +--------------------
> +
> +For more details, refer to the respective documentation of each
> +tracing tool and framework.
> +
> +.. only:: subproject and html
> +
> + Indices
> + =======
> +
> + * :ref:`genindex`
> \ No newline at end of file


Thanks,

-- Steve