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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20251125181957.5b61bdb3@kernel.org>
Date: Tue, 25 Nov 2025 18:19:57 -0800
From: Jakub Kicinski <kuba@...nel.org>
To: Oleksij Rempel <o.rempel@...gutronix.de>
Cc: Andrew Lunn <andrew@...n.ch>, Heiner Kallweit <hkallweit1@...il.com>,
 "David S. Miller" <davem@...emloft.net>, Eric Dumazet
 <edumazet@...gle.com>, Paolo Abeni <pabeni@...hat.com>, Rob Herring
 <robh@...nel.org>, Krzysztof Kozlowski <krzk+dt@...nel.org>, Florian
 Fainelli <f.fainelli@...il.com>, Maxime Chevallier
 <maxime.chevallier@...tlin.com>, Kory Maincent <kory.maincent@...tlin.com>,
 Lukasz Majewski <lukma@...x.de>, Jonathan Corbet <corbet@....net>, Donald
 Hunter <donald.hunter@...il.com>, Vadim Fedorenko
 <vadim.fedorenko@...ux.dev>, Jiri Pirko <jiri@...nulli.us>, Vladimir Oltean
 <vladimir.oltean@....com>, Alexei Starovoitov <ast@...nel.org>, Daniel
 Borkmann <daniel@...earbox.net>, Jesper Dangaard Brouer <hawk@...nel.org>,
 John Fastabend <john.fastabend@...il.com>, kernel@...gutronix.de,
 linux-kernel@...r.kernel.org, netdev@...r.kernel.org, Russell King
 <linux@...linux.org.uk>, Divya.Koppera@...rochip.com, Sabrina Dubroca
 <sd@...asysnail.net>, Stanislav Fomichev <sdf@...ichev.me>
Subject: Re: [PATCH net-next v8 1/1] Documentation: net: add flow control
 guide and document ethtool API

On Wed, 19 Nov 2025 15:03:17 +0100 Oleksij Rempel wrote:
> +Kernel Policy: "Set and Trust"
> +==============================
> +
> +The ethtool pause API is defined as a **wish policy** for
> +IEEE 802.3 link-wide PAUSE only. User requests express the preferred
> +configuration, but drivers may reject unsupported combinations and it
> +may not be possible to apply a request in all link states.
> +
> +Key constraints:
> +
> +- Link-wide PAUSE is not valid on half-duplex links.
> +- Link-wide PAUSE cannot be used together with Priority-based Flow Control
> +  (PFC, IEEE 802.1Q Clause 36).
> +- Drivers may require generic link autonegotiation to be enabled before
> +  allowing Pause Autonegotiation to be enabled.
> +
> +Because of these constraints, the configuration applied to the MAC
> +may differ from the user request depending on the active link mode.
> +
> +Implications for userspace:
> +
> +1. Set once (the "wish"): the requested Rx/Tx PAUSE policy is
> +   remembered even if it cannot be applied immediately.
> +2. Applied conditionally: when the link comes up, the kernel enables
> +   PAUSE only if the active mode allows it.

This section is quite confusing. Documenting the constrains make sense
but it seems like this mostly applies to autoneg on. Without really
saying so. Plus the get behavior.. see below..

> + * @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/@...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?
Why do we need to configure autoneg via this API and not link modes directly?

> + *      Drivers should reject a non-zero setting of @autoneg when
> + *      autonegotiation is disabled (or not supported) for the link.

I think this belong in the @set doc below..

> + *      If generic autonegotiation is disabled, pause autonegotiation is
> + *      treated as disabled/inactive.
> + *
> + * @set_pauseparam: Apply a policy for link-wide PAUSE (IEEE 802.3 Annex 31B).
> + *      If @autoneg is true:
> + *              Arrange for pause advertisement (Pause/Asym) based on
> + *              @rx_pause/@...pause and program the MAC to follow the
> + *              negotiated result (which may be symmetric, asymmetric, or off
> + *              depending on the link partner).
> + *      If @autoneg is false:
> + *              Do not rely on autonegotiation; force the MAC RX/TX pause
> + *              state directly per @rx_pause/@...pause.
> + *
> + *      Implementations that integrate with PHYLIB/PHYLINK should cooperate
> + *      with those frameworks for advertisement and resolution; MAC drivers are
> + *      still responsible for applying the required MAC state.
> + *
> + *      Return: 0 on success or a negative errno. Return -EOPNOTSUPP if
> + *      link-wide PAUSE is unsupported. If only symmetric pause is supported,
> + *      reject unsupported asymmetric requests with -EINVAL (or document any
> + *      coercion policy).
> + *
> + *      See also: Documentation/networking/flow_control.rst