Re: [PATCH net-next v8 1/1] Documentation: net: add flow control guide and document ethtool API

[Jakub Kicinski <kuba@kernel.org>]

On Wed, 26 Nov 2025 09:36:42 +0100 Oleksij Rempel wrote:
> 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:  
> > > + * @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/@tx_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",

Again, that's all well and good for autoneg, but in DC use cases with
integrated NICs autoneg is usually off. And in that case having get
report "desired" config of some sort makes much less sense, when we also
recommend that drivers reject unsupported configurations.

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

To spell it out more forcefully I think it describes the current
behavior for certain devices. I could be wrong but the expectations
for when autoneg is off should be different.

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

You say current API - is setting Pause and Asym_Pause via link modes
today rejected? I don't see an explicit check by grepping but I haven't
really tried..