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

[Oleksij Rempel <o.rempel@pengutronix.de>]

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.

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

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;
 *   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.
 */

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 |