Message-ID: <aSa8Gkl1AP1U2C9j@pengutronix.de>
Date: Wed, 26 Nov 2025 09:36:42 +0100
From: Oleksij Rempel <o.rempel@...gutronix.de>
To: Jakub Kicinski <kuba@...nel.org>
Cc: Andrew Lunn <andrew@...n.ch>, Vladimir Oltean <vladimir.oltean@....com>,
	Alexei Starovoitov <ast@...nel.org>,
	Russell King <linux@...linux.org.uk>,
	Eric Dumazet <edumazet@...gle.com>, Rob Herring <robh@...nel.org>,
	Florian Fainelli <f.fainelli@...il.com>,
	Donald Hunter <donald.hunter@...il.com>,
	Daniel Borkmann <daniel@...earbox.net>,
	Jonathan Corbet <corbet@....net>,
	John Fastabend <john.fastabend@...il.com>,
	Lukasz Majewski <lukma@...x.de>,
	Maxime Chevallier <maxime.chevallier@...tlin.com>,
	Stanislav Fomichev <sdf@...ichev.me>,
	Paolo Abeni <pabeni@...hat.com>, Jiri Pirko <jiri@...nulli.us>,
	Jesper Dangaard Brouer <hawk@...nel.org>,
	Divya.Koppera@...rochip.com,
	Kory Maincent <kory.maincent@...tlin.com>,
	Vadim Fedorenko <vadim.fedorenko@...ux.dev>, netdev@...r.kernel.org,
	Sabrina Dubroca <sd@...asysnail.net>, linux-kernel@...r.kernel.org,
	kernel@...gutronix.de, Krzysztof Kozlowski <krzk+dt@...nel.org>,
	"David S. Miller" <davem@...emloft.net>,
	Heiner Kallweit <hkallweit1@...il.com>
Subject: Re: [PATCH net-next v8 1/1] Documentation: net: add flow control
 guide and document ethtool API

On Tue, Nov 25, 2025 at 06:19:57PM -0800, Jakub Kicinski wrote:
> On Wed, 19 Nov 2025 15:03:17 +0100 Oleksij Rempel wrote:
> > +Kernel Policy: "Set and Trust"
> > +==============================
> > +
> > +The ethtool pause API is defined as a **wish policy** for
> > +IEEE 802.3 link-wide PAUSE only. User requests express the preferred
> > +configuration, but drivers may reject unsupported combinations and it
> > +may not be possible to apply a request in all link states.
> > +
> > +Key constraints:
> > +
> > +- Link-wide PAUSE is not valid on half-duplex links.
> > +- Link-wide PAUSE cannot be used together with Priority-based Flow Control
> > +  (PFC, IEEE 802.1Q Clause 36).
> > +- Drivers may require generic link autonegotiation to be enabled before
> > +  allowing Pause Autonegotiation to be enabled.
> > +
> > +Because of these constraints, the configuration applied to the MAC
> > +may differ from the user request depending on the active link mode.
> > +
> > +Implications for userspace:
> > +
> > +1. Set once (the "wish"): the requested Rx/Tx PAUSE policy is
> > +   remembered even if it cannot be applied immediately.
> > +2. Applied conditionally: when the link comes up, the kernel enables
> > +   PAUSE only if the active mode allows it.
> 
> This section is quite confusing. Documenting the constrains make sense
> but it seems like this mostly applies to autoneg on. Without really
> saying so. Plus the get behavior.. see below..
> 
> > + * @get_pauseparam: Report the configured policy for link-wide PAUSE
> > + *      (IEEE 802.3 Annex 31B). Drivers must fill struct ethtool_pauseparam
> > + *      such that:
> > + *      @autoneg:
> > + *              This refers to **Pause Autoneg** (IEEE 802.3 Annex 31B) only
> > + *              and is part of the link autonegotiation process.
> > + *              true  -> the device follows the negotiated result of pause
> > + *                       autonegotiation (Pause/Asym);
> > + *              false -> the device uses a forced MAC state independent of
> > + *                       negotiation.
> > + *      @rx_pause/@...pause:
> > + *              represent the desired policy (preferred configuration).
> > + *              In autoneg mode they describe what is to be advertised;
> > + *              in forced mode they describe the MAC state to apply.
> 
> How is the user supposed to know what ended up getting configured?

My current understanding is that get_pauseparam() is mainly a
configuration API. It seems to be designed symmetric to
set_pauseparam(): it reports the requested policy (autoneg flag and
rx/tx pause), not the resolved MAC state.

In autoneg mode this means the user sees what we intend to advertise
or force, but not necessarily what the MAC actually ended up with
after resolution.

The ethtool userspace tool tries to fill this gap by showing
"RX negotiated" and "TX negotiated" fields, for example:

  Pause parameters for lan1:
    Autonegotiate:  on
    RX:             off
    TX:             off
    RX negotiated:  on
    TX negotiated:  on

As far as I can see, these "negotiated" values are not read from hardware or
kernel. They are guessed in userspace from the local and link partner
advertisements, assuming that the kernel follows the same pause resolution
rules as ethtool does. If the kernel or hardware behaves differently, these
values can be wrong.

So, with the current API, the user gets:
- the configured policy via get_pauseparam(), and
- an ethtool-side guess of the resolved state via
  "RX negotiated"/"TX negotiated",

> Why do we need to configure autoneg via this API and not link modes directly?

I am not aware of a clear reason. This documentation aims to describe
the current behavior and capture the rationale of the existing API.

Configuring it via link modes directly would likely resolve some of this
confusion, but for now we focus on documenting how the current API is
expected to behave.

> > + *      Drivers should reject a non-zero setting of @autoneg when
> > + *      autonegotiation is disabled (or not supported) for the link.
> 
> I think this belong in the @set doc below..

ack

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

Powered by blists - more mailing lists