From nobody Fri Dec 19 20:39:40 2025 Received: from out30-133.freemail.mail.aliyun.com (out30-133.freemail.mail.aliyun.com [115.124.30.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id F04692DE1E5; Tue, 14 Oct 2025 12:32:17 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=115.124.30.133 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1760445140; cv=none; b=HXoPhys9M1Wfwisu+QfPikVoGqIAeLBJ+ZO3oRjQKxr2Hzstw6kb/o4KU6kOVLrng4xdOLmo44UbD9uJxFhDMRYo7/xCxRsthYfkOH1CstcgBi9ZGlxXXkoODXstnxfw4p7ewt7dUblOYPfHm/ZhT6J0qvHjMmgGgxgTsMSJLm4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1760445140; c=relaxed/simple; bh=9EXTsoYyDwgMiHeCGZOgLZPwxQhj3FEEbMGS+YkcfII=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=U6OUr1WQ8p6tVq6hYIDo+TiSwWAO/k8JT6lMsVyEGTRldBhfDgW6fRXqVMCu0p4KvT29iJIqglQPIx4kqkgonrpIQwGc1CyRRni5ddHa7QF7XXDigPCwd0ZKWrC86Dup9M2I3TmTnToJvfevirTNKGcvjREOcMEb0x/gimdhWPA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.alibaba.com; spf=pass smtp.mailfrom=linux.alibaba.com; dkim=pass (1024-bit key) header.d=linux.alibaba.com header.i=@linux.alibaba.com header.b=j9aPN6SI; arc=none smtp.client-ip=115.124.30.133 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.alibaba.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=linux.alibaba.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=linux.alibaba.com header.i=@linux.alibaba.com header.b="j9aPN6SI" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linux.alibaba.com; s=default; t=1760445129; h=From:To:Subject:Date:Message-Id:MIME-Version; bh=wylYT/mZM3lnsRpRtwbAL9gIUgFK9qjAvr+0WK+Oh3U=; b=j9aPN6SIcr3YJfOC3z47jVQnIKz1ZxZXD/rSeANIyCuuM0rkO9527m6RHTQIRZlCrjQuyZf0aOtQN1RRXuuC30QHHrdhKPFMfwob/a2qdSpCzvED5wAFUdkolrsew6hoB0wXKZN1/LKO/3qiSfd5sfY8gGgHdsvtmM2z08lvdHk= Received: from localhost.localdomain(mailfrom:xueshuai@linux.alibaba.com fp:SMTPD_---0WqC6J4u_1760445126 cluster:ay36) by smtp.aliyun-inc.com; Tue, 14 Oct 2025 20:32:07 +0800 From: Shuai Xue To: rostedt@goodmis.org, lukas@wunner.de, linux-pci@vger.kernel.org, linux-kernel@vger.kernel.org, linux-edac@vger.kernel.org, linux-trace-kernel@vger.kernel.org, helgaas@kernel.org, ilpo.jarvinen@linux.intel.com, mattc@purestorage.com, Jonathan.Cameron@huawei.com Cc: bhelgaas@google.com, tony.luck@intel.com, bp@alien8.de, xueshuai@linux.alibaba.com, mhiramat@kernel.org, mathieu.desnoyers@efficios.com, oleg@redhat.com, naveen@kernel.org, davem@davemloft.net, anil.s.keshavamurthy@intel.com, mark.rutland@arm.com, peterz@infradead.org, tianruidong@linux.alibaba.com Subject: [PATCH v12 3/3] Documentation: tracing: Add documentation about PCI tracepoints Date: Tue, 14 Oct 2025 20:31:59 +0800 Message-Id: <20251014123159.57764-4-xueshuai@linux.alibaba.com> X-Mailer: git-send-email 2.39.5 (Apple Git-154) In-Reply-To: <20251014123159.57764-1-xueshuai@linux.alibaba.com> References: <20251014123159.57764-1-xueshuai@linux.alibaba.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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 --- 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/event= s-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 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D +Subsystem Trace Points: PCI +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D + +Overview +=3D=3D=3D=3D=3D=3D=3D=3D +The PCI tracing system provides tracepoints to monitor critical hardware e= vents +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 h= otplugged) + 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 informa= tion. +:: + + pcie_link_event "%s type:%d, reason:%d, cur_bus_speed:%s, max_bus_spe= ed:%s, width:%u, flit_mode:%u, status:%s\n" + +**Parameters**: + +* ``type`` - PCIe device type (4=3DRoot Port, etc.) +* ``reason`` - Reason for link change: + + - ``0`` - Link retrain + - ``1`` - Bus enumeration + - ``2`` - Bandwidth controller enable + - ``3`` - Bandwidth controller 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 h= otplugged) + cat /sys/kernel/debug/tracing/trace_pipe + irq/51-pciehp-88 [001] ..... 381.545386: pcie_link_event: 00= 00: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 --=20 2.39.3