Message-Id: <20250425084941.253961-1-o.rempel@pengutronix.de>
Date: Fri, 25 Apr 2025 10:49:41 +0200
From: Oleksij Rempel <o.rempel@...gutronix.de>
To: Woojung Huh <woojung.huh@...rochip.com>,
	Andrew Lunn <andrew@...n.ch>,
	"David S. Miller" <davem@...emloft.net>,
	Eric Dumazet <edumazet@...gle.com>,
	Jakub Kicinski <kuba@...nel.org>,
	Paolo Abeni <pabeni@...hat.com>,
	Heiner Kallweit <hkallweit1@...il.com>,
	Russell King <linux@...linux.org.uk>,
	Jonathan Corbet <corbet@....net>
Cc: Oleksij Rempel <o.rempel@...gutronix.de>,
	kernel@...gutronix.de,
	linux-kernel@...r.kernel.org,
	netdev@...r.kernel.org,
	UNGLinuxDriver@...rochip.com,
	Simon Horman <horms@...nel.org>,
	Maxime Chevallier <maxime.chevallier@...tlin.com>,
	linux-doc@...r.kernel.org
Subject: [PATCH net-next v1 1/1] Documentation: networking: expand and clarify EEE_GET/EEE_SET documentation

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@...gutronix.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

Powered by blists - more mailing lists