1. Patchew
  2. linux
  3. [PATCH v13 0/3] PCI: trace: Add a RAS tracepoint to monitor link speed changes
  4. View patch

[PATCH v13 3/3] Documentation: tracing: Add documentation about PCI tracepoints

Shuai Xue posted 3 patches 3 months, 2 weeks ago
There is a newer version of this series
[PATCH v13 3/3] Documentation: tracing: Add documentation about PCI tracepoints
Posted by Shuai Xue 3 months, 2 weeks ago 
The PCI tracing system provides tracepoints to monitor critical hardware
events that can impact system performance and reliability. Add
documentation about it.

Reviewed-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
Signed-off-by: Shuai Xue <xueshuai@linux.alibaba.com>
---
 Documentation/trace/events-pci.rst | 74 ++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 Documentation/trace/events-pci.rst

diff --git a/Documentation/trace/events-pci.rst b/Documentation/trace/events-pci.rst
new file mode 100644
index 000000000000..88bd38fcc184
--- /dev/null
+++ b/Documentation/trace/events-pci.rst
@@ -0,0 +1,74 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================
+Subsystem Trace Points: PCI
+===========================
+
+Overview
+========
+The PCI tracing system provides tracepoints to monitor critical hardware events
+that can impact system performance and reliability. These events normally show
+up here:
+
+	/sys/kernel/tracing/events/pci
+
+Cf. include/trace/events/pci.h for the events definitions.
+
+Available Tracepoints
+=====================
+
+pci_hp_event
+------------
+
+Monitors PCI hotplug events including card insertion/removal and link
+state changes.
+::
+
+    pci_hp_event  "%s slot:%s, event:%s\n"
+
+**Event Types**:
+
+* ``LINK_UP`` - PCIe link established
+* ``LINK_DOWN`` - PCIe link lost
+* ``CARD_PRESENT`` - Card detected in slot
+* ``CARD_NOT_PRESENT`` - Card removed from slot
+
+**Example Usage**:
+
+    # Enable the tracepoint
+    echo 1> /sys/kernel/debug/tracing/events/pci/pci_hp_event/enable
+
+    # Monitor events (the following output is generated when a device is hotplugged)
+    cat /sys/kernel/debug/tracing/trace_pipe
+       irq/51-pciehp-88      [001] .....  1311.177459: pci_hp_event: 0000:00:02.0 slot:10, event:CARD_PRESENT
+
+       irq/51-pciehp-88      [001] .....  1311.177566: pci_hp_event: 0000:00:02.0 slot:10, event:LINK_UP
+
+pcie_link_event
+---------------
+
+Monitors PCIe link speed changes and provides detailed link status information.
+::
+
+    pcie_link_event  "%s type:%d, reason:%d, cur_bus_speed:%s, max_bus_speed:%s, width:%u, flit_mode:%u, status:%s\n"
+
+**Parameters**:
+
+* ``type`` - PCIe device type (4=Root Port, etc.)
+* ``reason`` - Reason for link change:
+
+  - ``0`` - Link retrain
+  - ``1`` - Bus enumeration
+  - ``2`` - Bandwidth notification enable
+  - ``3`` - Bandwidth notification IRQ
+  - ``4`` - Hotplug event
+
+
+**Example Usage**:
+
+    # Enable the tracepoint
+    echo1 > /sys/kernel/debug/tracing/events/pci/pcie_link_event/enable
+
+    # Monitor events (the following output is generated when a device is hotplugged)
+    cat /sys/kernel/debug/tracing/trace_pipe
+       irq/51-pciehp-88      [001] .....   381.545386: pcie_link_event: 0000:00:02.0 type:4, reason:4, cur_bus_speed:20, max_bus_speed:23, width:1, flit_mode:0, status:DLLLA
-- 
2.39.3
Re: [External] : [PATCH v13 3/3] Documentation: tracing: Add documentation about PCI tracepoints
Posted by ALOK TIWARI 2 months ago 

On 10/25/2025 5:11 PM, Shuai Xue wrote:
> The PCI tracing system provides tracepoints to monitor critical hardware
> events that can impact system performance and reliability. Add
> documentation about it.
> 
> Reviewed-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
> Signed-off-by: Shuai Xue <xueshuai@linux.alibaba.com>
> ---
>   Documentation/trace/events-pci.rst | 74 ++++++++++++++++++++++++++++++
>   1 file changed, 74 insertions(+)
>   create mode 100644 Documentation/trace/events-pci.rst
> 
> diff --git a/Documentation/trace/events-pci.rst b/Documentation/trace/events-pci.rst
> new file mode 100644
> index 000000000000..88bd38fcc184
> --- /dev/null
> +++ b/Documentation/trace/events-pci.rst
> @@ -0,0 +1,74 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===========================
> +Subsystem Trace Points: PCI
> +===========================
> +
> +Overview
> +========
> +The PCI tracing system provides tracepoints to monitor critical hardware events
> +that can impact system performance and reliability. These events normally show
> +up here:
> +
> +	/sys/kernel/tracing/events/pci
> +
> +Cf. include/trace/events/pci.h for the events definitions.
> +
> +Available Tracepoints
> +=====================
> +
> +pci_hp_event
> +------------
> +
> +Monitors PCI hotplug events including card insertion/removal and link
> +state changes.
> +::
> +
> +    pci_hp_event  "%s slot:%s, event:%s\n"
> +
> +**Event Types**:
> +
> +* ``LINK_UP`` - PCIe link established
> +* ``LINK_DOWN`` - PCIe link lost
> +* ``CARD_PRESENT`` - Card detected in slot
> +* ``CARD_NOT_PRESENT`` - Card removed from slot
> +
> +**Example Usage**:
> +
> +    # Enable the tracepoint
> +    echo 1> /sys/kernel/debug/tracing/events/pci/pci_hp_event/enable

missing space echo 1 >"

> +
> +    # Monitor events (the following output is generated when a device is hotplugged)
> +    cat /sys/kernel/debug/tracing/trace_pipe
> +       irq/51-pciehp-88      [001] .....  1311.177459: pci_hp_event: 0000:00:02.0 slot:10, event:CARD_PRESENT
> +
> +       irq/51-pciehp-88      [001] .....  1311.177566: pci_hp_event: 0000:00:02.0 slot:10, event:LINK_UP
> +
> +pcie_link_event
> +---------------
> +
> +Monitors PCIe link speed changes and provides detailed link status information.
> +::
> +
> +    pcie_link_event  "%s type:%d, reason:%d, cur_bus_speed:%s, max_bus_speed:%s, width:%u, flit_mode:%u, status:%s\n"

%s -> %d mismatch for cur_bus_speed and max_bus_speed

TP_printk("%s type:%d, reason:%d, cur_bus_speed:%d, max_bus_speed:%d, 
width:%u, flit_mode:%u, status:%s\n",

> +
> +**Parameters**:
> +
> +* ``type`` - PCIe device type (4=Root Port, etc.)
> +* ``reason`` - Reason for link change:
> +
> +  - ``0`` - Link retrain
> +  - ``1`` - Bus enumeration
> +  - ``2`` - Bandwidth notification enable
> +  - ``3`` - Bandwidth notification IRQ
> +  - ``4`` - Hotplug event
> +
> +
> +**Example Usage**:
> +
> +    # Enable the tracepoint
> +    echo1 > /sys/kernel/debug/tracing/events/pci/pcie_link_event/enable
> +
> +    # Monitor events (the following output is generated when a device is hotplugged)
> +    cat /sys/kernel/debug/tracing/trace_pipe
> +       irq/51-pciehp-88      [001] .....   381.545386: pcie_link_event: 0000:00:02.0 type:4, reason:4, cur_bus_speed:20, max_bus_speed:23, width:1, flit_mode:0, status:DLLLA


Thanks,
Alok
Re: [External] : [PATCH v13 3/3] Documentation: tracing: Add documentation about PCI tracepoints
Posted by Shuai Xue 2 months ago 
Hi, Alok,

在 2025/12/9 21:59, ALOK TIWARI 写道:
> 
> 
> On 10/25/2025 5:11 PM, Shuai Xue wrote:
>> The PCI tracing system provides tracepoints to monitor critical hardware
>> events that can impact system performance and reliability. Add
>> documentation about it.
>>
>> Reviewed-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
>> Signed-off-by: Shuai Xue <xueshuai@linux.alibaba.com>
>> ---
>>   Documentation/trace/events-pci.rst | 74 ++++++++++++++++++++++++++++++
>>   1 file changed, 74 insertions(+)
>>   create mode 100644 Documentation/trace/events-pci.rst
>>
>> diff --git a/Documentation/trace/events-pci.rst b/Documentation/trace/events-pci.rst
>> new file mode 100644
>> index 000000000000..88bd38fcc184
>> --- /dev/null
>> +++ b/Documentation/trace/events-pci.rst
>> @@ -0,0 +1,74 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +===========================
>> +Subsystem Trace Points: PCI
>> +===========================
>> +
>> +Overview
>> +========
>> +The PCI tracing system provides tracepoints to monitor critical hardware events
>> +that can impact system performance and reliability. These events normally show
>> +up here:
>> +
>> +    /sys/kernel/tracing/events/pci
>> +
>> +Cf. include/trace/events/pci.h for the events definitions.
>> +
>> +Available Tracepoints
>> +=====================
>> +
>> +pci_hp_event
>> +------------
>> +
>> +Monitors PCI hotplug events including card insertion/removal and link
>> +state changes.
>> +::
>> +
>> +    pci_hp_event  "%s slot:%s, event:%s\n"
>> +
>> +**Event Types**:
>> +
>> +* ``LINK_UP`` - PCIe link established
>> +* ``LINK_DOWN`` - PCIe link lost
>> +* ``CARD_PRESENT`` - Card detected in slot
>> +* ``CARD_NOT_PRESENT`` - Card removed from slot
>> +
>> +**Example Usage**:
>> +
>> +    # Enable the tracepoint
>> +    echo 1> /sys/kernel/debug/tracing/events/pci/pci_hp_event/enable
> 
> missing space echo 1 >"

Good catch.

> 
>> +
>> +    # Monitor events (the following output is generated when a device is hotplugged)
>> +    cat /sys/kernel/debug/tracing/trace_pipe
>> +       irq/51-pciehp-88      [001] .....  1311.177459: pci_hp_event: 0000:00:02.0 slot:10, event:CARD_PRESENT
>> +
>> +       irq/51-pciehp-88      [001] .....  1311.177566: pci_hp_event: 0000:00:02.0 slot:10, event:LINK_UP
>> +
>> +pcie_link_event
>> +---------------
>> +
>> +Monitors PCIe link speed changes and provides detailed link status information.
>> +::
>> +
>> +    pcie_link_event  "%s type:%d, reason:%d, cur_bus_speed:%s, max_bus_speed:%s, width:%u, flit_mode:%u, status:%s\n"
> 
> %s -> %d mismatch for cur_bus_speed and max_bus_speed
> 
> TP_printk("%s type:%d, reason:%d, cur_bus_speed:%d, max_bus_speed:%d, width:%u, flit_mode:%u, status:%s\n",

Sorry for missing the format.

> 
>> +
>> +**Parameters**:
>> +
>> +* ``type`` - PCIe device type (4=Root Port, etc.)
>> +* ``reason`` - Reason for link change:
>> +
>> +  - ``0`` - Link retrain
>> +  - ``1`` - Bus enumeration
>> +  - ``2`` - Bandwidth notification enable
>> +  - ``3`` - Bandwidth notification IRQ
>> +  - ``4`` - Hotplug event
>> +
>> +
>> +**Example Usage**:
>> +
>> +    # Enable the tracepoint
>> +    echo1 > /sys/kernel/debug/tracing/events/pci/pcie_link_event/enable
>> +
>> +    # Monitor events (the following output is generated when a device is hotplugged)
>> +    cat /sys/kernel/debug/tracing/trace_pipe
>> +       irq/51-pciehp-88      [001] .....   381.545386: pcie_link_event: 0000:00:02.0 type:4, reason:4, cur_bus_speed:20, max_bus_speed:23, width:1, flit_mode:0, status:DLLLA
> 
> 
> Thanks,
> Alok

I will send a new version to fix above issues.

Thanks.
Shuai

Patchew 2.1-devel-b67e4c2

© 2016 - 2026 Red Hat, Inc.