[PATCH net-next v1 1/1] Documentation: networking: expand and clarify EEE_GET/EEE_SET documentation

[PATCH net-next v1 1/1] Documentation: networking: expand and clarify EEE_GET/EEE_SET documentation

[Oleksij Rempel]

Improve the documentation for ETHTOOL_MSG_EEE_GET and ETHTOOL_MSG_EEE_SET
to provide accurate descriptions of all netlink attributes involved.

Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
---
 Documentation/networking/ethtool-netlink.rst | 103 ++++++++++++++++---
 1 file changed, 90 insertions(+), 13 deletions(-)

diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst
index b6e9af4d0f1b..dfbdd99a7228 100644
--- a/Documentation/networking/ethtool-netlink.rst
+++ b/Documentation/networking/ethtool-netlink.rst
@@ -1215,20 +1215,65 @@ Kernel response contents:
 
   =====================================  ======  ==========================
   ``ETHTOOL_A_EEE_HEADER``               nested  request header
-  ``ETHTOOL_A_EEE_MODES_OURS``           bool    supported/advertised modes
-  ``ETHTOOL_A_EEE_MODES_PEER``           bool    peer advertised link modes
+  ``ETHTOOL_A_EEE_MODES_OURS``           bitset  supported/advertised modes
+  ``ETHTOOL_A_EEE_MODES_PEER``           bitset  peer advertised link modes
   ``ETHTOOL_A_EEE_ACTIVE``               bool    EEE is actively used
   ``ETHTOOL_A_EEE_ENABLED``              bool    EEE is enabled
   ``ETHTOOL_A_EEE_TX_LPI_ENABLED``       bool    Tx lpi enabled
   ``ETHTOOL_A_EEE_TX_LPI_TIMER``         u32     Tx lpi timeout (in us)
   =====================================  ======  ==========================
 
-In ``ETHTOOL_A_EEE_MODES_OURS``, mask consists of link modes for which EEE is
-enabled, value of link modes for which EEE is advertised. Link modes for which
-peer advertises EEE are listed in ``ETHTOOL_A_EEE_MODES_PEER`` (no mask). The
-netlink interface allows reporting EEE status for all link modes but only
-first 32 are provided by the ``ethtool_ops`` callback.
+Detailed behavior:
 
+``ETHTOOL_A_EEE_MODES_OURS`` is a bitset consisting of:
+
+ - Value: link modes that the driver intends to advertise for EEE.
+ - Mask: subset of link modes supported for EEE by the interface.
+
+The `advertised` value is stored in software and remains even if EEE is
+disabled. It can be modified independently and is preserved across toggles of
+EEE enable/disable. If ``ETHTOOL_A_EEE_ENABLED`` is false, PHY does not
+advertise EEE, but the configured value is reported.
+
+``ETHTOOL_A_EEE_MODES_PEER`` shows the peer's EEE capabilities. It is a bitset
+consisting of:
+
+ - Value: link modes that the link partner advertises for EEE.
+ - Mask: empty
+
+This value is typically reported by the hardware and may represent only a
+subset of the actual capabilities supported and advertised by the link partner.
+The local hardware may not be able to detect or represent all EEE-capable modes
+of the peer. As a result, the true EEE support on the peer side may exceed what
+is reported.
+
+``ETHTOOL_A_EEE_ACTIVE`` indicates whether EEE is currently active on the link.
+This is determined by the kernel as a combination of the currently active link
+mode, locally advertised EEE modes, and peer-advertised EEE modes:
+
+    active = (current_link_mode & advertised & link_partner)
+
+In practice, the evaluation may also depend on whether the MAC supports EEE for
+the given mode. There is mostly no hardware status bit that directly indicates
+an active EEE state. Furthermore, even if ``ETHTOOL_A_EEE_ACTIVE`` is true,
+other settings such as ``ETHTOOL_A_EEE_TX_LPI_ENABLED`` or an excessively high
+``ETHTOOL_A_EEE_TX_LPI_TIMER`` may prevent the MAC from actually entering the
+LPI state. Thus, the "active" status should be interpreted as a potential
+capability, not as a guaranteed indication of LPI activity. The only strict
+rule is that if ``ETHTOOL_A_EEE_ENABLED`` is false, then
+``ETHTOOL_A_EEE_ACTIVE`` must also be false.
+
+``ETHTOOL_A_EEE_ENABLED`` is a software-only switch that controls if the
+advertisement is programmed into hardware.
+
+``ETHTOOL_A_EEE_TX_LPI_TIMER`` defines the delay in microseconds after the last
+transmitted frame before the MAC enters the Low Power Idle (LPI) state. This
+value applies globally to all link modes, though in practice, optimal values
+may differ between modes.
+
+The netlink interface can represent link modes up to
+``__ETHTOOL_LINK_MODE_MASK_NBITS``, but traditional ioctls only support the
+first 32.
 
 EEE_SET
 =======
@@ -1239,18 +1284,50 @@ Request contents:
 
   =====================================  ======  ==========================
   ``ETHTOOL_A_EEE_HEADER``               nested  request header
-  ``ETHTOOL_A_EEE_MODES_OURS``           bool    advertised modes
+  ``ETHTOOL_A_EEE_MODES_OURS``           bitset  advertised modes
   ``ETHTOOL_A_EEE_ENABLED``              bool    EEE is enabled
   ``ETHTOOL_A_EEE_TX_LPI_ENABLED``       bool    Tx lpi enabled
   ``ETHTOOL_A_EEE_TX_LPI_TIMER``         u32     Tx lpi timeout (in us)
   =====================================  ======  ==========================
 
-``ETHTOOL_A_EEE_MODES_OURS`` is used to either list link modes to advertise
-EEE for (if there is no mask) or specify changes to the list (if there is
-a mask). The netlink interface allows reporting EEE status for all link modes
-but only first 32 can be set at the moment as that is what the ``ethtool_ops``
-callback supports.
+Detailed behavior:
+
+``ETHTOOL_A_EEE_MODES_OURS`` can specify the list of advertised link modes.
+
+``ETHTOOL_A_EEE_ENABLED`` is a software flag that tells the kernel to prepare
+EEE functionality. If autonegotiation is enabled, this means writing the EEE
+advertisement register so that the PHY includes the EEE-capable modes in the
+autonegotiation pages it transmits. The actual advertisement set is a subset
+derived from PHY-supported modes, MAC capabilities, and possible blacklists.
+This subset can be further restricted by ``ETHTOOL_A_EEE_MODES_OURS``. If
+autonegotiation is disabled, EEE advertisement is not transmitted and EEE will
+not be negotiated or used.
+
+``ETHTOOL_A_EEE_TX_LPI_ENABLED`` controls whether the system should enter the
+Low Power Idle (LPI) state. In this state, the MAC typically notifies the PHY,
+which then transitions the medium (e.g., twisted pair) side into LPI. The exact
+behavior depends on the active link mode:
+
+ - In **100BaseT/Full**, an asymmetric LPI configuration (local off, peer on)
+   leads to asymmetric behavior: the local TX line remains active, while the RX
+   line may enter LPI.
+ - In **1000BaseT/Full**, there are no separate TX/RX lines; the wire is silent
+   only if both sides enter the LPI state.
+
+- ``ETHTOOL_A_EEE_TX_LPI_TIMER`` configures the delay after the last
+  transmitted frame before the MAC enters the LPI state. This single timer
+  value applies to all link modes, although using the same value for all modes
+  may not be optimal in practice. A value that is too high may effectively
+  prevent entry into the LPI state.
+
+.. note::
+   For EEE advertisement to take effect, PHY autonegotiation must be enabled.
+
+Limitations:
 
+The netlink interface allows configuring all link modes up to
+``__ETHTOOL_LINK_MODE_MASK_NBITS``, but if drivers depend on legacy
+``ethtool_ops``, only the first 32 link modes are supported.
 
 TSINFO_GET
 ==========
-- 
2.39.5

Re: [PATCH net-next v1 1/1] Documentation: networking: expand and clarify EEE_GET/EEE_SET documentation

[Russell King (Oracle)]

On Fri, Apr 25, 2025 at 10:49:41AM +0200, Oleksij Rempel wrote:
> +``ETHTOOL_A_EEE_ACTIVE`` indicates whether EEE is currently active on the link.
> +This is determined by the kernel as a combination of the currently active link
> +mode, locally advertised EEE modes, and peer-advertised EEE modes:
> +
> +    active = (current_link_mode & advertised & link_partner)

... and EEE is enabled.

EEE active is more "EEE is enabled and has been successfully negotiated
at the current link speed", rather than "the link is in LPI state"
which I think some people have thought it meant in the past. I'm also
wondering whether this should also include "and autonegotiation via
ETHTOOL_SLINKSETTINGS is enabled" as that is necessary to allow the
PHY to exchange autoneg pages which include the EEE page.

> +Detailed behavior:
> +
> +``ETHTOOL_A_EEE_MODES_OURS`` can specify the list of advertised link modes.
> +
> +``ETHTOOL_A_EEE_ENABLED`` is a software flag that tells the kernel to prepare
> +EEE functionality. If autonegotiation is enabled, this means writing the EEE
> +advertisement register so that the PHY includes the EEE-capable modes in the
> +autonegotiation pages it transmits. The actual advertisement set is a subset
> +derived from PHY-supported modes, MAC capabilities, and possible blacklists.
> +This subset can be further restricted by ``ETHTOOL_A_EEE_MODES_OURS``. If
> +autonegotiation is disabled, EEE advertisement is not transmitted and EEE will
> +not be negotiated or used.

Maybe similar here.

> +
> +``ETHTOOL_A_EEE_TX_LPI_ENABLED`` controls whether the system should enter the
> +Low Power Idle (LPI) state. In this state, the MAC typically notifies the PHY,
> +which then transitions the medium (e.g., twisted pair) side into LPI. The exact
> +behavior depends on the active link mode:
> +
> + - In **100BaseT/Full**, an asymmetric LPI configuration (local off, peer on)
> +   leads to asymmetric behavior: the local TX line remains active, while the RX
> +   line may enter LPI.
> + - In **1000BaseT/Full**, there are no separate TX/RX lines; the wire is silent
> +   only if both sides enter the LPI state.

I'm not sure this belongs in the API documentation, as (1) this is part
of the hardware specification and (2) it brings up "what about faster
link modes" which do support EEE as well.

If they're going to be looking at whether the physical signals are
entering low power mode, they're going to have hardware to probe the
signals, thus they've probably got hardware experience and thus would
surely refer to the documentation to work out what's supposed to be
happening, and probably wouldn't look at API documentation.

> +
> +- ``ETHTOOL_A_EEE_TX_LPI_TIMER`` configures the delay after the last
> +  transmitted frame before the MAC enters the LPI state. This single timer
> +  value applies to all link modes, although using the same value for all modes
> +  may not be optimal in practice. A value that is too high may effectively
> +  prevent entry into the LPI state.

As an interesting side note, stmmac defaults to one second, and it
doesn't prevent LPI entry.

Having a high value might be what an application wants - EEE introduces
additional latency to an ethernet link, and one may wish LPI mode to be
entered when e.g. a machine in a data centre has all users migrated off
it, thus allowing the ethernet connection to it to fall silent.
Otherwise one may wish the link to stay out of LPI mode, so choosing a
high LPI timer would suit that.

So, this is policy. I'm not sure statements about that should be in an
API specification. I'm also thinking that surely one would understand
that if one sets this to 1 second, then there needs to be no traffic
for 1 second before the link enters LPI state.

Finally, I'm wondering about the duplication of documentation between
this document and include/uapi/linux/ethtool.h. The struct definitions
are documented in the header file, and it seems we're describing the
same thing in two different places which means there's a possibility
for things to be described differently thus creating confusion. I
think we should have only one description and reference it from
other places.

-- 
RMK's Patch system: https://www.armlinux.org.uk/developer/patches/
FTTP is here! 80Mbps down 10Mbps up. Decent connectivity at last!