Message-ID: <aAtU45S6HChgb0_V@shell.armlinux.org.uk>
Date: Fri, 25 Apr 2025 10:24:51 +0100
From: "Russell King (Oracle)" <linux@...linux.org.uk>
To: Oleksij Rempel <o.rempel@...gutronix.de>
Cc: 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>,
	Jonathan Corbet <corbet@....net>, 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: Re: [PATCH net-next v1 1/1] Documentation: networking: expand and
 clarify EEE_GET/EEE_SET documentation

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!

Powered by blists - more mailing lists