linux-kernel - Re: [PATCH v2] docs: trace: Refactor index documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20250213114721.23d07909@gandalf.local.home>
Date: Thu, 13 Feb 2025 11:47:21 -0500
From: Steven Rostedt <rostedt@...dmis.org>
To: Purva Yeshi <purvayeshi550@...il.com>
Cc: mhiramat@...nel.org, corbet@....net, skhan@...uxfoundation.org,
 mathieu.desnoyers@...icios.com, linux-kernel@...r.kernel.org,
 linux-trace-kernel@...r.kernel.org, linux-doc@...r.kernel.org
Subject: Re: [PATCH v2] docs: trace: Refactor index documentation

On Thu, 13 Feb 2025 17:26:21 +0530
Purva Yeshi <purvayeshi550@...il.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