Re: [PATCH v2] docs: trace: Refactor index documentation
From: Steven Rostedt <rostedt@goodmis.org>
Date: 2025-02-10 22:45:54
Also in:
linux-doc, lkml
On Thu, 6 Feb 2025 19:44:53 +0530 Purva Yeshi [off-list ref] 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...
quoted hunk ↗ jump to hunk
bring the documentation into real order, similar to commit '270beb5b2aae' from Linux 6.13, improving clarity, structure, and usability. Signed-off-by: Purva Yeshi <redacted> --- V1 - https://lore.kernel.org/all/20250204133616.27694-1-purvayeshi550@gmail.com/ (local) 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-tracerThe 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_thring-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