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
