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

On Thu, Aug 20, 2026 at 10:03:53PM +0200, Ferran Duarri wrote:

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, synthesized from the latter alone on devices
predating PCIe r3.0, 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.

No functional change.

Signed-off-by: Ferran Duarri <redacted>

Did you forget the Assisted-by: tag?

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

You sent 2 v2 patches :(