[PATCH v3] PCI/sysfs: document the link speed and width attributes

max_link_speed, max_link_width, current_link_speed and current_link_width
have been exported under /sys/bus/pci/devices/.../ since 2018, by
commit 56c1af4606f0 ("PCI: Add sysfs max_link_speed/width, current_link_speed/width, etc"),
and none of the four appear anywhere in Documentation/ABI.

The gap matters most for current_link_speed. current_link_speed_show()
performs a fresh PCI_EXP_LNKSTA read on every open, so the value reflects
the link state at that instant. Modern GPUs retrain their link continuously
as part of idle power management, which means a single read can legitimately
return any speed the link supports, not the speed the link will use under
load.

Observed on an RTX 5070 in a PCIe 4.0 x16 slot, same boot, no configuration
change between the two reads: 5.0 GT/s while idle, 16.0 GT/s under load.
Comparing current_link_speed against max_link_speed at idle is therefore not
a valid test for a degraded link, though it reads like one.

Document all four. For the max_* pair, state that each reports the
capability of the device it is read from and not a property of the link: a
link trains at the lower of what its two ends support, so an endpoint
capable of more than the port above it reports the higher figure while that
port reports the lower one. Record where each value comes from, which
differs between the two attributes. max_link_speed is derived from the
Supported Link Speeds Vector in Link Capabilities 2, capped by Max Link
Speed in Link Capabilities, and cached at enumeration. max_link_width is
read from
Maximum Link Width in Link Capabilities on each access.

For current_link_speed, state that it is instantaneous, that comparing it
against max_link_speed at idle is not a valid degradation test, and that
callers wanting what the link will actually deliver should sample under
load -- noting that max_link_speed is not that figure either, being one
end's capability rather than the link's, and that the speed may also be
capped by Target Link Speed in Link Control 2 under bwctrl's control.

No functional change.

Assisted-by: Claude:claude-opus-5 checkpatch patch-audit
Signed-off-by: Ferran Duarri <redacted>
---
Changes in v3, all from Ilpo's review of v2:

 - max_link_speed: drop the "synthesized from Max Link Speed alone on
   pre-r3.0 devices" sentence. It was unnecessary detail and imprecise:
   what pcie_get_supported_speeds() synthesizes there is a SET of
   supported speeds, and max_link_speed_show() reports only the maximum
   of that set, which on a sane device equals Max Link Speed anyway.
 - current_link_speed: note that the speed may also be capped by Target
   Link Speed in Link Control 2, managed by the PCIe bandwidth controller
   (bwctrl), and that a link held there is configured, not degraded.
 - Add the Assisted-by: tag. v1 and v2 were written with an AI coding
   assistant and neither said so, which Documentation/process/coding-
   assistants.rst requires. Thanks for catching it. The content is
   unchanged from v2; this exists to carry the tag and to be the single
   v2 replacement, since v2 went out twice by my mistake.

Changes in v2, all corrections to what v1 claimed rather than new material:

 - max_link_speed: v1 called it "the ceiling the link may negotiate, which
   is the lower of what the two ends of the link support". That is wrong,
   and v1 contradicted it one sentence later. max_link_speed_show() calls
   pcie_get_speed_cap(), which returns the capability of the device being
   read and never consults the other end of the link.
 - max_link_speed: v1 said the value is read from the Max Link Speed field
   of Link Capabilities. pcie_get_supported_speeds() derives it from the
   Supported Link Speeds Vector in Link Capabilities 2, masks it against
   Max Link Speed, and synthesizes from Max Link Speed alone only on
   devices predating PCIe r3.0.
 - max_link_speed: v1 did not say the value is read once at enumeration and
   cached in pci_dev->supported_speeds. Since the current_link_speed entry
   states that nothing is cached there, a reader could reasonably infer the
   same of max_link_speed. It does not hold.
 - current_link_speed: v1 advised callers wanting the ceiling to use
   max_link_speed. That overestimates whenever the upstream port is the
   slower end. v2 says to sample under load and warns that max_link_speed
   is one end's capability, not the link's.
 - max_link_width: register attribution was correct and is unchanged in
   substance, reworded only for the same device-versus-link distinction.
 - Dropped a private Forward-Port-Notes: trailer that should not have been
   in the commit message.

 Documentation/ABI/testing/sysfs-bus-pci | 78 +++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci
index b767db2c52cb..ee1846f3dafa 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci
+++ b/Documentation/ABI/testing/sysfs-bus-pci

@@ -174,6 +174,84 @@ Description:
 		similiar to writing 1 to their individual "reset" file, so use
 		with caution.
 
+What:		/sys/bus/pci/devices/.../max_link_speed
+Date:		September 2018
+Contact:	linux-pci@vger.kernel.org
+Description:
+		The maximum link speed this device is capable of, as a
+		human-readable string such as "16.0 GT/s PCIe".
+
+		Derived from the Supported Link Speeds Vector in the device's
+		Link Capabilities 2 register, capped by the Max Link Speed
+		field in Link Capabilities. Read once during enumeration and
+		cached thereafter, so unlike current_link_speed it does not
+		change between reads.
+
+		This is the device's own capability, not a property of the
+		link. A link trains at the lower of what its two ends support,
+		so an endpoint capable of a higher speed than the port above it
+		reports that higher speed here while the port reports the lower
+		one. Reading one end therefore does not tell you what the link
+		will do; read both ends and take the lower.
+
+		Present only for PCI Express devices.
+
+What:		/sys/bus/pci/devices/.../max_link_width
+Date:		September 2018
+Contact:	linux-pci@vger.kernel.org
+Description:
+		The maximum link width this device is capable of, in lanes,
+		e.g. "16". Read from the Maximum Link Width field of the
+		device's Link Capabilities register.
+
+		As with max_link_speed this is the device's own capability, not
+		a property of the link; a link trains at the lower of what its
+		two ends support.
+
+		Present only for PCI Express devices.
+
+What:		/sys/bus/pci/devices/.../current_link_speed
+Date:		September 2018
+Contact:	linux-pci@vger.kernel.org
+Description:
+		The speed the link is operating at right now, as a
+		human-readable string such as "16.0 GT/s PCIe". Read fresh from
+		the device's Link Status register on every read of this file;
+		nothing is cached.
+
+		This value is instantaneous and may change at any time. A link
+		is permitted to retrain to a lower speed and back, and devices
+		with aggressive link power management (GPUs in particular) do so
+		routinely while idle. Two reads seconds apart, with no
+		configuration change in between, can legitimately differ by
+		several generations.
+
+		Consequently, comparing this attribute against max_link_speed is
+		not by itself a test for a degraded link: an idle device will
+		frequently report a lower speed and is working correctly.
+		Callers that need a figure representing what the link will
+		actually deliver should sample while the device is under load.
+		max_link_speed is not that figure either: it reports one end's
+		capability, and the link is limited by the lower of its two
+		ends.
+
+		The speed may also be capped below both ends' capability by
+		the Target Link Speed field in Link Control 2, which the PCIe
+		bandwidth controller (bwctrl) manages. A link held there is
+		operating as configured, not degraded.
+
+		Present only for PCI Express devices.
+
+What:		/sys/bus/pci/devices/.../current_link_width
+Date:		September 2018
+Contact:	linux-pci@vger.kernel.org
+Description:
+		The width the link is operating at right now, in lanes, e.g.
+		"16". Read fresh from the device's Link Status register on every
+		read of this file.
+
+		As with current_link_speed, this is instantaneous. Links may
+		also narrow and re-widen under link power management.
+
+		Present only for PCI Express devices.
+
 What:		/sys/bus/pci/devices/.../vpd
 Date:		February 2008
 Contact:	Ben Hutchings <bwh@kernel.org>

-- 
2.53.0