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

From: Oleksij Rempel
Date: Mon Dec 01 2025 - 04:52:46 EST

Hi Jakub, Russell, all,

On Fri, Nov 28, 2025 at 02:17:10PM -0800, Jakub Kicinski wrote:
> On Fri, 28 Nov 2025 20:38:28 +0000 Russell King (Oracle) wrote:
> > On Fri, Nov 28, 2025 at 09:16:24PM +0100, Andrew Lunn wrote:
> > > > Can you please tell me what is preventing us from deprecating pauseparam
> > > > API *for autoneg* and using linkmodes which are completely unambiguous.
> > >
> > > Just to make sure i understand you here...
> > >
> > > You mean make use of
> > >
> > > ETHTOOL_LINK_MODE_Pause_BIT = 13,
> > > ETHTOOL_LINK_MODE_Asym_Pause_BIT = 14,
> > >
> > > So i would do a ksettings_set() with
> > >
> > > __ETHTOOL_LINK_MODE_LEGACY_MASK(Pause) | __ETHTOOL_LINK_MODE_LEGACY_MASK(Asym_Pause)
> > >
> > > to indicate both pause and asym pause should be advertised.
> > >
> > > The man page for ethtool does not indicate you can do this. It does
> > > have a list of link mode bits you can pass via the advertise option to
> > > ethtool -s, bit they are all actual link modes, not features like TP,
> > > AUI, BNC, Pause, Backplane, FEC none, FEC baser, etc.
> >
> > I see the latest ethtool now supports -s ethX advertise MODE on|off,
> > but it doesn't describe that in the parameter entry for "advertise"
> > and doesn't suggest what MODE should be, nor how to specify multiple
> > modes that one may wish to turn on/off. I'm guessing this is what you're
> > referring to.
> >
> > The ports never get advertised, so I don't think they're relevant.
> >
> > However, the lack of the pause bits means that one is forced to use
> > the hex number, and I don't deem that to be a user interface. That's
> > a programmers interface, or rather a nightmare, because even if you're
> > a programmer, you still end up looking at include/uapi/linux/ethtool.h
> > and doing the maths to work out the hex number to pass, and then you
> > mistype it with the wrong number of zeros, so you try again, and
> > eventually you get the advertisement you wanted.
> >
> > So no, I don't accept Jakub's argument right now. Forcing people into
> > the nightmare of working out a hex number isn't something for users.
>
> I did some digging, too, just now. Looks like the options are indeed
> not documented in the man page but ethtool uses the "forward compatible"
> scheme with strings coming from the kernel. So this:
>
> ethtool -s enp0s13f0u1u1 advertise Pause on Asym_Pause on
>
> works just fine, with no changes in CLI.
>
> We should probably document that it works in the ethtool help and man
> page. And possibly add some synthetic options like Receive-Only /
> Transmit-Only so that users don't have to be aware of the encoding
> details? Let me know if it's impractical, otherwise I think we'll
> agree that having ethtool that makes it obvious how to achieve the
> desired configuration beats best long form docs in the kernel..

1. Reject vs Accept autoneg=1

I audited set_pauseparam implementations across the tree. We are seeing two
valid but distinct models here, driven by different hardware realities:

- Strict Hardware Model (Jakub's point): Mostly Enterprise/Server NICs (bnx2x,
bnxt, i40e, ice, cxgb4). These devices often rejects advertisement changes
if Link AN is off. They enforce a strict dependency for correctness.

- User Intent Model (Russell's point): Mostly embedded, older drivers, and
phylink users (e1000, igb, fec, mvneta, stmmac). These drivers handle the
state in software, accepting the config as a "wish" for when Link AN becomes
active.

Plan for v9: Since this is not a discussion about which model will win, but
rather documentation of the current reality, the text will support both
realities. I will document "User Intent" (Accepting configuration) as the
recommended behavior for flexible hardware to keep administrative state
separate from operational state. However, I will explicitly note that drivers
MAY enforce a strict dependency if their hardware/firmware model requires it,
so users are aware that behavior varies.

2. Deprecating pauseparam in favor of ethtool -s ... advertise

Jakub suggested deprecating set_pauseparam for autoneg in favor of ethtool -s
... advertise.

I agree with the technical merit: ethtool -s ... advertise is cleaner for
negotiation because it targets the Advertiser (PHY/Autoneg logic) directly. It
maps 1:1 to the hardware capability and avoids ambiguity.

However, ethtool -s cannot replace set_pauseparam entirely because it cannot
handle Forced Mode (Manual MAC override). We would still need a separate
interface for that.

Therefore, I prefer to keep ethtool -A (Pause UAPI) as the unified Link-wide
PAUSE Abstraction. It shields the user from knowing whether the underlying
hardware is using an Advertiser (Resolution Mode) or a Manual Override (Forced
Mode).

Proposed Text: Documentation/networking/flow_control.rst

Kernel Policy: User Intent & Resolution
=======================================

The ethtool pause API ('ethtool -A' or '--pause') configures the **User
Intent** for **Link-wide PAUSE** (IEEE 802.3 Annex 31B). The
**Operational State** (what actually happens on the wire) is derived
from this intent, the active link mode, and the link partner.

**Disambiguation: Pause Autoneg vs. Link Autoneg**
In this section, "autonegotiation" refers exclusively to the **Pause
Autonegotiation** parameter ('ethtool -A / --pause ... autoneg <on|off>').
This is distinct from, but interacts with, **Generic Link
Autonegotiation** ('ethtool -s / --change ... autoneg <on|off>').

The semantics of the Pause API depend on the 'autoneg' parameter:

1. **Resolution Mode** ('ethtool -A ... autoneg on')
The user intends for the device to **respect the negotiated result**.

- **Hardware Capability Check:** The driver must verify that the hardware
is capable of Autonegotiation. If the hardware is fixed-link or
lacks AN logic entirely, this request must be rejected (``-EOPNOTSUPP``).
- **Advertisement:** The system updates the PHY advertisement
(Symmetric/Asymmetric pause bits) to match the ``rx`` and ``tx`` parameters.
- **Resolution:** The system configures the MAC to follow the standard
IEEE 802.3 Resolution Truth Table based on the Local Advertisement
vs. Link Partner Advertisement.
- **Interaction with Link Autoneg:** If Generic Link Autonegotiation is
currently disabled, resolution cannot occur. The Operational State
effectively becomes **Disabled**.

**Note on Implementation Variation:** Provided the hardware supports AN
in principle, the system **SHOULD** accept this configuration as a valid
stored intent for when Link Autonegotiation is re-enabled. However,
legacy or strict-hardware drivers **MAY** reject this request if Link
Autonegotiation is disabled, enforcing a strict dependency.

2. **Forced Mode** ('ethtool -A ... autoneg off')
The user intends to **override negotiation** and force a specific
state.

- **Hardware Capability Check:** The driver must verify that the hardware
supports forced manual configuration. If the hardware is tightly coupled
to AN logic and cannot be forced, this request must be rejected.
- **Advertisement:** The system should update the PHY advertisement
to match the ``rx`` and ``tx`` parameters, ensuring the link partner
is aware of the forced configuration.
- **Resolution:** The system configures the MAC according to the
specified ``rx`` and ``tx`` parameters, ignoring the link partner's
advertisement.

**Global Constraint: Full-Duplex Only**
Link-wide PAUSE (Annex 31B) is strictly defined for **Full-Duplex** links.
If the link mode is **Half-Duplex** (whether forced or negotiated),
Link-wide PAUSE is operationally **disabled** regardless of the
parameters set above.

**Summary of "autoneg" Flag Meaning:**
- true -> **Delegate decision:** "Use the IEEE 802.3 logic to decide."
- false -> **Force decision:** "Do exactly what I say (if the network device
supports it)."

Proposed Text: include/linux/ethtool.h

/**
* @get_pauseparam: Report the configured administrative 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.
* true -> the device follows the result of pause autonegotiation
* (Pause/Asym) when the link allows it;
* false -> the device uses a forced configuration.
* @rx_pause/@tx_pause:
* Represent the desired policy (Administrative State).
* In autoneg mode they describe what is to be advertised;
* in forced mode they describe the MAC configuration to be forced.
*
* @set_pauseparam: Apply a policy for link-wide PAUSE (IEEE 802.3 Annex 31B).
* @rx_pause/@tx_pause:
* Desired state. If @autoneg is true, these define the
* advertisement. If @autoneg is false, these define the
* forced MAC configuration (and preferably the advertisement too).
* @autoneg:
* Select Resolution Mode (true) or Forced Mode (false).
*
* **Constraint Checking:**
* Drivers MUST validate that the hardware capabilities support the
* requested mode.
* - If the hardware does not support Autonegotiation (e.g. fixed link),
* drivers MUST reject @autoneg=1 with -EOPNOTSUPP.
* - If the hardware does not support Forced configuration (e.g. strict AN),
* drivers MUST reject @autoneg=0 with -EOPNOTSUPP.
*
* Provided the hardware capability exists, drivers SHOULD accept a setting
* of @autoneg=1 even if generic link autonegotiation ('ethtool -s') is
* currently disabled. This allows the user to pre-configure the desired
* policy for future link modes. Users should be aware that some drivers
* may strictly enforce the dependency and reject this configuration.
*
* New drivers are strongly encouraged to use phylink_ethtool_get_pauseparam()
* and phylink_ethtool_set_pauseparam() which implement this logic
* correctly.
*/

Best Regards,
Oleksij
--
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 |