Documentation: tracing: Add PCI controller event documentation

The PCI controller tracepoint, pcie_ltssm_state_transition, monitors the
LTSSM state transition and data rate changes for debugging purposes. Add
documentation for it.

Signed-off-by: Shawn Lin <shawn.lin@rock-chips.com>
[mani: added MAINTAINERS entry]
Signed-off-by: Manivannan Sadhasivam <mani@kernel.org>
Reviewed-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Link: https://patch.msgid.link/1774403912-210670-3-git-send-email-shawn.lin@rock-chips.com

diff --git a/Documentation/trace/events-pci-controller.rst b/Documentation/trace/events-pci-controller.rst
new file mode 100644 (file)
index 0000000..cb9f715
--- /dev/null
+++ b/Documentation/trace/events-pci-controller.rst
@@ -0,0 +1,42 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================================
+Subsystem Trace Points: PCI Controller
+======================================
+
+Overview
+========
+The PCI controller tracing system provides tracepoints to monitor controller
+level information for debugging purpose. The events normally show up here:
+
+       /sys/kernel/tracing/events/pci_controller
+
+Cf. include/trace/events/pci_controller.h for the events definitions.
+
+Available Tracepoints
+=====================
+
+pcie_ltssm_state_transition
+---------------------------
+
+Monitors PCIe LTSSM state transition including state and rate information
+::
+
+    pcie_ltssm_state_transition  "dev: %s state: %s rate: %s\n"
+
+**Parameters**:
+
+* ``dev`` - PCIe controller instance
+* ``state`` - PCIe LTSSM state
+* ``rate`` - PCIe date rate
+
+**Example Usage**:
+
+.. code-block:: shell
+
+    # Enable the tracepoint
+    echo 1 > /sys/kernel/debug/tracing/events/pci_controller/pcie_ltssm_state_transition/enable
+
+    # Monitor events (the following output is generated when a device is linking)
+    cat /sys/kernel/debug/tracing/trace_pipe
+       kworker/0:0-9       [000] .....     5.600221: pcie_ltssm_state_transition: dev: a40000000.pcie state: RCVRY_EQ2 rate: 8.0 GT/s

diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 338bc4d7cfab1ec9dcb9c7e805ec67e95997ecd5..5715a32866ab7415ea65239f803d386e3299f3b6 100644 (file)
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -55,6 +55,7 @@ applications.
    events-nmi
    events-msr
    events-pci
+   events-pci-controller
    boottime-trace
    histogram
    histogram-design

diff --git a/MAINTAINERS b/MAINTAINERS
index b5a83f0b4211230dab828387bb53c1a11b2e5c83..f81b918c75070347ee27d13de85e1c89df301f0f 100644 (file)
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -20396,6 +20396,7 @@ C:      irc://irc.oftc.net/linux-pci
 T:     git git://git.kernel.org/pub/scm/linux/kernel/git/pci/pci.git
 F:     Documentation/ABI/testing/debugfs-pcie-ptm
 F:     Documentation/devicetree/bindings/pci/
+F:     Documentation/trace/events-pci-controller.rst
 F:     drivers/pci/controller/
 F:     drivers/pci/pci-bridge-emul.c
 F:     drivers/pci/pci-bridge-emul.h