[PATCH v2] docs: trace: Refactor index documentation

[PATCH v2] docs: trace: Refactor index documentation

[Purva Yeshi]

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
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@gmail.com>
---
V1 - https://lore.kernel.org/all/20250204133616.27694-1-purvayeshi550@gmail.com/
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
 
-   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
+
+Hardware and Performance Tracing
+--------------------------------
+
+This section covers tracing features that monitor hardware
+interactions and system performance.
+
+.. toctree::
+   :maxdepth: 1
+
    intel_th
    ring-buffer-design
    ring-buffer-map
    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
+
+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
-- 
2.34.1

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

[Steven Rostedt]

On Thu,  6 Feb 2025 19:44:53 +0530
Purva Yeshi <purvayeshi550@gmail.com> 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@gmail.com>
> ---
> V1 - https://lore.kernel.org/all/20250204133616.27694-1-purvayeshi550@gmail.com/
> 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

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

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 786 bytes --]

On Mon, Feb 10, 2025 at 05:45:56PM -0500, Steven Rostedt wrote:
> On Thu,  6 Feb 2025 19:44:53 +0530
> Purva Yeshi <purvayeshi550@gmail.com> wrote:
> 
> > +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.

:maxdepth: specifies heading levels depth of the toctree. In this case,
the author wants only doc titles (hence 1), whereas 2 also includes
second-level (section) headings.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

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

[Steven Rostedt]

On Wed, 12 Feb 2025 18:10:44 +0700
Bagas Sanjaya <bagasdotme@gmail.com> wrote:

> > > +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.  
> 
> :maxdepth: specifies heading levels depth of the toctree. In this case,
> the author wants only doc titles (hence 1), whereas 2 also includes
> second-level (section) headings.

As I'm the original author, I would like to know why there was a change.

-- Steve

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

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 991 bytes --]

On Wed, Feb 12, 2025 at 09:51:11AM -0500, Steven Rostedt wrote:
> On Wed, 12 Feb 2025 18:10:44 +0700
> Bagas Sanjaya <bagasdotme@gmail.com> wrote:
> 
> > > > +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.  
> > 
> > :maxdepth: specifies heading levels depth of the toctree. In this case,
> > the author wants only doc titles (hence 1), whereas 2 also includes
> > second-level (section) headings.
> 
> As I'm the original author, I would like to know why there was a change.
> 

Oops, I mean I'm referring to the patch author (Purva Yeshi).

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

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@gmail.com> 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@gmail.com>
>> ---
>> V1 - https://lore.kernel.org/all/20250204133616.27694-1-purvayeshi550@gmail.com/
>> 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

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

[Steven Rostedt]

On Thu, 13 Feb 2025 17:26:21 +0530
Purva Yeshi <purvayeshi550@gmail.com> wrote:

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

Can you make that a separate patch. A commit should do only one thing and
that change isn't necessary to be part of the rest of the changes.

> >>   
> >> -   ftrace-design
> >> +   debugging
> >> +   tracepoints
> >>      tracepoint-analysis
> >> +

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


But it's not kernel implementation. It describes how to use it in user
space. That is, it's not part of the tracing framework.

-- Steve

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

[Purva Yeshi]

On 13/02/25 22:17, Steven Rostedt wrote:
> On Thu, 13 Feb 2025 17:26:21 +0530
> Purva Yeshi <purvayeshi550@gmail.com> wrote:
> 
>>>> +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.
>>
> 
> Can you make that a separate patch. A commit should do only one thing and
> that change isn't necessary to be part of the rest of the changes.

Okay, I’ll separate this change into a new patch.

> 
>>>>    
>>>> -   ftrace-design
>>>> +   debugging
>>>> +   tracepoints
>>>>       tracepoint-analysis
>>>> +
> 
>>>> +
>>>> +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?
> 
> 
> But it's not kernel implementation. It describes how to use it in user
> space. That is, it's not part of the tracing framework.
> 
> -- Steve

Thanks for the clarification. I’ll move it to the Introduction section 
in the next revision.