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

[Russell King (Oracle)]

On Fri, Nov 28, 2025 at 09:55:22AM +0100, Oleksij Rempel wrote:
> Hi all,
> 
> Before sending v9, I would like to summarize the discussion and validate
> the intended logic one last time.
> 
> Based on the feedback (specifically Russell's clarification on API
> semantics and Phylink behavior), I will document the following logic.
> 
> 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**.
> 
>    - **Advertisement:** The system updates the PHY advertisement
>      (Symmetric/Asymmetric pause bits if the link medium supports
>      advertisement) 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.
>    - **Constraint:** If Link Autonegotiation ('ethtool -s / --change')
>      is disabled, the resolution cannot occur. The Operational State
>      effectively becomes **Disabled** (as negotiation is impossible)
>      regardless of the advertisement. However, the system **MUST**
>      accept this configuration as a valid stored intent for future use.

This looks fine to me now, thanks.

> 
> 2. **Forced Mode** ('ethtool -A ... autoneg off')
>    The user intends to **override negotiation** and force a specific
>    state (if the link mode permits).
> 
>    - **Advertisement:** The system should update the PHY advertisement
>      (if the link medium supports 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 link supports it)."

"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 negotiated result of pause
>  *     autonegotiation (Pause/Asym) when the link allows it;

               "the device follows the result of pause autonegotiation
	 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 accept a setting of @autoneg (true) even if generic
>  *   link autonegotiation ('ethtool -s / --change') is currently disabled.
>  *   This allows the user to pre-configure the desired policy for future
>  *   link modes.
>  *
>  * New drivers are strongly encouraged to use phylink_ethtool_get_pauseparam()
>  * and phylink_ethtool_set_pauseparam() which implement this logic
>  * correctly.
>  */

Apart from the two minor issues above,

Reviewed-by: Russell King (Oracle) <rmk+kernel@xxxxxxxxxxxxxxx>

Thanks!

-- 
RMK's Patch system: https://www.armlinux.org.uk/developer/patches/
FTTP is here! 80Mbps down 10Mbps up. Decent connectivity at last!