* Re: [PATCH] PCI/sysfs: document the link speed and width attributes
2026-08-20 18:42 [PATCH] PCI/sysfs: document the link speed and width attributes Ferran Duarri
@ 2026-08-20 18:50 ` sashiko-bot
2026-08-20 19:53 ` [PATCH v2] " Ferran Duarri
2026-08-20 20:03 ` Ferran Duarri
2 siblings, 0 replies; 6+ messages in thread
From: sashiko-bot @ 2026-08-20 18:50 UTC (permalink / raw)
To: Ferran Duarri; +Cc: linux-pci
Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Medium] The added documentation incorrectly describes `max_link_speed` and `max_link_width` as the negotiated link ceiling (the minimum of what both ends support), which contradicts the underlying implementation. The `max_link_speed_show()` and `max_link_width_show()` sysfs callbacks return the device's own capabilities, not the negotiated link ceiling. The documentation for `max_link_speed` contradicts its own first sentence by subsequently acknowledging the endpoint will report its own higher speed. Furthermore, the `current_link_speed` documentation incorrectly advises users to "use max_link_speed if what they want is the ceiling" of what the link will actually deliver, which can lead user-space tools to overestimate the link capacity if the upstream port is slower. Lastly, the claim that the speed is "Read from the Max Link Speed field of the device's Link Capabilities register" is outdated; since PCIe r3.0, the kernel determines this primarily via the Supported Link Speeds Vector in the Link Capabilities 2 Register (PCI_EXP_LNKCAP2).
--
--- Patch [1]: [PATCH] PCI/sysfs: document the link speed and width attributes ---
commit 24d4206c0d1e19c29d8e3f471fd2f8be01ffaa11
Author: Ferran Duarri <ferran.duarri@me.com>
PCI/sysfs: document the link speed and width attributes
This commit documents the max_link_speed, max_link_width, current_link_speed,
and current_link_width sysfs attributes. It clarifies that current link
attributes represent instantaneous values and should be sampled under load.
> diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci
> index b767db2c52cb7..ad18bd634ee6a 100644
> --- a/Documentation/ABI/testing/sysfs-bus-pci
> +++ b/Documentation/ABI/testing/sysfs-bus-pci
> @@ -174,6 +174,71 @@ 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's link can operate at, as a
> + human-readable string such as "16.0 GT/s PCIe". Read from the
> + Max Link Speed field of the device's Link Capabilities register.
[Severity: Medium]
Is the claim that this is read from the Max Link Speed field of the Link
Capabilities register fully accurate?
Since PCIe r3.0, the kernel primarily determines this capability via the
Supported Link Speeds Vector in the Link Capabilities 2 Register
(PCI_EXP_LNKCAP2).
> +
> + This is the ceiling the link may negotiate, which is the lower
> + of what the two ends of the link support. An endpoint capable of
> + a higher speed than the port above it will report that higher
> + speed here while the port above it reports the lower one, and
> + the link will train at the lower of the two. To reason about a
> + link, read this attribute on both ends.
[Severity: Medium]
Does this description contradict itself and the sysfs implementation?
The documentation states this is the "ceiling the link may negotiate, which is
the lower of what the two ends of the link support", but then acknowledges the
endpoint will report its own higher capability.
Because the max_link_speed_show() and max_link_width_show() sysfs callbacks
return the device's own capabilities rather than the negotiated link ceiling,
calling it the "ceiling the link may negotiate" could cause user-space tools
to overestimate link capacities.
[ ... ]
> +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,
> + or use max_link_speed if what they want is the ceiling.
[Severity: Medium]
Is it correct to advise users to use max_link_speed if they want the link's
functional ceiling?
If the upstream port is slower than the device, relying on the device's
max_link_speed will overestimate what the link will actually deliver. This
could lead user-space tools to incorrectly evaluate the available capacity.
--
Sashiko AI review · https://sashiko.dev/#/patchset/20260820184228.166566-1-ferran.duarri@me.com?part=1
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH v2] PCI/sysfs: document the link speed and width attributes
2026-08-20 18:42 [PATCH] PCI/sysfs: document the link speed and width attributes Ferran Duarri
2026-08-20 18:50 ` sashiko-bot
@ 2026-08-20 19:53 ` Ferran Duarri
2026-08-20 19:56 ` sashiko-bot
2026-08-20 20:03 ` Ferran Duarri
2 siblings, 1 reply; 6+ messages in thread
From: Ferran Duarri @ 2026-08-20 19:53 UTC (permalink / raw)
To: Bjorn Helgaas; +Cc: linux-pci, linux-api, linux-kernel, Ferran Duarri
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 <ferran.duarri@me.com>
---
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. Devices predating PCIe r3.0 have no
+ Link Capabilities 2, and for those the value is synthesized
+ from Max Link Speed alone. 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.
+
+ 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
^ permalink raw reply related [flat|nested] 6+ messages in thread* Re: [PATCH v2] PCI/sysfs: document the link speed and width attributes
2026-08-20 19:53 ` [PATCH v2] " Ferran Duarri
@ 2026-08-20 19:56 ` sashiko-bot
0 siblings, 0 replies; 6+ messages in thread
From: sashiko-bot @ 2026-08-20 19:56 UTC (permalink / raw)
To: Ferran Duarri; +Cc: linux-pci
> 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
> [ ... ]
> end's capability rather than the link's.
>
> No functional change.
>
> Signed-off-by: Ferran Duarri <ferran.duarri@me.com>
Sashiko has reviewed this patch and found no issues. It looks great!
--
Sashiko AI review · https://sashiko.dev/#/patchset/20260820195334.275375-1-ferran.duarri@me.com?part=1
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH v2] PCI/sysfs: document the link speed and width attributes
2026-08-20 18:42 [PATCH] PCI/sysfs: document the link speed and width attributes Ferran Duarri
2026-08-20 18:50 ` sashiko-bot
2026-08-20 19:53 ` [PATCH v2] " Ferran Duarri
@ 2026-08-20 20:03 ` Ferran Duarri
2026-08-20 20:06 ` sashiko-bot
2 siblings, 1 reply; 6+ messages in thread
From: Ferran Duarri @ 2026-08-20 20:03 UTC (permalink / raw)
To: Bjorn Helgaas; +Cc: linux-pci, linux-api, linux-kernel, Ferran Duarri
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 <ferran.duarri@me.com>
---
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. Devices predating PCIe r3.0 have no
+ Link Capabilities 2, and for those the value is synthesized
+ from Max Link Speed alone. 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.
+
+ 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
^ permalink raw reply related [flat|nested] 6+ messages in thread* Re: [PATCH v2] PCI/sysfs: document the link speed and width attributes
2026-08-20 20:03 ` Ferran Duarri
@ 2026-08-20 20:06 ` sashiko-bot
0 siblings, 0 replies; 6+ messages in thread
From: sashiko-bot @ 2026-08-20 20:06 UTC (permalink / raw)
To: Ferran Duarri; +Cc: linux-pci
> 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
> [ ... ]
> end's capability rather than the link's.
>
> No functional change.
>
> Signed-off-by: Ferran Duarri <ferran.duarri@me.com>
Sashiko has reviewed this patch and found no issues. It looks great!
--
Sashiko AI review · https://sashiko.dev/#/patchset/20260820200359.283335-1-ferran.duarri@me.com?part=1
^ permalink raw reply [flat|nested] 6+ messages in thread