linux-kernel - Re: [PATCH v12 3/3] Documentation: tracing: Add documentation about PCI tracepoints

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <cf4d3079-2d1b-dfa4-aa5f-e018962131bd@linux.intel.com>
Date: Tue, 14 Oct 2025 17:40:56 +0300 (EEST)
From: Ilpo Järvinen <ilpo.jarvinen@...ux.intel.com>
To: Shuai Xue <xueshuai@...ux.alibaba.com>
cc: rostedt@...dmis.org, Lukas Wunner <lukas@...ner.de>, 
    linux-pci@...r.kernel.org, LKML <linux-kernel@...r.kernel.org>, 
    linux-edac@...r.kernel.org, linux-trace-kernel@...r.kernel.org, 
    helgaas@...nel.org, mattc@...estorage.com, Jonathan.Cameron@...wei.com, 
    bhelgaas@...gle.com, tony.luck@...el.com, bp@...en8.de, 
    mhiramat@...nel.org, mathieu.desnoyers@...icios.com, oleg@...hat.com, 
    naveen@...nel.org, davem@...emloft.net, anil.s.keshavamurthy@...el.com, 
    mark.rutland@....com, peterz@...radead.org, tianruidong@...ux.alibaba.com
Subject: Re: [PATCH v12 3/3] Documentation: tracing: Add documentation about
 PCI tracepoints

On Tue, 14 Oct 2025, 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.
> 
> Signed-off-by: Shuai Xue <xueshuai@...ux.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..500b27713224
> --- /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 controller enable
> +  - ``3`` - Bandwidth controller IRQ

Maybe these two should be called "Bandwidth notification" as that's the 
name of the underlying mechanism.

For the entire series,

Reviewed-by: Ilpo Järvinen <ilpo.jarvinen@...ux.intel.com>

> +  - ``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:2.5 GT/s PCIe, max_bus_speed:16.0 GT/s PCIe, width:1, flit_mode:0, status:DLLLA
> 

-- 
 i.