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

[Purva Yeshi]

On 11/02/25 04:15, Steven Rostedt wrote:
> 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".

Thanks for the clarification. I'll update the subject line in the next 
version of the patch.

> > 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...

I'll reword the commit message as suggested and resend the updated 
version shortly. I'll make sure to be more careful next time to avoid 
such mistakes.

> > 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.

I changed :maxdepth: from 2 to 1 to simplify the table of contents, 
keeping only document titles instead of also including second-level 
section headings. The intent was to improve readability and navigation.

Additionally, I referred to commit '270beb5b2aae', as suggested by 
Jonathan Corbet in the v1 patch, to align the documentation structure 
accordingly.

I'll update the commit message in the next revision to explicitly 
mention this change.

> >   
> > -   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.

Okay, I'll move hwlat_detector, osnoise-tracer, and timerlat-tracer to 
the Hardware Tracing section in the next version of the patch.

> > +
> > +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".

I'll move 'ring-buffer-design' to the Core Tracing Frameworks section.

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

For ring-buffer-map, placing it in the Introduction section could 
provide early context, but since it is more implementation-specific, it 
might fit better under Core Tracing Frameworks alongside 
ring-buffer-design. Would that placement works?

> >      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.

Okay, since 'mmiotrace' primarily traces MMIO interactions between 
hardware and drivers, it makes more sense under Hardware and Performance 
Tracing. I'll move it there in the next revision.

> > +
> > +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

Thanks for the suggestions. I'll incorporate these changes in the next 
revision.

Best regards,
Purva Yeshi