On 11/02/25 04:15, Steven Rostedt wrote:
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".
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@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.
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
