| Message ID | 20250206141453.139613-1-purvayeshi550@gmail.com (mailing list archive) |
|---|---|
| State | Changes Requested |
| Headers | show |
| Series | [v2] docs: trace: Refactor index documentation | expand |
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
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.
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
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).
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
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
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.
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
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(-)