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

[Donald Hunter]

Oleksij Rempel <o.rempel@xxxxxxxxxxxxxx> writes:

> Introduce a new document, flow_control.rst, to provide a comprehensive
> guide on Ethernet Flow Control in Linux. The guide explains how flow
> control works, how autonegotiation resolves pause capabilities, and how
> to configure it using ethtool and Netlink.
>
> In parallel, document the pause and pause-stat attributes in the
> ethtool.yaml netlink spec. This enables the ynl tool to generate
> kernel-doc comments for the corresponding enums in the UAPI header,
> making the C interface self-documenting.
>
> Finally, replace the legacy flow control section in phy.rst with a
> reference to the new document and add pointers in the relevant C source
> files.
>
> Signed-off-by: Oleksij Rempel <o.rempel@xxxxxxxxxxxxxx>
> ---
> changes v4:
> - Reworded pause stats-src doc: clarify that sources are MAC Merge layer
>   components, not PHYs.
> - Fixed non-ASCII dash in "Link-wide".
> - Added explicit note that pause_time = 0 resumes transmission immediately.
> - Corrected terminology: use "pause quantum" (singular) consistently.
> - Dropped paragraph about user tuning of FIFO watermarks (no ABI support).
> - Synced UAPI header comments with YAML wording (MAC Merge layer).
> - Ran ASCII sweep to remove stray non-ASCII characters.
> changes v3:
> - add warning about half-duplex collision-based flow control on shared media
> - clarify pause autoneg vs. generic autoneg and forced mode semantics
> - document pause quanta defaults used by common MAC drivers, with time examples
> - fix vague cross-reference, point to autonegotiation resolution section
> - expand notes on PAUSE vs. PFC exclusivity
> - include generated enums (pause / pause-stat) in UAPI with kernel-doc
> changes v2:
> - remove recommendations
> - add note about autoneg resolution
> ---
>  Documentation/netlink/specs/ethtool.yaml      |  27 ++
>  Documentation/networking/flow_control.rst     | 373 ++++++++++++++++++
>  Documentation/networking/index.rst            |   1 +
>  Documentation/networking/phy.rst              |  12 +-
>  include/linux/ethtool.h                       |  45 ++-
>  .../uapi/linux/ethtool_netlink_generated.h    |  28 +-
>  net/dcb/dcbnl.c                               |   2 +
>  net/ethtool/pause.c                           |   4 +
>  8 files changed, 477 insertions(+), 15 deletions(-)
>  create mode 100644 Documentation/networking/flow_control.rst
>
> diff --git a/Documentation/netlink/specs/ethtool.yaml b/Documentation/netlink/specs/ethtool.yaml
> index 7a7594713f1f..c3f6a9af6f08 100644
> --- a/Documentation/netlink/specs/ethtool.yaml
> +++ b/Documentation/netlink/specs/ethtool.yaml
> @@ -864,7 +864,9 @@ attribute-sets:
>  
>    -
>      name: pause-stat
> +    doc: Statistics counters for link-wide PAUSE frames (IEEE 802.3 Annex 31B).
>      attr-cnt-name: __ethtool-a-pause-stat-cnt
> +    enum-name: ethtool_a_pause_stat

Please use - instead of _ in all names in ynl specs. See existing
enum-name: entries in ethtool.yaml

>      attributes:
>        -
>          name: unspec
> @@ -875,13 +877,17 @@ attribute-sets:
>          type: pad
>        -
>          name: tx-frames
> +        doc: Number of PAUSE frames transmitted.
>          type: u64
>        -
>          name: rx-frames
> +        doc: Number of PAUSE frames received.
>          type: u64
>    -
>      name: pause
> +    doc: Parameters for link-wide PAUSE (IEEE 802.3 Annex 31B).
>      attr-cnt-name: __ethtool-a-pause-cnt
> +    enum-name: ethtool_a_pause

Also here.